1 files changed, 139 insertions, 0 deletions
diff --git a/trunk/doc/callfiles.txt b/trunk/doc/callfiles.txt
new file mode 100644
index 000000000..3fe6cb09e
--- /dev/null
+++ b/trunk/doc/callfiles.txt
@@ -0,0 +1,139 @@
+Asterisk call files
+===================
+
+Asterisk has the ability to initiate a call from outside of the normal
+methods such as the dialplan, manager interface, or spooling interface.
+
+Using the call file method, you must give Asterisk the following information:
+
+* How to perform the call, similar to the Dial() application
+* What to do when the call is answered
+
+With call files you submit this information simply by creating a file with 
+the required syntax and placing it in the outgoing spooling directory, located
+by default in /var/spool/asterisk/outgoing/ (configurable in asterisk.conf).
+
+The pbx_spool module aggressively examines the directory contents every second,
+creating a new call for every call file it finds. Do NOT write or create
+the call file directly in the outgoing directory, but always create the file
+in another directory of the same filesystem and then move the file to the
+/var/spool/asterisk/outgoing directory, or Asterisk may read just a partial 
+file.
+
+
+The call file syntax
+====================
+
+The call file consists of <Key>: <value> pairs; one per line.
+
+Comments are indicated by a '#' character that begins a line, or follows a space
+or tab character.  To be consistent with the configuration files in Asterisk,
+comments can also be indicated by a semicolon.  However, the multiline comments
+(;-- --;) used in Asterisk configuration files are not supported. Semicolons can
+be escaped by a backslash.
+
+
+The following keys-value pairs are used to specify how setup a call:
+
+Channel: <channel>      the channel to use for the new call, in the form
+                        technology/resource as in the Dial application. This
+                        value is required.
+
+Callerid: <callerid>    the caller id to use.
+
+WaitTime: <number>      how many seconds to wait for an answer before the call
+                        fails (ring cycle). Default 45 seconds.
+
+Maxretries: <number>    number of retries before failing, not including the
+                        initial attempt. Default = 0 e.g. don't retry if fails.
+
+RetryTime: <number>     how many seconds to wait before retry. The default is
+                        300 (5 minutes).
+
+Account: <account>      the account code for the call. This value will be
+                        assigned to CDR(accountcode)
+
+
+
+When the call answers there are two choices: 
+* Execute a single application, or
+* Execute the dialplan at the specified context/extension/priority.
+
+
+To execute an application:
+--------------------------
+
+Application: <appname>  the application to execute
+
+Data: <args>            the application arguments
+
+
+To start executing applications in the dialplan:
+------------------------------------------------
+
+Context: <context>      the context in the dialplan
+
+Extension: <exten>      the extension in the specified context
+
+Priority: <priority>    the priority of the specified extension 
+                        (numeric or label)
+
+
+
+Setvar: <var=value>     you may also assign values to variables that will be
+                        available to the channel, as if you had performed a
+			Set(var=value) in the dialplan. More than one Setvar:
+			maybe specified.
+
+
+The processing of the call file ends when the call is answered and terminated; when
+the call was not answered in the initial attempt and subsequent retries; or if
+the call file can't be successfully read and parsed.
+
+To specify what to do with the call file at the end of processing:
+
+Archive: <yes|no>       if "no" the call file is deleted. If set to "yes" the 
+                        call file is moved to the "outgoing_done" subdirectory 
+                        of the Asterisk spool directory. The default is to 
+			delete the call file.
+
+
+If the call file is archived, Asterisk will append to the call file:
+
+Status: <exitstatus>    can be "Expired", "Completed" or "Failed"
+
+
+
+Other lines generated by Asterisk:
+
+Asterisk keep track of how many retries the call has already attempted, 
+appending to the call file the following key-pairs in the form:
+
+StartRetry: <pid> <retrycount> (<time>)
+EndRetry: <pid> <retrycount> (<time>)
+
+With the main process ID (pid) of the Asterisk process, the retry number, and
+the attempts start and end times in time_t format.
+
+
+
+Directory locations
+===================
+
+<astspooldir>/outgoing          the outgoing dir, where call files are put
+                                for processing
+
+<astspooldir>/outgoing_done     the archive dir
+
+
+<astspooldir> is specified in asterisk.conf, usually /var/spool/asterisk
+
+
+
+How to schedule a call
+======================
+
+Call files that have the time of the last modification in the future are ignored
+by Asterisk. This makes it possible to modify the time of a call file to the
+wanted time, move to the outgoing directory, and Asterisk will attempt to
+create the call at that time.