SIP API Developer's Guide

Chapter 4 SIP API Functions

This section describes the functions in the SIP API.

Stack Initialization Function

int sip_stack_init(sip_stack_int_t *stack_init);

This function initializes the SIP stack. This is the stack initialization structure:

typedef struct sip_stack_init_s {
        int                     sip_version;
        uint32_t                sip_stack_flags;
        sip_io_pointers_t       *sip_io_pointers;
        sip_ulp_pointers_t      *sip_ulp_pointers;
        sip_header_function_t   *sip_function_table;
}sip_stack_init_t;

The structure has the following elements:

sip_version

The value of this variable is equal to the value of the SIP_STACK_VERSION attribute.

sip_stack_flags

Set the value of this variable to SIP_STACK_DIALOGS to make the stack manage dialogs.

sip_io_pointers

The values in this field provide the connection manager interfaces.

sip_ulp_pointers

The values in this field contain the upper layer registrations. Upper layer registrations are functions that the application must register with the stack during initialization.

sip_function_table

The values in this field are the custom headers that the application registers and the parsing functions that are associated with those headers. The application can specify the following elements for each custom header:

header_name
header_short_name (optional)
header_parse_func
header_check_compliance (optional)
header_is_equal (optional)
header_free

Message Allocation Functions

sip_msg_t sip_new_msg();

The sip_new_msg() function allocates and returns a SIP message.

void sip_free_msg(sip_msg_t sip_msg);

The sip_free_msg() function frees the resources that are associated with a SIP message. The function decrements the reference count. If the decremented reference count is zero, the function destroys the SIP message. If the decremented reference count is not zero, the function does not destroy the SIP message until the last thread that holds a reference to the message releases that reference.

void sip_hold_msg(sip_msg_t sip_msg);

Threads use the sip_hold_msg() function to hold a reference to the SIP message. A SIP message persists while the number of references to the message is greater than zero.

SIP Header Addition Functions

All of the functions that are described in this section, with the exception of the sip_add_param() function, take the SIP message as the first argument. These functions also take header specific attributes as arguments.

int sip_add_header(sip_msg_t sip_msg, char *header_string);

The sip_add_header() function takes a SIP header string as the second argument and appends it to the SIP message. This function creates the SIP header by appending a CRLF to the value provided in the header_string parameter, then adding it to the end of the SIP message.

sip_header_t sip_add_param(sip_header_t sip_header, char *param, int *error);

The sip_add_param() function adds the value in the param parameter to the SIP header in the first argument. The value of the param parameter cannot be null. The function returns the header with the parameter added.

Note –

Adding a parameter with this function creates a new header and marks the previous header as deleted. Developers working on multi-threaded applications should monitor headers that are being modified by multiple threads simultaneously.

All of the following header adding functions add a CRLF to the header before adding the header to the SIP message.

int sip_add_from(sip_msg_t sip_msg, char *display_name, char *from_uri, char *from_tag, boolean_t add_aquot, char *from_param);

The sip_add_from() function appends a FROM header to a SIP message. This function creates the header using the display_name, from_uri and from_tag parameters. The calling thread must provide the URI in the from_uri parameter. If the calling thread provides the value of the display_name parameter, the value of the add_aquot parameter must be B_TRUE. This value of the add_aquot parameter encloses URI within the delimiting characters < and >. If the display_name parameter has a value, this function quotes that name within " characters and adds the quoted name to the header. If the values in the from_tag parameter are NULL, the resulting SIP header does not contain a TAG parameter. You can specify any generic parameter in a from_param parameter.

Note –

Only one of the pair of parameters from_tag or from_param can have a non-NULL value. If both parameters have non-NULL values, the resulting FROM header contains only the TAG parameter.

int sip_add_to(sip_msg_t sip_msg, char *display_name, char *to_uri, char *to_tag, boolean_t add_aquot, char *to_param);

The sip_add_to() function appends a TO header to a SIP message. This function creates the header using the display_name, to_uri and to_tag parameters. The calling thread must provide the URI in the to_uri parameter. If the calling thread provides the value of the display_name parameter, the value of the add_aquot parameter must be B_TRUE. This value of the add_aquot parameter encloses the URI within the delimiting characters < and >. If the display_name parameter has a value, this function quotes that name within " characters and adds the quoted name to the header. If the values in the to_tag parameter are NULL, the resulting SIP header does not contain a TAG parameter. You can specify any generic parameter in a to_param parameter.

Note –

Only one of the pair of parameters to_tag or to_param can have a non-NULL value. If both parameters have non-NULL values, the resulting TO header contains only the TAG parameter.

int sip_add_contact(sip_msg_t sip_msg, char *display_name, char *contact_uri, boolean_t add_aquot, char *contact_param);

The sip_add_contact() function appends a CONTACT header to a SIP message. This function creates the header using the display_name and contact_uri parameters. The calling thread must provide the URI in the contact_uri parameter. If the calling thread provides the value of the display_name parameter, the value of the add_aquot parameter must be B_TRUE. This value of the add_aquot parameter encloses the URI within the delimiting characters < and >. If the display_name parameter has a value, this function quotes that name within " characters and adds the quoted name to the header. You can specify any generic parameter in a contact_param parameter.

int sip_add_via(sip_msg_t sip_msg, char *protocol_transport, char *sent_by_host, int sent_by_port, char *via_params);

The sip_add_via() function appends a VIA header to the SIP message that is specified by the value of the sip_msg parameter. The VIA header has the transport protocol that is specified in the protocol_transport parameter. The VIA header has the IP address or hostname that is specified by the sent_by_host parameter. The VIA header has the port that is specified in the sent_by_port parameter. If the sent_by_port parameter has a value of zero, the resulting VIA header does not have any port information. The VIA header's protocol is set to SIP and the version is set to 2.0. Specify any header-specific parameters in the via_params parameter. For example, you can specify the branch parameter in the via_params parameter with the string "branch=x9hG4b-mybranchid".

int sip_add_branchid_to_via(sip_msg_t sip_msg, char *branchid);

The sip_add_branchid_to_via() function adds a branch parameter to the topmost VIA header in the SIP message. The branch parameter cannot already exist in the VIA header.

Note –

int sip_add_maxforward(sip_msg_t sip_msg, uint_t maxforward);

