NUA Event Diagrams

The example diagrams below try to present how to use NUA API with different SIP use cases.

Basic Call

The SIP following event diagram shows a pretty simple, succesful call case. The nua events and nua function calls are show in the diagram below as well as the SIP messages.

The call setup above assumes parameters NUTAG_AUTOALERT(0), NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.

                   Alice           Proxy            Bob
 0                  |                |                |
 1  nua_handle()    |                |                |
 2  nua_invite() -> |-----INVITE---->|                |
 3   nua_i_state <- |                |                |
 4                  |                |-----INVITE---->| -> nua_i_invite
 5                  |<--100 Trying---|                | -> nua_i_state
 6                  |                |                |
 7                  |                |                |
 8                  |                |                |
 9                  |                |<--180 Ringing--| <- nua_respond(180)
10  nua_i_invite <- |<--180 Ringing--|                | -> nua_i_state
11   nua_i_state <- |                |                |
12                  |                |<--200 OK-------| <- nua_respond(200)
13  nua_i_invite <- |<---200 OK------|                | -> nua_i_state
14   nua_i_state <- |                |                |
15     nua_ack() -> |-----ACK------->|                |
16   nua_i_state <- |                |-----ACK------->| -> nua_i_ack
17                  |                |                | -> nua_i_state
18                  |                |                |
19               <<====== SIP Session Established =======>>
20                  |                |                |
21                  |                |                |
22     nua_bye() -> |-----BYE------->|                |
23                  |                |-----BYE------->| -> nua_i_bye
24                  |                |<----200 OK-----| -> nua_i_state
25     nua_r_bye <- |<---200 OK------|                |
26   nua_i_state <- |                |                |
                    |                |                |

Holding Call

The media (audio, video) can be put on hold. In SIP system this means that application can indicate to the remote end that it is engaged in other activity (another call, for instance) and does not wish to receive media from the remove end.

The call hold is usully implemented using re-INVITE. Re-INVITE is an INVITE request sent on existing SIP session. Both original caller and callee can send re-INVITEs. The main use of re-INVITE is modifying sessions: adding media lines to the session, changing codecs on existing media, and, as you might expect, putting existing media on hold as well as resuming media from hold.

A re-INVITE is sent by calling nua_invite() on handle with existing call. When putting call on hold, the application can include SOATAG_HOLD("audio") or SOATAG_HOLD("video") or SOATAG_HOLD("audio, video") or SOATAG_HOLD("*") as parameters to re-INVITE nua_invite(). (Note that last SOATAG_HOLD() in the tag list will override the SOATAG_HOLD() tags before it.)

