Group PJSIP_ENDPT_STATELESS

group PJSIP_ENDPT_STATELESS

Utilities to create various messages and base function to send messages.

Typedefs

typedef void (*pjsip_send_callback)(pjsip_send_state *st, pj_ssize_t sent, pj_bool_t *cont)

Declaration for callback function to be specified in pjsip_endpt_send_request_stateless(), pjsip_endpt_send_response(), or pjsip_endpt_send_response2().

Param st:

Structure to keep transmission state.

Param sent:

Number of bytes sent.

Param cont:

When current transmission fails, specify whether the function should fallback to next destination.

Functions

pj_status_t pjsip_endpt_create_request(pjsip_endpoint *endpt, const pjsip_method *method, const pj_str_t *target, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, const pj_str_t *call_id, int cseq, const pj_str_t *text, pjsip_tx_data **p_tdata)

Create an independent request message. This can be used to build any request outside a dialog, such as OPTIONS, MESSAGE, etc. To create a request inside a dialog, application should use pjsip_dlg_create_request.

This function adds the following headers in the request:

  • From, To, Call-ID, and CSeq,

  • Contact header, if contact is specified.

  • A blank Via header.

  • Additional request headers (such as Max-Forwards) which are copied from endpoint configuration.

In addition, the function adds a unique tag in the From header.

Once a transmit data is created, the reference counter is initialized to 1.

Parameters:

  • endpt – Endpoint instance.

  • method – SIP Method.

  • target – Target URI.

  • from – URL to put in From header.

  • to – URL to put in To header.

  • contact – Contact to be put as Contact header value, hence the format must follow RFC 3261 Section 20.10: When the header field value contains a display name, the URI including all URI parameters is enclosed in “<” and “>”. If no “<” and “>” are present, all parameters after the URI are header parameters, not URI parameters. The display name can be tokens, or a quoted string, if a larger character set is desired.

  • call_id – Optional Call-ID (put NULL to generate unique Call-ID).

  • cseq – Optional CSeq (put -1 to generate random CSeq).

  • text – Optional text body (put NULL to omit body).

  • p_tdata – Pointer to receive the transmit data.

Returns:

PJ_SUCCESS, or the appropriate error code.

pj_status_t pjsip_endpt_create_request_from_hdr(pjsip_endpoint *endpt, const pjsip_method *method, const pjsip_uri *target, const pjsip_from_hdr *from, const pjsip_to_hdr *to, const pjsip_contact_hdr *contact, const pjsip_cid_hdr *call_id, int cseq, const pj_str_t *text, pjsip_tx_data **p_tdata)

Create an independent request message from the specified headers. This function will clone the headers and put them in the request.

This function adds the following headers in the request:

  • From, To, Call-ID, and CSeq,

  • Contact header, if contact is specified.

  • A blank Via header.

  • Additional request headers (such as Max-Forwards) which are copied from endpoint configuration.

In addition, the function adds a unique tag in the From header.

Once a transmit data is created, the reference counter is initialized to 1.

Parameters:

  • endpt – Endpoint instance.

  • method – SIP Method.

  • target – Target URI.

  • from – From header.

  • to – To header.

  • contact – Contact header.

  • call_id – Optional Call-ID (put NULL to generate unique Call-ID).

  • cseq – Optional CSeq (put -1 to generate random CSeq).

  • text – Optional text body (put NULL to omit body).

  • p_tdata – Pointer to receive the transmit data.

Returns:

PJ_SUCCESS, or the appropriate error code.

pj_status_t pjsip_endpt_create_response(pjsip_endpoint *endpt, const pjsip_rx_data *rdata, int st_code, const pj_str_t *st_text, pjsip_tx_data **p_tdata)

Construct a minimal response message for the received request. This function will construct all the Via, Record-Route, Call-ID, From, To, CSeq, and Call-ID headers from the request.

Once a transmit data is created, the reference counter is initialized to 1.

Parameters:

  • endpt – The endpoint.

  • rdata – The request receive data.

  • st_code – Status code to be put in the response.

  • st_text – Optional status text, or NULL to get the default text.

  • p_tdata – Pointer to receive the transmit data.

Returns:

PJ_SUCCESS, or the appropriate error code.

pj_status_t pjsip_endpt_create_ack(pjsip_endpoint *endpt, const pjsip_tx_data *tdata, const pjsip_rx_data *rdata, pjsip_tx_data **ack)

Construct a full ACK request for the received non-2xx final response. This utility function is normally called by the transaction to construct an ACK request to 3xx-6xx final response. The generation of ACK message for 2xx final response is different than this one.

Once a transmit data is created, the reference counter is initialized to 1.

Parameters:

  • endpt – The endpoint.

  • tdata – This contains the original INVITE request

  • rdata – The final response.

  • ack – The ACK request created.

Returns:

PJ_SUCCESS, or the appropriate error code.

pj_status_t pjsip_endpt_create_cancel(pjsip_endpoint *endpt, const pjsip_tx_data *tdata, pjsip_tx_data **p_tdata)

Construct CANCEL request for the previously sent request.

Once a transmit data is created, the reference counter is initialized to 1.

