nua.docs

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

#define NUA_MAGIC_T   application

/* type for operation context data */
typedef union oper_ctx_u oper_ctx_t;
#define NUA_HMAGIC_T  oper_ctx_t
@endcode

The information area contents themselves can be defined as
C structures or unions:

@code
/* example of application context information structure */
typedef struct application
{
  su_home_t       home[1];  /* memory home */
  su_root_t      *root;     /* root object */
  nua_t          *nua;      /* NUA stack object */

  /* other data as needed ... */
} application;

/* Example of operation handle context information structure */
typedef union operation
{
  nua_handle_t    *handle;  /* operation handle /

  struct
  {
    nua_handle_t  *handle;  /* operation handle /
    ...                     /* call-related information */
  } call;

  struct
  {
    nua_handle_t  *handle;  /* operation handle /
    ...                     /* subscription-related information */
  } subscription;

  /* other data as needed ... */

} operation;
@endcode

NUA stack object and handle are opaque to the application programmer.
Likewise, the application context is completely opaque to the NUA stack
module. NUA functions are passed a pointer, and that pointer is then
given back to the application within the callback parameters. In this
case the application context information structure is also used to
store a root object and memory home for memory handling. The application
context information also contains the NUA stack object information.

@subsection nua_initanddeinit Initialization and deinitialization

The following code is an example of application function that initializes
the system, enters the main loop for processing the messages, and, after
message processing is ended, deinitalizes the system.

If the application is not just responding to incoming SIP messages there must
also be means to send messages to NUA. This can be handled for example by
having a separate thread that calls NUA functions to send messages or by
having a socket connection to the application for sending commands to the
application (see documentation of su_wait_create() and su_root_register()).

@code
/* Application context structure */
application appl[1] = {{{{(sizeof appl)}}}};

/* initialize system utilities */
su_init();

/* initialize memory handling */
su_home_init(appl->home);

/* initialize root object */
appl->root = su_root_create(appl);

if (appl->root != NULL) {
  /* create NUA stack */
  appl->nua = nua_create(appl->root,
                             app_callback,
                             appl,
                             /* tags as necessary ...*/
                             TAG_NULL());

  if (appl->nua != NULL) {
    /* set necessary parameters */
    nua_set_params(appl->nua,
                    /* tags as necessary ... */
                    TAG_NULL());

    /* enter main loop for processing of messages */
    su_root_run(appl->root);

    /* destroy NUA stack */
    nua_destroy(appl->nua);
  }

  /* deinit root object */
  su_root_destroy(appl->root);
  appl->root = NULL;
}

/* deinitialize memory handling */
su_home_deinit(appl->home);

/* deinitialize system utilities */
su_deinit();
@endcode

@subsection nua_handlingevents Handling events

Handling of the events coming from NUA stack is done in the callback
function that is registered for NUA stack with the nua_create() function
when the application is initialized. The content of callback function is
in its simplest form just a switch/case statement that dispatches the
incoming events for processing to separate functions.

@code
void app_callback(nua_event_t   event,
                  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[])
{
  switch (event) {
  case nua_i_invite:
    app_i_invite(status, phrase, nua, magic, nh, hmagic, sip, tags);
    break;

  case nua_r_invite:
    app_r_invite(status, phrase, nua, magic, nh, hmagic, sip, tags);
    break;

  /* and so on ... */

  default:
    /* unknown event -> print out error message */
    if (status > 100) {
      printf("unknown event %d: %03d %s\n",
             event,
             status,
             phrase);
    }
    else {
      printf("unknown event %d\n", event);
    }
    tl_print(stdout, "", tags);
    break;
  }
} /* app_callback */
@endcode

@subsection nua_placeacall Place a call

The following three functions show an example of how a basic SIP
call is created.

The place_a_call() function creates an operation handle and invokes the
SIP INVITE method.

@code
operation *place_a_call(char const *name, url_t const *url)
{
  operation *op;
  sip_to_t *to;

  /* create operation context information */
  op = su_zalloc(appl->home, (sizeof *op));
  if (!op)
     return NULL;

  /* Destination address */
  to = sip_to_create(NULL, url);
  if (!to)
     return NULL;

  to->a_display = name;

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

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

  nua_invite(op->handle,
              /* other tags as needed ... */
              TAG_END());

} /* place_a_call */
@endcode

The app_r_invite() function is called by callback function when response to
INVITE message is received. Here it is assumed that automatic acknowledge
is not enabled so ACK response must be sent explicitly.

@code
void app_r_invite(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[])
{
  if (status == 200) {
    nua_ack(nh, TAG_END());
  }
  else {
    printf("response to INVITE: %03d %s\n", status, phrase);
  }
} /* app_r_invite */
@endcode

The nua_i_state event is sent (and app_i_state() function called by callback
function) when the call state changes (see @ref nua_uac_call_model
"client-side call model").

@code
void app_i_state(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[])
{
  nua_callstate_t state = nua_callstate_init;

  tl_gets(tags,
          NUTAG_CALLSTATE_REF(state),
          NUTAG__REF(state),

  
    state = (nua_callstate_t)t->t_value;

  printf("call %s\n", nua_callstate_name(state));

} /* app_i_state */
@endcode

@subsection nua_receiveacall Receive a call

The app_i_invite() function is called by callback function when incoming
INVITE message is received. This example assumes that autoanswer is
not enabled so the response must be sent explicitly.

@code
void app_i_invite(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("incoming call\n");

  nua_respond(nh, 200, "OK", SOA_USER_SDP(magic->sdp), TAG_END());

} /* app_i_invite */
@endcode

The app_i_state() function is called by the callback function when call has
been successfully set up and the media has been activated.

@code
void app_i_active(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("call active\n");

} /* app_i_active */
@endcode

@subsection nua_terminatingcall Terminating a call

The following three functions show an example of how a basic SIP
call is terminated.

The terminate_call() function sends the SIP BYE message.

@code
void terminate_call(void)
{
  nua_bye(op->handle, TAG_END());

} /* terminate call */
@endcode

The app_r_bye() function is called by the callback function when answer to
the BYE message is received. The function destroys the call handle and
releases the memory allocated to operation context information.

@code
void app_r_bye(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[])
{
  if (status < 200)
     return;

  printf("call released\n");

  /* release operation handle */
  nua_handle_destroy(hmagic->handle);
  op->handle = NULL;

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

} /* app_r_bye */
@endcode

The app_i_bye() function is called by the callback function when an incoming
BYE message is received. The function destroys the call handle and releases
the memory allocated to operation context information.

@code
void app_i_bye(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("call released\n");

  /* release operation handle */
  nua_handle_destroy(hmagic->handle);
  op->handle = NULL;