The sip_add_maxforward() function appends a Max-Forwards header. The value of the header is equal to the value of the maxforward parameter.

int sip_add_callid(sip_msg_t sip_msg, char *callid);

The sip_add_callid() function appends a Call-ID header to the SIP message by using the value of the callid parameter. If the callid parameter has a value of NULL, the sip_add_callid() function generates a random value for the Call-ID header.

int sip_add_cseq(sip_msg_t sip_msg, sip_method_t method, uint32_t cseq);

The sip_add_cseq() function appends a CSeq header using the method and the value of cseq provided. The method can take on the following values:

INVITE
ACK
OPTIONS
BYE
CANCEL
REGISTER
REFER
INFO
SUBSCRIBE
NOTIFY
PRACK

The value of the cseq parameter must be a positive integer.

int sip_add_content_type(sip_msg_t sip_msg, char *, char *);

The sip_add_content_type() function adds a Content-Type header using the type and subtype specified in the arguments. The type and subtype cannot be null.

int sip_add_content(sip_msg_t sip_msg, char *contents);

The sip_add_content() function adds the message body to the SIP message. The value of the contents parameter must be a null-terminated string.

int sip_add_accept(sip_msg_t sip_msg, char *type, char *subtype, char *mparams, char *params);

The sip_add_accept() function adds an Accept header using the values of the type and subtype parameters. If the values of the type and subtype parameters are NULL, the function adds an empty Accept header. If the value of the type parameter is not NULL and the value of the subtype parameter is NULL, the function adds an Accept header that uses the value of the type parameter for the header's type value. The value of the subtype parameter for this header is equal to *. You can provide media and accept parameters by passing them as the mparams and params arguments.

int sip_add_accept_enc(sip_msg_t sip_msg, char *code, char *params);

The sip_add_accept_enc() function adds an Accept-Encoding header with the coding value that is specified in the code parameter. You can provide acceptance parameters in the params argument.

int sip_add_accept_lang(sip_msg_t sip_msg, char *lang, char *params);

The sip_add_accept_lang() function adds an Accept-Language header with the language that is specified in the lang parameter. You can provide acceptance parameters in the params argument.

int sip_add_alert_info(sip_msg_t sip_msg, char *alert, char *params);

The sip_add_alert_info() function adds an Alert-Info header with the alert parameter that is specified in the alert parameter. You can provide alert parameters in the params argument.

int sip_add_allow(sip_msg_t sip_msg, sip_method_t method);

The sip_add_allow() function adds an ALLOW header with the method that is specified in the method parameter. These are the valid values for the method parameter:

INVITE
ACK
OPTIONS
BYE
CANCEL
REGISTER
REFER
INFO
SUBSCRIBE
NOTIFY
PRACK

int sip_add_call_info(sip_msg_t sip_msg, char *uri, char *params);

The sip_add_call_info() function adds a Call-Info header by using the URI passed in the value of the uri parameter. You can provide URI parameters in the value of the params parameter.

int sip_add_content_disp(sip_msg_t sip_msg, char *dis_type, char *params);

The sip_add_content_disp() function adds a Content-Disposition header using the display type that is given by the value of the disp_type parameter. You can provide disposition parameters in the value of the params parameter.

int sip_add_content_enc(sip_msg_t sip_msg, char *code);

The sip_add_content_enc() adds a Content-Encoding header using the content encoding that is given by the value of the code parameter.

int sip_add_content_lang(sip_msg_t sip_msg, char *lang);

The sip_add_content_lang() adds a Content-Language header using the language that is given by the value of the lang parameter.

int sip_add_date(sip_msg_t sip_msg, char *date);

The sip_add_date() function adds a Date header using the value given in the date parameter. This value is a string from the SIP-Date field. See section 25.1 of RFC 3261 for more information.

int sip_add_error_info(sip_msg_t sip_msg, char *uri, char *params);

The sip_add_error_info() function adds an Error-Info header using the value for error-uri that is specified in the uri parameter. You can provide URI parameters in the value of the params parameter.

int sip_add_expires(sip_msg_t sip_msg, int secs);

The sip_add_expires() function adds an Expires header that uses the number of seconds that is specified by the value of the secs parameter.

int sip_add_in_reply_to(sip_msg_t sip_msg, char *reply_id);

The sip_add_in_reply_to() function adds an In-Reply-To header using the value for callid that is passed by the reply_id parameter.

int sip_add_mime_version(sip_msg_t sip_msg, char *version);

The sip_add_mime_version() function adds a Mime-Version header using the version number that is specified by the value of the version parameter.

int sip_add_min_expires(sip_msg_t sip_msg, int secs);

The sip_add_min_expires() function adds a Min-Expires header using number of seconds that is specified by the value of the secs parameter.

int sip_add_org(sip_msg_t sip_msg, char *org);

The sip_add_org() function adds an Organization header. The header has the value that is specified in the org parameter.

int sip_add_priority(sip_msg_t sip_msg, char *prio);

The sip_add_priority() function adds a Priority header. The header has the value that is specified in the prio parameter.

int sip_add_reply_to(sip_msg_t sip_msg, char *display_name, char *addr, char *plist, boolean_t add_aquot);

The sip_add_reply_to() function appends a REPLY-TO header to a SIP message. This function creates the header using the display_name and addr parameters, in addition to any parameters you specify in plist. If the value of the add_aquot parameter is B_TRUE, this function encloses the value of the addr parameter within the delimiting characters < and >. If the display_name parameter has a value, the value of the add_aquot parameter must be B_TRUE.

int sip_add_passertedid(sip_msg_t sip_msg, char *display_name, char *uri, boolean_t add_aquot);

The sip_add_passertedid() function appends a P-ASSERTED-IDENTITY header to a SIP message. This function creates the header using the display_name and uri parameters. The uri cannot have a null value. If the value of the add_aquot parameter is B_TRUE, this function encloses the value of the uri parameter within the delimiting characters < and >. If the display_name parameter has a value, the value of the add_aquot parameter must be B_TRUE.

int sip_add_ppreferredid(sip_msg_t sip_msg, char *display_name, char *uri, boolean_t add_aquot);

The sip_add_ppreferredid() function appends a P-PREFERRED-IDENTITY header to a SIP message. This function creates the header using the display_name and uri parameters. The uri cannot have a null value. If the value of the add_aquot parameter is B_TRUE, this function encloses the value of the uri parameter within the delimiting characters < and >.

