Loading...
Searching...
No Matches
msg_header.h File Reference
Headers

Message headers. More...

`#include <stdarg.h>`
`#include <string.h>`
`#include <sofia-sip/su_types.h>`
`#include <sofia-sip/su_alloc.h>`
`#include <sofia-sip/msg.h>`
`#include <sofia-sip/url.h>`
`#include <sofia-sip/msg_protos.h>`
Include dependency graph for msg_header.h:

Go to the source code of this file.

## Macros

#define | MSG_HEADER_H
| Defined when <sofia-sip/msg_header.h> has been included.
#define | MSG_CHUNK_BUFFER(pl)
| Get pointer to beginning of available buffer space.
#define | MSG_CHUNK_AVAIL(pl)
| Get size of available buffer space.
#define | MSG_CHUNK_NEXT(pl)
| Get next chunk in list.
#define | MSG_HEADER_INIT(h, msg_class, size)
| Initialize a header structure.
#define | MSG_HEADER_NONE
| No header.

## Functions

msg_header_t * | msg_header_alloc (su_home_t *, msg_hclass_t *hc, isize_t extra))
| Allocate a header structure.
isize_t | msg_header_size (msg_header_t const *h)
| Calculate the size of a duplicate of a header structure.
msg_header_t ** | msg_header_offset (msg_t const *, msg_pub_t const *, msg_header_t const *)
| Get offset of header h from structure mo.
msg_header_t ** | msg_hclass_offset (msg_mclass_t const *, msg_pub_t const *, msg_hclass_t *)
| Find place to insert header of the class hc.
msg_header_t * | msg_header_access (msg_pub_t const *pub, msg_hclass_t *hc)
| Get a header from the public message structure.
msg_header_t * | msg_header_copy_as (su_home_t *home, msg_hclass_t *hc, msg_header_t const *o))
| Copy a list of header objects.
msg_header_t * | msg_header_copy (su_home_t *home, msg_header_t const *o))
| Copy a header list.
msg_header_t * | msg_header_copy_one (su_home_t *home, msg_header_t const *o))
| Copy a single header.
msg_header_t * | msg_header_dup_as (su_home_t *home, msg_hclass_t *hc, msg_header_t const *o))
| Duplicate a header as class hc.
msg_header_t * | msg_header_dup (su_home_t *home, msg_header_t const *h))
| Duplicate a header list.
msg_header_t * | msg_header_dup_one (su_home_t *home, msg_header_t const *h))
| Duplicate a sigle header.
msg_header_t * | msg_header_d (su_home_t *home, msg_t const *msg, char const *b)
| Decode a message header.
issize_t | msg_header_e (char b[], isize_t bsiz, msg_header_t const *h, int flags)
| Encode a header.
issize_t | msg_object_e (char b[], isize_t size, msg_pub_t const *mo, int flags)
| Encode a message to the buffer.
issize_t | msg_header_field_e (char b[], isize_t bsiz, msg_header_t const *h, int flags)
| Encode header contents.
int | msg_header_remove (msg_t *msg, msg_pub_t *mo, msg_header_t *h)
| Remove a header from the header structure and fragment chain.
int | msg_header_remove_all (msg_t *msg, msg_pub_t *mo, msg_header_t *h)
| Remove a header list from the header structure and fragment chain.
int | msg_header_insert (msg_t *msg, msg_pub_t *mo, msg_header_t *h)
| Insert a (list of) header(s) to the fragment chain.
int | msg_header_replace (msg_t *msg, msg_pub_t *mo, msg_header_t *old_header, msg_header_t *new_header)
| Replace a header item with a (list of) header(s).
int | msg_header_add_dup (msg_t *msg, msg_pub_t *pub, msg_header_t const *o)
| Duplicate and add a (list of) header(s) to the message.
int | msg_header_add_str (msg_t *msg, msg_pub_t *pub, char const *str)
| Add string contents to message.
int | msg_header_parse_str (msg_t *msg, msg_pub_t *pub, char *s)
| Add string to message.
int | msg_header_add_dup_as (msg_t *msg, msg_pub_t *pub, msg_hclass_t *hc, msg_header_t const *o)
| Duplicate a header as a given type and add the duplicate into message.
int | msg_header_add_make (msg_t *msg, msg_pub_t *pub, msg_hclass_t *hc, char const *s)
| Parse a string as a given header field and add result to the message.
int | msg_header_add_format (msg_t *msg, msg_pub_t *pub, msg_hclass_t *hc, char const *fmt,...)
| Add formatting result to message.
int | msg_header_prepend (msg_t *msg, msg_pub_t *pub, msg_header_t **hh, msg_header_t *h)
| Prepend a (list of) header(s) to the header structure and fragment chain.
msg_header_t * | msg_header_make (su_home_t *home, msg_hclass_t *hc, char const *s))
| Make a header from a value string.
msg_header_t * | msg_header_vformat (su_home_t *home, msg_hclass_t *hc, char const *fmt, va_list ap))
| Make a MSG header with formatting provided.
void | msg_header_free (su_home_t *home, msg_header_t *h)
| Free a header structure.
void | msg_header_free_all (su_home_t *home, msg_header_t *h)
| Free a (list of) header structures.
msg_payload_t * | msg_payload_create (su_home_t *home, void const *data, usize_t len))
| Create a MIME payload.
issize_t | msg_headers_prepare (msg_t *, msg_header_t *headers, int flags)
| Encode headers in chain.
void | msg_fragment_clear (msg_common_t *h)
| Clear encoded data from header structure.
msg_param_t ** | msg_header_params (msg_common_t const *h)
| Pointer to header parameters.
void | msg_fragment_clear_chain (msg_header_t *h)
| Clear encoded data from header fields.
char const * | msg_header_find_param (msg_common_t const *, char const *name)
| Find a header parameter.
int | msg_header_add_param (su_home_t *, msg_common_t *h, char const *param)
| Add a parameter to a header.
int | msg_header_replace_param (su_home_t *, msg_common_t *h, char const *param)
| Replace or add a parameter to a header.
int | msg_header_remove_param (msg_common_t *h, char const *name)
| Remove a parameter from header.
char const * | msg_header_find_item (msg_common_t const *h, char const *item)
| Find a header item.
int | msg_header_replace_item (su_home_t *, msg_common_t *h, char const *item)
| Add an item to a header.
int | msg_header_remove_item (msg_common_t *h, char const *name)
| Remove an item from a header.
int | msg_list_append_items (su_home_t *home, msg_list_t *k, msg_param_t const items[])
| Append a list of constant items to a list.
int | msg_list_replace_items (su_home_t *home, msg_list_t *k, msg_param_t const items[])
| Replace a list of constant items on a list.
int | msg_header_join_items (su_home_t *home, msg_common_t *dst, msg_common_t const *src, int duplicate)
| Join header item lists.
issize_t | msg_random_token (char token[], isize_t tlen, void const *d, isize_t dlen)
| Generates a random token.
int | msg_params_cmp (char const *const a[], char const *const b[])
| Compare parameter lists.
size_t | msg_params_length (char const *const *params)
| Calculate number of parameters in a parameter list.
char * | msg_unquote_dup (su_home_t *home, char const *q))
| Unquote a string, return a duplicate.
char * | msg_unquote (char *dst, char const *s)
| Unquote string.
unsigned long | msg_hash_string (char const *id)
| Calculate a hash over a string.

