sofia-sip/nua.h File Reference


Detailed Description

Sofia-SIP User Agent Library API.

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

#include <sofia-sip/su_wait.h>
#include <sofia-sip/url.h>
#include <sofia-sip/sip.h>
#include <sofia-sip/nua_tag.h>

Include dependency graph for nua.h:


Defines

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

Typedefs

typedef NUA_MAGIC_T nua_magic_t
 Application context for NUA agent.
typedef NUA_HMAGIC_T nua_hmagic_t
 Application context for NUA handle.
typedef enum nua_event_e nua_event_t
 Events.
typedef NUA_SAVED_EVENT_T nua_saved_event_t
 Abstract type for saved nua events.

Enumerations

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

Functions

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

Variables

SOFIAPUBVAR char const nua_version []
 NUA module version.

Enumeration Type Documentation

enum nua_event_e

Events.

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

The prototype of the event callback function is:

 void nua_callback_f(nua_event_t   event,
                     int           status,
                     char const   *phrase,
                     nua_t        *nua,
                     nua_magic_t  *magic,
                     nua_handle_t *nh,
                     nua_hmagic_t *hmagic,
                     sip_t const  *sip,
                     tagi_t        tags[]);

Parameters:
event Callback event identification.
Always present
status Protocol status code.
Always present
phrase Text corresponding to status code.
Always present
nua Pointer to NUA stack object.
Always present
magic Pointer to callback context from nua_create().
Always present
nh Pointer to operation handle.
hmagic Pointer to callback context from nua_handle().
sip Parsed incoming message.
tags Tag list containing more information about the state of NUA.
Note that the contents of the last four parameters vary depending on the event. The descriptions can be found from the description of the individual event.

The events can be divided into the following categories:

Indications:
nua_i_active
nua_i_bye
nua_i_cancel
nua_i_chat
nua_i_error
nua_i_fork
nua_i_info
nua_i_invite
nua_i_media_error
nua_i_message
nua_i_method
nua_i_notify
nua_i_options
nua_i_prack
nua_i_publish
nua_i_refer
nua_i_subscribe
nua_i_subscription
nua_i_state
nua_i_terminated
nua_i_update
Responses:
nua_r_get_params
nua_r_notifier
nua_r_shutdown
nua_r_terminate
SIP responses:
nua_r_bye
nua_r_cancel
nua_r_info
nua_r_invite
nua_r_message
nua_r_notify
nua_r_options
nua_r_prack
nua_r_publish
nua_r_refer
nua_r_register
nua_r_subscribe
nua_r_unpublish
nua_r_unregister
nua_r_unsubscribe
nua_r_update
Enumerator:
nua_i_error  Error indication.

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

Parameters:
nh NULL or operation handle associated with the call
hmagic NULL or operation magic associated with the call
sip NULL
tags empty or error specific information
nua_i_invite  Incoming call.

Parameters:
nh operation handle associated with this call (maybe created for this call)
hmagic operation magic associated with this call (maybe NULL if call handle was created for this call)
sip incoming INVITE request
tags NUTAG_ACTIVE_*
nua_i_cancel  Incoming INVITE has been cancelled.

Incoming INVITE has been cancelled or no ACK has been received for an accepted call.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip incoming CANCEL request or NULL if time-out occured
tags empty
nua_i_ack  Response to INVITE has been ACKed.
nua_i_fork  Outgoing call has been forked.

This is sent when an INVITE request is answered with multiple 200 responses.

Parameters:
nh operation handle associated with the original call
hmagic operation magic associated with the original call
sip 200 series response to INVITE
tags NUTAG_HANDLE of the new forked call
nua_i_active  A call has been activated.

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

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip NULL
tags NUTAG_ACTIVE_* tags
nua_i_terminated  A call has been terminated.

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

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip NULL
tags empty
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, also SDP O/A negotiation status is included.

Note that nua_event_e::nua_i_state also covers call establisment (

See also:
nua_event_e::nua_i_active ) and termination (

nua_event_e::nua_i_terminated ).

