Message Creation and Stateless Operations
[At the Very Core]

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

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_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)

---

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:

	st	Structure to keep transmission state.
	sent	Number of bytes sent.
	cont	When 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:

	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.

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

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.

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.

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_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:

	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.

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:

	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.

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:

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.