msg.docs

Sofia SIP is an open-source SIP User-Agent library, compliant with the IETF RFC3261 specification.

  sip_max_forwards_t *sip_max_forwards; // Max-Forwards
  ...
} sip_t;
@endcode

As you can see above, the public #sip_t structure contains the common
header members that are also found in the beginning of a header
structure. The @e sip_size indicates the size of the structure - the
application can extend the parser and #sip_t structure beyond the
original size. The @e sip_flags contains various flags used during the
parsing and printing process. They are documented in the <sofia-sip/msg.h>. These
boilerplate members are followed by the pointers to various message
elements and headers.

@section msg_parsing_example Result of Parsing Process

Let us now show how a simple message is parsed and presented to the
applications. As an exampe, we choose a SIP request message with method BYE,
including only the mandatory fields:
@code
BYE sip:[e-mail] SIP/2.0
Via: SIP/2.0/UDP sip.example.edu;branch=d7f2e89c.74a72681
Via: SIP/2.0/UDP pc104.example.edu:1030;maddr=110.213.33.19
From: Bobby Brown <sip:[e-mail]>;tag=77241a86
To: Joe User <sip:[e-mail]>;tag=7c6276c1
Call-ID: [e-mail]
CSeq: 2
@endcode

The figure below shows the layout of the BYE message above after parsing:

@image html sip-parser2.gif BYE message and its representation in C 
@image latex sip-parser2.eps BYE message and its representation in C

The leftmost box represents the message of type #msg_t.  Next box from
the left reprents the #sip_t structure, which contains pointers to a
header objects.  The next column contains the header objects.  There is
one header object for each message fragment. The rightmost box represents
the I/O buffer used when the message was received.  Note that the I/O
buffer may be non-continous and composed of many separate memory areas.

The message object has link to the public message structure (@a
m_object), to the dual-linked fragment chain (@a m_frags) and to the I/O
buffer (@a m_buffer).  The public message structure contains pointers to
the headers according to their type.  If there are multiple headers of
the same type (like there are two Via headers in the above message), the
headers are put into a single-linked list.

Each fragment has pointers to successing and preceding fragment. It also
contains pointer to the corresponding data within the I/O buffer and its
length.

The main purpose of the fragment chain is to preserve the original order
of the headers.  If there were an third Via header after CSeq in the
message, the fragment representing it would be after the CSeq header in
the fragment chain but after second Via in the header list.

@section msg_parsing_memory Example: Parsing a Complete Message

The following code fragment is an example of parsing a complete message. The
parsing process is more hairy when there is stream to be parsed.

@code
msg_t *parse_memory(msg_mclass_t const *mclass, char const data[], int len)
{
  msg_t *msg;
  int m;
  msg_iovec_t iovec[2] = {{ 0 }};

  msg  = msg_create(mclass, 0);
  if (!msg)
    return NULL;

  m = msg_recv_iovec(msg, iovec, 2, n, 1);
  if (m < 0) {
    msg_destroy(msg);
    return NULL;
  }
  assert(m <= 2);
  assert(iovec[0].mv_len + iovec[1].mv_len == n);

  memcpy(iovec[0].mv_base, data, n = iovec[0].mv_len);
  if (m == 2)
    memcpy(iovec[1].mv_base + n, data + n, iovec[1].mv_len);

  msg_recv_commit(msg, iovec[0].mv_len + iovec[1].mv_len, 1);

  m = msg_extract(msg);
  assert(m != 0);
  if (m < 0) {
     msg_destroy(msg);
     return NULL;
  }
  return msg;
}
@endcode

Let's go through this simple function, step by step. First, we get the @a
data pointer and its size in bytes, @a len. We first initialize an I/O
vector used to represent message with the parser.

