nua_client_request Class Reference

Collaboration diagram for nua_client_request:
[legend]

Detailed Description

Each handle has a queue of client-side requests; if a request is pending, a new request from API is added to the queue.

After the request is complete, it is removed from the queue and destroyed by the default. The exception is the client requests bound to a dialog usage: they are saved and re-used when the dialog usage is refreshed (and sometimes when the usage is terminated).

The client request is subclassed and its behaviour modified using virtual function table in nua_client_methods_t.

The first three methods (crm_template(), crm_init(), crm_send()) are called when the request is sent first time.

The crm_template() is called if a template request message is needed (for example, in case of unregister, unsubscribe and unpublish, the template message is taken from the request establishing the usage).

The crm_init() is called when the template message and dialog leg has been created and populated by the tags procided by the application. Its parameters msg and sip are pointer to the template request message that is saved in the nua_client_request::cr_msg field.

The crm_send() is called with a copy of the template message that has been populated with all the fields included in the request, including CSeq and Max-Forwards. The crm_send() function, such as nua_publish_client_request(), usually calls nua_base_client_trequest() that then creates the nta-level transaction.

The response to the request is processed by crm_check_restart(), which modifies and restarts the request when needed (e.g., when negotiating expiration time). After the request has been suitably modified, e.g., the expiration time has been increased, the restart function calls nua_client_restart(), which restarts the request and relays the intermediate response to the application with nua_client_restart() and crm_report().

The final responses are processed by crm_recv() and and preliminary ones by crm_preliminary(). Both functions call nua_base_client_response() after method-specific processing.

The nua_base_client_response() relays the response to the application with nua_client_restart() and crm_report().

Terminating Dialog Usages and Dialogs
The response can be marked as terminating with nua_client_terminating(). When a terminating request completes the dialog usage is removed and the dialog is destroyed (unless there is an another active usage).


Data Fields

nua_client_request_t ** cr_prev
 Linked list of requests.
int cr_event
 Request event.
unsigned short cr_status
 Latest status.
unsigned short cr_retry_count
 Retry count for this request.
unsigned short cr_answer_recv
 Recv answer in response with this status.
unsigned cr_offer_sent:1
 Sent offer in this request.
unsigned cr_offer_recv:1
 Recv offer in a response.
unsigned cr_answer_sent:1
 Sent answer in (PR)ACK.
unsigned cr_neutral:1
 No effect on session or other usage.
unsigned cr_auto:1
 Request was generated by stack.
unsigned cr_has_contact:1
 Request has user Contact.
unsigned cr_contactize:1
 Request needs Contact.
unsigned cr_dialog:1
 Request can initiate dialog.
unsigned cr_challenged:1
 Request was challenged.
unsigned cr_wait_for_cred:1
 Request is pending authentication.
unsigned cr_restarting:1
 Request is being restarted.
unsigned cr_reporting:1
 Reporting in progress.
unsigned cr_terminating:1
 Request terminates the usage.
signed int cr_terminated:2
 Response terminated usage (1) or whole dialog (-1).
unsigned cr_graceful:1
 Graceful termination required.


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