Mon Mar 31 07:38:03 2008

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/channel.h"
00028 #include "asterisk/linkedlists.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_KEEPALIVE  10 /*!< Destroy the thread, but don't hang up the channel */
00041 #define AST_PBX_NO_HANGUP_PEER   11
00042 /*! } */
00043 
00044 #define PRIORITY_HINT   -1 /*!< Special Priority for a hint */
00045 
00046 /*! \brief Extension states 
00047    \note States can be combined 
00048    - \ref AstExtState
00049 */
00050 enum ast_extension_states {
00051    AST_EXTENSION_REMOVED = -2,   /*!< Extension removed */
00052    AST_EXTENSION_DEACTIVATED = -1,  /*!< Extension hint removed */
00053    AST_EXTENSION_NOT_INUSE = 0,  /*!< No device INUSE or BUSY  */
00054    AST_EXTENSION_INUSE = 1 << 0, /*!< One or more devices INUSE */
00055    AST_EXTENSION_BUSY = 1 << 1,  /*!< All devices BUSY */
00056    AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
00057    AST_EXTENSION_RINGING = 1 << 3,  /*!< All devices RINGING */
00058    AST_EXTENSION_ONHOLD = 1 << 4,   /*!< All devices ONHOLD */
00059 };
00060 
00061 
00062 struct ast_context;
00063 struct ast_exten;     
00064 struct ast_include;
00065 struct ast_ignorepat;
00066 struct ast_sw;
00067 
00068 /*! \brief Typedef for devicestate and hint callbacks */
00069 typedef int (*ast_state_cb_type)(char *context, char* id, enum ast_extension_states state, void *data);
00070 
00071 /*! \brief Data structure associated with a custom dialplan function */
00072 struct ast_custom_function {
00073    const char *name;    /*!< Name */
00074    const char *synopsis;      /*!< Short description for "show functions" */
00075    const char *desc;    /*!< Help text that explains it all */
00076    const char *syntax;     /*!< Syntax description */
00077    int (*read)(struct ast_channel *, char *, char *, char *, size_t);   /*!< Read function, if read is supported */
00078    int (*write)(struct ast_channel *, char *, char *, const char *); /*!< Write function, if write is supported */
00079    AST_LIST_ENTRY(ast_custom_function) acflist;
00080 };
00081 
00082 /*! \brief All switch functions have the same interface, so define a type for them */
00083 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
00084    const char *exten, int priority, const char *callerid, const char *data);
00085 
00086 /*!< Data structure associated with an Asterisk switch */
00087 struct ast_switch {
00088    AST_LIST_ENTRY(ast_switch) list;
00089    const char *name;       /*!< Name of the switch */
00090    const char *description;      /*!< Description of the switch */
00091    
00092    ast_switch_f *exists;
00093    ast_switch_f *canmatch;
00094    ast_switch_f *exec;
00095    ast_switch_f *matchmore;
00096 };
00097 
00098 struct ast_timing {
00099    int hastime;            /*!< If time construct exists */
00100    unsigned int monthmask;       /*!< Mask for month */
00101    unsigned int daymask;         /*!< Mask for date */
00102    unsigned int dowmask;         /*!< Mask for day of week (mon-sun) */
00103    unsigned int minmask[24];     /*!< Mask for minute */
00104 };
00105 
00106 int ast_build_timing(struct ast_timing *i, const char *info);
00107 int ast_check_timing(const struct ast_timing *i);
00108 
00109 struct ast_pbx {
00110    int dtimeout;           /*!< Timeout between digits (seconds) */
00111    int rtimeout;           /*!< Timeout for response (seconds) */
00112 };
00113 
00114 
00115 /*!
00116  * \brief Register an alternative dialplan switch
00117  *
00118  * \param sw switch to register
00119  *
00120  * This function registers a populated ast_switch structure with the
00121  * asterisk switching architecture.
00122  *
00123  * \return 0 on success, and other than 0 on failure
00124  */
00125 int ast_register_switch(struct ast_switch *sw);
00126 
00127 /*!
00128  * \brief Unregister an alternative switch
00129  *
00130  * \param sw switch to unregister
00131  * 
00132  * Unregisters a switch from asterisk.
00133  *
00134  * \return nothing
00135  */
00136 void ast_unregister_switch(struct ast_switch *sw);
00137 
00138 /*!
00139  * \brief Look up an application
00140  *
00141  * \param app name of the app
00142  *
00143  * This function searches for the ast_app structure within
00144  * the apps that are registered for the one with the name
00145  * you passed in.
00146  *
00147  * \return the ast_app structure that matches on success, or NULL on failure
00148  */
00149 struct ast_app *pbx_findapp(const char *app);
00150 
00151 /*!
00152  * \brief Execute an application
00153  *
00154  * \param c channel to execute on
00155  * \param app which app to execute
00156  * \param data the data passed into the app
00157  *
00158  * This application executes an application on a given channel.  It
00159  * saves the stack and executes the given appliation passing in
00160  * the given data.
00161  *
00162  * \return 0 on success, and -1 on failure
00163  */
00164 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data);
00165 
00166 /*!
00167  * \brief Register a new context
00168  *
00169  * \param extcontexts pointer to the ast_context structure pointer
00170  * \param name name of the new context
00171  * \param registrar registrar of the context
00172  *
00173  * This will first search for a context with your name.  If it exists already, it will not
00174  * create a new one.  If it does not exist, it will create a new one with the given name
00175  * and registrar.
00176  *
00177  * \return NULL on failure, and an ast_context structure on success
00178  */
00179 struct ast_context *ast_context_create(struct ast_context **extcontexts, const char *name, const char *registrar);
00180 
00181 /*!
00182  * \brief Register a new context or find an existing one
00183  *
00184  * \param extcontexts pointer to the ast_context structure pointer
00185  * \param name name of the new context
00186  * \param registrar registrar of the context
00187  *
00188  * This will first search for a context with your name.  If it exists already, it will not
00189  * create a new one.  If it does not exist, it will create a new one with the given name
00190  * and registrar.
00191  *
00192  * \return NULL on failure, and an ast_context structure on success
00193  */
00194 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, const char *name, const char *registrar);
00195 
00196 /*!
00197  * \brief Merge the temporary contexts into a global contexts list and delete from the 
00198  *        global list the ones that are being added
00199  *
00200  * \param extcontexts pointer to the ast_context structure pointer
00201  * \param registrar of the context; if it's set the routine will delete all contexts 
00202  *        that belong to that registrar; if NULL only the contexts that are specified 
00203  *        in extcontexts
00204  */
00205 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, const char *registrar);
00206 
00207 /*!
00208  * \brief Destroy a context (matches the specified context (or ANY context if NULL)
00209  *
00210  * \param con context to destroy
00211  * \param registrar who registered it
00212  *
00213  * You can optionally leave out either parameter.  It will find it
00214  * based on either the ast_context or the registrar name.
00215  *
00216  * \return nothing
00217  */
00218 void ast_context_destroy(struct ast_context *con, const char *registrar);
00219 
00220 /*!
00221  * \brief Find a context
00222  *
00223  * \param name name of the context to find
00224  *
00225  * Will search for the context with the given name.
00226  *
00227  * \return the ast_context on success, NULL on failure.
00228  */
00229 struct ast_context *ast_context_find(const char *name);
00230 
00231 /*! \brief The result codes when starting the PBX on a channel
00232    with \ref ast_pbx_start()
00233 
00234    AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
00235  */
00236 enum ast_pbx_result {
00237    AST_PBX_SUCCESS = 0,
00238    AST_PBX_FAILED = -1,
00239    AST_PBX_CALL_LIMIT = -2,
00240 };
00241 
00242 /*!
00243  * \brief Create a new thread and start the PBX
00244  *
00245  * \param c channel to start the pbx on
00246  *
00247  * See ast_pbx_run for a synchronous function to run the PBX in the
00248  * current thread, as opposed to starting a new one.
00249  *
00250  * \return Zero on success, non-zero on failure
00251  */
00252 enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
00253 
00254 /*!
00255  * \brief Execute the PBX in the current thread
00256  *
00257  * \param c channel to run the pbx on
00258  *
00259  * This executes the PBX on a given channel. It allocates a new
00260  * PBX structure for the channel, and provides all PBX functionality.
00261  * See ast_pbx_start for an asynchronous function to run the PBX in a
00262  * new thread as opposed to the current one.
00263  * 
00264  * \return Zero on success, non-zero on failure
00265  */
00266 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
00267 
00268 /*! 
00269  * \brief Add and extension to an extension context.  
00270  * 
00271  * \param context context to add the extension to
00272  * \param replace
00273  * \param extension extension to add
00274  * \param priority priority level of extension addition
00275  * \param label extension label
00276  * \param callerid pattern to match CallerID, or NULL to match any CallerID
00277  * \param application application to run on the extension with that priority level
00278  * \param data data to pass to the application
00279  * \param datad
00280  * \param registrar who registered the extension
00281  *
00282  * \retval 0 success 
00283  * \retval -1 failure
00284  */
00285 int ast_add_extension(const char *context, int replace, const char *extension, 
00286    int priority, const char *label, const char *callerid,
00287    const char *application, void *data, void (*datad)(void *), const char *registrar);
00288 
00289 /*! 
00290  * \brief Add an extension to an extension context, this time with an ast_context *.
00291  *
00292  * \note For details about the arguments, check ast_add_extension()
00293  */
00294 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
00295    int priority, const char *label, const char *callerid, 
00296    const char *application, void *data, void (*datad)(void *), const char *registrar);
00297 
00298 
00299 /*! 
00300  * \brief Register an application.
00301  *
00302  * \param app Short name of the application
00303  * \param execute a function callback to execute the application. It should return
00304  *                non-zero if the channel needs to be hung up.
00305  * \param synopsis a short description (one line synopsis) of the application
00306  * \param description long description with all of the details about the use of 
00307  *                    the application
00308  * 
00309  * This registers an application with Asterisk's internal application list. 
00310  * \note The individual applications themselves are responsible for registering and unregistering
00311  *       and unregistering their own CLI commands.
00312  * 
00313  * \retval 0 success 
00314  * \retval -1 failure.
00315  */
00316 int ast_register_application(const char *app, int (*execute)(struct ast_channel *, void *),
00317               const char *synopsis, const char *description);
00318 
00319 /*! 
00320  * \brief Unregister an application
00321  * 
00322  * \param app name of the application (does not have to be the same string as the one that was registered)
00323  * 
00324  * This unregisters an application from Asterisk's internal application list.
00325  * 
00326  * \retval 0 success 
00327  * \retval -1 failure
00328  */
00329 int ast_unregister_application(const char *app);
00330 
00331 /*! 
00332  * \brief Uses hint and devicestate callback to get the state of an extension
00333  *
00334  * \param c this is not important
00335  * \param context which context to look in
00336  * \param exten which extension to get state
00337  *
00338  * \return extension state as defined in the ast_extension_states enum
00339  */
00340 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
00341 
00342 /*! 
00343  * \brief Return string representation of the state of an extension
00344  * 
00345  * \param extension_state is the numerical state delivered by ast_extension_state
00346  *
00347  * \return the state of an extension as string
00348  */
00349 const char *ast_extension_state2str(int extension_state);
00350 
00351 /*!
00352  * \brief Registers a state change callback
00353  * 
00354  * \param context which context to look in
00355  * \param exten which extension to get state
00356  * \param callback callback to call if state changed
00357  * \param data to pass to callback
00358  *
00359  * The callback is called if the state of an extension is changed.
00360  *
00361  * \retval -1 on failure
00362  * \retval ID on success
00363  */ 
00364 int ast_extension_state_add(const char *context, const char *exten, 
00365              ast_state_cb_type callback, void *data);
00366 
00367 /*! 
00368  * \brief Deletes a registered state change callback by ID
00369  * 
00370  * \param id of the callback to delete
00371  * \param callback callback
00372  *
00373  * Removes the callback from list of callbacks
00374  *
00375  * \retval 0 success 
00376  * \retval -1 failure
00377  */
00378 int ast_extension_state_del(int id, ast_state_cb_type callback);
00379 
00380 /*! 
00381  * \brief If an extension hint exists, return non-zero
00382  * 
00383  * \param hint buffer for hint
00384  * \param maxlen size of hint buffer
00385  * \param name buffer for name portion of hint
00386  * \param maxnamelen size of name buffer
00387  * \param c this is not important
00388  * \param context which context to look in
00389  * \param exten which extension to search for
00390  *
00391  * \return If an extension within the given context with the priority PRIORITY_HINT
00392  * is found a non zero value will be returned.
00393  * Otherwise, 0 is returned.
00394  */
00395 int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, 
00396    struct ast_channel *c, const char *context, const char *exten);
00397 
00398 /*!
00399  * \brief Determine whether an extension exists
00400  *
00401  * \param c this is not important
00402  * \param context which context to look in
00403  * \param exten which extension to search for
00404  * \param priority priority of the action within the extension
00405  * \param callerid callerid to search for
00406  *
00407  * \return If an extension within the given context(or callerid) with the given priority 
00408  *         is found a non zero value will be returned. Otherwise, 0 is returned.
00409  */
00410 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, 
00411    int priority, const char *callerid);
00412 
00413 /*! 
00414  * \brief Find the priority of an extension that has the specified label
00415  * 
00416  * \param c this is not important
00417  * \param context which context to look in
00418  * \param exten which extension to search for
00419  * \param label label of the action within the extension to match to priority
00420  * \param callerid callerid to search for
00421  *
00422  * \return the priority which matches the given label in the extension or -1 if not found.
00423  */
00424 int ast_findlabel_extension(struct ast_channel *c, const char *context, 
00425    const char *exten, const char *label, const char *callerid);
00426 
00427 /*!
00428  * \brief Find the priority of an extension that has the specified label
00429  *
00430  * \note This function is the same as ast_findlabel_extension, except that it accepts
00431  * a pointer to an ast_context structure to specify the context instead of the
00432  * name of the context. Otherwise, the functions behave the same.
00433  */
00434 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, 
00435    const char *exten, const char *label, const char *callerid);
00436 
00437 /*! 
00438  * \brief Looks for a valid matching extension
00439  * 
00440  * \param c not really important
00441  * \param context context to serach within
00442  * \param exten extension to check
00443  * \param priority priority of extension path
00444  * \param callerid callerid of extension being searched for
00445  *
00446  * \return If "exten" *could be* a valid extension in this context with or without
00447  * some more digits, return non-zero.  Basically, when this returns 0, no matter
00448  * what you add to exten, it's not going to be a valid extension anymore
00449  */
00450 int ast_canmatch_extension(struct ast_channel *c, const char *context, 
00451    const char *exten, int priority, const char *callerid);
00452 
00453 /*! 
00454  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
00455  *
00456  * \param c not really important XXX
00457  * \param context context to serach within
00458  * \param exten extension to check
00459  * \param priority priority of extension path
00460  * \param callerid callerid of extension being searched for
00461  *
00462  * \return If "exten" *could match* a valid extension in this context with
00463  * some more digits, return non-zero.  Does NOT return non-zero if this is
00464  * an exact-match only.  Basically, when this returns 0, no matter
00465  * what you add to exten, it's not going to be a valid extension anymore
00466  */
00467 int ast_matchmore_extension(struct ast_channel *c, const char *context, 
00468    const char *exten, int priority, const char *callerid);
00469 
00470 /*! 
00471  * \brief Determine if a given extension matches a given pattern (in NXX format)
00472  * 
00473  * \param pattern pattern to match
00474  * \param extension extension to check against the pattern.
00475  *
00476  * Checks whether or not the given extension matches the given pattern.
00477  *
00478  * \retval 1 on match
00479  * \retval 0 on failure
00480  */
00481 int ast_extension_match(const char *pattern, const char *extension);
00482 
00483 int ast_extension_close(const char *pattern, const char *data, int needmore);
00484 
00485 /*! 
00486  * \brief Launch a new extension (i.e. new stack)
00487  * 
00488  * \param c not important
00489  * \param context which context to generate the extension within
00490  * \param exten new extension to add
00491  * \param priority priority of new extension
00492  * \param callerid callerid of extension
00493  *
00494  * This adds a new extension to the asterisk extension list.
00495  *
00496  * \retval 0 on success 
00497  * \retval -1 on failure.
00498  */
00499 int ast_spawn_extension(struct ast_channel *c, const char *context, 
00500    const char *exten, int priority, const char *callerid);
00501 
00502 /*! 
00503  * \brief Add a context include
00504  *
00505  * \param context context to add include to
00506  * \param include new include to add
00507  * \param registrar who's registering it
00508  *
00509  * Adds an include taking a char * string as the context parameter
00510  *
00511  * \retval 0 on success 
00512  * \retval -1 on error
00513 */
00514 int ast_context_add_include(const char *context, const char *include, 
00515    const char *registrar);
00516 
00517 /*! 
00518  * \brief Add a context include
00519  * 
00520  * \param con context to add the include to
00521  * \param include include to add
00522  * \param registrar who registered the context
00523  *
00524  * Adds an include taking a struct ast_context as the first parameter
00525  *
00526  * \retval 0 on success 
00527  * \retval -1 on failure
00528  */
00529 int ast_context_add_include2(struct ast_context *con, const char *include, 
00530    const char *registrar);
00531 
00532 /*! 
00533  * \brief Remove a context include
00534  * 
00535  * \note See ast_context_add_include for information on arguments
00536  *
00537  * \retval 0 on success
00538  * \retval -1 on failure
00539  */
00540 int ast_context_remove_include(const char *context, const char *include, 
00541    const char *registrar);
00542 
00543 /*! 
00544  * \brief Removes an include by an ast_context structure 
00545  * 
00546  * \note See ast_context_add_include2 for information on arguments
00547  *
00548  * \retval 0 on success
00549  * \retval -1 on success
00550  */
00551 int ast_context_remove_include2(struct ast_context *con, const char *include, 
00552    const char *registrar);
00553 
00554 /*! 
00555  * \brief Verifies includes in an ast_contect structure
00556  * 
00557  * \param con context in which to verify the includes
00558  *
00559  * \retval 0 if no problems found 
00560  * \retval -1 if there were any missing context
00561  */
00562 int ast_context_verify_includes(struct ast_context *con);
00563      
00564 /*! 
00565  * \brief Add a switch
00566  * 
00567  * \param context context to which to add the switch
00568  * \param sw switch to add
00569  * \param data data to pass to switch
00570  * \param eval whether to evaluate variables when running switch
00571  * \param registrar whoever registered the switch
00572  *
00573  * This function registers a switch with the asterisk switch architecture
00574  *
00575  * \retval 0 on success 
00576  * \retval -1 on failure
00577  */
00578 int ast_context_add_switch(const char *context, const char *sw, const char *data, 
00579    int eval, const char *registrar);
00580 
00581 /*! 
00582  * \brief Adds a switch (first param is a ast_context)
00583  * 
00584  * \note See ast_context_add_switch() for argument information, with the exception of
00585  *       the first argument. In this case, it's a pointer to an ast_context structure
00586  *       as opposed to the name.
00587  */
00588 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, 
00589    int eval, const char *registrar);
00590 
00591 /*! 
00592  * \brief Remove a switch
00593  * 
00594  * Removes a switch with the given parameters
00595  *
00596  * \retval 0 on success 
00597  * \retval -1 on failure
00598  */
00599 int ast_context_remove_switch(const char *context, const char *sw, 
00600    const char *data, const char *registrar);
00601 
00602 int ast_context_remove_switch2(struct ast_context *con, const char *sw, 
00603    const char *data, const char *registrar);
00604 
00605 /*! 
00606  * \brief Simply remove extension from context
00607  * 
00608  * \param context context to remove extension from
00609  * \param extension which extension to remove
00610  * \param priority priority of extension to remove
00611  * \param registrar registrar of the extension
00612  *
00613  * This function removes an extension from a given context.
00614  *
00615  * \retval 0 on success 
00616  * \retval -1 on failure
00617  */
00618 int ast_context_remove_extension(const char *context, const char *extension, int priority,
00619    const char *registrar);
00620 
00621 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
00622    int priority, const char *registrar);
00623 
00624 /*! 
00625  * \brief Add an ignorepat
00626  * 
00627  * \param context which context to add the ignorpattern to
00628  * \param ignorepat ignorepattern to set up for the extension
00629  * \param registrar registrar of the ignore pattern
00630  *
00631  * Adds an ignore pattern to a particular context.
00632  *
00633  * \retval 0 on success 
00634  * \retval -1 on failure
00635  */
00636 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
00637 
00638 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
00639 
00640 /* 
00641  * \brief Remove an ignorepat
00642  * 
00643  * \param context context from which to remove the pattern
00644  * \param ignorepat the pattern to remove
00645  * \param registrar the registrar of the ignore pattern
00646  *
00647  * This removes the given ignorepattern
00648  *
00649  * \retval 0 on success 
00650  * \retval -1 on failure
00651  */
00652 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
00653 
00654 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
00655 
00656 /*! 
00657  * \brief Checks to see if a number should be ignored
00658  * 
00659  * \param context context to search within
00660  * \param pattern to check whether it should be ignored or not
00661  *
00662  * Check if a number should be ignored with respect to dialtone cancellation.
00663  *
00664  * \retval 0 if the pattern should not be ignored 
00665  * \retval non-zero if the pattern should be ignored 
00666  */
00667 int ast_ignore_pattern(const char *context, const char *pattern);
00668 
00669 /* Locking functions for outer modules, especially for completion functions */
00670 
00671 /*! 
00672  * \brief Locks the context list
00673  *
00674  * \retval 0 on success 
00675  * \retval -1 on error
00676  */
00677 int ast_lock_contexts(void); /* equivalent to wrlock */
00678 int ast_rdlock_contexts(void);
00679 int ast_wrlock_contexts(void);
00680 
00681 /*! 
00682  * \brief Unlocks contexts
00683  * 
00684  * \retval 0 on success 
00685  * \retval -1 on failure
00686  */
00687 int ast_unlock_contexts(void);
00688 
00689 /*! 
00690  * \brief Locks a given context
00691  * 
00692  * \param con context to lock
00693  *
00694  * \retval 0 on success 
00695  * \retval -1 on failure
00696  */
00697 int ast_lock_context(struct ast_context *con);
00698 
00699 /*! 
00700  * \retval Unlocks the given context
00701  * 
00702  * \param con context to unlock
00703  *
00704  * \retval 0 on success 
00705  * \retval -1 on failure
00706  */
00707 int ast_unlock_context(struct ast_context *con);
00708 
00709 /*! 
00710  * \brief locks the macrolock in the given given context
00711  *
00712  * \param macrocontext name of the macro-context to lock
00713  *
00714  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
00715  *
00716  * \retval 0 on success
00717  * \retval -1 on failure
00718  */
00719 int ast_context_lockmacro(const char *macrocontext);
00720 
00721 /*!
00722  * \brief Unlocks the macrolock in the given context
00723  *
00724  * \param macrocontext name of the macro-context to unlock
00725  *
00726  * Unlocks the given macro-context so that another thread (call) can execute it
00727  *
00728  * \retval 0 on success
00729  * \retval -1 on failure
00730  */
00731 int ast_context_unlockmacro(const char *macrocontext);
00732 
00733 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
00734 
00735 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
00736 
00737 /*! Synchronously or asynchronously make an outbound call and send it to a
00738    particular extension */
00739 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);
00740 
00741 /*! Synchronously or asynchronously make an outbound call and send it to a
00742    particular application with given extension */
00743 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);
00744 
00745 /*!
00746  * \brief Evaluate a condition
00747  *
00748  * \retval 0 if the condition is NULL or of zero length
00749  * \retval int If the string is an integer, the integer representation of
00750  *             the integer is returned
00751  * \retval 1 Any other non-empty string
00752  */
00753 int pbx_checkcondition(const char *condition);
00754 
00755 /*! @name 
00756  * Functions for returning values from structures */
00757 /*! @{ */
00758 const char *ast_get_context_name(struct ast_context *con);
00759 const char *ast_get_extension_name(struct ast_exten *exten);
00760 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
00761 const char *ast_get_include_name(struct ast_include *include);
00762 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
00763 const char *ast_get_switch_name(struct ast_sw *sw);
00764 const char *ast_get_switch_data(struct ast_sw *sw);
00765 /*! @} */
00766 
00767 /*! @name Other Extension stuff */
00768 /*! @{ */
00769 int ast_get_extension_priority(struct ast_exten *exten);
00770 int ast_get_extension_matchcid(struct ast_exten *e);
00771 const char *ast_get_extension_cidmatch(struct ast_exten *e);
00772 const char *ast_get_extension_app(struct ast_exten *e);
00773 const char *ast_get_extension_label(struct ast_exten *e);
00774 void *ast_get_extension_app_data(struct ast_exten *e);
00775 /*! @} */
00776 
00777 /*! @name Registrar info functions ... */
00778 /*! @{ */
00779 const char *ast_get_context_registrar(struct ast_context *c);
00780 const char *ast_get_extension_registrar(struct ast_exten *e);
00781 const char *ast_get_include_registrar(struct ast_include *i);
00782 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
00783 const char *ast_get_switch_registrar(struct ast_sw *sw);
00784 /*! @} */
00785 
00786 /* Walking functions ... */
00787 struct ast_context *ast_walk_contexts(struct ast_context *con);
00788 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
00789    struct ast_exten *priority);
00790 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
00791    struct ast_exten *priority);
00792 struct ast_include *ast_walk_context_includes(struct ast_context *con,
00793    struct ast_include *inc);
00794 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
00795    struct ast_ignorepat *ip);
00796 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
00797 
00798 /*!
00799  * \note Will lock the channel.
00800  */
00801 int pbx_builtin_serialize_variables(struct ast_channel *chan, char *buf, size_t size);
00802 
00803 /*!
00804  * \note Will lock the channel.
00805  */
00806 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
00807 
00808 /*!
00809  * \note Will lock the channel.
00810  */
00811 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
00812 
00813 /*!
00814  * \note Will lock the channel.
00815  */
00816 void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
00817 
00818 /*!
00819  * \note Will lock the channel.
00820  */
00821 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
00822 void pbx_builtin_clear_globals(void);
00823 
00824 /*!
00825  * \note Will lock the channel.
00826  */
00827 int pbx_builtin_setvar(struct ast_channel *chan, void *data);
00828 
00829 void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
00830 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
00831 
00832 int ast_extension_patmatch(const char *pattern, const char *data);
00833 
00834 /*! Set "autofallthrough" flag, if newval is <0, does not acutally set.  If
00835   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
00836   fall through (reads extension instead).  Returns previous value. */
00837 int pbx_set_autofallthrough(int newval);
00838 
00839 /*!
00840  * \note This function will handle locking the channel as needed.
00841  */
00842 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
00843 
00844 /*!
00845  * \note I can find neither parsable nor parseable at dictionary.com, 
00846  *       but google gives me 169000 hits for parseable and only 49,800 
00847  *       for parsable 
00848  *
00849  * \note This function will handle locking the channel as needed.
00850  */
00851 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
00852 
00853 /*!
00854  * \note This function will handle locking the channel as needed.
00855  */
00856 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
00857 
00858 /*!
00859  * \note This function will handle locking the channel as needed.
00860  */
00861 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
00862 
00863 struct ast_custom_function* ast_custom_function_find(const char *name);
00864 
00865 /*!
00866  * \brief Unregister a custom function
00867  */
00868 int ast_custom_function_unregister(struct ast_custom_function *acf);
00869 
00870 /*!
00871  * \brief Reigster a custom function
00872  */
00873 int ast_custom_function_register(struct ast_custom_function *acf);
00874 
00875 /*! 
00876  * \brief Retrieve the number of active calls
00877  */
00878 int ast_active_calls(void);
00879    
00880 /*!
00881  * \brief executes a read operation on a function 
00882  *
00883  * \param chan Channel to execute on
00884  * \param function Data containing the function call string (will be modified)
00885  * \param workspace A pointer to safe memory to use for a return value 
00886  * \param len the number of bytes in workspace
00887  *
00888  * This application executes a function in read mode on a given channel.
00889  *
00890  * \return zero on success, non-zero on failure
00891  */
00892 int ast_func_read(struct ast_channel *chan, char *function, char *workspace, size_t len);
00893 
00894 /*!
00895  * \brief executes a write operation on a function
00896  *
00897  * \param chan Channel to execute on
00898  * \param function Data containing the function call string (will be modified)
00899  * \param value A value parameter to pass for writing
00900  *
00901  * This application executes a function in write mode on a given channel.
00902  *
00903  * \return zero on success, non-zero on failure
00904  */
00905 int ast_func_write(struct ast_channel *chan, char *function, const char *value);
00906 
00907 void ast_hint_state_changed(const char *device);
00908 
00909 #if defined(__cplusplus) || defined(c_plusplus)
00910 }
00911 #endif
00912 
00913 #endif /* _ASTERISK_PBX_H */

Generated on Mon Mar 31 07:38:03 2008 for Asterisk - the Open Source PBX by  doxygen 1.5.1