STUN-aware socket transport

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_t *	pj_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

pj_stun_sock

typedef struct pj_stun_sock pj_stun_sock

Opaque type to represent a STUN transport.

Enumeration Type Documentation

pj_stun_sock_op

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

pj_stun_sock_cfg_default()

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_stun_sock_create()

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_stun_sock_destroy()

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_stun_sock_get_grp_lock()

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_sock

The STUN transport instance.

Returns

The group lock.

pj_stun_sock_get_info()

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.

pj_stun_sock_get_user_data()

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.

pj_stun_sock_op_name()

const char * pj_stun_sock_op_name

(

pj_stun_sock_op

op

)

Retrieve the name representing the specified operation.

pj_stun_sock_sendto()

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.

References PJ_END_DECL.

pj_stun_sock_set_user_data()

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_stun_sock_start()

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 STUN 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_status() callback.