ADD-A-HEADER 4.66 KB
Newer Older
1 2
Adding a SIP Header to Sofia SIP
================================
Pekka Pessi's avatar
Pekka Pessi committed
3

4
by Pekka Pessi (2002-08-16, last updated 2007-09-19)
5

6 7 8
There are two recommended ways to extend the Sofia SIP parser, including a
standard header in extra headers or putting the extension headers into a
separate library.
Pekka Pessi's avatar
Pekka Pessi committed
9 10 11 12 13 14

In the text below, we use "Example" header as our example with following
ABNF:

   sip-example = "Example" COLON 1*DIGIT

Pekka Pessi's avatar
Pekka Pessi committed
15

16 17
IF YOUR HEADER IS A STANDARD ONE
--------------------------------
Pekka Pessi's avatar
Pekka Pessi committed
18

19
  * In <sofia-sip/sip_extra.h>, add:
Pekka Pessi's avatar
Pekka Pessi committed
20

21
  - Add typedef to the header structure.
Pekka Pessi's avatar
Pekka Pessi committed
22

23
    You should add a typedef line like this:
Pekka Pessi's avatar
Pekka Pessi committed
24 25

     typedef struct sip_example_s sip_example_t;
26

Pekka Pessi's avatar
Pekka Pessi committed
27 28 29
    Note that the typedefs are documented together with the
    implementation in the .c file.

30
 - Add the actual header structure:
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49

    The header structure would look like below. The first field MUST be a
    sip_common_t structure, second field MUST be a pointer to next header
    with same name. As a convention, if there can be only one header field
    of this kind, the type of the "next" pointer is sip_error_t.

    The fields representing the header value are located after the mandatory
    fields, usually in the order they are present in the header contents. In
    this case, the Example header consist of a 32-bit integer:

       /**@ingroup sip_example
        * @brief Structure for Example header.
        */
       struct sip_example_s {
         sip_common_t   ex_common[1];	    /**< Common fragment info. */
         sip_error_t   *ex_next;	    /**< Link to next (dummy). */
         unsigned long  ex_value;	    /**< Value of example. */
       };

50 51 52
  * Add entry to sip_extra_headers.txt:
   - In this case:
     example @NEW_2_0 /* Example header */
53
   - The first is the base C name used for functions and types related to
54 55 56 57
     the type. The AWK script msg_parser.awk automatically creates the
     default prototypes and tags for the newly created header. It will
     complain about mismatches between header name and the base name.

58
   - If the entry is before #### DEFAULT HEADER LIST ENDS HERE ####
59 60 61
     the new header is added to the default parser
   - If after, the new header is added only to the extended parser.

62
   - The extended parser will be used after call to
63 64
     sip_update_default_mclass(NULL)

65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
  * Write parsing tests for your new headers in torture_sip.c:

    Add all relevant parsing/processing cases you can think of
    at the end of function sip_header_test() or add a testing
    function of your own.

  * Add implementation in a suitable ".c" file
    - For an simple example, see implementation of Date header in sip_basic.c
    - Add a documentation group with @defgroup
    - Document the typedef
    - Add header class structure
    - Add parsing and printing functions:
      + sip_example_d(), sip_example_e()
    - Add functions used when copying the header structure:
      + sip_example_dup_xtra(), sip_example_dup_one()

  * 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
Pekka Pessi's avatar
Pekka Pessi committed
84

85
  * Run "make check" after you are ready
Pekka Pessi's avatar
Pekka Pessi committed
86

87 88 89
  * Run "make check" after you are ready. Really.


90 91 92 93
IF YOUR HEADERS ARE COMPLETELY NON-STANDARD
-------------------------------------------

  * Add a separate library package for them
94 95 96 97

    - There is an example package sofia-sip-2543.tar.gz, available from
      sofia-sip.sourceforge.net

98
      See the extension package for 1)
99

100 101
    - Create a header template for your header just like
      sofia-sip/rfc2543.h.in (found in <sofia-sip/rfc2543.h> package),
Pekka Pessi's avatar
Pekka Pessi committed
102 103 104 105 106 107 108 109
      e.g, sip_example.h.in:

---8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<---
/**@file sip_example.h.in
 *
 * Template for <sip_example.h>.
 */

110
#ifndef SIP_EXAMPLE_H
Pekka Pessi's avatar
Pekka Pessi committed
111
/** Defined when <sip_example.h> has been included. */
112
#define SIP_EXAMPLE_H
Pekka Pessi's avatar
Pekka Pessi committed
113

114
/**@file sip_example.h
Pekka Pessi's avatar
Pekka Pessi committed
115 116 117 118 119 120 121 122 123 124 125
*
 * @brief Example header.
 *
 * #AUTO#
 *
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>.
 *
 * @date Created: Fri May 27 18:40:38 EEST 2005 ppessi
 */

#ifndef SIP_H
126 127 128 129
#include <sofia-sip/sip.h>
#endif
#ifndef SIP_HEADER_H
#include <sofia-sip/sip_header.h>
Pekka Pessi's avatar
Pekka Pessi committed
130 131
#endif

132 133
/**@ingroup sip_example
 * @brief Structure for @b Example header.
Pekka Pessi's avatar
Pekka Pessi committed
134
 */
135
struct sip_example_s
Pekka Pessi's avatar
Pekka Pessi committed
136
{
137 138 139
  sip_common_t   ex_common[1];    /**< Common fragment info */
  sip_error_t   *ex_next;	  /**< Link to next (dummy). */
  uint32_t       ex_value;	  /**< Value of Example */
Pekka Pessi's avatar
Pekka Pessi committed
140 141
};

142
typedef struct sip_example_s sip_example_t;
Pekka Pessi's avatar
Pekka Pessi committed
143 144 145

struct sip_example_dummy_structure {
  /* === Headers start here */
146
  sip_example_t *sip_example;                            /**< Example */
Pekka Pessi's avatar
Pekka Pessi committed
147 148 149 150 151 152
  /* === Headers end here */
};


#endif /** !defined(SIP_EXAMPLE_H) */
--->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---