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