Transport independent TURN client session
[TURN Client Library]

Detailed Description

This module describes the transport independent TURN client session. This interface is provided for implementors of a TURN client transport, and application usually will want to use TURN client transport instead.

The transport independent TURN client session is created to facilitate the creation of different types of transports between the client and the TURN server.

Typedef Documentation

typedef struct pj_turn_session pj_turn_session

Opaque declaration for TURN client session.

Enumeration Type Documentation

enum pj_turn_state_t

TURN session state

Enumerator:

PJ_TURN_STATE_NULL	TURN session has just been created.
PJ_TURN_STATE_RESOLVING	TURN server has been configured and now is being resolved via DNS SRV resolution.
PJ_TURN_STATE_RESOLVED	TURN server has been resolved. If there is pending allocation to be done, it will be invoked immediately.
PJ_TURN_STATE_ALLOCATING	TURN session has issued ALLOCATE request and is waiting for response from the TURN server.
PJ_TURN_STATE_READY	TURN session has successfully allocated relay resoruce and now is ready to be used.
PJ_TURN_STATE_DEALLOCATING	TURN session has issued deallocate request and is waiting for a response from the TURN server.
PJ_TURN_STATE_DEALLOCATED	Deallocate response has been received. Normally the session will proceed to DESTROYING state immediately.
PJ_TURN_STATE_DESTROYING	TURN session is being destroyed.

enum pj_turn_tp_type

TURN transport types, which will be used both to specify the connection type for reaching TURN server and the type of allocation transport to be requested to server (the REQUESTED-TRANSPORT attribute).

Enumerator:

PJ_TURN_TP_UDP	UDP transport, which value corresponds to IANA protocol number.
PJ_TURN_TP_TCP	TCP transport, which value corresponds to IANA protocol number.
PJ_TURN_TP_TLS	TLS transport. The TLS transport will only be used as the connection type to reach the server and never as the allocation transport type.

Function Documentation

void pj_turn_alloc_param_copy	(	pj_pool_t *	pool,
		pj_turn_alloc_param *	dst,
		const pj_turn_alloc_param *	src
	)

Duplicate pj_turn_alloc_param.

Parameters:

	pool	Pool to allocate memory (currently not used)
	dst	Destination parameter.
	src	Source parameter.

void pj_turn_alloc_param_default ( pj_turn_alloc_param * prm )

Initialize pj_turn_alloc_param with the default values.

Parameters:

prm

The TURN allocation parameter to be initialized.

pj_status_t pj_turn_session_alloc	(	pj_turn_session *	sess,
		const pj_turn_alloc_param *	param
	)

Allocate a relay address/resource in the TURN server by sending TURN Allocate request. Application must first initiate the server resolution process with pj_turn_session_set_server() and set the credential to be used with pj_turn_session_set_credential() before calling this function.

This function will complete asynchronously, and the application will be notified about the allocation result in on_state() callback. The TURN session state will move to PJ_TURN_STATE_READY if allocation is successful, and PJ_TURN_STATE_DEALLOCATING or greater state if allocation has failed.

Once allocation has been successful, the TURN session will keep this allocation alive until the session is destroyed, by sending periodic allocation refresh to the TURN server.

Parameters:

	sess	The TURN client session.
	param	Optional TURN allocation parameter.

Returns:: PJ_SUCCESS if the operation has been successfully initiated or the appropriate error code on failure.

pj_status_t pj_turn_session_bind_channel	(	pj_turn_session *	sess,
		const pj_sockaddr_t *	peer,
		unsigned	addr_len
	)

Optionally establish channel binding for the specified a peer address. This function will assign a unique channel number for the peer address and request channel binding to the TURN server for this address. When a channel has been bound to a peer, the TURN client and TURN server will exchange data using ChannelData encapsulation format, which has lower bandwidth overhead than Send Indication (the default format used when peer address is not bound to a channel).

This function will complete asynchronously, and application will be notified about the result in on_channel_bound() callback.

Parameters:

	sess	The TURN client session.
	peer	The remote peer address.
	addr_len	Length of the address.

Returns:: PJ_SUCCESS if the operation has been successfully initiated, or the appropriate error code on failure.

pj_status_t pj_turn_session_create	(	const pj_stun_config *	cfg,
		const char *	name,
		int	af,
		pj_turn_tp_type	conn_type,
		const pj_turn_session_cb *	cb,
		unsigned	options,
		void *	user_data,
		pj_turn_session **	p_sess
	)

Create a TURN session instance with the specified address family and connection type. Once TURN session instance is created, application must call pj_turn_session_alloc() to allocate a relay address in the TURN server.

Parameters:

	cfg	The STUN configuration which contains among other things the ioqueue and timer heap instance for the operation of this session.
	name	Optional name to identify this session in the log.
	af	Address family of the client connection. Currently pj_AF_INET() and pj_AF_INET6() are supported.
	conn_type	Connection type to the TURN server.
	cb	Callback to receive events from the TURN session.
	options	Option flags, currently this value must be zero.
	user_data	Arbitrary application data to be associated with this transport.
	p_sess	Pointer to receive the created instance of the TURN session.

Returns:: PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_turn_session_destroy ( pj_turn_session * sess )

