NUA Call Model

The NUA call follows a relative simple state model presented below.

The call model is used to present changes in call: when media starts to flow, when call is considered established, when call is terminated.

In the figure below, a simplified state diagram for a SIP call is presented. The application will receive an nua_i_state event indicating change in call state after it has occurred. The states in NUA call model are represented by enum nua_callstate, and the current value of state is included in tag NUTAG_CALLSTATE() with the nua_i_state event.

The SDP Offer/Answer negotiation status is also included in the event. The nua_i_state event is not sent, however, if the change is invoked by by application calling API functions like nua_bye(), and there is no change in SDP offer/answer status.

                    +---------------+
             +------|     INIT      |-----+
    INVITE/- |      +---------------+     | INVITE/100
             V                            |
       +------------+               +------------+
  +----|  CALLING   |--+        +---|  RECEIVED  |--+
  |    +------------+  |        |   +------------+  |
  |          |         |        |         |         |
  |          | 18X/-   |        |         | -/18X   |
  |          V         |        |         V         |
  |    +------------+  |        |   +------------+  |
  |<---| PROCEEDING |  |        |   |   EARLY    |->|
  |    +------------+  |        |   +------------+  |  -/[3456]XX
  |          |         |        |         |         |
  |          | 2XX/-   | 2XX/-  | -/2XX   | -/2XX   |    or
  |          V         |        |         V         |
  |    + - - - - - -+  |        |   +------------+  |  CANCEL/200,487
  |    : COMPLETING :<-+        +-->|  COMPLETE  |  |
  |    + - - - - - -+               +------------+  |
  |          |                            |         |
  |          | -/ACK                ACK/- |         |
  |          |                            |         |
  |          |                            |         |
  |          |      +---------------+     |         |
  |          +----->|     READY     |<----+         |
  |                 +---------------+               |
  |                   |           |                 |
  |          BYE/200  |           | -/BYE           |
  |                   |           |                 |
  |                   |           V                 |
  |                   |   +--------------+          |
  | [3456]XX/ACK      |   | TERMINATING  |          |
  |                   |   +--------------+          |
  |                   |           |                 |
  |                   |           | [23456]XX/-     |
  |                   V           V                 |
  |                 +---------------+               |
  +---------------->|  TERMINATED   |<--------------+
                    +---------------+

The labels "input/output" along each transition indicates SIP messages received from and sent to network, for instance, state transition "INVITE/100" occurs when a SIP INVITE request is received, and it is immediately returned a 100 (Trying) response. Label "2XX" means any 200-series response, e.g., 200 OK or 202 Accepted). Notation "[3456]XX" means any final error response in 300, 400, 500, or 600 series. Label "18X" means any provisional response from 101 to 199, most typically 180 (Ringing) or 183 (Session Progress).

Detailed Client Call Model
The detailed call model at client side is presented below. This model does not include the extensions like 100rel or UPDATE.

            +------------+
            |    INIT    |
            +------------+
                  |
                 (1) nua_invite/INVITE
                  |
                  V
            +------------+
            |            |-----------------------------(6a)-----+
            |            |----+                                 |
     +------|  CALLING   |  (7a) nua_cancel/CANCEL              |
     |      |            |<---+                                 |
     |      |            |                                      |
     |      +------------+                                      |
     |            |                                             |
     |           (2) 18X/-                                      |
     |            |                                             |
     |            V                                             |
     |      +------------+                                      |
     |      |            |-----------------------------(6b)---->|
     |      |            |----+                                 |
     |      | PROCEEDING |  (7b) nua_cancel/CANCEL              |
     |      |            |<---+                                 |
     |      |            |----------------------+               |
     |      +------------+                      |               |
     |            |                             |               |
   (3a) 2XX/-   (3b) 2XX/-                      |              (6) [3456]XX/ACK
     |            |                             |               |
     |            V                             |               |
     |      + - - - - - -+                      |               |
     +----->:            :                      |               |
            : COMPLETING :-------+              |               |
     + - - -:            :       |              |               |
     :      + - - - - - -+       |              |               |
     :            |              |              |               |
     :<auto_ack>  |              |              |               |
     :or nua_ack  | <auto_ack>   |              |               |
     :and media   | or nua_ack   | nua_bye      |               |
    (5) error    (4) /ACK       (9) /ACK+BYE   (8) nua_bye/BYE  |
     : /ACK+BYE   |              |              |               |
     :            V              |              |               |
     :      +------------+       |              |               |
     :      |            |       |              |               |
     :      |   READY    |       |              |               |
     :      |            |       |              |               |
     :      +------------+       |              |               |
     :                           |              |               |
     |                           |              |               |
     :                           |              |               |
     :      +-------------+      |              |               |
     + - - >| TERMINATING |<-----+<-------------+               |
            +-------------+                                     |
                  |                                             |
                  | [23456]XX/-                                 |
                  |                                             |
                  V                                             |
            +------------+                                      |
            | TERMINATED |<-------------------------------------+
            +------------+

