nua.c 40.8 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <pekka.pessi@nokia.com>
 *
 * * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

/**@CFILE nua.c Nokia User Agent API.
 *
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>
 *
 * @date Created: Wed Feb 14 18:32:58 2001 ppessi
 *
31
 * $Date: 2005/10/03 16:48:22 $
Pekka Pessi's avatar
Pekka Pessi committed
32 33 34 35 36
 */

#include "config.h"

const char _nua_c_id[] =
37
"$Id: nua.c,v 1.7 2005/10/03 16:48:22 ppessi Exp $";
Pekka Pessi's avatar
Pekka Pessi committed
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65

/* From AM_INIT/AC_INIT in our "config.h" */
char const nua_version[] = VERSION;

#include <stddef.h>
#include <stdlib.h>
#include <string.h>

#include <assert.h>

#include <su_tag.h>
#include <su_tag_class.h>
#include <su_tagarg.h>

#include <stdio.h>

#include <su_tag_io.h>

#define SU_LOG (nua_log)
#include <su_debug.h>

#define SU_ROOT_MAGIC_T   struct nua_s
#define SU_MSG_ARG_T      struct event_s

#include <su_wait.h>

#include <su_strlst.h>

66 67
#define NUA_SAVED_EVENT_T su_msg_t *

Pekka Pessi's avatar
Pekka Pessi committed
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
#include "nua.h"
#include "nua_tag.h"

#define NTA_AGENT_MAGIC_T    struct nua_s
#define NTA_LEG_MAGIC_T      struct nua_handle_s
#define NTA_OUTGOING_MAGIC_T struct nua_handle_s
#define NTA_INCOMING_MAGIC_T struct nua_handle_s

#define NTR_AGENT_MAGIC_T    struct nua_s
#define NTR_SESSION_MAGIC_T  struct nua_handle_s
#define NTR_OUTGOING_MAGIC_T struct nua_handle_s
#define NTR_INCOMING_MAGIC_T struct nua_handle_s

#define NEA_SMAGIC_T         nua_handle_t
#define NEA_EMAGIC_T         nua_handle_t

#include <sip.h>
#include <sip_header.h>
#include <sip_status.h>
#include <sip_util.h>

#include <nta.h>
#include <nea.h>

#include <tport_tag.h>
#if HAVE_UICC_H
#include <uicc.h>
#endif
#include <auth_client.h>

#if HAVE_SMIME 		/* Start NRC Boston */
#include "smimec.h"
#endif                  /* End NRC Boston */

#include <sdp.h>

#include <sl_utils.h>

#include "nua_stack.h"

Pekka Pessi's avatar
Pekka Pessi committed
108 109
#undef nua_default

Pekka Pessi's avatar
Pekka Pessi committed
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195
const char _nua_h_id[] = NUA_H;

/**@var NUA_DEBUG
 *
 * Environment variable determining the debug log level for @b nua module.
 *
 * The NUA_DEBUG environment variable is used to determine the debug logging
 * level for @b nua module. The default level is 3.
 * 
 * @sa <su_debug.h>, nua_log, SOFIA_DEBUG
 */
extern char const NUA_DEBUG[];

#ifndef SU_DEBUG
#define SU_DEBUG 3
#endif

/**Debug log for @b nua module. 
 * 
 * The nua_log is the log object used by @b nua module. The level of
 * #nua_log is set using #NUA_DEBUG environment variable.
 */
su_log_t nua_log[] = { SU_LOG_INIT("nua", "NUA_DEBUG", SU_DEBUG) };

#if 0
/** Handle filter.
 *
 * This is used to convert string tags to header tags.
 */
static tagi_t const nua_filter[] =
  {{ SIPTAG_REQUEST(0) },
   { SIPTAG_STATUS(0) },
   { SIPTAG_FROM(0) },
   { SIPTAG_TO(0) },
   { SIPTAG_CSEQ(0) },
   { SIPTAG_CONTACT(0) },
   { SIPTAG_CALL_INFO(0) },
   { SIPTAG_ALLOW(0), },
   { SIPTAG_SUBJECT(0) },
   { SIPTAG_REQUIRE(0) },
   { SIPTAG_SUPPORTED(0) },
   { SIPTAG_WWW_AUTHENTICATE(0) },
   { SIPTAG_PROXY_AUTHENTICATE(0) },
   { SIPTAG_CONTENT_TYPE(0) },
   { SIPTAG_PAYLOAD(0) },
   { TAG_NULL() }};
#endif

/**Create a NUA agent.
 *
 * This function creates a Nokia User Agent stack object and 
 * initializes its parameters by given tagged values.
 *
 * @param root            Pointer to a root object
 * @param callback        Pointer to event callback function
 * @param magic           Pointer to callback context
 * @param tag,value,... List of tagged parameters
 *
 * @retval !=NULL a pointer to a NUA stack object \n
 * @retval NULL upon an error
 *
 * @par Related tags:
 *     #NUTAG_MEDIA_DESCS      \n
 *     #NUTAG_MEDIA_ENABLE     \n
 *     #NUTAG_PROXY            \n
 *     #NUTAG_SIP_PARSER       \n
 *     #NUTAG_SIPS_URL         \n
 *     #NUTAG_UICC             \n
 *     #NUTAG_CERTIFICATE_DIR  \n
 *     #NUTAG_URL              \n
 *     #NUTAG_MEDIA_ADDRESS    \n
 *     #NUTAG_MEDIA_PARAMS     \n
 *     all relevant NTATAG_* are passed to NTA 
 *
 * @par Events:
 *     none
 */
