UDP Transport

API to create and register UDP transport.The functions below are used to create UDP transport and register the transport to the framework. More...

Data Structures
struct	pjsip_udp_transport_cfg

Enumerations
enum	{ PJSIP_UDP_TRANSPORT_KEEP_SOCKET = 1 , PJSIP_UDP_TRANSPORT_DESTROY_SOCKET = 2 }

Functions
void	pjsip_udp_transport_cfg_default (pjsip_udp_transport_cfg *cfg, int af)
pj_status_t	pjsip_udp_transport_start2 (pjsip_endpoint *endpt, const pjsip_udp_transport_cfg *cfg, pjsip_transport **p_transport)
pj_status_t	pjsip_udp_transport_start (pjsip_endpoint *endpt, const pj_sockaddr_in *local, const pjsip_host_port *a_name, unsigned async_cnt, pjsip_transport **p_transport)
pj_status_t	pjsip_udp_transport_start6 (pjsip_endpoint *endpt, const pj_sockaddr_in6 *local, const pjsip_host_port *a_name, unsigned async_cnt, pjsip_transport **p_transport)
pj_status_t	pjsip_udp_transport_attach (pjsip_endpoint *endpt, pj_sock_t sock, const pjsip_host_port *a_name, unsigned async_cnt, pjsip_transport **p_transport)
pj_status_t	pjsip_udp_transport_attach2 (pjsip_endpoint *endpt, pjsip_transport_type_e type, pj_sock_t sock, const pjsip_host_port *a_name, unsigned async_cnt, pjsip_transport **p_transport)
pj_sock_t	pjsip_udp_transport_get_socket (pjsip_transport *transport)
pj_status_t	pjsip_udp_transport_pause (pjsip_transport *transport, unsigned option)
pj_status_t	pjsip_udp_transport_restart (pjsip_transport *transport, unsigned option, pj_sock_t sock, const pj_sockaddr_in *local, const pjsip_host_port *a_name)
pj_status_t	pjsip_udp_transport_restart2 (pjsip_transport *transport, unsigned option, pj_sock_t sock, const pj_sockaddr *local, const pjsip_host_port *a_name)

Detailed Description

Enumeration Type Documentation

anonymous enum

anonymous enum

Flag that can be specified when calling pjsip_udp_transport_pause() or pjsip_udp_transport_restart().

Enumerator
PJSIP_UDP_TRANSPORT_KEEP_SOCKET	This flag tells the transport to keep the existing/internal socket handle.
PJSIP_UDP_TRANSPORT_DESTROY_SOCKET	This flag tells the transport to destroy the existing/internal socket handle. Naturally this flag and PJSIP_UDP_TRANSPORT_KEEP_SOCKET are mutually exclusive.

Function Documentation

pjsip_udp_transport_cfg_default()

void pjsip_udp_transport_cfg_default	(	pjsip_udp_transport_cfg *	cfg,
		int	af
	)

Initialize pjsip_udp_transport_cfg structure with default values for the specifed address family.

Parameters

cfg	The structure to initialize.
af	Address family to be used.

pjsip_udp_transport_start2()

pj_status_t pjsip_udp_transport_start2	(	pjsip_endpoint *	endpt,
		const pjsip_udp_transport_cfg *	cfg,
		pjsip_transport **	p_transport
	)

Start UDP IPv4/IPv6 transport.

Parameters

endpt	The SIP endpoint.
cfg	UDP transport settings. Application should initialize this setting with pjsip_udp_transport_cfg_default().
p_transport	Pointer to receive the transport.

Returns

PJ_SUCCESS when the transport has been successfully started and registered to transport manager, or the appropriate error code.

pjsip_udp_transport_start()

pj_status_t pjsip_udp_transport_start	(	pjsip_endpoint *	endpt,
		const pj_sockaddr_in *	local,
		const pjsip_host_port *	a_name,
		unsigned	async_cnt,
		pjsip_transport **	p_transport
	)

Start UDP transport.

Parameters