Parameters:
status Protocol status code.
Always present
phrase Text corresponding to status code.
Always present
nh Operation handle associated with the call
hmagic Operation magic associated with the call
sip NULL
tags NUTAG_ACTIVE_*
NUTAG_SOA_SESSION
nua_i_outbound  Status from outbound processing.

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

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to REGISTER request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_i_bye  Incoming call hangup.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip pointer to BYE request
tags empty
nua_i_options  Incoming options.

Parameters:
nh operation handle associated with the call (default operation handle if outside session)
hmagic operation magic associated with the call (NULL if outside session)
sip incoming OPTIONS request
tags empty
nua_i_refer  Incoming call transfer.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call (NULL if outside session)
sip incoming REFER request
tags NUTAG_REFER_EVENT
SIPTAG_REFERRED_BY
nua_i_publish  Incoming PUBLISH.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call (NULL if outside session)
sip incoming PUBLISH request
tags empty
nua_i_prack  Incoming PRACK.
nua_i_info  Incoming session INFO.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip incoming INFO request
tags empty
nua_i_update  Incoming session UPDATE.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip incoming UPDATE request
tags empty
nua_i_message  Incoming MESSAGE.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call (maybe NULL if outside session)
sip incoming MESSAGE request
tags empty
nua_i_chat  Incoming chat MESSAGE.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip incoming char MESSAGE
tags empty
nua_i_subscribe  Incoming subscription.

Not implemented.

Parameters:
nh 
hmagic 
sip 
tags 
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 and to authorize the subscriber.

Parameters:
nh operation handle associated with the nua_notifier
hmagic operation magic
sip incoming SUBSRIBE request
tags empty
nua_i_notify  Incoming event.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip incoming NOTIFY request
tags NUTAG_SUBSTATE indicating the subscription state
nua_i_method  Incoming, unknown method.

The extension method must be listed using SIPTAG_ALLOW tag in nua_set_options().

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip incoming request with unknown method
tags empty
nua_i_media_error  Offer-answer error indication.

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

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with this call (maybe NULL if call handle was created for this call)
sip NULL
tags NUTAG_MEDIA_SESSION (optionally)
nua_r_set_params  Answer to nua_set_params().
nua_r_get_params  Answer to nua_get_params() or nua_get_hparams().

Parameters:
nh NULL
hmagic NULL
sip NULL
tags NUTAG_*
SIPTAG_*
NTATAG_*
nua_r_shutdown  Answer to nua_shutdown().

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

Parameters:
nh NULL
hmagic NULL
sip NULL
tags empty
nua_r_notifier  Answer to nua_notifier().

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip NULL
tags SIPTAG_EVENT
SIPTAG_CONTENT_TYPE
nua_r_terminate  Answer to nua_terminate().

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip NULL
tags empty
nua_r_authorize  Answer to nua_authorize().
nua_r_register  Answer to outgoing REGISTER.

The REGISTER may be sent explicitly by nua_register() or implicitly by NUA state machines. The status may be 100 even if the real response status returned is different if the REGISTER request has been restarted.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
status registration status
sip response to REGISTER request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_unregister  Answer to outgoing un-REGISTER.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to REGISTER request or NULL upon an error (error code and message are in status and phrase parameters)
tags empty
nua_r_invite  Answer to outgoing INVITE.

The INVITE may be sent explicitly by nua_invite() or implicitly by NUA state machine.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to INFO or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_cancel  Answer to outgoing CANCEL.
nua_r_bye  Answer to outgoing BYE.

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

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to BYE request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_options  Answer to outgoing OPTIONS.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to OPTIONS request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_refer  Answer to outgoing REFER.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to REFER request or NULL upon an error (error code and message are in status an phrase parameters)
tags NUTAG_REFER_EVENT
NUTAG_SUBSTATE
nua_r_publish  Answer to outgoing PUBLISH.

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

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to PUBLISH request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_unpublish  Answer to outgoing un-PUBLISH.

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

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to PUBLISH request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_info  Answer to outgoing INFO.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to INFO or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_prack  Answer to outgoing PRACK.
nua_r_update  Answer to outgoing UPDATE.

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

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to UPDATE request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_message  Answer to outgoing MESSAGE.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to MESSAGE request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_chat  Answer to outgoing chat message.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to MESSAGE request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_subscribe  Answer to outgoing SUBSCRIBE.

