erlagi (ERLang AGI implementation)
----------------------------------

This is a library and an OTP application, intended to be used for developing
and serving telephony applications for Asterisk using Erlang.

It can be used with and without FastAGI. A FastAGI server
implementation is included, suitable to run many calls
concurrently, on 1 or more erlang nodes.

I used my own box to test it, with R13B04. Please
let me know if you have (un)successfully tried it
in a different version.

License
-------
erlagi is under the Apache License 2.0. See the LICENSE file
for more details.

Usage
-----
See the example files:

 * bin/run_call.sh: No FastAGI server, executed by asterisk
to handle 1 call (See extension 1, below).

 * bin/run_fastagi.sh: Starts the FastAGI server and accepts
multiple calls (See extension 2, below). Will spawn as many workers as specified
in the backlog option to accept incoming connections.

OTP
---
erlagi is also the name of the included OTP application. Just start is as
any other application, like:

1> application:start(erlagi).

The application will start a supervisor, that has 1 supervisor per configured
listening address, which in turn, contain as many workers as the configured
backlog.

So let's say you configure 2 listening address, with a backlog of 5 each. This
will result in having:
 * 1 main supervisor, that supervises...
 * 2 Listeners (1 per address), which in turn supervises..
 * 10 workers which accept the client connections (5 per listening address).

Compiling
---------
Just type make in the top level directory. The .beam files will
be generated in the ebin/ directory. The Makefile contains the correct
rebar commands to run.

Running it
----------
Configure your asterisk dialplan (extensions.conf)
to have an extension like:

; Without FastAGI (handles 1 call per process)
exten => 1,1,AGI(bin/run_call.sh)
exten => 1,n,Hangup

; For FastAGI (handles multiple concurrent calls per
; process)
exten => 2,1,AGI(agi://127.0.0.1)
exten => 2,n,Hangup

Running the FastAGI server from the erlang shell
------------------------------------------------
Start the FastAGI server with erlagi_fastagi:run/1, like:

1> c(erlagi_fastagi).
{ok,erlagi_fastagi}
2> c(erlagi_demo).
{ok,erlagi_demo}
3> Pid = erlagi_fastagi:start_link(
    demo_app, [
        {host, "127.0.0.1"},
        {port, 20000},
        {backlog, 5},
        {callback, erlagi_demo}, % A module that implements new_call/1
        {logfile, "/tmp/erlagi.log"}
    ]).
{ok,<0.33.0>}
4>

So that's how you start and stop the fastagi server (using the
example shipped "application"). Reload your asterisk
and make a couple of calls to the extension. You should see some
output in the shell and the log file.

Running the FastAGI server from OS command line
-----------------------------------------------
See the example in bin/run_fastagi.sh

Configuring
-----------
You can see how to configure the erlagi application (and how to run a fastagi
server) in rel/files/sys.config:
[
    {host, "127.0.0.1"},
    {port, 20000},
    {backlog, 5},
    {callback, erlagi_demo},
    {logfile, "/tmp/erlagi-addressName1.log"}
]

Note
----
I come mostly from an OOP background, and I wrote erlagi to learn some
erlang. Please let me know any suggestions you may have, they will
be really appreciated :)

Main modules
------------
 * erlagi: The AGI library.
 * erlagi_fastagi: A FastAGI server (and supervisor) that will create and
 listen in a socket, spawning and supervising N workers to accept a connection
 call the callback, passing in an #agicall record.
 * erlagi_debug: Some useful functions to debug your
application.
 * erlagi_demo: An example ivr "application".