Sat Aug 6 00:39:30 2011

Asterisk developer's documentation


pbx.h

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

Generated on Sat Aug 6 00:39:30 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7