nua.h 14 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3 4 5 6 7
/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <pekka.pessi@nokia.com>
 *
8
 * This library is free software; you can redistribute it and/or
Pekka Pessi's avatar
Pekka Pessi committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
 * 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
 *
 */

25 26
/**@file sofia-sip/nua.h  
 * @brief Sofia-SIP User Agent Library API
Pekka Pessi's avatar
Pekka Pessi committed
27 28 29 30 31 32 33
 *
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>
 *
 * @date Created: Wed Feb 14 17:09:44 2001 ppessi
 */

#ifndef NUA_H
34
/** Defined when @b <sofia-sip/nua.h> has been included. */
Pekka Pessi's avatar
Pekka Pessi committed
35
#define NUA_H
Pekka Pessi's avatar
Pekka Pessi committed
36 37

#ifndef SU_WAIT_H
38
#include <sofia-sip/su_wait.h>
Pekka Pessi's avatar
Pekka Pessi committed
39 40 41
#endif

#ifndef URL_H
42
#include <sofia-sip/url.h>
Pekka Pessi's avatar
Pekka Pessi committed
43 44 45
#endif

#ifndef SIP_H
46
#include <sofia-sip/sip.h>
Pekka Pessi's avatar
Pekka Pessi committed
47 48
#endif

49
#ifndef NUA_TAG_H
50
#include <sofia-sip/nua_tag.h>
51 52 53 54
#endif

SOFIA_BEGIN_DECLS

Pekka Pessi's avatar
Pekka Pessi committed
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
#ifndef NUA_MAGIC_T 
#define NUA_MAGIC_T void
#endif
/** Application context for NUA agent. */
typedef NUA_MAGIC_T nua_magic_t;

#ifndef NUA_HMAGIC_T 
#define NUA_HMAGIC_T void
#endif
/** Application context for NUA handle. */
typedef NUA_HMAGIC_T nua_hmagic_t;

