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

Functions

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


Detailed Description

AGI Extension interfaces - Asterisk Gateway Interface.

Definition in file agi.h.


Typedef Documentation

typedef struct agi_state AGI


Function Documentation

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

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

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

03407 {
03408    char fullcmd[MAX_CMD_LEN];
03409 
03410    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
03411 
03412    if (!find_command(cmd->cmda, 1)) {
03413       *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
03414       if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
03415 #ifdef AST_XML_DOCS
03416          *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd, NULL);
03417          *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd, NULL);
03418          *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd, NULL);
03419          *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd, NULL);
03420          *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
03421 #endif
03422 #ifndef HAVE_NULLSAFE_PRINTF
03423          if (!cmd->summary) {
03424             *((char **) &cmd->summary) = ast_strdup("");
03425          }
03426          if (!cmd->usage) {
03427             *((char **) &cmd->usage) = ast_strdup("");
03428          }
03429          if (!cmd->syntax) {
03430             *((char **) &cmd->syntax) = ast_strdup("");
03431          }
03432          if (!cmd->seealso) {
03433             *((char **) &cmd->seealso) = ast_strdup("");
03434          }
03435 #endif
03436       }
03437 
03438       cmd->mod = mod;
03439       AST_RWLIST_WRLOCK(&agi_commands);
03440       AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
03441       AST_RWLIST_UNLOCK(&agi_commands);
03442       if (mod != ast_module_info->self)
03443          ast_module_ref(ast_module_info->self);
03444       ast_verb(2, "AGI Command '%s' registered\n",fullcmd);
03445       return 1;
03446    } else {
03447       ast_log(LOG_WARNING, "Command already registered!\n");
03448       return 0;
03449    }
03450 }

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

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

Referenced by load_module().

03491 {
03492    unsigned int i, x = 0;
03493 
03494    for (i = 0; i < len; i++) {
03495       if (ast_agi_register(mod, cmd + i) == 1) {
03496          x++;
03497          continue;
03498       }
03499 
03500       /* registration failed, unregister everything
03501          that had been registered up to that point
03502       */
03503       for (; x > 0; x--) {
03504          /* we are intentionally ignoring the
03505             result of ast_agi_unregister() here,
03506             but it should be safe to do so since
03507             we just registered these commands and
03508             the only possible way for unregistration
03509             to fail is if the command is not
03510             registered
03511          */
03512          (void) ast_agi_unregister(mod, cmd + x - 1);
03513       }
03514       return -1;
03515    }
03516 
03517    return 0;
03518 }

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

References agi_buf, AGI_BUF_INITSIZE, 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().

01103 {
01104    int res = 0;
01105    va_list ap;
01106    struct ast_str *buf;
01107 
01108    if (!(buf = ast_str_thread_get(&agi_buf, AGI_BUF_INITSIZE)))
01109       return -1;
01110 
01111    va_start(ap, fmt);
01112    res = ast_str_set_va(&buf, 0, fmt, ap);
01113    va_end(ap);
01114 
01115    if (res == -1) {
01116       ast_log(LOG_ERROR, "Out of memory\n");
01117       return -1;
01118    }
01119 
01120    if (agidebug) {
01121       if (chan) {
01122          ast_verbose("<%s>AGI Tx >> %s", ast_channel_name(chan), ast_str_buffer(buf));
01123       } else {
01124          ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
01125       }
01126    }
01127 
01128    return ast_carefulwrite(fd, ast_str_buffer(buf), ast_str_strlen(buf), 100);
01129 }

int ast_agi_unregister ( struct ast_module mod,
agi_command cmd 
)

Unregisters an AGI command.

Parameters:
mod Pointer to the module_info structure for the module that is unregistering the command
cmd Pointer to the descriptor for the command
Returns:
1 on success, 0 if the command was not already registered

Definition at line 3452 of file res_agi.c.

References ast_free, ast_join, ast_module_unref, 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, e, agi_command::list, MAX_CMD_LEN, agi_command::mod, 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().

03453 {
03454    struct agi_command *e;
03455    int unregistered = 0;
03456    char fullcmd[MAX_CMD_LEN];
03457 
03458    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
03459 
03460    AST_RWLIST_WRLOCK(&agi_commands);
03461    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&agi_commands, e, list) {
03462       if (cmd == e) {
03463          AST_RWLIST_REMOVE_CURRENT(list);
03464          if (mod != ast_module_info->self)
03465             ast_module_unref(ast_module_info->self);
03466 #ifdef AST_XML_DOCS
03467          if (e->docsrc == AST_XML_DOC) {
03468             ast_free((char *) e->summary);
03469             ast_free((char *) e->usage);
03470             ast_free((char *) e->syntax);
03471             ast_free((char *) e->seealso);
03472             *((char **) &e->summary) = NULL;
03473             *((char **) &e->usage) = NULL;
03474             *((char **) &e->syntax) = NULL;
03475             *((char **) &e->seealso) = NULL;
03476          }
03477 #endif
03478          unregistered=1;
03479          break;
03480       }
03481    }
03482    AST_RWLIST_TRAVERSE_SAFE_END;
03483    AST_RWLIST_UNLOCK(&agi_commands);
03484    if (unregistered) {
03485       ast_verb(2, "AGI Command '%s' unregistered\n",fullcmd);
03486    }
03487    return unregistered;
03488 }

int ast_agi_unregister_multiple ( struct ast_module mod,
struct agi_command cmd,
unsigned int  len 
)

Unregisters 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 unregistering 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 unregister, this function will continue to unregister the remaining commands in the array; it will not reregister the already-unregistered commands.

Definition at line 3520 of file res_agi.c.

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

Referenced by unload_module().

03521 {
03522    unsigned int i;
03523    int res = 0;
03524 
03525    for (i = 0; i < len; i++) {
03526       /* remember whether any of the unregistration
03527          attempts failed... there is no recourse if
03528          any of them do
03529       */
03530       res |= ast_agi_unregister(mod, cmd + i);
03531    }
03532 
03533    return res;
03534 }


Generated on Thu Apr 16 06:28:12 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6