nua_t *nua_create(su_root_t *root,
		  nua_callback_f callback,
		  nua_magic_t *magic,
		  tag_type_t tag, tag_value_t value, ...)
{
  nua_t *nua = NULL;

  enter;

196 197
  if (callback == NULL)
    return (void)(errno = EFAULT), NULL;
Pekka Pessi's avatar
Pekka Pessi committed
198

199 200 201
  if (root == NULL)
    return (void)(errno = EFAULT), NULL;

202
  if ((nua = su_home_new(sizeof(*nua)))) {
Pekka Pessi's avatar
Pekka Pessi committed
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
    ta_list ta;

    su_home_threadsafe(nua->nua_home);
    nua->nua_api_root = root;

    ta_start(ta, tag, value);

    nua->nua_args = ta_args(ta);

    su_task_copy(nua->nua_client, su_root_task(root));

    /* XXX: where to put this in the nua_server case? */
#if HAVE_SMIME		/* Start NRC Boston */
      nua->sm = sm_create();
#endif                  /* End NRC Boston */

#ifndef NUA_SERVER
    if (su_clone_start(root,
		       nua->nua_clone,
		       nua,
		       ua_init,
		       ua_deinit) == SU_SUCCESS) {
      su_task_copy(nua->nua_server, su_clone_task(nua->nua_clone));
      nua->nua_callback = callback;
      nua->nua_magic = magic;
    }
    else {
230
      su_home_unref(nua->nua_home);
Pekka Pessi's avatar
Pekka Pessi committed
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261
      nua = NULL;
    }
#endif

    ta_end(ta);
  }

  return nua;
}

/**Shutdown a NUA stack.
 *
 * Ongoing calls are released, registrations unregistered, and 
 * subscriptions terminated.  If the stack cannot terminate within 
 * 30 seconds, it sends the nua_r_shutdown event with status 500.
 *
 * @param nua         Pointer to NUA stack object
 *
 * @return
 *     nothing
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     #nua_r_shutdown
 */
void nua_shutdown(nua_t *nua)
{
  enter;

262 263
  if (nua)
    nua->nua_shutdown_started = 1;
Pekka Pessi's avatar
Pekka Pessi committed
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289
  nua_signal(nua, NULL, NULL, 1, nua_r_shutdown, 0, NULL, TAG_END());
}

/** Destroy the NUA stack.
 *
 * Before calling nua_destroy() the application 
 * should call nua_shutdown and wait for successful #nua_r_shutdown event.
 * Shuts down and destroys the NUA stack. Ongoing calls, registrations, 
 * and subscriptions are left as they are.
 *
 * @param nua         Pointer to NUA stack object
 *
 * @return
 *     nothing
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
void nua_destroy(nua_t *nua)
{
  enter;

  if (nua) {
290 291 292 293 294 295 296
    if (!nua->nua_shutdown_final) {
      SU_DEBUG_0(("nua_destroy(%p): FATAL: nua_shutdown not completed\n", nua));
      assert(nua->nua_shutdown);
      return;
    }

    su_task_deinit(nua->nua_server);
297 298
    su_task_deinit(nua->nua_client);

Pekka Pessi's avatar
Pekka Pessi committed
299 300 301 302
    su_clone_wait(nua->nua_api_root, nua->nua_clone);
#if HAVE_SMIME		/* Start NRC Boston */
    sm_destroy(nua->sm);
#endif			/* End NRC Boston */
303
    su_home_unref(nua->nua_home);
Pekka Pessi's avatar
Pekka Pessi committed
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
  }
}

/** Obtain default operation handle of the NUA stack object.
 *
 * A default operation can be used for operations where the 
 * ultimate result is not important or can be discarded.
 *
 * @param nua         Pointer to NUA stack object
 *
 * @retval !=NULL Pointer to NUA operation handle
 * @retval NULL   No default operation exists
 *
 * @par Related tags:
 *    none
 *
 * @par Events:
 *    none
 *
Pekka Pessi's avatar
Pekka Pessi committed
323
 */
Pekka Pessi's avatar
Pekka Pessi committed
324 325
nua_handle_t *nua_default(nua_t *nua)
{
Pekka Pessi's avatar
Pekka Pessi committed
326
  return nua ? nua->nua_handles : NULL;
Pekka Pessi's avatar
Pekka Pessi committed
327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631
}

/** Create an operation handle 
 *
 * Allocates a new operation handle and associated storage.
 *
 * @param nua         Pointer to NUA stack object
 * @param hmagic      Pointer to callback context
 * @param tag, value, ... List of tagged parameters
 *
 * @retval !=NULL  Pointer to operation handle
 * @retval NULL    Creation failed
 *
 * @par Related tags:
 *     Creates a copy of provided tags and they will 
 *     be used with every operation.
 *
 * @par Events:
 *     none
 *
 */
nua_handle_t *nua_handle(nua_t *nua, nua_hmagic_t *hmagic,
			 tag_type_t tag, tag_value_t value, ...)
{
  nua_handle_t *nh = NULL;

  if (nua) {
    ta_list ta;

    ta_start(ta, tag, value);

    nh = nh_create_handle(nua, hmagic, ta_args(ta));
    
    if (nh)
      nh->nh_ref_by_user = 1;

    ta_end(ta);
  }

  return nh;
}

