Asterisk - The Open Source Telephony Project  GIT-master-e8cda4b
agi.h
Go to the documentation of this file.
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/xmldoc.h"
32 #include "asterisk/optional_api.h"
33 
34 typedef struct agi_state {
35  int fd; /*!< FD for general output */
36  int audio; /*!< FD for audio output */
37  int ctrl; /*!< FD for input control */
38  unsigned int fast:1; /*!< flag for fast agi or not */
39  struct ast_speech *speech; /*!< Speech structure for speech recognition */
40 } AGI;
41 
42 typedef struct agi_command {
43  const char * const cmda[AST_MAX_CMD_LEN]; /*!< Null terminated list of the words of the command */
44  /*! Handler for the command (channel, AGI state, # of arguments, argument list).
45  Returns RESULT_SHOWUSAGE for improper arguments */
46  int (* const handler)(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[]);
47  /*! Summary of the command (< 60 characters) */
48  const char * const summary;
49  /*! Detailed usage information */
50  const char * const usage;
51  /*! Does this application run dead */
52  const int dead;
53  /*! AGI command syntax description */
54  const char * const syntax;
55  /*! See also content */
56  const char * const seealso;
57  /*! Where the documentation come from. */
58  const enum ast_doc_src docsrc;
59  /*! Pointer to module that registered the agi command */
60  struct ast_module *mod;
61  /*! Linked list pointer */
63 } agi_command;
64 
65 /*!
66  * \brief
67  *
68  * Registers an AGI command.
69  *
70  * \param mod Pointer to the module_info structure for the module that is registering the command
71  * \param cmd Pointer to the descriptor for the command
72  * \retval 1 on success
73  * \retval 0 the command is already registered
74  * \retval AST_OPTIONAL_API_UNAVAILABLE the module is not loaded.
75  */
77  (struct ast_module *mod, agi_command *cmd),
78  { return AST_OPTIONAL_API_UNAVAILABLE; });
79 
80 /*!
81  * \brief
82  *
83  * Unregisters an AGI command.
84  *
85  * \param cmd Pointer to the descriptor for the command
86  * \return 1 on success, 0 if the command was not already registered
87  *
88  */
90  (agi_command *cmd),
91  { return AST_OPTIONAL_API_UNAVAILABLE; });
92 
93 /*!
94  * \brief
95  *
96  * Registers a group of AGI commands, provided as an array of struct agi_command
97  * entries.
98  *
99  * \param mod Pointer to the module_info structure for the module that is registering the commands
100  * \param cmd Pointer to the first entry in the array of command descriptors
101  * \param len Length of the array (use the ARRAY_LEN macro to determine this easily)
102  * \return 0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
103  *
104  * \note If any command fails to register, all commands previously registered during the operation
105  * will be unregistered. In other words, this function registers all the provided commands, or none
106  * of them.
107  */
109  (struct ast_module *mod, struct agi_command *cmd, unsigned int len),
110  { return AST_OPTIONAL_API_UNAVAILABLE; });
111 
112 /*!
113  * \brief
114  *
115  * Unregisters a group of AGI commands, provided as an array of struct agi_command
116  * entries.
117  *
118  * \param cmd Pointer to the first entry in the array of command descriptors
119  * \param len Length of the array (use the ARRAY_LEN macro to determine this easily)
120  * \return 0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
121  *
122  * \note If any command fails to unregister, this function will continue to unregister the
123  * remaining commands in the array; it will not reregister the already-unregistered commands.
124  */
126  (struct agi_command *cmd, unsigned int len),
127  { return AST_OPTIONAL_API_UNAVAILABLE; });
128 
129 /*!
130  * \brief
131  *
132  * Sends a string of text to an application connected via AGI.
133  *
134  * \param fd The file descriptor for the AGI session (from struct agi_state)
135  * \param chan Pointer to an associated Asterisk channel, if any
136  * \param fmt printf-style format string
137  * \return 0 for success, -1 for failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
138  *
139  */
140 AST_OPTIONAL_API_ATTR(int, format(printf, 3, 4), ast_agi_send,
141  (int fd, struct ast_channel *chan, char *fmt, ...),
142  { return AST_OPTIONAL_API_UNAVAILABLE; });
143 
144 #if defined(__cplusplus) || defined(c_plusplus)
145 }
146 #endif
147 
148 #endif /* _ASTERISK_AGI_H */
const char *const summary
Definition: agi.h:48
const char *const seealso
Definition: agi.h:56
Main Channel structure associated with a channel.
Optional API function macros.
int ast_agi_register(struct ast_module *mod, agi_command *cmd)
Registers an AGI command.
Definition: res_agi.c:3783
int ast_agi_register_multiple(struct ast_module *mod, struct agi_command *cmd, unsigned int len)
Registers a group of AGI commands, provided as an array of struct agi_command entries.
Definition: res_agi.c:3863
int ast_agi_unregister(agi_command *cmd)
Unregisters an AGI command.
Definition: res_agi.c:3827
const char *const usage
Definition: agi.h:50
struct ast_module * mod
Definition: agi.h:60
int ctrl
Definition: agi.h:37
#define AST_OPTIONAL_API(result, name, proto, stub)
Declare an optional API function.
Definition: optional_api.h:230
ast_doc_src
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:30
const int dead
Definition: agi.h:52
#define AST_OPTIONAL_API_UNAVAILABLE
A common value for optional API stub functions to return.
Definition: optional_api.h:74
const char *const syntax
Definition: agi.h:54
int ast_agi_unregister_multiple(struct agi_command *cmd, unsigned int len)
Unregisters a group of AGI commands, provided as an array of struct agi_command entries.
Definition: res_agi.c:3893
struct agi_state AGI
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
int fd
Definition: agi.h:35
struct ast_speech * speech
Definition: agi.h:39
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
int audio
Definition: agi.h:36
Asterisk XML Documentation API.
unsigned int fast
Definition: agi.h:38
#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)
Declare an optional API function with compiler attributes.
Definition: optional_api.h:233
Standard Command Line Interface.
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
Definition: agi.h:34
static snd_pcm_format_t format
Definition: chan_alsa.c:102
#define AST_MAX_CMD_LEN
Definition: cli.h:48
int ast_agi_send(int fd, struct ast_channel *chan, char *fmt,...)
Sends a string of text to an application connected via AGI.
Definition: res_agi.c:1486
struct agi_command agi_command