sofia-sip/nua.h File Reference


Detailed Description

Sofia-SIP User Agent Library API.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Date:
Created: Wed Feb 14 17:09:44 2001 ppessi

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


Defines

#define NUA_MAGIC_T
 Defined when <sofia-sip/nua.h> has been included.
#define NUA_VERSION
 NUA API version.

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 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 { ,
  nua_i_error,
  nua_i_invite,
  nua_i_cancel,
  nua_i_ack,
  nua_i_fork,
  nua_i_active,
  nua_i_terminated,
  nua_i_state,
  nua_i_outbound,
  nua_i_bye,
  nua_i_options,
  nua_i_refer,
  nua_i_publish,
  nua_i_prack,
  nua_i_info,
  nua_i_update,
  nua_i_message,
  nua_i_chat,
  nua_i_subscribe,
  nua_i_subscription,
  nua_i_notify,
  nua_i_method,
  nua_i_media_error,
  nua_r_set_params,
  nua_r_get_params,
  nua_r_shutdown,
  nua_r_notifier,
  nua_r_terminate,
  nua_r_authorize,
  nua_r_register,
  nua_r_unregister,
  nua_r_invite,
  nua_r_cancel,
  nua_r_bye,
  nua_r_options,
  nua_r_refer,
  nua_r_publish,
  nua_r_unpublish,
  nua_r_info,
  nua_r_prack,
  nua_r_update,
  nua_r_message,
  nua_r_chat,
  nua_r_subscribe,
  nua_r_unsubscribe,
  nua_r_notify,
  nua_r_method,
  nua_r_authenticate ,
  nua_i_network_changed,
  nua_i_register
}
 Events. More...

Functions

nua_tnua_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_tnua_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_tnua_default (nua_t *nua)
 Obtain default operation handle of the NUA stack object.
nua_handle_tnua_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_tnua_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_tnua_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.
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,...)
 Extension request method.
void nua_respond (nua_handle_t *nh, int status, char const *phrase, tag_type_t, tag_value_t,...)
 Respond with given status.
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_tnua_saved_event_request (nua_saved_event_t const *saved)
 Get request message from saved nua event.
msg_tnua_current_request (nua_t const *nua)
 Get current request message.
sip_replaces_tnua_handle_make_replaces (nua_handle_t *nh, su_home_t *home, int early_only)
 Generate a Replaces header for handle.
nua_handle_tnua_handle_by_replaces (nua_t *nua, sip_replaces_t const *rp)
 Obtain a new reference to an existing handle based on Replaces header.

Variables

char const nua_version []
 NUA module version.

Typedef Documentation

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

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

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 Parsed incoming message. May be NULL.
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:

Indications:
nua_i_active
nua_i_ack
nua_i_bye
nua_i_cancel
nua_i_chat
nua_i_error
nua_i_fork
nua_i_info
nua_i_invite
nua_i_media_error
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_subscription
nua_i_state
nua_i_terminated
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
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.

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 message

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

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.

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 200 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.
nua_i_terminated  A call has been terminated.
nua_i_state  Call state has changed.
nua_i_outbound  Status from outbound processing.

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.

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.

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.

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.

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

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 INFO request
tags empty
See also:
nua_prack(), nua_r_prack, RFC 3262, NUTAG_EARLY_MEDIA()
 
nua_i_info  Incoming session INFO.

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.
nua_i_message  Incoming MESSAGE.

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.

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.

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

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()). 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_CURRENT()/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 because the SUBSCRIBE request was forked by an intermediate proxy.

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.

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.

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

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.

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 incoming request
tags NUTAG_METHOD()
The extension name is in sip->sip_request->rq_method_name, too.

See also:
nua_method(), nua_r_method
 
nua_i_media_error  Offer-answer 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().

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

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

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.

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.

The INVITE may be sent explicitly by nua_invite() 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 message to INVITE or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tags empty
See also:
nua_invite(), NUA Call Model, nua_i_state, nua_i_invite, nua_ack(), NUTAG_AUTOACK()
 
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.

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, Refer-To, RFC 3892, Referred-By
 
nua_r_publish  Answer to 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.

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.

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.

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.

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 an phrase parameters)
tags empty
See also:
nua_chat(), nua_r_message
 
nua_r_subscribe  Answer to outgoing SUBSCRIBE.

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.

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.

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)

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
See also:
nua_notify(), RFC 3265, nua_i_subscribe, nua_i_refer
 
nua_r_method  Answer to unknown outgoing method.

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

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
nua_i_register  Incoming REGISTER.

Since:
New in 1.12.4.

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

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

Acknowledge a succesfull response to INVITE request.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <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

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

