Main Page | Alphabetical List | Data Structures | File List | Data Fields | Globals

pbx.h

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

Generated on Fri Feb 27 12:19:43 2004 for Asterisk by doxygen 1.3.5