/** Bind a callback context to an operation handle. 
 *
 * @param nh          Pointer to operation handle
 * @param hmagic      Pointer to callback context
 *
 * @return
 *     nothing
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
void nua_handle_bind(nua_handle_t *nh, nua_hmagic_t *hmagic)
{
  enter;

  if (NH_IS_VALID(nh))
    nh->nh_magic = hmagic;
}

/* ---------------------------------------------------------------------- */

/** Check if operation handle is used for INVITE
 *
 * Check if operation handle has been used with either outgoing or incoming INVITE request.
 *
 * @param nh          Pointer to operation handle
 *
 * @retval 0 no invite in operation or operation handle is invalid 
 * @retval 1 operation has invite 
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
int nua_handle_has_invite(nua_handle_t const *nh)
{
  return nh ? nh->nh_has_invite : 0;
}

/**Check if operation handle has active event subscriptions. 
 *
 * Active subscription can be established either by nua_subscribe 
 * or nua_refer() calls. 
 *
 * @param nh          Pointer to operation handle
 *
 * @retval 0    no event subscriptions in operation or 
 *              operation handle is invalid 
 * @retval !=0  operation has event subscriptions
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
int nua_handle_has_events(nua_handle_t const *nh)
{
  return nh ? nh->nh_ds->ds_has_events : 0;
}

/** Check if operation handle has active registrations
 *
 * Either REGISTER operation is ongoing or NUA stack is expected to 
 * refresh in the future.
 *
 * @param nh          Pointer to operation handle
 *
 * @retval 0 no active registration in operation or 
 *           operation handle is invalid
 * @retval 1 operation has registration
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
int nua_handle_has_registrations(nua_handle_t const *nh)
{
  return nh && nh->nh_ds->ds_has_register;
}

/** Check if operation handle has been used with outgoing SUBSCRIBE of REFER request. 
 *
 * @param nh          Pointer to operation handle
 *
 * @retval 0 no active subscription in operation or 
 *           operation handle is invalid 
 * @retval 1 operation has subscription.
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
int nua_handle_has_subscribe(nua_handle_t const *nh)
{
  return nh ? nh->nh_has_subscribe : 0;
}

/** Check if operation handle has been used with nua_register() or nua_unregister().
 *
 * @param nh          Pointer to operation handle
 *
 * @retval 0 no active register in operation or operation handle is invalid
 * @retval 1 operation has been used with nua_register() or nua-unregister()
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none

 */
int nua_handle_has_register(nua_handle_t const *nh)
{
  return nh ? nh->nh_has_register : 0;
}

int nua_handle_has_streaming(nua_handle_t const *nh)
{
  return nh ? nh->nh_has_streaming : 0;
}

/** Check if operation handle has an active call 
 *
 * @param nh          Pointer to operation handle
 *
 * @retval 0 no active call in operation or operation handle is invalid
 * @retval 1 operation has established call or pending call request.
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
int nua_handle_has_active_call(nua_handle_t const *nh)
{
  return nh ? nh->nh_ss->ss_active : 0;
}

/** Check if operation handle has a call on hold 
 *
 * Please note that this status is not affected by remote end putting 
 * this end on hold. Remote end can put each media separately on hold 
 * and status is reflected on #NUTAG_ACTIVE_AUDIO, #NUTAG_ACTIVE_VIDEO 
 * and #NUTAG_ACTIVE_CHAT tag values in nua_i_active event.
 *
 * @param nh          Pointer to operation handle
 *
 * @retval 0  if no call on hold in operation or operation handle is invalid 
 * @retval 1  if operation has call on hold, for example nua_invite() or 
 *            nua_update() has been called with #NUTAG_HOLD with != 0 argument.
 *
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
int nua_handle_has_call_on_hold(nua_handle_t const *nh)
{
  return nh ? nh->nh_ss->ss_hold_remote : 0;
}

/** Get the remote address (From/To header) of operation handle
 *
 * Remote address is used as To header in outgoing operations and 
 * derived from From: header in incoming operations.
 *
 * @param nh          Pointer to operation handle
 *
 * @retval NULL   no remote address for operation or operation handle invalid
 * @retval !=NULL pointer to remote address for operation
 *     
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
sip_to_t const *nua_handle_remote(nua_handle_t const *nh)
{
  return nh ? nh->nh_ds->ds_remote : NULL;
}

/** Get the local address (From/To header) of operation handle
 *
 * Local address is used as From header in outgoing operations and 
 * derived from To: header in incoming operations.
 *
 * @param nh          Pointer to operation handle
 *
 * @retval NULL   no local address for operation or operation handle invalid
 * @retval !=NULL pointer to local address for operation
 *     
 * @par Related tags:
 *     none
 *
 * @par Events:
 *     none
 */
sip_to_t const *nua_handle_local(nua_handle_t const *nh)
{
  return nh ? nh->nh_ds->ds_local : NULL;
}