int sip_add_require(sip_msg_t sip_msg, char *req);

The sip_add_require() function adds a Require header by using the value of option-tag that is specified in the req parameter.

int sip_add_retry_after(sip_msg_t sip_msg, int secs, char *cmt, char *params);

The sip_add_retry_after() function adds a Retry-After header with a value equal to the number of seconds that is specified by the value of the secs parameter. You can provide retry parameters in the value of the params parameter. You can provide comments in the value of the cmt parameter.

int sip_add_route(sip_msg_t sip_msg, char *display_name, char *route_uri, char *route_param);

The sip_add_route() function appends a ROUTE header to a SIP message. This function creates the header using the display_name and route_uri parameters, in addition to any parameters that you specify in route_param. This function encloses the value of the route_uri parameter within the delimiting characters < and > before adding that value to the header.

int sip_add_record_route(sip_msg_t sip_msg, char *display_name, char *route_uri, char *route_param);

The sip_add_record_route() function appends a RECORD-ROUTE header to a SIP message. This function creates the header using the display_name and route_uri parameters, in addition to any parameters that you specify in route_param. This function encloses the value of the route_uri parameter within the delimiting characters < and > before adding that value to the header.

int sip_add_server(sip_msg_t sip_msg, char *svr_val);

The sip_add_server() function adds a Server header by using the value of server-val that is given by the svr_val parameter.

int sip_add_subject(sip_msg_t sip_msg, char *subject);

The sip_add_subject() function adds a Subject header with the value given in the subject parameter.

int sip_add_supported(sip_msg_t sip_msg, char *support);

The sip_add_supported() function adds a Supported header with the value of option-tag that is given in the support parameter.

int sip_add_tstamp(sip_msg_t sip_msg, char *time, char *delay);

The sip_add_tstamp() function adds a Timestamp header using the timestamp value that is given in the time parameter. If the value of the delay is not NULL, this function adds the delay value given in the *delay parameter.

int sip_add_unsupported(sip_msg_t sip_msg, char *unsupport);

The sip_add_unsupported() function adds an Unsupported header using the value for option-tag that is specified by the unsupport parameter.

int sip_add_user_agent(sip_msg_t sip_msg, char *usr);

The sip_add_user_agent() function adds a User-Agent header using the value for server-val that is specified by the usr parameter.

int sip_add_warning(sip_msg_t sip_msg, int code, char *addr, char *msg);

The sip_add_warning() function adds a Warning header using the warning code that is specified by the value of the code parameter. The function uses the warning agent that is specified by the value of the addr parameter. The function uses the warning text that is specified by the value of the msg parameter.

SIP Request and Response Creation Functions

int sip_add_response_line(sip_msg_t sip_response, int response, char *response_code);

The sip_add_response_line() function adds a response line that uses the values that are passed in the response and response_code parameters. The response_code parameter is the reason phrase for the response. The value of the response_code parameter cannot be NULL. The SIP version in the response line is SIP/2.0. The sip_add_request_line() function adds a CRLF to the response line before adding the line to the SIP message. For the response listed in Section 21 of RFC 3261, obtain the value of the response_code parameter by using the sip_get_resp_desc() function.

int sip_add_request_line(sip_msg_t sip_request, sip_method_t method, char *request_uri);

The sip_add_request_line() function adds a request line to a SIP message using the method and the request URI. The request URI cannot be NULL. The method can take on the following values:

INVITE
ACK
OPTIONS
BYE
CANCEL
REGISTER
REFER
INFO
SUBSCRIBE
NOTIFY
PRACK

The added request line has a SIP version of SIP/2.0. The API adds a CRLF to the request line before adding the line to the SIP message.

sip_msg_t sip_create_response(sip_msg_t sip_request, int response, char *response_code, char *totag, char *contacturi);

The sip_create_response() function creates a response for the SIP request that is provided by the sip_request parameter. The response and *response_code parameters serve the same purpose as in the sip_add_response_line() function. You can specify a tag value that the sip_create_response() function adds to the TO header. If you do not specify the tag value, this function adds a tag value unless the response is 100 (Trying). In this case, the application must specifically add the tag. The SIP response message is created by adding a Response line by using the response and *response_code parameters with a SIP version of SIP/2.0. This function then copies the following headers from the request to the response message:

All VIA headers
FROM header
TO header
Call-ID header
Cseq header
All Record-Route headers

The sip_create_response() function returns the resulting SIP response message.

sip_msg_t sip_create_dialog_req(sip_method_t method, sip_dialog_t dialog, char *transport, char *sent_by, int sent_by_port, char *via_param, uint32_t maxforward, int cseq);

The sip_create_dialog_req() function creates an in-dialog request using the state that is maintained in the dialog parameter. This function uses the method that is specified in the method parameter to create the request line. The request URI is either the contact URI from the specified dialog or the first URI from the Route set, if that set is present. For more details on the Route set, see section 12.2 of RFC 3261. The FROM, TO, CONTACT and Call-ID headers are added to the request using the state that is maintained in the dialog. The Max-Forwards header is added using the value of the maxforward parameter. If the value of the cseq parameter is not negative, this function adds the Cseq header using the provided value. In all other cases, this function increments the dialog's local cseq and uses the result as the sequence number.

This function adds a VIA header to the request. This function constructs the VIA header by using the values in the transport, sent_by, and sent_by_port parameters, as well as any values you specify in the via_params parameter. The VIA header's protocol is SIP and the version number is 2.0.

int sip_create_OKack(sip_msg_t response, sip_msg_t ack_msg, char *transport, char *sent_by, int sent_by_port, char *via_params);

The sip_create_OKack() function constructs an ACK signal for a final 2xx response, in compliance with section 13.2.2.4 of RC 3261. The value of the response parameter is the 2xx response.

Header and Message Copying Functions

int sip_copy_start_line(sip_msg_t from, sip_msg_t to);

The sip_copy_start_line() function copies the first line of the SIP message. The first line is either the request or the response line. The line is copied from the position that is indicated by the value of msg_from to the position that is indicated by the value of msg_to.

int sip_copy_header(sip_msg_t sip_msg, sip_header_t sip_header, char *param);

The sip_copy_header() function creates a new SIP header using the values given by the sip_header and param parameters, if the values for these parameters are not NULL. This function adds the new header to the message that is indicated by the value of the sip_msg parameter.

