sofia-sip/msg_parser.h File Reference

Message parser interface. More...

#include <sofia-sip/su_alloc.h>
#include <sofia-sip/msg_header.h>
#include <sofia-sip/bnf.h>
#include <sofia-sip/url.h>

Include dependency graph for msg_parser.h:

Go to the source code of this file.

Defines
#define	MSG_PARSER_H
	Defined when <sofia-sip/msg_parser.h> has been included.
#define	MSG_HEADER_CLASS(pr, c, l, s, params, kind, dup, upd)
	Define a header class.
#define	MSG_TERM_E(p, e)
	Terminate encoding.
#define	MSG_CHAR_E(p, e, c)
	Encode a character.
#define	MSG_STRING_LEN(s, sep_size)
	Calculate separator and string length.
#define	MSG_STRING_E(p, e, s)
	Encode a string.
#define	MSG_STRING_DUP(p, d, s)
	Duplicate string.
#define	MSG_STRING_SIZE(s)
	Calculate string size.
#define	MSG_COMMALIST_E(b, end, params, compact)
	Encode a comma-separated parameter list.
#define	MSG_PARAM_MATCH(v, s, name)
	Match a parameter with any value.
#define	MSG_PARAM_MATCH_P(v, s, name)
	Match a parameter with known value.
#define	MSG_PARAMS_NUM(n)
	Calculate allocated number of items in parameter list.
#define	MSG_PARAMS_E(b, end, params, flags)
	Encode a list of parameters.
#define	MSG_PARAMS_SIZE(rv, params)
	Calculate extra size of parametes.
Functions
issize_t	msg_extract_header (msg_t *msg, msg_pub_t *mo, char b[], isize_t bsiz, int eos)
	Extract a header.
issize_t	msg_extract_separator (msg_t *msg, msg_pub_t *mo, char b[], isize_t bsiz, int eos)
	Extract a separator line.
issize_t	msg_extract_payload (msg_t *msg, msg_pub_t *mo, msg_header_t **return_payload, usize_t body_len, char b[], isize_t bsiz, int eos)
	Extract a message body of body_len bytes.
int	msg_firstline_d (char *s, char **ss2, char **ss3)
	Parse first line.
isize_t	msg_default_dup_xtra (msg_header_t const *header, isize_t offset)
	Calculate extra size of a plain header.
char *	msg_default_dup_one (msg_header_t *dst, msg_header_t const *src, char *b, isize_t xtra)
	Duplicate a header object without external references.
issize_t	msg_generic_d (su_home_t *, msg_header_t *, char *, isize_t)
	Parse a generic header.
issize_t	msg_generic_e (char[], isize_t, msg_header_t const *, int)
	Encode a generic header.
isize_t	msg_generic_dup_xtra (msg_header_t const *h, isize_t offset)
	Calculate the size of strings associated with a msg_generic_t object.
char *	msg_generic_dup_one (msg_header_t *dst, msg_header_t const *src, char *b, isize_t xtra)
	Duplicate one msg_generic_t object.
issize_t	msg_payload_d (su_home_t *, msg_header_t *h, char *s, isize_t slen)
	Parse payload.
issize_t	msg_separator_d (su_home_t *, msg_header_t *, char *, isize_t)
	Parse a separator line.
issize_t	msg_separator_e (char[], isize_t, msg_header_t const *, int)
	Encode a separator line.
issize_t	msg_auth_d (su_home_t *, msg_header_t *h, char *s, isize_t slen)
	Parse security headers.
char *	msg_auth_dup_one (msg_header_t *dst, msg_header_t const *src, char *b, isize_t xtra)
	Duplicate one msg_auth_t object.
void *	msg_header_data (msg_frg_t *h)
	Return pointer to extra data after header structure.
int	msg_hostport_d (char **ss, char const **return_host, char const **return_port)
	Parse host[":"port] pair.
issize_t	msg_token_d (char **ss, char const **return_token)
	Parse a token.
issize_t	msg_uint32_d (char **ss, uint32_t *return_value)
	Parse a 32-bit unsigned int.
