Group PJSIP_PARSER

group PJSIP_PARSER

Message and message elements parsing.

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.

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.

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.

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.

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.

Parameters

  • buf – The input buffer, which must be NULL terminated.

  • size – The buffer size.

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

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.

Parameters

  • pool – The pool.

  • input – The input text to parse, which must be NULL terminated.

  • size – The text length.

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

struct pjsip_parser_err_report
#include <sip_parser.h>

This structure is used to get error reporting from parser.

struct pjsip_parse_ctx
#include <sip_parser.h>

Parsing context, the default argument for parsing functions.