Home --> Documentations --> PJSIP Reference

Data Structures | Typedefs | Functions
Message Creation and Stateless Operations

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

Data Structures

struct  pjsip_send_state
 
struct  pjsip_response_addr
 

Typedefs

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

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)
 
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)
 
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)
 
pj_status_t pjsip_endpt_create_ack (pjsip_endpoint *endpt, const pjsip_tx_data *tdata, const pjsip_rx_data *rdata, pjsip_tx_data **ack)
 
pj_status_t pjsip_endpt_create_cancel (pjsip_endpoint *endpt, const pjsip_tx_data *tdata, pjsip_tx_data **p_tdata)
 
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)
 
pj_status_t pjsip_get_request_dest (const pjsip_tx_data *tdata, pjsip_host_info *dest_info)
 
pj_status_t pjsip_process_route_set (pjsip_tx_data *tdata, pjsip_host_info *dest_info)
 
void pjsip_restore_strict_route_set (pjsip_tx_data *tdata)
 
pj_status_t pjsip_endpt_send_request_stateless (pjsip_endpoint *endpt, pjsip_tx_data *tdata, void *token, pjsip_send_callback cb)
 
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)
 
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)
 
pj_status_t pjsip_get_response_addr (pj_pool_t *pool, pjsip_rx_data *rdata, pjsip_response_addr *res_addr)
 
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)
 
pj_status_t pjsip_endpt_send_response2 (pjsip_endpoint *endpt, pjsip_rx_data *rdata, pjsip_tx_data *tdata, void *token, pjsip_send_callback cb)
 
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)
 

Detailed Description

Typedef Documentation

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

Parameters
stStructure to keep transmission state.
sentNumber of bytes sent.
contWhen current transmission fails, specify whether the function should fallback to next destination.

Function Documentation

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
endptEndpoint instance.
methodSIP Method.
targetTarget URI.
fromURL to put in From header.
toURL to put in To header.
contactContact 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_idOptional Call-ID (put NULL to generate unique Call-ID).
cseqOptional CSeq (put -1 to generate random CSeq).
textOptional text body (put NULL to omit body).
p_tdataPointer 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
endptEndpoint instance.
methodSIP Method.
targetTarget URI.
fromFrom header.
toTo header.
contactContact header.
call_idOptional Call-ID (put NULL to generate unique Call-ID).
cseqOptional CSeq (put -1 to generate random CSeq).
textOptional text body (put NULL to omit body).
p_tdataPointer 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.

Note: the txdata reference counter is set to ZERO!.

Parameters
endptThe endpoint.
rdataThe request receive data.
st_codeStatus code to be put in the response.
st_textOptional status text, or NULL to get the default text.
p_tdataPointer 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.

Parameters
endptThe endpoint.
tdataThis contains the original INVITE request
rdataThe final response.
ackThe 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.

Parameters
endptThe endpoint.
tdataThe transmit buffer for the request being cancelled.
p_tdataPointer 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_uriThe destination URI.
request_uriOptional request URI to be considered. May be NULL.
poolPool to allocate memory from.
dest_infoTo 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()).

Parameters
tdataThe transmit data containing the request message.
dest_infoOn 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.
See also
pjsip_process_route_set
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.

Parameters
tdataThe transmit data containing the request message.
dest_infoOn 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.
See also
pjsip_get_request_addr
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
tdataTransmit 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
endptThe endpoint instance.
tdataThe transmit data to be sent.
tokenArbitrary token to be given back on the callback.
cbOptional 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
endptThe SIP endpoint instance.
tp_typeTransport type.
selOptional pointer to transport selector instance if application wants to use a specific transport instance rather then letting transport manager finds the suitable transport..
raw_dataThe data to be sent.
data_lenThe length of the data.
addrDestination address.
addr_lenLength of destination address.
tokenArbitrary token to be returned back to callback.
cbOptional 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
endptThe SIP endpoint instance.
dst_uriDestination address URI.
selOptional pointer to transport selector instance if application wants to use a specific transport instance rather then letting transport manager finds the suitable transport..
raw_dataThe data to be sent.
data_lenThe length of the data.
tokenArbitrary token to be returned back to callback.
cbOptional 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
poolThe pool.
rdataThe incoming request received by the server.
res_addrOn 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
endptThe endpoint instance.
res_addrThe information about the address and transport to send the response to. Application can get this information by calling pjsip_get_response_addr().
tdataThe response message to be sent.
tokenToken to be passed back when the callback is called.
cbOptional 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
endptThe endpoint instance.
rdataThe original request to be responded.
tdataThe response message to be sent.
tokenToken to be passed back when the callback is called.
cbOptional 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
endptThe endpoint instance.
rdataThe incoming request message.
st_codeStatus code of the response.
st_textOptional status text of the response.
hdr_listOptional header list to be added to the response.
bodyOptional message body to be added to the response.
Returns
PJ_SUCCESS if response message has successfully been sent.

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.