Group PJSIP_TRANSPORT

group PJSIP_TRANSPORT

This is the transport framework.

The transport framework is fully extensible. Please see PJSIP Developer’s Guide PDF document for more information.

Application MUST register at least one transport to PJSIP before any messages can be sent or received. Please see UDP Transport on how to create/register UDP transport to the transport framework.

Defines

PJSIP_TRANSPORT_IS_RELIABLE(tp)

Check if transport tp is reliable.

PJSIP_TRANSPORT_IS_SECURE(tp)

Check if transport tp is secure.

Typedefs

typedef void (*pjsip_transport_callback)(pjsip_transport *tp, void *token, pj_ssize_t sent_bytes)

Type of callback to receive transport operation status.

typedef void (*pjsip_rx_callback)(pjsip_endpoint *ep, pj_status_t status, pjsip_rx_data *rd)

Type of callback to be called when transport manager receives incoming SIP message.

Param ep:

Endpoint.

Param status:

Receiption status.

Param rd:

Received packet.

typedef pj_status_t (*pjsip_tx_callback)(pjsip_endpoint *ep, pjsip_tx_data *td)

Type of callback to be called before transport manager is about to transmit SIP message.

Param ep:

Endpoint.

Param td:

Transmit data.

typedef void (*pjsip_tp_send_callback)(void *token, pjsip_tx_data *tdata, pj_ssize_t bytes_sent)

Type of callback to receive notification when message or raw data has been sent.

Param token:

The token that was given when calling the function to send message or raw data.

Param tdata:

The transmit buffer used to send the message.

Param bytes_sent:

Number of bytes sent. On success, the value will be positive number indicating the number of bytes sent. On failure, the value will be a negative number of the error code (i.e. bytes_sent = -status).

typedef void pjsip_tp_state_listener_key

Definition of transport state listener key.

typedef void (*pjsip_tp_state_callback)(pjsip_transport *tp, pjsip_transport_state state, const pjsip_transport_state_info *info)

Type of callback to receive transport state notifications, such as transport connected/disconnected. Application may shutdown the transport in this callback.

Param tp:

The transport instance.

Param state:

The transport state.

Param info:

The transport state info.

typedef void (*pjsip_tp_on_rx_dropped_cb)(pjsip_tp_dropped_data *data)

Type of callback to data dropping notifications.

Param data:

The dropped data.

typedef pj_status_t (*pjsip_tp_on_rx_data_cb)(pjsip_tp_rx_data *data)

Type of callback to data received notifications.

Param data:

The received data.

Enums

enum pjsip_transport_flags_e

Flags for SIP transports.

Values:

enumerator PJSIP_TRANSPORT_RELIABLE

Transport is reliable.

enumerator PJSIP_TRANSPORT_SECURE

Transport is secure.

enumerator PJSIP_TRANSPORT_DATAGRAM

Datagram based transport.

(it’s also assumed to be connectionless)

enum pjsip_tpselector_type

This structure describes the type of data in pjsip_tpselector.

Values:

enumerator PJSIP_TPSELECTOR_NONE

Transport is not specified.

enumerator PJSIP_TPSELECTOR_TRANSPORT

Use the specific transport to send request.

enumerator PJSIP_TPSELECTOR_LISTENER

Use the specific listener to send request.

enumerator PJSIP_TPSELECTOR_IP_VER

Use the IP version criteria to send request.

enum pjsip_tpselector_ip_ver

This enumerator describes the IP version criteria for pjsip_tpselector.

Values:

enumerator PJSIP_TPSELECTOR_USE_IPV4_ONLY

IPv4 only.

enumerator PJSIP_TPSELECTOR_NO_PREFERENCE

No preference. IP version used will depend on the order of addresses returned by pjsip_resolver.

enumerator PJSIP_TPSELECTOR_PREFER_IPV4

IPv4 is preferred.

enumerator PJSIP_TPSELECTOR_PREFER_IPV6

IPv6 is preferred.

enumerator PJSIP_TPSELECTOR_USE_IPV6_ONLY

IPv6 only.

enum pjsip_transport_dir

Enumeration of transport direction types.

Values:

enumerator PJSIP_TP_DIR_NONE

Direction not set, normally used by connectionless transports such as UDP transport.

enumerator PJSIP_TP_DIR_OUTGOING

Outgoing connection or client mode, this is only for connection-oriented transports.

enumerator PJSIP_TP_DIR_INCOMING

Incoming connection or server mode, this is only for connection-oriented transports.

enum pjsip_transport_state

Enumeration of transport state types.

Values:

enumerator PJSIP_TP_STATE_CONNECTED

Transport connected, applicable only to connection-oriented transports such as TCP and TLS.

enumerator PJSIP_TP_STATE_DISCONNECTED

Transport disconnected, applicable only to connection-oriented transports such as TCP and TLS.

enumerator PJSIP_TP_STATE_SHUTDOWN

Transport shutdown, either due to TCP/TLS disconnect error from the network, or when shutdown is initiated by PJSIP itself.

enumerator PJSIP_TP_STATE_DESTROY

Transport destroy, when transport is about to be destroyed.

Functions

pj_status_t pjsip_transport_register_type(unsigned tp_flag, const char *tp_name, int def_port, int *p_tp_type)

Register new transport type to PJSIP. The PJSIP transport framework contains the info for some standard transports, as declared by pjsip_transport_type_e. Application may use non-standard transport with PJSIP, but before it does so, it must register the information about the new transport type to PJSIP by calling this function.

Parameters:
  • tp_flag – The flags describing characteristics of this transport type.

  • tp_name – Transport type name.

  • def_port – Default port to be used for the transport.

  • p_tp_type – On successful registration, it will be filled with the registered type. This argument is optional.

Returns:

PJ_SUCCESS if registration is successful, or PJSIP_ETYPEEXISTS if the same transport type has already been registered.

pjsip_transport_type_e pjsip_transport_get_type_from_name(const pj_str_t *name)

Get the transport type from the transport name.

Parameters:

name – Transport name, such as “TCP”, or “UDP”.

Returns:

The transport type, or PJSIP_TRANSPORT_UNSPECIFIED if the name is not recognized as the name of supported transport.

pjsip_transport_type_e pjsip_transport_get_type_from_flag(unsigned flag)

Get the first transport type that has the specified flags.

Parameters:

flag – The transport flag.

Returns:

Transport type.

int pjsip_transport_type_get_af(pjsip_transport_type_e type)

Get the socket address family of a given transport type.

Parameters:

type – Transport type.

Returns:

Transport type.

unsigned pjsip_transport_get_flag_from_type(pjsip_transport_type_e type)

Get transport flag from type.

Parameters:

type – Transport type.

Returns:

Transport flags.

int pjsip_transport_get_default_port_for_type(pjsip_transport_type_e type)

Get the default SIP port number for the specified type.

Parameters:

type – Transport type.

Returns:

The port number, which is the default SIP port number for the specified type.

const char *pjsip_transport_get_type_name(pjsip_transport_type_e t)

Get transport type name.

Parameters:

t – Transport type.

Returns:

Transport name.

const char *pjsip_transport_get_type_desc(pjsip_transport_type_e t)

Get longer description for the specified transport type.

Parameters:

t – Transport type.

Returns:

Transport description.

void pjsip_tpselector_add_ref(pjsip_tpselector *sel)

Add transport/listener reference in the selector to prevent the specified transport/listener from being destroyed while application still has reference to it.

Parameters:

sel – The transport selector.

void pjsip_tpselector_dec_ref(pjsip_tpselector *sel)

Decrement transport/listener reference in the selector.

Parameters:

sel – The transport selector

char *pjsip_rx_data_get_info(pjsip_rx_data *rdata)

Get printable information about the message in the rdata.

Parameters:

rdata – The receive data buffer.

Returns:

Printable information.

pj_status_t pjsip_rx_data_clone(const pjsip_rx_data *src, unsigned flags, pjsip_rx_data **p_rdata)

Clone pjsip_rx_data. This will duplicate the contents of pjsip_rx_data and add reference count to the transport. Once application has finished using the cloned pjsip_rx_data, it must release it by calling pjsip_rx_data_free_cloned().

By default (if flags is set to zero), this function copies the transport pointer in tp_info, duplicates the pkt_info, perform deep clone of the msg_info parts of the rdata, and fills the endpt_info (i.e. the mod_data) with zeros.

Parameters:
  • src – The source to be cloned.

  • flags – Optional flags. Must be zero for now.

  • p_rdata – Pointer to receive the cloned rdata.

Returns:

PJ_SUCCESS on success or the appropriate error.

pj_status_t pjsip_rx_data_free_cloned(pjsip_rx_data *rdata)

Free cloned pjsip_rx_data. This function must be and must only be called for a cloned pjsip_rx_data. Specifically, it must NOT be called for the original pjsip_rx_data that is returned by transports.

This function will free the memory used by the pjsip_rx_data and decrement the transport reference counter.

Parameters:

rdata – The receive data buffer.

Returns:

PJ_SUCCESS on success or the appropriate error.

pj_status_t pjsip_tx_data_create(pjsip_tpmgr *mgr, pjsip_tx_data **tdata)

Create a new, blank transmit buffer. The reference count is initialized to zero.

Parameters:
  • mgr – The transport manager.

  • tdata – Pointer to receive transmit data.

Returns:

PJ_SUCCESS, or the appropriate error code.

void pjsip_tx_data_add_ref(pjsip_tx_data *tdata)

Add reference counter to the transmit buffer. The reference counter controls the life time of the buffer, ie. when the counter reaches zero, then it will be destroyed.

Parameters:

tdata – The transmit buffer.

pj_status_t pjsip_tx_data_dec_ref(pjsip_tx_data *tdata)

Decrement reference counter of the transmit buffer. When the transmit buffer is no longer used, it will be destroyed and caller is informed with PJSIP_EBUFDESTROYED return status.

Parameters:

tdata – The transmit buffer data.

Returns:

This function will always succeeded eventhough the return status is non-zero. A status PJSIP_EBUFDESTROYED will be returned to inform that buffer is destroyed.

pj_status_t pjsip_tx_data_encode(pjsip_tx_data *tdata)

Print the SIP message to transmit data buffer’s internal buffer. This may allocate memory for the buffer, if the buffer has not been allocated yet, and encode the SIP message to that buffer.

Parameters:

tdata – The transmit buffer.

Returns:

PJ_SUCCESS on success of the appropriate error code.

pj_bool_t pjsip_tx_data_is_valid(pjsip_tx_data *tdata)

Check if transmit data buffer contains a valid message.

Parameters:

tdata – The transmit buffer.

Returns:

Non-zero (PJ_TRUE) if buffer contains a valid message.

void pjsip_tx_data_invalidate_msg(pjsip_tx_data *tdata)

Invalidate the print buffer to force message to be re-printed. Call when the message has changed after it has been printed to buffer. The message is printed to buffer normally by transport when it is about to be sent to the wire. Subsequent sending of the message will not cause the message to be re-printed, unless application invalidates the buffer by calling this function.

Parameters:

tdata – The transmit buffer.

char *pjsip_tx_data_get_info(pjsip_tx_data *tdata)

Get short printable info about the transmit data. This will normally return short information about the message.

Parameters:

tdata – The transmit buffer.

Returns:

Null terminated info string.

pj_status_t pjsip_tx_data_set_transport(pjsip_tx_data *tdata, const pjsip_tpselector *sel)

Set the explicit transport to be used when sending this transmit data. Application should not need to call this function, but rather use pjsip_tsx_set_transport() and pjsip_dlg_set_transport() instead (which will call this function).

Parameters:
  • tdata – The transmit buffer.

  • sel – Transport selector.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_tx_data_clone(const pjsip_tx_data *src, unsigned flags, pjsip_tx_data **p_rdata)

Clone pjsip_tx_data. This will duplicate the message contents of pjsip_tx_data (pjsip_tx_data.msg) and add reference count to the tdata. Once application has finished using the cloned pjsip_tx_data, it must release it by calling pjsip_tx_data_dec_ref(). Currently, this will only clone response message.

Parameters:
  • src – The source to be cloned.

  • flags – Optional flags. Must be zero for now.

  • p_rdata – Pointer to receive the cloned tdata.

Returns:

PJ_SUCCESS on success or the appropriate error.

pj_status_t pjsip_transport_register(pjsip_tpmgr *mgr, pjsip_transport *tp)

Register a transport instance to the transport manager. This function is normally called by the transport instance when it is created by application.

Parameters:
  • mgr – The transport manager.

  • tp – The new transport to be registered.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_transport_shutdown(pjsip_transport *tp)

Start graceful shutdown procedure for this transport. After graceful shutdown has been initiated, no new reference can be obtained for the transport. However, existing objects that currently uses the transport may still use this transport to send and receive packets.

After all objects release their reference to this transport, the transport will be destroyed immediately.

Parameters:

tp – The transport.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_transport_shutdown2(pjsip_transport *tp, pj_bool_t force)

Start shutdown procedure for this transport. If force is false, the API is the same as pjsip_transport_shutdown(), while if force is true, existing transport users will immediately receive PJSIP_TP_STATE_DISCONNECTED notification and should not use the transport anymore. In either case, transport will only be destroyed after all objects release their references.

Parameters:
  • tp – The transport.

  • force – Force transport to immediately send disconnection state notification.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_transport_destroy(pjsip_transport *tp)

Destroy a transport when there is no object currently uses the transport. This function is normally called internally by transport manager or the transport itself. Application should use pjsip_transport_shutdown() instead.

Parameters:

tp – The transport instance.

Returns:

PJ_SUCCESS on success or the appropriate error code. Some of possible errors are PJSIP_EBUSY if the transport’s reference counter is not zero.

pj_status_t pjsip_transport_add_ref(pjsip_transport *tp)

Add reference counter to the specified transport. Any objects that wishes to keep the reference of the transport MUST increment the transport’s reference counter to prevent it from being destroyed.

Parameters:

tp – The transport instance.

Returns:

PJ_SUCCESS on success or the appropriate error code.

pj_status_t pjsip_transport_dec_ref(pjsip_transport *tp)

Decrement reference counter of the specified transport. When an object no longer want to keep the reference to the transport, it must decrement the reference counter. When the reference counter of the transport reaches zero, the transport manager will start the idle timer to destroy the transport if no objects acquire the reference counter during the idle interval.

Parameters:

tp – The transport instance.

Returns:

PJ_SUCCESS on success.

pj_ssize_t pjsip_tpmgr_receive_packet(pjsip_tpmgr *mgr, pjsip_rx_data *rdata)

This function is called by transport instances to report an incoming packet to the transport manager. The transport manager then would try to parse all SIP messages in the packet, and for each parsed SIP message, it would report the message to the SIP endpoint (pjsip_endpoint).

Parameters:
  • mgr – The transport manager instance.

  • rdata – The receive data buffer containing the packet. The transport MUST fully initialize tp_info and pkt_info member of the rdata.

Returns:

The number of bytes successfully processed from the packet. If the transport is datagram oriented, the value will be equal to the size of the packet. For stream oriented transport (e.g. TCP, TLS), the value returned may be less than the packet size, if partial message is received. The transport then MUST keep the remainder part and report it again to this function once more data/packet is received.

pj_status_t pjsip_tpmgr_register_tpfactory(pjsip_tpmgr *mgr, pjsip_tpfactory *tpf)

Register a transport factory.

Parameters:
  • mgr – The transport manager.

  • tpf – Transport factory.

Returns:

PJ_SUCCESS if listener was successfully created.

pj_status_t pjsip_tpmgr_unregister_tpfactory(pjsip_tpmgr *mgr, pjsip_tpfactory *tpf)

Unregister factory.

Parameters:
  • mgr – The transport manager.

  • tpf – Transport factory.

Returns:

PJ_SUCCESS is sucessfully unregistered.

pj_status_t pjsip_tpmgr_create(pj_pool_t *pool, pjsip_endpoint *endpt, pjsip_rx_callback rx_cb, pjsip_tx_callback tx_cb, pjsip_tpmgr **p_mgr)

Create a transport manager. Normally application doesn’t need to call this function directly, since a transport manager will be created and destroyed automatically by the SIP endpoint.

Parameters:
  • pool – Pool.

  • endpt – Endpoint instance.

  • rx_cb – Callback to receive incoming message.

  • tx_cb – Callback to be called before transport manager is sending outgoing message.

  • p_mgr – Pointer to receive the new transport manager.

Returns:

PJ_SUCCESS or the appropriate error code on error.

pj_status_t pjsip_tpmgr_find_local_addr(pjsip_tpmgr *tpmgr, pj_pool_t *pool, pjsip_transport_type_e type, const pjsip_tpselector *sel, pj_str_t *ip_addr, int *port)

Find out the appropriate local address info (IP address and port) to advertise in Contact header based on the remote address to be contacted. The local address info would be the address name of the transport or listener which will be used to send the request.

In this implementation, it will only select the transport based on the transport type in the request.

Parameters:
  • tpmgr – The transport manager.

  • pool – Pool to allocate memory for the IP address.

  • type – Destination address to contact.

  • sel – Optional pointer to prefered transport, if any.

  • ip_addr – Pointer to receive the IP address.

  • port – Pointer to receive the port number.

Returns:

PJ_SUCCESS, or the appropriate error code.

void pjsip_tpmgr_fla2_param_default(pjsip_tpmgr_fla2_param *prm)

Initialize with default values.

Parameters:

prm – The parameter to be initialized.

pj_status_t pjsip_tpmgr_find_local_addr2(pjsip_tpmgr *tpmgr, pj_pool_t *pool, pjsip_tpmgr_fla2_param *prm)

Find out the appropriate local address info (IP address and port) to advertise in Contact or Via header header based on the remote address to be contacted. The local address info would be the address name of the transport or listener which will be used to send the request.

Parameters:
  • tpmgr – The transport manager.

  • pool – Pool to allocate memory for the IP address.

  • prm – Function input and output parameters.

Returns:

PJ_SUCCESS, or the appropriate error code.

unsigned pjsip_tpmgr_get_transport_count(pjsip_tpmgr *mgr)

Return number of transports currently registered to the transport manager.

Parameters:

mgr – The transport manager.

Returns:

Number of transports.

pj_status_t pjsip_tpmgr_destroy(pjsip_tpmgr *mgr)

Destroy a transport manager. Normally application doesn’t need to call this function directly, since a transport manager will be created and destroyed automatically by the SIP endpoint.

Parameters:

mgr – The transport manager.

Returns:

PJ_SUCCESS on success.

void pjsip_tpmgr_dump_transports(pjsip_tpmgr *mgr)

Dump transport info and status to log.

Parameters:

mgr – The transport manager.

void pjsip_tpmgr_shutdown_param_default(pjsip_tpmgr_shutdown_param *prm)

Initialize transports shutdown parameter with default values.

Parameters:

prm – The parameter to be initialized.

pj_status_t pjsip_tpmgr_shutdown_all(pjsip_tpmgr *mgr, const pjsip_tpmgr_shutdown_param *param)

Shutdown all transports. This basically invokes pjsip_transport_shutdown2() on all transports.

Parameters:
  • mgr – The transport manager.

  • param – The function parameters.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_tpmgr_acquire_transport(pjsip_tpmgr *mgr, pjsip_transport_type_e type, const pj_sockaddr_t *remote, int addr_len, const pjsip_tpselector *sel, pjsip_transport **tp)

Find transport to be used to send message to remote destination. If no suitable transport is found, a new one will be created.

This is an internal function since normally application doesn’t have access to transport manager. Application should use pjsip_endpt_acquire_transport() instead.

Parameters:
  • mgr – The transport manager instance.

  • type – The type of transport to be acquired.

  • remote – The remote address to send message to.

  • addr_len – Length of the remote address.

  • sel – Optional pointer to transport selector instance which is used to find explicit transport, if required.

  • tp – Pointer to receive the transport instance, if one is found.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsip_tpmgr_acquire_transport2(pjsip_tpmgr *mgr, pjsip_transport_type_e type, const pj_sockaddr_t *remote, int addr_len, const pjsip_tpselector *sel, pjsip_tx_data *tdata, pjsip_transport **tp)

Find suitable transport for sending SIP message to specified remote destination by also considering the outgoing SIP message. If no suitable transport is found, a new one will be created.

This is an internal function since normally application doesn’t have access to transport manager. Application should use pjsip_endpt_acquire_transport2() instead.

