UDP Transport
[Transport]

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

Enumerations
enum	{ PJSIP_UDP_TRANSPORT_KEEP_SOCKET = 1, PJSIP_UDP_TRANSPORT_DESTROY_SOCKET = 2 }
Functions
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)

Enumeration Type Documentation

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

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.

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.

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.

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.

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

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.

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.

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.

UDP Transport [Transport]

Enumerations

Functions

Enumeration Type Documentation

Function Documentation

UDP Transport
[Transport]