STUN Client/Server Session
[STUN Library]

Detailed Description

Typedef Documentation

typedef struct pj_stun_rx_data pj_stun_rx_data

Forward declaration for pj_stun_rx_data

typedef struct pj_stun_session pj_stun_session

Forward declaration for pj_stun_session

typedef struct pj_stun_tx_data pj_stun_tx_data

Forward declaration for pj_stun_tx_data

Enumeration Type Documentation

enum pj_stun_sess_msg_log_flag

These are the flags to control the message logging in the STUN session.

Enumerator:

PJ_STUN_SESS_LOG_TX_REQ	Log outgoing STUN requests.
PJ_STUN_SESS_LOG_TX_RES	Log outgoing STUN responses.
PJ_STUN_SESS_LOG_TX_IND	Log outgoing STUN indications.
PJ_STUN_SESS_LOG_RX_REQ	Log incoming STUN requests.
PJ_STUN_SESS_LOG_RX_RES	Log incoming STUN responses
PJ_STUN_SESS_LOG_RX_IND	Log incoming STUN indications

Function Documentation

void pj_stun_msg_destroy_tdata	(	pj_stun_session *	sess,
		pj_stun_tx_data *	tdata
	)

Destroy the transmit data. Call this function only when tdata has been created but application doesn't want to send the message (perhaps because of other error).

Parameters:

	sess	The STUN session.
	tdata	The transmit data.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_cancel_req	(	pj_stun_session *	sess,
		pj_stun_tx_data *	tdata,
		pj_bool_t	notify,
		pj_status_t	status
	)

Cancel outgoing STUN transaction. This operation is only valid for outgoing STUN request, to cease retransmission of the request and destroy the STUN client transaction that is used to send the request.

Parameters:

	sess	The STUN session instance.
	tdata	The request message previously sent.
	notify	Specify whether on_request_complete() callback should be called.
	status	If on_request_complete() callback is to be called, specify the error status to be given when calling the callback. This error status MUST NOT be PJ_SUCCESS.

Returns:: PJ_SUCCESS if transaction is successfully cancelled. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in on_request_complete() callback.

pj_status_t pj_stun_session_create	(	pj_stun_config *	cfg,
		const char *	name,
		const pj_stun_session_cb *	cb,
		pj_bool_t	fingerprint,
		pj_stun_session **	p_sess
	)

Create a STUN session.

Parameters:

	cfg	The STUN endpoint, to be used to register timers etc.
	name	Optional name to be associated with this instance. The name will be used for example for logging purpose.
	cb	Session callback.
	fingerprint	Enable message fingerprint for outgoing messages.
	p_sess	Pointer to receive STUN session instance.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_create_ind	(	pj_stun_session *	sess,
		int	msg_type,
		pj_stun_tx_data **	p_tdata
	)

Create a STUN Indication message. After the message has been successfully created, application can send the message by calling pj_stun_session_send_msg().

Parameters:

	sess	The STUN session instance.
	msg_type	The STUN request message type, from pj_stun_method_e or from pj_stun_msg_type. This function will add the indication bit as necessary.
	p_tdata	Pointer to receive STUN transmit data instance containing the message.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_create_req	(	pj_stun_session *	sess,
		int	msg_type,
		pj_uint32_t	magic,
		const pj_uint8_t	tsx_id[12],
		pj_stun_tx_data **	p_tdata
	)

Create a STUN request message. After the message has been successfully created, application can send the message by calling pj_stun_session_send_msg().

Parameters:

	sess	The STUN session instance.
	msg_type	The STUN request message type, from pj_stun_method_e or from pj_stun_msg_type.
	magic	STUN magic, use PJ_STUN_MAGIC.
	tsx_id	Optional transaction ID.
	p_tdata	Pointer to receive STUN transmit data instance containing the request.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_create_res	(	pj_stun_session *	sess,
		const pj_stun_rx_data *	rdata,
		unsigned	err_code,
		const pj_str_t *	err_msg,
		pj_stun_tx_data **	p_tdata
	)