Parameters:
  • mgr – The transport manager instance.

  • type – The type of transport to be acquired.

  • remote – The remote address to send message to.

  • addr_len – Length of the remote address.

  • sel – Optional pointer to transport selector instance which is used to find explicit transport, if required.

  • tdata – Optional pointer to data to be sent.

  • tp – Pointer to receive the transport instance, if one is found.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsip_transport_send(pjsip_transport *tr, pjsip_tx_data *tdata, const pj_sockaddr_t *addr, int addr_len, void *token, pjsip_tp_send_callback cb)

This is a low-level function to send a SIP message using the specified transport to the specified destination.

Parameters:
  • tr – The SIP transport to be used.

  • tdata – Transmit data buffer containing SIP message.

  • addr – Destination address.

  • addr_len – Length of destination address.

  • token – Arbitrary token to be returned back to callback.

  • cb – Optional callback to be called to notify caller about the completion status of the pending send operation.

Returns:

If the message has been sent successfully, this function will return PJ_SUCCESS and the callback will not be called. If message cannot be sent immediately, this function will return PJ_EPENDING, and application will be notified later about the completion via the callback. Any statuses other than PJ_SUCCESS or PJ_EPENDING indicates immediate failure, and in this case the callback will not be called.

pj_status_t pjsip_tpmgr_send_raw(pjsip_tpmgr *mgr, pjsip_transport_type_e tp_type, const pjsip_tpselector *sel, pjsip_tx_data *tdata, const void *raw_data, pj_size_t data_len, const pj_sockaddr_t *addr, int addr_len, void *token, pjsip_tp_send_callback cb)

This is a low-level function to send raw data to a destination.

See also pjsip_endpt_send_raw() and pjsip_endpt_send_raw_to_uri().

Parameters:
  • mgr – Transport manager.

  • tp_type – Transport type.

  • sel – Optional pointer to transport selector instance if application wants to use a specific transport instance rather then letting transport manager finds the suitable transport.

  • tdata – Optional transmit data buffer to be used. If this value is NULL, this function will create one internally. If tdata is specified, this function will decrement the reference counter upon completion.

  • raw_data – The data to be sent.

  • data_len – The length of the data.

  • addr – Destination address.

  • addr_len – Length of destination address.

  • token – Arbitrary token to be returned back to callback.

  • cb – Optional callback to be called to notify caller about the completion status of the pending send operation.

Returns:

If the message has been sent successfully, this function will return PJ_SUCCESS and the callback will not be called. If message cannot be sent immediately, this function will return PJ_EPENDING, and application will be notified later about the completion via the callback. Any statuses other than PJ_SUCCESS or PJ_EPENDING indicates immediate failure, and in this case the callback will not be called.

pj_status_t pjsip_tpmgr_set_state_cb(pjsip_tpmgr *mgr, pjsip_tp_state_callback cb)

Set callback of global transport state notification. The caller will be notified whenever the state of any transport is changed. The type of events are defined in pjsip_transport_state.

Note that this function will override the existing callback, if any, so application is recommended to keep the old callback and manually forward the notification to the old callback, otherwise other component that concerns about the transport state will no longer receive transport state events.

Parameters:
  • mgr – Transport manager.

  • cb – Callback to be called to notify caller about transport state changing.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pjsip_tp_state_callback pjsip_tpmgr_get_state_cb(const pjsip_tpmgr *mgr)

Get the callback of global transport state notification.

Parameters:

mgr – Transport manager.

Returns:

The transport state callback or NULL if it is not set.

pj_status_t pjsip_transport_add_state_listener(pjsip_transport *tp, pjsip_tp_state_callback cb, void *user_data, pjsip_tp_state_listener_key **key)

Add a listener to the specified transport for transport state notification.

Parameters:
  • tp – The transport.

  • cb – Callback to be called to notify listener about transport state changing.

  • user_data – The user data.

  • key – Output key, used to remove this listener.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsip_transport_remove_state_listener(pjsip_transport *tp, pjsip_tp_state_listener_key *key, const void *user_data)

Remove a listener from the specified transport for transport state notification.

Parameters:
  • tp – The transport.

  • key – The listener key.

  • user_data – The user data, for validation purpose.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsip_tpmgr_set_drop_data_cb(pjsip_tpmgr *mgr, pjsip_tp_on_rx_dropped_cb cb)

Set callback of data dropping. The caller will be notified whenever any received data is dropped (due to leading newlines or keep-alive packet or invalid SIP message). This callback can be useful for application, for example, to implement custom keep-alive mechanism or connection availability detection.

Parameters:
  • mgr – Transport manager.

  • cb – The callback function, set to NULL to reset the callback.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsip_tpmgr_set_recv_data_cb(pjsip_tpmgr *mgr, pjsip_tp_on_rx_data_cb cb)

Set callback to be called whenever any data is received by a stream oriented transport. This can be useful for application to do its own verification, filtering, or logging of potential malicious activities.

Parameters:
  • mgr – Transport manager.

  • cb – The callback function, set to NULL to reset the callback.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

struct pjsip_tpselector
#include <sip_transport.h>

This structure describes the transport/listener preference to be used when sending outgoing requests.

Normally transport will be selected automatically according to rules about sending requests. But some applications (such as proxies or B2BUAs) may want to explicitly use specific transport to send requests, for example when they want to make sure that outgoing request should go from a specific network interface.

The pjsip_tpselector structure is used for that purpose, i.e. to allow application specificly request that a particular transport/listener should be used to send request. This structure is used when calling pjsip_tsx_set_transport() and pjsip_dlg_set_transport().

