nua 1.12.11devel
Loading...
Searching...
No Matches
Macros | Typedefs | Enumerations | Functions | Variables
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_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.
 
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_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_t * nua_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.
 
nua_handle_tnua_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

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

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:

int status,
char const *phrase,
nua_t *nua,
nua_magic_t *magic,
nua_hmagic_t *hmagic,
sip_t const *sip,
tagi_t tags[]);
NUA_HMAGIC_T nua_hmagic_t
Application context for NUA handle.
Definition nua.h:66
NUA_MAGIC_T nua_magic_t
Application context for NUA agent.
Definition nua.h:60
enum nua_event_e nua_event_t
Events.
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
struct nua_handle_s nua_handle_t
NUA transaction handle.
Definition nua_tag.h:66
struct nua_s nua_t
NUA agent.
Definition nua_tag.h:63
Parameters
eventCallback event identification.
Always present
statusProtocol status code.
Always present
phraseText corresponding to status code.
Always present
nuaPointer to NUA stack object.
Always present
magicPointer to callback context from nua_create().
Always present
nhPointer to operation handle.
hmagicPointer to callback context from nua_handle().
sipHeaders in parsed incoming message. May be NULL. See also nua_current_request().
tagsTag 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
statusSIP status code or NUA status code (>= 900) describing the problem
phrasea short textual description of status code
nhNULL or operation handle associated with the call
hmagicNULL or operation magic associated with the call
sipNULL
tagsempty or error specific information
 
nua_i_invite 

Incoming call INVITE.

Indication of incoming call or re-INVITE request.

Parameters
statusstatuscode of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with this call (maybe created for this call)
hmagicapplication context associated with this call (maybe NULL if call handle was created for this call)
sipincoming INVITE request
tagsSOATAG_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
statusstatus code of response to CANCEL sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipincoming CANCEL request
tagsempty
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
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipincoming ACK request
tagsempty
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
statusresponse status code
phrasea short textual description of status code
nhoperation handle associated with the original call
hmagicoperation magic associated with the original call
sippreliminary or 2XX response to INVITE
tagsNUTAG_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
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipNULL
tagsSOATAG_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
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipNULL
tagsempty
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
statusprotocol status code
(always present)
phraseshort description of status code
(always present)
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipNULL
tagsNUTAG_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
statusSIP status code or NUA status code (>= 900) describing the outbound state
phrasea short textual description of status code
nhoperation handle associated with the outbound engine
hmagicapplication context associated with the handle
sipNULL or response message to an keepalive message or registration probe (error code and message are in status an phrase parameters)
tagsempty
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
statusstatuscode of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sippointer to BYE request
tagsempty
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
statusstatus code of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the OPTIONS request
hmagicapplication context associated with the call (NULL if outside session)
sipincoming OPTIONS request
tagsempty
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
statusstatus code of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the incoming request
hmagicapplication context associated with the handle (NULL if outside of an already established session)
sipincoming REFER request
tagsNUTAG_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
statusstatus code of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the incoming request
hmagicapplication context associated with the call (usually NULL)
sipincoming PUBLISH request
tagsempty
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
statusstatus code of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipincoming PRACK request
tagsempty
See also
nua_prack(), nua_r_prack, RFC 3262, NUTAG_EARLY_MEDIA()
 
nua_i_info 

Incoming session INFO.

Incoming session INFO request.

Parameters
statusstatuscode of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipincoming INFO request
tagsempty
See also
nua_info(), nua_r_info, RFC 2976
 
nua_i_update 

Incoming session UPDATE.

Incoming session UPDATE request.

Parameters
statusstatuscode of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipincoming UPDATE request
tagsempty
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
statusstatus code of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the message
hmagicapplication context associated with the handle (maybe NULL if outside session)
sipincoming MESSAGE request
tagsempty
See also
nua_message(), nua_r_message, RFC 3428, RFC 3862
 
nua_i_chat 

Incoming chat MESSAGE

Incoming chat message.

Parameters
nhoperation handle associated with the message
hmagicoperation magic associated with the handle
sipincoming chat message
tagsempty
 
nua_i_subscribe 

Incoming SUBSCRIBE

Incoming SUBSCRIBE request.

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

Parameters
statusstatus code of response sent automatically by stack
phraseresponse phrase sent automatically by stack
nhoperation handle associated with the incoming request
hmagicapplication context associated with the handle (NULL when handle is created by the stack)
sipSUBSCRIBE request headers
tagsNUTAG_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
nhoperation handle associated with the notifier
hmagicoperation magic
statusstatuscode of response sent automatically by stack
sipincoming SUBSCRIBE request
tagsNEATAG_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
statusstatuscode of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the subscription
hmagicapplication context associated with the handle
sipincoming NOTIFY request
tagsNUTAG_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
statusstatus code of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the method
hmagicapplication context associated with the handle (maybe NULL if outside session)
sipheaders in incoming request (see also nua_current_request())
tagsNUTAG_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
statusSIP status code or NUA status code (>= 900) describing the problem
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicoperation magic associated with this handle (maybe NULL if call handle was created for this call)
sipNULL
tagsempty
 