Forcefully destroy the TURN session. This will destroy the session immediately. If there is an active allocation, the server will not be notified about the client destruction.

Parameters:

sess

The TURN client session.

Returns:: PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_turn_session_get_info	(	pj_turn_session *	sess,
		pj_turn_session_info *	info
	)

Get the information about this TURN session and the allocation, if any.

Parameters:

	sess	The TURN client session.
	info	The structure to be initialized with the TURN session info.

Returns:: PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

void* pj_turn_session_get_user_data ( pj_turn_session * sess )

Retrieve the previously assigned user data associated with this TURN session.

Parameters:

sess

The TURN client session.

Returns:: The user/application data.

pj_status_t pj_turn_session_on_rx_pkt	(	pj_turn_session *	sess,
		void *	pkt,
		unsigned	pkt_len
	)

Notify TURN client session upon receiving a packet from server. Since the TURN session is transport independent, it does not read packet from any sockets, and rather relies on application giving it packets that are received from the TURN server. The session then processes this packet and decides whether it is part of TURN protocol exchange or if it is a data to be reported back to user, which in this case it will call the on_rx_data() callback.

Parameters:

	sess	The TURN client session.
	pkt	The packet as received from the TURN server. This should contain either STUN encapsulated message or a ChannelData packet.
	pkt_len	The length of the packet.

Returns:: The function may return non-PJ_SUCCESS if it receives non-STUN and non-ChannelData packet, or if the on_rx_data() returns non-PJ_SUCCESS;

pj_status_t pj_turn_session_sendto	(	pj_turn_session *	sess,
		const pj_uint8_t *	pkt,
		unsigned	pkt_len,
		const pj_sockaddr_t *	peer_addr,
		unsigned	addr_len
	)

Send a data to the specified peer address via the TURN relay. This function will encapsulate the data as STUN Send Indication or TURN ChannelData packet and send the message to the TURN server. The TURN server then will send the data to the peer.

The allocation (pj_turn_session_alloc()) must have been successfully created before application can relay any data.

Since TURN session is transport independent, this function will ultimately call on_send_pkt() callback to request the application to actually send the packet containing the data to the TURN server.

Parameters:

	sess	The TURN client session.
	pkt	The data/packet to be sent to peer.
	pkt_len	Length of the data.
	peer_addr	The remote peer address (the ultimate destination of the data, and not the TURN server address).
	addr_len	Length of the address.

Returns:: PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_turn_session_set_credential	(	pj_turn_session *	sess,
		const pj_stun_auth_cred *	cred
	)

Set credential to be used to authenticate against TURN server. Application must call this function before sending Allocate request with pj_turn_session_alloc().

Parameters:

	sess	The TURN client session
	cred	STUN credential to be used.

Returns:: PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

void pj_turn_session_set_log	(	pj_turn_session *	sess,
		unsigned	flags
	)

Configure message logging. By default all flags are enabled.

Parameters:

	sess	The TURN client session.
	flags	Bitmask combination of pj_stun_sess_msg_log_flag

pj_status_t pj_turn_session_set_server	(	pj_turn_session *	sess,
		const pj_str_t *	domain,
		int	default_port,
		pj_dns_resolver *	resolver
	)

Set the server or domain name of the server. Before the application can send Allocate request (with pj_turn_session_alloc()), it must first resolve the server address(es) using this function. This function will resolve the TURN server using DNS SRV resolution if the resolver is set. The server resolution process will complete asynchronously, and application will be notified in on_state() callback with the session state set to PJ_TURN_STATE_RESOLVED.

Application may call with pj_turn_session_alloc() before the server resolution completes. In this case, the operation will be queued by the session, and it will be sent once the server resolution completes.

Parameters:

	sess	The TURN client session.
	domain	The domain, hostname, or IP address of the TURN server. When this parameter contains domain name, the resolver parameter must be set to activate DNS SRV resolution.
	default_port	The default TURN port number to use when DNS SRV resolution is not used. If DNS SRV resolution is used, the server port number will be set from the DNS SRV records.
	resolver	If this parameter is not NULL, then the domain parameter will be first resolved with DNS SRV and then fallback to using DNS A/AAAA resolution when DNS SRV resolution fails. If this parameter is NULL, the domain parameter will be resolved as hostname.

Returns:: PJ_SUCCESS if the operation has been successfully queued, or the appropriate error code on failure. When this function returns PJ_SUCCESS, the final result of the resolution process will be notified to application in on_state() callback.

pj_status_t pj_turn_session_set_user_data	(	pj_turn_session *	sess,
		void *	user_data
	)

Associate a user data with this TURN session. The user data may then be retrieved later with pj_turn_session_get_user_data().

Parameters:

	sess	The TURN client session.
	user_data	Arbitrary data.

Returns:: PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_status_t pj_turn_session_shutdown ( pj_turn_session * sess )

Shutdown TURN client session. This will gracefully deallocate and destroy the client session.

Parameters:

sess

The TURN client session.

Returns:: PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

const char* pj_turn_state_name ( pj_turn_state_t state )

Get string representation for the given TURN state.

Parameters:

state

The TURN session state.

Returns:: The state name as NULL terminated string.

Transport independent TURN client session [TURN Client Library]

Detailed Description

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Transport independent TURN client session
[TURN Client Library]