Main Page | Alphabetical List | Data Structures | Directories | 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 //! 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

Generated on Thu Nov 29 22:50:24 2007 for Asterisk by  doxygen 1.4.2