If application disables connection reuse and wants to force creating a new transport, it needs to consider the following couple of things:

  • If it still wants to reuse an existing transport (if any), it needs to keep a reference to that transport and specifically set the transport to be used for sending requests.

  • Delete those existing transports manually when no longer needed.

Public Members

pjsip_tpselector_type type

The type of data in the union

pj_bool_t disable_connection_reuse

Whether to disable reuse of an existing connection. This setting will be ignored if (type == PJSIP_TPSELECTOR_TRANSPORT) and transport in the union below is set.

union pjsip_tpselector::[anonymous] u

Union representing the transport/listener/IP version criteria to be used.

struct pjsip_rx_data_op_key
#include <sip_transport.h>

A customized ioqueue async operation key which is used by transport to locate rdata when a pending read operation completes.

Public Members

pj_ioqueue_op_key_t op_key

ioqueue op_key.

pjsip_rx_data *rdata

rdata associated with this

struct pjsip_rx_data
#include <sip_transport.h>

Incoming message buffer. This structure keep all the information regarding the received message. This buffer lifetime is only very short, normally after the transaction has been called, this buffer will be deleted/recycled. So care must be taken when allocating storage from the pool of this buffer.

Forward declaration for receive data/buffer (sip_transport.h).

Public Members

pj_pool_t *pool

Memory pool for this buffer.

pjsip_transport *transport

The transport object which received this packet.

void *tp_data

Other transport specific data to be attached to this buffer.

pjsip_rx_data_op_key op_key

Ioqueue key.

struct pjsip_rx_data::[anonymous] tp_info

tp_info is part of rdata that remains static for the duration of the buffer. It is initialized when the buffer was created by transport.

pj_time_val timestamp

Time when the message was received.

char packet[PJSIP_MAX_PKT_LEN]

Pointer to the original packet.

pj_uint32_t zero

Zero termination for the packet.

pj_ssize_t len

The length of the packet received.

pj_sockaddr src_addr

The source address from which the packet was received.

int src_addr_len

The length of the source address.

char src_name[PJ_INET6_ADDRSTRLEN]

The IP source address string (NULL terminated).

int src_port

The IP source port number.

struct pjsip_rx_data::[anonymous] pkt_info

pkt_info is initialized by transport when it receives an incoming packet.

char *msg_buf

Start of msg buffer.

int len

Length fo message.

pjsip_msg *msg

The parsed message, if any.

char *info

Short description about the message. Application should use pjsip_rx_data_get_info() instead.

pjsip_cid_hdr *cid

The Call-ID header as found in the message.

pjsip_from_hdr *from

The From header as found in the message.

pjsip_to_hdr *to

The To header as found in the message.

pjsip_via_hdr *via

The topmost Via header as found in the message.

pjsip_cseq_hdr *cseq

The CSeq header as found in the message.

pjsip_max_fwd_hdr *max_fwd

Max forwards header.

pjsip_route_hdr *route

The first route header.

pjsip_rr_hdr *record_route

The first record-route header.

pjsip_ctype_hdr *ctype

Content-type header.

pjsip_clen_hdr *clen

Content-length header.

pjsip_require_hdr *require

“Require” header containing aggregates of all Require headers found in the message, or NULL.

pjsip_supported_hdr *supported

“Supported” header containing aggregates of all Supported headers found in the message, or NULL.

pjsip_parser_err_report parse_err

The list of error generated by the parser when parsing this message.

struct pjsip_rx_data::[anonymous] msg_info

msg_info is initialized by transport mgr (tpmgr) before this buffer is passed to endpoint.

void *mod_data[PJSIP_MAX_MODULE]

Data attached by modules to this message.

struct pjsip_rx_data::[anonymous] endpt_info

endpt_info is initialized by endpoint after this buffer reaches endpoint.

struct pjsip_tx_data_op_key
#include <sip_transport.h>

Customized ioqueue async operation key, used by transport to keep callback parameters.

Public Members

pj_ioqueue_op_key_t key

ioqueue pending operation key.

pjsip_tx_data *tdata

Transmit data associated with this key.

void *token

Arbitrary token (attached by transport)

void (*callback)(pjsip_transport*, void*, pj_ssize_t)

Callback to be called when pending transmit operation has completed.

struct pjsip_tx_data
#include <sip_transport.h>

Data structure for sending outgoing message. Application normally creates this buffer by calling pjsip_endpt_create_tdata.

The lifetime of this buffer is controlled by the reference counter in this structure, which is manipulated by calling pjsip_tx_data_add_ref and pjsip_tx_data_dec_ref. When the reference counter has reached zero, then this buffer will be destroyed.

A transaction object normally will add reference counter to this buffer when application calls pjsip_tsx_send_msg, because it needs to keep the message for retransmission. The transaction will release the reference counter once its state has reached final state.

Forward declaration for transmit data/buffer (sip_transport.h).

Public Functions

PJ_DECL_LIST_MEMBER(struct pjsip_tx_data)

This is for transmission queue; it’s managed by transports.

Public Members

pj_pool_t *pool

Memory pool for this buffer.

char obj_name[PJ_MAX_OBJ_NAME]

A name to identify this buffer.

char *info

Short information describing this buffer and the message in it. Application should use pjsip_tx_data_get_info() instead of directly accessing this member.