Create a STUN response message. After the message has been successfully created, application can send the message by calling pj_stun_session_send_msg(). Alternatively application may use pj_stun_session_respond() to create and send response in one function call.

Parameters:

	sess	The STUN session instance.
	rdata	The STUN request where the response is to be created.
	err_code	Error code to be set in the response, if error response is to be created, according to pj_stun_status enumeration. This argument MUST be zero if successful response is to be created.
	err_msg	Optional pointer for the error message string, when creating error response. If the value is NULL and the err_code is non-zero, then default error message will be used.
	p_tdata	Pointer to receive the response message created.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_destroy ( pj_stun_session * sess )

Destroy the STUN session and all objects created in the context of this session.

Parameters:

sess

The STUN session instance.

Returns:: PJ_SUCCESS on success, or the appropriate error code. This function will return PJ_EPENDING if the operation cannot be performed immediately because callbacks are being called; in this case the session will be destroyed as soon as the last callback returns.

void* pj_stun_session_get_user_data ( pj_stun_session * sess )

Retrieve the user data previously associated to this STUN session with pj_stun_session_set_user_data().

Parameters:

sess

The STUN session instance.

Returns:: The user data associated with this STUN session.

pj_status_t pj_stun_session_on_rx_pkt	(	pj_stun_session *	sess,
		const void *	packet,
		pj_size_t	pkt_size,
		unsigned	options,
		void *	token,
		unsigned *	parsed_len,
		const pj_sockaddr_t *	src_addr,
		unsigned	src_addr_len
	)

Application must call this function to notify the STUN session about the arrival of STUN packet. The STUN packet MUST have been checked first with pj_stun_msg_check() to verify that this is indeed a valid STUN packet.

The STUN session will decode the packet into pj_stun_msg, and process the message accordingly. If the message is a response, it will search through the outstanding STUN client transactions for a matching transaction ID and hand over the response to the transaction.

On successful message processing, application will be notified about the message via one of the pj_stun_session_cb callback.

Parameters:

	sess	The STUN session instance.
	packet	The packet containing STUN message.
	pkt_size	Size of the packet.
	options	Options, from pj_stun_decode_options.
	parsed_len	Optional pointer to receive the size of the parsed STUN message (useful if packet is received via a stream oriented protocol).
	token	Optional token which will be given back to application in the on_rx_request(), on_rx_indication() and on_send_msg() callbacks. The token can be used to associate processing or incoming request or indication with some context.
	src_addr	The source address of the packet, which will also be given back to application callbacks, along with source address length.
	src_addr_len	Length of the source address.

Returns:: PJ_SUCCESS on success, or the appropriate error code. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in one of the callback.

pj_status_t pj_stun_session_respond	(	pj_stun_session *	sess,
		const pj_stun_rx_data *	rdata,
		unsigned	code,
		const char *	err_msg,
		void *	token,
		pj_bool_t	cache,
		const pj_sockaddr_t *	dst_addr,
		unsigned	addr_len
	)

This is a utility function to create and send response for an incoming STUN request. Internally this function calls pj_stun_session_create_res() and pj_stun_session_send_msg(). It is provided here as a matter of convenience.

Parameters:

	sess	The STUN session instance.
	rdata	The STUN request message to be responded.
	code	Error code to be set in the response, if error response is to be created, according to pj_stun_status enumeration. This argument MUST be zero if successful response is to be created.
	err_msg	Optional pointer for the error message string, when creating error response. If the value is NULL and the err_code is non-zero, then default error message will be used.
	token	Optional token which will be given back to application in on_send_msg() callback and on_request_complete() callback, if the message is a STUN request message. Internally this function will put the token in the token field of pj_stun_tx_data, hence it will overwrite any value that the application puts there.
	cache	Specify whether session should cache this response for future request retransmission. If TRUE, subsequent request retransmission will be handled by the session and it will not call request callback.
	dst_addr	Destination address of the response (or equal to the source address of the original request).
	addr_len	Address length.

Returns:: PJ_SUCCESS on success, or the appropriate error code. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in on_send_msg() callback.

pj_status_t pj_stun_session_retransmit_req	(	pj_stun_session *	sess,
		pj_stun_tx_data *	tdata
	)

Explicitly request retransmission of the request. Normally application doesn't need to do this, but this functionality is needed by ICE to speed up connectivity check completion.

Parameters:

	sess	The STUN session instance.
	tdata	The request message previously sent.

Returns:: PJ_SUCCESS on success, or the appropriate error. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in on_send_msg() callback.

pj_status_t pj_stun_session_send_msg	(	pj_stun_session *	sess,
		void *	token,
		pj_bool_t	cache_res,
		pj_bool_t	retransmit,
		const pj_sockaddr_t *	dst_addr,
		unsigned	addr_len,
		pj_stun_tx_data *	tdata
	)

Send STUN message to the specified destination. This function will encode the pj_stun_msg instance to a packet buffer, and add credential or fingerprint if necessary. If the message is a request, the session will also create and manage a STUN client transaction to be used to manage the retransmission of the request. After the message has been encoded and transaction is setup, the on_send_msg() callback of pj_stun_session_cb (which is registered when the STUN session is created) will be called to actually send the message to the wire.

Parameters:

	sess	The STUN session instance.
	token	Optional token which will be given back to application in on_send_msg() callback and on_request_complete() callback, if the message is a STUN request message. Internally this function will put the token in the token field of pj_stun_tx_data, hence it will overwrite any value that the application puts there.
	cache_res	If the message is a response message for an incoming request, specify PJ_TRUE to instruct the STUN session to cache this response for subsequent incoming request retransmission. Otherwise this parameter will be ignored for non-response message.
	retransmit	If the message is a request message, specify whether the request should be retransmitted. Normally application will specify TRUE if the underlying transport is UDP and FALSE if the underlying transport is TCP or TLS.
	dst_addr	The destination socket address.
	addr_len	Length of destination address.
	tdata	The STUN transmit data containing the STUN message to be sent.

Returns:: PJ_SUCCESS on success, or the appropriate error code. This function will return PJNATH_ESTUNDESTROYED if application has destroyed the session in on_send_msg() callback.

pj_status_t pj_stun_session_set_credential	(	pj_stun_session *	sess,
		pj_stun_auth_type	auth_type,
		const pj_stun_auth_cred *	cred
	)

Set credential to be used by this session. Once credential is set, all outgoing messages will include MESSAGE-INTEGRITY, and all incoming message will be authenticated against this credential.

To disable authentication after it has been set, call this function again with NULL as the argument.

Parameters:

	sess	The STUN session instance.
	auth_type	Type of authentication.
	cred	The credential to be used by this session. If NULL is specified, authentication will be disabled.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_stun_session_set_lock	(	pj_stun_session *	sess,
		pj_lock_t *	lock,
		pj_bool_t	auto_del
	)

Change the lock object used by the STUN session. By default, the STUN session uses a mutex to protect its internal data. If application already protects access to STUN session with higher layer lock, it may disable the mutex protection in the STUN session by changing the STUN session lock to a NULL mutex.

Parameters:

	sess	The STUN session instance.
	lock	New lock instance to be used by the STUN session.
	auto_del	Specify whether STUN session should destroy this lock instance when it's destroyed.

void pj_stun_session_set_log	(	pj_stun_session *	sess,
		unsigned	flags
	)

Configure message logging. By default all flags are enabled.

Parameters:

	sess	The STUN session instance.
	flags	Bitmask combination of pj_stun_sess_msg_log_flag

pj_status_t pj_stun_session_set_server_name	(	pj_stun_session *	sess,
		const pj_str_t *	srv_name
	)

Set server name to be included in all response.

Parameters:

	sess	The STUN session instance.
	srv_name	Server name string.

Returns:: The user data associated with this STUN session.

pj_status_t pj_stun_session_set_user_data	(	pj_stun_session *	sess,
		void *	user_data
	)

Associated an arbitrary data with this STUN session. The user data may be retrieved later with pj_stun_session_get_user_data() function.

Parameters:

	sess	The STUN session instance.
	user_data	The user data.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

STUN Client/Server Session [STUN Library]

Detailed Description

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation

STUN Client/Server Session
[STUN Library]