Skip to content

GitLab

Commit 2b480f01 authored by Pekka Pessi's avatar Pekka Pessi
Browse files

Updated ADD-A-HEADER file in sip module. 

darcs-hash:20060511092406-65a35-2cf1cd79173ccfe74e482ec93525b9e8f3f0c0cc.gz
parent d75b4bf2
Hide whitespace changes
Inline Side-by-side
Showing with 84 additions and 84 deletions
libsofia-sip-ua/sip/ADD-A-HEADER
View file @ 2b480f01
Description of Adding a SIP Header to Sofia SIP
===============================================
by Pekka Pessi (2002-08-16, updated 2005-10-05)
by Pekka Pessi (2002-08-16, updated 2006-05-11)
There are two ways to extend the Sofia SIP parser, either including a
standard header in normal distribution or putting the non-standar extension
headers into a separate library.
In the text below, we use "Example" header as our example with following
ABNF:
sip-example = "Example" COLON 1*DIGIT
There are two ways to extend your parser.
* 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.
IF YOUR HEADER IS A STANDARD ONE:
IF YOUR HEADER IS A STANDARD ONE
--------------------------------
* In <sip.h>, add:
- Add typedefs to the header structures.
- Add typedef to the header structure.
The typedefs to ordinary headers are also in more or less alphabetic
The typedefs to ordinary headers are in more or less alphabetic
order after typedef of sip_unknown_t. You should add a typedef line
like this:
......@@ -32,16 +29,71 @@ IF YOUR HEADER IS A STANDARD ONE:
Note that the typedefs are documented together with the
implementation in the .c file.
- Add field to the sip_t structure (struct sip_s)
- remember to add a comment after field for AWK script:
sip_example_t *sip_example; /**< Example */
- NOTE: the AWK script msg_parser.awk automatically creates the default
prototypes and tags for the newly created header, when the entry in
sip_t structure is formatted like to the example above
- Add field to the sip_t structure (struct sip_s)
- Remember to add a comment containing the header name
after field for benefit of the AWK script autmatically generating
boilerplate functions and macros:
sip_example_t *sip_example; /**< Example */
- The AWK script msg_parser.awk automatically creates the default
prototypes and tags for the newly created header when the entry in
sip_t structure is formatted like to the example above.
It will complain about mismatches between header name and field name.
* Add the actual header structure:
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. */
};
* 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
- remember to run autogen.sh unless you have given --enable-maintainer-mode
to configure script
IF YOUR HEADERS ARE NON-STANDARD:
* Run "make check" after you are ready
- Create a header template for your header just like sip_rfc2543.h.in,
* Run "make check" after you are ready. Really.
IF YOUR HEADERS ARE NON-STANDARD
--------------------------------
- There is an example package sofia-sip-2543.tar.gz, available from
sofia-sip.sourceforge.net
See the extension package for 1)
- Create a header template for your header just like
sofia-sip/rfc2543.h.in (found in <sofia-sip/rfc2543.h> package),
e.g, sip_example.h.in:
---8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<---
......@@ -66,31 +118,27 @@ IF YOUR HEADERS ARE NON-STANDARD:
*/
#ifndef SIP_H
#include <sip.h>
#include <sofia-sip/sip.h>
#endif
#ifndef SIP_HEADER_H
#include <sofia-sip/sip_header.h>
#endif
/**@ingroup sip_also
* @brief Structure for @b Also header.
/**@ingroup sip_example
* @brief Structure for @b Example header.
*/
struct sip_also_s
struct sip_example_s
{
sip_common_t also_common[1]; /**< Common fragment info */
sip_also_t *also_next; /**< Link to next Also header */
char const *also_display; /**< Display name */
url_t also_url[1]; /**< URL */
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 */
};
typedef struct sip_also_s sip_also_t;
typedef sip_generic_t sip_hide_t;
typedef sip_auth_t sip_encryption_t;
typedef sip_auth_t sip_response_key_t;
typedef struct sip_example_s sip_example_t;
struct sip_example_dummy_structure {
/* === Headers start here */
sip_also_t *sip_also; /**< Also */
sip_hide_t *sip_hide; /**< Hide */
sip_encryption_t *sip_encryption; /**< Encryption */
sip_response_key_t *sip_response_key; /**< Response-Key */
sip_example_t *sip_example; /**< Example */
/* === Headers end here */
};
......@@ -98,53 +146,5 @@ struct sip_example_dummy_structure {
#endif /** !defined(SIP_EXAMPLE_H) */
--->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---->8---
- Add a makefile rule
$s/sip_example.h: $s/sip_example.h.in
${AWK} -f ${sofiaexecdir}/msg_parser.awk module=sip PR=$@ \
NO_FIRST=1 NO_LAST=1 \
TEMPLATE1=$i/sip_hclasses.h.in \
TEMPLATE2=$i/sip_protos.h.in \
TEMPLATE3=$i/sip_tag.h.in \
$s/sip_example.h.in
$s/sip_example_tag.c: $s/sip_example_tag.c.in $s/sip_example.h.in
${AWK} -f ${sofiaexecdir}/msg_parser.awk module=sip PR=$@ \
NO_FIRST=1 NO_LAST=1 \
$s/sip_example.h.in
- Add the actual header structure:
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. */
};
* 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
* run "make check" after you are ready
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment