msg_parser_util.c File Reference


Detailed Description

Text-message parser helper functions.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Date:
Created: Tue Aug 28 16:26:34 2001 ppessi

#include "config.h"
#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <assert.h>
#include <limits.h>
#include <stdarg.h>
#include <sofia-sip/su_tagarg.h>
#include <sofia-sip/su.h>
#include <sofia-sip/su_alloc.h>
#include "msg_internal.h"
#include "sofia-sip/msg_parser.h"
#include "sofia-sip/bnf.h"
#include "sofia-sip/url.h"
#include <sofia-sip/su_uniqueid.h>

Include dependency graph for msg_parser_util.c:

Functions

int msg_firstline_d (char *s, char **return_part2, char **return_part3)
 Parse first line.
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_any_list_d (su_home_t *home, char **ss, msg_param_t **append_list, issize_t(*scanner)(char *s), int sep)
 Parse any list.
issize_t msg_attribute_value_scanner (char *s)
 Scan an attribute (name [= value]) pair.
issize_t msg_avlist_d (su_home_t *home, char **ss, msg_param_t const **append_list)
 Parse a semicolong-separated attribute-value list.
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.
isize_t msg_params_e (char b[], isize_t bsiz, msg_param_t const pparams[])
 Encode a 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.
issize_t msg_commalist_d (su_home_t *home, 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_comment_d (char **ss, char const **return_comment)
 Parse a comment.
issize_t msg_quoted_d (char **ss, char **return_quoted)
 Parse a quoted string.
int msg_hostport_d (char **ss, char const **return_host, char const **return_port)
 Parse host[":"port] pair.
char const * msg_header_find_param (msg_common_t const *h, char const *name)
 Find a header parameter.
int msg_header_add_param (su_home_t *home, msg_common_t *h, char const *param)
 Add a parameter to a header.
int msg_header_replace_param (su_home_t *home, 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.
int msg_header_update_params (msg_common_t *h, int clear)
 Update shortcuts to parameter values.
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 *home, 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.
msg_param_t msg_params_find (msg_param_t const params[], msg_param_t token)
 Find a parameter from a parameter list.
msg_param_t * msg_params_find_slot (msg_param_t params[], msg_param_t token)
 Find a slot for parameter from a parameter list.
int msg_params_replace (su_home_t *home, msg_param_t **inout_params, msg_param_t param)
 Replace or add a parameter from a list.
int msg_params_remove (msg_param_t *params, msg_param_t param)
 Remove a parameter from a list.
size_t msg_params_length (char const *const *params)
 Calculate number of parameters in a parameter list.
int msg_params_add (su_home_t *home, msg_param_t **inout_params, msg_param_t param)
 Add a parameter to a list.
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.
int msg_header_join_items (su_home_t *home, msg_common_t *dst, msg_common_t const *src, int duplicate)
 Join header item lists.
int msg_params_cmp (char const *const a[], char const *const b[])
 Compare parameter lists.
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.
issize_t msg_unquoted_e (char *b, isize_t bsiz, char const *s)
 Quote string.
unsigned long msg_hash_string (char const *id)
 Calculate a hash over a string.
isize_t msg_header_size (msg_header_t const *h)
 Calculate the size of a duplicate of a header structure.
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.
msg_header_t ** msg_header_offset (msg_t const *msg, msg_pub_t const *mo, msg_header_t const *h)
 Get offset of header h from structure mo.
msg_header_tmsg_header_access (msg_pub_t const *pub, msg_hclass_t *hc)
 Get a header from the public message structure.
issize_t msg_random_token (char token[], isize_t tlen, void const *rmemp, isize_t rsize)
 Generates a random token.
msg_tmsg_make (msg_mclass_t const *mc, int flags, void const *data, ssize_t len)
 Parse a message.


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

issize_t msg_avlist_d ( su_home_t *  home,
char **  ss,
msg_param_t const **  append_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.

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.

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

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

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

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.

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.

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

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

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

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

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.

msg_t* msg_make ( msg_mclass_t const *  mc,
int  flags,
void const *  data,
ssize_t  len 
)

Parse a message.

Parse a text message with parser mc. The data is copied and it is not modified or referenced by the parsed message.

Example
Parse a SIP message fragment (e.g., payload of NOTIFY sent in response to REFER):
 msg_t *m = msg_make(sip_default_mclass(), 0, pl->pl_data, pl->pl_len);
 sip_t *frag = sip_object(m);
Parameters:
mc message class (parser table)
flags message flags (see msg_flg_user)
data message text
len size of message text (if -1, use strlen(data))
Return values:
A pointer to a freshly allocated and parsed message.
Upon parsing error, the header structure may be left incomplete. The MSG_FLG_ERROR is set in msg_object(msg)->msg_flags.

Since:
New in 1.12.4
See also:
msg_as_string(), msg_extract()

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 #

int msg_params_add ( su_home_t *  home,
msg_param_t **  inout_params,
msg_param_t  param 
)

Add a parameter to a list.

Add a parameter to the list; the list must have been created by msg_params_d() or by msg_params_dup() (or it may contain only NULL).

Note:
This function does not duplicate param.
Parameters:
home memory home
inout_params pointer to pointer to parameter list
param parameter to be added
Return values:
0 if parameter was added
-1 upon an error

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

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()

msg_param_t msg_params_find ( msg_param_t const   params[],
msg_param_t  token 
)

Find a parameter from a parameter list.

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

Parameters:
params list (or vector) of parameters
token parameter name (with or without "=" sign)
Returns:
A pointer to parameter value, or NULL if parameter was not found.

msg_param_t* msg_params_find_slot ( msg_param_t  params[],
msg_param_t  token 
)

Find a slot for parameter from a parameter list.

Searches for given parameter token from the parameter list. If parameter is found, it returns a non-NULL pointer to the item containing the parameter.

Parameters:
params list (or vector) of parameters
token parameter name (with or without "=" sign)
Returns:
A pointer to parameter slot, or NULL if parameter was not found.

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.

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
0do not prune
1prune parameters with identical names
2case-insensitive values
3case-sensitive values
Returns:
Return values:
>= 0 when successful
-1 upon an error

int msg_params_remove ( msg_param_t *  params,
msg_param_t  param 
)

Remove a parameter from a list.

Return values:
1 if parameter was removed
0 if parameter was not found
-1 upon an error

int msg_params_replace ( su_home_t *  home,
msg_param_t **  inout_params,
msg_param_t  param 
)

Replace or add a parameter from a list.

A non-NULL parameter list must have been created by msg_params_d() or by msg_params_dup().

Note:
This function does not duplicate param.
Parameters:
home memory home
inout_params pointer to pointer to parameter list
param parameter to be replaced or added
Return values:
0 if parameter was added
1 if parameter was replaced
-1 upon an error

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

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.6work - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.