improve handling of API calls provided by loaded modules through use of some GCC...
[asterisk/asterisk.git] / include / asterisk / agi.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief AGI Extension interfaces - Asterisk Gateway Interface
21  */
22
23 #ifndef _ASTERISK_AGI_H
24 #define _ASTERISK_AGI_H
25
26 #if defined(__cplusplus) || defined(c_plusplus)
27 extern "C" {
28 #endif
29
30 #include "asterisk/cli.h"
31 #include "asterisk/optional_api.h"
32
33 typedef struct agi_state {
34         int fd;                 /*!< FD for general output */
35         int audio;              /*!< FD for audio output */
36         int ctrl;               /*!< FD for input control */
37         unsigned int fast:1;    /*!< flag for fast agi or not */
38         struct ast_speech *speech; /*!< Speech structure for speech recognition */
39 } AGI;
40
41 typedef struct agi_command {
42         char *cmda[AST_MAX_CMD_LEN];            /*!< Null terminated list of the words of the command */
43         /*! Handler for the command (channel, AGI state, # of arguments, argument list). 
44             Returns RESULT_SHOWUSAGE for improper arguments */
45         int (*handler)(struct ast_channel *chan, AGI *agi, int argc, char *argv[]);
46         /*! Summary of the command (< 60 characters) */
47         char *summary;
48         /*! Detailed usage information */
49         char *usage;
50         /*! Does this application run dead */
51         int dead;
52         /*! AGI command syntax description */
53         char *syntax;
54         /*! See also content */
55         char *seealso;
56         /*! Where the documentation come from. */
57         enum ast_doc_src docsrc;
58         /*! Pointer to module that registered the agi command */
59         struct ast_module *mod;
60         /*! Linked list pointer */
61         AST_LIST_ENTRY(agi_command) list;
62 } agi_command;
63
64 /*!
65  * \brief
66  *
67  * Registers an AGI command.
68  *
69  * \param mod Pointer to the module_info structure for the module that is registering the command
70  * \param cmd Pointer to the descriptor for the command
71  * \return 1 on success, 0 if the command is already registered
72  *
73  */
74 AST_OPTIONAL_API(int, ast_agi_register, (struct ast_module *mod, agi_command *cmd),
75                  { return AST_OPTIONAL_API_UNAVAILABLE; });
76
77 /*!
78  * \brief
79  *
80  * Unregisters an AGI command.
81  *
82  * \param mod Pointer to the module_info structure for the module that is unregistering the command
83  * \param cmd Pointer to the descriptor for the command
84  * \return 1 on success, 0 if the command was not already registered
85  *
86  */
87 AST_OPTIONAL_API(int, ast_agi_unregister, (struct ast_module *mod, agi_command *cmd),
88                  { return AST_OPTIONAL_API_UNAVAILABLE; });
89
90 /*!
91  * \brief
92  *
93  * Registers a group of AGI commands, provided as an array of struct agi_command
94  * entries.
95  *
96  * \param mod Pointer to the module_info structure for the module that is registering the commands
97  * \param cmd Pointer to the first entry in the array of command descriptors
98  * \param len Length of the array (use the ARRAY_LEN macro to determine this easily)
99  * \return 0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
100  *
101  * \note If any command fails to register, all commands previously registered during the operation
102  * will be unregistered. In other words, this function registers all the provided commands, or none
103  * of them.
104  */
105 AST_OPTIONAL_API(int, ast_agi_register_multiple, (struct ast_module *mod, struct agi_command *cmd, unsigned int len),
106                  { return AST_OPTIONAL_API_UNAVAILABLE; });
107
108 /*!
109  * \brief
110  *
111  * Unregisters a group of AGI commands, provided as an array of struct agi_command
112  * entries.
113  *
114  * \param mod Pointer to the module_info structure for the module that is unregistering the commands
115  * \param cmd Pointer to the first entry in the array of command descriptors
116  * \param len Length of the array (use the ARRAY_LEN macro to determine this easily)
117  * \return 0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
118  *
119  * \note If any command fails to unregister, this function will continue to unregister the
120  * remaining commands in the array; it will not reregister the already-unregistered commands.
121  */
122 AST_OPTIONAL_API(int, ast_agi_unregister_multiple, (struct ast_module *mod, struct agi_command *cmd, unsigned int len),
123                  { return AST_OPTIONAL_API_UNAVAILABLE; });
124
125 /*!
126  * \brief
127  *
128  * Sends a string of text to an application connected via AGI.
129  *
130  * \param fd The file descriptor for the AGI session (from struct agi_state)
131  * \param chan Pointer to an associated Asterisk channel, if any
132  * \param fmt printf-style format string
133  * \return 0 for success, -1 for failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
134  *
135  */
136 AST_OPTIONAL_API_ATTR(int, format(printf, 3, 4), ast_agi_send, (int fd, struct ast_channel *chan, char *fmt, ...),
137                       { return AST_OPTIONAL_API_UNAVAILABLE; });
138
139 #if defined(__cplusplus) || defined(c_plusplus)
140 }
141 #endif
142
143 #endif /* _ASTERISK_AGI_H */