Thu Apr 28 2011 17:13:34

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