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 //! Add a switch
00380 /*!
00381  * \param context context to which to add the switch
00382  * \param sw switch to add
00383  * \param data data to pass to switch
00384  * \param registrar whoever registered the switch
00385  * This function registers a switch with the asterisk switch architecture
00386  * It returns 0 on success, -1 on failure
00387  */
00388 int ast_context_add_switch(char *context, char *sw, char *data, char *registrar);
00389 //! Adds a switch (first param is a ast_context)
00390 /*!
00391  * See ast_context_add_switch()
00392  */
00393 int ast_context_add_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
00394 
00395 //! Remove a switch
00396 /*!
00397  * Removes a switch with the given parameters
00398  * Returns 0 on success, -1 on failure
00399  */
00400 int ast_context_remove_switch(char *context, char *sw, char *data, char *registrar);
00401 int ast_context_remove_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
00402 
00403 //! Simply remove extension from context
00404 /*!
00405  * \param context context to remove extension from
00406  * \param extension which extension to remove
00407  * \param priority priority of extension to remove
00408  * \param registrar registrar of the extension
00409  * This function removes an extension from a given context.
00410  * Returns 0 on success, -1 on failure
00411  */
00412 int ast_context_remove_extension(char *context, char *extension, int priority,
00413    char *registrar);
00414 int ast_context_remove_extension2(struct ast_context *con, char *extension,
00415    int priority, char *registrar);
00416 
00417 //! Add an ignorepat
00418 /*!
00419  * \param context which context to add the ignorpattern to
00420  * \param ignorpat ignorepattern to set up for the extension
00421  * \param registrar registrar of the ignore pattern
00422  * Adds an ignore pattern to a particular context.
00423  * Returns 0 on success, -1 on failure
00424  */
00425 int ast_context_add_ignorepat(char *context, char *ignorepat, char *registrar);
00426 int ast_context_add_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
00427 
00428 /* Remove an ignorepat */
00429 /*!
00430  * \param context context from which to remove the pattern
00431  * \param ignorepat the pattern to remove
00432  * \param registrar the registrar of the ignore pattern
00433  * This removes the given ignorepattern
00434  * Returns 0 on success, -1 on failure
00435  */
00436 int ast_context_remove_ignorepat(char *context, char *ignorepat, char *registrar);
00437 int ast_context_remove_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
00438 
00439 //! Checks to see if a number should be ignored
00440 /*!
00441  * \param context context to search within
00442  * \param extension to check whether it should be ignored or not
00443  * Check if a number should be ignored with respect to dialtone cancellation.  
00444  * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 
00445  */
00446 int ast_ignore_pattern(char *context, char *pattern);
00447 
00448 /* Locking functions for outer modules, especially for completion functions */
00449 //! Locks the contexts
00450 /*! Locks the context list
00451  * Returns 0 on success, -1 on error
00452  */
00453 int ast_lock_contexts(void);
00454 
00455 //! Unlocks contexts
00456 /*!
00457  * Returns 0 on success, -1 on failure
00458  */
00459 int ast_unlock_contexts(void);
00460 
00461 //! Locks a given context
00462 /*!
00463  * \param con context to lock
00464  * Locks the context.
00465  * Returns 0 on success, -1 on failure
00466  */
00467 int ast_lock_context(struct ast_context *con);
00468 //! Unlocks the given context
00469 /*!
00470  * \param con context to unlock
00471  * Unlocks the given context
00472  * Returns 0 on success, -1 on failure
00473  */
00474 int ast_unlock_context(struct ast_context *con);
00475 
00476 
00477 int ast_async_goto(struct ast_channel *chan, char *context, char *exten, int priority, int needlock);
00478 
00479 int ast_async_goto_by_name(char *chan, char *context, char *exten, int priority);
00480 
00481 /* Synchronously or asynchronously make an outbound call and send it to a
00482    particular extension */
00483 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 );
00484 
00485 /* Synchronously or asynchronously make an outbound call and send it to a
00486    particular application with given extension */
00487 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);
00488 
00489 /* Functions for returning values from structures */
00490 char *ast_get_context_name(struct ast_context *con);
00491 char *ast_get_extension_name(struct ast_exten *exten);
00492 char *ast_get_include_name(struct ast_include *include);
00493 char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
00494 char *ast_get_switch_name(struct ast_sw *sw);
00495 char *ast_get_switch_data(struct ast_sw *sw);
00496 
00497 /* Other extension stuff */
00498 int ast_get_extension_priority(struct ast_exten *exten);
00499 char *ast_get_extension_app(struct ast_exten *e);
00500 void *ast_get_extension_app_data(struct ast_exten *e);
00501 
00502 /* Registrar info functions ... */
00503 char *ast_get_context_registrar(struct ast_context *c);
00504 char *ast_get_extension_registrar(struct ast_exten *e);
00505 char *ast_get_include_registrar(struct ast_include *i);
00506 char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
00507 char *ast_get_switch_registrar(struct ast_sw *sw);
00508 
00509 /* Walking functions ... */
00510 struct ast_context *ast_walk_contexts(struct ast_context *con);
00511 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
00512    struct ast_exten *priority);
00513 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
00514    struct ast_exten *priority);
00515 struct ast_include *ast_walk_context_includes(struct ast_context *con,
00516    struct ast_include *inc);
00517 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
00518    struct ast_ignorepat *ip);
00519 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
00520 
00521 extern char *pbx_builtin_getvar_helper(struct ast_channel *chan, char *name);
00522 extern void pbx_builtin_setvar_helper(struct ast_channel *chan, char *name, char *value);
00523 extern void pbx_builtin_clear_globals(void);
00524 extern void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
00525 
00526 #if defined(__cplusplus) || defined(c_plusplus)
00527 }
00528 #endif
00529 
00530 
00531 #endif

Generated on Fri Oct 31 07:05:08 2003 for Asterisk by doxygen 1.3.4