nua_r_set_params 

Answer to nua_set_params() or nua_get_hparams().

Response to nua_set_params() or nua_set_hparams().

Parameters
status200 when successful, error code otherwise
phrasea short textual description of status code
nhNULL when responding to nua_set_params(), operation handle when responding to nua_set_hparams()
hmagicNULL when responding to nua_set_params(), application contact associated with the operation handle when responding to nua_set_hparams()
sipNULL
tagsNone
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
status200 when succesful, error code otherwise
phrasea short textual description of status code
nhNULL when responding to nua_get_params(), operation handle when responding to nua_get_hparams()
hmagicNULL when responding to nua_get_params(), application contact associated with the operation handle when responding to nua_get_hparams()
sipNULL
tagsNUTAG_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
nuaPointer 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
statusshutdown status code
nhNULL
hmagicNULL
sipNULL
tagsempty
See also
nua_shutdown(), nua_destroy()
 
nua_r_notifier 

Answer to nua_notifier()

Answer to nua_notitier()

Parameters
nhoperation handle associated with the call
hmagicoperation magic associated with the call
sipNULL
tagsSIPTAG_EVENT()
SIPTAG_CONTENT_TYPE()
See also
nua_notitier(), nua_i_subscription, RFC 3265
 
nua_r_terminate 

Answer to nua_terminate()

Answer to nua_terminate().

Parameters
nhoperation handle associated with the notifier
hmagicoperation magic associated with the notifier
sipNULL
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the registration
hmagicapplication context associated with the registration
sipresponse message to REGISTER request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the registration
hmagicapplication context associated with the registration
sipresponse message to REGISTER request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
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
statusresponse status code
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipresponse to CANCEL request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipresponse to BYE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
See also
nua_bye(), NUA Call Model, nua_i_state, nua_r_invite()
 
nua_r_options 

Answer to outgoing OPTIONS.

Parameters
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the incoming OPTIONS request
hmagicapplication context associated with the handle
sipresponse to OPTIONS request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
See also
nua_options(), RFC 3261 section 11, nua_i_options
 
nua_r_refer 

Answer to outgoing REFER.

Response to outgoing REFER.

Parameters
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the REFER request
hmagicapplication context associated with the handle
sipresponse to REFER request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsNUTAG_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
statusstatus 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)
phrasea short textual description of status code
nhoperation handle associated with the publication
hmagicapplication context associated with the handle
sipresponse to PUBLISH request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the publication
hmagicapplication context associated with the handle
sipresponse to PUBLISH request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipresponse to INFO or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipresponse to PRACK or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the call
hmagicapplication context associated with the call
sipresponse to UPDATE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the message
hmagicapplication context associated with the handle
sipresponse to MESSAGE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsempty
See also
nua_message(), nua_i_message, RFC 3428
 
nua_r_chat 

Answer to outgoing chat message.

Parameters
nhoperation handle associated with the notifier
hmagicoperation magic associated with the notifier
sipresponse to MESSAGE request or NULL upon an error (error code and message are in status and phrase parameters)
tagsempty
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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the subscription
hmagicapplication context associated with the handle
sipresponse to SUBSCRIBE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsNUTAG_SUBSTATE()
See also
nua_subscribe(), RFC 3265
 
nua_r_unsubscribe 

Answer to outgoing un-SUBSCRIBE.

Response to an outgoing un-SUBSCRIBE.

Parameters
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the subscription
hmagicapplication context associated with the handle
sipresponse to SUBSCRIBE request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsNUTAG_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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the subscription
hmagicapplication context associated with the handle
sipresponse to NOTIFY request or NULL upon an error (status code is in status and descriptive message in phrase parameters)
tagsNUTAG_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
statusresponse 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)
phrasea short textual description of status code
nhoperation handle associated with the method
hmagicapplication context associated with the handle
sipresponse to the extension request or NULL upon an error (status code is in status and descriptive method in phrase parameters)
tagsempty
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
statusstatus code from authentication
phrasea short textual description of status code
nhoperation handle authenticated
hmagicapplication context associated with the handle
sipNULL
tagsempty
See also
nua_terminate(), nua_handle_destroy()
 
nua_i_network_changed 

Local IP(v6) address has changed.

