Group PJSUA_LIB_TRANSPORT

group PJSUA_LIB_TRANSPORT

API for managing SIP transports.

PJSUA-API supports creating multiple transport instances, for example UDP, TCP, and TLS transport. SIP transport must be created before adding an account.

Typedefs

typedef int pjsua_transport_id

SIP transport identification.

Functions

void pjsua_transport_config_default(pjsua_transport_config *cfg)

Call this function to initialize UDP config with default values.

Parameters:

cfg – The UDP config to be initialized.

void pjsua_transport_config_dup(pj_pool_t *pool, pjsua_transport_config *dst, const pjsua_transport_config *src)

Duplicate transport config.

Parameters:

  • pool – The pool.

  • dst – The destination config.

  • src – The source config.

pj_status_t pjsua_transport_create(pjsip_transport_type_e type, const pjsua_transport_config *cfg, pjsua_transport_id *p_id)

Create and start a new SIP transport according to the specified settings.

Parameters:

  • type – Transport type.

  • cfg – Transport configuration.

  • p_id – Optional pointer to receive transport ID.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_transport_register(pjsip_transport *tp, pjsua_transport_id *p_id)

Register transport that has been created by application. This function is useful if application wants to implement custom SIP transport and use it with pjsua.

Parameters:

  • tp – Transport instance.

  • p_id – Optional pointer to receive transport ID.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_tpfactory_register(pjsip_tpfactory *tf, pjsua_transport_id *p_id)

Register transport factory that has been created by application. This function is useful if application wants to implement custom SIP transport and use it with pjsua.

Parameters:

  • tf – Transport factory instance.

  • p_id – Optional pointer to receive transport ID.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_enum_transports(pjsua_transport_id id[], unsigned *count)

Enumerate all transports currently created in the system. This function will return all transport IDs, and application may then call pjsua_transport_get_info() function to retrieve detailed information about the transport.

Parameters:

  • id – Array to receive transport ids.

  • count – In input, specifies the maximum number of elements. On return, it contains the actual number of elements.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_transport_get_info(pjsua_transport_id id, pjsua_transport_info *info)

Get information about transports.

Parameters:

  • id – Transport ID.

  • info – Pointer to receive transport info.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_transport_set_enable(pjsua_transport_id id, pj_bool_t enabled)

Disable a transport or re-enable it. By default transport is always enabled after it is created. Disabling a transport does not necessarily close the socket, it will only discard incoming messages and prevent the transport from being used to send outgoing messages.

Parameters:

  • id – Transport ID.

  • enabled – Non-zero to enable, zero to disable.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_transport_close(pjsua_transport_id id, pj_bool_t force)

Close the transport. The system will wait until all transactions are closed while preventing new users from using the transport, and will close the transport when it is safe to do so.

NOTE: Forcefully closing transport (force = PJ_TRUE) is deprecated, since any pending transactions that are using the transport may not terminate properly and can even crash. Application wishing to immediately close the transport for the purpose of restarting it should use pjsua_handle_ip_change() instead.

Parameters:

  • id – Transport ID.

  • force – Must be PJ_FALSE. force = PJ_TRUE is deprecated.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_transport_lis_start(pjsua_transport_id id, const pjsua_transport_config *cfg)

Start the listener of the transport. This is useful when listener is not automatically started when creating the transport.

Parameters:

  • id – Transport ID.

  • cfg – The new transport config used by the listener. Only port, public_addr and bound_addr are used at the moment.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

struct pjsua_transport_config
#include <pjsua.h>

Transport configuration for creating transports for both SIP and media. Before setting some values to this structure, application MUST call pjsua_transport_config_default() to initialize its values with default settings.

Public Members

unsigned port

UDP port number to bind locally. This setting MUST be specified even when default port is desired. If the value is zero, the transport will be bound to any available port, and application can query the port by querying the transport info.

unsigned port_range

Specify the port range for socket binding, relative to the start port number specified in port. Note that this setting is only applicable to media transport when the start port number is non zero. Media transport is configurable via account setting, i.e: pjsua_acc_config.rtp_cfg, please check the media transport config docs for more info.

Available ports are in the range of [port, port + port_range].

Default value is zero.

pj_bool_t randomize_port

Specify whether to randomly pick the starting port number from the range of [port, port + port_range]. This setting is used only if both port and port_range are non-zero, and only applicable for the port selection of UDP and loop media transport.

Default is PJ_FALSE.

pj_str_t public_addr

Optional address to advertise as the address of this transport. Application can specify any address or hostname for this field, for example it can point to one of the interface address in the system, or it can point to the public address of a NAT router where port mappings have been configured for the application.

Note: this option can be used for both UDP and TCP as well!

pj_str_t bound_addr

Optional address where the socket should be bound to. This option SHOULD only be used to selectively bind the socket to particular interface (instead of 0.0.0.0), and SHOULD NOT be used to set the published address of a transport (the public_addr field should be used for that purpose).

Note that unlike public_addr field, the address (or hostname) here MUST correspond to the actual interface address in the host, since this address will be specified as bind() argument.

pjsip_tls_setting tls_setting

This specifies TLS settings for TLS transport. It’s only used when creating a SIP TLS transport.

pj_qos_type qos_type

QoS traffic type to be set on this transport. When application wants to apply QoS tagging to the transport, it’s preferable to set this field rather than qos_param fields since this is more portable.

For TLS transport, this field will be ignored, the QoS traffic type can be set via tls_setting.

Default is QoS not set.

pj_qos_params qos_params

Set the low level QoS parameters to the transport. This is a lower level operation than setting the qos_type field and may not be supported on all platforms.

For TLS transport, this field will be ignored, the low level QoS parameters can be set via tls_setting.

Default is QoS not set.

pj_sockopt_params sockopt_params

Specify options to be set on the transport.

For TLS transport, this field will be ignored, the socket options can be set via tls_setting.

By default there is no options.

struct pjsua_transport_info
#include <pjsua.h>

This structure describes transport information returned by pjsua_transport_get_info() function.

Public Members

pjsua_transport_id id

PJSUA transport identification.

pjsip_transport_type_e type

Transport type.

pj_str_t type_name

Transport type name.

pj_str_t info

Transport string info/description.

unsigned flag

Transport flag (see #pjsip_transport_flags_e).

unsigned addr_len

Local address length.

pj_sockaddr local_addr

Local/bound address.

pjsip_host_port local_name

Published address (or transport address name).

unsigned usage_count

Current number of objects currently referencing this transport.