UxFax2 Windows Client/Server
Protocol Description and API
Index
Introduction
The document descibes the protocol used by the UxFax2 Windows Client to
submit faxes to a host computer running the UxFax2 Unix Fax Server software,
and the methods that may be used to submit faxes from a client, of which there
are three;
- Invoke
the client "UxFax Send Control Panel" and allow the user to manually
adjust the send options, including the fax number. The user will need to
manually click the "Send" button
- Bypass
the "UxFax Send Control Panel" and pass the fax number and send options
directly, and optionally display the results of the transmission request
in the "Network Control Panel".
- Bypass
the windows client altogether and submit the fax directly to the
TCP port on the fax server using the client/server protocol.
The simplest methods are the first two, of which the second is probably
the most useful for interfacing with third party applications where the fax
number is known. These two methods are described first;
Invoking the UxFax
Send Control Panel
As part of the installation
of the Windows client, a printer called "UxFax" will have been
created. When a document is printed to this printer, a PCL file is written
to the spool directory configured in the client. The spool directory location
is stored in the registry as a string value named
HKEY_CURRENT_USER\Software\UxFax\1.0\Settings\SpoolFile
Simply printing to this printer will create a print file named "fax.pcl"
in the spool directory and invoke the UxFax Send Control Panel (shown below).
When the file is written, this control panel is displayed allowing the user
to enter a fax number and adjust the send options.
If the fax number is known, this can also be written to a file named "faxcmd.txt"
in the spool directory and that number will be displayed in this control
panel allowing the user to simply click the "Send" button.
Bypassing the UxFax
Send Control Panel
When the fax number is known, the "UxFax Send Control Panel" described
above can be bypassed, and the results of the transmission can optionally
be displayed in the "Network Control Panel".
This method is almost identical to that described above, except the transmission
options are also written intto the second line of the "faxcmd.txt" file
in the spool directory, e.g.;
95034451\r\n
-type pcl -base64 -ok -fine -now -reply phil@realtime.com.au\r\n
*\r\n
|
If the third line of this file
is not blank (as in the above example) the "Network Control Panel"
will be displayed with the results, otherwise if this third line is blank,
nothing will be displayed and the entire fax transmission will occur in
the background.
The options shown above are required as a minimum. These correspond to
the default options generated by the "UxFax Send Control Panel". For a description
of all the available options, refer to send options in the "faxcmd"
manual reference page.
This method allows the options to be altered, such as sending in standard
resolution (-std) instead of fine (-fine), or adding options such as "-ref"
which allows the transmission to appear with a meaningful reference in the
queue.
Client/Server Protocol
Faxes and fax commands may be submitted directly to the fax server, and
bypass the client altogether. This method is the most complex as it will require
detailed programming by the third party application. In summary, the steps
required to send a fax directly to the fax server are;
- Generate a PCL print file encoded using "base64"
- Open a connection to TCP 22101 on the fax server
- Send the command to the opened TCP port, e.g.
- "send - 95034451 -type pcl -base64 -ok -fine -now -reply
phil@realtime.com.au\n"
- Send the encoded print file followed by the end of message string,
i.e;
- Read the result from the opened TCP port
- Close the TCP port when the end of message is receieved.
Alternately, a simple text file may be sent for transmission as a fax.
In this case, encoding a PCL file as base64 is not required. Instead, the
text file may be sent instead of the encoded print file, and the command
would be;
"send
- 95034451 -type ascii -ok -fine -now -reply phil@realtime.com.au\n"
The same method is used to submit simple commands to the fax server. Any
"faxcmd"
command, such as "startup" or "status" may be sent, e.g;
- Open a connection to TCP 22101 on the fax server
- Send the command to the opened TCP port, e.g.
- Read the result from the opened TCP port
- Close the TCP port when the end of message is receieved.
This protocol may be better undertstood by examining how the interface
operates on the fax server. This is descibed next.
The Unix Server
The server runs as an "inetd" process on the
Unix host listening on TCP port 22102.
The actual server process is a simple Unix shell script named $Utools/Utools/bin/faxstat,
shown below. This same script handles all client commands, such as obtaining
the status of transmitted faxes, as well as handling the submission
of faxes for transmission. The shell script code is;
Utools=/usr
FAXCMD=$Utools/Utools/bin/faxcmd
read args
echo $args >&2
while read str &&
[ ! "$str" = EOM ]
do
echo $str
done | eval "$FAXCMD $args
-print pcfax"
echo EOM
|
If you are familiar with shell script, this
may help to describe the protocol. In summary, the script will read a command
from standard input, followed by an "EOM" string. This command will be passed
as the arguments to the "faxcmd" program.
The "faxcmd" response will be written to standard output, followed by
an "EOM" string.
The command, "EOM" strings and response are each terminated by a linefeed
charcater. Carriage return characters are not used.
Simple client commands
The simplest example of a client command is
the server "status" command which will return the overall status of the fax
server.
- The client will open TCP port 22102 to the fax server.
- The client will write "status" followed by a newline character.
- The client will write "EOM" followed by a newline character.
- The client will then read everything written to the TCP port by
the fax server.
- The server will write its response to the command to the TCP port.
- The server will write "EOM" followed by a newline character.
The client command will be a simple two line
text string;
The server response will be verbose and may carry across multiple lines,
each terminated by a newline character, e.g.;
Faxcmd: Request 'status' sent Wed Jun 29
07:31:51 2005\n
Server: Command CMD_STATUS rcv'd
from root@localhost\n
Spooler status: 1 modem(s) attached,
0 active task(s)\n
Modem
Mode
Status\n
modem1
Send only
Waiting\n
EOM\n
|
If the server response contains a "bell" (ASCII
0x07) character, this indicates that the server has returned an error result,
such as;
^GFaxcmd: Request 'status'
sent Wed Jun 29 07:41:02 2005\n
Client error 8: The fax server is not running. Cannot open lock file\n
EOM\n
|
Sending an ASCII fax
ASCII files may be sent without any complex
encoding. In summary, the steps are;
- The client will open TCP port 22102 to the fax server.
- The client will write command followed by the file.
- The client will write an "EOM"string.
- The client will then read everything written to the TCP port by the
fax server.
- The server will write its response to the command to the TCP port.
- The server will write an "EOM" string.
The client command will contain the fax command
on the first line followed by the text body of the fax. Lines are separated
by newline characters (\n) and pages are separated by formfeed characters
(\f);
send - 95034451 -type ascii -ok -fine -now\n
This is the first line of
the fax message body\n
This is the second line\n
\fThis is the
first line of the second page\n
And this is the second line\n
EOM\n
|
The server response will be verbose and may carry across multiple lines,
each terminated by a newline character, e.g.;
+----------------------------------------------------------------+\n
|
Facsimile Transmission Request Summary
|\n
+----------------------------------------------------------------+\n
File name
: Standard Input (Standard Input)\n
File type
: PCL - LaserJet print file\n
Attachments : None\n
Dial Mode
: Manual Dial - No Name & Address\n
Send when
: Immediate\n
Retry Scheme : default\n
Resolution : Fine
- 200dpi vertical\n
Reply to
: phil@realtime.com.au\n
Faxcmd: Request 'send' sent
Wed Jun 29 23:39:58 2005\n
Server: Command CMD_ENQUEUE
rcv'd from root@localhost\n
Request 0015 has been queued\n
EOM\n
|
Sending a PCL fax
A high quality print image may be prepared
as a PCL file and sent by the fax server. The mechanism to do this is much
the same as sending an ASCII file, except the PCL file must be encoded using
base64 so it is sent over the TCP link as ASCII.
- Generate a PCL print file encoded using "base64"
- Open a connection to TCP 22101 on the fax server
- Send the command to the opened TCP port, e.g.
- "send - 95034451 -type pcl -base64 -ok -fine -now -reply
phil@realtime.com.au\n"
- Send the encoded print file followed by the end of message string,
i.e;
- "EOM\n"
- Read the result from the opened TCP port
- Close the TCP port when the end of message is receieved.
The client command will consist of the fax command on the first line
followed by the PCF fax page encoded in base64;
send - 95034451 -type pcl -base64 -ok -fine -now\n
G0UbJmwwUxsqcjBGGyZsME8bJmwwUxsmbDFIGyZsMmE4YzFFGyp0MzAwUhsmbDFYGypi\n
ME0NGypwMjcwWRsqcDYwMFgbKmMxNjUzNUQbKXM2NFcAQAACAAAAdgCPAJYAAQE1AIQA\n
fABdAAAA/gAAAAAAAAAAAAAAAAAAAAAAAAAAAABUaW1lcyBOZXcgUm9tYW4AGypjMTY1\n
[...ditto...]
wP/D//f8H//+Af+D/wD///AAf//gP///GypiMzZXAAAAAA//AH/4D/z/wP/B/+f8D//8\n
Af+B/wB///AAf/+AH//+GypiMzZXAAAAAAf/AD/wD/z/wP/A/8f8A//wAP8B/gAf/8AA\n
H/8AB//8GypyQgwbRQ==\n
EOM\n
|
The server response will be the same as all other commands. i.e. It will
be verbose and carry across multiple lines separated by newline characters
(\n) and terminted by "EOM\n". If the server responds with an error, the
response will contain a bell (0x07) character.