The detailed description of state transitions on the client side is as follows:

# Previous state Input Output Next state Offer/ Answer Description
C1 init nua_invite() INVITE calling Generate offer Client application starts call be invoking nua_invite(). By default, stack runs the initial offer/answer step and sends INVITE request with the SDP offer.
C2 calling18X-proceeding (Save answer) Stack receives a 18X response (a provisional response between 101 and 199). It establishes an early dialog with server. If the provisional response contains an SDP answer, a session with early media is established. The caller can be listen to, for instance, ring tone or announcements about call progress using the early media session.
C3a calling2XX -completing Save answer Client receives a 2XX response (usually 200 OK) indicating that call has been accepted by the server. If there is an SDP session description included with response, it is stored.

Unless the auto-ack mode is explicitly turned off by application the client does not stay in completing state, but proceeds immediately to next state transition.

C3b proceeding
C4 completing nua_ack() or
auto-ack
ACKready Process answer Client sends an ACK request in this state transition. If the initial offer was sent with INVITE, the answer must have been received by this time, usually in the 2XX response. Client now completes the SDP offer-answer exchange and activates the media.
C5 completing nua_ack() or
auto-ack and
media error
ACK
BYE
terminating Process answer If there was an failure in SDP negotiation or other failure with media, the stack will automatically terminate the call. The BYE follows immediatelhy after the ACK.
C6a calling 3XX 4XX
5XX 6XX
ACK* terminated - Call is terminated when client receives a final error response (from 300 to 699) to its INVITE request. In this case, the underlying transaction engine takes care of sending ACK even when application-driven-ack mode is requested by application.
C6b proceeding
C7a calling nua_cancel() CANCEL calling - Client can ask server to cancel the call attempt while in in calling or proceeding state. There is no direct call state transition caused by nua_cancel(). However, the server will return a 487 Request Terminated response when receiving CANCEL and call is terminated as in previous item.
C7b proceeding proceeding
C8 proceeding nua_bye() BYE terminating - Even an early session can be terminated after entering proceeding state with nua_bye(). Stack sends a BYE request, and enters terminating state. Unlike CANCEL, BYE affects only one fork.
C9 completingnua_bye()ACK
BYE
terminating - If the stack is in completing state (it has already received 2XX response), it will have to ACK the final response, too.

