Loading...
Searching...
No Matches
SIP Header X - Conventions
SIP Headers

For a SIP header X, there are types, functions, macros and global data declared in <sofia-sip/sip_protos.h> and <sofia-sip/sip_hclass.h> as follows: More...

## Macros

#define | SIP_X_INIT()
| Initializer for structure sip_X_t.

## Typedefs

typedef struct sip_X_s | sip_X_t
| The structure sip_X_t contains representation of a SIP X header.

## Enumerations

enum | { sip_X_hash }

## Functions

sip_X_t * | sip_X_init (sip_X_t x[1])
| Initialize a structure sip_X_t.
int | sip_is_X (sip_header_t const *header)
| Test if header object is instance of sip_X_t.
sip_X_t * | sip_X_dup (su_home_t *home, sip_X_t const *hdr)
| Duplicate (deep copy) `sip_X_t`.
sip_X_t * | sip_X_copy (su_home_t *home, sip_X_t const *hdr)
| Copy a sip_X_t header structure.
sip_X_t * | sip_X_make (su_home_t *home, char const *s)
| Make a header structure sip_X_t.
sip_X_t * | sip_X_format (su_home_t *home, char const *fmt,...)))
| Make a X from formatting result.
int | sip_X_d (su_home_t *home, sip_header_t *h, char *s, int bsiz)
| Decode a header X.
int | sip_X_e (char buf[], int bsiz, sip_header_t const *h, int flags)
| Encode a header X.

## Variables

msg_hclass_t | sip_X_class []
| Header class for SIP X.
msg_parse_f | sip_X_d
| Parse a X.
msg_print_f | sip_X_e
| Print a X.

## Detailed Description

For a SIP header X, there are types, functions, macros and global data 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 header class for header X.

All header structures contain the common part, a sip_common_t structure (X_common[]), a link to the next header in list (X_next), and various fields describing the header value (in this case, X_value). The header structure looks like this:

typedef struct sip_X_s
{
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
} sip_X_t;
sip_X_t
struct sip_X_s sip_X_t
The structure sip_X_t contains representation of a SIP X header.
Definition sip.docs:317
msg_hclass_t
struct msg_hclass_s const msg_hclass_t
msg_header_t
MSG_HDR_T msg_header_t
msg_common_s
uint32_t
SU_U32_T uint32_t

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 fragment chain (h_succ, h_prev), a pointer to header class (h_class), a pointer to the text encoding of header contents (h_data) and the length of the encoding (h_len). (X_common is an array of size 1, as it makes it easy to cast a header pointer to a pointer to msg_common_t.)

The X_next is a pointer to another header (usually a pointer to structure of same type). If there are multiple headers with same name, like the two "Via" headers in the example above, the X_next is used to 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 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 X_params.

For more complex header structures, see sip_contact_t or sip_rack_t.

## Macro Definition Documentation

## SIP_X_INIT

#define SIP_X_INIT | ( |  | ) |

Initializer for structure sip_X_t.

A static sip_X_t structure must be initialized with the SIP_X_INIT() macro. For instance,

sip_X_t sip_X = SIP_X_INIT;
SIP_X_INIT
#define SIP_X_INIT()
Initializer for structure sip_X_t.
Definition sip.docs:352

## Typedef Documentation

## sip_X_t

typedef struct sip_X_s sip_X_t

The structure sip_X_t contains representation of a SIP X header.

The sip_X_t is defined as follows:

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;
msg_common_t
struct msg_common_s msg_common_t

## Enumeration Type Documentation

## anonymous enum

anonymous enum

Enumerator
sip_X_hash | Hash of X.

## Function Documentation

## sip_is_X()

int sip_is_X | ( | sip_header_t const * | header | ) |

inline

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.

Parameters

  header | pointer to the header structure to be tested

Returns
  The function sip_is_X() returns true (nonzero) if the header object is an instance of header X and false (zero) otherwise.

## sip_X_copy()

