Group PJSIP_TRANSPORT_UDP

group PJSIP_TRANSPORT_UDP

API to create and register UDP transport.

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

Enums

enum [anonymous]

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

Values:

enumerator PJSIP_UDP_TRANSPORT_KEEP_SOCKET

This flag tells the transport to keep the existing/internal socket handle.

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

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)

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.