STUN Client Transaction

STUN client transaction. More...

Data Structures
struct	pj_stun_tsx_cb

Typedefs
typedef struct pj_stun_client_tsx	pj_stun_client_tsx

Functions
pj_status_t	pj_stun_client_tsx_create (pj_stun_config *cfg, pj_pool_t *pool, pj_grp_lock_t *grp_lock, const pj_stun_tsx_cb *cb, pj_stun_client_tsx **p_tsx)
pj_status_t	pj_stun_client_tsx_schedule_destroy (pj_stun_client_tsx *tsx, const pj_time_val *delay)
pj_status_t	pj_stun_client_tsx_destroy (pj_stun_client_tsx *tsx)
pj_status_t	pj_stun_client_tsx_stop (pj_stun_client_tsx *tsx)
pj_bool_t	pj_stun_client_tsx_is_complete (pj_stun_client_tsx *tsx)
pj_status_t	pj_stun_client_tsx_set_data (pj_stun_client_tsx *tsx, void *data)
void *	pj_stun_client_tsx_get_data (pj_stun_client_tsx *tsx)
pj_status_t	pj_stun_client_tsx_send_msg (pj_stun_client_tsx *tsx, pj_bool_t retransmit, void *pkt, unsigned pkt_len)
pj_status_t	pj_stun_client_tsx_retransmit (pj_stun_client_tsx *tsx, pj_bool_t mod_count)
pj_status_t	pj_stun_client_tsx_on_rx_msg (pj_stun_client_tsx *tsx, const pj_stun_msg *msg, const pj_sockaddr_t *src_addr, unsigned src_addr_len)

Detailed Description

The STUN Client Transaction is used to manage outgoing STUN request, for example to retransmit the request and to notify application about the completion of the request.

The STUN Client Transaction does not use any networking operations, but instead application must supply the transaction with a callback to be used by the transaction to send outgoing requests. This way the STUN transaction is made more generic and can work with different types of networking codes in application.

Typedef Documentation

pj_stun_client_tsx

typedef struct pj_stun_client_tsx pj_stun_client_tsx

Opaque declaration of STUN client transaction.

Function Documentation

pj_stun_client_tsx_create()

pj_status_t pj_stun_client_tsx_create	(	pj_stun_config *	cfg,
		pj_pool_t *	pool,
		pj_grp_lock_t *	grp_lock,
		const pj_stun_tsx_cb *	cb,
		pj_stun_client_tsx **	p_tsx
	)

Create an instance of STUN client transaction. The STUN client transaction is used to transmit outgoing STUN request and to ensure the reliability of the request by periodically retransmitting the request, if necessary.

Parameters

cfg	The STUN endpoint, which will be used to retrieve various settings for the transaction.
pool	Pool to be used to allocate memory from.
grp_lock	Group lock to synchronize.
cb	Callback structure, to be used by the transaction to send message and to notify the application about the completion of the transaction.
p_tsx	Pointer to receive the transaction instance.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_stun_client_tsx_destroy()

pj_status_t pj_stun_client_tsx_destroy

(

pj_stun_client_tsx *

tsx

)

Destroy the STUN transaction immediately after the transaction is complete. Application normally calls this function in the on_complete() callback.

Parameters

tsx	The STUN transaction.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_stun_client_tsx_get_data()

void * pj_stun_client_tsx_get_data

(

pj_stun_client_tsx *

tsx

)

Get the user data that was previously associated with the STUN transaction.

Parameters

tsx	The STUN client transaction.

Returns

The user data.

pj_stun_client_tsx_is_complete()

pj_bool_t pj_stun_client_tsx_is_complete

(

pj_stun_client_tsx *

tsx

)

Check if transaction has completed.

Parameters

tsx	The STUN transaction.

Returns

Non-zero if transaction has completed.

pj_stun_client_tsx_on_rx_msg()

pj_status_t pj_stun_client_tsx_on_rx_msg	(	pj_stun_client_tsx *	tsx,
		const pj_stun_msg *	msg,
		const pj_sockaddr_t *	src_addr,
		unsigned	src_addr_len
	)

Notify the STUN transaction about the arrival of STUN response. If the STUN response contains a final error (300 and greater), the transaction will be terminated and callback will be called. If the STUN response contains response code 100-299, retransmission will cease, but application must still call this function again with a final response later to allow the transaction to complete.

Parameters

tsx	The STUN client transaction instance.
msg	The incoming STUN message.
src_addr	The source address of the packet.
src_addr_len	The length of the source address.

Returns

PJ_SUCCESS on success or the appropriate error code.

pj_stun_client_tsx_retransmit()

pj_status_t pj_stun_client_tsx_retransmit	(	pj_stun_client_tsx *	tsx,
		pj_bool_t	mod_count
	)

Request to retransmit the request. Normally application should not need to call this function since retransmission would be handled internally, but this functionality is needed by ICE.

Parameters

tsx	The STUN client transaction instance.
mod_count	Boolean flag to indicate whether transmission count needs to be incremented.

Returns

PJ_SUCCESS on success, or PJNATH_ESTUNDESTROYED when the user has destroyed the transaction in on_send_msg() callback, or any other error code as returned by on_send_msg() callback.

pj_stun_client_tsx_schedule_destroy()

pj_status_t pj_stun_client_tsx_schedule_destroy	(	pj_stun_client_tsx *	tsx,
		const pj_time_val *	delay
	)

Schedule timer to destroy the transaction after the transaction is complete. Application normally calls this function in the on_complete() callback. When this timer elapsed, the on_destroy() callback will be called.

This is convenient to let the STUN transaction absorbs any response for the previous request retransmissions. If application doesn't want this, it can destroy the transaction immediately by calling pj_stun_client_tsx_destroy().

Parameters

tsx	The STUN transaction.
delay	The delay interval before on_destroy() callback is called.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_stun_client_tsx_send_msg()

pj_status_t pj_stun_client_tsx_send_msg	(	pj_stun_client_tsx *	tsx,
		pj_bool_t	retransmit,
		void *	pkt,
		unsigned	pkt_len
	)

Start the STUN client transaction by sending STUN request using this transaction. If reliable transport such as TCP or TLS is used, the retransmit flag should be set to PJ_FALSE because reliablity will be assured by the transport layer.

Parameters

tsx	The STUN client transaction.
retransmit	Should this message be retransmitted by the STUN transaction.
pkt	The STUN packet to send.
pkt_len	Length of STUN packet.

Returns

PJ_SUCCESS on success, or PJNATH_ESTUNDESTROYED when the user has destroyed the transaction in on_send_msg() callback, or any other error code as returned by on_send_msg() callback.

pj_stun_client_tsx_set_data()

pj_status_t pj_stun_client_tsx_set_data	(	pj_stun_client_tsx *	tsx,
		void *	data
	)

Associate an arbitrary data with the STUN transaction. This data can be then retrieved later from the transaction, by using pj_stun_client_tsx_get_data() function.

Parameters

tsx	The STUN client transaction.
data	Application data to be associated with the STUN transaction.

Returns

PJ_SUCCESS on success.

pj_stun_client_tsx_stop()

pj_status_t pj_stun_client_tsx_stop

(

pj_stun_client_tsx *

tsx

)

Stop the client transaction.

Parameters

tsx	The STUN transaction.

Returns

PJ_SUCCESS on success or PJ_EINVAL if the parameter is NULL.