int sip_copy_header_by_name(sip_msg_t from, sip_msg_t to, char *header_name, char *param);

The sip_copy_header_by_name() function copies the header given by the value of the header_name parameter from the position specified in msg_from to the position specified in msg_to. The value of the header_name parameter can be either the long name or the compact name. The function creates a new SIP header using the contents of the header_name field in msg_from, then adds the value of the param parameter if that value is not NULL. The function adds the resulting header to msg_to.

int sip_copy_all_headers(sip_msg_t from, sip_msg_t to);

The sip_copy_all_headers() function copies all of the headers, except for the start line, from the SIP message indicated in the from parameter to the SIP message indicated in the to parameter. The API will not copy headers from a message that is marked as deleted.

sip_msg_t sip_clone_msg(const sip_msg_t sip_msg);

The sip_clone_msg() function returns a message that is a copy of the SIP message that is indicated by the value of the sip_msg parameter. The function returns a message that contains all of the headers and the contents that are present in the SIP message that is indicated by the value of the sip_msg parameter.

Header and Value Deleting Functions

void sip_delete_start_line(sip_msg_t sip_msg);

The sip_delete_start_line() function deletes the start line from the SIP message that is indicated by the value of the sip_msg parameter. The start line can be either the request line or the response line.

int sip_delete_header(sip_header_t sip_header);

The sip_delete_header() function deletes the header that is indicated by the value of the sip_header parameter from its associated SIP message. The function marks that header as deleted. The stack destroys that header when the SIP message is destroyed.

int sip_delete_header_by_name(sip_msg_t sip_msg, char *header_name);

The sip_delete_header_by_name() function deletes the header that is specified by the value of the header_name parameter from the SIP message that is indicated by the value of the sip_msg parameter. The value of the header_name parameter can be either the long name or the compact name for the SIP header. This function marks the header as deleted. The stack destroys this header when it destroys the SIP message.

int sip_delete_value(sip_header_t header, sip_header_value_t value);

The sip_delete_value() function deletes the value that is specified by the sip_value parameter from the header that is specified by the sip_header parameter. The stack marks the value as deleted and destroys the value when it destroys the header.

Header Lookup Functions

const struct sip_header *sip_get_header(sip_msg_t sip_msg, char *header_name, sip_header_t old_header, int *error);

The sip_get_header() function obtains the SIP message header that is specified by the value of the header_name parameter. If the value of the header_name parameter is NULL, the function returns the first header of the SIP message. If the value of the old_header parameter is not NULL, the function searches for a header that matches the value of the header_name parameter. This search begins from the header specified by the value of the old_header parameter. For example, to search for the first VIA header, use VIA as the value for the header_name parameter and NULL as the value for the old_header parameter. To get the next VIA header from the message, use the value of the sip_header parameter that the previous call to the sip_get_header() function returned as the value of the old_header parameter. This function ignores headers that are marked as deleted. A lookup for a deleted header returns a result of NULL unless the message has another header of the same name that is not marked as deleted. The value of the header_name parameter can be either the long or the compact name.

The value of the error parameter is set to zero when this function completes successfully. When this function completes unsuccessfully, it sets the value of the error parameter to the appropriate error value. If the value of the sip_msg parameter is null, the function sets the value of the error parameter to EINVAL. If the function cannot find the header, it sets the value of the error parameter to ENOENT.

Value Retrieval and Response Description Functions

const struct sip_value *sip_get_header_value(const struct sip_header *sip_header, int *error);

The *sip_get_header_value() function returns the parsed value for the header that is specified by the value of the sip_header parameter. This function does not return any values that are marked as deleted.

const struct sip_value *sip_get_next_value(sip_header_value_t old_value, int *error);

the *sip_get_next_value() function returns the value, if any, that follows the value that is specified by the value of the old_value parameter. This function does not return any values that are marked as deleted.

const sip_str_t *sip_get_param_value(sip_header_value_t value, char *param_name, int *error);

The *sip_get_param_value() function returns the parameter that is specified by the value of the param_name parameter from the SIP message header that is specified by the header_value parameter.

const sip_param_t *sip_get_params(sip_header_value_t value, int *error);

The *sip_get_params() function returns the parameter list that is associated with the value that is specified in the header_value parameter.

char *sip_get_resp_desc(int resp_code);

The *sip_get_resp_desc() function returns the reason phrase for the response code that is specified by the value of the resp_code parameter. This function supports the response codes that are listed in section 21 of RFC 3261. This function returns UNKNOWN for unknown response codes.

SIP ID Generating Functions

char *sip_branchid(sip_msg_t sip_msg);

The *sip_branchid() function returns a randomly generated string for the branch parameter in a VIA header. This function prefixes the string with the string z9hG4bK to meet the requirements of RFC 3261. If the value of the sip_msg parameter is a valid SIP message, this function constructs the branch ID by using an MD5 hash of the VIA, TO, FROM, CALL-ID, CSeq, and Request URI headers. If the value of the sip_msg parameter is NULL, this function returns a random string that is prefixed with the string z9hG4bK. The calling thread must free the string that this function returns.

char *sip_guid();

The *sip_guid() function returns a randomly generated string. The calling thread must free the string that this function returns.

uint32_t sip_get_cseq();

The sip_get_cseq() function returns the most significant 31 bits returned by the time(2) system call. You can use this value as the initial sequence number.

VIA Functions

int sip_get_num_via(sip_msg_t sip_msg, int *error);

The sip_get_num_via() function returns the number of VIA headers that are in the SIP message.

char *sip_get_branchid(sip_msg_t sip_msg, int *error);

The *sip_get_branchid() function returns the value of the branch parameter in the topmost VIA header in the SIP message. The calling thread must free the string that this function returns.

SIP Message Sending Function

int sip_sendmsg(sip_conn_object_t obj, sip_msg_t sip_msg, sip_dialog_t sip_dialog, uint32_t flags);

The sip_sendmsg() function sends a SIP message to the SIP stack and, subsequently, to the peer. The function passes the connection object that is specified by the value of the obj parameter along with the message that is specified by the value of the sip_msg parameter. This function provides the dialog that is associated with the specified SIP message, if that dialog exists and the SIP stack is maintaining dialogs. This function uses flags to indicate any special processing that the stack needs to do for the specified SIP message. The values of flags are the result of a boolean OR operation performed on the following attributes:

