Group PJNATH_STUN_SOCK¶

group PJNATH_STUN_SOCK

STUN aware UDP socket transport.

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)

Typedefs

typedef struct pj_stun_sock pj_stun_sock¶: Opaque type to represent a STUN transport.

Enums

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

Values:

enumerator PJ_STUN_SOCK_DNS_OP¶: Asynchronous DNS resolution.

enumerator PJ_STUN_SOCK_BINDING_OP¶: Initial STUN Binding request.

enumerator PJ_STUN_SOCK_KEEP_ALIVE_OP¶: Subsequent STUN Binding request for keeping the binding alive.

enumerator PJ_STUN_SOCK_MAPPED_ADDR_CHANGE¶: IP address change notification from the keep-alive operation.

Functions

const char *pj_stun_sock_op_name(pj_stun_sock_op op)¶: Retrieve the name representing the specified operation.

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_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.

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_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.

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_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_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.

struct pj_stun_sock_cb¶: #include <stun_sock.h>
This structure contains callbacks that will be called by the STUN transport to notify application about various events.

struct pj_stun_sock_info¶: #include <stun_sock.h>
This structure contains information about the STUN transport. Application may query this information by calling pj_stun_sock_get_info().

struct pj_stun_sock_cfg¶: #include <stun_sock.h>
This describe the settings to be given to the STUN transport during its creation. Application should initialize this structure by calling pj_stun_sock_cfg_default().