sip.docs

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

/* -*- c -*- */

/**@MODULEPAGE "sip" - SIP Parser Module
 *
 * @section sip_meta Module Meta Information
 *
 * The Sofia @b sip module contains interface to the SIP parser and the
 * header and message objects.
 *
 * @CONTACT Pekka Pessi <[e-mail]>
 *
 * @STATUS @SofiaSIP Core library
 *
 * @LICENSE LGPL
 *
 * @section sip_overview Overview
 *
 * The structure of each header is defined in @b <sofia-sip/sip.h>. In addition to the
 * header structure, there is defined a @em header @em class structure and
 * some standard functions for each header in the include file @b
 * <sofia-sip/sip_header.h>. For header @c X, there are types, functions,
 * macros and header class declared in <sofia-sip/sip_protos.h> and
 * <sofia-sip/sip_hclass.h>. See @ref sip_header_x for detailed description
 * of these header-specific boilerplate declarations.
 *
 * In addition to this interface, the @ref sip_parser "SIP parser documentation"
 * contains description of the functionality required when a parser is
 * extended by a new header. It is possible to add new headers to the SIP
 * parser or extend the definition of existing ones.
 *
 * @section sip_parser_intro Parsing SIP Messages
 *
 * Sofia SIP parser follows @em recursive-descent principle.  In other words,
 * it is a program that descends the SIP syntax tree top-down recursively.
 * (All syntax trees have root at top and they grow downwards.)
 *
 * In the case of SIP such a parser is very efficient. The parser can choose
 * between different forms based on each token, as SIP syntax is carefully
 * designed so that it requires only minimal scan-ahead.  It is also easy to
 * extend a recursive-descent parser via a standard API, unlike, for
 * instance, a LALR parser generated by @em Bison.
 *
 * The abstract message module @b msg contains a high-level parser engine
 * that drives the parsing process and invokes the SIP parser for each
 * header. As there are no framing between SIP messages, the parser
 * considers any received data, be it a UDP datagram or a TCP stream, as a
 * @em message @em stream, which may consist of one or more SIP messages. 
 * The parser works by first separating stream into fragments, then building
 * a complete message based on parsing result. After a message is completed,
 * it can be given to the message stream customer (typically a protocol
 * state machine). The parser continues processing the stream and feeding
 * the messages to protocol engine until the end of the stream is reached.
 *
 * For each message, the parser starts by separating the first fragment,
 * which is either a request or status line. After the first line has been
 * processed, the parser engine continues by separating the headers
 * one-by-one from the message. After the parser encounters an empty line
 * separating the headers and the message body (payload), it invokes a
 * function parsing the separator and payload fragment(s). When the message
 * is complete, the parser can hand the message over to the protocol engine. 
 * Then it is ready to start again with first fragment of the next message.
 *
 * @image html sip-parser.gif Separating byte stream to messages
 * @image latex sip-parser.eps Separating byte stream to messages
 *
 * When the parsing process has completed, the request or status line, each
 * header, separator and the payload are all in their own fragment
 * structure. The fragments form a dual-linked list known as @e fragment @e
 * chain as shown in the above figure. The buffers for the message, the
 * fragment chain, and a whole other stuff is held by the generic message
 * type, #msg_t, defined in <sofia-sip/msg.h>. The internal structure of #msg_t is
 * known only within @b msg module and it is hidden from other modules.
 * 
 * The abstract message module @b msg also drives the reverse process,
 * invoking the encoding method of each fragment so that the whole outgoing
 * SIP message is encoded properly.
 *
 * @section sip_header_struct SIP Header as a C struct
 *
 * Just separating headers from each other and from the message body is not
 * usually enough. When a header contains structured data, the header
 * contents should be converted to a form that is convenient to use from C
 * programs. For that purpose, the message parser needs a special function
 * for each individual header. The header-specific parsing function divides
 * the contents of the header into semantically meaningful segments and
 * stores the result in a header-specific structure.
 *
 * The parser passes the fragment contents to a parsing function immediately
 * after it has separated a fragment from the message. The parsing function
 * is defined by the @e header @e class. The header class is either
 * determined by the fragment position (first line, separator line or
 * payload), or it is found from the hash table using the header name as
 * key. There is also a special header class for @e unknown headers, headers
 * with a name that is not regocnized by the parser.
 *
 * For instance, the @From header has following syntax:
 *
 * @code
 * from           = ("From" | "f") ":" 
 *                  ( name-addr | addr-spec ) *( ";" addr-params )
 * name-addr      = [ display-name ] "<" addr-spec ">"
 * addr-spec      = SIP-URL | URI
 * display-name   = *token | quoted-string
 * addr-params    = *( tag-param |  generic-param )
 * tag-param      = "tag" "=" ( token | quoted-string )
 * @endcode
 *
 * When a @From header is parsed, the header parser function sip_from_d()
 * separates the @e display-name, @e addr-spec and each parameter in the @e
 * addr-params list. The parsing result is assigned to a #sip_from_t
 * structure, which is defined as follows:
 *
 * @code
 * typedef struct sip_addr_s {
 *   sip_common_t        a_common[1];
 *   sip_unknown_t      *a_next;
 *   char const         *a_display;
 *   url_t               a_url[1];
 *   sip_param_t const  *a_params;
 *   char const         *a_tag;
 * } sip_from_t;
 * @endcode
 *
 * The string containing the @e display-name is put into the @c a_display
 * field, the URL contents can be found in the @c a_url field, and the list
 * of @e addr-params parameters is put in the @c a_params array.  If there
 * is a @e tag-param present, a pointer to the parameter value is assigned
 * to @c a_tag field.
 *
 * @section sip_msg_struct SIP Message as a C struct
 *
 * It is not enough to represent a SIP message as a collection of headers
 * following each other. The programmer also needs a convenient way to
 * access certain headers at the SIP message level, for example, accessing
 * directly the @From header instead of going through all headers and
 * examining their name. The structured view to the SIP message is provided
 * via a C struct with type #sip_t. 
 *
 * In other words, a single message is represented by two types, first type
 * (#msg_t) is private to the msg module and inaccessable by an application
 * programmer, second (#sip_t) is a public structure containing the parsed
 * headers.
 *
 * The #sip_t structure is defined as follows:
 * @code
 * typedef struct sip_s {
 *   msg_common_t        sip_common[1];    // Used with recursive inclusion
 *   msg_pub_t          *sip_next;         // Ditto
 *   void               *sip_user;	   // Application data
 *   unsigned            sip_size;
 *   int                 sip_flags;
 *
 *   sip_error_t        *sip_error;	   // Erroneous headers
 * 
 *   sip_request_t      *sip_request;      // Request line
 *   sip_status_t       *sip_status;       // Status line
 *
 *   sip_via_t          *sip_via;          // @Via (v)
 *   sip_route_t        *sip_route;        // @Route
 *   sip_record_route_t *sip_record_route; // @RecordRoute
 *   sip_max_forwards_t *sip_max_forwards; // @MaxForwards
 *   ...
 * } 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.
 *
 * @note Within the @b msg module, the public structure is known as
 * #msg_pub_t. The application programmer can cast a #msg_t pointer to
 * #sip_t with sip_object() function (or macro).
 *
 *
 * @section sip_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 BYE message with only the
 * mandatory fields included:
 * @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 header 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 the second @Via in the header list.
 *
 */

