BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

Message and message elements parsing. More...

Data Structures

struct  pjsip_parser_err_report
 
struct  pjsip_parse_ctx
 

Macros

#define PJSIP_MIN_CONTENT_LENGTH   0
 
#define PJSIP_MAX_CONTENT_LENGTH   PJ_MAXINT32
 
#define PJSIP_MIN_PORT   0
 
#define PJSIP_MAX_PORT   PJ_MAXUINT16
 
#define PJSIP_MIN_TTL   0
 
#define PJSIP_MAX_TTL   PJ_MAXUINT8
 
#define PJSIP_MIN_STATUS_CODE   100
 
#define PJSIP_MAX_STATUS_CODE   999
 
#define PJSIP_MIN_Q1000   0
 
#define PJSIP_MAX_Q1000   PJ_MAXINT32 / 1000
 
#define PJSIP_MIN_EXPIRES   0
 
#define PJSIP_MAX_EXPIRES   PJ_MAXINT32
 
#define PJSIP_MIN_CSEQ   0
 
#define PJSIP_MAX_CSEQ   PJ_MAXINT32
 
#define PJSIP_MIN_RETRY_AFTER   0
 
#define PJSIP_MAX_RETRY_AFTER   PJ_MAXINT32
 

Typedefs

typedef pjsip_hdr *() pjsip_parse_hdr_func(pjsip_parse_ctx *context)
 
typedef void *() pjsip_parse_uri_func(pj_scanner *scanner, pj_pool_t *pool, pj_bool_t parse_params)
 

Enumerations

enum  { PJSIP_PARSE_URI_AS_NAMEADDR = 1, PJSIP_PARSE_URI_IN_FROM_TO_HDR = 2 }
 

Functions

pj_status_t pjsip_register_hdr_parser (const char *hname, const char *hshortname, pjsip_parse_hdr_func *fptr)
 
pj_status_t pjsip_unregister_hdr_parser (const char *hname, const char *hshortname, pjsip_parse_hdr_func *fptr)
 
pj_status_t pjsip_register_uri_parser (char *scheme, pjsip_parse_uri_func *func)
 
pj_status_t pjsip_unregister_uri_parser (const char *scheme, pjsip_parse_uri_func *func)
 
pjsip_uripjsip_parse_uri (pj_pool_t *pool, char *buf, pj_size_t size, unsigned options)
 
pj_status_t pjsip_parse_status_line (char *buf, pj_size_t size, pjsip_status_line *status_line)
 
pjsip_msgpjsip_parse_msg (pj_pool_t *pool, char *buf, pj_size_t size, pjsip_parser_err_report *err_list)
 
pjsip_msgpjsip_parse_rdata (char *buf, pj_size_t size, pjsip_rx_data *rdata)
 
pj_status_t pjsip_find_msg (const char *buf, pj_size_t size, pj_bool_t is_datagram, pj_size_t *msg_size)
 
void * pjsip_parse_hdr (pj_pool_t *pool, const pj_str_t *hname, char *line, pj_size_t size, int *parsed_len)
 
pj_status_t pjsip_parse_headers (pj_pool_t *pool, char *input, pj_size_t size, pjsip_hdr *hlist, unsigned options)
 

Variables

int PJSIP_SYN_ERR_EXCEPTION
 
int PJSIP_EINVAL_ERR_EXCEPTION
 

Detailed Description

Macro Definition Documentation

◆ PJSIP_MIN_CONTENT_LENGTH

#define PJSIP_MIN_CONTENT_LENGTH   0

Contants for limit checks

Typedef Documentation

◆ pjsip_parse_hdr_func

typedef pjsip_hdr*() pjsip_parse_hdr_func(pjsip_parse_ctx *context)

Type of function to parse header. The parsing function must follow these specification:

  • It must not modify the input text.
  • The hname and HCOLON has been parsed prior to invoking the handler.
  • It returns the header instance on success.
  • For error reporting, it must throw PJSIP_SYN_ERR_EXCEPTION exception instead of just returning NULL. When exception is thrown, the return value is ignored.
  • It must read the header separator after finished reading the header body. The separator types are described below, and if they don't exist, exception must be thrown. Header separator can be a:
    • newline, such as when the header is part of a SIP message.
    • ampersand, such as when the header is part of an URI.
    • for the last header, these separator is optional since parsing can be terminated when seeing EOF.

