nta.c File Reference


Detailed Description

Sofia SIP Transaction API implementation.

This source file has been divided into sections as follows: 1) agent 2) tport handling 3) dispatching messages received from network 4) message creation and message utility functions 5) stateless operation 6) dialogs (legs) 7) server transactions (incoming) 8) client transactions (outgoing) 9) resolving URLs for client transactions 10) 100rel reliable responses (reliable) 11) SigComp handling and public transport interface

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Date:
Created: Tue Jun 13 02:57:51 2000 ppessi

#include "config.h"
#include <sofia-sip/string0.h>
#include <sofia-sip/su_alloc.h>
#include <sofia-sip/su.h>
#include <sofia-sip/su_time.h>
#include <sofia-sip/su_wait.h>
#include <sofia-sip/su_tagarg.h>
#include <sofia-sip/base64.h>
#include <sofia-sip/su_uniqueid.h>
#include <sofia-sip/sip.h>
#include <sofia-sip/sip_header.h>
#include <sofia-sip/sip_util.h>
#include <sofia-sip/sip_status.h>
#include <sofia-sip/hostdomain.h>
#include <sofia-sip/msg_addr.h>
#include <sofia-sip/msg_parser.h>
#include "nta_internal.h"
#include "sofia-sip/nta_stateless.h"
#include "sofia-sip/url_tag.h"
#include <stddef.h>
#include <stdlib.h>
#include <stdio.h>
#include <stdarg.h>
#include <assert.h>
#include <limits.h>
#include <errno.h>
#include <sofia-sip/su_md5.h>
#include <sofia-sip/nta_tport.h>

Include dependency graph for nta.c:


Functions

void incoming_cut_off (nta_incoming_t *irq)
 Remove references to the irq.
void incoming_reclaim (nta_incoming_t *irq)
 Reclaim the memory used by irq.
nta_incoming_tincoming_find (nta_agent_t const *agent, sip_t const *sip, sip_via_t const *v, nta_incoming_t **return_merge, nta_incoming_t **return_ack)
 Find a matching server transaction object.
int incoming_recv (nta_incoming_t *irq, msg_t *msg, sip_t *sip, tport_t *tport)
 Process retransmitted requests.
int incoming_merge (nta_incoming_t *irq, msg_t *msg, sip_t *sip, tport_t *tport)
 Process merged requests.
void outgoing_cut_off (nta_outgoing_t *orq)
 Remove outgoing request from hash tables.
void outgoing_reclaim (nta_outgoing_t *orq)
 Reclaim outgoing request.
nta_agent_tnta_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.
void nta_agent_destroy (nta_agent_t *agent)
 Destroy an NTA agent object.
nta_agent_magic_tnta_agent_magic (nta_agent_t const *agent)
 Return agent context.
sip_contact_tnta_agent_contact (nta_agent_t const *agent)
 Return Contact header.
sip_via_tnta_agent_via (nta_agent_t const *agent)
 Return a list of Via headers.
sip_via_tnta_agent_public_via (nta_agent_t const *agent)
 Return a list of public (UPnP, STUN) Via headers.
char const * nta_agent_version (nta_agent_t const *agent)
 Return User-Agent header.
int nta_agent_set_params (nta_agent_t *agent, tag_type_t tag, tag_value_t value,...)
 Set NTA Parameters.
int nta_agent_get_params (nta_agent_t *agent, tag_type_t tag, tag_value_t value,...)
 Get NTA Parameters.
int nta_agent_get_stats (nta_agent_t *agent, tag_type_t tag, tag_value_t value,...)
 Get NTA statistics.
char const * nta_agent_newtag (su_home_t *home, char const *fmt, nta_agent_t *sa)
 Calculate a new unique tag.
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.
int nta_tpn_by_url (su_home_t *home, tp_name_t *tpn, char const **scheme, char const **port, url_string_t const *us)
 Get transport name from URL.
msg_tnta_msg_create (nta_agent_t *agent, int flags)
 Create a new message belonging to the agent.
int nta_msg_complete (msg_t *msg)
 Complete a message.
void nta_msg_discard (nta_agent_t *agent, msg_t *msg)
 Discard a message.
