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/channel.h"
00027 #include "asterisk/sched.h"
00028 #include "asterisk/devicestate.h"
00029 #include "asterisk/presencestate.h"
00030 #include "asterisk/chanvars.h"
00031 #include "asterisk/hashtab.h"
00032 #include "asterisk/stringfields.h"
00033 #include "asterisk/xmldoc.h"
00034 #include "asterisk/format.h"
00035 
00036 #if defined(__cplusplus) || defined(c_plusplus)
00037 extern "C" {
00038 #endif
00039 
00040 #define AST_MAX_APP  32 /*!< Max length of an application */
00041 
00042 #define AST_PBX_GOTO_FAILED -3
00043 #define AST_PBX_KEEP    0
00044 #define AST_PBX_REPLACE 1
00045 
00046 /*! \brief Special return values from applications to the PBX
00047  * @{ */
00048 #define AST_PBX_HANGUP                -1    /*!< Jump to the 'h' exten */
00049 #define AST_PBX_OK                     0    /*!< No errors */
00050 #define AST_PBX_ERROR                  1    /*!< Jump to the 'e' exten */
00051 #define AST_PBX_INCOMPLETE             12   /*!< Return to PBX matching, allowing more digits for the extension */
00052 /*! @} */
00053 
00054 #define PRIORITY_HINT   -1 /*!< Special Priority for a hint */
00055 
00056 /*!
00057  * \brief Extension states
00058  * \note States can be combined
00059  * \ref AstExtState
00060  */
00061 enum ast_extension_states {
00062    AST_EXTENSION_REMOVED = -2,   /*!< Extension removed */
00063    AST_EXTENSION_DEACTIVATED = -1,  /*!< Extension hint removed */
00064    AST_EXTENSION_NOT_INUSE = 0,  /*!< No device INUSE or BUSY  */
00065    AST_EXTENSION_INUSE = 1 << 0, /*!< One or more devices INUSE */
00066    AST_EXTENSION_BUSY = 1 << 1,  /*!< All devices BUSY */
00067    AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
00068    AST_EXTENSION_RINGING = 1 << 3,  /*!< All devices RINGING */
00069    AST_EXTENSION_ONHOLD = 1 << 4,   /*!< All devices ONHOLD */
00070 };
00071 
00072 /*!
00073  * \brief extension matchcid types
00074  * \note matchcid in ast_exten retains 0/1, this adds 3rd state for functions to specify all
00075  * \see ast_context_remove_extension_callerid
00076  */
00077 enum ast_ext_matchcid_types {
00078    AST_EXT_MATCHCID_OFF = 0,  /*!< Match only extensions with matchcid=0 */
00079    AST_EXT_MATCHCID_ON = 1,   /*!< Match only extensions with matchcid=1 AND cidmatch matches */
00080    AST_EXT_MATCHCID_ANY = 2,  /*!< Match both - used only in functions manipulating ast_exten's */
00081 };
00082 
00083 struct ast_context;
00084 struct ast_exten;
00085 struct ast_include;
00086 struct ast_ignorepat;
00087 struct ast_sw;
00088  
00089 enum ast_state_cb_update_reason {
00090    /*! The extension state update is a result of a device state changing on the extension. */
00091    AST_HINT_UPDATE_DEVICE = 1,
00092    /*! The extension state update is a result of presence state changing on the extension. */
00093    AST_HINT_UPDATE_PRESENCE = 2,
00094 };
00095 
00096 struct ast_device_state_info {
00097    enum ast_device_state device_state;
00098    struct ast_channel *causing_channel;
00099    char device_name[1];
00100 };
00101 
00102 struct ast_state_cb_info {
00103    enum ast_state_cb_update_reason reason;
00104    enum ast_extension_states exten_state;
00105    struct ao2_container *device_state_info; /* holds ast_device_state_info, must be referenced by callback if stored */
00106    enum ast_presence_state presence_state;
00107    const char *presence_subtype;
00108    const char *presence_message;
00109 };
00110 
00111 /*! \brief Typedef for devicestate and hint callbacks */
00112 typedef int (*ast_state_cb_type)(char *context, char *id, struct ast_state_cb_info *info, void *data);
00113 
00114 /*! \brief Typedef for devicestate and hint callback removal indication callback */
00115 typedef void (*ast_state_cb_destroy_type)(int id, void *data);
00116 
00117 /*! \brief Data structure associated with a custom dialplan function */
00118 struct ast_custom_function {
00119    const char *name;       /*!< Name */
00120    AST_DECLARE_STRING_FIELDS(
00121       AST_STRING_FIELD(synopsis);     /*!< Synopsis text for 'show functions' */
00122       AST_STRING_FIELD(desc);    /*!< Description (help text) for 'show functions &lt;name&gt;' */
00123       AST_STRING_FIELD(syntax);       /*!< Syntax text for 'core show functions' */
00124       AST_STRING_FIELD(arguments);    /*!< Arguments description */
00125       AST_STRING_FIELD(seealso);      /*!< See also */
00126    );
00127    enum ast_doc_src docsrc;      /*!< Where the documentation come from */
00128    /*! Read function, if read is supported */
00129    ast_acf_read_fn_t read;    /*!< Read function, if read is supported */
00130    /*! Read function, if read is supported.  Note: only one of read or read2
00131     * needs to be implemented.  In new code, read2 should be implemented as
00132     * the way forward, but they should return identical results, within the
00133     * constraints of buffer size, if both are implemented.  That is, if the
00134     * read function is handed a 16-byte buffer, and the result is 17 bytes
00135     * long, then the first 15 bytes (remember NULL terminator) should be
00136     * the same for both the read and the read2 methods. */
00137    ast_acf_read2_fn_t read2;
00138    /*! If no read2 function is provided, what maximum size? */
00139    size_t read_max;
00140    /*! Write function, if write is supported */
00141    ast_acf_write_fn_t write;  /*!< Write function, if write is supported */
00142    struct ast_module *mod;         /*!< Module this custom function belongs to */
00143    unsigned int read_escalates:1;  /*!< The read function is to be considered
00144                 * 'dangerous', and should not be run directly
00145                 * from external interfaces (AMI, ARI, etc.)
00146                 * \since 12 */
00147    unsigned int write_escalates:1; /*!< The write function is to be considerd
00148                 * 'dangerous', and should not be run directly
00149                 * from external interfaces (AMI, ARI, etc.)
00150                 * \since 12 */
00151 
00152    AST_RWLIST_ENTRY(ast_custom_function) acflist;
00153 };
00154 
00155 /*! \brief All switch functions have the same interface, so define a type for them */
00156 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
00157    const char *exten, int priority, const char *callerid, const char *data);
00158 
00159 /*!< Data structure associated with an Asterisk switch */
00160 struct ast_switch {
00161    AST_LIST_ENTRY(ast_switch) list;
00162    const char *name;       /*!< Name of the switch */
00163    const char *description;      /*!< Description of the switch */
00164 
00165    ast_switch_f *exists;
00166    ast_switch_f *canmatch;
00167    ast_switch_f *exec;
00168    ast_switch_f *matchmore;
00169 };
00170 
00171 struct ast_timing {
00172    int hastime;                    /*!< If time construct exists */
00173    unsigned int monthmask;         /*!< Mask for month */
00174    unsigned int daymask;           /*!< Mask for date */
00175    unsigned int dowmask;           /*!< Mask for day of week (sun-sat) */
00176    unsigned int minmask[48];       /*!< Mask for minute */
00177    char *timezone;                 /*!< NULL, or zoneinfo style timezone */
00178 };
00179 
00180 /*!
00181  * \brief Construct a timing bitmap, for use in time-based conditionals.
00182  * \param i Pointer to an ast_timing structure.
00183  * \param info Standard string containing a timerange, weekday range, monthday range, and month range, as well as an optional timezone.
00184  * \retval Returns 1 on success or 0 on failure.
00185  */
00186 int ast_build_timing(struct ast_timing *i, const char *info);
00187 
00188 /*!
00189  * \brief Evaluate a pre-constructed bitmap as to whether the current time falls within the range specified.
00190  * \param i Pointer to an ast_timing structure.
00191  * \retval Returns 1, if the time matches or 0, if the current time falls outside of the specified range.
00192  */
00193 int ast_check_timing(const struct ast_timing *i);
00194 
00195 /*!
00196  * \brief Evaluate a pre-constructed bitmap as to whether a particular time falls within the range specified.
00197  * \param i Pointer to an ast_timing structure.
00198  * \param tv Specified time
00199  * \retval Returns 1, if the time matches or 0, if the time falls outside of the specified range.
00200  */
00201 int ast_check_timing2(const struct ast_timing *i, const struct timeval tv);
00202 
00203 /*!
00204  * \brief Deallocates memory structures associated with a timing bitmap.
00205  * \param i Pointer to an ast_timing structure.
00206  * \retval 0 success
00207  * \retval non-zero failure (number suitable to pass to \see strerror)
00208  */
00209 int ast_destroy_timing(struct ast_timing *i);
00210 
00211 struct ast_pbx {
00212    int dtimeoutms;            /*!< Timeout between digits (milliseconds) */
00213    int rtimeoutms;            /*!< Timeout for response (milliseconds) */
00214 };
00215 
00216 
00217 /*!
00218  * \brief Register an alternative dialplan switch
00219  *
00220  * \param sw switch to register
00221  *
00222  * This function registers a populated ast_switch structure with the
00223  * asterisk switching architecture.
00224  *
00225  * \retval 0 success
00226  * \retval non-zero failure
00227  */
00228 int ast_register_switch(struct ast_switch *sw);
00229 
00230 /*!
00231  * \brief Unregister an alternative switch
00232  *
00233  * \param sw switch to unregister
00234  *
00235  * Unregisters a switch from asterisk.
00236  *
00237  * \return nothing
00238  */
00239 void ast_unregister_switch(struct ast_switch *sw);
00240 
00241 /*!
00242  * \brief Look up an application
00243  *
00244  * \param app name of the app
00245  *
00246  * This function searches for the ast_app structure within
00247  * the apps that are registered for the one with the name
00248  * you passed in.
00249  *
00250  * \return the ast_app structure that matches on success, or NULL on failure
00251  */
00252 struct ast_app *pbx_findapp(const char *app);
00253 
00254 /*!
00255  * \brief Execute an application
00256  *
00257  * \param c channel to execute on
00258  * \param app which app to execute
00259  * \param data the data passed into the app
00260  *
00261  * This application executes an application on a given channel.  It
00262  * saves the stack and executes the given application passing in
00263  * the given data.
00264  *
00265  * \retval 0 success
00266  * \retval -1 failure
00267  */
00268 int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data);
00269 
00270 /*!
00271  * \brief Register a new context or find an existing one
00272  *
00273  * \param extcontexts pointer to the ast_context structure pointer
00274  * \param exttable pointer to the hashtable that contains all the elements in extcontexts
00275  * \param name name of the new context
00276  * \param registrar registrar of the context
00277  *
00278  * This function allows you to play in two environments: the global contexts (active dialplan)
00279  * or an external context set of your choosing. To act on the external set, make sure extcontexts
00280  * and exttable are set; for the globals, make sure both extcontexts and exttable are NULL.
00281  *
00282  * This will first search for a context with your name.  If it exists already, it will not
00283  * create a new one.  If it does not exist, it will create a new one with the given name
00284  * and registrar.
00285  *
00286  * \return NULL on failure, and an ast_context structure on success
00287  */
00288 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar);
00289 
00290 /*!
00291  * \brief Merge the temporary contexts into a global contexts list and delete from the
00292  *        global list the ones that are being added
00293  *
00294  * \param extcontexts pointer to the ast_context structure
00295  * \param exttable pointer to the ast_hashtab structure that contains all the elements in extcontexts
00296  * \param registrar of the context; if it's set the routine will delete all contexts
00297  *        that belong to that registrar; if NULL only the contexts that are specified
00298  *        in extcontexts
00299  */
00300 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar);
00301 
00302 /*!
00303  * \brief Destroy a context (matches the specified context (or ANY context if NULL)
00304  *
00305  * \param con context to destroy
00306  * \param registrar who registered it
00307  *
00308  * You can optionally leave out either parameter.  It will find it
00309  * based on either the ast_context or the registrar name.
00310  *
00311  * \return nothing
00312  */
00313 void ast_context_destroy(struct ast_context *con, const char *registrar);
00314 
00315 /*!
00316  * \brief Find a context
00317  *
00318  * \param name name of the context to find
00319  *
00320  * Will search for the context with the given name.
00321  *
00322  * \return the ast_context on success, NULL on failure.
00323  */
00324 struct ast_context *ast_context_find(const char *name);
00325 
00326 /*!
00327  * \brief The result codes when starting the PBX on a channel with ast_pbx_start.
00328  * \note AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
00329  * \see ast_pbx_start
00330  */
00331 enum ast_pbx_result {
00332    AST_PBX_SUCCESS = 0,
00333    AST_PBX_FAILED = -1,
00334    AST_PBX_CALL_LIMIT = -2,
00335 };
00336 
00337 /*!
00338  * \brief Create a new thread and start the PBX
00339  *
00340  * \param c channel to start the pbx on
00341  *
00342  * \see ast_pbx_run for a synchronous function to run the PBX in the
00343  * current thread, as opposed to starting a new one.
00344  *
00345  * \retval Zero on success
00346  * \retval non-zero on failure
00347  */
00348 enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
00349 
00350 /*!
00351  * \brief Execute the PBX in the current thread
00352  *
00353  * \param c channel to run the pbx on
00354  *
00355  * This executes the PBX on a given channel. It allocates a new
00356  * PBX structure for the channel, and provides all PBX functionality.
00357  * See ast_pbx_start for an asynchronous function to run the PBX in a
00358  * new thread as opposed to the current one.
00359  *
00360  * \retval Zero on success
00361  * \retval non-zero on failure
00362  */
00363 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
00364 
00365 /*!
00366  * \brief Options for ast_pbx_run()
00367  */
00368 struct ast_pbx_args {
00369    union {
00370       /*! Pad this out so that we have plenty of room to add options
00371        *  but still maintain ABI compatibility over time. */
00372       uint64_t __padding;
00373       struct {
00374          /*! Do not hangup the channel when the PBX is complete. */
00375          unsigned int no_hangup_chan:1;
00376       };
00377    };
00378 };
00379 
00380 /*!
00381  * \brief Execute the PBX in the current thread
00382  *
00383  * \param c channel to run the pbx on
00384  * \param args options for the pbx
00385  *
00386  * This executes the PBX on a given channel. It allocates a new
00387  * PBX structure for the channel, and provides all PBX functionality.
00388  * See ast_pbx_start for an asynchronous function to run the PBX in a
00389  * new thread as opposed to the current one.
00390  *
00391  * \retval Zero on success
00392  * \retval non-zero on failure
00393  */
00394 enum ast_pbx_result ast_pbx_run_args(struct ast_channel *c, struct ast_pbx_args *args);
00395 
00396 /*!
00397  * \brief Run the h exten from the given context.
00398  * \since 11.0
00399  *
00400  * \param chan Channel to run the h exten on.
00401  * \param context Context the h exten is in.
00402  *
00403  * \return Nothing
00404  */
00405 void ast_pbx_h_exten_run(struct ast_channel *chan, const char *context);
00406 
00407 /*!
00408  * \brief Run all hangup handlers on the channel.
00409  * \since 11.0
00410  *
00411  * \param chan Channel to run the hangup handlers on.
00412  *
00413  * \note Absolutely _NO_ channel locks should be held before calling this function.
00414  *
00415  * \retval Zero if no hangup handlers run.
00416  * \retval non-zero if hangup handlers were run.
00417  */
00418 int ast_pbx_hangup_handler_run(struct ast_channel *chan);
00419 
00420 /*!
00421  * \brief Init the hangup handler container on a channel.
00422  * \since 11.0
00423  *
00424  * \param chan Channel to init the hangup handler container on.
00425  *
00426  * \return Nothing
00427  */
00428 void ast_pbx_hangup_handler_init(struct ast_channel *chan);
00429 
00430 /*!
00431  * \brief Destroy the hangup handler container on a channel.
00432  * \since 11.0
00433  *
00434  * \param chan Channel to destroy the hangup handler container on.
00435  *
00436  * \return Nothing
00437  */
00438 void ast_pbx_hangup_handler_destroy(struct ast_channel *chan);
00439 
00440 /*!
00441  * \brief Pop the top of the channel hangup handler stack.
00442  * \since 11.0
00443  *
00444  * \param chan Channel to push the hangup handler onto.
00445  *
00446  * \retval TRUE if a handler was popped off of the stack.
00447  */
00448 int ast_pbx_hangup_handler_pop(struct ast_channel *chan);
00449 
00450 /*!
00451  * \brief Push the given hangup handler onto the channel hangup handler stack.
00452  * \since 11.0
00453  *
00454  * \param chan Channel to push the hangup handler onto.
00455  * \param handler Gosub application parameter string.
00456  *
00457  * \return Nothing
00458  */
00459 void ast_pbx_hangup_handler_push(struct ast_channel *chan, const char *handler);
00460 
00461 /*!
00462  * \brief Add and extension to an extension context.
00463  *
00464  * \param context context to add the extension to
00465  * \param replace
00466  * \param extension extension to add
00467  * \param priority priority level of extension addition
00468  * \param label extension label
00469  * \param callerid pattern to match CallerID, or NULL to match any CallerID
00470  * \param application application to run on the extension with that priority level
00471  * \param data data to pass to the application
00472  * \param datad
00473  * \param registrar who registered the extension
00474  *
00475  * \retval 0 success
00476  * \retval -1 failure
00477  */
00478 int ast_add_extension(const char *context, int replace, const char *extension,
00479    int priority, const char *label, const char *callerid,
00480    const char *application, void *data, void (*datad)(void *), const char *registrar);
00481 
00482 /*!
00483  * \brief Add an extension to an extension context, this time with an ast_context *.
00484  *
00485  * \note For details about the arguments, check ast_add_extension()
00486  */
00487 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
00488    int priority, const char *label, const char *callerid,
00489    const char *application, void *data, void (*datad)(void *), const char *registrar);
00490 
00491 /*!
00492  * \brief Same as ast_add_extension2, but assumes you have already locked context
00493  * \since 12.0.0
00494  *
00495  * \note con must be write locked prior to calling. For details about the arguments,
00496  *       check ast_add_extension2()
00497  */
00498 int ast_add_extension2_nolock(struct ast_context *con, int replace, const char *extension,
00499    int priority, const char *label, const char *callerid,
00500    const char *application, void *data, void (*datad)(void *), const char *registrar);
00501 
00502 /*!
00503  * \brief Map devstate to an extension state.
00504  *
00505  * \param[in] devstate device state
00506  *
00507  * \return the extension state mapping.
00508  */
00509 enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate);
00510 
00511 /*!
00512  * \brief Uses hint and devicestate callback to get the state of an extension
00513  *
00514  * \param c this is not important
00515  * \param context which context to look in
00516  * \param exten which extension to get state
00517  *
00518  * \return extension state as defined in the ast_extension_states enum
00519  */
00520 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
00521 
00522 /*!
00523  * \brief Uses hint and devicestate callback to get the extended state of an extension
00524  * \since 11
00525  *
00526  * \param c this is not important
00527  * \param context which context to look in
00528  * \param exten which extension to get state
00529  * \param[out] device_state_info ptr to an ao2_container with extended state info, must be unref'd after use.
00530  *
00531  * \return extension state as defined in the ast_extension_states enum
00532  */
00533 int ast_extension_state_extended(struct ast_channel *c, const char *context, const char *exten,
00534    struct ao2_container **device_state_info);
00535 
00536 /*!
00537  * \brief Uses hint and presence state callback to get the presence state of an extension
00538  *
00539  * \param c this is not important
00540  * \param context which context to look in
00541  * \param exten which extension to get state
00542  * \param[out] subtype Further information regarding the presence returned
00543  * \param[out] message Custom message further describing current presence
00544  *
00545  * \note The subtype and message are dynamically allocated and must be freed by
00546  * the caller of this function.
00547  *
00548  * \return returns the presence state value.
00549  */
00550 int ast_hint_presence_state(struct ast_channel *c, const char *context, const char *exten, char **subtype, char **message);
00551 
00552 /*!
00553  * \brief Return string representation of the state of an extension
00554  *
00555  * \param extension_state is the numerical state delivered by ast_extension_state
00556  *
00557  * \return the state of an extension as string
00558  */
00559 const char *ast_extension_state2str(int extension_state);
00560 
00561 /*!
00562  * \brief Registers a state change callback with destructor.
00563  * \since 1.8.9
00564  * \since 10.1.0
00565  *
00566  * \param context which context to look in
00567  * \param exten which extension to get state
00568  * \param change_cb callback to call if state changed
00569  * \param destroy_cb callback to call when registration destroyed.
00570  * \param data to pass to callback
00571  *
00572  * \note The change_cb is called if the state of an extension is changed.
00573  *
00574  * \note The destroy_cb is called when the registration is
00575  * deleted so the registerer can release any associated
00576  * resources.
00577  *
00578  * \retval -1 on failure
00579  * \retval ID on success
00580  */
00581 int ast_extension_state_add_destroy(const char *context, const char *exten,
00582    ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
00583 
00584 /*!
00585  * \brief Registers an extended state change callback with destructor.
00586  * \since 11
00587  *
00588  * \param context which context to look in
00589  * \param exten which extension to get state
00590  * \param change_cb callback to call if state changed
00591  * \param destroy_cb callback to call when registration destroyed.
00592  * \param data to pass to callback
00593  *
00594  * \note The change_cb is called if the state of an extension is changed.
00595  * The extended state is passed to the callback in the device_state_info
00596  * member of ast_state_cb_info.
00597  *
00598  * \note The destroy_cb is called when the registration is
00599  * deleted so the registerer can release any associated
00600  * resources.
00601  *
00602  * \retval -1 on failure
00603  * \retval ID on success
00604  */
00605 int ast_extension_state_add_destroy_extended(const char *context, const char *exten,
00606    ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
00607 
00608 /*!
00609  * \brief Registers a state change callback
00610  *
00611  * \param context which context to look in
00612  * \param exten which extension to get state
00613  * \param change_cb callback to call if state changed
00614  * \param data to pass to callback
00615  *
00616  * \note The change_cb is called if the state of an extension is changed.
00617  *
00618  * \retval -1 on failure
00619  * \retval ID on success
00620  */
00621 int ast_extension_state_add(const char *context, const char *exten,
00622    ast_state_cb_type change_cb, void *data);
00623 
00624 /*!
00625  * \brief Registers an extended state change callback
00626  * \since 11
00627  *
00628  * \param context which context to look in
00629  * \param exten which extension to get state
00630  * \param change_cb callback to call if state changed
00631  * \param data to pass to callback
00632  *
00633  * \note The change_cb is called if the state of an extension is changed.
00634  * The extended state is passed to the callback in the device_state_info
00635  * member of ast_state_cb_info.
00636  *
00637  * \retval -1 on failure
00638  * \retval ID on success
00639  */
00640 int ast_extension_state_add_extended(const char *context, const char *exten,
00641    ast_state_cb_type change_cb, void *data);
00642 
00643 /*!
00644  * \brief Deletes a registered state change callback by ID
00645  *
00646  * \param id of the registered state callback to delete
00647  * \param change_cb callback to call if state changed (Used if id == 0 (global))
00648  *
00649  * \retval 0 success
00650  * \retval -1 failure
00651  */
00652 int ast_extension_state_del(int id, ast_state_cb_type change_cb);
00653 
00654 /*!
00655  * \brief If an extension hint exists, return non-zero
00656  *
00657  * \param hint buffer for hint
00658  * \param hintsize size of hint buffer, in bytes
00659  * \param name buffer for name portion of hint
00660  * \param namesize size of name buffer
00661  * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
00662  * \param context which context to look in
00663  * \param exten which extension to search for
00664  *
00665  * \return If an extension within the given context with the priority PRIORITY_HINT
00666  * is found, a non zero value will be returned.
00667  * Otherwise, 0 is returned.
00668  */
00669 int ast_get_hint(char *hint, int hintsize, char *name, int namesize,
00670    struct ast_channel *c, const char *context, const char *exten);
00671 
00672 /*!
00673  * \brief If an extension hint exists, return non-zero
00674  *
00675  * \param hint buffer for hint
00676  * \param hintsize Maximum size of hint buffer (<0 to prevent growth, >0 to limit growth to that number of bytes, or 0 for unlimited growth)
00677  * \param name buffer for name portion of hint
00678  * \param namesize Maximum size of name buffer (<0 to prevent growth, >0 to limit growth to that number of bytes, or 0 for unlimited growth)
00679  * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
00680  * \param context which context to look in
00681  * \param exten which extension to search for
00682  *
00683  * \return If an extension within the given context with the priority PRIORITY_HINT
00684  * is found, a non zero value will be returned.
00685  * Otherwise, 0 is returned.
00686  */
00687 int ast_str_get_hint(struct ast_str **hint, ssize_t hintsize, struct ast_str **name, ssize_t namesize,
00688    struct ast_channel *c, const char *context, const char *exten);
00689 
00690 /*!
00691  * \brief Determine whether an extension exists
00692  *
00693  * \param c this is not important
00694  * \param context which context to look in
00695  * \param exten which extension to search for
00696  * \param priority priority of the action within the extension
00697  * \param callerid callerid to search for
00698  *
00699  * \note It is possible for autoservice to be started and stopped on c during this
00700  * function call, it is important that c is not locked prior to calling this. Otherwise
00701  * a deadlock may occur
00702  *
00703  * \return If an extension within the given context(or callerid) with the given priority
00704  *         is found a non zero value will be returned. Otherwise, 0 is returned.
00705  */
00706 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten,
00707    int priority, const char *callerid);
00708 
00709 /*!
00710  * \brief Find the priority of an extension that has the specified label
00711  *
00712  * \param c this is not important
00713  * \param context which context to look in
00714  * \param exten which extension to search for
00715  * \param label label of the action within the extension to match to priority
00716  * \param callerid callerid to search for
00717  *
00718  * \note It is possible for autoservice to be started and stopped on c during this
00719  * function call, it is important that c is not locked prior to calling this. Otherwise
00720  * a deadlock may occur
00721  *
00722  * \retval the priority which matches the given label in the extension
00723  * \retval -1 if not found.
00724  */
00725 int ast_findlabel_extension(struct ast_channel *c, const char *context,
00726    const char *exten, const char *label, const char *callerid);
00727 
00728 /*!
00729  * \brief Find the priority of an extension that has the specified label
00730  *
00731  * \note It is possible for autoservice to be started and stopped on c during this
00732  * function call, it is important that c is not locked prior to calling this. Otherwise
00733  * a deadlock may occur
00734  *
00735  * \note This function is the same as ast_findlabel_extension, except that it accepts
00736  * a pointer to an ast_context structure to specify the context instead of the
00737  * name of the context. Otherwise, the functions behave the same.
00738  */
00739 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con,
00740    const char *exten, const char *label, const char *callerid);
00741 
00742 /*!
00743  * \brief Looks for a valid matching extension
00744  *
00745  * \param c not really important
00746  * \param context context to serach within
00747  * \param exten extension to check
00748  * \param priority priority of extension path
00749  * \param callerid callerid of extension being searched for
00750  *
00751  * \note It is possible for autoservice to be started and stopped on c during this
00752  * function call, it is important that c is not locked prior to calling this. Otherwise
00753  * a deadlock may occur
00754  *
00755  * \return If "exten" *could be* a valid extension in this context with or without
00756  * some more digits, return non-zero.  Basically, when this returns 0, no matter
00757  * what you add to exten, it's not going to be a valid extension anymore
00758  */
00759 int ast_canmatch_extension(struct ast_channel *c, const char *context,
00760    const char *exten, int priority, const char *callerid);
00761 
00762 /*!
00763  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
00764  *
00765  * \param c not really important XXX
00766  * \param context context to serach within
00767  * \param exten extension to check
00768  * \param priority priority of extension path
00769  * \param callerid callerid of extension being searched for
00770  *
00771  * \note It is possible for autoservice to be started and stopped on c during this
00772  * function call, it is important that c is not locked prior to calling this. Otherwise
00773  * a deadlock may occur
00774  *
00775  * \return If "exten" *could match* a valid extension in this context with
00776  * some more digits, return non-zero.  Does NOT return non-zero if this is
00777  * an exact-match only.  Basically, when this returns 0, no matter
00778  * what you add to exten, it's not going to be a valid extension anymore
00779  */
00780 int ast_matchmore_extension(struct ast_channel *c, const char *context,
00781    const char *exten, int priority, const char *callerid);
00782 
00783 /*!
00784  * \brief Determine if a given extension matches a given pattern (in NXX format)
00785  *
00786  * \param pattern pattern to match
00787  * \param extension extension to check against the pattern.
00788  *
00789  * Checks whether or not the given extension matches the given pattern.
00790  *
00791  * \retval 1 on match
00792  * \retval 0 on failure
00793  */
00794 int ast_extension_match(const char *pattern, const char *extension);
00795 
00796 int ast_extension_close(const char *pattern, const char *data, int needmore);
00797 
00798 /*!
00799  * \brief Determine if one extension should match before another
00800  *
00801  * \param a extension to compare with b
00802  * \param b extension to compare with a
00803  *
00804  * Checks whether or extension a should match before extension b
00805  *
00806  * \retval 0 if the two extensions have equal matching priority
00807  * \retval 1 on a > b
00808  * \retval -1 on a < b
00809  */
00810 int ast_extension_cmp(const char *a, const char *b);
00811 
00812 /*!
00813  * \brief Launch a new extension (i.e. new stack)
00814  *
00815  * \param c not important
00816  * \param context which context to generate the extension within
00817  * \param exten new extension to add
00818  * \param priority priority of new extension
00819  * \param callerid callerid of extension
00820  * \param found
00821  * \param combined_find_spawn
00822  *
00823  * This adds a new extension to the asterisk extension list.
00824  *
00825  * \note It is possible for autoservice to be started and stopped on c during this
00826  * function call, it is important that c is not locked prior to calling this. Otherwise
00827  * a deadlock may occur
00828  *
00829  * \retval 0 on success
00830  * \retval -1 on failure.
00831  */
00832 int ast_spawn_extension(struct ast_channel *c, const char *context,
00833       const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn);
00834 
00835 /*!
00836  * \brief Add a context include
00837  *
00838  * \param context context to add include to
00839  * \param include new include to add
00840  * \param registrar who's registering it
00841  *
00842  * Adds an include taking a char * string as the context parameter
00843  *
00844  * \retval 0 on success
00845  * \retval -1 on error
00846 */
00847 int ast_context_add_include(const char *context, const char *include,
00848    const char *registrar);
00849 
00850 /*!
00851  * \brief Add a context include
00852  *
00853  * \param con context to add the include to
00854  * \param value include value to add
00855  * \param registrar who registered the context
00856  *
00857  * Adds an include taking a struct ast_context as the first parameter
00858  *
00859  * \retval 0 on success
00860  * \retval -1 on failure
00861  */
00862 int ast_context_add_include2(struct ast_context *con, const char *include,
00863    const char *registrar);
00864 
00865 /*!
00866  * \brief Remove a context include
00867  *
00868  * \note See ast_context_add_include for information on arguments
00869  *
00870  * \retval 0 on success
00871  * \retval -1 on failure
00872  */
00873 int ast_context_remove_include(const char *context, const char *include,
00874    const char *registrar);
00875 
00876 /*!
00877  * \brief Removes an include by an ast_context structure
00878  *
00879  * \note See ast_context_add_include2 for information on arguments
00880  *
00881  * \retval 0 on success
00882  * \retval -1 on success
00883  */
00884 int ast_context_remove_include2(struct ast_context *con, const char *include,
00885    const char *registrar);
00886 
00887 /*!
00888  * \brief Verifies includes in an ast_contect structure
00889  *
00890  * \param con context in which to verify the includes
00891  *
00892  * \retval 0 if no problems found
00893  * \retval -1 if there were any missing context
00894  */
00895 int ast_context_verify_includes(struct ast_context *con);
00896 
00897 /*!
00898  * \brief Add a switch
00899  *
00900  * \param context context to which to add the switch
00901  * \param sw switch to add
00902  * \param data data to pass to switch
00903  * \param eval whether to evaluate variables when running switch
00904  * \param registrar whoever registered the switch
00905  *
00906  * This function registers a switch with the asterisk switch architecture
00907  *
00908  * \retval 0 on success
00909  * \retval -1 on failure
00910  */
00911 int ast_context_add_switch(const char *context, const char *sw, const char *data,
00912    int eval, const char *registrar);
00913 
00914 /*!
00915  * \brief Adds a switch (first param is a ast_context)
00916  *
00917  * \note See ast_context_add_switch() for argument information, with the exception of
00918  *       the first argument. In this case, it's a pointer to an ast_context structure
00919  *       as opposed to the name.
00920  */
00921 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data,
00922    int eval, const char *registrar);
00923 
00924 /*!
00925  * \brief Remove a switch
00926  *
00927  * Removes a switch with the given parameters
00928  *
00929  * \retval 0 on success
00930  * \retval -1 on failure
00931  */
00932 int ast_context_remove_switch(const char *context, const char *sw,
00933    const char *data, const char *registrar);
00934 
00935 int ast_context_remove_switch2(struct ast_context *con, const char *sw,
00936    const char *data, const char *registrar);
00937 
00938 /*!
00939  * \brief Simply remove extension from context
00940  *
00941  * \param context context to remove extension from
00942  * \param extension which extension to remove
00943  * \param priority priority of extension to remove (0 to remove all)
00944  * \param registrar registrar of the extension
00945  *
00946  * This function removes an extension from a given context.
00947  *
00948  * \retval 0 on success
00949  * \retval -1 on failure
00950  *
00951  * @{
00952  */
00953 int ast_context_remove_extension(const char *context, const char *extension, int priority,
00954    const char *registrar);
00955 
00956 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
00957    int priority, const char *registrar, int already_locked);
00958 
00959 int ast_context_remove_extension_callerid(const char *context, const char *extension,
00960    int priority, const char *callerid, int matchcid, const char *registrar);
00961 
00962 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
00963    int priority, const char *callerid, int matchcid, const char *registrar,
00964    int already_locked);
00965 /*! @} */
00966 
00967 /*!
00968  * \brief Add an ignorepat
00969  *
00970  * \param context which context to add the ignorpattern to
00971  * \param ignorepat ignorepattern to set up for the extension
00972  * \param registrar registrar of the ignore pattern
00973  *
00974  * Adds an ignore pattern to a particular context.
00975  *
00976  * \retval 0 on success
00977  * \retval -1 on failure
00978  */
00979 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
00980 
00981 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
00982 
00983 /*
00984  * \brief Remove an ignorepat
00985  *
00986  * \param context context from which to remove the pattern
00987  * \param ignorepat the pattern to remove
00988  * \param registrar the registrar of the ignore pattern
00989  *
00990  * This removes the given ignorepattern
00991  *
00992  * \retval 0 on success
00993  * \retval -1 on failure
00994  */
00995 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
00996 
00997 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
00998 
00999 /*!
01000  * \brief Checks to see if a number should be ignored
01001  *
01002  * \param context context to search within
01003  * \param pattern to check whether it should be ignored or not
01004  *
01005  * Check if a number should be ignored with respect to dialtone cancellation.
01006  *
01007  * \retval 0 if the pattern should not be ignored
01008  * \retval non-zero if the pattern should be ignored
01009  */
01010 int ast_ignore_pattern(const char *context, const char *pattern);
01011 
01012 /* Locking functions for outer modules, especially for completion functions */
01013 
01014 /*!
01015  * \brief Write locks the context list
01016  *
01017  * \retval 0 on success
01018  * \retval -1 on error
01019  */
01020 int ast_wrlock_contexts(void);
01021 
01022 /*!
01023  * \brief Read locks the context list
01024  *
01025  * \retval 0 on success
01026  * \retval -1 on error
01027  */
01028 int ast_rdlock_contexts(void);
01029 
01030 /*!
01031  * \brief Unlocks contexts
01032  *
01033  * \retval 0 on success
01034  * \retval -1 on failure
01035  */
01036 int ast_unlock_contexts(void);
01037 
01038 /*!
01039  * \brief Write locks a given context
01040  *
01041  * \param con context to lock
01042  *
01043  * \retval 0 on success
01044  * \retval -1 on failure
01045  */
01046 int ast_wrlock_context(struct ast_context *con);
01047 
01048 /*!
01049  * \brief Read locks a given context
01050  *
01051  * \param con context to lock
01052  *
01053  * \retval 0 on success
01054  * \retval -1 on failure
01055  */
01056 int ast_rdlock_context(struct ast_context *con);
01057 
01058 /*!
01059  * \retval Unlocks the given context
01060  *
01061  * \param con context to unlock
01062  *
01063  * \retval 0 on success
01064  * \retval -1 on failure
01065  */
01066 int ast_unlock_context(struct ast_context *con);
01067 
01068 /*!
01069  * \brief locks the macrolock in the given given context
01070  *
01071  * \param macrocontext name of the macro-context to lock
01072  *
01073  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
01074  *
01075  * \retval 0 on success
01076  * \retval -1 on failure
01077  */
01078 int ast_context_lockmacro(const char *macrocontext);
01079 
01080 /*!
01081  * \brief Unlocks the macrolock in the given context
01082  *
01083  * \param macrocontext name of the macro-context to unlock
01084  *
01085  * Unlocks the given macro-context so that another thread (call) can execute it
01086  *
01087  * \retval 0 on success
01088  * \retval -1 on failure
01089  */
01090 int ast_context_unlockmacro(const char *macrocontext);
01091 
01092 /*!
01093  * \brief Set the channel to next execute the specified dialplan location.
01094  * \see ast_async_parseable_goto, ast_async_goto_if_exists
01095  *
01096  * \note Do _NOT_ hold any channel locks when calling this function.
01097  */
01098 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
01099 
01100 /*!
01101  * \brief Set the channel to next execute the specified dialplan location.
01102  */
01103 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
01104 
01105 /*!
01106  * \brief Synchronously or asynchronously make an outbound call and send it to a
01107  * particular extension
01108  *
01109  * \param type The channel technology to create
01110  * \param cap The format capabilities for the channel
01111  * \param addr Address data to pass to the channel technology driver
01112  * \param timeout How long we should attempt to dial the outbound channel
01113  * \param context The destination context for the outbound channel
01114  * \param exten The destination extension for the outbound channel
01115  * \param priority The destination priority for the outbound channel
01116  * \param reason Optional.  If provided, the dialed status of the outgoing channel.
01117  *        Codes are AST_CONTROL_xxx values.  Valid only if synchronous is non-zero.
01118  * \param synchronous If zero then don't wait for anything.
01119  *        If one then block until the outbound channel answers or the call fails.
01120  *        If greater than one then wait for the call to complete or if the call doesn't
01121  *        answer and failed@context exists then run a channel named OutgoingSpoolFailed
01122  *        at failed@context.
01123  * \param cid_num The caller ID number to set on the outbound channel
01124  * \param cid_name The caller ID name to set on the outbound channel
01125  * \param vars Variables to set on the outbound channel
01126  * \param account The accountcode for the outbound channel
01127  * \param locked_channel Optional.  The outbound channel that was created if success
01128  *        is returned.  Otherwise it is set to NULL.  This is returned both locked
01129  *        and reference bumped.
01130  * \param early_media If non-zero the channel "answers" when progress is indicated.
01131  * \param assignedids Optional. The uniqueid(s) to assign the channel(s) that are created.
01132  *
01133  * \retval 0 on success
01134  * \retval -1 on failure
01135  */
01136 int ast_pbx_outgoing_exten(const char *type, struct ast_format_cap *cap, const char *addr,
01137    int timeout, const char *context, const char *exten, int priority, int *reason,
01138    int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars,
01139    const char *account, struct ast_channel **locked_channel, int early_media,
01140    const struct ast_assigned_ids *assignedids);
01141 
01142 /*!
01143  * \brief Synchronously or asynchronously make an outbound call and execute an
01144  *  application on the channel.
01145  *
01146  * Note that when the application stops executing, the channel is hungup.
01147  *
01148  * \param type The channel technology to create
01149  * \param cap The format capabilities for the channel
01150  * \param addr Address data to pass to the channel technology driver
01151  * \param timeout How long we should attempt to dial the outbound channel
01152  * \param app The name of the application to execute
01153  * \param appdata Data to pass to the application
01154  * \param reason Optional.  If provided, the dialed status of the outgoing channel.
01155  *        Codes are AST_CONTROL_xxx values.  Valid only if synchronous is non-zero.
01156  * \param synchronous If zero then don't wait for anything.
01157  *        If one then block until the outbound channel answers or the call fails.
01158  *        If greater than one then wait for the call to complete.
01159  * \param cid_num The caller ID number to set on the outbound channel
01160  * \param cid_name The caller ID name to set on the outbound channel
01161  * \param vars Variables to set on the outbound channel
01162  * \param account The accountcode for the outbound channel
01163  * \param locked_channel Optional.  The outbound channel that was created if success
01164  *        is returned.  Otherwise it is set to NULL.  This is returned both locked
01165  *        and reference bumped.
01166  * \param assignedids Optional. The uniqueid(s) to assign the channel(s) that are created.
01167  *
01168  * \retval 0 on success
01169  * \retval -1 on failure
01170  */
01171 int ast_pbx_outgoing_app(const char *type, struct ast_format_cap *cap, const char *addr,
01172    int timeout, const char *app, const char *appdata, int *reason, int synchronous,
01173    const char *cid_num, const char *cid_name, struct ast_variable *vars,
01174    const char *account, struct ast_channel **locked_channel,
01175    const struct ast_assigned_ids *assignedids);
01176 
01177 /*!
01178  * \brief Evaluate a condition
01179  *
01180  * \retval 0 if the condition is NULL or of zero length
01181  * \retval int If the string is an integer, the integer representation of
01182  *             the integer is returned
01183  * \retval 1 Any other non-empty string
01184  */
01185 int pbx_checkcondition(const char *condition);
01186 
01187 /*! @name
01188  * Functions for returning values from structures */
01189 /*! @{ */
01190 const char *ast_get_context_name(struct ast_context *con);
01191 const char *ast_get_extension_name(struct ast_exten *exten);
01192 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
01193 const char *ast_get_include_name(struct ast_include *include);
01194 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
01195 const char *ast_get_switch_name(struct ast_sw *sw);
01196 const char *ast_get_switch_data(struct ast_sw *sw);
01197 int ast_get_switch_eval(struct ast_sw *sw);
01198 
01199 /*! @} */
01200 
01201 /*! @name Other Extension stuff */
01202 /*! @{ */
01203 int ast_get_extension_priority(struct ast_exten *exten);
01204 int ast_get_extension_matchcid(struct ast_exten *e);
01205 const char *ast_get_extension_cidmatch(struct ast_exten *e);
01206 const char *ast_get_extension_app(struct ast_exten *e);
01207 const char *ast_get_extension_label(struct ast_exten *e);
01208 void *ast_get_extension_app_data(struct ast_exten *e);
01209 /*! @} */
01210 
01211 /*! @name Registrar info functions ... */
01212 /*! @{ */
01213 const char *ast_get_context_registrar(struct ast_context *c);
01214 const char *ast_get_extension_registrar(struct ast_exten *e);
01215 const char *ast_get_include_registrar(struct ast_include *i);
01216 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
01217 const char *ast_get_switch_registrar(struct ast_sw *sw);
01218 /*! @} */
01219 
01220 /*! @name Walking functions ... */
01221 /*! @{ */
01222 struct ast_context *ast_walk_contexts(struct ast_context *con);
01223 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
01224    struct ast_exten *priority);
01225 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
01226    struct ast_exten *priority);
01227 struct ast_include *ast_walk_context_includes(struct ast_context *con,
01228    struct ast_include *inc);
01229 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
01230    struct ast_ignorepat *ip);
01231 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
01232 /*! @} */
01233 
01234 /*!
01235  * \brief Create a human-readable string, specifying all variables and their corresponding values.
01236  * \param chan Channel from which to read variables
01237  * \param buf Dynamic string in which to place the result (should be allocated with ast_str_create).
01238  * \see ast_str_create
01239  * \note Will lock the channel.
01240  */
01241 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
01242 
01243 /*!
01244  * \brief Return a pointer to the value of the corresponding channel variable.
01245  * \note Will lock the channel.
01246  *
01247  * \note This function will return a pointer to the buffer inside the channel
01248  * variable.  This value should only be accessed with the channel locked.  If
01249  * the value needs to be kept around, it should be done by using the following
01250  * thread-safe code:
01251  * \code
01252  *    const char *var;
01253  *
01254  *    ast_channel_lock(chan);
01255  *    if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
01256  *       var = ast_strdupa(var);
01257  *    }
01258  *    ast_channel_unlock(chan);
01259  * \endcode
01260  */
01261 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
01262 
01263 /*!
01264  * \brief Add a variable to the channel variable stack, without removing any previously set value.
01265  * \note Will lock the channel.
01266  */
01267 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
01268 
01269 /*!
01270  * \brief Add a variable to the channel variable stack, removing the most recently set value for the same name.
01271  * \note Will lock the channel.  May also be used to set a channel dialplan function to a particular value.
01272  * \see ast_func_write
01273  * \return -1 if the dialplan function fails to be set
01274  * \version 1.8 changed the function to return an error code
01275  */
01276 int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
01277 
01278 /*!
01279  * \brief Retrieve the value of a builtin variable or variable from the channel variable stack.
01280  * \note Will lock the channel.
01281  */
01282 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
01283 void pbx_builtin_clear_globals(void);
01284 
01285 /*!
01286  * \brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
01287  * \note Will lock the channel.
01288  */
01289 int pbx_builtin_setvar(struct ast_channel *chan, const char *data);
01290 
01291 /*!
01292  * \brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
01293  * \note Will lock the channel.
01294  */
01295 int pbx_builtin_setvar_multiple(struct ast_channel *chan, const char *data);
01296 
01297 int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data);
01298 
01299 /*! @name Substitution routines, using static string buffers
01300  * @{ */
01301 void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count);
01302 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
01303 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
01304 /*! @} */
01305 /*! @} */
01306 
01307 /*! @name Substitution routines, using dynamic string buffers */
01308 
01309 /*!
01310  * \param buf Result will be placed in this buffer.
01311  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
01312  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
01313  * \param headp If no channel is specified, a channel list from which to extract variable values
01314  * \param var Variable name to retrieve.
01315  */
01316 const char *ast_str_retrieve_variable(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, struct varshead *headp, const char *var);
01317 
01318 /*!
01319  * \param buf Result will be placed in this buffer.
01320  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
01321  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
01322  * \param templ Variable template to expand.
01323  */
01324 void ast_str_substitute_variables(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, const char *templ);
01325 
01326 /*!
01327  * \param buf Result will be placed in this buffer.
01328  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
01329  * \param headp If no channel is specified, a channel list from which to extract variable values
01330  * \param templ Variable template to expand.
01331  */
01332 void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen, struct varshead *headp, const char *templ);
01333 
01334 /*!
01335  * \param buf Result will be placed in this buffer.
01336  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
01337  * \param c Channel variables from which to extract values, and channel to pass to any dialplan functions.
01338  * \param headp If no channel is specified, a channel list from which to extract variable values
01339  * \param templ Variable template to expand.
01340  * \param used Number of bytes read from the template.
01341  */
01342 void ast_str_substitute_variables_full(struct ast_str **buf, ssize_t maxlen, struct ast_channel *c, struct varshead *headp, const char *templ, size_t *used);
01343 /*! @} */
01344 
01345 int ast_extension_patmatch(const char *pattern, const char *data);
01346 
01347 /*! Set "autofallthrough" flag, if newval is <0, does not actually set.  If
01348   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
01349   fall through (reads extension instead).  Returns previous value. */
01350 int pbx_set_autofallthrough(int newval);
01351 
01352 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not actually set.  If
01353   set to 1, sets to use the new Trie-based pattern matcher.  If newval set to 0, sets to use
01354   the old linear-search algorithm.  Returns previous value. */
01355 int pbx_set_extenpatternmatchnew(int newval);
01356 
01357 /*! Set "overrideswitch" field.  If set and of nonzero length, all contexts
01358  * will be tried directly through the named switch prior to any other
01359  * matching within that context.
01360  * \since 1.6.1
01361  */
01362 void pbx_set_overrideswitch(const char *newval);
01363 
01364 /*!
01365  * \note This function will handle locking the channel as needed.
01366  */
01367 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
01368 
01369 /*!
01370  * \note This function will handle locking the channel as needed.
01371  */
01372 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
01373 
01374 /*!
01375  * \note This function will handle locking the channel as needed.
01376  */
01377 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string);
01378 
01379 /*!
01380  * \note This function will handle locking the channel as needed.
01381  */
01382 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
01383 
01384 /*!
01385  * \note This function will handle locking the channel as needed.
01386  */
01387 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
01388 
01389 struct ast_custom_function* ast_custom_function_find(const char *name);
01390 
01391 /*!
01392  * \brief Unregister a custom function
01393  */
01394 int ast_custom_function_unregister(struct ast_custom_function *acf);
01395 
01396 /*!
01397  * \brief Description of the ways in which a function may escalate privileges.
01398  */
01399 enum ast_custom_function_escalation {
01400    AST_CFE_NONE,
01401    AST_CFE_READ,
01402    AST_CFE_WRITE,
01403    AST_CFE_BOTH,
01404 };
01405 
01406 /*!
01407  * \brief Register a custom function
01408  */
01409 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, ast_module_info->self)
01410 
01411 /*!
01412  * \brief Register a custom function which requires escalated privileges.
01413  *
01414  * Examples would be SHELL() (for which a read needs permission to execute
01415  * arbitrary code) or FILE() (for which write needs permission to change files
01416  * on the filesystem).
01417  */
01418 #define ast_custom_function_register_escalating(acf, escalation) __ast_custom_function_register_escalating(acf, escalation, ast_module_info->self)
01419 
01420 /*!
01421  * \brief Register a custom function
01422  */
01423 int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod);
01424 
01425 /*!
01426  * \brief Register a custom function which requires escalated privileges.
01427  *
01428  * Examples would be SHELL() (for which a read needs permission to execute
01429  * arbitrary code) or FILE() (for which write needs permission to change files
01430  * on the filesystem).
01431  */
01432 int __ast_custom_function_register_escalating(struct ast_custom_function *acf, enum ast_custom_function_escalation escalation, struct ast_module *mod);
01433 
01434 /*!
01435  * \brief Retrieve the number of active calls
01436  */
01437 int ast_active_calls(void);
01438 
01439 /*!
01440  * \brief Retrieve the total number of calls processed through the PBX since last restart
01441  */
01442 int ast_processed_calls(void);
01443 
01444 /*!
01445  * \brief executes a read operation on a function
01446  *
01447  * \param chan Channel to execute on
01448  * \param function Data containing the function call string (will be modified)
01449  * \param workspace A pointer to safe memory to use for a return value
01450  * \param len the number of bytes in workspace
01451  *
01452  * This application executes a function in read mode on a given channel.
01453  *
01454  * \retval 0 success
01455  * \retval non-zero failure
01456  */
01457 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
01458 
01459 /*!
01460  * \brief executes a read operation on a function
01461  *
01462  * \param chan Channel to execute on
01463  * \param function Data containing the function call string (will be modified)
01464  * \param str A dynamic string buffer into which to place the result.
01465  * \param maxlen <0 if the dynamic buffer should not grow; >0 if the dynamic buffer should be limited to that number of bytes; 0 if the dynamic buffer has no upper limit
01466  *
01467  * This application executes a function in read mode on a given channel.
01468  *
01469  * \retval 0 success
01470  * \retval non-zero failure
01471  */
01472 int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, ssize_t maxlen);
01473 
01474 /*!
01475  * \brief executes a write operation on a function
01476  *
01477  * \param chan Channel to execute on
01478  * \param function Data containing the function call string (will be modified)
01479  * \param value A value parameter to pass for writing
01480  *
01481  * This application executes a function in write mode on a given channel.
01482  *
01483  * \retval 0 success
01484  * \retval non-zero failure
01485  */
01486 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
01487 
01488 /*!
01489  * \details
01490  * When looking up extensions, we can have different requests
01491  * identified by the 'action' argument, as follows.
01492  *
01493  * \note that the coding is such that the low 4 bits are the
01494  * third argument to extension_match_core.
01495  */
01496 enum ext_match_t {
01497    E_MATCHMORE =  0x00, /* extension can match but only with more 'digits' */
01498    E_CANMATCH =   0x01, /* extension can match with or without more 'digits' */
01499    E_MATCH =   0x02, /* extension is an exact match */
01500    E_MATCH_MASK = 0x03, /* mask for the argument to extension_match_core() */
01501    E_SPAWN =   0x12, /* want to spawn an extension. Requires exact match */
01502    E_FINDLABEL =  0x22  /* returns the priority for a given label. Requires exact match */
01503 };
01504 
01505 #define STATUS_NO_CONTEXT  1
01506 #define STATUS_NO_EXTENSION   2
01507 #define STATUS_NO_PRIORITY 3
01508 #define STATUS_NO_LABEL    4
01509 #define STATUS_SUCCESS     5
01510 #define AST_PBX_MAX_STACK  128
01511 
01512 /* request and result for pbx_find_extension */
01513 struct pbx_find_info {
01514 #if 0
01515    const char *context;
01516    const char *exten;
01517    int priority;
01518 #endif
01519 
01520    char *incstack[AST_PBX_MAX_STACK];      /* filled during the search */
01521    int stacklen;                   /* modified during the search */
01522    int status;                     /* set on return */
01523    struct ast_switch *swo;         /* set on return */
01524    const char *data;               /* set on return */
01525    const char *foundcontext;       /* set on return */
01526 };
01527 
01528 struct ast_exten *pbx_find_extension(struct ast_channel *chan,
01529                             struct ast_context *bypass, struct pbx_find_info *q,
01530                             const char *context, const char *exten, int priority,
01531                             const char *label, const char *callerid, enum ext_match_t action);
01532 
01533 /*! \brief hashtable functions for contexts */
01534 /*! @{ */
01535 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
01536 unsigned int ast_hashtab_hash_contexts(const void *obj);
01537 /*! @} */
01538 
01539 /*!
01540  * \brief Command completion for the list of installed applications.
01541  *
01542  * This can be called from a CLI command completion function that wants to
01543  * complete from the list of available applications.
01544  */
01545 char *ast_complete_applications(const char *line, const char *word, int state);
01546 
01547 /*!
01548  * \brief Enable/disable the execution of 'dangerous' functions from external
01549  * protocols (AMI, etc.).
01550  *
01551  * These dialplan functions (such as \c SHELL) provide an opportunity for
01552  * privilege escalation. They are okay to invoke from the dialplan, but external
01553  * protocols with permission controls should not normally invoke them.
01554  *
01555  * This function can globally enable/disable the execution of dangerous
01556  * functions from external protocols.
01557  *
01558  * \param new_live_dangerously If true, enable the execution of escalating
01559  * functions from external protocols.
01560  */
01561 void pbx_live_dangerously(int new_live_dangerously);
01562 
01563 /*!
01564  * \brief Inhibit (in the current thread) the execution of dialplan functions
01565  * which cause privilege escalations. If pbx_live_dangerously() has been
01566  * called, this function has no effect.
01567  *
01568  * \return 0 if successfuly marked current thread.
01569  * \return Non-zero if marking current thread failed.
01570  */
01571 int ast_thread_inhibit_escalations(void);
01572 
01573 #if defined(__cplusplus) || defined(c_plusplus)
01574 }
01575 #endif
01576 
01577 #endif /* _ASTERISK_PBX_H */

Generated on Thu Apr 16 06:27:42 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6