Wed Feb 11 11:59:57 2009

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

Generated on Wed Feb 11 11:59:57 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7