C language API

The C language Application Programmer's Interface (API) allows application programs to submit faxes to the Zetafax server for sending, and to control and monitor their progress as required.

A simple function call is provided to submit an ASCII text file in a given format. This format (termed Submit file format) includes details of the recipients of a message, in addition to the message text which can include text formatting such as bold and underlining. See The ZSUBMIT program for more on the Submit file format.

A range of other function calls allow other supported file formats to be submitted, and give full control over messages queued for a given user.

Libraries

The API comprises a set of C callable functions. It is distributed as a set of object libraries and a DLL (for use in different environments) for building into the application programs, together with a C header file containing definitions required to call the API functions. The following operating systems are currently supported:

•Microsoft Windows XP Professional

•Microsoft Windows Vista

•Microsoft Windows 7

•Microsoft Windows Server 2003

•Microsoft Windows Server 2008

Compilers

The object libraries for the API are available for use with the Microsoft C/C++ compiler.

File system structure

When the API is initialized you must specify a Zetafax username. Messages submitted by the API will appear as if submitted from a client logged on as this user, and the defaults for items such as the coversheet From name will be those for the user (exactly as if you submit a message from the client without changing any of the default values).

Store the message files to be sent in the user's out sub directory USERS\\username\\Z-OUT, where username is the username. If necessary API programs can use the ZfxGetUserOutDir function to get the name of this directory.

A message for sending consists of two files in the out directory: a control file and a data file. Both of these files, and all other files created by the server relating to this message, have the name filename.ext where filename identifies the message, and ext identifies the type of file. The filename is referred to in the API as the message body name, and this is supplied to the API functions when specifying messages to submit, delete, etc. The ZfxCreateAutoFile function is used to create a file with a unique body name in a given directory.

The control file is identified with a .CTL extension. This is an ASCII text file and gives full details of the options to be used in preparing a message for sending, including the coversheet, letterhead, and priority, together with details of the intended recipients of the message (name, organization, fax number, etc.). The file is updated by the server as the message is processed to give details of the progress for each addressee, errors, etc. For use with the API this file will generally have been created by interpreting a Submit format file.

The data file contains the message to be sent, and its extension depends on the format of the data. Supported formats are as follows:

Extension	Format
.TXT	ASCII text
.EPN	Epson FX or Epson LQ Windows driver
.G3NTIFF	fax format normal resolution (200x100 dpi)
.G3FTIFF	fax format fine resolution (200x200 dpi)

Message information

When a message is submitted to the server for sending (after creating a control file and a data file for the message), an entry is made in the info file in the user's out directory. This entry includes the file name of the message, the comment associated with it, and the current status of the message (converting, sending, etc.). The server is then notified that a new message is ready for sending, and will add the message to its queue.

The status field is updated by the server program as the message is processed. When the server completes processing of the message and the status has changed to OK or FAILED the message may be deleted. This is done by removing the info file entry then deleting the message files, and may be done either from the client or via the API.

Details of a message in the info file may be obtained using the ZfxGetMsgInfo or ZfxGetMsgList routines, giving details of a single message or all messages in the info file respectively. These store the information in a data structure of type ZFMSGINFO. The fields in this structure are as follows:

Field	Structure
szBody	Character string giving the body name of the message files (i.e. the file name without extension or preceding period.). The maximum length of this string (excluding terminating NULL) is given by the constant ZFMSG_BODY_LEN.
szComment	Character string giving the description of the message being sent (as displayed on the right in the client main display). The maximum length of this string (excluding terminating NULL) is given by the constant ZFMSG_COMMENT_LEN.
Status	Current status of message. This is a variable of type ZFMSGSTATUS, and the value is one of the ZFMSG_??? values listed below.

The following list gives the possible states for a message and their meanings:

State	Meaning
ZFMSG_ADDING	Message being added to queue.
ZFMSG_HELD	Message held by user.
ZFMSG_DEFERRED	Message waiting for sending after a specific time, either because that time was specified when the message was submitted, or the user does not have sufficient permissions to send until after the given time.
ZFMSG_WAITING	Waiting for conversion or for a free device to send the message.
ZFMSG_CONVERTING	Preparing the message for sending (merging with letterhead, creating coversheet, e.t.c.).
ZFMSG_CONNECTING	Dialing remote device, or connecting to local printer, etc.
ZFMSG_SENDING	Connection made, sending message to remote device.
ZFMSG_SCANNING	Not applicable.
ZFMSG_ABORTING	Processing an Abort request, waiting for device controller or convert program to cancel processing of the message.ZFMSG_INCOMING Being received by the device.
ZFMSG_OK	Completed (sent) successfully, with no errors. The message may now be deleted (using the ZfxDeleteMsg function).
ZFMSG_FAILED.	Completed with one or more errors. Details of the errors which occurred are listed in the control file, although this would normally be checked manually. The message may now be deleted (using the ZfxDeleteMsg function)