SIP_SEND_STATEFUL: Send the request or response statefully. The stack creates and maintains a transaction for the request or response in compliance with section 17 of RFC 3261.
SIP_DIALOG_ON_FORK: When this flag is set, the stack creates multiple dialogs when the application forks the request. This flag is only meaningful when the stack maintains dialogs. When this flag is not set, only the first dialog creating request creates a dialog.

Processing Inbound Messages

void sip_process_new_packet(sip_conn_object_t conn_object, void *msgstr, size_t msglen);

The sip_process_new_packet() function processes the incoming message string from the application using the message string's length and associated connection object. This function transforms the incoming message string into a SIP message. If the transport is byte-stream oriented, this function manages breaking the byte stream at the SIP message boundaries. The stack delivers the SIP message to the application after completing any other required stack processing.

Transaction Layer Functions

const struct sip_xaction *sip_get_trans(sip_msg_t sip_msg, int which, int *error);

The *sip_get_trans() function returns the transaction that is associated with the SIP message in the sip_msg parameter. This function follows the specifications of sections 17.1.3 and 17.2.3 of RFC 3261 to determine a matching transaction. If this function finds a matching transaction, this call increments the reference count on the transaction. The calling thread must release the hold on the transaction by using the sip_release_trans() function. The which parameter specifies whether the transaction of interest is a client or a server transaction. When a client receives a response, the value of the which parameter is SIP_CLIENT_TRANSACTION. When a server gets a request, the value of the which parameter is SIP_SERVER_TRANSACTION.

sip_method_t sip_get_trans_method(sip_transaction_t sip_trans, int *error);

The sip_get_trans_method() function returns the method that created the transaction that is specified by the value of the sip_trans parameter.

int sip_get_trans_state(sip_transaction_t sip_trans, int *error);

The sip_get_trans_state() function returns the state of the transaction that is specified by the value of the sip_trans parameter. A CLIENT transaction can have the following states:

SIP_CLNT_CALLING
SIP_CLNT_INV_PROCEEDING
SIP_CLNT_INV_COMPLETED
SIP_CLNT_INV_TERMINATED
SIP_CLNT_TRYING
SIP_CLNT_NONINV_PROCEEDING
SIP_CLNT_NONINV_COMPLETED
SIP_CLNT_NONINV_TERMINATED

A SERVER transaction can have the following states:

SIP_SRV_INV_PROCEEDING
SIP_SRV_INV_COMPLETED
SIP_SRV_CONFIRMED
SIP_SRV_INV_TERMINATED
SIP_SRV_TRYING
SIP_SRV_NONINV_PROCEEDING
SIP_SRV_NONINV_COMPLETED
SIP_SRV_NONINV_TERMINATED

const struct sip_message *sip_get_trans_orig_msg(sip_transaction_t sip_trans, int *error);

The *sip_get_trans_orig_msg() function returns the original message that created this transaction. A client transaction returns the request. A server transaction returns the response sent to the transaction creating request.

const struct sip_conn_object *sip_get_trans_conn_obj(sip_transaction_t sip_trans, int *error);

The *sip_get_trans_conn_obj() function returns the cached connection object for the transaction that is specified by the value of the sip_trans parameter. This connection object is the object that the application passed in, along with the most recent message for this transaction.

void sip_hold_trans(sip_transaction_t sip_trans, int *error);

The sip_hold_trans() function increments the reference count on the transaction that is specified by the value of the sip_trans parameter. The caller of the sip_get_trans() function must call the sip_release_trans() function for the returned transaction after using the transaction.

void sip_release_trans(sip_transaction_t sip_trans, int *error);

The sip_release_trans() function decrements the reference count on the transaction that is specified by the value of the sip_trans parameter. The caller of the sip_get_trans() function must call the sip_release_trans() function for the returned transaction after using the transaction. If the reference count drops to zero and the transaction is in a terminated state, the stack destroys the transaction.

Dialog Layer Functions

int sip_get_dialog_state(sip_dialog_t dialog, int *error);

The sip_get_dialog_state() function returns the state of a dialog. A dialog be in the following states:

NEW-DIALOG
EARLY-DIALOG
CONFIRMED-DIALOG
DESTROYED-DIALOG

const sip_str_t sip_get_dialog_callid(sip_dialog_t dialog, int *error);

The sip_get_dialog_callid() function returns the pointer to the callid value for the dialog that is specified by the value of the dialog parameter. This function returns a pointer to the value and the length of the value.

const sip_str_t sip_get_dialog_local_tag(sip_dialog_t dialog, int *error);

The sip_get_dialog_local_tag() function returns a pointer to the local tag value for the dialog that is specified by the value of the dialog parameter. This function returns a pointer to the value and the length of the value.

const sip_str_t sip_get_dialog_remote_tag(sip_dialog_t dialog, int *error);

The sip_get_dialog_remote_tag() function returns a pointer to the remote tag value for the dialog that is specified by the value of the dialog parameter. This function returns a pointer to the value and the length of the value.

const struct uri_t sip_get_dialog_local_uri(sip_dialog_t dialog, int *error);

The sip_get_dialog_local_uri() function returns the local URI for the dialog that is specified by the value of the dialog parameter. This function returns a parsed URI.

const struct uri_t sip_get_dialog_remote_uri(sip_dialog_t dialog, int *error);

The sip_get_dialog_remote_uri() function returns the remote URI for the dialog that is specified by the value of the dialog parameter. This function returns a parsed URI.

const struct uri_t sip_get_dialog_remote_target_uri(sip_dialog_t dialog, int *error);

The sip_get_dialog_remote_target_uri() function returns the remote target URI for the dialog that is specified by the value of the dialog parameter. This function returns a URI in the sip_uri_t variable, which is a parsed URI.

const sip_str_t sip_get_dialog_route_set(sip_dialog_t dialog, int *error);

The sip_get_dialog_route_set() function returns the route set for the dialog that is specified by the value of the dialog parameter. The return value is a pointer to the list of comma separated routes and the length of the list.

uint32_t sip_get_dialog_local_cseq(sip_dialog_t dialog, int *error);

The sip_get_dialog_local_cseq() function returns the sequence number for the next request in the dialog.

