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

Generated on Fri Sep 25 19:28:13 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.5