/** Set NUA parameters.
 *
 * @param nua             Pointer to NUA stack object
 * @param tag, value, ... List of tagged parameters
 *
 * @return
 *     nothing
 *
 * @par Related tags:
 *     #NUTAG_AUTOACK \n
 *     #NUTAG_AUTOALERT \n
 *     #NUTAG_AUTOANSWER \n
 *     #NUTAG_EARLY_MEDIA \n
 *     #NUTAG_ENABLEINVITE \n
 *     #NUTAG_ENABLEMESSAGE \n
 *     #NUTAG_ENABLEMESSENGER \n
 *     #NUTAG_INVITE_TIMER \n
 *     #NUTAG_MEDIA_FEATURES \n
 *     #NUTAG_MIN_SE \n
 *     #NUTAG_PROXY \n
 *     #NUTAG_REGISTRAR \n
 *     #NUTAG_SESSION_REFRESHER \n
 *     #NUTAG_SESSION_TIMER \n
 *     #NUTAG_URL \n
 *     #NUTAG_USER_AGENT \n
 *     #NUTAG_UPDATE_REFRESH \n
 *     #NUTAG_SIP_PARSER \n
 *     #NUTAG_CERTIFICATE_DIR \n
 *     #NUTAG_SMIME_ENABLE \n
 *     #NUTAG_SMIME_OPT \n
 *     #NUTAG_SMIME_PROTECTION_MODE \n
 *     #NUTAG_SMIME_MESSAGE_DIGEST \n
 *     #NUTAG_SMIME_SIGNATURE \n
 *     #NUTAG_SMIME_KEY_ENCRYPTION \n
 *     #NUTAG_SMIME_MESSAGE_ENCRYPTION \n
 *     #NUTAG_SIPS_URL \n
 *     #SIPTAG_FROM_STR \n
 *     #SIPTAG_ORGANIZATION_STR \n
 *     #SIPTAG_SUPPORTED_STR \n
 *     #SIPTAG_ALLOW_STR \n
 *     #NTATAG_DEFAULT_PROXY \n
 *     #NTATAG_SIP_T1 \n
 *     #NTATAG_SIP_T2 \n
 *     #NTATAG_SIP_T4 \n
 *     #NTATAG_SIP_T1X64 \n
 *     #NTATAG_DEBUG_DROP_PROB \n
 *     #NTATAG_SIPFLAGS
 *
632 633 634
 * nua_set_params() also accepts any soa tags from <soa_tag.h> (or
 * <mss_soa.h>).
 * 
Pekka Pessi's avatar
Pekka Pessi committed
635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685
 * @par Events:
 *     none
 */
void nua_set_params(nua_t *nua, tag_type_t tag, tag_value_t value, ...)
{
  ta_list ta;
  ta_start(ta, tag, value);

  enter;

  nua_signal(nua, NULL, NULL, 0, nua_r_set_params, 0, NULL, ta_tags(ta));

  ta_end(ta);
}

/** Get NUA parameters.
 *
 * Get values of NUA parameters in nua_r_get_params event.
 *
 * @param nua             Pointer to NUA stack object
 * @param tag, value, ... List of tagged parameters
 *
 * @return
 *     nothing
 *
 * @par Related tags:
 *     #TAG_ANY \n
 *     othervise same tags as nua_set_params()
 *
 * @par Events:
 *     #nua_r_get_params
 */
void nua_get_params(nua_t *nua, tag_type_t tag, tag_value_t value, ...)
{
  ta_list ta;
  ta_start(ta, tag, value);

  enter;

  nua_signal(nua, NULL, NULL, 0, nua_r_get_params, 0, NULL, ta_tags(ta));

  ta_end(ta);
}

