Home --> Documentations --> PJSIP Reference

Data Structures | Enumerations | Functions
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)
 

Detailed Description

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

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
cfgThe structure to initialize.
afAddress family to be used.
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
endptThe SIP endpoint.
cfgUDP transport settings. Application should initialize this setting with pjsip_udp_transport_cfg_default().
p_transportPointer 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_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
endptThe SIP endpoint.
localOptional local address to bind. If this argument is NULL, the UDP transport will be bound to arbitrary UDP port.
a_namePublished 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_cntNumber of simultaneous async operations.
p_transportPointer 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
endptThe SIP endpoint.
sockUDP socket to use.
a_namePublished address (only the host and port portion is used).
async_cntNumber of simultaneous async operations.
p_transportPointer 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
endptThe SIP endpoint.
typeTransport type, which is PJSIP_TRANSPORT_UDP for IPv4 or PJSIP_TRANSPORT_UDP6 for IPv6 socket.
sockUDP socket to use.
a_namePublished address (only the host and port portion is used).
async_cntNumber of simultaneous async operations.
p_transportPointer 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
transportThe 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
transportThe UDP transport.
optionPause 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
transportThe UDP transport.
optionRestart option.
sockOptional socket to be used by the transport.
localThe address where the socket should be bound to. If this argument is NULL, socket will be bound to any available port.
a_nameOptionally 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 Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.