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

mod	Pointer to the module_info structure for the module that is registering the command
cmd	Pointer to the descriptor for the command

Return values

1	on success
0	the command is already registered
AST_OPTIONAL_API_UNAVAILABLE	the module is not loaded.

Definition at line 3954 of file res_agi.c.

{
    char fullcmd[MAX_CMD_LEN];
 
    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
 
    if (!find_command(cmd->cmda, 1)) {
        *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
        if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
#ifdef AST_XML_DOCS
            *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd, NULL);
            *((char **) &cmd->since) = ast_xmldoc_build_since("agi", fullcmd, NULL);
            *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd, NULL);
            *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd, NULL);
            *((char **) &cmd->arguments) = ast_xmldoc_build_arguments("agi", fullcmd, NULL);
            *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd, NULL);
            *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
#endif
#ifndef HAVE_NULLSAFE_PRINTF
            if (!cmd->summary) {
                *((char **) &cmd->summary) = ast_strdup("");
            }
            if (!cmd->usage) {
                *((char **) &cmd->usage) = ast_strdup("");
            }
            if (!cmd->syntax) {
                *((char **) &cmd->syntax) = ast_strdup("");
            }
            if (!cmd->seealso) {
                *((char **) &cmd->seealso) = ast_strdup("");
            }
#endif
        }
 
        cmd->mod = mod;
        AST_RWLIST_WRLOCK(&agi_commands);
        AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
        AST_RWLIST_UNLOCK(&agi_commands);
        ast_verb(5, "AGI Command '%s' registered\n",fullcmd);
        return 1;
    } else {
        ast_log(LOG_WARNING, "Command already registered!\n");
        return 0;
    }
}

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

mod	Pointer to the module_info structure for the module that is registering the commands
cmd	Pointer to the first entry in the array of command descriptors
len	Length 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 4040 of file res_agi.c.

{
    unsigned int i, x = 0;
 
    for (i = 0; i < len; i++) {
        if (ast_agi_register(mod, cmd + i) == 1) {
            x++;
            continue;
        }
 
        /* registration failed, unregister everything
           that had been registered up to that point
        */
        for (; x > 0; x--) {
            /* we are intentionally ignoring the
               result of ast_agi_unregister() here,
               but it should be safe to do so since
               we just registered these commands and
               the only possible way for unregistration
               to fail is if the command is not
               registered
            */
            (void) ast_agi_unregister(cmd + x - 1);
        }
        return -1;
    }
 
    return 0;
}

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

fd	The file descriptor for the AGI session (from struct agi_state)
chan	Pointer to an associated Asterisk channel, if any
fmt	printf-style format string

Returns

0 for success, -1 for failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded

Definition at line 1612 of file res_agi.c.

{
    int res = 0;
    va_list ap;
    struct ast_str *buf;
 
    if (!(buf = ast_str_thread_get(&agi_buf, AGI_BUF_INITSIZE)))
        return -1;
 
    va_start(ap, fmt);
    res = ast_str_set_va(&buf, 0, fmt, ap);
    va_end(ap);
 
    if (res == -1) {
        ast_log(LOG_ERROR, "Out of memory\n");
        return -1;
    }
 
    if (agidebug) {
        if (chan) {
            ast_verbose("<%s>AGI Tx >> %s", ast_channel_name(chan), ast_str_buffer(buf));
        } else {
            ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
        }
    }
 
    return ast_carefulwrite(fd, ast_str_buffer(buf), ast_str_strlen(buf), 100);
}

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

cmd	Pointer to the descriptor for the command

Returns

1 on success, 0 if the command was not already registered

Definition at line 4000 of file res_agi.c.

{
    struct agi_command *e;
    int unregistered = 0;
    char fullcmd[MAX_CMD_LEN];
 
    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
 
    AST_RWLIST_WRLOCK(&agi_commands);
    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&agi_commands, e, list) {
        if (cmd == e) {
            AST_RWLIST_REMOVE_CURRENT(list);
#ifdef AST_XML_DOCS
            if (e->docsrc == AST_XML_DOC) {
                ast_free((char *) e->summary);
                ast_free((char *) e->since);
                ast_free((char *) e->usage);
                ast_free((char *) e->syntax);
                ast_free((char *) e->arguments);
                ast_free((char *) e->seealso);
                *((char **) &e->summary) = NULL;
                *((char **) &e->since) = NULL;
                *((char **) &e->usage) = NULL;
                *((char **) &e->syntax) = NULL;
                *((char **) &e->arguments) = NULL;
                *((char **) &e->seealso) = NULL;
            }
#endif
            unregistered=1;
            break;
        }
    }
    AST_RWLIST_TRAVERSE_SAFE_END;
    AST_RWLIST_UNLOCK(&agi_commands);
    if (unregistered) {
        ast_verb(5, "AGI Command '%s' unregistered\n",fullcmd);
    }
    return unregistered;
}

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

cmd	Pointer to the first entry in the array of command descriptors
len	Length 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 4070 of file res_agi.c.

{
    unsigned int i;
    int res = 0;
 
    for (i = 0; i < len; i++) {
        /* remember whether any of the unregistration
           attempts failed... there is no recourse if
           any of them do
        */
        res |= ast_agi_unregister(cmd + i);
    }
 
    return res;
}

References ast_agi_unregister(), and len().

Referenced by unload_module().