SIP API Developer's Guide

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 –

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.


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:

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:

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.