int nta_is_internal_msg (msg_t const *msg)
 Check if the message is internally generated by NTA.
int nta_msg_tsend (nta_agent_t *agent, msg_t *msg, url_string_t const *u, tag_type_t tag, tag_value_t value,...)
 Forward a request or response message.
int nta_msg_treply (nta_agent_t *agent, msg_t *req_msg, int status, char const *phrase, tag_type_t tag, tag_value_t value,...)
 Reply to a request message.
int nta_msg_mreply (nta_agent_t *agent, msg_t *reply, sip_t *sip, int status, char const *phrase, msg_t *req_msg, tag_type_t tag, tag_value_t value,...)
 Reply to a request message.
int nta_msg_ackbye (nta_agent_t *agent, msg_t *msg)
 ACK and BYE an unknown 200 OK response to INVITE.
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.
hash_value_t hash_istring (char const *s, char const *term, hash_value_t hash)
 Calculate a simple case-insensitive hash over a string.
nta_leg_tnta_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.
nta_leg_tnta_default_leg (nta_agent_t const *agent)
 Return the default leg, if any.
void nta_leg_destroy (nta_leg_t *leg)
 Destroy a leg.
nta_leg_magic_tnta_leg_magic (nta_leg_t const *leg, nta_request_f *callback)
 Return application context for the leg.
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.
char const * nta_leg_tag (nta_leg_t *leg, char const *tag)
 Add local tag.
char const * nta_leg_get_tag (nta_leg_t const *leg)
 Get local tag.
char const * nta_leg_rtag (nta_leg_t *leg, char const *tag)
 Add remote tag.
char const * nta_leg_get_rtag (nta_leg_t const *leg)
 Get remote tag.
int nta_leg_client_route (nta_leg_t *leg, sip_record_route_t const *route, sip_contact_t const *contact)
 Set UAC route.
int nta_leg_server_route (nta_leg_t *leg, sip_record_route_t const *route, sip_contact_t const *contact)
 Set UAS route.
int nta_leg_get_route (nta_leg_t *leg, sip_route_t const **return_route, sip_contact_t const **return_target)
 Get route.
sip_replaces_tnta_leg_make_replaces (nta_leg_t *leg, su_home_t *home, int early_only)
 Generate Replaces header.
nta_leg_tnta_leg_by_replaces (nta_agent_t *sa, sip_replaces_t const *rp)
 Get dialog leg by Replaces header.
int addr_cmp (url_t const *a, url_t const *b)
 Compare two SIP from/to fields.
nta_leg_tnta_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.
nta_leg_tnta_leg_by_uri (nta_agent_t const *agent, url_string_t const *us)
 Get leg by destination.
size_t incoming_mass_destroy (nta_agent_t *sa, incoming_queue_t *q)
 Mass destroy server transactions.
nta_incoming_tincoming_call_callback (nta_incoming_t *irq, msg_t *msg, sip_t *sip)
 Call callback of incoming transaction.
nta_incoming_tnta_incoming_default (nta_agent_t *agent)
 Create a default server transaction.
nta_incoming_tnta_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.
void nta_incoming_destroy (nta_incoming_t *irq)
 Destroy an incoming transaction.
void incoming_free_queue (incoming_queue_t *q, nta_incoming_t *irq)
 Queue request to be freed.
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.
char const * nta_incoming_tag (nta_incoming_t *irq, char const *tag)
 Add a To tag to incoming request if needed.
msg_tnta_incoming_getrequest (nta_incoming_t *irq)
 Get request message.
msg_tnta_incoming_getrequest_ackcancel (nta_incoming_t *irq)
 Get ACK or CANCEL message.
msg_tnta_incoming_getresponse (nta_incoming_t *irq)
 Get response message.
sip_method_t nta_incoming_method (nta_incoming_t const *irq)
 Get method of a server transaction.
char const * nta_incoming_method_name (nta_incoming_t const *irq)
 Get method name of a server transaction.
url_t const * nta_incoming_url (nta_incoming_t const *irq)
 Get Request-URI of a server transaction.
