1Adding a SIP Header to Sofia SIP
2================================
3
4by Pekka Pessi (2002-08-16, last updated 2007-09-19)
5
6There are two recommended ways to extend the Sofia SIP parser, including a
7standard header in extra headers or putting the extension headers into a
8separate library.
9
10In the text below, we use "Example" header as our example with following
11ABNF:
12
13   sip-example = "Example" COLON 1*DIGIT
14
15
16IF YOUR HEADER IS A STANDARD ONE
17--------------------------------
18
19  * In <sofia-sip/sip_extra.h>, add:
20
21  - Add typedef to the header structure.
22
23    You should add a typedef line like this:
24
25     typedef struct sip_example_s sip_example_t;
26
27    Note that the typedefs are documented together with the
28    implementation in the .c file.
29
30 - Add the actual header structure:
31
32    The header structure would look like below. The first field MUST be a
33    sip_common_t structure, second field MUST be a pointer to next header
34    with same name. As a convention, if there can be only one header field
35    of this kind, the type of the "next" pointer is sip_error_t.
36
37    The fields representing the header value are located after the mandatory
38    fields, usually in the order they are present in the header contents. In
39    this case, the Example header consist of a 32-bit integer:
40
41       /**@ingroup sip_example
42        * @brief Structure for Example header.
43        */
44       struct sip_example_s {
45         sip_common_t   ex_common[1];	    /**< Common fragment info. */
46         sip_error_t   *ex_next;	    /**< Link to next (dummy). */
47         unsigned long  ex_value;	    /**< Value of example. */
48       };
49
50  * Add entry to sip_extra_headers.txt:
51   - In this case:
52     example @NEW_2_0 /* Example header */
53   - The first is the base C name used for functions and types related to
54     the type. The AWK script msg_parser.awk automatically creates the
55     default prototypes and tags for the newly created header. It will
56     complain about mismatches between header name and the base name.
57
58   - If the entry is before #### DEFAULT HEADER LIST ENDS HERE ####
59     the new header is added to the default parser
60   - If after, the new header is added only to the extended parser.
61
62   - The extended parser will be used after call to
63     sip_update_default_mclass(NULL)
64
65  * Write parsing tests for your new headers in torture_sip.c:
66
67    Add all relevant parsing/processing cases you can think of
68    at the end of function sip_header_test() or add a testing
69    function of your own.
70
71  * Add implementation in a suitable ".c" file
72    - For an simple example, see implementation of Date header in sip_basic.c
73    - Add a documentation group with @defgroup
74    - Document the typedef
75    - Add header class structure
76    - Add parsing and printing functions:
77      + sip_example_d(), sip_example_e()
78    - Add functions used when copying the header structure:
79      + sip_example_dup_xtra(), sip_example_dup_one()
80
81  * If you added a .c file, add to the Makefile.am
82    - remember to run autogen.sh unless you have given --enable-maintainer-mode
83      to configure script
84
85  * Run "make check" after you are ready
86
87  * Run "make check" after you are ready. Really.
88
89
90IF YOUR HEADERS ARE COMPLETELY NON-STANDARD
91-------------------------------------------
92
93  * Add a separate library package for them
94
95    - There is an example package sofia-sip-2543.tar.gz, available from
96      sofia-sip.sourceforge.net
97
98      See the extension package for 1)
99
100    - Create a header template for your header just like
101      sofia-sip/rfc2543.h.in (found in <sofia-sip/rfc2543.h> package),
102      e.g, sip_example.h.in:
103
104---8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<---
105/**@file sip_example.h.in
106 *
107 * Template for <sip_example.h>.
108 */
109
110#ifndef SIP_EXAMPLE_H
111/** Defined when <sip_example.h> has been included. */
112#define SIP_EXAMPLE_H
113
114/**@file sip_example.h
115*
116 * @brief Example header.
117 *
118 * #AUTO#
119 *
120 * @author Pekka Pessi <Pekka.Pessi@nokia.com>.
121 *
122 * @date Created: Fri May 27 18:40:38 EEST 2005 ppessi
123 */
124
125#ifndef SIP_H
126#include <sofia-sip/sip.h>
127#endif
128#ifndef SIP_HEADER_H
129#include <sofia-sip/sip_header.h>
130#endif
131
132/**@ingroup sip_example
133 * @brief Structure for @b Example header.
134 */
135struct sip_example_s
136{
137  sip_common_t   ex_common[1];    /**< Common fragment info */
138  sip_error_t   *ex_next;	  /**< Link to next (dummy). */
139  uint32_t       ex_value;	  /**< Value of Example */
140};
141
142typedef struct sip_example_s sip_example_t;
143
144struct sip_example_dummy_structure {
145  /* === Headers start here */
146  sip_example_t *sip_example;                            /**< Example */
147  /* === Headers end here */
148};
149
150
151#endif /** !defined(SIP_EXAMPLE_H) */
152--->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---
153