## Detailed Description

Message headers.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com

Date
  Created: Mon Aug 27 15:44:27 2001 ppessi

## Function Documentation

## msg_fragment_clear_chain()

void msg_fragment_clear_chain | ( | msg_header_t * | h | ) |

Clear encoded data from header fields.

Clear encoded or cached unencoded headers from header fields.

Parameters

  h | pointer to header structure

## msg_hash_string()

unsigned long msg_hash_string | ( | char const * | id | ) |

Calculate a hash over a string.

Calculate a hash over a string.

## msg_header_access()

msg_header_t * msg_header_access | ( | msg_pub_t const * | pub,
|  | msg_hclass_t * | hc )

Get a header from the public message structure.

Gets a pointer to header from a message structure.

Parameters

  pub | public message structure from which header is obtained
  hc | header class

## msg_header_add_dup()

int msg_header_add_dup | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | msg_header_t const * | src )

Duplicate and add a (list of) header(s) to the message.

The function `msg_header_add_dup()` duplicates and adds a (list of) header(s) into a message structure.

When inserting headers into the fragment chain, a request (or status) is inserted first and replaces the existing request (or status). Other headers are inserted after the request or status.

If the header is a singleton, existing headers with the same class are removed.

Parameters

  msg | message owning the fragment chain
  pub | public message structure to which header is added
  src | list of header(s) to be added

