HOWTO: Using the Zetafax API functions

ZTN1066

ID: ZTN1066

This Zetafax technical note applies to:

• Zetafax 6

Summary

The 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.

Programs can submit new messages by creating an ASCII text file in a given format, then calling a simple function.  The format is termed SUBMIT file format, and gives details of the recipients and message options to use.  It can either contain the message text (including text formatting such as bold and underlining) or refer to other text or graphic files containing the message.  This is similar to submitting the file using the ZSUBMIT program (which uses the API library), but gives more direct control.

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.

More information

Once submitted, messages can be monitored using the Zetafax client.  Alternatively a range of other function calls allows programs to control and obtain information about the messages.  Programs can also get details about user settings and control the Zetafax server programs.

The functions are supplied as both static object libraries and 16 and 32-bit DLLs, with a C header file.  API programs may be built with the static library only, or use the DLL as preferred.

The following operating systems are currently supported:

• Microsoft Windows Vista Business and above
• Microsoft Windows Server 2003
• Microsoft Windows  2000
• Microsoft Windows  NT (Intel) versions 3.51, 4.0
• Microsoft Windows  NT (Alpha AXP, PowerPC) version 3.51, 4.0
• Microsoft Windows  95/98
• Microsoft Windows version 3.1/3.11
• MS-DOS version 5.0 or later

Installation and use

The Zetafax API toolkit pack contains a license number for the Zetafax server to allow API programs to run.  A separate API toolkit license number is required for each Zetafax system on which you wish to run programs that use it (including the ZSUBMIT program); this is added to the system using the " Register or upgrade software" option in the Zetafax Configuration program.

The C language libraries are available separately.  Instructions for obtaining them are included in the API toolkit pack. The C language libraries only need to be installed on your computer if you want to build programs using them. To use other parts of the API (including the ZSUBMIT program) it is sufficient just to add the API toolkit license to the Zetafax server.

The static libraries and DLL stub libraries are supplied for Microsoft compilers (Visual C++ and Developer Studio). However the DLLs can also be used with other compilers provided either a stub library is produced (using the tools provided with the compiler), or the program uses run-time procedure linking (eg using LoadLibrary and GetProcAddress function calls).

To install the files, run the self-extracting executable and follow the instructions on screen. The setup program will suggest a default directory in which it will attempt to install the files C:\ZFAPI.

Add the INCLUDE and relevant LIB directory to the compiler and linker search paths. Depending on the development environment being used , Tthis can be done by modifying the INCLUDE and LIB environment variables or from within Visual C or Developer Studio the development environment directly.

The following table describes the constituent parts of the C language API:

File system structure

When the API is initialised a Zetafax user name must generally be specified. Messages submitted by the API will appear as if submitted from a Zetafaxclient logged on as this user. Similarly, the message defaults (eg the coversheet to use and the sender name) will be those for the user, exactly as if you submit a message from the Zetafax client without changing any of the default values.  The user given must have been added in the normal manner.

Message files for sending are stored in the user's OUT directory.  The full pathname of this is typically:

zfax\USERS\username\Z-OUT

where 'zfax' is the Zetafax base directory, as specified when the system was installed. API programs should use the ZfxGetUserOutDir function to get the name of this directory if required.

A message for sending comprises at least two files in the OUT directory - a CONTROL file and a DATA file.  Both files (and all other files created by the server relating to this message) have a common file body name, with different extensions for the different files.  So for example files for message " ~SEND000" would have file names of format " ~SEND000.*" .  " ~SEND000" is referred to in the API as the message body name, and it is this which 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 a file with extension " .CTL" .  This is an ASCII text file and gives full details of the options to be used in preparing a message for sending (the coversheet, letterhead, priority etc), together with details of the intended recipients of the message (name, organizationorganisation, fax number etc).  The file is updated by the server as the message is processed to give details of 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.  The extension depends on the format of the data.  Supported formats include:

The message may also have one or more additional DATA files.  These have the extensions " .001" , " .002" etc. (in sequence), and are added to the standard DATA file automatically at the time of preparation.  They are not referenced directly in the CONTROL file, but instead the server looks for additional files in order (starting from .001), until it finds the next one in the sequence missing.  The additional files can be in any format supported by the server - they do not need to be in the same format as the main DATA file.

Received message files are stored in the user's IN directory.  The full pathname of this is typically

zfax\USERS\username\Z-IN

where 'zfax' is the Zetafax base directory, as specified when the system was installed. API programs should use the ZfxGetUserInDir function to get the name of this directory if required.

