/* -*- 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 <Pekka.Pessi@nokia.com> * * @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: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 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.