Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
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 3823 of file res_agi.c.

3824{
3825 char fullcmd[MAX_CMD_LEN];
3826
3827 ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3828
3829 if (!find_command(cmd->cmda, 1)) {
3830 *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
3831 if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
3832#ifdef AST_XML_DOCS
3833 *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd, NULL);
3834 *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd, NULL);
3835 *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd, NULL);
3836 *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd, NULL);
3837 *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
3838#endif
3839#ifndef HAVE_NULLSAFE_PRINTF
3840 if (!cmd->summary) {
3841 *((char **) &cmd->summary) = ast_strdup("");
3842 }
3843 if (!cmd->usage) {
3844 *((char **) &cmd->usage) = ast_strdup("");
3845 }
3846 if (!cmd->syntax) {
3847 *((char **) &cmd->syntax) = ast_strdup("");
3848 }
3849 if (!cmd->seealso) {
3850 *((char **) &cmd->seealso) = ast_strdup("");
3851 }
3852#endif
3853 }
3854
3855 cmd->mod = mod;
3859 ast_verb(5, "AGI Command '%s' registered\n",fullcmd);
3860 return 1;
3861 } else {
3862 ast_log(LOG_WARNING, "Command already registered!\n");
3863 return 0;
3864 }
3865}
#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:3949
#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 3903 of file res_agi.c.

3904{
3905 unsigned int i, x = 0;
3906
3907 for (i = 0; i < len; i++) {
3908 if (ast_agi_register(mod, cmd + i) == 1) {
3909 x++;
3910 continue;
3911 }
3912
3913 /* registration failed, unregister everything
3914 that had been registered up to that point
3915 */
3916 for (; x > 0; x--) {
3917 /* we are intentionally ignoring the
3918 result of ast_agi_unregister() here,
3919 but it should be safe to do so since
3920 we just registered these commands and
3921 the only possible way for unregistration
3922 to fail is if the command is not
3923 registered
3924 */
3925 (void) ast_agi_unregister(cmd + x - 1);
3926 }
3927 return -1;
3928 }
3929
3930 return 0;
3931}
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:3867
int AST_OPTIONAL_API_NAME() ast_agi_register(struct ast_module *mod, agi_command *cmd)
Registers an AGI command.
Definition: res_agi.c:3823

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

3868{
3869 struct agi_command *e;
3870 int unregistered = 0;
3871 char fullcmd[MAX_CMD_LEN];
3872
3873 ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3874
3877 if (cmd == e) {
3879#ifdef AST_XML_DOCS
3880 if (e->docsrc == AST_XML_DOC) {
3881 ast_free((char *) e->summary);
3882 ast_free((char *) e->usage);
3883 ast_free((char *) e->syntax);
3884 ast_free((char *) e->seealso);
3885 *((char **) &e->summary) = NULL;
3886 *((char **) &e->usage) = NULL;
3887 *((char **) &e->syntax) = NULL;
3888 *((char **) &e->seealso) = NULL;
3889 }
3890#endif
3891 unregistered=1;
3892 break;
3893 }
3894 }
3897 if (unregistered) {
3898 ast_verb(5, "AGI Command '%s' unregistered\n",fullcmd);
3899 }
3900 return unregistered;
3901}
#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 3933 of file res_agi.c.

3934{
3935 unsigned int i;
3936 int res = 0;
3937
3938 for (i = 0; i < len; i++) {
3939 /* remember whether any of the unregistration
3940 attempts failed... there is no recourse if
3941 any of them do
3942 */
3943 res |= ast_agi_unregister(cmd + i);
3944 }
3945
3946 return res;
3947}

References ast_agi_unregister(), and len().

Referenced by unload_module().