This is the transport framework. More...

Modules
	SIP SRV Server Resolution (RFC 3263 - Locating SIP Servers)
	Framework to resolve SIP servers based on RFC 3263.

	Loop Transport
	Loopback transport (for testing purposes).The loopback transport simply bounce back outgoing messages as incoming messages. This feature is used mostly during automated testing, to provide controlled behavior.

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

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

	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.

Data Structures
struct	pjsip_tpselector

struct	pjsip_rx_data_op_key

struct	pjsip_rx_data

struct	pjsip_tx_data_op_key

struct	pjsip_tx_data

struct	pjsip_transport_key

struct	pjsip_transport

struct	pjsip_tpfactory

struct	pjsip_tpmgr_fla2_param

struct	pjsip_transport_state_info

struct	pjsip_tp_dropped_data

Macros
#define	PJSIP_TRANSPORT_IS_RELIABLE(tp) ((tp)->flag & PJSIP_TRANSPORT_RELIABLE)

#define	PJSIP_TRANSPORT_IS_SECURE(tp) ((tp)->flag & PJSIP_TRANSPORT_SECURE)

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

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

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

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

typedef void	pjsip_tp_state_listener_key

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

typedef void(*	pjsip_tp_on_rx_dropped_cb) (pjsip_tp_dropped_data *data)

Enumerations
enum	pjsip_transport_flags_e { PJSIP_TRANSPORT_RELIABLE = 1 , PJSIP_TRANSPORT_SECURE = 2 , PJSIP_TRANSPORT_DATAGRAM = 4 }

enum	pjsip_tpselector_type { PJSIP_TPSELECTOR_NONE , PJSIP_TPSELECTOR_TRANSPORT , PJSIP_TPSELECTOR_LISTENER }

enum	pjsip_transport_dir { PJSIP_TP_DIR_NONE , PJSIP_TP_DIR_OUTGOING , PJSIP_TP_DIR_INCOMING }

enum	pjsip_transport_state { PJSIP_TP_STATE_CONNECTED , PJSIP_TP_STATE_DISCONNECTED , PJSIP_TP_STATE_SHUTDOWN , PJSIP_TP_STATE_DESTROY }

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

pjsip_transport_type_e	pjsip_transport_get_type_from_name (const pj_str_t *name)

pjsip_transport_type_e	pjsip_transport_get_type_from_flag (unsigned flag)

int	pjsip_transport_type_get_af (pjsip_transport_type_e type)

unsigned	pjsip_transport_get_flag_from_type (pjsip_transport_type_e type)

int	pjsip_transport_get_default_port_for_type (pjsip_transport_type_e type)

const char *	pjsip_transport_get_type_name (pjsip_transport_type_e t)

const char *	pjsip_transport_get_type_desc (pjsip_transport_type_e t)

void	pjsip_tpselector_add_ref (pjsip_tpselector *sel)

void	pjsip_tpselector_dec_ref (pjsip_tpselector *sel)

char *	pjsip_rx_data_get_info (pjsip_rx_data *rdata)

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

pj_status_t	pjsip_rx_data_free_cloned (pjsip_rx_data *rdata)

pj_status_t	pjsip_tx_data_create (pjsip_tpmgr mgr, pjsip_tx_data *tdata)

void	pjsip_tx_data_add_ref (pjsip_tx_data *tdata)

pj_status_t	pjsip_tx_data_dec_ref (pjsip_tx_data *tdata)

pj_status_t	pjsip_tx_data_encode (pjsip_tx_data *tdata)

pj_bool_t	pjsip_tx_data_is_valid (pjsip_tx_data *tdata)

void	pjsip_tx_data_invalidate_msg (pjsip_tx_data *tdata)

char *	pjsip_tx_data_get_info (pjsip_tx_data *tdata)

pj_status_t	pjsip_tx_data_set_transport (pjsip_tx_data tdata, const pjsip_tpselector sel)

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

