nua.h 13.1 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 <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
#endif

41

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

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

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

SOFIA_BEGIN_DECLS

Pekka Pessi's avatar
Pekka Pessi committed
56 57 58 59 60 61 62 63 64 65 66 67
#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;

68 69 70 71 72 73 74
/**Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES().
 *
 * @sa NUTAG_DETECT_NETWORK_UPDATES(), #nua_i_network_changed
 *
 * @since New in @VERSION_1_12_2.
 */
typedef enum nua_nw_detector_e {
75 76 77 78 79
  NUA_NW_DETECT_NOTHING = 0,
  NUA_NW_DETECT_ONLY_INFO,
  NUA_NW_DETECT_TRY_FULL,
} nua_nw_detector_t;

Pekka Pessi's avatar
Pekka Pessi committed
80 81
/** Events */
typedef enum nua_event_e {
82 83 84
  /* Event used by stack internally */
  nua_i_none = -1,

Pekka Pessi's avatar
Pekka Pessi committed
85
  /* Indications */
Pekka Pessi's avatar
Pekka Pessi committed
86
  nua_i_error,			/**< Error indication */
Pekka Pessi's avatar
Pekka Pessi committed
87

Pekka Pessi's avatar
Pekka Pessi committed
88
  nua_i_invite,			/**< Incoming call INVITE */
89
  nua_i_cancel,			/**< Incoming INVITE has been cancelled */
90
  nua_i_ack,			/**< Final response to INVITE has been ACKed */
Pekka Pessi's avatar
Pekka Pessi committed
91 92
  nua_i_fork,			/**< Outgoing call has been forked */
  nua_i_active,			/**< A call has been activated */
93 94
  nua_i_terminated,		/**< A call has been terminated */
  nua_i_state,		        /**< Call state has changed */
Pekka Pessi's avatar
Pekka Pessi committed
95

Pekka Pessi's avatar
Pekka Pessi committed
96 97
  nua_i_outbound,		/**< Status from outbound processing */

Pekka Pessi's avatar
Pekka Pessi committed
98 99 100
  nua_i_bye,			/**< Incoming BYE call hangup */
  nua_i_options,		/**< Incoming OPTIONS */
  nua_i_refer,			/**< Incoming REFER call transfer */
Pekka Pessi's avatar
Pekka Pessi committed
101 102 103 104 105 106
  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  */
Pekka Pessi's avatar
Pekka Pessi committed
107
  nua_i_subscribe,		/**< Incoming SUBSCRIBE  */
108
  nua_i_subscription,		/**< Incoming subscription to be authorized */
Pekka Pessi's avatar
Pekka Pessi committed
109
  nua_i_notify,			/**< Incoming event NOTIFY */
Pekka Pessi's avatar
Pekka Pessi committed
110 111
  nua_i_method,			/**< Incoming, unknown method */

Pekka Pessi's avatar
Pekka Pessi committed
112
  nua_i_media_error,		/**< Offer-answer error indication */
Pekka Pessi's avatar
Pekka Pessi committed
113 114

  /* Responses */
Pekka Pessi's avatar
Pekka Pessi committed
115 116
  nua_r_set_params,		/**< Answer to nua_set_params() or 
				 * nua_get_hparams(). */
117
  nua_r_get_params,		/**< Answer to nua_get_params() or 
118
				 * nua_get_hparams(). */
Pekka Pessi's avatar
Pekka Pessi committed
119 120 121
  nua_r_shutdown,		/**< Answer to nua_shutdown() */
  nua_r_notifier,		/**< Answer to nua_notifier() */
  nua_r_terminate,		/**< Answer to nua_terminate() */
122
  nua_r_authorize,		/**< Answer to nua_authorize()  */
Pekka Pessi's avatar
Pekka Pessi committed
123 124 125 126 127

  /* SIP responses */
  nua_r_register,		/**< Answer to outgoing REGISTER */
  nua_r_unregister,		/**< Answer to outgoing un-REGISTER */
  nua_r_invite,		        /**< Answer to outgoing INVITE */
128
  nua_r_cancel,			/**< Answer to outgoing CANCEL */
Pekka Pessi's avatar
Pekka Pessi committed
129 130 131 132
  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
133
  nua_r_unpublish,		/**< Answer to outgoing un-PUBLISH */
Pekka Pessi's avatar
Pekka Pessi committed
134
  nua_r_info,		        /**< Answer to outgoing INFO */
Pekka Pessi's avatar
Pekka Pessi committed
135
  nua_r_prack,			/**< Answer to outgoing PRACK */
Pekka Pessi's avatar
Pekka Pessi committed
136 137
  nua_r_update,		        /**< Answer to outgoing UPDATE */
  nua_r_message,		/**< Answer to outgoing MESSAGE */
Pekka Pessi's avatar
Pekka Pessi committed
138
  nua_r_chat,			/**< Answer to outgoing chat message */
Pekka Pessi's avatar
Pekka Pessi committed
139 140 141
  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
142
  nua_r_method,			/**< Answer to unknown outgoing method */
Martti Mela's avatar
Martti Mela committed
143
 
Pekka Pessi's avatar
Pekka Pessi committed
144 145
  nua_r_authenticate,		/**< Answer to nua_authenticate() */

146
  /* Internal events: nua hides them from application */
Pekka Pessi's avatar
Pekka Pessi committed
147 148 149
  nua_r_redirect,
  nua_r_destroy,
  nua_r_respond,
150
  nua_r_nit_respond,
Pekka Pessi's avatar
Pekka Pessi committed
151 152
  nua_r_ack,			/*#< Answer to ACK */

Martti Mela's avatar
Martti Mela committed
153 154
  /* NOTE: Post 1.12 release events come here (below) to keep ABI
     compatibility! */
155 156 157
  nua_i_network_changed,        /**< Local IP(v6) address has changed. 
				   @NEW_1_12_2 */
  nua_i_register,		/**< Incoming REGISTER. @NEW_1_12_4. */
Pekka Pessi's avatar
Pekka Pessi committed
158 159
} nua_event_t;

