00001 /* 00002 * Asterisk -- A telephony toolkit for Linux. 00003 * 00004 * Core PBX routines and definitions. 00005 * 00006 * Copyright (C) 1999, Mark Spencer 00007 * 00008 * Mark Spencer <markster@linux-support.net> 00009 * 00010 * This program is free software, distributed under the terms of 00011 * the GNU General Public License 00012 */ 00013 #ifndef _ASTERISK_PBX_H 00014 #define _ASTERISK_PBX_H 00015 00016 #include <asterisk/sched.h> 00017 #include <asterisk/channel.h> 00018 00019 #if defined(__cplusplus) || defined(c_plusplus) 00020 extern "C" { 00021 #endif 00022 00023 #define AST_PBX_KEEP 0 00024 #define AST_PBX_REPLACE 1 00025 00026 //! Max length of an application 00027 #define AST_MAX_APP 32 00028 00029 //! Special return values from applications to the PBX 00030 #define AST_PBX_KEEPALIVE 10 /* Destroy the thread, but don't hang up the channel */ 00031 #define AST_PBX_NO_HANGUP_PEER 11 00032 00033 //! Special Priority for an hint 00034 #define PRIORITY_HINT -1 00035 00036 //! Extension states 00037 //! No device INUSE or BUSY 00038 #define AST_EXTENSION_NOT_INUSE 0 00039 //! One or more devices INUSE 00040 #define AST_EXTENSION_INUSE 1 00041 //! All devices BUSY 00042 #define AST_EXTENSION_BUSY 2 00043 //! All devices UNAVAILABLE/UNREGISTERED 00044 #define AST_EXTENSION_UNAVAILABLE 3 00045 //! One ore more devices RINGING 00046 #define AST_EXTENSION_RINGING 4 00047 00048 struct ast_context; 00049 struct ast_exten; 00050 struct ast_include; 00051 struct ast_ignorepat; 00052 struct ast_sw; 00053 00054 typedef int (*ast_state_cb_type)(char *context, char* id, int state, void *data); 00055 00056 //! Data structure associated with an asterisk switch 00057 struct ast_switch { 00058 /*! NULL */ 00059 struct ast_switch *next; 00060 /*! Name of the switch */ 00061 char *name; 00062 /*! Description of the switch */ 00063 char *description; 00064 00065 int (*exists)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data); 00066 00067 int (*canmatch)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data); 00068 00069 int (*exec)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, int newstack, char *data); 00070 00071 int (*matchmore)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data); 00072 }; 00073 00074 struct ast_pbx { 00075 int dtimeout; /* Timeout between digits (seconds) */ 00076 int rtimeout; /* Timeout for response 00077 (seconds) */ 00078 }; 00079 00080 00081 //! Register an alternative switch 00082 /*! 00083 * \param sw switch to register 00084 * This function registers a populated ast_switch structure with the 00085 * asterisk switching architecture. 00086 * It returns 0 on success, and other than 0 on failure 00087 */ 00088 extern int ast_register_switch(struct ast_switch *sw); 00089 00090 //! Unregister an alternative switch 00091 /*! 00092 * \param sw switch to unregister 00093 * Unregisters a switch from asterisk. 00094 * Returns nothing 00095 */ 00096 extern void ast_unregister_switch(struct ast_switch *sw); 00097 00098 //! Look up an application 00099 /*! 00100 * \param app name of the app 00101 * This function searches for the ast_app structure within 00102 * the apps that are registered for the one with the name 00103 * you passed in. 00104 * Returns the ast_app structure that matches on success, or NULL on failure 00105 */ 00106 extern struct ast_app *pbx_findapp(char *app); 00107 00108 void *ast_pbx_run_app(void *data); 00109 00110 //! executes an application 00111 /*! 00112 * \param c channel to execute on 00113 * \param app which app to execute 00114 * \param data the data passed into the app 00115 * \param newstack stack pointer 00116 * This application executes an application on a given channel. It 00117 * saves the stack and executes the given appliation passing in 00118 * the given data. 00119 * It returns 0 on success, and -1 on failure 00120 */ 00121 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data, int newstack); 00122 00123 //! Register a new context 00124 /*! 00125 * \param extcontexts pointer to the ast_context structure pointer 00126 * \param name name of the new context 00127 * \param registrar registrar of the context 00128 * This will first search for a context with your name. If it exists already, it will not 00129 * create a new one. If it does not exist, it will create a new one with the given name 00130 * and registrar. 00131 * It returns NULL on failure, and an ast_context structure on success 00132 */ 00133 struct ast_context *ast_context_create(struct ast_context **extcontexts, char *name, char *registrar); 00134 00135 //! Merge the temporary contexts into a global contexts list and delete from the global list the ones that are being added 00136 /*! 00137 * \param extcontexts pointer to the ast_context structure pointer 00138 * \param registar of the context; if it's set the routine will delete all contexts that belong to that registrar; if NULL only the contexts that are specified in extcontexts 00139 */ 00140 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, char *registrar); 00141 00142 //! Destroy a context (matches the specified context (or ANY context if NULL) 00143 /*! 00144 * \param con context to destroy 00145 * \param registrar who registered it 00146 * You can optionally leave out either parameter. It will find it 00147 * based on either the ast_context or the registrar name. 00148 * Returns nothing 00149 */ 00150 void ast_context_destroy(struct ast_context *con, char *registrar); 00151 00152 //! Find a context 00153 /*! 00154 * \param name name of the context to find 00155 * Will search for the context with the given name. 00156 * Returns the ast_context on success, NULL on failure. 00157 */ 00158 struct ast_context *ast_context_find(char *name); 00159 00160 //! Create a new thread and start the PBX (or whatever) 00161 /*! 00162 * \param c channel to start the pbx on 00163 * Starts a pbx thread on a given channel 00164 * It returns -1 on failure, and 0 on success 00165 */ 00166 int ast_pbx_start(struct ast_channel *c); 00167 00168 //! Execute the PBX in the current thread 00169 /*! 00170 * \param c channel to run the pbx on 00171 * This executes the PBX on a given channel. It allocates a new 00172 * PBX structure for the channel, and provides all PBX functionality. 00173 */ 00174 int ast_pbx_run(struct ast_channel *c); 00175 00176 /*! 00177 * \param context context to add the extension to 00178 * \param replace 00179 * \param extension extension to add 00180 * \param priority priority level of extension addition 00181 * \param callerid callerid of extension 00182 * \param application application to run on the extension with that priority level 00183 * \param data data to pass to the application 00184 * \param datad 00185 * \param registrar who registered the extension 00186 * Add and extension to an extension context. 00187 * Callerid is a pattern to match CallerID, or NULL to match any callerid 00188 * Returns 0 on success, -1 on failure 00189 */ 00190 int ast_add_extension(char *context, int replace, char *extension, int priority, char *callerid, 00191 char *application, void *data, void (*datad)(void *), char *registrar); 00192 00193 //! Add an extension to an extension context, this time with an ast_context *. CallerID is a pattern to match on callerid, or NULL to not care about callerid 00194 /*! 00195 * For details about the arguements, check ast_add_extension() 00196 */ 00197 int ast_add_extension2(struct ast_context *con, 00198 int replace, char *extension, int priority, char *callerid, 00199 char *application, void *data, void (*datad)(void *), 00200 char *registrar); 00201 00202 //! Add an application. The function 'execute' should return non-zero if the line needs to be hung up. 00203 /*! 00204 \param app Short name of the application 00205 \param execute a function callback to execute the application 00206 \param synopsis a short description of the application 00207 \param description long description of the application 00208 Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline 00209 description with more detail, including under what conditions the application 00210 will return 0 or -1. 00211 This registers an application with asterisks internal application list. Please note: 00212 The individual applications themselves are responsible for registering and unregistering 00213 CLI commands. 00214 It returns 0 on success, -1 on failure. 00215 */ 00216 int ast_register_application(char *app, int (*execute)(struct ast_channel *, void *), 00217 char *synopsis, char *description); 00218 00219 //! Remove an application 00220 /*! 00221 * \param app name of the application (does not have to be the same string as the one that was registered) 00222 * This unregisters an application from asterisk's internal registration mechanisms. 00223 * It returns 0 on success, and -1 on failure. 00224 */ 00225 int ast_unregister_application(char *app); 00226 00227 //! Uses hint and devicestate callback to get the state of an extension 00228 /*! 00229 * \param c this is not important 00230 * \param context which context to look in 00231 * \param exten which extension to get state 00232 * Returns extension state !! = AST_EXTENSION_??? 00233 */ 00234 int ast_extension_state(struct ast_channel *c, char *context, char *exten); 00235 00236 //! Tells Asterisk the State for Device is changed 00237 /*! 00238 * \param fmt devicename like a dialstring with format parameters 00239 * Asterisk polls the new extensionstates and calls the registered 00240 * callbacks for the changed extensions 00241 * Returns 0 on success, -1 on failure 00242 */ 00243 int ast_device_state_changed(const char *fmt, ...) 00244 __attribute__ ((format (printf, 1, 2))); 00245 00246 //! Registers a state change callback 00247 /*! 00248 * \param context which context to look in 00249 * \param exten which extension to get state 00250 * \param callback callback to call if state changed 00251 * \param data to pass to callback 00252 * The callback is called if the state for extension is changed 00253 * Return -1 on failure, ID on success 00254 */ 00255 int ast_extension_state_add(char *context, char *exten, 00256 ast_state_cb_type callback, void *data); 00257 00258 //! Deletes a registered state change callback by ID 00259 /*! 00260 * \param id of the callback to delete 00261 * Removes the callback from list of callbacks 00262 * Return 0 on success, -1 on failure 00263 */ 00264 int ast_extension_state_del(int id, ast_state_cb_type callback); 00265 00266 //! If an extension exists, return non-zero 00267 /*! 00268 * \param hint buffer for hint 00269 * \param maxlen size of hint buffer 00270 * \param c this is not important 00271 * \param context which context to look in 00272 * \param exten which extension to search for 00273 * If an extension within the given context with the priority PRIORITY_HINT 00274 * is found a non zero value will be returned. 00275 * Otherwise, 0 is returned. 00276 */ 00277 int ast_get_hint(char *hint, int maxlen, struct ast_channel *c, char *context, char *exten); 00278 00279 //! If an extension exists, return non-zero 00280 // work 00281 /*! 00282 * \param c this is not important 00283 * \param context which context to look in 00284 * \param exten which extension to search for 00285 * \param priority priority of the action within the extension 00286 * \param callerid callerid to search for 00287 * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned. 00288 * Otherwise, 0 is returned. 00289 */ 00290 int ast_exists_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid); 00291 00292 //! Looks for a valid matching extension 00293 /*! 00294 \param c not really important 00295 \param context context to serach within 00296 \param exten extension to check 00297 \param priority priority of extension path 00298 \param callerid callerid of extension being searched for 00299 If "exten" *could be* a valid extension in this context with or without 00300 some more digits, return non-zero. Basically, when this returns 0, no matter 00301 what you add to exten, it's not going to be a valid extension anymore 00302 */ 00303 int ast_canmatch_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid); 00304 00305 //! Looks to see if adding anything to this extension might match something. (exists ^ canmatch) 00306 /*! 00307 \param c not really important 00308 \param context context to serach within 00309 \param exten extension to check 00310 \param priority priority of extension path 00311 \param callerid callerid of extension being searched for 00312 If "exten" *could match* a valid extension in this context with 00313 some more digits, return non-zero. Does NOT return non-zero if this is 00314 an exact-match only. Basically, when this returns 0, no matter 00315 what you add to exten, it's not going to be a valid extension anymore 00316 */ 00317 int ast_matchmore_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid); 00318 00319 //! Determine if a given extension matches a given pattern (in NXX format) 00320 /*! 00321 * \param pattern pattern to match 00322 * \param extension extension to check against the pattern. 00323 * Checks whether or not the given extension matches the given pattern. 00324 * Returns 1 on match, 0 on failure 00325 */ 00326 int ast_extension_match(char *pattern, char *extension); 00327 00328 //! Launch a new extension (i.e. new stack) 00329 /*! 00330 * \param c not important 00331 * \param context which context to generate the extension within 00332 * \param exten new extension to add 00333 * \param priority priority of new extension 00334 * \param callerid callerid of extension 00335 * This adds a new extension to the asterisk extension list. 00336 * It returns 0 on success, -1 on failure. 00337 */ 00338 int ast_spawn_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid); 00339 00340 //! Execute an extension. 00341 /*! 00342 \param c channel to execute upon 00343 \param context which context extension is in 00344 \param exten extension to execute 00345 \param priority priority to execute within the given extension 00346 If it's not available, do whatever you should do for 00347 default extensions and halt the thread if necessary. This function does not 00348 return, except on error. 00349 */ 00350 int ast_exec_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid); 00351 00352 //! Add an include 00353 /*! 00354 \param context context to add include to 00355 \param include new include to add 00356 \param registrar who's registering it 00357 Adds an include taking a char * string as the context parameter 00358 Returns 0 on success, -1 on error 00359 */ 00360 int ast_context_add_include(char *context, char *include, char *registrar); 00361 00362 //! Add an include 00363 /*! 00364 \param con context to add the include to 00365 \param include include to add 00366 \param registrar who registered the context 00367 Adds an include taking a struct ast_context as the first parameter 00368 Returns 0 on success, -1 on failure 00369 */ 00370 int ast_context_add_include2(struct ast_context *con, char *include, char *registrar); 00371 00372 //! Removes an include 00373 /*! 00374 * See add_include 00375 */ 00376 int ast_context_remove_include(char *context, char *include, char *registrar); 00377 //! Removes an include by an ast_context structure 00378 /*! 00379 * See add_include2 00380 */ 00381 int ast_context_remove_include2(struct ast_context *con, char *include, char *registrar); 00382 00383 //! Verifies includes in an ast_contect structure 00384 /*! 00385 * \param con context in which to verify the includes 00386 * Returns 0 if no problems found, -1 if there were any missing context 00387 */ 00388 int ast_context_verify_includes(struct ast_context *con); 00389 00390 //! Add a switch 00391 /*! 00392 * \param context context to which to add the switch 00393 * \param sw switch to add 00394 * \param data data to pass to switch 00395 * \param registrar whoever registered the switch 00396 * This function registers a switch with the asterisk switch architecture 00397 * It returns 0 on success, -1 on failure 00398 */ 00399 int ast_context_add_switch(char *context, char *sw, char *data, char *registrar); 00400 //! Adds a switch (first param is a ast_context) 00401 /*! 00402 * See ast_context_add_switch() 00403 */ 00404 int ast_context_add_switch2(struct ast_context *con, char *sw, char *data, char *registrar); 00405 00406 //! Remove a switch 00407 /*! 00408 * Removes a switch with the given parameters 00409 * Returns 0 on success, -1 on failure 00410 */ 00411 int ast_context_remove_switch(char *context, char *sw, char *data, char *registrar); 00412 int ast_context_remove_switch2(struct ast_context *con, char *sw, char *data, char *registrar); 00413 00414 //! Simply remove extension from context 00415 /*! 00416 * \param context context to remove extension from 00417 * \param extension which extension to remove 00418 * \param priority priority of extension to remove 00419 * \param registrar registrar of the extension 00420 * This function removes an extension from a given context. 00421 * Returns 0 on success, -1 on failure 00422 */ 00423 int ast_context_remove_extension(char *context, char *extension, int priority, 00424 char *registrar); 00425 int ast_context_remove_extension2(struct ast_context *con, char *extension, 00426 int priority, char *registrar); 00427 00428 //! Add an ignorepat 00429 /*! 00430 * \param context which context to add the ignorpattern to 00431 * \param ignorpat ignorepattern to set up for the extension 00432 * \param registrar registrar of the ignore pattern 00433 * Adds an ignore pattern to a particular context. 00434 * Returns 0 on success, -1 on failure 00435 */ 00436 int ast_context_add_ignorepat(char *context, char *ignorepat, char *registrar); 00437 int ast_context_add_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar); 00438 00439 /* Remove an ignorepat */ 00440 /*! 00441 * \param context context from which to remove the pattern 00442 * \param ignorepat the pattern to remove 00443 * \param registrar the registrar of the ignore pattern 00444 * This removes the given ignorepattern 00445 * Returns 0 on success, -1 on failure 00446 */ 00447 int ast_context_remove_ignorepat(char *context, char *ignorepat, char *registrar); 00448 int ast_context_remove_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar); 00449 00450 //! Checks to see if a number should be ignored 00451 /*! 00452 * \param context context to search within 00453 * \param extension to check whether it should be ignored or not 00454 * Check if a number should be ignored with respect to dialtone cancellation. 00455 * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 00456 */ 00457 int ast_ignore_pattern(char *context, char *pattern); 00458 00459 /* Locking functions for outer modules, especially for completion functions */ 00460 //! Locks the contexts 00461 /*! Locks the context list 00462 * Returns 0 on success, -1 on error 00463 */ 00464 int ast_lock_contexts(void); 00465 00466 //! Unlocks contexts 00467 /*! 00468 * Returns 0 on success, -1 on failure 00469 */ 00470 int ast_unlock_contexts(void); 00471 00472 //! Locks a given context 00473 /*! 00474 * \param con context to lock 00475 * Locks the context. 00476 * Returns 0 on success, -1 on failure 00477 */ 00478 int ast_lock_context(struct ast_context *con); 00479 //! Unlocks the given context 00480 /*! 00481 * \param con context to unlock 00482 * Unlocks the given context 00483 * Returns 0 on success, -1 on failure 00484 */ 00485 int ast_unlock_context(struct ast_context *con); 00486 00487 00488 int ast_async_goto(struct ast_channel *chan, char *context, char *exten, int priority); 00489 00490 int ast_async_goto_by_name(char *chan, char *context, char *exten, int priority); 00491 00492 /* Synchronously or asynchronously make an outbound call and send it to a 00493 particular extension */ 00494 int ast_pbx_outgoing_exten(char *type, int format, void *data, int timeout, char *context, char *exten, int priority, int *reason, int sync, int callingpres, char *callerid, char *variable, char *account, char *uniqueid); 00495 00496 /* Synchronously or asynchronously make an outbound call and send it to a 00497 particular application with given extension */ 00498 int ast_pbx_outgoing_app(char *type, int format, void *data, int timeout, char *app, char *appdata, int *reason, int sync, char *callerid, char *variable, char *account, char *uniqueid); 00499 00500 /* Functions for returning values from structures */ 00501 char *ast_get_context_name(struct ast_context *con); 00502 char *ast_get_extension_name(struct ast_exten *exten); 00503 char *ast_get_include_name(struct ast_include *include); 00504 char *ast_get_ignorepat_name(struct ast_ignorepat *ip); 00505 char *ast_get_switch_name(struct ast_sw *sw); 00506 char *ast_get_switch_data(struct ast_sw *sw); 00507 00508 /* Other extension stuff */ 00509 int ast_get_extension_priority(struct ast_exten *exten); 00510 int ast_get_extension_matchcid(struct ast_exten *e); 00511 char *ast_get_extension_cidmatch(struct ast_exten *e); 00512 char *ast_get_extension_app(struct ast_exten *e); 00513 void *ast_get_extension_app_data(struct ast_exten *e); 00514 00515 /* Registrar info functions ... */ 00516 char *ast_get_context_registrar(struct ast_context *c); 00517 char *ast_get_extension_registrar(struct ast_exten *e); 00518 char *ast_get_include_registrar(struct ast_include *i); 00519 char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip); 00520 char *ast_get_switch_registrar(struct ast_sw *sw); 00521 00522 /* Walking functions ... */ 00523 struct ast_context *ast_walk_contexts(struct ast_context *con); 00524 struct ast_exten *ast_walk_context_extensions(struct ast_context *con, 00525 struct ast_exten *priority); 00526 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten, 00527 struct ast_exten *priority); 00528 struct ast_include *ast_walk_context_includes(struct ast_context *con, 00529 struct ast_include *inc); 00530 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con, 00531 struct ast_ignorepat *ip); 00532 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw); 00533 00534 extern char *pbx_builtin_getvar_helper(struct ast_channel *chan, char *name); 00535 extern void pbx_builtin_setvar_helper(struct ast_channel *chan, char *name, char *value); 00536 extern void pbx_builtin_clear_globals(void); 00537 extern int pbx_builtin_setvar(struct ast_channel *chan, void *data); 00538 extern void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count); 00539 00540 int ast_extension_patmatch(const char *pattern, const char *data); 00541 00542 #if defined(__cplusplus) || defined(c_plusplus) 00543 } 00544 #endif 00545 00546 00547 #endif