Mon Jun 27 16:50:55 2011

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

Generated on Mon Jun 27 16:50:55 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7