nua.c File Reference


Detailed Description

High-Level User Agent Library - "nua" Implementation.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Kai Vehmanen <Kai.Vehmanen@nokia-email.address.hidden>

Pasi Rinne-Rahkola

Date:
Created: Wed Feb 14 18:32:58 2001 ppessi

#include "config.h"
#include <sofia-sip/su_tag.h>
#include <sofia-sip/su_tag_class.h>
#include <sofia-sip/su_tagarg.h>
#include <sofia-sip/su_tag_io.h>
#include <sofia-sip/su_debug.h>
#include <sofia-sip/sip_status.h>
#include <sofia-sip/sip_header.h>
#include <sofia-sip/nta.h>
#include "sofia-sip/nua.h"
#include "sofia-sip/nua_tag.h"
#include "nua_stack.h"
#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <assert.h>

Include dependency graph for nua.c:


Functions

nua_tnua_create (su_root_t *root, nua_callback_f callback, nua_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Create a NUA agent.
void nua_shutdown (nua_t *nua)
 Shutdown NUA stack.
void nua_destroy (nua_t *nua)
 Destroy the NUA stack.
nua_magic_tnua_magic (nua_t *nua)
 Fetch callback context from nua.
nua_handle_tnua_default (nua_t *nua)
 Obtain default operation handle of the NUA stack object.
nua_handle_tnua_handle (nua_t *nua, nua_hmagic_t *hmagic, tag_type_t tag, tag_value_t value,...)
 Create an operation handle.
void nua_handle_bind (nua_handle_t *nh, nua_hmagic_t *hmagic)
 Bind a callback context to an operation handle.
nua_hmagic_tnua_handle_magic (nua_handle_t *nh)
 Fetch a callback context from an operation handle.
int nua_handle_has_invite (nua_handle_t const *nh)
 Check if operation handle is used for INVITE.
int nua_handle_has_events (nua_handle_t const *nh)
 Check if handle has active event subscriptions (refers sent).
int nua_handle_has_registrations (nua_handle_t const *nh)
 Check if operation handle has active registrations.
int nua_handle_has_subscribe (nua_handle_t const *nh)
 Check if operation handle has been used with outgoing SUBSCRIBE of REFER request.
int nua_handle_has_register (nua_handle_t const *nh)
 Check if operation handle has been used with nua_register() or nua_unregister().
int nua_handle_has_active_call (nua_handle_t const *nh)
 Check if operation handle has an active call.
int nua_handle_has_call_on_hold (nua_handle_t const *nh)
 Check if operation handle has a call on hold.
sip_to_t const * nua_handle_remote (nua_handle_t const *nh)
 Get the remote address (From/To header) of operation handle.
sip_to_t const * nua_handle_local (nua_handle_t const *nh)
 Get the local address (From/To header) of operation handle.
void nua_set_params (nua_t *nua, tag_type_t tag, tag_value_t value,...)
 Set NUA parameters.
void nua_get_params (nua_t *nua, tag_type_t tag, tag_value_t value,...)
 Get NUA parameters.
void nua_set_hparams (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Set handle parameters.
void nua_get_hparams (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Get handle parameters.
void nua_register (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Send SIP REGISTER request to the registrar.
void nua_unregister (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Unregister.
void nua_invite (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Place a call using SIP INVITE method.
void nua_ack (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Acknowledge a succesfull response to INVITE request.
void nua_bye (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Hangdown a call.
void nua_cancel (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Cancel an INVITE operation.
void nua_options (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Query capabilities from server.
void nua_message (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Send an instant message.
void nua_method (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Send a request message with an extension method.
void nua_chat (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Send a chat message.
void nua_subscribe (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Subscribe a SIP event.
void nua_unsubscribe (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Unsubscribe an event.
void nua_notify (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Send a NOTIFY message.
void nua_notifier (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Create an event server.
void nua_terminate (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Terminate an event server.
void nua_refer (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Transfer a call.
void nua_publish (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Send PUBLISH request to publication server.
void nua_unpublish (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Send un-PUBLISH request to publication server.
void nua_info (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Send an INFO request.
void nua_prack (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Acknowledge a reliable preliminary response to INVITE request.
void nua_update (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Update a call.
void nua_authenticate (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Authenticate an operation.
void nua_authorize (nua_handle_t *nh, tag_type_t tag, tag_value_t value,...)
 Authorize a subscriber.
void nua_respond (nua_handle_t *nh, int status, char const *phrase, tag_type_t tag, tag_value_t value,...)
 Respond to a request with given status code and phrase.
void nua_handle_destroy (nua_handle_t *nh)
 Destroy a handle.
msg_tnua_current_request (nua_t const *nua)
 Get current request message.
msg_tnua_saved_event_request (nua_saved_event_t const *saved)
 Get request message from saved nua event.
int nua_save_event (nua_t *nua, nua_saved_event_t return_saved[1])
 Save last nua event.
nua_event_data_t const * nua_event_data (nua_saved_event_t const saved[1])
 Get information from saved event.
void nua_destroy_event (nua_saved_event_t saved[1])
 Destroy saved event.
sip_replaces_tnua_handle_make_replaces (nua_handle_t *nh, su_home_t *home, int early_only)
 Generate a Replaces header for handle.
nua_handle_tnua_handle_by_replaces (nua_t *nua, sip_replaces_t const *r)
 Obtain a new reference to an existing handle based on Replaces header.

Variables

char const nua_version []
 NUA module version.
char const NUA_DEBUG []
 Environment variable determining the debug log level for nua module.
su_log_t nua_log []
 Debug log for nua module.

Function Documentation

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

Acknowledge a succesfull response to INVITE request.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>
Events:
nua_i_media_error
nua_i_state (nua_i_active, nua_i_terminated)
See also:
NUTAG_AUTOACK(), NUA Call Model, nua_i_state

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

Authenticate an operation.

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

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

Authorize a subscriber.

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NEATAG_SUB()
NUTAG_SUBSTATE()
Events:
nua_i_subscription
See also:
nua_notifier(), nua_terminate()

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

Hangdown a call.

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

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

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

Cancel an INVITE operation.

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
Tags in <sip_tag.h>
Events:
nua_r_cancel, nua_i_state (nua_i_active, nua_i_terminated)
See also:
NUA Call Model, nua_invite(), nua_i_cancel

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

Send a chat message.

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

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

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

Create a NUA agent.

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

Parameters:
root Pointer to a root object
callback Pointer to event callback function
magic Pointer to callback context
tag, value, ... List of tagged parameters
Return values:
!=NULL a pointer to a nua stack object
NULL upon an error
Related tags:
NUTAG_PROXY()
NUTAG_URL()
NUTAG_SIPS_URL()
NUTAG_SIP_PARSER()
NUTAG_UICC()
NUTAG_CERTIFICATE_DIR()
and all tags listed in nua_set_params(),
and all relevant NTATAG_* are passed to NTA
and all tport tags listed in <sofia-sip/tport_tag.h>
Note:
From the 1.12.2 all the nua_set_params() tags are processed. Previously all nutags except NUTAG_SOA_NAME() and NUTAG_MEDIA_ENABLE() were ignored.

Both the NUTAG_URL() and NUTAG_SIPS_URL() are used to pass arguments to nta_agent_add_tport().

Events:
none
See also:
nua_shutdown(), nua_destroy(), nua_handle()

msg_t* nua_current_request ( nua_t const *  nua  ) 

Get current request message.

Since:
New in 1.12.4.

nua_handle_t* nua_default ( nua_t nua  ) 

Obtain default operation handle of the NUA stack object.

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

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

void nua_destroy ( nua_t nua  ) 

Destroy the NUA stack.

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

Parameters:
nua Pointer to nua stack object
Returns:
nothing
Related tags:
none
Events:
none
See also:
nua_shutdown(), nua_create(), nua_handle_destroy(), nua_handle_unref()

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

Get handle parameters.

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

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

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

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

Get NUA parameters.

The values of NUA parameters is returned in nua_r_get_params event.

Parameters:
nua Pointer to NUA stack object
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
TAG_ANY()
otherwise same tags as nua_set_params()
Events:
nua_r_get_params
Examples
Find out default values of all parameters:

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

Create an operation handle.

Allocates a new operation handle and associated storage.

Parameters:
nua Pointer to nua stack object
hmagic Pointer to callback context
tag,value,... List of tagged parameters
Return values:
!=NULL Pointer to operation handle
NULL Creation failed
Related tags:
Duplicates the provided tags for use with every operation. Note that NUTAG_URL() is converted to SIPTAG_TO() if there is no SIPTAG_TO(). And also vice versa, request-URI is taken from SIPTAG_TO() if there is no NUTAG_URL(). Note that certain SIP headers cannot be saved with the handle. They include Content-Length, CSeq, RSeq, RAck, and Timestamp.
nua_handle() accepts all the tags accepted by nua_set_hparams(), too.
Events:
none
See also:
nua_handle_bind(), nua_handle_destroy(), nua_handle_ref(), nua_handle_unref().

void nua_handle_bind ( nua_handle_t nh,
nua_hmagic_t hmagic 
)

Bind a callback context to an operation handle.

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

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

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

Since:
New in 1.12.4.
Note:
You should release the reference with nua_handle_unref() when you are done with the handle.
See also:
nua_handle_make_replaces(), Replaces, RFC 3891, nua_refer(), nua_i_refer, Refer-To, nta_leg_by_replaces()

void nua_handle_destroy ( nua_handle_t nh  ) 

Destroy a handle.

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

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

Parameters:
nh Pointer to operation handle
Returns:
nothing
Related Tags:
none
Events:
none
See also:
nua_handle(), nua_handle_bind(), nua_handle_ref(), nua_handle_unref(), nua_unregister(), nua_unpublish(), nua_unsubscribe(), nua_bye().

int nua_handle_has_active_call ( nua_handle_t const *  nh  ) 

Check if operation handle has an active call.

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

int nua_handle_has_call_on_hold ( nua_handle_t const *  nh  ) 

Check if operation handle has a call on hold.

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

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

int nua_handle_has_events ( nua_handle_t const *  nh  ) 

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

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

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

int nua_handle_has_invite ( nua_handle_t const *  nh  ) 

Check if operation handle is used for INVITE.

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

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

int nua_handle_has_register ( nua_handle_t const *  nh  ) 

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

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

int nua_handle_has_registrations ( nua_handle_t const *  nh  ) 

Check if operation handle has active registrations.

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

Parameters:
nh Pointer to operation handle
Return values:
0 no active registration in operation or operation handle is invalid
1 operation has registration
Related tags:
none
Events:
none
See also:
nua_register(), nua_unregister(), nua_r_register, nua_r_unregister

int nua_handle_has_subscribe ( nua_handle_t const *  nh  ) 

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

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

sip_to_t const* nua_handle_local ( nua_handle_t const *  nh  ) 

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

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

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

nua_hmagic_t* nua_handle_magic ( nua_handle_t nh  ) 

Fetch a callback context from an operation handle.

Parameters:
nh Pointer to operation handle
Returns:
Pointer to callback context
Related tags:
none
Events:
none
Since:
New in 1.12.4.

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

Generate a Replaces header for handle.

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

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

Parameters:
nh pointer to operation handle
home memory home used to allocate the header
early_only if true, include "early-only" parameter in Replaces, too
Returns:
A newly created Replaces header.
Since:
New in 1.12.4.
See also:
nua_handle_by_replaces(), Replaces, RFC 3891, RFC 3515, nua_refer(), nua_i_refer(), Refer-To, nta_leg_make_replaces(), sip_headers_as_url_query()

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

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

Send an INFO request.

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

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

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

Place a call using SIP INVITE method.

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

Optionally

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
Tags of nua_set_hparams()
NUTAG_INCLUDE_EXTRA_SDP()
SOATAG_HOLD(), SOATAG_AF(), SOATAG_ADDRESS(), SOATAG_RTP_SELECT(), SOATAG_RTP_SORT(), SOATAG_RTP_MISMATCH(), SOATAG_AUDIO_AUX(),
SOATAG_USER_SDP() or SOATAG_USER_SDP_STR()
See use of tags in <sip_tag.h> below
Events:
nua_r_invite
nua_i_state (nua_i_active, nua_i_terminated)
nua_i_media_error
nua_i_fork
Populating SIP Request Message with Tagged Arguments
The tagged arguments can be used to pass values for any SIP headers to the stack. When the INVITE message (or any other SIP message) is created, the tagged values saved with nua_handle() are used first, next the tagged values given with the operation (nua_invite()) are added.
When multiple tags for the same header are specified, the behaviour depends on the header type. If only a single header field can be included in a SIP message, the latest non-NULL value is used, e.g., Subject. However, if the SIP header can consist of multiple lines or header fields separated by comma, e.g., Accept, all the tagged values are concatenated.
However, if a tag value is SIP_NONE (-1 casted as a void pointer), the values from previous tags are ignored.
Next, values previously set with nua_set_params() or nua_set_hparams() are used: Allow, Supported, Organization, and User-Agent headers are added to the request if they are not already set.
Now, the target URI for the request needs to be determined.
For initial INVITE requests, values from tags are used. If NUTAG_URL() is given, it is used as target URI. Otherwise, if SIPTAG_TO() is given, it is used as target URI. If neither is given, the complete request line already specified using SIPTAG_REQUEST() or SIPTAG_REQUEST_STR() is used. If none of the tags above are given, an internal error is returned to the application. At this point, the target URI is stored in the request line, together with method name ("INVITE") and protocol version ("SIP/2.0"). The initial dialog information is also created: Call-ID, CSeq headers are generated, if they do not exist, and tag is added to From header.
For in-dialog INVITE (re-INVITE), the request URI is taken from the Contact header received from the remote party during the dialog establishment. Also, the Call-ID and CSeq headers and From and To tags are generated based on the dialog information and added to the request. If the dialog has a route (set by Record-Route headers), it is added to the request, too.
Max-Forwards header (with default value set by NTATAG_MAX_FORWARDS()) is also added now, if it does not exist.
Next, the stack generates a Contact header for the request (Unless the application already gave a Contact header or it does not want to use Contact and indicates that by including SIPTAG_CONTACT(NULL) or SIPTAG_CONTACT(SIP_NONE) in the tagged parameters.) If the application has registered the URI in From header, the Contact header used with registration is used. Otherwise, the Contact header is generated from the local IP address and port number.
For the initial INVITE requests, Service-Route set received from the registrar is also added to the request message.
The INVITE request message created by nua_invite() operation is saved as a template for automatic re-INVITE requests sent by the session timer ("timer") feature (see NUTAG_SESSION_TIMER() for more details). Please note that the template message is not used when ACK, PRACK, UPDATE or INFO requests are created (however, these requests will include dialog-specific headers like To, From, and Call-ID as well as preference headers Allow, Supported, User-Agent, Organization).
SDP Handling
The initial nua_invite() creates a soa media session unless NUTAG_MEDIA_ENABLE(0) has been given. The SDP description of the soa media session is included in the INVITE request as message body.
The SDP in a 1XX or 2XX response message is interpreted as an answer, given to the soa media session object for processing.
Bug:
If the INVITE request already contains a message body, SDP is not added. Also, if the response contains a multipart body, it is not parsed.
Authentication
The INVITE request may need authentication. Each proxy or server requiring authentication can respond with 401 or 407 response. The nua_authenticate() operation stores authentication information (username and password) to the handle, and stack tries to authenticate all the rest of the requests (e.g., PRACK, ACK, UPDATE, re-INVITE, BYE) using same username and password.
See also:
NUA Call Model, nua_r_invite, nua_i_state,
nua_handle_has_active_call()
nua_handle_has_call_on_hold()
nua_handle_has_invite()
nua_authenticate()
nua_prack()
nua_update()
nua_info()
nua_cancel()
nua_bye()
nua_i_invite, nua_respond()

nua_magic_t* nua_magic ( nua_t nua  ) 

Fetch callback context from nua.

Parameters:
nua Pointer to nua stack object
Returns:
Callback context pointer.
Since:
New in 1.12.4.

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

Create an event server.

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

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

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

Send a NOTIFY message.

This function is used when the application implements itself the notifier. The application must provide valid Subscription-State and Event headers using SIP tags. If there is no Subscription-State header, the subscription state can be modified with NUTAG_SUBSTATE().

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

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

Query capabilities from server.

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

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

Acknowledge a reliable preliminary response to INVITE request.

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

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

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

Send PUBLISH request to publication server.

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
Tags of nua_set_hparams()
Tags in <sip_tag.h>
Events:
nua_r_publish
See also:
nua_r_publish, RFC 3903, SIP-If-Match, nua_unpublish(), nua_r_unpublish, nua_i_publish

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

Send SIP REGISTER request to the registrar.

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(), NUTAG_M_USERNAME(), NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),
Events:
nua_r_register, nua_i_outbound
Generating Contact Header
If the application did not specify the Contact header in the tags, nua_register() will generate one. It will obtain the schema, IP address for the host and port number for the Contact URI from the transport socket. The diplay name is taken from NUTAG_M_DISPLAY(), URL username part is taken from NUTAG_M_USERNAME(), URI parameters from NUTAG_M_PARAMS(), and Contact header parameters from NUTAG_M_FEATURES(). If NUTAG_CALLEE_CAPS(1) is specified, additional Contact header parameters are generated based on SDP capabilities and SIP Allow header.

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

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

For instance, if application uses tags like

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

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

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

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

See also:
NUTAG_M_DISPLAY(), NUTAG_M_USERNAME(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(), NUTAG_CALLEE_CAPS().
NAT, Firewall and Outbound Support
Normally, nua will start start a protocol engine for outbound connections used for NAT and firewall traversal and connectivity checks when registering.

Note:
If the application provides nua with a Contact header of its own (or includes a SIPTAG_CONTACT(NULL) tag in nua_register() tags), the outbound protocol engine is not started. It is assumed that the application knows better what it is doing when it sets the Contact, or it is using experimental CPL upload as specified in draft-lennox-sip-reg-payload-01.txt.
First, outbound engine will probe for NATs in between UA and registrar. It will send a REGISTER request as usual. Upon receiving the response it checks for the presence of "received" and "rport" parameters in the Via header returned by registrar. The presence of NAT is determined from the "received" parameter in a Via header. When a REGISTER request was sent, the stack inserted the actual source IP address in the Via header: if that is different from the source IP address seen by the registrar, the registrar inserts the source IP address it sees into the "received" parameter.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Respond to a request with given status code and phrase.

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

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

Parameters:
nh Pointer to operation handle
status SIP response status code (see RFCs of SIP)
phrase free text (default response phrase is used if NULL)
tag,value,... List of tagged parameters
Returns:
nothing
Responses by Protocol Engine
When nua protocol engine receives an incoming SIP request, it can either respond to the request automatically or let application to respond to the request. The automatic response is returned to the client if the request fails syntax check, or the method, SIP extension or content negotiation fails.

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

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

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

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

Related Tags:
NUTAG_WITH(), NUTAG_WITH_THIS(), NUTAG_WITH_SAVED()
NUTAG_EARLY_ANSWER()
SOATAG_ADDRESS()
SOATAG_AF()
SOATAG_HOLD()
Tags used with nua_set_hparams()
Tags in <sip_tag.h>.
Events:
nua_i_state
nua_i_media_error
nua_i_error
nua_i_active
nua_i_terminated
See also:
nua_i_invite, nua_i_register, nua_i_subscribe, nua_i_publish

msg_t* nua_saved_event_request ( nua_saved_event_t const *  saved  ) 

Get request message from saved nua event.

Since:
New in 1.12.4.

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

Set handle parameters.

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

Parameters:
nh Pointer to a NUA handle
tag,value,... List of tagged parameters
Returns:
nothing
Tags Used to Set Handle-Specific Parameters:
NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and SIPTAG_ALLOW_EVENTS_STR()
NUTAG_AUTH_CACHE()
NUTAG_AUTOACK()
NUTAG_AUTOALERT()
NUTAG_AUTOANSWER()
NUTAG_CALLEE_CAPS()
NUTAG_EARLY_ANSWER()
NUTAG_EARLY_MEDIA()
NUTAG_ENABLEINVITE()
NUTAG_ENABLEMESSAGE()
NUTAG_ENABLEMESSENGER()
NUTAG_INSTANCE()
NUTAG_INVITE_TIMER()
NUTAG_KEEPALIVE()
NUTAG_KEEPALIVE_STREAM()
NUTAG_MAX_SUBSCRIPTIONS()
NUTAG_MEDIA_ENABLE()
NUTAG_MEDIA_FEATURES()
NUTAG_MIN_SE()
NUTAG_M_DISPLAY()
NUTAG_M_FEATURES()
NUTAG_M_PARAMS()
NUTAG_M_USERNAME()
NUTAG_ONLY183_100REL()
NUTAG_OUTBOUND()
NUTAG_PATH_ENABLE()
NUTAG_REFER_EXPIRES()
NUTAG_REFER_WITH_ID()
NUTAG_REGISTRAR()
NUTAG_RETRY_COUNT()
NUTAG_SERVICE_ROUTE_ENABLE()
NUTAG_SESSION_REFRESHER()
NUTAG_SESSION_TIMER()
NUTAG_SOA_NAME()
NUTAG_SUBSTATE()
NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR()
NUTAG_UPDATE_REFRESH()
NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR()
SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR()
Any soa tags are also considered as handle-specific parameters. They are defined in <sofia-sip/soa_tag.h>.
The global parameters that can not be set by nua_set_hparams() include NUTAG_DETECT_NETWORK_UPDATES(), NUTAG_SMIME_* tags, and all NTA tags.

Events:
nua_r_set_params

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

Set NUA parameters.

Parameters:
nua Pointer to NUA stack object
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR()
NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and SIPTAG_ALLOW_EVENTS_STR()
NUTAG_AUTOACK()
NUTAG_AUTOALERT()
NUTAG_AUTOANSWER()
NUTAG_CALLEE_CAPS()
NUTAG_DETECT_NETWORK_UPDATES()
NUTAG_EARLY_ANSWER()
NUTAG_EARLY_MEDIA()
NUTAG_ENABLEINVITE()
NUTAG_ENABLEMESSAGE()
NUTAG_ENABLEMESSENGER()
NUTAG_INSTANCE()
NUTAG_INVITE_TIMER()
NUTAG_KEEPALIVE()
NUTAG_KEEPALIVE_STREAM()
NUTAG_MAX_SUBSCRIPTIONS()
NUTAG_MEDIA_ENABLE()
NUTAG_MEDIA_FEATURES()
NUTAG_MIN_SE()
NUTAG_M_DISPLAY()
NUTAG_M_FEATURES()
NUTAG_M_PARAMS()
NUTAG_M_USERNAME()
NUTAG_ONLY183_100REL()
NUTAG_OUTBOUND()
NUTAG_PATH_ENABLE()
NUTAG_REFER_EXPIRES()
NUTAG_REFER_WITH_ID()
NUTAG_REGISTRAR()
NUTAG_RETRY_COUNT()
NUTAG_SERVICE_ROUTE_ENABLE()
NUTAG_SESSION_REFRESHER()
NUTAG_SESSION_TIMER()
NUTAG_SMIME_ENABLE()
NUTAG_SMIME_KEY_ENCRYPTION()
NUTAG_SMIME_MESSAGE_DIGEST()
NUTAG_SMIME_MESSAGE_ENCRYPTION()
NUTAG_SMIME_OPT()
NUTAG_SMIME_PROTECTION_MODE()
NUTAG_SMIME_SIGNATURE()
NUTAG_SOA_NAME()
NUTAG_SUBSTATE()
NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR()
NUTAG_UPDATE_REFRESH()
NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR()
SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR()
nua_set_params() also accepts any soa tags, defined in <sofia-sip/soa_tag.h>, and nta tags, defined in <sofia-sip/nta_tag.h>.

Events:
nua_r_set_params
SIP Header as NUA Parameters
The nua parameters include SIP headers Allow, Supported, Organization, User-Agent and From. They are included in most of the SIP messages sent by nua. They are set in the same way as the tagged arguments are used to populate a SIP message.
When multiple tags for the same header are specified, the behaviour depends on the header type. If only a single header field can be included in a SIP message, the latest non-NULL value is used, e.g., Organization. However, if the SIP header can consist of multiple lines or header fields separated by comma, in this case, Allow and Supported, all the tagged values are concatenated.
However, if the tag value is SIP_NONE (-1 casted as a void pointer), the values from previous tags are ignored.
For example, the nua_set_params() call like this: will leave Allow and Organization headers empty. The User-Agent header will contain value "tester/1.0".
 nua_set_params(nua,
                SIPTAG_ORGANIZATION_STR("Malevolent Microwavers"),
                SIPTAG_ALLOW_STR("OPTIONS"),
                SIPTAG_ALLOW(SIP_NONE),
                SIPTAG_ORGANIZATION_STR("The Phone Company"),
                SIPTAG_ALLOW_STR("SUBSCRIBE"),
                SIPTAG_ALLOW(NULL),
                SIPTAG_ORGANIZATION_STR(NULL),
                TAG_END());
sets the header Allow with value SUBSCRIBE and the header Organization will have value The Phone Company.

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

Terminate an event server.

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

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

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

Send un-PUBLISH request to publication server.

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

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
NUTAG_URL()
SIPTAG_IF_MATCH(), SIPTAG_IF_MATCH_STR()
SIPTAG_EVENT(), SIPTAG_EVENT_STR()
Tags of nua_set_hparams()
Tags in <sip_tag.h>
Events:
nua_r_unpublish
See also:
nua_r_unpublish, RFC 3903, SIP-If-Match, nua_i_publish, nua_publish(), nua_r_publish

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

Unregister.

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related tags:
NUTAG_REGISTRAR()
Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
Events:
nua_r_unregister
See also:
nua_register(), nua_r_register, nua_handle_destroy(), nua_shutdown(), nua_i_register, Expires, Contact, Call-ID, CSeq, RFC 3261 section 10, Path, RFC 3327, Service-Route, RFC 3608, RFC 3680, NUTAG_REGISTRAR(), NUTAG_INSTANCE(), NUTAG_OUTBOUND(), NUTAG_KEEPALIVE(), NUTAG_KEEPALIVE_STREAM(), SIPTAG_CONTACT(), SIPTAG_CONTACT_STR(), NUTAG_M_USERNAME(), NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),

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

Update a call.

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

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

Parameters:
nh Pointer to operation handle
tag,value,... List of tagged parameters
Returns:
nothing
Related Tags:
same as nua_invite()
Events:
nua_r_update
nua_i_state (nua_i_active, nua_i_terminated)
nua_i_media_error
See also:
NUA Call Model, RFC 3311, nua_update(), nua_i_update


Variable Documentation

char const NUA_DEBUG[]

Environment variable determining the debug log level for nua module.

The NUA_DEBUG environment variable is used to determine the debug logging level for nua module. The default level is 3.

See also:
<sofia-sip/su_debug.h>, nua_log, SOFIA_DEBUG

su_log_t nua_log[]

Debug log for nua module.

The nua_log is the log object used by nua module. The level of nua_log is set using NUA_DEBUG environment variable.


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