pj_status_t	pjsip_transport_register (pjsip_tpmgr mgr, pjsip_transport tp)

pj_status_t	pjsip_transport_shutdown (pjsip_transport *tp)

pj_status_t	pjsip_transport_shutdown2 (pjsip_transport *tp, pj_bool_t force)

pj_status_t	pjsip_transport_destroy (pjsip_transport *tp)

pj_status_t	pjsip_transport_add_ref (pjsip_transport *tp)

pj_status_t	pjsip_transport_dec_ref (pjsip_transport *tp)

pj_ssize_t	pjsip_tpmgr_receive_packet (pjsip_tpmgr mgr, pjsip_rx_data rdata)

pj_status_t	pjsip_tpmgr_register_tpfactory (pjsip_tpmgr mgr, pjsip_tpfactory tpf)

pj_status_t	pjsip_tpmgr_unregister_tpfactory (pjsip_tpmgr mgr, pjsip_tpfactory tpf)

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)

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)

void	pjsip_tpmgr_fla2_param_default (pjsip_tpmgr_fla2_param *prm)

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

unsigned	pjsip_tpmgr_get_transport_count (pjsip_tpmgr *mgr)

pj_status_t	pjsip_tpmgr_destroy (pjsip_tpmgr *mgr)

void	pjsip_tpmgr_dump_transports (pjsip_tpmgr *mgr)

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)

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)

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)

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)

pj_status_t	pjsip_tpmgr_set_state_cb (pjsip_tpmgr *mgr, pjsip_tp_state_callback cb)

pjsip_tp_state_callback	pjsip_tpmgr_get_state_cb (const pjsip_tpmgr *mgr)

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)

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

pj_status_t	pjsip_tpmgr_set_drop_data_cb (pjsip_tpmgr *mgr, pjsip_tp_on_rx_dropped_cb cb)

Detailed Description

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.

Macro Definition Documentation

◆ PJSIP_TRANSPORT_IS_RELIABLE

#define PJSIP_TRANSPORT_IS_RELIABLE ( tp ) ((tp)->flag & PJSIP_TRANSPORT_RELIABLE)

Check if transport tp is reliable.

◆ PJSIP_TRANSPORT_IS_SECURE

#define PJSIP_TRANSPORT_IS_SECURE ( tp ) ((tp)->flag & PJSIP_TRANSPORT_SECURE)

Check if transport tp is secure.

Typedef Documentation

◆ pjsip_transport_callback

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

Type of callback to receive transport operation status.

◆ pjsip_rx_callback

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.

Parameters

ep	Endpoint.
status	Receiption status.
rd	Received packet.

◆ pjsip_tx_callback

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.

Parameters

ep	Endpoint.
td	Transmit data.

◆ pjsip_tp_send_callback

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.

Parameters

token	The token that was given when calling the function to send message or raw data.
tdata	The transmit buffer used to send the message.
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).

◆ pjsip_tp_state_listener_key

typedef void pjsip_tp_state_listener_key

Definition of transport state listener key.

◆ pjsip_tp_state_callback

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.

Parameters

tp	The transport instance.
state	The transport state.
info	The transport state info.

◆ pjsip_tp_on_rx_dropped_cb

typedef void(* pjsip_tp_on_rx_dropped_cb) (pjsip_tp_dropped_data *data)

Type of callback to data dropping notifications.

Parameters

data	The dropped data.

Enumeration Type Documentation

◆ pjsip_transport_flags_e

enum pjsip_transport_flags_e

Flags for SIP transports.