The SUBSCRIBE may be sent explicitly by nua_subscribe() or implicitly by NUA state machine.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to SUBSCRIBE request or NULL upon an error (error code and message are in status an phrase parameters)
tags NUTAG_SUBSTATE
nua_r_unsubscribe  Answer to outgoing un-SUBSCRIBE.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to SUBSCRIBE request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_notify  Answer to outgoing NOTIFY.

The NOTIFY may be sent explicitly by nua_notify() or implicitly by NUA state machine.

Parameters:
nh operation handle associated with the call
hmagic operation magic associated with the call
sip response to NOTIFY request or NULL upon an error (error code and message are in status an phrase parameters)
tags empty
nua_r_method  Answer to unknown outgoing method.


Function Documentation

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

Acknowledge a succesfull response to INVITE request.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>
Events:
nua_i_media_error
nua_i_active

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

Authenticate an operation.

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

SOFIAPUBFUN 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 subscriber launches nua_i_subscription event. Subscriber can be authorized in this application callback.

NUTAG_SUB() tag NUTAG_SUBSTATE() tag

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

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

Hangdown a call.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
none
Events:
nua_r_bye
nua_i_media_error

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

Cancel an INVITE operation.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>
Events:
nua_r_cancel

SOFIAPUBFUN 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_active event containing SOATAG_ACTIVE_CHAT tag. Chat messages can be sent using this channel with nua_chat() function. Currently this is implemented using SIP MESSAGE requests but in future MSRP (message session protocol) will replace it.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
SIPTAG_CONTENT_TYPE
SIPTAG_PAYLOAD
SIPTAG_FROM
SIPTAG_TO
use of other SIP tags' is deprecated
Events:
nua_r_chat

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

Create a NUA agent.

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

Parameters:
root Pointer to a root object
callback Pointer to event callback function
magic Pointer to callback context
tag, value, ... List of tagged parameters
Return values:
!=NULL a pointer to a NUA stack object
NULL upon an error
Related tags:
NUTAG_MEDIA_ENABLE()
NUTAG_SOA_NAME()
NUTAG_PROXY()
NUTAG_URL()
NUTAG_SIPS_URL()
NUTAG_SIP_PARSER()
NUTAG_UICC()
NUTAG_CERTIFICATE_DIR()
all relevant NTATAG_* are passed to NTA
Note:
Both the NUTAG_URL and NUTAG_SIPS_URL() are used to pass arguments to nta_agent_add_tport().
Events:
none

SOFIAPUBFUN nua_handle_t* nua_default ( nua_t nua  ) 

Obtain default operation handle of the NUA stack object.

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

Parameters:
nua Pointer to NUA stack object
Return values:
!=NULL Pointer to NUA operation handle
NULL No default operation exists
Related tags:
none
Events:
none

SOFIAPUBFUN void nua_destroy ( nua_t nua  ) 

Destroy the NUA stack.

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

Parameters:
nua Pointer to NUA stack object
Returns:
nothing
Related tags:
none
Events:
none

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

Get handle parameters.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
The handle-specific parameters will contain only the parameters actually modified by application, either by nua_set_hparams() or some other handle-specific call. Currently, no NTA parameters are returned. They are returned only when application asks for user-agent-level parameters using either nua_get_params() or using default handle, eg.
 nua_get_hparams(nua_default(nua), TAG_ANY())

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

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

Get NUA parameters.

Get values of NUA parameters in nua_r_get_params event.

Parameters:
nua Pointer to NUA stack object
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
TAG_ANY
othervise same tags as nua_set_params()
Events:
nua_r_get_params

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

Create an operation handle.

