add ExternalIVR() application
authorKevin P. Fleming <kpfleming@digium.com>
Wed, 10 Aug 2005 23:24:39 +0000 (23:24 +0000)
committerKevin P. Fleming <kpfleming@digium.com>
Wed, 10 Aug 2005 23:24:39 +0000 (23:24 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@6317 65c4cc65-6c06-0410-ace0-fbb531ad65f3

apps/Makefile
apps/app_externalivr.c [new file with mode: 0755]
doc/README.externalivr [new file with mode: 0755]

index 104aa40..a6e7a9d 100755 (executable)
@@ -32,7 +32,7 @@ APPS=app_dial.so app_playback.so app_voicemail.so app_directory.so app_mp3.so\
      app_test.so app_forkcdr.so app_math.so app_realtime.so \
      app_dumpchan.so app_waitforsilence.so app_while.so app_setrdnis.so \
      app_md5.so app_readfile.so app_chanspy.so app_settransfercapability.so \
-     app_dictate.so
+     app_dictate.so app_externalivr.c
 
 ifneq (${OSARCH},Darwin)
 ifneq (${OSARCH},SunOS)
diff --git a/apps/app_externalivr.c b/apps/app_externalivr.c
new file mode 100755 (executable)
index 0000000..f8a7e03
--- /dev/null
@@ -0,0 +1,502 @@
+/*
+ * Asterisk -- A telephony toolkit for Linux.
+ *
+ * External IVR application interface
+ * 
+ * Copyright (C) 2005, Digium, Inc.
+ *
+ * Kevin P. Fleming <kpfleming@digium.com>
+ *
+ * Portions taken from the file-based music-on-hold work
+ * created by Anthony Minessale II in res_musiconhold.c
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License
+ */
+
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <stdlib.h>
+#include <errno.h>
+
+#include "asterisk.h"
+
+ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
+
+#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"
+
+static char *tdesc = "External IVR Interface Application";
+
+static char *app = "ExternalIVR";
+
+static char *synopsis = "Interfaces with an external IVR application";
+
+static char *descrip = 
+"  ExternalIVR(command[|arg[|arg...]]): Forks an process to run the supplied command,\n"
+"and starts a generator on the channel. The generator's play list is\n"
+"controlled by the external application, which can add and clear entries\n"
+"via simple commands issued over its stdout. The external application\n"
+"will receive all DTMF events received on the channel, and notification\n"
+"if the channel is hung up. The application will not be forcibly terminated\n"
+"when the channel is hung up.\n"
+"See doc/README.externalivr for a protocol specification.\n";
+
+struct playlist_entry {
+       AST_LIST_ENTRY(playlist_entry) list;
+       char filename[1];
+};
+
+struct localuser {
+       struct ast_channel *chan;
+       struct localuser *next;
+       AST_LIST_HEAD(playlist, playlist_entry) playlist;
+       int list_cleared;
+};
+
+LOCAL_USER_DECL;
+
+struct gen_state {
+       struct localuser *u;
+       struct ast_filestream *stream;
+       int sample_queue;
+       int playing_silence;
+};
+
+static void *gen_alloc(struct ast_channel *chan, void *params)
+{
+       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)
+{
+       if (!state->stream)
+               return;
+
+       ast_closestream(state->stream);
+       state->u->chan->stream = NULL;
+       state->stream = NULL;
+}
+
+static void gen_release(struct ast_channel *chan, void *data)
+{
+       struct gen_state *state = data;
+
+       gen_closestream(state);
+       free(data);
+}
+
+/* caller has the playlist locked */
+static int gen_nextfile(struct gen_state *state)
+{
+       struct playlist_entry *entry;
+       struct localuser *u = state->u;
+       char *file_to_stream;
+       
+       state->u->list_cleared = 0;
+       state->playing_silence = 0;
+       gen_closestream(state);
+
+       while (!state->stream) {
+               if (AST_LIST_FIRST(&u->playlist))
+                       entry = AST_LIST_REMOVE_HEAD(&u->playlist, list);
+               else
+                       entry = NULL;
+
+               if (entry) {
+                       file_to_stream = ast_strdupa(entry->filename);
+                       free(entry);
+               } else {
+                       file_to_stream = "silence-10";
+                       state->playing_silence = 1;
+               }
+
+               if (!(state->stream = ast_openstream_full(u->chan, file_to_stream, u->chan->language, 1))) {
+                       ast_log(LOG_WARNING, "File '%s' could not be opened for channel '%s': %s\n", file_to_stream, u->chan->name, strerror(errno));
+                       if (!state->playing_silence)
+                               continue;
+                       else
+                               break;
+               }
+       }
+
+       return (!state->stream);
+}
+
+static struct ast_frame *gen_readframe(struct gen_state *state)
+{
+       struct ast_frame *f = NULL;
+       
+       if (state->u->list_cleared ||
+           (state->playing_silence && AST_LIST_FIRST(&state->u->playlist))) {
+               gen_closestream(state);
+               AST_LIST_LOCK(&state->u->playlist);
+               gen_nextfile(state);
+               AST_LIST_UNLOCK(&state->u->playlist);
+       }
+
+       if (!(state->stream && (f = ast_readframe(state->stream)))) {
+               if (!gen_nextfile(state))
+                       f = ast_readframe(state->stream);
+       }
+
+       return f;
+}
+
+static int gen_generate(struct ast_channel *chan, void *data, int len, int 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_log(LOG_WARNING, "Failed to write frame to '%s': %s\n", chan->name, strerror(errno));
+                       return -1;
+               }
+               state->sample_queue -= f->samples;
+       }
+
+       return res;
+}
+
+static struct ast_generator gen =
+{
+       alloc: gen_alloc,
+       release: gen_release,
+       generate: gen_generate,
+};
+
+static struct playlist_entry *make_entry(const char *filename)
+{
+       struct playlist_entry *entry;
+
+       entry = calloc(1, sizeof(*entry) + strlen(filename));
+
+       if (!entry)
+               return NULL;
+
+       strcpy(entry->filename, filename);
+
+       return entry;
+}
+
+static int app_exec(struct ast_channel *chan, void *data)
+{
+       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 *command;
+       char *argv[32];
+       int argc = 1;
+       char *buf;
+       FILE *child_commands = NULL;
+       FILE *child_errors = NULL;
+       FILE *child_events = NULL;
+
+       if (!args || ast_strlen_zero(args)) {
+               ast_log(LOG_WARNING, "ExternalIVR requires a command to execute\n");
+               goto exit;
+       }
+
+       buf = ast_strdupa(data);
+       command = strsep(&buf, "|");
+       argv[0] = command;
+       while ((argc < 31) && (argv[argc++] = strsep(&buf, "|")));
+       argv[argc] = NULL;
+
+       LOCAL_USER_ADD(u);
+
+       if (pipe(child_stdin)) {
+               ast_log(LOG_WARNING, "Could not create pipe for child input on channel '%s': %s\n", chan->name, strerror(errno));
+               goto exit;
+       }
+
+       if (pipe(child_stdout)) {
+               ast_log(LOG_WARNING, "Could not create pipe for child output on channel '%s': %s\n", chan->name, strerror(errno));
+               goto exit;
+       }
+
+       if (pipe(child_stderr)) {
+               ast_log(LOG_WARNING, "Could not create pipe for child errors on channel '%s': %s\n", chan->name, strerror(errno));
+               goto exit;
+       }
+
+       u->list_cleared = 0;
+       AST_LIST_HEAD_INIT(&u->playlist);
+
+       if (chan->_state != AST_STATE_UP) {
+               ast_answer(chan);
+       }
+
+       if (ast_activate_generator(chan, &gen, u) < 0) {
+               ast_log(LOG_WARNING,"Failed to activate generator on '%s'\n", chan->name);
+               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;
+
+               dup2(child_stdin[0], STDIN_FILENO);
+               dup2(child_stdout[1], STDOUT_FILENO);
+               dup2(child_stderr[1], STDERR_FILENO);
+               close(child_stdin[1]);
+               close(child_stdout[0]);
+               close(child_stderr[0]);
+               for (i = STDERR_FILENO + 1; i < 1024; i++)
+                       close(i);
+               execv(command, argv);
+               fprintf(stderr, "Failed to execute '%s': %s\n", command, 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;
+
+               close(child_stdin[0]);
+               close(child_stdout[1]);
+               close(child_stderr[1]);
+
+               if (!(child_events = fdopen(child_events_fd, "w"))) {
+                       ast_log(LOG_WARNING, "Could not open stream for child events for channel '%s'\n", chan->name);
+                       goto exit;
+               }
+
+               setvbuf(child_events, NULL, _IONBF, 0);
+
+               if (!(child_commands = fdopen(child_commands_fd, "r"))) {
+                       ast_log(LOG_WARNING, "Could not open stream for child commands for channel '%s'\n", chan->name);
+                       goto exit;
+               }
+
+               if (!(child_errors = fdopen(child_errors_fd, "r"))) {
+                       ast_log(LOG_WARNING, "Could not open stream for child errors for channel '%s'\n", chan->name);
+                       goto exit;
+               }
+
+               res = 0;
+
+               while (1) {
+                       if (ast_test_flag(chan, AST_FLAG_ZOMBIE)) {
+                               ast_log(LOG_NOTICE, "Channel '%s' is a zombie\n", chan->name);
+                               res = -1;
+                               break;
+                       }
+
+                       if (ast_check_hangup(chan)) {
+                               ast_log(LOG_NOTICE, "Channel '%s' got check_hangup\n", chan->name);
+                               fprintf(child_events, "H,%10ld\n", time(NULL));
+                               res = -1;
+                               break;
+                       }
+
+                       ready_fd = 0;
+                       ms = 1000;
+                       errno = 0;
+                       exception = 0;
+
+                       rchan = ast_waitfor_nandfds(&chan, 1, waitfds, 2, &exception, &ready_fd, &ms);
+
+                       if (rchan) {
+                               /* the channel has something */
+                               f = ast_read(chan);
+                               if (!f) {
+                                       fprintf(child_events, "H,%10ld\n", time(NULL));
+                                       ast_log(LOG_NOTICE, "Channel '%s' returned no frame\n", chan->name);
+                                       res = -1;
+                                       break;
+                               }
+
+                               if (f->frametype == AST_FRAME_DTMF) {
+                                       fprintf(child_events, "%c,%10ld\n", f->subclass, time(NULL));
+                               } else if ((f->frametype == AST_FRAME_CONTROL) && (f->subclass == AST_CONTROL_HANGUP)) {
+                                       ast_log(LOG_NOTICE, "Channel '%s' got AST_CONTROL_HANGUP\n", chan->name);
+                                       fprintf(child_events, "H,%10ld\n", time(NULL));
+                                       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_log(LOG_WARNING, "Child process went away for channel '%s'\n", chan->name);
+                                       res = -1;
+                                       break;
+                               }
+
+                               if (!fgets(input, sizeof(input), child_commands))
+                                       continue;
+
+                               command = ast_strip(input);
+
+                               if (strlen(input) < 4)
+                                       continue;
+
+                               if (input[0] == 'S') {
+                                       if (ast_fileexists(&input[2], NULL, NULL) == -1) {
+                                               fprintf(child_events, "Z,%10ld\n", time(NULL));
+                                               ast_log(LOG_WARNING, "Unknown file requested '%s' for channel '%s'\n", &input[2], chan->name);
+                                               strcpy(&input[2], "exception");
+                                       }
+                                       AST_LIST_LOCK(&u->playlist);
+                                       while ((entry = AST_LIST_REMOVE_HEAD(&u->playlist, list)))
+                                               free(entry);
+                                       u->list_cleared = 1;
+                                       entry = make_entry(&input[2]);
+                                       if (entry)
+                                               AST_LIST_UNLOCK(&u->playlist);
+                                       AST_LIST_INSERT_TAIL(&u->playlist, entry, list);
+                               } else if (input[0] == 'A') {
+                                       if (ast_fileexists(&input[2], NULL, NULL) == -1) {
+                                               fprintf(child_events, "Z,%10ld\n", time(NULL));
+                                               ast_log(LOG_WARNING, "Unknown file requested '%s' for channel '%s'\n", &input[2], chan->name);
+                                               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_log(LOG_NOTICE, "Hanging up: %s\n", &input[2]);
+                                       fprintf(child_events, "H,%10ld\n", time(NULL));
+                                       break;
+                               }
+                       } else if (ready_fd == child_errors_fd) {
+                               char input[1024];
+
+                               if (exception || feof(child_errors)) {
+                                       ast_log(LOG_WARNING, "Child process went away for channel '%s'\n", chan->name);
+                                       res = -1;
+                                       break;
+                               }
+
+                               if (fgets(input, sizeof(input), child_errors)) {
+                                       command = ast_strip(input);
+                                       ast_log(LOG_NOTICE, "%s\n", command);
+                               }
+                       } else if ((ready_fd < 0) && ms) { 
+                               if (errno == 0 || errno == EINTR)
+                                       continue;
+
+                               ast_log(LOG_WARNING, "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]);
+               close(child_stdin[1]);
+       }
+
+       if (child_stdout[0]) {
+               close(child_stdout[0]);
+               close(child_stdout[1]);
+       }
+
+       if (child_stderr[0]) {
+               close(child_stderr[0]);
+               close(child_stderr[1]);
+       }
+
+       if (u) {
+               while ((entry = AST_LIST_REMOVE_HEAD(&u->playlist, list)))
+                       free(entry);
+
+               LOCAL_USER_REMOVE(u);
+       }
+
+       return res;
+}
+
+int unload_module(void)
+{
+       STANDARD_HANGUP_LOCALUSERS;
+
+       return ast_unregister_application(app);
+}
+
+int load_module(void)
+{
+       return ast_register_application(app, app_exec, synopsis, descrip);
+}
+
+char *description(void)
+{
+       return tdesc;
+}
+
+int usecount(void)
+{
+       int res;
+
+       STANDARD_USECOUNT(res);
+
+       return res;
+}
+
+char *key()
+{
+       return ASTERISK_GPL_KEY;
+}
diff --git a/doc/README.externalivr b/doc/README.externalivr
new file mode 100755 (executable)
index 0000000..ff4ff12
--- /dev/null
@@ -0,0 +1,96 @@
+Asterisk External IVR Interface
+-------------------------------
+
+If you load app_externalivr.so in your Asterisk instance, you will
+have an ExternalIVR() application available in your dialplan. This
+application implements a simple protocol for bidirectional
+communication with an external process, while simultaneous playing
+audio files to the connected channel (without interruption or
+blocking).
+
+The arguments to ExternalIVR() consist of the command to execute and
+any arguments to pass to it, the same as the System() application
+accepts. The external command will be executed in a child process,
+with its standard file handles connected to the Asterisk process as
+follows:
+
+stdin (0) - DTMF and hangup events will be received on this handle
+stdout (1) - Playback and hangup commands can be sent on this handle
+stderr (2) - Error messages can be sent on this handle
+
+The application will also create an audio generator to play audio to
+the channel, and will start playing silence. When your application
+wants to send audio to the channel, it can send a command (see below)
+to add file(s) to the generator's playlist. The generator will then
+work its way through the list, playing each file in turn until it
+either runs out of files to play, the channel is hung up, or a command
+is received to clear the list and start with a new file. At any time,
+more files can be added to the list and the generator will play them
+in sequence.
+
+While the generator is playing audio (or silence), any DTMF events
+received on the channel will be sent to the child process (see
+below). Note that this can happen at any time, since the generator,
+the child process and the channel thread are all executing
+independently. It is very important that your external application be
+ready to receive events from Asterisk at all times (without blocking),
+or you could cause the channel to become non-responsive.
+
+If the child process dies, ExternalIVR() will notice this and hang up
+the channel immediately (and also send a message to the log).
+
+DTMF (and other) events
+-----------------------
+
+All events will be newline-terminated strings.
+
+Events send to the child's stdin will be in the following format:
+
+tag,timestamp
+
+The tag can be one of the following characters:
+
+0-9: DTMF event for keys 0 through 9
+A-D: DTMF event for keys A through D
+*: DTMF event for key *
+#: DTMF event for key #
+H: the channel was hung up by the connected party
+Z: the previous command was unable to be executed (file does not
+exist, etc.)
+
+The timestamp will be 10 digits long, and will be a decimal
+representation of a standard Unix epoch-based timestamp.
+
+Commands
+--------
+
+All commands must be newline-terminated strings.
+
+The child process can send commands on stdout in the following formats:
+
+S,filename
+A,filename
+H,message
+
+The 'S' command checks to see if there is a playable audio file with
+the specified name, and if so, clear's the generator's playlist and
+places the file onto the list. Note that the playability check does
+not take into account transcoding requirements, so it is possible for
+the file to not be played even though it was found. If the file cannot
+be found, a 'Z' event (see above) will be sent to the child.
+
+The 'A' command checks to see if there is a playable audio file with
+the specified name, and if so, adds it to the generator's
+playlist. The same playability and exception rules apply as for the
+'S' command.
+
+The 'H' command stops the generator and hangs up the channel, and logs
+the supplied message to the Asterisk log.
+
+Errors
+------
+
+Any newline-terminated output generated by the child process on its
+stderr handle will be copied into the Asterisk log.
+
+