## msg_header_add_dup_as()

int msg_header_add_dup_as | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | msg_hclass_t * | hc,
|  | msg_header_t const * | src )

Duplicate a header as a given type and add the duplicate into message.

The function `msg_header_add_dup_as()` duplicates a header as a instance of the given header class. It adds the new copy into the message.

When inserting headers into the fragment chain, a request (or status) is inserted first and replaces the existing request (or status). Other headers are inserted after the request or status.

If the header is a singleton, existing headers with the same class are removed.

Parameters

  msg | message owning the fragment chain
  pub | public message structure to which header is added
  hc | header class for header target type
  src | list of header(s) to be duplicated and added

## msg_header_add_format()

int msg_header_add_format | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | msg_hclass_t * | hc,
|  | char const * | fmt,
|  |  | ... )

Add formatting result to message.

Parse result from printf-formatted params as a given header field and add result to the message.

Since
  New in 1.12.10

## msg_header_add_param()

int msg_header_add_param | ( | su_home_t * | home,
|  | msg_common_t * | h,
|  | char const * | param )

Add a parameter to a header.

You should use this function only when the header accepts multiple parameters (or list items) with the same name. If that is not the case, you should use msg_header_replace_param().

Note
  This function does not duplicate `param`. The caller should have allocated the param from the memory home associated with header h.

The possible shortcuts to parameter values are updated. For example, the "received" parameter in Via header has shortcut in structure sip_via_t, the v_received field. The shortcut is usully a pointer to the parameter value. If the parameter was "received=127.0.0.1" the v_received field would be a pointer to "127.0.0.1". If the parameter was "received=" or "received", the shortcut would be a pointer to an empty string, "".

Parameters

  home | memory home used to re-allocate parameter list in header
  h | pointer to a header
  param | parameter to be replaced or added

Return values

  0 | if parameter was added
  -1 | upon an error

See also
  msg_header_replace_param(), msg_header_remove_param(), msg_header_update_params(), msg_common_t, msg_header_t, msg_hclass_t, msg_hclass_t::hc_params, msg_hclass_t::hc_update

## msg_header_add_str()

int msg_header_add_str | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | char const * | str )

Add string contents to message.

Duplicate a string containing headers (or a message body, if the string starts with linefeed), parse it and add resulting header objects to the message object.

Parameters

  msg | message object
  pub | message header structure where heades are added (may be NULL)
  str | string to be copied and parsed (not modified, may be NULL)

Return values

  0 | when succesful
  -1 | upon an error

## msg_header_alloc()

msg_header_t * msg_header_alloc | ( | su_home_t * | home,
|  | msg_hclass_t * | hc,
|  | isize_t | extra )

Allocate a header structure.

The msg_header_alloc() function allocates a generic MO header structure and returns a pointer to it.

Parameters

  home | memory home
  hc | header class
  extra | amount of extra memory to be allocated after header structure

Returns
  A pointer to the newly created header object, or `NULL` upon an error.

## msg_header_copy_as()

msg_header_t * msg_header_copy_as | ( | su_home_t * | home,
|  | msg_hclass_t * | hc,
|  | msg_header_t const * | src )

Copy a list of header objects.

The function `msg_header_copy_as()` shallowly copies a list of header objects, and casts them to the given header class.

Parameters

  home | pointer to the memory home
  hc | header class
  src | pointer to a list of header objects to be copied