Another feature where nua tries to be helpful is autoanswer and auto-ACK on existing sessions: the re-INVITE is automatically responded with 200 OK and ACK is automatically sent. (If the application wants to respond and ACK by itself, it should explicitly set NUTAG_AUTOANSWER(0) and/or NUTAG_AUTOACK(0) in the handle; either include them in nua_invite() or nua_respond() parameters or call nua_set_hparams() explicitly.

                   Alice           Proxy            Bob
 0     nua_handle() |                |                |
 1                  |                |                |
 2  nua_invite() -> |-----INVITE---->|                |
 3   nua_i_state <- |                |                |
 4                  |                |-----INVITE---->| -> nua_i_invite
 5                  |<--100 Trying---|                | -> nua_i_state
 6                  |                |                |
 7                  |                |                |
 8                  |                |                |
 9                  |                |<--180 Ringing--| <- nua_respond(180)
10  nua_i_invite <- |<--180 Ringing--|                | -> nua_i_state
11   nua_i_state <- |                |                |
12                  |                |<--200 OK-------| <- nua_respond(200)
13  nua_i_invite <- |<---200 OK------|                | -> nua_i_state
14   nua_i_state <- |                |                |
15     nua_ack() -> |-----ACK------->|                |
16   nua_i_state <- |                |-----ACK------->| -> nua_i_ack
17                  |                |                | -> nua_i_state
18                  |                |                |
19               <<== Bi-Directional RTP Established ==>>
20                  |                |                |
21                  |                |                |
22                  |                |<--INVITE(hold)-| <- nua_invite(..
21                  |                |                |       NUTAG_HOLD("*")..)
23  nua_i_invite <- |<-INVITE(hold)--|                | -> nua_i_state
25   nua_i_state <- |----200 OK----->|                |
26                  |                |----200 OK----->| -> nua_i_invite
28                  |                |<-----ACK-------| -> nua_i_state
29     nua_i_ack <- |<----ACK--------|                |
24                  |                |                |
30               <<== Uni-Directional RTP Established ==>>
24                  |                |                |
31                  |                |                |
32                  |                |<--INVITE-------| <- nua_invite(..
21                  |                |                |      NUTAG_HOLD(NULL)..)
33  nua_i_invite <- |<--INVITE-------|                | -> nua_i_state
35   nua_i_state <- |---200 OK------>|                |
36                  |                |---200 OK------>| -> nua_i_invite
38                  |                |<----ACK--------| -> nua_i_state
39     nua_i_ack <- |<----ACK--------|                |
40   nua_i_state <- |                |                |
19               <<== Bi-Directional RTP Established ==>>
42                  |                |                |
43     nua_bye() -> |-----BYE------->|                |
44   nua_i_state <- |                |-----BYE------->| -> nua_i_bye
46                  |                |<----200 OK-----| -> nua_i_state
47                  |<---200 OK------|                |
                    |                |                |

Call Transfer

This is the unattended call transfer case.

1st MSC showing Alice's end:

           Alice                      Bob                 Carol
 0                     |                    |                    |
 1     nua_i_invite <- |<-----INVITE--------|                    |
 2      nua_i_state <- |                    |                    |
 2                     |                    |                    |
 3 nua_respond(180) -> |----180 Ringing---->|                    |
 2      nua_i_state <- |                    |                    |
 4                     |                    |                    |
 5 nua_respond(200) -> |------200 OK------->|                    |
 6      nua_i_state <- |                    |                    |
 8                     |                    |                    |
 7        nua_i_ack <- |<-------ACK---------|                    |
 8      nua_i_state <- |                    |                    |
 9                     |<========RTP=======>|                    |
10                     |                    |                    |
11             << Alice performs unattended transfer >>          |
12                     |                    |                    |
13                     |                    |                    |
14      nua_refer() -> |---REFER("r: C")--->|                    |
15                     |                    |                    |
16      nua_r_refer <- |<---202 Accepted----|                    |
17                     |                    |                    |
18     nua_i_notify <- |<-----NOTIFY--------|                    |
19                     |                    |                    |
20                     |------200 OK------->|                    |
21                     |                    |---INVITE("b: A")-->|
23                     |                    |                    |
22        nua_bye() -> |-------BYE--------->|                    |
23                     |                    |                    |
24        nua_r_bye <- |<----200 OK---------|                    |
25      nua_i_state <- |   No RTP Session   |                    |
28                     |                    |<----180 Ringing----|
26     nua_i_notify <- |<- - -NOTIFY - - - -|                    |
27                     |                    |                    |
20                     |- - - 200 OK- - - ->|                    |
29                     |                    |                    |
30                     |                    |<------200 OK-------|
31                     |                    |                    |
32                     |                    |---------ACK------->|
33                     |                    |        RTP         |
34                     |                    |<==================>|
35                     |                    |                    |
36                     |<-----NOTIFY--------|                    |
37                     |                    |                    |
38                     |------200 OK------->|                    |
                       |                    |                    |

2nd MSC showing Bobs's end:

   Alice               Bob (nh1)            Bob (nh2)             Carol
 0   |                    |                    |                    |
 1   |<-----INVITE--------|                    |                    |
 2   |                    |                    |                    |
 3   |---180 Ringing----->|                    |                    |
 4   |                    |                    |                    |
 5   |------200 OK------->|                    |                    |
 6   |                    |                    |                    |
 7   |<-------ACK---------|                    |                    |
 8   |        RTP         |                    |                    |
 9   |<==================>|                    |                    |
10   |                    |                    |                    |
11<< Alice performs unattended transfer >>     |                    |
12   |                    |                    |                    |
13   |       Refer-To:C F5|                    |                    |
14   |-REFER------------->| -> nua_i_refer     |                    |
15   |                    |                    |                    |
16   |<-202 Accepted------|                    |                    |
17   |                    |                    |                    |
18   |<-----NOTIFY--------|                    |                    |
19   |                    |                    |                    |
20   |------200 OK------->| -> nua_r_notify    |                    |
21   |                    |                    |                    |
22   |-------BYE--------->| -> nua_i_bye       |                    |
23   |                    | -> nua_i_state     |                    |
24   |<----200 OK---------|    nua_handle() -> |                    |
25   |   No RTP Session   |    nua_invite() -> |                    |
26   |                    |                    |--INVITE("b: A")--->|
27   |                    |                    |                    |
28   |                    |    nua_i_invite <- |<--180 Ringing------|
29   |                    |     nua_i_state <- |                    |
30   |                    |    nua_i_invite <- |<----200 OK---------|
31   |                    |     nua_i_state <- |                    |
32   |                    |         nua_ack -> |-------ACK--------->|
33   |                    |                    |                    |
34   |                    |                    |<=======RTP========>|
35   |                    |                    |                    |
36   |<-----NOTIFY--------|                    |                    |
37   |                    |
38   |------200 OK------->| -> nua_r_notify
39   |                    | <- nua_handle_destroy
     |                    |

Bob includes nh1 in nua_invite()/25 as NUTAG_NOTIFY_REFER() parameter.

Open Issue 1:

3GPP Call Model

The 3GPP call model is defined in 3GPP TS 24.229. In order to select only a single codec and ensure that the QoS reservationa are made before the call is alerting, the 3GPP call model employs multiple offer/answer exchanges. It uses 100rel and PRACK (RFC 3262), UPDATE (RFC 3311) and preconditions (RFC 3312) extensions specified by IETF.

The call setup below assumes parameters NUTAG_AUTOALERT(0), NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.

                      A                       B
 0    nua_handle()    |                       |
 1    nua_invite() -> |                       |
 2     nua_i_state <- |----INVITE (offer)---->|
 3                    |                       | -> nua_i_invite
 4                    |                       | -> nua_i_state
 5                    |                       |
 6                    |                       | <- nua_respond(183)
 7    nua_i_invite <- |<----183 (answer)------| -> nua_i_state
 8     nua_i_state <- |                       |
 9                << single codec is selected now >>
10                    |-----PRACK(offer2)---->| -> nua_i_prack
11                    |                       | -> nua_i_state
12    nua_r_prack  <- |<--200/PRACK(answer2)--|
13                    |                       |
14                    |                       |
15            << resource reservations are done now >>
16                    |                       |
17    nua_update() -> |----UPDATE (offer3)--->|
18    nua_i_state  <- |                       |
19    nua_i_state  <- |<-200/UPDATE (answer3)-| -> nua_i_update
20                    |                       | -> nua_i_state
21                    |                       |
22                    |                       |    << B rings >>
23                    |                       |
24                    |                       | <- nua_respond(180)
25    nua_i_invite <- |<---------180----------|
26    nua_i_state  <- |                       |
27                    |--------PRACK--------->| -> nua_i_prack
28    nua_r_prack  <- |<-----200/PRACK------->| -> nua_i_state
29                    |                       |
30                    |                       | <- nua_respond(200)
31    nua_i_invite <- |<---------200----------| -> nua_i_state
32    nua_i_state  <- |                       |
33    nua_ack()    -> |                       |
34    nua_i_state  <- |----------ACK--------->| -> nua_i_ack
35                    |                       | -> nua_i_state
                      |                       |
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

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