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

Sofia-SIP User Agent Library API. More...

`#include <sofia-sip/su_wait.h>`
`#include <sofia-sip/url.h>`
`#include <sofia-sip/sip.h>`
`#include <sofia-sip/nua_tag.h>`
Include dependency graph for nua.h:

## Macros

#define | NUA_H
| Defined when <sofia-sip/nua.h> has been included.
#define | NUA_VERSION
| NUA API version.
#define | nua_handle_home(nh)
| Cast a nua_handle_t pointer to a su_home_t.

## Typedefs

typedef NUA_MAGIC_T | nua_magic_t
| Application context for NUA agent.
typedef NUA_HMAGIC_T | nua_hmagic_t
| Application context for NUA handle.
typedef enum nua_nw_detector_e | nua_nw_detector_t
| Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES().
typedef enum nua_event_e | nua_event_t
| Events.
typedef void(* | nua_callback_f) (nua_event_t event, int status, char const *phrase, nua_t *nua, nua_magic_t *magic, nua_handle_t *nh, nua_hmagic_t *hmagic, sip_t const *sip, tagi_t tags[])
| Typedef of NUA event callback.
typedef NUA_SAVED_EVENT_T | nua_saved_event_t
| Abstract type for saved nua events.

## Enumerations

enum | nua_nw_detector_e
| Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES(). More...
enum | nua_event_e { }
| Events. More...

## Functions