uint32_t nta_incoming_cseq (nta_incoming_t const *irq)
 Get sequence number of a server transaction.
char const * nta_incoming_gettag (nta_incoming_t const *irq)
 Get local tag for incoming request.
int nta_incoming_status (nta_incoming_t const *irq)
 Get status code of a server transaction.
nta_incoming_magic_tnta_incoming_magic (nta_incoming_t *irq, nta_ack_cancel_f *callback)
 Get context pointer for an incoming transaction.
nta_incoming_tnta_incoming_find (nta_agent_t const *agent, sip_t const *sip, sip_via_t const *v)
 Find incoming transaction.
int nta_incoming_set_params (nta_incoming_t *irq, tag_type_t tag, tag_value_t value,...)
 Set server transaction parameters.
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.
msg_tnta_incoming_create_response (nta_incoming_t *irq, int status, char const *phrase)
 Create a response message for request.
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.
int nta_incoming_mreply (nta_incoming_t *irq, msg_t *msg)
 Return a response message to client.
void outgoing_set_timer (nta_outgoing_t *orq, unsigned interval)
 Set retransmit timer (orq_retry).
nta_outgoing_tnta_outgoing_default (nta_agent_t *agent, nta_response_f *callback, nta_outgoing_magic_t *magic)
 Create a default outgoing transaction.
nta_outgoing_tnta_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.
nta_outgoing_tnta_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.
int nta_outgoing_cancel (nta_outgoing_t *orq)
 Cancel the request.
nta_outgoing_tnta_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.
void nta_outgoing_destroy (nta_outgoing_t *orq)
 Destroy a request object.
url_t const * nta_outgoing_request_uri (nta_outgoing_t const *orq)
 Return the request URI.
url_t const * nta_outgoing_route_uri (nta_outgoing_t const *orq)
 Return the URI used to route the request.
sip_method_t nta_outgoing_method (nta_outgoing_t const *orq)
 Return method of the client transaction.
char const * nta_outgoing_method_name (nta_outgoing_t const *orq)
 Return method name of the client transaction.
uint32_t nta_outgoing_cseq (nta_outgoing_t const *orq)
 Get sequence number of a client transaction.
int nta_outgoing_status (nta_outgoing_t const *orq)
 Get the status code of a client transaction.
unsigned nta_outgoing_delay (nta_outgoing_t const *orq)
 Get the RTT delay measured using Timestamp header.
msg_tnta_outgoing_getresponse (nta_outgoing_t *orq)
 Get reference to response message.
msg_tnta_outgoing_getrequest (nta_outgoing_t *orq)
 Get request message.
void outgoing_free_queue (outgoing_queue_t *q, nta_outgoing_t *orq)
 Queue request to be freed.
nta_outgoing_tnta_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.
int reliable_check (nta_incoming_t *irq)
 Check that server transaction can be used to send reliable provisional responses.
nta_reliable_tnta_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.
nta_reliable_tnta_reliable_mreply (nta_incoming_t *irq, nta_prack_f *callback, nta_reliable_magic_t *rmagic, msg_t *msg)
 Respond reliably with msg.
void nta_reliable_destroy (nta_reliable_t *rel)
 Destroy a reliable response.
nta_outgoing_tnta_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.
nta_outgoing_tnta_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.
uint32_t nta_outgoing_rseq (nta_outgoing_t const *orq)
 Get RSeq value stored with client transaction.
int nta_outgoing_setrseq (nta_outgoing_t *orq, uint32_t rseq)
 Set RSeq value stored with client transaction.
int nta_agent_bind_tport_update (nta_agent_t *agent, nta_update_magic_t *magic, nta_update_tport_f *callback)
 Bind transport update callback.
int nta_agent_tport_is_updating (nta_agent_t *agent)
 Check if public transport binding is in progress.
int nta_tport_keepalive (nta_outgoing_t *orq)
 Initiate STUN keepalive controller to TPORT.
int nta_agent_close_tports (nta_agent_t *agent)
 Close all transports.

Variables

char const nta_version []
 NTA module version.
char const NTA_DEBUG []
 Environment variable determining the default debug log level.
su_log_t nta_log []
 Debug log for nta module.

