#include <sofia-sip/su_wait.h>
#include <sofia-sip/sip.h>
#include <sofia-sip/nta_tag.h>
Include dependency graph for nta.h:
Go to the source code of this file.
Defines | |
#define | NTA_AGENT_MAGIC_T |
Default type of application context for NTA agents. | |
#define | NTA_LEG_MAGIC_T |
Default type of application context for NTA call legs. | |
#define | NTA_OUTGOING_MAGIC_T |
Default type of application context for outgoing NTA requests. | |
#define | NTA_INCOMING_MAGIC_T |
Default type of application context for incoming NTA requests. | |
#define | NTA_VERSION |
NTA API version number. | |
#define | NTA_RELIABLE_MAGIC_T |
Default type of application context for reliable NTA responses. | |
Typedefs | |
typedef typedefSOFIA_BEGIN_DECLS struct nta_agent_s | nta_agent_t |
NTA agent. | |
typedef nta_leg_s | nta_leg_t |
NTA call leg. | |
typedef nta_outgoing_s | nta_outgoing_t |
NTA outgoing request. | |
typedef nta_incoming_s | nta_incoming_t |
NTA incoming request. | |
typedef NTA_AGENT_MAGIC_T | nta_agent_magic_t |
Application context for NTA agents. | |
typedef NTA_LEG_MAGIC_T | nta_leg_magic_t |
Application context for NTA call legs. | |
typedef NTA_OUTGOING_MAGIC_T | nta_outgoing_magic_t |
Application context for outgoing NTA requests. | |
typedef NTA_INCOMING_MAGIC_T | nta_incoming_magic_t |
Application context for incoming NTA requests. | |
typedef int | nta_message_f (nta_agent_magic_t *context, nta_agent_t *agent, msg_t *msg, sip_t *sip) |
Callback for incoming messages. | |
typedef int | nta_request_f (nta_leg_magic_t *lmagic, nta_leg_t *leg, nta_incoming_t *irq, sip_t const *sip) |
Callback for incoming requests. | |
typedef int | nta_ack_cancel_f (nta_incoming_magic_t *imagic, nta_incoming_t *irq, sip_t const *sip) |
Callback function prototype for CANCELed/ACKed requests. | |
typedef int | nta_response_f (nta_outgoing_magic_t *magic, nta_outgoing_t *request, sip_t const *sip) |
Callback for replies to outgoing requests. | |
typedef nta_reliable_s | nta_reliable_t |
NTA reliable response. | |
typedef NTA_RELIABLE_MAGIC_T | nta_reliable_magic_t |
Application context for reliable NTA requests. | |
Enumerations | |
enum | { NTA_SIP_T1, NTA_SIP_T2, NTA_SIP_T4, NTA_TIME_MAX } |
Functions | |
SOFIAPUBFUN nta_agent_t * | nta_agent_create (su_root_t *root, url_string_t const *name, nta_message_f *callback, nta_agent_magic_t *magic, tag_type_t tag, tag_value_t value,...) |
Create an NTA agent object. | |
SOFIAPUBFUN void | nta_agent_destroy (nta_agent_t *agent) |
Destroy an NTA agent object. | |
SOFIAPUBFUN char const * | nta_agent_version (nta_agent_t const *a) |
Return User-Agent header. | |
SOFIAPUBFUN nta_agent_magic_t * | nta_agent_magic (nta_agent_t const *a) |
Return agent context. | |
SOFIAPUBFUN int | nta_agent_add_tport (nta_agent_t *agent, url_string_t const *url, tag_type_t tag, tag_value_t value,...) |
Add a transport to the agent. | |
SOFIAPUBFUN sip_contact_t * | nta_agent_contact (nta_agent_t const *a) |
Return Contact header. | |
SOFIAPUBFUN sip_via_t * | nta_agent_via (nta_agent_t const *a) |
Return a list of Via headers. | |
SOFIAPUBFUN sip_via_t * | nta_agent_public_via (nta_agent_t const *a) |
Return a list of public (UPnP, STUN) Via headers. | |
SOFIAPUBFUN char const * | nta_agent_newtag (su_home_t *, char const *fmt, nta_agent_t *) |
Calculate a new unique tag. | |
SOFIAPUBFUN int | nta_agent_set_params (nta_agent_t *agent, tag_type_t tag, tag_value_t value,...) |
Set NTA Parameters. | |
SOFIAPUBFUN int | nta_agent_get_params (nta_agent_t *agent, tag_type_t tag, tag_value_t value,...) |
Get NTA Parameters. | |
SOFIAPUBFUN int | nta_agent_get_stats (nta_agent_t *agent, tag_type_t tag, tag_value_t value,...) |
Get NTA statistics. | |
SOFIAPUBFUN msg_t * | nta_msg_create (nta_agent_t *self, int flags) |
Create a new message belonging to the agent. | |
SOFIAPUBFUN int | nta_msg_complete (msg_t *msg) |
Complete a message. | |
SOFIAPUBFUN int | nta_msg_request_complete (msg_t *msg, nta_leg_t *leg, sip_method_t method, char const *method_name, url_string_t const *req_url) |
Complete a request with values from dialog. | |
SOFIAPUBFUN int | nta_is_internal_msg (msg_t const *msg) |
Check if the message is internally generated by NTA. | |
SOFIAPUBFUN nta_leg_t * | nta_leg_tcreate (nta_agent_t *agent, nta_request_f *req_callback, nta_leg_magic_t *magic, tag_type_t tag, tag_value_t value,...) |
Create a new leg object. | |
SOFIAPUBFUN void | nta_leg_destroy (nta_leg_t *leg) |
Destroy a leg. | |
SOFIAPUBFUN nta_leg_t * | nta_default_leg (nta_agent_t const *agent) |
Return the default leg, if any. | |
SOFIAPUBFUN nta_leg_magic_t * | nta_leg_magic (nta_leg_t const *leg, nta_request_f *callback) |
Return application context for the leg. | |
SOFIAPUBFUN void | nta_leg_bind (nta_leg_t *leg, nta_request_f *callback, nta_leg_magic_t *) |
Bind a callback function and context to a leg object. | |
SOFIAPUBFUN char const * | nta_leg_tag (nta_leg_t *leg, char const *tag) |
Add local tag. | |
SOFIAPUBFUN char const * | nta_leg_get_tag (nta_leg_t const *leg) |
Get local tag. | |
SOFIAPUBFUN char const * | nta_leg_rtag (nta_leg_t *leg, char const *tag) |
Add remote tag. | |
SOFIAPUBFUN char const * | nta_leg_get_rtag (nta_leg_t const *leg) |
Get remote tag. | |
SOFIAPUBFUN int | nta_leg_client_route (nta_leg_t *leg, sip_record_route_t const *route, sip_contact_t const *contact) |
Set UAC route. | |
SOFIAPUBFUN int | nta_leg_server_route (nta_leg_t *leg, sip_record_route_t const *route, sip_contact_t const *contact) |
Set UAS route. | |
SOFIAPUBFUN int | nta_leg_get_route (nta_leg_t *leg, sip_route_t const **return_route, sip_contact_t const **return_target) |
Get route. | |
SOFIAPUBFUN nta_leg_t * | nta_leg_by_uri (nta_agent_t const *, url_string_t const *) |
Get leg by destination. | |
SOFIAPUBFUN nta_leg_t * | nta_leg_by_dialog (nta_agent_t const *agent, url_t const *request_uri, sip_call_id_t const *call_id, char const *from_tag, url_t const *from_url, char const *to_tag, url_t const *to_url) |
Get leg by dialog. | |
SOFIAPUBFUN nta_incoming_t * | nta_incoming_create (nta_agent_t *agent, nta_leg_t *leg, msg_t *msg, sip_t *sip, tag_type_t tag, tag_value_t value,...) |
Create a server transaction. | |
SOFIAPUBFUN nta_incoming_t * | nta_incoming_default (nta_agent_t *agent) |
Create a default server transaction. | |
SOFIAPUBFUN void | nta_incoming_bind (nta_incoming_t *irq, nta_ack_cancel_f *callback, nta_incoming_magic_t *imagic) |
Bind a callback and context to an incoming transaction object. | |
SOFIAPUBFUN nta_incoming_magic_t * | nta_incoming_magic (nta_incoming_t *irq, nta_ack_cancel_f *callback) |
Get context pointer for an incoming transaction. | |
SOFIAPUBFUN nta_incoming_t * | nta_incoming_find (nta_agent_t const *agent, sip_t const *sip, sip_via_t const *v) |
Find incoming transaction. | |
SOFIAPUBFUN char const * | nta_incoming_tag (nta_incoming_t *irq, char const *tag) |
Add a To tag to incoming request if needed. | |
SOFIAPUBFUN char const * | nta_incoming_gettag (nta_incoming_t const *irq) |
Get local tag for incoming request. | |
SOFIAPUBFUN int | nta_incoming_status (nta_incoming_t const *irq) |
Get status code of a server transaction. | |
SOFIAPUBFUN sip_method_t | nta_incoming_method (nta_incoming_t const *irq) |
Get method of a server transaction. | |
SOFIAPUBFUN char const * | nta_incoming_method_name (nta_incoming_t const *irq) |
Get method name of a server transaction. | |
SOFIAPUBFUN url_t const * | nta_incoming_url (nta_incoming_t const *irq) |
Get Request-URI of a server transaction. | |
SOFIAPUBFUN uint32_t | nta_incoming_cseq (nta_incoming_t const *irq) |
Get sequence number of a server transaction. | |
SOFIAPUBFUN int | nta_incoming_set_params (nta_incoming_t *irq, tag_type_t tag, tag_value_t value,...) |
Set server transaction parameters. | |
SOFIAPUBFUN msg_t * | nta_incoming_getrequest (nta_incoming_t *irq) |
Get request message. | |
SOFIAPUBFUN msg_t * | nta_incoming_getrequest_ackcancel (nta_incoming_t *irq) |
Get ACK or CANCEL message. | |
SOFIAPUBFUN msg_t * | nta_incoming_getresponse (nta_incoming_t *irq) |
Get response message. | |
SOFIAPUBFUN int | nta_incoming_complete_response (nta_incoming_t *irq, msg_t *msg, int status, char const *phrase, tag_type_t tag, tag_value_t value,...) |
Complete a response message. | |
SOFIAPUBFUN int | nta_incoming_treply (nta_incoming_t *ireq, int status, char const *phrase, tag_type_t tag, tag_value_t value,...) |
Reply to an incoming transaction request. | |
SOFIAPUBFUN int | nta_incoming_mreply (nta_incoming_t *irq, msg_t *msg) |
Return a response message to client. | |
SOFIAPUBFUN void | nta_incoming_destroy (nta_incoming_t *irq) |
Destroy an incoming transaction. | |
SOFIAPUBFUN int | nta_check_required (nta_incoming_t *irq, sip_t const *sip, sip_supported_t const *supported, tag_type_t tag, tag_value_t value,...) |
Check that all features UAC requires are also in supported. | |
SOFIAPUBFUN int | nta_check_supported (nta_incoming_t *irq, sip_t const *sip, sip_require_t *require, tag_type_t tag, tag_value_t value,...) |
Check that all features we require are also supported by UAC. | |
SOFIAPUBFUN int | nta_check_method (nta_incoming_t *irq, sip_t const *sip, sip_allow_t const *allow, tag_type_t tag, tag_value_t value,...) |
Check that we support the request method. | |
SOFIAPUBFUN int | nta_check_accept (nta_incoming_t *irq, sip_t const *sip, sip_accept_t const *acceptable, sip_accept_t const **return_acceptable, tag_type_t tag, tag_value_t value,...) |
Check that UAC accepts (application/sdp). | |
SOFIAPUBFUN int | nta_check_session_expires (nta_incoming_t *irq, sip_t const *sip, sip_time_t my_min_se, tag_type_t tag, tag_value_t value,...) |
Check Session-Expires header. | |
SOFIAPUBFUN nta_outgoing_t * | nta_outgoing_tcreate (nta_leg_t *leg, nta_response_f *callback, nta_outgoing_magic_t *magic, url_string_t const *route_url, sip_method_t method, char const *method_name, url_string_t const *request_uri, tag_type_t tag, tag_value_t value,...) |
Create an outgoing request and client transaction belonging to the leg. | |
SOFIAPUBFUN nta_outgoing_t * | nta_outgoing_mcreate (nta_agent_t *agent, nta_response_f *callback, nta_outgoing_magic_t *magic, url_string_t const *route_url, msg_t *msg, tag_type_t tag, tag_value_t value,...) |
Create an outgoing client transaction. | |
SOFIAPUBFUN nta_outgoing_t * | nta_outgoing_default (nta_agent_t *agent, nta_response_f *callback, nta_outgoing_magic_t *magic) |
Create a default outgoing transaction. | |
SOFIAPUBFUN int | nta_outgoing_status (nta_outgoing_t const *orq) |
Get the status code of a client transaction. | |
SOFIAPUBFUN sip_method_t | nta_outgoing_method (nta_outgoing_t const *orq) |
Return method of the client transaction. | |
SOFIAPUBFUN char const * | nta_outgoing_method_name (nta_outgoing_t const *orq) |
Return method name of the client transaction. | |
SOFIAPUBFUN uint32_t | nta_outgoing_cseq (nta_outgoing_t const *orq) |
Get sequence number of a client transaction. | |
SOFIAPUBFUN unsigned | nta_outgoing_delay (nta_outgoing_t const *orq) |
Get the RTT delay measured using Timestamp header. | |
SOFIAPUBFUN url_t const * | nta_outgoing_request_uri (nta_outgoing_t const *orq) |
Return the request URI. | |
SOFIAPUBFUN url_t const * | nta_outgoing_route_uri (nta_outgoing_t const *orq) |
Return the URI used to route the request. | |
SOFIAPUBFUN msg_t * | nta_outgoing_getresponse (nta_outgoing_t *orq) |
Get reference to response message. | |
SOFIAPUBFUN msg_t * | nta_outgoing_getrequest (nta_outgoing_t *orq) |
Get request message. | |
SOFIAPUBFUN nta_outgoing_t * | nta_outgoing_tagged (nta_outgoing_t *orq, nta_response_f *callback, nta_outgoing_magic_t *magic, char const *to_tag, sip_rseq_t const *rseq) |
Create a tagged fork of outgoing request. | |
SOFIAPUBFUN int | nta_outgoing_cancel (nta_outgoing_t *) |
Cancel the request. | |
SOFIAPUBFUN nta_outgoing_t * | nta_outgoing_tcancel (nta_outgoing_t *orq, nta_response_f *callback, nta_outgoing_magic_t *magic, tag_type_t, tag_value_t,...) |
Cancel the request. | |
SOFIAPUBFUN void | nta_outgoing_destroy (nta_outgoing_t *) |
Destroy a request object. | |
SOFIAPUBFUN nta_outgoing_t * | nta_outgoing_find (nta_agent_t const *sa, msg_t const *msg, sip_t const *sip, sip_via_t const *v) |
Find an outgoing request corresponging to a message and Via line. | |
SOFIAPUBFUN int | nta_tport_keepalive (nta_outgoing_t *orq) |
Initiate STUN keepalive controller to TPORT. | |
SOFIAPUBFUN nta_outgoing_t * | nta_outgoing_prack (nta_leg_t *leg, nta_outgoing_t *oorq, nta_response_f *callback, nta_outgoing_magic_t *magic, url_string_t const *route_url, sip_t const *response_to_prack, tag_type_t, tag_value_t,...) |
PRACK a provisional response. | |
SOFIAPUBFUN uint32_t | nta_outgoing_rseq (nta_outgoing_t const *orq) |
Get RSeq value stored with client transaction. | |
SOFIAPUBFUN int | nta_outgoing_setrseq (nta_outgoing_t *orq, uint32_t rseq) |
Set RSeq value stored with client transaction. | |
SOFIAPUBFUN nta_reliable_t * | nta_reliable_treply (nta_incoming_t *ireq, nta_prack_f *callback, nta_reliable_magic_t *rmagic, int status, char const *phrase, tag_type_t tag, tag_value_t value,...) |
Respond reliably. | |
SOFIAPUBFUN nta_reliable_t * | nta_reliable_mreply (nta_incoming_t *irq, nta_prack_f *callback, nta_reliable_magic_t *rmagic, msg_t *msg) |
Respond reliably with msg. | |
SOFIAPUBFUN void | nta_reliable_destroy (nta_reliable_t *) |
Destroy a reliable response. | |
SOFIAPUBFUN void | nta_msg_discard (nta_agent_t *agent, msg_t *msg) |
Discard a message. | |
Variables | |
SOFIAPUBVAR char const | nta_version [] |
NTA module version. |
#define NTA_AGENT_MAGIC_T |
Default type of application context for NTA agents.
Application may define this to appropriate type before including <nta.h>.
#define NTA_INCOMING_MAGIC_T |
Default type of application context for incoming NTA requests.
Application may define this to appropriate type before including <nta.h>.
#define NTA_LEG_MAGIC_T |
Default type of application context for NTA call legs.
Application may define this to appropriate type before including <nta.h>.
#define NTA_OUTGOING_MAGIC_T |
Default type of application context for outgoing NTA requests.
Application may define this to appropriate type before including <nta.h>.
#define NTA_RELIABLE_MAGIC_T |
Default type of application context for reliable NTA responses.
Application may define this to appropriate type before including <nta.h>.
Callback function prototype for CANCELed/ACKed requests.
This is a callback function is invoked by NTA when an incoming request has been cancelled or an response to an incoming INVITE request has been acknowledged.
magic | incoming request context | |
ireq | incoming request | |
sip | ACK/CANCEL message |
0 | This callback function should return always 0. |
SOFIA_BEGIN_DECLSint nta_message_f |
Callback for incoming messages.
The typedef nta_message_f() defines prototype for the callback functions invoked by NTA when it has received an incoming message that will be processed statelessly.
The application can either discard the message by calling nta_msg_discard(), forward it by calling nta_msg_tsend() or reply to the message by calling nta_msg_treply(). When application wants to process a request statefully, it passes the message to a leg with the function nta_leg_stateful(). A new leg can be created by calling the function nta_leg_tcreate().
int message_callback(nta_agent_magic_t *context, nta_agent_t *agent, msg_t *msg, sip_t *sip);
context | agent context | |
agent | agent handle | |
msg | received message | |
sip | contents of message |
Callback for incoming requests.
This is a callback function invoked by NTA for each incoming SIP request.
lmagic | call leg context | |
leg | call leg handle | |
ireq | incoming request | |
sip | incoming request contents |
100..699 | NTA constructs a reply message with given error code and corresponding standard phrase, then sends the reply. | |
0 | The application takes care of sending (or not sending) the reply. | |
other | All other return values will be interpreted as 500 Internal server error. |
Callback for replies to outgoing requests.
This is a callback function invoked by NTA when it has received a new reply to an outgoing request.
magic | request context | |
request | request handle | |
sip | received status message |
anonymous enum |
SOFIAPUBFUN int nta_agent_add_tport | ( | nta_agent_t * | self, | |
url_string_t const * | uri, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Add a transport to the agent.
The function nta_agent_add_tport() creates a new transport and binds it to the port specified by the uri. The uri must have sip: or sips: scheme or be a wildcard uri ("*"). The uri syntax allowed is as follows:
url <scheme>:<host>[:<port>]<url-params>
;transport=<xxx> ;maddr=<actual addr> ;comp=sigcomp
The scheme part determines which transports are used. "sip" implies UDP and TCP, "sips" TLS over TCP. In the future, more transports can be supported, for instance, "sip" can use SCTP or DCCP, "sips" DTLS or TLS over SCTP.
The "host" part determines what address/domain name is used in Contact. An "*" in "host" part is shorthand for any local IP address. 0.0.0.0 means that the only the IPv4 addresses are used. [::] means that only the IPv6 addresses are used. If a domain name or a specific IP address is given as "host" part, an additional "maddr" parameter can be used to control which addresses are used by the stack when binding listen sockets for incoming requests.
The "port" determines what port is used in contact, and to which port the stack binds in order to listen for incoming requests. Empty or missing port means that default port should be used (5060 for sip, 5061 for sips). An "*" in "port" part means any port, i.e., the stack binds to an ephemeral port.
The "transport" parameter determines the transport protocol that is used and how they are preferred. If no protocol is specified, both UDP and TCP are used for SIP URL and TLS for SIPS URL. The preference can be indicated with a comma-separated list of transports, for instance, parameter
transport=tcp,udp @endocde indicates that TCP is preferred to UDP. The "maddr" parameter determines to which address the stack binds in order to listen for incoming requests. An "*" in "maddr" parameter is shorthand for any local IP address. 0.0.0.0 means that only IPv4 sockets are created. [::] means that only IPv6 sockets are created. The "comp" parameter determines the supported compression protocol. Currently only sigcomp is supported (with suitable library. @par Examples: @code sip:172.21.40.24;maddr=*
sip:172.21.40.24:50600;transport=TCP,UDP;comp=sigcomp
sips:*
SOFIAPUBFUN sip_contact_t* nta_agent_contact | ( | nta_agent_t const * | agent | ) |
Return Contact header.
The function nta_agent_contact() returns a Contact header, which can be used to reach agent.
agent | NTA agent object |
Proxies can use the Contact header to create appropriate Record-Route headers:
r_r = sip_record_route_create(msg_home(msg), sip->sip_request->rq_url, contact->m_url);
SOFIAPUBFUN nta_agent_t* nta_agent_create | ( | su_root_t * | root, | |
url_string_t const * | contact_url, | |||
nta_message_f * | callback, | |||
nta_agent_magic_t * | magic, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Create an NTA agent object.
The function nta_agent_create() creates an NTA agent object. The agent object creates and binds a server socket with address specified in url. If the host portion of the url is "*"
, the agent listens to all addresses available on the host.
When a message is received, the agent object parses it. If the result is a valid SIP message, the agent object passes the message to the application by invoking the nta_message_f callback function.
If url is NULL
, the default url "sip:*"
is used.
transport
parameters are specified in url, agent uses only specified transport type.maddr
parameter is specified in url, agent binds to the specified address, but uses host part of url in Contact and Via headers. The maddr
parameter is also included, unless it equals to INADDR_ANY
(0.0.0.0
or
[::]).root | pointer to a su_root_t used for synchronization | |
contact_url | URL that agent uses to bind the server sockets | |
callback | pointer to callback function | |
magic | pointer to user data | |
tag,value,... | other arguments |
handle | to the agent when successful, | |
NULL | upon an error. |
SOFIAPUBFUN void nta_agent_destroy | ( | nta_agent_t * | agent | ) |
Destroy an NTA agent object.
agent | the NTA agent object to be destroyed. |
SOFIAPUBFUN int nta_agent_get_params | ( | nta_agent_t * | agent, | |
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Get NTA Parameters.
The nta_agent_get_params() function retrieves the stack parameters. The parameters determine the way NTA handles the retransmissions, how long NTA keeps transactions alive, does NTA apply proxy or user-agent logic to INVITE transactions, or how the Via headers are generated.
SOFIAPUBFUN int nta_agent_get_stats | ( | nta_agent_t * | agent, | |
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Get NTA statistics.
The nta_agent_get_stats() function retrieves the stack statistics.
SOFIAPUBFUN char const* nta_agent_newtag | ( | su_home_t * | home, | |
char const * | fmt, | |||
nta_agent_t * | sa | |||
) |
Calculate a new unique tag.
This function generates a series of 2**64 unique tags for From or To headers. The start of the tag series is derived from the NTP time the NTA agent was initialized.
SOFIAPUBFUN sip_via_t* nta_agent_public_via | ( | nta_agent_t const * | agent | ) |
Return a list of public (UPnP, STUN) Via headers.
The function nta_agent_public_via() returns public Via headers for all activated transports.
agent | NTA agent object |
SOFIAPUBFUN int nta_agent_set_params | ( | nta_agent_t * | agent, | |
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Set NTA Parameters.
The nta_agent_set_params() function sets the stack parameters. The parameters determine the way NTA handles the retransmissions, how long NTA keeps transactions alive, does NTA apply proxy or user-agent logic to INVITE transactions, or how the Via headers are generated.
SOFIAPUBFUN char const* nta_agent_version | ( | nta_agent_t const * | agent | ) |
Return User-Agent header.
The function nta_agent_name() returns a User-Agent information with NTA version.
agent | NTA agent object |
SOFIAPUBFUN sip_via_t* nta_agent_via | ( | nta_agent_t const * | agent | ) |
Return a list of Via headers.
The function nta_agent_via() returns Via headers for all activated transport.
agent | NTA agent object |
SOFIAPUBFUN int nta_check_session_expires | ( | nta_incoming_t * | irq, | |
sip_t const * | sip, | |||
sip_time_t | my_min_se, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Check Session-Expires header.
If the proposed session-expiration time is smaller than Min-SE or our minimal session expiration time, respond with 422 containing our minimal session expiration time in Min-SE header.
SOFIAPUBFUN void nta_incoming_bind | ( | nta_incoming_t * | irq, | |
nta_ack_cancel_f * | callback, | |||
nta_incoming_magic_t * | magic | |||
) |
Bind a callback and context to an incoming transaction object.
The function nta_incoming_bind() is used to set the callback and context pointer attached to an incoming request object. The callback function will be invoked if the incoming request is cancelled, or if the final response to an incoming INVITE request has been acknowledged.
If the callback is NULL, or no callback has been bound, NTA invokes the request callback of the call leg.
irq | incoming transaction | |
callback | callback function | |
magic | application context |
SOFIAPUBFUN int nta_incoming_complete_response | ( | nta_incoming_t * | irq, | |
msg_t * | msg, | |||
int | status, | |||
char const * | phrase, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Complete a response message.
irq | server transaction object | |
msg | response message to be completed | |
status | status code (in range 100 - 699) | |
phrase | status phrase (may be NULL) | |
tag,value,... | taged argument list |
SOFIAPUBFUN nta_incoming_t* nta_incoming_create | ( | nta_agent_t * | agent, | |
nta_leg_t * | leg, | |||
msg_t * | msg, | |||
sip_t * | sip, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Create a server transaction.
The function nta_incoming_create() creates a server transaction for a request message. This function is used when an element processing requests statelessly wants to process a particular request statefully.
agent | pointer to agent object | |
leg | pointer to leg object (either agent or leg may be NULL) | |
msg | pointer to message object | |
sip | pointer to SIP structure (may be NULL) | |
tag,value,... | optional tagged parameters |
nta_incoming_t | pointer to the newly created server transaction | |
NULL | if failed |
SOFIAPUBFUN nta_incoming_t* nta_incoming_default | ( | nta_agent_t * | agent | ) |
Create a default server transaction.
The default server transaction is used by a proxy to forward responses statelessly.
agent | pointer to agent object |
pointer | to default server transaction object | |
NULL | if failed |
SOFIAPUBFUN void nta_incoming_destroy | ( | nta_incoming_t * | irq | ) |
Destroy an incoming transaction.
This function does not actually free transaction object, but marks it as disposable. The object is freed after a timeout.
irq | incoming request object to be destroyed |
SOFIAPUBFUN msg_t* nta_incoming_getrequest | ( | nta_incoming_t * | irq | ) |
Get request message.
Retrieve the incoming request message of the incoming transaction. Note that the message is not copied, but a new reference to it is created.
irq | incoming transaction handle |
A | pointer to request message is returned. |
SOFIAPUBFUN msg_t* nta_incoming_getrequest_ackcancel | ( | nta_incoming_t * | irq | ) |
Get ACK or CANCEL message.
Retrieve the incoming ACK or CANCEL request message of the incoming transaction. Note that the ACK or CANCEL message is not copied, but a new reference to it is created.
irq | incoming transaction handle |
A | pointer to request message is returned, or NULL if there is no CANCEL or ACK received. |
SOFIAPUBFUN msg_t* nta_incoming_getresponse | ( | nta_incoming_t * | irq | ) |
Get response message.
Retrieve the response message latest sent by the server transaction. Note that the message is not copied, but a new reference to it is created. Use msg_dup() or msg_copy() to make a copy of it.
irq | incoming transaction handle |
A | pointer to a response message is returned. |
SOFIAPUBFUN int nta_incoming_mreply | ( | nta_incoming_t * | irq, | |
msg_t * | msg | |||
) |
Return a response message to client.
SOFIAPUBFUN int nta_incoming_set_params | ( | nta_incoming_t * | irq, | |
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Set server transaction parameters.
Sets the server transaction parameters. The parameters determine the way the SigComp compression is handled.
number | of set parameters when succesful | |
-1 | upon an error |
SOFIAPUBFUN char const* nta_incoming_tag | ( | nta_incoming_t * | irq, | |
char const * | tag | |||
) |
Add a To tag to incoming request if needed.
If tag is NULL, a new tag is generated.
SOFIAPUBFUN int nta_incoming_treply | ( | nta_incoming_t * | irq, | |
int | status, | |||
char const * | phrase, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Reply to an incoming transaction request.
This function creates a response message to an incoming request and sends it to the client.
irq | incoming request | |
status | status code | |
phrase | status phrase (may be NULL if status code is well-known) | |
tag,value,... | optional additional headers terminated by TAG_END() |
0 | when succesful | |
-1 | upon an error |
SOFIAPUBFUN void nta_leg_bind | ( | nta_leg_t * | leg, | |
nta_request_f * | callback, | |||
nta_leg_magic_t * | magic | |||
) |
Bind a callback function and context to a leg object.
The function nta_leg_bind() is used to change the callback and context pointer attached to a leg object.
leg | leg object to be bound | |
callback | new callback function (or NULL if no callback is desired) | |
magic | new context pointer |
SOFIAPUBFUN nta_leg_t* nta_leg_by_dialog | ( | nta_agent_t const * | agent, | |
url_t const * | request_uri, | |||
sip_call_id_t const * | call_id, | |||
char const * | remote_tag, | |||
url_t const * | remote_uri, | |||
char const * | local_tag, | |||
url_t const * | local_uri | |||
) |
Get leg by dialog.
The function nta_leg_by_dialog() searches for a dialog leg from agent's hash table. The matching rules based on parameters are as follows:
agent | pointer to agent object | |
request_uri | if non-NULL, and there is destination URI associated with the dialog, these URIs must match | |
call_id | if non-NULL, must match with Call-ID header contents | |
remote_tag | if there is remote tag associated with dialog, remote_tag must match | |
remote_uri | if there is no remote tag, the remote URI must match | |
local_tag | if non-NULL and there is local tag associated with leg, it must math | |
local_uri | if there is no local tag, the local URI must match |
SOFIAPUBFUN int nta_leg_client_route | ( | nta_leg_t * | leg, | |
sip_record_route_t const * | route, | |||
sip_contact_t const * | contact | |||
) |
Set UAC route.
bis04 section 16.1
SOFIAPUBFUN void nta_leg_destroy | ( | nta_leg_t * | leg | ) |
Destroy a leg.
leg | leg to be destroyed |
SOFIAPUBFUN char const* nta_leg_rtag | ( | nta_leg_t * | leg, | |
char const * | tag | |||
) |
Add remote tag.
leg | leg to be tagged | |
tag | tag to be added (must be non-NULL) |
SOFIAPUBFUN int nta_leg_server_route | ( | nta_leg_t * | leg, | |
sip_record_route_t const * | route, | |||
sip_contact_t const * | contact | |||
) |
Set UAS route.
bis04 section 16.2
SOFIAPUBFUN char const* nta_leg_tag | ( | nta_leg_t * | leg, | |
char const * | tag | |||
) |
Add local tag.
leg | leg to be tagged | |
tag | tag to be added (if NULL, a tag generated by NTA is added) |
SOFIAPUBFUN nta_leg_t* nta_leg_tcreate | ( | nta_agent_t * | agent, | |
nta_request_f * | callback, | |||
nta_leg_magic_t * | magic, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Create a new leg object.
The function nta_leg_tcreate() creates a leg object. A leg object is used to represent dialogs, partial dialogs (for example, in case of REGISTER), and destinations within a particular NTA object.
When a leg is created, a callback pointer and a application context is provided. All other parameters are optional.
agent | agent object | |
callback | function which is called for each incoming request belonging to this leg | |
magic | call leg context | |
tag,value,... | optional extra headers in taglist |
If there is a (preloaded) route associated with the leg, SIPTAG_ROUTE() and NTATAG_TARGET() can be used. A client or server can also set the route using Record-Route and Contact headers from a response or request message with the functions nta_leg_client_route() and nta_leg_server_route(), respectively.
When a leg representing a local destination is created, the tags NTATAG_NO_DIALOG(1), NTATAG_METHOD(), and URLTAG_URL() are used. When a request with matching request-URI (URLTAG_URL()) and method (NTATAG_METHOD()) is received, it is passed to the callback function provided with the leg.
SOFIAPUBFUN int nta_msg_request_complete | ( | msg_t * | msg, | |
nta_leg_t * | leg, | |||
sip_method_t | method, | |||
char const * | method_name, | |||
url_string_t const * | request_uri | |||
) |
Complete a request with values from dialog.
The function nta_msg_request_complete() completes a request message msg belonging to a dialog associated with leg. It increments the local CSeq value, adds Call-ID, To, From and Route headers (if there is such headers present in leg), and creates a new request line object from method, method_name and request_uri.
msg | pointer to a request message object | |
leg | pointer to a nta_leg_t object | |
method | request method number or sip_method_unknown | |
method_name | method name (if method == sip_method_unknown) | |
request_uri | request URI |
0 | when successful | |
-1 | upon an error |
SOFIAPUBFUN nta_outgoing_t* nta_outgoing_default | ( | nta_agent_t * | agent, | |
nta_response_f * | callback, | |||
nta_outgoing_magic_t * | magic | |||
) |
Create a default outgoing transaction.
The default outgoing transaction is used when agent receives responses not belonging to any transaction.
SOFIAPUBFUN void nta_outgoing_destroy | ( | nta_outgoing_t * | orq | ) |
Destroy a request object.
SOFIAPUBFUN nta_outgoing_t* nta_outgoing_find | ( | nta_agent_t const * | agent, | |
msg_t const * | msg, | |||
sip_t const * | sip, | |||
sip_via_t const * | v | |||
) |
Find an outgoing request corresponging to a message and Via line.
Return an outgoing request object based on a message and the Via line given as argument. This function is used when doing loop checking: if we have sent the request and it has been routed back to us.
agent | ||
msg | ||
sip | ||
v |
SOFIAPUBFUN msg_t* nta_outgoing_getrequest | ( | nta_outgoing_t * | orq | ) |
Get request message.
Retrieves the request message sent to the network. Note that the request message is not copied, but a new reference to it is created.
A | pointer to the request message is returned, or NULL if an error occurred. |
SOFIAPUBFUN msg_t* nta_outgoing_getresponse | ( | nta_outgoing_t * | orq | ) |
Get reference to response message.
Retrieve the latest incoming response message to the outgoing transaction. Note that the message is not copied, but a new reference to it is created instead.
orq | outgoing transaction handle |
A | pointer to response message is returned, or NULL if no response message has been received. |
SOFIAPUBFUN nta_outgoing_t* nta_outgoing_mcreate | ( | nta_agent_t * | agent, | |
nta_response_f * | callback, | |||
nta_outgoing_magic_t * | magic, | |||
url_string_t const * | route_url, | |||
msg_t * | msg, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Create an outgoing client transaction.
Create an outgoing transaction object. The request message is passed to the transaction object, which sends the request to the network. The request is sent to the route_url (if non-NULL), default proxy (if defined by NTATAG_DEFAULT_PROXY()), or to the address specified by request_uri. If no request_uri is specified, it is taken from route-set target or from the To header.
When NTA receives response to the request, it invokes the callback function.
agent | NTA agent object | |
callback | callback function (may be NULL ) | |
magic | application context pointer | |
route_url | optional URL used to route transaction requests | |
msg | request message | |
tag,value,... | tagged parameter list |
If NTATAG_STATELESS(1) tag is given and the callback is NULL, the transaction object is marked as destroyed from the beginning. In that case, the function may return
(nta_outgoing_t *)-1
SOFIAPUBFUN nta_outgoing_t* nta_outgoing_prack | ( | nta_leg_t * | leg, | |
nta_outgoing_t * | oorq, | |||
nta_response_f * | callback, | |||
nta_outgoing_magic_t * | magic, | |||
url_string_t const * | route_url, | |||
sip_t const * | resp, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
PRACK a provisional response.
The function nta_outgoing_prack() creates and sends a PRACK request used to acknowledge a provisional response.
The request is sent using the route of the original request orq.
When NTA receives response to the prack request, it invokes the callback function.
leg | dialog object | |
oorq | original transaction request | |
callback | callback function (may be NULL ) | |
magic | application context pointer | |
route_url | optional URL used to route transaction requests | |
resp | (optional) response message to be acknowledged | |
tag,value,... | optional |
SOFIAPUBFUN int nta_outgoing_setrseq | ( | nta_outgoing_t * | orq, | |
uint32_t | rseq | |||
) |
Set RSeq value stored with client transaction.
-1 if rseq is invalid or orq is NULL.
SOFIAPUBFUN nta_outgoing_t* nta_outgoing_tagged | ( | nta_outgoing_t * | orq, | |
nta_response_f * | callback, | |||
nta_outgoing_magic_t * | magic, | |||
char const * | to_tag, | |||
sip_rseq_t const * | rseq | |||
) |
Create a tagged fork of outgoing request.
When a dialog-creating INVITE request is forked, each response from diffent fork will create an early dialog with a distinct tag in To header. When each fork should be handled separately, a tagged INVITE request can be used. It will only receive responses from the specified fork. Please note that the tagged transaction should be terminated with the final response from another fork, too.
orq | ||
callback | ||
magic | ||
to_tag | ||
rseq |
SOFIAPUBFUN nta_outgoing_t* nta_outgoing_tcancel | ( | nta_outgoing_t * | orq, | |
nta_response_f * | callback, | |||
nta_outgoing_magic_t * | magic, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Cancel the request.
Initiate a cancel transaction for client transaction orq.
orq | client transaction to cancel | |
callback | callback function (may be NULL ) | |
magic | application context pointer | |
tag,value,... | list of extra arguments |
SOFIAPUBFUN nta_outgoing_t* nta_outgoing_tcreate | ( | nta_leg_t * | leg, | |
nta_response_f * | callback, | |||
nta_outgoing_magic_t * | magic, | |||
url_string_t const * | route_url, | |||
sip_method_t | method, | |||
char const * | name, | |||
url_string_t const * | request_uri, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Create an outgoing request and client transaction belonging to the leg.
The function nta_outgoing_tcreate() creates a request message and passes the request message to an outgoing client transaction object. The request is sent to the route_url (if non-NULL), default proxy (if defined by NTATAG_DEFAULT_PROXY()), or to the address specified by request_uri. If no request_uri is specified, it is taken from route-set target or from the To header.
When NTA receives response to the request, it invokes the callback function.
leg | call leg object | |
callback | callback function (may be NULL ) | |
magic | application context pointer | |
route_url | optional URL used to route transaction requests | |
method | method type | |
name | method name | |
request_uri | Request-URI | |
tag,value,... | list of extra arguments |
(nta_outgoing_t *)-1
SOFIAPUBFUN void nta_reliable_destroy | ( | nta_reliable_t * | rel | ) |
Destroy a reliable response.
The function nta_reliable_destroy() marks a reliable response object for destroyal, and frees it if possible.
SOFIAPUBFUN nta_reliable_t* nta_reliable_mreply | ( | nta_incoming_t * | irq, | |
nta_prack_f * | callback, | |||
nta_reliable_magic_t * | rmagic, | |||
msg_t * | msg | |||
) |
Respond reliably with msg.
irq | ||
callback | ||
rmagic | ||
msg |
SOFIAPUBFUN nta_reliable_t* nta_reliable_treply | ( | nta_incoming_t * | irq, | |
nta_prack_f * | callback, | |||
nta_reliable_magic_t * | rmagic, | |||
int | status, | |||
char const * | phrase, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Respond reliably.
irq | ||
callback | ||
rmagic | ||
status | ||
phrase | ||
tag,value,.. |