#define NUA_SIGNAL(nh, event, tag, value) \
  enter; \
  if (NH_IS_VALID((nh))) { \
    ta_list ta; \
    ta_start(ta, tag, value); \
    nua_signal((nh)->nh_nua, nh, NULL, 0, event, 0, NULL, ta_tags(ta));	\
    ta_end(ta); \
686 687
  } \
  else { \
Pekka Pessi's avatar
Pekka Pessi committed
688
    SU_DEBUG_1(("nua: " #event " with invalid handle %p\n", nh));	\
Pekka Pessi's avatar
Pekka Pessi committed
689 690
  }

691 692
/** Set handle-specific parameters.
 *
693
 * @param nh              Pointer to a NUA handle
694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709
 * @param tag, value, ... List of tagged parameters
 *
 * @return
 *     nothing
 *
 * @par Related tags:
 *     #NUTAG_AUTOACK \n
 *     #NUTAG_AUTOALERT \n
 *     #NUTAG_AUTOANSWER \n
 *     #NUTAG_EARLY_MEDIA \n
 *     #NUTAG_ENABLEINVITE \n
 *     #NUTAG_ENABLEMESSAGE \n
 *     #NUTAG_ENABLEMESSENGER \n
 *     #NUTAG_INVITE_TIMER \n
 *     #NUTAG_MEDIA_FEATURES \n
 *     #NUTAG_MIN_SE \n
710
 *     #NUTAG_PROXY (XXX) \n
711 712 713 714 715
 *     #NUTAG_REGISTRAR \n
 *     #NUTAG_SESSION_REFRESHER \n
 *     #NUTAG_SESSION_TIMER \n
 *     #NUTAG_USER_AGENT \n
 *     #NUTAG_UPDATE_REFRESH \n
716 717
 *     #NUTAG_SIP_PARSER (XXX) \n
 *     #NUTAG_CERTIFICATE_DIR (XXX) \n
718 719 720 721 722 723 724 725
 *     #NUTAG_SMIME_ENABLE \n
 *     #NUTAG_SMIME_OPT \n
 *     #NUTAG_SMIME_PROTECTION_MODE \n
 *     #NUTAG_SMIME_MESSAGE_DIGEST \n
 *     #NUTAG_SMIME_SIGNATURE \n
 *     #NUTAG_SMIME_KEY_ENCRYPTION \n
 *     #NUTAG_SMIME_MESSAGE_ENCRYPTION \n
 *     #NUTAG_SIPS_URL \n
726
 *     #SIPTAG_ORGANIZATION \n
727
 *     #SIPTAG_ORGANIZATION_STR \n
728
 *     #SIPTAG_SUPPORTED \n
729 730 731 732 733 734
 *     #SIPTAG_SUPPORTED_STR \n
 *     #SIPTAG_ALLOW_STR \n
 *
 * @par Events:
 *     none
 */
735
void nua_set_hparams(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
736 737 738 739 740
{
  NUA_SIGNAL(nh, nua_r_set_params, tag, value);
}

/** Get values of handle-specific parameters in nua_r_get_params event.
741 742 743 744
 *
 * Application will specify either expilicit list of tags it is interested
 * in, or a filter (at the moment, TAG_ANY()). The values are returned as a
 * list of tags in the nua_r_get_params event.
745 746 747 748
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
749 750 751 752 753 754 755 756 757 758
 * The handle-specific parameters will contain only the parameters actually
 * modified by application, either by nua_set_handle_params() or some other
 * handle-specific call. Currently, no NTA parameters are returned. They are
 * returned only when application asks for user-agent-level parameters using
 * either nua_get_params() or using default handle, eg.
 * @code
 * nua_get_handle_params(nua_default(nua), TAG_ANY())
 * @endcode
 *
 *
759 760 761 762 763 764 765 766 767 768
 * @return
 *     nothing
 *
 * @par Related tags:
 *     #TAG_ANY \n
 *     othervise same tags as nua_set_handle_params()
 *
 * @par Events:
 *     #nua_r_get_params
 */
769
void nua_get_hparams(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
770 771 772
{
  NUA_SIGNAL(nh, nua_r_get_params, tag, value);
}
Pekka Pessi's avatar
Pekka Pessi committed
773

Pekka Pessi's avatar
Pekka Pessi committed
774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877
/** Send SIP REGISTER request to the registrar. 
 *
 * Request status will be delivered to the application using #nua_r_register
 * event. When successful the registration will be updated periodically. If
 * the registrar includes Service-Route header in response, and service
 * route is enabled using NUTAG_SERVICE_ROUTE_ENABLE(), the service route
 * will be used for initial non-REGISTER requests.
 *
 * The handle used for registration cannot be used for any other purposes.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return
 *     nothing
 *
 * @par Related tags:
 *     #NUTAG_REGISTRAR
 *
 * @par Events:
 *     #nua_r_register
 */

void nua_register(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_register, tag, value);
}

/** Unregister. 
 *
 * Send a REGISTER request with expiration time 0. This removes the 
 * registration from the registrar. If the handle was earlier used 
 * with nua_register() the periodic updates will be terminated. 
 *
 * If a #SIPTAG_CONTACT_STR with argument "*" is used, the all registrations 
 * will be removed from the registrar otherwise only the contact address 
 * belonging to the NUA stack is removed.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return
 *     nothing
 *
 * @par Related tags:
 *     #NUTAG_REGISTRAR \n
 *     Tags in <sip_tag.h> except #SIPTAG_EXPIRES or #SIPTAG_EXPIRES_STR
 *
 * @par Events:
 *     #nua_r_unregister
 */
void nua_unregister(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_unregister, tag, value);
}

/** Place a call using SIP INVITE method. 
 *
 * By default creates a media session, includes its description as 
 * SDP and send the request to the recipient. Upon receiving the 
 * response it will active the media session and establish the call. \n
 * \n
 * Incomple call can be hung-up with nua_cancel() \n
 * \n
 * Optionally 
 * - uses early media if #NUTAG_EARLY_MEDIA tag is used with non zero value
 * - media parameters can be set by NUTAG_MEDIA_* tags
 * - if #NUTAG_MEDIA_ENABLE tag is used with value zero then the MSS is 
 *   not used and application must create the SDP
 * - nua_invite() can be used to change call status: 
 *   - #NUTAG_HOLD tag with value 1 sets the call on hold
 *   - if new media path is given either new media parameters are taken in 
 *     use or new media is added to session.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #NUTAG_AF \n
 *    #NUTAG_HOLD \n
 *    #NUTAG_INVITE_TIMER \n
 *    #NUTAG_MEDIA_ADDRESS \n
 *    #NUTAG_MEDIA_CLONE \n
 *    #NUTAG_MEDIA_EVENT_DATA \n
 *    #NUTAG_MEDIA_EVENT_DLEN \n
 *    #NUTAG_MEDIA_EVENT_PATH \n
 *    #NUTAG_MEDIA_FEATURES \n
 *    #NUTAG_MEDIA_PATH \n
 *    #NUTAG_MEDIA_PARAMS \n
 *    #NUTAG_REFER_PAUSE \n
 *    #NUTAG_VIDEO_LOCAL \n
 *    #NUTAG_VIDEO_REMOTE \n
 *    #NUTAG_MEDIA_ENABLE \n
 *    #NUTAG_URL \n
 *    #NUTAG_MEDIA_SESSION \n
 *    tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_invite \n
 *    #nua_i_media_error \n
 *    #nua_i_fork \n
878 879
 *    #nua_i_active \n
 *    #nua_i_media_update
Pekka Pessi's avatar
Pekka Pessi committed
880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187
 *
 * \sa nua_handle_has_active_call() \n
 *     nua_handle_has_call_on_hold()\n
 *     nua_handle_has_invite() \n
 *     nua_update() \n
 *     nua_info() \n 
 *     nua_cancel() \n
 *     nua_bye()
 */
void nua_invite(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_invite, tag, value);
}

/** Acknowledge a succesfull response to INVITE request.
 *
 * Acknowledge a successful response to INVITE request 
 * with SIP ACK message. This function is need only if 
 * #NUTAG_AUTOACK parameter has been cleared.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_i_media_error \n
 *    #nua_i_active
 */
void nua_ack(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_ack, tag, value);
}

