Group PJSIP_PARSER

group PJSIP_PARSER

Message and message elements parsing.

Defines

PJSIP_MIN_CONTENT_LENGTH

Contants for limit checks For limit checks

PJSIP_MAX_CONTENT_LENGTH

For limit checks

PJSIP_MIN_PORT

For limit checks

PJSIP_MAX_PORT

For limit checks

PJSIP_MIN_TTL

For limit checks

PJSIP_MAX_TTL

For limit checks

PJSIP_MIN_STATUS_CODE

For limit checks

PJSIP_MAX_STATUS_CODE

For limit checks

PJSIP_MIN_Q1000

For limit checks

PJSIP_MAX_Q1000

For limit checks

PJSIP_MIN_EXPIRES

For limit checks

PJSIP_MAX_EXPIRES

for chk

PJSIP_MIN_CSEQ

For limit checks

PJSIP_MAX_CSEQ

For limit checks

PJSIP_MIN_RETRY_AFTER

For limit checks

PJSIP_MAX_RETRY_AFTER

For limit checks

Typedefs

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.

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

Enums

enum [anonymous]

URI Parsing options.

Values:

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.

enumerator 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).

Functions

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.

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.

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.

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

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

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.

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.

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.

Variables

int PJSIP_SYN_ERR_EXCEPTION

Parser syntax error exception value.

int PJSIP_EINVAL_ERR_EXCEPTION

Invalid value error exception value.

struct pjsip_parser_err_report
#include <sip_parser.h>

This structure is used to get error reporting from parser.

Public Functions

PJ_DECL_LIST_MEMBER(struct pjsip_parser_err_report)

Standard header fields.

Public Members

int except_code

Error exception (e.g. PJSIP_SYN_ERR_EXCEPTION)

int line

Line number.

int col

Column number.

pj_str_t hname

Header name, if any.

struct pjsip_parse_ctx
#include <sip_parser.h>

Parsing context, the default argument for parsing functions.

Public Members

pj_scanner *scanner

The scanner.

pj_pool_t *pool

The pool.

pjsip_rx_data *rdata

Optional rdata.