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.
int msg_token_d (char **ss, char const **return_token)
 Parse a token.
int msg_uint32_d (char **ss, uint32_t *return_value)
 Parse a 32-bit unsigned int.
int msg_any_list_d (su_home_t *home, char **ss, msg_param_t **return_list, int(*scanner)(char *s), int sep)
 Parse any list.
int msg_attribute_value_scanner (char *s)
 Scan an attribute [= value] pair.
int msg_avlist_d (su_home_t *home, char **ss, msg_param_t const **return_list)
 Parse a semicolong-separated attribute-value list.
int msg_params_d (su_home_t *home, char **ss, msg_param_t const **return_list)
 Parse a semicolon-separated parameter list starting with semicolon.
int msg_params_e (char b[], int 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, int xtra)
 Duplicate a parameter list.
int msg_commalist_d (su_home_t *home, char **ss, msg_param_t **return_list, int(*scanner)(char *s))
 Parse a comma-separated list.
int msg_token_scan (char *start)
 Token scanner for msg_commalist_d() accepting also empty entries.
int msg_comment_d (char **ss, char const **return_comment)
 Parse a comment.
int 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 all parameters.
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.
int 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_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.
int msg_unquoted_e (char *b, int bsiz, char const *s)
 Quote string.
unsigned long msg_hash_string (char const *id)
 Calculate a hash over a string.
int msg_header_size (msg_header_t const *h)
 Calculate the size of a duplicate of a header structure.
int msg_object_e (char b[], int size, msg_pub_t const *mo, int flags)
 Encode a message to the buffer.
int msg_header_field_e (char b[], int 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.
int msg_random_token (char token[], int tlen, void const *rmemp, int rsize)
 Generates a random token.

Function Documentation

int msg_any_list_d ( su_home_t home,
char **  ss,
msg_param_t **  return_list,
int(*)(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.

A pointer to the resulting list is returned in the return-value parameter return_list. If there already is a list in return_list, new items are appended. Empty list items are ignored, and are not included in 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. The scanning function returns the length of the scanned item, including any linear whitespace after it.

Parameters:
home memory home used to allocate memory for list pointers [IN]
ss pointer to pointer to string to be parsed [IN/OUT]
return_list return-value parameter for parsed list [IN/OUT]
sep separator character [IN]
scanner pointer to function scanning a single item (optional) [IN]
Return values:
0 if successful.
-1 upon an error.

int msg_avlist_d ( su_home_t home,
char **  ss,
msg_param_t const **  return_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:
home pointer to a memory home [IN]
ss pointer to string at the start of parameter list [IN/OUT]
return_list return-value parameter for parsed list [IN/OUT]
Return values:
0 if successful
-1 upon an error

int msg_commalist_d ( su_home_t home,
char **  ss,
msg_param_t **  return_list,
int(*)(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:
home memory home used to allocate memory for list pointers [in]
ss pointer to pointer to string to be parsed [in/out]
return_list return-value parameter for parsed list [in/out]
scanner pointer to function scanning a single item (optional) [in]
Return values:
0 if successful.
-1 upon an error.

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

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

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

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

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.

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 #

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

int msg_params_d ( su_home_t home,
char **  ss,
msg_param_t const **  return_list 
)

Parse a semicolon-separated parameter list starting with semicolon.

Parse a parameter list, which has syntax as follows:

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

Parameters:
home pointer to a memory home [IN]
ss pointer to string at the start of parameter list [IN/OUT]
return_list return-value parameter for the parsed list [IN/OUT]
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.

int 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:
The function msg_params_join() returns 0 if successful, or a negative value 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.

The parameter 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 replaced or added
Return values:
0 if parameter was added
1 if parameter was replaced
-1 upon an error

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

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

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.