/* -*- c -*- *//**@mainpage SIP Parser, Messages and Headers * * @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 <Pekka.Pessi@nokia.com> * * @STATUS Core library * * @LICENSE LGPL * * @section sip_overview Overview * * The structure of each header is defined in @b <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 * <sip_header.h>.  For header @c X, there are types, functions, macros and * header class as follows: * *  - @c sip_X_t is the structure used to store parsed header, *  - @c SIP_X_INIT() initializes a static instance of sip_X_t, *  - @c sip_X_init() initializes a dynamic instance of sip_X_t, *  - @c sip_is_X() tests if header object is instance of header X, *  - @c sip_X_make() creates a header X object by decoding given string, *  - @c sip_X_format() creates a header X object by decoding given  *    printf() list, *  - @c sip_X_dup() duplicates (deeply copies) the header X,  *  - @c sip_X_copy() copies the header X, *  - @c sip_hclass_t @c sip_X_class[] contains the @em header @em class  *    for header X. *  * 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 <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 @b 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. * * 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; // Record-Route *   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 <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:joe@example.com 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:bb@example.edu>;tag=77241a86 * To: Joe User <sip:joe@example.com>;tag=7c6276c1 * Call-ID: 4c4e911b@pc104.example.edu * 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. * * @} *//**@defgroup sip_headers SIP Headers * * SIP headers and other SIP message elements. * * @{ *//**@page sip_header_x SIP Header Structure Conventions * * 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. * All header structures contain the common part, a sip_common_t structure * (@c X_common[]), a link to the next header in list (@c X_next), and a * various fields describing the header value (in this case, @c X_value). * * @code * typedef struct sip_X_s * { *  sip_common_t    X_common[1]; *  sip_X_t        *X_next; *  unsigned long   X_value;  * } sip_X_t; * @endcode * * The @c X_common is a structure sip_common_t (aka msg_common_t), which is * common to each fragment and can be considered as a base class for all * headers. The structure sip_common_t 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). (X_common is an array of size * 1, as it makes it easy to cast a header pointer to a pointer to * sip_common_t.) * * The @c 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 @c 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. *//**@ingroup sip_X * @var msg_hclass_t sip_X_class[]; * @brief Header class for SIP X. *  * The header class sip_X_class defines how a SIP * X is parsed and printed.  It also * contains methods used by SIP parser and other functions * to manipulate the sip_X_t header structure. *