/**@defgroup sip_headers SIP Headers
 *
 * SIP headers and other SIP message elements.
 *
 * For each SIP header recognized by the SIP module, there is a header
 * structure containing the parsed value.  The header structure name is
 * generated from the header name by lowercasing the name, replacing the
 * non-alphanumeric characters (usually just minus "-") with underscore "_"
 * characters, and then adding prefix @c sip_ and suffix @c _t.  For
 * instance, the contents of header "MIME-Version" is stored in a structure
 * called sip_mime_version_t.
 *
 */

/**@ingroup sip_headers
 * @defgroup sip_header_x SIP Header X - Conventions
 * 
 * For a SIP header X, there are types, functions, macros and global data
 * declared in <sofia-sip/sip_protos.h> and <sofia-sip/sip_hclass.h> as
 * follows:
 *  - #sip_X_t is the structure used to store parsed header,
 *  - SIP_X_INIT() initializes a static instance of #sip_X_t,
 *  - sip_X_init() initializes a dynamic instance of #sip_X_t,
 *  - sip_is_X() tests if header object is instance of header X,
 *  - sip_X_make() creates a header X object by decoding given string,
 *  - sip_X_format() creates a header X object by decoding given 
 *    printf() list,
 *  - sip_X_dup() duplicates (deeply copies) the header X, 
 *  - sip_X_copy() copies the header X,
 *  - #msg_hclass_t #sip_X_class[] contains the @em header @em class 
 *    for header X.
 * 
 * All header structures contain the common part, a #sip_common_t structure
 * (@a X_common[]), a link to the next header in list (@a X_next), and
 * various fields describing the header value (in this case, @a X_value).
 * The header structure looks like this:
 * @code
 * typedef struct sip_X_s
 * {
 *   struct msg_common_s {
 *     msg_header_t       *h_succ;   // Pointer to succeeding fragment
 *     msg_header_t      **h_prev;   // Pointer to preceeding fragment
 *     msg_hclass_t       *h_class;  // Header class 
 *     void const         *h_data;   // Encoded data
 *     usize_t             h_len;    // Encoding length (including CRLF)
 *   } X_common[1];
 *   sip_X_t        *X_next;	     // Link to next X header field
 *   uint32_t       X_value;         // Value of X
 *   msg_param_t   *X_param;         // List of parameters
 * } sip_X_t;
 * @endcode
 *
 * The common structure #msg_common_t (aka #sip_common_t)
 * can be considered as a base class for all
 * headers. The structure contains the pointers for dual-linked
 * fragment chain (@a h_succ, @a h_prev), a pointer to header class (@a
 * h_class), a pointer to the text encoding of header contents (@a h_data)
 * and the length of the encoding (@a h_len). (@a X_common is an array of size
 * 1, as it makes it easy to cast a header pointer to a pointer to
 * msg_common_t.)
 *
 * The @a X_next is a pointer to another header (usually a pointer to
 * structure of same type). If there are multiple headers with same name,
 * like the two "Via" headers in the example above, the @a X_next is used to
 * link the second header to the first. The fragment chain cannot be used
 * for this purpose as the headers with same name are not necessarily
 * adjacent in the parsed message.
 *
 * The rest of the fields contain the parsed or decoded representation of
 * the header. In this case, it is a 32-bit integer followed by a list of
 * parameters. The content of parameters is not parsed, they are just
 * separated from each other and then stored in an dynamically allocated
 * array of string pointers. Pointer to the array is stored to @a X_params.
 * 
 * For more complex header structures, see #sip_contact_t or #sip_rack_t.
 *
 * @{
 */

/**The structure #sip_X_t contains representation of a SIP
 * @ref sip_header_x "X" header.