nua.docs

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

  /* release operation context information */
  su_free(appl->home, hmagic);

} /* app_i_bye */
@endcode

@subsection nua_sendamessage Sending a message

The following functions show an example of how a SIP MESSAGE is sent.

The send_message() function sends the SIP MESSAGE.

@code
void send_message(void)
{
  op_t *op;

  /* create operation context information */
  op = su_zalloc(appl->home, sizeof(op_t));
  if (op = NULL) {
    printf("cannot create operation context information\n");
    return;
  }

  /* how we create destination_address? */

  /* create operation handle */
  op->handle = nua_handle(appl->nua,
                                op,
                                NUTAG_URL(destination_address),
                                TAG_END());

  if (op->handle == NULL) {
    printf("cannot create operation handle\n");
    return;
  }

  /* send MESSAGE */
  nua_message(op->handle,
               SIPTAG_CONTENT_TYPE_STR("text/plain"),
               SIPTAG_PAYLOAD_STR("Hello, world!"),
               /* other tags as needed ... */
               TAG_END());

} /* send_message */
@endcode

The app_r_message() function is called by the callback function when
answer to the MESSAGE is received.

@code
void app_r_message(int           status,
                    char const   *phrase,
                    nua_t        *nua,
                    nua_magic_t  *magic,
                    nua_handle_t *nh,
                    nua_hmagic_t *hmagic,
                    sip_t const  *sip,
                    tagi_t        tags[])
{
  printf("response to MESSAGE: %03d %s\n", status, phrase);
} /* app_r_message */
@endcode

@subsection nua_receivemessage Receiving a message

The following function shows an example of how a SIP MESSAGE is received.

The app_i_message() function is called by the callback function when
a SIP MESSAGE is received.

@code
void app_i_message(int           status,
                   char const   *phrase,
                   nua_t        *nua,
                   nua_magic_t  *magic,
                   nua_handle_t *nh,
                   nua_hmagic_t *hmagic,
                   sip_t const  *sip,
                   tagi_t        tags[])
{
  printf("received MESSAGE: %03d %s\n", status, phrase);

  printf("From: %s%s" URL_PRINT_FORMAT "\n",
         sip->sip_from->a_display ? sip->sip_from->a_display : "",
         sip->sip_from->a_display ? " " : "",
         URL_PRINT_ARGS(sip->sip_from->a_url));

  if (sip->sip_subject) {
    printf("Subject: %s\n", sip->sip_subject->g_value);
  }

  if (sip->sip_payload) {
    fwrite(sip->sip_payload->pl_data, sip->sip_payload->pl_len, 1, stdout);
    fputs("\n", stdout);
  }
} /* app_i_message */
@endcode

@subsection nua_notifier Creating a Presence Server

@code

...
  application_t *app;
  operation_t   *oper;

...

  oper->app = app;


  app->nua = nua_create(ssip->s_root,
                        app_callback,
                        app,
                        TAG_NULL());
...

  oper->handle = nua_handle(app->nua, app,
                            NUTAG_URL(to->a_url),
                            SIPTAG_TO(to),
                            ta_tags(ta));
...

    nua_notifier(oper->handle,
		 SIPTAG_EXPIRES_STR("3600"),
		 SIPTAG_EVENT_STR("presence"),
		 SIPTAG_CONTENT_TYPE_STR("application/pidf-partial+xml"),
		 NUTAG_SUBSTATE(nua_substate_pending),
		 TAG_END());
@endcode

After the nua_notifier object -- the presence server -- is created, an
event nua_r_notifier is returned. Status and phrase values of the
app_callback function indicate the success of the creation.

Authorization of an incoming subscription (to the local presence
server) can be handled in the callback function.

