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