Fri Jun 19 12:09:55 2009

Asterisk developer's documentation


agi.h File Reference

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

#include "asterisk/cli.h"

Go to the source code of this file.

Data Structures

struct  agi_command
struct  agi_state

Defines

#define AGI_WEAK

Typedefs

typedef agi_state AGI

Functions

int AGI_WEAK ast_agi_register (struct ast_module *mod, agi_command *cmd)
int AGI_WEAK 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 AGI_WEAK ast_agi_send (int fd, struct ast_channel *chan, char *fmt,...)
 Sends a string of text to an application connected via AGI.
int AGI_WEAK ast_agi_unregister (struct ast_module *mod, agi_command *cmd)
int AGI_WEAK 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.


Define Documentation

#define AGI_WEAK

Definition at line 61 of file agi.h.


Typedef Documentation

typedef struct agi_state AGI


Function Documentation

int AGI_WEAK ast_agi_register ( struct ast_module mod,
agi_command cmd 
)

Definition at line 2369 of file res_agi.c.

References ast_join(), AST_LIST_INSERT_TAIL, ast_log(), ast_module_ref(), AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verb, agi_command::cmda, find_command(), agi_command::list, LOG_WARNING, and agi_command::mod.

Referenced by ast_agi_register_multiple(), and load_module().

02370 {
02371    char fullcmd[80];
02372 
02373    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
02374 
02375    if (!find_command(cmd->cmda,1)) {
02376       cmd->mod = mod;
02377       AST_RWLIST_WRLOCK(&agi_commands);
02378       AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
02379       AST_RWLIST_UNLOCK(&agi_commands);
02380       if (mod != ast_module_info->self)
02381          ast_module_ref(ast_module_info->self);
02382       ast_verb(2, "AGI Command '%s' registered\n",fullcmd);
02383       return 1;
02384    } else {
02385       ast_log(LOG_WARNING, "Command already registered!\n");
02386       return 0;
02387    }
02388 }

int AGI_WEAK 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 commands
len Length of the array (use the ARRAY_LEN macro to determine this easily)
Returns:
0 on success, -1 on failure
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 2417 of file res_agi.c.

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

Referenced by load_module().

02418 {
02419    unsigned int i, x = 0;
02420 
02421    for (i = 0; i < len; i++) {
02422       if (ast_agi_register(mod, cmd + i) == 1) {
02423          x++;
02424          continue;
02425       }
02426 
02427       /* registration failed, unregister everything
02428          that had been registered up to that point
02429       */
02430       for (; x > 0; x--) {
02431          /* we are intentionally ignoring the
02432             result of ast_agi_unregister() here,
02433             but it should be safe to do so since
02434             we just registered these commands and
02435             the only possible way for unregistration
02436             to fail is if the command is not
02437             registered
02438          */
02439          (void) ast_agi_unregister(mod, cmd + x - 1);
02440       }
02441       return -1;
02442    }
02443 
02444    return 0;
02445 }

int AGI_WEAK 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

Definition at line 118 of file res_agi.c.

References agi_buf, AGI_BUF_INITSIZE, ast_carefulwrite(), ast_log(), ast_str_set_va(), ast_str_thread_get(), ast_verbose, buf, chan, and LOG_ERROR.

Referenced by agi_handle_command(), handle_answer(), 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(), and setup_env().

00119 {
00120    int res = 0;
00121    va_list ap;
00122    struct ast_str *buf;
00123 
00124    if (!(buf = ast_str_thread_get(&agi_buf, AGI_BUF_INITSIZE)))
00125       return -1;
00126 
00127    va_start(ap, fmt);
00128    res = ast_str_set_va(&buf, 0, fmt, ap);
00129    va_end(ap);
00130 
00131    if (res == -1) {
00132       ast_log(LOG_ERROR, "Out of memory\n");
00133       return -1;
00134    }
00135 
00136    if (agidebug) {
00137       if (chan) {
00138          ast_verbose("<%s>AGI Tx >> %s", chan->name, buf->str);
00139       } else {
00140          ast_verbose("AGI Tx >> %s", buf->str);
00141       }
00142    }
00143 
00144    return ast_carefulwrite(fd, buf->str, buf->used, 100);
00145 }

int AGI_WEAK ast_agi_unregister ( struct ast_module mod,
agi_command cmd 
)

Definition at line 2390 of file res_agi.c.

References 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, agi_command::cmda, agi_command::list, LOG_WARNING, and agi_command::mod.

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

02391 {
02392    struct agi_command *e;
02393    int unregistered = 0;
02394    char fullcmd[80];
02395 
02396    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
02397 
02398    AST_RWLIST_WRLOCK(&agi_commands);
02399    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&agi_commands, e, list) {
02400       if (cmd == e) {
02401          AST_RWLIST_REMOVE_CURRENT(list);
02402          if (mod != ast_module_info->self)
02403             ast_module_unref(ast_module_info->self);
02404          unregistered=1;
02405          break;
02406       }
02407    }
02408    AST_RWLIST_TRAVERSE_SAFE_END;
02409    AST_RWLIST_UNLOCK(&agi_commands);
02410    if (unregistered)
02411       ast_verb(2, "AGI Command '%s' unregistered\n",fullcmd);
02412    else
02413       ast_log(LOG_WARNING, "Unable to unregister command: '%s'!\n",fullcmd);
02414    return unregistered;
02415 }

int AGI_WEAK 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 commands
len Length of the array (use the ARRAY_LEN macro to determine this easily)
Returns:
0 on success, -1 on failure
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 2447 of file res_agi.c.

References ast_agi_unregister(), and agi_command::mod.

Referenced by unload_module().

02448 {
02449    unsigned int i;
02450    int res = 0;
02451 
02452    for (i = 0; i < len; i++) {
02453       /* remember whether any of the unregistration
02454          attempts failed... there is no recourse if
02455          any of them do
02456       */
02457       res |= ast_agi_unregister(mod, cmd + i);
02458    }
02459 
02460    return res;
02461 }


Generated on Fri Jun 19 12:09:55 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7