nua_t * | nua_create (su_root_t *root, nua_callback_f callback, nua_magic_t *magic, tag_type_t tag, tag_value_t value,...)
| Create a NUA agent.
void | nua_shutdown (nua_t *nua)
| Shutdown NUA stack.
void | nua_destroy (nua_t *nua)
| Destroy the NUA stack.
nua_magic_t * | nua_magic (nua_t *nua)
| Fetch callback context from nua.
void | nua_set_params (nua_t *, tag_type_t, tag_value_t,...)
| Set NUA parameters.
void | nua_get_params (nua_t *nua, tag_type_t, tag_value_t,...)
| Get NUA parameters.
nua_handle_t * | nua_default (nua_t *nua)
| Obtain default operation handle of the NUA stack object.
nua_handle_t * | nua_handle (nua_t *nua, nua_hmagic_t *hmagic, tag_type_t, tag_value_t,...)
| Create an operation handle.
void | nua_handle_destroy (nua_handle_t *h)
| Destroy a handle.
nua_handle_t * | nua_handle_ref (nua_handle_t *)
| Make a new reference to handle.
int | nua_handle_unref (nua_handle_t *)
| Destroy reference to handle.
void | nua_handle_bind (nua_handle_t *nh, nua_hmagic_t *magic)
| Bind a callback context to an operation handle.
nua_hmagic_t * | nua_handle_magic (nua_handle_t *nh)
| Fetch a callback context from an operation handle.
void | nua_set_hparams (nua_handle_t *, tag_type_t, tag_value_t,...)
| Set handle parameters.
void | nua_get_hparams (nua_handle_t *, tag_type_t, tag_value_t,...)
| Get handle parameters.
int | nua_handle_has_invite (nua_handle_t const *nh)
| Check if operation handle is used for INVITE.
int | nua_handle_has_subscribe (nua_handle_t const *nh)
| Check if operation handle has been used with outgoing SUBSCRIBE of REFER request.
int | nua_handle_has_register (nua_handle_t const *nh)
| Check if operation handle has been used with nua_register() or nua_unregister().
int | nua_handle_has_active_call (nua_handle_t const *nh)
| Check if operation handle has an active call.
int | nua_handle_has_call_on_hold (nua_handle_t const *nh)
| Check if operation handle has a call on hold.
int | nua_handle_has_events (nua_handle_t const *nh)
| Check if handle has active event subscriptions (refers sent).
int | nua_handle_has_registrations (nua_handle_t const *nh)
| Check if operation handle has active registrations.
sip_to_t const * | nua_handle_remote (nua_handle_t const *nh)
| Get the remote address (From/To header) of operation handle.
sip_to_t const * | nua_handle_local (nua_handle_t const *nh)
| Get the local address (From/To header) of operation handle.
char const * | nua_event_name (nua_event_t event)
| Get name for NUA event.
char const * | nua_callstate_name (enum nua_callstate state)
| Get name for NUA callstate.
char const * | nua_substate_name (enum nua_substate substate)
| Return name of subscription state.
enum nua_substate | nua_substate_make (char const *sip_substate)
| Convert string to enum nua_substate.
void | nua_register (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Send SIP REGISTER request to the registrar.
void | nua_unregister (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Unregister.
void | nua_invite (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Place a call using SIP INVITE method.
void | nua_ack (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Acknowledge a succesfull response to INVITE request.
void | nua_prack (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Acknowledge a reliable preliminary response to INVITE request.
void | nua_options (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Query capabilities from server.
void | nua_publish (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Send PUBLISH request to publication server.
void | nua_unpublish (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Send un-PUBLISH request to publication server.
void | nua_message (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Send an instant message.
void | nua_chat (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Send a chat message.
void | nua_info (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Send an INFO request.
void | nua_subscribe (nua_handle_t *nh, tag_type_t, tag_value_t,...)
| Subscribe a SIP event.
void | nua_unsubscribe (nua_handle_t *, tag_type_t, tag_value_t,...)
| Unsubscribe an event.
void | nua_notify (nua_handle_t *, tag_type_t, tag_value_t,...)
| Send a NOTIFY message.
void | nua_notifier (nua_handle_t *, tag_type_t, tag_value_t,...)
| Create an event server.
void | nua_terminate (nua_handle_t *, tag_type_t, tag_value_t,...)
| Terminate an event server.
void | nua_refer (nua_handle_t *, tag_type_t, tag_value_t,...)
| Transfer a call.
void | nua_update (nua_handle_t *, tag_type_t, tag_value_t,...)
| Update a call.
void | nua_bye (nua_handle_t *, tag_type_t, tag_value_t,...)
| Hangdown a call.
void | nua_cancel (nua_handle_t *, tag_type_t, tag_value_t,...)
| Cancel an INVITE operation.
void | nua_authenticate (nua_handle_t *, tag_type_t, tag_value_t,...)
| Authenticate an operation.
void | nua_authorize (nua_handle_t *, tag_type_t, tag_value_t,...)
| Authorize a subscriber.
void | nua_method (nua_handle_t *, tag_type_t, tag_value_t,...)
| Send a request message with an extension method.
void | nua_respond (nua_handle_t *nh, int status, char const *phrase, tag_type_t, tag_value_t,...)
| Respond to a request with given status code and phrase.
int | nua_event_is_incoming_request (nua_event_t e)
| Check if event can be responded with nua_respond().
char const * | nua_generate_instance_identifier (su_home_t *)
| Generate an instance identifier.
int | nua_save_event (nua_t *nua, nua_saved_event_t return_saved[1])
| Save last nua event.
nua_event_data_t const * | nua_event_data (nua_saved_event_t const saved[1])
| Get information from saved event.
void | nua_destroy_event (nua_saved_event_t *saved)
| Destroy a save nua event.
msg_t * | nua_saved_event_request (nua_saved_event_t const *saved)
| Get request message from saved nua event.
msg_t * | nua_current_request (nua_t const *nua)
| Get current request message.
sip_replaces_t * | nua_handle_make_replaces (nua_handle_t *nh, su_home_t *home, int early_only)
| Generate a Replaces header for handle.
nua_handle_t * | nua_handle_by_replaces (nua_t *nua, sip_replaces_t const *rp)
| Obtain a new reference to an existing handle based on Replaces header.
nua_handle_t * | nua_handle_by_call_id (nua_t *nua, const char *call_id)
| Obtain a new reference to an existing handle based on Call-ID.

## Variables

char const | nua_version []
| NUA module version.

## Detailed Description

Sofia-SIP User Agent Library API.

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

Date
  Created: Wed Feb 14 17:09:44 2001 ppessi

## Typedef Documentation

## nua_nw_detector_t

typedef enum nua_nw_detector_e nua_nw_detector_t

Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES().

See also
  NUTAG_DETECT_NETWORK_UPDATES(), nua_i_network_changed

Since
  New in 1.12.2.

## Enumeration Type Documentation

## nua_event_e

enum nua_event_e

Events.

The NUA event loop calls an event callback function when an application needs to act on something that happened in the Sofia stack. The callback function is registered when nua_create() function call is used to create the NUA stack object.

The prototype of the event callback function is:

void nua_callback_f(nua_event_t event,
int status,
char const *phrase,
nua_t *nua,
nua_magic_t *magic,
nua_handle_t *nh,
nua_hmagic_t *hmagic,
sip_t const *sip,
tagi_t tags[]);
nua_hmagic_t
NUA_HMAGIC_T nua_hmagic_t
Application context for NUA handle.
Definition nua.h:66
nua_magic_t
NUA_MAGIC_T nua_magic_t
Application context for NUA agent.
Definition nua.h:60
nua_event_t
enum nua_event_e nua_event_t
Events.
nua_callback_f
void(* nua_callback_f)(nua_event_t event, int status, char const *phrase, nua_t *nua, nua_magic_t *magic, nua_handle_t *nh, nua_hmagic_t *hmagic, sip_t const *sip, tagi_t tags[])
Typedef of NUA event callback.
Definition nua.h:178
nua_handle_t
struct nua_handle_s nua_handle_t
NUA transaction handle.
Definition nua_tag.h:66
nua_t
struct nua_s nua_t
NUA agent.
Definition nua_tag.h:63
sip_t
struct sip_s sip_t
tagi_t

Parameters

  event | Callback event identification. Always present
  status | Protocol status code. Always present
  phrase | Text corresponding to status code. Always present
  nua | Pointer to NUA stack object. Always present
  magic | Pointer to callback context from nua_create(). Always present
  nh | Pointer to operation handle.
  hmagic | Pointer to callback context from nua_handle().
  sip | Headers in parsed incoming message. May be NULL. See also nua_current_request().
  tags | Tag list containing more information about the state of NUA. May be empty.

Note that the contents of the last four parameters vary depending on the event. The descriptions can be found from the description of the individual event.

The events can be divided into the following categories:

Status or Error Indications:
  nua_i_active
  nua_i_error
  nua_i_fork
  nua_i_media_error
  nua_i_subscription
  nua_i_state
  nua_i_terminated

SIP requests:
  nua_i_ack
  nua_i_bye
  nua_i_cancel
  nua_i_chat
  nua_i_info
  nua_i_invite
  nua_i_message
  nua_i_method
  nua_i_notify
  nua_i_options
  nua_i_prack
  nua_i_publish
  nua_i_refer
  nua_i_register
  nua_i_subscribe
  nua_i_update

Responses:
  nua_r_get_params
  nua_r_notifier
  nua_r_shutdown
  nua_r_terminate

SIP responses:
  nua_r_bye
  nua_r_cancel
  nua_r_info
  nua_r_invite
  nua_r_message
  nua_r_notify
  nua_r_options
  nua_r_prack
  nua_r_publish
  nua_r_refer
  nua_r_register
  nua_r_subscribe
  nua_r_unpublish
  nua_r_unregister
  nua_r_unsubscribe
  nua_r_update

See also
  nua_event_is_incoming_request(), nua_event_name()

Enumerator

nua_i_error

Error indication.

Will be sent when an internal error happened or an error occurred while responding a request.

Parameters

  status | SIP status code or NUA status code (>= 900) describing the problem
  phrase | a short textual description of status code
  nh | NULL or operation handle associated with the call
  hmagic | NULL or operation magic associated with the call
  sip | NULL
  tags | empty or error specific information

nua_i_invite

Incoming call INVITE.

Indication of incoming call or re-INVITE request.

Parameters

  status | statuscode of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with this call (maybe created for this call)
  hmagic | application context associated with this call (maybe NULL if call handle was created for this call)
  sip | incoming INVITE request
  tags | SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO()

Responding to INVITE with nua_respond()

If status in nua_i_invite event is below 200, the application should accept or reject the call with nua_respond(). See the NUA Call Model for the detailed explanation of various options in call processing at server end.

The INVITE request takes care of session setup using SDP Offer-Answer negotiation as specified in RFC 3264 (updated in RFC 3262 section 5, RFC 3311, and RFC 3312). The Offer-Answer can be taken care by application (if NUTAG_MEDIA_ENABLE(0) parameter has been set) or by the built-in SDP Offer/Answer engine soa (by default and when NUTAG_MEDIA_ENABLE(1) parameter has been set). When soa is enabled, it will take care of parsing the SDP, negotiating the media and codecs, and including the SDP in the SIP message bodies as required by the Offer-Answer model.

When soa is enabled, the SDP in the incoming INVITE is parsed and feed to a soa_session_t object. The nua_i_state event sent to the application immediately after nua_i_invite will contain the parsing results in SOATAG_REMOTE_SDP() and SOATAG_REMOTE_SDP_STR() tags.

Note that currently the parser within nua does not handle MIME multipart. The SDP Offer/Answer engine can get confused if the SDP offer is included in a MIME multipart, therefore such an INVITE is rejected with 415 Unsupported Media Type error response: the client is expected to retry the INVITE without MIME multipart content.

If the call is to be accepted, the application should include the SDP in the 2XX response. If soa is not disabled with NUTAG_MEDIA_ENABLE(0), the SDP should be included in the SOATAG_USER_SDP() or SOATAG_USER_SDP_STR() parameter given to nua_respond(). If it is disabled, the SDP should be included in the response message using SIPTAG_PAYLOAD() or SIPTAG_PAYLOAD_STR(). Also, the Content-Type should be set using SIPTAG_CONTENT_TYPE() or SIPTAG_CONTENT_TYPE_STR().

Preliminary Responses and 100rel

Call progress can be signaled with preliminary responses (with status code in the range 101..199). It is possible to conclude the SDP Offer-Answer negotiation using preliminary responses, too. If NUTAG_EARLY_ANSWER(1), SOATAG_USER_SDP() or SOATAG_USER_SDP_STR() parameter is included with in a preliminary nua_response(), the SDP answer is generated and sent with the preliminary responses, too.

The preliminary responses are sent reliably if feature tag "100rel" is included in the Require header of the response or if NUTAG_EARLY_MEDIA(1) parameter has been given. The reliably delivery of preliminary responses mean that a sequence number is included in the RSeq header in the response message and the response message is resent until the client responds with a PRACK request with matching sequence number in RAck header.

Note that only the "183" response is sent reliably if the NUTAG_ONLY183_100REL(1) parameter has been given. The reliable preliminary responses are acknowledged with PRACK request sent by the client.

Note if the SDP offer-answer is completed with the reliable preliminary responses, the is no need to include SDP in 200 OK response (or other 2XX response). However, it the tag NUTAG_INCLUDE_EXTRA_SDP(1) is included with nua_respond(), a copy of the SDP answer generated earlier by soa is included as the message body.

See also
  nua_respond(), Detailed Server-Side Call Model, nua_i_state, NUTAG_MEDIA_ENABLE(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), RFC 3262, NUTAG_EARLY_ANSWER(), NUTAG_EARLY_MEDIA(), NUTAG_ONLY183_100REL(), NUTAG_INCLUDE_EXTRA_SDP(), nua_i_prack, nua_i_update, nua_update(), nua_invite(), nua_r_invite

Third Party Call Control

When so called 2rd party call control is used, the initial INVITE may not contain SDP offer. In that case, the offer is sent by the recipient of the INVITE request (User-Agent Server, UAS). The SDP sent in 2XX response (or in a preliminary reliable response) is considered as an offer, and the answer will be included in the ACK request sent by the UAC (or PRACK in case of preliminary reliable response).

See also
  Third Party Call Control

nua_i_cancel

Incoming INVITE has been cancelled.

Incoming INVITE has been cancelled by the client.

Parameters

  status | status code of response to CANCEL sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | incoming CANCEL request
  tags | empty

See also
  Detailed Server-Side Call Model, nua_cancel(), nua_i_invite, nua_i_state

nua_i_ack

Final response to INVITE has been ACKed.

Final response to INVITE has been acknowledged by UAC with ACK.

Note
  This event is only sent after 2XX response.

Parameters

  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | incoming ACK request
  tags | empty

See also
  nua_i_invite, nua_i_state, Detailed Server-Side Call Model, nua_ack()

nua_i_fork

Outgoing call has been forked.

This is sent when an INVITE request is answered with multiple 2XX series responses.

Parameters

  status | response status code
  phrase | a short textual description of status code
  nh | operation handle associated with the original call
  hmagic | operation magic associated with the original call
  sip | preliminary or 2XX response to INVITE
  tags | NUTAG_HANDLE() of the new forked call

See also
  nua_r_invite, nua_i_state, NUA Call Model

nua_i_active

A call has been activated.

This event will be sent after a succesful response to the initial INVITE has been received and the media has been activated.

Parameters

  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | NULL
  tags | SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO(), SOATAG_ACTIVE_IMAGE(), SOATAG_ACTIVE_CHAT().

Deprecated
  Use nua_i_state instead.

See also
  NUA Call Model, nua_i_state, nua_i_terminated, nua_i_invite

nua_i_terminated

A call has been terminated.

This event will be sent after a call has been terminated. A call is terminated, when 1) an error response (300..599) is sent to an incoming initial INVITE 2) a reliable response (200..299 or reliable preliminary response) to an incoming initial INVITE is not acknowledged with ACK or PRACK 3) BYE is received or sent

Parameters

  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | NULL
  tags | empty

Deprecated
  Use nua_i_state instead.

See also
  NUA Call Model, nua_i_state, nua_i_active, nua_i_bye, nua_i_invite

nua_i_state

Call state has changed.

This event will be sent whenever the call state changes.

In addition to basic changes of session status indicated with enum nua_callstate, the RFC 3264 SDP Offer/Answer negotiation status is also included. The tags NUTAG_OFFER_RECV() or NUTAG_ANSWER_RECV() indicate whether the remote SDP that was received was considered as an offer or an answer. Tags NUTAG_OFFER_SENT() or NUTAG_ANSWER_SENT() indicate whether the local SDP which was sent was considered as an offer or answer.

If the soa SDP negotiation is enabled (by default or with NUTAG_MEDIA_ENABLE(1)), the received remote SDP is included in tags SOATAG_REMOTE_SDP() and SOATAG_REMOTE_SDP_STR(). The SDP negotiation result from soa is included in the tags SOATAG_LOCAL_SDP() and SOATAG_LOCAL_SDP_STR().

SOATAG_ACTIVE_AUDIO() and SOATAG_ACTIVE_VIDEO() are informational tags used to indicate what is the status of audio or video.

Note that nua_i_state also covers the information relayed in call establisment (nua_i_active) and termination (nua_i_terminated) events.

Parameters

  status | protocol status code (always present)
  phrase | short description of status code (always present)
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | NULL
  tags | NUTAG_CALLSTATE(), SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR(), NUTAG_OFFER_SENT(), NUTAG_ANSWER_SENT(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(), NUTAG_OFFER_RECV(), NUTAG_ANSWER_RECV(), SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO(), SOATAG_ACTIVE_IMAGE(), SOATAG_ACTIVE_CHAT().

See also
  NUA Call Model, nua_i_active, nua_i_terminated, nua_invite(), nua_r_invite, nua_i_invite, nua_respond(), NUTAG_MEDIA_ENABLE(), NUTAG_AUTOALERT(), NUTAG_AUTOANSWER(), NUTAG_EARLY_MEDIA(), NUTAG_EARLY_ANSWER(), NUTAG_INCLUDE_EXTRA_SDP(), nua_ack(), NUTAG_AUTOACK(), nua_bye(), nua_r_bye, nua_i_bye, nua_cancel(), nua_r_cancel, nua_i_cancel, nua_prack(), nua_r_prack, nua_i_prack, nua_update(), nua_r_update, nua_i_update

History
  Prior 1.12.6 the tags NUTAG_OFFER_RECV(), NUTAG_ANSWER_RECV(), NUTAG_ANSWER_SENT(), NUTAG_OFFER_SENT() were not included with nua_i_state eventif media was disabled.

nua_i_outbound

Status from outbound processing.

Status from outbound engine.

Parameters

  status | SIP status code or NUA status code (>= 900) describing the outbound state
  phrase | a short textual description of status code
  nh | operation handle associated with the outbound engine
  hmagic | application context associated with the handle
  sip | NULL or response message to an keepalive message or registration probe (error code and message are in status an phrase parameters)
  tags | empty

See also
  NUTAG_OUTBOUND(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(), nua_register(), nua_r_register, nua_unregister(), nua_r_unregister

nua_i_bye

Incoming BYE call hangup.

Incoming BYE request, call hangup.

Parameters

  status | statuscode of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | pointer to BYE request
  tags | empty

See also
  NUA Call Model, nua_i_state, nua_bye(), nua_bye(), nua_r_cancel

nua_i_options

Incoming OPTIONS.

Incoming OPTIONS request.

The user-agent should respond to an OPTIONS request with the same statuscode as it would respond to an INVITE request.

Stack responds automatically to OPTIONS request unless OPTIONS is included in the set of application methods, set by NUTAG_APPL_METHOD().

The OPTIONS request does not create a dialog. Currently the processing of incoming OPTIONS creates a new handle for each incoming request which is not assiciated with an existing dialog. If the handle nh is not bound, you should probably destroy it after responding to the OPTIONS request.

Parameters

  status | status code of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the OPTIONS request
  hmagic | application context associated with the call (NULL if outside session)
  sip | incoming OPTIONS request
  tags | empty

See also
  nua_respond(), nua_options(), nua_r_options, RFC 3261 section 11.2

nua_i_refer

Incoming REFER call transfer.

Incoming REFER request used to transfer calls.

The tag list will contain tag NUTAG_REFER_EVENT() with the Event header constructed from the REFER request. It will also contain the SIPTAG_REFERRED_BY() tag with the Referred-By header containing the identity of the party sending the REFER. The Referred-By structure contained in the tag is constructed from the From header if the Referred-By header was not present in the REFER request.

The application can let the nua to send NOTIFYs from the call it initiates with nua_invite() if it includes in the nua_invite() arguments both the NUTAG_NOTIFY_REFER() with the handle with which nua_i_refer was received and the NUTAG_REFER_EVENT() from nua_i_refer event tags.

Parameters

  status | status code of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the incoming request
  hmagic | application context associated with the handle (NULL if outside of an already established session)
  sip | incoming REFER request
  tags | NUTAG_REFER_EVENT() SIPTAG_REFERRED_BY()

See also
  nua_refer(), nua_r_refer, Refer-To, NUTAG_REFER_EVENT(), SIPTAG_REFERRED_BY(), Referred-By, NUTAG_NOTIFY_REFER(), NUTAG_REFER_WITH_ID(), RFC 3515.

nua_i_publish

Incoming PUBLISH.

Incoming PUBLISH request.

In order to receive nua_i_publish events, the application must enable both the PUBLISH method with NUTAG_ALLOW() tag and the acceptable SIP events with nua_set_params() tag NUTAG_ALLOW_EVENTS().

The nua_response() call responding to a PUBLISH request must have NUTAG_WITH() (or NUTAG_WITH_THIS()/NUTAG_WITH_SAVED()) tag. Note that a successful response to PUBLISH MUST include Expires and SIP-ETag headers.

The PUBLISH request does not create a dialog. Currently the processing of incoming PUBLISH creates a new handle for each incoming request which is not assiciated with an existing dialog. If the handle nh is not bound, you should probably destroy it after responding to the PUBLISH request.

Parameters

  status | status code of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the incoming request
  hmagic | application context associated with the call (usually NULL)
  sip | incoming PUBLISH request
  tags | empty

See also
  RFC 3903, nua_respond(), Expires, SIP-ETag, SIP-If-Match, Event, nua_subscribe(), nua_i_subscribe, nua_notifier(), nua_i_subscription,

Since
  First used in 1.12.4

nua_i_prack

Incoming PRACK.

Incoming PRACK request.

PRACK request is used to acknowledge reliable preliminary responses and it is usually sent automatically by the nua stack.

Parameters

  status | status code of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | incoming PRACK request
  tags | empty

See also
  nua_prack(), nua_r_prack, RFC 3262, NUTAG_EARLY_MEDIA()

nua_i_info

Incoming session INFO.

Incoming session INFO request.

Parameters

  status | statuscode of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | incoming INFO request
  tags | empty

See also
  nua_info(), nua_r_info, RFC 2976

nua_i_update

Incoming session UPDATE.

Incoming session UPDATE request.

Parameters

  status | statuscode of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | incoming UPDATE request
  tags | empty

See also
  nua_update(), nua_r_update, nua_i_state

nua_i_message

Incoming MESSAGE.

Incoming MESSAGE request.

The MESSAGE request does not create a dialog. If the incoming MESSAGE request is not assiciated with an existing dialog the stack creates a new handle for it. If the handle nh is not bound, you should probably destroy it after responding to the MESSAGE request.

Parameters

  status | status code of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the message
  hmagic | application context associated with the handle (maybe NULL if outside session)
  sip | incoming MESSAGE request
  tags | empty

See also
  nua_message(), nua_r_message, RFC 3428, RFC 3862

nua_i_chat

Incoming chat MESSAGE.

Incoming chat message.

Parameters

  nh | operation handle associated with the message
  hmagic | operation magic associated with the handle
  sip | incoming chat message
  tags | empty

nua_i_subscribe

Incoming SUBSCRIBE.

Incoming SUBSCRIBE request.

SUBSCRIBE request is used to query SIP event state or establish a SIP event subscription.

Parameters

  status | status code of response sent automatically by stack
  phrase | response phrase sent automatically by stack
  nh | operation handle associated with the incoming request
  hmagic | application context associated with the handle (NULL when handle is created by the stack)
  sip | SUBSCRIBE request headers
  tags | NUTAG_SUBSTATE()

Initial SUBSCRIBE requests are dropped with 489 Bad Event response, unless the application has explicitly included the Event in the list of allowed events with nua_set_params() tag NUTAG_ALLOW_EVENTS() (or SIPTAG_ALLOW_EVENTS() or SIPTAG_ALLOW_EVENTS_STR()).

If the event has been allowed the application can decide whether to accept the SUBSCRIBE request or reject it. The nua_response() call responding to a SUBSCRIBE request must have NUTAG_WITH() (or NUTAG_WITH_THIS()/NUTAG_WITH_SAVED()) tag.

If the application accepts the SUBSCRIBE request, it must immediately send an initial NOTIFY establishing the dialog. This is because the response to the SUBSCRIBE request may be lost by an intermediate proxy because it had forked the SUBSCRIBE request.

SUBSCRIBE requests modifying (usually refreshing or terminating) an existing event subscription are accepted by default and a 200 OK response along with a copy of previously sent NOTIFY is sent automatically to the subscriber.

By default, only event subscriptions accepted are those created implicitly by REFER request. See nua_i_refer how the application must handle the REFER requests.

Subscription Lifetime and Terminating Subscriptions

Accepting the SUBSCRIBE request creates a dialog with a notifier dialog usage on the handle. The dialog usage is active, until the subscriber terminates the subscription, it times out or the application terminates the usage with nua_notify() call containing the tag NUTAG_SUBSTATE(nua_substate_terminated) or Subscription-State header with state "terminated" and/or expiration time 0.

When the subscriber terminates the subscription, the application is notified of an termination by a nua_i_subscribe event with NUTAG_SUBSTATE(nua_substate_terminated) tag. When the subscription times out, nua automatically initiates a NOTIFY transaction. When it is terminated, the application is sent a nua_r_notify event with NUTAG_SUBSTATE(nua_substate_terminated) tag.

See also
  RFC 3265, nua_notify(), NUTAG_SUBSTATE(), Subscription-State, Event, nua_subscribe(), nua_r_subscribe, nua_i_refer, nua_refer()

nua_i_subscription

Incoming subscription to be authorized.

This event is launched by nua_notifier() to inform application of the current state of the subscriber. The subscriber state is included in the NUTAG_SUBSTATE() tag. If the state is nua_substate_pending or nua_substate_embryonic, application should to authorize the subscriber with nua_authorize().

Parameters

  nh | operation handle associated with the notifier
  hmagic | operation magic
  status | statuscode of response sent automatically by stack
  sip | incoming SUBSCRIBE request
  tags | NEATAG_SUB(), NUTAG_SUBSTATE()

See also
  nua_notifier(), nua_i_subscribe, nua_authorize(), nua_terminate() RFC 3265

nua_i_notify

Incoming event NOTIFY.

Event for incoming NOTIFY request.

Parameters

  status | statuscode of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the subscription
  hmagic | application context associated with the handle
  sip | incoming NOTIFY request
  tags | NUTAG_SUBSTATE() indicating the subscription state

See also
  nua_subscribe(), nua_unsubscribe(), RFC 3265, nua_i_subscribe

nua_i_method

Incoming, unknown method.

Incoming extension request.

The extension request does not create a dialog. If the incoming request was not assiciated with an existing dialog the stack creates a new handle for it. If the handle nh is not bound, you should probably destroy it after responding to the request.

Parameters

  status | status code of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the method
  hmagic | application context associated with the handle (maybe NULL if outside session)
  sip | headers in incoming request (see also nua_current_request())
  tags | NUTAG_METHOD()

The extension method name is in sip->sip_request->rq_method_name, too.

Note
  If the status is < 200, it is up to application to respond to the request with nua_respond(). If the handle is destroyed, the stack returns a 500 Internal Server Error response to any unresponded request.

See also
  nua_method(), nua_r_method, NUTAG_ALLOW(), NUTAG_APPL_METHOD(), nua_respond(), NUTAG_WITH(), NUTAG_WITH_THIS(), NUTAG_

nua_i_media_error

Offer-answer error indication.

Media error indication.

This may be sent after an SOA operation has failed while processing incoming or outgoing call.

Parameters

  status | SIP status code or NUA status code (>= 900) describing the problem
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | operation magic associated with this handle (maybe NULL if call handle was created for this call)
  sip | NULL
  tags | empty

nua_r_set_params

Answer to nua_set_params() or nua_get_hparams().

Response to nua_set_params() or nua_set_hparams().

Parameters

  status | 200 when successful, error code otherwise
  phrase | a short textual description of status code
  nh | NULL when responding to nua_set_params(), operation handle when responding to nua_set_hparams()
  hmagic | NULL when responding to nua_set_params(), application contact associated with the operation handle when responding to nua_set_hparams()
  sip | NULL
  tags | None

See also
  nua_set_params(), nua_set_hparams(), nua_r_get_params, nua_get_params(), nua_get_hparams()

nua_r_get_params

Answer to nua_get_params() or nua_get_hparams().

Parameters

  status | 200 when succesful, error code otherwise
  phrase | a short textual description of status code
  nh | NULL when responding to nua_get_params(), operation handle when responding to nua_get_hparams()
  hmagic | NULL when responding to nua_get_params(), application contact associated with the operation handle when responding to nua_get_hparams()
  sip | NULL

  tags

  NUTAG_ACCEPT_MULTIPART()
  NUTAG_APPL_EVENT()
  NUTAG_APPL_METHOD()
  NUTAG_AUTH_CACHE()
  NUTAG_AUTOACK()
  NUTAG_AUTOALERT()
  NUTAG_AUTOANSWER()
  NUTAG_CALLEE_CAPS()
  NUTAG_DETECT_NETWORK_UPDATES()
  NUTAG_EARLY_ANSWER()
  NUTAG_EARLY_MEDIA()
  NUTAG_ENABLEINVITE()
  NUTAG_ENABLEMESSAGE()
  NUTAG_ENABLEMESSENGER()
  NUTAG_INITIAL_ROUTE()
  NUTAG_INITIAL_ROUTE_STR()
  NUTAG_INSTANCE()
  NUTAG_INVITE_TIMER()
  NUTAG_KEEPALIVE()
  NUTAG_KEEPALIVE_STREAM()
  NUTAG_MAX_SUBSCRIPTIONS()
  NUTAG_MEDIA_ENABLE()
  NUTAG_MEDIA_FEATURES()
  NUTAG_MIN_SE()
  NUTAG_M_DISPLAY()
  NUTAG_M_FEATURES()
  NUTAG_M_PARAMS()
  NUTAG_M_USERNAME()
  NUTAG_ONLY183_100REL()
  NUTAG_OUTBOUND()
  NUTAG_PATH_ENABLE()
  NUTAG_REFER_EXPIRES()
  NUTAG_REFER_WITH_ID()
  NUTAG_REFRESH_WITHOUT_SDP()
  NUTAG_REGISTRAR()
  NUTAG_RETRY_COUNT()
  NUTAG_SERVICE_ROUTE_ENABLE()
  NUTAG_SESSION_REFRESHER()
  NUTAG_SESSION_TIMER()
  NUTAG_SMIME_ENABLE()
  NUTAG_SMIME_KEY_ENCRYPTION()
  NUTAG_SMIME_MESSAGE_DIGEST()
  NUTAG_SMIME_MESSAGE_ENCRYPTION()
  NUTAG_SMIME_OPT()
  NUTAG_SMIME_PROTECTION_MODE()
  NUTAG_SMIME_SIGNATURE()
  NUTAG_SOA_NAME()
  NUTAG_SUBSTATE()
  NUTAG_SUB_EXPIRES()
  NUTAG_UPDATE_REFRESH()
  NUTAG_USER_AGENT()
  SIPTAG_ALLOW()
  SIPTAG_ALLOW_STR()
  SIPTAG_ALLOW_EVENTS()
  SIPTAG_ALLOW_EVENTS_STR()
  SIPTAG_FROM()
  SIPTAG_FROM_STR()
  SIPTAG_ORGANIZATION()
  SIPTAG_ORGANIZATION_STR()
  SIPTAG_SUPPORTED()
  SIPTAG_SUPPORTED_STR()
  SIPTAG_USER_AGENT()
  SIPTAG_USER_AGENT_STR()

See also
  nua_get_params(), nua_get_hparams(), nua_set_params(), nua_set_hparams(), nua_r_set_params

nua_r_shutdown

Answer to nua_shutdown().

Shutdown a nua stack.

When the nua stack is shutdown, ongoing calls are released, registrations unregistered, publications un-PUBLISHed and subscriptions terminated. If the stack cannot terminate everything within 30 seconds, it sends the nua_r_shutdown event with status 500.

Parameters

  nua | Pointer to nua stack object

Returns
  nothing

Related tags:
  none

Events:
  nua_r_shutdown

See also
  nua_r_shutdown, nua_destroy(), nua_create(), nua_bye(), nua_unregister(), nua_unpublish(), nua_unsubscribe(), nua_notify(), nua_handle_destroy(), nua_handle_unref()

Answer to nua_shutdown().

Status codes

- 100 shutdown started
- 101 shutdown in progress (sent when shutdown has been progressed)
- 200 shutdown was successful
- 500 shutdown timeout after 30 sec

Parameters

  status | shutdown status code
  nh | NULL
  hmagic | NULL
  sip | NULL
  tags | empty

See also
  nua_shutdown(), nua_destroy()

nua_r_notifier

Answer to nua_notifier().

Answer to nua_notitier().

Parameters

  nh | operation handle associated with the call
  hmagic | operation magic associated with the call
  sip | NULL
  tags | SIPTAG_EVENT() SIPTAG_CONTENT_TYPE()

See also
  nua_notitier(), nua_i_subscription, RFC 3265

nua_r_terminate

Answer to nua_terminate().

Parameters

  nh | operation handle associated with the notifier
  hmagic | operation magic associated with the notifier
  sip | NULL
  tags | empty

See also
  nua_terminate(), nua_handle_destroy()

nua_r_authorize | Answer to nua_authorize().

nua_r_register

Answer to outgoing REGISTER.

Response to an outgoing REGISTER.

The REGISTER may be sent explicitly by nua_register() or implicitly by NUA state machines.

When REGISTER request has been restarted the status may be 100 even while the real response status returned is different.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the registration
  hmagic | application context associated with the registration
  sip | response message to REGISTER request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_register(), nua_unregister(), nua_r_unregister, Contact, Call-ID, CSeq, RFC 3261 section 10, Path, RFC 3327, Service-Route, RFC 3608, RFC 3680

nua_r_unregister

Answer to outgoing un-REGISTER.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the registration
  hmagic | application context associated with the registration
  sip | response message to REGISTER request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_unregister(), nua_register(), nua_r_register, Contact, Call-ID, CSeq, RFC 3261 section 10, Path, RFC 3327, Service-Route, RFC 3608, RFC 3680

nua_r_invite | Answer to outgoing INVITE.

nua_r_cancel

Answer to outgoing CANCEL.

The CANCEL may be sent explicitly by nua_cancel() or implicitly by NUA state machine.

Parameters

  status | response status code
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | response to CANCEL request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_cancel(), Detailed Client Call Model, nua_r_invite, nua_invite(), nua_i_state

nua_r_bye

Answer to outgoing BYE.

The BYE may be sent explicitly by nua_bye() or implicitly by NUA state machine.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | response to BYE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_bye(), NUA Call Model, nua_i_state, nua_r_invite()

nua_r_options

Answer to outgoing OPTIONS.

Parameters

  status | response status code (if the request is retried the status is 100 and the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the incoming OPTIONS request
  hmagic | application context associated with the handle
  sip | response to OPTIONS request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_options(), RFC 3261 section 11, nua_i_options

nua_r_refer

Answer to outgoing REFER.

Response to outgoing REFER.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the REFER request
  hmagic | application context associated with the handle
  sip | response to REFER request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | NUTAG_REFER_EVENT() NUTAG_SUBSTATE()

See also
  nua_refer(), NUTAG_SUBSTATE(), nua_i_refer, RFC 3515, RFC 4488, Refer-Sub

nua_r_publish

Answer to outgoing PUBLISH.

Response to an outgoing PUBLISH.

The PUBLISH request may be sent explicitly by nua_publish() or implicitly by NUA state machine.

Parameters

  status | status code of PUBLISH request (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the publication
  hmagic | application context associated with the handle
  sip | response to PUBLISH request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_publish(), RFC 3903, SIP-ETag, Expires, nua_unpublish(), nua_r_unpublish, nua_i_publish

nua_r_unpublish

Answer to outgoing un-PUBLISH.

Response to an outgoing un-PUBLISH.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the publication
  hmagic | application context associated with the handle
  sip | response to PUBLISH request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_unpublish(), RFC 3903, SIP-ETag, Expires, nua_publish(), nua_r_publish, nua_i_publish

nua_r_info

Answer to outgoing INFO.

Response to an outgoing INFO request.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | response to INFO or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_info(), nua_i_info, RFC 2976

nua_r_prack

Answer to outgoing PRACK.

Response to an outgoing PRACK request.

PRACK request is used to acknowledge reliable preliminary responses and it is usually sent automatically by the nua stack.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | response to PRACK or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_prack(), nua_i_prack, RFC 3262

nua_r_update

Answer to outgoing UPDATE.

The UPDATE may be sent explicitly by nua_update() or implicitly by NUA state machine.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the call
  hmagic | application context associated with the call
  sip | response to UPDATE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  NUA Call Model, RFC 3311, nua_update(), nua_i_update

nua_r_message

Answer to outgoing MESSAGE.

Response to an outgoing MESSAGE request.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the message
  hmagic | application context associated with the handle
  sip | response to MESSAGE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | empty

See also
  nua_message(), nua_i_message, RFC 3428

nua_r_chat

Answer to outgoing chat message.

Parameters

  nh | operation handle associated with the notifier
  hmagic | operation magic associated with the notifier
  sip | response to MESSAGE request or NULL upon an error (error code and message are in status and phrase parameters)
  tags | empty

See also
  nua_chat(), nua_r_message

nua_r_subscribe

Answer to outgoing SUBSCRIBE.

Response to an outgoing SUBSCRIBE request.

The SUBSCRIBE request may have been sent explicitly by nua_subscribe() or implicitly by NUA state machine.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the subscription
  hmagic | application context associated with the handle
  sip | response to SUBSCRIBE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | NUTAG_SUBSTATE()

See also
  nua_subscribe(), RFC 3265

nua_r_unsubscribe

Answer to outgoing un-SUBSCRIBE.

Response to an outgoing un-SUBSCRIBE.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the subscription
  hmagic | application context associated with the handle
  sip | response to SUBSCRIBE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | NUTAG_SUBSTATE()

See also
  nua_unsubscribe(), RFC 3265

nua_r_notify

Answer to outgoing NOTIFY.

Response to an outgoing NOTIFY request.

The NOTIFY may be sent explicitly by nua_notify() or implicitly by NUA state machine. Implicit NOTIFY is sent when an established dialog is refreshed by client or it is terminated (either by client or because of a timeout).

The current subscription state is included in NUTAG_SUBSTATE() tag. The nua_substate_terminated indicates that the subscription is terminated, the notifier usage has been removed and when there was no other usages of the dialog the dialog state is also removed.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response message, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the subscription
  hmagic | application context associated with the handle
  sip | response to NOTIFY request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
  tags | NUTAG_SUBSTATE() indicating subscription state SIPTAG_EVENT() indicating subscription event

See also
  nua_notify(), RFC 3265, nua_i_subscribe, nua_i_refer, NUTAG_SUBSTATE()

nua_r_method

Answer to unknown outgoing method.

Response to an outgoing extension request.

Parameters

  status | response status code (if the request is retried, status is 100, the sip->sip_status->st_status contain the real status code from the response method, e.g., 302, 401, or 407)
  phrase | a short textual description of status code
  nh | operation handle associated with the method
  hmagic | application context associated with the handle
  sip | response to the extension request or NULL upon an error (status code is in status and descriptive method in phrase parameters)
  tags | empty

See also
  nua_method(), nua_i_method, RFC 3428

nua_r_authenticate

Answer to nua_authenticate().

Response to nua_authenticate().

Under normal operation, this event is never sent but rather the unauthenticated operation is completed. However, if there is no operation to authentication or if there is an authentication error the nua_r_authenticate event is sent to the application with the status code as follows:

- 202 No operation to restart:
  The authenticator associated with the handle was updated, but there was no operation to retry with the new credentials.
- 900 Cannot add credentials:
  There was internal problem updating authenticator.
- 904 No matching challenge:
  There was no challenge matching with the credentials provided by nua_authenticate(), e.g., their realm did not match with the one received with the challenge.

Parameters

  status | status code from authentication
  phrase | a short textual description of status code
  nh | operation handle authenticated
  hmagic | application context associated with the handle
  sip | NULL
  tags | empty

See also
  nua_terminate(), nua_handle_destroy()

nua_i_network_changed

Local IP(v6) address has changed.

Since
  New in 1.12.2

Parameters

  nh | default operation handle
  hmagic | operation magic associated with the default operation handle
  sip | NULL
  tags | empty

Since
  Experimental in 1.12.2.

nua_i_register

Incoming REGISTER.

Incoming REGISTER request.

Since
  New in 1.12.4.

In order to receive nua_i_register events, the application must enable the REGISTER method with NUTAG_ALLOW() tag, e.g.,

    * nua_set_params(nua;
    *    NUTAG_APPL_METHOD("REGISTER"),
    *    NUTAG_ALLOW("REGISTER"),
    *    TAG_END());
    *

The nua_response() call responding to a REGISTER request must include NUTAG_WITH() (or NUTAG_WITH_THIS()/NUTAG_WITH_SAVED()) tag. Note that a successful response to REGISTER MUST include the Contact header bound to the the AoR URI (in To header).

The REGISTER request does not create a dialog. Currently the processing of incoming REGISTER creates a new handle for each incoming request which is not assiciated with an existing dialog. If the handle nh is not bound, you should probably destroy it after responding to the REGISTER request.

Parameters

  status | status code of response sent automatically by stack
  phrase | a short textual description of status code
  nh | operation handle associated with the request
  hmagic | application context associated with the handle (usually NULL)
  sip | incoming REGISTER request
  tags | empty

See also
  nua_respond(), RFC 3261 section 10.3, Expires, Contact, Call-ID, CSeq, Path, RFC 3327, Service-Route, RFC 3608, RFC 3680, nua_register(), nua_i_register, nua_unregister(), #nua_i_unregister

Since
  New in 1.12.4

## nua_nw_detector_e

enum nua_nw_detector_e

Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES().

See also
  NUTAG_DETECT_NETWORK_UPDATES(), nua_i_network_changed

Since
  New in 1.12.2.

## Function Documentation

## nua_ack()

void nua_ack | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Acknowledge a succesfull response to INVITE request.

Acknowledge a succesful response to INVITE request.

Acknowledge a successful response (200..299) to INVITE request with the SIP ACK request message. This function is needed only if NUTAG_AUTOACK() parameter has been cleared.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  Header tags defined in <sofia-sip/sip_tag.h>

Events:
  nua_i_media_error
  nua_i_state (nua_i_active, nua_i_terminated)

See also
  NUTAG_AUTOACK(), NUA Call Model, nua_i_state

## nua_authenticate()

void nua_authenticate | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Authenticate an operation.

- 401 / 407 response with www-authenticate header/ proxy-authenticate header
- application should provide stack with username&password for each realm with NUTAG_AUTH() tag
- restarts operation

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NUTAG_AUTH()

Events:
  (any operation events)

## nua_authorize()

void nua_authorize | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Authorize a subscriber.

After creating a local presence server by nua_notifier(), an incoming SUBSCRIBE request causes nua_i_subscription event. Each subscriber is identified with NEATAG_SUB() tag in the nua_i_subscription event. Application can either authorize the subscriber with NUTAG_SUBSTATE(nua_substate_active) or terminate the subscription with NUTAG_SUBSTATE(nua_substate_terminated).

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NEATAG_SUB()
  NUTAG_SUBSTATE()

Events:
  nua_i_subscription

See also
  nua_notifier(), nua_terminate()

## nua_bye()

void nua_bye | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Hangdown a call.

Hangdown a call using SIP BYE method. Also the media session associated with the call is terminated.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  none

Events:
  nua_r_bye
  nua_i_media_error

## nua_callstate_name()

char const * nua_callstate_name | ( | enum nua_callstate | state | ) |

Get name for NUA callstate.

Get name for NUA callstate.

See also
  enum nua_callstate, nua_event_name(), nua_substate_name()

## nua_cancel()

void nua_cancel | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Cancel an INVITE operation.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  Header tags defined in <sofia-sip/sip_tag.h>

Events:
  nua_r_cancel, nua_i_state (nua_i_active, nua_i_terminated)

See also
  NUA Call Model, nua_invite(), nua_i_cancel

## nua_chat()

void nua_chat | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Send a chat message.

A chat channel can be established during call setup using "message" media. An active chat channel is indicated using nua_i_state event containing SOATAG_ACTIVE_CHAT() tag. Chat messages can be sent using this channel with nua_chat() function. Currently this is implemented using SIP MESSAGE requests but in future MSRP (message session protocol) will replace it.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  SIPTAG_CONTENT_TYPE()
  SIPTAG_PAYLOAD()
  SIPTAG_FROM()
  SIPTAG_TO()
  Use of other SIP tags is deprecated

Events:
  nua_r_chat

## nua_create()

nua_t * nua_create | ( | su_root_t * | root,
|  | nua_callback_f | callback,
|  | nua_magic_t * | magic,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Create a NUA agent.

Create a NUA agent.

This function creates a Sofia-SIP User Agent stack object (nua) and initializes its parameters by given tagged values.

Parameters

  root | Pointer to a root object
  callback | Pointer to event callback function
  magic | Pointer to callback context
  tag, value, ... | List of tagged parameters

Return values

  !=NULL | a pointer to a nua stack object
  NULL | upon an error

Related tags:
  - NUTAG_PROXY(), giving the URI of the outbound proxy (but see also NUTAG_INITIAL_ROUTE()).
  - NUTAG_URL() (and NUTAG_SIPS_URL(), listing URIs describing transports)
  - NUTAG_CERTIFICATE_DIR(), specifying the location of the root and client/server certificate files
  - NUTAG_SIP_PARSER(), providing customized parser used to parse received SIP messages
  - All parameter tags, listed with nua_set_params()
  - All NTATAG_* are passed to NTA documented in <sofia-sip/nta_tag.h>: see NTATAG_EXTRA_100(),
  - All tport tags are passed to tport. They are documented in <sofia-sip/tport_tag.h>
  - All SOATAG_* are passed to the default SOA (media session) object which is created by nua_create() unless NUTAG_MEDIA_ENABLE(0) is included in the tag list
  - STUN tags STUNTAG_DOMAIN(), STUNTAG_SERVER(). STUN is deprecated, however.

Note
  From the 1.12.2 all the nua_set_params() tags are processed. Previously all nutags except NUTAG_SOA_NAME() and NUTAG_MEDIA_ENABLE() were ignored.
  Both the NUTAG_URL() and NUTAG_SIPS_URL() are used to pass arguments to nta_agent_add_tport().

Events:
  none

See also
  nua_shutdown(), nua_destroy(), nua_handle(), nta_agent_create().

## nua_current_request()

msg_t * nua_current_request | ( | nua_t const * | nua | ) |

Get current request message.

Since
  New in 1.12.4.

Note
  A response message is returned when processing response message.

See also
  nua_event_e, nua_respond(), NUTAG_WITH_CURRENT()

## nua_default()

nua_handle_t * nua_default | ( | nua_t * | nua | ) |

Obtain default operation handle of the NUA stack object.

Obtain default operation handle of the NUA stack object.

A default operation can be used for operations where the ultimate result is not important or can be discarded.

Parameters

  nua | Pointer to nua stack object

Return values

  !=NULL | Pointer to nua operation handle
  NULL | No default operation exists

Related tags:
  none

Events:
  none

## nua_destroy()

void nua_destroy | ( | nua_t * | nua | ) |

Destroy the NUA stack.

Destroy the NUA stack.

Before calling nua_destroy() the application should call nua_shutdown and wait for successful nua_r_shutdown event. Shuts down and destroys the nua stack. Ongoing calls, registrations, and subscriptions are left as they are.

Parameters

  nua | Pointer to nua stack object

Returns
  nothing

Related tags:
  none

Events:
  none

See also
  nua_shutdown(), nua_create(), nua_handle_destroy(), nua_handle_unref()

## nua_event_data()

nua_event_data_t const * nua_event_data | ( | nua_saved_event_t const | saved[1] | ) |

Get information from saved event.

Get information from saved event.

See also
  nua_event_e, nua_event_save(), nua_saved_event_request(), nua_destroy_event().

## nua_event_is_incoming_request()

int nua_event_is_incoming_request | ( | nua_event_t | event | ) |

Check if event can be responded with nua_respond().

Check if event can be responded with nua_respond().

Note that if event status is 200 or greater, it already has been responded. This function is provided for compatibility with future versions of nua. An unknown event can always be handled in the event callback like this:

switch (event) {
...
default:
if (status < 200 && nua_event_is_incoming_request(event))
nua_respond(nh, SIP_501_NOT_IMPLEMENTED,
NUTAG_WITH_THIS(nua), TAG_END());
if (hmagic == NULL)
nua_handle_destroy(nh);
return;
...
SIP_501_NOT_IMPLEMENTED
#define SIP_501_NOT_IMPLEMENTED
nua_respond
void nua_respond(nua_handle_t *nh, int status, char const *phrase, tag_type_t, tag_value_t,...)
Respond to a request with given status code and phrase.
Definition nua.c:874
nua_event_is_incoming_request
int nua_event_is_incoming_request(nua_event_t e)
Check if event can be responded with nua_respond().
Definition nua_common.c:284
nua_handle_destroy
void nua_handle_destroy(nua_handle_t *h)
Destroy a handle.
Definition nua.c:919
NUTAG_WITH_THIS
#define NUTAG_WITH_THIS(nua)
Specify request to respond to.
Definition nua_tag.h:88
TAG_END
#define TAG_END()

See also
  nua_respond(), nua_event_e, nua_event_t, nua_event_name()

Since
  New in 1.12.6.

## nua_event_name()

char const * nua_event_name | ( | nua_event_t | event | ) |

Get name for NUA event.

Get name for NUA event.

See also
  nua_event_e, nua_event_t, nua_callstate_name(), nua_substate_name()

## nua_get_hparams()

void nua_get_hparams | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Get handle parameters.

Get values of handle-specific parameters in nua_r_get_params event.

Application will specify either expilicit list of tags it is interested in, or a filter (at the moment, TAG_ANY()). The values are returned as a list of tags in the nua_r_get_params event.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

The handle-specific parameters will contain only the parameters actually modified by application, either by nua_set_hparams() or some other handle-specific call. Currently, no NTA parameters are returned. They are returned only when application asks for user-agent-level parameters using either nua_get_params() or using default handle, eg.

nua_get_hparams(nua_default(nua), TAG_ANY())
nua_get_hparams
void nua_get_hparams(nua_handle_t *, tag_type_t, tag_value_t,...)
Get handle parameters.
Definition nua.c:614
nua_default
nua_handle_t * nua_default(nua_t *nua)
Obtain default operation handle of the NUA stack object.
Definition nua.c:271
TAG_ANY
#define TAG_ANY()

Returns
  nothing

Related tags:
  TAG_ANY
  othervise same tags as nua_set_hparams()

Events:
  nua_r_get_params

## nua_get_params()

void nua_get_params | ( | nua_t * | nua,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Get NUA parameters.

Get NUA parameters matching with the given filter.

The values of NUA parameters is returned in nua_r_get_params event.

Parameters

  nua | Pointer to NUA stack object
  tag,value,... | List of tagged parameters

Returns
  nothing

Related tags:
  TAG_ANY()
  otherwise same tags as nua_set_params()

Events:
  nua_r_get_params

Examples
  Find out default values of all parameters:
  nua_get_params(nua, TAG_ANY(), TAG_END());
  nua_get_params
  void nua_get_params(nua_t *nua, tag_type_t, tag_value_t,...)
  Get NUA parameters.
  Definition nua.c:583

## nua_handle()

nua_handle_t * nua_handle | ( | nua_t * | nua,
|  | nua_hmagic_t * | hmagic,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Create an operation handle.

Allocates a new operation handle and associated storage.

Parameters

  nua | Pointer to nua stack object
  hmagic | Pointer to callback context
  tag,value,... | List of tagged parameters

Return values

  !=NULL | Pointer to operation handle
  NULL | Creation failed

Related tags:
  Duplicates the provided tags for use with every operation. Note that NUTAG_URL() is converted to SIPTAG_TO() if there is no SIPTAG_TO(). And also vice versa, request-URI is taken from SIPTAG_TO() if there is no NUTAG_URL(). Note that certain SIP headers cannot be saved with the handle. They include Content-Length, CSeq, RSeq, RAck, and Timestamp.

  nua_handle() accepts all the tags accepted by nua_set_hparams(), too.

Events:
  none

See also
  nua_handle_bind(), nua_handle_destroy(), nua_handle_ref(), nua_handle_unref().

## nua_handle_bind()

void nua_handle_bind | ( | nua_handle_t * | nh,
|  | nua_hmagic_t * | hmagic )

Bind a callback context to an operation handle.

Parameters

  nh | Pointer to operation handle
  hmagic | Pointer to callback context

Returns
  nothing

Related tags:
  none

Events:
  none

## nua_handle_by_call_id()

nua_handle_t * nua_handle_by_call_id | ( | nua_t * | nua,
|  | const char * | call_id )

Obtain a new reference to an existing handle based on Call-ID.

Since
  New in 1.12.9.

Note
  You should release the reference with nua_handle_unref() when you are done with the handle.

See also
  nua_handle_make_replaces(), Replaces, RFC 3891, nua_refer(), nua_i_refer, Refer-To, nta_leg_by_replaces()

## nua_handle_by_replaces()

nua_handle_t * nua_handle_by_replaces | ( | nua_t * | nua,
|  | sip_replaces_t const * | r )

Obtain a new reference to an existing handle based on Replaces header.

Since
  New in 1.12.4.

Note
  You should release the reference with nua_handle_unref() when you are done with the handle.

See also
  nua_handle_make_replaces(), Replaces, RFC 3891, nua_refer(), nua_i_refer, Refer-To, nta_leg_by_replaces()

## nua_handle_destroy()

void nua_handle_destroy | ( | nua_handle_t * | nh | ) |

Destroy a handle.

Terminate the protocol state associated with an operation handle. The stack discards resources and terminates the ongoing dialog usage, sessions and transactions associated with this handle. For example, calls are terminated with BYE request. Also, the reference count for the handle is also decremented.

The handles use reference counting for memory management. In order to make it more convenient for programmer, nua_handle_destroy() decreases the reference count, too.

Parameters

  nh | Pointer to operation handle

Returns
  nothing

Related Tags:
  none

Events:
  none

See also
  nua_handle(), nua_handle_bind(), nua_handle_ref(), nua_handle_unref(), nua_unregister(), nua_unpublish(), nua_unsubscribe(), nua_bye().

## nua_handle_has_active_call()

int nua_handle_has_active_call | ( | nua_handle_t const * | nh | ) |

Check if operation handle has an active call.

Parameters

  nh | Pointer to operation handle

Return values

  0 | no active call in operation or operation handle is invalid
  1 | operation has established call or pending call request.

Related tags:
  none

Events:
  none

## nua_handle_has_call_on_hold()

int nua_handle_has_call_on_hold | ( | nua_handle_t const * | nh | ) |

Check if operation handle has a call on hold.

Please note that this status is not affected by remote end putting this end on hold. Remote end can put each media separately on hold and status is reflected on SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO() and SOATAG_ACTIVE_CHAT() tag values in nua_i_state event.

Parameters

  nh | Pointer to operation handle

Return values

  0 | if no call on hold in operation or operation handle is invalid
  1 | if operation has call on hold, for example nua_invite() or nua_update() has been called with SOATAG_HOLD() with non-NULL argument.

Related tags:
  none

Events:
  none

## nua_handle_has_events()

int nua_handle_has_events | ( | nua_handle_t const * | nh | ) |

Check if handle has active event subscriptions (refers sent).

Check if handle has active event subscriptions (refers sent).

Active subscription can be established either by nua_subscribe() or nua_refer() calls.

Parameters

  nh | Pointer to operation handle

Return values

  0 | no event subscriptions in operation or operation handle is invalid
  !=0 | operation has event subscriptions

Related tags:
  none

Events:
  none

## nua_handle_has_invite()

int nua_handle_has_invite | ( | nua_handle_t const * | nh | ) |

Check if operation handle is used for INVITE.

Check if operation handle has been used with either outgoing or incoming INVITE request.

Parameters

  nh | Pointer to operation handle

Return values

  0 | no invite in operation or operation handle is invalid
  1 | operation has invite

Related tags:
  none

Events:
  none

## nua_handle_has_register()

int nua_handle_has_register | ( | nua_handle_t const * | nh | ) |

Check if operation handle has been used with nua_register() or nua_unregister().

Parameters

  nh | Pointer to operation handle

Return values

  0 | no active register in operation or operation handle is invalid
  1 | operation has been used with nua_register() or nua-unregister()

Related tags:
  none

Events:
  none

## nua_handle_has_registrations()

int nua_handle_has_registrations | ( | nua_handle_t const * | nh | ) |

Check if operation handle has active registrations.

A registration is active when either when a REGISTER operation is going on or when it has successfully completed so that nua stack is expected to refresh the registration in the future. Normally, a handle has active registration after nua_register() until nua_unregister() completes, unless the initial nua_register() had either expiration time of 0 or it had SIPTAG_CONTACT(NULL) as an argument.

Parameters

  nh | Pointer to operation handle

Return values

  0 | no active registration in operation or operation handle is invalid
  1 | operation has registration

Related tags:
  none

Events:
  none

See also
  nua_register(), nua_unregister(), nua_r_register, nua_r_unregister

## nua_handle_has_subscribe()

int nua_handle_has_subscribe | ( | nua_handle_t const * | nh | ) |

Check if operation handle has been used with outgoing SUBSCRIBE of REFER request.

Parameters

  nh | Pointer to operation handle

Return values

  0 | no active subscription in operation or operation handle is invalid
  1 | operation has subscription.

Related tags:
  none

Events:
  none

## nua_handle_local()

sip_to_t const * nua_handle_local | ( | nua_handle_t const * | nh | ) |

Get the local address (From/To header) of operation handle.

Local address is used as From header in outgoing operations and derived from To: header in incoming operations.

Parameters

  nh | Pointer to operation handle

Return values

  NULL | no local address for operation or operation handle invalid
  !=NULL | pointer to local address for operation

Related tags:
  none

Events:
  none

## nua_handle_magic()

nua_hmagic_t * nua_handle_magic | ( | nua_handle_t * | nh | ) |

Fetch a callback context from an operation handle.

Parameters

  nh | Pointer to operation handle

Returns
  Pointer to callback context

Related tags:
  none

Events:
  none

Since
  New in 1.12.4.

## nua_handle_make_replaces()

sip_replaces_t * nua_handle_make_replaces | ( | nua_handle_t * | nh,
|  | su_home_t * | home,
|  | int | early_only )

Generate a Replaces header for handle.

A Replaces header contains the Call-ID value, From and To tags corresponding to SIP dialog associated with handle nh. Note that the Replaces matches with dialog of the remote peer, nua_handle_by_replaces() does not return same handle (unless you swap rp_from_tag and rp_to_tag in Replaces header).

A Replaces header is used in attended transfer, among other things.

Parameters

  nh | pointer to operation handle
  home | memory home used to allocate the header
  early_only | if true, include "early-only" parameter in Replaces, too

Returns
  A newly created Replaces header.

Since
  New in 1.12.4.

See also
  nua_handle_by_replaces(), Replaces, RFC 3891, RFC 3515, nua_refer(), nua_i_refer(), Refer-To, nta_leg_make_replaces(), sip_headers_as_url_query()

## nua_handle_ref()

nua_handle_t * nua_handle_ref | ( | nua_handle_t * | nh | ) |

Make a new reference to handle.

The handles use reference counting for memory management. In addition to the memory management, there is protocol state associated with the handles. The protocol state is terminated with nua_handle_destroy(). In order to make it more convenient for programmer, nua_handle_destroy() decreases the reference count, too.

Note
  All handle references are destroyed when the nua object is destroyed.

See also
  nua_handle_unref(), nua_handle(), nua_handle_destroy().

## nua_handle_remote()

sip_to_t const * nua_handle_remote | ( | nua_handle_t const * | nh | ) |

Get the remote address (From/To header) of operation handle.

Remote address is used as To header in outgoing operations and derived from From: header in incoming operations.

Parameters

  nh | Pointer to operation handle

Return values

  NULL | no remote address for operation or operation handle invalid
  !=NULL | pointer to remote address for operation

Related tags:
  none

Events:
  none

## nua_handle_unref()

int nua_handle_unref | ( | nua_handle_t * | nh | ) |

Destroy reference to handle.

The handles use reference counting for memory management. In addition to the memory management, there is protocol state associated with the handles. The protocol state is terminated with nua_handle_destroy(). In order to make it more convenient for programmer, nua_handle_destroy() decreases the reference count, too.

See also
  nua_handle_ref(), nua_handle(), nua_handle_destroy().

## nua_info()

void nua_info | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Send an INFO request.

INFO is used to send call related information like DTMF digit input events. See RFC 2976.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  Header tags defined in <sofia-sip/sip_tag.h>.

Events:
  nua_r_info

See also
  nua_i_info

## nua_invite()

void nua_invite | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Place a call using SIP INVITE method.

Place a call using SIP INVITE method.

The INVITE method is used to initiate a call between two parties. The call is also known as SIP session.

At SIP level the session is represented as Dialog, which is a peer-to-peer association between two SIP User-Agents. The dialog is established by a successful 2XX response to the INVITE. The dialog is terminated by BYE transaction, which application can initiate with nua_bye() call.

An early dialog is established by an preliminary response (101..199), such as 180 Ringing. An early dialog is terminated with an error response with response code in range 300...699.

The media session belonging to the SIP session is usually represented by SDP, Session Description Protocol. The media session it is usually established during the call set-up with procedure known as SDP Offer/Answer exchange, defined by RFC 3264. See Media Session Handling below for details.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Events:
  nua_r_invite
  nua_i_state (nua_i_active, nua_i_terminated)
  nua_i_media_error
  nua_i_fork

Tags:
  NUTAG_AUTH_CACHE()
  NUTAG_AUTOACK()
  NUTAG_AUTOANSWER()
  NUTAG_EARLY_MEDIA()
  NUTAG_ENABLEINVITE()
  NUTAG_INITIAL_ROUTE(), NUTAG_INITIAL_ROUTE_STR()
  NUTAG_INVITE_TIMER()
  NUTAG_MEDIA_ENABLE()
  NUTAG_MEDIA_FEATURES()
  NUTAG_MIN_SE()
  NUTAG_RETRY_COUNT()
  NUTAG_SERVICE_ROUTE_ENABLE()
  NUTAG_SESSION_REFRESHER()
  NUTAG_SESSION_TIMER()
  NUTAG_SOA_NAME()
  NUTAG_UPDATE_REFRESH()

Populating SIP Request Message with Tagged Arguments
  The tagged arguments can be used to pass values for any SIP headers to the stack. When the INVITE message (or any other SIP message) is created, the tagged values saved with nua_handle() are used first, next the tagged values given with the operation (nua_invite()) are added.

  When multiple tags for the same header are specified, the behaviour depends on the header type. If only a single header field can be included in a SIP message, the latest non-NULL value is used, e.g., Subject. However, if the SIP header can consist of multiple lines or header fields separated by comma, e.g., Accept, all the tagged values are concatenated.

  However, if a tag value is SIP_NONE (-1 casted as a void pointer), the values from previous tags are ignored.

  Next, values previously set with nua_set_params() or nua_set_hparams() are used: Allow, Supported, Organization, and User-Agent headers are added to the request if they are not already set.

  Now, the target URI for the request needs to be determined.

  For initial INVITE requests, values from tags are used. If NUTAG_URL() is given, it is used as target URI. Otherwise, if SIPTAG_TO() is given, it is used as target URI. If neither is given, the complete request line already specified using SIPTAG_REQUEST() or SIPTAG_REQUEST_STR() is used. If none of the tags above are given, an internal error is returned to the application. At this point, the target URI is stored in the request line, together with method name ("INVITE") and protocol version ("SIP/2.0"). The initial dialog information is also created: Call-ID, CSeq headers are generated, if they do not exist, and an unique tag is added to From header.

  For the initial INVITE requests, the Route headers specified by SIPTAG_ROUTE()/SIPTAG_ROUTER_STR() tags in nua_handle() and nua_invite() calls are inserted to the request. Next the initial route set specified by NUTAG_INITIAL_ROUTE()/NUTAG_INITIAL_ROUTE_STR() tags is prepended to the route. Finally (unless NUTAG_SERVICE_ROUTE_ENABLE(0) is used) the Service-Route set received from the registrar is also appended to the route set of the initial request message.

  Next, the stack generates a Contact header for the request (Unless the application already gave a Contact header or it does not want to use Contact and indicates that by including SIPTAG_CONTACT(NULL) or SIPTAG_CONTACT(SIP_NONE) in the tagged parameters.) If the application has a registration active, the Contact header used with registration is used. Otherwise, the Contact header is generated from the local IP address and port number, taking also the values from NUTAG_M_DISPLAY(), NUTAG_M_FEATURES(), NUTAG_M_PARAMS(), and NUTAG_M_USERNAME().

  For in-dialog INVITE (re-INVITE), the request URI is taken from the Contact header received from the remote party during the dialog establishment. Also, the Call-ID and CSeq headers and From and To tags are generated based on the dialog information and added to the request. If the dialog has a route (set by Record-Route headers), it is added to the request, too.

  Max-Forwards header (with default value set by NTATAG_MAX_FORWARDS()) is also added now, if it does not exist.

  The INVITE request message created by nua_invite() operation is saved as a template for automatic re-INVITE requests sent by the session timer ("timer") feature (see NUTAG_SESSION_TIMER() for more details). Please note that the template message is not used when ACK, PRACK, UPDATE or INFO requests are created (however, these requests will include dialog-specific headers like To, From, and Call-ID as well as preference headers Allow, Supported, User-Agent, Organization).

Tags Related to SIP Headers and Request-URI
  NUTAG_URL(), SIPTAG_REQUEST(), SIPTAG_REQUEST_STR()
  NUTAG_INITIAL_ROUTE(), NUTAG_INITIAL_ROUTE_STR(), SIPTAG_ROUTE(), SIPTAG_ROUTE_STR(), NUTAG_SERVICE_ROUTE_ENABLE()
  SIPTAG_MAX_FORWARDS(), SIPTAG_MAX_FORWARDS_STR()
  SIPTAG_PROXY_REQUIRE(), SIPTAG_PROXY_REQUIRE_STR()
  SIPTAG_FROM(), SIPTAG_FROM_STR()
  SIPTAG_TO(), SIPTAG_TO_STR()
  SIPTAG_CALL_ID(), SIPTAG_CALL_ID_STR()
  SIPTAG_CSEQ(), SIPTAG_CSEQ_STR() (note that CSeq value is incremented if request gets retried)
  SIPTAG_CONTACT(), SIPTAG_CONTACT_STR()
  SIPTAG_REQUEST_DISPOSITION(), SIPTAG_REQUEST_DISPOSITION_STR()
  SIPTAG_ACCEPT_CONTACT(), SIPTAG_ACCEPT_CONTACT_STR()
  SIPTAG_REJECT_CONTACT(), SIPTAG_REJECT_CONTACT_STR()
  SIPTAG_EXPIRES(), SIPTAG_EXPIRES_STR()
  SIPTAG_DATE(), SIPTAG_DATE_STR()
  SIPTAG_TIMESTAMP(), SIPTAG_TIMESTAMP_STR()
  SIPTAG_SUBJECT(), SIPTAG_SUBJECT_STR()
  SIPTAG_PRIORITY(), SIPTAG_PRIORITY_STR()
  SIPTAG_CALL_INFO(), SIPTAG_CALL_INFO_STR()
  SIPTAG_ORGANIZATION(), SIPTAG_ORGANIZATION_STR()
  NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR()
  SIPTAG_IN_REPLY_TO(), SIPTAG_IN_REPLY_TO_STR()
  SIPTAG_ACCEPT(), SIPTAG_ACCEPT_STR()
  SIPTAG_ACCEPT_ENCODING(), SIPTAG_ACCEPT_ENCODING_STR()
  SIPTAG_ACCEPT_LANGUAGE(), SIPTAG_ACCEPT_LANGUAGE_STR()
  NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
  NUTAG_EARLY_MEDIA(), SIPTAG_REQUIRE(), and SIPTAG_REQUIRE_STR()
  NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR()
  SIPTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS_STR()
  SIPTAG_PROXY_AUTHORIZATION(), SIPTAG_PROXY_AUTHORIZATION_STR()
  SIPTAG_AUTHORIZATION(), SIPTAG_AUTHORIZATION_STR()
  SIPTAG_REFERRED_BY(), SIPTAG_REFERRED_BY_STR()
  SIPTAG_REPLACES(), SIPTAG_REPLACES_STR()
  NUTAG_SESSION_TIMER(), NUTAG_SESSION_REFRESHER(), SIPTAG_SESSION_EXPIRES(), SIPTAG_SESSION_EXPIRES_STR()
  NUTAG_MIN_SE(), SIPTAG_MIN_SE(), SIPTAG_MIN_SE_STR()
  SIPTAG_SECURITY_CLIENT(), SIPTAG_SECURITY_CLIENT_STR()
  SIPTAG_SECURITY_VERIFY(), SIPTAG_SECURITY_VERIFY_STR()
  SIPTAG_PRIVACY(), SIPTAG_PRIVACY_STR()
  SIPTAG_MIME_VERSION(), SIPTAG_MIME_VERSION_STR()
  SIPTAG_CONTENT_TYPE(), SIPTAG_CONTENT_TYPE_STR()
  SIPTAG_CONTENT_ENCODING(), SIPTAG_CONTENT_ENCODING_STR()
  SIPTAG_CONTENT_LANGUAGE(), SIPTAG_CONTENT_LANGUAGE_STR()
  SIPTAG_CONTENT_DISPOSITION(), SIPTAG_CONTENT_DISPOSITION_STR()
  SIPTAG_HEADER(), SIPTAG_HEADER_STR()
  SIPTAG_PAYLOAD(), SIPTAG_PAYLOAD_STR()

SDP Handling
  By default the nua_invite() uses an SOA mediasession object to take care of the Offer/Answer exchange. The SOA can be disabled with tag NUTAG_MEDIA_ENABLE(0).

  The SDP description of the soa media session is included in the INVITE request as a message body. The SDP in the message body of the 1XX or 2XX response message is interpreted as an answer, given to the soa mediasession object for processing.

Bug
  If the INVITE request already contains a message body, SDP is not added. Also, if the response contains a multipart body, it is not parsed.

Tags Related to SDP Management and Offer/Answer Model:
  NUTAG_MEDIA_ENABLE(),
  NUTAG_INCLUDE_EXTRA_SDP(),
  SOATAG_HOLD(), SOATAG_AF(), SOATAG_ADDRESS(), SOATAG_ORDERED_USER(), SOATAG_REUSE_REJECTED(), SOATAG_RTP_SELECT(), SOATAG_RTP_SORT(), SOATAG_RTP_MISMATCH(), SOATAG_AUDIO_AUX(),
  SOATAG_USER_SDP() or SOATAG_USER_SDP_STR()

Alternative Call Models
  In addition to the basic SIP call model described in RFC 3261 and RFC 3264, the early media model described in RFC 3262 is available. The use of 100rel and early media can be use can be forced with NUTAG_EARLY_MEDIA(1).

Also, the "precondition" call model described in RFC 3312 is supported at SIP level, that is, the SIP PRACK and UPDATE requests are sent if "precondition" is added to the Require header in the INVITE request.

Optionally

- uses early media if NUTAG_EARLY_MEDIA() tag is used with non zero-value
- media parameters can be set by SOA tags
- nua_invite() can be used to change status of an existing call:
  - SOATAG_HOLD tag can be used to list the media that will be put on hold, the value "*" sets all the media beloginging to the session on hold

Authentication
  The INVITE request may need authentication. Each proxy or server requiring authentication can respond with 401 or 407 response. The nua_authenticate() operation stores authentication information (username and password) to the handle, and stack tries to authenticate all the rest of the requests (e.g., PRACK, ACK, UPDATE, re-INVITE, BYE) using the stored username and password.

See also
  NUA Call Model, nua_r_invite, nua_i_state,
  nua_handle_has_active_call()
  nua_handle_has_call_on_hold()
  nua_handle_has_invite()
  nua_authenticate()
  nua_prack()
  nua_update()
  nua_info()
  nua_cancel()
  nua_bye()
  nua_i_invite, nua_respond()

## nua_magic()

nua_magic_t * nua_magic | ( | nua_t * | nua | ) |

Fetch callback context from nua.

Parameters

  nua | Pointer to nua stack object

Returns
  Callback context pointer.

Since
  New in 1.12.4.

## nua_message()

void nua_message | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Send an instant message.

Send an instant message using SIP MESSAGE method.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NUTAG_URL()
  Tags of nua_set_hparams()
  Header tags defined in <sofia-sip/sip_tag.h>

Events:
  nua_r_message

See also
  nua_i_message, RFC 3428

## nua_notifier()

void nua_notifier | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Create an event server.

This function create an event server taking care of sending NOTIFY requests and responding to further SUBSCRIBE requests. The event server can accept multiple subscriptions from several sources and takes care for distributing the notifications. Unlike other functions this call only accepts the SIP tags listed below.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NUTAG_URL()
  SIPTAG_EVENT() or SIPTAG_EVENT_STR()
  SIPTAG_CONTENT_TYPE() or SIPTAG_CONTENT_TYPE_STR()
  SIPTAG_PAYLOAD() or SIPTAG_PAYLOAD_STR()
  SIPTAG_ACCEPT() or SIPTAG_ACCEPT_STR()

Events:
  nua_r_notify

## nua_notify()

void nua_notify | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Send a NOTIFY message.

Send a SIP NOTIFY request message.

This function is used when the application implements itself the notifier. The application must provide valid Subscription-State and Event headers using SIP tags. The subscription state can be modified with NUTAG_SUBSTATE(), however, its effect is overriden by Subscription-State header included in the nua_notify() tags.

Bug
  If the Event is not given by application, stack uses the Event header from the first subscription usage on handle.

If there is no active notifier dialog usage or no notifier dialog usage matches the Event header given by the application the nua_notify() request is rejected locally by the stack with status code 481. The local rejection can be bypassed if NUTAG_NEWSUB(1) is included in tags.

Please note that including NUTAG_NEWSUB(1) in nua_notify() tags if there is a valid subscription may lead to an extra NOTIFY sent to subscriber if the subscription had been terminated by the subscriber or by a timeout before the nua_notify() is processed.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NUTAG_SUBSTATE()
  NUTAG_NEWSUB()
  Tags of nua_set_hparams()
  Header tags defined in <sofia-sip/sip_tag.h>

Events:
  nua_r_notify

See also
  RFC 3265, nua_i_subscribe, nua_i_refer, NUTAG_ALLOW_EVENTS()

## nua_options()

void nua_options | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Query capabilities from server.

Query capabilities from server with OPTIONS request.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  Header tags defined in <sofia-sip/sip_tag.h>

Events:
  nua_r_options

See also
  nua_i_options, RFC 3261 section 10

## nua_prack()

void nua_prack | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Acknowledge a reliable preliminary response to INVITE request.

Send a PRACK request.

PRACK is used to acknowledge receipt of 100rel responses. See RFC 3262.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  Tags in <sofia-sip/soa_tag.h>, <sofia-sip/sip_tag.h>.

Events:
  nua_r_prack

## nua_publish()

void nua_publish | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Send PUBLISH request to publication server.

Request status will be delivered to the application using nua_r_publish event. When successful the publication will be updated periodically until nua_unpublish() is called or handle is destroyed. Note that the periodic updates and unpublish do not include the original message body nor the Content-Type header. Instead, the periodic update will include the SIP-If-Match header, which was generated from the latest SIP-ETag header received in response to PUBLISH request.

The handle used for publication cannot be used for any other purposes.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NUTAG_URL()
  Tags of nua_set_hparams()
  Header tags defined in <sofia-sip/sip_tag.h>

Events:
  nua_r_publish

See also
  nua_r_publish, RFC 3903, SIP-If-Match, nua_unpublish(), nua_r_unpublish, nua_i_publish

## nua_refer()

void nua_refer | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Transfer a call.

Send a REFER request asking the recipient to transfer the call.

The REFER request also establishes an implied subscription to the "refer" event. The "refer" event can have an "id" parameter, which has the value of CSeq number in the REFER request. After initiating the REFER request, the nua engine sends application a nua_r_refer event with status 100 and tag NUTAG_REFER_EVENT() containing a matching event header with id parameter.

Note that the Event header in the locally generated nua_r_refer event contains the id parameter. The id parameter contains the CSeq number of the REFER request, and it may get incremented if the request is retried because it got challenged or redirected. In that case, the application gets a new nua_r_refer event with status 100 and tag NUTAG_REFER_EVENT(). Also the recipient of the REFER request may or may not include the id parameter with the Event header in the NOTIFY requests messages which it sends to the sender of the REFER request.

Therefore the application is not able to modify the state of the implied subscription before receiving the first NOTIFY request.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NUTAG_URL()
  Tags of nua_set_hparams()
  Header tags defined in <sofia-sip/sip_tag.h>

Events:
  nua_r_refer
  nua_i_notify

See also
  nua_r_refer, NUTAG_SUBSTATE(), NUTAG_REFER_EVENT(),nua_i_refer, RFC 3515, Refer-To, SIPTAG_REFER_TO(), SIPTAG_REFER_TO_STR(), RFC 3892, Referred-By, SIPTAG_REFERRED_BY(), SIPTAG_REFERRED_BY_STR(), RFC 3891, Replaces, SIPTAG_REPLACES(), SIPTAG_REPLACES_STR(), RFC 4488, Refer-Sub, SIPTAG_REFER_SUB(), SIPTAG_REFER_SUB_STR()

## nua_register()

void nua_register | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Send SIP REGISTER request to the registrar.

Request status will be delivered to the application using nua_r_register event. When successful the registration will be updated periodically.

The handle used for registration cannot be used for any other purposes.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related tags:
  NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(), NUTAG_M_USERNAME(), NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES()

Events:
  nua_r_register, nua_i_outbound

Generating Contact Header

If the application did not specify the Contact header in the tags, nua_register() will generate one. It will obtain the schema, IP address for the host and port number for the Contact URI from the transport socket. The diplay name is taken from NUTAG_M_DISPLAY(), URL username part is taken from NUTAG_M_USERNAME(), URI parameters from NUTAG_M_PARAMS(), and Contact header parameters from NUTAG_M_FEATURES(). If NUTAG_CALLEE_CAPS(1) is specified, additional Contact header parameters are generated based on SDP capabilities and SIP Allow header.

Note that nua may append a identifier of its own to the Contact URI username. Such nua-generated identifier trailer always starts with "=" (equal sign), rest of the nua-generated identifier may contain any url-unreserved characters except "=".

Likewise, nua may add transport parameters (such as "transport=tcp" or "maddr") to the Contact URI. It can add addtional header parameters, like "+sip.instance" or "reg-id", too.

For instance, if application uses tags like

nua_register(nh,
NUTAG_M_DISPLAY("1"),
NUTAG_M_USERNAME("line-1"),
NUTAG_M_PARAMS("user=phone"),
NUTAG_M_FEATURES("audio"),
NUTAG_CALLEE_CAPS(0),
TAG_END())
nua_register
void nua_register(nua_handle_t *nh, tag_type_t, tag_value_t,...)
Send SIP REGISTER request to the registrar.
Definition nua.c:620
NUTAG_CALLEE_CAPS
#define NUTAG_CALLEE_CAPS(x)
Add methods parameter and media feature parameter to the Contact headers generated for REGISTER reque...
Definition nua_tag.h:563
NUTAG_M_DISPLAY
#define NUTAG_M_DISPLAY(x)
Display name for Contact.
Definition nua_tag.h:397
NUTAG_M_FEATURES
#define NUTAG_M_FEATURES(x)
Header parameters for Contact used in registration.
Definition nua_tag.h:412
NUTAG_M_USERNAME
#define NUTAG_M_USERNAME(x)
Username prefix for Contact.
Definition nua_tag.h:402
NUTAG_M_PARAMS
#define NUTAG_M_PARAMS(x)
URL parameters for Contact.
Definition nua_tag.h:407

nua can generate a Contact header like

Contact: 1 <sip:line-1=SSQAIbjv@192.168.1.200;transport=tcp;user=phone>
;audio;reg-id=1
;+sip.instance=urn:uuid:97701ad9-39df-1229-1083-dbc0a85f029c

The incoming request from the proxy should contain the registered contact URI as the request URI. The application can use the username prefix set by NUTAG_M_USERNAME() and the non-transport parameters of the request URI set by NUTAG_M_PARAMS() when determining to which registration the incoming request belongs.

For example, a request line correspoding to the Contact in above example may look like:

INVITE sip:line-1=SSQAIbjv@192.168.1.200;user=phone SIP/2.0

See also
  NUTAG_M_DISPLAY(), NUTAG_M_USERNAME(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(), NUTAG_CALLEE_CAPS().

NAT, Firewall and Outbound Support

Normally, nua will start start a protocol engine for outbound connections used for NAT and firewall traversal and connectivity checks when registering.

Note
  If the application provides nua with a Contact header of its own (or includes a SIPTAG_CONTACT(NULL) tag in nua_register() tags), the outbound protocol engine is not started. It is assumed that the application knows better what it is doing when it sets the Contact, or it is using experimental CPL upload as specified in draft-lennox-sip-reg-payload-01.txt.

First, outbound engine will probe for NATs in between UA and registrar. It will send a REGISTER request as usual. Upon receiving the response it checks for the presence of "received" and "rport" parameters in the Via header returned by registrar. The presence of NAT is determined from the "received" parameter in a Via header. When a REGISTER request was sent, the stack inserted the actual source IP address in the Via header: if that is different from the source IP address seen by the registrar, the registrar inserts the source IP address it sees into the "received" parameter.

Please note that an ALG (application-level gateway) modifying the Via headers in outbound requests and again in incoming responses will make the above-described NAT check to fail.

The response to the initial REGISTER should also include option tags indicating whether registrar supports various SIP extension options: outbound, pref, path, gruu.

Basically, outbound means that instead of registering its contact URI with a particular address-of-record URI, the user-agent registers a transport-level connection. Such a connection is identified on the Contact header field with an instance identifier, application-provided unique string identifying the user-agent instance and a stack-generated numeric index identifying the transport-level connection.

If the outbound extension is supported, NUTAG_OUTBOUND() contains option string "outbound" and the application has provided an instance identifer to the stack with NUTAG_INSTANCE(), the nua_register() will try to use outbound.

If outbound is not supported, nua_register() has to generate a URI that can be used to reach it from outside. It will check for public transport addresses detected by underlying stack with, e.g., STUN, UPnP or SOCKS. If there are public addresses, nua_register() will use them. If there is no public address, it will try to generate a Contact URI from the "received" and "rport" parameters found in the Via header of the response message.

Todo
  Actually generate public addresses.

You can disable this kind of NAT traversal by setting "no-natify" into NUTAG_OUTBOUND() options string.

GRUU and Service-Route

After a successful response to the REGISTER request has been received, nua_register() will update the information about the registration based on it. If there is a "gruu" parameter included in the response, nua_register() will save it and use the gruu URI in the Contact header fields of dialog-establishing messages, such as INVITE or SUBSCRIBE. Also, if the registrar has included a Service-Route header in the response, and the service route feature has not been disabled using NUTAG_SERVICE_ROUTE_ENABLE(), the route URIs from the Service-Route header will be used for initial non-REGISTER requests.

The nua_r_register message will include the contact header and route used in with the registration.

Registration Keep-Alive

After the registration has successfully completed the nua_register() will validate the registration and initiate the keepalive mechanism, too. The user-agent validates the registration by sending a OPTIONS requests to itself. If there is an error, nua_register() will indicate that to the application using nua_i_outbound event, and start unregistration procedure (unless that has been explicitly disabled).

You can disable validation by inserting "no-validate" into NUTAG_OUTBOUND() string.

The keepalive mechanism depends on the network features detected earlier. If outbound extension is used, the STUN keepalives will be used. Otherwise, NUA stack will repeatedly send OPTIONS requests to itself. In order to save bandwidth, it will include Max-Forwards: 0 in the keep-alive requests, however. The keepalive interval is determined by NUTAG_KEEPALIVE() parameter. If the interval is 0, no keepalive messages is sent.

You can disable keepalive OPTIONS by inserting "no-options-keepalive" into NUTAG_OUTBOUND() string. Currently there are no other keepalive mechanisms available.

The value of NUTAG_KEEPALIVE_STREAM(), if specified, is used to indicate the desired transport-layer keepalive interval for stream-based transports like TLS and TCP.

As alternative to OPTIONS/STUN keepalives, the client can propose a more frequent registration refresh interval with NUTAG_M_FEATURES() (e.g. NUTAG_M_FEATURES("expires=120") given as parameter to nua_register()).

See also
  nua_r_register, nua_unregister(), nua_r_unregister, nua_i_register, RFC 3261 section 10, Expires, Contact, Call-ID, CSeq, Path, RFC 3327, Service-Route, RFC 3608, RFC 3680, NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(), SIPTAG_CONTACT(), SIPTAG_CONTACT_STR(), NUTAG_M_USERNAME(), NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),

## nua_respond()

void nua_respond | ( | nua_handle_t * | nh,
|  | int | status,
|  | char const * | phrase,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Respond to a request with given status code and phrase.

The stack returns a SIP response message with given status code and phrase to the client. The tagged parameter list can specify extra headers to include with the response message and other stack parameters. The SIP session or other protocol state associated with the handle is updated accordingly (for instance, if an initial INVITE is responded with 200, a SIP session is established.)

When responding to an incoming INVITE request, the nua_respond() can be called without NUTAG_WITH() (or NUTAG_WITH_CURRENT() or NUTAG_WITH_SAVED()). Otherwise, NUTAG_WITH() will contain an indication of the request being responded.

Parameters

  nh | Pointer to operation handle
  status | SIP response status code (see RFCs of SIP)
  phrase | free text (default response phrase is used if NULL)
  tag,value,... | List of tagged parameters

Returns
  nothing

Responses by Protocol Engine

When nua protocol engine receives an incoming SIP request, it can either respond to the request automatically or let application to respond to the request. The automatic response is returned to the client if the request fails syntax check, or the method, SIP extension or content negotiation fails.

When the request event is delivered to the application, the application should examine the status parameter. The status parameter is 200 or greater if the request has been already responded automatically by the stack.

The application can add methods that it likes to handle by itself with NUTAG_APPL_METHOD(). The default set of NUTAG_APPL_METHOD() includes INVITE, PUBLISH, REGISTER and SUBSCRIBE. Note that unless the method is also included in the set of allowed methods with NUTAG_ALLOW(), the stack will respond to the incoming methods with 405 Not Allowed.

In order to simplify the simple applications, most requests are responded automatically. The BYE and CANCEL requests are always responded by the stack. Likewise, the NOTIFY requests associated with an event subscription are responded by the stack.

Note that certain methods are rejected outside a SIP session (created with INVITE transaction). They include BYE, UPDATE, PRACK and INFO. Also the auxiliary methods ACK and CANCEL are rejected by the stack if there is no ongoing INVITE transaction corresponding to them.

Related Tags:
  NUTAG_WITH(), NUTAG_WITH_THIS(), NUTAG_WITH_SAVED()
  NUTAG_EARLY_ANSWER()
  SOATAG_ADDRESS()
  SOATAG_AF()
  SOATAG_HOLD()
  Tags used with nua_set_hparams()
  Header tags defined in <sofia-sip/sip_tag.h>.

Events:
  nua_i_state
  nua_i_media_error
  nua_i_error
  nua_i_active
  nua_i_terminated

See also
  nua_i_invite, nua_i_register, nua_i_subscribe, nua_i_publish

## nua_save_event()

int nua_save_event | ( | nua_t * | nua,
|  | nua_saved_event_t | return_saved[1] )

Save last nua event.

Save last nua event.

See also
  nua_event_e, nua_event_data() nua_saved_event_request(), nua_destroy_event()

## nua_saved_event_request()

msg_t * nua_saved_event_request | ( | nua_saved_event_t const * | saved | ) |

Get request message from saved nua event.

Since
  New in 1.12.4.

See also
  nua_save_event(), nua_respond(), NUTAG_WITH_SAVED(),

## nua_set_hparams()

void nua_set_hparams | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Set handle parameters.

Set the handle-specific parameters.

The handle-specific parameters override default or global parameters set by nua_set_params(). The handle-specific parameters are set by several other operations: nua_invite(), nua_respond(), nua_ack(), nua_prack(), nua_update(), nua_info(), nua_bye(), nua_options(), nua_message(), nua_register(), nua_publish(), nua_refer(), nua_subscribe(), nua_notify(), nua_refer(), and nua_notifier().

Parameters

  nh | Pointer to a NUA handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Tags Used to Set Handle-Specific Parameters:
  NUTAG_ACCEPT_MULTIPART()
  NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
  NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and SIPTAG_ALLOW_EVENTS_STR()
  NUTAG_APPL_EVENT()
  NUTAG_APPL_METHOD()
  NUTAG_AUTH_CACHE()
  NUTAG_AUTO100()
  NUTAG_AUTO302()
  NUTAG_AUTO305()
  NUTAG_AUTOACK()
  NUTAG_AUTOALERT()
  NUTAG_AUTOANSWER()
  NUTAG_CALLEE_CAPS()
  NUTAG_EARLY_ANSWER()
  NUTAG_EARLY_MEDIA()
  NUTAG_ENABLEINVITE()
  NUTAG_ENABLEMESSAGE()
  NUTAG_ENABLEMESSENGER()
  NUTAG_INITIAL_ROUTE()
  NUTAG_INITIAL_ROUTE_STR()
  NUTAG_INSTANCE()
  NUTAG_INVITE_TIMER()
  NUTAG_KEEPALIVE()
  NUTAG_KEEPALIVE_STREAM()
  NUTAG_MAX_RETRY_AFTER()
  NUTAG_MAX_SUBSCRIPTIONS()
  NUTAG_MEDIA_ENABLE()
  NUTAG_MEDIA_FEATURES()
  NUTAG_MIN_SE()
  NUTAG_M_DISPLAY()
  NUTAG_M_FEATURES()
  NUTAG_M_PARAMS()
  NUTAG_M_USERNAME()
  NUTAG_ONLY183_100REL()
  NUTAG_OUTBOUND()
  NUTAG_PATH_ENABLE()
  NUTAG_PROXY() (aka NTATAG_DEFAULT_PROXY())
  NUTAG_REFER_EXPIRES()
  NUTAG_REFER_WITH_ID()
  NUTAG_REFRESH_WITHOUT_SDP()
  NUTAG_REGISTRAR()
  NUTAG_RETRY_COUNT()
  NUTAG_SERVICE_ROUTE_ENABLE()
  NUTAG_SESSION_REFRESHER()
  NUTAG_SESSION_TIMER()
  NUTAG_SOA_NAME()
  NUTAG_SUBSTATE()
  NUTAG_SUB_EXPIRES()
  NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR()
  NUTAG_UPDATE_REFRESH()
  NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR()
  SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR()
  Any soa tags are also considered as handle-specific parameters. They are defined in <sofia-sip/soa_tag.h>.

The global parameters that can not be set by nua_set_hparams() include NUTAG_DETECT_NETWORK_UPDATES(), NUTAG_SMIME_* tags, and all NTA tags.

Events:
  nua_r_set_params

## nua_set_params()

void nua_set_params | ( | nua_t * | nua,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Set NUA parameters.

Set nua parameters, shared by all handles.

Parameters

  nua | Pointer to NUA stack object
  tag,value,... | List of tagged parameters

Returns
  nothing

Related tags:
  NUTAG_ACCEPT_MULTIPART()
  NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
  NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and SIPTAG_ALLOW_EVENTS_STR()
  NUTAG_APPL_EVENT()
  NUTAG_APPL_METHOD()
  NUTAG_AUTO100()
  NUTAG_AUTO302()
  NUTAG_AUTO305()
  NUTAG_AUTOACK()
  NUTAG_AUTOALERT()
  NUTAG_AUTOANSWER()
  NUTAG_CALLEE_CAPS()
  NUTAG_DETECT_NETWORK_UPDATES()
  NUTAG_EARLY_ANSWER()
  NUTAG_EARLY_MEDIA()
  NUTAG_ENABLEINVITE()
  NUTAG_ENABLEMESSAGE()
  NUTAG_ENABLEMESSENGER()
  NUTAG_INITIAL_ROUTE()
  NUTAG_INITIAL_ROUTE_STR()
  NUTAG_INSTANCE()
  NUTAG_INVITE_TIMER()
  NUTAG_KEEPALIVE()
  NUTAG_KEEPALIVE_STREAM()
  NUTAG_MAX_RETRY_AFTER()
  NUTAG_MAX_SUBSCRIPTIONS()
  NUTAG_MEDIA_ENABLE()
  NUTAG_MEDIA_FEATURES()
  NUTAG_MIN_SE()
  NUTAG_M_DISPLAY()
  NUTAG_M_FEATURES()
  NUTAG_M_PARAMS()
  NUTAG_M_USERNAME()
  NUTAG_ONLY183_100REL()
  NUTAG_OUTBOUND()
  NUTAG_PATH_ENABLE()
  NUTAG_PROXY() (aka NTATAG_DEFAULT_PROXY())
  NUTAG_REFER_EXPIRES()
  NUTAG_REFER_WITH_ID()
  NUTAG_REFRESH_WITHOUT_SDP()
  NUTAG_REGISTRAR()
  NUTAG_RETRY_COUNT()
  NUTAG_SERVICE_ROUTE_ENABLE()
  NUTAG_SESSION_REFRESHER()
  NUTAG_SESSION_TIMER()
  NUTAG_SMIME_ENABLE()
  NUTAG_SMIME_KEY_ENCRYPTION()
  NUTAG_SMIME_MESSAGE_DIGEST()
  NUTAG_SMIME_MESSAGE_ENCRYPTION()
  NUTAG_SMIME_OPT()
  NUTAG_SMIME_PROTECTION_MODE()
  NUTAG_SMIME_SIGNATURE()
  NUTAG_SOA_NAME()
  NUTAG_SUBSTATE()
  NUTAG_SUB_EXPIRES()
  NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR()
  NUTAG_UPDATE_REFRESH()
  NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR()
  SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR()
  nua_set_params() also accepts any soa tags, defined in <sofia-sip/soa_tag.h>, and nta tags, defined in <sofia-sip/nta_tag.h>.

Events:
  nua_r_set_params

SIP Header as NUA Parameters
  The nua parameters include SIP headers Allow, Supported, Organization, User-Agent and From. They are included in most of the SIP messages sent by nua. They are set in the same way as the tagged arguments are used to populate a SIP message.

  When multiple tags for the same header are specified, the behaviour depends on the header type. If only a single header field can be included in a SIP message, the latest non-NULL value is used, e.g., Organization. However, if the SIP header can consist of multiple lines or header fields separated by comma, in this case, Allow and Supported, all the tagged values are concatenated.

  However, if the tag value is SIP_NONE (-1 casted as a void pointer), the values from previous tags are ignored.

For example, the nua_set_params() call like this:

nua_set_params(nua,
SIPTAG_USER_AGENT_STR("tester/1.0"),
SIPTAG_ALLOW_STR("INVITE,CANCEL,BYE,ACK"),
SIPTAG_ORGANIZATION(NULL),
SIPTAG_USER_AGENT(NULL),
SIPTAG_ALLOW(SIP_NONE),
TAG_END());
SIPTAG_ALLOW
#define SIPTAG_ALLOW(x)
SIPTAG_ALLOW_STR
#define SIPTAG_ALLOW_STR(s)
SIPTAG_ORGANIZATION
#define SIPTAG_ORGANIZATION(x)
SIPTAG_USER_AGENT_STR
#define SIPTAG_USER_AGENT_STR(s)
SIPTAG_USER_AGENT
#define SIPTAG_USER_AGENT(x)
nua_set_params
void nua_set_params(nua_t *, tag_type_t, tag_value_t,...)
Set NUA parameters.
Definition nua.c:570
SIP_NONE
#define SIP_NONE

will leave Allow and Organization headers empty. The User-Agent header will contain value "tester/1.0".

nua_set_params(nua,
SIPTAG_ORGANIZATION_STR("Malevolent Microwavers"),
SIPTAG_ALLOW_STR("OPTIONS"),
SIPTAG_ALLOW(SIP_NONE),
SIPTAG_ORGANIZATION_STR("The Phone Company"),
SIPTAG_ALLOW_STR("SUBSCRIBE"),
SIPTAG_ALLOW(NULL),
SIPTAG_ORGANIZATION_STR(NULL),
TAG_END());
SIPTAG_ORGANIZATION_STR
#define SIPTAG_ORGANIZATION_STR(s)

sets the header Allow with value `SUBSCRIBE` and the header Organization will have value `The Phone Company`.

## nua_subscribe()

void nua_subscribe | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Subscribe a SIP event.

Subscribe to a SIP event.

Subscribe a SIP event using the SIP SUBSCRIBE request. If the SUBSCRBE is successful a subscription state is established and the subscription is refreshed regularly. The refresh requests will generate nua_r_subscribe events.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NUTAG_URL() Header tags defined in <sofia-sip/sip_tag.h>

Events:
  nua_r_subscribe
  nua_i_notify

See also
  NUTAG_SUBSTATE(), RFC 3265

## nua_substate_make()

enum nua_substate nua_substate_make | ( | char const * | sip_substate | ) |

Convert string to enum nua_substate.

Since
  New in 1.12.5.

## nua_substate_name()

char const * nua_substate_name | ( | enum nua_substate | substate | ) |

Return name of subscription state.

Since
  New in 1.12.5.
  New in 1.12.5.

See also
  enum nua_substate, nua_event_name(), nua_callstate_name()

## nua_terminate()

void nua_terminate | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Terminate an event server.

Terminate an event server with matching event and content type. The event server was created earlier with nua_notifier() function.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  SIPTAG_EVENT()
  SIPTAG_CONTENT_TYPE()
  SIPTAG_PAYLOAD()
  NEATAG_REASON()

Events:
  nua_r_terminate

See also
  nua_notifier(), nua_authorize().

## nua_unpublish()

void nua_unpublish | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Send un-PUBLISH request to publication server.

Un-PUBLISH request is just a PUBLISH request with Expires set to 0. It is possible to un-publish a publication not associated with the handle by providing correct ETag in SIPTAG_IF_MATCH() or SIPTAG_IF_MATCH_STR() tags.

Response to the un-PUBLISH request will be delivered to the application using nua_r_unpublish event.

The handle used for publication cannot be used for any other purposes.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  NUTAG_URL()
  SIPTAG_IF_MATCH(), SIPTAG_IF_MATCH_STR()
  SIPTAG_EVENT(), SIPTAG_EVENT_STR()
  Tags of nua_set_hparams()
  Other header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()

Events:
  nua_r_unpublish

See also
  nua_r_unpublish, RFC 3903, SIP-If-Match, nua_i_publish, nua_publish(), nua_r_publish

## nua_unregister()

void nua_unregister | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Unregister.

Send a REGISTER request with expiration time 0. This removes the registration from the registrar. If the handle was earlier used with nua_register() the periodic updates will be terminated.

If a SIPTAG_CONTACT_STR() with argument "*" is used, all the registrations will be removed from the registrar otherwise only the contact address belonging to the NUA stack is removed.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related tags:
  NUTAG_REGISTRAR()
  Header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()

Events:
  nua_r_unregister

See also
  nua_register(), nua_r_register, nua_handle_destroy(), nua_shutdown(), nua_i_register, Expires, Contact, Call-ID, CSeq, RFC 3261 section 10, Path, RFC 3327, Service-Route, RFC 3608, RFC 3680, NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(), SIPTAG_CONTACT(), SIPTAG_CONTACT_STR(), NUTAG_M_USERNAME(), NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),

## nua_unsubscribe()

void nua_unsubscribe | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Unsubscribe an event.

Unsubscribe an active or pending subscription with SUBSCRIBE request containing Expires: header with value 0. The dialog associated with subscription will be destroyed if there is no other subscriptions or call using this dialog.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  SIPTAG_EVENT() or SIPTAG_EVENT_STR()
  Header tags defined in <sofia-sip/sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()

Events:
  nua_r_unsubscribe

See also
  NUTAG_SUBSTATE(), RFC 3265

## nua_update()

void nua_update | ( | nua_handle_t * | nh,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Update a call.

Update a session.

Update a session using SIP UPDATE method. See RFC 3311.

Update method can be used when the session has been established with INVITE. It's mainly used during the session establishment when preconditions are used (RFC 3312). It can be also used during the call if no user input is needed for offer/answer negotiation.

Parameters

  nh | Pointer to operation handle
  tag,value,... | List of tagged parameters

Returns
  nothing

Related Tags:
  same as nua_invite()

Events:
  nua_r_update
  nua_i_state (nua_i_active, nua_i_terminated)
  nua_i_media_error

See also
  NUA Call Model, RFC 3311, nua_update(), nua_i_update

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