C language API > Function Overview

Function overview

This section gives a brief overview of the functions which comprise the API.

User supplied functions

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.

General routines

Before using any API functions the program should call ZfxAPIInit. This specifies the username to use and returns a handle which is used in subsequent calls. It may be called more than once with different usernames if required. The ZfxAPIClosedown routine should be called by the program for each handle returned by ZfxAPIInit before exiting. The ZfxGetAPIVersion function returns the version number of the library (for printing in a startup message). ZfxCreateAutoFile generates a file in a given directory so that no other files exist with the same body name. Finally ZfxCheckServer checks whether the Zetafax server is running (although several of the other routines will also return an error if the Zetafax server is not running when they are called).

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 sub directory called USERS\\username where username is the username. Message files for sending and received messages are stored by the server in sub directories USERS\\username\\Z-OUT and USERS\\username\\Z-IN respectively. The full pathnames of these directories are returned by the ZfxGetUserArea, ZfxGetUserOutDir and ZfxGetUserInDir functions respectively. Although not normally needed, the ZfxGetSystemArea routine may be used to obtain the full pathname of the SYSTEM sub directory, used for storing letterheads, etc.

Submitting a message

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 user's 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 ZfxCreateCtlFile 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 ZfxSendMsg function makes an entry in the info file and submits a control and data file pair to the server.

Programs which 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.

There are three additional routines ZfxSendSubmitFileFP, ZfxCreateCtlFileFP and ZfxCreateDataFileFP which are provided to assist in porting programs written for older versions of the API. Their functions are the same as their namesakes above, but they use C file pointers instead of file names and are therefore only supported in the static libraries, not in the DLL.

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

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

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

The ZfxAbortMsg function requests the Zetafax server to abort processing of a given message (i.e. 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 ZfxDeleteMsg function can also be used to delete all messages for a given user.

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.

These functions, except ZfxAbortMsg, ZfxHoldMsg, ZfxRushMsg and ZfxReleaseMsg, can also be used for received messages. API licensing

The API must be licensed on each Zetafax system on which you wish to run programs which use it (including the ZSUBMIT program). Call Equisys or your supplier for price details of multiple licenses.