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

Generated on Thu Jul 9 13:40:38 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7