Asterisk - The Open Source Telephony Project GIT-master-f3e88d3
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)
27extern "C" {
28#endif
29
30#include "asterisk/cli.h"
31#include "asterisk/xmldoc.h"
33
34typedef 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 */
41
42typedef 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 */
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),
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),
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 */
140AST_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 */
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:1481
int ast_agi_register(struct ast_module *mod, agi_command *cmd)
Registers an AGI command.
Definition: res_agi.c:3815
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:3925
int ast_agi_unregister(agi_command *cmd)
Unregisters an AGI command.
Definition: res_agi.c:3859
struct agi_state AGI
struct agi_command agi_command
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:3895
Standard Command Line Interface.
#define AST_MAX_CMD_LEN
Definition: cli.h:48
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
Optional API function macros.
#define AST_OPTIONAL_API_UNAVAILABLE
A common value for optional API stub functions to return.
Definition: optional_api.h:74
#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)
Declare an optional API function with compiler attributes.
Definition: optional_api.h:233
#define AST_OPTIONAL_API(result, name, proto, stub)
Declare an optional API function.
Definition: optional_api.h:230
struct agi_command::@181 list
int(*const handler)(struct ast_channel *chan, AGI *agi, int argc, const char *const argv[])
Definition: agi.h:46
const char *const summary
Definition: agi.h:48
struct ast_module * mod
Definition: agi.h:60
enum ast_doc_src docsrc
Definition: agi.h:58
const char *const usage
Definition: agi.h:50
const int dead
Definition: agi.h:52
const char *const seealso
Definition: agi.h:56
const char *const syntax
Definition: agi.h:54
const char *const cmda[AST_MAX_CMD_LEN]
Definition: agi.h:43
Definition: agi.h:34
int ctrl
Definition: agi.h:37
int audio
Definition: agi.h:36
int fd
Definition: agi.h:35
unsigned int fast
Definition: agi.h:38
struct ast_speech * speech
Definition: agi.h:39
Main Channel structure associated with a channel.
Asterisk XML Documentation API.
ast_doc_src
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:30