Wed Aug 18 22:33:54 2010

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/devicestate.h"
00028 #include "asterisk/chanvars.h"
00029 #include "asterisk/hashtab.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_HANGUP                -1    /*!< Jump to the 'h' exten */
00042 #define AST_PBX_OK                     0    /*!< No errors */
00043 #define AST_PBX_ERROR                  1    /*!< Jump to the 'e' exten */
00044 #define AST_PBX_INCOMPLETE             12   /*!< Return to PBX matching, allowing more digits for the extension */
00045 /*! } */
00046 
00047 #define PRIORITY_HINT   -1 /*!< Special Priority for a hint */
00048 
00049 /*! \brief Extension states 
00050    \note States can be combined 
00051    - \ref AstExtState
00052 */
00053 enum ast_extension_states {
00054    AST_EXTENSION_REMOVED = -2,   /*!< Extension removed */
00055    AST_EXTENSION_DEACTIVATED = -1,  /*!< Extension hint removed */
00056    AST_EXTENSION_NOT_INUSE = 0,  /*!< No device INUSE or BUSY  */
00057    AST_EXTENSION_INUSE = 1 << 0, /*!< One or more devices INUSE */
00058    AST_EXTENSION_BUSY = 1 << 1,  /*!< All devices BUSY */
00059    AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
00060    AST_EXTENSION_RINGING = 1 << 3,  /*!< All devices RINGING */
00061    AST_EXTENSION_ONHOLD = 1 << 4,   /*!< All devices ONHOLD */
00062 };
00063 
00064 
00065 struct ast_context;
00066 struct ast_exten;     
00067 struct ast_include;
00068 struct ast_ignorepat;
00069 struct ast_sw;
00070 
00071 /*! \brief Typedef for devicestate and hint callbacks */
00072 typedef int (*ast_state_cb_type)(char *context, char* id, enum ast_extension_states state, void *data);
00073 
00074 /*! \brief Data structure associated with a custom dialplan function */
00075 struct ast_custom_function {
00076    const char *name;    /*!< Name */
00077    const char *synopsis;      /*!< Short description for "show functions" */
00078    const char *desc;    /*!< Help text that explains it all */
00079    const char *syntax;     /*!< Syntax description */
00080    int (*read)(struct ast_channel *, const char *, char *, char *, size_t);   /*!< Read function, if read is supported */
00081    int (*write)(struct ast_channel *, const char *, char *, const char *);    /*!< Write function, if write is supported */
00082    struct ast_module *mod;         /*!< Module this custom function belongs to */
00083    AST_RWLIST_ENTRY(ast_custom_function) acflist;
00084 };
00085 
00086 /*! \brief All switch functions have the same interface, so define a type for them */
00087 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
00088    const char *exten, int priority, const char *callerid, const char *data);
00089 
00090 /*!< Data structure associated with an Asterisk switch */
00091 struct ast_switch {
00092    AST_LIST_ENTRY(ast_switch) list;
00093    const char *name;       /*!< Name of the switch */
00094    const char *description;      /*!< Description of the switch */
00095    
00096    ast_switch_f *exists;
00097    ast_switch_f *canmatch;
00098    ast_switch_f *exec;
00099    ast_switch_f *matchmore;
00100 };
00101 
00102 struct ast_timing {
00103    int hastime;            /*!< If time construct exists */
00104    unsigned int monthmask;       /*!< Mask for month */
00105    unsigned int daymask;         /*!< Mask for date */
00106    unsigned int dowmask;         /*!< Mask for day of week (mon-sun) */
00107    unsigned int minmask[24];     /*!< Mask for minute */
00108 };
00109 
00110 int ast_build_timing(struct ast_timing *i, const char *info);
00111 int ast_check_timing(const struct ast_timing *i);
00112 
00113 struct ast_pbx {
00114    int dtimeoutms;            /*!< Timeout between digits (milliseconds) */
00115    int rtimeoutms;            /*!< Timeout for response (milliseconds) */
00116 };
00117 
00118 
00119 /*!
00120  * \brief Register an alternative dialplan switch
00121  *
00122  * \param sw switch to register
00123  *
00124  * This function registers a populated ast_switch structure with the
00125  * asterisk switching architecture.
00126  *
00127  * \return 0 on success, and other than 0 on failure
00128  */
00129 int ast_register_switch(struct ast_switch *sw);
00130 
00131 /*!
00132  * \brief Unregister an alternative switch
00133  *
00134  * \param sw switch to unregister
00135  * 
00136  * Unregisters a switch from asterisk.
00137  *
00138  * \return nothing
00139  */
00140 void ast_unregister_switch(struct ast_switch *sw);
00141 
00142 /*!
00143  * \brief Look up an application
00144  *
00145  * \param app name of the app
00146  *
00147  * This function searches for the ast_app structure within
00148  * the apps that are registered for the one with the name
00149  * you passed in.
00150  *
00151  * \return the ast_app structure that matches on success, or NULL on failure
00152  */
00153 struct ast_app *pbx_findapp(const char *app);
00154 
00155 /*!
00156  * \brief Execute an application
00157  *
00158  * \param c channel to execute on
00159  * \param app which app to execute
00160  * \param data the data passed into the app
00161  *
00162  * This application executes an application on a given channel.  It
00163  * saves the stack and executes the given application passing in
00164  * the given data.
00165  *
00166  * \return 0 on success, and -1 on failure
00167  */
00168 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data);
00169 
00170 /*!
00171  * \brief Register a new context or find an existing one
00172  *
00173  * \param extcontexts pointer to the ast_context structure pointer
00174  * \param exttable pointer to the hashtable that contains all the elements in extcontexts
00175  * \param name name of the new context
00176  * \param registrar registrar of the context
00177  *
00178  * This function allows you to play in two environments: the global contexts (active dialplan)
00179  * or an external context set of your choosing. To act on the external set, make sure extcontexts
00180  * and exttable are set; for the globals, make sure both extcontexts and exttable are NULL.
00181  *
00182  * This will first search for a context with your name.  If it exists already, it will not
00183  * create a new one.  If it does not exist, it will create a new one with the given name
00184  * and registrar.
00185  *
00186  * \return NULL on failure, and an ast_context structure on success
00187  */
00188 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar);
00189 
00190 /*!
00191  * \brief Merge the temporary contexts into a global contexts list and delete from the 
00192  *        global list the ones that are being added
00193  *
00194  * \param extcontexts pointer to the ast_context structure
00195  * \param exttable pointer to the ast_hashtab structure that contains all the elements in extcontexts
00196  * \param registrar of the context; if it's set the routine will delete all contexts 
00197  *        that belong to that registrar; if NULL only the contexts that are specified 
00198  *        in extcontexts
00199  */
00200 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar);
00201 
00202 /*!
00203  * \brief Destroy a context (matches the specified context (or ANY context if NULL)
00204  *
00205  * \param con context to destroy
00206  * \param registrar who registered it
00207  *
00208  * You can optionally leave out either parameter.  It will find it
00209  * based on either the ast_context or the registrar name.
00210  *
00211  * \return nothing
00212  */
00213 void ast_context_destroy(struct ast_context *con, const char *registrar);
00214 
00215 /*!
00216  * \brief Find a context
00217  *
00218  * \param name name of the context to find
00219  *
00220  * Will search for the context with the given name.
00221  *
00222  * \return the ast_context on success, NULL on failure.
00223  */
00224 struct ast_context *ast_context_find(const char *name);
00225 
00226 /*! \brief The result codes when starting the PBX on a channelwith \see ast_pbx_start.
00227    AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
00228  */
00229 enum ast_pbx_result {
00230    AST_PBX_SUCCESS = 0,
00231    AST_PBX_FAILED = -1,
00232    AST_PBX_CALL_LIMIT = -2,
00233 };
00234 
00235 /*!
00236  * \brief Create a new thread and start the PBX
00237  *
00238  * \param c channel to start the pbx on
00239  *
00240  * \see ast_pbx_run for a synchronous function to run the PBX in the
00241  * current thread, as opposed to starting a new one.
00242  *
00243  * \retval Zero on success
00244  * \retval non-zero on failure
00245  */
00246 enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
00247 
00248 /*!
00249  * \brief Execute the PBX in the current thread
00250  *
00251  * \param c channel to run the pbx on
00252  *
00253  * This executes the PBX on a given channel. It allocates a new
00254  * PBX structure for the channel, and provides all PBX functionality.
00255  * See ast_pbx_start for an asynchronous function to run the PBX in a
00256  * new thread as opposed to the current one.
00257  * 
00258  * \retval Zero on success
00259  * \retval non-zero on failure
00260  */
00261 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
00262 
00263 /*!
00264  * \brief Options for ast_pbx_run()
00265  */
00266 struct ast_pbx_args {
00267    union {
00268       /*! Pad this out so that we have plenty of room to add options
00269        *  but still maintain ABI compatibility over time. */
00270       uint64_t __padding;
00271       struct {
00272          /*! Do not hangup the channel when the PBX is complete. */
00273          unsigned int no_hangup_chan:1;
00274       };
00275    };
00276 };
00277 
00278 /*!
00279  * \brief Execute the PBX in the current thread
00280  *
00281  * \param c channel to run the pbx on
00282  * \param args options for the pbx
00283  *
00284  * This executes the PBX on a given channel. It allocates a new
00285  * PBX structure for the channel, and provides all PBX functionality.
00286  * See ast_pbx_start for an asynchronous function to run the PBX in a
00287  * new thread as opposed to the current one.
00288  * 
00289  * \retval Zero on success
00290  * \retval non-zero on failure
00291  */
00292 enum ast_pbx_result ast_pbx_run_args(struct ast_channel *c, struct ast_pbx_args *args);
00293 
00294 /*! 
00295  * \brief Add and extension to an extension context.  
00296  * 
00297  * \param context context to add the extension to
00298  * \param replace
00299  * \param extension extension to add
00300  * \param priority priority level of extension addition
00301  * \param label extension label
00302  * \param callerid pattern to match CallerID, or NULL to match any CallerID
00303  * \param application application to run on the extension with that priority level
00304  * \param data data to pass to the application
00305  * \param datad
00306  * \param registrar who registered the extension
00307  *
00308  * \retval 0 success 
00309  * \retval -1 failure
00310  */
00311 int ast_add_extension(const char *context, int replace, const char *extension, 
00312    int priority, const char *label, const char *callerid,
00313    const char *application, void *data, void (*datad)(void *), const char *registrar);
00314 
00315 /*! 
00316  * \brief Add an extension to an extension context, this time with an ast_context *.
00317  *
00318  * \note For details about the arguments, check ast_add_extension()
00319  */
00320 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
00321    int priority, const char *label, const char *callerid, 
00322    const char *application, void *data, void (*datad)(void *), const char *registrar);
00323 
00324 /*!
00325  * \brief Map devstate to an extension state.
00326  *
00327  * \param[in] device state
00328  *
00329  * \return the extension state mapping.
00330  */
00331 enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate);
00332 
00333 /*! 
00334  * \brief Uses hint and devicestate callback to get the state of an extension
00335  *
00336  * \param c this is not important
00337  * \param context which context to look in
00338  * \param exten which extension to get state
00339  *
00340  * \return extension state as defined in the ast_extension_states enum
00341  */
00342 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
00343 
00344 /*! 
00345  * \brief Return string representation of the state of an extension
00346  * 
00347  * \param extension_state is the numerical state delivered by ast_extension_state
00348  *
00349  * \return the state of an extension as string
00350  */
00351 const char *ast_extension_state2str(int extension_state);
00352 
00353 /*!
00354  * \brief Registers a state change callback
00355  * 
00356  * \param context which context to look in
00357  * \param exten which extension to get state
00358  * \param callback callback to call if state changed
00359  * \param data to pass to callback
00360  *
00361  * The callback is called if the state of an extension is changed.
00362  *
00363  * \retval -1 on failure
00364  * \retval ID on success
00365  */ 
00366 int ast_extension_state_add(const char *context, const char *exten, 
00367              ast_state_cb_type callback, void *data);
00368 
00369 /*! 
00370  * \brief Deletes a registered state change callback by ID
00371  * 
00372  * \param id of the callback to delete
00373  * \param callback callback
00374  *
00375  * Removes the callback from list of callbacks
00376  *
00377  * \retval 0 success 
00378  * \retval -1 failure
00379  */
00380 int ast_extension_state_del(int id, ast_state_cb_type callback);
00381 
00382 /*! 
00383  * \brief If an extension hint exists, return non-zero
00384  * 
00385  * \param hint buffer for hint
00386  * \param maxlen size of hint buffer
00387  * \param name buffer for name portion of hint
00388  * \param maxnamelen size of name buffer
00389  * \param c this is not important
00390  * \param context which context to look in
00391  * \param exten which extension to search for
00392  *
00393  * \return If an extension within the given context with the priority PRIORITY_HINT
00394  * is found a non zero value will be returned.
00395  * Otherwise, 0 is returned.
00396  */
00397 int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, 
00398    struct ast_channel *c, const char *context, const char *exten);
00399 
00400 /*!
00401  * \brief Determine whether an extension exists
00402  *
00403  * \param c this is not important
00404  * \param context which context to look in
00405  * \param exten which extension to search for
00406  * \param priority priority of the action within the extension
00407  * \param callerid callerid to search for
00408  *
00409  * \note It is possible for autoservice to be started and stopped on c during this
00410  * function call, it is important that c is not locked prior to calling this. Otherwise
00411  * a deadlock may occur
00412  *
00413  * \return If an extension within the given context(or callerid) with the given priority 
00414  *         is found a non zero value will be returned. Otherwise, 0 is returned.
00415  */
00416 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, 
00417    int priority, const char *callerid);
00418 
00419 /*! 
00420  * \brief Find the priority of an extension that has the specified label
00421  * 
00422  * \param c this is not important
00423  * \param context which context to look in
00424  * \param exten which extension to search for
00425  * \param label label of the action within the extension to match to priority
00426  * \param callerid callerid to search for
00427  *
00428  * \note It is possible for autoservice to be started and stopped on c during this
00429  * function call, it is important that c is not locked prior to calling this. Otherwise
00430  * a deadlock may occur
00431  *
00432  * \retval the priority which matches the given label in the extension
00433  * \retval -1 if not found.
00434  */
00435 int ast_findlabel_extension(struct ast_channel *c, const char *context, 
00436    const char *exten, const char *label, const char *callerid);
00437 
00438 /*!
00439  * \brief Find the priority of an extension that has the specified label
00440  *
00441  * \note It is possible for autoservice to be started and stopped on c during this
00442  * function call, it is important that c is not locked prior to calling this. Otherwise
00443  * a deadlock may occur
00444  *
00445  * \note This function is the same as ast_findlabel_extension, except that it accepts
00446  * a pointer to an ast_context structure to specify the context instead of the
00447  * name of the context. Otherwise, the functions behave the same.
00448  */
00449 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, 
00450    const char *exten, const char *label, const char *callerid);
00451 
00452 /*! 
00453  * \brief Looks for a valid matching extension
00454  * 
00455  * \param c not really important
00456  * \param context context to serach within
00457  * \param exten extension to check
00458  * \param priority priority of extension path
00459  * \param callerid callerid of extension being searched for
00460  *
00461  * \note It is possible for autoservice to be started and stopped on c during this
00462  * function call, it is important that c is not locked prior to calling this. Otherwise
00463  * a deadlock may occur
00464  *
00465  * \return If "exten" *could be* a valid extension in this context with or without
00466  * some more digits, return non-zero.  Basically, when this returns 0, no matter
00467  * what you add to exten, it's not going to be a valid extension anymore
00468  */
00469 int ast_canmatch_extension(struct ast_channel *c, const char *context, 
00470    const char *exten, int priority, const char *callerid);
00471 
00472 /*! 
00473  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
00474  *
00475  * \param c not really important XXX
00476  * \param context context to serach within
00477  * \param exten extension to check
00478  * \param priority priority of extension path
00479  * \param callerid callerid of extension being searched for
00480  *
00481  * \note It is possible for autoservice to be started and stopped on c during this
00482  * function call, it is important that c is not locked prior to calling this. Otherwise
00483  * a deadlock may occur
00484  *
00485  * \return If "exten" *could match* a valid extension in this context with
00486  * some more digits, return non-zero.  Does NOT return non-zero if this is
00487  * an exact-match only.  Basically, when this returns 0, no matter
00488  * what you add to exten, it's not going to be a valid extension anymore
00489  */
00490 int ast_matchmore_extension(struct ast_channel *c, const char *context, 
00491    const char *exten, int priority, const char *callerid);
00492 
00493 /*! 
00494  * \brief Determine if a given extension matches a given pattern (in NXX format)
00495  * 
00496  * \param pattern pattern to match
00497  * \param extension extension to check against the pattern.
00498  *
00499  * Checks whether or not the given extension matches the given pattern.
00500  *
00501  * \retval 1 on match
00502  * \retval 0 on failure
00503  */
00504 int ast_extension_match(const char *pattern, const char *extension);
00505 
00506 int ast_extension_close(const char *pattern, const char *data, int needmore);
00507 
00508 /*! 
00509  * \brief Determine if one extension should match before another
00510  * 
00511  * \param a extension to compare with b
00512  * \param b extension to compare with a
00513  *
00514  * Checks whether or extension a should match before extension b
00515  *
00516  * \retval 0 if the two extensions have equal matching priority
00517  * \retval 1 on a > b
00518  * \retval -1 on a < b
00519  */
00520 int ast_extension_cmp(const char *a, const char *b);
00521 
00522 /*! 
00523  * \brief Launch a new extension (i.e. new stack)
00524  * 
00525  * \param c not important
00526  * \param context which context to generate the extension within
00527  * \param exten new extension to add
00528  * \param priority priority of new extension
00529  * \param callerid callerid of extension
00530  * \param found
00531  * \param combined_find_spawn 
00532  *
00533  * This adds a new extension to the asterisk extension list.
00534  *
00535  * \note It is possible for autoservice to be started and stopped on c during this
00536  * function call, it is important that c is not locked prior to calling this. Otherwise
00537  * a deadlock may occur
00538  *
00539  * \retval 0 on success 
00540  * \retval -1 on failure.
00541  */
00542 int ast_spawn_extension(struct ast_channel *c, const char *context, 
00543       const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn);
00544 
00545 /*! 
00546  * \brief Add a context include
00547  *
00548  * \param context context to add include to
00549  * \param include new include to add
00550  * \param registrar who's registering it
00551  *
00552  * Adds an include taking a char * string as the context parameter
00553  *
00554  * \retval 0 on success 
00555  * \retval -1 on error
00556 */
00557 int ast_context_add_include(const char *context, const char *include, 
00558    const char *registrar);
00559 
00560 /*! 
00561  * \brief Add a context include
00562  * 
00563  * \param con context to add the include to
00564  * \param include include to add
00565  * \param registrar who registered the context
00566  *
00567  * Adds an include taking a struct ast_context as the first parameter
00568  *
00569  * \retval 0 on success 
00570  * \retval -1 on failure
00571  */
00572 int ast_context_add_include2(struct ast_context *con, const char *include, 
00573    const char *registrar);
00574 
00575 /*! 
00576  * \brief Remove a context include
00577  * 
00578  * \note See ast_context_add_include for information on arguments
00579  *
00580  * \retval 0 on success
00581  * \retval -1 on failure
00582  */
00583 int ast_context_remove_include(const char *context, const char *include, 
00584    const char *registrar);
00585 
00586 /*! 
00587  * \brief Removes an include by an ast_context structure 
00588  * 
00589  * \note See ast_context_add_include2 for information on arguments
00590  *
00591  * \retval 0 on success
00592  * \retval -1 on success
00593  */
00594 int ast_context_remove_include2(struct ast_context *con, const char *include, 
00595    const char *registrar);
00596 
00597 /*! 
00598  * \brief Verifies includes in an ast_contect structure
00599  * 
00600  * \param con context in which to verify the includes
00601  *
00602  * \retval 0 if no problems found 
00603  * \retval -1 if there were any missing context
00604  */
00605 int ast_context_verify_includes(struct ast_context *con);
00606      
00607 /*! 
00608  * \brief Add a switch
00609  * 
00610  * \param context context to which to add the switch
00611  * \param sw switch to add
00612  * \param data data to pass to switch
00613  * \param eval whether to evaluate variables when running switch
00614  * \param registrar whoever registered the switch
00615  *
00616  * This function registers a switch with the asterisk switch architecture
00617  *
00618  * \retval 0 on success 
00619  * \retval -1 on failure
00620  */
00621 int ast_context_add_switch(const char *context, const char *sw, const char *data, 
00622    int eval, const char *registrar);
00623 
00624 /*! 
00625  * \brief Adds a switch (first param is a ast_context)
00626  * 
00627  * \note See ast_context_add_switch() for argument information, with the exception of
00628  *       the first argument. In this case, it's a pointer to an ast_context structure
00629  *       as opposed to the name.
00630  */
00631 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, 
00632    int eval, const char *registrar);
00633 
00634 /*! 
00635  * \brief Remove a switch
00636  * 
00637  * Removes a switch with the given parameters
00638  *
00639  * \retval 0 on success 
00640  * \retval -1 on failure
00641  */
00642 int ast_context_remove_switch(const char *context, const char *sw, 
00643    const char *data, const char *registrar);
00644 
00645 int ast_context_remove_switch2(struct ast_context *con, const char *sw, 
00646    const char *data, const char *registrar);
00647 
00648 /*! 
00649  * \brief Simply remove extension from context
00650  * 
00651  * \param context context to remove extension from
00652  * \param extension which extension to remove
00653  * \param priority priority of extension to remove (0 to remove all)
00654  * \param callerid NULL to remove all; non-NULL to match a single record per priority
00655  * \param matchcid non-zero to match callerid element (if non-NULL); 0 to match default case
00656  * \param registrar registrar of the extension
00657  *
00658  * This function removes an extension from a given context.
00659  *
00660  * \retval 0 on success 
00661  * \retval -1 on failure
00662  */
00663 int ast_context_remove_extension(const char *context, const char *extension, int priority,
00664    const char *registrar);
00665 
00666 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
00667    int priority, const char *registrar, int already_locked);
00668 
00669 int ast_context_remove_extension_callerid(const char *context, const char *extension,
00670    int priority, const char *callerid, int matchcid, const char *registrar);
00671 
00672 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
00673    int priority, const char *callerid, int matchcid, const char *registrar,
00674    int already_locked);
00675 
00676 /*! 
00677  * \brief Add an ignorepat
00678  * 
00679  * \param context which context to add the ignorpattern to
00680  * \param ignorepat ignorepattern to set up for the extension
00681  * \param registrar registrar of the ignore pattern
00682  *
00683  * Adds an ignore pattern to a particular context.
00684  *
00685  * \retval 0 on success 
00686  * \retval -1 on failure
00687  */
00688 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
00689 
00690 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
00691 
00692 /* 
00693  * \brief Remove an ignorepat
00694  * 
00695  * \param context context from which to remove the pattern
00696  * \param ignorepat the pattern to remove
00697  * \param registrar the registrar of the ignore pattern
00698  *
00699  * This removes the given ignorepattern
00700  *
00701  * \retval 0 on success 
00702  * \retval -1 on failure
00703  */
00704 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
00705 
00706 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
00707 
00708 /*! 
00709  * \brief Checks to see if a number should be ignored
00710  * 
00711  * \param context context to search within
00712  * \param pattern to check whether it should be ignored or not
00713  *
00714  * Check if a number should be ignored with respect to dialtone cancellation.
00715  *
00716  * \retval 0 if the pattern should not be ignored 
00717  * \retval non-zero if the pattern should be ignored 
00718  */
00719 int ast_ignore_pattern(const char *context, const char *pattern);
00720 
00721 /* Locking functions for outer modules, especially for completion functions */
00722 
00723 /*! 
00724  * \brief Write locks the context list
00725  *
00726  * \retval 0 on success 
00727  * \retval -1 on error
00728  */
00729 int ast_wrlock_contexts(void);
00730 
00731 /*!
00732  * \brief Read locks the context list
00733  *
00734  * \retval 0 on success
00735  * \retval -1 on error
00736  */
00737 int ast_rdlock_contexts(void);
00738 
00739 /*! 
00740  * \brief Unlocks contexts
00741  * 
00742  * \retval 0 on success 
00743  * \retval -1 on failure
00744  */
00745 int ast_unlock_contexts(void);
00746 
00747 /*! 
00748  * \brief Write locks a given context
00749  * 
00750  * \param con context to lock
00751  *
00752  * \retval 0 on success 
00753  * \retval -1 on failure
00754  */
00755 int ast_wrlock_context(struct ast_context *con);
00756 
00757 /*!
00758  * \brief Read locks a given context
00759  *
00760  * \param con context to lock
00761  *
00762  * \retval 0 on success
00763  * \retval -1 on failure
00764  */
00765 int ast_rdlock_context(struct ast_context *con);
00766 
00767 /*! 
00768  * \retval Unlocks the given context
00769  * 
00770  * \param con context to unlock
00771  *
00772  * \retval 0 on success 
00773  * \retval -1 on failure
00774  */
00775 int ast_unlock_context(struct ast_context *con);
00776 
00777 /*! 
00778  * \brief locks the macrolock in the given given context
00779  *
00780  * \param macrocontext name of the macro-context to lock
00781  *
00782  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
00783  *
00784  * \retval 0 on success
00785  * \retval -1 on failure
00786  */
00787 int ast_context_lockmacro(const char *macrocontext);
00788 
00789 /*!
00790  * \brief Unlocks the macrolock in the given context
00791  *
00792  * \param macrocontext name of the macro-context to unlock
00793  *
00794  * Unlocks the given macro-context so that another thread (call) can execute it
00795  *
00796  * \retval 0 on success
00797  * \retval -1 on failure
00798  */
00799 int ast_context_unlockmacro(const char *macrocontext);
00800 
00801 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
00802 
00803 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
00804 
00805 /*! Synchronously or asynchronously make an outbound call and send it to a
00806    particular extension */
00807 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);
00808 
00809 /*! Synchronously or asynchronously make an outbound call and send it to a
00810    particular application with given extension */
00811 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);
00812 
00813 /*!
00814  * \brief Evaluate a condition
00815  *
00816  * \retval 0 if the condition is NULL or of zero length
00817  * \retval int If the string is an integer, the integer representation of
00818  *             the integer is returned
00819  * \retval 1 Any other non-empty string
00820  */
00821 int pbx_checkcondition(const char *condition);
00822 
00823 /*! @name 
00824  * Functions for returning values from structures */
00825 /*! @{ */
00826 const char *ast_get_context_name(struct ast_context *con);
00827 const char *ast_get_extension_name(struct ast_exten *exten);
00828 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
00829 const char *ast_get_include_name(struct ast_include *include);
00830 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
00831 const char *ast_get_switch_name(struct ast_sw *sw);
00832 const char *ast_get_switch_data(struct ast_sw *sw);
00833 int ast_get_switch_eval(struct ast_sw *sw);
00834    
00835 /*! @} */
00836 
00837 /*! @name Other Extension stuff */
00838 /*! @{ */
00839 int ast_get_extension_priority(struct ast_exten *exten);
00840 int ast_get_extension_matchcid(struct ast_exten *e);
00841 const char *ast_get_extension_cidmatch(struct ast_exten *e);
00842 const char *ast_get_extension_app(struct ast_exten *e);
00843 const char *ast_get_extension_label(struct ast_exten *e);
00844 void *ast_get_extension_app_data(struct ast_exten *e);
00845 /*! @} */
00846 
00847 /*! @name Registrar info functions ... */
00848 /*! @{ */
00849 const char *ast_get_context_registrar(struct ast_context *c);
00850 const char *ast_get_extension_registrar(struct ast_exten *e);
00851 const char *ast_get_include_registrar(struct ast_include *i);
00852 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
00853 const char *ast_get_switch_registrar(struct ast_sw *sw);
00854 /*! @} */
00855 
00856 /* Walking functions ... */
00857 struct ast_context *ast_walk_contexts(struct ast_context *con);
00858 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
00859    struct ast_exten *priority);
00860 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
00861    struct ast_exten *priority);
00862 struct ast_include *ast_walk_context_includes(struct ast_context *con,
00863    struct ast_include *inc);
00864 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
00865    struct ast_ignorepat *ip);
00866 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
00867 
00868 /*!
00869  * \note Will lock the channel.
00870  */
00871 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
00872 
00873 /*!
00874  * \note Will lock the channel.
00875  *
00876  * \note This function will return a pointer to the buffer inside the channel
00877  * variable.  This value should only be accessed with the channel locked.  If
00878  * the value needs to be kept around, it should be done by using the following
00879  * thread-safe code:
00880  * \code
00881  *    const char *var;
00882  *
00883  *    ast_channel_lock(chan);
00884  *    if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
00885  *       var = ast_strdupa(var);
00886  *    }
00887  *    ast_channel_unlock(chan);
00888  * \endcode
00889  */
00890 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
00891 
00892 /*!
00893  * \note Will lock the channel.
00894  */
00895 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
00896 
00897 /*!
00898  * \note Will lock the channel.
00899  */
00900 void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
00901 
00902 /*!
00903  * \note Will lock the channel.
00904  */
00905 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
00906 void pbx_builtin_clear_globals(void);
00907 
00908 /*!
00909  * \note Will lock the channel.
00910  */
00911 int pbx_builtin_setvar(struct ast_channel *chan, void *data);
00912 int pbx_builtin_setvar_multiple(struct ast_channel *chan, void *data);
00913 
00914 int pbx_builtin_raise_exception(struct ast_channel *chan, void *data);
00915 
00916 void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
00917 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
00918 
00919 int ast_extension_patmatch(const char *pattern, const char *data);
00920 
00921 /*! Set "autofallthrough" flag, if newval is <0, does not acutally set.  If
00922   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
00923   fall through (reads extension instead).  Returns previous value. */
00924 int pbx_set_autofallthrough(int newval);
00925 
00926 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not acutally set.  If
00927   set to 1, sets to use the new Trie-based pattern matcher.  If newval set to 0, sets to use
00928   the old linear-search algorithm.  Returns previous value. */
00929 int pbx_set_extenpatternmatchnew(int newval);
00930 
00931 /*! Set "overrideswitch" field.  If set and of nonzero length, all contexts
00932  * will be tried directly through the named switch prior to any other
00933  * matching within that context.
00934  * \since 1.6.1
00935  */ 
00936 void pbx_set_overrideswitch(const char *newval);
00937 
00938 /*!
00939  * \note This function will handle locking the channel as needed.
00940  */
00941 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
00942 
00943 /*!
00944  * \note I can find neither parsable nor parseable at dictionary.com, 
00945  *       but google gives me 169000 hits for parseable and only 49,800 
00946  *       for parsable 
00947  *
00948  * \note This function will handle locking the channel as needed.
00949  */
00950 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
00951 
00952 /*!
00953  * \note This function will handle locking the channel as needed.
00954  */
00955 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string);
00956 
00957 /*!
00958  * \note This function will handle locking the channel as needed.
00959  */
00960 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
00961 
00962 /*!
00963  * \note This function will handle locking the channel as needed.
00964  */
00965 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
00966 
00967 struct ast_custom_function* ast_custom_function_find(const char *name);
00968 
00969 /*!
00970  * \brief Unregister a custom function
00971  */
00972 int ast_custom_function_unregister(struct ast_custom_function *acf);
00973 
00974 /*!
00975  * \brief Register a custom function
00976  */
00977 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, ast_module_info->self)
00978 
00979 /*!
00980  * \brief Register a custom function
00981  */
00982 int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod);
00983 
00984 /*! 
00985  * \brief Retrieve the number of active calls
00986  */
00987 int ast_active_calls(void);
00988 
00989 /*! 
00990  * \brief Retrieve the total number of calls processed through the PBX since last restart
00991  */
00992 int ast_processed_calls(void);
00993    
00994 /*!
00995  * \brief executes a read operation on a function 
00996  *
00997  * \param chan Channel to execute on
00998  * \param function Data containing the function call string (will be modified)
00999  * \param workspace A pointer to safe memory to use for a return value 
01000  * \param len the number of bytes in workspace
01001  *
01002  * This application executes a function in read mode on a given channel.
01003  *
01004  * \return zero on success, non-zero on failure
01005  */
01006 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
01007 
01008 /*!
01009  * \brief executes a write operation on a function
01010  *
01011  * \param chan Channel to execute on
01012  * \param function Data containing the function call string (will be modified)
01013  * \param value A value parameter to pass for writing
01014  *
01015  * This application executes a function in write mode on a given channel.
01016  *
01017  * \return zero on success, non-zero on failure
01018  */
01019 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
01020 
01021 /*!
01022  * When looking up extensions, we can have different requests
01023  * identified by the 'action' argument, as follows.
01024  * Note that the coding is such that the low 4 bits are the
01025  * third argument to extension_match_core.
01026  */
01027 
01028 enum ext_match_t {
01029    E_MATCHMORE =  0x00, /* extension can match but only with more 'digits' */
01030    E_CANMATCH =   0x01, /* extension can match with or without more 'digits' */
01031    E_MATCH =   0x02, /* extension is an exact match */
01032    E_MATCH_MASK = 0x03, /* mask for the argument to extension_match_core() */
01033    E_SPAWN =   0x12, /* want to spawn an extension. Requires exact match */
01034    E_FINDLABEL =  0x22  /* returns the priority for a given label. Requires exact match */
01035 };
01036 
01037 #define STATUS_NO_CONTEXT  1
01038 #define STATUS_NO_EXTENSION   2
01039 #define STATUS_NO_PRIORITY 3
01040 #define STATUS_NO_LABEL    4
01041 #define STATUS_SUCCESS     5 
01042 #define AST_PBX_MAX_STACK  128
01043 
01044 /* request and result for pbx_find_extension */
01045 struct pbx_find_info {
01046 #if 0
01047    const char *context;
01048    const char *exten;
01049    int priority;
01050 #endif
01051 
01052    char *incstack[AST_PBX_MAX_STACK];      /* filled during the search */
01053    int stacklen;                   /* modified during the search */
01054    int status;                     /* set on return */
01055    struct ast_switch *swo;         /* set on return */
01056    const char *data;               /* set on return */
01057    const char *foundcontext;       /* set on return */
01058 };
01059  
01060 struct ast_exten *pbx_find_extension(struct ast_channel *chan,
01061                             struct ast_context *bypass, struct pbx_find_info *q,
01062                             const char *context, const char *exten, int priority,
01063                             const char *label, const char *callerid, enum ext_match_t action);
01064 
01065 
01066 /* every time a write lock is obtained for contexts,
01067    a counter is incremented. You can check this via the
01068    following func */
01069 
01070 int ast_wrlock_contexts_version(void);
01071    
01072 
01073 /* hashtable functions for contexts */
01074 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
01075 unsigned int ast_hashtab_hash_contexts(const void *obj);
01076 
01077 #if defined(__cplusplus) || defined(c_plusplus)
01078 }
01079 #endif
01080 
01081 #endif /* _ASTERISK_PBX_H */

Generated on Wed Aug 18 22:33:54 2010 for Asterisk - the Open Source PBX by  doxygen 1.4.7