#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_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. | |
void | nua_shutdown (nua_t *nua) |
Shutdown NUA stack. | |
void | nua_destroy (nua_t *nua) |
Destroy the NUA stack. | |
nua_magic_t * | nua_magic (nua_t *nua) |
Fetch callback context from nua. | |
nua_handle_t * | nua_default (nua_t *nua) |
Obtain default operation handle of the NUA stack object. | |
nua_handle_t * | nua_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_t * | nua_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_t * | nua_current_request (nua_t const *nua) |
Get current request message. | |
msg_t * | nua_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_t * | nua_handle_make_replaces (nua_handle_t *nh, su_home_t *home, int early_only) |
Generate a Replaces header for handle. | |
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. | |
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. |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
void nua_authenticate | ( | nua_handle_t * | nh, | |
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Authenticate an operation.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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).
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
void nua_cancel | ( | nua_handle_t * | nh, | |
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Cancel an INVITE operation.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
root | Pointer to a root object | |
callback | Pointer to event callback function | |
magic | Pointer to callback context | |
tag,value,... | List of tagged parameters |
!=NULL | a pointer to a nua stack object | |
NULL | upon an error |
Both the NUTAG_URL() and NUTAG_SIPS_URL() are used to pass arguments to nta_agent_add_tport().
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.
nua | Pointer to nua stack object |
!=NULL | Pointer to nua operation handle | |
NULL | No default operation exists |
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.
nua | Pointer to nua stack object |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
nua_get_hparams(nua_default(nua), TAG_ANY())
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.
nua | Pointer to NUA stack object | |
tag,value,... | List of tagged parameters |
nua_get_params(nua, TAG_ANY(), TAG_END());
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.
nua | Pointer to nua stack object | |
hmagic | Pointer to callback context | |
tag,value,... | List of tagged parameters |
!=NULL | Pointer to operation handle | |
NULL | Creation failed |
void nua_handle_bind | ( | nua_handle_t * | nh, | |
nua_hmagic_t * | hmagic | |||
) |
Bind a callback context to an operation handle.
nh | Pointer to operation handle | |
hmagic | Pointer to callback context |
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.
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.
nh | Pointer to operation handle |
int nua_handle_has_active_call | ( | nua_handle_t const * | nh | ) |
Check if operation handle has an active call.
nh | Pointer to operation handle |
0 | no active call in operation or operation handle is invalid | |
1 | operation has established call or pending call request. |
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.
nh | Pointer to operation handle |
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. |
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.
nh | Pointer to operation handle |
0 | no event subscriptions in operation or operation handle is invalid | |
!=0 | operation has event subscriptions |
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.
nh | Pointer to operation handle |
0 | no invite in operation or operation handle is invalid | |
1 | operation has invite |
int nua_handle_has_register | ( | nua_handle_t const * | nh | ) |
Check if operation handle has been used with nua_register() or nua_unregister().
nh | Pointer to operation handle |
0 | no active register in operation or operation handle is invalid | |
1 | operation has been used with nua_register() or nua-unregister() |
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.
nh | Pointer to operation handle |
0 | no active registration in operation or operation handle is invalid | |
1 | operation has registration |
int nua_handle_has_subscribe | ( | nua_handle_t const * | nh | ) |
Check if operation handle has been used with outgoing SUBSCRIBE of REFER request.
nh | Pointer to operation handle |
0 | no active subscription in operation or operation handle is invalid | |
1 | operation has subscription. |
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.
nh | Pointer to operation handle |
NULL | no local address for operation or operation handle invalid | |
!=NULL | pointer to local address for operation |
nua_hmagic_t* nua_handle_magic | ( | nua_handle_t * | nh | ) |
Fetch a callback context from an operation handle.
nh | Pointer to operation handle |
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.
nh | pointer to operation handle | |
home | memory home used to allocate the header | |
early_only | if true, include "early-only" parameter in Replaces, too |
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.
nh | Pointer to operation handle |
NULL | no remote address for operation or operation handle invalid | |
!=NULL | pointer to remote address for operation |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
nua_magic_t* nua_magic | ( | nua_t * | nua | ) |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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().
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
void nua_options | ( | nua_handle_t * | nh, | |
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Query capabilities from server.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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_register(nh, NUTAG_M_DISPLAY("1"), NUTAG_M_USERNAME("line-1"), NUTAG_M_PARAMS("user=phone"), NUTAG_M_FEATURES("audio"), NUTAG_CALLEE_CAPS(0), TAG_END())
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
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.
The nua_r_register message will include the contact header and route used in with the registration.
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()).
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.
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 |
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.
msg_t* nua_saved_event_request | ( | nua_saved_event_t const * | saved | ) |
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().
nh | Pointer to a NUA handle | |
tag,value,... | List of tagged parameters |
void nua_set_params | ( | nua_t * | nua, | |
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Set NUA parameters.
nua | Pointer to NUA stack object | |
tag,value,... | List of tagged parameters |
nua_set_params(nua, SIPTAG_USER_AGENT_STR("tester/1.0"), SIPTAG_ALLOW_STR("INVITE,CANCEL,BYE,ACK"), SIPTAG_ORGANIZATION(NULL), SIPTAG_USER_AGENT(NULL), SIPTAG_ALLOW(SIP_NONE), TAG_END());
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());
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.
nh | Pointer to operation handle | |
tag,value,... | List of tagged parameters |
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.