Detailed Server-Side Call Model
The detailed call model at server side is presented below. This model does not include the extensions like 100rel or UPDATE.

                           +----------------------------------+
                           |                INIT              |
                           +----------------------------------+
                             |              :               :
                             |              :               :
                            (1) INVITE/100 (2b) INVITE/18X (3c) INVITE/2XX
                             |              :               :
                             |              :               :
                             V              :               :
                          +------------+    :               :
     +--------------------|            |    :               :
     |                    |  RECEIVED  |--------------+     :
     |    +---------------|            |    :         |     :
     |    |               +------------+    :         |     :
     |    |                           |     :         |     :
     |    |          nua_respond/18X (2)    :         |     :
     |    |                           |     :         |     :
     |    |                           V     V         |     :
     |    |                          +------------+   |     :
     |<------------------------------|            |   |     :
     |    |<-------------------------|    EARLY   |   |     :
     |    |               +----------|            |   |     :
     |    |               |          +------------+   |     :
     | nua_respond/       |                     |     |     :
    (6) /[3456]XX         |    nua_respond/2XX (3b)  (3a)   :
     |    |               |                     |     |     :
     |    |               |                     V     V     V
     |    |               |                    +-------------+
     |    |               |                    |             |
     |    |               |              +-----|  COMPLETED  |- - +
     |    |               |              |     |             |    :
     |    |               |              |     +-------------+    :
     |    |               |              |            |           :
     |    |               |              |           (4) ACK/-    :
     |    |               |              |            |           :
     |    |               |              |            V           :
     |    |               |              |     +-------------+    :
     |    |               |              |     |             |    :
     |    |               |              |     |    READY    |    :
     |    |               |              |     |             |    :
     |    |               |              |     +-------------+    :
     |    |               |              |                        :
     |   (7) CANCEL/487  (8) BYE/487    (9) BYE/200              (5) timeout/BYE
     |    |               |              |                        :
     |    |               |              |     +-------------+    :
     |    |               |              |     | TERMINATING |<- -+
     |    |               |              |     +-------------+
     |    |               |              |            |
     |    |               |              |            | [23456]XX/-
     |    |               |              |            |
     |    |               |              |            V
     |    V               V              V     +-------------+
     +---------------------------------------->| TERMINATED  |
                                               +-------------+

The detailed description of state transitions on the server side is as follows:
# Previous state Input Output Next state Offer/ Answer Description
S1 init INVITE 100 Trying received Save offer When a INVITE request for a new call is received, the server creates a fresh call handle for it, responds to the client with 100 Trying and enters in the received state by default. It saves the possible SDP offer included in INVITE and passes it to the application.
S2a received nua_respond() 18X early (Generate early answer) When server returns a preliminary response for the initial INVITE request, a early dialog is created. The server can also send an SDP answer with the preliminary answer and establish an early session, too. It can use the early session to send early media, e.g., ringing tone and announcements towards the client.
S2b init INVITE and auto-alert 180 Ringing Save offer (and generate early answer) When auto-alert option is enabled, stack sends 180 Ringing immediately after receiving INVITE and enters early state.
S3a received nua_respond() 2XX completed Generate answer When the server sends a 2XX response towards the client, it accepts the call. The INVITE transaction is now considered complete but unconfirmed at the server side. If the offer was sent in INVITE request, the answer should be included in the 2XX response.
S3b early
S3c init INVITE and auto-answer 200 OK Save offer and
generate answer
When auto-answer option is enabled, stack send 200 OK immediately after receiving INVITE and enters completed state.
S4 completed ACK - ready - The ready state is entered at server side after receiving ACK request from client, indicating that the client have received server's 2XX response. The call is ready, the INVITE transaction is confirmed.
S5td> completed timeout BYE terminating - If the server does not receive an ACK request in timely fashion, it will terminate the call by sending a BYE request to client.
S6a received nua_respond() 3XX 4XX
5XX 6XX
terminated - The server can reject the call by sending a 3XX, 4XX, 5XX, or 6XX response towards the client. The underlying transaction engine takes care of retransmitting the response when needed. It consumes the ACK response sent by the client, too.
S6b early
S7a received CANCEL 487 Request terminated terminated - The client can cancel the call attempt before it is completed with a CANCEL request. Server returns a 200 OK response to CANCEL and a 487 Request Terminated response to the INVITE transaction and the call is terminated.
S7b early
S8 early BYE 487 to INVITE
200 to BYE
terminated - The client can terminate an early session with a BYE request, too. Like in the CANCEL case above, the server will terminate call immediately, return a 200 OK response to BYE and a 487 Request Terminated response to the INVITE transaction.
S9 completed BYE 200 to BYE terminated - The client can terminate a completed dialog with a BYE request. Server terminates call immediately, returns a 200 OK response to BYE and lets the underlying transaction engine to take care of consuming ACK.