◆ pjsip_parse_uri_func

typedef void*() pjsip_parse_uri_func(pj_scanner *scanner, pj_pool_t *pool, pj_bool_t parse_params)

Type of function to parse URI scheme. Most of the specification of header parser handler (pjsip_parse_hdr_func) also applies here (except the separator part).

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

URI Parsing options.

Enumerator
PJSIP_PARSE_URI_AS_NAMEADDR 

If this option is specified, function pjsip_parse_uri will return the URI object as pjsip_name_addr instead of the corresponding URI object.

PJSIP_PARSE_URI_IN_FROM_TO_HDR 

If this option is specified, function pjsip_parse_uri and other internal functions that this function calls will parse URI according to convention for parsing From/To/Contact header. For example, when the URI is not enclosed in brackets ("<" and ">"), all parameters are treated as header parameters (not URI parameters).

Function Documentation

◆ pjsip_register_hdr_parser()

pj_status_t pjsip_register_hdr_parser ( const char *  hname,
const char *  hshortname,
pjsip_parse_hdr_func fptr 
)

Register header parser handler. The parser handler MUST follow the specification of header parser handler function. New registration overwrites previous registration with the same name.

Parameters
hnameThe header name.
hshortnameThe short header name or NULL.
fptrThe pointer to function to parser the header.
Returns
PJ_SUCCESS if success, or the appropriate error code.

◆ pjsip_unregister_hdr_parser()

pj_status_t pjsip_unregister_hdr_parser ( const char *  hname,
const char *  hshortname,
pjsip_parse_hdr_func fptr 
)

Unregister previously registered header parser handler. All the arguments MUST exactly equal to the value specified upon registration of the handler.

Parameters
hnameThe header name registered.
hshortnameThe short header name registered, or NULL.
fptrPreviously registered function to parse the header.
Returns
zero if unregistration was successfull.

◆ pjsip_register_uri_parser()

pj_status_t pjsip_register_uri_parser ( char *  scheme,
pjsip_parse_uri_func func 
)

Register URI scheme parser handler.

Parameters
schemeThe URI scheme registered.
funcThe URI parser function.
Returns
zero on success.

◆ pjsip_unregister_uri_parser()

pj_status_t pjsip_unregister_uri_parser ( const char *  scheme,
pjsip_parse_uri_func func 
)

Unregister URI scheme parser handler. All the arguments MUST exactly equal to the value specified upon registration of the handler.

Parameters
schemeThe URI scheme as registered previously.
funcThe function handler as registered previously.
Returns
zero if the registration was successfull.

◆ pjsip_parse_uri()

pjsip_uri* pjsip_parse_uri ( pj_pool_t pool,
char *  buf,
pj_size_t  size,
unsigned  options 
)

Parse an URI in the input and return the correct instance of URI. Note that the input string buffer MUST be NULL terminated and have length at least size+1 (size MUST NOT include the NULL terminator).

Parameters
poolThe pool to get memory allocations.
bufThe input buffer, which MUST be NULL terminated.
sizeThe length of the string (not counting NULL terminator).
optionsIf no options are given (value is zero), the object returned is dependent on the syntax of the URI, eg. basic SIP URL, TEL URL, or name address. If option PJSIP_PARSE_URI_AS_NAMEADDR is given, then the returned object is always name address object, with the relevant URI object contained in the name address object.
Returns
The URI or NULL when failed. No exception is thrown by this function (or any public parser functions).

◆ pjsip_parse_status_line()

pj_status_t pjsip_parse_status_line ( char *  buf,
pj_size_t  size,
pjsip_status_line status_line 
)

Parse SIP status line. Note that the input string buffer MUST be NULL terminated and have length at least size+1 (size MUST NOT include the NULL terminator).

Parameters
bufText buffer to parse, which MUST be NULL terminated.
sizeThe size of the buffer, excluding the NULL character.
status_lineStructure to receive the parsed elements.
Returns
PJ_SUCCESS if a status line is parsed successfully.

◆ pjsip_parse_msg()

pjsip_msg* pjsip_parse_msg ( pj_pool_t pool,
char *  buf,
pj_size_t  size,
pjsip_parser_err_report err_list 
)

Parse a packet buffer and build a full SIP message from the packet. This function parses all parts of the message, including request/status line, all headers, and the message body. The message body however is only treated as a text block, ie. the function will not try to parse the content of the body.

