BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJNATH Reference

STUN aware UDP socket transport. More...

Data Structures

struct  pj_stun_sock_cb
 
struct  pj_stun_sock_info
 
struct  pj_stun_sock_cfg
 

Typedefs

typedef struct pj_stun_sock pj_stun_sock
 

Enumerations

enum  pj_stun_sock_op {
  PJ_STUN_SOCK_DNS_OP = 1,
  PJ_STUN_SOCK_BINDING_OP,
  PJ_STUN_SOCK_KEEP_ALIVE_OP,
  PJ_STUN_SOCK_MAPPED_ADDR_CHANGE
}
 

Functions

const char * pj_stun_sock_op_name (pj_stun_sock_op op)
 
void pj_stun_sock_cfg_default (pj_stun_sock_cfg *cfg)
 
pj_status_t pj_stun_sock_create (pj_stun_config *stun_cfg, const char *name, int af, const pj_stun_sock_cb *cb, const pj_stun_sock_cfg *cfg, void *user_data, pj_stun_sock **p_sock)
 
pj_status_t pj_stun_sock_start (pj_stun_sock *stun_sock, const pj_str_t *domain, pj_uint16_t default_port, pj_dns_resolver *resolver)
 
pj_status_t pj_stun_sock_destroy (pj_stun_sock *sock)
 
pj_status_t pj_stun_sock_set_user_data (pj_stun_sock *stun_sock, void *user_data)
 
void * pj_stun_sock_get_user_data (pj_stun_sock *stun_sock)
 
pj_grp_lock_tpj_stun_sock_get_grp_lock (pj_stun_sock *stun_sock)
 
pj_status_t pj_stun_sock_get_info (pj_stun_sock *stun_sock, pj_stun_sock_info *info)
 
pj_status_t pj_stun_sock_sendto (pj_stun_sock *stun_sock, pj_ioqueue_op_key_t *send_key, const void *pkt, unsigned pkt_len, unsigned flag, const pj_sockaddr_t *dst_addr, unsigned addr_len)
 

Detailed Description

The STUN transport provides asynchronous UDP like socket transport with the additional STUN capability. It has the following features:

  • API to send and receive UDP packets
  • multiplex STUN and non-STUN incoming packets and distinguish between STUN responses that belong to internal requests with application data (the application data may be STUN packets as well)
  • DNS SRV resolution to the STUN server (if wanted), along with fallback to DNS A resolution if SRV record is not found.
  • STUN keep-alive maintenance, and handle changes to the mapped address (when the NAT binding changes)

Typedef Documentation

typedef struct pj_stun_sock pj_stun_sock

Opaque type to represent a STUN transport.

Enumeration Type Documentation

Types of operation being reported in on_status() callback of pj_stun_sock_cb. Application may retrieve the string representation of these constants with pj_stun_sock_op_name().

Enumerator
PJ_STUN_SOCK_DNS_OP 

Asynchronous DNS resolution.

PJ_STUN_SOCK_BINDING_OP 

Initial STUN Binding request.

PJ_STUN_SOCK_KEEP_ALIVE_OP 

Subsequent STUN Binding request for keeping the binding alive.

PJ_STUN_SOCK_MAPPED_ADDR_CHANGE 

IP address change notification from the keep-alive operation.

Function Documentation

void pj_stun_sock_cfg_default ( pj_stun_sock_cfg cfg)

Initialize the STUN transport setting with its default values.

Parameters
cfgThe STUN transport config.
pj_status_t pj_stun_sock_create ( pj_stun_config stun_cfg,
const char *  name,
int  af,
const pj_stun_sock_cb cb,
const pj_stun_sock_cfg cfg,
void *  user_data,
pj_stun_sock **  p_sock 
)

Create the STUN transport using the specified configuration. Once the STUN transport has been create, application should call pj_stun_sock_start() to start the transport.

Parameters
stun_cfgThe STUN configuration which contains among other things the ioqueue and timer heap instance for the operation of this transport.
afAddress family of socket. Currently pj_AF_INET() and pj_AF_INET6() are supported.
nameOptional name to be given to this transport to assist debugging.
cbCallback to receive events/data from the transport.
cfgOptional transport settings.
user_dataArbitrary application data to be associated with this transport.
p_sockPointer to receive the created transport instance.
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
pj_status_t pj_stun_sock_destroy ( pj_stun_sock sock)

Destroy the STUN transport.

Parameters
sockThe STUN transport socket.
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
pj_grp_lock_t* pj_stun_sock_get_grp_lock ( pj_stun_sock stun_sock)

Get the group lock for this STUN transport.

Parameters
stun_sockThe STUN transport instance.
Returns
The group lock.
pj_status_t pj_stun_sock_get_info ( pj_stun_sock stun_sock,
pj_stun_sock_info info 
)

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

Parameters
stun_sockThe STUN transport instance.
infoPointer to be filled with STUN transport info.
Returns
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
void* pj_stun_sock_get_user_data ( pj_stun_sock stun_sock)

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

Parameters
stun_sockThe STUN transport instance.
Returns
The user/application data.
const char* pj_stun_sock_op_name ( pj_stun_sock_op  op)

Retrieve the name representing the specified operation.

pj_status_t pj_stun_sock_sendto ( pj_stun_sock stun_sock,
pj_ioqueue_op_key_t send_key,
const void *  pkt,
unsigned  pkt_len,
unsigned  flag,
const pj_sockaddr_t dst_addr,
unsigned  addr_len 
)

Send a data to the specified address. This function may complete asynchronously and in this case on_data_sent() will be called.

Parameters
stun_sockThe STUN transport instance.
send_keyOptional send key for sending the packet down to the ioqueue. This value will be given back to on_data_sent() callback
pktThe data/packet to be sent to peer.
pkt_lenLength of the data.
flagpj_ioqueue_sendto() flag.
dst_addrThe remote address.
addr_lenLength 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_status_t pj_stun_sock_set_user_data ( pj_stun_sock stun_sock,
void *  user_data 
)

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

Parameters
stun_sockThe STUN 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_stun_sock_start ( pj_stun_sock stun_sock,
const pj_str_t domain,
pj_uint16_t  default_port,
pj_dns_resolver resolver 
)

Start the STUN transport. This will start the DNS SRV resolution for the STUN server (if desired), and once the server is resolved, STUN Binding request will be sent to resolve the publicly mapped address. Once the initial STUN Binding response is received, the keep-alive timer will be started.

Parameters
stun_sockThe STUN transport instance.
domainThe domain, hostname, or IP address of the STUN server. When this parameter contains domain name, the resolver parameter must be set to activate DNS SRV resolution.
default_portThe default STUN 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. The recommended value for this parameter is PJ_STUN_PORT.
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.
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.

 


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