There is an alternative offer-answer model for third party call control (3pcc). The call setup involves a 3rd party, client C, which sends initial INVITE to server A without SDP. The call setup looks perfectly ordinary to server B, however.

        A                       C                       B
        |                       |                       |
        |<-------INVITE---------|                       |
        |                       |                       |
        |                       |                       |
        |------200 (offer)----->|                       |
        |                       |----INVITE (offer)---->|
        |                       |                       |
        |                       |                       |
        |                       |<-----200 (answer)-----|
        |<-----ACK (answer)-----|                       |
        |                       |                       |
        |                       |----------ACK--------->|
        |                       |                       |

The modifications to the call model affect mainly offer-answer model. The detailed description of state transitions for 3pcc on the server side is as follows:

# Previous state Input Output Next state Offer/ Answer Description
S1' init INVITE 100 Trying received - There is no SDP to save.
S2b' init INVITE and auto-alert 180 Ringing early - There is no SDP to save.
S3a early nua_respond() 2XX completed Generate offer The offer is sent in 200 OK.
S3b' received
S3c' init INVITE and auto-answer 200 OK
S4' completed ACK - ready Save and process answer The answer is processed and media activated after receiving ACK.
S9b' completed ACK and O/A error BYE terminating Save and process answer If the offer/answer negotiation ends in error after the server receives answer in ACK request, the server will have to terminate call by sending a BYE request.

Model for Modifying and Terminating Call
After the SIP session has been established, it can be further modified by INVITE transactions, initiated by either the original client or the original server. These so-called re-INVITE transactions can be used to upgrade session (add new media to it), put the session on hold or resume a held call.

A session can be terminated with a BYE request at any time.

If any in-dialog request fail with certain response codes, the session can be considered terminated, too. These response codes are documented with sip_response_terminates_dialog(). In some cases, the session should be terminated gracefully by sending a BYE request.

    +-------------------------------------------------------------+
    |                            READY                            |
    +-------------------------------------------------------------+
      |           |                |                |
      |           |                |                |
     (1) BYE/200 (2) nua_bye/BYE  (4) graceful/BYE (5) final/BYE
      |           |                |                |
      |           V                V                |
      |     +-----------------------------+         |
      |     |         TERMINATING         |         |
      |     +-----------------------------+         |
      |                    |                        |
      |                   (3) [23456]XX/-           |
      |                    |                        |
      V                    V                        V
    +-------------------------------------------------------------+
    |                         TERMINATED                          |
    +-------------------------------------------------------------+

The detailed description of state transitions while call is terminated is as follows:
# Previous state Input Output Next state Description
T1 ready BYE 200 OK terminated When the BYE request is received, the recipient terminates the currently ongoing INVITE transaction, the session and its dialog usage (if there is another dialog usage active, e.g., a subscription creted by REFER.)
T2 ready nua_bye BYE terminating The application terminates the session by calling nua_bye(). All the call-related requests on the dialog are rejected while in terminating state (XXX - with what?).
T3 terminating 2XX 3XX 4XX 5XX 6XX - terminated The session is finally terminated when a final response to BYE is received. Note that nua stack does retry BYE requests.
T4 ready "graceful" response BYE terminating A call-related request (re-INVITE, UPDATE, INFO, PRACK, REFER) fails with a response code indicating that the client should gracefully terminate the call.
T5 ready "fatal" response - terminated A call-related request (re-INVITE, UPDATE, INFO, PRACK, REFER) fails with a response code indicating that the call has been terminated.

See also:
http://www.ietf.org/internet-drafts/draft-sparks-sipping-dialogusage-01.txt

sip_response_terminates_dialog()


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