- almost finished user guide... Phew...
git-svn-id: https://svn.ibp.de/svn/capisuite/trunk/capisuite@29 4ebea2bb-67d4-0310-8558-a5799e421b66
This commit is contained in:
gernot
parent
ecf08119ba
commit
8eae5669f2
|
|
@ -930,23 +930,33 @@ automake -a</screen>
|
|||
|
||||
<para>The following options are recognized by <command>capisuitefax</command>:</para>
|
||||
|
||||
<screen>capisuitefax -d dialstring [-h] [-q] file1 [file2...]</screen>
|
||||
<screen>capisuitefax [-q] -d dialstring file1 [file2...]</screen>
|
||||
<screen>capisuitefax [-q] -a id</screen>
|
||||
<screen>capisuitefax [-h] [-l]</screen>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>-a id</option></term>
|
||||
<listitem><para>Abort the job with the given id. To get a job id, use the <option>-l</option> option.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>-d dialstring</option></term>
|
||||
<listitem><para>the number which should be called (destination of the fax)</para></listitem>
|
||||
<listitem><para>The number which should be called (destination of the fax)</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>-h</option></term>
|
||||
<listitem><para>show a short commandline help</para></listitem>
|
||||
<listitem><para>Show a short commandline help</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>-</option></term>
|
||||
<listitem><para>Shows the jobs which are currenty in the send queue.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>-q</option></term>
|
||||
<listitem><para>be quiet, don't output informational messages</para></listitem>
|
||||
<listitem><para>Be quiet, don't output informational messages</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>file1 [file2...]</option></term>
|
||||
<listitem><para>one or more PostScript files to send to this destination (more than
|
||||
<listitem><para>One or more PostScript files to send to this destination (more than
|
||||
one PostScript file will produce several separate fax jobs)</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
|
@ -1773,7 +1783,7 @@ def faxIncoming(call):
|
|||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="idle_examples"><title>Examples for idle scripts</title>
|
||||
<sect1 id="idle_examples"><title>Example for an idle script</title>
|
||||
|
||||
<para>After we've seen how to handle incoming calls, a very short introduction to
|
||||
initiate outgoing calls by using the idle script will follow.</para>
|
||||
|
|
@ -1974,24 +1984,207 @@ def idle(capi):<co id="idle_ex2_4"/>
|
|||
examples or the files distributed with &cs; (read <xref linkend="default_script_overview"/> before). You will find a
|
||||
complete reference of the available commands in <xref linkend="command_reference"/>.</para>
|
||||
|
||||
<para>If you have any trouble in getting your scripts up and running, please use the &cs; mailing lists.</para>
|
||||
<para>If you have any trouble in getting your scripts up and running, please use the &cs; mailing lists. And don't forget to have
|
||||
fun. ;-)</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="default_script_overview"><title>Structural overview of the default scripts</title>
|
||||
<sect2 id="default_incoming"><title>incoming.py</title>
|
||||
<para></para>
|
||||
<para>The incoming script handles all incoming connections. It reads two configuration files containing all necessary
|
||||
data which were described in detail in <xref linkend="script_config"/>. The overall structure will be described here
|
||||
giving you an overview of how it is implemented. Firstly (after importing some necessary modules), it defines
|
||||
the necessary function <function>callIncoming</function> which will call all other functions if needed.</para>
|
||||
|
||||
<sect3 id="default_incoming_1"><title>function <function>callIncoming</function></title>
|
||||
<para>This function starts with a call to <function>cs_helpers.readConfig</function>
|
||||
to read the configuration. It then iterates through all sections representing the configured users (except GLOBAL) to see
|
||||
if the called number belongs to any user. If a match is found, the user and the defined service are saved to
|
||||
<literal>curr_user</literal> and <literal>curr_service</literal>.</para>
|
||||
|
||||
<para>If no match has been found (<literal>curr_user</literal> is empty), the call is rejected and the function returns.
|
||||
Otherwise the directory to use for incoming fax or voice data is determined and created if not there yet.</para>
|
||||
|
||||
<para>The last thing the function does, is to produce a log entry, accept the call with the right service (fax
|
||||
or voice) and call either <function>faxIncoming</function> or <function>voiceIncoming</function>. It also defines
|
||||
an exeception handler for <literal>capisuite.CallGoneError</literal>.</para>
|
||||
</sect3>
|
||||
<sect3 id="default_incoming_2"><title>function <function>faxIncoming</function></title>
|
||||
<para><function>faxIncoming</function> is quite straight forward: it creates a uniqe filename, calls
|
||||
<function>capisuite.fax_receive</function>, disconnects and logs the disconnection reasons. Then it checks if a fax
|
||||
have been really received succesfully (i.e. if the file exists), if yes, creates a description file for it, chown's the
|
||||
file to the right user and sends the file as mail.</para>
|
||||
</sect3>
|
||||
<sect3 id="default_incoming_3"><title>function <function>voiceIncoming</function></title>
|
||||
<para><function>voiceIncoming</function> has much more features to accomplish like fax recognition
|
||||
and switching to fax mode, starting a remote inquiry etc.</para>
|
||||
|
||||
<para>It also starts by determining the directory to use and creating a unique filename. Also, the PIN for remote inquiry
|
||||
is saved to a private variable. There are two possibilites now: the user has already an own announcement - in this case
|
||||
it's played now. Otherwise, a predefined announcement containing of a general announcement and the number which was called
|
||||
is played. If recording a message wasn't disabled (by setting <literal>voice_action</literal> to <literal>None</literal>),
|
||||
the it starts now after a beep.</para>
|
||||
|
||||
<para>All <function>audio_send</function> and <literal>audio_receive</literal> calls used so far had DTMF abortion enabled
|
||||
and so the script "falls through" all these calls after a DTMF signal was recognized. After them,
|
||||
<function>read_DTMF</function> is used to see if any such signal has been found. "X" represents the fax tone and so triggers
|
||||
a switch to fax protocols and a call to <function>faxIncoming</function>. Any other received signals are interpreted to be
|
||||
a part of the PIN for remote inquiry and so a loop which waits 3 seconds after each tone for the next one is entered. If
|
||||
a valid PIN is entered, it starts the <function>remoteInquiry</function>. After three wrong attempts, it will disconnect.</para>
|
||||
|
||||
<para>After disconnecting, logging, a description file is written (if recorded file exists), both files will be chown'ed to
|
||||
the right user and the recorded message will be mailed to him.</para>
|
||||
</sect3>
|
||||
<sect3 id="default_incoming_4"><title>function <function>remoteInquiry</function></title>
|
||||
<para>The <function>remoteInquiry</function> starts by creating a lock file and acquiring an exclusive
|
||||
lock on it to prevent two parallel remote inquiries for the same user. If the lock can't be acquired, an error message is
|
||||
played and the function returns. If locking has succeeded, a list of the voice call numbers in the user directory is compiled
|
||||
by listing the directory, filtering and sorting it. Now, a file called <filename>last_inquiry</filename> is read when it exists.
|
||||
It contains the number of the last heard message. With this information, the old messages can be filtered out to a seperate
|
||||
list and thus the caller can listen only to the messages he doesn't know alredy.</para>
|
||||
|
||||
<para>The number of new messages is played, followed by a small menu where the caller can choose to either record an announcment
|
||||
or hear the recorded messages. If he chooses announcement recording, the function <function>newAnnouncement</function> is called,
|
||||
otherwise <function>remoteInquiry will continue. </function></para>
|
||||
|
||||
<para>Now, a loop will first iterate over the new and then the all old messages. It starts by telling the caller how much messages
|
||||
have been found. Then all messages will be played, repeating the following steps for each one:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>read the description file of the current message</para></listitem>
|
||||
<listitem><para>play an information block containing the current message number, source and destination of the call,
|
||||
date and time.</para></listitem>
|
||||
<listitem><para>play the message</para></listitem>
|
||||
<listitem><para>provide a menu where the caller can go on to the next or last message, repeat the message or delete it</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>At the end, the caller will be informed that no more messages are available and the connection will be finished, followed
|
||||
by releasing the lock acquired at the begin of this function and deleting the lock file.</para>
|
||||
</sect3>
|
||||
<sect3 id="default_incoming_5"><title>function <function>newAnnouncement</function></title>
|
||||
<para><function>newAnnouncement</function> presents the caller some instructions first. Then, the announcement will be recorded
|
||||
to a temporary file. To give the user the ability to check it, it will be played, followed by a menu allowing to save it or to
|
||||
repeat the recording. If the user has chosen to save it, it will be moved from the temporary file to
|
||||
<filename>announcement.la</filename> in the users voice directory and chown'ed to him. The call will be finished with an approval
|
||||
to the caller that it has been saved succesful.</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
<sect2 id="default_idle"><title>idle.py</title>
|
||||
<para></para>
|
||||
<para>The idle script is responsible for collecting jobs from the user directories where they're stored by <command>capisuitefax</command>
|
||||
and sending them to the given destinations. It reads its configuration again from the config files presented in
|
||||
<xref linkend="script_config"/>.</para>
|
||||
|
||||
<sect3 id="default_idle_1"><title>function <function>idle</function></title>
|
||||
<para>After reading the configuration by calling <function>cs_helpers.readConfig</function> and testing for the existence
|
||||
of the directories needed, the userlist is compiled from the list of available sections.</para>
|
||||
|
||||
<para>For each user who has a valid fax setup (otherwise this user will be skipped), the send queue will be looked at. If the necessary
|
||||
directories don't exist, they'll be created. After that, the names of all files in the send queue are filtered to only contain fax
|
||||
jobs and stored in a list called <literal>files</literal>.</para>
|
||||
|
||||
<para>For each found job, a security check is done to see if it was created by the right user. If this check has been successful, a
|
||||
lock file is created and a lock on it is acquired. This prevents the <command>capisuitefax</command> command to abort a job while
|
||||
it is in transfer. After the lock is acquired, the existence of the file is checked (perhaps it has been cancelled before we could
|
||||
acquire the lock?).</para>
|
||||
|
||||
<para>Now, the description file for this job is read and the starttime is checked. If it's not reached, the script will go on with
|
||||
the next job. Some parameters are taken from the configuration and a log message is created. The file is transferred by calling
|
||||
<function>sendfax</function>. The results are stored and logged. If the job was successful, it is moved to the done dir and
|
||||
an approval is mailed to the user. If it wasn't succesful, the delay interval will be determined from the configuration and the new
|
||||
starttime is calculated by increasing the old starttime by this interval. A counter for the used tries is increased and the description
|
||||
file is rewritten with the new values. If the number of tries exceeds a given maximum, the job is moved to the failed dir and the
|
||||
error is reported by mail to the user.</para>
|
||||
|
||||
<para>Finally, the locked file will be unlocked and deleted.</para>
|
||||
</sect3>
|
||||
<sect3 id="default_idle_2"><title>function <function>sendfax</function></title>
|
||||
<para>This function handles the actual send process. After determining the MSN to use from either the <literal>outgoing_MS</literal>
|
||||
setting or from the <literal>fax_numbers</literal> list, a call to the destination is initiated. If it fails, the function returns;
|
||||
otherwise the file will be sent and the connection finished.</para>
|
||||
</sect3>
|
||||
<sect3 id="default_idle_3"><title>function <function>movejob</function></title>
|
||||
<para>This is a small helper function used for moving a job and its accompanying description file to another directory.</para>
|
||||
</sect3>
|
||||
|
||||
</sect2>
|
||||
<sect2 id="default_capisuitefax"><title>capisuitefax</title>
|
||||
<para><command>capisuitefax</command> allows to enqueue fax jobs, list the current queue and abort jobs. It's not used by the
|
||||
&cs; system - it's only a frontend for the users send queue directory. It has several commandline options - for an explanation
|
||||
of its usage, please refer to <xref linkend="usingscripts_send"/>.</para>
|
||||
|
||||
<para>There are three helper functions defined first. <emphasis><function>usage</function></emphasis> prints out a small help if
|
||||
"--help" or "-h" was given as parameter or if a parameter isn't understood. <emphasis><function>showlist</function></emphasis>
|
||||
gets a listing from the users send queue directory and prints it nicely formatted as table. <emphasis><function>abortjob</function>
|
||||
</emphasis> removes a job from this queue. It does this safely to not interfere with the sending process by using a lock file.</para>
|
||||
|
||||
<para>The main code of this script checks the given commandline options first. It sets several variables to the given values.
|
||||
After some checks of the validity of the options, the rights of the user to send faxes and the existence of the necessary
|
||||
directories, it will fulfill the requested task. Either, <function>listqueue</function> will be called to show a listing of
|
||||
active jobs, <function>abortjob</function> will be called to abort a job or the given files are processed and put to the queue.</para>
|
||||
|
||||
<para>To process a job, the existence of it and its format will be checked. Currently, only PostScript is allowed. But as &cs;
|
||||
itself only supports the SFF format, the files will be transferred from PostScript to it by calling <command>ghostscript</command>.
|
||||
Finally, the description file for this job is created containing the given parameters like the destination number.</para>
|
||||
</sect2>
|
||||
<sect2 id="default_helpers"><title>cs_helpers.py</title>
|
||||
<para></para>
|
||||
<para>The <filename>cs_helpers.py</filename> script contains many small helper functions used in the other scripts. These are:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><function>readConfig</function></term>
|
||||
<listitem><para>Reads either the configuration files described in <xref linkend="script_config"/> or an arbitrary
|
||||
config file. Used e.g. for the description files accompanying each received file or job to send.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><function>getOption</function></term>
|
||||
<listitem><para>Get an option from the given user section and fall back to the global section if it's not found.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><function>getAudio</function></term>
|
||||
<listitem><para>Get an audio file from the users directory or fall back to the global &cs; directory.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><function>uniqueName</function></term>
|
||||
<listitem><para>Construct a new file name in a given directory by using a given prefix & suffix and adding a counter. See
|
||||
also <xref linkend="incoming_tut_unique_names"/>.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><function>sendMIMEMail</function></term>
|
||||
<listitem><para>Send a E-Mail with attachment to a given user. Supports also automatic format conversion SFF -> PDF and
|
||||
inversed A-Law -> WAV.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><function>sendSimpleMail</function></term>
|
||||
<listitem><para>Send a normal E-Mail without attachment to a given user.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><function>writeDescription</function></term>
|
||||
<listitem><para>Create a description file which can be read by <function>readConfig</function> later.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><function>sayNumber</function></term>
|
||||
<listitem><para>Supports saying a number using various wave fragments. Works only for german output currently.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>For a detailled description of each function and its usage, please have a look at the script file itself. There are
|
||||
comments describing each function in detail.</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="command_reference"><title>&cs; command reference</title>
|
||||
<para>askdj</para>
|
||||
<para>&cs; provides an internal Python module called <literal>capisuite</literal> which is imported as usual by <literal>import capisuite</literal>.
|
||||
Internal means, it's compiled in the &cs; binary and will only be found if &cs; interpretes the script.</para>
|
||||
|
||||
<para>A complete reference of all functions of this module is auto-generated from the &cs; sources and so you'll find it in the reference
|
||||
manual available locally on <ulink url="../reference/group__python.html"/> or online on
|
||||
<ulink url="http://www.capisuite.de/capisuite/reference/group__python.html"/>.</para>
|
||||
|
||||
<para>As it doesn't make sense to duplicate the information here, please refer to it.</para>
|
||||
|
||||
<note><para>These functions are implemented in C internally and so the reference document shows the C function header instead
|
||||
of the header as you would define it in Python. So please ignore the function header shown there and only have a look at the
|
||||
parameters given under <emphasis>args</emphasis>. I hope this isn't too confusing. Perhaps I'll find a better way to auto-create
|
||||
this document sometimes...</para></note>
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in New Issue