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.
- Parameters
ep – Endpoint.
status – Receiption status.
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.
- Parameters
ep – Endpoint.
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.
- 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).
-
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.
- Parameters
tp – The transport instance.
state – The transport state.
info – The transport state info.
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)
-
enumerator
-
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
-
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.
-
enumerator
-
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
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 transport type for 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_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_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_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.
-
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.
-
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.
-
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().
-
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.
-
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).
-
struct
pjsip_tx_data_op_key
¶ - #include <sip_transport.h>
Customized ioqueue async operation key, used by transport to keep callback parameters.
-
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).
-
struct
pjsip_transport_key
¶ - #include <sip_transport.h>
This structure describes transport key to be registered to hash table.
-
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.
-
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.
-
struct
pjsip_transport_state_info
¶ - #include <sip_transport.h>
Structure of transport state info passed by pjsip_tp_state_callback.
-