Thu Sep 7 01:03:02 2017

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

Generated on 7 Sep 2017 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1