Loading...
Searching...
No Matches
nta.h File Reference

Nokia Transaction API for SIP. More...

`#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.

## Macros

#define | NTA_H
| Defined when <sofia-sip/nta.h> has been included.
#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 preliminary responses.

## Typedefs

typedef struct nta_agent_s | nta_agent_t
| NTA agent.
typedef struct nta_leg_s | nta_leg_t
| NTA call leg.
typedef struct nta_outgoing_s | nta_outgoing_t
| NTA outgoing request.
typedef struct 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 struct nta_reliable_s | nta_reliable_t
| NTA reliable response.
typedef NTA_RELIABLE_MAGIC_T | nta_reliable_magic_t
| Application context for reliable preliminary responses.

## Enumerations

enum | { NTA_SIP_T1 , NTA_SIP_T2 , NTA_SIP_T4 , NTA_TIME_MAX }

## Functions

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.
void | nta_agent_destroy (nta_agent_t *agent)
| Destroy an NTA agent object.
char const * | nta_agent_version (nta_agent_t const *a)
| Return User-Agent header.
nta_agent_magic_t * | nta_agent_magic (nta_agent_t const *a)
| Return agent context.
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.
int | nta_agent_close_tports (nta_agent_t *agent)
| Close all transports.
sip_contact_t * | nta_agent_contact (nta_agent_t const *a)
| Return Contact header.
sip_via_t * | nta_agent_via (nta_agent_t const *a)
| Return a list of Via headers.
sip_via_t * | nta_agent_public_via (nta_agent_t const *a)
| Return a list of public (UPnP, STUN) Via headers.
char const * | nta_agent_newtag (su_home_t *, char const *fmt, nta_agent_t *)
| Calculate a new unique tag.
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.
msg_t * | nta_msg_create (nta_agent_t *self, int flags)
| Create a new message belonging to the agent.
int | nta_msg_complete (msg_t *msg)
| Complete a message.
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.
int | nta_msg_is_internal (msg_t const *msg)
| Check if the message is internally generated by NTA.
int | nta_sip_is_internal (sip_t const *sip)
| Check if the headers are from response generated locally by NTA.
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.
void | nta_leg_destroy (nta_leg_t *leg)
| Destroy a leg.
nta_leg_t * | nta_default_leg (nta_agent_t const *agent)
| Return the default leg, if any.
nta_leg_magic_t * | nta_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 *)
| 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.
uint32_t | nta_leg_get_seq (nta_leg_t const *leg)
| Get local request sequence number.
uint32_t | nta_leg_get_rseq (nta_leg_t const *leg)
| Get remote request sequence number.
int | nta_leg_client_route (nta_leg_t *leg, sip_record_route_t const *route, sip_contact_t const *contact)
| Save target and route set at UAC side.
int | nta_leg_client_reroute (nta_leg_t *leg, sip_record_route_t const *route, sip_contact_t const *contact, int initial)
| Save target and route set at UAC side.
int | nta_leg_server_route (nta_leg_t *leg, sip_record_route_t const *route, sip_contact_t const *contact)
| Save target and route set at UAS side.
int | nta_leg_get_route (nta_leg_t *leg, sip_route_t const **return_route, sip_contact_t const **return_target)
| Get route.
nta_leg_t * | nta_leg_by_uri (nta_agent_t const *, url_string_t const *)
| Get leg by destination.
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.
sip_replaces_t * | nta_leg_make_replaces (nta_leg_t *leg, su_home_t *home, int early_only)
| Generate Replaces header.
nta_leg_t * | nta_leg_by_replaces (nta_agent_t *, sip_replaces_t const *)
| Get dialog leg by Replaces header.
nta_leg_t * | nta_leg_by_call_id (nta_agent_t *sa, const char *call_id)
| Get dialog leg by CallID.
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.
nta_incoming_t * | nta_incoming_default (nta_agent_t *agent)
| Create a default server transaction.
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.
nta_incoming_magic_t * | nta_incoming_magic (nta_incoming_t *irq, nta_ack_cancel_f *callback)
| Get application context for a server transaction.
nta_incoming_t * | nta_incoming_find (nta_agent_t const *agent, sip_t const *sip, sip_via_t const *v)
| Find incoming transaction.
char const * | nta_incoming_tag (nta_incoming_t *irq, char const *tag)
| Add a To tag to incoming request if needed.
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.
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.
sip_time_t | nta_incoming_received (nta_incoming_t *irq, su_nanotime_t *nano)
| When received.
int | nta_incoming_set_params (nta_incoming_t *irq, tag_type_t tag, tag_value_t value,...)
| Set server transaction parameters.
msg_t * | nta_incoming_getrequest (nta_incoming_t *irq)
| Get request message.
msg_t * | nta_incoming_getrequest_ackcancel (nta_incoming_t *irq)
| Get ACK or CANCEL message.
msg_t * | nta_incoming_getresponse (nta_incoming_t *irq)
| Get response message.
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_t * | nta_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 *ireq, 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 | nta_incoming_destroy (nta_incoming_t *irq)
| Destroy an incoming transaction.
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 we support all features which UAC requires.
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 UAC supports all the required features.
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 allow the request method.
int | nta_check_session_content (nta_incoming_t *irq, sip_t const *sip, sip_accept_t const *session_accepts, tag_type_t tag, tag_value_t value,...)
| Check that we understand session content in the request.
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 one of listed MIME content-types.
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.
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.
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.
nta_outgoing_t * | nta_outgoing_default (nta_agent_t *agent, nta_response_f *callback, nta_outgoing_magic_t *magic)
| Create a default outgoing transaction.
int | nta_outgoing_bind (nta_outgoing_t *orq, nta_response_f *callback, nta_outgoing_magic_t *magic)
| Bind callback and application context to a client transaction.
nta_outgoing_magic_t * | nta_outgoing_magic (nta_outgoing_t const *orq, nta_response_f *callback)
| Get application context bound to a client transaction.
int | nta_outgoing_status (nta_outgoing_t const *orq)
| Get the status code of a client transaction.
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.
char const * | nta_outgoing_branch (nta_outgoing_t const *orq)
| Get the branch parameter.
unsigned | nta_outgoing_delay (nta_outgoing_t const *orq)
| Get the RTT delay measured using Timestamp header.
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.
msg_t * | nta_outgoing_getresponse (nta_outgoing_t *orq)
| Get reference to response message.
msg_t * | nta_outgoing_getrequest (nta_outgoing_t *orq)
| Get request message.
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.
int | nta_outgoing_cancel (nta_outgoing_t *)
| Cancel the request.
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.
void | nta_outgoing_destroy (nta_outgoing_t *)
| Destroy a request object.
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.
int | nta_tport_keepalive (nta_outgoing_t *orq)
| Initiate STUN keepalive controller to TPORT.
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.
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.
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.
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.
void | nta_reliable_destroy (nta_reliable_t *)
| Destroy a reliable response.
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.

## Variables

char const | nta_version []
| NTA module version.

## Detailed Description

Nokia Transaction API for SIP.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com

Date
  Created: Tue Jul 18 09:18:32 2000 ppessi

## Macro Definition Documentation

## NTA_AGENT_MAGIC_T

#define NTA_AGENT_MAGIC_T

Default type of application context for NTA agents.

Application may define this to appropriate type before including <sofia-sip/nta.h>.

## NTA_INCOMING_MAGIC_T

#define NTA_INCOMING_MAGIC_T

Default type of application context for incoming NTA requests.

Application may define this to appropriate type before including <sofia-sip/nta.h>.

## NTA_LEG_MAGIC_T

#define NTA_LEG_MAGIC_T

Default type of application context for NTA call legs.

Application may define this to appropriate type before including <sofia-sip/nta.h>.

## NTA_OUTGOING_MAGIC_T

#define NTA_OUTGOING_MAGIC_T

Default type of application context for outgoing NTA requests.

Application may define this to appropriate type before including <sofia-sip/nta.h>.

## NTA_RELIABLE_MAGIC_T

#define NTA_RELIABLE_MAGIC_T

Default type of application context for reliable preliminary responses.

Application may define this to appropriate type before including <sofia-sip/nta.h>.

## Typedef Documentation

## nta_ack_cancel_f

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.

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.

Parameters

  magic | incoming request context
  ireq | incoming request
  sip | ACK/CANCEL message

Return values

  0 | This callback function should return always 0.

## nta_message_f

typedef int nta_message_f(nta_agent_magic_t *context, nta_agent_t *agent, msg_t *msg, sip_t *sip)

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

Prototype
  int message_callback(nta_agent_magic_t *context,
  nta_agent_t *agent,
  msg_t *msg,
  sip_t *sip);
  msg_t
  struct msg_s msg_t
  nta_agent_magic_t
  NTA_AGENT_MAGIC_T nta_agent_magic_t
  Application context for NTA agents.
  Definition nta.h:89
  nta_agent_t
  struct nta_agent_s nta_agent_t
  NTA agent.
  Definition nta.h:55
  sip_t
  struct sip_s sip_t

Parameters

  context | agent context
  agent | agent handle
  msg | received message
  sip | contents of message

Returns
  This callback function should always return 0.

## nta_request_f

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.

This is a callback function invoked by NTA for each incoming SIP request.

Parameters

  lmagic | call leg context
  leg | call leg handle
  ireq | incoming request
  sip | incoming request contents

Return values

  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.

## nta_response_f

typedef int nta_response_f(nta_outgoing_magic_t *magic, nta_outgoing_t *request, sip_t const *sip)

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.

Parameters

  magic | request context
  request | request handle
  sip | received status message

Returns
  This callback function should return always 0.

## Enumeration Type Documentation

## anonymous enum

anonymous enum

Enumerator
NTA_SIP_T1 | SIP T1, 500 milliseconds.
NTA_SIP_T2 | SIP T2, 4 seconds.
NTA_SIP_T4 | SIP T4, 5 seconds.
NTA_TIME_MAX | Maximum value for timers.

## Function Documentation

## nta_agent_add_tport()

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

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

Examples:
  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.

## nta_agent_close_tports()

int nta_agent_close_tports | ( | nta_agent_t * | agent | ) |

Close all transports.

Since
  Experimental in 1.12.2.

## nta_agent_contact()

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);
sip_record_route_create
sip_record_route_t * sip_record_route_create(su_home_t *, url_t const *rq_url, url_t const *m_url)
msg_home
#define msg_home(h)

Returns
  A sip_contact_t object corresponding to the agent.

## nta_agent_create()

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,... | tagged arguments

Related Tags:
  NTATAG_ALIASES(), NTATAG_BAD_REQ_MASK(), NTATAG_BAD_RESP_MASK(), NTATAG_BLACKLIST(), NTATAG_CANCEL_2543(), NTATAG_CANCEL_487(), NTATAG_CLIENT_RPORT(), NTATAG_DEBUG_DROP_PROB(), NTATAG_DEFAULT_PROXY(), NTATAG_EXTRA_100(), NTATAG_GRAYLIST(), NTATAG_MAXSIZE(), NTATAG_MAX_FORWARDS(), NTATAG_MERGE_482(), NTATAG_MCLASS() NTATAG_PASS_100(), NTATAG_PASS_408(), NTATAG_PRELOAD(), NTATAG_PROGRESS(), NTATAG_REL100(), NTATAG_SERVER_RPORT(), NTATAG_SIPFLAGS(), NTATAG_SIP_T1X64(), NTATAG_SIP_T1(), NTATAG_SIP_T2(), NTATAG_SIP_T4(), NTATAG_STATELESS(), NTATAG_TAG_3261(), NTATAG_TCP_RPORT(), NTATAG_TIMEOUT_408(), NTATAG_TLS_RPORT(), NTATAG_TIMER_C(), NTATAG_MAX_PROCEEDING(), NTATAG_UA(), NTATAG_UDP_MTU(), NTATAG_USER_VIA(), NTATAG_USE_NAPTR(), NTATAG_USE_SRV() and NTATAG_USE_TIMESTAMP().

Note
  The value from following tags are stored, but they currently do nothing: NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_OPTIONS(), NTATAG_SMIME()
  It is possible to provide ``(url_string_t*)-1 as contact_url. In that case, no server sockets are bound.

Return values

  handle | to the agent when successful,
  NULL | upon an error.

See also
  NUTAG_

## nta_agent_destroy()

void nta_agent_destroy | ( | nta_agent_t * | agent | ) |

Destroy an NTA agent object.

Parameters

  agent | the NTA agent object to be destroyed.

## nta_agent_get_params()

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_BLACKLIST_REF(), NTATAG_CANCEL_2543_REF(), NTATAG_CANCEL_487_REF(), NTATAG_CLIENT_RPORT_REF(), NTATAG_CONTACT_REF(), NTATAG_DEBUG_DROP_PROB_REF(), NTATAG_DEFAULT_PROXY_REF(), NTATAG_EXTRA_100_REF(), NTATAG_GRAYLIST_REF(), NTATAG_MAXSIZE_REF(), NTATAG_MAX_FORWARDS_REF(), NTATAG_MCLASS_REF(), NTATAG_MERGE_482_REF(), NTATAG_MAX_PROCEEDING_REF(), NTATAG_PASS_100_REF(), NTATAG_PASS_408_REF(), NTATAG_PRELOAD_REF(), NTATAG_PROGRESS_REF(), NTATAG_REL100_REF(), NTATAG_SERVER_RPORT_REF(), NTATAG_SIGCOMP_ALGORITHM_REF(), NTATAG_SIGCOMP_OPTIONS_REF(), NTATAG_SIPFLAGS_REF(), NTATAG_SIP_T1_REF(), NTATAG_SIP_T1X64_REF(), NTATAG_SIP_T2_REF(), NTATAG_SIP_T4_REF(), NTATAG_SMIME_REF(), NTATAG_STATELESS_REF(), NTATAG_TAG_3261_REF(), NTATAG_TIMEOUT_408_REF(), NTATAG_TIMER_C_REF(), NTATAG_UA_REF(), NTATAG_UDP_MTU_REF(), NTATAG_USER_VIA_REF(), NTATAG_USE_NAPTR_REF(), NTATAG_USE_SRV_REF(), and NTATAG_USE_TIMESTAMP_REF().

## nta_agent_get_stats()

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_ACKED_TR_REF(), NTATAG_S_BAD_MESSAGE_REF(), NTATAG_S_BAD_REQUEST_REF(), NTATAG_S_BAD_RESPONSE_REF(), NTATAG_S_CANCELED_TR_REF(), NTATAG_S_CLIENT_TR_REF(), NTATAG_S_DIALOG_TR_REF(), NTATAG_S_DROP_REQUEST_REF(), NTATAG_S_DROP_RESPONSE_REF(), NTATAG_S_IRQ_HASH_REF(), NTATAG_S_IRQ_HASH_USED_REF(), NTATAG_S_LEG_HASH_REF(), NTATAG_S_LEG_HASH_USED_REF(), NTATAG_S_MERGED_REQUEST_REF(), NTATAG_S_ORQ_HASH_REF(), NTATAG_S_ORQ_HASH_USED_REF(), NTATAG_S_RECV_MSG_REF(), NTATAG_S_RECV_REQUEST_REF(), NTATAG_S_RECV_RESPONSE_REF(), NTATAG_S_RECV_RETRY_REF(), NTATAG_S_RETRY_REQUEST_REF(), NTATAG_S_RETRY_RESPONSE_REF(), NTATAG_S_SENT_MSG_REF(), NTATAG_S_SENT_REQUEST_REF(), NTATAG_S_SENT_RESPONSE_REF(), NTATAG_S_SERVER_TR_REF(), NTATAG_S_TOUT_REQUEST_REF(), NTATAG_S_TOUT_RESPONSE_REF(), NTATAG_S_TRLESS_200_REF(), NTATAG_S_TRLESS_REQUEST_REF(), NTATAG_S_TRLESS_RESPONSE_REF(), and NTATAG_S_TRLESS_TO_TR_REF(),

## nta_agent_newtag()

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.

## nta_agent_public_via()

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.

## nta_agent_set_params()

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_MAX_PROCEEDING(), 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_BLACKLIST(), NTATAG_CANCEL_2543(), NTATAG_CANCEL_487(), NTATAG_CLIENT_RPORT(), NTATAG_DEBUG_DROP_PROB(), NTATAG_DEFAULT_PROXY(), NTATAG_EXTRA_100(), NTATAG_GRAYLIST(), NTATAG_MAXSIZE(), NTATAG_MAX_FORWARDS(), NTATAG_MERGE_482(), NTATAG_MCLASS() NTATAG_PASS_100(), NTATAG_PASS_408(), NTATAG_PRELOAD(), NTATAG_PROGRESS(), NTATAG_REL100(), NTATAG_SERVER_RPORT(), NTATAG_SIPFLAGS(), NTATAG_SIP_T1X64(), NTATAG_SIP_T1(), NTATAG_SIP_T2(), NTATAG_SIP_T4(), NTATAG_STATELESS(), NTATAG_TAG_3261(), NTATAG_TCP_RPORT(), NTATAG_TIMEOUT_408(), NTATAG_TLS_RPORT(), NTATAG_TIMER_C(), NTATAG_MAX_PROCEEDING(), NTATAG_UA(), NTATAG_UDP_MTU(), NTATAG_USER_VIA(), NTATAG_USE_NAPTR(), NTATAG_USE_SRV() and NTATAG_USE_TIMESTAMP().

Note
  The value from following tags are stored, but they currently do nothing: NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_OPTIONS(), NTATAG_SMIME()

## nta_agent_version()

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.

## nta_agent_via()

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.

## nta_check_accept()

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 one of listed MIME content-types.

The list of acceptable content-types are compared with the acceptable content-types. If match is found, it is returned in return_acceptable. If no match is found, a 406 is returned. If irq is non-NULL, the 406 response message is sent to the client, too.

Parameters

  irq | incoming transaction object (may be NULL).
  sip | contents of the SIP message
  acceptable | list of acceptable content types
  return_acceptable | optional return-value parameter for matched content-type
  tag,value,... | optional list of tagged arguments used when responding to the transaction

Return values

  0 | if successful
  406 | if no supported Content-Type is acceptable by client
  500 | if an internal error occurred

Note
  From UNRELEASED onwards, checks for wildcards, too.

## nta_check_method()

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 allow the request method.

The request-method is compared with the list of supported methods in allow. If match is found, 0 is is returned. Otherwise, if the request-method is well-known, 405 is returned. If the request-method is unknown, 501 is returned. If irq is non-NULL, the 405 or 501 response message is sent to the client, too.

Parameters

  irq | incoming transaction object (may be NULL).
  sip | contents of the SIP message
  allow | list of allowed methods
  tag,value,... | optional list of tagged arguments used when responding to the transaction

Return values

  0 | if successful
  405 | is request-method is not allowed
  501 | if request-method is unknown
  500 | if an internal error occurred

## nta_check_required()

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 we support all features which UAC requires.

The list of supported features is compared with the list of features required by the UAC. If some features are not listed as supported, return

1. If irq is non-NULL, the 420 response message is sent to the client along with list of unsupported features in the Unsupported header, too.

Parameters

  irq | incoming transaction object (may be NULL).
  sip | contents of the SIP message
  supported | list of protocol features supported
  tag,value,... | optional list of tagged arguments used when responding to the transaction

Return values

  0 | if successful
  420 | if any of the required features is not supported by UAS
  500 | if an internal error occurred

## nta_check_session_content()

int nta_check_session_content | ( | nta_incoming_t * | irq,
|  | sip_t const * | sip,
|  | sip_accept_t const * | session_accepts,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Check that we understand session content in the request.

If there is no Content-Disposition header or the Content-Disposition header indicated "session", the message body and content-type is compared with the acceptable session content-types listed in session_accepts. (typically, `"application/sdp"`). If no match is found, a 415 is returned. If irq is non-NULL, the 415 response message is sent to the client, too.

If the Content-Disposition header indicates something else but "session", and it does not contain "handling=optional" parameter, a 415 response is returned, too.

Also, the Content-Encoding header is checked. If it is not empty (indicating no content-encoding), a 415 response is returned, too.

Parameters

  irq | incoming (server) transaction object (may be NULL).
  sip | contents of the SIP message
  session_accepts | list of acceptable content-types for "session" content disposition
  tag,value,... | optional list of tagged arguments used when responding to the transaction

Return values

  0 | if successful
  415 | if Content-Type is not acceptable
  500 | if an internal error occurred

## nta_check_session_expires()

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 shortest acceptable session expiration time in Min-SE header.

Parameters

  irq | incoming transaction object (may be NULL).
  sip | contents of the SIP message
  my_min_se | minimal session expiration time in seconds
  tag,value,... | optional list of tagged arguments used when responding to the transaction

Return values

  0 | when successful
  422 | if session expiration time is too small
  500 | if an internal error occurred

## nta_check_supported()

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 UAC supports all the required features.

The list of required features is compared with the features supported by the UAC. If some features are not supported, return 421. If irq is non-NULL, the 421 response message is sent to the client, too.

Parameters

  irq | incoming transaction object (may be NULL).
  sip | contents of the SIP message
  require | list of required protocol features
  tag,value,... | optional list of tagged arguments used when responding to the transaction

Return values

  0 | if successful
  421 | if any of the required features is not supported by UAC
  500 | if an internal error occurred

## nta_incoming_bind()

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

## nta_incoming_complete_response()

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

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:

\n 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

## nta_incoming_create_response()

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

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

## nta_incoming_destroy()

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

## nta_incoming_getrequest()

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.

## nta_incoming_getrequest_ackcancel()

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.

## nta_incoming_getresponse()

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.

## nta_incoming_magic()

nta_incoming_magic_t * nta_incoming_magic | ( | nta_incoming_t * | irq,
|  | nta_ack_cancel_f * | callback )

Get application context for a server transaction.

Parameters

  irq | server transaction
  callback | callback pointer

Return the application context bound to the server transaction. If the callback function pointer is given, return application context only if the callback matches with the callback bound to the server transaction.

## nta_incoming_mreply()

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

## nta_incoming_received()

sip_time_t nta_incoming_received | ( | nta_incoming_t * | irq,
|  | su_nanotime_t * | return_nano )

When received.

Return timestamp from the reception of the initial request.

Since
  New in 1.12.7.

## nta_incoming_set_params()

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. Among others, parameters determine the way the SigComp compression is handled.

Related Tags:
  NTATAG_COMP(), NTATAG_SIGCOMP_CLOSE() and NTATAG_EXTRA_100().

Return values

  number | of set parameters when succesful
  -1 | upon an error

## nta_incoming_tag()

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.

## nta_incoming_treply()

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

## nta_is_internal_msg()

int nta_is_internal_msg | ( | msg_t const * | msg | ) |

Check if the message is internally generated by NTA.

Deprecated
  Use nta_msg_is_internal() instead

## nta_leg_bind()

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

nta_leg_t * nta_leg_by_call_id | ( | nta_agent_t * | sa,
|  | const char * | call_id )

Get dialog leg by CallID.

Get dialog leg by CallID.

Note
  Usually there should be only single dialog per Call-ID on User-Agents. However, proxies may fork requests initiating the dialog and result in multiple calls per Call-ID.

Since
  New in 1.12.9.

## nta_leg_by_dialog()

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.

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 | ignored
  local_tag | if non-NULL and there is local tag associated with leg, it must math
  local_uri | ignored

Note
  If remote_tag or local_tag is an empty string (""), the tag is ignored when matching legs.

## nta_leg_by_replaces()

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

Get dialog leg by Replaces header.

Get dialog leg by Replaces header.

Since
  New in 1.12.2.

## nta_leg_client_reroute()

int nta_leg_client_reroute | ( | nta_leg_t * | leg,
|  | sip_record_route_t const * | route,
|  | sip_contact_t const * | contact,
|  | int | initial )

Save target and route set at UAC side.

If initial is true, the route set is modified even if it has been set earlier.

Parameters

  leg | pointer to dialog leg
  route | Record-Route headers from response
  contact | Contact header from response
  initial | true if response to initial transaction

See also
  nta_leg_client_route(), nta_leg_server_route(), RFC 3261 section 12.1.2

Since
  New in 1.12.11

## nta_leg_client_route()

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

Save target and route set at UAC side.

See also
  nta_leg_client_reroute(), nta_leg_server_route(), RFC 3261 section 12.1.2

Bug
  Allows modifying the route set after initial transaction, if initial transaction had no Record-Route headers.

Deprecated
  Use nta_leg_client_reroute() instead.

## nta_leg_destroy()

void nta_leg_destroy | ( | nta_leg_t * | leg | ) |

Destroy a leg.

Parameters

  leg | leg to be destroyed

## nta_leg_get_route()

int nta_leg_get_route | ( | nta_leg_t * | leg,
|  | sip_route_t const ** | return_route,
|  | sip_contact_t const ** | return_target )

Get route.

Get route.

## nta_leg_get_rseq()

uint32_t nta_leg_get_rseq | ( | nta_leg_t const * | leg | ) |

Get remote request sequence number.

Since
  New in 1.12.9

## nta_leg_get_seq()

uint32_t nta_leg_get_seq | ( | nta_leg_t const * | leg | ) |

Get local request sequence number.

Since
  New in 1.12.9

## nta_leg_make_replaces()

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

Generate Replaces header.

Generate Replaces header.

Since
  New in 1.12.2.

## nta_leg_rtag()

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

Add remote 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.

## nta_leg_server_route()

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

Save target and route set at UAS side.

Parameters

  leg | pointer to dialog leg
  route | Record-Route headers from request
  contact | Contact header from request

See also
  nta_leg_client_reroute(), RFC 3261 section 12.1.1

## nta_leg_tag()

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

Add local 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_tcreate()

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

## nta_msg_request_complete()

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

## nta_outgoing_bind()

int nta_outgoing_bind | ( | nta_outgoing_t * | orq,
|  | nta_response_f * | callback,
|  | nta_outgoing_magic_t * | magic )

Bind callback and application context to a client transaction.

Parameters

  orq | outgoing client transaction
  callback | callback function (may be NULL)
  magic | application context pointer (given as argument to callback)

Since
  New in 1.12.9

## nta_outgoing_branch()

char const * nta_outgoing_branch | ( | nta_outgoing_t const * | orq | ) |

Get the branch parameter.

Since
  New in 1.12.7.

## nta_outgoing_default()

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

## nta_outgoing_destroy()

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

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 |

## nta_outgoing_getrequest()

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.

## nta_outgoing_getresponse()

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

nta_outgoing_magic_t * nta_outgoing_magic | ( | nta_outgoing_t const * | orq,
|  | nta_response_f * | callback )

Get application context bound to a client transaction.

Parameters

  orq | outgoing client transaction
  callback | callback function (may be NULL)

Return the application context bound to a client transaction. If the callback function pointer is given, return application context only if the callback matches with the callback bound to the client transaction.

Since
  New in 1.12.11

## nta_outgoing_mcreate()

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
  (nta_outgoing_t *)-1
  nta_outgoing_t
  struct nta_outgoing_s nta_outgoing_t
  NTA outgoing request.
  Definition nta.h:59
  if the transaction is freed before returning from the function.

See also
  nta_outgoing_tcreate(), 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 <sofia-sip/sip_tag.h> can be used to manipulate the request message. SIP tags after SIPTAG_END() are ignored, however.

## nta_outgoing_prack()

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

## nta_outgoing_setrseq()

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

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

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
  (nta_outgoing_t *)-1
  (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_tcreate()

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
  (nta_outgoing_t *)-1
  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 <sofia-sip/sip_tag.h> can be used to manipulate the request message. SIP tags after SIPTAG_END() are ignored, however.

## nta_reliable_destroy()

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

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

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

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