Before we'll continue with writing scripts, please let me tell you some words about the file formats the CapiSuite core uses.
CapiSuite always reads and saves files in the native format as they are be expected and given by the CAPI ISDN drivers. This preserves it from having to convert everything from and to other formats thus reducing unnecessary overhead.
As these formats aren't that well-known and you will need special tools to convert or view/play them, I'll give you a short overview of how you can do this.
Most likely, your scripts will convert the special ISDN file formats to well-known ones for sending them to you via e-mail for example. Nevertheless, I'd advice you to store the received and sent files in the native CapiSuite formats somewhere. This will protect you from losing data in the case the conversion fails and will help you in debugging problems which may arise with your scripts.
All tools which I refer to here are described in the section called “Software”. See there for informations how to get them.
ISDN transmits voice data as waves with a sample-rate of 8kHz in mono. To save bandwith, a compression called A-Law is used (at least in Europe, other countries like the USA use u-Law which is quite similar to A-Law). For any reason beyond my understanding, they use a bit-reversed form of A-Law called "inversed A-Law".
There are two possible ways to create A-Law files.
The first one is to call your computer with your phone (either use the default answering machine script and configure it as described in answering_machine.conf t will disconnect.
After disconnecting and logging, a description file is written (if the recorded file exists), both files will be chown'ed to the right user and the recorded message will be mailed to him/her.
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:
read the description file of the current message
play an information block containing the current message number, source, destination, date and time of the call.
play the message
provide a menu where the caller can go on to the next or last message, repeat the current message or delete it
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.
newAnnouncement presents some instructions to the caller first. Then, the new 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 him/her 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 announcement.la in the users voice directory and chown'ed to him/her. The call will be finished with an approval to the caller that it has been saved succesfully.
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.
This function handles the send process. After determining the MSN to use from either the outgoing_MSN setting or from the fax_numbers list, a call to the destination is initiated. If it fails, the function returns; otherwise the file will be sent and the connection finished.
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 j