Asterisk - The Open Source Telephony Project GIT-master-f3e88d3
Data Structures | Typedefs | Functions
agi.h File Reference

AGI Extension interfaces - Asterisk Gateway Interface. More...

#include "asterisk/cli.h"
#include "asterisk/xmldoc.h"
#include "asterisk/optional_api.h"
Include dependency graph for agi.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  agi_command
struct  agi_state


typedef struct agi_state AGI
typedef struct agi_command agi_command


int ast_agi_register (struct ast_module *mod, agi_command *cmd)
 Registers an AGI command. More...
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. More...
int ast_agi_send (int fd, struct ast_channel *chan, char *fmt,...)
 Sends a string of text to an application connected via AGI. More...
int ast_agi_unregister (agi_command *cmd)
 Unregisters an AGI command. More...
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. More...

Detailed Description

AGI Extension interfaces - Asterisk Gateway Interface.

Definition in file agi.h.

Typedef Documentation


typedef struct agi_state AGI

◆ agi_command

typedef struct agi_command agi_command

Function Documentation

◆ ast_agi_register()

int ast_agi_register ( struct ast_module mod,
agi_command cmd 

Registers an AGI command.

modPointer to the module_info structure for the module that is registering the command
cmdPointer to the descriptor for the command
Return values
1on success
0the command is already registered
AST_OPTIONAL_API_UNAVAILABLEthe module is not loaded.

Definition at line 3815 of file res_agi.c.

3817 char fullcmd[MAX_CMD_LEN];
3819 ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3821 if (!find_command(cmd->cmda, 1)) {
3822 *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
3823 if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
3824#ifdef AST_XML_DOCS
3825 *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd, NULL);
3826 *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd, NULL);
3827 *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd, NULL);
3828 *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd, NULL);
3829 *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
3832 if (!cmd->summary) {
3833 *((char **) &cmd->summary) = ast_strdup("");
3834 }
3835 if (!cmd->usage) {
3836 *((char **) &cmd->usage) = ast_strdup("");
3837 }
3838 if (!cmd->syntax) {
3839 *((char **) &cmd->syntax) = ast_strdup("");
3840 }
3841 if (!cmd->seealso) {
3842 *((char **) &cmd->seealso) = ast_strdup("");
3843 }
3845 }
3847 cmd->mod = mod;
3851 ast_verb(5, "AGI Command '%s' registered\n",fullcmd);
3852 return 1;
3853 } else {
3854 ast_log(LOG_WARNING, "Command already registered!\n");
3855 return 0;
3856 }
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
#define ast_log
Definition: astobj2.c:42
#define ast_verb(level,...)
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:731
#define MAX_CMD_LEN
Definition: res_agi.c:1384
static agi_command * find_command(const char *const cmds[], int exact)
Definition: res_agi.c:3941
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
#define ast_join(s, len, w)
Join an array of strings into a single string.
Definition: strings.h:520
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 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
char * ast_xmldoc_build_description(const char *type, const char *name, const char *module)
Generate description documentation from XML.
Definition: xmldoc.c:2271
char * ast_xmldoc_build_syntax(const char *type, const char *name, const char *module)
Get the syntax for a specified application or function.
Definition: xmldoc.c:1252
char * ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
Generate synopsis documentation from XML.
Definition: xmldoc.c:2248
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:30
Definition: xmldoc.h:31
Definition: xmldoc.h:32
char * ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
Parse the <see-also> node content.
Definition: xmldoc.c:1702

References ast_join, AST_LIST_INSERT_TAIL, ast_log, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, AST_STATIC_DOC, ast_strdup, ast_strlen_zero(), ast_verb, AST_XML_DOC, ast_xmldoc_build_description(), ast_xmldoc_build_seealso(), ast_xmldoc_build_synopsis(), ast_xmldoc_build_syntax(), find_command(), LOG_WARNING, MAX_CMD_LEN, and NULL.

Referenced by ast_agi_register_multiple(), AST_TEST_DEFINE(), and load_module().

◆ ast_agi_register_multiple()

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.

modPointer to the module_info structure for the module that is registering the commands
cmdPointer to the first entry in the array of command descriptors
lenLength of the array (use the ARRAY_LEN macro to determine this easily)
0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
If any command fails to register, all commands previously registered during the operation will be unregistered. In other words, this function registers all the provided commands, or none of them.

Definition at line 3895 of file res_agi.c.

3897 unsigned int i, x = 0;
3899 for (i = 0; i < len; i++) {
3900 if (ast_agi_register(mod, cmd + i) == 1) {
3901 x++;
3902 continue;
3903 }
3905 /* registration failed, unregister everything
3906 that had been registered up to that point
3907 */
3908 for (; x > 0; x--) {
3909 /* we are intentionally ignoring the
3910 result of ast_agi_unregister() here,
3911 but it should be safe to do so since
3912 we just registered these commands and
3913 the only possible way for unregistration
3914 to fail is if the command is not
3915 registered
3916 */
3917 (void) ast_agi_unregister(cmd + x - 1);
3918 }
3919 return -1;
3920 }
3922 return 0;
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
int AST_OPTIONAL_API_NAME() ast_agi_unregister(agi_command *cmd)
Unregisters an AGI command.
Definition: res_agi.c:3859
int AST_OPTIONAL_API_NAME() ast_agi_register(struct ast_module *mod, agi_command *cmd)
Registers an AGI command.
Definition: res_agi.c:3815

References ast_agi_register(), ast_agi_unregister(), len(), and agi_command::mod.

Referenced by load_module().

◆ ast_agi_send()

