Home --> Documentations --> PJNATH Reference

Client transport utilizing TURN relay. More...

Data Structures

struct  pj_turn_sock_cb
 
struct  pj_turn_sock_cfg
 

Typedefs

typedef struct pj_turn_sock pj_turn_sock
 

Functions

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_tpj_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)
 

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.

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_sockThe TURN transport instance.
domainThe 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_portThe 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.
resolverIf 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.
credThe STUN credential to be used for the TURN server.
paramOptional 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_sockThe TURN transport instance.
peerThe remote peer address.
addr_lenLength of the address.
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
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
cfgThe STUN configuration which contains among other things the ioqueue and timer heap instance for the operation of this transport.
afAddress family of the client connection. Currently pj_AF_INET() and pj_AF_INET6() are supported.
conn_typeConnection type to the TURN server. Both TCP and UDP are supported.
cbCallback to receive events from the TURN transport.
settingOptional settings to be specified to the transport. If this parameter is NULL, default values will be used.
user_dataArbitrary application data to be associated with this transport.
p_turn_sockPointer 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_sockThe TURN transport instance.
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_sockThe TURN transport instance.
Returns
The group lock.
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_sockThe TURN transport instance.
infoPointer 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_sockThe 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_sockThe 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_sockThe TURN transport instance.
pktThe data/packet to be sent to peer.
pkt_lenLength of the data.
peer_addrThe remote peer address (the ultimate destination of the data, and not the TURN server address).
addr_lenLength 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_sockThe TURN transport instance.
flagsBitmask combination of pj_stun_sess_msg_log_flag
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_sockThe TURN transport instance.
addr_cntNumber of IP addresses.
addrArray of peer IP addresses. Only the address family and IP address portion of the socket address matter.
optionsSpecify 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_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_sockThe TURN transport instance.
swSoftware 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_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_sockThe TURN transport instance.
user_dataArbitrary 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_sockThe TURN transport instance.
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

 


PJNATH - Open Source NAT traversal helper library supporting STUN, TURN, and ICE
Copyright (C) 2006-2009 Teluu Inc.