Group PJNATH_TURN_SOCK¶

group PJNATH_TURN_SOCK

Client transport utilizing TURN relay.

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.

Typedefs

typedef struct pj_turn_sock pj_turn_sock¶: Opaque declaration for TURN client.

Functions

void pj_turn_sock_cfg_default(pj_turn_sock_cfg *cfg)¶: Initialize pj_turn_sock_cfg structure with default values.

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.

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_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.

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_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_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_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.

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_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_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_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_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.

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.

struct pj_turn_sock_cb¶: #include <turn_sock.h>
This structure contains callbacks that will be called by the TURN transport.

struct pj_turn_sock_cfg¶: #include <turn_sock.h>
This structure describes options that can be specified when creating the TURN socket. Application should call pj_turn_sock_cfg_default() to initialize this structure with its default values before using it.