endpt	The SIP endpoint.
local	Optional local address to bind. If this argument is NULL, the UDP transport will be bound to arbitrary UDP port.
a_name	Published address (only the host and port portion is used). If this argument is NULL, then the bound address will be used as the published address.
async_cnt	Number of simultaneous async operations.
p_transport	Pointer to receive the transport.

Returns

PJ_SUCCESS when the transport has been successfully started and registered to transport manager, or the appropriate error code.

pjsip_udp_transport_start6()

pj_status_t pjsip_udp_transport_start6	(	pjsip_endpoint *	endpt,
		const pj_sockaddr_in6 *	local,
		const pjsip_host_port *	a_name,
		unsigned	async_cnt,
		pjsip_transport **	p_transport
	)

Start IPv6 UDP transport.

pjsip_udp_transport_attach()

pj_status_t pjsip_udp_transport_attach	(	pjsip_endpoint *	endpt,
		pj_sock_t	sock,
		const pjsip_host_port *	a_name,
		unsigned	async_cnt,
		pjsip_transport **	p_transport
	)

Attach IPv4 UDP socket as a new transport and start the transport.

Parameters

endpt	The SIP endpoint.
sock	UDP socket to use.
a_name	Published address (only the host and port portion is used).
async_cnt	Number of simultaneous async operations.
p_transport	Pointer to receive the transport.

Returns

PJ_SUCCESS when the transport has been successfully started and registered to transport manager, or the appropriate error code.

pjsip_udp_transport_attach2()

pj_status_t pjsip_udp_transport_attach2	(	pjsip_endpoint *	endpt,
		pjsip_transport_type_e	type,
		pj_sock_t	sock,
		const pjsip_host_port *	a_name,
		unsigned	async_cnt,
		pjsip_transport **	p_transport
	)

Attach IPv4 or IPv6 UDP socket as a new transport and start the transport.

Parameters

endpt	The SIP endpoint.
type	Transport type, which is PJSIP_TRANSPORT_UDP for IPv4 or PJSIP_TRANSPORT_UDP6 for IPv6 socket.
sock	UDP socket to use.
a_name	Published address (only the host and port portion is used).
async_cnt	Number of simultaneous async operations.
p_transport	Pointer to receive the transport.

Returns

PJ_SUCCESS when the transport has been successfully started and registered to transport manager, or the appropriate error code.

pjsip_udp_transport_get_socket()

pj_sock_t pjsip_udp_transport_get_socket

(

pjsip_transport *

transport

)

Retrieve the internal socket handle used by the UDP transport. Note that this socket normally is registered to ioqueue, so if application wants to make use of this socket, it should temporarily pause the transport.

Parameters

transport

The UDP transport.

Returns

The socket handle, or PJ_INVALID_SOCKET if no socket is currently being used (for example, when transport is being paused).

pjsip_udp_transport_pause()

pj_status_t pjsip_udp_transport_pause	(	pjsip_transport *	transport,
		unsigned	option
	)

Temporarily pause or shutdown the transport. When transport is being paused, it cannot be used by the SIP stack to send or receive SIP messages.

Two types of operations are supported by this function:

• to temporarily make this transport unavailable for SIP uses, but otherwise keep the socket handle intact. Application then can retrieve the socket handle with pjsip_udp_transport_get_socket() and use it to send/receive application data (for example, STUN messages). In this case, application should specify PJSIP_UDP_TRANSPORT_KEEP_SOCKET when calling this function, and also to specify this flag when calling pjsip_udp_transport_restart() later.
• to temporarily shutdown the transport, including closing down the internal socket handle. This is useful for example to temporarily suspend the application for an indefinite period. In this case, application should specify PJSIP_UDP_TRANSPORT_DESTROY_SOCKET flag when calling this function, and specify a new socket when calling pjsip_udp_transport_restart().

Parameters

transport	The UDP transport.
option	Pause option.

Returns

PJ_SUCCESS if transport is paused successfully, or the appropriate error code.

pjsip_udp_transport_restart()

pj_status_t pjsip_udp_transport_restart	(	pjsip_transport *	transport,
		unsigned	option,
		pj_sock_t	sock,
		const pj_sockaddr_in *	local,
		const pjsip_host_port *	a_name
	)

