Sat Oct 11 06:50:10 2008

Asterisk developer's documentation

---

app_externalivr.c File Reference

External IVR application interface. More...

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <errno.h>
#include <signal.h>
#include "asterisk.h"
#include "asterisk/lock.h"
#include "asterisk/file.h"
#include "asterisk/logger.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/module.h"
#include "asterisk/linkedlists.h"
#include "asterisk/app.h"
#include "asterisk/options.h"

Include dependency graph for app_externalivr.c:

Go to the source code of this file.

Data Structures
struct	gen_state
struct	localuser
	We define a custom "local user" structure because we use it not only for keeping track of what is in use but also for keeping track of who we're dialing. More...
struct	playlist_entry
Defines
#define	ast_chan_log(level, channel, format,...)   ast_log(level, "%s: " format, channel->name , ## __VA_ARGS__)
Functions
static int	app_exec (struct ast_channel *chan, void *data)
char *	description (void)
	Provides a description of the module.
static void *	gen_alloc (struct ast_channel *chan, void *params)
static void	gen_closestream (struct gen_state *state)
static int	gen_generate (struct ast_channel *chan, void *data, int len, int samples)
static int	gen_nextfile (struct gen_state *state)
static struct ast_frame *	gen_readframe (struct gen_state *state)
static void	gen_release (struct ast_channel *chan, void *data)
char *	key ()
	Returns the ASTERISK_GPL_KEY.
int	load_module (void)
	Initialize the module.
static struct playlist_entry *	make_entry (const char *filename)
static void	send_child_event (FILE *handle, const char event, const char *data, const struct ast_channel *chan)
int	unload_module (void)
	Cleanup all module structures, sockets, etc.
int	usecount (void)
	Provides a usecount.
Variables
static const char *	app = "ExternalIVR"
static const char *	descrip
static struct ast_generator	gen
	LOCAL_USER_DECL
static const char *	synopsis = "Interfaces with an external IVR application"
static const char *	tdesc = "External IVR Interface Application"

---

Detailed Description

External IVR application interface.

Definition in file app_externalivr.c.

---

Define Documentation

