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