Authenticate an operation.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_AUTH()
Events:
(any operation events)

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

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

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:
Tags in <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

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

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()
NUTAG_URL()
NUTAG_SIPS_URL()
NUTAG_SIP_PARSER()
NUTAG_UICC()
NUTAG_CERTIFICATE_DIR()
and all tags listed in nua_set_params(),
and all relevant NTATAG_* are passed to NTA.
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()

msg_t* nua_current_request ( nua_t const *  nua  ) 

Get current request message.

Since:
New in 1.12.4.

nua_handle_t* nua_default ( nua_t nua  ) 

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

void nua_destroy ( nua_t nua  ) 

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

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

Get handle parameters.

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.

Returns:
nothing
Related tags:
TAG_ANY
othervise same tags as nua_set_hparams()
Events:
nua_r_get_params

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

Get NUA parameters.

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

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_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 handle.
See also:
nua_handle_make_replaces(), Replaces, RFC 3891, nua_refer(), nua_i_refer, Refer-To, nta_leg_by_replaces()

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

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

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

int nua_handle_has_events ( nua_handle_t const *  nh  ) 

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

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

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

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

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

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

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

Generate a Replaces header for handle.

Since:
New in 1.12.4.
See also:
nua_handle_by_replaces(), Replaces, RFC 3891, nua_refer(), nua_i_refer, Refer-To, nta_leg_make_replaces()

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

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

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

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:
Tags in <sip_tag.h>.
Events:
nua_r_info
See also:
nua_i_info

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

Place a call using SIP INVITE method.

Incomplete call can be hung-up with nua_cancel(). Complete or incomplete calls can be hung-up with nua_bye().

Optionally

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
Tags of nua_set_hparams()
NUTAG_INCLUDE_EXTRA_SDP()
SOATAG_HOLD(), SOATAG_AF(), SOATAG_ADDRESS(), SOATAG_RTP_SELECT(), SOATAG_RTP_SORT(), SOATAG_RTP_MISMATCH(), SOATAG_AUDIO_AUX(),
SOATAG_USER_SDP() or SOATAG_USER_SDP_STR()
See use of tags in <sip_tag.h> below
Events:
nua_r_invite
nua_i_state (nua_i_active, nua_i_terminated)
nua_i_media_error
nua_i_fork
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 tag is added to From header.
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.
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 registered the URI in From header, the Contact header used with registration is used. Otherwise, the Contact header is generated from the local IP address and port number.
For the initial INVITE requests, Service-Route set received from the registrar is also added to the request message.
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).
SDP Handling
The initial nua_invite() creates a soa media session unless NUTAG_MEDIA_ENABLE(0) has been given. The SDP description of the soa media session is included in the INVITE request as message body.
The SDP in a 1XX or 2XX response message is interpreted as an answer, given to the soa media session 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.
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 same 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_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.

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

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

Send a NOTIFY 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. If there is no Subscription-State header, the subscription state can be modified with NUTAG_SUBSTATE().

Bug:
If the Event is not given by application, stack uses the Event header from the first subscription usage on handle.
Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_SUBSTATE()
Tags of nua_set_hparams()
Tags in <sip_tag.h>
Events:
nua_r_notify
See also:
RFC 3265, nua_i_subscribe, nua_i_refer, NUTAG_ALLOW_EVENTS()

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

Query capabilities from server.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>
Events:
nua_r_options
See also:
nua_i_options, RFC 3261 section 10

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

Acknowledge a reliable preliminary response to INVITE 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

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

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

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

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.

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

Set handle 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_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and SIPTAG_ALLOW_EVENTS_STR()
NUTAG_AUTOACK()
NUTAG_AUTOALERT()
NUTAG_AUTOANSWER()
NUTAG_CALLEE_CAPS()
NUTAG_EARLY_ANSWER()
NUTAG_EARLY_MEDIA()
NUTAG_ENABLEINVITE()
NUTAG_ENABLEMESSAGE()
NUTAG_ENABLEMESSENGER()
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_REGISTRAR()
NUTAG_RETRY_COUNT()
NUTAG_SERVICE_ROUTE_ENABLE()
NUTAG_SESSION_REFRESHER()
NUTAG_SESSION_TIMER()
NUTAG_SOA_NAME()
NUTAG_SUBSTATE()
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

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

Set NUA parameters.

Parameters:
nua Pointer to NUA stack object
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and SIPTAG_ALLOW_EVENTS_STR()
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_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_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_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());
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());
sets the header Allow with value SUBSCRIBE and the header Organization will have value The Phone Company.

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

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()
Tags in <sip_tag.h>
Events:
nua_r_unpublish
See also:
nua_r_unpublish, RFC 3903, SIP-If-Match, nua_i_publish, nua_publish(), nua_r_publish

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()
Tags in <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(),

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

Update a call.

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.4 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.