Function Documentation

int addr_cmp ( url_t const *  a,
url_t const *  b 
) [inline]

Compare two SIP from/to fields.

Return values:
nonzero if matching.
zero if not matching.

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.

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> 
where <url-params> may be
 ;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:* 

Returns:
On success, zero is returned. On error, -1 is returned, and errno is set appropriately.

int nta_agent_close_tports ( nta_agent_t agent  ) 

Close all transports.

Since:
Experimental in 1.12.2.

sip_contact_t* nta_agent_contact ( nta_agent_t const *  agent  ) 

Return Contact header.

Get a Contact header, which can be used to reach agent.

Parameters:
agent NTA agent object
User agents can insert the Contact header in the outgoing REGISTER, INVITE, and ACK requests and replies to incoming INVITE and OPTIONS transactions.

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);

Returns:
A sip_contact_t object corresponding to the agent.

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.

Create 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.

Note:
The url can be either parsed url (of type url_t ()), or a valid SIP URL as a string.

If url is NULL, the default url "sip:*" is used.

If url is NONE (iow, (void*)-1), no server sockets are bound.
If transport parameters are specified in url, agent uses only specified transport type.
If an maddr parameter is specified in url, agent binds to the specified address, but uses host part of url when it generates Contact and Via headers. The maddr parameter is also included, unless it equals to INADDR_ANY (0.0.0.0 or [::]).
Parameters:
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
Note:
It is possible to provide -1 as contact_url.
Return values:
handle to the agent when successful,
NULL upon an error.

void nta_agent_destroy ( nta_agent_t agent  ) 

Destroy an NTA agent object.

Parameters:
agent the NTA agent object to be destroyed.

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.

Related Tags:
NTATAG_ALIASES_REF(), NTATAG_CANCEL_2543_REF(), NTATAG_CANCEL_487_REF(), NTATAG_CONTACT_REF(), NTATAG_DEBUG_DROP_PROB_REF(), NTATAG_DEFAULT_PROXY_REF(), NTATAG_EXTRA_100_REF(), NTATAG_MAXSIZE_REF(), NTATAG_MAX_FORWARDS_REF(), NTATAG_MERGE_482_REF(), NTATAG_PASS_100_REF(), NTATAG_PRELOAD_REF(), NTATAG_REL100_REF(), NTATAG_RPORT_REF(), NTATAG_SIPFLAGS_REF(), NTATAG_SIP_T1X64_REF(), NTATAG_SIP_T1_REF(), NTATAG_SIP_T2_REF(), NTATAG_SIP_T4_REF(), NTATAG_SMIME_REF(), NTATAG_STATELESS_REF(), NTATAG_TAG_3261_REF(), NTATAG_TIMEOUT_408_REF(), NTATAG_PASS_408_REF(), NTATAG_UA_REF(), NTATAG_USER_VIA_REF(), and NTATAG_USE_TIMESTAMP_REF().

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.

Related Tags:
NTATAG_S_*

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.

sip_via_t* nta_agent_public_via ( nta_agent_t const *  agent  ) 

Return a list of public (UPnP, STUN) Via headers.

Get public Via headers for all activated transports.

Parameters:
agent NTA agent object
Returns:
A list of sip_via_t objects used by the agent.

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.

Note:
Setting the parameters NTATAG_MAXSIZE(), NTATAG_UDP_MTU(), NTATAG_SIP_T1X64(), NTATAG_SIP_T1(), NTATAG_SIP_T2(), NTATAG_SIP_T4() to 0 selects the default value.
Related Tags:
NTATAG_ALIASES(), NTATAG_BAD_REQ_MASK(), NTATAG_BAD_RESP_MASK(), NTATAG_CANCEL_2543(), NTATAG_CANCEL_487(), NTATAG_DEBUG_DROP_PROB(), NTATAG_DEFAULT_PROXY(), NTATAG_EXTRA_100(), NTATAG_MAXSIZE(), NTATAG_MAX_FORWARDS(), NTATAG_UDP_MTU(), NTATAG_MERGE_482(), NTATAG_PASS_100(), NTATAG_PRELOAD(), NTATAG_REL100(), NTATAG_RPORT(), NTATAG_SERVER_RPORT(), NTATAG_TCP_RPORT(), NTATAG_SIPFLAGS(), NTATAG_SIP_T1X64(), NTATAG_SIP_T1(), NTATAG_SIP_T2(), NTATAG_SIP_T4(), NTATAG_SMIME(), NTATAG_STATELESS(), NTATAG_TAG_3261(), NTATAG_TIMEOUT_408(), NTATAG_PASS_408(), NTATAG_UA(), NTATAG_USER_VIA(), and NTATAG_USE_TIMESTAMP().

