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 | | |
6 | | |
7 | | |
8 | | |
15
nua_ack() -> |-----ACK------->| |
18 | | |
19 <<====== SIP Session Established =======>>
20 | | |
21 | | |
22
nua_bye() -> |-----BYE------->| |
| | |
nua_handle_t * nua_handle(nua_t *nua, nua_hmagic_t *hmagic, tag_type_t, tag_value_t,...)
Create an operation handle.
Definition nua.c:305
void nua_invite(nua_handle_t *nh, tag_type_t, tag_value_t,...)
Place a call using SIP INVITE method.
Definition nua.c:631
void nua_respond(nua_handle_t *nh, int status, char const *phrase, tag_type_t, tag_value_t,...)
Respond to a request with given status code and phrase.
Definition nua.c:874
void nua_ack(nua_handle_t *nh, tag_type_t, tag_value_t,...)
Acknowledge a succesfull response to INVITE request.
Definition nua.c:637
@ nua_i_ack
Final response to INVITE has been ACKed.
Definition nua.h:92
@ nua_i_bye
Incoming BYE call hangup.
Definition nua.h:100
@ nua_r_bye
Answer to outgoing BYE.
Definition nua.h:131
@ nua_i_state
Call state has changed.
Definition nua.h:96
@ nua_i_invite
Incoming call INVITE.
Definition nua.h:90
void nua_bye(nua_handle_t *, tag_type_t, tag_value_t,...)
Hangdown a call.
Definition nua.c:643
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
1 | | |
6 | | |
7 | | |
8 | | |
15
nua_ack() -> |-----ACK------->| |
18 | | |
19 <<== Bi-Directional RTP Established ==>>
20 | | |
21 | | |
21 | | | NUTAG_HOLD("*")..)
24 | | |
30 <<== Uni-Directional RTP Established ==>>
24 | | |
31 | | |
21 | | | NUTAG_HOLD(NULL)..)
19 <<== Bi-Directional RTP Established ==>>
42 | | |
43
nua_bye() -> |-----BYE------->| |
47 |<---200 OK------| |
| | |
Call Transfer
This is the unattended call transfer case.
1st MSC showing Alice's end:
Alice Bob Carol
0 | | |
2 | | |
4 | | |
8 | | |
9 |<========RTP=======>| |
10 | | |
11 << Alice performs unattended transfer >> |
12 | | |
13 | | |
15 | | |
17 | | |
19 | | |
20 |------200 OK------->| |
21 | |---INVITE("b: A")-->|
23 | | |
22
nua_bye() -> |-------BYE--------->| |
23 | | |
28 | |<----180 Ringing----|
27 | | |
20 |- - - 200 OK- - - ->| |
29 | | |
30 | |<------200 OK-------|
31 | | |
32 | |---------ACK------->|
33 | | RTP |
34 | |<==================>|
35 | | |
36 |<-----NOTIFY--------| |
37 | | |
38 |------200 OK------->| |
| | |
void nua_refer(nua_handle_t *, tag_type_t, tag_value_t,...)
Transfer a call.
Definition nua.c:778
@ nua_r_refer
Answer to outgoing REFER.
Definition nua.h:133
@ nua_i_notify
Incoming event NOTIFY.
Definition nua.h:111
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| | |
15 | | | |
16 |<-202 Accepted------| | |
17 | | | |
18 |<-----NOTIFY--------| | |
19 | | | |
21 | | | |
26 | | |--INVITE("b: A")--->|
27 | | | |
32 | |
nua_ack -> |-------ACK--------->|
33 | | | |
34 | | |<=======RTP========>|
35 | | | |
36 |<-----NOTIFY--------| | |
37 | |
| |
@ nua_r_notify
Answer to outgoing NOTIFY.
Definition nua.h:143
@ nua_i_refer
Incoming REFER call transfer.
Definition nua.h:102
void nua_handle_destroy(nua_handle_t *h)
Destroy a handle.
Definition nua.c:919
Bob includes nh1 in nua_invite()/25 as NUTAG_NOTIFY_REFER() parameter.
Open Issue 1:
- how Bob know when to destroy nh1?
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
5 | |
9 << single codec is selected now >>
13 | |
14 | |
15 << resource reservations are done now >>
16 | |
21 | |
22 | | << B rings >>
23 | |
29 | |
| |
@ nua_i_update
Incoming session UPDATE.
Definition nua.h:106
@ nua_i_prack
Incoming PRACK.
Definition nua.h:104
@ nua_r_prack
Answer to outgoing PRACK.
Definition nua.h:137
void nua_update(nua_handle_t *, tag_type_t, tag_value_t,...)
Update a call.
Definition nua.c:808