issize_t	msg_comment_d (char **ss, char const **return_comment)
	Parse a comment.
issize_t	msg_quoted_d (char **ss, char **return_unquoted)
	Parse a quoted string.
issize_t	msg_unquoted_e (char *b, isize_t bsiz, char const *s)
	Quote string.
issize_t	msg_parse_next_field (su_home_t *home, msg_header_t *prev, char *s, isize_t slen)
	Complete this header field and parse next header field.
issize_t	msg_commalist_d (su_home_t *, char **ss, msg_param_t **append_list, issize_t(*scanner)(char *s))
	Parse a comma-separated list.
issize_t	msg_token_scan (char *start)
	Token scanner for msg_commalist_d() accepting also empty entries.
issize_t	msg_attribute_value_scanner (char *s)
	Scan an attribute (name [= value]) pair.
issize_t	msg_any_list_d (su_home_t *, char **ss, msg_param_t **append_list, issize_t(*scanner)(char *s), int sep)
	Parse any list.
int	msg_header_update_params (msg_common_t *h, int clear)
	Update shortcuts to parameter values.
issize_t	msg_avlist_d (su_home_t *, char **ss, msg_param_t const **return_params)
	Parse a semicolong-separated attribute-value list.
issize_t	msg_params_d (su_home_t *, char **ss, msg_param_t const **return_params)
	Parse a semicolon-separated parameter list starting with semicolon.
isize_t	msg_params_e (char b[], isize_t bsiz, msg_param_t const pparams[])
	Encode a list of parameters.
issize_t	msg_params_join (su_home_t *, msg_param_t **dst, msg_param_t const *src, unsigned prune, int dup)
	Join list of parameters.
char *	msg_params_dup (msg_param_t const **d, msg_param_t const *s, char *b, isize_t xtra)
	Duplicate a parameter list.
isize_t	msg_params_count (msg_param_t const params[])
	Count number of parameters in the list.
isize_t	msg_params_dup_xtra (msg_param_t const params[], isize_t offset)
	Calculate memory size required by parameter list.

---

Detailed Description

Message parser interface.

Author:

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

Date:

Created: Tue Aug 21 16:03:45 2001 ppessi

---

Define Documentation

#define MSG_PARSER_H

Defined when <sofia-sip/msg_parser.h> has been included.

---

Function Documentation

issize_t msg_any_list_d	(	su_home_t *	home,
		char **	ss,
		msg_param_t **	append_list,
		issize_t(*)(char *s)	scanner,
		int	sep
	)

Parse any list.

Parses a list of items, separated by sep. The parsed string is passed in *ss, which is updated to point to the first non-linear-whitespace character after the list. The function modifies the string as it parses it.

The parsed items are appended to the list *append_list. If there the list in *append_list is NULL, allocate a new list and return it in *append_list. Empty list items are ignored, and are not appended to the list.

The function must be passed a scanning function scanner. The scanning function scans for a legitimate list item, for example, a token. It should also compact the list item, for instance, if the item consists of name=value parameter definitions it should remove whitespace around "=" sign. The scanning function returns the length of the scanned item, including any linear whitespace after it.

Parameters:

[in]	home	memory home for allocating list pointers
[in,out]	ss	pointer to pointer to string to be parsed
[in,out]	append_list	pointer to list where parsed list items are appended
[in]	sep	separator character
[in]	scanner	pointer to function for scanning a single item

Return values:

	0	if successful.
	-1	upon an error.

issize_t msg_attribute_value_scanner

(

char *

s

)

Scan an attribute (name [= value]) pair.

The attribute consists of name (a token) and optional value, separated by equal sign. The value can be a token or quoted string.

This function compacts the scanned value. It removes the whitespace around equal sign "=" by moving the equal sign character and value towards name.

If there is whitespace within the scanned value or after it, NUL-terminates the scanned attribute.

Return values:

	>	0 number of characters scanned, including the whitespace within the value
	-1	upon an error

char* msg_auth_dup_one	(	msg_header_t *	dst,
		msg_header_t const *	src,
		char *	b,
		isize_t	xtra
	)