Parameters:

  • endpt – The endpoint.

  • tdata – The transmit buffer for the request being cancelled.

  • p_tdata – Pointer to receive the transmit data.

Returns:

PJ_SUCCESS, or the appropriate error code.

pj_status_t pjsip_get_dest_info(const pjsip_uri *target_uri, const pjsip_uri *request_uri, pj_pool_t *pool, pjsip_host_info *dest_info)

Get destination address and port and transport type information for the specified URI.

Parameters:

  • target_uri – The destination URI.

  • request_uri – Optional request URI to be considered. May be NULL.

  • pool – Pool to allocate memory from.

  • dest_info – To be filled with destination info.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pjsip_get_request_dest(const pjsip_tx_data *tdata, pjsip_host_info *dest_info)

Find which destination to be used to send the request message, based on the request URI and Route headers in the message. The procedure used here follows the guidelines on sending the request in RFC 3261 chapter 8.1.2.

Note there was a change in the behavior of this function since version 0.5.10.2. Previously this function may modify the request when strict route is present (to update request URI and route-set). This is no longer the case now, and this process is done in separate function (see pjsip_process_route_set()).

See also

pjsip_process_route_set

Parameters:

  • tdata – The transmit data containing the request message.

  • dest_info – On return, it contains information about destination host to contact, along with the preferable transport type, if any. Caller will then normally proceed with resolving this host with server resolution procedure described in RFC 3263.

Returns:

PJ_SUCCESS, or the appropriate error code.

pj_status_t pjsip_process_route_set(pjsip_tx_data *tdata, pjsip_host_info *dest_info)

Process route-set found in the request and calculate destination to be used to send the request message, based on the request URI and Route headers in the message. The procedure used here follows the guidelines on sending the request in RFC 3261 chapter 8.1.2.

This function may modify the message (request line and Route headers), if the Route information specifies strict routing and the request URI in the message is different than the calculated target URI. In that case, the target URI will be put as the request URI of the request and current request URI will be put as the last entry of the Route headers.

See also

pjsip_get_request_addr

Parameters:

  • tdata – The transmit data containing the request message.

  • dest_info – On return, it contains information about destination host to contact, along with the preferable transport type, if any. Caller will then normally proceed with resolving this host with server resolution procedure described in RFC 3263.

Returns:

PJ_SUCCESS, or the appropriate error code.

void pjsip_restore_strict_route_set(pjsip_tx_data *tdata)

Swap the request URI and strict route back to the original position before pjsip_process_route_set() function is called. If no strict route URI was found by pjsip_process_route_set(), this function will do nothing.

This function should only used internally by PJSIP client authentication module.

Parameters:

tdata – Transmit data containing request message.

pj_status_t pjsip_endpt_send_request_stateless(pjsip_endpoint *endpt, pjsip_tx_data *tdata, void *token, pjsip_send_callback cb)

Send outgoing request statelessly The function will take care of which destination and transport to use based on the information in the message, taking care of URI in the request line and Route header.

This function is different than pjsip_transport_send() in that this function adds/modify the Via header as necessary.

Parameters:

  • endpt – The endpoint instance.

  • tdata – The transmit data to be sent.

  • token – Arbitrary token to be given back on the callback.

  • cb – Optional callback to notify transmission status (also gives chance for application to discontinue retrying sending to alternate address).

Returns:

PJ_SUCCESS, or the appropriate error code.

pj_status_t pjsip_endpt_send_raw(pjsip_endpoint *endpt, pjsip_transport_type_e tp_type, const pjsip_tpselector *sel, const void *raw_data, pj_size_t data_len, const pj_sockaddr_t *addr, int addr_len, void *token, pjsip_tp_send_callback cb)

This is a low-level function to send raw data to a destination.

See also pjsip_endpt_send_raw_to_uri().

Parameters:

  • endpt – The SIP endpoint instance.

  • tp_type – Transport type.

  • sel – Optional pointer to transport selector instance if application wants to use a specific transport instance rather then letting transport manager finds the suitable transport..

  • raw_data – The data to be sent.

  • data_len – The length of the data.

  • addr – Destination address.

  • addr_len – Length of destination address.

  • token – Arbitrary token to be returned back to callback.

  • cb – Optional callback to be called to notify caller about the completion status of the pending send operation.

Returns:

If the message has been sent successfully, this function will return PJ_SUCCESS and the callback will not be called. If message cannot be sent immediately, this function will return PJ_EPENDING, and application will be notified later about the completion via the callback. Any statuses other than PJ_SUCCESS or PJ_EPENDING indicates immediate failure, and in this case the callback will not be called.

pj_status_t pjsip_endpt_send_raw_to_uri(pjsip_endpoint *endpt, const pj_str_t *dst_uri, const pjsip_tpselector *sel, const void *raw_data, pj_size_t data_len, void *token, pjsip_tp_send_callback cb)

Send raw data to the specified destination URI. The actual destination address will be calculated from the URI, using normal SIP URI to host resolution.

See also pjsip_endpt_send_raw().

