sip.docs 22.7 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2
/* -*- c -*- */

3
/**@MODULEPAGE "sip" - SIP Parser Module
Pekka Pessi's avatar
Pekka Pessi committed
4 5 6 7 8 9 10 11
 *
 * @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>
 *
12
 * @STATUS @SofiaSIP Core library
Pekka Pessi's avatar
Pekka Pessi committed
13 14 15 16 17
 *
 * @LICENSE LGPL
 *
 * @section sip_overview Overview
 *
18
 * The structure of each header is defined in @b <sofia-sip/sip.h>. In addition to the
Pekka Pessi's avatar
Pekka Pessi committed
19 20
 * header structure, there is defined a @em header @em class structure and
 * some standard functions for each header in the include file @b
21 22 23 24 25
 * <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.
 *
Pekka Pessi's avatar
Pekka Pessi committed
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
 * 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
71
 * type, #msg_t, defined in <sofia-sip/msg.h>. The internal structure of #msg_t is
Pekka Pessi's avatar
Pekka Pessi committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
 * 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.
 *
96
 * For instance, the @From header has following syntax:
Pekka Pessi's avatar
Pekka Pessi committed
97 98 99 100 101 102 103 104 105 106 107
 *
 * @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
 *
108
 * When a @From header is parsed, the header parser function sip_from_d()
Pekka Pessi's avatar
Pekka Pessi committed
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
 * 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
135
 * directly the @From header instead of going through all headers and
Pekka Pessi's avatar
Pekka Pessi committed
136 137 138 139 140
 * 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
141 142
 * programmer, second (#sip_t) is a public structure containing the parsed
 * headers.
Pekka Pessi's avatar
Pekka Pessi committed
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
 *
 * 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
 *
158 159 160 161
 *   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
Pekka Pessi's avatar
Pekka Pessi committed
162 163 164 165 166 167 168 169 170
 *   ...
 * } 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
171
 * parsing and printing process. They are documented in the <sofia-sip/msg.h>. These
Pekka Pessi's avatar
Pekka Pessi committed
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208
 * 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
209 210 211 212
 * 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.
Pekka Pessi's avatar
Pekka Pessi committed
213 214 215 216 217 218
 * 
 * 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
219 220 221
 * 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.
Pekka Pessi's avatar
Pekka Pessi committed
222
 *
Pekka Pessi's avatar
Pekka Pessi committed
223 224
 */

Pekka Pessi's avatar
Pekka Pessi committed
225
/**@defgroup sip_headers SIP Headers
Pekka Pessi's avatar
Pekka Pessi committed
226 227
 *
 * SIP headers and other SIP message elements.
Pekka Pessi's avatar
Pekka Pessi committed
228 229 230 231 232 233 234 235 236
 *
 * 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.
 *
237 238
 */

239 240
/**@ingroup sip_headers
 * @defgroup sip_header_x SIP Header X - Conventions
241
 * 
242
 * For a SIP header X, there are types, functions, macros and global data
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
 * 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:
Pekka Pessi's avatar
Pekka Pessi committed
261 262 263
 * @code
 * typedef struct sip_X_s
 * {
264 265 266 267 268 269 270 271 272 273
 *   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
Pekka Pessi's avatar
Pekka Pessi committed
274 275 276
 * } sip_X_t;
 * @endcode
 *
277 278 279
 * 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
Pekka Pessi's avatar
Pekka Pessi committed
280 281
 * 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)
282
 * and the length of the encoding (@a h_len). (@a X_common is an array of size
Pekka Pessi's avatar
Pekka Pessi committed
283
 * 1, as it makes it easy to cast a header pointer to a pointer to
284
 * msg_common_t.)
Pekka Pessi's avatar
Pekka Pessi committed
285
 *
286
 * The @a X_next is a pointer to another header (usually a pointer to
Pekka Pessi's avatar
Pekka Pessi committed
287
 * structure of same type). If there are multiple headers with same name,
288
 * like the two "Via" headers in the example above, the @a X_next is used to
Pekka Pessi's avatar
Pekka Pessi committed
289 290
 * 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
291 292 293 294 295 296 297 298 299
 * 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.
300 301
 *
 * @{
302 303
 */

304
/**The structure #sip_X_t contains representation of a SIP
305 306 307 308 309 310 311 312 313 314 315
 * @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
Pekka Pessi's avatar
Pekka Pessi committed
316
 */
317
typedef struct sip_X_s sip_X_t;
Pekka Pessi's avatar
Pekka Pessi committed
318

319
/**@var msg_hclass_t sip_X_class[];
Pekka Pessi's avatar
Pekka Pessi committed
320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457
 * @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.
 */
458
sip_X_t *sip_X_copy(su_home_t *home, sip_X_t const *hdr);
Pekka Pessi's avatar
Pekka Pessi committed
459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565

/**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.
566
 * 
Pekka Pessi's avatar
Pekka Pessi committed
567 568 569
 */
int sip_X_e(char buf[], int bsiz, sip_header_t const *h, int flags);

570 571
/** @} */

Pekka Pessi's avatar
Pekka Pessi committed
572
/**@defgroup sip_status_codes SIP Status Codes and Reason Phrases
Pekka Pessi's avatar
Pekka Pessi committed
573
 *
574
 * The macros and variables for the standard SIP status codes and reason
575
 * phrases are defined in <sofia-sip/sip_status.h>.
Pekka Pessi's avatar
Pekka Pessi committed
576 577
 */

Pekka Pessi's avatar
Pekka Pessi committed
578
/**@defgroup sip_tag SIP Tags
Pekka Pessi's avatar
Pekka Pessi committed
579 580 581
 *
 * SIP headers in tag item lists and tagged argument lists. 
 *
582
 * The include file <sofia-sip/sip_tag.h> defines tags and tag items for including SIP
Pekka Pessi's avatar
Pekka Pessi committed
583 584
 * 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
585
 * containing header value. For example, @From header has tags
Pekka Pessi's avatar
Pekka Pessi committed
586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603
 * 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
 *
604 605 606
 * 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".
Pekka Pessi's avatar
Pekka Pessi committed
607 608
 *
 */