Allocates a new operation handle and associated storage.

Parameters:
nua Pointer to NUA stack object
hmagic Pointer to callback context
tag,value,... List of tagged parameters
Return values:
!=NULL Pointer to operation handle
NULL Creation failed
Related tags:
Creates a copy of provided tags and they will be used with every operation.
Events:
none

SOFIAPUBFUN void nua_handle_bind ( nua_handle_t nh,
nua_hmagic_t hmagic 
)

Bind a callback context to an operation handle.

Parameters:
nh Pointer to operation handle
hmagic Pointer to callback context
Returns:
nothing
Related tags:
none
Events:
none

SOFIAPUBFUN void nua_handle_destroy ( nua_handle_t nh  ) 

Destroy a handle.

Destroy an operation handle and asks stack to discard resources and ongoing sessions and transactions associated with this handle. For example calls are terminated with BYE request.

Parameters:
nh Pointer to operation handle
Returns:
nothing
Related Tags:
none
Events:
none

SOFIAPUBFUN int nua_handle_has_active_call ( nua_handle_t const *  nh  ) 

Check if operation handle has an active call.

Parameters:
nh Pointer to operation handle
Return values:
0 no active call in operation or operation handle is invalid
1 operation has established call or pending call request.
Related tags:
none
Events:
none

SOFIAPUBFUN 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_active event.

Parameters:
nh Pointer to operation handle
Return values:
0 if no call on hold in operation or operation handle is invalid
1 if operation has call on hold, for example nua_invite() or nua_update() has been called with NUTAG_HOLD() with != 0 argument.
Related tags:
none
Events:
none

SOFIAPUBFUN int nua_handle_has_events ( nua_handle_t const *  nh  ) 

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

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

Parameters:
nh Pointer to operation handle
Return values:
0 no event subscriptions in operation or operation handle is invalid
!=0 operation has event subscriptions
Related tags:
none
Events:
none

SOFIAPUBFUN int nua_handle_has_invite ( nua_handle_t const *  nh  ) 

Check if operation handle is used for INVITE.

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

Parameters:
nh Pointer to operation handle
Return values:
0 no invite in operation or operation handle is invalid
1 operation has invite
Related tags:
none
Events:
none

SOFIAPUBFUN int nua_handle_has_register ( nua_handle_t const *  nh  ) 

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

Parameters:
nh Pointer to operation handle
Return values:
0 no active register in operation or operation handle is invalid
1 operation has been used with nua_register() or nua-unregister()
Related tags:
none
Events:
none

SOFIAPUBFUN int nua_handle_has_registrations ( nua_handle_t const *  nh  ) 

Check if operation handle has active registrations.

Either REGISTER operation is ongoing or NUA stack is expected to refresh in the future.

Parameters:
nh Pointer to operation handle
Return values:
0 no active registration in operation or operation handle is invalid
1 operation has registration
Related tags:
none
Events:
none

SOFIAPUBFUN int nua_handle_has_subscribe ( nua_handle_t const *  nh  ) 

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

Parameters:
nh Pointer to operation handle
Return values:
0 no active subscription in operation or operation handle is invalid
1 operation has subscription.
Related tags:
none
Events:
none

SOFIAPUBFUN sip_to_t const* nua_handle_local ( nua_handle_t const *  nh  ) 

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

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

Parameters:
nh Pointer to operation handle
Return values:
NULL no local address for operation or operation handle invalid
!=NULL pointer to local address for operation
Related tags:
none
Events:
none

SOFIAPUBFUN nua_handle_t* nua_handle_ref ( nua_handle_t nh  ) 

Make a new reference to handle.

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

SOFIAPUBFUN sip_to_t const* nua_handle_remote ( nua_handle_t const *  nh  ) 

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

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

Parameters:
nh Pointer to operation handle
Return values:
NULL no remote address for operation or operation handle invalid
!=NULL pointer to remote address for operation
Related tags:
none
Events:
none

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

Send an INFO request.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>.
Events:
nua_r_info

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

Place a call using SIP INVITE method.