Parameters:

  • endpt – The SIP endpoint instance.

  • dst_uri – Destination address URI.

  • sel – Optional pointer to transport selector instance if application wants to use a specific transport instance rather then letting transport manager finds the suitable transport..

  • raw_data – The data to be sent.

  • data_len – The length of the data.

  • token – Arbitrary token to be returned back to callback.

  • cb – Optional callback to be called to notify caller about the completion status of the pending send operation.

Returns:

If the message has been sent successfully, this function will return PJ_SUCCESS and the callback will not be called. If message cannot be sent immediately, this function will return PJ_EPENDING, and application will be notified later about the completion via the callback. Any statuses other than PJ_SUCCESS or PJ_EPENDING indicates immediate failure, and in this case the callback will not be called.

pj_status_t pjsip_get_response_addr(pj_pool_t *pool, pjsip_rx_data *rdata, pjsip_response_addr *res_addr)

Determine which address (and transport) to use to send response message based on the received request. This function follows the specification in section 18.2.2 of RFC 3261 and RFC 3581 for calculating the destination address and transport.

The information about destination to send the response will be returned in res_addr argument. Please see pjsip_response_addr for more info.

Parameters:

  • pool – The pool.

  • rdata – The incoming request received by the server.

  • res_addr – On return, it will be initialized with information about destination address and transport to send the response.

Returns:

zero (PJ_OK) if successfull.

pj_status_t pjsip_endpt_send_response(pjsip_endpoint *endpt, pjsip_response_addr *res_addr, pjsip_tx_data *tdata, void *token, pjsip_send_callback cb)

Send response in tdata statelessly. The function will take care of which response destination and transport to use based on the information in the Via header (such as the presence of rport, symmetric transport, etc.).

This function will create a new ephemeral transport if no existing transports can be used to send the message to the destination. The ephemeral transport will be destroyed after some period if it is not used to send any more messages.

The behavior of this function complies with section 18.2.2 of RFC 3261 and RFC 3581.

Parameters:

  • endpt – The endpoint instance.

  • res_addr – The information about the address and transport to send the response to. Application can get this information by calling pjsip_get_response_addr().

  • tdata – The response message to be sent.

  • token – Token to be passed back when the callback is called.

  • cb – Optional callback to notify the transmission status to application, and to inform whether next address or transport will be tried.

Returns:

PJ_SUCCESS if response has been successfully created and sent to transport layer, or a non-zero error code. However, even when it returns PJ_SUCCESS, there is no guarantee that the response has been successfully sent.

pj_status_t pjsip_endpt_send_response2(pjsip_endpoint *endpt, pjsip_rx_data *rdata, pjsip_tx_data *tdata, void *token, pjsip_send_callback cb)

This is a convenient function which wraps pjsip_get_response_addr() and pjsip_endpt_send_response() in a single function.

Parameters:

  • endpt – The endpoint instance.

  • rdata – The original request to be responded.

  • tdata – The response message to be sent.

  • token – Token to be passed back when the callback is called.

  • cb – Optional callback to notify the transmission status to application, and to inform whether next address or transport will be tried.

Returns:

PJ_SUCCESS if response has been successfully created and sent to transport layer, or a non-zero error code. However, even when it returns PJ_SUCCESS, there is no guarantee that the response has been successfully sent.

pj_status_t pjsip_endpt_respond_stateless(pjsip_endpoint *endpt, pjsip_rx_data *rdata, int st_code, const pj_str_t *st_text, const pjsip_hdr *hdr_list, const pjsip_msg_body *body)

This composite function sends response message statelessly to an incoming request message. Internally it calls pjsip_endpt_create_response() and pjsip_endpt_send_response().

Parameters:

  • endpt – The endpoint instance.

  • rdata – The incoming request message.

  • st_code – Status code of the response.

  • st_text – Optional status text of the response.

  • hdr_list – Optional header list to be added to the response.

  • body – Optional message body to be added to the response.

Returns:

PJ_SUCCESS if response message has successfully been sent.

struct pjsip_send_state
#include <sip_util.h>

This structure holds the state of outgoing stateless request.

Public Members

void *token

Application token, which was specified when the function pjsip_endpt_send_request_stateless() is called.

pjsip_endpoint *endpt

Endpoint instance.

pjsip_tx_data *tdata

Transmit data buffer being sent.

pjsip_transport *cur_transport

Current transport being used.

void (*app_cb)(struct pjsip_send_state*, pj_ssize_t sent, pj_bool_t *cont)

The application callback which was specified when the function pjsip_endpt_send_request_stateless() was called.

struct pjsip_response_addr
#include <sip_util.h>

This structure describes destination information to send response. It is initialized by calling pjsip_get_response_addr().

If the response message should be sent using transport from which the request was received, then transport, addr, and addr_len fields are initialized.

The dst_host field is also initialized. It should be used when server fails to send the response using the transport from which the request was received, or when the transport is NULL, which means server must send the response to this address (this situation occurs when maddr parameter is set, or when rport param is not set in the request).

Public Members

pjsip_transport *transport

Immediate transport to be used.

pj_sockaddr addr

Immediate address to send to.

int addr_len

Address length.

pjsip_host_info dst_host

Destination host to contact.