Returns
  The function `msg_header_copy_as()` returns a pointer to the first of the copied msg header object(s), or `NULL` upon an error.

## msg_header_dup()

msg_header_t * msg_header_dup | ( | su_home_t * | home,
|  | msg_header_t const * | h )

Duplicate a header list.

The function `msg_header_dup()` deeply copies a list of message headers objects.

Parameters

  home | pointer to the memory home
  h | pointer to a list of header objects to be copied

Returns
  The function `msg_header_dup()` returns a pointer to the first of the copied message header object(s), or `NULL` upon an error.

## msg_header_dup_as()

msg_header_t * msg_header_dup_as | ( | su_home_t * | home,
|  | msg_hclass_t * | hc,
|  | msg_header_t const * | src )

Duplicate a header as class hc.

The function `msg_header_dup_as()` casts a list of header headers to given type, and then deeply copies the list.

Parameters

  home | pointer to the memory home
  hc | header class
  src | pointer to a list of header objects to be copied

Returns
  The function `msg_header_copy_as()` returns a pointer to the first of the copied msg header object(s), or `NULL` upon an error.

## msg_header_dup_one()

msg_header_t * msg_header_dup_one | ( | su_home_t * | home,
|  | msg_header_t const * | src )

Duplicate a sigle header.

Deeply copy a single header.

Parameters

  home | pointer to the memory home
  src | pointer to asingle header object to be copied

Returns
  Return a pointer to the the duplicated msg header object(s), or `NULL` upon an error.

## msg_header_e()

issize_t msg_header_e | ( | char | b[],
|  | isize_t | bsiz,
|  | msg_header_t const * | h,
|  | int | flags )

Encode a header.

The function msg_header_e() encodes a header field in the buffer b[]. The encoding includes its name and trailing CRLF. The function returns the length of the encoding in bytes, excluding the final `NUL`. The buffer b must be large enough for whole encoding, including the final `NUL`.

The flags parameter define how the encoding is done. If the flags specify `MSG_DO_COMPACT`, the encoding is compact (short form with minimal whitespace).

## msg_header_find_item()

char const * msg_header_find_item | ( | msg_common_t const * | h,
|  | char const * | item )

Find a header item.

Searches for given item name from the header. If item is found, the function returns a non-NULL pointer to the item.

Parameters

  h | pointer to header structure
  item | item

Returns
  A pointer to item, or NULL if it was not found.

Since
  New in 1.12.4

See also
  msg_header_replace_item(), msg_header_remove_item(), Allow, Allow-Events

## msg_header_find_param()

char const * msg_header_find_param | ( | msg_common_t const * | h,
|  | char const * | name )

Find a header parameter.

Searches for given parameter name from the header. If parameter is found, it returns a non-NULL pointer to the parameter value. If there is no value for the name (in form "name" or "name=value"), the returned pointer points to a NUL character.

Parameters

  h | pointer to header structure
  name | parameter name (with or without "=" sign)

Returns
  A pointer to parameter value, or NULL if parameter was not found.

## msg_header_insert()

int msg_header_insert | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | msg_header_t * | h )

Insert a (list of) header(s) to the fragment chain.

The function `msg_header_insert()` inserts header or list of headers into a message structure. It also inserts them into the the message fragment chain, if it exists.

When inserting headers into the fragment chain, a request (or status) is inserted first and replaces the existing request (or status). Other headers are inserted after the request or status.

If there can be only one header field of this type (hc_kind is msg_kind_single), existing header objects with the same class are removed.

Parameters

  msg | message object owning the fragment chain
  pub | public message structure to which header is added
  h | list of header(s) to be added

## msg_header_join_items()

int msg_header_join_items | ( | su_home_t * | home,
|  | msg_common_t * | dst,
|  | msg_common_t const * | src,
|  | int | duplicate )

Join header item lists.

Join items from a source header to the destination header. The item are compared with the existing ones. If a match is found, it is not added to the list. If duplicate is true, the entries are duplicated while they are added to the list.

