Mon Mar 19 11:30:31 2012

Asterisk developer's documentation


agi.h File Reference

AGI Extension interfaces - Asterisk Gateway Interface. More...

#include "asterisk/cli.h"
#include "asterisk/xmldoc.h"
#include "asterisk/optional_api.h"

Go to the source code of this file.

Data Structures

struct  agi_command
struct  agi_state

Typedefs

typedef 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 3118 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, ast_xmldoc_build_description(), ast_xmldoc_build_seealso(), ast_xmldoc_build_synopsis(), ast_xmldoc_build_syntax(), find_command(), LOG_WARNING, and MAX_CMD_LEN.

Referenced by ast_agi_register_multiple(), and load_module().

03119 {
03120    char fullcmd[MAX_CMD_LEN];
03121 
03122    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
03123 
03124    if (!find_command(cmd->cmda, 1)) {
03125       *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
03126       if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
03127 #ifdef AST_XML_DOCS
03128          *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd, NULL);
03129          *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd, NULL);
03130          *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd, NULL);
03131          *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd, NULL);
03132          *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
03133 #endif
03134 #ifndef HAVE_NULLSAFE_PRINTF
03135          if (!cmd->summary) {
03136             *((char **) &cmd->summary) = ast_strdup("");
03137          }
03138          if (!cmd->usage) {
03139             *((char **) &cmd->usage) = ast_strdup("");
03140          }
03141          if (!cmd->syntax) {
03142             *((char **) &cmd->syntax) = ast_strdup("");
03143          }
03144          if (!cmd->seealso) {
03145             *((char **) &cmd->seealso) = ast_strdup("");
03146          }
03147 #endif
03148       }
03149 
03150       cmd->mod = mod;
03151       AST_RWLIST_WRLOCK(&agi_commands);
03152       AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
03153       AST_RWLIST_UNLOCK(&agi_commands);
03154       if (mod != ast_module_info->self)
03155          ast_module_ref(ast_module_info->self);
03156       ast_verb(2, "AGI Command '%s' registered\n",fullcmd);
03157       return 1;
03158    } else {
03159       ast_log(LOG_WARNING, "Command already registered!\n");
03160       return 0;
03161    }
03162 }

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

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

Referenced by load_module().

03204 {
03205    unsigned int i, x = 0;
03206 
03207    for (i = 0; i < len; i++) {
03208       if (ast_agi_register(mod, cmd + i) == 1) {
03209          x++;
03210          continue;
03211       }
03212 
03213       /* registration failed, unregister everything
03214          that had been registered up to that point
03215       */
03216       for (; x > 0; x--) {
03217          /* we are intentionally ignoring the
03218             result of ast_agi_unregister() here,
03219             but it should be safe to do so since
03220             we just registered these commands and
03221             the only possible way for unregistration
03222             to fail is if the command is not
03223             registered
03224          */
03225          (void) ast_agi_unregister(mod, cmd + x - 1);
03226       }
03227       return -1;
03228    }
03229 
03230    return 0;
03231 }

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

References agi_buf, AGI_BUF_INITSIZE, ast_carefulwrite(), ast_log(), ast_str_buffer(), ast_str_set_va(), ast_str_strlen(), ast_str_thread_get(), ast_verbose, 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().

00940 {
00941    int res = 0;
00942    va_list ap;
00943    struct ast_str *buf;
00944 
00945    if (!(buf = ast_str_thread_get(&agi_buf, AGI_BUF_INITSIZE)))
00946       return -1;
00947 
00948    va_start(ap, fmt);
00949    res = ast_str_set_va(&buf, 0, fmt, ap);
00950    va_end(ap);
00951 
00952    if (res == -1) {
00953       ast_log(LOG_ERROR, "Out of memory\n");
00954       return -1;
00955    }
00956 
00957    if (agidebug) {
00958       if (chan) {
00959          ast_verbose("<%s>AGI Tx >> %s", chan->name, ast_str_buffer(buf));
00960       } else {
00961          ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
00962       }
00963    }
00964 
00965    return ast_carefulwrite(fd, ast_str_buffer(buf), ast_str_strlen(buf), 100);
00966 }

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

References ast_free, ast_join(), ast_log(), 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, LOG_WARNING, and MAX_CMD_LEN.

Referenced by ast_agi_register_multiple(), ast_agi_unregister_multiple(), and unload_module().

03165 {
03166    struct agi_command *e;
03167    int unregistered = 0;
03168    char fullcmd[MAX_CMD_LEN];
03169 
03170    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
03171 
03172    AST_RWLIST_WRLOCK(&agi_commands);
03173    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&agi_commands, e, list) {
03174       if (cmd == e) {
03175          AST_RWLIST_REMOVE_CURRENT(list);
03176          if (mod != ast_module_info->self)
03177             ast_module_unref(ast_module_info->self);
03178 #ifdef AST_XML_DOCS
03179          if (e->docsrc == AST_XML_DOC) {
03180             ast_free((char *) e->summary);
03181             ast_free((char *) e->usage);
03182             ast_free((char *) e->syntax);
03183             ast_free((char *) e->seealso);
03184             *((char **) &e->summary) = NULL;
03185             *((char **) &e->usage) = NULL;
03186             *((char **) &e->syntax) = NULL;
03187             *((char **) &e->seealso) = NULL;
03188          }
03189 #endif
03190          unregistered=1;
03191          break;
03192       }
03193    }
03194    AST_RWLIST_TRAVERSE_SAFE_END;
03195    AST_RWLIST_UNLOCK(&agi_commands);
03196    if (unregistered)
03197       ast_verb(2, "AGI Command '%s' unregistered\n",fullcmd);
03198    else
03199       ast_log(LOG_WARNING, "Unable to unregister command: '%s'!\n",fullcmd);
03200    return unregistered;
03201 }

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

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

Referenced by unload_module().

03234 {
03235    unsigned int i;
03236    int res = 0;
03237 
03238    for (i = 0; i < len; i++) {
03239       /* remember whether any of the unregistration
03240          attempts failed... there is no recourse if
03241          any of them do
03242       */
03243       res |= ast_agi_unregister(mod, cmd + i);
03244    }
03245 
03246    return res;
03247 }


Generated on Mon Mar 19 11:30:31 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7