1/* -*- text -*- */ 2 3/**@MODULEPAGE "nua" - High-Level User Agent Module 4 5@section nua_meta Module Meta Information 6 7The @b nua module contains the user-agent library taking care of basic 8SIP User Agent functions. Its functionality includes call management, 9messaging and event retrieval. 10 11@CONTACT Pekka Pessi <Pekka.Pessi@nokia.com> 12 13@STATUS @SofiaSIP Core library 14 15@LICENSE LGPL 16 17@par Contributor(s): 18- Pekka Pessi <Pekka.Pessi@nokia.com> 19- Pasi Rinne-Rahkola <Pasi.Rinne-Rahkola@nokia.com> 20- Kai Vehmanen <Kai.Vehmanen@nokia.com> 21- Martti Mela <Martti.Mela@nokia.com> 22 23@section nua_overview Overview 24 25The NUA API gives the high-level application programmer transparent and 26full control to the SIP protocol engine�below it. NUA provides the call 27semantics on top of existing transaction semantics found in 28<a href="../nta/index.html"><b>nta</b></a> module. 29With NUA it is possible to create different kind of SIP User Agents, 30like terminals, gateways or MCUs. 31 32The @b nua engine hides many low-level signaling and media management 33aspects from the application programmer. It is possible to use different 34kind of media interfaces - even remote ones - in a fully transparent way. 35 36The application and the protocol engine within User Agent library can be run 37in separate threads. The protocol engine communicates with the application 38using @ref nua_event_e "events", delivered to the application with a a 39callback function. The callback function is called within the thread context 40of the application, represented with a #su_root_t object. 41 42@section nua_concepts_user Sofia Concepts for NUA User 43 44@subsection nua_intro Introduction 45 46The Sofia software suite is based on certain basic ideas and concepts that 47are used in all levels of Sofia software. Many of those are implemented in 48Sofia utility library (<a href="../su/index.html"><b>su</b></a>) providing 49unified interface to the most important OS services and utilities . 50 51The following sections contain descriptions of the concepts that a user of 52NUA library must understand to create a working application. The other 53utilities (in the SU library and other libraries of Sofia software suite) 54might also be useful for an application developer but one must be careful 55when using them because they might change the behavior of the Sofia 56software suite in a way that causes NUA library to work incorrectly. 57See [<a href="../su/index.html"><b>su</b></a>] for more detailed 58description of the SU services. 59 60@subsection nua_root Event loop - root object 61 62The NUA uses the reactor pattern (also known as dispatcher pattern and 63notifier pattern) for event driven systems (see [Using Design Patterns 64to Develop Reusable Object-oriented Communication Software, D.C. Schmidt, 65CACM October '95, 38(10): 65-74]). Sofia uses a task as basic execution 66unit for the programming model. According to the model, the program can 67ask that the event loop invokes a callback function when a certain event 68occurs. Such events include I/O activity, timers or a asynchronously 69delivered messages from other task. 70 71The root object is a handle representing the task in the application. 72Another way of seeing the same thing is that the root object represents 73the main event loop of the task. Through the root object the task code 74can access its context information (magic) and thread-synchronization 75features like wait objects, timers, and messages. 76 77An application using NUA services must create a root object and the callback 78routine to handle @ref nua_event_e "NUA events". The root object is created 79with su_root_create() function and the callback routine is registered with 80nua_create() function. 81 82Root object has type #su_root_t. 83 84See documentation of <sofia-sip/su_wait.h> and <su_root.c> for more information 85of root object. 86 87See section #nua_event_e for more information of the callback function. 88 89@subsection nua_magic Magic 90 91The magic is a term used for the context pointer that can be bound 92to various objects in Sofia stack (for example root object and operation 93handle) by the application code. This context pointer is passed back 94to the application code when a registered callback function is called by 95the main event loop. The Sofia stack retains the context information between 96calls to the callback function. An application can use the context information 97to store any information it needs for processing the events. 98 99@subsection nua_memmgmt Memory Handling 100 101The home-based memory management is useful when a lot of memory blocks are 102allocated for given task. The allocations are done via the memory home, 103which keeps a reference to each allocated memory block. When the memory 104home is then freed, it will free all memory blocks to which it has 105reference. This simplifies application logic because application code does 106not need to keep track of the allocated memory and free every allocated block 107separately. 108 109An application using NUA services can use the memory management services 110provided by the SU library but it is not mandatory. 111 112See documentation of <sofia-sip/su_alloc.h> for more information of memory 113management services. 114 115@subsection nua_tags Tags 116 117Tagging is the mechanism used in Sofia software for packing parameters to 118functions. It enables passing a variable number of parameters having 119non-fixed types. For an application programmer the tagging is visible as 120macros that are used to encapsulate the passed parameters. When evaluated a 121tagging macro creates a structure that contains a tag (telling what is the 122type of a parameter) and a value (pointer to opaque data). By checking the 123tag the layers of Sofia software check whether they can handle the parameter 124or should it just be passed to lower layers for processing. 125 126There are some tags with special meaning: 127- TAG_NULL() (synonymous to TAG_END()) end of tag list 128- TAG_SKIP() empty tag item 129- TAG_NEXT() tag item pointing to another tag list, ends the current tag list 130- TAG_ANY() filter tag accepting any tag 131- TAG_IF() conditional inclusion of tag item 132 133The NUA functions can be called with a list of tagged values if they have 134following parameters at the end of parameter list: 135 136@code 137tag_type_t tag, 138tag_value_t value, 139...); 140@endcode 141 142The last tagged value on the parameter list must be TAG_NULL() 143(or TAG_END(), synonym for TAG_NULL()). 144 145Every tag has two versions: \n 146NUTAG_<tagname> \n 147which takes a value parameter and \n 148NUTAG_<tagname>_REF \n 149which takes a reference parameter. The latter is used with 150tl_gets() function to retrieve tag values from tag list. 151 152For SIP headers there exists also additional 153version of tags: \n 154SIPTAG_<tagname>_STR \n 155This tag version takes a C-language character string as parameter. 156The corresponding tag without _STR suffix takes a parsed value structure 157as parameter. 158 159The following is an example of call to NUA function containing tagged values: 160@code 161nua_unregister(op->op_handle, 162 TAG_IF(use_registrar, NUTAG_REGISTRAR(registrar)), 163 SIPTAG_CONTACT_STR("*"), 164 SIPTAG_EXPIRES_STR("0"), 165 TAG_NULL()); 166@endcode 167 168An application using NUA services must use tagged arguments for passing the 169parameters to functions. See nua_invite() for discussion on how a SIP 170message is constructed from the tags. 171 172See documentation of <sofia-sip/su_tag.h> for more information of tags and the 173module-specific documentation of each Sofia module for information of 174tags specific for that module. 175 176@subsection nua_debugandlogging Debugging and Logging 177 178The modules of Sofia stack contain configurable debugging and logging 179functionality based on the services defined in <sofia-sip/su_log.h>. The debugging 180and logging details (for example level of details on output and output 181file name) can be configured by environment variables, directives in 182configuration files and compilation directives in the source files. 183 184Examples of useful directives/ environment variables are: 185- #SOFIA_DEBUG Default debug level (0..9) 186- #NUA_DEBUG NUA debug level (0..9) 187- #NTA_DEBUG Transaction engine debug level (0..9) 188- #TPORT_DEBUG Transport event debug level (0..9) 189- #TPORT_LOG If set, print out all parsed SIP messages on transport layer 190- #TPORT_DUMP Filename for dumping unparsed messages from transport 191 192The defined debug output levels are: 193- 0 fatal errors, panic 194- 1 critical errors, minimal progress at subsystem level 195- 2 non-critical errors 196- 3 warnings, progress messages 197- 5 signaling protocol actions (incoming packets, ...) 198- 7 media protocol actions (incoming packets, ...) 199- 9 entering/exiting functions, very verbatim progress 200 201An application using NUA services can also use the debugging and 202logging services provided by the Sofia stack but it is not mandatory. 203 204See documentation of <sofia-sip/su_log.h> for more information of debugging and 205logging services. 206 207@section nua_concepts NUA Concepts 208 209@subsection nua_stackobject NUA Stack Object 210 211Stack object represents an instance of SIP stack and media engine. It 212contains reference to root object of that stack, user-agent-specific 213settings, and reference to the SIP transaction engine, for example. 214 215A NUA stack object is created by nua_create() function and deleted by 216nua_destroy() function. The nua_shutdown() function is used to gracefully 217release active the sessions by @b nua engine. 218 219NUA stack object has type nua_t. 220 221@subsection nua_operationhandle NUA Operation Handle 222 223Operation handle represents an abstract SIP call/session. It contains 224information of SIP dialog and media session, and state machine that 225takes care of the call, high-level SDP offer-answer protocol, registration, 226subscriptions, publications and simple SIP transactions. An operation 227handle may contain list of tags used when SIP messages are created by 228NUA (e.g. From and To headers). 229 230An operation handle is created explicitly by the application using NUA 231for sending messages (function nua_handle()) and by stack for incoming 232calls/sessions (starting with INVITE or MESSAGE). The handle is destroyed 233by the application using NUA (function nua_handle_destroy()). 234 235Indication and response events are associated with an operation handle. 236 237NUA operation handle has type nua_handle_t. 238 239@subsection nua_stacktread Stack Thread and Message Passing Concepts 240 241The stack thread is a separate thread from application that provides the 242real-time protocol stack operations so that application thread can for 243example block or redraw UI as it likes. 244 245The communication between stack thread and application thread is asynchronous. 246Most of the NUA API functions cause a send of a message to the stack thread 247for processing and similarly when something happens in the stack thread it 248sends a message to the application thread. The messages to the application 249thread are delivered as invokes of the application callback function when 250the application calls su_root_run() or su_root_step() function. 251 252@subsection nua_sip_message SIP Message and Header Manipulation 253 254SIP messages are manipulated with typesafe SIPTAG_ tags. There are 255three versions of each SIP tag: 256- SIPTAG_<tagname>() takes a parsed value as parameter. 257- SIPTAG_<tagname>_STR() takes an unparsed string as parameter. 258- SIPTAG_<tagname>_REF() takes a reference as parameter, is used 259 with tl_gets() function to retrieve tag values from tag list. 260- SIPTAG_<tagname>__STR_REF() takes a reference as parameter, is used 261 with tl_gets() function to retrieve string tag values from tag list. 262 263For example a header named "Example" would have tags names SIPTAG_EXAMPLE(), 264SIPTAG_EXAMPLE_STR(), and SIPTAG_EXAMPLE_REF(). 265 266When tags are used in NUA calls the corresponding headers are added to 267the message. In case the header can be present only once in a message 268and there already exists a value for the header the value given by 269tag replaces the existing header value. Passing tag value NULL has no 270effect on headers. Passing tag value (void *)-1 removes corresponding 271headers from the message. 272 273For example: 274 275- sending a SUBSCRIBE with @b Event: header and two @b Accept: headers: 276 277@code 278 nua_subscribe(nh, 279 SIPTAG_EVENT_STR("presence"), 280 SIPTAG_ACCEPT(accept1), 281 SIPTAG_ACCEPT(accept2), 282 TAG_END()); 283@endcode 284 285- fetching tag values when processing nua_r_subscribe event: 286 287@code 288 sip_accept_t *ac = NULL; 289 sip_event_t *o = NULL; 290 291 tl_gets(tl, 292 SIPTAG_EVENT_REF(o), /* _REF takes a reference! */ 293 SIPTAG_ACCEPT_REF(ac), 294 TAG_END()); 295@endcode 296 297@section nua_tutorial SIP/NUA tutorial 298 299This section describes basic usage scenarios of NUA/Sofia stack using 300message sequence charts. 301 302@subsection nua_outgoingcall Outgoing Call 303 304@image latex SIP_outgoing_call.eps 305 306@image html SIP_outgoing_call.gif 307 308 309@subsection nua_incomingcall Incoming Call 310 311@image latex SIP_incoming_call.eps 312 313@image html SIP_incoming_call.gif 314 315@subsection nua_basicoutgoingoperation Basic Outgoing Operation 316 317@image latex SIP_basic_outgoing_operation.eps 318 319@image html SIP_basic_outgoing_operation.gif 320 321 322@subsection nua_basicincomingoperation Basic Incoming Operation 323 324@image latex SIP_basic_incoming_operation.eps 325 326@image html SIP_basic_incoming_operation.gif 327 328 329@subsection nua_outgoingoperationwithauth Outgoing Operation with Authentication 330 331@image latex SIP_outgoing_operation_with_auth.eps 332 333@image html SIP_outgoing_operation_with_auth.gif 334 335@section nua_simpleapplication Simple Application 336 337The following sections will present code examples from a simple application 338that uses services of NUA. The example is not complete but should present 339all relevant details of the basic use of NUA. 340 341On sourceforge.net there is available an example application 342<a href="http://sourceforge.net/project/showfiles.php?group_id=143636&package_id=179933"> 343sofisip_cli.c</a> that can be studied for more complete example. 344 345@subsection nua_datastructures Data Structures & Defines 346 347An application using services of NUA normally defines data areas that are 348used to store context information (i.e., "magic"). The types of pointers to 349these context information areas are passed to NUA by defines. 350 351@code 352/* type for application context data */ 353typedef struct application application; 354#define NUA_MAGIC_T application 355 356/* type for operation context data */ 357typedef union oper_ctx_u oper_ctx_t; 358#define NUA_HMAGIC_T oper_ctx_t 359@endcode 360 361The information area contents themselves can be defined as 362C structures or unions: 363 364@code 365/* example of application context information structure */ 366typedef struct application 367{ 368 su_home_t home[1]; /* memory home */ 369 su_root_t *root; /* root object */ 370 nua_t *nua; /* NUA stack object */ 371 372 /* other data as needed ... */ 373} application; 374 375/* Example of operation handle context information structure */ 376typedef union operation 377{ 378 nua_handle_t *handle; /* operation handle / 379 380 struct 381 { 382 nua_handle_t *handle; /* operation handle / 383 ... /* call-related information */ 384 } call; 385 386 struct 387 { 388 nua_handle_t *handle; /* operation handle / 389 ... /* subscription-related information */ 390 } subscription; 391 392 /* other data as needed ... */ 393 394} operation; 395@endcode 396 397NUA stack object and handle are opaque to the application programmer. 398Likewise, the application context is completely opaque to the NUA stack 399module. NUA functions are passed a pointer, and that pointer is then 400given back to the application within the callback parameters. In this 401case the application context information structure is also used to 402store a root object and memory home for memory handling. The application 403context information also contains the NUA stack object information. 404 405@subsection nua_initanddeinit Initialization and deinitialization 406 407The following code is an example of application function that initializes 408the system, enters the main loop for processing the messages, and, after 409message processing is ended, deinitalizes the system. 410 411If the application is not just responding to incoming SIP messages there must 412also be means to send messages to NUA. This can be handled for example by 413having a separate thread that calls NUA functions to send messages or by 414having a socket connection to the application for sending commands to the 415application (see documentation of su_wait_create() and su_root_register()). 416 417@code 418/* Application context structure */ 419application appl[1] = {{{{(sizeof appl)}}}}; 420 421/* initialize system utilities */ 422su_init(); 423 424/* initialize memory handling */ 425su_home_init(appl->home); 426 427/* initialize root object */ 428appl->root = su_root_create(appl); 429 430if (appl->root != NULL) { 431 /* create NUA stack */ 432 appl->nua = nua_create(appl->root, 433 app_callback, 434 appl, 435 /* tags as necessary ...*/ 436 TAG_NULL()); 437 438 if (appl->nua != NULL) { 439 /* set necessary parameters */ 440 nua_set_params(appl->nua, 441 /* tags as necessary ... */ 442 TAG_NULL()); 443 444 /* enter main loop for processing of messages */ 445 su_root_run(appl->root); 446 447 /* destroy NUA stack */ 448 nua_destroy(appl->nua); 449 } 450 451 /* deinit root object */ 452 su_root_destroy(appl->root); 453 appl->root = NULL; 454} 455 456/* deinitialize memory handling */ 457su_home_deinit(appl->home); 458 459/* deinitialize system utilities */ 460su_deinit(); 461@endcode 462 463@subsection nua_handlingevents Handling events 464 465Handling of the events coming from NUA stack is done in the callback 466function that is registered for NUA stack with the nua_create() function 467when the application is initialized. The content of callback function is 468in its simplest form just a switch/case statement that dispatches the 469incoming events for processing to separate functions. 470 471@code 472void app_callback(nua_event_t event, 473 int status, 474 char const *phrase, 475 nua_t *nua, 476 nua_magic_t *magic, 477 nua_handle_t *nh, 478 nua_hmagic_t *hmagic, 479 sip_t const *sip, 480 tagi_t tags[]) 481{ 482 switch (event) { 483 case nua_i_invite: 484 app_i_invite(status, phrase, nua, magic, nh, hmagic, sip, tags); 485 break; 486 487 case nua_r_invite: 488 app_r_invite(status, phrase, nua, magic, nh, hmagic, sip, tags); 489 break; 490 491 /* and so on ... */ 492 493 default: 494 /* unknown event -> print out error message */ 495 if (status > 100) { 496 printf("unknown event %d: %03d %s\n", 497 event, 498 status, 499 phrase); 500 } 501 else { 502 printf("unknown event %d\n", event); 503 } 504 tl_print(stdout, "", tags); 505 break; 506 } 507} /* app_callback */ 508@endcode 509 510@subsection nua_placeacall Place a call 511 512The following three functions show an example of how a basic SIP 513call is created. 514 515The place_a_call() function creates an operation handle and invokes the 516SIP INVITE method. 517 518@code 519operation *place_a_call(char const *name, url_t const *url) 520{ 521 operation *op; 522 sip_to_t *to; 523 524 /* create operation context information */ 525 op = su_zalloc(appl->home, (sizeof *op)); 526 if (!op) 527 return NULL; 528 529 /* Destination address */ 530 to = sip_to_create(NULL, url); 531 if (!to) 532 return NULL; 533 534 to->a_display = name; 535 536 /* create operation handle */ 537 op->handle = nua_handle(appl->nua, op, SIPTAG_TO(to), TAG_END()); 538 539 if (op->handle == NULL) { 540 printf("cannot create operation handle\n"); 541 return NULL; 542 } 543 544 nua_invite(op->handle, 545 /* other tags as needed ... */ 546 TAG_END()); 547 548} /* place_a_call */ 549@endcode 550 551The app_r_invite() function is called by callback function when response to 552INVITE message is received. Here it is assumed that automatic acknowledge 553is not enabled so ACK response must be sent explicitly. 554 555@code 556void app_r_invite(int status, 557 char const *phrase, 558 nua_t *nua, 559 nua_magic_t *magic, 560 nua_handle_t *nh, 561 nua_hmagic_t *hmagic, 562 sip_t const *sip, 563 tagi_t tags[]) 564{ 565 if (status == 200) { 566 nua_ack(nh, TAG_END()); 567 } 568 else { 569 printf("response to INVITE: %03d %s\n", status, phrase); 570 } 571} /* app_r_invite */ 572@endcode 573 574The nua_i_state event is sent (and app_i_state() function called by callback 575function) when the call state changes (see @ref nua_uac_call_model 576"client-side call model"). 577 578@code 579void app_i_state(int status, 580 char const *phrase, 581 nua_t *nua, 582 nua_magic_t *magic, 583 nua_handle_t *nh, 584 nua_hmagic_t *hmagic, 585 sip_t const *sip, 586 tagi_t tags[]) 587{ 588 nua_callstate_t state = nua_callstate_init; 589 590 tl_gets(tags, 591 NUTAG_CALLSTATE_REF(state), 592 NUTAG__REF(state), 593 594 595 state = (nua_callstate_t)t->t_value; 596 597 printf("call %s\n", nua_callstate_name(state)); 598 599} /* app_i_state */ 600@endcode 601 602@subsection nua_receiveacall Receive a call 603 604The app_i_invite() function is called by callback function when incoming 605INVITE message is received. This example assumes that autoanswer is 606not enabled so the response must be sent explicitly. 607 608@code 609void app_i_invite(int status, 610 char const *phrase, 611 nua_t *nua, 612 nua_magic_t *magic, 613 nua_handle_t *nh, 614 nua_hmagic_t *hmagic, 615 sip_t const *sip, 616 tagi_t tags[]) 617{ 618 printf("incoming call\n"); 619 620 nua_respond(nh, 200, "OK", SOA_USER_SDP(magic->sdp), TAG_END()); 621 622} /* app_i_invite */ 623@endcode 624 625The app_i_state() function is called by the callback function when call has 626been successfully set up and the media has been activated. 627 628@code 629void app_i_active(int status, 630 char const *phrase, 631 nua_t *nua, 632 nua_magic_t *magic, 633 nua_handle_t *nh, 634 nua_hmagic_t *hmagic, 635 sip_t const *sip, 636 tagi_t tags[]) 637{ 638 printf("call active\n"); 639 640} /* app_i_active */ 641@endcode 642 643@subsection nua_terminatingcall Terminating a call 644 645The following three functions show an example of how a basic SIP 646call is terminated. 647 648The terminate_call() function sends the SIP BYE message. 649 650@code 651void terminate_call(void) 652{ 653 nua_bye(op->handle, TAG_END()); 654 655} /* terminate call */ 656@endcode 657 658The app_r_bye() function is called by the callback function when answer to 659the BYE message is received. The function destroys the call handle and 660releases the memory allocated to operation context information. 661 662@code 663void app_r_bye(int status, 664 char const *phrase, 665 nua_t *nua, 666 nua_magic_t *magic, 667 nua_handle_t *nh, 668 nua_hmagic_t *hmagic, 669 sip_t const *sip, 670 tagi_t tags[]) 671{ 672 if (status < 200) 673 return; 674 675 printf("call released\n"); 676 677 /* release operation handle */ 678 nua_handle_destroy(hmagic->handle); 679 op->handle = NULL; 680 681 /* release operation context information */ 682 su_free(appl->home, hmagic); 683 684} /* app_r_bye */ 685@endcode 686 687The app_i_bye() function is called by the callback function when an incoming 688BYE message is received. The function destroys the call handle and releases 689the memory allocated to operation context information. 690 691@code 692void app_i_bye(int status, 693 char const *phrase, 694 nua_t *nua, 695 nua_magic_t *magic, 696 nua_handle_t *nh, 697 nua_hmagic_t *hmagic, 698 sip_t const *sip, 699 tagi_t tags[]) 700{ 701 printf("call released\n"); 702 703 /* release operation handle */ 704 nua_handle_destroy(hmagic->handle); 705 op->handle = NULL; 706 707 /* release operation context information */ 708 su_free(appl->home, hmagic); 709 710} /* app_i_bye */ 711@endcode 712 713@subsection nua_sendamessage Sending a message 714 715The following functions show an example of how a SIP MESSAGE is sent. 716 717The send_message() function sends the SIP MESSAGE. 718 719@code 720void send_message(void) 721{ 722 op_t *op; 723 724 /* create operation context information */ 725 op = su_zalloc(appl->home, sizeof(op_t)); 726 if (op = NULL) { 727 printf("cannot create operation context information\n"); 728 return; 729 } 730 731 /* how we create destination_address? */ 732 733 /* create operation handle */ 734 op->handle = nua_handle(appl->nua, 735 op, 736 NUTAG_URL(destination_address), 737 TAG_END()); 738 739 if (op->handle == NULL) { 740 printf("cannot create operation handle\n"); 741 return; 742 } 743 744 /* send MESSAGE */ 745 nua_message(op->handle, 746 SIPTAG_CONTENT_TYPE_STR("text/plain"), 747 SIPTAG_PAYLOAD_STR("Hello, world!"), 748 /* other tags as needed ... */ 749 TAG_END()); 750 751} /* send_message */ 752@endcode 753 754The app_r_message() function is called by the callback function when 755answer to the MESSAGE is received. 756 757@code 758void app_r_message(int status, 759 char const *phrase, 760 nua_t *nua, 761 nua_magic_t *magic, 762 nua_handle_t *nh, 763 nua_hmagic_t *hmagic, 764 sip_t const *sip, 765 tagi_t tags[]) 766{ 767 printf("response to MESSAGE: %03d %s\n", status, phrase); 768} /* app_r_message */ 769@endcode 770 771@subsection nua_receivemessage Receiving a message 772 773The following function shows an example of how a SIP MESSAGE is received. 774 775The app_i_message() function is called by the callback function when 776a SIP MESSAGE is received. 777 778@code 779void app_i_message(int status, 780 char const *phrase, 781 nua_t *nua, 782 nua_magic_t *magic, 783 nua_handle_t *nh, 784 nua_hmagic_t *hmagic, 785 sip_t const *sip, 786 tagi_t tags[]) 787{ 788 printf("received MESSAGE: %03d %s\n", status, phrase); 789 790 printf("From: %s%s" URL_PRINT_FORMAT "\n", 791 sip->sip_from->a_display ? sip->sip_from->a_display : "", 792 sip->sip_from->a_display ? " " : "", 793 URL_PRINT_ARGS(sip->sip_from->a_url)); 794 795 if (sip->sip_subject) { 796 printf("Subject: %s\n", sip->sip_subject->g_value); 797 } 798 799 if (sip->sip_payload) { 800 fwrite(sip->sip_payload->pl_data, sip->sip_payload->pl_len, 1, stdout); 801 fputs("\n", stdout); 802 } 803} /* app_i_message */ 804@endcode 805 806@subsection nua_notifier Creating a Presence Server 807 808@code 809 810... 811 application_t *app; 812 operation_t *oper; 813 814... 815 816 oper->app = app; 817 818 819 app->nua = nua_create(ssip->s_root, 820 app_callback, 821 app, 822 TAG_NULL()); 823... 824 825 oper->handle = nua_handle(app->nua, app, 826 NUTAG_URL(to->a_url), 827 SIPTAG_TO(to), 828 ta_tags(ta)); 829... 830 831 nua_notifier(oper->handle, 832 SIPTAG_EXPIRES_STR("3600"), 833 SIPTAG_EVENT_STR("presence"), 834 SIPTAG_CONTENT_TYPE_STR("application/pidf-partial+xml"), 835 NUTAG_SUBSTATE(nua_substate_pending), 836 TAG_END()); 837@endcode 838 839After the nua_notifier object -- the presence server -- is created, an 840event nua_r_notifier is returned. Status and phrase values of the 841app_callback function indicate the success of the creation. 842 843Authorization of an incoming subscription (to the local presence 844server) can be handled in the callback function. 845 846@code 847void app_callback(nua_event_t event, 848 int status, char const *phrase, 849 nua_t *nua, application_t *app, 850 nua_handle_t *nh, oper_t *op, 851 sip_t const *sip, tagi_t tags[]) 852{ 853 nea_sub_t *subscriber = NULL; 854 855 switch (event) { 856 case nua_i_subscription: 857 tl_gets(tags, 858 NEATAG_SUB_REF(subscriber), 859 TAG_END()); 860 861 862 nua_authorize(nua_substate_active); 863 864 865 default: 866 break; 867} 868 869 870@endcode 871 872 873@subsection nua_shutting_down Shutdown 874 875The following functions show an example of how application terminates 876the NUA stack. 877 878The shutdown() function starts the termination. 879 880@code 881void shutdown(void) 882{ 883 nua_shutdown(appl->nua); 884 885} /* shutdown */ 886@endcode 887 888The app_r_shutdown() function is called by the callback function when NUA 889stack termination is either finished or failed. 890 891@code 892void app_r_shutdown(int status, 893 char const *phrase, 894 nua_t *nua, 895 nua_magic_t *magic, 896 nua_handle_t *nh, 897 nua_hmagic_t *hmagic, 898 sip_t const *sip, 899 tagi_t tags[]) 900{ 901 printf("shutdown: %d %s\n", status, phrase); 902 903 if (status < 200) { 904 /* shutdown in progress -> return */ 905 return; 906 } 907 908 /* end the event loop. su_root_run() will return */ 909 su_root_break(magic->root); 910 911} /* app_r_shutdown */ 912@endcode 913 914*/ 915 916/** @page nua_call_model NUA Call Model 917 918The NUA call follows a relatively simple state model presented below. The call 919model is used to present changes in call: when media starts to flow, when 920call is considered established, when call is terminated. 921 922In the figure below, a simplified state diagram for a SIP call is presented. 923After the call state has changes the application will receive an 924#nua_i_state event indicating the change. The states in NUA call model are 925represented by @e enum #nua_callstate, and the current value of state is 926included as the tag NUTAG_CALLSTATE() with the #nua_i_state event. 927 928The @RFC3264 SDP Offer/Answer negotiation status is also included in the 929#nua_i_state event. The negotiation status includes the local SDP (in 930SOATAG_LOCAL_SDP()) sent and flags indicating whether the local SDP was an 931offer or answer (NUTAG_OFFER_SENT(), NUTAG_ANSWER_SENT()). Likewise, the 932received remote SDP is included in tag SOATAG_REMOTE_SDP() and flags 933indicating whether the remote SDP was an offer or an answer in tags 934NUTAG_OFFER_RECV() or NUTAG_ANSWER_RECV(). SOATAG_ACTIVE_AUDIO() and 935SOATAG_ACTIVE_VIDEO() are informational tags used to indicate what is the 936status of these media. 937 938The #nua_i_state event is not sent, however, if the change is invoked by 939application calling API functions like nua_bye() and there is no change in 940SDP offer/answer status. 941 942@code 943 +---------------+ 944 +------| INIT |-----+ 945 INVITE/- | +---------------+ | INVITE/100 946 V | 947 +------------+ +------------+ 948 +----| CALLING |--+ +---| RECEIVED |--+ 949 | +------------+ | | +------------+ | 950 | | | | | | 951 | | 18X/- | | | -/18X | 952 | V | | V | 953 | +------------+ | | +------------+ | 954 |<---| PROCEEDING | | | | EARLY |->| 955 | +------------+ | | +------------+ | -/[3456]XX 956 | | | | | | 957 | | 2XX/- | 2XX/- | -/2XX | -/2XX | or 958 | V | | V | 959 | + - - - - - -+ | | +------------+ | CANCEL/200,487 960 | : COMPLETING :<-+ +-->| COMPLETE | | 961 | + - - - - - -+ +------------+ | 962 | | | | 963 | | -/ACK ACK/- | | 964 | | | | 965 | | | | 966 | | +---------------+ | | 967 | +----->| READY |<----+ | 968 | +---------------+ | 969 | | | | 970 | BYE/200 | | -/BYE | 971 | | | | 972 | | V | 973 | | +--------------+ | 974 | [3456]XX/ACK | | TERMINATING | | 975 | | +--------------+ | 976 | | | | 977 | | | [23456]XX/- | 978 | V V | 979 | +---------------+ | 980 +---------------->| TERMINATED |<--------------+ 981 +---------------+ 982@endcode 983 984The labels "input/output" along each transition indicates SIP messages 985received from and sent to network, for instance, state transition 986"INVITE/100" occurs when a SIP @b INVITE request is received, and it is 987immediately returned a 100 (<i>Trying</i>) response. Label "2XX" means any 988200-series response, e.g., <i>200 OK</i> or <i>202 Accepted</i>). Notation 989"[3456]XX" means any final error response in 300, 400, 500, or 600 990series. Label "18X" means any provisional response from 101 to 199, most 991typically 180 (<i>Ringing</i>) or 183 (<i>Session Progress</i>). 992 993@section nua_uac_call_model Detailed Client Call Model 994 995The detailed call model at client side is presented below. This model does 996not include the extensions like @b 100rel or @b UPDATE. 997 998@code 999 +------------+ 1000 | INIT | 1001 +------------+ 1002 | 1003 (1) nua_invite/INVITE 1004 | 1005 V 1006 +------------+ 1007 | |-----------------------------(6a)-----+ 1008 | |----+ nua_cancel | 1009 +------| CALLING | (7a) /CANCEL | 1010 | | |<---+ | 1011 | | |----------------------+ | 1012 | +------------+ | | 1013 | | (8a) nua_bye | 1014 | (2) 18X/- | /CANCEL | 1015 | | | | 1016 | V | | 1017 | +------------+ | | 1018 | | |-----------------------------(6b)---->| 1019 | | |----+ nua_cancel | | 1020 | | PROCEEDING | (7b) /CANCEL | | 1021 | | |<---+ | | 1022 | | |----------------------+ | 1023 | +------------+ | | 1024 | | | | 1025 (3a) 2XX/- (3b) 2XX/- | (6) [3456]XX/ACK 1026 | | | | 1027 | V | | 1028 | + - - - - - -+ | | 1029 +----->: : | | 1030 : COMPLETING :-------+ | | 1031 + - - -: : | | | 1032 : + - - - - - -+ | | | 1033 : | | | | 1034 :<auto_ack> | | | | 1035 :or nua_ack | <auto_ack> | | | 1036 :and media | or nua_ack | nua_bye | | 1037 (5) error (4) /ACK (9) /ACK+BYE (8b) nua_bye/BYE | 1038 : /ACK+BYE | | | | 1039 : V | V | 1040 : +------------+ | +-------------+ | 1041 : | | | | | | 1042 : | READY | | | TERMINATING*| | 1043 : | | | | | | 1044 : +------------+ | +-------------+ | 1045 : | | | | 1046 : | (10) 2XX (11) 3XX 4XX | 1047 : +-------------+ | | /BYE | 5XX 6XX | 1048 : | | V V | /- | 1049 + - - >| TERMINATING |<-------------------------+ | 1050 | | | 1051 +-------------+ | 1052 | | 1053 (12) [23456]XX to BYE/- | 1054 | | 1055 V | 1056 +------------+ | 1057 | TERMINATED |<-------------------------------------+ 1058 +------------+ 1059@endcode 1060 1061The detailed description of state transitions on the client side is as 1062follows: 1063 1064<table> 1065<tr><th>#</th> 1066 <th>Previous state</th> 1067 <th>Input</th> 1068 <th>Output</th> 1069 <th>Next state</th> 1070 <th>Offer/ Answer</th> 1071 <th align="left">Description</th> 1072</tr> 1073<tr><td>C1</td> <!-- transition --> 1074 <td>init</td> <!-- previous state --> 1075 <td>nua_invite()</td> <!-- input --> 1076 <td>INVITE</td> <!-- output --> 1077 <td>calling</td> <!-- next state --> 1078 <td>Generate offer</td> <!-- offer/answer --> 1079 <td> 1080 Client application starts call be invoking nua_invite(). By default, stack runs 1081 the initial offer/answer step and sends @b INVITE request with the SDP 1082 offer. 1083</td></tr> 1084<tr><td>C2</td> 1085 <td>calling</td><td>18X</td><td>-</td><td>proceeding</td> 1086 <td>(Save answer)</td> 1087 <td> 1088 Stack receives a 18X response (a provisional response between 101 1089 and 199). It establishes an early dialog with server. If the provisional 1090 response contains an SDP answer, a session with early media is 1091 established. The caller can be listen to, for instance, ring tone or 1092 announcements about call progress using the early media session. 1093</td></tr> 1094<tr><td>C3a</td> 1095 <td>calling</td><td rowspan="2">2XX</td> 1096 <td rowspan="2">-</td><td rowspan="2">completing</td> 1097 <td rowspan="2">Save answer</td> 1098 <td rowspan="2"> 1099 Client receives a 2XX response (usually <i>200 OK</i>) indicating that 1100 call has been accepted by the server. If there is an SDP session 1101 description included with response, it is stored. 1102 1103 Unless the @ref NUTAG_AUTOACK() "auto-ack" mode is explicitly turned off 1104 by application the client does not stay in @b completing state, but 1105 proceeds immediately to next state transition. 1106</td></tr> 1107<tr><td>C3b</td> 1108 <td>proceeding</td></tr> 1109<tr><td>C4</td> 1110 <td>completing</td> 1111 <td>nua_ack() or<br>@ref NUTAG_AUTOACK() "auto-ack" </td> 1112 <td>ACK</td><td>ready</td> 1113 <td>Process answer</td> 1114 <td> 1115 Client sends an ACK request in this state transition. If the initial 1116 offer was sent with INVITE, the answer must have been received by this 1117 time, usually in the 2XX response. Client now completes the SDP 1118 offer-answer exchange and activates the media. 1119</td></tr> 1120<tr><td>C5</td> 1121 <td>completing</td> 1122 <td>nua_ack() or<br>@ref NUTAG_AUTOACK() "auto-ack" and<br> media error</td> 1123 <td>ACK<br>BYE</td> 1124 <td>terminating</td> 1125 <td>Process answer</td> 1126 <td> 1127 If there was a failure in SDP negotiation or other failure with media, 1128 the stack will automatically terminate the call. The BYE follows 1129 immediately after the ACK. 1130</td></tr> 1131<tr><td>C6a</td> 1132 <td>calling</td> 1133 <td rowspan=2>3XX 4XX <br> 5XX 6XX</td> 1134 <td rowspan=2>ACK*</td> 1135 <td rowspan=2>terminated</td> 1136 <td rowspan=2>-</td> 1137 <td rowspan=2> 1138 Call is terminated when client receives a final error response (from 300 1139 to 699) to its INVITE request. In this case, the underlying transaction 1140 engine takes care of sending ACK even when application-driven-ack mode is 1141 requested by application. 1142</td></tr> 1143<tr><td>C6b</td> 1144 <td>proceeding</td> 1145</tr> 1146 1147<tr><td>C7a</td> 1148 <td>calling</td> 1149 <td rowspan=2>nua_cancel()</td> 1150 <td rowspan=2>CANCEL</td> 1151 <td>calling</td> 1152 <td rowspan=2>-</td> 1153 <td rowspan=2> 1154 Client can ask server to cancel the call attempt while in @b calling or 1155 @b proceeding state. There is no direct call state transition caused by 1156 nua_cancel(). The call state changes when the server returns a response. 1157 After receiving a CANCEL request the server will usually return a <i>487 1158 Request Terminated</i> response and call is terminated as in previous 1159 item. 1160 1161 However, there is a race condition and the server can respond with a 1162 succesful 2XX response before receiving CANCEL. In that case, the call is 1163 established as usual. It is up to application to terminate the call with 1164 nua_bye(). 1165</td></tr> 1166<tr><td>C7b</td> 1167 <td>proceeding</td> 1168 <td>proceeding</td> 1169</tr> 1170<tr><td>C8a</td> 1171 <td>proceeding</td> 1172 <td>nua_bye()</td> 1173 <td>CANCEL</td> 1174 <td rowspan=2>terminating*</td> 1175 <td rowspan=2>-</td> 1176 <td> 1177 The call cannot be terminated with BYE before the dialog is established 1178 with a non-100 preliminary response. So, instead of a @b BYE, stack sends 1179 a @b CANCEL request, and enters terminating state. 1180 1181 However, there is a race condition and the server can respond with a 1182 succesful 2XX response before receiving CANCEL. If the server responds with 1183 a 2XX response, the nua will automatically send a BYE request asking server 1184 to terminate the call. 1185</td></tr> 1186<tr><td>C8b</td> 1187 <td>proceeding</td> 1188 <td>nua_bye()</td> 1189 <td>BYE</td> 1190<td> 1191 Even an early session can be terminated after entering @b proceeding 1192 state with nua_bye(). Stack sends a @b BYE request, and enters 1193 terminating state. Unlike @b CANCEL, @b BYE affects only one fork. 1194 1195 However, there is a race condition and the server can respond with a 1196 succesful 2XX response before receiving BYE. If the server responds with 1197 a 2XX response, the nua will automatically send a BYE request asking server 1198 to terminate the call. 1199</td></tr> 1200<tr><td>C9</td> 1201 <td>completing</td><td>nua_bye()</td><td>ACK<br>BYE</td><td>terminating</td> 1202 <td>-</td> 1203 <td> 1204 If the stack is in @b completing state (it has already 1205 received 2XX response), it will have to @b ACK the final response, too. 1206</td></tr> 1207 1208<tr><td>C10</td> 1209 <td>terminating*</td> 1210 <td>2XX<br>to INVITE</td> 1211 <td>BYE</td> 1212 <td>terminating</td> 1213 <td>-</td> 1214 <td> 1215 There is a race condition between @b BYE and @b INVITE. The call may have 1216 been re-established with @b INVITE after @b BYE was processed. @b BYE is 1217 re-sent and call state transitions to normal terminating state. 1218</td></tr> 1219 1220<tr><td>C11</td> 1221 <td>terminating*</td> 1222 <td>3XX 4XX<br>5XX 6XX<br>to INVITE</td> 1223 <td>BYE</td> 1224 <td>terminating</td> 1225 <td>-</td> 1226 <td> 1227 The @b INVITE transaction is completed without a call being created. The 1228 call state transitions to normal terminating state. 1229</td></tr> 1230 1231<tr><td>C12</td> 1232 <td>terminating</td> 1233 <td>3XX 4XX<br>5XX 6XX<br>to BYE</td> 1234 <td>-</td> 1235 <td>terminated</td> 1236 <td>-</td> 1237 <td> 1238 Call is terminated when the final response to the BYE is received. 1239</td></tr> 1240 1241</table> 1242 1243@section nua_uas_call_model Detailed Server-Side Call Model 1244 1245The detailed call model at server side (UAS) is presented below. This model 1246does not include the extensions like @b 100rel or @b UPDATE. 1247 1248@code 1249 1250 +----------------------------------+ 1251 | INIT | 1252 +----------------------------------+ 1253 | : : 1254 | : : 1255 (1) INVITE/100 (2b) INVITE/18X (3c) INVITE/2XX 1256 | : : 1257 | : : 1258 V : : 1259 +------------+ : : 1260 +--------------------| | : : 1261 | | RECEIVED |--------------+ : 1262 | +---------------| | : | : 1263 | | +------------+ : | : 1264 | | | : | : 1265 | | nua_respond/18X (2a) : | : 1266 | | | : | : 1267 | | V V | : 1268 | | +------------+ | : 1269 |<------------------------------| | | : 1270 | |<-------------------------| EARLY | | : 1271 | | +----------| | | : 1272 | | | +------------+ | : 1273 | nua_respond/ | | | : 1274 (6) /[3456]XX | nua_respond/2XX (3b) (3a) : 1275 | | | | | : 1276 | | | V V V 1277 | | | +-------------+ 1278 | | | | | 1279 | | | +-----| COMPLETED |- - + 1280 | | | | | | : 1281 | | | | +-------------+ : 1282 | | | | | : 1283 | | | | (4) ACK/- : 1284 | | | | | : 1285 | | | | V : 1286 | | | | +-------------+ : 1287 | | | | | | : 1288 | | | | | READY | : 1289 | | | | | | : 1290 | | | | +-------------+ : 1291 | | | | : 1292 | (7) CANCEL/487 (8) BYE/487 (9) BYE/200 (5) timeout 1293 | | | | : /BYE 1294 | | | | +-------------+ : 1295 | | | | | TERMINATING |<- -+ 1296 | | | | +-------------+ 1297 | | | | | 1298 | | | | | [23456]XX/- 1299 | | | | | 1300 | | | | V 1301 | V V V +-------------+ 1302 +---------------------------------------->| TERMINATED | 1303 +-------------+ 1304@endcode 1305 1306The detailed description of state transitions on the server side is as 1307follows: 1308<table> 1309<tr><th>#</th> 1310 <th>Previous state</th> 1311 <th>Input</th> 1312 <th>Output</th> 1313 <th>Next state</th> 1314 <th>Offer/ Answer</th> 1315 <th align="left">Description</th> 1316</tr> 1317<tr><td>S1</td> <!-- transition --> 1318 <td>init</td> <!-- previous state --> 1319 <td>INVITE</td> <!-- input --> 1320 <td>100 Trying</td> <!-- output --> 1321 <td>received</td> <!-- next state --> 1322 <td>Save offer</td> <!-- offer/answer --> 1323 <td> 1324 When a @b INVITE request for a new call is received, the server creates a 1325 fresh call handle for it, responds to the client with <i>100 Trying</i> 1326 and enters in the @b received state by default. It saves the possible SDP 1327 offer included in @b INVITE and passes it to the application. 1328</td></tr> 1329<tr><td>S2a</td> <!-- transition --> 1330 <td>received</td> <!-- previous state --> 1331 <td>nua_respond()</td> <!-- input --> 1332 <td>18X</td> <!-- output --> 1333 <td rowspan=2>early</td> <!-- next state --> 1334 <td>(Generate early answer)</td> <!-- offer/answer --> 1335 <td> 1336 When server returns a preliminary response for the initial @b INVITE request, 1337 a early dialog is created. The server can also send an SDP answer with 1338 the preliminary answer and establish an early session, too. It can use 1339 the early session to send early media, e.g., ringing tone and 1340 announcements towards the client. 1341</td></tr> 1342<tr><td>S2b</td> <!-- transition --> 1343 <td>init</td> <!-- previous state --> 1344 <td>INVITE and <!-- input --> 1345 @ref NUTAG_AUTOALERT() "auto-alert"</td> 1346 <td>180 Ringing</td> <!-- output --> 1347 <td>Save offer (and 1348 generate early answer)</td> <!-- offer/answer --> 1349 <td> 1350 When @ref NUTAG_AUTOALERT() "auto-alert" option is enabled, stack sends 1351 180 Ringing immediately after receiving INVITE and enters @b early state. 1352</td></tr> 1353<tr><td>S3a</td> <!-- transition --> 1354 <td>received</td> <!-- previous state --> 1355 <td rowspan=2>nua_respond()</td> <!-- input --> 1356 <td rowspan=2>2XX</td> <!-- output --> 1357 <td rowspan=3>completed</td> <!-- next state --> 1358 <td rowspan=2>Generate answer</td> <!-- offer/answer --> 1359 <td rowspan=2> 1360 When the server sends a 2XX response towards the client, it accepts the 1361 call. The @b INVITE transaction is now considered complete but unconfirmed 1362 at the server side. If the offer was sent in @b INVITE request, the answer 1363 should be included in the 2XX response. 1364</td></tr> 1365<tr><td>S3b</td> <!-- transition --> 1366 <td>early</td> <!-- previous state --> 1367</td></tr> 1368<tr><td>S3c</td> <!-- transition --> 1369 <td>init</td> <!-- previous state --> 1370 <td>INVITE and @ref NUTAG_AUTOANSWER() "auto-answer" 1371 </td> <!-- input --> 1372 <td>200 OK</td> <!-- output --> 1373 <td>Save offer and 1374 <br>generate answer</td> <!-- offer/answer --> 1375 <td> 1376 When @ref NUTAG_AUTOANSWER() "auto-answer" option is enabled, stack send 1377 200 OK immediately after receiving INVITE and enters @b completed state. 1378</td></tr> 1379</td></tr> 1380<tr><td>S4</td> <!-- transition --> 1381 <td>completed</td> <!-- previous state --> 1382 <td>ACK</td> <!-- input --> 1383 <td>-</td> <!-- output --> 1384 <td>ready</td> <!-- next state --> 1385 <td>-</td> <!-- offer/answer --> 1386 <td> 1387 The ready state is entered at server side after receiving @b ACK request 1388 from client, indicating that the client have received server's 2XX 1389 response. The call is ready, the @b INVITE transaction is confirmed. 1390</td></tr> 1391<tr><td>S5td> <!-- transition --> 1392 <td>completed</td> <!-- previous state --> 1393 <td>timeout</td> <!-- input --> 1394 <td>BYE</td> <!-- output --> 1395 <td>terminating</td> <!-- next state --> 1396 <td>-</td> <!-- offer/answer --> 1397 <td> 1398 If the server does not receive an @b ACK request in timely fashion, it will 1399 terminate the call by sending a @b BYE request to client. 1400</td></tr> 1401<tr><td>S6a</td> <!-- transition --> 1402 <td>received</td> <!-- previous state --> 1403 <td rowspan=2>nua_respond()</td> <!-- input --> 1404 <td rowspan=2>3XX 4XX<br>5XX 6XX</td><!-- output --> 1405 <td rowspan=2>terminated</td> <!-- next state --> 1406 <td rowspan=2>-</td> <!-- offer/answer --> 1407 <td rowspan=2> 1408 The server can reject the call by sending a 3XX, 4XX, 5XX, or 6XX response 1409 towards the client. The underlying transaction engine takes care of 1410 retransmitting the response when needed. It consumes the ACK response 1411 sent by the client, too. 1412</td></tr> 1413<tr><td>S6b</td> <!-- transition --> 1414 <td>early</td> <!-- previous state --> 1415</td></tr> 1416<tr><td>S7a</td> <!-- transition --> 1417 <td>received</td> <!-- previous state --> 1418 <td rowspan=2>CANCEL</td> <!-- input --> 1419 <td rowspan=2>487 Request terminated</td><!-- output --> 1420 <td rowspan=2>terminated</td> <!-- next state --> 1421 <td rowspan=2>-</td> <!-- offer/answer --> 1422 <td rowspan=2> 1423 The client can cancel the call attempt before it is completed with a @b 1424 CANCEL request. Server returns a <i>200 OK</i> response to @b CANCEL and 1425 a <i>487 Request Terminated</i> response to the @b INVITE transaction and 1426 the call is terminated. 1427</td></tr> 1428<tr><td>S7b</td> <!-- transition --> 1429 <td>early</td> <!-- previous state --> 1430</td></tr> 1431<tr><td>S8</td> <!-- transition --> 1432 <td>early</td> <!-- previous state --> 1433 <td>BYE</td> <!-- input --> 1434 <td>487 to INVITE<br> 1435 200 to BYE</td> <!-- output --> 1436 <td>terminated</td> <!-- next state --> 1437 <td>-</td> <!-- offer/answer --> 1438 <td> 1439 The client can terminate an early session with a @b BYE request, too. Like 1440 in the @b CANCEL case above, the server will terminate call immediately, 1441 return a <i>200 OK</i> response to @b BYE and a <i>487 Request 1442 Terminated</i> response to the @b INVITE transaction. 1443</td></tr> 1444<tr><td>S9</td> <!-- transition --> 1445 <td>completed</td> <!-- previous state --> 1446 <td>BYE</td> <!-- input --> 1447 <td>200 to BYE</td> <!-- output --> 1448 <td>terminated</td> <!-- next state --> 1449 <td>-</td> <!-- offer/answer --> 1450 <td> 1451 The client can terminate a completed dialog with a @b BYE request. Server 1452 terminates call immediately, returns a <i>200 OK</i> response to @b BYE 1453 and lets the underlying transaction engine to take care of consuming @b 1454 ACK. 1455</td></tr> 1456</table> 1457 1458@section nua_3pcc_call_model Third Party Call Control 1459 1460There is an alternative offer-answer model for third party call control 1461(3pcc). The call setup involves a 3rd party, client C, which sends initial 1462INVITE to server A without SDP. The call setup looks perfectly ordinary to 1463server B, however. 1464 1465@code 1466 A C B 1467 | | | 1468 |<-------INVITE---------| | 1469 | | | 1470 | | | 1471 |------200 (offer)----->| | 1472 | |----INVITE (offer)---->| 1473 | | | 1474 | | | 1475 | |<-----200 (answer)-----| 1476 |<-----ACK (answer)-----| | 1477 | | | 1478 | |----------ACK--------->| 1479 | | | 1480@endcode 1481 1482The modifications to the call model affect mainly offer-answer model. 1483The detailed description of state transitions for 3pcc on the server side is as 1484follows: 1485 1486<table> 1487<tr><th>#</th> 1488 <th>Previous state</th> 1489 <th>Input</th> 1490 <th>Output</th> 1491 <th>Next state</th> 1492 <th>Offer/ Answer</th> 1493 <th align="left">Description</th> 1494</tr> 1495<tr><td>S1'</td> <!-- transition --> 1496 <td>init</td> <!-- previous state --> 1497 <td>INVITE</td> <!-- input --> 1498 <td>100 Trying</td> <!-- output --> 1499 <td>received</td> <!-- next state --> 1500 <td>-</td> <!-- offer/answer --> 1501 <td> 1502 There is no SDP to save. 1503</td></tr> 1504<tr><td>S2b'</td> <!-- transition --> 1505 <td>init</td> <!-- previous state --> 1506 <td>INVITE and <!-- input --> 1507 @ref NUTAG_AUTOALERT() "auto-alert"</td> 1508 <td>180 Ringing</td> <!-- output --> 1509 <td>early</td> <!-- next state --> 1510 <td>-</td> <!-- offer/answer --> 1511 <td> 1512 There is no SDP to save. 1513</td></tr> 1514<tr><td>S3a'</td> <!-- transition --> 1515 <td>early</td> <!-- previous state --> 1516 <td rowspan=2>nua_respond()</td> <!-- input --> 1517 <td rowspan=2>2XX</td> <!-- output --> 1518 <td rowspan=3>completed</td> <!-- next state --> 1519 <td rowspan=3>Generate offer</td> <!-- offer/answer --> 1520 <td rowspan=3> 1521 The offer is sent in 200 OK. 1522</td></tr> 1523<tr><td>S3b'</td> <!-- transition --> 1524 <td>received</td> <!-- previous state --> 1525</td></tr> 1526<tr><td>S3c'</td> <!-- transition --> 1527 <td>init</td> <!-- previous state --> 1528 <td>INVITE and <!-- input --> 1529 @ref NUTAG_AUTOANSWER() "auto-answer"</td> 1530 <td>200 OK</td> <!-- output --> 1531</td></tr> 1532<tr><td>S4'</td> <!-- transition --> 1533 <td>completed</td> <!-- previous state --> 1534 <td>ACK</td> <!-- input --> 1535 <td>-</td> <!-- output --> 1536 <td>ready</td> <!-- next state --> 1537 <td>Save and process answer</td> <!-- offer/answer --> 1538 <td> 1539 The answer is processed and media activated after receiving @b ACK. 1540</td></tr> 1541<tr><td>S9b'</td> <!-- transition --> 1542 <td>completed</td> <!-- previous state --> 1543 <td>ACK and O/A error</td> <!-- input --> 1544 <td>BYE</td> <!-- output --> 1545 <td>terminating</td> <!-- next state --> 1546 <td>Save and process answer</td> <!-- offer/answer --> 1547 <td> 1548 If the offer/answer negotiation ends in error after the server receives 1549 answer in @b ACK request, the server will have to terminate call by 1550 sending a @b BYE request. 1551</td></tr> 1552</table> 1553 1554 1555@section nua_terminate_call_model Model for Modifying and Terminating Call 1556 1557After the SIP session has been established, it can be further modified by @b 1558INVITE transactions, initiated by either the original client or the original 1559server. These so-called re-INVITE transactions can be used to upgrade 1560session (add new media to it), put the session on hold or resume a held 1561call. 1562 1563A session can be terminated with a @b BYE request at any time. 1564 1565If any in-dialog request (including re-INVITE) fails with certain response 1566code, the session can be considered terminated, too. These response codes 1567are documented with sip_response_terminates_dialog(). In some cases, the 1568session should be terminated gracefully by sending a @b BYE request after 1569the failed requests. 1570 1571@code 1572 +-------------------------------------------------------------+ 1573 | READY | 1574 +-------------------------------------------------------------+ 1575 | | | | 1576 | | | | 1577 (1) BYE/200 (2) nua_bye/BYE (4) graceful/BYE (5) fatal/- 1578 | | | | 1579 | V V | 1580 | +-----------------------------+ | 1581 | | TERMINATING | | 1582 | +-----------------------------+ | 1583 | | | 1584 | (3) [23456]XX/- | 1585 | | | 1586 V V V 1587 +-------------------------------------------------------------+ 1588 | TERMINATED | 1589 +-------------------------------------------------------------+ 1590@endcode 1591 1592The detailed description of state transitions while call is terminated is as 1593follows: 1594<table> 1595<tr><th>#</th> 1596 <th>Previous state</th> 1597 <th>Input</th> 1598 <th>Output</th> 1599 <th>Next state</th> 1600 <th align="left">Description</th> 1601</tr> 1602<tr><td>T1</td> <!-- transition --> 1603 <td>ready</td> <!-- previous state --> 1604 <td>BYE</td> <!-- input --> 1605 <td>200 OK</td> <!-- output --> 1606 <td>terminated</td> <!-- next state --> 1607 <td> 1608 When the @b BYE request is received, the recipient terminates the 1609 currently ongoing @b INVITE transaction, the session and its dialog 1610 usage (if there is another dialog usage active, e.g., a subscription 1611 creted by @b REFER.) 1612</td></tr> 1613<tr><td>T2</td> <!-- transition --> 1614 <td>ready</td> <!-- previous state --> 1615 <td>nua_bye</td> <!-- input --> 1616 <td>BYE</td> <!-- output --> 1617 <td>terminating</td> <!-- next state --> 1618 <td> 1619 The application terminates the session by calling nua_bye(). All the 1620 call-related requests on the dialog are rejected while in 1621 terminating state with <i>487 No Such Call</i> response. 1622</td></tr> 1623<tr><td>T3</td> <!-- transition --> 1624 <td>terminating</td> <!-- previous state --> 1625 <td>2XX 3XX 4XX 5XX 6XX</td> <!-- input --> 1626 <td>-</td> <!-- output --> 1627 <td>terminated</td> <!-- next state --> 1628 <td> 1629 The session is finally terminated when a final response to @b BYE is 1630 received. Note that nua stack does retry @b BYE requests. 1631</td></tr> 1632<tr><td>T4</td> <!-- transition --> 1633 <td>ready</td> <!-- previous state --> 1634 <td>"graceful" response</td> <!-- input --> 1635 <td>BYE</td> <!-- output --> 1636 <td>terminating</td> <!-- next state --> 1637 <td> 1638 A call-related request (@b re-INVITE, @b UPDATE, @b INFO, @b PRACK, 1639 @b REFER) fails with a response code indicating that the client 1640 should gracefully terminate the call. 1641</td></tr> 1642<tr><td>T5</td> <!-- transition --> 1643 <td>ready</td> <!-- previous state --> 1644 <td>"fatal" response</td> <!-- input --> 1645 <td>-</td> <!-- output --> 1646 <td>terminated</td> <!-- next state --> 1647 <td> 1648 A call-related request (@b re-INVITE, @b UPDATE, @b INFO, @b PRACK, 1649 @b REFER) fails with a response code indicating that the call has 1650 been terminated. 1651</td></tr> 1652</table> 1653 1654@sa http://www.ietf.org/internet-drafts/draft-sparks-sipping-dialogusage-01.txt 1655@sa sip_response_terminates_dialog() 1656 1657*/ 1658 1659/* 1660For reference: 1661 1662 +---------------+ 1663 +-(1)--| INIT |-----+ 1664 INVITE/- | +---------------+ (A) INVITE/100 1665 V | 1666 +------------+ +------------+ 1667 +----| CALLING | +---| RECEIVED |--+ 1668 | +------------+ | +------------+ | 1669 | | | | | 1670 | (2) 18X/- | (B) -/18X | 1671 | V | V | 1672 | +------------+ | +------------+ | 1673 |<---| PROCEEDING |--+ | | EARLY |->| 1674 | +------------+ | | +------------+ (F) -/[3456]XX 1675 | : | | | | 1676 | (4) 2XX/- | (E) -/2XX (C) -/2XX | or 1677 | V | | V | 1678 | + - - - - - -+ | | +------------+ (G) CANCEL/200,487 1679 | : COMPLETING : | +-->| COMPLETE | | 1680 | + - - - - - -+ | +------------+ | 1681 | : | | : | 1682 | (5)-/ACK (3) 2XX/ACK ACK/-(D) : | 1683 | : | | : | 1684 | : V | : | 1685 | : +---------------+ | : | 1686 | + - - >| READY |<----+ : | 1687 | +---------------+ : | 1688 | | | : | 1689 | BYE/200 (i) (ii) -/BYE timeout/ : | 1690 | | | BYE (H) | 1691 | | V : | 1692 | | +--------------+ : | 1693 (6) [3456]XX/ACK | | TERMINATING |<- - + | 1694 | | +--------------+ | 1695 | | | | 1696 | | (iii) [23456]XX/- | 1697 | V V | 1698 | +---------------+ | 1699 +---------------->| TERMINATED |<--------------+ 1700 +---------------+ 1701 | 1702 V 1703 INIT 1704 1705*/ 1706 1707/**@page nua_event_diagrams NUA Event Diagrams 1708 1709The example diagrams below try to present how to use NUA API with different 1710SIP use cases. 1711 1712@section nua_event_diagram_call Basic Call 1713 1714The SIP following event diagram shows a pretty simple, succesful call case. 1715The nua events and nua function calls are show in the diagram below as well 1716as the SIP messages. 1717 1718The call setup above assumes parameters NUTAG_AUTOALERT(0), 1719NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side. 1720 1721@code 1722 1723 Alice Proxy Bob 1724 0 | | | 1725 1 nua_handle() | | | 1726 2 nua_invite() -> |-----INVITE---->| | 1727 3 nua_i_state <- | | | 1728 4 | |-----INVITE---->| -> nua_i_invite 1729 5 |<--100 Trying---| | -> nua_i_state 1730 6 | | | 1731 7 | | | 1732 8 | | | 1733 9 | |<--180 Ringing--| <- nua_respond(180) 173410 nua_i_invite <- |<--180 Ringing--| | -> nua_i_state 173511 nua_i_state <- | | | 173612 | |<--200 OK-------| <- nua_respond(200) 173713 nua_i_invite <- |<---200 OK------| | -> nua_i_state 173814 nua_i_state <- | | | 173915 nua_ack() -> |-----ACK------->| | 174016 nua_i_state <- | |-----ACK------->| -> nua_i_ack 174117 | | | -> nua_i_state 174218 | | | 174319 <<====== SIP Session Established =======>> 174420 | | | 174521 | | | 174622 nua_bye() -> |-----BYE------->| | 174723 | |-----BYE------->| -> nua_i_bye 174824 | |<----200 OK-----| -> nua_i_state 174925 nua_r_bye <- |<---200 OK------| | 175026 nua_i_state <- | | | 1751 | | | 1752@endcode 1753 1754@section nua_event_diagram_call_hold Holding Call 1755 1756The media (audio, video) can be put on hold. In SIP system this means that 1757application can indicate to the remote end that it is engaged in other 1758activity (another call, for instance) and does not wish to receive media 1759from the remove end. 1760 1761The call hold is usully implemented using re-INVITE. Re-INVITE is an INVITE 1762request sent on existing SIP session. Both original caller and callee can 1763send re-INVITEs. The main use of re-INVITE is modifying sessions: adding 1764media lines to the session, changing codecs on existing media, and, as you 1765might expect, putting existing media on hold as well as resuming media from 1766hold. 1767 1768A re-INVITE is sent by calling nua_invite() on handle with existing call. 1769When putting call on hold, the application can include SOATAG_HOLD("audio") 1770or SOATAG_HOLD("video") or SOATAG_HOLD("audio, video") or SOATAG_HOLD("*") 1771as parameters to re-INVITE nua_invite(). (Note that last SOATAG_HOLD() in 1772the tag list will override the SOATAG_HOLD() tags before it.) 1773 1774Another feature where nua tries to be helpful is autoanswer and auto-ACK on 1775existing sessions: the re-INVITE is automatically responded with <i>200 OK</i> 1776and ACK is automatically sent. (If the application wants to respond and ACK 1777by itself, it should explicitly set NUTAG_AUTOANSWER(0) and/or 1778NUTAG_AUTOACK(0) in the handle; either include them in nua_invite() or 1779nua_respond() parameters or call nua_set_hparams() explicitly. 1780 1781@code 1782 Alice Proxy Bob 1783 0 nua_handle() | | | 1784 1 | | | 1785 2 nua_invite() -> |-----INVITE---->| | 1786 3 nua_i_state <- | | | 1787 4 | |-----INVITE---->| -> nua_i_invite 1788 5 |<--100 Trying---| | -> nua_i_state 1789 6 | | | 1790 7 | | | 1791 8 | | | 1792 9 | |<--180 Ringing--| <- nua_respond(180) 179310 nua_i_invite <- |<--180 Ringing--| | -> nua_i_state 179411 nua_i_state <- | | | 179512 | |<--200 OK-------| <- nua_respond(200) 179613 nua_i_invite <- |<---200 OK------| | -> nua_i_state 179714 nua_i_state <- | | | 179815 nua_ack() -> |-----ACK------->| | 179916 nua_i_state <- | |-----ACK------->| -> nua_i_ack 180017 | | | -> nua_i_state 180118 | | | 180219 <<== Bi-Directional RTP Established ==>> 180320 | | | 180421 | | | 180522 | |<--INVITE(hold)-| <- nua_invite(.. 180621 | | | NUTAG_HOLD("*")..) 180723 nua_i_invite <- |<-INVITE(hold)--| | -> nua_i_state 180825 nua_i_state <- |----200 OK----->| | 180926 | |----200 OK----->| -> nua_i_invite 181028 | |<-----ACK-------| -> nua_i_state 181129 nua_i_ack <- |<----ACK--------| | 181224 | | | 181330 <<== Uni-Directional RTP Established ==>> 181424 | | | 181531 | | | 181632 | |<--INVITE-------| <- nua_invite(.. 181721 | | | NUTAG_HOLD(NULL)..) 181833 nua_i_invite <- |<--INVITE-------| | -> nua_i_state 181935 nua_i_state <- |---200 OK------>| | 182036 | |---200 OK------>| -> nua_i_invite 182138 | |<----ACK--------| -> nua_i_state 182239 nua_i_ack <- |<----ACK--------| | 182340 nua_i_state <- | | | 182419 <<== Bi-Directional RTP Established ==>> 182542 | | | 182643 nua_bye() -> |-----BYE------->| | 182744 nua_i_state <- | |-----BYE------->| -> nua_i_bye 182846 | |<----200 OK-----| -> nua_i_state 182947 |<---200 OK------| | 1830 | | | 1831@endcode 1832 1833 1834 1835@section nua_event_diagram_call_transfer Call Transfer 1836 1837This is the unattended call transfer case. 1838 18391st MSC showing Alice's end: 1840 1841@code 1842 Alice Bob Carol 1843 0 | | | 1844 1 nua_i_invite <- |<-----INVITE--------| | 1845 2 nua_i_state <- | | | 1846 2 | | | 1847 3 nua_respond(180) -> |----180 Ringing---->| | 1848 2 nua_i_state <- | | | 1849 4 | | | 1850 5 nua_respond(200) -> |------200 OK------->| | 1851 6 nua_i_state <- | | | 1852 8 | | | 1853 7 nua_i_ack <- |<-------ACK---------| | 1854 8 nua_i_state <- | | | 1855 9 |<========RTP=======>| | 185610 | | | 185711 << Alice performs unattended transfer >> | 185812 | | | 185913 | | | 186014 nua_refer() -> |---REFER("r: C")--->| | 186115 | | | 186216 nua_r_refer <- |<---202 Accepted----| | 186317 | | | 186418 nua_i_notify <- |<-----NOTIFY--------| | 186519 | | | 186620 |------200 OK------->| | 186721 | |---INVITE("b: A")-->| 186823 | | | 186922 nua_bye() -> |-------BYE--------->| | 187023 | | | 187124 nua_r_bye <- |<----200 OK---------| | 187225 nua_i_state <- | No RTP Session | | 187328 | |<----180 Ringing----| 187426 nua_i_notify <- |<- - -NOTIFY - - - -| | 187527 | | | 187620 |- - - 200 OK- - - ->| | 187729 | | | 187830 | |<------200 OK-------| 187931 | | | 188032 | |---------ACK------->| 188133 | | RTP | 188234 | |<==================>| 188335 | | | 188436 |<-----NOTIFY--------| | 188537 | | | 188638 |------200 OK------->| | 1887 | | | 1888@endcode 1889 18902nd MSC showing Bobs's end: 1891 1892@code 1893 Alice Bob (nh1) Bob (nh2) Carol 1894 0 | | | | 1895 1 |<-----INVITE--------| | | 1896 2 | | | | 1897 3 |---180 Ringing----->| | | 1898 4 | | | | 1899 5 |------200 OK------->| | | 1900 6 | | | | 1901 7 |<-------ACK---------| | | 1902 8 | RTP | | | 1903 9 |<==================>| | | 190410 | | | | 190511<< Alice performs unattended transfer >> | | 190612 | | | | 190713 | Refer-To:C F5| | | 190814 |-REFER------------->| -> nua_i_refer | | 190915 | | | | 191016 |<-202 Accepted------| | | 191117 | | | | 191218 |<-----NOTIFY--------| | | 191319 | | | | 191420 |------200 OK------->| -> nua_r_notify | | 191521 | | | | 191622 |-------BYE--------->| -> nua_i_bye | | 191723 | | -> nua_i_state | | 191824 |<----200 OK---------| nua_handle() -> | | 191925 | No RTP Session | nua_invite() -> | | 192026 | | |--INVITE("b: A")--->| 192127 | | | | 192228 | | nua_i_invite <- |<--180 Ringing------| 192329 | | nua_i_state <- | | 192430 | | nua_i_invite <- |<----200 OK---------| 192531 | | nua_i_state <- | | 192632 | | nua_ack -> |-------ACK--------->| 192733 | | | | 192834 | | |<=======RTP========>| 192935 | | | | 193036 |<-----NOTIFY--------| | | 193137 | | 193238 |------200 OK------->| -> nua_r_notify 193339 | | <- nua_handle_destroy 1934 | | 1935@endcode 1936 1937Bob includes nh1 in nua_invite()/25 as NUTAG_NOTIFY_REFER() parameter. 1938 1939Open Issue 1: 1940 1941- how Bob know when to destroy nh1? 1942 1943 1944@section nua_event_diagram_3gpp_call 3GPP Call Model 1945 1946The 3GPP call model is defined in 3GPP TS 24.229. In order to select only a 1947single codec and ensure that the QoS reservationa are made before the call 1948is alerting, the 3GPP call model employs multiple offer/answer exchanges. It 1949uses 100rel and PRACK (@RFC3262), UPDATE (@RFC3311) and preconditions 1950(@RFC3312) extensions specified by IETF. 1951 1952The call setup below assumes parameters NUTAG_AUTOALERT(0), 1953NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side. 1954 1955@code 1956 A B 1957 0 nua_handle() | | 1958 1 nua_invite() -> | | 1959 2 nua_i_state <- |----INVITE (offer)---->| 1960 3 | | -> nua_i_invite 1961 4 | | -> nua_i_state 1962 5 | | 1963 6 | | <- nua_respond(183) 1964 7 nua_i_invite <- |<----183 (answer)------| -> nua_i_state 1965 8 nua_i_state <- | | 1966 9 << single codec is selected now >> 196710 |-----PRACK(offer2)---->| -> nua_i_prack 196811 | | -> nua_i_state 196912 nua_r_prack <- |<--200/PRACK(answer2)--| 197013 | | 197114 | | 197215 << resource reservations are done now >> 197316 | | 197417 nua_update() -> |----UPDATE (offer3)--->| 197518 nua_i_state <- | | 197619 nua_i_state <- |<-200/UPDATE (answer3)-| -> nua_i_update 197720 | | -> nua_i_state 197821 | | 197922 | | << B rings >> 198023 | | 198124 | | <- nua_respond(180) 198225 nua_i_invite <- |<---------180----------| 198326 nua_i_state <- | | 198427 |--------PRACK--------->| -> nua_i_prack 198528 nua_r_prack <- |<-----200/PRACK------->| -> nua_i_state 198629 | | 198730 | | <- nua_respond(200) 198831 nua_i_invite <- |<---------200----------| -> nua_i_state 198932 nua_i_state <- | | 199033 nua_ack() -> | | 199134 nua_i_state <- |----------ACK--------->| -> nua_i_ack 199235 | | -> nua_i_state 1993 | | 1994@endcode 1995 1996*/ 1997 1998/**@var nua_event_e 1999 * 2000 * @brief Events 2001 * 2002 * The NUA event loop calls an event callback function when an application 2003 * needs to act on something that happened in the Sofia stack. The callback 2004 * function is registered when nua_create() function call is used to create 2005 * the NUA stack object. 2006 * 2007 * The prototype of the event callback function is: 2008 * @code 2009 * void nua_callback_f(nua_event_t event, 2010 * int status, 2011 * char const *phrase, 2012 * nua_t *nua, 2013 * nua_magic_t *magic, 2014 * nua_handle_t *nh, 2015 * nua_hmagic_t *hmagic, 2016 * sip_t const *sip, 2017 * tagi_t tags[]); 2018 * @endcode 2019 * 2020 * @param event Callback event identification. \n 2021 * Always present 2022 * @param status Protocol status code. \n 2023 * Always present 2024 * @param phrase Text corresponding to status code. \n 2025 * Always present 2026 * @param nua Pointer to NUA stack object. \n 2027 * Always present 2028 * @param magic Pointer to callback context from nua_create(). \n 2029 * Always present 2030 * @param nh Pointer to operation handle. 2031 * @param hmagic Pointer to callback context from nua_handle(). 2032 * @param sip Headers in parsed incoming message. May be NULL. 2033 * See also nua_current_request(). 2034 * @param tags Tag list containing more information about the state of NUA. 2035 * May be empty. 2036 * 2037 * Note that the contents of the last four parameters vary depending on 2038 * the event. The descriptions can be found from the description of the 2039 * individual event. 2040 * 2041 * The events can be divided into the following categories: \n 2042 * @par Status or Error Indications: 2043 * #nua_i_active \n 2044 * #nua_i_error \n 2045 * #nua_i_fork \n 2046 * #nua_i_media_error \n 2047 * #nua_i_subscription \n 2048 * #nua_i_state \n 2049 * #nua_i_terminated 2050 * 2051 * @par SIP requests: 2052 * #nua_i_ack \n 2053 * #nua_i_bye \n 2054 * #nua_i_cancel \n 2055 * #nua_i_chat \n 2056 * #nua_i_info \n 2057 * #nua_i_invite \n 2058 * #nua_i_message \n 2059 * #nua_i_method \n 2060 * #nua_i_notify \n 2061 * #nua_i_options \n 2062 * #nua_i_prack \n 2063 * #nua_i_publish \n 2064 * #nua_i_refer \n 2065 * #nua_i_register \n 2066 * #nua_i_subscribe \n 2067 * #nua_i_update 2068 * 2069 * @par Responses: 2070 * #nua_r_get_params \n 2071 * #nua_r_notifier \n 2072 * #nua_r_shutdown \n 2073 * #nua_r_terminate 2074 * 2075 * @par SIP responses: 2076 * #nua_r_bye \n 2077 * #nua_r_cancel \n 2078 * #nua_r_info \n 2079 * #nua_r_invite \n 2080 * #nua_r_message \n 2081 * #nua_r_notify \n 2082 * #nua_r_options \n 2083 * #nua_r_prack \n 2084 * #nua_r_publish \n 2085 * #nua_r_refer \n 2086 * #nua_r_register \n 2087 * #nua_r_subscribe \n 2088 * #nua_r_unpublish \n 2089 * #nua_r_unregister \n 2090 * #nua_r_unsubscribe \n 2091 * #nua_r_update 2092 * 2093 * @sa nua_event_is_incoming_request(), nua_event_name() 2094 */ 2095 2096/** @NUA_EVENT nua_i_chat 2097 * 2098 * Incoming chat message. 2099 * 2100 * @param nh operation handle associated with the message 2101 * @param hmagic operation magic associated with the handle 2102 * @param sip incoming chat message 2103 * @param tags empty 2104 * 2105 * @END_NUA_EVENT 2106 */ 2107 2108/** @NUA_EVENT nua_i_error 2109 * 2110 * Error indication. 2111 * 2112 * Will be sent when an internal error happened or 2113 * an error occurred while responding a request. 2114 * 2115 * @param status SIP status code or NUA status code (>= 900) 2116 * describing the problem 2117 * @param phrase a short textual description of @a status code 2118 * @param nh NULL or operation handle associated with the call 2119 * @param hmagic NULL or operation magic associated with the call 2120 * @param sip NULL 2121 * @param tags empty or error specific information 2122 * 2123 * @END_NUA_EVENT 2124 */ 2125 2126/** @NUA_EVENT nua_i_fork 2127 * 2128 * Outgoing call has been forked. 2129 * 2130 * This is sent when an INVITE request is answered with multiple 2XX series 2131 * responses. 2132 * 2133 * @param status response status code 2134 * @param phrase a short textual description of @a status code 2135 * @param nh operation handle associated with the original call 2136 * @param hmagic operation magic associated with the original call 2137 * @param sip preliminary or 2XX response to INVITE 2138 * @param tags NUTAG_HANDLE() of the new forked call 2139 * 2140 * @sa #nua_r_invite, #nua_i_state, @ref nua_call_model 2141 * 2142 * @END_NUA_EVENT 2143 */ 2144 2145/** @NUA_EVENT nua_i_media_error 2146 * 2147 * Media error indication. 2148 * 2149 * This may be sent after an SOA operation has failed while processing 2150 * incoming or outgoing call. 2151 * 2152 * @param status SIP status code or NUA status code (>= 900) 2153 * describing the problem 2154 * @param phrase a short textual description of @a status code 2155 * @param nh operation handle associated with the call 2156 * @param hmagic operation magic associated with this handle 2157 * (maybe NULL if call handle was created for this call) 2158 * @param sip NULL 2159 * @param tags empty 2160 * 2161 * @END_NUA_EVENT 2162 */ 2163 2164/* nua_i_message is documented with nua_stack_process_message() */ 2165 2166/* nua_i_method is documented with nua_stack_process_method() */ 2167 2168/** @NUA_EVENT nua_i_network_changed 2169 * 2170 * Local IP(v6) address has changed. 2171 * 2172 * @param nh default operation handle 2173 * @param hmagic operation magic associated with the default operation handle 2174 * @param sip NULL 2175 * @param tags empty 2176 * 2177 * @since Experimental in @VERSION_1_12_2. 2178 * 2179 * @END_NUA_EVENT 2180 */ 2181 2182/* nua_i_notify is documented with nua_stack_process_notify() */ 2183 2184/* nua_i_options is documented with nua_stack_process_options() */ 2185 2186/* nua_i_publish is documented with nua_stack_process_publish() */ 2187 2188/* nua_i_refer is documented with nua_stack_process_refer() */ 2189 2190/* nua_i_subscribe is documented with nua_stack_process_subscribe() */ 2191 2192/** @NUA_EVENT nua_i_subscription 2193 * 2194 * Incoming subscription to be authorized. 2195 * 2196 * This event is launched by nua_notifier() to inform application of the 2197 * current state of the subscriber. The subscriber state is included in the 2198 * NUTAG_SUBSTATE() tag. If the state is #nua_substate_pending or 2199 * #nua_substate_embryonic, application should to authorize the subscriber 2200 * with nua_authorize(). 2201 * 2202 * @param nh operation handle associated with the notifier 2203 * @param hmagic operation magic 2204 * @param status statuscode of response sent automatically by stack 2205 * @param sip incoming SUBSCRIBE request 2206 * @param tags NEATAG_SUB(), 2207 * NUTAG_SUBSTATE() 2208 * 2209 * @sa nua_notifier(), #nua_i_subscribe, nua_authorize(), nua_terminate() 2210 * @RFC3265 2211 * 2212 * @END_NUA_EVENT 2213 */ 2214 2215/* nua_i_update is documented with nua_stack_process_update() */ 2216 2217/* nua_r_bye is documented with process_response_to_bye() */ 2218 2219/* nua_r_cancel is documented with process_response_to_cancel() */ 2220 2221/** @NUA_EVENT nua_r_chat 2222 * 2223 * Answer to outgoing chat message. 2224 * 2225 * @param nh operation handle associated with the notifier 2226 * @param hmagic operation magic associated with the notifier 2227 * @param sip response to MESSAGE request or NULL upon an error 2228 * (error code and message are in status and phrase parameters) 2229 * @param tags empty 2230 * 2231 * @sa nua_chat(), #nua_r_message 2232 * 2233 * @END_NUA_EVENT 2234 */ 2235 2236/* nua_r_info is documented with process_response_to_info() */ 2237 2238/* nua_r_invite is documented with process_response_to_invite() */ 2239 2240/* nua_r_message is documented with process_response_to_message() */ 2241 2242/** @NUA_EVENT nua_r_notifier 2243 * 2244 * Answer to nua_notitier() 2245 * 2246 * @param nh operation handle associated with the call 2247 * @param hmagic operation magic associated with the call 2248 * @param sip NULL 2249 * @param tags SIPTAG_EVENT() \n 2250 * SIPTAG_CONTENT_TYPE() 2251 * 2252 * @sa nua_notitier(), #nua_i_subscription, @RFC3265 2253 * 2254 * @END_NUA_EVENT 2255 */ 2256 2257/* nua_r_notify is documented with process_response_to_notify() */ 2258 2259/* nua_r_options is documented with process_response_to_options() */ 2260 2261/* nua_r_prack is documented with process_response_to_prack() */ 2262 2263/* nua_r_publish is documented with process_response_to_publish() */ 2264 2265/* nua_r_refer is documented with process_response_to_refer() */ 2266 2267/* nua_r_shutdown is documented with nua_stack_shutdown() */ 2268 2269/* nua_r_subscribe is documented with process_response_to_subscribe() */ 2270 2271/** @NUA_EVENT nua_r_terminate 2272 * 2273 * Answer to nua_terminate(). 2274 * 2275 * @param nh operation handle associated with the notifier 2276 * @param hmagic operation magic associated with the notifier 2277 * @param sip NULL 2278 * @param tags empty 2279 * 2280 * @sa nua_terminate(), nua_handle_destroy() 2281 * 2282 * @END_NUA_EVENT 2283 */ 2284 2285/* nua_r_unsubscribe is documented with process_response_to_subscribe() */ 2286