char const* nta_agent_version ( nta_agent_t const *  agent  ) 

Return User-Agent header.

Get User-Agent information with NTA version.

Parameters:
agent NTA agent object (may be NULL)
Returns:
A string containing the agent version.

sip_via_t* nta_agent_via ( nta_agent_t const *  agent  ) 

Return a list of Via headers.

Get Via headers for all activated transport.

Parameters:
agent NTA agent object
Returns:
A list of sip_via_t objects used by the agent.

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.

Set the callback function 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.

Parameters:
irq incoming transaction
callback callback function
magic application context

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.

Parameters:
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
Generate status structure based on status and phrase. Add essential headers to the response message: From, To, Call-ID, CSeq, Via, and optionally Record-Route.

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.

Create a server transaction for a request message. This function is used when an element processing requests statelessly wants to process a particular request statefully.

Parameters:
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
Note:
The ownership of msg is taken over by the function even if the function fails.
Related Tags:
NTATAG_TPORT() specifies the transport used to receive the request and also default transport for sending the response.
Return values:
nta_incoming_t pointer to the newly created server transaction
NULL if failed

msg_t* nta_incoming_create_response ( nta_incoming_t irq,
int  status,
char const *  phrase 
)

Create a response message for request.

Since:
New in 1.12.5.

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.

Parameters:
agent pointer to agent object
Return values:
pointer to default server transaction object
NULL if failed

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.

Parameters:
irq incoming request object to be destroyed

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.

Parameters:
irq incoming transaction handle
Return values:
A pointer to request message is returned.

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.

Parameters:
irq incoming transaction handle
Return values:
A pointer to request message is returned, or NULL if there is no CANCEL or ACK received.

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.

Parameters:
irq incoming transaction handle
Return values:
A pointer to a response message is returned.

int nta_incoming_mreply ( nta_incoming_t irq,
msg_t msg 
)

Return a response message to client.

Note:
The ownership of msg is taken over by the function even if the function fails.
Return values:
0 when succesful
-1 upon an error

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.

Related Tags:
NTATAG_COMP(), and NTATAG_SIGCOMP_CLOSE().
Return values:
number of set parameters when succesful
-1 upon an error

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.

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.

Note:
It is possible to send several non-final (1xx) responses, but only one final response.
Parameters:
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()
Return values:
0 when succesful
-1 upon an error

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.

Change the callback function and context pointer attached to a leg object.

Parameters:
leg leg object to be bound
callback new callback function (or NULL if no callback is desired)
magic new context pointer

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.

Search for a dialog leg from agent's hash table. The matching rules based on parameters are as follows:

Parameters:
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

nta_leg_t* nta_leg_by_replaces ( nta_agent_t sa,
sip_replaces_t const *  rp 
)

Get dialog leg by Replaces header.

Since:
New in 1.12.2.

int nta_leg_client_route ( nta_leg_t leg,
sip_record_route_t const *  route,
sip_contact_t const *  contact 
)

Set UAC route.

See also:
nta_leg_server_route(), RFC 3261 section 12.1.2

void nta_leg_destroy ( nta_leg_t leg  ) 

Destroy a leg.

Parameters:
leg leg to be destroyed

sip_replaces_t* nta_leg_make_replaces ( nta_leg_t leg,
su_home_t *  home,
int  early_only 
)

Generate Replaces header.

Since:
New in 1.12.2.

char const* nta_leg_rtag ( nta_leg_t leg,
char const *  tag 
)

Add remote tag.

