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_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:
cfg The 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_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 socket. Currently pj_AF_INET() and pj_AF_INET6() are supported.
name Optional name to be given to this transport to assist debugging.
cb Callback to receive events/data from the transport.
cfg Optional transport settings.
user_data Arbitrary application data to be associated with this transport.
p_sock Pointer 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:
sock The STUN transport socket.
Returns:
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
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_sock The STUN transport instance.
info Pointer 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_sock The 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_sock The STUN transport instance.
send_key Optional send key for sending the packet down to the ioqueue. This value will be given back to on_data_sent() callback
pkt The data/packet to be sent to peer.
pkt_len Length of the data.
flag pj_ioqueue_sendto() flag.
dst_addr The remote 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_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_sock The STUN 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_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_sock The STUN 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 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.
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.
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.