Converting programs from older versions of the Zetafax API
The API has been significantly extended over time. Existing API programs will continue to work correctly, and need not be rebuilt. However, any program which is to be rebuilt with the new version of the library will need some modification.
Version differences from versions 4.5 to 5 and 5 to 6 are detailed below.
For API 4.5 programs, a set of porting macros are included in the header file ZFAPI.H to allow programs to be ported with minimal changes (the addition of "#define" line before ZFAPI.H is included). They translate from the old function names to the new ones adding the necessary extra parameters. These are enabled by adding the following line before ZFAPI.H is included:
#define API_VER 0x450
For API 5 programs the superceded function names and structures are still supported by the DLLs and libraries, but by default are not included in the header file to assist new programmers. To continue using the old functions, add the following line before ZFAPI.H is included:
#define API_VER 0x500
However, the modifications required to reflect the changes described above are minor and quick to do. For clarity, it is therefore recommended that these changes are made in any programs which are still being developed or maintained, rather than relying on the porting macros.
Differences between version 4.5 and version 5
The API was significantly extended with Zetafax 5.
New features included:
- DLL version of library functions added
- Support for received faxes
- Retrieval of default user settings
- Support for multiple data files for each message
- Specifying the coversheet text in SUBMIT files
These enhancements made it necessary to make a number of changes to the original functions. The changes necessary for programs using version 4.5 are:
| 1. | All functions have been renamed from Zf... to Zfx... (to ensure that any mismatching of old and new source code gives linker warnings). |
| 2. | Previously a function named ZfPrintError had to be written and was called directly by the API libraries. This function can now have any name, and is passed as a parameter to ZfxAPIInit. The prototype of the function has now changed to: void ZFAPICALLBACK Proc(CHAR FAR *) |
| 3. | All functions other than ZfxAPIInit and ZfxGetAPIVersion now take a session handle (of type ZFSESSIONHANDLE) as the first parameter. This is returned in the first parameter by the ZfxAPIInit function. |
| 4. | The following functions have an extra parameter of type ZFMSGDIR, to specify whether the function should act on the OUT or IN directory: ZfxAbortMsg, ZfxHoldMsg, ZfxReleaseMsg, ZfxDeleteMsg, ZfxCheckNewMsgStatus, ZfxGetMsgInfo, ZfxGetMsgList, ZfxGetMsgHistory |
| 5. | ZfxGetAPIVersion has an additional parameter to return an integer value giving the version number. This can be NULL if not required. |
| 6. | The functions ZfSendSubmitFile, ZfCreateCtlFile and ZfCreateDataFile have been changed so they now take file names (CHAR FAR *) instead of file pointers (FILE *) to allow them to be used in the DLL version of the library. Three functions ZfxSendSubmitFileFP etc have been supplied in the static library version of the API to simplify porting of existing applications; these take file pointers as before. |
Differences between version 5 and version 6
The API has been extended again for Zetafax 6.
New features include:
- Support for the subject line in faxes
- Inclusion of Least Cost Routing information in message status, message history, and server status calls
- Info structures and functions extended
These enhancements made it necessary to add new some new functions to the API. The new functions are similar to the original functions, but include extra parameters for newly supported features.
The following structures are new, replacing the equivalent structures without the "EX" ending:
ZFMSGINFOEX
ZFMSGHISTORYEX
ZFSERVERINFOEX
The following functions are new, replacing the equivalent functions without the "Ex" ending:
ZfxGetServerStatusEx
ZfxGetMsgHistoryEx
ZfxGetMsgInfoEx
ZfxGetMsgListEx
Related topics
Function error returns and reference