/** Events */
typedef enum nua_event_e {
  /* Indications */
Pekka Pessi's avatar
Pekka Pessi committed
70
  nua_i_error,			/**< Error indication */
Pekka Pessi's avatar
Pekka Pessi committed
71 72

  nua_i_invite,			/**< Incoming call */
73 74
  nua_i_cancel,			/**< Incoming INVITE has been cancelled */
  nua_i_ack,			/**< Response to INVITE has been ACKed */
Pekka Pessi's avatar
Pekka Pessi committed
75 76
  nua_i_fork,			/**< Outgoing call has been forked */
  nua_i_active,			/**< A call has been activated */
77 78
  nua_i_terminated,		/**< A call has been terminated */
  nua_i_state,		        /**< Call state has changed */
Pekka Pessi's avatar
Pekka Pessi committed
79 80 81 82 83 84 85 86 87 88 89

  nua_i_bye,			/**< Incoming call hangup */
  nua_i_options,		/**< Incoming options */
  nua_i_refer,			/**< Incoming call transfer */
  nua_i_publish,		/**< Incoming PUBLISH */
  nua_i_prack,			/**< Incoming PRACK */
  nua_i_info,			/**< Incoming session INFO */
  nua_i_update,			/**< Incoming session UPDATE */
  nua_i_message,		/**< Incoming MESSAGE */
  nua_i_chat,			/**< Incoming chat MESSAGE  */
  nua_i_subscribe,		/**< Incoming subscription */
90
  nua_i_subscription,		/**< Incoming subscription to be authorized */
Pekka Pessi's avatar
Pekka Pessi committed
91 92 93
  nua_i_notify,			/**< Incoming event */
  nua_i_method,			/**< Incoming, unknown method */

Pekka Pessi's avatar
Pekka Pessi committed
94
  nua_i_media_error,		/**< Offer-answer error indication */
Pekka Pessi's avatar
Pekka Pessi committed
95 96

  /* Responses */
97
  nua_r_set_params,		/**< Answer to nua_set_params() */
98
  nua_r_get_params,		/**< Answer to nua_get_params() or 
99
				 * nua_get_hparams(). */
Pekka Pessi's avatar
Pekka Pessi committed
100 101 102
  nua_r_shutdown,		/**< Answer to nua_shutdown() */
  nua_r_notifier,		/**< Answer to nua_notifier() */
  nua_r_terminate,		/**< Answer to nua_terminate() */
103
  nua_r_authorize,		/**< Answer to nua_authorize()  */
Pekka Pessi's avatar
Pekka Pessi committed
104 105 106 107 108

  /* SIP responses */
  nua_r_register,		/**< Answer to outgoing REGISTER */
  nua_r_unregister,		/**< Answer to outgoing un-REGISTER */
  nua_r_invite,		        /**< Answer to outgoing INVITE */
109
  nua_r_cancel,			/**< Answer to outgoing CANCEL */
Pekka Pessi's avatar
Pekka Pessi committed
110 111 112 113
  nua_r_bye,			/**< Answer to outgoing BYE */
  nua_r_options,		/**< Answer to outgoing OPTIONS */
  nua_r_refer,			/**< Answer to outgoing REFER */
  nua_r_publish,		/**< Answer to outgoing PUBLISH */
Pekka Pessi's avatar
Pekka Pessi committed
114
  nua_r_unpublish,		/**< Answer to outgoing un-PUBLISH */
Pekka Pessi's avatar
Pekka Pessi committed
115
  nua_r_info,		        /**< Answer to outgoing INFO */
Pekka Pessi's avatar
Pekka Pessi committed
116
  nua_r_prack,			/**< Answer to outgoing PRACK */
Pekka Pessi's avatar
Pekka Pessi committed
117 118
  nua_r_update,		        /**< Answer to outgoing UPDATE */
  nua_r_message,		/**< Answer to outgoing MESSAGE */
Pekka Pessi's avatar
Pekka Pessi committed
119
  nua_r_chat,			/**< Answer to outgoing chat message */
Pekka Pessi's avatar
Pekka Pessi committed
120 121 122
  nua_r_subscribe,		/**< Answer to outgoing SUBSCRIBE */
  nua_r_unsubscribe,		/**< Answer to outgoing un-SUBSCRIBE */
  nua_r_notify,			/**< Answer to outgoing NOTIFY */
Pekka Pessi's avatar
Pekka Pessi committed
123 124
  nua_r_method,			/**< Answer to unknown outgoing method */

125
  /* Internal events: nua hides them from application */
Pekka Pessi's avatar
Pekka Pessi committed
126 127 128 129
  nua_r_authenticate,
  nua_r_redirect,
  nua_r_destroy,
  nua_r_respond,
130
  nua_r_nit_respond,
Pekka Pessi's avatar
Pekka Pessi committed
131 132
  nua_r_ack,			/*#< Answer to ACK */

Pekka Pessi's avatar
Pekka Pessi committed
133

Pekka Pessi's avatar
Pekka Pessi committed
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
  /************************************
   * Obsolete events (to-be-removed): *
   ************************************/
  nua_i_media_event,		/**< Incoming media event */
  nua_r_set_media_param,	/**< Answer to nua_set_media_param() */
  nua_r_get_media_param,	/**< Answer to nua_get_media_param() */
  nua_r_media_setup,		/**< Answer to nua_media_setup() */
  nua_r_media_describe,		/**< Answer to nua_media_describe() */
  nua_r_media_event,		/**< Answer to nua_media_event() */
  /* RTSP methods (obsolete) */
  nua_i_announce,               /*#< Incoming RTSP record announce */
  nua_i_describe,               /*#< Incoming RTSP presentation description */
  nua_i_get_parameter,          /*#< Incoming RTSP server parameter fetch */
  nua_i_pause,                  /*#< Incoming RTSP pause  */
  nua_i_options2,               /*#< Incoming RTSP options */
  nua_i_play,                   /*#< Incoming RTSP play */
  nua_i_record,                 /*#< Incoming RTSP record  */
  nua_i_set_parameter,          /*#< Incoming RTSP server parameter setting  */
  nua_i_setup,                  /*#< Incoming RTSP setup */
  nua_i_teardown,               /*#< Incoming RTSP teardown the session */
  /* RTSP responses (obsolete) */
Pekka Pessi's avatar
Pekka Pessi committed
155 156 157 158 159 160 161 162 163
  nua_r_setup,                  /*#< Answer to outgoing SETUP */
  nua_r_play,                   /*#< Answer to outgoing PLAY */
  nua_r_record,                 /*#< Answer to outgoing RECORD */
  nua_r_pause,                  /*#< Answer to outgoing PAUSE */
  nua_r_describe,               /*#< Answer to outgoing DESCRIBE */
  nua_r_teardown,               /*#< Answer to outgoing TEARDOWN */
  nua_r_options2,               /*#< Answer to outgoing OPTIONS */
  nua_r_announce,               /*#< Answer to outgoing ANNOUNCE */
  nua_r_get_parameter,          /*#< Answer to outgoing GET_PARAMETER */
Pekka Pessi's avatar
Pekka Pessi committed
164
  nua_r_set_parameter           /*#< Answer to outgoing SET_PARAMETER */
Pekka Pessi's avatar
Pekka Pessi committed
165 166 167

} nua_event_t;

