Asterisk - The Open Source Telephony Project GIT-master-66c01d8
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
 

Typedefs

typedef struct agi_state AGI
 
typedef struct agi_command agi_command
 

Functions

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

◆ AGI

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.

Parameters
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 3988 of file res_agi.c.

3989{
3990 char fullcmd[MAX_CMD_LEN];
3991
3992 ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3993
3994 if (!find_command(cmd->cmda, 1)) {
3995 *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
3996 if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
3997#ifdef AST_XML_DOCS
3998 *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd, NULL);
3999 *((char **) &cmd->since) = ast_xmldoc_build_since("agi", fullcmd, NULL);
4000 *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd, NULL);
4001 *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd, NULL);
4002 *((char **) &cmd->arguments) = ast_xmldoc_build_arguments("agi", fullcmd, NULL);
4003 *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd, NULL);
4004 *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
4005#endif
4006#ifndef HAVE_NULLSAFE_PRINTF
4007 if (!cmd->summary) {
4008 *((char **) &cmd->summary) = ast_strdup("");
4009 }
4010 if (!cmd->usage) {
4011 *((char **) &cmd->usage) = ast_strdup("");
4012 }
4013 if (!cmd->syntax) {
4014 *((char **) &cmd->syntax) = ast_strdup("");
4015 }
4016 if (!cmd->seealso) {
4017 *((char **) &cmd->seealso) = ast_strdup("");
4018 }
4019#endif
4020 }
4021
4022 cmd->mod = mod;
4026 ast_verb(5, "AGI Command '%s' registered\n",fullcmd);
4027 return 1;
4028 } else {
4029 ast_log(LOG_WARNING, "Command already registered!\n");
4030 return 0;
4031 }
4032}
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
#define ast_log
Definition: astobj2.c:42
#define ast_verb(level,...)
#define LOG_WARNING
#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:1549
static agi_command * find_command(const char *const cmds[], int exact)
Definition: res_agi.c:4120
#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 since
Definition: agi.h:64
const char *const summary
Definition: agi.h:48
const char *const arguments
Definition: agi.h:66
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:2356
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_arguments(const char *type, const char *name, const char *module)
Generate the [arguments] tag based on type of node ('application', 'function' or 'agi') and name.
Definition: xmldoc.c:2169
char * ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
Generate synopsis documentation from XML.
Definition: xmldoc.c:2333
char * ast_xmldoc_build_since(const char *type, const char *name, const char *module)
Parse the <since> node content.
Definition: xmldoc.c:1787
ast_doc_src
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:30
@ AST_XML_DOC
Definition: xmldoc.h:31
@ AST_STATIC_DOC
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_arguments(), ast_xmldoc_build_description(), ast_xmldoc_build_seealso(), ast_xmldoc_build_since(), 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.

Parameters
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)
Returns
0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
Note
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 4074 of file res_agi.c.

4075{
4076 unsigned int i, x = 0;
4077
4078 for (i = 0; i < len; i++) {
4079 if (ast_agi_register(mod, cmd + i) == 1) {
4080 x++;
4081 continue;
4082 }
4083
4084 /* registration failed, unregister everything
4085 that had been registered up to that point
4086 */
4087 for (; x > 0; x--) {
4088 /* we are intentionally ignoring the
4089 result of ast_agi_unregister() here,
4090 but it should be safe to do so since
4091 we just registered these commands and
4092 the only possible way for unregistration
4093 to fail is if the command is not
4094 registered
4095 */
4096 (void) ast_agi_unregister(cmd + x - 1);
4097 }
4098 return -1;
4099 }
4100
4101 return 0;
4102}
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:4034
int AST_OPTIONAL_API_NAME() ast_agi_register(struct ast_module *mod, agi_command *cmd)
Registers an AGI command.
Definition: res_agi.c:3988

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.

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

Definition at line 1646 of file res_agi.c.

1647{
1648 int res = 0;
1649 va_list ap;
1650 struct ast_str *buf;
1651
1653 return -1;
1654
1655 va_start(ap, fmt);
1656 res = ast_str_set_va(&buf, 0, fmt, ap);
1657 va_end(ap);
1658
1659 if (res == -1) {
1660 ast_log(LOG_ERROR, "Out of memory\n");
1661 return -1;
1662 }
1663
1664 if (agidebug) {
1665 if (chan) {
1666 ast_verbose("<%s>AGI Tx >> %s", ast_channel_name(chan), ast_str_buffer(buf));
1667 } else {
1668 ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
1669 }
1670 }
1671
1673}
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:1643
static int agidebug
Definition: res_agi.c:1560
#define AGI_BUF_INITSIZE
Definition: res_agi.c:1644
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.

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

Definition at line 4034 of file res_agi.c.

4035{
4036 struct agi_command *e;
4037 int unregistered = 0;
4038 char fullcmd[MAX_CMD_LEN];
4039
4040 ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
4041
4044 if (cmd == e) {
4046#ifdef AST_XML_DOCS
4047 if (e->docsrc == AST_XML_DOC) {
4048 ast_free((char *) e->summary);
4049 ast_free((char *) e->since);
4050 ast_free((char *) e->usage);
4051 ast_free((char *) e->syntax);
4052 ast_free((char *) e->arguments);
4053 ast_free((char *) e->seealso);
4054 *((char **) &e->summary) = NULL;
4055 *((char **) &e->since) = NULL;
4056 *((char **) &e->usage) = NULL;
4057 *((char **) &e->syntax) = NULL;
4058 *((char **) &e->arguments) = NULL;
4059 *((char **) &e->seealso) = NULL;
4060 }
4061#endif
4062 unregistered=1;
4063 break;
4064 }
4065 }
4068 if (unregistered) {
4069 ast_verb(5, "AGI Command '%s' unregistered\n",fullcmd);
4070 }
4071 return unregistered;
4072}
#define ast_free(a)
Definition: astmm.h:180
#define AST_RWLIST_REMOVE_CURRENT
Definition: linkedlists.h:570
#define AST_RWLIST_TRAVERSE_SAFE_BEGIN
Definition: linkedlists.h:545
#define AST_RWLIST_TRAVERSE_SAFE_END
Definition: linkedlists.h:617
struct agi_command::@181 list

References agi_command::arguments, 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::since, 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.

Parameters
cmdPointer to the first entry in the array of command descriptors
lenLength of the array (use the ARRAY_LEN macro to determine this easily)
Returns
0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded
Note
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 4104 of file res_agi.c.

4105{
4106 unsigned int i;
4107 int res = 0;
4108
4109 for (i = 0; i < len; i++) {
4110 /* remember whether any of the unregistration
4111 attempts failed... there is no recourse if
4112 any of them do
4113 */
4114 res |= ast_agi_unregister(cmd + i);
4115 }
4116
4117 return res;
4118}

References ast_agi_unregister(), and len().

Referenced by unload_module().