Note:
No remote tag is ever generated.
Parameters:
leg leg to be tagged
tag tag to be added (must be non-NULL)
Returns:
Pointer to tag if successful, NULL otherwise.

int nta_leg_server_route ( nta_leg_t leg,
sip_record_route_t const *  route,
sip_contact_t const *  contact 
)

Set UAS route.

See also:
nta_leg_client_route(), RFC 3261 section 12.1.1

char const* nta_leg_tag ( nta_leg_t leg,
char const *  tag 
)

Add local tag.

Parameters:
leg leg to be tagged
tag tag to be added (if NULL, a tag generated by NTA is added)
Returns:
Pointer to tag if successful, NULL otherwise.

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.

Creates a leg object, which 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.

Parameters:
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
When a leg representing dialog is created, the tags SIPTAG_CALL_ID(), SIPTAG_FROM(), SIPTAG_TO(), and SIPTAG_CSEQ() (for local CSeq number) are used to establish dialog context. The SIPTAG_FROM() is used to pass local address (From header when making a call, To header when answering to a call) to the newly created leg. Respectively, the SIPTAG_TO() is used to pass remote address (To header when making a call, From header when answering to a call).

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.

See also:
nta_leg_stateful(), nta_leg_bind(), nta_leg_tag(), nta_leg_rtag(), nta_leg_client_route(), nta_leg_server_route(), nta_leg_destroy(), nta_outgoing_tcreate(), and nta_request_f().
Related Tags:
NTATAG_NO_DIALOG(), NTATAG_STATELESS(), NTATAG_METHOD(), URLTAG_URL(), SIPTAG_CALL_ID(), SIPTAG_CALL_ID_STR(), SIPTAG_FROM(), SIPTAG_FROM_STR(), SIPTAG_TO(), SIPTAG_TO_STR(), SIPTAG_ROUTE(), NTATAG_TARGET() and SIPTAG_CSEQ().

int nta_msg_ackbye ( nta_agent_t agent,
msg_t msg 
)

ACK and BYE an unknown 200 OK response to INVITE.

A UAS may still return a 2XX series response to an INVITE request after the client transaction has been terminated. In that case, the UAC can not really accept the call, but it may send a ACK request to UAS followed immediately by BYE using nta_msg_ackbye(). The function does not create a transaction objects, but just sends the ACK and BYE request messages according to the Record-Route and Contact headers in the msg.

