STUN-aware socket transport [STUN: Session Traversal Utilities for NAT]

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

enum pj_stun_sock_op

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.