00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2006, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief Core PBX routines and definitions. 00021 */ 00022 00023 #ifndef _ASTERISK_PBX_H 00024 #define _ASTERISK_PBX_H 00025 00026 #include "asterisk/sched.h" 00027 #include "asterisk/devicestate.h" 00028 #include "asterisk/chanvars.h" 00029 #include "asterisk/hashtab.h" 00030 #include "asterisk/stringfields.h" 00031 00032 #if defined(__cplusplus) || defined(c_plusplus) 00033 extern "C" { 00034 #endif 00035 00036 #define AST_MAX_APP 32 /*!< Max length of an application */ 00037 00038 #define AST_PBX_KEEP 0 00039 #define AST_PBX_REPLACE 1 00040 00041 /*! \brief Special return values from applications to the PBX 00042 * @{ */ 00043 #define AST_PBX_HANGUP -1 /*!< Jump to the 'h' exten */ 00044 #define AST_PBX_OK 0 /*!< No errors */ 00045 #define AST_PBX_ERROR 1 /*!< Jump to the 'e' exten */ 00046 #define AST_PBX_INCOMPLETE 12 /*!< Return to PBX matching, allowing more digits for the extension */ 00047 /*! @} */ 00048 00049 #define PRIORITY_HINT -1 /*!< Special Priority for a hint */ 00050 00051 /*! \brief Extension states 00052 \note States can be combined 00053 - \ref AstExtState 00054 */ 00055 enum ast_extension_states { 00056 AST_EXTENSION_REMOVED = -2, /*!< Extension removed */ 00057 AST_EXTENSION_DEACTIVATED = -1, /*!< Extension hint removed */ 00058 AST_EXTENSION_NOT_INUSE = 0, /*!< No device INUSE or BUSY */ 00059 AST_EXTENSION_INUSE = 1 << 0, /*!< One or more devices INUSE */ 00060 AST_EXTENSION_BUSY = 1 << 1, /*!< All devices BUSY */ 00061 AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */ 00062 AST_EXTENSION_RINGING = 1 << 3, /*!< All devices RINGING */ 00063 AST_EXTENSION_ONHOLD = 1 << 4, /*!< All devices ONHOLD */ 00064 }; 00065 00066 00067 struct ast_context; 00068 struct ast_exten; 00069 struct ast_include; 00070 struct ast_ignorepat; 00071 struct ast_sw; 00072 00073 /*! \brief Typedef for devicestate and hint callbacks */ 00074 typedef int (*ast_state_cb_type)(char *context, char* id, enum ast_extension_states state, void *data); 00075 00076 /*! \brief From where the documentation come from */ 00077 enum ast_doc_src { 00078 AST_XML_DOC, /*!< From XML documentation */ 00079 AST_STATIC_DOC /*!< From application/function registration */ 00080 }; 00081 00082 /*! \brief Data structure associated with a custom dialplan function */ 00083 struct ast_custom_function { 00084 const char *name; /*!< Name */ 00085 AST_DECLARE_STRING_FIELDS( 00086 AST_STRING_FIELD(synopsis); /*!< Synopsis text for 'show functions' */ 00087 AST_STRING_FIELD(desc); /*!< Description (help text) for 'show functions <name>' */ 00088 AST_STRING_FIELD(syntax); /*!< Syntax text for 'core show functions' */ 00089 AST_STRING_FIELD(arguments); /*!< Arguments description */ 00090 AST_STRING_FIELD(seealso); /*!< See also */ 00091 ); 00092 enum ast_doc_src docsrc; /*!< Where the documentation come from */ 00093 ast_acf_read_fn_t read; /*!< Read function, if read is supported */ 00094 ast_acf_write_fn_t write; /*!< Write function, if write is supported */ 00095 struct ast_module *mod; /*!< Module this custom function belongs to */ 00096 AST_RWLIST_ENTRY(ast_custom_function) acflist; 00097 }; 00098 00099 /*! \brief All switch functions have the same interface, so define a type for them */ 00100 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context, 00101 const char *exten, int priority, const char *callerid, const char *data); 00102 00103 /*!< Data structure associated with an Asterisk switch */ 00104 struct ast_switch { 00105 AST_LIST_ENTRY(ast_switch) list; 00106 const char *name; /*!< Name of the switch */ 00107 const char *description; /*!< Description of the switch */ 00108 00109 ast_switch_f *exists; 00110 ast_switch_f *canmatch; 00111 ast_switch_f *exec; 00112 ast_switch_f *matchmore; 00113 }; 00114 00115 struct ast_timing { 00116 int hastime; /*!< If time construct exists */ 00117 unsigned int monthmask; /*!< Mask for month */ 00118 unsigned int daymask; /*!< Mask for date */ 00119 unsigned int dowmask; /*!< Mask for day of week (sun-sat) */ 00120 unsigned int minmask[48]; /*!< Mask for minute */ 00121 char *timezone; /*!< NULL, or zoneinfo style timezone */ 00122 }; 00123 00124 /*!\brief Construct a timing bitmap, for use in time-based conditionals. 00125 * \param i Pointer to an ast_timing structure. 00126 * \param info Standard string containing a timerange, weekday range, monthday range, and month range, as well as an optional timezone. 00127 * \retval Returns 1 on success or 0 on failure. 00128 */ 00129 int ast_build_timing(struct ast_timing *i, const char *info); 00130 00131 /*!\brief Evaluate a pre-constructed bitmap as to whether the current time falls within the range specified. 00132 * \param i Pointer to an ast_timing structure. 00133 * \retval Returns 1, if the time matches or 0, if the current time falls outside of the specified range. 00134 */ 00135 int ast_check_timing(const struct ast_timing *i); 00136 00137 /*!\brief Deallocates memory structures associated with a timing bitmap. 00138 * \param i Pointer to an ast_timing structure. 00139 * \retval 0 success 00140 * \retval non-zero failure (number suitable to pass to \see strerror) 00141 */ 00142 int ast_destroy_timing(struct ast_timing *i); 00143 00144 struct ast_pbx { 00145 int dtimeoutms; /*!< Timeout between digits (milliseconds) */ 00146 int rtimeoutms; /*!< Timeout for response (milliseconds) */ 00147 }; 00148 00149 00150 /*! 00151 * \brief Register an alternative dialplan switch 00152 * 00153 * \param sw switch to register 00154 * 00155 * This function registers a populated ast_switch structure with the 00156 * asterisk switching architecture. 00157 * 00158 * \retval 0 success 00159 * \retval non-zero failure 00160 */ 00161 int ast_register_switch(struct ast_switch *sw); 00162 00163 /*! 00164 * \brief Unregister an alternative switch 00165 * 00166 * \param sw switch to unregister 00167 * 00168 * Unregisters a switch from asterisk. 00169 * 00170 * \return nothing 00171 */ 00172 void ast_unregister_switch(struct ast_switch *sw); 00173 00174 /*! 00175 * \brief Look up an application 00176 * 00177 * \param app name of the app 00178 * 00179 * This function searches for the ast_app structure within 00180 * the apps that are registered for the one with the name 00181 * you passed in. 00182 * 00183 * \return the ast_app structure that matches on success, or NULL on failure 00184 */ 00185 struct ast_app *pbx_findapp(const char *app); 00186 00187 /*! 00188 * \brief Execute an application 00189 * 00190 * \param c channel to execute on 00191 * \param app which app to execute 00192 * \param data the data passed into the app 00193 * 00194 * This application executes an application on a given channel. It 00195 * saves the stack and executes the given application passing in 00196 * the given data. 00197 * 00198 * \retval 0 success 00199 * \retval -1 failure 00200 */ 00201 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data); 00202 00203 /*! 00204 * \brief Register a new context or find an existing one 00205 * 00206 * \param extcontexts pointer to the ast_context structure pointer 00207 * \param exttable pointer to the hashtable that contains all the elements in extcontexts 00208 * \param name name of the new context 00209 * \param registrar registrar of the context 00210 * 00211 * This function allows you to play in two environments: the global contexts (active dialplan) 00212 * or an external context set of your choosing. To act on the external set, make sure extcontexts 00213 * and exttable are set; for the globals, make sure both extcontexts and exttable are NULL. 00214 * 00215 * This will first search for a context with your name. If it exists already, it will not 00216 * create a new one. If it does not exist, it will create a new one with the given name 00217 * and registrar. 00218 * 00219 * \return NULL on failure, and an ast_context structure on success 00220 */ 00221 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar); 00222 00223 /*! 00224 * \brief Merge the temporary contexts into a global contexts list and delete from the 00225 * global list the ones that are being added 00226 * 00227 * \param extcontexts pointer to the ast_context structure 00228 * \param exttable pointer to the ast_hashtab structure that contains all the elements in extcontexts 00229 * \param registrar of the context; if it's set the routine will delete all contexts 00230 * that belong to that registrar; if NULL only the contexts that are specified 00231 * in extcontexts 00232 */ 00233 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar); 00234 00235 /*! 00236 * \brief Destroy a context (matches the specified context (or ANY context if NULL) 00237 * 00238 * \param con context to destroy 00239 * \param registrar who registered it 00240 * 00241 * You can optionally leave out either parameter. It will find it 00242 * based on either the ast_context or the registrar name. 00243 * 00244 * \return nothing 00245 */ 00246 void ast_context_destroy(struct ast_context *con, const char *registrar); 00247 00248 /*! 00249 * \brief Find a context 00250 * 00251 * \param name name of the context to find 00252 * 00253 * Will search for the context with the given name. 00254 * 00255 * \return the ast_context on success, NULL on failure. 00256 */ 00257 struct ast_context *ast_context_find(const char *name); 00258 00259 /*! \brief The result codes when starting the PBX on a channel with \see ast_pbx_start. 00260 AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf 00261 */ 00262 enum ast_pbx_result { 00263 AST_PBX_SUCCESS = 0, 00264 AST_PBX_FAILED = -1, 00265 AST_PBX_CALL_LIMIT = -2, 00266 }; 00267 00268 /*! 00269 * \brief Create a new thread and start the PBX 00270 * 00271 * \param c channel to start the pbx on 00272 * 00273 * \see ast_pbx_run for a synchronous function to run the PBX in the 00274 * current thread, as opposed to starting a new one. 00275 * 00276 * \retval Zero on success 00277 * \retval non-zero on failure 00278 */ 00279 enum ast_pbx_result ast_pbx_start(struct ast_channel *c); 00280 00281 /*! 00282 * \brief Execute the PBX in the current thread 00283 * 00284 * \param c channel to run the pbx on 00285 * 00286 * This executes the PBX on a given channel. It allocates a new 00287 * PBX structure for the channel, and provides all PBX functionality. 00288 * See ast_pbx_start for an asynchronous function to run the PBX in a 00289 * new thread as opposed to the current one. 00290 * 00291 * \retval Zero on success 00292 * \retval non-zero on failure 00293 */ 00294 enum ast_pbx_result ast_pbx_run(struct ast_channel *c); 00295 00296 /*! 00297 * \brief Options for ast_pbx_run() 00298 */ 00299 struct ast_pbx_args { 00300 union { 00301 /*! Pad this out so that we have plenty of room to add options 00302 * but still maintain ABI compatibility over time. */ 00303 uint64_t __padding; 00304 struct { 00305 /*! Do not hangup the channel when the PBX is complete. */ 00306 unsigned int no_hangup_chan:1; 00307 }; 00308 }; 00309 }; 00310 00311 /*! 00312 * \brief Execute the PBX in the current thread 00313 * 00314 * \param c channel to run the pbx on 00315 * \param args options for the pbx 00316 * 00317 * This executes the PBX on a given channel. It allocates a new 00318 * PBX structure for the channel, and provides all PBX functionality. 00319 * See ast_pbx_start for an asynchronous function to run the PBX in a 00320 * new thread as opposed to the current one. 00321 * 00322 * \retval Zero on success 00323 * \retval non-zero on failure 00324 */ 00325 enum ast_pbx_result ast_pbx_run_args(struct ast_channel *c, struct ast_pbx_args *args); 00326 00327 /*! 00328 * \brief Add and extension to an extension context. 00329 * 00330 * \param context context to add the extension to 00331 * \param replace 00332 * \param extension extension to add 00333 * \param priority priority level of extension addition 00334 * \param label extension label 00335 * \param callerid pattern to match CallerID, or NULL to match any CallerID 00336 * \param application application to run on the extension with that priority level 00337 * \param data data to pass to the application 00338 * \param datad 00339 * \param registrar who registered the extension 00340 * 00341 * \retval 0 success 00342 * \retval -1 failure 00343 */ 00344 int ast_add_extension(const char *context, int replace, const char *extension, 00345 int priority, const char *label, const char *callerid, 00346 const char *application, void *data, void (*datad)(void *), const char *registrar); 00347 00348 /*! 00349 * \brief Add an extension to an extension context, this time with an ast_context *. 00350 * 00351 * \note For details about the arguments, check ast_add_extension() 00352 */ 00353 int ast_add_extension2(struct ast_context *con, int replace, const char *extension, 00354 int priority, const char *label, const char *callerid, 00355 const char *application, void *data, void (*datad)(void *), const char *registrar); 00356 00357 /*! 00358 * \brief Map devstate to an extension state. 00359 * 00360 * \param[in] device state 00361 * 00362 * \return the extension state mapping. 00363 */ 00364 enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate); 00365 00366 /*! 00367 * \brief Uses hint and devicestate callback to get the state of an extension 00368 * 00369 * \param c this is not important 00370 * \param context which context to look in 00371 * \param exten which extension to get state 00372 * 00373 * \return extension state as defined in the ast_extension_states enum 00374 */ 00375 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten); 00376 00377 /*! 00378 * \brief Return string representation of the state of an extension 00379 * 00380 * \param extension_state is the numerical state delivered by ast_extension_state 00381 * 00382 * \return the state of an extension as string 00383 */ 00384 const char *ast_extension_state2str(int extension_state); 00385 00386 /*! 00387 * \brief Registers a state change callback 00388 * 00389 * \param context which context to look in 00390 * \param exten which extension to get state 00391 * \param callback callback to call if state changed 00392 * \param data to pass to callback 00393 * 00394 * The callback is called if the state of an extension is changed. 00395 * 00396 * \retval -1 on failure 00397 * \retval ID on success 00398 */ 00399 int ast_extension_state_add(const char *context, const char *exten, 00400 ast_state_cb_type callback, void *data); 00401 00402 /*! 00403 * \brief Deletes a registered state change callback by ID 00404 * 00405 * \param id of the callback to delete 00406 * \param callback callback 00407 * 00408 * Removes the callback from list of callbacks 00409 * 00410 * \retval 0 success 00411 * \retval -1 failure 00412 */ 00413 int ast_extension_state_del(int id, ast_state_cb_type callback); 00414 00415 /*! 00416 * \brief If an extension hint exists, return non-zero 00417 * 00418 * \param hint buffer for hint 00419 * \param hintsize size of hint buffer, in bytes 00420 * \param name buffer for name portion of hint 00421 * \param namesize size of name buffer 00422 * \param c Channel from which to return the hint. This is only important when the hint or name contains an expression to be expanded. 00423 * \param context which context to look in 00424 * \param exten which extension to search for 00425 * 00426 * \return If an extension within the given context with the priority PRIORITY_HINT 00427 * is found, a non zero value will be returned. 00428 * Otherwise, 0 is returned. 00429 */ 00430 int ast_get_hint(char *hint, int hintsize, char *name, int namesize, 00431 struct ast_channel *c, const char *context, const char *exten); 00432 00433 /*! 00434 * \brief Determine whether an extension exists 00435 * 00436 * \param c this is not important 00437 * \param context which context to look in 00438 * \param exten which extension to search for 00439 * \param priority priority of the action within the extension 00440 * \param callerid callerid to search for 00441 * 00442 * \note It is possible for autoservice to be started and stopped on c during this 00443 * function call, it is important that c is not locked prior to calling this. Otherwise 00444 * a deadlock may occur 00445 * 00446 * \return If an extension within the given context(or callerid) with the given priority 00447 * is found a non zero value will be returned. Otherwise, 0 is returned. 00448 */ 00449 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, 00450 int priority, const char *callerid); 00451 00452 /*! 00453 * \brief Find the priority of an extension that has the specified label 00454 * 00455 * \param c this is not important 00456 * \param context which context to look in 00457 * \param exten which extension to search for 00458 * \param label label of the action within the extension to match to priority 00459 * \param callerid callerid to search for 00460 * 00461 * \note It is possible for autoservice to be started and stopped on c during this 00462 * function call, it is important that c is not locked prior to calling this. Otherwise 00463 * a deadlock may occur 00464 * 00465 * \retval the priority which matches the given label in the extension 00466 * \retval -1 if not found. 00467 */ 00468 int ast_findlabel_extension(struct ast_channel *c, const char *context, 00469 const char *exten, const char *label, const char *callerid); 00470 00471 /*! 00472 * \brief Find the priority of an extension that has the specified label 00473 * 00474 * \note It is possible for autoservice to be started and stopped on c during this 00475 * function call, it is important that c is not locked prior to calling this. Otherwise 00476 * a deadlock may occur 00477 * 00478 * \note This function is the same as ast_findlabel_extension, except that it accepts 00479 * a pointer to an ast_context structure to specify the context instead of the 00480 * name of the context. Otherwise, the functions behave the same. 00481 */ 00482 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, 00483 const char *exten, const char *label, const char *callerid); 00484 00485 /*! 00486 * \brief Looks for a valid matching extension 00487 * 00488 * \param c not really important 00489 * \param context context to serach within 00490 * \param exten extension to check 00491 * \param priority priority of extension path 00492 * \param callerid callerid of extension being searched for 00493 * 00494 * \note It is possible for autoservice to be started and stopped on c during this 00495 * function call, it is important that c is not locked prior to calling this. Otherwise 00496 * a deadlock may occur 00497 * 00498 * \return If "exten" *could be* a valid extension in this context with or without 00499 * some more digits, return non-zero. Basically, when this returns 0, no matter 00500 * what you add to exten, it's not going to be a valid extension anymore 00501 */ 00502 int ast_canmatch_extension(struct ast_channel *c, const char *context, 00503 const char *exten, int priority, const char *callerid); 00504 00505 /*! 00506 * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch) 00507 * 00508 * \param c not really important XXX 00509 * \param context context to serach within 00510 * \param exten extension to check 00511 * \param priority priority of extension path 00512 * \param callerid callerid of extension being searched for 00513 * 00514 * \note It is possible for autoservice to be started and stopped on c during this 00515 * function call, it is important that c is not locked prior to calling this. Otherwise 00516 * a deadlock may occur 00517 * 00518 * \return If "exten" *could match* a valid extension in this context with 00519 * some more digits, return non-zero. Does NOT return non-zero if this is 00520 * an exact-match only. Basically, when this returns 0, no matter 00521 * what you add to exten, it's not going to be a valid extension anymore 00522 */ 00523 int ast_matchmore_extension(struct ast_channel *c, const char *context, 00524 const char *exten, int priority, const char *callerid); 00525 00526 /*! 00527 * \brief Determine if a given extension matches a given pattern (in NXX format) 00528 * 00529 * \param pattern pattern to match 00530 * \param extension extension to check against the pattern. 00531 * 00532 * Checks whether or not the given extension matches the given pattern. 00533 * 00534 * \retval 1 on match 00535 * \retval 0 on failure 00536 */ 00537 int ast_extension_match(const char *pattern, const char *extension); 00538 00539 int ast_extension_close(const char *pattern, const char *data, int needmore); 00540 00541 /*! 00542 * \brief Determine if one extension should match before another 00543 * 00544 * \param a extension to compare with b 00545 * \param b extension to compare with a 00546 * 00547 * Checks whether or extension a should match before extension b 00548 * 00549 * \retval 0 if the two extensions have equal matching priority 00550 * \retval 1 on a > b 00551 * \retval -1 on a < b 00552 */ 00553 int ast_extension_cmp(const char *a, const char *b); 00554 00555 /*! 00556 * \brief Launch a new extension (i.e. new stack) 00557 * 00558 * \param c not important 00559 * \param context which context to generate the extension within 00560 * \param exten new extension to add 00561 * \param priority priority of new extension 00562 * \param callerid callerid of extension 00563 * \param found 00564 * \param combined_find_spawn 00565 * 00566 * This adds a new extension to the asterisk extension list. 00567 * 00568 * \note It is possible for autoservice to be started and stopped on c during this 00569 * function call, it is important that c is not locked prior to calling this. Otherwise 00570 * a deadlock may occur 00571 * 00572 * \retval 0 on success 00573 * \retval -1 on failure. 00574 */ 00575 int ast_spawn_extension(struct ast_channel *c, const char *context, 00576 const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn); 00577 00578 /*! 00579 * \brief Add a context include 00580 * 00581 * \param context context to add include to 00582 * \param include new include to add 00583 * \param registrar who's registering it 00584 * 00585 * Adds an include taking a char * string as the context parameter 00586 * 00587 * \retval 0 on success 00588 * \retval -1 on error 00589 */ 00590 int ast_context_add_include(const char *context, const char *include, 00591 const char *registrar); 00592 00593 /*! 00594 * \brief Add a context include 00595 * 00596 * \param con context to add the include to 00597 * \param include include to add 00598 * \param registrar who registered the context 00599 * 00600 * Adds an include taking a struct ast_context as the first parameter 00601 * 00602 * \retval 0 on success 00603 * \retval -1 on failure 00604 */ 00605 int ast_context_add_include2(struct ast_context *con, const char *include, 00606 const char *registrar); 00607 00608 /*! 00609 * \brief Remove a context include 00610 * 00611 * \note See ast_context_add_include for information on arguments 00612 * 00613 * \retval 0 on success 00614 * \retval -1 on failure 00615 */ 00616 int ast_context_remove_include(const char *context, const char *include, 00617 const char *registrar); 00618 00619 /*! 00620 * \brief Removes an include by an ast_context structure 00621 * 00622 * \note See ast_context_add_include2 for information on arguments 00623 * 00624 * \retval 0 on success 00625 * \retval -1 on success 00626 */ 00627 int ast_context_remove_include2(struct ast_context *con, const char *include, 00628 const char *registrar); 00629 00630 /*! 00631 * \brief Verifies includes in an ast_contect structure 00632 * 00633 * \param con context in which to verify the includes 00634 * 00635 * \retval 0 if no problems found 00636 * \retval -1 if there were any missing context 00637 */ 00638 int ast_context_verify_includes(struct ast_context *con); 00639 00640 /*! 00641 * \brief Add a switch 00642 * 00643 * \param context context to which to add the switch 00644 * \param sw switch to add 00645 * \param data data to pass to switch 00646 * \param eval whether to evaluate variables when running switch 00647 * \param registrar whoever registered the switch 00648 * 00649 * This function registers a switch with the asterisk switch architecture 00650 * 00651 * \retval 0 on success 00652 * \retval -1 on failure 00653 */ 00654 int ast_context_add_switch(const char *context, const char *sw, const char *data, 00655 int eval, const char *registrar); 00656 00657 /*! 00658 * \brief Adds a switch (first param is a ast_context) 00659 * 00660 * \note See ast_context_add_switch() for argument information, with the exception of 00661 * the first argument. In this case, it's a pointer to an ast_context structure 00662 * as opposed to the name. 00663 */ 00664 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, 00665 int eval, const char *registrar); 00666 00667 /*! 00668 * \brief Remove a switch 00669 * 00670 * Removes a switch with the given parameters 00671 * 00672 * \retval 0 on success 00673 * \retval -1 on failure 00674 */ 00675 int ast_context_remove_switch(const char *context, const char *sw, 00676 const char *data, const char *registrar); 00677 00678 int ast_context_remove_switch2(struct ast_context *con, const char *sw, 00679 const char *data, const char *registrar); 00680 00681 /*! 00682 * \brief Simply remove extension from context 00683 * 00684 * \param context context to remove extension from 00685 * \param extension which extension to remove 00686 * \param priority priority of extension to remove (0 to remove all) 00687 * \param callerid NULL to remove all; non-NULL to match a single record per priority 00688 * \param matchcid non-zero to match callerid element (if non-NULL); 0 to match default case 00689 * \param registrar registrar of the extension 00690 * 00691 * This function removes an extension from a given context. 00692 * 00693 * \retval 0 on success 00694 * \retval -1 on failure 00695 * 00696 * @{ 00697 */ 00698 int ast_context_remove_extension(const char *context, const char *extension, int priority, 00699 const char *registrar); 00700 00701 int ast_context_remove_extension2(struct ast_context *con, const char *extension, 00702 int priority, const char *registrar, int already_locked); 00703 00704 int ast_context_remove_extension_callerid(const char *context, const char *extension, 00705 int priority, const char *callerid, int matchcid, const char *registrar); 00706 00707 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension, 00708 int priority, const char *callerid, int matchcid, const char *registrar, 00709 int already_locked); 00710 /*! @} */ 00711 00712 /*! 00713 * \brief Add an ignorepat 00714 * 00715 * \param context which context to add the ignorpattern to 00716 * \param ignorepat ignorepattern to set up for the extension 00717 * \param registrar registrar of the ignore pattern 00718 * 00719 * Adds an ignore pattern to a particular context. 00720 * 00721 * \retval 0 on success 00722 * \retval -1 on failure 00723 */ 00724 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar); 00725 00726 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar); 00727 00728 /* 00729 * \brief Remove an ignorepat 00730 * 00731 * \param context context from which to remove the pattern 00732 * \param ignorepat the pattern to remove 00733 * \param registrar the registrar of the ignore pattern 00734 * 00735 * This removes the given ignorepattern 00736 * 00737 * \retval 0 on success 00738 * \retval -1 on failure 00739 */ 00740 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar); 00741 00742 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar); 00743 00744 /*! 00745 * \brief Checks to see if a number should be ignored 00746 * 00747 * \param context context to search within 00748 * \param pattern to check whether it should be ignored or not 00749 * 00750 * Check if a number should be ignored with respect to dialtone cancellation. 00751 * 00752 * \retval 0 if the pattern should not be ignored 00753 * \retval non-zero if the pattern should be ignored 00754 */ 00755 int ast_ignore_pattern(const char *context, const char *pattern); 00756 00757 /* Locking functions for outer modules, especially for completion functions */ 00758 00759 /*! 00760 * \brief Write locks the context list 00761 * 00762 * \retval 0 on success 00763 * \retval -1 on error 00764 */ 00765 int ast_wrlock_contexts(void); 00766 00767 /*! 00768 * \brief Read locks the context list 00769 * 00770 * \retval 0 on success 00771 * \retval -1 on error 00772 */ 00773 int ast_rdlock_contexts(void); 00774 00775 /*! 00776 * \brief Unlocks contexts 00777 * 00778 * \retval 0 on success 00779 * \retval -1 on failure 00780 */ 00781 int ast_unlock_contexts(void); 00782 00783 /*! 00784 * \brief Write locks a given context 00785 * 00786 * \param con context to lock 00787 * 00788 * \retval 0 on success 00789 * \retval -1 on failure 00790 */ 00791 int ast_wrlock_context(struct ast_context *con); 00792 00793 /*! 00794 * \brief Read locks a given context 00795 * 00796 * \param con context to lock 00797 * 00798 * \retval 0 on success 00799 * \retval -1 on failure 00800 */ 00801 int ast_rdlock_context(struct ast_context *con); 00802 00803 /*! 00804 * \retval Unlocks the given context 00805 * 00806 * \param con context to unlock 00807 * 00808 * \retval 0 on success 00809 * \retval -1 on failure 00810 */ 00811 int ast_unlock_context(struct ast_context *con); 00812 00813 /*! 00814 * \brief locks the macrolock in the given given context 00815 * 00816 * \param macrocontext name of the macro-context to lock 00817 * 00818 * Locks the given macro-context to ensure only one thread (call) can execute it at a time 00819 * 00820 * \retval 0 on success 00821 * \retval -1 on failure 00822 */ 00823 int ast_context_lockmacro(const char *macrocontext); 00824 00825 /*! 00826 * \brief Unlocks the macrolock in the given context 00827 * 00828 * \param macrocontext name of the macro-context to unlock 00829 * 00830 * Unlocks the given macro-context so that another thread (call) can execute it 00831 * 00832 * \retval 0 on success 00833 * \retval -1 on failure 00834 */ 00835 int ast_context_unlockmacro(const char *macrocontext); 00836 00837 /*!\brief Set the channel to next execute the specified dialplan location. 00838 * \see ast_async_parseable_goto, ast_async_goto_if_exists 00839 */ 00840 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority); 00841 00842 /*!\brief Set the channel to next execute the specified dialplan location. 00843 */ 00844 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority); 00845 00846 /*! Synchronously or asynchronously make an outbound call and send it to a 00847 particular extension */ 00848 int ast_pbx_outgoing_exten(const char *type, int format, void *data, int timeout, const char *context, const char *exten, int priority, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel); 00849 00850 /*! Synchronously or asynchronously make an outbound call and send it to a 00851 particular application with given extension */ 00852 int ast_pbx_outgoing_app(const char *type, int format, void *data, int timeout, const char *app, const char *appdata, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel); 00853 00854 /*! 00855 * \brief Evaluate a condition 00856 * 00857 * \retval 0 if the condition is NULL or of zero length 00858 * \retval int If the string is an integer, the integer representation of 00859 * the integer is returned 00860 * \retval 1 Any other non-empty string 00861 */ 00862 int pbx_checkcondition(const char *condition); 00863 00864 /*! @name 00865 * Functions for returning values from structures */ 00866 /*! @{ */ 00867 const char *ast_get_context_name(struct ast_context *con); 00868 const char *ast_get_extension_name(struct ast_exten *exten); 00869 struct ast_context *ast_get_extension_context(struct ast_exten *exten); 00870 const char *ast_get_include_name(struct ast_include *include); 00871 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip); 00872 const char *ast_get_switch_name(struct ast_sw *sw); 00873 const char *ast_get_switch_data(struct ast_sw *sw); 00874 int ast_get_switch_eval(struct ast_sw *sw); 00875 00876 /*! @} */ 00877 00878 /*! @name Other Extension stuff */ 00879 /*! @{ */ 00880 int ast_get_extension_priority(struct ast_exten *exten); 00881 int ast_get_extension_matchcid(struct ast_exten *e); 00882 const char *ast_get_extension_cidmatch(struct ast_exten *e); 00883 const char *ast_get_extension_app(struct ast_exten *e); 00884 const char *ast_get_extension_label(struct ast_exten *e); 00885 void *ast_get_extension_app_data(struct ast_exten *e); 00886 /*! @} */ 00887 00888 /*! @name Registrar info functions ... */ 00889 /*! @{ */ 00890 const char *ast_get_context_registrar(struct ast_context *c); 00891 const char *ast_get_extension_registrar(struct ast_exten *e); 00892 const char *ast_get_include_registrar(struct ast_include *i); 00893 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip); 00894 const char *ast_get_switch_registrar(struct ast_sw *sw); 00895 /*! @} */ 00896 00897 /*! @name Walking functions ... */ 00898 /*! @{ */ 00899 struct ast_context *ast_walk_contexts(struct ast_context *con); 00900 struct ast_exten *ast_walk_context_extensions(struct ast_context *con, 00901 struct ast_exten *priority); 00902 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten, 00903 struct ast_exten *priority); 00904 struct ast_include *ast_walk_context_includes(struct ast_context *con, 00905 struct ast_include *inc); 00906 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con, 00907 struct ast_ignorepat *ip); 00908 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw); 00909 /*! @} */ 00910 00911 /*!\brief Create a human-readable string, specifying all variables and their corresponding values. 00912 * \param chan Channel from which to read variables 00913 * \param buf Dynamic string in which to place the result (should be allocated with \see ast_str_create). 00914 * \note Will lock the channel. 00915 */ 00916 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf); 00917 00918 /*!\brief Return a pointer to the value of the corresponding channel variable. 00919 * \note Will lock the channel. 00920 * 00921 * \note This function will return a pointer to the buffer inside the channel 00922 * variable. This value should only be accessed with the channel locked. If 00923 * the value needs to be kept around, it should be done by using the following 00924 * thread-safe code: 00925 * \code 00926 * const char *var; 00927 * 00928 * ast_channel_lock(chan); 00929 * if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) { 00930 * var = ast_strdupa(var); 00931 * } 00932 * ast_channel_unlock(chan); 00933 * \endcode 00934 */ 00935 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name); 00936 00937 /*!\brief Add a variable to the channel variable stack, without removing any previously set value. 00938 * \note Will lock the channel. 00939 */ 00940 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value); 00941 00942 /*!\brief Add a variable to the channel variable stack, removing the most recently set value for the same name. 00943 * \note Will lock the channel. May also be used to set a channel dialplan function to a particular value. 00944 * \see ast_func_write 00945 */ 00946 void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value); 00947 00948 /*!\brief Retrieve the value of a builtin variable or variable from the channel variable stack. 00949 * \note Will lock the channel. 00950 */ 00951 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp); 00952 void pbx_builtin_clear_globals(void); 00953 00954 /*!\brief Parse and set a single channel variable, where the name and value are separated with an '=' character. 00955 * \note Will lock the channel. 00956 */ 00957 int pbx_builtin_setvar(struct ast_channel *chan, void *data); 00958 00959 /*!\brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character. 00960 * \note Will lock the channel. 00961 */ 00962 int pbx_builtin_setvar_multiple(struct ast_channel *chan, void *data); 00963 00964 int pbx_builtin_raise_exception(struct ast_channel *chan, void *data); 00965 00966 /*! @name Substitution routines, using static string buffers 00967 * @{ */ 00968 void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count); 00969 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count); 00970 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used); 00971 void ast_str_substitute_variables(struct ast_str **buf, size_t maxlen, struct ast_channel *chan, const char *templ); 00972 /*! @} */ 00973 00974 int ast_extension_patmatch(const char *pattern, const char *data); 00975 00976 /*! Set "autofallthrough" flag, if newval is <0, does not actually set. If 00977 set to 1, sets to auto fall through. If newval set to 0, sets to no auto 00978 fall through (reads extension instead). Returns previous value. */ 00979 int pbx_set_autofallthrough(int newval); 00980 00981 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not actually set. If 00982 set to 1, sets to use the new Trie-based pattern matcher. If newval set to 0, sets to use 00983 the old linear-search algorithm. Returns previous value. */ 00984 int pbx_set_extenpatternmatchnew(int newval); 00985 00986 /*! Set "overrideswitch" field. If set and of nonzero length, all contexts 00987 * will be tried directly through the named switch prior to any other 00988 * matching within that context. 00989 * \since 1.6.1 00990 */ 00991 void pbx_set_overrideswitch(const char *newval); 00992 00993 /*! 00994 * \note This function will handle locking the channel as needed. 00995 */ 00996 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority); 00997 00998 /*! 00999 * \note This function will handle locking the channel as needed. 01000 */ 01001 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string); 01002 01003 /*! 01004 * \note This function will handle locking the channel as needed. 01005 */ 01006 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string); 01007 01008 /*! 01009 * \note This function will handle locking the channel as needed. 01010 */ 01011 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority); 01012 01013 /*! 01014 * \note This function will handle locking the channel as needed. 01015 */ 01016 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority); 01017 01018 struct ast_custom_function* ast_custom_function_find(const char *name); 01019 01020 /*! 01021 * \brief Unregister a custom function 01022 */ 01023 int ast_custom_function_unregister(struct ast_custom_function *acf); 01024 01025 /*! 01026 * \brief Register a custom function 01027 */ 01028 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, ast_module_info->self) 01029 01030 /*! 01031 * \brief Register a custom function 01032 */ 01033 int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod); 01034 01035 /*! 01036 * \brief Retrieve the number of active calls 01037 */ 01038 int ast_active_calls(void); 01039 01040 /*! 01041 * \brief Retrieve the total number of calls processed through the PBX since last restart 01042 */ 01043 int ast_processed_calls(void); 01044 01045 /*! 01046 * \brief executes a read operation on a function 01047 * 01048 * \param chan Channel to execute on 01049 * \param function Data containing the function call string (will be modified) 01050 * \param workspace A pointer to safe memory to use for a return value 01051 * \param len the number of bytes in workspace 01052 * 01053 * This application executes a function in read mode on a given channel. 01054 * 01055 * \retval 0 success 01056 * \retval non-zero failure 01057 */ 01058 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len); 01059 01060 /*! 01061 * \brief executes a write operation on a function 01062 * 01063 * \param chan Channel to execute on 01064 * \param function Data containing the function call string (will be modified) 01065 * \param value A value parameter to pass for writing 01066 * 01067 * This application executes a function in write mode on a given channel. 01068 * 01069 * \retval 0 success 01070 * \retval non-zero failure 01071 */ 01072 int ast_func_write(struct ast_channel *chan, const char *function, const char *value); 01073 01074 /*! 01075 * When looking up extensions, we can have different requests 01076 * identified by the 'action' argument, as follows. 01077 * Note that the coding is such that the low 4 bits are the 01078 * third argument to extension_match_core. 01079 */ 01080 01081 enum ext_match_t { 01082 E_MATCHMORE = 0x00, /* extension can match but only with more 'digits' */ 01083 E_CANMATCH = 0x01, /* extension can match with or without more 'digits' */ 01084 E_MATCH = 0x02, /* extension is an exact match */ 01085 E_MATCH_MASK = 0x03, /* mask for the argument to extension_match_core() */ 01086 E_SPAWN = 0x12, /* want to spawn an extension. Requires exact match */ 01087 E_FINDLABEL = 0x22 /* returns the priority for a given label. Requires exact match */ 01088 }; 01089 01090 #define STATUS_NO_CONTEXT 1 01091 #define STATUS_NO_EXTENSION 2 01092 #define STATUS_NO_PRIORITY 3 01093 #define STATUS_NO_LABEL 4 01094 #define STATUS_SUCCESS 5 01095 #define AST_PBX_MAX_STACK 128 01096 01097 /* request and result for pbx_find_extension */ 01098 struct pbx_find_info { 01099 #if 0 01100 const char *context; 01101 const char *exten; 01102 int priority; 01103 #endif 01104 01105 char *incstack[AST_PBX_MAX_STACK]; /* filled during the search */ 01106 int stacklen; /* modified during the search */ 01107 int status; /* set on return */ 01108 struct ast_switch *swo; /* set on return */ 01109 const char *data; /* set on return */ 01110 const char *foundcontext; /* set on return */ 01111 }; 01112 01113 struct ast_exten *pbx_find_extension(struct ast_channel *chan, 01114 struct ast_context *bypass, struct pbx_find_info *q, 01115 const char *context, const char *exten, int priority, 01116 const char *label, const char *callerid, enum ext_match_t action); 01117 01118 /*!\brief hashtable functions for contexts */ 01119 /*! @{ */ 01120 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b); 01121 unsigned int ast_hashtab_hash_contexts(const void *obj); 01122 /*! @} */ 01123 01124 #if defined(__cplusplus) || defined(c_plusplus) 01125 } 01126 #endif 01127 01128 #endif /* _ASTERISK_PBX_H */