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