Restart the transport. Several operations are supported by this function:

• if transport was made temporarily unavailable to SIP stack with pjsip_udp_transport_pause() and PJSIP_UDP_TRANSPORT_KEEP_SOCKET, application can make the transport available to the SIP stack again, by specifying PJSIP_UDP_TRANSPORT_KEEP_SOCKET flag here.
• if application wants to replace the internal socket with a new socket, it must specify PJSIP_UDP_TRANSPORT_DESTROY_SOCKET when calling this function, so that the internal socket will be destroyed if it hasn't been closed. In this case, application has two choices on how to create the new socket: 1) to let the transport create the new socket, in this case the sock option should be set to PJ_INVALID_SOCKET and optionally the local parameter can be filled with the desired address and port where the new socket should be bound to, or 2) to specify its own socket to be used by this transport, by specifying a valid socket in sock argument and set the local argument to NULL. In both cases, application may specify the published address of the socket in a_name argument.

Note that prior to calling this method, any locks acquired need to be released temporarily to avoid any deadlock scenario.
This method will loop to wait for read operation to finish before actually restart the transport. This might lead to deadlock if any other thread with the read operation tries to acquire the same lock held by the thread calling this method. Please see https://github.com/pjsip/pjproject/pull/2731 for more details.

Parameters

transport	The UDP transport.
option	Restart option.
sock	Optional socket to be used by the transport.
local	The address where the socket should be bound to. If this argument is NULL, socket will be bound to any available port.
a_name	Optionally specify the published address for this transport. If the socket is not replaced (PJSIP_UDP_TRANSPORT_KEEP_SOCKET flag is specified), then if this argument is NULL, the previous value will be used. If the socket is replaced and this argument is NULL, the bound address will be used as the published address of the transport.

Returns

PJ_SUCCESS if transport can be restarted, or the appropriate error code.

pjsip_udp_transport_restart2()

pj_status_t pjsip_udp_transport_restart2	(	pjsip_transport *	transport,
		unsigned	option,
		pj_sock_t	sock,
		const pj_sockaddr *	local,
		const pjsip_host_port *	a_name
	)

Restart the transport. Several operations are supported by this function:

• if transport was made temporarily unavailable to SIP stack with pjsip_udp_transport_pause() and PJSIP_UDP_TRANSPORT_KEEP_SOCKET, application can make the transport available to the SIP stack again, by specifying PJSIP_UDP_TRANSPORT_KEEP_SOCKET flag here.
• if application wants to replace the internal socket with a new socket, it must specify PJSIP_UDP_TRANSPORT_DESTROY_SOCKET when calling this function, so that the internal socket will be destroyed if it hasn't been closed. In this case, application has two choices on how to create the new socket: 1) to let the transport create the new socket, in this case the sock option should be set to PJ_INVALID_SOCKET and optionally the local parameter can be filled with the desired address and port where the new socket should be bound to, or 2) to specify its own socket to be used by this transport, by specifying a valid socket in sock argument and set the local argument to NULL. In both cases, application may specify the published address of the socket in a_name argument. This is another version of pjsip_udp_transport_restart() able to restart IPv6 transport.

Note that prior to calling this method, any locks acquired need to be released temporarily to avoid any deadlock scenario.
This method will loop to wait for read operation to finish before actually restart the transport. This might lead to deadlock if any other thread with the read operation tries to acquire the same lock held by the thread calling this method. Please see https://github.com/pjsip/pjproject/pull/2731 for more details.

Parameters

transport	The UDP transport.
option	Restart option.
sock	Optional socket to be used by the transport.
local	The address where the socket should be bound to. If this argument is NULL, socket will be bound to any available port.
a_name	Optionally specify the published address for this transport. If the socket is not replaced (PJSIP_UDP_TRANSPORT_KEEP_SOCKET flag is specified), then if this argument is NULL, the previous value will be used. If the socket is replaced and this argument is NULL, the bound address will be used as the published address of the transport.

Returns

PJ_SUCCESS if transport can be restarted, or the appropriate error code.

References PJ_END_DECL.