pj_time_val rx_timestamp

For response message, this contains the reference to timestamp when the original request message was received. The value of this field is set when application creates response message to a request by calling pjsip_endpt_create_response.

pjsip_tpmgr *mgr

The transport manager for this buffer.

pjsip_tx_data_op_key op_key

Ioqueue asynchronous operation key.

pj_lock_t *lock

Lock object.

pjsip_msg *msg

The message in this buffer.

pjsip_route_hdr *saved_strict_route

Strict route header saved by pjsip_process_route_set(), to be restored by pjsip_restore_strict_route_set().

pjsip_buffer buf

Buffer to the printed text representation of the message. When the content of this buffer is set, then the transport will send the content of this buffer instead of re-printing the message structure. If the message structure has changed, then application must invalidate this buffer by calling pjsip_tx_data_invalidate_msg.

pj_atomic_t *ref_cnt

Reference counter.

int is_pending

Being processed by transport?

void *token

Transport manager internal.

void (*cb)(void*, pjsip_tx_data*, pj_ssize_t)

Callback to be called when this tx_data has been transmitted.

pj_str_t name

Server name.

pjsip_server_addresses addr

Server addresses resolved.

unsigned cur_addr

Current server address being tried.

struct pjsip_tx_data::[anonymous] dest_info

Destination information, to be used to determine the network address of the message. For a request, this information is initialized when the request is sent with pjsip_endpt_send_request_stateless() and network address is resolved. For CANCEL request, this information will be copied from the original INVITE to make sure that the CANCEL request goes to the same physical network address as the INVITE request.

pjsip_transport *transport

Transport being used.

pj_sockaddr dst_addr

Destination address.

int dst_addr_len

Length of address.

char dst_name[PJ_INET6_ADDRSTRLEN]

Destination address.

int dst_port

Destination port.

struct pjsip_tx_data::[anonymous] tp_info

Transport information, only valid during on_tx_request() and on_tx_response() callback.

pjsip_tpselector tp_sel

Transport selector, to specify which transport to be used. The value here must be set with pjsip_tx_data_set_transport(), to allow reference counter to be set properly.

pj_bool_t auth_retry

Special flag to indicate that this transmit data is a request that has been updated with proper authentication response and is ready to be sent for retry.

void *mod_data[PJSIP_MAX_MODULE]

Arbitrary data attached by PJSIP modules.

pjsip_host_port via_addr

If via_addr is set, it will be used as the “sent-by” field of the Via header for outgoing requests as long as the request uses via_tp transport. Normally application should not use or access these fields. Via address.

const void *via_tp

Via transport.

struct pjsip_transport_key
#include <sip_transport.h>

This structure describes transport key to be registered to hash table.

Public Members

long type

Transport type.

pj_sockaddr rem_addr

Destination address.

struct pjsip_transport
#include <sip_transport.h>

This structure represent the “public” interface of a SIP transport. Applications normally extend this structure to include transport specific members.

Forward declaration for SIP transport.

Public Members

char obj_name[PJ_MAX_OBJ_NAME]

Name.

pj_pool_t *pool

Pool used by transport.

pj_atomic_t *ref_cnt

Reference counter.

pj_lock_t *lock

Lock object.

pj_grp_lock_t *grp_lock

Group lock for sync with ioqueue and timer.

pj_bool_t tracing

Tracing enabled?

pj_bool_t is_shutdown

Being shutdown?

pj_bool_t is_destroying

Destroy in progress?

pjsip_transport_key key

Key for indexing this transport in hash table.

char *type_name

Type name.

unsigned flag

pjsip_transport_flags_e

char *info

Transport info/description.

int addr_len

Length of addresses.

pj_sockaddr local_addr

Bound address.

pjsip_host_port local_name

Published name (eg. STUN).

pjsip_host_port remote_name

Remote address name.

pjsip_transport_dir dir

Connection direction.

pjsip_endpoint *endpt

Endpoint instance.

pjsip_tpmgr *tpmgr

Transport manager.

pjsip_tpfactory *factory

Factory instance. Note: it may be invalid/shutdown.

pj_timer_entry idle_timer

Timer when ref cnt is zero.

pj_timestamp last_recv_ts

Last time receiving data.

pj_size_t last_recv_len

Last received data length.

void *data

Internal transport data.

unsigned initial_timeout

Initial timeout interval to be applied to incoming TCP/TLS transports when no valid data received after a successful connection.

pj_status_t (*send_msg)(pjsip_transport *transport, pjsip_tx_data *tdata, const pj_sockaddr_t *rem_addr, int addr_len, void *token, pjsip_transport_callback callback)

Function to be called by transport manager to send SIP message.

Param transport:

The transport to send the message.

Param packet:

The buffer to send.

Param length:

The length of the buffer to send.

Param op_key:

Completion token, which will be supplied to caller when pending send operation completes.

Param rem_addr:

The remote destination address.

Param addr_len:

Size of remote address.

Param callback:

If supplied, the callback will be called once a pending transmission has completed. If the function completes immediately (i.e. return code is not PJ_EPENDING), the callback will not be called.

Return:

Should return PJ_SUCCESS only if data has been succesfully queued to operating system for transmission. Otherwise it may return PJ_EPENDING if the underlying transport can not send the data immediately and will send it later, which in this case caller doesn’t have to do anything except wait the calback to be called, if it supplies one. Other return values indicate the error code.

