nua.docs

Sofia SIP is an open-source SIP User-Agent library, compliant with the IETF RFC3261 specification.

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

<table>
<tr><th>#</th>
    <th>Previous state</th>
    <th>Input</th>
    <th>Output</th>
    <th>Next state</th>
    <th>Offer/ Answer</th>
    <th align="left">Description</th>
</tr>
<tr><td>C1</td>			<!-- transition -->
    <td>init</td>		<!-- previous state -->
    <td>nua_invite()</td>	<!-- input -->
    <td>INVITE</td>		<!-- output -->
    <td>calling</td>		<!-- next state -->
    <td>Generate offer</td>	<!-- offer/answer -->
    <td>
   Client application starts call be invoking nua_invite(). By default, stack runs
   the initial offer/answer step and sends @b INVITE request with the SDP
   offer.
</td></tr>
<tr><td>C2</td>
    <td>calling</td><td>18X</td><td>-</td><td>proceeding</td>
    <td>(Save answer)</td>
  <td>
   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.
</td></tr>
<tr><td>C3a</td>
    <td>calling</td><td rowspan="2">2XX</td>
    <td rowspan="2">-</td><td rowspan="2">completing</td>
    <td rowspan="2">Save answer</td>
  <td rowspan="2">
   Client receives a 2XX response (usually <i>200 OK</i>) indicating that
   call has been accepted by the server. If there is an SDP session
   description included with response, it is stored.

   Unless the @ref NUTAG_AUTOACK() "auto-ack" mode is explicitly turned off
   by application the client does not stay in @b completing state, but
   proceeds immediately to next state transition.
</td></tr>
<tr><td>C3b</td>
    <td>proceeding</td></tr>
<tr><td>C4</td>
    <td>completing</td>
    <td>nua_ack() or<br>@ref NUTAG_AUTOACK() "auto-ack" </td>
    <td>ACK</td><td>ready</td>
    <td>Process answer</td>
    <td>
   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.
</td></tr>
<tr><td>C5</td>
    <td>completing</td>
    <td>nua_ack() or<br>@ref NUTAG_AUTOACK() "auto-ack" and<br> media error</td>
    <td>ACK<br>BYE</td>
    <td>terminating</td>
    <td>Process answer</td>
    <td>
   If there was a failure in SDP negotiation or other failure with media,
   the stack will automatically terminate the call. The BYE follows
   immediatelhy after the ACK.
</td></tr>
<tr><td>C6a</td>
    <td>calling</td>
    <td rowspan=2>3XX 4XX <br> 5XX 6XX</td>
    <td rowspan=2>ACK*</td>
    <td rowspan=2>terminated</td>
    <td rowspan=2>-</td>
    <td rowspan=2>
   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.
</td></tr>
<tr><td>C6b</td>
    <td>proceeding</td>
</tr>

<tr><td>C7a</td>
    <td>calling</td>
    <td rowspan=2>nua_cancel()</td>
    <td rowspan=2>CANCEL</td>
    <td>calling</td>
    <td rowspan=2>-</td>
    <td rowspan=2>
   Client can ask server to cancel the call attempt while in @b calling or
   @b proceeding state. There is no direct call state transition caused by
   nua_cancel(). The call state changes when the server returns a response.
   After receiving a CANCEL request the server will usually return a <i>487
   Request Terminated</i> response and call is terminated as in previous
   item.

   However, there is a race condition and the server can respond with a
   succesful 2XX response before receiving CANCEL. In that case, the call is
   established as usual. It is up to application to terminate the call with
   nua_bye().
</td></tr>
<tr><td>C7b</td>
    <td>proceeding</td>
    <td>proceeding</td>
</tr>
<tr><td>C8a</td>
    <td>proceeding</td>
    <td>nua_bye()</td>
    <td>CANCEL</td>
    <td rowspan=2>terminating*</td>
    <td rowspan=2>-</td>
    <td>
   The call cannot be terminated with BYE before the dialog is established
   with a non-100 preliminary response. So, instead of a @b BYE, stack sends
   a @b CANCEL request, and enters terminating state.

   However, there is a race condition and the server can respond with a
   succesful 2XX response before receiving CANCEL. If the server responds with
   a 2XX response, the nua will automatically send a BYE request asking server
   to terminate the call.
</td></tr>
<tr><td>C8b</td>
    <td>proceeding</td>
    <td>nua_bye()</td>
    <td>BYE</td>
<td>
   Even an early session can be terminated after entering @b proceeding
   state with nua_bye(). Stack sends a @b BYE request, and enters
   terminating state. Unlike @b CANCEL, @b BYE affects only one fork.

   However, there is a race condition and the server can respond with a
   succesful 2XX response before receiving BYE. If the server responds with
   a 2XX response, the nua will automatically send a BYE request asking server
   to terminate the call.
</td></tr>
<tr><td>C9</td>
    <td>completing</td><td>nua_bye()</td><td>ACK<br>BYE</td><td>terminating</td>
    <td>-</td>
    <td>
   If the stack is in @b completing state (it has already
   received 2XX response), it will have to @b ACK the final response, too.
</td></tr>

<tr><td>C10</td>
    <td>terminating*</td>
    <td>2XX<br>to INVITE</td>
    <td>BYE</td>
    <td>terminating</td>
    <td>-</td>
    <td>
   There is a race condition between @b BYE and @b INVITE. The call may have
   been re-established with @b INVITE after @b BYE was processed. @b BYE is
   re-sent and call state transitions to normal terminating state.
</td></tr>

