nua  1.12.11devel
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. More...
 
#define NUA_VERSION
 NUA API version.
 
#define nua_handle_home(nh)
 Cast a nua_handle_t pointer to a su_home_t. More...
 

Typedefs

typedef NUA_MAGIC_T nua_magic_t
 Application context for NUA agent. More...
 
typedef NUA_HMAGIC_T nua_hmagic_t
 Application context for NUA handle. More...
 
typedef enum nua_nw_detector_e nua_nw_detector_t
 Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES(). More...
 
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. More...
 
typedef NUA_SAVED_EVENT_T nua_saved_event_t
 Abstract type for saved nua events. More...
 

Enumerations

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

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

Macro Definition Documentation

#define NUA_H

Defined when <sofia-sip/nua.h> has been included.

#define nua_handle_home (   nh)

Cast a nua_handle_t pointer to a su_home_t.

Typedef Documentation

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_HMAGIC_T nua_hmagic_t

Application context for NUA handle.

typedef NUA_MAGIC_T nua_magic_t

Application context for NUA agent.

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.
typedef NUA_SAVED_EVENT_T nua_saved_event_t

Abstract type for saved nua events.

Enumeration Type Documentation

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:

1 void nua_callback_f(nua_event_t event,
2  int status,
3  char const *phrase,
4  nua_t *nua,
5  nua_magic_t *magic,
6  nua_handle_t *nh,
7  nua_hmagic_t *hmagic,
8  sip_t const *sip,
9  tagi_t tags[]);
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
 

Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES().

See also
NUTAG_DETECT_NETWORK_UPDATES(), nua_i_network_changed
Since
New in 1.12.2.

Function Documentation

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

Acknowledge a succesfull response to INVITE request.

Acknowledge a 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
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)
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()
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
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()
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
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_t* nua_create ( su_root_t root,
nua_callback_f  callback,
nua_magic_t