pj_status_t (*do_shutdown)(pjsip_transport *transport)

Instruct the transport to initiate graceful shutdown procedure. After all objects release their reference to this transport, the transport will be deleted.

Note that application MUST use pjsip_transport_shutdown() instead.

Param transport:

The transport.

Return:

PJ_SUCCESS on success.

pj_status_t (*destroy)(pjsip_transport *transport)

Forcefully destroy this transport regardless whether there are objects that currently use this transport. This function should only be called by transport manager or other internal objects (such as the transport itself) who know what they’re doing. Application should use pjsip_transport_shutdown() instead.

Param transport:

The transport.

Return:

PJ_SUCCESS on success.

struct pjsip_tpfactory
#include <sip_transport.h>

A transport factory is normally used for connection oriented transports (such as TCP or TLS) to create instances of transports. It registers a new transport type to the transport manager, and the transport manager would ask the factory to create a transport instance when it received command from application to send a SIP message using the specified transport type.

Public Functions

PJ_DECL_LIST_MEMBER(struct pjsip_tpfactory)

This list is managed by transport manager.

Public Members

char obj_name[PJ_MAX_OBJ_NAME]

Name.

pj_pool_t *pool

Owned memory pool.

pj_lock_t *lock

Lock object.

pjsip_transport_type_e type

Transport type.

char *type_name

Type string name.

unsigned flag

Transport flag.

char *info

Transport info/description.

pj_sockaddr local_addr

Bound address.

pjsip_host_port addr_name

Published name.

pj_status_t (*create_transport)(pjsip_tpfactory *factory, pjsip_tpmgr *mgr, pjsip_endpoint *endpt, const pj_sockaddr *rem_addr, int addr_len, pjsip_transport **transport)

Create new outbound connection suitable for sending SIP message to specified remote address. Note that the factory is responsible for both creating the transport and registering it to the transport manager.

pj_status_t (*create_transport2)(pjsip_tpfactory *factory, pjsip_tpmgr *mgr, pjsip_endpoint *endpt, const pj_sockaddr *rem_addr, int addr_len, pjsip_tx_data *tdata, pjsip_transport **transport)

Create new outbound connection suitable for sending SIP message to specified remote address by also considering outgoing SIP message data. Note that the factory is responsible for both creating the transport and registering it to the transport manager.

pj_status_t (*destroy)(pjsip_tpfactory *factory)

Destroy the listener.

struct pjsip_tpmgr_fla2_param
#include <sip_transport.h>

Parameter for pjsip_tpmgr_find_local_addr2() function.

Public Members

pjsip_transport_type_e tp_type

Specify transport type to use. This must be set.

const pjsip_tpselector *tp_sel

Optional pointer to preferred transport, if any.

pj_str_t dst_host

Destination host, if known. The destination host is needed if local_if field below is set.

pj_bool_t local_if

Specify if the function should return which local interface to use for the specified destination in dst_host. By definition, the returned address will always be local interface address.

pj_str_t ret_addr

The returned address.

pj_uint16_t ret_port

The returned port.

const void *ret_tp

Returned pointer to the transport. Only set if local_if is set.

struct pjsip_tpmgr_shutdown_param
#include <sip_transport.h>

Parameter for pjsip_tpmgr_shutdown_all() function.

Public Members

pj_bool_t force

Specify whether disconnection state notification should be sent immediately, see pjsip_transport_shutdown2() for more info.

Default: PJ_TRUE.

pj_bool_t include_udp

Specify whether UDP transports should also be shutdown.

Default: PJ_TRUE.

struct pjsip_transport_state_info
#include <sip_transport.h>

Structure of transport state info passed by pjsip_tp_state_callback.

Public Members

pj_status_t status

The last error code related to the transport state.

void *ext_info

Optional extended info, the content is specific for each transport type.

void *user_data

Optional user data. In global transport state notification, this will always be NULL.

struct pjsip_tp_dropped_data
#include <sip_transport.h>

Structure of dropped received data.

Public Members

pjsip_transport *tp

The transport receiving the data.

void *data

The data.

pj_size_t len

The data length. If the status field below indicates an invalid SIP message (PJSIP_EINVALIDMSG) and application detects a SIP message at position p, it can pass the data back to PJSIP to be processed by setting the len to p. This can be useful for apps which wishes to use the same transport for SIP signalling and non-SIP purposes (such as SIP outbound using STUN message).

pj_status_t status

The status or reason of drop. For example, a leading newlines (common keep-alive packet) will be dropped with status PJ_EIGNORED, an invalid SIP message will have status PJSIP_EINVALIDMSG, a SIP message overflow will have status PJSIP_ERXOVERFLOW.

struct pjsip_tp_rx_data
#include <sip_transport.h>

Structure of received data that will be passed to data received notification callback.

Public Members

pjsip_transport *tp

The transport receiving the data.

void *data

The data.

pj_size_t len

The data length. If application wishes to discard some data of len p, it can pass the remaining data back to PJSIP to be processed by setting the len to (len - p). If application wants to shutdown the transport from within the callback (for example after if finds out that the data is suspicious/garbage), app must set the len to zero to prevent further processing of the data.