uint32_t sip_get_dialog_remote_cseq(sip_dialog_t dialog, int *error);

The sip_get_dialog_remote_cseq() function returns the remote CSeq number for the dialog.

int sip_get_dialog_type(sip_dialog_t dialog, int *error);

The sip_get_dialog_type() function returns the type of the dialog. A dialog can have the following types:

SIP_UAC_DIALOG: UAC created dialog
SIP_UAS_DIALOG: UAS created dialog

void sip_hold_dialog(sip_dialog_t dialog, int *error);

The sip_hold_dialog() function increments the reference number for the dialog that is specified by the value of the dialog parameter. The stack will not destroy a dialog with a reference count greater than zero. An application that holds a dialog must release the dialog after using it.

void sip_release_dialog(sip_dialog_t dialog, int *error);

The sip_release_dialog() function decrements the reference number for the dialog that is specified by the value of the dialog parameter. The stack will not destroy a dialog with a reference count greater than zero. An application that holds a dialog must release the dialog after using it.

void sip_delete_dialog(sip_dialog_t dialog, int *error);

The sip_delete_dialog() function terminates the dialog that is specified by the value of the dialog parameter. This function first decrements the reference count for the dialog, then destroys it if the count is zero. The stack will not destroy a dialog with a reference count greater than zero. An application that holds a dialog must release the dialog after using it.

URI Functions

const struct uri_t sip_get_uri_parsed(sip_header_value_t value, int *error);

The sip_get_uri_parsed() function returns the parsed URI from the value that is specified by the value parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const struct uri_t sip_get_request_uri(sip_msg_t sip_msg, int *error);

The sip_get_request_uri() function returns the parsed URI from the start line of a SIP request. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const struct uri_t sip_parse_uri(sip_str_t *sip_uri, int *error);

The sip_parse_uri() function accepts the URI string in the sip_uri parameter and returns a parsed URI. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

boolean_t sip_is_sipuri(sip_uri_t sip_uri);

The sip_is_sipuri() function returns a value of B_TRUE if the sip_uri parameter contains a SIP URI. This function returns a value of B_FALSE in all other cases. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_uri_scheme(const struct uri_t *uri, int *error);

The sip_uri_scheme() function returns the scheme value of the parsed URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_uri_user(const struct uri_t *uri, int *error);

The sip_get_uri_user() function returns the user value of the parsed URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_uri_password(const struct uri_t *uri, int *error);

The sip_get_uri_password() function returns the password value of the parsed URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_uri_host(const struct uri_t *uri, int *error);

The sip_get_uri_host() function returns the host value of the parsed URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

uint_t sip_get_uri_port(sip_uri_t sip_uri, int *error);

The sip_get_uri_port() function returns the port value of the parsed URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_param_t sip_get_sip_uri_params(sip_uri_t sip_uri, int *error);

The sip_get_sip_uri_params() function returns the list of URI parameters for the parsed URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_sip_uri_headers(sip_uri_t sip_uri, int *error);

The sip_get_sip_uri_headers() function returns the URI header from the parsed URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_abs_uri_opaque(sip_uri_t sip_uri, int *error);

The sip_get_abs_uri_opaque() function returns the opaque part of the parsed absolute URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_abs_uri_query(sip_uri_t sip_uri, int *error);

The sip_get_abs_uri_query() function returns the query part of the parsed absolute URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_sip_abs_uri_path(sip_uri_t sip_uri, int *error);

The sip_get_sip_abs_uri_path() function returns the path part of the parsed absolute URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_sip_abs_uri_regname(sip_uri_t sip_uri, int *error);

The sip_get_sip_abs_uri_regname() function returns the reg-name part of the parsed absolute URI that is contained in the sip_uri parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

boolean_t sip_uri_is_tel_user(sip_uri_t sip_uri);

The sip_uri_is_tel_user() function returns a value of B_TRUE if the user from the URI is a telephone subscriber.

char sip_get_uri_error(uint_t errflags);

The sip_get_uri_error() function returns the string representation of the error flags that are contained in the errflags parameter. The calling thread must free the string that this function returns.

SIP Header Value Retrieval Functions

boolean_t sip_msg_is_request(const sip_msg_t sip_msg, int *error);

The sip_msg_is_request() function returns a value of B_TRUE if the message is a request. This function returns a value of B_FALSE in all other cases.

boolean_t sip_msg_is_response(const sip_msg_t sip_msg, int *error);

The sip_msg_is_response() function returns a value of B_TRUE if the message is a response. This function returns a value of B_FALSE in all other cases.

sip_method_t sip_get_request_method(const sip_msg_t sip_msg, int *error);

The sip_get_request_method() function returns the SIP method from the start line of the SIP request message that is contained in the sip_msg parameter.

int sip_get_response_code(sip_msg_t sip_msg, int *error);

The sip_get_response_code() function returns the response code from the start line of the SIP response message that is contained in the sip_msg parameter.

const sip_str_t *sip_get_response_phrase(sip_msg_t sip_msg, int *error);

The sip_get_response_phrase() function returns the reason phrase from the start line of the SIP response message that is contained in the sip_msg parameter.

const sip_str_t *sip_get_sip_version(sip_msg_t sip_msg, int *error);

The sip_get_sip_version() function returns the SIP version from the start line of the SIP response message that is contained in the sip_msg parameter.

int sip_get_msg_len(sip_msg_t sip_msg, int *error);

The sip_get_msg_len() function returns the length of the SIP message that is contained in the sip_msg parameter.

const sip_str_t sip_get_contact_display_name(sip_header_value_t value, int *error);

The sip_get_contact_display_name() function returns the display name from a CONTACT header. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value.

const sip_str_t sip_get_from_display_name(sip_msg_t sip_msg, int *error, int *error);

The sip_get_from_display_name() function returns the display name from a FROM header. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_to_display_name(sip_msg_t sip_msg, int *error);

The sip_get_to_display_name() function returns the display name from a TO header. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t *sip_get_from_tag(sip_msg_t sip_msg, int *error);

The sip_get_from_tag() function returns the tag value from a FROM header. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_to_tag(sip_msg_t sip_msg, int *error);

The sip_get_to_tag() function returns the tag value from a TO header. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_callid(sip_msg_t sip_msg, int *error);

The sip_get_callid() function gets the callid value from a Call-ID header. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