/** Hangdown a call.
 *
 * Hangdown a call using SIP BYE method. Also the media session 
 * associated with the call is terminated. 
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    none
 *
 * @par Events:
 *    #nua_r_bye \n
 *    #nua_i_media_error
 */
void nua_bye(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_bye, tag, value);
}

/** Cancel an INVITE operation 
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_cancel
 */
void nua_cancel(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_cancel, tag, value);
}

/** Query capabilities from server 
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_options
 *
 */
void nua_options(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_options, tag, value);
}

/** Send an instant message. 
 *
 * Send an instant message using SIP MESSAGE method.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_message
 */
void nua_message(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_message, tag, value);
}

/** Send a chat message. 
 *
 * A chat channel can be established during call setup using "message" media. 
 * An active chat channel is indicated using nua_i_active event containing 
 * #NUTAG_ACTIVE_CHAT tag. Chat messages can be sent using this channel with 
 * nua_chat() function. Currently this is implemented using SIP MESSAGE 
 * requests but in future MSRP (message session protocol) will replace it.
*
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #SIPTAG_CONTENT_TYPE \n
 *    #SIPTAG_PAYLOAD      \n
 *    #SIPTAG_FROM         \n
 *    #SIPTAG_TO           \n
 *    use of other SIP tags' is deprecated
 *
 * @par Events:
 *    #nua_r_chat
 */
void nua_chat(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_chat, tag, value);
}

/** Subscribe a SIP event. 
 *
 * Subscribe a SIP event using the SIP SUBSCRIBE request. If the 
 * SUBSCRBE is successful a subscription state is established and 
 * the subscription is refreshed regularly. The refresh requests will
 * generate #nua_r_subscribe events.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #NUTAG_URL
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_subscribe \n
 *    #nua_i_notify
 */
void nua_subscribe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_subscribe, tag, value);
}

/** Unsubscribe an event. 
 *
 * Unsubscribe an active or pending subscription with SUBSCRIBE request 
 * containing Expires: header with value 0. The dialog associated with 
 * subscription will be destroyed if there is no other subscriptions or 
 * call using this dialog.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #SIPTAG_EVENT \n
 *    Tags in <sip_tag.h> except #SIPTAG_EXPIRES or #SIPTAG_EXPIRES_STR
 *
 * @par Events:
 *    #nua_r_unsubscribe 
 */
void nua_unsubscribe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_unsubscribe, tag, value);
}

/** Send a SIP NOTIFY request message. 
 *
 * This function is used when the application implements itself 
 * the subscription state machine. The application must provide 
 * valid @b Subscription-State and @b Event headers using SIP tags.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_notify
 */
void nua_notify(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_notify, tag, value);
}

/** Create an event server. 
 *
 * This function create an event server taking care of sending NOTIFY 
 * requests and responding to further SUBSCRIBE requests. The event 
 * server can accept multiple subscriptions from several sources and 
 * takes care for distributing the notifications. Unlike other functions 
 * this call only accepts the SIP tags listed below.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #NUTAG_URL \n
 *    #SIPTAG_EVENT \n
 *    #SIPTAG_CONTENT_TYPE \n
 *    #SIPTAG_PAYLOAD \n
 *    #SIPTAG_ACCEPT
 *
 * @par Events:
 *    #nua_r_notify
 */
void nua_notifier(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_notifier, tag, value);
}

/** Terminate an event server. 
 *
 * Terminate an event server with matching event and content type. 
 * The event server was created earlier with nua_notifier() 
 * function containing the same content and event type tags.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #SIPTAG_EVENT \n
 *    #SIPTAG_CONTENT_TYPE \n
 *    #NEATAG_REASON
 *
 * @par Events:
 *    #nua_r_terminate
 */
void nua_terminate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_terminate, tag, value);
}

/** Transfer a call. 
 * 
 * Send a REFER request asking the recipient to transfer the call. The REFER
 * request also establishes a subscription to the "refer" event. The event
 * id parameter can be determined by the CSeq number from the SIP response
 * returned with the nua_r_refer event.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #NUTAG_URL \n
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_refer \n
 *    #nua_i_notify
 *
 * @sa RFC 3515
 */
void nua_refer(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_refer, tag, value);
}

/** Send PUBLISH request to publication server. 
 *
Pekka Pessi's avatar
Pekka Pessi committed
1188 1189 1190 1191
 * Request status will be delivered to the application using #nua_r_publish
 * event. When successful the publication will be updated periodically until
 * nua_unpublish() is called or handle is destroyed. The handle used for
 * publication cannot be used for any other purposes.
Pekka Pessi's avatar
Pekka Pessi committed
1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #NUTAG_URL \n
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_publish
 */
void nua_publish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_publish, tag, value);
}

Pekka Pessi's avatar
Pekka Pessi committed
1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234
/** Send un-PUBLISH request to publication server. 
 *
 * Request status will be delivered to the application using 
 * #nua_r_publish event. The handle used for un-publication 
 * cannot be used for any other purposes.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #NUTAG_URL \n
 *    Tags in <sip_tag.h>
 *
 * @par Events:
 *    #nua_r_publish
 */
void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_unpublish, tag, value);
}