sip_X_t * sip_X_copy | ( | 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 hdr. If the header structure hdr contains a reference (`hdr->h_next`) to a list of headers, all the headers in that list are copied, too. The function uses given memory home to allocate all the memory areas used to copy the header structure hdr.

Parameters

  home | memory home used to allocate new structure
  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 header, including the encoding of the old header, if present.

Example
  X = sip_X_copy(home, sip->sip_X);
  sip_X_copy
  sip_X_t * sip_X_copy(su_home_t *home, sip_X_t const *hdr)
  Copy a sip_X_t header structure.

Returns
  The function sip_X_copy() returns a pointer to newly copied header structure, or NULL upon an error.

## sip_X_d()

int sip_X_d | ( | su_home_t * | home,
|  | sip_header_t * | h,
|  | char * | s,
|  | int | bsiz )

Decode a header X.

The function sip_X_d() decodes value of the header X in the preallocated header structure h. The string 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 s.

Parameters

  home | memory home used to allocate new header structure.
  h | sip_X_t header structure
  s | string to be decoded
  bsiz | length of string s

Returns
  The function sip_X_d() returns non-negative value when successful, or -1 upon an error.

## sip_X_dup()

sip_X_t * sip_X_dup | ( | su_home_t * | home,
|  | sip_X_t const * | hdr )

Duplicate (deep copy) `sip_X_t`.

The function sip_X_dup() duplicates a header structure hdr. If the header structure hdr contains a reference (`hdr->x_next`) to a list of headers, all the headers in the list are duplicated, too.

Parameters

  home | memory home used to allocate new structure
  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 home to allocate all the memory areas used to copy the header.

Example
  X = sip_X_dup(home, sip->sip_X);
  sip_X_dup
  sip_X_t * sip_X_dup(su_home_t *home, sip_X_t const *hdr)
  Duplicate (deep copy) sip_X_t.

Returns
  The function sip_X_dup() returns a pointer to the newly duplicated sip_X_t header structure, or NULL upon an error.

## sip_X_e()

int sip_X_e | ( | char | buf[],
|  | int | bsiz,
|  | sip_header_t const * | h,
|  | int | flags )

Encode a header X.

The function sip_X_e() encodes a header structure h to the given buffer buf. Even if the given buffer buf is NULL or its size bufsiz is too small to fit the encoding result, the function returns the number of characters required for the encoding.

Parameters

  buf | buffer to store the encoding result
  bsiz | size of the encoding buffer
  h | header to be encoded.
  flags | flags controlling the encoding

Note
  The encoding buffer size must be bigger than, not equal to, the actual encoding result.

Returns
  The function sip_X_e() returns the number of characters required for the encoding.

## sip_X_format()

sip_X_t * sip_X_format | ( | su_home_t * | home,
|  | char const * | fmt,
|  |  | ... )

inline

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 fmt specified. Then it allocates a new header structure, and uses the formatting result as the header value.

Parameters

  home | memory home used to allocate new header structure.
  fmt | string used as a printf()-style format
  ... | argument list for format

Note
  This function is usually implemented as a macro calling msg_header_format().

Returns
  The function sip_X_format() returns a pointer to newly makes header structure, or NULL upon an error.

## sip_X_init()

sip_X_t * sip_X_init | ( | sip_X_t | x[1] | ) |

inline

Initialize a structure sip_X_t.

An sip_X_t structure can be initialized with the sip_X_init() function/macro. For instance,

sip_X_t sip_X;
sip_X_init(&sip_X);
sip_X_init
sip_X_t * sip_X_init(sip_X_t x[1])
Initialize a structure sip_X_t.
Definition sip.docs:368

## sip_X_make()

sip_X_t * sip_X_make | ( | su_home_t * | home,
|  | char const * | s )

inline

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 s as the value of the structure.

Parameters

  home | memory home used to allocate new header structure.
  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().

Returns
  The function sip_X_make() returns a pointer to newly maked sip_X_t header structure, or NULL upon an error.

## Variable Documentation

## sip_X_class

msg_hclass_t sip_X_class[]

extern

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.

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.