sofia-sip/msg_header.h File Reference

---

Detailed Description

Message headers.

Author:

Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Date:

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

#include <stdarg.h>
#include <string.h>
#include <sofia-sip/su_types.h>
#include <sofia-sip/su_alloc.h>
#include <sofia-sip/url.h>
#include <sofia-sip/msg_protos.h>
#include <sofia-sip/msg.h>

Include dependency graph for msg_header.h:

Go to the source code of this file.

Defines
#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
SOFIA_BEGIN_DECLS SOFIAPUBFUN msg_header_t *	msg_header_alloc (su_home_t *, msg_hclass_t *hc, int extra))
	Allocate a header structure.
SOFIAPUBFUN int	msg_header_size (msg_header_t const *h)
	Calculate the size of a duplicate of a header structure.
SOFIAPUBFUN 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.
SOFIAPUBFUN 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.
SOFIAPUBFUN msg_header_t *	msg_header_access (msg_pub_t const *pub, msg_hclass_t *hc)
	Get a header from the public message structure.
SOFIAPUBFUN 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.
SOFIAPUBFUN msg_header_t *	msg_header_copy (su_home_t *home, msg_header_t const *o))
	Copy a header list.
SOFIAPUBFUN msg_header_t *	msg_header_copy_one (su_home_t *home, msg_header_t const *o))
	Copy a single header.
SOFIAPUBFUN 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.
SOFIAPUBFUN msg_header_t *	msg_header_dup (su_home_t *home, msg_header_t const *h))
	Duplicate a header list.
SOFIAPUBFUN msg_header_t *	msg_header_dup_one (su_home_t *home, msg_header_t const *h))
	Duplicate a sigle header.
SOFIAPUBFUN msg_header_t *	msg_header_d (su_home_t *home, msg_t const *msg, char const *b)
	Decode a message header.
SOFIAPUBFUN int	msg_header_e (char b[], int bsiz, msg_header_t const *h, int flags)
	Encode a header.
SOFIAPUBFUN int	msg_object_e (char b[], int size, msg_pub_t const *mo, int flags)
	Encode a message to the buffer.
SOFIAPUBFUN int	msg_header_field_e (char b[], int bsiz, msg_header_t const *h, int flags)
	Encode header contents.
SOFIAPUBFUN 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.
SOFIAPUBFUN 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.
SOFIAPUBFUN 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.
SOFIAPUBFUN 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).
SOFIAPUBFUN 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.
SOFIAPUBFUN int	msg_header_add_str (msg_t *msg, msg_pub_t *pub, char const *str)
	Parse a string and add resulting headers to the message.
SOFIAPUBFUN 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.
SOFIAPUBFUN 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.
SOFIAPUBFUN 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.
SOFIAPUBFUN msg_header_t *	msg_header_make (su_home_t *home, msg_hclass_t *hc, char const *s))
	Make a header from a value string.
SOFIAPUBFUN 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.
SOFIAPUBFUN void	msg_header_free (su_home_t *home, msg_header_t *h)
	Free a header structure.
SOFIAPUBFUN void	msg_header_free_all (su_home_t *home, msg_header_t *h)
	Free a (list of) header structures.
SOFIAPUBFUN msg_payload_t *	msg_payload_create (su_home_t *home, void const *data, int len))
	Create a MIME payload.
SOFIAPUBFUN int	msg_headers_prepare (msg_t *, msg_header_t *headers, int flags)
	Encode headers in chain.
SOFIAPUBFUN char const *	msg_header_find_param (msg_common_t const *, char const *name)
	Find a header parameter.
SOFIAPUBFUN int	msg_header_add_param (su_home_t *, msg_common_t *h, char const *param)
	Add a parameter to a header.
SOFIAPUBFUN int	msg_header_replace_param (su_home_t *, msg_common_t *h, char const *param)
	Replace or add a parameter to a header.
SOFIAPUBFUN int	msg_header_remove_param (msg_common_t *h, char const *name)
	Remove a parameter from header.
SOFIAPUBFUN 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.
SOFIAPUBFUN 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.
SOFIAPUBFUN int	msg_random_token (char token[], int tlen, void const *d, int dlen)
	Generates a random token.
SOFIAPUBFUN int	msg_params_cmp (char const *const a[], char const *const b[])
	Compare parameter lists.
SOFIAPUBFUN size_t	msg_params_length (char const *const *params)
	Calculate number of parameters in a parameter list.
SOFIAPUBFUN char *	msg_unquote_dup (su_home_t *home, char const *q))
	Unquote a string, return a duplicate.
SOFIAPUBFUN char *	msg_unquote (char *dst, char const *s)
	Unquote string.
SOFIAPUBFUN unsigned long	msg_hash_string (char const *id)
	Calculate a hash over a string.

---

Function Documentation

SOFIAPUBFUN 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

SOFIAPUBFUN 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

SOFIAPUBFUN 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

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

Add a parameter to a header.

A header parameter param is a string of format name "=" value or just name. The caller of msg_header_add_param() should have allocated it from memory home associated with header h.

Return values:

	0	if parameter was added
	-1	upon an error

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

Parse a string and add resulting headers to the message.

The function msg_header_add_str() parses a string and adds resulting header objects to the message object.

SOFIA_BEGIN_DECLS SOFIAPUBFUN msg_header_t* msg_header_alloc	(	su_home_t *	home,
		msg_hclass_t *	hc,
		int	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.

SOFIAPUBFUN 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.

SOFIAPUBFUN 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.

SOFIAPUBFUN 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.

SOFIAPUBFUN 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.

SOFIAPUBFUN int msg_header_e	(	char	b[],
		int	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).

SOFIAPUBFUN 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.

SOFIAPUBFUN 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 the header is a singleton, existing headers 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

SOFIAPUBFUN 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

SOFIAPUBFUN 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

SOFIAPUBFUN 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

SOFIAPUBFUN 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 are ignored.

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

SOFIAPUBFUN 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
	h	list of header(s) to be added

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

Replace or add a parameter to a header.

The shortcuts to parameter values are updated accordingly.

Note:

This function does not duplicate param.

Parameters:

	home	memory home
	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

SOFIAPUBFUN int 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.

SOFIAPUBFUN int msg_object_e	(	char	b[],
		int	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 #

SOFIAPUBFUN 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

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

Unquote a string, return a duplicate.

Duplicates the string q in unquoted form.

---

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