nua.docs

this is simple sip stack.

<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 an 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 in @b calling
   or @b proceeding state. There is no direct call state transition caused
   by nua_cancel(). However, the server will return a <i>487 Request
   Terminated</i> response when receiving CANCEL and call is terminated as in
   previous item.
</td></tr>
<tr><td>C7b</td>
    <td>proceeding</td>
    <td>proceeding</td></tr>
<tr><td>C8</td>
    <td>proceeding</td>
    <td>nua_bye()</td>
    <td>BYE</td>
    <td>terminating</td>
    <td>-</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.
</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>
</table>

@par Detailed Server-Side Call Model

The detailed call model at server side 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 (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  |
                                               +-------------+
@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>
<tr><td>S6b</td>			<!-- transition -->
    <td>early</td>			<!-- previous state -->
</td></tr>
<tr><td>S7a</td>			<!-- transition -->
    <td>received</td>			<!-- previous state -->
    <td rowspan=2>CANCEL</td>		<!-- input -->
    <td rowspan=2>487 Request terminated</td><!-- output -->
    <td rowspan=2>terminated</td>	<!-- next state -->
    <td rowspan=2>-</td>		<!-- offer/answer -->
    <td rowspan=2>
   The client can cancel the call attempt before it is completed with a @b
   CANCEL request. Server returns a <i>200 OK</i> response to @b CANCEL and
   a <i>487 Request Terminated</i> response to the @b INVITE transaction and
   the call is terminated.
</td></tr>
<tr><td>S7b</td>			<!-- transition -->
    <td>early</td>			<!-- previous state -->
</td></tr>
<tr><td>S8</td>				<!-- transition -->
    <td>early</td>			<!-- previous state -->
    <td>BYE</td>			<!-- input -->
    <td>487 to INVITE<br>
        200 to BYE</td>			<!-- output -->
    <td>terminated</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
   The client can terminate an early session with a @b BYE request, too. Like
   in the @b CANCEL case above, the server will terminate call immediately,
   return a <i>200 OK</i> response to @b BYE and a <i>487 Request
   Terminated</i> response to the @b INVITE transaction.
</td></tr>
<tr><td>S9</td>				<!-- transition -->
    <td>completed</td>			<!-- previous state -->
    <td>BYE</td>			<!-- input -->
    <td>200 to BYE</td>			<!-- output -->
    <td>terminated</td>			<!-- next state -->
    <td>-</td>				<!-- offer/answer -->
    <td>
   The client can terminate a completed dialog with a @b BYE request. Server
   terminates call immediately, returns a <i>200 OK</i> response to @b BYE
   and lets the underlying transaction engine to take care of consuming @b
   ACK.
</td></tr>
</table>

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.

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