Parser

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_uint32_t)0xFFFFFFFFUL)
#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_uri *	pjsip_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_msg *	pjsip_parse_msg (pj_pool_t *pool, char *buf, pj_size_t size, pjsip_parser_err_report *err_list)
pjsip_msg *	pjsip_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 For limit checks

PJSIP_MAX_CONTENT_LENGTH

#define PJSIP_MAX_CONTENT_LENGTH   PJ_MAXINT32

For limit checks

PJSIP_MIN_PORT

#define PJSIP_MIN_PORT   0

For limit checks

PJSIP_MAX_PORT

#define PJSIP_MAX_PORT   PJ_MAXUINT16

For limit checks

PJSIP_MIN_TTL

#define PJSIP_MIN_TTL   0

For limit checks

PJSIP_MAX_TTL

#define PJSIP_MAX_TTL   PJ_MAXUINT8

For limit checks

PJSIP_MIN_STATUS_CODE

#define PJSIP_MIN_STATUS_CODE   100

For limit checks

PJSIP_MAX_STATUS_CODE

#define PJSIP_MAX_STATUS_CODE   999

For limit checks

PJSIP_MIN_Q1000

#define PJSIP_MIN_Q1000   0

For limit checks

PJSIP_MAX_Q1000

#define PJSIP_MAX_Q1000   PJ_MAXINT32 / 1000

For limit checks

PJSIP_MIN_EXPIRES

#define PJSIP_MIN_EXPIRES   0

For limit checks

PJSIP_MAX_EXPIRES

#define PJSIP_MAX_EXPIRES   ((pj_uint32_t)0xFFFFFFFFUL)

for chk

PJSIP_MIN_CSEQ

#define PJSIP_MIN_CSEQ   0

For limit checks

PJSIP_MAX_CSEQ

#define PJSIP_MAX_CSEQ   PJ_MAXINT32

For limit checks

PJSIP_MIN_RETRY_AFTER

#define PJSIP_MIN_RETRY_AFTER   0

For limit checks

PJSIP_MAX_RETRY_AFTER

#define PJSIP_MAX_RETRY_AFTER   PJ_MAXINT32

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

hname	The header name.
hshortname	The short header name or NULL.
fptr	The 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

hname	The header name registered.
hshortname	The short header name registered, or NULL.
fptr	Previously 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

scheme	The URI scheme registered.
func	The 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

scheme	The URI scheme as registered previously.
func	The 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

pool	The pool to get memory allocations.
buf	The input buffer, which MUST be NULL terminated.
size	The length of the string (not counting NULL terminator).
options	If 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

buf	Text buffer to parse, which MUST be NULL terminated.
size	The size of the buffer, excluding the NULL character.
status_line	Structure 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

pool	The pool to allocate memory.
buf	The input buffer, which MUST be NULL terminated.
size	The length of the string (not counting NULL terminator).
err_list	If 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

buf	The input buffer, which MUST be NULL terminated.
size	The length of the string (not counting NULL terminator).
rdata	The 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

buf	The input buffer, which must be NULL terminated.
size	The length of the string (not counting NULL terminator).
is_datagram	Put 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

pool	Pool to allocate memory for the header.
hname	Header name which is used to find the correct function to parse the header.
line	Header content, which must be NULL terminated.
size	The length of the string (not counting NULL terminator, if any).
parsed_len	If 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

pool	The pool.
input	The input text to parse, which must be NULL terminated.
size	The text length (not counting NULL terminator).
hlist	The header list to store the parsed headers. This list must have been initialized before calling this function.
options	Specify 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

extern

Parser syntax error exception value.

PJSIP_EINVAL_ERR_EXCEPTION

int PJSIP_EINVAL_ERR_EXCEPTION

extern

Invalid value error exception value.