Enumerator
PJSIP_TRANSPORT_RELIABLE	Transport is reliable.
PJSIP_TRANSPORT_SECURE	Transport is secure.
PJSIP_TRANSPORT_DATAGRAM	Datagram based transport. (it's also assumed to be connectionless)

◆ pjsip_tpselector_type

enum pjsip_tpselector_type

This structure describes the type of data in pjsip_tpselector.

Enumerator
PJSIP_TPSELECTOR_NONE	Transport is not specified.
PJSIP_TPSELECTOR_TRANSPORT	Use the specific transport to send request.
PJSIP_TPSELECTOR_LISTENER	Use the specific listener to send request.

◆ pjsip_transport_dir

enum pjsip_transport_dir

Enumeration of transport direction types.

Enumerator
PJSIP_TP_DIR_NONE	Direction not set, normally used by connectionless transports such as UDP transport.
PJSIP_TP_DIR_OUTGOING	Outgoing connection or client mode, this is only for connection-oriented transports.
PJSIP_TP_DIR_INCOMING	Incoming connection or server mode, this is only for connection-oriented transports.

◆ pjsip_transport_state

enum pjsip_transport_state

Enumeration of transport state types.

Enumerator
PJSIP_TP_STATE_CONNECTED	Transport connected, applicable only to connection-oriented transports such as TCP and TLS.
PJSIP_TP_STATE_DISCONNECTED	Transport disconnected, applicable only to connection-oriented transports such as TCP and TLS.
PJSIP_TP_STATE_SHUTDOWN	Transport shutdown, either due to TCP/TLS disconnect error from the network, or when shutdown is initiated by PJSIP itself.
PJSIP_TP_STATE_DESTROY	Transport destroy, when transport is about to be destroyed.

Function Documentation

◆ pjsip_transport_register_type()

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_get_type_from_name()

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_get_type_from_flag()

pjsip_transport_type_e pjsip_transport_get_type_from_flag ( unsigned flag )

Get the transport type for the specified flags.

Parameters

flag	The transport flag.

Returns: Transport type.

◆ pjsip_transport_type_get_af()

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.

◆ pjsip_transport_get_flag_from_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.

◆ pjsip_transport_get_default_port_for_type()

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.

◆ pjsip_transport_get_type_name()

const char * pjsip_transport_get_type_name ( pjsip_transport_type_e t )

Get transport type name.

Parameters

t	Transport type.

Returns: Transport name.

◆ pjsip_transport_get_type_desc()

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.

◆ pjsip_tpselector_add_ref()

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.

◆ pjsip_tpselector_dec_ref()

void pjsip_tpselector_dec_ref ( pjsip_tpselector * sel )

Decrement transport/listener reference in the selector.

Parameters

sel	The transport selector

◆ pjsip_rx_data_get_info()

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.

◆ pjsip_rx_data_clone()

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.

◆ pjsip_rx_data_free_cloned()

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.

◆ pjsip_tx_data_create()

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.

See also: pjsip_endpt_create_tdata

◆ pjsip_tx_data_add_ref()

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.

◆ pjsip_tx_data_dec_ref()

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.

◆ pjsip_tx_data_encode()

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.

◆ pjsip_tx_data_is_valid()

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.

◆ pjsip_tx_data_invalidate_msg()

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.

◆ pjsip_tx_data_get_info()

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.

◆ pjsip_tx_data_set_transport()

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.

◆ pjsip_tx_data_clone()

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.

◆ pjsip_transport_register()

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.

◆ pjsip_transport_shutdown()

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.

◆ pjsip_transport_shutdown2()

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.

◆ pjsip_transport_destroy()

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.

◆ pjsip_transport_add_ref()

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.

◆ pjsip_transport_dec_ref()

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.

◆ pjsip_tpmgr_receive_packet()

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.

◆ pjsip_tpmgr_register_tpfactory()

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.

◆ pjsip_tpmgr_unregister_tpfactory()

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.

◆ pjsip_tpmgr_create()

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.

◆ pjsip_tpmgr_find_local_addr()

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.

See also: pjsip_tpmgr_find_local_addr2()

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.

◆ pjsip_tpmgr_fla2_param_default()

void pjsip_tpmgr_fla2_param_default ( pjsip_tpmgr_fla2_param * prm )

Initialize with default values.

Parameters

prm	The parameter to be initialized.

◆ pjsip_tpmgr_find_local_addr2()

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.

See also: pjsip_tpmgr_find_local_addr()

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.

◆ pjsip_tpmgr_get_transport_count()

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.

◆ pjsip_tpmgr_destroy()

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.

◆ pjsip_tpmgr_dump_transports()

void pjsip_tpmgr_dump_transports ( pjsip_tpmgr * mgr )

Dump transport info and status to log.

Parameters

mgr	The transport manager.

◆ pjsip_tpmgr_acquire_transport()

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.

◆ pjsip_tpmgr_acquire_transport2()

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.

◆ pjsip_transport_send()

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.

◆ pjsip_tpmgr_send_raw()

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.

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.

◆ pjsip_tpmgr_set_state_cb()

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_tpmgr_get_state_cb()

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.

◆ pjsip_transport_add_state_listener()

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.

◆ pjsip_transport_remove_state_listener()

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.

◆ pjsip_tpmgr_set_drop_data_cb()

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.

References PJ_END_DECL.

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PJSIP_TRANSPORT_IS_RELIABLE

◆ PJSIP_TRANSPORT_IS_SECURE

Typedef Documentation

◆ pjsip_transport_callback

◆ pjsip_rx_callback

◆ pjsip_tx_callback

◆ pjsip_tp_send_callback

◆ pjsip_tp_state_listener_key

◆ pjsip_tp_state_callback

◆ pjsip_tp_on_rx_dropped_cb

Enumeration Type Documentation

◆ pjsip_transport_flags_e

◆ pjsip_tpselector_type

◆ pjsip_transport_dir

◆ pjsip_transport_state

Function Documentation

◆ pjsip_transport_register_type()

◆ pjsip_transport_get_type_from_name()

◆ pjsip_transport_get_type_from_flag()

◆ pjsip_transport_type_get_af()

◆ pjsip_transport_get_flag_from_type()

◆ pjsip_transport_get_default_port_for_type()

◆ pjsip_transport_get_type_name()

◆ pjsip_transport_get_type_desc()

◆ pjsip_tpselector_add_ref()

◆ pjsip_tpselector_dec_ref()

◆ pjsip_rx_data_get_info()

◆ pjsip_rx_data_clone()

◆ pjsip_rx_data_free_cloned()

◆ pjsip_tx_data_create()

◆ pjsip_tx_data_add_ref()

◆ pjsip_tx_data_dec_ref()

◆ pjsip_tx_data_encode()

◆ pjsip_tx_data_is_valid()

◆ pjsip_tx_data_invalidate_msg()

◆ pjsip_tx_data_get_info()

◆ pjsip_tx_data_set_transport()

◆ pjsip_tx_data_clone()

◆ pjsip_transport_register()

◆ pjsip_transport_shutdown()

◆ pjsip_transport_shutdown2()

◆ pjsip_transport_destroy()

◆ pjsip_transport_add_ref()

◆ pjsip_transport_dec_ref()

◆ pjsip_tpmgr_receive_packet()

◆ pjsip_tpmgr_register_tpfactory()

◆ pjsip_tpmgr_unregister_tpfactory()

◆ pjsip_tpmgr_create()

◆ pjsip_tpmgr_find_local_addr()

◆ pjsip_tpmgr_fla2_param_default()

◆ pjsip_tpmgr_find_local_addr2()

◆ pjsip_tpmgr_get_transport_count()

◆ pjsip_tpmgr_destroy()

◆ pjsip_tpmgr_dump_transports()

◆ pjsip_tpmgr_acquire_transport()

◆ pjsip_tpmgr_acquire_transport2()

◆ pjsip_transport_send()

◆ pjsip_tpmgr_send_raw()

◆ pjsip_tpmgr_set_state_cb()

◆ pjsip_tpmgr_get_state_cb()

◆ pjsip_transport_add_state_listener()

◆ pjsip_transport_remove_state_listener()

◆ pjsip_tpmgr_set_drop_data_cb()