Note that the input string buffer MUST be NULL terminated and have length at least size+1 (size MUST NOT include the NULL terminator).

Parameters
poolThe pool to allocate memory.
bufThe input buffer, which MUST be NULL terminated.
sizeThe length of the string (not counting NULL terminator).
err_listIf this parameter is not NULL, then the parser will put error messages during parsing in this list.
Returns
The message or NULL when failed. No exception is thrown by this function (or any public parser functions).

◆ pjsip_parse_rdata()

pjsip_msg* pjsip_parse_rdata ( char *  buf,
pj_size_t  size,
pjsip_rx_data rdata 
)

Parse a packet buffer and build a rdata. The resulting message will be stored in msg field in the rdata. This behaves pretty much like pjsip_parse_msg(), except that it will also initialize the header fields in the rdata.

This function is normally called by the transport layer.

Note that the input string buffer MUST be NULL terminated and have length at least size+1 (size MUST NOT include the NULL terminator).

Parameters
bufThe input buffer, which MUST be NULL terminated.
sizeThe length of the string (not counting NULL terminator).
rdataThe receive data buffer to store the message and its elements.
Returns
The message inside the rdata if successfull, or NULL.

◆ pjsip_find_msg()

pj_status_t pjsip_find_msg ( const char *  buf,
pj_size_t  size,
pj_bool_t  is_datagram,
pj_size_t msg_size 
)

Check incoming packet to see if a (probably) valid SIP message has been received. Note that the input string buffer MUST be NULL terminated and have length at least size+1 (size MUST NOT include the NULL terminator).

Parameters
bufThe input buffer, which must be NULL terminated.
sizeThe length of the string (not counting NULL terminator).
is_datagramPut non-zero if transport is datagram oriented.
msg_size[out] If message is valid, this parameter will contain the size of the SIP message (including body, if any).
Returns
PJ_SUCCESS if a message is found, or an error code.

◆ pjsip_parse_hdr()

void* pjsip_parse_hdr ( pj_pool_t pool,
const pj_str_t hname,
char *  line,
pj_size_t  size,
int parsed_len 
)

Parse the content of a header and return the header instance. This function parses the content of a header (ie. part after colon) according to the expected name, and will return the correct instance of header.

Note that the input string buffer MUST be NULL terminated and have length at least size+1 (size MUST NOT include the NULL terminator).

Parameters
poolPool to allocate memory for the header.
hnameHeader name which is used to find the correct function to parse the header.
lineHeader content, which must be NULL terminated.
sizeThe length of the string (not counting NULL terminator, if any).
parsed_lenIf the value is not NULL, then upon return the function will fill the pointer with the length of the string that has been parsed. This is usefull for two purposes, one is when the string may contain more than one header lines, and two when an error happen the value can pinpoint the location of the error in the buffer.
Returns
The instance of the header if parsing was successful, or otherwise a NULL pointer will be returned.

◆ pjsip_parse_headers()

pj_status_t pjsip_parse_headers ( pj_pool_t pool,
char *  input,
pj_size_t  size,
pjsip_hdr hlist,
unsigned  options 
)

Parse header line(s). Multiple headers can be parsed by this function. When there are multiple headers, the headers MUST be separated by either a newline (as in SIP message) or ampersand mark (as in URI). This separator is optional for the last header.

Note that the input string buffer MUST be NULL terminated and have length at least size+1 (size MUST NOT include the NULL terminator).

Parameters
poolThe pool.
inputThe input text to parse, which must be NULL terminated.
sizeThe text length (not counting NULL terminator).
hlistThe header list to store the parsed headers. This list must have been initialized before calling this function.
optionsSpecify 1 here to make parsing stop when error is encountered when parsing the header. Otherwise the error is silently ignored and parsing resumes to the next line.
Returns
zero if successfull, or -1 if error is encountered. Upon error, the hlist argument MAY contain successfully parsed headers.

Variable Documentation

◆ PJSIP_SYN_ERR_EXCEPTION

int PJSIP_SYN_ERR_EXCEPTION

Parser syntax error exception value.

◆ PJSIP_EINVAL_ERR_EXCEPTION

int PJSIP_EINVAL_ERR_EXCEPTION

Invalid value error exception value.

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.