Received messages are similar to sent messages as described above.  They also comprise a CONTROL file and a DATA file, which is generally in TIFF fax format

Function overview

This section gives a brief overview of the functions that comprise the C language API. Full details of each function are given in Zetafax API toolkit guide page 69 'C language API'.

User supplied routine

If an API function encounters an error, it can call a user-supplied error routine with a textual error string before returning an error code to the calling program.  This can be particularly useful when writing or testing the application, or to log additional information if an error occurs.

General routines

Before using any API functions the program should call ZfxAPIInit. This specifies the Zetafax user account to use and returns a handle that is used in subsequent calls.  It may be called more than once with different user names if required.  The program should call the ZfxAPIClosedown routine for each handle returned by ZfxAPIInit before exiting.

User information

Messages submitted by API programs use the Zetafax user's default settings for any message options which are not specified directly. The ZfxGetUserCoversheet and ZfxGetUserFromname functions return the user's default coversheet and sender name, and are used when a program wants to change its behavior depending on these settings.

Location of files 

The standard Zetafax installation gives each user a base directory called zfax\USERS\username (where 'zfax' is the Zetafax base directory specified at installation time). Each user's message files for sent and received messages are stored by the server in directories zfax\USERS\username\Z-OUT and zfax\USERS\username\Z-IN.

The full pathnames of these directories are returned by the ZfxGetUserArea,ZfxGetUserOutDir and ZfxGetUserInDir functions respectively.  The ZfxGetSystemAreafunction may be used to obtain the full pathname of the zfax\SYSTEM directory, used for storing letterheads etc. The ZfxGetAPIVersion function returns the version number of the library (typically this is used for printing in your applications startup message). ZfxCreateAutoFile generates a file in a given directory so that no other files exist with the same body name.

Server status

ZfxCheckServer checks whether the fax server is running (although several of the other routines will also return an error if the fax server is not running when they are called). ZfxGetServerStatusEx returns information about the server, including the number of queued messages in various states, the status of each of the devices, and the status of any links to remote servers.

Server control

ZfxStartServer, ZfxStopServer and ZfxRestartServer can be used to control the Zetafax server programs for completely automated systems.

Message control

The ZfxAbortMsg function requests the fax server to abort processing of a given message (ie stop preparation or transmission of the message).  When the server has completed processing it sets the message status to OK or FAILED.  Messages in either of these states may be deleted from the INFO file by calling ZfxDeleteMsg - optionally, this will also delete the CONTROL and DATA files for the message, together with any other temporary files generated by the server.  The ZfxDeleteMsgfunction can also be used to delete all messages for a given user, or for received faxes.

The ZfxHoldMsg and ZfxReleaseMsg functions can be used to pause and then resume processing for a specific message.  Held messages are not submitted to devices for sending, though they retain their position in the queue.

Submitting faxes

The simplest method of submitting a fax for sending is to create an ASCII text SUBMIT file containing both the message options and the message text, then call the ZfxSendSubmitFile function.  This creates a CONTROL and DATA file in the users OUT directory, then submits the message to the server (which also makes an entry in the INFO file for that user).

Alternatively these three stages may be carried out independently.  The ZfxCreateCtlFileEx function interprets the %%[MESSAGE] section of a SUBMIT file, which contains details of the message options and addresses, and generates a CONTROL file.  The ZfxCreateDataFile interprets the %%[TEXT] section of a SUBMIT file to generate an ASCII text or Epson FX format data file if required (or a file of the correct format could simply be copied or created by the program).  Finally the ZfxSendMsgEx function makes an entry in the INFO file and submits a CONTROL and DATA file pair to the server.

Programs that are unable to store a session handle for passing to the other routines can use ZfxVBSendSubmitFile. This is a self contained function which initializes an API session, submits a file, then closes the session again, and is ideal for calling from Visual Basic or macro languages.

Message information

Once a message has been submitted to the fax server, its status may be obtained using the ZfxGetMsgInfoEx function.  When the message completes this function also specifies whether it was successfully transmitted.  The ZfxGetMsgHistoryEx function can be used to retrieve the full transmission history for the message, including details such as LCR routing, the number of dial attempts made and the connection time.

The ZfxGetMsgListEx function returns the status of all messages currently queued (or completed but not yet deleted) for the given user.  The ZfxCheckNewMsgStatus function is used in conjunction with this - it checks whether the status of any messages for the user have changed since it was last called to save the overhead involved in calling ZfxGetMsgListEx unnecessarily.

References

For more information on using C language callable functions see the Zetafax API toolkit guide page 69 'C language API'.

Last updated: 15 May 2000 (GC/GW)