Parameters

  home | memory home
  dst | destination header
  src | source header
  duplicate | if true, allocate and copy items that are added

Returns

Return values

  >= | 0 when successful
  -1 | upon an error

Since
  New in 1.12.5.

## msg_header_parse_str()

int msg_header_parse_str | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | char * | s )

Add string to message.

Parse a string containing headers (or a message body, if the string starts with linefeed) and add resulting header objects to the message object.

Parameters

  msg | message object
  pub | message header structure where heades are added (may be NULL)
  s | string to be parsed (and modified)

Return values

  0 | when succesful
  -1 | upon an error

See also
  msg_header_add_str(), url_headers_as_string()

Since
  New in 1.12.4.

## msg_header_prepend()

int msg_header_prepend | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | msg_header_t ** | hh,
|  | msg_header_t * | h )

Prepend a (list of) header(s) to the header structure and fragment chain.

The function `msg_header_prepend()` adds a header or list of headers into the given place within the message structure. It also inserts the headers into the the message fragment chain, if it exists.

Unlike msg_header_add(), msg_header_prepend() always inserts header h before other headers of the same class. If the header is a singleton, existing headers of the same class are removed. If the header is a list header, the values in the new header are prepended to the existing list.

Parameters

  msg | message owning the fragment chain
  pub | public message structure
  hh | place in message structure to which header is added
  h | list of header(s) to be added

## msg_header_remove()

int msg_header_remove | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | msg_header_t * | h )

Remove a header from the header structure and fragment chain.

The function `msg_header_remove()` removes a header from a message structure. It also removes the message from the message fragment chain and clears the encoding of other headers objects that share same encoding.

Parameters

  msg | message owning the fragment chain
  pub | public message structure to which header is added
  h | header to be removed

## msg_header_remove_all()

int msg_header_remove_all | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | msg_header_t * | h )

Remove a header list from the header structure and fragment chain.

The function `msg_header_remove_all()` removes a list of headers from a message structure. It also removes the message from the message fragment chain and clears the encoding of other headers objects that share same encoding.

Parameters

  msg | message owning the fragment chain
  pub | public message structure to which header is added
  h | header list to be removed

## msg_header_remove_item()

int msg_header_remove_item | ( | msg_common_t * | h,
|  | char const * | name )

Remove an item from a header.

This function treats a msg_header_t as set of C strings. The item is a C string. If identical string is found from the list, it is removed.

The shortcuts, if any, to item values are updated accordingly.

Parameters

  h | pointer to a header
  name | item to be removed

Return values

  0 | if item was added
  1 | if item was replaced
  -1 | upon an error

Since
  New in 1.12.4.

See also
  msg_header_replace_item(), Allow, Allow-Events, msg_header_replace_param(), msg_header_remove_param(), msg_common_t, msg_header_t, msg_list_t msg_hclass_t, msg_hclass_t::hc_params

## msg_header_remove_param()

int msg_header_remove_param | ( | msg_common_t * | h,
|  | char const * | name )

Remove a parameter from header.

The parameter name is given as token optionally followed by "=" sign and value. The "=" and value after it are ignored when selecting a parameter to remove.

The possible shortcuts to parameter values are updated. For example, the "received" parameter in Via header has shortcut in structure sip_via_t, the v_received field. The shortcut to removed parameter would be set to NULL.

Parameters

  h | pointer to a header
  name | name of parameter to be removed

Return values

  1 | if a parameter was removed
  0 | if no parameter was not removed
  -1 | upon an error

See also
  msg_header_add_param(), msg_header_replace_param(), msg_header_update_params(), msg_common_t, msg_header_t, msg_hclass_t, msg_hclass_t::hc_params, msg_hclass_t::hc_update

## msg_header_replace()

int msg_header_replace | ( | msg_t * | msg,
|  | msg_pub_t * | pub,
|  | msg_header_t * | replaced,
|  | msg_header_t * | h )

Replace a header item with a (list of) header(s).

The function `msg_header_replace()` removes a header structure from message and replaces it with a new one or a list of headers. It inserts the new headers into the the message fragment chain, if it exists.

