Client transport utilizing TURN relay. More...

Data Structures
struct	pj_turn_sock_cb

struct	pj_turn_sock_tls_cfg

struct	pj_turn_sock_cfg

Macros
#define	PJ_TURN_TLS_DEFAULT_PROTO

Typedefs
typedef struct pj_turn_sock	pj_turn_sock

Functions
void	pj_turn_sock_tls_cfg_default (pj_turn_sock_tls_cfg *tls_cfg)

void	pj_turn_sock_tls_cfg_dup (pj_pool_t pool, pj_turn_sock_tls_cfg dst, const pj_turn_sock_tls_cfg *src)

void	pj_turn_sock_tls_cfg_wipe_keys (pj_turn_sock_tls_cfg *tls_cfg)

void	pj_turn_sock_cfg_default (pj_turn_sock_cfg *cfg)

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, const pj_turn_sock_cfg setting, void user_data, pj_turn_sock **p_turn_sock)

void	pj_turn_sock_destroy (pj_turn_sock *turn_sock)

pj_status_t	pj_turn_sock_set_user_data (pj_turn_sock turn_sock, void user_data)

void *	pj_turn_sock_get_user_data (pj_turn_sock *turn_sock)

pj_grp_lock_t *	pj_turn_sock_get_grp_lock (pj_turn_sock *turn_sock)

pj_status_t	pj_turn_sock_get_info (pj_turn_sock turn_sock, pj_turn_session_info info)

pj_status_t	pj_turn_sock_lock (pj_turn_sock *turn_sock)

pj_status_t	pj_turn_sock_unlock (pj_turn_sock *turn_sock)

void	pj_turn_sock_set_log (pj_turn_sock *turn_sock, unsigned flags)

pj_status_t	pj_turn_sock_set_software_name (pj_turn_sock turn_sock, const pj_str_t sw)

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)

pj_status_t	pj_turn_sock_set_perm (pj_turn_sock *turn_sock, unsigned addr_cnt, const pj_sockaddr addr[], unsigned options)

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)

pj_status_t	pj_turn_sock_bind_channel (pj_turn_sock turn_sock, const pj_sockaddr_t peer, unsigned addr_len)

pj_status_t	pj_turn_sock_connect (pj_turn_sock turn_sock, const pj_sockaddr_t peer, unsigned addr_len)

pj_status_t	pj_turn_sock_disconnect (pj_turn_sock turn_sock, const pj_sockaddr_t peer, unsigned addr_len)

Detailed Description

This is a ready to use object for relaying application data via a TURN server, by managing all the operations in Overview of TURN operations.

Using TURN transport

This object provides a thin wrapper to the TURN client session, hence the API is very much the same (apart from the obvious difference in the names). Please see TURN client session for the documentation on how to use the session.

Samples

The pjturn-client, a sample TURN client is a sample application to use the TURN client transport.

Also see PJNATH Samples and screenshots for other samples.

Macro Definition Documentation

◆ PJ_TURN_TLS_DEFAULT_PROTO

#define PJ_TURN_TLS_DEFAULT_PROTO

Value:

                                       (PJ_SSL_SOCK_PROTO_TLS1 | \
                                       PJ_SSL_SOCK_PROTO_TLS1_1 | \
                                       PJ_SSL_SOCK_PROTO_TLS1_2)

The default enabled SSL proto to be used. Default is all protocol above TLSv1 (TLSv1 & TLS v1.1 & TLS v1.2).

Typedef Documentation

◆ pj_turn_sock

typedef struct pj_turn_sock pj_turn_sock

Opaque declaration for TURN client.

Function Documentation

◆ pj_turn_sock_alloc()

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_turn_sock_bind_channel()

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_turn_sock_cfg_default()

void pj_turn_sock_cfg_default ( pj_turn_sock_cfg * cfg )

Initialize pj_turn_sock_cfg structure with default values.

◆ pj_turn_sock_connect()

pj_status_t pj_turn_sock_connect	(	pj_turn_sock *	turn_sock,
		const pj_sockaddr_t *	peer,
		unsigned	addr_len
	)

Initiate connection to the specified peer using Connect request. Application must call this function when it uses RFC 6062 (TURN TCP allocations) to initiate a data connection to a peer. The connection status will be notified via on_connection_status callback.

According to RFC 6062, the TURN transport instance must be created with connection type are set to PJ_TURN_TP_TCP, application must send TCP Allocate request (with pj_turn_session_alloc(), set TURN allocation parameter peer_conn_type to PJ_TURN_TP_TCP) before calling this function.

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_turn_sock_create()

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,
		const pj_turn_sock_cfg *	setting,
		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.
