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
 

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

3816{
3817 char fullcmd[MAX_CMD_LEN];
3818
3819 ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3820
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;
3830#endif
3831#ifndef HAVE_NULLSAFE_PRINTF
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 }
3844#endif
3845 }
3846
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 }
3857}
#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: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
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_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.

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

3896{
3897 unsigned int i, x = 0;
3898
3899 for (i = 0; i < len; i++) {
3900 if (ast_agi_register(mod, cmd + i) == 1) {
3901 x++;
3902 continue;
3903 }
3904
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 }
3921
3922 return 0;
3923}
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.

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

1482{
1483 int res = 0;
1484 va_list ap;
1485 struct ast_str *buf;
1486
1488 return -1;
1489
1490 va_start(ap, fmt);
1491 res = ast_str_set_va(&buf, 0, fmt, ap);
1492 va_end(ap);
1493
1494 if (res == -1) {
1495 ast_log(LOG_ERROR, "Out of memory\n");
1496 return -1;
1497 }
1498
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 }
1506
1508}
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
#define AGI_BUF_INITSIZE
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.

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

Definition at line 3859 of file res_agi.c.

3860{
3861 struct agi_command *e;
3862 int unregistered = 0;
3863 char fullcmd[MAX_CMD_LEN];
3864
3865 ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3866
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 }
3882#endif
3883 unregistered=1;
3884 break;
3885 }
3886 }
3889 if (unregistered) {
3890 ast_verb(5, "AGI Command '%s' unregistered\n",fullcmd);
3891 }
3892 return unregistered;
3893}
#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 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.

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

3926{
3927 unsigned int i;
3928 int res = 0;
3929
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 }
3937
3938 return res;
3939}

References ast_agi_unregister(), and len().

Referenced by unload_module().