<tr><td>C11</td>
    <td>terminating*</td>
    <td>3XX 4XX<br>5XX 6XX<br>to INVITE</td>
    <td>BYE</td>
    <td>terminating</td>
    <td>-</td>
    <td>
   The @b INVITE transaction is completed without a call being created. The
   call state transitions to normal terminating state.
</td></tr>

<tr><td>C12</td>
    <td>terminating</td>
    <td>3XX 4XX<br>5XX 6XX<br>to BYE</td>
    <td>-</td>
    <td>terminated</td>
    <td>-</td>
    <td>
   Call is terminated when the final response to the BYE is received.
</td></tr>

</table>

@section nua_uas_call_model Detailed Server-Side Call Model

The detailed call model at server side (UAS) is presented below. This model
does not include the extensions like @b 100rel or @b UPDATE.

@code

                           +----------------------------------+
                           |                INIT              |
                           +----------------------------------+
                             |              :               :
                             |              :               :
                            (1) INVITE/100 (2b) INVITE/18X (3c) INVITE/2XX
                             |              :               :
                             |              :               :
                             V              :               :
                          +------------+    :               :
     +--------------------|            |    :               :
     |                    |  RECEIVED  |--------------+     :
     |    +---------------|            |    :         |     :
     |    |               +------------+    :         |     :
     |    |                           |     :         |     :
     |    |          nua_respond/18X (2a)   :         |     :
     |    |                           |     :         |     :
     |    |                           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  |
                                               +-------------+
@endcode

The detailed description of state transitions on the server side is as
follows:
<table>
<tr><th>#</th>
    <th>Previous state</th>
    <th>Input</th>
    <th>Output</th>
    <th>Next state</th>
    <th>Offer/ Answer</th>
    <th align="left">Description</th>
</tr>
<tr><td>S1</td>				<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE</td>			<!-- input -->
    <td>100 Trying</td>			<!-- output -->
    <td>received</td>			<!-- next state -->
    <td>Save offer</td>			<!-- offer/answer -->
    <td>
   When a @b INVITE request for a new call is received, the server creates a
   fresh call handle for it, responds to the client with <i>100 Trying</i>
   and enters in the @b received state by default. It saves the possible SDP
   offer included in @b INVITE and passes it to the application.
</td></tr>
<tr><td>S2a</td>			<!-- transition -->
    <td>received</td>			<!-- previous state -->
    <td>nua_respond()</td>		<!-- input -->
    <td>18X</td>			<!-- output -->
    <td rowspan=2>early</td>		<!-- next state -->
    <td>(Generate early answer)</td>	<!-- offer/answer -->
    <td>
   When server returns a preliminary response for the initial @b 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.
</td></tr>
<tr><td>S2b</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and			<!-- input -->
        @ref NUTAG_AUTOALERT() "auto-alert"</td>
    <td>180 Ringing</td>		<!-- output -->
    <td>Save offer (and
        generate early answer)</td>	<!-- offer/answer -->
    <td>
    When @ref NUTAG_AUTOALERT() "auto-alert" option is enabled, stack sends
    180 Ringing immediately after receiving INVITE and enters @b early state.
</td></tr>
<tr><td>S3a</td>			<!-- transition -->
    <td>received</td>			<!-- previous state -->
    <td rowspan=2>nua_respond()</td>	<!-- input -->
    <td rowspan=2>2XX</td>		<!-- output -->
    <td rowspan=3>completed</td>	<!-- next state -->
    <td rowspan=2>Generate answer</td>	<!-- offer/answer -->
    <td rowspan=2>
   When the server sends a 2XX response towards the client, it accepts the
   call. The @b INVITE transaction is now considered complete but unconfirmed
   at the server side. If the offer was sent in @b INVITE request, the answer
   should be included in the 2XX response.
</td></tr>
<tr><td>S3b</td>			<!-- transition -->
    <td>early</td>			<!-- previous state -->
</td></tr>
<tr><td>S3c</td>			<!-- transition -->
    <td>init</td>			<!-- previous state -->
    <td>INVITE and @ref NUTAG_AUTOANSWER() "auto-answer"
    </td>				<!-- input -->
    <td>200 OK</td>			<!-- output -->
    <td>Save offer and
    <br>generate answer</td>		<!-- offer/answer -->
    <td>
    When @ref NUTAG_AUTOANSWER() "auto-answer" option is enabled, stack send
    200 OK immediately after receiving INVITE and enters @b completed state.
</td></tr>
</td></tr>
<tr><td>S4</td>				<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>ACK</td>			<!-- input -->
    <td>-</td>				<!-- output -->
    <td>ready</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
   The ready state is entered at server side after receiving @b ACK request
   from client, indicating that the client have received server's 2XX
   response. The call is ready, the @b INVITE transaction is confirmed.
</td></tr>
<tr><td>S5td>				<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>timeout</td>			<!-- input -->
    <td>BYE</td>			<!-- output -->
    <td>terminating</td>		<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
   If the server does not receive an @b ACK request in timely fashion, it will
   terminate the call by sending a @b BYE request to client.
</td></tr>
<tr><td>S6a</td>			<!-- transition -->
    <td>received</td>			<!-- previous state -->
    <td rowspan=2>nua_respond()</td>	<!-- input -->
    <td rowspan=2>3XX 4XX<br>5XX 6XX</td><!-- output -->
    <td rowspan=2>terminated</td>	<!-- next state -->
    <td rowspan=2>-</td>		<!-- offer/answer -->
    <td rowspan=2>
   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.
</td></tr>