By default creates a media session, includes its description as SDP and send the request to the recipient. Upon receiving the response it will active the media session and establish the call.

Incomplete call can be hung-up with nua_cancel(). Completed call can be hung-up with nua_bye().

Optionally

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
NUTAG_HOLD()
NUTAG_NOTIFY_REFER()
NUTAG_REFER_PAUSE()
NUTAG_INVITE_TIMER()
NUTAG_MEDIA_FEATURES()
NUTAG_MEDIA_ENABLE()
SOATAG_HOLD()
SOATAG_AF()
SOATAG_ADDRESS()
SOATAG_USER_SDP() or SOATAG_USER_SDP_STR()
tags in <sip_tag.h>
Events:
nua_r_invite
nua_i_state
nua_i_active
nua_i_media_error
nua_i_fork
See also:
nua_handle_has_active_call()
nua_handle_has_call_on_hold()
nua_handle_has_invite()
nua_update()
nua_info()
nua_cancel()
nua_bye()

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

Send an instant message.

Send an instant message using SIP MESSAGE method.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>
Events:
nua_r_message

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

Create an event server.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
SIPTAG_EVENT or SIPTAG_EVENT_STR
SIPTAG_CONTENT_TYPE or SIPTAG_CONTENT_TYPE_STR
SIPTAG_PAYLOAD or SIPTAG_PAYLOAD_STR
SIPTAG_ACCEPT or SIPTAG_ACCEPT_STR
Events:
nua_r_notify

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

Send a NOTIFY message.

This function is used when the application implements itself the subscription state machine. The application must provide valid Subscription-State and Event headers using SIP tags.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>
Events:
nua_r_notify

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

Query capabilities from server.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>
Events:
nua_r_options

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

Acknowledge a reliable preliminary response to INVITE request.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sofia-sip/soa_tag.h>, <sofia-sip/sip_tag.h>.
Events:
nua_r_prack

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

Send PUBLISH request to publication server.

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
Tags in <sip_tag.h>
Events:
nua_r_publish

SOFIAPUBFUN 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 a subscription to the "refer" event. The "refer" event will 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 SIPTAG_EVENT() containing a matching event header.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
Tags in <sip_tag.h>
Events:
nua_r_refer
nua_i_notify
See also:
RFC 3515

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

Send SIP REGISTER request to the registrar.

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(),
Events:
nua_r_register, nua_i_outbound
NAT, Firewall and Outbound Support
If the application did not include the Contact header in the tags, nua_register() will generate one and start a protocol engine for outbound connections used for NAT and firewall traversal and connectivity checks.

First, nua_register() 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 valid "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 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 feature tags indicating whether registrar supports various SIP extensions: outbound, pref, path, gruu.

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

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

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

Todo:
Actually generate public addresses.
You can disable this kind of NAT traversal by setting "no-natify" into NUTAG_OUTBOUND() options string.

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

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

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

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

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

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

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

See also:
NUTAG_OUTBOUND() and tags.

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

Respond with given status.

The INVITE requests should be responded with nua_intive_respond() function because there might be another request going on besides INVITE.

Parameters:
nh Pointer to operation handle
status SIP response status (see RFCs of SIP)
phrase free text (default response phrase used if NULL)
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
SOATAG_ADDRESS
SOATAG_AF
SOATAG_HOLD
Tags in <sip_tag.h>.
Events:
nua_i_active
nua_i_media_error
nua_i_error

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

Set handle parameters.

