TURN client transport
[TURN Client Library]

Detailed Description

The TURN relay client transport can be used to relay data from the client to peer via a TURN relay. The application establishes TURN connection to the TURN server using UDP or TCP as the transport, then creates a relay address in the TURN server to be advertised to remote peer(s) as the transport address. When application sends data to a remote address via this transport, the data will be sent via the TURN relay, and vice versa.

Typedef Documentation

typedef struct pj_turn_sock pj_turn_sock

Opaque declaration for TURN client.

Function Documentation

pj_status_t pj_turn_sock_alloc	(	pj_turn_sock *	turn_sock,
		const pj_str_t *	domain,
		int	default_port,
		pj_dns_resolver *	resolver,
		const pj_stun_auth_cred *	cred,
		const pj_turn_alloc_param *	param
	)

Allocate a relay address/resource in the TURN server. This function will resolve the TURN server using DNS SRV (if desired) and send TURN Allocate request using the specified credential to allocate a relay address in the server. This function completes asynchronously, and application will be notified when the allocation process has been successful in the on_state() callback when the state is set to PJ_TURN_STATE_READY. If the allocation fails, the state will be set to PJ_TURN_STATE_DEALLOCATING or greater.

Parameters:

	turn_sock	The TURN transport instance.
	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.
	cred	The STUN credential to be used for the TURN server.
	param	Optional TURN allocation parameter.

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 allocation process will be notified to application in on_state() callback.

pj_status_t pj_turn_sock_bind_channel	(	pj_turn_sock *	turn_sock,
		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 transport 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).

Parameters:

	turn_sock	The TURN transport instance.
	peer	The remote peer 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_sock_create	(	pj_stun_config *	cfg,
		int	af,
		pj_turn_tp_type	conn_type,
		const pj_turn_sock_cb *	cb,
		unsigned	options,
		void *	user_data,
		pj_turn_sock **	p_turn_sock
	)

Create a TURN transport instance with the specified address family and connection type. Once TURN transport instance is created, application must call pj_turn_sock_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 transport.
	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. Both TCP and UDP are supported.
	cb	Callback to receive events from the TURN transport.
	options	Option flags, currently this value must be zero.
	user_data	Arbitrary application data to be associated with this transport.
	p_turn_sock	Pointer to receive the created instance of the TURN transport.

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

void pj_turn_sock_destroy ( pj_turn_sock * turn_sock )

Destroy the TURN transport instance. This will gracefully close the connection between the client and the TURN server. Although this function will return immediately, the TURN socket deletion may continue in the background and the application may still get state changes notifications from this transport.

Parameters:

turn_sock

The TURN transport instance.

pj_status_t pj_turn_sock_get_info	(	pj_turn_sock *	turn_sock,
		pj_turn_session_info *	info
	)

Get the TURN transport info. The transport info contains, among other things, the allocated relay address.

Parameters:

	turn_sock	The TURN transport instance.
	info	Pointer to be filled with TURN transport info.

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

void* pj_turn_sock_get_user_data ( pj_turn_sock * turn_sock )

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

Parameters:

turn_sock

The TURN transport instance.

Returns:: The user/application data.

pj_status_t pj_turn_sock_lock ( pj_turn_sock * turn_sock )

Acquire the internal mutex of the TURN transport. Application may need to call this function to synchronize access to other objects alongside the TURN transport, to avoid deadlock.

Parameters:

turn_sock

The TURN transport instance.

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

pj_status_t pj_turn_sock_sendto	(	pj_turn_sock *	turn_sock,
		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_sock_alloc()) must have been successfully created before application can relay any data.

Parameters:

	turn_sock	The TURN transport instance.
	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.

void pj_turn_sock_set_log	(	pj_turn_sock *	turn_sock,
		unsigned	flags
	)

Set STUN message logging for this TURN session. See pj_stun_session_set_log().

Parameters:

	turn_sock	The TURN transport instance.
	flags	Bitmask combination of pj_stun_sess_msg_log_flag

pj_status_t pj_turn_sock_set_user_data	(	pj_turn_sock *	turn_sock,
		void *	user_data
	)

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

Parameters:

	turn_sock	The TURN transport instance.
	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_sock_unlock ( pj_turn_sock * turn_sock )

Release the internal mutex previously held with pj_turn_sock_lock().

Parameters:

turn_sock

The TURN transport instance.

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

TURN client transport [TURN Client Library]

Detailed Description

Data Structures

Typedefs

Functions

Typedef Documentation

Function Documentation

TURN client transport
[TURN Client Library]