Pekka Pessi's avatar
Pekka Pessi committed
1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279
/** Send an INFO request. 
 *
 * INFO is used to send call related information like DTMF 
 * digit input events. See
 * <a href="http://www.ietf.org/rfc/rfc2976.txt">RFC 2976</a>
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    Tags in <sip_tag.h>.
 *
 * @par Events:
 *    #nua_r_info
 */
void nua_info(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_info, tag, value);
}

/** Update a session. 
 * 
 * Update a session using SIP UPDATE method. See RFC
 * <a href="http://www.ietf.org/rfc/rfc3311.txt">RFC 3311</a>
 *
 * Update method can be used when the session has been established 
 * with INVITE. It's mainly used during the session establishment 
 * when preconditions are used (
 * <a href="http://www.ietf.org/rfc/rfc3312.txt">RFC 3312</a>
 * ). It can be also used during the call if no user input is needed.
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    same as nua_invite()
 *
 * @par Events:
 *    #nua_r_update \n
1280 1281
 *    #nua_i_media_error \n
 *    #nua_i_media_update
Pekka Pessi's avatar
Pekka Pessi committed
1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364
 */
void nua_update(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_update, tag, value);
}

/** Authenticate an operation.
 *
 * - 401 / 407 response with www-authenticate header/ proxy-authenticate header
 * - application should provide stack with username&password for each realm
 * with #NUTAG_AUTH tag
 * - restarts operation
 *
 * @param nh              Pointer to operation handle
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #NUTAG_AUTH
 *
 * @par Events:
 *    #nua_r_authenticate \n
 *    #nua_r_* (operation events)
 */
void nua_authenticate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_authenticate, tag, value);
}

/*# Redirect an operation. */
void nua_redirect(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  NUA_SIGNAL(nh, nua_r_redirect, tag, value);
}

/** Respond with given status. 
 * 
 * The INVITE requests should be responded with 
 * #nua_intive_respond() function because there 
 * might be another request going on besides INVITE.
 *
 * @param nh              Pointer to operation handle
 * @param status          SIP response status (see RFCs of SIP)
 * @param phrase          free text (default response phrase used if NULL)
 * @param tag, value, ... List of tagged parameters
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    #NUTAG_MEDIA_PATH \n
 *    #NUTAG_MEDIA_PARAMS \n
 *    #NUTAG_MEDIA_ADDRESS \n
 *    #NUTAG_MEDIA_CLONE \n
 *    #NUTAG_MEDIA_SESSION \n
 *    #NUTAG_MEDIA_EVENT_PATH \n
 *    #NUTAG_AF \n
 *    #NUTAG_HOLD \n
 *    #NUTAG_VIDEO_LOCAL \n
 *    #NUTAG_VIDEO_REMOTE \n
 *    Tags in <sip_tag.h>.
 *
 * @par Events:
 *    #nua_i_active \n
 *    #nua_i_media_error \n
 *    #nua_i_error
 */
void nua_respond(nua_handle_t *nh,
		 int status, char const *phrase,
		 tag_type_t tag, tag_value_t value,
		 ...)
{
  enter;

  if (NH_IS_VALID(nh)) {
    ta_list ta;
    ta_start(ta, tag, value);
    nua_signal(nh->nh_nua, nh, NULL, 0, nua_r_respond,
	       status, phrase, ta_tags(ta));
    ta_end(ta);
  }
1365
  else {
Pekka Pessi's avatar
Pekka Pessi committed
1366
    SU_DEBUG_1(("nua: respond with invalid handle %p\n", nh));
1367
  }
Pekka Pessi's avatar
Pekka Pessi committed
1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408
}

/** Destroy a handle 
 *
 * Destroy an operation handle and asks stack to discard resources 
 * and ongoing sessions and transactions associated with this handle. 
 * For example calls are terminated with BYE request.
 *
 * @param nh              Pointer to operation handle
 *
 * @return 
 *    nothing
 *
 * @par Related Tags:
 *    none
 *
 * @par Events:
 *    none
 */
void nua_handle_destroy(nua_handle_t *nh)
{
  enter;

  if (NH_IS_VALID(nh)) {
    nh->nh_valid = NULL;	/* Events are no more delivered to appl. */
    nua_signal(nh->nh_nua, nh, NULL, 1, nua_r_destroy, 0, NULL, TAG_END());
  }
}



/*# Send a request to the protocol thread */
void nua_signal(nua_t *nua, nua_handle_t *nh, msg_t *msg, int always,
		nua_event_t event,
		int status, char const *phrase,
		tag_type_t tag, tag_value_t value, ...)
{
  su_msg_r sumsg = SU_MSG_R_INIT;
  int len, xtra, e_len, l_len = 0, l_xtra = 0;
  ta_list ta;

1409 1410 1411
  if (nua == NULL || (nua->nua_shutdown_started && event != nua_r_shutdown))
    return;

Pekka Pessi's avatar
Pekka Pessi committed
1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455
  ta_start(ta, tag, value);

  e_len = offsetof(event_t, e_tags);
  len = tl_len(ta_args(ta));
  xtra = tl_xtra(ta_args(ta), len);

  if (su_msg_create(sumsg, nua->nua_server, nua->nua_client,
		    ua_signal,
		    e_len + len + l_len + xtra + l_xtra) == 0) {
    event_t *e = su_msg_data(sumsg);
    tagi_t *t = e->e_tags;
    void *b = (char *)t + len + l_len;

    tagi_t *tend = (tagi_t *)b;
    char *bend = (char *)b + xtra + l_xtra;

    t = tl_dup(t, ta_args(ta), &b);

    assert(tend == t); assert(b == bend);

    e->e_always = always;
    e->e_event = event;
    e->e_nh = nh_incref(nh);
    e->e_status = status;
    e->e_phrase = phrase;

    if (su_msg_send(sumsg) != 0)
      nh_decref(nh);
  } 
  else {
    assert(0);
  }

  ta_end(ta);
}

