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