agi.h File Reference

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

#include "asterisk/cli.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
Defines
#define	AGI_WEAK
Typedefs
typedef struct 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 2389 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(), LOG_WARNING, and agi_command::mod.

Referenced by ast_agi_register_multiple(), and load_module().

{
   char fullcmd[80];

   ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);

   if (!find_command(cmd->cmda,1)) {
      cmd->mod = mod;
      AST_RWLIST_WRLOCK(&agi_commands);
      AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
      AST_RWLIST_UNLOCK(&agi_commands);
      if (mod != ast_module_info->self)
         ast_module_ref(ast_module_info->self);
      ast_verb(2, "AGI Command '%s' registered\n",fullcmd);
      return 1;
   } else {
      ast_log(LOG_WARNING, "Command already registered!\n");
      return 0;
   }
}

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

References ast_agi_register(), and ast_agi_unregister().

Referenced by load_module().

{
   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(mod, cmd + x - 1);
      }
      return -1;
   }

   return 0;
}

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, LOG_ERROR, ast_str::str, and ast_str::used.

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(), and setup_env().

{
   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", chan->name, buf->str);
      } else {
         ast_verbose("AGI Tx >> %s", buf->str);
      }
   }

   return ast_carefulwrite(fd, buf->str, buf->used, 100);
}

int AGI_WEAK ast_agi_unregister	(	struct ast_module *	mod,
		agi_command *	cmd
	)

Definition at line 2410 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, and LOG_WARNING.

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

{
   struct agi_command *e;
   int unregistered = 0;
   char fullcmd[80];

   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);
         if (mod != ast_module_info->self)
            ast_module_unref(ast_module_info->self);
         unregistered=1;
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&agi_commands);
   if (unregistered)
      ast_verb(2, "AGI Command '%s' unregistered\n",fullcmd);
   else
      ast_log(LOG_WARNING, "Unable to unregister command: '%s'!\n",fullcmd);
   return unregistered;
}

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

References ast_agi_unregister().

Referenced by unload_module().

{
   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(mod, cmd + i);
   }

   return res;
}