/*# Receive event from protocol machine and hand it over to application */
void nua_event(nua_t *root_magic, su_msg_r sumsg, event_t *e)
{
  nua_t *nua;
  nua_handle_t *nh = e->e_nh;

  enter;

Pekka Pessi's avatar
Pekka Pessi committed
1456
  if (nh && nh != nh->nh_nua->nua_handles) {
1457
    if (!nh->nh_ref_by_user && nh->nh_valid) {
Pekka Pessi's avatar
Pekka Pessi committed
1458
      nh->nh_ref_by_user = 1;
1459
      nh_incref(nh);
Pekka Pessi's avatar
Pekka Pessi committed
1460 1461 1462 1463
    }
  }

  if (!nh || !nh->nh_valid) {	/* Handle has been destroyed */
Pekka Pessi's avatar
Pekka Pessi committed
1464
    if (nh && nh != nh->nh_nua->nua_handles && nh_decref(nh)) {
1465 1466
      SU_DEBUG_9(("nua(%p): freed by application\n", nh));
    }
Pekka Pessi's avatar
Pekka Pessi committed
1467 1468 1469 1470 1471
    if (e->e_msg)
      msg_destroy(e->e_msg);
    return;
  }

1472 1473 1474 1475
  nua = nh->nh_nua; assert(nua);

  if (e->e_event == nua_r_shutdown && e->e_status >= 200)
    nua->nua_shutdown_final = 1;
Pekka Pessi's avatar
Pekka Pessi committed
1476 1477 1478 1479

  if (!nua->nua_callback)
    return;

Pekka Pessi's avatar
Pekka Pessi committed
1480
  if (nh == nua->nua_handles)
Pekka Pessi's avatar
Pekka Pessi committed
1481 1482
    nh = NULL;

1483 1484 1485 1486
  su_msg_save(nua->nua_current, sumsg);

  e->e_nh = NULL;

Pekka Pessi's avatar
Pekka Pessi committed
1487 1488 1489 1490 1491 1492
  nua->nua_callback(e->e_event, e->e_status, e->e_phrase,
		    nua, nua->nua_magic,
		    nh, nh ? nh->nh_magic : NULL,
		    e->e_msg ? sip_object(e->e_msg) : NULL,
		    e->e_tags);

1493 1494 1495
  if (!su_msg_is_non_null(nua->nua_current))
    return;

Pekka Pessi's avatar
Pekka Pessi committed
1496 1497
  if (e->e_msg)
    msg_destroy(e->e_msg);
1498

Pekka Pessi's avatar
Pekka Pessi committed
1499
  if (nh && nh != nh->nh_nua->nua_handles && nh_decref(nh)) {
1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510
    SU_DEBUG_9(("nua(%p): freed by application\n", nh));
  }

  su_msg_destroy(nua->nua_current);
}

/** Save nua event and its arguments */
int nua_save_event(nua_t *nua, nua_saved_event_t return_saved[1])
{
  if (nua && return_saved) {
    su_msg_save(return_saved, nua->nua_current);
1511 1512 1513 1514 1515
    if (su_msg_is_non_null(return_saved)) {
      /* Remove references to tasks */
      su_msg_remove_refs(return_saved);
      return 1;
    }
1516 1517 1518 1519
  }
  return 0;
}

1520 1521
/** Get event data */
nua_event_data_t const *nua_event_data(nua_saved_event_t const saved[1])
1522
{
1523
  return saved ? su_msg_data(saved) : NULL;
1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535
}

/** Destroy saved event */
void nua_destroy_event(nua_saved_event_t saved[1])
{
  if (su_msg_is_non_null(saved)) {
    event_t *e = su_msg_data(saved);
    nua_handle_t *nh = e->e_nh;

    if (e->e_msg)
      msg_destroy(e->e_msg);

Pekka Pessi's avatar
Pekka Pessi committed
1536
    if (nh && nh != nh->nh_nua->nua_handles && nh_decref(nh)) {
1537 1538 1539 1540 1541
      SU_DEBUG_9(("nua(%p): freed by application\n", nh));
    }

    su_msg_destroy(saved);
  }
Pekka Pessi's avatar
Pekka Pessi committed
1542
}
1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652

/*******************************************************
 * Obsoleted API functions (to-be-removed)
 *******************************************************/

void
nua_set_media_param(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

void
nua_get_media_param(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

void
nua_media_setup(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

void
nua_media_describe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

void
nua_media_event(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Play. */
void nua_play(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Setup. */
void nua_setup(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Options2. */
void nua_options2(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Describe. */
void nua_describe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Announce. */
void nua_announce(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

void nua_get_parameter(nua_handle_t *nh, tag_type_t tag,
                      tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Set parameter. */
void nua_set_parameter(nua_handle_t *nh, tag_type_t tag,
                      tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Record. */
void nua_record(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Pause. */
void nua_pause(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}

/*# Teardown. */
void nua_teardown(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
{
  /* XXX: to-be-removed */
  SU_DEBUG_0(("**WARNING** Using obsolete API function: %s", __func__));
}