#define ast_chan_log	(	level,
		channel,
		format,
		...		)	ast_log(level, "%s: " format, channel->name , ## __VA_ARGS__)

Definition at line 67 of file app_externalivr.c.

Referenced by app_exec(), gen_generate(), gen_nextfile(), and send_child_event().

---

Function Documentation

static int app_exec	(	struct ast_channel *	chan,
		void *	data
	)			[static]

Definition at line 245 of file app_externalivr.c.

References ast_channel::_state, ast_activate_generator(), ast_answer(), ast_app_separate_args(), ast_chan_log, ast_check_hangup(), AST_CONTROL_HANGUP, ast_deactivate_generator(), ast_fileexists(), AST_FLAG_ZOMBIE, AST_FRAME_CONTROL, AST_FRAME_DTMF, ast_frfree(), AST_LIST_EMPTY, AST_LIST_HEAD_INIT, AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_REMOVE_HEAD, AST_LIST_UNLOCK, ast_log(), ast_read(), ast_set_priority(), AST_STATE_UP, ast_strdupa, ast_strlen_zero(), ast_test_flag, ast_waitfor_nandfds(), localuser::chan, ast_frame::frametype, free, gen, input(), ast_channel::language, list, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_DEBUG, LOG_ERROR, LOG_NOTICE, LOG_WARNING, make_entry(), option_highpriority, send_child_event(), and ast_frame::subclass.

{
   struct localuser *u = NULL;
   struct playlist_entry *entry;
   const char *args = data;
   int child_stdin[2] = { 0,0 };
   int child_stdout[2] = { 0,0 };
   int child_stderr[2] = { 0,0 };
   int res = -1;
   int gen_active = 0;
   int pid;
   char *argv[32];
   int argc = 1;
   char *buf, *command;
   FILE *child_commands = NULL;
   FILE *child_errors = NULL;
   FILE *child_events = NULL;
   sigset_t fullset, oldset;

   LOCAL_USER_ADD(u);

   sigfillset(&fullset);
   pthread_sigmask(SIG_BLOCK, &fullset, &oldset);

   AST_LIST_HEAD_INIT(&u->playlist);
   AST_LIST_HEAD_INIT(&u->finishlist);
   u->abort_current_sound = 0;
   
   if (ast_strlen_zero(args)) {
      ast_log(LOG_WARNING, "ExternalIVR requires a command to execute\n");
      goto exit;
   }

   buf = ast_strdupa(data);
   if (!buf) {
      ast_log(LOG_ERROR, "Out of memory!\n");
      LOCAL_USER_REMOVE(u);
      return -1;
   }

   argc = ast_app_separate_args(buf, '|', argv, sizeof(argv) / sizeof(argv[0]));

   if (pipe(child_stdin)) {
      ast_chan_log(LOG_WARNING, chan, "Could not create pipe for child input: %s\n", strerror(errno));
      goto exit;
   }

   if (pipe(child_stdout)) {
      ast_chan_log(LOG_WARNING, chan, "Could not create pipe for child output: %s\n", strerror(errno));
      goto exit;
   }

   if (pipe(child_stderr)) {
      ast_chan_log(LOG_WARNING, chan, "Could not create pipe for child errors: %s\n", strerror(errno));
      goto exit;
   }

   if (chan->_state != AST_STATE_UP) {
      ast_answer(chan);
   }

   if (ast_activate_generator(chan, &gen, u) < 0) {
      ast_chan_log(LOG_WARNING, chan, "Failed to activate generator\n");
      goto exit;
   } else
      gen_active = 1;

   pid = fork();
   if (pid < 0) {
      ast_log(LOG_WARNING, "Failed to fork(): %s\n", strerror(errno));
      goto exit;
   }

   if (!pid) {
      /* child process */
      int i;

      signal(SIGPIPE, SIG_DFL);
      pthread_sigmask(SIG_UNBLOCK, &fullset, NULL);

      if (option_highpriority)
         ast_set_priority(0);

      dup2(child_stdin[0], STDIN_FILENO);
      dup2(child_stdout[1], STDOUT_FILENO);
      dup2(child_stderr[1], STDERR_FILENO);
      for (i = STDERR_FILENO + 1; i < 1024; i++)
         close(i);
      execv(argv[0], argv);
      fprintf(stderr, "Failed to execute '%s': %s\n", argv[0], strerror(errno));
      _exit(1);
   } else {
      /* parent process */
      int child_events_fd = child_stdin[1];
      int child_commands_fd = child_stdout[0];
      int child_errors_fd = child_stderr[0];
      struct ast_frame *f;
      int ms;
      int exception;
      int ready_fd;
      int waitfds[2] = { child_errors_fd, child_commands_fd };
      struct ast_channel *rchan;

      pthread_sigmask(SIG_SETMASK, &oldset, NULL);

      close(child_stdin[0]);
      child_stdin[0] = 0;
      close(child_stdout[1]);
      child_stdout[1] = 0;
      close(child_stderr[1]);
      child_stderr[1] = 0;

      if (!(child_events = fdopen(child_events_fd, "w"))) {
         ast_chan_log(LOG_WARNING, chan, "Could not open stream for child events\n");
         goto exit;
      }

      if (!(child_commands = fdopen(child_commands_fd, "r"))) {
         ast_chan_log(LOG_WARNING, chan, "Could not open stream for child commands\n");
         goto exit;
      }

      if (!(child_errors = fdopen(child_errors_fd, "r"))) {
         ast_chan_log(LOG_WARNING, chan, "Could not open stream for child errors\n");
         goto exit;
      }

      setvbuf(child_events, NULL, _IONBF, 0);
      setvbuf(child_commands, NULL, _IONBF, 0);
      setvbuf(child_errors, NULL, _IONBF, 0);

      res = 0;

      while (1) {
         if (ast_test_flag(chan, AST_FLAG_ZOMBIE)) {
            ast_chan_log(LOG_NOTICE, chan, "Is a zombie\n");
            res = -1;
            break;
         }

         if (ast_check_hangup(chan)) {
            ast_chan_log(LOG_NOTICE, chan, "Got check_hangup\n");
            send_child_event(child_events, 'H', NULL, chan);
            res = -1;
            break;
         }

         ready_fd = 0;
         ms = 100;
         errno = 0;
         exception = 0;

         rchan = ast_waitfor_nandfds(&chan, 1, waitfds, 2, &exception, &ready_fd, &ms);

         if (!AST_LIST_EMPTY(&u->finishlist)) {
            AST_LIST_LOCK(&u->finishlist);
            while ((entry = AST_LIST_REMOVE_HEAD(&u->finishlist, list))) {
               send_child_event(child_events, 'F', entry->filename, chan);
               free(entry);
            }
            AST_LIST_UNLOCK(&u->finishlist);
         }

         if (rchan) {
            /* the channel has something */
            f = ast_read(chan);
            if (!f) {
               ast_chan_log(LOG_NOTICE, chan, "Returned no frame\n");
               send_child_event(child_events, 'H', NULL, chan);
               res = -1;
               break;
            }

            if (f->frametype == AST_FRAME_DTMF) {
               send_child_event(child_events, f->subclass, NULL, chan);
               if (u->option_autoclear) {
                  if (!u->abort_current_sound && !u->playing_silence)
                     send_child_event(child_events, 'T', NULL, chan);
                  AST_LIST_LOCK(&u->playlist);
                  while ((entry = AST_LIST_REMOVE_HEAD(&u->playlist, list))) {
                     send_child_event(child_events, 'D', entry->filename, chan);
                     free(entry);
                  }
                  if (!u->playing_silence)
                     u->abort_current_sound = 1;
                  AST_LIST_UNLOCK(&u->playlist);
               }
            } else if ((f->frametype == AST_FRAME_CONTROL) && (f->subclass == AST_CONTROL_HANGUP)) {
               ast_chan_log(LOG_NOTICE, chan, "Got AST_CONTROL_HANGUP\n");
               send_child_event(child_events, 'H', NULL, chan);
               ast_frfree(f);
               res = -1;
               break;
            }
            ast_frfree(f);
         } else if (ready_fd == child_commands_fd) {
            char input[1024];

            if (exception || feof(child_commands)) {
               ast_chan_log(LOG_WARNING, chan, "Child process went away\n");
               res = -1;
               break;
            }

            if (!fgets(input, sizeof(input), child_commands))
               continue;

            command = ast_strip(input);

            ast_chan_log(LOG_DEBUG, chan, "got command '%s'\n", input);

            if (strlen(input) < 4)
               continue;

            if (input[0] == 'S') {
               if (ast_fileexists(&input[2], NULL, u->chan->language) == -1) {
                  ast_chan_log(LOG_WARNING, chan, "Unknown file requested '%s'\n", &input[2]);
                  send_child_event(child_events, 'Z', NULL, chan);
                  strcpy(&input[2], "exception");
               }
               if (!u->abort_current_sound && !u->playing_silence)
                  send_child_event(child_events, 'T', NULL, chan);
               AST_LIST_LOCK(&u->playlist);
               while ((entry = AST_LIST_REMOVE_HEAD(&u->playlist, list))) {
                  send_child_event(child_events, 'D', entry->filename, chan);
                  free(entry);
               }
               if (!u->playing_silence)
                  u->abort_current_sound = 1;
               entry = make_entry(&input[2]);
               if (entry)
                  AST_LIST_INSERT_TAIL(&u->playlist, entry, list);
               AST_LIST_UNLOCK(&u->playlist);
            } else if (input[0] == 'A') {
               if (ast_fileexists(&input[2], NULL, u->chan->language) == -1) {
                  ast_chan_log(LOG_WARNING, chan, "Unknown file requested '%s'\n", &input[2]);
                  send_child_event(child_events, 'Z', NULL, chan);
                  strcpy(&input[2], "exception");
               }
               entry = make_entry(&input[2]);
               if (entry) {
                  AST_LIST_LOCK(&u->playlist);
                  AST_LIST_INSERT_TAIL(&u->playlist, entry, list);
                  AST_LIST_UNLOCK(&u->playlist);
               }
            } else if (input[0] == 'H') {
               ast_chan_log(LOG_NOTICE, chan, "Hanging up: %s\n", &input[2]);
               send_child_event(child_events, 'H', NULL, chan);
               break;
            } else if (input[0] == 'O') {
               if (!strcasecmp(&input[2], "autoclear"))
                  u->option_autoclear = 1;
               else if (!strcasecmp(&input[2], "noautoclear"))
                  u->option_autoclear = 0;
               else
                  ast_chan_log(LOG_WARNING, chan, "Unknown option requested '%s'\n", &input[2]);
            }
         } else if (ready_fd == child_errors_fd) {
            char input[1024];

            if (exception || feof(child_errors)) {
               ast_chan_log(LOG_WARNING, chan, "Child process went away\n");
               res = -1;
               break;
            }

            if (fgets(input, sizeof(input), child_errors)) {
               command = ast_strip(input);
               ast_chan_log(LOG_NOTICE, chan, "stderr: %s\n", command);
            }
         } else if ((ready_fd < 0) && ms) { 
            if (errno == 0 || errno == EINTR)
               continue;

            ast_chan_log(LOG_WARNING, chan, "Wait failed (%s)\n", strerror(errno));
            break;
         }
      }
   }

 exit:
   if (gen_active)
      ast_deactivate_generator(chan);

   if (child_events)
      fclose(child_events);

   if (child_commands)
      fclose(child_commands);

   if (child_errors)
      fclose(child_errors);

   if (child_stdin[0])
      close(child_stdin[0]);

   if (child_stdin[1])
      close(child_stdin[1]);

   if (child_stdout[0])
      close(child_stdout[0]);

   if (child_stdout[1])
      close(child_stdout[1]);

   if (child_stderr[0])
      close(child_stderr[0]);

   if (child_stderr[1])
      close(child_stderr[1]);

   while ((entry = AST_LIST_REMOVE_HEAD(&u->playlist, list)))
      free(entry);

   LOCAL_USER_REMOVE(u);

   return res;
}

char* description

(

void

)

Provides a description of the module.

Returns:

a short description of your module

Definition at line 580 of file app_externalivr.c.

{
   return (char *) tdesc;
}

static void* gen_alloc	(	struct ast_channel *	chan,
		void *	params
	)			[static]

Definition at line 108 of file app_externalivr.c.

References calloc, and gen_state::u.

{
   struct localuser *u = params;
   struct gen_state *state;

   state = calloc(1, sizeof(*state));

   if (!state)
      return NULL;

   state->u = u;

   return state;
}

static void gen_closestream

(

struct gen_state *

state

)

[static]

Definition at line 123 of file app_externalivr.c.

References ast_closestream(), localuser::chan, ast_channel::stream, gen_state::stream, and gen_state::u.

Referenced by gen_nextfile(), gen_readframe(), and gen_release().

{
   if (!state->stream)
      return;

   ast_closestream(state->stream);
   state->u->chan->stream = NULL;
   state->stream = NULL;
}

static int gen_generate	(	struct ast_channel *	chan,
		void *	data,
		int	len,
		int	samples
	)			[static]

Definition at line 200 of file app_externalivr.c.

References ast_chan_log, ast_frfree(), ast_write(), localuser::chan, gen_readframe(), LOG_WARNING, gen_state::sample_queue, and ast_frame::samples.

{
   struct gen_state *state = data;
   struct ast_frame *f = NULL;
   int res = 0;

   state->sample_queue += samples;

   while (state->sample_queue > 0) {
      if (!(f = gen_readframe(state)))
         return -1;

      res = ast_write(chan, f);
      ast_frfree(f);
      if (res < 0) {
         ast_chan_log(LOG_WARNING, chan, "Failed to write frame: %s\n", strerror(errno));
         return -1;
      }
      state->sample_queue -= f->samples;
   }

   return res;
}

static int gen_nextfile

(

struct gen_state *

state

)

[static]

Definition at line 142 of file app_externalivr.c.

References ast_chan_log, AST_LIST_REMOVE_HEAD, ast_openstream_full(), localuser::chan, gen_state::current, gen_closestream(), ast_channel::language, list, LOG_WARNING, gen_state::stream, and gen_state::u.

Referenced by gen_readframe().

{
   struct localuser *u = state->u;
   char *file_to_stream;
   
   u->abort_current_sound = 0;
   u->playing_silence = 0;
   gen_closestream(state);

   while (!state->stream) {
      state->current = AST_LIST_REMOVE_HEAD(&u->playlist, list);
      if (state->current) {
         file_to_stream = state->current->filename;
      } else {
         file_to_stream = "silence/10";
         u->playing_silence = 1;
      }

      if (!(state->stream = ast_openstream_full(u->chan, file_to_stream, u->chan->language, 1))) {
         ast_chan_log(LOG_WARNING, u->chan, "File '%s' could not be opened: %s\n", file_to_stream, strerror(errno));
         if (!u->playing_silence) {
            continue;
         } else { 
            break;
         }
      }
   }

   return (!state->stream);
}

static struct ast_frame* gen_readframe

(

struct gen_state *

state

)

[static]

Definition at line 173 of file app_externalivr.c.

References AST_LIST_FIRST, AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_readframe(), gen_state::current, gen_closestream(), gen_nextfile(), list, gen_state::stream, and gen_state::u.

Referenced by gen_generate().

{
   struct ast_frame *f = NULL;
   struct localuser *u = state->u;
   
   if (u->abort_current_sound ||
       (u->playing_silence && AST_LIST_FIRST(&u->playlist))) {
      gen_closestream(state);
      AST_LIST_LOCK(&u->playlist);
      gen_nextfile(state);
      AST_LIST_UNLOCK(&u->playlist);
   }

   if (!(state->stream && (f = ast_readframe(state->stream)))) {
      if (state->current) {
         AST_LIST_LOCK(&u->finishlist);
         AST_LIST_INSERT_TAIL(&u->finishlist, state->current, list);
         AST_LIST_UNLOCK(&u->finishlist);
         state->current = NULL;
      }
      if (!gen_nextfile(state))
         f = ast_readframe(state->stream);
   }

   return f;
}

static void gen_release	(	struct ast_channel *	chan,
		void *	data
	)			[static]

Definition at line 133 of file app_externalivr.c.

References free, and gen_closestream().

{
   struct gen_state *state = data;

   gen_closestream(state);
   free(data);
}

char* key

(

void

)

Returns the ASTERISK_GPL_KEY.

This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of the GPL stated in the ASTERISK_GPL_KEY. Your module will not load if it does not return the EXACT message:

 char *key(void) {
         return ASTERISK_GPL_KEY;
 }

Returns:

ASTERISK_GPL_KEY

Definition at line 594 of file app_externalivr.c.

References ASTERISK_GPL_KEY.

{
   return ASTERISK_GPL_KEY;
}

int load_module

(

void

)

Initialize the module.

TE STUFF END

Definition at line 575 of file app_externalivr.c.

References app_exec, and ast_register_application().

{
   return ast_register_application(app, app_exec, synopsis, descrip);
}

static struct playlist_entry* make_entry

(

const char *

filename

)

[static]

Definition at line 231 of file app_externalivr.c.

References calloc.

Referenced by app_exec().

{
   struct playlist_entry *entry;

   entry = calloc(1, sizeof(*entry) + strlen(filename) + 10);

   if (!entry)
      return NULL;

   strcpy(entry->filename, filename);

   return entry;
}

static void send_child_event	(	FILE *	handle,
		const char	event,
		const char *	data,
		const struct ast_channel *	chan
	)			[static]

Definition at line 93 of file app_externalivr.c.

References ast_chan_log, localuser::chan, and LOG_DEBUG.

Referenced by app_exec().

{
   char tmp[256];

   if (!data) {
      snprintf(tmp, sizeof(tmp), "%c,%10d", event, (int)time(NULL));
   } else {
      snprintf(tmp, sizeof(tmp), "%c,%10d,%s", event, (int)time(NULL), data);
   }

   fprintf(handle, "%s\n", tmp);
   ast_chan_log(LOG_DEBUG, chan, "sent '%s'\n", tmp);
}

int unload_module

(

void

)

Cleanup all module structures, sockets, etc.

This is called at exit. Any registrations and memory allocations need to be unregistered and free'd here. Nothing else will do these for you (until exit).

Returns:

Zero on success, or non-zero on error.

Definition at line 564 of file app_externalivr.c.

References ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

{
   int res;

   res = ast_unregister_application(app);

   STANDARD_HANGUP_LOCALUSERS;

   return res;
}

int usecount

(

void

)

Provides a usecount.

This function will be called by various parts of asterisk. Basically, all it has to do is to return a usecount when called. You will need to maintain your usecount within the module somewhere. The usecount should be how many channels provided by this module are in use.

Returns:

The module's usecount.

Definition at line 585 of file app_externalivr.c.

References STANDARD_USECOUNT.

{
   int res;

   STANDARD_USECOUNT(res);

   return res;
}

---

Variable Documentation

const char* app = "ExternalIVR" [static]

Definition at line 52 of file app_externalivr.c.

const char* descrip [static]

Definition at line 56 of file app_externalivr.c.

struct ast_generator gen [static]

Definition at line 224 of file app_externalivr.c.

Referenced by app_exec(), and ast_activate_generator().

LOCAL_USER_DECL

Definition at line 84 of file app_externalivr.c.

const char* synopsis = "Interfaces with an external IVR application" [static]

Definition at line 54 of file app_externalivr.c.

const char* tdesc = "External IVR Interface Application" [static]

Definition at line 50 of file app_externalivr.c.

---