Sofia-SIP User Agent Library API. More...
#include <sofia-sip/su_wait.h>#include <sofia-sip/url.h>#include <sofia-sip/sip.h>#include <sofia-sip/nua_tag.h>
Defines | |
| #define | NUA_H |
| Defined when <sofia-sip/nua.h> has been included. | |
| #define | NUA_VERSION |
| NUA API version. | |
| #define | nua_handle_home(nh) |
| Cast a nua_handle_t pointer to a su_home_t. | |
Typedefs | |
| typedef NUA_MAGIC_T | nua_magic_t |
| Application context for NUA agent. | |
| typedef NUA_HMAGIC_T | nua_hmagic_t |
| Application context for NUA handle. | |
| typedef enum nua_nw_detector_e | nua_nw_detector_t |
| Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES(). | |
| typedef enum nua_event_e | nua_event_t |
| Events. | |
| typedef void(* | nua_callback_f )(nua_event_t event, int status, char const *phrase, nua_t *nua, nua_magic_t *magic, nua_handle_t *nh, nua_hmagic_t *hmagic, sip_t const *sip, tagi_t tags[]) |
| Typedef of NUA event callback. | |
| typedef NUA_SAVED_EVENT_T | nua_saved_event_t |
| Abstract type for saved nua events. | |
Enumerations | |
| enum | nua_nw_detector_e |
Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES(). More... | |
| enum | nua_event_e { , 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, nua_r_authenticate , nua_i_network_changed, nua_i_register } |
Events. More... | |
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. | |
| void | nua_set_params (nua_t *, tag_type_t, tag_value_t,...) |
| Set NUA parameters. | |
| void | nua_get_params (nua_t *nua, tag_type_t, tag_value_t,...) |
| Get NUA parameters. | |
| nua_handle_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_value_t,...) |
| Create an operation handle. | |
| void | nua_handle_destroy (nua_handle_t *h) |
| Destroy a handle. | |
| nua_handle_t * | nua_handle_ref (nua_handle_t *) |
| Make a new reference to handle. | |
| int | nua_handle_unref (nua_handle_t *) |
| Destroy reference to handle. | |
| void | nua_handle_bind (nua_handle_t *nh, nua_hmagic_t *magic) |
| Bind a callback context to an operation handle. | |
| nua_hmagic_t * | nua_handle_magic (nua_handle_t *nh) |
| Fetch a callback context from an operation handle. | |
| void | nua_set_hparams (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Set handle parameters. | |
| void | nua_get_hparams (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Get handle parameters. | |
| int | nua_handle_has_invite (nua_handle_t const *nh) |
| Check if operation handle is used for INVITE. | |
| int | nua_handle_has_subscribe (nua_handle_t const *nh) |
| Check if operation handle has been used with outgoing SUBSCRIBE of REFER request. | |
| int | nua_handle_has_register (nua_handle_t const *nh) |
| Check if operation handle has been used with nua_register() or nua_unregister(). | |
| int | nua_handle_has_active_call (nua_handle_t const *nh) |
| Check if operation handle has an active call. | |
| int | nua_handle_has_call_on_hold (nua_handle_t const *nh) |
| Check if operation handle has a call on hold. | |
| int | nua_handle_has_events (nua_handle_t const *nh) |
| Check if handle has active event subscriptions (refers sent). | |
| int | nua_handle_has_registrations (nua_handle_t const *nh) |
| Check if operation handle has active registrations. | |
| sip_to_t const * | nua_handle_remote (nua_handle_t const *nh) |
| Get the remote address (From/To header) of operation handle. | |
| sip_to_t const * | nua_handle_local (nua_handle_t const *nh) |
| Get the local address (From/To header) of operation handle. | |
| char const * | nua_event_name (nua_event_t event) |
| Get name for NUA event. | |
| char const * | nua_callstate_name (enum nua_callstate state) |
| Get name for NUA callstate. | |
| char const * | nua_substate_name (enum nua_substate substate) |
| Return name of subscription state. | |
| enum nua_substate | nua_substate_make (char const *sip_substate) |
| Convert string to enum nua_substate. | |
| void | nua_register (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Send SIP REGISTER request to the registrar. | |
| void | nua_unregister (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Unregister. | |
| void | nua_invite (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Place a call using SIP INVITE method. | |
| void | nua_ack (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Acknowledge a succesfull response to INVITE request. | |
| void | nua_prack (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Acknowledge a reliable preliminary response to INVITE request. | |
| void | nua_options (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Query capabilities from server. | |
| void | nua_publish (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Send PUBLISH request to publication server. | |
| void | nua_unpublish (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Send un-PUBLISH request to publication server. | |
| void | nua_message (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Send an instant message. | |
| void | nua_chat (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Send a chat message. | |
| void | nua_info (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Send an INFO request. | |
| void | nua_subscribe (nua_handle_t *nh, tag_type_t, tag_value_t,...) |
| Subscribe a SIP event. | |
| void | nua_unsubscribe (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Unsubscribe an event. | |
| void | nua_notify (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Send a NOTIFY message. | |
| void | nua_notifier (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Create an event server. | |
| void | nua_terminate (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Terminate an event server. | |
| void | nua_refer (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Transfer a call. | |
| void | nua_update (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Update a call. | |
| void | nua_bye (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Hangdown a call. | |
| void | nua_cancel (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Cancel an INVITE operation. | |
| void | nua_authenticate (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Authenticate an operation. | |
| void | nua_authorize (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Authorize a subscriber. | |
| void | nua_method (nua_handle_t *, tag_type_t, tag_value_t,...) |
| Send a request message with an extension method. | |
| void | nua_respond (nua_handle_t *nh, int status, char const *phrase, tag_type_t, tag_value_t,...) |
| Respond to a request with given status code and phrase. | |
| int | nua_event_is_incoming_request (nua_event_t e) |
| Check if event can be responded with nua_respond(). | |
| char const * | nua_generate_instance_identifier (su_home_t *) |
| Generate an instance identifier. | |
| int | nua_save_event (nua_t *nua, nua_saved_event_t return_saved[1]) |
| Save last nua event. | |
| nua_event_data_t const * | nua_event_data (nua_saved_event_t const saved[1]) |
| Get information from saved event. | |
| void | nua_destroy_event (nua_saved_event_t *saved) |
| Destroy a save nua event. | |
| msg_t * | nua_saved_event_request (nua_saved_event_t const *saved) |
| Get request message from saved nua event. | |
| msg_t * | nua_current_request (nua_t const *nua) |
| Get current request message. | |
| sip_replaces_t * | nua_handle_make_replaces (nua_handle_t *nh, su_home_t *home, int early_only) |
| Generate a Replaces header for handle. | |
| nua_handle_t * | nua_handle_by_replaces (nua_t *nua, sip_replaces_t const *rp) |
| Obtain a new reference to an existing handle based on Replaces header. | |
| nua_handle_t * | nua_handle_by_call_id (nua_t *nua, const char *call_id) |
| Obtain a new reference to an existing handle based on Call-ID. | |
Variables | |
| char const | nua_version [] |
| NUA module version. | |
Sofia-SIP User Agent Library API.
| #define NUA_H |
Defined when <sofia-sip/nua.h> has been included.
| #define nua_handle_home | ( | nh | ) |
Cast a nua_handle_t pointer to a su_home_t.
| typedef void(* nua_callback_f)(nua_event_t event, int status, char const *phrase, nua_t *nua, nua_magic_t *magic, nua_handle_t *nh, nua_hmagic_t *hmagic, sip_t const *sip, tagi_t tags[]) |
Typedef of NUA event callback.
| typedef NUA_HMAGIC_T nua_hmagic_t |
Application context for NUA handle.
| typedef NUA_MAGIC_T nua_magic_t |
Application context for NUA agent.
| typedef enum nua_nw_detector_e nua_nw_detector_t |
Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES().
| typedef NUA_SAVED_EVENT_T nua_saved_event_t |
Abstract type for saved nua events.
| 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[]);
| 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 | Headers in parsed incoming message. May be NULL. See also nua_current_request(). | |
| tags | Tag list containing more information about the state of NUA. May be empty. |
Note that the contents of the last four parameters vary depending on the event. The descriptions can be found from the description of the individual event.
The events can be divided into the following categories:
| nua_i_error |
Error indication. Will be sent when an internal error happened or an error occurred while responding a request.
| ||||||||||||||||||
| nua_i_invite |
Incoming call INVITE. Indication of incoming call or re-INVITE request.
If status in nua_i_invite event is below 200, the application should accept or reject the call with nua_respond(). See the NUA Call Model for the detailed explanation of various options in call processing at server end. The INVITE request takes care of session setup using SDP Offer-Answer negotiation as specified in RFC 3264 (updated in RFC 3262 section 5, RFC 3311, and RFC 3312). The Offer-Answer can be taken care by application (if NUTAG_MEDIA_ENABLE(0) parameter has been set) or by the built-in SDP Offer/Answer engine soa (by default and when NUTAG_MEDIA_ENABLE(1) parameter has been set). When soa is enabled, it will take care of parsing the SDP, negotiating the media and codecs, and including the SDP in the SIP message bodies as required by the Offer-Answer model. When soa is enabled, the SDP in the incoming INVITE is parsed and feed to a soa_session_t object. The nua_i_state event sent to the application immediately after nua_i_invite will contain the parsing results in SOATAG_REMOTE_SDP() and SOATAG_REMOTE_SDP_STR() tags. Note that currently the parser within nua does not handle MIME multipart. The SDP Offer/Answer engine can get confused if the SDP offer is included in a MIME multipart, therefore such an INVITE is rejected with 415 Unsupported Media Type error response: the client is expected to retry the INVITE without MIME multipart content. If the call is to be accepted, the application should include the SDP in the 2XX response. If soa is not disabled with NUTAG_MEDIA_ENABLE(0), the SDP should be included in the SOATAG_USER_SDP() or SOATAG_USER_SDP_STR() parameter given to nua_respond(). If it is disabled, the SDP should be included in the response message using SIPTAG_PAYLOAD() or SIPTAG_PAYLOAD_STR(). Also, the Content-Type should be set using SIPTAG_CONTENT_TYPE() or SIPTAG_CONTENT_TYPE_STR().
Call progress can be signaled with preliminary responses (with status code in the range 101..199). It is possible to conclude the SDP Offer-Answer negotiation using preliminary responses, too. If NUTAG_EARLY_ANSWER(1), SOATAG_USER_SDP() or SOATAG_USER_SDP_STR() parameter is included with in a preliminary nua_response(), the SDP answer is generated and sent with the preliminary responses, too. The preliminary responses are sent reliably if feature tag "100rel" is included in the Require header of the response or if NUTAG_EARLY_MEDIA(1) parameter has been given. The reliably delivery of preliminary responses mean that a sequence number is included in the RSeq header in the response message and the response message is resent until the client responds with a PRACK request with matching sequence number in RAck header. Note that only the "183" response is sent reliably if the NUTAG_ONLY183_100REL(1) parameter has been given. The reliable preliminary responses are acknowledged with PRACK request sent by the client. Note if the SDP offer-answer is completed with the reliable preliminary responses, the is no need to include SDP in 200 OK response (or other 2XX response). However, it the tag NUTAG_INCLUDE_EXTRA_SDP(1) is included with nua_respond(), a copy of the SDP answer generated earlier by soa is included as the message body.
When so called 2rd party call control is used, the initial INVITE may not contain SDP offer. In that case, the offer is sent by the recipient of the INVITE request (User-Agent Server, UAS). The SDP sent in 2XX response (or in a preliminary reliable response) is considered as an offer, and the answer will be included in the ACK request sent by the UAC (or PRACK in case of preliminary reliable response).
| ||||||||||||||||||
| nua_i_cancel |
Incoming INVITE has been cancelled. Incoming INVITE has been cancelled by the client.
| ||||||||||||||||||
| nua_i_ack |
Final response to INVITE has been ACKed. Final response to INVITE has been acknowledged by UAC with ACK.
| ||||||||||||||||||
| nua_i_fork |
Outgoing call has been forked. This is sent when an INVITE request is answered with multiple 2XX series responses.
| ||||||||||||||||||
| nua_i_active |
A call has been activated. This event will be sent after a succesful response to the initial INVITE has been received and the media has been activated.
| ||||||||||||||||||
| 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
| ||||||||||||||||||
| nua_i_state |
Call state has changed. This event will be sent whenever the call state changes. In addition to basic changes of session status indicated with enum nua_callstate, the RFC 3264 SDP Offer/Answer negotiation status is also included. The tags NUTAG_OFFER_RECV() or NUTAG_ANSWER_RECV() indicate whether the remote SDP that was received was considered as an offer or an answer. Tags NUTAG_OFFER_SENT() or NUTAG_ANSWER_SENT() indicate whether the local SDP which was sent was considered as an offer or answer. If the soa SDP negotiation is enabled (by default or with NUTAG_MEDIA_ENABLE(1)), the received remote SDP is included in tags SOATAG_REMOTE_SDP() and SOATAG_REMOTE_SDP_STR(). The SDP negotiation result from soa is included in the tags SOATAG_LOCAL_SDP() and SOATAG_LOCAL_SDP_STR(). SOATAG_ACTIVE_AUDIO() and SOATAG_ACTIVE_VIDEO() are informational tags used to indicate what is the status of audio or video. Note that nua_i_state also covers the information relayed in call establisment (nua_i_active) and termination (nua_i_terminated) events.
| ||||||||||||||||||
| nua_i_outbound |
Status from outbound processing. Status from outbound engine.
| ||||||||||||||||||
| nua_i_bye |
Incoming BYE call hangup. Incoming BYE request, call hangup.
| ||||||||||||||||||
| nua_i_options |
Incoming OPTIONS. Incoming OPTIONS request. The user-agent should respond to an OPTIONS request with the same statuscode as it would respond to an INVITE request. Stack responds automatically to OPTIONS request unless OPTIONS is included in the set of application methods, set by NUTAG_APPL_METHOD(). The OPTIONS request does not create a dialog. Currently the processing of incoming OPTIONS creates a new handle for each incoming request which is not assiciated with an existing dialog. If the handle nh is not bound, you should probably destroy it after responding to the OPTIONS request.
| ||||||||||||||||||
| nua_i_refer |
Incoming REFER call transfer. Incoming REFER request used to transfer calls. The tag list will contain tag NUTAG_REFER_EVENT() with the Event header constructed from the REFER request. It will also contain the SIPTAG_REFERRED_BY() tag with the Referred-By header containing the identity of the party sending the REFER. The Referred-By structure contained in the tag is constructed from the From header if the Referred-By header was not present in the REFER request. The application can let the nua to send NOTIFYs from the call it initiates with nua_invite() if it includes in the nua_invite() arguments both the NUTAG_NOTIFY_REFER() with the handle with which nua_i_refer was received and the NUTAG_REFER_EVENT() from nua_i_refer event tags.
| ||||||||||||||||||
| nua_i_publish |
Incoming PUBLISH. Incoming PUBLISH request. In order to receive nua_i_publish events, the application must enable both the PUBLISH method with NUTAG_ALLOW() tag and the acceptable SIP events with nua_set_params() tag NUTAG_ALLOW_EVENTS(). The nua_response() call responding to a PUBLISH request must have NUTAG_WITH() (or NUTAG_WITH_THIS()/NUTAG_WITH_SAVED()) tag. Note that a successful response to PUBLISH MUST include Expires and SIP-ETag headers. The PUBLISH request does not create a dialog. Currently the processing of incoming PUBLISH creates a new handle for each incoming request which is not assiciated with an existing dialog. If the handle nh is not bound, you should probably destroy it after responding to the PUBLISH request.
| ||||||||||||||||||
| nua_i_prack |
Incoming PRACK. Incoming PRACK request. PRACK request is used to acknowledge reliable preliminary responses and it is usually sent automatically by the nua stack.
| ||||||||||||||||||
| nua_i_info |
Incoming session INFO. Incoming session INFO request.
| ||||||||||||||||||
| nua_i_update |
Incoming session UPDATE. Incoming session UPDATE request.
| ||||||||||||||||||
| nua_i_message |
Incoming MESSAGE. Incoming MESSAGE request. The MESSAGE request does not create a dialog. If the incoming MESSAGE request is not assiciated with an existing dialog the stack creates a new handle for it. If the handle nh is not bound, you should probably destroy it after responding to the MESSAGE request.
| ||||||||||||||||||
| nua_i_chat |
Incoming chat MESSAGE. Incoming chat message.
| ||||||||||||||||||
| nua_i_subscribe |
Incoming SUBSCRIBE. Incoming SUBSCRIBE request. SUBSCRIBE request is used to query SIP event state or establish a SIP event subscription.
Initial SUBSCRIBE requests are dropped with 489 Bad Event response, unless the application has explicitly included the Event in the list of allowed events with nua_set_params() tag NUTAG_ALLOW_EVENTS() (or SIPTAG_ALLOW_EVENTS() or SIPTAG_ALLOW_EVENTS_STR()). If the event has been allowed the application can decide whether to accept the SUBSCRIBE request or reject it. The nua_response() call responding to a SUBSCRIBE request must have NUTAG_WITH() (or NUTAG_WITH_THIS()/NUTAG_WITH_SAVED()) tag. If the application accepts the SUBSCRIBE request, it must immediately send an initial NOTIFY establishing the dialog. This is because the response to the SUBSCRIBE request may be lost by an intermediate proxy because it had forked the SUBSCRIBE request. SUBSCRIBE requests modifying (usually refreshing or terminating) an existing event subscription are accepted by default and a 200 OK response along with a copy of previously sent NOTIFY is sent automatically to the subscriber. By default, only event subscriptions accepted are those created implicitly by REFER request. See nua_i_refer how the application must handle the REFER requests.
Accepting the SUBSCRIBE request creates a dialog with a notifier dialog usage on the handle. The dialog usage is active, until the subscriber terminates the subscription, it times out or the application terminates the usage with nua_notify() call containing the tag NUTAG_SUBSTATE(nua_substate_terminated) or Subscription-State header with state "terminated" and/or expiration time 0. When the subscriber terminates the subscription, the application is notified of an termination by a nua_i_subscribe event with NUTAG_SUBSTATE(nua_substate_terminated) tag. When the subscription times out, nua automatically initiates a NOTIFY transaction. When it is terminated, the application is sent a nua_r_notify event with NUTAG_SUBSTATE(nua_substate_terminated) tag.
| ||||||||||||||||||
| nua_i_subscription |
Incoming subscription to be authorized. This event is launched by nua_notifier() to inform application of the current state of the subscriber. The subscriber state is included in the NUTAG_SUBSTATE() tag. If the state is nua_substate_pending or nua_substate_embryonic, application should to authorize the subscriber with nua_authorize().
| ||||||||||||||||||
| nua_i_notify |
Incoming event NOTIFY. Event for incoming NOTIFY request.
| ||||||||||||||||||
| nua_i_method |
Incoming, unknown method. Incoming extension request. The extension request does not create a dialog. If the incoming request was not assiciated with an existing dialog the stack creates a new handle for it. If the handle nh is not bound, you should probably destroy it after responding to the request.
The extension method name is in sip->sip_request->rq_method_name, too.
| ||||||||||||||||||
| nua_i_media_error |
Offer-answer error indication. Media error indication. This may be sent after an SOA operation has failed while processing incoming or outgoing call.
| ||||||||||||||||||
| nua_r_set_params |
Answer to nua_set_params() or nua_get_hparams(). Response to nua_set_params() or nua_set_hparams().
| ||||||||||||||||||
| nua_r_get_params |
Answer to nua_get_params() or nua_get_hparams().
| ||||||||||||||||||
| nua_r_shutdown |
Answer to nua_shutdown(). Shutdown a nua stack. When the nua stack is shutdown, ongoing calls are released, registrations unregistered, publications un-PUBLISHed and subscriptions terminated. If the stack cannot terminate everything within 30 seconds, it sends the nua_r_shutdown event with status 500.
Answer to nua_shutdown(). Status codes
| ||||||||||||||||||
| nua_r_notifier |
Answer to nua_notifier(). Answer to nua_notitier().
| ||||||||||||||||||
| nua_r_terminate |
Answer to nua_terminate().
| ||||||||||||||||||
| nua_r_authorize |
Answer to nua_authorize(). | ||||||||||||||||||
| nua_r_register |
Answer to outgoing REGISTER. Response to an outgoing REGISTER. The REGISTER may be sent explicitly by nua_register() or implicitly by NUA state machines. When REGISTER request has been restarted the status may be 100 even while the real response status returned is different.
| ||||||||||||||||||
| nua_r_unregister |
Answer to outgoing un-REGISTER.
| ||||||||||||||||||
| nua_r_invite |
Answer to outgoing INVITE. | ||||||||||||||||||
| nua_r_cancel |
Answer to outgoing CANCEL. The CANCEL may be sent explicitly by nua_cancel() or implicitly by NUA state machine.
| ||||||||||||||||||
| nua_r_bye |
Answer to outgoing BYE. The BYE may be sent explicitly by nua_bye() or implicitly by NUA state machine.
| ||||||||||||||||||
| nua_r_options |
Answer to outgoing OPTIONS.
| ||||||||||||||||||
| nua_r_refer |
Answer to outgoing REFER. Response to outgoing REFER.
| ||||||||||||||||||
| nua_r_publish |
Answer to outgoing PUBLISH. Response to an outgoing PUBLISH. The PUBLISH request may be sent explicitly by nua_publish() or implicitly by NUA state machine.
| ||||||||||||||||||
| nua_r_unpublish |
Answer to outgoing un-PUBLISH. Response to an outgoing un-PUBLISH.
| ||||||||||||||||||
| nua_r_info |
Answer to outgoing INFO. Response to an outgoing INFO request.
| ||||||||||||||||||
| nua_r_prack |
Answer to outgoing PRACK. Response to an outgoing PRACK request. PRACK request is used to acknowledge reliable preliminary responses and it is usually sent automatically by the nua stack.
| ||||||||||||||||||
| nua_r_update |
Answer to outgoing UPDATE. The UPDATE may be sent explicitly by nua_update() or implicitly by NUA state machine.
| ||||||||||||||||||
| nua_r_message |
Answer to outgoing MESSAGE. Response to an outgoing MESSAGE request.
| ||||||||||||||||||
| nua_r_chat |
Answer to outgoing chat message.
| ||||||||||||||||||
| nua_r_subscribe |
Answer to outgoing SUBSCRIBE. Response to an outgoing SUBSCRIBE request. The SUBSCRIBE request may have been sent explicitly by nua_subscribe() or implicitly by NUA state machine.
| ||||||||||||||||||
| nua_r_unsubscribe |
Answer to outgoing un-SUBSCRIBE. Response to an outgoing un-SUBSCRIBE.
| ||||||||||||||||||
| nua_r_notify |
Answer to outgoing NOTIFY. Response to an outgoing NOTIFY request. The NOTIFY may be sent explicitly by nua_notify() or implicitly by NUA state machine. Implicit NOTIFY is sent when an established dialog is refreshed by client or it is terminated (either by client or because of a timeout). The current subscription state is included in NUTAG_SUBSTATE() tag. The nua_substate_terminated indicates that the subscription is terminated, the notifier usage has been removed and when there was no other usages of the dialog the dialog state is also removed.
| ||||||||||||||||||
| nua_r_method |
Answer to unknown outgoing method. Response to an outgoing extension request.
| ||||||||||||||||||
| nua_r_authenticate |
Answer to nua_authenticate(). Response to nua_authenticate(). Under normal operation, this event is never sent but rather the unauthenticated operation is completed. However, if there is no operation to authentication or if there is an authentication error the nua_r_authenticate event is sent to the application with the status code as follows:
| ||||||||||||||||||
| nua_i_network_changed |
Local IP(v6) address has changed.
| ||||||||||||||||||
| nua_i_register |
Incoming REGISTER. Incoming REGISTER request.
In order to receive nua_i_register events, the application must enable the REGISTER method with NUTAG_ALLOW() tag, e.g.,
* nua_set_params(nua;
* NUTAG_APPL_METHOD("REGISTER"),
* NUTAG_ALLOW("REGISTER"),
* TAG_END());
* The nua_response() call responding to a REGISTER request must include NUTAG_WITH() (or NUTAG_WITH_THIS()/NUTAG_WITH_SAVED()) tag. Note that a successful response to REGISTER MUST include the Contact header bound to the the AoR URI (in To header). The REGISTER request does not create a dialog. Currently the processing of incoming REGISTER creates a new handle for each incoming request which is not assiciated with an existing dialog. If the handle nh is not bound, you should probably destroy it after responding to the REGISTER request.
|
| enum nua_nw_detector_e |
Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES().
| void nua_ack | ( | nua_handle_t * | nh, | |
| tag_type_t | tag, | |||
| tag_value_t | value, | |||
| ... | ||||
| ) |
Acknowledge a succesfull response to INVITE request.
Acknowledge a succesful response to INVITE request.
Acknowledge a successful response (200..299) to INVITE request with the SIP ACK request message. This function is needed only if NUTAG_AUTOACK() parameter has been cleared.
| 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 |
| char const* nua_callstate_name | ( | enum nua_callstate | state | ) |
Get name for NUA callstate.
Get name for NUA callstate.
| 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.
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 |
Get current request message.
| nua_handle_t* nua_default | ( | nua_t * | nua | ) |
Obtain default operation handle of the NUA stack object.
Obtain default operation handle of the NUA stack object.
A default operation can be used for operations where the ultimate result is not important or can be discarded.
| 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.
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 |
| nua_event_data_t const* nua_event_data | ( | nua_saved_event_t const | saved[1] | ) |
Get information from saved event.
Get information from saved event.
| int nua_event_is_incoming_request | ( | nua_event_t | event | ) |
Check if event can be responded with nua_respond().
Check if event can be responded with nua_respond().
Note that if event status is 200 or greater, it already has been responded. This function is provided for compatibility with future versions of nua. An unknown event can always be handled in the event callback like this:
switch (event) { ... default: if (status < 200 && nua_event_is_incoming_request(event)) nua_respond(nh, SIP_501_NOT_IMPLEMENTED, NUTAG_WITH_THIS(nua), TAG_END()); if (hmagic == NULL) nua_handle_destroy(nh); return; ...
| char const* nua_event_name | ( | nua_event_t | event | ) |
Get name for NUA event.
Get name for NUA event.
| char const* nua_generate_instance_identifier | ( | su_home_t * | home | ) |
Generate an instance identifier.
| void nua_get_hparams | ( | nua_handle_t * | nh, | |
| tag_type_t | tag, | |||
| tag_value_t | value, | |||
| ... | ||||
| ) |
Get handle parameters.
Get values of handle-specific parameters in nua_r_get_params event.
Application will specify either expilicit list of tags it is interested in, or a filter (at the moment, TAG_ANY()). The values are returned as a list of tags in the nua_r_get_params event.
| 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())
| void nua_get_params | ( | nua_t * | nua, | |
| tag_type_t | tag, | |||
| tag_value_t | value, | |||
| ... | ||||
| ) |
Get NUA parameters.
Get NUA parameters matching with the given filter.
The values of NUA parameters is returned in nua_r_get_params event.
| 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_call_id | ( | nua_t * | nua, | |
| const char * | call_id | |||
| ) |
Obtain a new reference to an existing handle based on Call-ID.
| 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).
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 |
| nua_handle_t* nua_handle_ref | ( | nua_handle_t * | nh | ) |
Make a new reference to handle.
The handles use reference counting for memory management. In addition to the memory management, there is protocol state associated with the handles. The protocol state is terminated with nua_handle_destroy(). In order to make it more convenient for programmer, nua_handle_destroy() decreases the reference count, too.
| 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 |
| int nua_handle_unref | ( | nua_handle_t * | nh | ) |
Destroy reference to handle.
The handles use reference counting for memory management. In addition to the memory management, there is protocol state associated with the handles. The protocol state is terminated with nua_handle_destroy(). In order to make it more convenient for programmer, nua_handle_destroy() decreases the reference count, too.
| 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.
Place a call using SIP INVITE method.
The INVITE method is used to initiate a call between two parties. The call is also known as SIP session.
At SIP level the session is represented as Dialog, which is a peer-to-peer association between two SIP User-Agents. The dialog is established by a successful 2XX response to the INVITE. The dialog is terminated by BYE transaction, which application can initiate with nua_bye() call.
An early dialog is established by an preliminary response (101..199), such as 180 Ringing. An early dialog is terminated with an error response with response code in range 300...699.
The media session belonging to the SIP session is usually represented by SDP, Session Description Protocol. The media session it is usually established during the call set-up with procedure known as SDP Offer/Answer exchange, defined by RFC 3264. See Media Session Handling below for details.
| nh | Pointer to operation handle | |
| tag,value,... | List of tagged parameters |
Also, the "precondition" call model described in RFC 3312 is supported at SIP level, that is, the SIP PRACK and UPDATE requests are sent if "precondition" is added to the Require header in the INVITE request.
Optionally
| nua_magic_t* nua_magic | ( | nua_t * | nua | ) |
| 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.
| nh | Pointer to operation handle | |
| tag,value,... | List of tagged parameters |
| void nua_method | ( | nua_handle_t * | , | |
| tag_type_t | , | |||
| tag_value_t | , | |||
| ... | ||||
| ) |
Send a request message with an extension method.
| 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.
Send a SIP NOTIFY request message.
This function is used when the application implements itself the notifier. The application must provide valid Subscription-State and Event headers using SIP tags. The subscription state can be modified with NUTAG_SUBSTATE(), however, its effect is overriden by Subscription-State header included in the nua_notify() tags.
If there is no active notifier dialog usage or no notifier dialog usage matches the Event header given by the application the nua_notify() request is rejected locally by the stack with status code 481. The local rejection can be bypassed if NUTAG_NEWSUB(1) is included in tags.
Please note that including NUTAG_NEWSUB(1) in nua_notify() tags if there is a valid subscription may lead to an extra NOTIFY sent to subscriber if the subscription had been terminated by the subscriber or by a timeout before the nua_notify() is processed.
| 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.
Query capabilities from server with OPTIONS request.
| 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.
Send a PRACK 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_refer | ( | nua_handle_t * | nh, | |
| tag_type_t | tag, | |||
| tag_value_t | value, | |||
| ... | ||||
| ) |
Transfer a call.
Send a REFER request asking the recipient to transfer the call.
The REFER request also establishes an implied subscription to the "refer" event. The "refer" event can have an "id" parameter, which has the value of CSeq number in the REFER request. After initiating the REFER request, the nua engine sends application a nua_r_refer event with status 100 and tag NUTAG_REFER_EVENT() containing a matching event header with id parameter.
Note that the Event header in the locally generated nua_r_refer event contains the id parameter. The id parameter contains the CSeq number of the REFER request, and it may get incremented if the request is retried because it got challenged or redirected. In that case, the application gets a new nua_r_refer event with status 100 and tag NUTAG_REFER_EVENT(). Also the recipient of the REFER request may or may not include the id parameter with the Event header in the NOTIFY requests messages which it sends to the sender of the REFER request.
Therefore the application is not able to modify the state of the implied subscription before receiving the first NOTIFY request.
| 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 |
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_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())
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
Normally, nua will start start a protocol engine for outbound connections used for NAT and firewall traversal and connectivity checks when registering.
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.
You can disable this kind of NAT traversal by setting "no-natify" into NUTAG_OUTBOUND() options string.
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.
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()).
| 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 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.
| int nua_save_event | ( | nua_t * | nua, | |
| nua_saved_event_t | return_saved[1] | |||
| ) |
Save last nua event.
Save last nua event.
| msg_t* nua_saved_event_request | ( | nua_saved_event_t const * | saved | ) |
Get request message from saved nua event.
| void nua_set_hparams | ( | nua_handle_t * | nh, | |
| tag_type_t | tag, | |||
| tag_value_t | value, | |||
| ... | ||||
| ) |
Set handle parameters.
Set the handle-specific parameters.
The handle-specific parameters override default or global parameters set by nua_set_params(). The handle-specific parameters are set by several other operations: nua_invite(), nua_respond(), nua_ack(), nua_prack(), nua_update(), nua_info(), nua_bye(), nua_options(), nua_message(), nua_register(), nua_publish(), nua_refer(), nua_subscribe(), nua_notify(), nua_refer(), and nua_notifier().
| nh | Pointer to a NUA handle | |
| tag,value,... | List of tagged parameters |
The global parameters that can not be set by nua_set_hparams() include NUTAG_DETECT_NETWORK_UPDATES(), NUTAG_SMIME_* tags, and all NTA tags.
| void nua_set_params | ( | nua_t * | nua, | |
| tag_type_t | tag, | |||
| tag_value_t | value, | |||
| ... | ||||
| ) |
Set NUA parameters.
Set nua parameters, shared by all handles.
| nua | Pointer to NUA stack object | |
| tag,value,... | List of tagged parameters |
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>.
For example, the nua_set_params() call like this:
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());
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_shutdown | ( | nua_t * | nua | ) |
Shutdown NUA stack.
| void nua_subscribe | ( | nua_handle_t * | nh, | |
| tag_type_t | tag, | |||
| tag_value_t | value, | |||
| ... | ||||
| ) |
Subscribe a SIP event.
Subscribe to a SIP event.
Subscribe a SIP event using the SIP SUBSCRIBE request. If the SUBSCRBE is successful a subscription state is established and the subscription is refreshed regularly. The refresh requests will generate nua_r_subscribe events.
| nh | Pointer to operation handle | |
| tag,value,... | List of tagged parameters |
| enum nua_substate nua_substate_make | ( | char const * | sip_substate | ) |
Convert string to enum nua_substate.
| char const* nua_substate_name | ( | enum nua_substate | substate | ) |
Return name of subscription state.
| 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_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.
| 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.
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 |