Parameters

  msg | message object owning the fragment chain
  pub | public message structure to which header is added
  replaced | old header to be removed (may be NULL)
  h | list of header(s) to be added (may be NULL)

## msg_header_replace_item()

int msg_header_replace_item | ( | su_home_t * | home,
|  | msg_common_t * | h,
|  | char const * | item )

Add an item to a header.

This function treats a msg_header_t as set of C strings. The item is a C string. If no identical string is found from the list, it is added to the list.

The shortcuts, if any, to item values are updated accordingly.

Parameters

  home | memory home used to re-allocate list in header
  h | pointer to a header
  item | item to be removed

Return values

  0 | if item was added
  1 | if item was replaced
  -1 | upon an error

Since
  New in 1.12.4.

See also
  msg_header_remove_item(), Allow, Allow-Events, msg_header_replace_param(), msg_header_remove_param(), msg_common_t, msg_header_t, msg_list_t msg_hclass_t, msg_hclass_t::hc_params

## msg_header_replace_param()

int msg_header_replace_param | ( | su_home_t * | home,
|  | msg_common_t * | h,
|  | char const * | param )

Replace or add a parameter to a header.

A header parameter param is a string of format name "=" value or just name. The value part following "=" is ignored when selecting a parameter to replace.

Note
  This function does not duplicate `param`. The caller should have allocated the param from the memory home associated with header h.

The possible shortcuts to parameter values are updated. For example, the "received" parameter in Via header has shortcut in structure sip_via_t, the v_received field.

Parameters

  home | memory home used to re-allocate parameter list in header
  h | pointer to a header
  param | parameter to be replaced or added

Return values

  0 | if parameter was added
  1 | if parameter was replaced
  -1 | upon an error

See also
  msg_header_add_param(), msg_header_remove_param(), msg_header_update_params(), msg_common_t, msg_header_t, msg_hclass_t, msg_hclass_t::hc_params, msg_hclass_t::hc_update

## msg_headers_prepare()

issize_t msg_headers_prepare | ( | msg_t * | msg,
|  | msg_header_t * | headers,
|  | int | flags )

Encode headers in chain.

The function msg_headers_prepare() encodes all the headers in the header chain. You have to call msg_serialize() before calling msg_headers_prepare() in order to make sure that all the heades and other message fragments are included in the chain.

Returns
  The size of all the headers in chain, or -1 upon an error.

## msg_list_append_items()

int msg_list_append_items | ( | su_home_t * | home,
|  | msg_list_t * | k,
|  | msg_param_t const | items[] )

Append a list of constant items to a list.

Return values

  0 | when successful
  -1 | upon an error

## msg_list_replace_items()

int msg_list_replace_items | ( | su_home_t * | home,
|  | msg_list_t * | k,
|  | msg_param_t const | items[] )

Replace a list of constant items on a list.

Replace a list of constant items on a list.

Return values

  0 | when successful
  -1 | upon an error

## msg_object_e()

issize_t msg_object_e | ( | char | b[],
|  | isize_t | size,
|  | msg_pub_t const * | mo,
|  | int | flags )

Encode a message to the buffer.

The function msg_encode_e encodes a message to a given buffer. It returns the length of the message to be encoded, even if the buffer is too small (just like snprintf() is supposed to do).

Parameters

  b | buffer (may be NULL)
  size | size of buffer
  mo | public message structure (sip_t, http_t)
  flags | see #

## msg_params_cmp()

int msg_params_cmp | ( | char const *const | a[],
|  | char const *const | b[] )

Compare parameter lists.

Compares parameter lists.

Parameters

  a | pointer to a parameter list
  b | pointer to a parameter list

Return values

  an | integer less than zero if is less than b
  an | integer zero if match with b
  an | integer greater than zero if is greater than b

## msg_unquote_dup()

char * msg_unquote_dup | ( | su_home_t * | home,
|  | char const * | q )

Unquote a string, return a duplicate.

Unquote a string, return a duplicate.

Duplicates the string q in unquoted form.

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