160 161 162 163 164 165 166 167 168 169
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
170 171 172
/** NUA API version */
#define NUA_VERSION "2.0"
/** NUA module version */
173
SOFIAPUBVAR char const nua_version[];
Pekka Pessi's avatar
Pekka Pessi committed
174

175
/** Typedef of NUA event callback. */
Pekka Pessi's avatar
Pekka Pessi committed
176 177 178 179 180 181 182 183
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. */
184 185 186 187 188
SOFIAPUBFUN nua_t *nua_create(su_root_t *root,
			      nua_callback_f callback,
			      nua_magic_t *magic,
			      tag_type_t tag, tag_value_t value,
			      ...);
Pekka Pessi's avatar
Pekka Pessi committed
189 190

/** Shutdown NUA stack. */
191
SOFIAPUBFUN void nua_shutdown(nua_t *nua);
Pekka Pessi's avatar
Pekka Pessi committed
192 193

/** Destroy the NUA stack. */
194
SOFIAPUBFUN void nua_destroy(nua_t *nua);
Pekka Pessi's avatar
Pekka Pessi committed
195

196 197 198
/** Fetch callback context from nua. */
SOFIAPUBFUN nua_magic_t *nua_magic(nua_t *nua);

Pekka Pessi's avatar
Pekka Pessi committed
199
/** Set NUA parameters. */
200
SOFIAPUBFUN void nua_set_params(nua_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
201 202

/** Get NUA parameters. */
203
SOFIAPUBFUN void nua_get_params(nua_t *nua, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
204 205

/** Obtain default operation handle of the NUA stack object. */
206
SOFIAPUBFUN nua_handle_t *nua_default(nua_t *nua);
Pekka Pessi's avatar
Pekka Pessi committed
207 208

/** Create an operation handle */
209 210
SOFIAPUBFUN nua_handle_t *nua_handle(nua_t *nua, nua_hmagic_t *hmagic,
				     tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
211 212

/** Destroy a handle */
213
SOFIAPUBFUN void nua_handle_destroy(nua_handle_t *h);
Pekka Pessi's avatar
Pekka Pessi committed
214

215
/** Make a new reference to handle */
216
SOFIAPUBFUN nua_handle_t *nua_handle_ref(nua_handle_t *);
217 218

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

Pekka Pessi's avatar
Pekka Pessi committed
221
/** Bind a callback context to an operation handle. */
222
SOFIAPUBFUN void nua_handle_bind(nua_handle_t *nh, nua_hmagic_t *magic);
Pekka Pessi's avatar
Pekka Pessi committed
223

224
/** Fetch a callback context from an operation handle. */
225
SOFIAPUBFUN nua_hmagic_t *nua_handle_magic(nua_handle_t *nh);
226

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

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

Pekka Pessi's avatar
Pekka Pessi committed
233
/** Check if operation handle is used for INVITE */
234
SOFIAPUBFUN int nua_handle_has_invite(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
235 236

/** Check if operation handle has been used with outgoing SUBSCRIBE of REFER request. */
237
SOFIAPUBFUN int nua_handle_has_subscribe(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
238 239

/** Check if operation handle has been used with nua_register() or nua_unregister(). */
240
SOFIAPUBFUN int nua_handle_has_register(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
241 242

/** Check if operation handle has an active call */
243
SOFIAPUBFUN int nua_handle_has_active_call(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
244 245

/** Check if operation handle has a call on hold */
246
SOFIAPUBFUN int nua_handle_has_call_on_hold(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
247 248

/** Check if handle has active event subscriptions (refers sent). */
249
SOFIAPUBFUN int nua_handle_has_events(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
250 251

/** Check if operation handle has active registrations */
252
SOFIAPUBFUN int nua_handle_has_registrations(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
253 254

/** Get the remote address (From/To header) of operation handle */
255
SOFIAPUBFUN sip_to_t const *nua_handle_remote(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
256 257

/** Get the local address (From/To header) of operation handle  */
258
SOFIAPUBFUN sip_to_t const *nua_handle_local(nua_handle_t const *nh);
Pekka Pessi's avatar
Pekka Pessi committed
259 260

/** Get name for NUA event. */
261
SOFIAPUBFUN char const *nua_event_name(nua_event_t event);
Pekka Pessi's avatar
Pekka Pessi committed
262

Pekka Pessi's avatar
Pekka Pessi committed
263 264 265
/** Get name for NUA callstate. */
SOFIAPUBFUN char const *nua_callstate_name(enum nua_callstate state);

Pekka Pessi's avatar
Pekka Pessi committed
266 267 268 269 270 271
/** Return name of subscription state. @NEW_1_12_5. */
SOFIAPUBFUN char const *nua_substate_name(enum nua_substate substate);

/** Convert string to enum nua_substate. @NEW_1_12_5. */
SOFIAPUBFUN enum nua_substate nua_substate_make(char const *sip_substate);

Pekka Pessi's avatar
Pekka Pessi committed
272
/** Send SIP REGISTER request to the registrar. */ 
273
SOFIAPUBFUN void nua_register(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
274 275

/** Unregister. */ 
276
SOFIAPUBFUN void nua_unregister(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
277 278

/** Place a call using SIP INVITE method. */
279
SOFIAPUBFUN void nua_invite(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
280 281

/** Acknowledge a succesfull response to INVITE request. */ 
282
SOFIAPUBFUN void nua_ack(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
283

284
/** Acknowledge a reliable preliminary response to INVITE request. */
285
SOFIAPUBFUN void nua_prack(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
286

Pekka Pessi's avatar
Pekka Pessi committed
287
/** Query capabilities from server */
288
SOFIAPUBFUN void nua_options(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
289 290

/** Send PUBLISH request to publication server. */
291
SOFIAPUBFUN void nua_publish(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
292

Pekka Pessi's avatar
Pekka Pessi committed
293
/** Send un-PUBLISH request to publication server. */
294
SOFIAPUBFUN void nua_unpublish(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
295

Pekka Pessi's avatar
Pekka Pessi committed
296
/** Send an instant message. */
297
SOFIAPUBFUN void nua_message(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
298 299

/** Send a chat message. */
300
SOFIAPUBFUN void nua_chat(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
301 302

/** Send an INFO request. */
303
SOFIAPUBFUN void nua_info(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
304 305

/** Subscribe a SIP event. */
306
SOFIAPUBFUN void nua_subscribe(nua_handle_t *nh, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
307 308

/** Unsubscribe an event. */
309
SOFIAPUBFUN void nua_unsubscribe(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
310 311

/** Send a NOTIFY message. */
312
SOFIAPUBFUN void nua_notify(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
313 314

/** Create an event server. */
315
SOFIAPUBFUN void nua_notifier(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
316 317

/** Terminate an event server. */
318
SOFIAPUBFUN void nua_terminate(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
319 320

/** Transfer a call. */
321
SOFIAPUBFUN void nua_refer(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
322 323

/** Update a call */ 
324
SOFIAPUBFUN void nua_update(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
325 326

/** Hangdown a call. */
327
SOFIAPUBFUN void nua_bye(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
328 329

/** Cancel an INVITE operation */
330
SOFIAPUBFUN void nua_cancel(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
331

Pekka Pessi's avatar
Pekka Pessi committed
332
/** Authenticate an operation. */
333
SOFIAPUBFUN void nua_authenticate(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
334

335
/** Authorize a subscriber. */
336
SOFIAPUBFUN void nua_authorize(nua_handle_t *, tag_type_t, tag_value_t, ...);
337

338
/*# Redirect an operation. @deprecated */
339
SOFIAPUBFUN void nua_redirect(nua_handle_t *, tag_type_t, tag_value_t, ...);
Pekka Pessi's avatar
Pekka Pessi committed
340

341
/** Send a request message with an extension method. */
342 343
SOFIAPUBFUN void nua_method(nua_handle_t *, tag_type_t, tag_value_t, ...);

344
/** Respond to a request with given status code and phrase. */
345 346 347 348
SOFIAPUBFUN void nua_respond(nua_handle_t *nh, 
			     int status, char const *phrase,
			     tag_type_t, tag_value_t, 
			     ...);
Pekka Pessi's avatar
Pekka Pessi committed
349

350 351 352
/** Check if event can be responded with nua_respond() */
SOFIAPUBFUN int nua_event_is_incoming_request(nua_event_t e);

353
/** Cast a #nua_handle_t pointer to a #su_home_t. */
Pekka Pessi's avatar
Pekka Pessi committed
354 355
#define nua_handle_home(nh) ((su_home_t *)(nh))

356
/** Generate an instance identifier. */
357
SOFIAPUBFUN char const *nua_generate_instance_identifier(su_home_t *);
358

Pekka Pessi's avatar
Pekka Pessi committed
359 360 361
#ifndef NUA_SAVED_EVENT_T
#define NUA_SAVED_EVENT_T struct nua_saved_event *
#endif
362
/** Abstract type for saved nua events. */
Pekka Pessi's avatar
Pekka Pessi committed
363 364
typedef NUA_SAVED_EVENT_T nua_saved_event_t;

365
/** Save last nua event */
366
SOFIAPUBFUN int nua_save_event(nua_t *nua, nua_saved_event_t return_saved[1]);
Pekka Pessi's avatar
Pekka Pessi committed
367

368
/** Get information from saved event */
369
SOFIAPUBFUN nua_event_data_t const *nua_event_data(nua_saved_event_t const saved[1]);
Pekka Pessi's avatar
Pekka Pessi committed
370

371
/** Destroy a save nua event */
372
SOFIAPUBFUN void nua_destroy_event(nua_saved_event_t *saved);
Pekka Pessi's avatar
Pekka Pessi committed
373

374 375 376 377 378 379
/** Get request message from saved nua event. */
SOFIAPUBFUN msg_t *nua_saved_event_request(nua_saved_event_t const *saved);

/** Get current request message. */
SOFIAPUBFUN  msg_t *nua_current_request(nua_t const *nua);

380 381 382 383 384 385 386 387
SOFIAPUBFUN sip_replaces_t *nua_handle_make_replaces(nua_handle_t *nh, 
						     su_home_t *home,
						     int early_only);

SOFIAPUBFUN nua_handle_t *nua_handle_by_replaces(nua_t *nua,
						 sip_replaces_t const *rp);


388 389
SOFIA_END_DECLS

Pekka Pessi's avatar
Pekka Pessi committed
390
#endif