/* -*- 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.
*
* The #sip_X_t is defined as follows:
* @code
* typedef struct sip_X_s {
* msg_common_t X_common[1]; // Common fragment info
* 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
*/
typedef struct sip_X_s sip_X_t;
/**@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.
*
*/
SIP_DLL extern msg_hclass_t sip_X_class[];
enum {
/** Hash of X. @internal */
sip_X_hash = hash
};
/** Parse a X. @internal */
msg_parse_f sip_X_d;
/** Print a X. @internal */
msg_print_f sip_X_e;
/**Initializer for structure sip_X_t.
*
* A static sip_X_t structure must be initialized
* with the SIP_X_INIT() macro. For instance,
* @code
*
* sip_X_t sip_X = SIP_X_INIT;
*
* @endcode
* @HI
*/
#define SIP_X_INIT() SIP_HDR_INIT(X)
/**Initialize a structure sip_X_t.
*
* An sip_X_t structure can be initialized with the
* sip_X_init() function/macro. For instance,
* @code
*
* sip_X_t sip_X;
*
* sip_X_init(&sip_X);
*
* @endcode
* @HI
*/
#if SU_HAVE_INLINE
su_inline sip_X_t *sip_X_init(sip_X_t x[1])
{
return SIP_HEADER_INIT(x, sip_X_class, sizeof(sip_X_t));
}
#else
#define sip_X_init(x) \
SIP_HEADER_INIT(x, sip_X_class, sizeof(sip_X_t))
#endif
/**Test if header object is instance of sip_X_t.
*
* The function sip_is_X() returns true (nonzero) if
* the header class is an instance of X
* object and false (zero) otherwise.
*
* @param header pointer to the header structure to be tested
*
* @return
* The function sip_is_X() returns true (nonzero) if
* the header object is an instance of header X and
* false (zero) otherwise.
*/
#if SU_HAVE_INLINE
su_inline int sip_is_X(sip_header_t const *header)
{
return header && header->sh_class->hc_id == sip_hdr_X;
}
#else
int sip_is_X(sip_header_t const *header);
#endif
#define sip_X_p(h) sip_is_X((h))
/**Duplicate (deep copy) @c sip_X_t.
*
* The function sip_X_dup() duplicates a header
* structure @a hdr. If the header structure @a hdr
* contains a reference (@c hdr->x_next) to a list of
* headers, all the headers in the list are duplicated, too.
*
* @param home memory home used to allocate new structure
* @param hdr header structure to be duplicated
*
* When duplicating, all parameter lists and non-constant
* strings attached to the header are copied, too. The
* function uses given memory @a home to allocate all the
* memory areas used to copy the header.
*
* @par Example
* @code
*
* X = sip_X_dup(home, sip->sip_X);
*
* @endcode
*
* @return
* The function sip_X_dup() returns a pointer to the
* newly duplicated sip_X_t header structure, or NULL
* upon an error.
*/
sip_X_t *sip_X_dup(su_home_t *home, sip_X_t const *hdr);
/**Copy a sip_X_t header structure.
*
* The function sip_X_copy() copies a header structure @a
* hdr. If the header structure @a hdr contains a reference (@c
* hdr->h_next) to a list of headers, all the headers in that
* list are copied, too. The function uses given memory @a home
* to allocate all the memory areas used to copy the header
* structure @a hdr.
*
* @param home memory home used to allocate new structure
* @param hdr pointer to the header structure to be duplicated
*
* When copying, only the header structure and parameter lists
* attached to it are duplicated. The new header structure
* retains all the references to the strings within the old @a
* header, including the encoding of the old header, if present.
*
* @par Example
* @code
*
* X = sip_X_copy(home, sip->sip_X);
*
* @endcode
*
* @return
* The function sip_X_copy() returns a pointer to
* newly copied header structure, or NULL upon an error.
*/
sip_X_t *sip_X_copy(su_home_t *home, sip_X_t const *hdr);
/**Make a header structure sip_X_t.
*
* The function sip_X_make() makes a new
* sip_X_t header structure. It allocates a new
* header structure, and decodes the string @a s as the
* value of the structure.
*
* @param home memory home used to allocate new header structure.
* @param s string to be decoded as value of the new header structure
*
* @note This function is usually implemented as a macro calling
* sip_header_make().
*
* @return
* The function sip_X_make() returns a pointer to
* newly maked sip_X_t header structure, or NULL upon
* an error.
*/
#if SU_HAVE_INLINE
su_inline sip_X_t *sip_X_make(su_home_t *home, char const *s)
{
return sip_header_make(home, sip_X_class, s)->sh_X;
}
#else
sip_X_t *sip_X_make(su_home_t *home, char const *s);
#endif
/**Make a X from formatting result.
*
* The function sip_X_format() makes a new
* X object using formatting result as its
* value. The function first prints the arguments according to
* the format @a fmt specified. Then it allocates a new header
* structure, and uses the formatting result as the header
* value.
*
* @param home memory home used to allocate new header structure.
* @param fmt string used as a printf()-style format
* @param ... argument list for format
*
* @note This function is usually implemented as a macro calling
* msg_header_format().
*
* @return
* The function sip_X_format() returns a pointer to newly
* makes header structure, or NULL upon an error.
*
* @HIDE
*/
#if SU_HAVE_INLINE
su_inline
#endif
sip_X_t *sip_X_format(su_home_t *home, char const *fmt, ...)
__attribute__((format (printf, 2, 3)));
#if SU_HAVE_INLINE
su_inline sip_X_t *sip_X_format(su_home_t *home, char const *fmt, ...)
{
sip_header_t *h;
va_list ap;
va_start(ap, fmt);
h = sip_header_vformat(home, sip_X_class, fmt, ap);
va_end(ap);
return h->sh_X;
}
#endif
/**Decode a header X.
*
* The function sip_X_d() decodes value of the header X in the preallocated
* header structure @a h. The string @a s to be decoded should not contain
* the header name or colon. The decoding function also expects that the
* leading and trailing whitespace has been removed from the string @a s.
*
* @param home memory home used to allocate new header structure.
* @param h sip_X_t header structure
* @param s string to be decoded
* @param bsiz length of string @a s
*
* @return
* The function sip_X_d() returns non-negative value when successful, or
* -1 upon an error.
*/
int sip_X_d(su_home_t *home, sip_header_t *h, char *s, int bsiz);
/**Encode a header X.
*
* The function sip_X_e() encodes a header structure @a h to the given
* buffer @a buf. Even if the given buffer @a buf is NULL or its size @a
* bufsiz is too small to fit the encoding result, the function returns the
* number of characters required for the encoding.
*
* @param buf buffer to store the encoding result
* @param bsiz size of the encoding buffer
* @param h header to be encoded.
* @param flags flags controlling the encoding
*
* @note
* The encoding buffer size @b must be @b bigger than, not equal to,
* the actual encoding result.
*
* @return
* The function sip_X_e() returns the number of characters required for the
* encoding.
*
*/
int sip_X_e(char buf[], int bsiz, sip_header_t const *h, int flags);
/** @} */
/**@defgroup sip_status_codes SIP Status Codes and Reason Phrases
*
* The macros and variables for the standard SIP status codes and reason
* phrases are defined in <sofia-sip/sip_status.h>.
*/
/**@defgroup sip_tag SIP Tags
*
* SIP headers in tag item lists and tagged argument lists.
*
* The include file <sofia-sip/sip_tag.h> defines tags and tag items for including SIP
* headers in tag item lists or tagged argument lists. For each header,
* there is a tag for pointer to header object and an another tag for string
* containing header value. For example, @From header has tags
* SIPTAG_FROM() and SIPTAG_FROM_STR().
*
* It is also possible to include user-defined headers or non-standard
* headers using SIPTAG_HEADER_STR().
*
* A function taking SIP headers as arguments could be called like this:
* @code
* sip_payload_t *payload;
* ...
* sip_add_tl(msg, sip,
* SIPTAG_CONTENT_TYPE_STR("text/plain"),
* SIPTAG_USER_AGENT(agent->user_agent),
* SIPTAG_PAYLOAD(payload),
* SIPTAG_HEADER_STR("X-Header: contents\nP-Header: bar"),
* TAG_END());
* ...
* @endcode
*
* In the above fragment, the function sip_add_tl() will add @ContentType
* and @UserAgent headers along with message payload to the SIP message.
* The @ContentType header is made with value "text/plain".
*
*/