Duplicate one msg_auth_t object.

issize_t msg_avlist_d	(	su_home_t *	home,
		char **	ss,
		msg_param_t const **	append_list
	)

Parse a semicolong-separated attribute-value list.

Parse a semicolong-separated attribute-value list.

Parses an attribute-value list, which has syntax as follows:

  av-list = (av-pair *(";" av-pair)
  av-pair = token ["=" ( value / quoted-string) ]        ; optional value

Parameters:

[in]	home	pointer to a memory home
[in,out]	ss	pointer to string at the start of parameter list
[in,out]	append_list	pointer to list where parsed list items are appended

Return values:

	>=	0 if successful
	-1	upon an error

issize_t msg_commalist_d	(	su_home_t *	home,
		char **	ss,
		msg_param_t **	append_list,
		issize_t(*)(char *s)	scanner
	)

Parse a comma-separated list.

Parses a comma-separated list. The parsed string is passed in *ss, which is updated to point to the first non-linear-whitespace character after the list. The function modifies the string as it parses it.

A pointer to the resulting list is returned in *retval. If there already is a list in *retval, new items are appended. Empty list items are ignored, and are not included in the list.

The function can be passed an optional scanning function. The scanning function scans for a legitimate list item, for example, a token. It also compacts the list item, for instance, if the item consists of name=value parameter definitions. The scanning function returns the length of the scanned item, including any linear whitespace after it.

By default, the scanning function accepts tokens, quoted strings or separators (except comma, of course).

Parameters:

[in]	home	memory home for allocating list pointers
[in,out]	ss	pointer to pointer to string to be parsed
[in,out]	append_list	pointer to list where parsed list items are appended
[in]	scanner	pointer to function scanning a single item (optional)

Return values:

	0	if successful.
	-1	upon an error.

issize_t msg_comment_d	(	char **	ss,
		char const **	return_comment
	)

Parse a comment.

Parses a multilevel comment. The comment assigned to return-value parameter return_comment is NUL-terminated. The string at return-value parameter ss is updated to point to first non-linear-whitespace character after the comment.

char* msg_default_dup_one	(	msg_header_t *	h,
		msg_header_t const *	src,
		char *	b,
		isize_t	xtra
	)

Duplicate a header object without external references.

The function msg_default_dup_one() copies the contents of header object src to h. The header object should not contain external references (pointers).

Parameters:

	h	pointer to newly allocated header object
	src	pointer to a header object to be duplicated
	b	memory buffer used to copy (not used)
	xtra	number bytes in buffer b (not used)

Returns:

The function msg_default_dup_one() returns a pointer to the memory buffer b.

isize_t msg_default_dup_xtra	(	msg_header_t const *	header,
		isize_t	offset
	)

Calculate extra size of a plain header.

issize_t msg_extract_header	(	msg_t *	msg,
		msg_pub_t *	mo,
		char	b[],
		isize_t	bsiz,
		int	eos
	)

Extract a header.

int msg_firstline_d	(	char *	s,
		char **	return_part2,
		char **	return_part3
	)

Parse first line.

Splits the first line from a message into three whitespace-separated parts.

issize_t msg_generic_d	(	su_home_t *	home,
		msg_header_t *	h,
		char *	s,
		isize_t	slen
	)

Parse a generic header.

The function msg_generic_d() parses a generic header structure.

Parameters:

[in]	home	memory home
[in,out]	h	header structure
[in]	s	string to be parsed
[in]	slen	length of the string

Return values:

	0	when successful,
	-1	upon an error.

char* msg_generic_dup_one	(	msg_header_t *	dst,
		msg_header_t const *	src,
		char *	b,
		isize_t	xtra
	)

Duplicate one msg_generic_t object.

isize_t msg_generic_dup_xtra	(	msg_header_t const *	h,
		isize_t	offset
	)

Calculate the size of strings associated with a msg_generic_t object.

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

Encode a generic header.

The function msg_generic_e encodes a generic header.

int msg_header_update_params	(	msg_common_t *	h,
		int	clear
	)

Update shortcuts to parameter values.

Update the shortcuts to parameter values in parameter list. 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, "".

Return values:

	0	when successful
	-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

int msg_hostport_d	(	char **	ss,
		char const **	return_host,
		char const **	return_port
	)

Parse host[":"port] pair.

Parses a host[":"port] pair. The caller passes function a pointer to a string via ss, and pointers to which parsed host and port are assigned via hhost and pport, respectively. The value-result parameter *pport must be initialized to default value (e.g., NULL).

Parameters:

	ss	pointer to pointer to string to be parsed
	return_host	value-result parameter for host
	return_port	value-result parameter for port

Returns:

Returns zero when successful, and a negative value upon an error. The parsed values for host and port are assigned via return_host and return_port, respectively. The function also updates the pointer *ss, so if call is successful, the *ss points to first non-linear-whitespace character after host[":"port] pair.

Note:

If there is no whitespace after port, the value in *pport may not be NUL-terminated. The calling function must NUL terminate the value by setting the **ss to NUL after first examining its value.

issize_t msg_params_d	(	su_home_t *	home,
		char **	ss,
		msg_param_t const **	append_list
	)

Parse a semicolon-separated parameter list starting with semicolon.

Parse a parameter list, which has syntax as follows:

  *(";" token [ "=" (token | quoted-string)]).

Parameters:

[in]	home	pointer to a memory home
[in,out]	ss	pointer to string at the start of parameter list
[in,out]	append_list	pointer to list where parsed list items are appended

Return values:

	>=	0 if successful
	-1	upon an error

See also:

msg_avlist_d()

isize_t msg_params_e	(	char	b[],
		isize_t	bsiz,
		msg_param_t const	pparams[]
	)

Encode a list of parameters.

issize_t msg_params_join	(	su_home_t *	home,
		msg_param_t **	dst,
		msg_param_t const *	src,
		unsigned	prune,
		int	dup
	)

Join list of parameters.

Join list of parameters.

The function msg_params_join() joins two parameter lists; the first list must have been created by msg_params_d() or by msg_params_dup() (or it may contain only NULL).

Parameters:

	home	memory home
	dst	pointer to pointer to destination parameter list
	src	source list
	prune	prune duplicates
	dup	duplicate parameters in src list

Pruning

0	do not prune
1	prune parameters with identical names
2	case-insensitive values
3	case-sensitive values

Returns:

Return values:

	>=	0 when successful
	-1	upon an error

issize_t msg_parse_next_field	(	su_home_t *	home,
		msg_header_t *	prev,
		char *	s,
		isize_t	slen
	)

Complete this header field and parse next header field.

This function completes parsing a multi-field header like Accept, Contact, Via or Warning. It scans for the next header field and if one is found, it calls the parsing function recursively.

Parameters:

	home	memory home used ot allocate new header structures and parameter lists
	prev	pointer to header structure already parsed
	s	header content to parse; should point to the area after current header field (either end of line or to a comma separating header fields)
	slen	ignored

Since:

New in 1.12.4.

Return values:

	>=	0 when successful
	-1	upon an error

issize_t msg_payload_d	(	su_home_t *	home,
		msg_header_t *	h,
		char *	s,
		isize_t	slen
	)

Parse payload.

issize_t msg_separator_d	(	su_home_t *	home,
		msg_header_t *	h,
		char *	s,
		isize_t	slen
	)

Parse a separator line.

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

Encode a separator line.

issize_t msg_token_d	(	char **	ss,
		char const **	return_token
	)

Parse a token.

Parses a token from string pointed by *ss. It stores the token value in return_token, and updates the ss to the end of token and possible whitespace.

issize_t msg_token_scan

(

char *

start

)

Token scanner for msg_commalist_d() accepting also empty entries.

issize_t msg_uint32_d	(	char **	ss,
		uint32_t *	return_value
	)

Parse a 32-bit unsigned int.

The function msg_uint32_d() parses a 32-bit unsigned integer in string pointed by *ss. It stores the value in return_token and updates the ss to the end of integer and possible whitespace.

Return values:

length

of parsed integer, or -1 upon an error.