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