@code
void app_callback(nua_event_t event,
                  int status, char const *phrase,
                  nua_t *nua, application_t *app,
                  nua_handle_t *nh, oper_t *op,
                  sip_t const *sip, tagi_t tags[])
{
  nea_sub_t *subscriber = NULL;

  switch (event) {
  case nua_i_subscription:
    tl_gets(tags,
	    NEATAG_SUB_REF(subscriber),
	    TAG_END());


    nua_authorize(nua_substate_active);


  default:
    break;
}


@endcode


@subsection nua_shutting_down Shutdown

The following functions show an example of how application terminates
the NUA stack.

The shutdown() function starts the termination.

@code
void shutdown(void)
{
  nua_shutdown(appl->nua);

} /* shutdown */
@endcode

The app_r_shutdown() function is called by the callback function when NUA
stack termination is either finished or failed.

@code
void app_r_shutdown(int           status,
                    char const   *phrase,
                    nua_t        *nua,
                    nua_magic_t  *magic,
                    nua_handle_t *nh,
                    nua_hmagic_t *hmagic,
                    sip_t const  *sip,
                    tagi_t        tags[])
{
  printf("shutdown: %d %s\n", status, phrase);

  if (status < 200) {
    /* shutdown in progress -> return */
    return;
  }

  /* end the event loop. su_root_run() will return */
  su_root_break(magic->root);

} /* app_r_shutdown */
@endcode

*/

/** @page nua_call_model NUA Call Model

The NUA call follows a relatively simple state model presented below. The call
model is used to present changes in call: when media starts to flow, when
call is considered established, when call is terminated.

In the figure below, a simplified state diagram for a SIP call is presented.
After the call state has changes the application will receive an
#nua_i_state event indicating the change. The states in NUA call model are
represented by @e enum #nua_callstate, and the current value of state is
included as the tag NUTAG_CALLSTATE() with the #nua_i_state event.

The @RFC3264 SDP Offer/Answer negotiation status is also included in the
#nua_i_state event. The negotiation status includes the local SDP (in
SOATAG_LOCAL_SDP()) sent and flags indicating whether the local SDP was an
offer or answer (NUTAG_OFFER_SENT(), NUTAG_ANSWER_SENT()). Likewise, the
received remote SDP is included in tag SOATAG_REMOTE_SDP() and flags
indicating whether the remote SDP was an offer or an answer in tags
NUTAG_OFFER_RECV() or NUTAG_ANSWER_RECV(). SOATAG_ACTIVE_AUDIO() and
SOATAG_ACTIVE_VIDEO() are informational tags used to indicate what is the
status of these media.

The #nua_i_state event is not sent, however, if the change is invoked by 
application calling API functions like nua_bye() and there is no change in
SDP offer/answer status.

@code
                    +---------------+
             +------|     INIT      |-----+
    INVITE/- |      +---------------+     | INVITE/100
             V                            |
       +------------+               +------------+
  +----|  CALLING   |--+        +---|  RECEIVED  |--+
  |    +------------+  |        |   +------------+  |
  |          |         |        |         |         |
  |          | 18X/-   |        |         | -/18X   |
  |          V         |        |         V         |
  |    +------------+  |        |   +------------+  |
  |<---| PROCEEDING |  |        |   |   EARLY    |->|
  |    +------------+  |        |   +------------+  |  -/[3456]XX
  |          |         |        |         |         |
  |          | 2XX/-   | 2XX/-  | -/2XX   | -/2XX   |    or
  |          V         |        |         V         |
  |    + - - - - - -+  |        |   +------------+  |  CANCEL/200,487
  |    : COMPLETING :<-+        +-->|  COMPLETE  |  |
  |    + - - - - - -+               +------------+  |
  |          |                            |         |
  |          | -/ACK                ACK/- |         |
  |          |                            |         |
  |          |                            |         |
  |          |      +---------------+     |         |
  |          +----->|     READY     |<----+         |
  |                 +---------------+               |
  |                   |           |                 |
  |          BYE/200  |           | -/BYE           |
  |                   |           |                 |
  |                   |           V                 |
  |                   |   +--------------+          |
  | [3456]XX/ACK      |   | TERMINATING  |          |
  |                   |   +--------------+          |
  |                   |           |                 |
  |                   |           | [23456]XX/-     |
  |                   V           V                 |
  |                 +---------------+               |
  +---------------->|  TERMINATED   |<--------------+
                    +---------------+
@endcode

The labels "input/output" along each transition indicates SIP messages
received from and sent to network, for instance, state transition
"INVITE/100" occurs when a SIP @b INVITE request is received, and it is
immediately returned a 100 (<i>Trying</i>) response. Label "2XX" means any
200-series response, e.g., <i>200 OK</i> or <i>202 Accepted</i>). Notation
"[3456]XX" means any final error response in 300, 400, 500, or 600
series. Label "18X" means any provisional response from 101 to 199, most
typically 180 (<i>Ringing</i>) or 183 (<i>Session Progress</i>).

@section nua_uac_call_model Detailed Client Call Model

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

@code
            +------------+
            |    INIT    |
            +------------+
                  |
                 (1) nua_invite/INVITE
                  |
                  V
            +------------+
            |            |-----------------------------(6a)-----+
            |            |----+  nua_cancel                     |
     +------|  CALLING   |  (7a)  /CANCEL                       |
     |      |            |<---+                                 |
     |      |            |----------------------+               |
     |      +------------+                      |               |
     |            |                           (8a) nua_bye      |
     |           (2) 18X/-                      |   /CANCEL     |
     |            |                             |               |
     |            V                             |               |
     |      +------------+                      |               |
     |      |            |-----------------------------(6b)---->|
     |      |            |----+  nua_cancel     |               |
     |      | PROCEEDING |  (7b)  /CANCEL       |               |
     |      |            |<---+                 |               |
     |      |            |----------------------+               |
     |      +------------+                      |               |
     |            |                             |               |
   (3a) 2XX/-   (3b) 2XX/-                      |              (6) [3456]XX/ACK
     |            |                             |               |
     |            V                             |               |
     |      + - - - - - -+                      |               |
     +----->:            :                      |               |
            : COMPLETING :-------+              |               |
     + - - -:            :       |              |               |
     :      + - - - - - -+       |              |               |
     :     	  |         	 |              |               |
     :<auto_ack>  |         	 |              |               |
     :or nua_ack  | <auto_ack>   |              |               |
     :and media   | or nua_ack   | nua_bye      |               |
    (5) error 	 (4) /ACK   	(9) /ACK+BYE  (8b) nua_bye/BYE  |
     : /ACK+BYE	  |         	 |              |               |
     :     	  V         	 |              V               |
     :      +------------+       |       +-------------+        |
     :      |            |       |       |             |        |
     :      |   READY    |       |       | TERMINATING*|        |
     :      |            |       |       |             |        |
     :      +------------+       |       +-------------+        |
     :                           |        |	     |		|
     :                           |      (10) 2XX   (11) 3XX 4XX |
     :      +-------------+      |        |   /BYE   |	5XX 6XX |
     :      |             |      V        V          |   /-     |
     + - - >| TERMINATING |<-------------------------+	        |
            |             |                                     |
            +-------------+			      	        |
                  |        			      		|
                (12) [23456]XX to BYE/-		      		|
                  |             		      		|
                  V             		      		|
            +------------+             		      		|
            | TERMINATED |<-------------------------------------+
            +------------+
@endcode