Since
New in 1.12.2
Parameters
nhdefault operation handle
hmagicoperation magic associated with the default operation handle
sipNULL
tagsempty
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
statusstatus code of response sent automatically by stack
phrasea short textual description of status code
nhoperation handle associated with the request
hmagicapplication context associated with the handle (usually NULL)
sipincoming REGISTER request
tagsempty
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

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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
rootPointer to a root object
callbackPointer to event callback function
magicPointer to callback context
tag, value, ...List of tagged parameters
Return values
!=NULLa pointer to a nua stack object
NULLupon an error
Related tags:
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
nuaPointer to nua stack object
Return values
!=NULLPointer to nua operation handle
NULLNo 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
nuaPointer 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,
if (hmagic == NULL)
return;
...
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
int nua_event_is_incoming_request(nua_event_t e)
Check if event can be responded with nua_respond()
Definition nua_common.c:284
void nua_handle_destroy(nua_handle_t *h)
Destroy a handle.
Definition nua.c:919
#define NUTAG_WITH_THIS(nua)
Specify request to respond to.
Definition nua_tag.h:88
#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
nhPointer 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.

void nua_get_hparams(nua_handle_t *, tag_type_t, tag_value_t,...)
Get handle parameters.
Definition nua.c:614
nua_handle_t * nua_default(nua_t *nua)
Obtain default operation handle of the NUA stack object.
Definition nua.c:271
#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
nuaPointer 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:
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
nuaPointer to nua stack object
hmagicPointer to callback context
tag,value,...List of tagged parameters
Return values
!=NULLPointer to operation handle
NULLCreation 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
nhPointer to operation handle
hmagicPointer 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
nhPointer 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
nhPointer to operation handle
Return values
0no active call in operation or operation handle is invalid
1operation 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
nhPointer to operation handle
Return values
0if no call on hold in operation or operation handle is invalid
1if 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
nhPointer to operation handle
Return values
0no event subscriptions in operation or operation handle is invalid
!=0operation 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
nhPointer to operation handle
Return values
0no invite in operation or operation handle is invalid
1operation 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
nhPointer to operation handle
Return values
0no active register in operation or operation handle is invalid
1operation 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
nhPointer to operation handle
Return values
0no active registration in operation or operation handle is invalid
1operation 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
nhPointer to operation handle
Return values
0no active subscription in operation or operation handle is invalid
1operation 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

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
nhPointer to operation handle
Return values
NULLno local address for operation or operation handle invalid
!=NULLpointer 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
nhPointer 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
nhpointer to operation handle
homememory home used to allocate the header
early_onlyif 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
nhPointer to operation handle
Return values
NULLno remote address for operation or operation handle invalid
!=NULLpointer 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
nhPointer 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
nhPointer 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). @par The SDP description of the @ref soa_session_t "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 @ref soa_session_t "soa media session" object for processing. \xrefitem bug 2. @par Tags Related to SDP Management and Offer/Answer Model: NUTAG_MEDIA_ENABLE(), \n NUTAG_INCLUDE_EXTRA_SDP(), \n SOATAG_HOLD(), SOATAG_AF(), SOATAG_ADDRESS(), SOATAG_ORDERED_USER(), SOATAG_REUSE_REJECTED(), SOATAG_RTP_SELECT(), SOATAG_RTP_SORT(), SOATAG_RTP_MISMATCH(), SOATAG_AUDIO_AUX(), \n SOATAG_USER_SDP() or SOATAG_USER_SDP_STR() \n @par Alternative Call Models In addition to the basic SIP call model described in <a href="http://tools.ietf.org/html3261">RFC 3261</a> and <a href="http://tools.ietf.org/html3264">RFC 3264</a>, the early media model described in <a href="http://tools.ietf.org/html3262">RFC 3262</a> 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 <a href="http://tools.ietf.org/html3312">RFC 3312</a> is supported at SIP level, that is, the SIP PRACK and UPDATE requests are sent if "precondition" is added to the @ref sip_require "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
nuaPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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

NUTAG_M_USERNAME("line-1"),
NUTAG_M_PARAMS("user=phone"),
NUTAG_M_FEATURES("audio"),
void nua_register(nua_handle_t *nh, tag_type_t, tag_value_t,...)
Send SIP REGISTER request to the registrar.
Definition nua.c:620
#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
#define NUTAG_M_DISPLAY(x)
Display name for Contact.
Definition nua_tag.h:397
#define NUTAG_M_FEATURES(x)
Header parameters for Contact used in registration.
Definition nua_tag.h:412
#define NUTAG_M_USERNAME(x)
Username prefix for Contact.
Definition nua_tag.h:402
#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
nhPointer to operation handle
statusSIP response status code (see RFCs of SIP)
phrasefree 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
nhPointer 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
nuaPointer 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:

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

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

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),
TAG_END());
#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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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
nhPointer 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.