@code
msg_t *parse_memory(msg_mclass_t const *mclass, char const data[], int len)
{
  msg_t *msg;
  int m;
  msg_iovec_t iovec[2] = {{ 0 }};
@endcode

The message class @a mclass (a parser driver object, #msg_mclass_t) is used
to represent a particular protocol-specific parser instance. When a message
object is created, it is given as an argument to msg_create() function:

@code
  msg  = msg_create(mclass, 0);
  if (!msg)
    return NULL;
@endcode

Next we obtain a memory buffer for data with msg_recv_iovec(). The memory
buffer is usually a single continous memory area, but in some cases it may
consist of two distinct areas. Therefore the @a iovec is used here to pass
the buffers around. The @a iovec is also very handly as it can be directly
passed to various system I/O calls.

@code
  m = msg_recv_iovec(msg, iovec, 2, n, 1);
  if (m < 0) {
    msg_destroy(msg);
    return NULL;
  }
@endcode

These assumptions hold always true when you call msg_recv_iovec() first
time with a complete message:

@code
  assert(m >= 1 && m <= 2);
  assert(iovec[0].mv_len + iovec[1].mv_len == n);
@endcode

Next, we copy the data to the I/O vector and commit the copied data to the
message. Earlier with msg_recv_iovec() we allocated buffer space for data,
now calling msg_recv_commit() indicates that valid data has been copied to
the buffer. The last parameter to msg_recv_commit() indicates that the end
of stream is encountered and no more data is to be expected.

@code
  memcpy(iovec[0].mv_base, data, n = iovec[0].mv_len);
  if (m == 2)
    memcpy(iovec[1].mv_base + n, data + n, iovec[1].mv_len);

  msg_recv_commit(msg, iovec[0].mv_len + iovec[1].mv_len, 1);
@endcode

We call msg_extract() next; it takes care of parsing the message. A fatal
parsing error is indicated by returning -1. If the message is incomplete,
msg_extract() returns 0. When a complete message has been parsed, a positive
value is returned. We know that a message cannot be incomplete, as a call to
msg_recv_commit() indicated to the parser that the end-of-stream has been
encountered.

@code
  m = msg_extract(msg);
  assert(m != 0);
  if (m < 0) {
     msg_destroy(msg);
     return NULL;
  }
  return msg;
}
@endcode

 */

/**@class msg_s msg.h
 *
 * @brief Message object.
 *
 * The message object is used by Sofia parsers for SIP and HTTP
 * protocols. The message object has an abstract, protocol-independent
 * inteface type #msg_t, and a separate public protocol-specific interface
 * #msg_pub_t (which is typedef'ed to #sip_t or #http_t depending
 * on the protocol).
 *
 * The main interface to abstract messages is defined in <sofia-sip/msg.h>. The
 * network I/O interface used by transport protocols is defined in
 * <sofia-sip/msg_addr.h>. The protocol-specific parser table, also known as message
 * class, is defined in <sofia-sip/msg_mclass.h>. (The message class is used as a
 * factory object when a message object is created with msg_create()).
 */

/**@typedef typedef struct msg_s msg_t;
 *
 * Message object. 
 *
 * The @a msg_t is the type of a message object used by Sofia signaling
 * protocols and parsers. Its contents are not directly accessible.
 */

/**@typedef typedef struct msg_common_s msg_common_t;
 *
 * Common part of header. 
 *
 * The @a msg_common_t is the base type of a message headers used by
 * protocol parsers. Instead of #msg_common_t, most interfaces use
 * #msg_header_t, which is supposed to be a union of all possible headers.
 */


/**
 * @defgroup msg_parser Parser Building Blocks
 *
 * This submodule contains the functions and types for building a
 * protocol-specific parser.
 */

/**
 * @defgroup msg_headers Headers
 *
 * This submodule contains the functions and types for handling message
 * headers and other elements.
 */


/**
 * @defgroup msg_mime MIME Headers
 *
 * This submodule contains the header classes, functions and types for
 * handling MIME headers (@RFC2045) and MIME multipart (@RFC2046) processing.
 *
 * The MIME headers implemented are as follows:
 * - @ref msg_accept "@b Accept header"
 * - @ref msg_accept_charset "@b Accept-Charser header"
 * - @ref msg_accept_encoding "@b Accept-Encoding header"
 * - @ref msg_accept_language "@b Accept-Language header"
 * - @ref msg_content_disposition "@b Content-Disposition header"
 * - @ref msg_content_encoding "@b Content-Encoding header"
 * - @ref msg_content_id "@b Content-ID header"
 * - @ref msg_content_location "@b Content-Location header"
 * - @ref msg_content_language "@b Content-Language header"
 * - @ref msg_content_md5 "@b Content-MD5 header"
 * - @ref msg_content_transfer_encoding "@b Content-Transfer-Encoding header"
 * - @ref msg_mime_version "@b MIME-Version header"
 */

/**
 * @defgroup test_msg Testing Parser
 *
 * This submodule contains the functions and types for building a
 * parser objects for testing purposes.
 */