Parameters:
nh Pointer to a NUA handle
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
NUTAG_ALLOW()
NUTAG_AUTOACK()
NUTAG_AUTOALERT()
NUTAG_AUTOANSWER()
NUTAG_CALLEE_CAPS()
NUTAG_EARLY_MEDIA()
NUTAG_ENABLEINVITE()
NUTAG_ENABLEMESSAGE()
NUTAG_ENABLEMESSENGER()
NUTAG_INVITE_TIMER()
NUTAG_KEEPALIVE()
NUTAG_KEEPALIVE_STREAM()
NUTAG_MAX_SUBSCRIPTIONS()
NUTAG_MEDIA_FEATURES()
NUTAG_MIN_SE()
NUTAG_PATH_ENABLE()
NUTAG_RETRY_COUNT()
NUTAG_SERVICE_ROUTE_ENABLE()
NUTAG_SESSIONRESHER()
NUTAG_SESSION_TIMER()
NUTAG_SUBSTATE()
NUTAG_UPDATERESH()
NUTAG_USER_AGENT()
SIPTAG_ALLOW()
SIPTAG_ALLOW_STR()
SIPTAG_ORGANIZATION()
SIPTAG_ORGANIZATION_STR()
SIPTAG_SUPPORTED()
SIPTAG_SUPPORTED_STR()
SIPTAG_USER_AGENT()
SIPTAG_USER_AGENT_STR()
nua_set_hparams() also accepts any soa tags, defined in <sofia-sip/soa_tag.h>.

Events:
none

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

Set NUA parameters.

Parameters:
nua Pointer to NUA stack object
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
NUTAG_ALLOW()
NUTAG_AUTOACK()
NUTAG_AUTOALERT()
NUTAG_AUTOANSWER()
NUTAG_CALLEE_CAPS()
NUTAG_CERTIFICATE_DIR()
NUTAG_EARLY_MEDIA()
NUTAG_ENABLEINVITE()
NUTAG_ENABLEMESSAGE()
NUTAG_ENABLEMESSENGER()
NUTAG_INSTANCE()
NUTAG_INVITE_TIMER()
NUTAG_KEEPALIVE()
NUTAG_KEEPALIVE_STREAM()
NUTAG_MAX_SUBSCRIPTIONS()
NUTAG_MEDIA_FEATURES()
NUTAG_MIN_SE()
NUTAG_OUTBOUND()
NUTAG_PATH_ENABLE()
NUTAG_REGISTRAR()
NUTAG_SERVICE_ROUTE_ENABLE()
NUTAG_SESSIONRESHER()
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_SUBSTATE()
NUTAG_UPDATERESH()
NUTAG_USER_AGENT()
SIPTAG_ALLOW()
SIPTAG_ALLOW_STR()
SIPTAG_FROM()
SIPTAG_FROM_STR()
SIPTAG_ORGANIZATION()
SIPTAG_ORGANIZATION_STR()
SIPTAG_SUPPORTED()
SIPTAG_SUPPORTED_STR()
SIPTAG_USER_AGENT()
SIPTAG_USER_AGENT_STR()
NUTAG_RETRY_COUNT()
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

SOFIAPUBFUN void nua_shutdown ( nua_t nua  ) 

Shutdown NUA stack.

Ongoing calls are released, registrations unregistered, and subscriptions terminated. If the stack cannot terminate within 30 seconds, it sends the nua_r_shutdown event with status 500.

Parameters:
nua Pointer to NUA stack object
Returns:
nothing
Related tags:
none
Events:
nua_r_shutdown

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

Subscribe a SIP event.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL() Tags in <sip_tag.h>
Events:
nua_r_subscribe
nua_i_notify

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

Terminate an event server.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
SIPTAG_EVENT
SIPTAG_CONTENT_TYPE
SIPTAG_PAYLOAD
NEATAG_REASON
Events:
nua_r_terminate

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

Send un-PUBLISH request to publication server.

Request status will be delivered to the application using nua_r_unpublish event. The handle used for un-publication cannot be used for any other purposes.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
Tags in <sip_tag.h>
Events:
nua_r_publish

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

Unregister.

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
NUTAG_REGISTRAR()
Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
Events:
nua_r_unregister

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

Unsubscribe an event.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
SIPTAG_EVENT
Tags in <sip_tag.h> except SIPTAG_EXPIRES or SIPTAG_EXPIRES_STR
Events:
nua_r_unsubscribe

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

Update a call.

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
same as nua_invite()
Events:
nua_r_update
nua_i_media_error
nua_i_media_update


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