int sip_get_callseq_num(sip_msg_t sip_msg, int *error);

The sip_get_callseq_num() function returns the call sequence value from the Cseq header. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

sip_method_t sip_get_callseq_method(sip_msg_t sip_msg, int *error);

The sip_get_callseq_method() function returns the method from the Cseq header. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_via_sent_by_host(sip_header_value_t value, int *error);

The sip_get_via_sent_by_host() function returns the value of the host from a VIA header.

int sip_get_via_sent_by_port(sip_header_value_t value, int *error);

The sip_get_via_sent_by_port() function returns the value of the port from a VIA header.

const sip_str_t sip_get_via_sent_protocol_version(sip_header_value_t value, int *error);

The sip_get_via_sent_protocol_version() function returns the value of the protocol version from a VIA header.

const sip_str_t sip_get_via_sent_protocol_name(sip_header_value_t value, int *error);

The sip_get_via_sent_protocol_name() function returns the value of the protocol name from a VIA header.

const sip_str_t sip_get_via_sent_transport(sip_header_value_t value, int *error);

The sip_get_via_sent_transport() function returns the value of the transport from a VIA header.

int sip_get_maxforward(sip_msg_t sip_msg, int *error);

The sip_get_maxforward() function returns the number of hops that is listed as a value in the Max-forwards header. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

int sip_get_content_length(sip_msg_t sip_msg, int *error);

the sip_get_content_length() function returns the length that is listed as a value in the Content-Length header of a SIP message. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_content_type(sip_msg_t sip_msg, int *error);

The sip_get_content_type() function returns the content type from the Content-Type header of a SIP message. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_content_sub_type(sip_msg_t sip_msg, int *error);

The sip_get_content_sub_type() function returns the content subtype from the Content-Type header of a SIP message. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

char sip_get_content(sip_msg_t sip_msg, int *error);

The sip_get_content() function returns the message body of the SIP message. The calling thread must free the string that this function returns. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_accept_type(sip_header_value_t value, int *error);

The sip_get_accept_type() function returns the type from the Accept header value of a SIP message. This function returns a pointer to the header and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_accept_sub_type(sip_header_value_t value, int *error);

The sip_get_accept_sub_type() function returns the subtype from the Accept header value of a SIP message. This function returns a pointer to the header and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_accept_enc(sip_header_value_t value, int *error);

The sip_get_accept_enc() function returns the encoding from the Accept-Encoding header value of a SIP message. This function returns a pointer to the header and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_accept_lang(sip_header_value_t value, int *error);

The sip_get_accept_lang() function returns the language from the Accept-Language header value of a SIP message. This function returns a pointer to the header and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_alert_info_uri(sip_header_value_t value, int *error);

The sip_get_alert_info_uri() function returns the URI string alert-param from the Alert-Info header value of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

sip_method_t sip_get_allow_method(sip_header_value_t value, int *error);

The sip_get_allow_method() function returns the method from the Allow header value of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

int sip_get_min_expires(sip_msg_t sip_msg, int *error);

The sip_get_min_expires() function returns the number of seconds that is specified in the Min-Expires header value of the SIP message that is specified in the sip_msg parameter. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_mime_version(sip_msg_t sip_msg, int *error);

The sip_get_mime_version() function returns the MIME version value of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_org(sip_msg_t sip_msg, int *error);

The sip_get_org() function returns the value of the Organization header value of a SIP message. This function returns a pointer to the header and the length of the value.

const sip_str_t *sip_get_priority(sip_msg_t sip_msg, int *error);

The sip_get_priority() function returns the value of the Priority header value of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_replyto_display_name(sip_msg_t sip_msg, int *error);

The sip_get_replyto_display_name() function returns the display name from the Reply-To header value of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_replyto_uri_str(sip_msg_t sip_msg, int *error);

The sip_get_replyto_uri_str() function returns the URI from the Reply-To header value of a SIP message. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_date_time(sip_msg_t sip_msg, int *error);

The sip_get_date_time() function returns the value of the time from the Date header of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

int sip_get_date_day(sip_msg_t sip_msg, int *error);

The sip_get_date_day() function returns the value of the day from the Date header of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_date_month(sip_msg_t sip_msg, int *error);

The sip_get_date_month() function returns the value of the month from the Date header of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_date_wkday(sip_msg_t sip_msg, int *error);

The sip_get_date_wkday() function returns the value of the weekday from the Date header of a SIP message. This function returns a pointer to the header and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

int sip_get_date_year(sip_msg_t sip_msg, int *error);

The sip_get_date_year() function returns the value of the year from the Date header of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_date_timezone(sip_msg_t sip_msg, int *error);

The sip_get_date_timezone() function returns the value of the time zone from the Date header of a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_content_disp(sip_msg_t sip_msg, int *error);

The sip_get_content_disp() function returns the value of the Content-Disposition header in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_date_content_enc(sip_header_value_t value, int *error);

The sip_get_date_content_enc() function returns the encoding from the Content-Encoding header value. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_error_info_uri(sip_header_value_t value, int *error);

The sip_get_error_info_uri() function returns the URI string from the Error-Info header value. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

int sip_get_expires(sip_msg_t sip_msg, int *error);

The sip_get_expires() function returns the Expires header value. This header value is an integer. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_require(sip_header_value_t value, int *error);

The sip_get_require() function returns the value of the Require header. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_subject(sip_msg_t sip_msg, int *error);

The sip_get_subject() function returns the value of the Subject header in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_supported(sip_header_value_t value, int *error);

The sip_get_supported() function returns the value of the supported extension from the Supported header. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_tstamp_delay(sip_msg_t, int *, int *error);

The sip_get_tstamp_delay() function returns the value of the Timestamp header in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value.

const sip_str_t sip_get_unsupported(sip_header_value_t value, int *error);

The sip_get_unsupported() function returns the list of the unsupported features from the Unsupported header value in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_server(sip_msg_t sip_msg, int *error);

The sip_get_server() function returns the value of the Server header in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_user_agent(sip_msg_t sip_msg, int *error);

The sip_get_user_agent() function returns the value of the User-Agent header in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

int sip_get_warning_code(sip_header_value_t value, int *error);

The sip_get_warning_code() function returns the value of the warning code from the Warning header value in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_warning_agent(sip_header_value_t value, int *error);

