1 /* 2 * This file is part of the Sofia-SIP package 3 * 4 * Copyright (C) 2005 Nokia Corporation. 5 * 6 * Contact: Pekka Pessi <pekka.pessi@nokia.com> 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public License 10 * as published by the Free Software Foundation; either version 2.1 of 11 * the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, but 14 * WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 21 * 02110-1301 USA 22 * 23 */ 24 25 /**@file sofia-sip/nua.h 26 * @brief Sofia-SIP User Agent Library API 27 * 28 * @author Pekka Pessi <Pekka.Pessi@nokia.com> 29 * 30 * @date Created: Wed Feb 14 17:09:44 2001 ppessi 31 */ 32 33 #ifndef NUA_H 34 /** Defined when <sofia-sip/nua.h> has been included. */ 35 #define NUA_H 36 37 #ifndef SU_WAIT_H 38 #include <sofia-sip/su_wait.h> 39 #endif 40 41 42 #ifndef URL_H 43 #include <sofia-sip/url.h> 44 #endif 45 46 #ifndef SIP_H 47 #include <sofia-sip/sip.h> 48 #endif 49 50 #ifndef NUA_TAG_H 51 #include <sofia-sip/nua_tag.h> 52 #endif 53 54 SOFIA_BEGIN_DECLS 55 56 #ifndef NUA_MAGIC_T 57 #define NUA_MAGIC_T void 58 #endif 59 /** Application context for NUA agent. */ 60 typedef NUA_MAGIC_T nua_magic_t; 61 62 #ifndef NUA_HMAGIC_T 63 #define NUA_HMAGIC_T void 64 #endif 65 /** Application context for NUA handle. */ 66 typedef NUA_HMAGIC_T nua_hmagic_t; 67 68 /**Network change event levels given to NUTAG_DETECT_NETWORK_UPDATES(). 69 * 70 * @sa NUTAG_DETECT_NETWORK_UPDATES(), #nua_i_network_changed 71 * 72 * @since New in @VERSION_1_12_2. 73 */ 74 typedef enum nua_nw_detector_e { 75 NUA_NW_DETECT_NOTHING = 0, 76 NUA_NW_DETECT_ONLY_INFO, 77 NUA_NW_DETECT_TRY_FULL 78 } nua_nw_detector_t; 79 80 /** Events */ 81 typedef enum nua_event_e { 82 /* Event used by stack internally */ 83 nua_i_none = -1, 84 85 /* Indications */ 86 nua_i_error, /**< Error indication */ 87 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 */ 91 nua_i_fork, /**< Outgoing call has been forked */ 92 nua_i_active, /**< A call has been activated */ 93 nua_i_terminated, /**< A call has been terminated */ 94 nua_i_state, /**< Call state has changed */ 95 96 nua_i_outbound, /**< Status from outbound processing */ 97 98 nua_i_bye, /**< Incoming BYE call hangup */ 99 nua_i_options, /**< Incoming OPTIONS */ 100 nua_i_refer, /**< Incoming REFER call transfer */ 101 nua_i_publish, /**< Incoming PUBLISH */ 102 nua_i_prack, /**< Incoming PRACK */ 103 nua_i_info, /**< Incoming session INFO */ 104 nua_i_update, /**< Incoming session UPDATE */ 105 nua_i_message, /**< Incoming MESSAGE */ 106 nua_i_chat, /**< Incoming chat MESSAGE */ 107 nua_i_subscribe, /**< Incoming SUBSCRIBE */ 108 nua_i_subscription, /**< Incoming subscription to be authorized */ 109 nua_i_notify, /**< Incoming event NOTIFY */ 110 nua_i_method, /**< Incoming, unknown method */ 111 112 nua_i_media_error, /**< Offer-answer error indication */ 113 114 /* Responses */ 115 nua_r_set_params, /**< Answer to nua_set_params() or 116 * nua_get_hparams(). */ 117 nua_r_get_params, /**< Answer to nua_get_params() or 118 * nua_get_hparams(). */ 119 nua_r_shutdown, /**< Answer to nua_shutdown() */ 120 nua_r_notifier, /**< Answer to nua_notifier() */ 121 nua_r_terminate, /**< Answer to nua_terminate() */ 122 nua_r_authorize, /**< Answer to nua_authorize() */ 123 124 /* SIP responses */ 125 nua_r_register, /**< Answer to outgoing REGISTER */ 126 nua_r_unregister, /**< Answer to outgoing un-REGISTER */ 127 nua_r_invite, /**< Answer to outgoing INVITE */ 128 nua_r_cancel, /**< Answer to outgoing CANCEL */ 129 nua_r_bye, /**< Answer to outgoing BYE */ 130 nua_r_options, /**< Answer to outgoing OPTIONS */ 131 nua_r_refer, /**< Answer to outgoing REFER */ 132 nua_r_publish, /**< Answer to outgoing PUBLISH */ 133 nua_r_unpublish, /**< Answer to outgoing un-PUBLISH */ 134 nua_r_info, /**< Answer to outgoing INFO */ 135 nua_r_prack, /**< Answer to outgoing PRACK */ 136 nua_r_update, /**< Answer to outgoing UPDATE */ 137 nua_r_message, /**< Answer to outgoing MESSAGE */ 138 nua_r_chat, /**< Answer to outgoing chat message */ 139 nua_r_subscribe, /**< Answer to outgoing SUBSCRIBE */ 140 nua_r_unsubscribe, /**< Answer to outgoing un-SUBSCRIBE */ 141 nua_r_notify, /**< Answer to outgoing NOTIFY */ 142 nua_r_method, /**< Answer to unknown outgoing method */ 143 144 nua_r_authenticate, /**< Answer to nua_authenticate() */ 145 146 /* Internal events: nua hides them from application */ 147 nua_r_redirect, 148 nua_r_destroy, 149 nua_r_respond, 150 nua_r_nit_respond, 151 nua_r_ack, /*#< Answer to ACK */ 152 153 /* NOTE: Post 1.12 release events come here (below) to keep ABI 154 compatibility! */ 155 nua_i_network_changed, /**< Local IP(v6) address has changed. 156 @NEW_1_12_2 */ 157 nua_i_register /**< Incoming REGISTER. @NEW_1_12_4. */ 158 } nua_event_t; 159 160 typedef struct event_s { 161 nua_handle_t *e_nh; 162 int e_event; 163 short e_always; 164 short e_status; 165 char const *e_phrase; 166 msg_t *e_msg; 167 tagi_t e_tags[1]; 168 } nua_event_data_t; 169 170 /** NUA API version */ 171 #define NUA_VERSION "2.0" 172 /** NUA module version */ 173 SOFIAPUBVAR char const nua_version[]; 174 175 /** Typedef of NUA event callback. */ 176 typedef void (*nua_callback_f)(nua_event_t event, 177 int status, char const *phrase, 178 nua_t *nua, nua_magic_t *magic, 179 nua_handle_t *nh, nua_hmagic_t *hmagic, 180 sip_t const *sip, 181 tagi_t tags[]); 182 183 /** Create a NUA agent. */ 184 SOFIAPUBFUN nua_t *nua_create(su_root_t *root, 185 nua_callback_f callback, 186 nua_magic_t *magic, 187 tag_type_t tag, tag_value_t value, 188 ...); 189 190 /** Shutdown NUA stack. */ 191 SOFIAPUBFUN void nua_shutdown(nua_t *nua); 192 193 /** Destroy the NUA stack. */ 194 SOFIAPUBFUN void nua_destroy(nua_t *nua); 195 196 /** Fetch callback context from nua. */ 197 SOFIAPUBFUN nua_magic_t *nua_magic(nua_t *nua); 198 199 /** Set NUA parameters. */ 200 SOFIAPUBFUN void nua_set_params(nua_t *, tag_type_t, tag_value_t, ...); 201 202 /** Get NUA parameters. */ 203 SOFIAPUBFUN void nua_get_params(nua_t *nua, tag_type_t, tag_value_t, ...); 204 205 /** Obtain default operation handle of the NUA stack object. */ 206 SOFIAPUBFUN nua_handle_t *nua_default(nua_t *nua); 207 208 /** Create an operation handle */ 209 SOFIAPUBFUN nua_handle_t *nua_handle(nua_t *nua, nua_hmagic_t *hmagic, 210 tag_type_t, tag_value_t, ...); 211 212 /** Destroy a handle */ 213 SOFIAPUBFUN void nua_handle_destroy(nua_handle_t *h); 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 221 /** Bind a callback context to an operation handle. */ 222 SOFIAPUBFUN void nua_handle_bind(nua_handle_t *nh, nua_hmagic_t *magic); 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 233 /** Check if operation handle is used for INVITE */ 234 SOFIAPUBFUN int nua_handle_has_invite(nua_handle_t const *nh); 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); 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); 241 242 /** Check if operation handle has an active call */ 243 SOFIAPUBFUN int nua_handle_has_active_call(nua_handle_t const *nh); 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); 247 248 /** Check if handle has active event subscriptions (refers sent). */ 249 SOFIAPUBFUN int nua_handle_has_events(nua_handle_t const *nh); 250 251 /** Check if operation handle has active registrations */ 252 SOFIAPUBFUN int nua_handle_has_registrations(nua_handle_t const *nh); 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); 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); 259 260 /** Get name for NUA event. */ 261 SOFIAPUBFUN char const *nua_event_name(nua_event_t event); 262 263 /** Get name for NUA callstate. */ 264 SOFIAPUBFUN char const *nua_callstate_name(enum nua_callstate state); 265 266 /** Return name of subscription state. @NEW_1_12_5. */ 267 SOFIAPUBFUN char const *nua_substate_name(enum nua_substate substate); 268 269 /** Convert string to enum nua_substate. @NEW_1_12_5. */ 270 SOFIAPUBFUN enum nua_substate nua_substate_make(char const *sip_substate); 271 272 /** Send SIP REGISTER request to the registrar. */ 273 SOFIAPUBFUN void nua_register(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 274 275 /** Unregister. */ 276 SOFIAPUBFUN void nua_unregister(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 277 278 /** Place a call using SIP INVITE method. */ 279 SOFIAPUBFUN void nua_invite(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 280 281 /** Acknowledge a succesfull response to INVITE request. */ 282 SOFIAPUBFUN void nua_ack(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 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 287 /** Query capabilities from server */ 288 SOFIAPUBFUN void nua_options(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 289 290 /** Send PUBLISH request to publication server. */ 291 SOFIAPUBFUN void nua_publish(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 292 293 /** Send un-PUBLISH request to publication server. */ 294 SOFIAPUBFUN void nua_unpublish(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 295 296 /** Send an instant message. */ 297 SOFIAPUBFUN void nua_message(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 298 299 /** Send a chat message. */ 300 SOFIAPUBFUN void nua_chat(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 301 302 /** Send an INFO request. */ 303 SOFIAPUBFUN void nua_info(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 304 305 /** Subscribe a SIP event. */ 306 SOFIAPUBFUN void nua_subscribe(nua_handle_t *nh, tag_type_t, tag_value_t, ...); 307 308 /** Unsubscribe an event. */ 309 SOFIAPUBFUN void nua_unsubscribe(nua_handle_t *, tag_type_t, tag_value_t, ...); 310 311 /** Send a NOTIFY message. */ 312 SOFIAPUBFUN void nua_notify(nua_handle_t *, tag_type_t, tag_value_t, ...); 313 314 /** Create an event server. */ 315 SOFIAPUBFUN void nua_notifier(nua_handle_t *, tag_type_t, tag_value_t, ...); 316 317 /** Terminate an event server. */ 318 SOFIAPUBFUN void nua_terminate(nua_handle_t *, tag_type_t, tag_value_t, ...); 319 320 /** Transfer a call. */ 321 SOFIAPUBFUN void nua_refer(nua_handle_t *, tag_type_t, tag_value_t, ...); 322 323 /** Update a call */ 324 SOFIAPUBFUN void nua_update(nua_handle_t *, tag_type_t, tag_value_t, ...); 325 326 /** Hangdown a call. */ 327 SOFIAPUBFUN void nua_bye(nua_handle_t *, tag_type_t, tag_value_t, ...); 328 329 /** Cancel an INVITE operation */ 330 SOFIAPUBFUN void nua_cancel(nua_handle_t *, tag_type_t, tag_value_t, ...); 331 332 /** Authenticate an operation. */ 333 SOFIAPUBFUN void nua_authenticate(nua_handle_t *, tag_type_t, tag_value_t, ...); 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, ...); 340 341 /** Send a request message with an extension method. */ 342 SOFIAPUBFUN void nua_method(nua_handle_t *, tag_type_t, tag_value_t, ...); 343 344 /** Respond to a request with given status code and phrase. */ 345 SOFIAPUBFUN void nua_respond(nua_handle_t *nh, 346 int status, char const *phrase, 347 tag_type_t, tag_value_t, 348 ...); 349 350 /** Check if event can be responded with nua_respond() */ 351 SOFIAPUBFUN int nua_event_is_incoming_request(nua_event_t e); 352 353 /** Cast a #nua_handle_t pointer to a #su_home_t. */ 354 #define nua_handle_home(nh) ((su_home_t *)(nh)) 355 356 /** Generate an instance identifier. */ 357 SOFIAPUBFUN char const *nua_generate_instance_identifier(su_home_t *); 358 359 #ifndef NUA_SAVED_EVENT_T 360 #define NUA_SAVED_EVENT_T struct nua_saved_event * 361 #endif 362 /** Abstract type for saved nua events. */ 363 typedef NUA_SAVED_EVENT_T nua_saved_event_t; 364 365 /** Save last nua event */ 366 SOFIAPUBFUN int nua_save_event(nua_t *nua, nua_saved_event_t return_saved[1]); 367 368 /** Get information from saved event */ 369 SOFIAPUBFUN nua_event_data_t const *nua_event_data(nua_saved_event_t const saved[1]); 370 371 /** Destroy a save nua event */ 372 SOFIAPUBFUN void nua_destroy_event(nua_saved_event_t *saved); 373 374 /** Get request message from saved nua event. */ 375 SOFIAPUBFUN msg_t *nua_saved_event_request(nua_saved_event_t const *saved); 376 377 /** Get current request message. */ 378 SOFIAPUBFUN msg_t *nua_current_request(nua_t const *nua); 379 380 SOFIAPUBFUN sip_replaces_t *nua_handle_make_replaces(nua_handle_t *nh, 381 su_home_t *home, 382 int early_only); 383 384 SOFIAPUBFUN nua_handle_t *nua_handle_by_replaces(nua_t *nua, 385 sip_replaces_t const *rp); 386 387 nua_handle_t *nua_handle_by_call_id(nua_t *nua, const char *call_id); 388 389 SOFIA_END_DECLS 390 391 #endif 392