Wed Oct 28 11:45:40 2009

Asterisk developer's documentation


pbx.h

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

Generated on Wed Oct 28 11:45:40 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6