Structural overview of the default scripts

The incoming script handles all incoming connections. It reads two configuration files containing all necessary data which were described in detail in the section called “Script configuration”. 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 callIncoming which will call all other functions if needed.

The remoteInquiry 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 recorded voice calls is compiled by listing the user directory, filtering and sorting it. Now, a file called last_inquiry 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 separate list and thus the caller can listen to messages he doesn't know already first.

The number of new messages is said, 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 newAnnouncement is called, otherwise remoteInquiry will continue.

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:

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 file and deleting it.

The idle script is responsible for collecting jobs from the send queues (where they're stored by capisuitefax) and sending them to the given destinations. It reads its configuration from the files presented in the section called “Script configuration”, too.

After reading the configuration by calling cs_helpers.readConfig and testing for the existence of the archive directories needed, the userlist is compiled from the list of available sections.

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 queue directories don't exist, they'll be created. After that, a list called files with the names of all files in the send queue is created and filtered to only contain fax jobs.

For each found job, a security check is done to see if it was created by the right user. If this check was successful, a lock file is created and a lock on it is acquired. This prevents the capisuitefax command to abort a job while it is in transfer. After that, the existence of the file is checked (perhaps the job has been cancelled before we could acquire the lock?).

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. Otherwise, some parameters are taken from the configuration and a log message is created. The file is transferred by calling sendfax. 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 to the user by mail.

Finally, the lock file will be unlocked and deleted.

capisuitefax allows to enqueue fax jobs, list the current queue and abort jobs. It's not used directly by the CapiSuite system - it's a frontend for the users send queue directory. It has several commandline options - for an explanation of its usage, please refer to the section called “Sending fax jobs”.

There are three helper functions defined first. usage prints out a small help if "--help" or "-h" was given as parameter or if a parameter isn't understood. showlist gets a listing from the users send queue directory and prints it nicely formatted as table. abortjob removes a job from the queue. It does this safely by using a lock file to not interfere with the sending process.

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, listqueue will be called to show a listing of active jobs, abortjob to abort a job or the given files are processed and put to the queue.

To process a job, the existence of it and its format will be checked. Currently, only PostScript is allowed. The CapiSuite core itself only supports the SF format. Therefore, the files are coverted from PostScript to it by calling ghostscript. Finally, the description file for this job is created containing the given parameters like the destination number.

The cs_helpers.py script contains many small helper functions used in the other scripts. These are:

readConfig

Reads either the configuration files described in the section called “Script configuration” or an arbitrary config file like the description files accompanying each received file or job to send.

getOption

Get an option from the given user section and fall back to the global section if it's not found.

getAudio

Get an audio file from the users directory or fall back to the global CapiSuite directory.

uniqueName

Construct a new file name in a given directory by using a given prefix & suffix and adding a counter. See also the section called “Using sensible file names”.

sendMIMEMail

Send an e-mail with attachment to a given user. Supports also automatic format conversion SFF -> PDF and inversed A-Law -> WAV.

sendSimpleMail

Send a normal e-mail without attachment to a given user.

writeDescription

Create a description file which can be read by readConfig later.

sayNumber

Supports saying a number using various wave fragments. Works only for german output currently.

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.