HotWire EasyFAX: Client Software Interfaces

This function enables client software programs from virtually any operating environment to use HotWire as a fax server. There are very strict rules that have to be obeyed in order for this to work. There are two external interfaces that can be used, one is a LINUX process that can be called, and the other is a "file" into which requests can be placed. We will discuss the programatical interface first, most useful for users of UNIX/LINUX programs that wish to interface with the HotWire fax spooler.

Programitcal Client Interface

HotWire includes a program called hwdispatch.pl. Its suffix of .pl is a convention signifying that it is a PERL script. It can be called from any application whatsoever on the LINUX/UNIX computer for dispatching faxes to the HotWire spooler subsystem. Once submitted to the spooler, the fax can be managed and tracked through the usual HotWire user interface. Typing hwdispatch.pl -h will print out the usage of the command thus:
 
hwdispatch: Wrong number of arguments
USAGE: hwdispatch.pl {params}
Where { params } are:
-t tel_num
-Z Subject
-C Coverpage_filename (or NOCOVER)
-F From_name
-T To_name
-p Priority [0-5] (0 is higher)
-U UserID
files Space-separated filenames to convert and send
NOTE: You must quote any arguments that contain spaces.

As you can see hwdispatch takes the arguments necessary to send the file to whichever destination you choose. Some of the arguments are obviously necessary, but some others are optional. Here's an explanation:
 
-t The telephone number to dial
-Z Subject matter. eg. -Z "Regarding our purchase order"
-C Name of postscript coverpage file
-F Name of person sending this fax. eg. "Gary Heller"
-T Name of person receiving this fax. eg. "Dirk Haaga"
-p Priority. 0 = as soon as possible, 5 = send last
-U Userid of "owner" of this fax - other users can't delete it 
files List of filenames separated by spaces. These files must be either ascii or postscript. They are converted into a single fax and appear in the order in which they are entered on the commandline.
Sample command:
    hwdispatch.pl -t 1-407-834-8013  -Z "Test Fax"  -T  "Myself"  -T "Myself again" -U 0
 
 

Client Request Queue Interface

This interface exists for those clients that cannot execute UNIX/LINUX processes directly.  This interface requires  that the client be able to see the HotWire system's filename space.  This means that the client systems must be able to see the directories on the LINUX/UNIX server.   This is normally accomplished via NFS, or the SAMBA package.

Requests from these clients must be written into the request queue in a specific format.  Since the request queue accepts only ascii lines, a simple printer driver could easily send its requests to this file instead of a printer device.  This requests is picked up by the HotWire Reques Queue monitor and dispatched.  Once this has been done, the fax can be managed through the usual  HotWire user interface.  This Request Que is actuallay a  named pipe, for those of you who know  what that means.  In order for clients to be able to write into the Request Queue they must obviously be able to see the file, and the HotWire Client Request Monitor must be active.

To enable the HotWire Client Request Monitor you must use the HotWire user interface and choose External off the main screen menu and then choose Request Queue - Clients.   You are presented with the following dialog:

The Pathname of client Request Queue must be the full pathname (from the LINUX viewpoint) of the Request Pipe.  It must obviously must be in a place where the client system can see it.  There's no point in putting it in, say, /tmp/RequestQueue (as in the example) unless the client systems can see the /tmp directory.  Also, bear in mind that not all operating systems can handle case sensitive filenames.  Do NOT put spaces in the filename.  Some operating systems don't like that either.

The checkbox labelled Client Queue Enabled is how we determine if we are accepting requests from client systems.  If the Client Request Queue monitor is currently active this checkbox will be checked.  Also, you can see the checkbox on the External menu next to the Client Queue option.  If you exit this dialog with this checkbox enabled the Client Request Queue will be active, otherwise the Client Request Queue will be inactive and you won't be able to send requests from other operating systems other than UNIX.

Following are the rules for making requests to the HotWire fax server from a foreign operating system.   There is a very limited vocabulary that the Client Request Monitor understands.  In addition, the words can only be used at certain times during the request cycle to be meaningful.  In short, every "phase" or command that the Client Request Monitor understands starts with a BEGIN statment and ends with an END statement.

To send a request to the HotWire spooler you must first print./write to the request queue the BEGIN REQUEST command.  It must be on a line by itself, and must the the first thing sent to the Request Monitor.  The last command sent when you have completed supplying the specifics of your request is END REQUEST.  Much like the hwdispatch.pl interface, there is a minimal amount of information required in order to correctly queue a fax for transmission.  The minimal requrements are:
 

From= Mandtory - It is not necessary to quote the text after the'=' sign
To= Mandtory - It is not necessary to quote the text after the'=' sign
Dial= Mandtory - It is not necessary to quote the text after the'=' sign
ATTACH= Optional - the full pathname of a file in the UNIX filesystem to attatch.  Must be either ascii or postscript.  You man have up to 20 attatchments, each with its own ATTACH= statment, one per line.  Remember:  you cannot ATTACH a file that is on the client system unless the LINUX/UNIX computer can access its pathname.  Use the BEGIN FILE command (below) to do this.
Subject= Optional - The subject matter for this fax
Userid= Optional - The user id of the UNIX/LINUX user who can delete this fax
BEGIN REQUEST Mandatory - Always the first command sent to the request queue
END REQUEST Mandatory - Always the last command sent to the request queue
BEGIN FILE Optional - This command must also appear on a line by itself.  It signifies that every line appearing in this file from the next line onward will be part of an ATTACHMENT until the END FILE command is encountered.  You may include any number of BEGIN FILE/END FILE commands.  They behave in the same manner as "here" documents in the Bourne, Korn, Bash and other shells.  Since this command takes its data for the file one line at a time, the data MUST be ascii.  Binary data cannot be embedded into the request since we can't tell where it ends.
END FILE Optional - Terminator of fiel data from the BEGIN FILE command.
Here is an example request that would be sent to the Request Queue: BEGIN REQUEST 
From=Darth Vader 
To=James Richards 
Dial=834-1973 
ATTACH=/etc/profile 
Subject=This is the subject 
BEGIN FILE 
sub init_params() 
{ 
    if (! -r $hw_license ) { 
        print "ERROR: Can't read /etc/HotWire - aborting!\n"; 
        exit 1; 
        } 
    $hwfd = FileHandle->new(); 
    open($hwfd, "< $hw_license") 
            || die "ERROR: Can't open HotWire license file.\n"; 
    $hwroot = <$hwfd>; 
    chomp($hwroot); 
    $hwfd->close(); 

    $hwtmp = $hwroot . "/tmp"; 

    return 1; 
} 
END FILE 
Userid=101 
ATTACH=/var/log/httpd/access_log.1 
ATTACH=/var/log/httpd/access_log 
BEGIN FILE 
** Now is the time for all good men 
** to come to the aid of the party. 
END FILE 
ATTACH=/var/log/httpd/access_log.4 
END REQUEST