setting	Optional settings to be specified to the transport. If this parameter is NULL, default values will be used.
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.

◆ pj_turn_sock_destroy()

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_turn_sock_disconnect()

pj_status_t pj_turn_sock_disconnect	(	pj_turn_sock *	turn_sock,
		const pj_sockaddr_t *	peer,
		unsigned	addr_len
	)

Close previous TCP data connection for the specified peer. According to RFC 6062, when the client wishes to terminate its relayed connection to the peer, it closes the data connection to the server.

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.

References PJ_END_DECL.

◆ pj_turn_sock_get_grp_lock()

pj_grp_lock_t * pj_turn_sock_get_grp_lock ( pj_turn_sock * turn_sock )

Get the group lock for this TURN transport.

Parameters

turn_sock The TURN transport instance.

Returns: The group lock.

◆ pj_turn_sock_get_info()

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.

◆ pj_turn_sock_get_user_data()

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_turn_sock_lock()

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_turn_sock_sendto()

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 data has been sent immediately, or PJ_EPENDING if data cannot be sent immediately. In this case the on_data_sent() callback will be called when data is actually sent. Any other return value indicates error condition.

◆ pj_turn_sock_set_log()

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_turn_sock_set_perm()

pj_status_t pj_turn_sock_set_perm	(	pj_turn_sock *	turn_sock,
		unsigned	addr_cnt,
		const pj_sockaddr	addr[],
		unsigned	options
	)

Create or renew permission in the TURN server for the specified peer IP addresses. Application must install permission for a particular (peer) IP address before it sends any data to that IP address, or otherwise the TURN server will drop the data.

Parameters

turn_sock	The TURN transport instance.
addr_cnt	Number of IP addresses.
addr	Array of peer IP addresses. Only the address family and IP address portion of the socket address matter.
options	Specify 1 to let the TURN client session automatically renew the permission later when they are about to expire.

Returns: PJ_SUCCESS if the operation has been successfully issued, or the appropriate error code. Note that the operation itself will complete asynchronously.

◆ pj_turn_sock_set_software_name()

pj_status_t pj_turn_sock_set_software_name	(	pj_turn_sock *	turn_sock,
		const pj_str_t *	sw
	)

Configure the SOFTWARE name to be sent in all STUN requests by the TURN session.

Parameters

turn_sock	The TURN transport instance.
sw	Software name string. If this argument is NULL or empty, the session will not include SOFTWARE attribute in STUN requests and responses.

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

◆ pj_turn_sock_set_user_data()

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_turn_sock_tls_cfg_default()

void pj_turn_sock_tls_cfg_default ( pj_turn_sock_tls_cfg * tls_cfg )

Initialize TLS setting with default values.

Parameters

tls_cfg The TLS setting to be initialized.

◆ pj_turn_sock_tls_cfg_dup()

void pj_turn_sock_tls_cfg_dup	(	pj_pool_t *	pool,
		pj_turn_sock_tls_cfg *	dst,
		const pj_turn_sock_tls_cfg *	src
	)

Duplicate TLS setting.

Parameters

pool	The pool to duplicate strings etc.
dst	Destination structure.
src	Source structure.

◆ pj_turn_sock_tls_cfg_wipe_keys()

void pj_turn_sock_tls_cfg_wipe_keys ( pj_turn_sock_tls_cfg * tls_cfg )

Wipe out certificates and keys in the TLS setting.

Parameters

tls_cfg The TLS setting.

◆ pj_turn_sock_unlock()

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.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Using TURN transport

Samples

Macro Definition Documentation

◆ PJ_TURN_TLS_DEFAULT_PROTO

Typedef Documentation

◆ pj_turn_sock

Function Documentation

◆ pj_turn_sock_alloc()

◆ pj_turn_sock_bind_channel()

◆ pj_turn_sock_cfg_default()

◆ pj_turn_sock_connect()

◆ pj_turn_sock_create()

◆ pj_turn_sock_destroy()

◆ pj_turn_sock_disconnect()

◆ pj_turn_sock_get_grp_lock()

◆ pj_turn_sock_get_info()

◆ pj_turn_sock_get_user_data()

◆ pj_turn_sock_lock()

◆ pj_turn_sock_sendto()

◆ pj_turn_sock_set_log()

◆ pj_turn_sock_set_perm()

◆ pj_turn_sock_set_software_name()

◆ pj_turn_sock_set_user_data()

◆ pj_turn_sock_tls_cfg_default()

◆ pj_turn_sock_tls_cfg_dup()

◆ pj_turn_sock_tls_cfg_wipe_keys()

◆ pj_turn_sock_unlock()