From 92f7c2d82d594b0efffa2c06f45d7ee957cf071c Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Sat, 18 Mar 2006 17:38:51 +0000 Subject: - remove some unnecessary extern keywords - cleanups to doxygen formatted documentation git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@13393 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/pbx.h | 624 +++++++++++++++++++++++++++++++------------------ 1 file changed, 401 insertions(+), 223 deletions(-) (limited to 'include/asterisk/pbx.h') diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h index 9fa5655a0..eccae45db 100644 --- a/include/asterisk/pbx.h +++ b/include/asterisk/pbx.h @@ -36,11 +36,12 @@ extern "C" { /*! Max length of an application */ #define AST_MAX_APP 32 -/*! Special return values from applications to the PBX */ -#define AST_PBX_KEEPALIVE 10 /* Destroy the thread, but don't hang up the channel */ -#define AST_PBX_NO_HANGUP_PEER 11 +/*! Special return values from applications to the PBX { */ +#define AST_PBX_KEEPALIVE 10 /*!< Destroy the thread, but don't hang up the channel */ +#define AST_PBX_NO_HANGUP_PEER 11 +/*! } */ -/*! Special Priority for an hint */ +/*! Special Priority for a hint */ #define PRIORITY_HINT -1 /*! Extension states */ @@ -100,97 +101,122 @@ struct ast_switch { }; struct ast_timing { - int hastime; /* If time construct exists */ - unsigned int monthmask; /* Mask for month */ - unsigned int daymask; /* Mask for date */ - unsigned int dowmask; /* Mask for day of week (mon-sun) */ - unsigned int minmask[24]; /* Mask for minute */ + int hastime; /*!< If time construct exists */ + unsigned int monthmask; /*!< Mask for month */ + unsigned int daymask; /*!< Mask for date */ + unsigned int dowmask; /*!< Mask for day of week (mon-sun) */ + unsigned int minmask[24]; /*!< Mask for minute */ }; -extern int ast_build_timing(struct ast_timing *i, char *info); -extern int ast_check_timing(struct ast_timing *i); +int ast_build_timing(struct ast_timing *i, char *info); +int ast_check_timing(struct ast_timing *i); struct ast_pbx { - int dtimeout; /* Timeout between digits (seconds) */ - int rtimeout; /* Timeout for response + int dtimeout; /*!< Timeout between digits (seconds) */ + int rtimeout; /*!< Timeout for response (seconds) */ }; -/*! Register an alternative switch */ /*! + * \brief Reigster an alternative switch + * * \param sw switch to register + * * This function registers a populated ast_switch structure with the * asterisk switching architecture. - * It returns 0 on success, and other than 0 on failure + * + * \return 0 on success, and other than 0 on failure */ -extern int ast_register_switch(struct ast_switch *sw); +int ast_register_switch(struct ast_switch *sw); -/*! Unregister an alternative switch */ /*! + * \brief Unregister an alternative switch + * * \param sw switch to unregister + * * Unregisters a switch from asterisk. - * Returns nothing + * + * \return nothing */ -extern void ast_unregister_switch(struct ast_switch *sw); +void ast_unregister_switch(struct ast_switch *sw); -/*! Look up an application */ /*! + * \brief Look up an application + * * \param app name of the app + * * This function searches for the ast_app structure within * the apps that are registered for the one with the name * you passed in. - * Returns the ast_app structure that matches on success, or NULL on failure + * + * \return the ast_app structure that matches on success, or NULL on failure */ -extern struct ast_app *pbx_findapp(const char *app); +struct ast_app *pbx_findapp(const char *app); -/*! executes an application */ /*! + * \brief Execute an application + * * \param c channel to execute on * \param app which app to execute * \param data the data passed into the app * \param newstack stack pointer + * * This application executes an application on a given channel. It * saves the stack and executes the given appliation passing in * the given data. - * It returns 0 on success, and -1 on failure + * + * \return 0 on success, and -1 on failure */ int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data, int newstack); -/*! Register a new context */ /*! + * \brief Register a new context + * * \param extcontexts pointer to the ast_context structure pointer * \param name name of the new context * \param registrar registrar of the context + * * This will first search for a context with your name. If it exists already, it will not * create a new one. If it does not exist, it will create a new one with the given name * and registrar. - * It returns NULL on failure, and an ast_context structure on success + * + * \return NULL on failure, and an ast_context structure on success */ struct ast_context *ast_context_create(struct ast_context **extcontexts, const char *name, const char *registrar); -/*! Merge the temporary contexts into a global contexts list and delete from the global list the ones that are being added */ /*! + * \brief Merge the temporary contexts into a global contexts list and delete from the + * global list the ones that are being added + * * \param extcontexts pointer to the ast_context structure pointer - * \param registrar of the context; if it's set the routine will delete all contexts that belong to that registrar; if NULL only the contexts that are specified in extcontexts + * \param registrar of the context; if it's set the routine will delete all contexts + * that belong to that registrar; if NULL only the contexts that are specified + * in extcontexts */ void ast_merge_contexts_and_delete(struct ast_context **extcontexts, const char *registrar); -/*! Destroy a context (matches the specified context (or ANY context if NULL) */ /*! + * \brief Destroy a context (matches the specified context (or ANY context if NULL) + * * \param con context to destroy * \param registrar who registered it + * * You can optionally leave out either parameter. It will find it * based on either the ast_context or the registrar name. - * Returns nothing + * + * \return nothing */ void ast_context_destroy(struct ast_context *con, const char *registrar); -/*! Find a context */ /*! + * \brief Find a context + * * \param name name of the context to find + * * Will search for the context with the given name. - * Returns the ast_context on success, NULL on failure. + * + * \return the ast_context on success, NULL on failure. */ struct ast_context *ast_context_find(const char *name); @@ -200,113 +226,147 @@ enum ast_pbx_result { AST_PBX_CALL_LIMIT = -2, }; -/*! Create a new thread and start the PBX (or whatever) */ /*! + * \brief Create a new thread and start the PBX + * * \param c channel to start the pbx on + * + * See ast_pbx_run for a synchronous function to run the PBX in the + * current thread, as opposed to starting a new one. + * * \return Zero on success, non-zero on failure */ enum ast_pbx_result ast_pbx_start(struct ast_channel *c); -/*! Execute the PBX in the current thread */ /*! + * \brief Execute the PBX in the current thread + * * \param c channel to run the pbx on - * \return Zero on success, non-zero on failure + * * This executes the PBX on a given channel. It allocates a new * PBX structure for the channel, and provides all PBX functionality. + * See ast_pbx_start for an asynchronous function to run the PBX in a + * new thread as opposed to the current one. + * + * \return Zero on success, non-zero on failure */ enum ast_pbx_result ast_pbx_run(struct ast_channel *c); /*! + * \brief Add and extension to an extension context. + * * \param context context to add the extension to * \param replace * \param extension extension to add * \param priority priority level of extension addition * \param label extension label - * \param callerid callerid of extension + * \param callerid pattern to match CallerID, or NULL to match any CallerID * \param application application to run on the extension with that priority level * \param data data to pass to the application * \param datad * \param registrar who registered the extension - * Add and extension to an extension context. - * Callerid is a pattern to match CallerID, or NULL to match any callerid - * Returns 0 on success, -1 on failure + * + * \retval 0 success + * \retval -1 failure */ -int ast_add_extension(const char *context, int replace, const char *extension, int priority, const char *label, const char *callerid, +int ast_add_extension(const char *context, int replace, const char *extension, + int priority, const char *label, const char *callerid, const char *application, void *data, void (*datad)(void *), const char *registrar); -/*! Add an extension to an extension context, this time with an ast_context *. CallerID is a pattern to match on callerid, or NULL to not care about callerid */ /*! - * For details about the arguements, check ast_add_extension() + * \brief Add an extension to an extension context, this time with an ast_context *. + * + * \note For details about the arguments, check ast_add_extension() */ -int ast_add_extension2(struct ast_context *con, - int replace, const char *extension, int priority, const char *label, const char *callerid, - const char *application, void *data, void (*datad)(void *), - const char *registrar); +int ast_add_extension2(struct ast_context *con, int replace, const char *extension, + int priority, const char *label, const char *callerid, + const char *application, void *data, void (*datad)(void *), const char *registrar); -/*! Add an application. The function 'execute' should return non-zero if the line needs to be hung up. */ -/*! - \param app Short name of the application - \param execute a function callback to execute the application - \param synopsis a short description of the application - \param description long description of the application - Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline - description with more detail, including under what conditions the application - will return 0 or -1. - This registers an application with asterisks internal application list. Please note: - The individual applications themselves are responsible for registering and unregistering - CLI commands. - It returns 0 on success, -1 on failure. -*/ + +/*! + * \brief Reigster an application. + * + * \param app Short name of the application + * \param execute a function callback to execute the application. It should return + * non-zero if the channel needs to be hung up. + * \param synopsis a short description (one line synopsis) of the application + * \param description long description with all of the details about the use of + * the application + * + * This registers an application with Asterisk's internal application list. + * \note The individual applications themselves are responsible for registering and unregistering + * and unregistering their own CLI commands. + * + * \retval 0 success + * \retval -1 failure. + */ int ast_register_application(const char *app, int (*execute)(struct ast_channel *, void *), const char *synopsis, const char *description); -/*! Remove an application */ -/*! +/*! + * \brief Unregister an application + * * \param app name of the application (does not have to be the same string as the one that was registered) - * This unregisters an application from asterisk's internal registration mechanisms. - * It returns 0 on success, and -1 on failure. + * + * This unregisters an application from Asterisk's internal application list. + * + * \retval 0 success + * \retval -1 failure */ int ast_unregister_application(const char *app); -/*! Uses hint and devicestate callback to get the state of an extension */ -/*! +/*! + * \brief Uses hint and devicestate callback to get the state of an extension + * * \param c this is not important * \param context which context to look in * \param exten which extension to get state - * Returns extension state !! = AST_EXTENSION_??? + * + * \return extension state as defined in the ast_extension_states enum */ int ast_extension_state(struct ast_channel *c, const char *context, const char *exten); -/*! Return string of the state of an extension */ -/*! +/*! + * \brief Return string representation of the state of an extension + * * \param extension_state is the numerical state delivered by ast_extension_state - * Returns the state of an extension as string + * + * \return the state of an extension as string */ const char *ast_extension_state2str(int extension_state); -/*! Registers a state change callback */ /*! + * \brief Registers a state change callback + * * \param context which context to look in * \param exten which extension to get state * \param callback callback to call if state changed * \param data to pass to callback - * The callback is called if the state for extension is changed - * Return -1 on failure, ID on success + * + * The callback is called if the state of an extension is changed. + * + * \retval -1 on failure + * \retval ID on success */ int ast_extension_state_add(const char *context, const char *exten, ast_state_cb_type callback, void *data); -/*! Deletes a registered state change callback by ID */ -/*! +/*! + * \brief Deletes a registered state change callback by ID + * * \param id of the callback to delete * \param callback callback + * * Removes the callback from list of callbacks - * Return 0 on success, -1 on failure + * + * \retval 0 success + * \retval -1 failure */ int ast_extension_state_del(int id, ast_state_cb_type callback); -/*! If an extension exists, return non-zero */ -/*! +/*! + * \brief If an extension exists, return non-zero + * * \param hint buffer for hint * \param maxlen size of hint buffer * \param name buffer for name portion of hint @@ -314,233 +374,336 @@ int ast_extension_state_del(int id, ast_state_cb_type callback); * \param c this is not important * \param context which context to look in * \param exten which extension to search for - * If an extension within the given context with the priority PRIORITY_HINT + * + * \return If an extension within the given context with the priority PRIORITY_HINT * is found a non zero value will be returned. * Otherwise, 0 is returned. */ -int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, struct ast_channel *c, const char *context, const char *exten); +int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, + struct ast_channel *c, const char *context, const char *exten); -/*! If an extension exists, return non-zero */ -/* work */ /*! + * \brief Determine whether an extension exists + * * \param c this is not important * \param context which context to look in * \param exten which extension to search for * \param priority priority of the action within the extension * \param callerid callerid to search for - * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned. - * Otherwise, 0 is returned. + * + * \return If an extension within the given context(or callerid) with the given priority + * is found a non zero value will be returned. Otherwise, 0 is returned. */ -int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid); +int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, + int priority, const char *callerid); -/*! If an extension exists, return non-zero */ -/* work */ -/*! +/*! + * \brief Find the priority of an extension that has the specified label + * * \param c this is not important * \param context which context to look in * \param exten which extension to search for * \param label label of the action within the extension to match to priority * \param callerid callerid to search for - * If an priority which matches given label in extension or -1 if not found. -\ */ -int ast_findlabel_extension(struct ast_channel *c, const char *context, const char *exten, const char *label, const char *callerid); - -int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, const char *exten, const char *label, const char *callerid); + * + * \return the priority which matches the given label in the extension or -1 if not found. + */ +int ast_findlabel_extension(struct ast_channel *c, const char *context, + const char *exten, const char *label, const char *callerid); -/*! Looks for a valid matching extension */ /*! - \param c not really important - \param context context to serach within - \param exten extension to check - \param priority priority of extension path - \param callerid callerid of extension being searched for - If "exten" *could be* a valid extension in this context with or without - some more digits, return non-zero. Basically, when this returns 0, no matter - what you add to exten, it's not going to be a valid extension anymore -*/ -int ast_canmatch_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid); + * \brief Find the priority of an extension that has the specified label + * + * \note This function is the same as ast_findlabel_extension, except that it accepts + * a pointer to an ast_context structure to specify the context instead of the + * name of the context. Otherwise, the functions behave the same. + */ +int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, + const char *exten, const char *label, const char *callerid); -/*! Looks to see if adding anything to this extension might match something. (exists ^ canmatch) */ -/*! - \param c not really important - \param context context to serach within - \param exten extension to check - \param priority priority of extension path - \param callerid callerid of extension being searched for - If "exten" *could match* a valid extension in this context with - some more digits, return non-zero. Does NOT return non-zero if this is - an exact-match only. Basically, when this returns 0, no matter - what you add to exten, it's not going to be a valid extension anymore -*/ -int ast_matchmore_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid); +/*! + * \brief Looks for a valid matching extension + * + * \param c not really important + * \param context context to serach within + * \param exten extension to check + * \param priority priority of extension path + * \param callerid callerid of extension being searched for + * + * \return If "exten" *could be* a valid extension in this context with or without + * some more digits, return non-zero. Basically, when this returns 0, no matter + * what you add to exten, it's not going to be a valid extension anymore + */ +int ast_canmatch_extension(struct ast_channel *c, const char *context, + const char *exten, int priority, const char *callerid); -/*! Determine if a given extension matches a given pattern (in NXX format) */ -/*! +/*! + * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch) + * + * \param c not really important XXX + * \param context context to serach within + * \param exten extension to check + * \param priority priority of extension path + * \param callerid callerid of extension being searched for + * + * \return If "exten" *could match* a valid extension in this context with + * some more digits, return non-zero. Does NOT return non-zero if this is + * an exact-match only. Basically, when this returns 0, no matter + * what you add to exten, it's not going to be a valid extension anymore + */ +int ast_matchmore_extension(struct ast_channel *c, const char *context, + const char *exten, int priority, const char *callerid); + +/*! + * \brief Determine if a given extension matches a given pattern (in NXX format) + * * \param pattern pattern to match * \param extension extension to check against the pattern. + * * Checks whether or not the given extension matches the given pattern. - * Returns 1 on match, 0 on failure + * + * \retval 1 on match + * \retval 0 on failure */ int ast_extension_match(const char *pattern, const char *extension); + int ast_extension_close(const char *pattern, const char *data, int needmore); -/*! Launch a new extension (i.e. new stack) */ -/*! + +/*! + * \brief Launch a new extension (i.e. new stack) + * * \param c not important * \param context which context to generate the extension within * \param exten new extension to add * \param priority priority of new extension * \param callerid callerid of extension + * * This adds a new extension to the asterisk extension list. - * It returns 0 on success, -1 on failure. + * + * \retval 0 on success + * \retval -1 on failure. */ -int ast_spawn_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid); +int ast_spawn_extension(struct ast_channel *c, const char *context, + const char *exten, int priority, const char *callerid); -/*! Execute an extension. */ -/*! - \param c channel to execute upon - \param context which context extension is in - \param exten extension to execute - \param priority priority to execute within the given extension - \param callerid Caller-ID - If it's not available, do whatever you should do for - default extensions and halt the thread if necessary. This function does not - return, except on error. -*/ -int ast_exec_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid); +/*! + * \brief Execute an extension. + * + * \param c channel to execute upon + * \param context which context extension is in + * \param exten extension to execute + * \param priority priority to execute within the given extension + * \param callerid Caller-ID + * + * If it's not available, do whatever you should do for + * default extensions and halt the thread if necessary. This function does not + * return, except on error. + */ +int ast_exec_extension(struct ast_channel *c, const char *context, + const char *exten, int priority, const char *callerid); -/*! Add an include */ -/*! - \param context context to add include to - \param include new include to add - \param registrar who's registering it - Adds an include taking a char * string as the context parameter - Returns 0 on success, -1 on error +/*! + * \brief Add a context include + * + * \param context context to add include to + * \param include new include to add + * \param registrar who's registering it + * + * Adds an include taking a char * string as the context parameter + * + * \retval 0 on success + * \retval -1 on error */ -int ast_context_add_include(const char *context, const char *include, const char *registrar); +int ast_context_add_include(const char *context, const char *include, + const char *registrar); -/*! Add an include */ -/*! - \param con context to add the include to - \param include include to add - \param registrar who registered the context - Adds an include taking a struct ast_context as the first parameter - Returns 0 on success, -1 on failure -*/ -int ast_context_add_include2(struct ast_context *con, const char *include, const char *registrar); +/*! + * \brief Add a context include + * + * \param con context to add the include to + * \param include include to add + * \param registrar who registered the context + * + * Adds an include taking a struct ast_context as the first parameter + * + * \retval 0 on success + * \retval -1 on failure + */ +int ast_context_add_include2(struct ast_context *con, const char *include, + const char *registrar); -/*! Removes an include */ -/*! - * See add_include +/*! + * \brief Remove a context include + * + * \note See ast_context_add_include for information on arguments + * + * \retval 0 on success + * \retval -1 on failure */ -int ast_context_remove_include(const char *context, const char *include,const char *registrar); -/*! Removes an include by an ast_context structure */ -/*! - * See add_include2 +int ast_context_remove_include(const char *context, const char *include, + const char *registrar); + +/*! + * \brief Removes an include by an ast_context structure + * + * \note See ast_context_add_include2 for information on arguments + * + * \retval 0 on success + * \retval -1 on success */ -int ast_context_remove_include2(struct ast_context *con, const char *include, const char *registrar); +int ast_context_remove_include2(struct ast_context *con, const char *include, + const char *registrar); -/*! Verifies includes in an ast_contect structure */ -/*! +/*! + * \brief Verifies includes in an ast_contect structure + * * \param con context in which to verify the includes - * Returns 0 if no problems found, -1 if there were any missing context + * + * \retval 0 if no problems found + * \retval -1 if there were any missing context */ int ast_context_verify_includes(struct ast_context *con); -/*! Add a switch */ -/*! +/*! + * \brief Add a switch + * * \param context context to which to add the switch * \param sw switch to add * \param data data to pass to switch * \param eval whether to evaluate variables when running switch * \param registrar whoever registered the switch + * * This function registers a switch with the asterisk switch architecture - * It returns 0 on success, -1 on failure + * + * \retval 0 on success + * \retval -1 on failure */ -int ast_context_add_switch(const char *context, const char *sw, const char *data, int eval, const char *registrar); -/*! Adds a switch (first param is a ast_context) */ -/*! - * See ast_context_add_switch() +int ast_context_add_switch(const char *context, const char *sw, const char *data, + int eval, const char *registrar); + +/*! + * \brief Adds a switch (first param is a ast_context) + * + * \note See ast_context_add_switch() for argument information, with the exception of + * the first argument. In this case, it's a pointer to an ast_context structure + * as opposed to the name. */ -int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, int eval, const char *registrar); +int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, + int eval, const char *registrar); -/*! Remove a switch */ -/*! +/*! + * \brief Remove a switch + * * Removes a switch with the given parameters - * Returns 0 on success, -1 on failure + * + * \retval 0 on success + * \retval -1 on failure */ -int ast_context_remove_switch(const char *context, const char *sw, const char *data, const char *registrar); -int ast_context_remove_switch2(struct ast_context *con, const char *sw, const char *data, const char *registrar); +int ast_context_remove_switch(const char *context, const char *sw, + const char *data, const char *registrar); -/*! Simply remove extension from context */ -/*! +int ast_context_remove_switch2(struct ast_context *con, const char *sw, + const char *data, const char *registrar); + +/*! + * \brief Simply remove extension from context + * * \param context context to remove extension from * \param extension which extension to remove * \param priority priority of extension to remove * \param registrar registrar of the extension + * * This function removes an extension from a given context. - * Returns 0 on success, -1 on failure + * + * \retval 0 on success + * \retval -1 on failure */ int ast_context_remove_extension(const char *context, const char *extension, int priority, const char *registrar); + int ast_context_remove_extension2(struct ast_context *con, const char *extension, int priority, const char *registrar); -/*! Add an ignorepat */ -/*! +/*! + * \brief Add an ignorepat + * * \param context which context to add the ignorpattern to * \param ignorepat ignorepattern to set up for the extension * \param registrar registrar of the ignore pattern + * * Adds an ignore pattern to a particular context. - * Returns 0 on success, -1 on failure + * + * \retval 0 on success + * \retval -1 on failure */ int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar); + int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar); -/* Remove an ignorepat */ -/*! +/* + * \brief Remove an ignorepat + * * \param context context from which to remove the pattern * \param ignorepat the pattern to remove * \param registrar the registrar of the ignore pattern + * * This removes the given ignorepattern - * Returns 0 on success, -1 on failure + * + * \retval 0 on success + * \retval -1 on failure */ int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar); + int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar); -/*! Checks to see if a number should be ignored */ -/*! +/*! + * \brief Checks to see if a number should be ignored + * * \param context context to search within * \param pattern to check whether it should be ignored or not - * Check if a number should be ignored with respect to dialtone cancellation. - * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored + * + * Check if a number should be ignored with respect to dialtone cancellation. + * + * \retval 0 if the pattern should not be ignored + * \retval non-zero if the pattern should be ignored */ int ast_ignore_pattern(const char *context, const char *pattern); /* Locking functions for outer modules, especially for completion functions */ -/*! Locks the contexts */ -/*! Locks the context list - * Returns 0 on success, -1 on error + +/*! + * \brief Locks the context list + * + * \retval 0 on success + * \retval -1 on error */ int ast_lock_contexts(void); -/*! Unlocks contexts */ -/*! - * Returns 0 on success, -1 on failure +/*! + * \brief Unlocks contexts + * + * \retval 0 on success + * \retval -1 on failure */ int ast_unlock_contexts(void); -/*! Locks a given context */ -/*! +/*! + * \brief Locks a given context + * * \param con context to lock - * Locks the context. - * Returns 0 on success, -1 on failure + * + * \retval 0 on success + * \retval -1 on failure */ int ast_lock_context(struct ast_context *con); -/*! Unlocks the given context */ -/*! + +/*! + * \retval Unlocks the given context + * * \param con context to unlock - * Unlocks the given context - * Returns 0 on success, -1 on failure + * + * \retval 0 on success + * \retval -1 on failure */ int ast_unlock_context(struct ast_context *con); @@ -549,11 +712,11 @@ int ast_async_goto(struct ast_channel *chan, const char *context, const char *ex int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority); -/* Synchronously or asynchronously make an outbound call and send it to a +/*! Synchronously or asynchronously make an outbound call and send it to a particular extension */ 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); -/* Synchronously or asynchronously make an outbound call and send it to a +/*! Synchronously or asynchronously make an outbound call and send it to a particular application with given extension */ 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); @@ -593,21 +756,21 @@ struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con, struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw); int pbx_builtin_serialize_variables(struct ast_channel *chan, char *buf, size_t size); -extern const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name); -extern void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value); -extern void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value); -extern void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp); -extern void pbx_builtin_clear_globals(void); -extern int pbx_builtin_setvar(struct ast_channel *chan, void *data); -extern void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count); -extern void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count); +const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name); +void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value); +void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value); +void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp); +void pbx_builtin_clear_globals(void); +int pbx_builtin_setvar(struct ast_channel *chan, void *data); +void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count); +void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count); int ast_extension_patmatch(const char *pattern, const char *data); -/* Set "autofallthrough" flag, if newval is <0, does not acutally set. If +/*! Set "autofallthrough" flag, if newval is <0, does not acutally set. If set to 1, sets to auto fall through. If newval set to 0, sets to no auto fall through (reads extension instead). Returns previous value. */ -extern int pbx_set_autofallthrough(int newval); +int pbx_set_autofallthrough(int newval); int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority); /* I can find neither parsable nor parseable at dictionary.com, but google gives me 169000 hits for parseable and only 49,800 for parsable */ int ast_parseable_goto(struct ast_channel *chan, const char *goto_string); @@ -615,31 +778,46 @@ int ast_explicit_goto(struct ast_channel *chan, const char *context, const char int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority); struct ast_custom_function* ast_custom_function_find(const char *name); + +/*! + * \brief Unregister a custom function + */ int ast_custom_function_unregister(struct ast_custom_function *acf); + +/*! + * \brief Reigster a custom function + */ int ast_custom_function_register(struct ast_custom_function *acf); -/* Number of active calls */ +/*! + * \brief Retrieve the number of active calls + */ int ast_active_calls(void); -/*! executes a read operation on a function */ /*! + * \brief executes a read operation on a function + * * \param chan Channel to execute on * \param function Data containing the function call string (will be modified) * \param workspace A pointer to safe memory to use for a return value * \param len the number of bytes in workspace + * + * This application executes a function in read mode on a given channel. + * * \return zero on success, non-zero on failure - * This application executes an function in read mode on a given channel. - * */ - + */ int ast_func_read(struct ast_channel *chan, char *function, char *workspace, size_t len); -/*! executes a write operation on a function */ /*! + * \brief executes a write operation on a function + * * \param chan Channel to execute on * \param function Data containing the function call string (will be modified) * \param value A value parameter to pass for writing + * + * This application executes a function in write mode on a given channel. + * * \return zero on success, non-zero on failure - * This application executes an function in write mode on a given channel. */ int ast_func_write(struct ast_channel *chan, char *function, const char *value); -- cgit v1.2.3