168 169 170 171 172 173 174 175 176 177
typedef struct event_s {
  nua_handle_t *e_nh;
  int           e_event;
  short         e_always;
  short         e_status;
  char const   *e_phrase;
  msg_t        *e_msg;
  tagi_t        e_tags[1];
} nua_event_data_t;

Pekka Pessi's avatar
Pekka Pessi committed
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
/** NUA API version */
#define NUA_VERSION "2.0"
/** NUA module version */
extern char const nua_version[];

typedef void (*nua_callback_f)(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[]);

/** Create a NUA agent. */
nua_t *nua_create(su_root_t *root,
		  nua_callback_f callback,
		  nua_magic_t *magic,
		  tag_type_t tag, tag_value_t value,
		  ...);

/** Shutdown NUA stack. */
void nua_shutdown(nua_t *nua);

/** Destroy the NUA stack. */
void nua_destroy(nua_t *nua);

/** Set NUA parameters. */
void nua_set_params(nua_t *nua, tag_type_t tag, tag_value_t value, ...);

/** Get NUA parameters. */
void nua_get_params(nua_t *nua, tag_type_t tag, tag_value_t value, ...);

/** Obtain default operation handle of the NUA stack object. */
nua_handle_t *nua_default(nua_t *nua);

/** Create an operation handle */
nua_handle_t *nua_handle(nua_t *nua, nua_hmagic_t *hmagic,
			 tag_type_t tag, tag_value_t value, ...);

/** Destroy a handle */
void nua_handle_destroy(nua_handle_t *h);

219 220 221 222 223 224
/** Make a new reference to handle */
nua_handle_t *nua_handle_ref(nua_handle_t *);

/** Destroy reference to handle */
int nua_handle_unref(nua_handle_t *);

Pekka Pessi's avatar
Pekka Pessi committed
225 226 227
/** Bind a callback context to an operation handle. */
void nua_handle_bind(nua_handle_t *nh, nua_hmagic_t *magic);

228
/** Set handle parameters. */
229
void nua_set_hparams(nua_handle_t *, tag_type_t, tag_value_t, ...);
230 231

/** Get handle parameters. */
232
void nua_get_hparams(nua_handle_t *, tag_type_t, tag_value_t, ...);
233

Pekka Pessi's avatar
Pekka Pessi committed
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 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
/** Check if operation handle is used for INVITE */
int nua_handle_has_invite(nua_handle_t const *nh);

/** Check if operation handle has been used with outgoing SUBSCRIBE of REFER request. */
int nua_handle_has_subscribe(nua_handle_t const *nh);

/** Check if operation handle has been used with nua_register() or nua_unregister(). */
int nua_handle_has_register(nua_handle_t const *nh);

/** Check if operation handle has an active call */
int nua_handle_has_active_call(nua_handle_t const *nh);

/** Check if operation handle has a call on hold */
int nua_handle_has_call_on_hold(nua_handle_t const *nh);

/** Check if handle has active event subscriptions (refers sent). */
int nua_handle_has_events(nua_handle_t const *nh);

/** Check if operation handle has active registrations */
int nua_handle_has_registrations(nua_handle_t const *nh);

/** Get the remote address (From/To header) of operation handle */
sip_to_t const *nua_handle_remote(nua_handle_t const *nh);

/** Get the local address (From/To header) of operation handle  */
sip_to_t const *nua_handle_local(nua_handle_t const *nh);

/** Get name for NUA event. */
char const *nua_event_name(nua_event_t event);