int ast_agi_send ( int  fd,
struct ast_channel chan,
char *  fmt,

Sends a string of text to an application connected via AGI.

fdThe file descriptor for the AGI session (from struct agi_state)
chanPointer to an associated Asterisk channel, if any
fmtprintf-style format string
0 for success, -1 for failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded

Definition at line 1481 of file res_agi.c.

1483 int res = 0;
1484 va_list ap;
1485 struct ast_str *buf;
1488 return -1;
1490 va_start(ap, fmt);
1491 res = ast_str_set_va(&buf, 0, fmt, ap);
1492 va_end(ap);
1494 if (res == -1) {
1495 ast_log(LOG_ERROR, "Out of memory\n");
1496 return -1;
1497 }
1499 if (agidebug) {
1500 if (chan) {
1501 ast_verbose("<%s>AGI Tx >> %s", ast_channel_name(chan), ast_str_buffer(buf));
1502 } else {
1503 ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
1504 }
1505 }
const char * ast_channel_name(const struct ast_channel *chan)
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
void ast_verbose(const char *fmt,...)
Definition: extconf.c:2206
#define LOG_ERROR
static struct ast_threadstorage agi_buf
Definition: res_agi.c:1478
static int agidebug
Definition: res_agi.c:1395
Definition: res_agi.c:1479
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
int ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap)
Set a dynamic string from a va_list.
Definition: strings.h:1030
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:730
struct ast_str * ast_str_thread_get(struct ast_threadstorage *ts, size_t init_len)
Retrieve a thread locally stored dynamic string.
Definition: strings.h:909
Support for dynamic strings.
Definition: strings.h:623
int ast_carefulwrite(int fd, char *s, int len, int timeoutms)
Try to write string, but wait no more than ms milliseconds before timing out.
Definition: utils.c:1771

References agi_buf, AGI_BUF_INITSIZE, agidebug, ast_carefulwrite(), ast_channel_name(), ast_log, ast_str_buffer(), ast_str_set_va(), ast_str_strlen(), ast_str_thread_get(), ast_verbose(), buf, and LOG_ERROR.

Referenced by agi_handle_command(), handle_answer(), handle_asyncagi_break(), handle_autohangup(), handle_channelstatus(), handle_controlstreamfile(), handle_dbdel(), handle_dbdeltree(), handle_dbget(), handle_dbput(), handle_exec(), handle_getdata(), handle_getoption(), handle_getvariable(), handle_getvariablefull(), handle_gosub(), handle_hangup(), handle_noop(), handle_recordfile(), handle_recvchar(), handle_recvtext(), handle_sayalpha(), handle_saydate(), handle_saydatetime(), handle_saydigits(), handle_saynumber(), handle_sayphonetic(), handle_saytime(), handle_sendimage(), handle_sendtext(), handle_setcallerid(), handle_setcontext(), handle_setextension(), handle_setmusic(), handle_setpriority(), handle_setvariable(), handle_speechactivategrammar(), handle_speechcreate(), handle_speechdeactivategrammar(), handle_speechdestroy(), handle_speechloadgrammar(), handle_speechrecognize(), handle_speechset(), handle_speechunloadgrammar(), handle_streamfile(), handle_tddmode(), handle_verbose(), handle_waitfordigit(), launch_netscript(), run_agi(), and setup_env().

◆ ast_agi_unregister()

int ast_agi_unregister ( agi_command cmd)

Unregisters an AGI command.

cmdPointer to the descriptor for the command
1 on success, 0 if the command was not already registered

Definition at line 3859 of file res_agi.c.

3861 struct agi_command *e;
3862 int unregistered = 0;
3863 char fullcmd[MAX_CMD_LEN];
3865 ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3869 if (cmd == e) {
3871#ifdef AST_XML_DOCS
3872 if (e->docsrc == AST_XML_DOC) {
3873 ast_free((char *) e->summary);
3874 ast_free((char *) e->usage);
3875 ast_free((char *) e->syntax);
3876 ast_free((char *) e->seealso);
3877 *((char **) &e->summary) = NULL;
3878 *((char **) &e->usage) = NULL;
3879 *((char **) &e->syntax) = NULL;
3880 *((char **) &e->seealso) = NULL;
3881 }
3883 unregistered=1;
3884 break;
3885 }
3886 }
3889 if (unregistered) {
3890 ast_verb(5, "AGI Command '%s' unregistered\n",fullcmd);
3891 }
3892 return unregistered;
#define ast_free(a)
Definition: astmm.h:180
Definition: linkedlists.h:570
Definition: linkedlists.h:545
Definition: linkedlists.h:617
struct agi_command::@181 list

References ast_free, ast_join, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verb, AST_XML_DOC, agi_command::docsrc, agi_command::list, MAX_CMD_LEN, NULL, agi_command::seealso, agi_command::summary, agi_command::syntax, and agi_command::usage.

Referenced by ast_agi_register_multiple(), ast_agi_unregister_multiple(), AST_TEST_DEFINE(), and unload_module().

◆ ast_agi_unregister_multiple()

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.

cmdPointer to the first entry in the array of command descriptors
lenLength of the array (use the ARRAY_LEN macro to determine this easily)
0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
If any command fails to unregister, this function will continue to unregister the remaining commands in the array; it will not reregister the already-unregistered commands.

Definition at line 3925 of file res_agi.c.

3927 unsigned int i;
3928 int res = 0;
3930 for (i = 0; i < len; i++) {
3931 /* remember whether any of the unregistration
3932 attempts failed... there is no recourse if
3933 any of them do
3934 */
3935 res |= ast_agi_unregister(cmd + i);
3936 }
3938 return res;

References ast_agi_unregister(), and len().

Referenced by unload_module().