The sip_get_warning_agent() function returns the value of the warning agent from the Warning header value in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_warning_text(sip_header_value_t value, int *error);

The sip_get_warning_text() function returns the value of the warning text from the Warning header value in a SIP message. This function returns a pointer to the header and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_call_info_uri(sip_header_value_t value, int *error);

The sip_call_info_uri() function returns the URI string from the Call-Info header value in a SIP message. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_in_reply_to(sip_header_value_t value, int *error);

The sip_get_in_reply_to() function returns the value of callid from the In-Reply-To header value in a SIP message. This function returns a pointer to the display name (or the tag or callid, as appropriate) and the length of the value. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

int sip_get_retry_after_time(sip_msg_t sip_msg, int *error);

The sip_get_retry_after_time() function returns the value of the time interval from the Retry-After header in a SIP message. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

const sip_str_t sip_get_retry_after_cmts(sip_msg_t sip_msg, int *error);

The sip_get_retry_after_cmts() function returns the value of the comments from the Retry-After header in a SIP message. If the value of the *error parameter is not NULL, the function sets the value to zero if the function completes successfully. If the function does not complete successfully, the function sets the value of the *error parameter to the error number.

Connection Object Functions

int sip_conn_send(const sip_conn_object_t conn_obj, char *msg, int msglen);

The sip_conn_send() function is an interface that the application registers. This function sends out the message in the *msg parameter with a length defined by the msglen parameter over the connection that is represented by the conn_obj parameter. The stack invokes this function to send the message to the peer after processing.

void sip_hold_conn_object(sip_conn_object_t conn_obj);

The sip_hold_conn_object() function is an interface that the application registers. The stack invokes this interface to increment the reference count on the connection object referenced by the conn_obj parameter. The stack invokes this function when it caches the connection object. The application cannot free the connection object if the object has any existing references.

void sip_rel_conn_object(sip_conn_object_t conn_obj);

The sip_rel_conn_object() function is an interface that the application registers. The stack invokes this interface to release a reference to a connection object referenced by the conn_obj parameter. The stack invokes this function after removing any cached connection object. The application can free connection objects that have no references.

boolean_t sip_conn_is_reliable(sip_conn_object_t conn_obj);

The sip_conn_is_reliable() function is an interface that the application registers. The stack invokes this interface to query whether or not the transport protocol for the connection object referenced by the conn_obj parameter is reliable. Reliable transport protocols include TCP and SCTP. UDP is an unreliable protocol.

boolean_t sip_conn_is_stream(sip_conn_object_t conn_obj);

The sip_conn_is_stream() function is an interface that the application registers. The stack invokes this interface to query whether or not is byte-stream oriented. TCP is a byte-stream protocol. SCTP and UDP are message-oriented protocols.

int sip_conn_remote_address(sip_conn_object_t conn_obj, struct sockaddr *name, socklen_t *namelen);

The sip_conn_remote_address() function provides the remote address in the sockaddr structure provided in the name parameter. On invocation, the namelen parameter contains the length of the address that the calling thread provides to this function. When this function returns from the call, the len parameter contains the actual length of the address.

int sip_conn_local_address(sip_conn_object_t conn_obj, struct sockaddr *name, socklen_t *namelen);

The sip_conn_local_address() function provides the local address in the sockaddr structure provided in the name parameter. On invocation, the namelen parameter contains the length of the address that the calling thread provides to this function. When this function returns from the call, the len parameter contains the actual length of the address.

int sip_conn_transport(const sip_conn_object_t conn_obj);

The sip_conn_transport() function returns the transport protocol that is associated with the connection object that is specified in the conn_obj parameter.

int sip_conn_timer1(const sip_conn_object_t conn_obj);

An application can register the sip_conn_timer1() function to provide a timer value for the T1 timer that is specific to the connection object that is defined in the conn_obj parameter. If the application does not register this function, the stack uses the default value of 500 msec. Timer T1 is the round trip time (RTT) estimate.

int sip_conn_timer2(const sip_conn_object_t conn_obj);

An application can register the sip_conn_timer2() function to provide a timer value for the T2 timer that is specific to the connection object that is defined in the conn_obj parameter. If the application does not register this function, the stack uses the default value of 4 seconds. Timer T2 is the maximum retransmit interval for non-INVITE requests and INVITE responses.

int sip_conn_timer4(const sip_conn_object_t conn_obj);

An application can register the sip_conn_timer4() function to provide a timer value for the T4 timer that is specific to the connection object that is defined in the conn_obj parameter. If the application does not register this function, the stack uses the default value of 5 seconds. Timer T4 is the maximum duration that a message will remain in the network.

int sip_conn_timerd(const sip_conn_object_t conn_obj);

An application can register the sip_conn_timerd() function to provide a timer value for the TD timer that is specific to the connection object that is defined in the conn_obj parameter. If the application does not register this function, the stack uses the default value of 32 seconds. Timer TD is the wait time for response retransmits.

Miscellaneous Functions

char sip_msg_to_str(sip_msg_t sip_msg, int *error);

The sip_msg_to_str() function returns a string that contains all of the headers and content in the SIP message that is defined by the sip_msg parameter. The calling thread must free the string that this function returns.

char sip_hdr_to_str(sip_header_t sip_header, int *error);

The sip_hdr_to_str() function returns the value of the sip_header parameter as a string. The calling thread must free the string that this function returns.

char sip_reqline_to_str(sip_msg_t sip_msg, int *error);

The sip_reqline_to_str() function returns the request line in the SIP message that is defined by the sip_msg parameter as a string. The calling thread must free the string that this function returns.

char *sip_respline_to_str(sip_msg_t sip_msg, int *error);

The sip_respline_to_str() function returns the response line in the SIP message that is defined by the sip_msg parameter as a string. The calling thread must free the string that this function returns.

int sip_init_conn_object(sip_conn_object_t conn_obj);

The sip_init_conn_object() function initializes a connection object with library specific private data.

void sip_clear_stale_data(sip_conn_object_t conn_obj);

The sip_clear_stale_data() function clears any library specific private data that is stored in the connection object that is specified by the conn_obj parameter.

void sip_conn_destroyed(sip_conn_object_t conn_obj);

The sip_conn_destroyed() function clears any library specific private data that is stored in the connection object that is defined by the value of the obj parameter. This function also performs cleanup if this connection object has been cached by the system.