/** Send SIP REGISTER request to the registrar. */ 
void nua_register(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Unregister. */ 
void nua_unregister(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Place a call using SIP INVITE method. */
void nua_invite(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Acknowledge a succesfull response to INVITE request. */ 
void nua_ack(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Query capabilities from server */
void nua_options(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Send PUBLISH request to publication server. */
void nua_publish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

Pekka Pessi's avatar
Pekka Pessi committed
282 283 284
/** Send un-PUBLISH request to publication server. */
void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

Pekka Pessi's avatar
Pekka Pessi committed
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323
/** Send an instant message. */
void nua_message(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Send a chat message. */
void nua_chat(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Send an INFO request. */
void nua_info(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Subscribe a SIP event. */
void nua_subscribe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/** Unsubscribe an event. */
void nua_unsubscribe(nua_handle_t *, tag_type_t, tag_value_t, ...);

/** Send a NOTIFY message. */
void nua_notify(nua_handle_t *, tag_type_t, tag_value_t, ...);

/** Create an event server. */
void nua_notifier(nua_handle_t *, tag_type_t, tag_value_t, ...);

/** Terminate an event server. */
void nua_terminate(nua_handle_t *, tag_type_t, tag_value_t, ...);

/** Transfer a call. */
void nua_refer(nua_handle_t *, tag_type_t, tag_value_t, ...);

/** Update a call */ 
void nua_update(nua_handle_t *, tag_type_t tag, tag_value_t value, ...);

/** Hangdown a call. */
void nua_bye(nua_handle_t *, tag_type_t, tag_value_t, ...);

/** Cancel an INVITE operation */
void nua_cancel(nua_handle_t *, tag_type_t, tag_value_t, ...);
 
/** Authenticate an operation. */
void nua_authenticate(nua_handle_t *, tag_type_t, tag_value_t, ...);

324 325 326
/** Authorize a subscriber. */
void nua_authorize(nua_handle_t *, tag_type_t, tag_value_t, ...);

327
/** Redirect an operation. */
Pekka Pessi's avatar
Pekka Pessi committed
328 329
void nua_redirect(nua_handle_t *, tag_type_t, tag_value_t, ...);

330
/** Respond with given status. */
Pekka Pessi's avatar
Pekka Pessi committed
331 332 333 334 335 336 337
void nua_respond(nua_handle_t *nh, 
		 int status, char const *phrase,
		 tag_type_t tag, tag_value_t value, 
		 ...);

#define nua_handle_home(nh) ((su_home_t *)(nh))

Pekka Pessi's avatar
Pekka Pessi committed
338 339 340 341 342
#ifndef NUA_SAVED_EVENT_T
#define NUA_SAVED_EVENT_T struct nua_saved_event *
#endif
typedef NUA_SAVED_EVENT_T nua_saved_event_t;

343
/** Save last nua event */
344
int nua_save_event(nua_t *nua, nua_saved_event_t return_saved[1]);
Pekka Pessi's avatar
Pekka Pessi committed
345

346 347
/** Get information from saved event */
nua_event_data_t const *nua_event_data(nua_saved_event_t const saved[1]);
Pekka Pessi's avatar
Pekka Pessi committed
348

349
/** Destroy a save nua event */
Pekka Pessi's avatar
Pekka Pessi committed
350 351
void nua_destroy_event(nua_saved_event_t *saved);

352 353 354 355
/***************************************
 * Obsolete functions (to-be-removed): *
 ***************************************/

356 357 358
/** XXX/obsolete: Check for RTSP support. */ 
int nua_handle_has_streaming(nua_handle_t const *nh);

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
/** XXX/obsolete: Set media parameter. */ 
void nua_set_media_param(nua_handle_t *nh, tag_type_t, tag_value_t, ...);

/** XXX/obsolete: Get a media parameter. */ 
void nua_get_media_param(nua_handle_t *nh, tag_type_t, tag_value_t, ...);

/** XXX/obsolete: Setup a local media session. */
void nua_media_setup(nua_handle_t *nh, tag_type_t, tag_value_t, ...);

/** XXX/obsolete: Describe a media session using SDP. */
void nua_media_describe(nua_handle_t *nh, tag_type_t, tag_value_t, ...);

/** XXX/obsolete: Send an event to media subsystem. */
void nua_media_event(nua_handle_t *nh, tag_type_t, tag_value_t, ...);

/*# XXX/obsolete: Play. */ 
void nua_play(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/*# XXX/obsolete: Setup. */ 
void nua_setup(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/*# XXX/obsolete: Options2. */ 
void nua_options2(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/*# XXX/obsolete: Describe. */ 
void nua_describe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/*# XXX/obsolete: Announce. */ 
void nua_announce(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/*# XXX/obsolete: Get RTSP parameter. */ 
void nua_get_parameter(nua_handle_t *nh, tag_type_t tag,
		       tag_value_t value, ...);

/*# XXX/obsolete: Set RTSP parameter. */ 
void nua_set_parameter(nua_handle_t *nh, tag_type_t tag,
		       tag_value_t value, ...);

/*# XXX/obsolete: Record. */ 
void nua_record(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/*# XXX/obsolete: Pause. */ 
void nua_pause(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

/*# XXX/obsolete: Teardown. */ 
void nua_teardown(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);

406 407
SOFIA_END_DECLS

Pekka Pessi's avatar
Pekka Pessi committed
408
#endif