int nta_msg_mreply ( nta_agent_t agent,
msg_t reply,
sip_t sip,
int  status,
char const *  phrase,
msg_t req_msg,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Reply to a request message.

Note:
The ownership of msg is taken over by the function even if the function fails.

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.

Complete 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.

Parameters:
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
If request_uri contains query part, the query part is converted as SIP headers and added to the request.

Return values:
0 when successful
-1 upon an error
See also:
nta_outgoing_mcreate(), nta_outgoing_tcreate()

int nta_msg_treply ( nta_agent_t agent,
msg_t req_msg,
int  status,
char const *  phrase,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Reply to a request message.

Parameters:
agent nta agent object
req_msg request message
status status code
phrase status phrase (may be NULL if status code is well-known)
tag,value,... optional additional headers terminated by TAG_END()
Return values:
0 when succesful
-1 upon an error
Note:
The ownership of msg is taken over by the function even if the function fails.

int nta_msg_tsend ( nta_agent_t agent,
msg_t msg,
url_string_t const *  u,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Forward a request or response message.

Note:
The ownership of msg is taken over by the function even if the function fails.

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.

See also:
nta_leg_default(), nta_incoming_default().

void nta_outgoing_destroy ( nta_outgoing_t orq  ) 

Destroy a request object.

Note:
This function does not actually free the object, but marks it as disposable. The object is freed after a timeout.

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.

Parameters:
agent 
msg 
sip 
v 

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.

Return values:
A pointer to the request message is returned, or NULL if an error occurred.

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.

Parameters:
orq outgoing transaction handle
Return values:
A pointer to response message is returned, or NULL if no response message has been received.

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.

Parameters:
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
Returns:
Returns a pointer to newly created outgoing transaction object if successful, and NULL otherwise.
Note:
The caller is responsible for destroying the request message msg upon failure.

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

if the transaction is freed before returning from the function.
See also:
nta_outgoing_tcreate(), nnta_outgoing_tcancel(), nta_outgoing_destroy().
Related Tags:
NTATAG_STATELESS(), NTATAG_DELAY_SENDING(), NTATAG_BRANCH_KEY(), NTATAG_ACK_BRANCH(), NTATAG_DEFAULT_PROXY(), NTATAG_PASS_100(), NTATAG_USE_TIMESTAMP(), NTATAG_USER_VIA(), TPTAG_IDENT(), NTATAG_TPORT(). All SIP tags from <sip_tag.h> can be used to manipulate the request message. SIP tags after SIPTAG_END() are ignored, however.

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.

Create and send a PRACK request used to acknowledge a provisional response.

The request is sent using the route of the original request oorq.

When NTA receives response to the prack request, it invokes the callback function.

Parameters:
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
Returns:
If successful, return a pointer to newly created client transaction object for PRACK request, NULL otherwise.
See also:
nta_outgoing_tcreate(), nta_outgoing_tcancel(), nta_outgoing_destroy().

int nta_outgoing_setrseq ( nta_outgoing_t orq,
uint32_t  rseq 
)

Set RSeq value stored with client transaction.

Returns:
0 if rseq was set successfully

-1 if rseq is invalid or orq is NULL.

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.

Parameters:
orq 
callback 
magic 
to_tag 
rseq 
Bug:
Fix the memory leak - either one of the requests is left unreleased for ever.

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.

Parameters:
orq client transaction to cancel
callback callback function (may be NULL)
magic application context pointer
tag,value,... list of extra arguments
Note:
The function may return (NONE) if callback is NULL.
Related Tags:
NTATAG_CANCEL_2534(), NTATAG_CANCEL_408() and all the tags that are accepted by nta_outgoing_tcreate().
If NTATAG_CANCEL_408(1) or NTATAG_CANCEL_2543(1) is given, the stack generates a 487 response to the request internally. If NTATAG_CANCEL_408(1) is given, no CANCEL request is actually sent.

Note:
nta_outgoing_tcancel() refuses to send a CANCEL request for non-INVITE requests.

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.

Create a request message and pass 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.

Parameters:
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 tagged arguments
Returns:
A pointer to a newly created outgoing transaction object if successful, and NULL otherwise.
Note:
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 if the transaction is freed before returning from the function.
See also:
nta_outgoing_mcreate(), nta_outgoing_tcancel(), nta_outgoing_destroy().
Related Tags:
NTATAG_STATELESS(), NTATAG_DELAY_SENDING(), NTATAG_BRANCH_KEY(), NTATAG_ACK_BRANCH(), NTATAG_DEFAULT_PROXY(), NTATAG_PASS_100(), NTATAG_USE_TIMESTAMP(), NTATAG_USER_VIA(), TPTAG_IDENT(), NTATAG_TPORT(). All SIP tags from <sip_tag.h> can be used to manipulate the request message. SIP tags after SIPTAG_END() are ignored, however.

void nta_reliable_destroy ( nta_reliable_t rel  ) 

Destroy a reliable response.

Mark a reliable response object for destroyal and free it if possible.

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.

Note:
The stack takes over the ownership of msg. (It is destroyed even if sending the response fails.)
Parameters:
irq 
callback 
rmagic 
msg 

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.

Parameters:
irq 
callback 
rmagic 
status 
phrase 
tag,value,.. 

void outgoing_set_timer ( nta_outgoing_t orq,
unsigned  interval 
) [inline]

Set retransmit timer (orq_retry).

Set the retry timer (B/D) on the outgoing request (client transaction).


Variable Documentation

char const NTA_DEBUG[]

Environment variable determining the default debug log level.

The NTA_DEBUG environment variable is used to determine the default debug logging level. The normal level is 3.

See also:
<su_debug.h>, su_log_global, SOFIA_DEBUG

su_log_t nta_log[]

Debug log for nta module.

The nta_log is the log object used by nta module. The level of nta_log is set using NTA_DEBUG environment variable.


Sofia-SIP 1.12.6 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.