<< Click to Display Table of Contents >>




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.




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




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:





ASCII text


Epson FX or Epson LQ Windows driver


fax format normal resolution (200x100 dpi)


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:





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.


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.


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:  







Message being added to queue.


Message held by user.



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.


Waiting for conversion or for a free device to send the message.


Preparing the message for sending (merging with letterhead, creating coversheet, e.t.c.).


Dialing remote device, or connecting to local printer, etc.



Connection made, sending message to remote device.


Not applicable.


Processing an Abort request, waiting for device controller or convert program to cancel processing of the message.ZFMSG_INCOMING Being received by the device.



Completed (sent) successfully, with no errors. The message may now be deleted (using the ZfxDeleteMsg function).


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)


Related topics

Function error returns and reference

Alphabetical reference

Message information functions

Message transmission history functions

Server and device status functions

Converting from older versions of the API