Group PJLIB_UTIL_STUN_CLIENT

group PJLIB_UTIL_STUN_CLIENT

A simple and small footprint STUN resolution helper.

This is the older implementation of STUN client, with only one function provided (pjstun_get_mapped_addr()) to retrieve the public IP address of multiple sockets.

Functions

pj_status_t pjstun_get_mapped_addr(pj_pool_factory *pf, int sock_cnt, pj_sock_t sock[], const pj_str_t *srv1, int port1, const pj_str_t *srv2, int port2, pj_sockaddr_in mapped_addr[])

This is the main function to request the mapped address of local sockets to multiple STUN servers. This function is able to find the mapped addresses of multiple sockets simultaneously, and for each socket, two requests will be sent to two different STUN servers to see if both servers get the same public address for the same socket. (Note that application can specify the same address for the two servers, but still two requests will be sent for each server).

This function will perform necessary retransmissions of the requests if response is not received within a predetermined period. When all responses have been received, the function will compare the mapped addresses returned by the servers, and when both are equal, the address will be returned in mapped_addr argument.

Parameters:

  • pf – The pool factory where memory will be allocated from.

  • sock_cnt – Number of sockets in the socket array.

  • sock – Array of local UDP sockets which public addresses are to be queried from the STUN servers.

  • srv1 – Host name or IP address string of the first STUN server.

  • port1 – The port number of the first STUN server.

  • srv2 – Host name or IP address string of the second STUN server.

  • port2 – The port number of the second STUN server.

  • mapped_addr – Array to receive the mapped public address of the local UDP sockets, when the function returns PJ_SUCCESS.

Returns:

This functions returns PJ_SUCCESS if responses are received from all servers AND all servers returned the same mapped public address. Otherwise this function may return one of the following error codes:

  • PJLIB_UTIL_ESTUNNOTRESPOND: no respons from servers.

  • PJLIB_UTIL_ESTUNSYMMETRIC: different mapped addresses are returned by servers.

  • etc.

pj_status_t pjstun_get_mapped_addr2(pj_pool_factory *pf, const pjstun_setting *opt, int sock_cnt, pj_sock_t sock[], pj_sockaddr_in mapped_addr[])

Another version of mapped address resolution of local sockets to multiple STUN servers configured in pjstun_setting. This function is able to find the mapped addresses of multiple sockets simultaneously, and for each socket, two requests will be sent to two different STUN servers to see if both servers get the same public address for the same socket. (Note that application can specify the same address for the two servers, but still two requests will be sent for each server).

This function will perform necessary retransmissions of the requests if response is not received within a predetermined period. When all responses have been received, the function will compare the mapped addresses returned by the servers, and when both are equal, the address will be returned in mapped_addr argument.

Parameters:

  • pf – The pool factory where memory will be allocated from.

  • opt – The STUN settings.

  • sock_cnt – Number of sockets in the socket array.

  • sock – Array of local UDP sockets which public addresses are to be queried from the STUN servers.

  • mapped_addr – Array to receive the mapped public address of the local UDP sockets, when the function returns PJ_SUCCESS.

Returns:

This functions returns PJ_SUCCESS if responses are received from all servers AND all servers returned the same mapped public address. Otherwise this function may return one of the following error codes:

  • PJLIB_UTIL_ESTUNNOTRESPOND: no respons from servers.

  • PJLIB_UTIL_ESTUNSYMMETRIC: different mapped addresses are returned by servers.

  • etc.

struct pjstun_setting

Public Members

pj_bool_t use_stun2

Specifies whether STUN request generated by old STUN library should insert magic cookie (specified in RFC 5389) in the transaction ID.

int af

Address family of the STUN servers.

pj_str_t srv1

Host name or IP address string of the first STUN server.

int port1

The port number of the first STUN server.

pj_str_t srv2

Host name or IP address string of the second STUN server.

int port2

The port number of the second STUN server.