HOWTO: Develop and distribute your fax-enabled application

ZTN1239

ID: ZTN1239

This Zetafax technical note applies to:

• Zetafax CommsEngine version 9

Summary

The Zetafax CommsEngine is a powerful fax solution which offers software vendors the opportunity to add faxing capabilities to their products.

This document is designed for software development personnel or product managers who are planning to add faxing capabilities to their application.  It describes the simple steps in the process from having chosen Equisys as your fax technology partner to deploying your first solution at a customer site.

Developing your application

1. Request an Equisys Software Development Kit (SDK)
2. Install the Zetafax Server and developer tools
3. Register the Zetafax API object model library (if you are using COM API)
4. Develop and test your custom application

Deploying your application at a customer site

1. Obtain a Zetafax CommsEngine for sale to your customer
2. Install the Zetafax CommsEngine
3. Install your custom application, including redistributable Zetafax API components
4. Register the Zetafax API object model library (if you are using COM API)

These stages are described in more detail below.

More information

Developing your application

Request an Equisys SDK

The Equisys Software Development Kit is available to all Equisys ISV partners. Included in the kit is a 5 user, 2 lines Zetafax server and the developer tools required to develop fully integrated applications. 

Full documentation on how to install the server software and on using the development tools is included in the documentation supplied with the developer kit. Additional resources are available free of charge in the support section of the Equisys web site http://www.equisys.com/

Install the Zetafax CommsEngine and development tools

The Zetafax CommsEngine runs under Windows, and supports the same operating systems as the Zetafax server. One or more fax modems, active ISDN controllers or intelligent fax boards are required for sending and receiving faxes. Installation is a very simple process and should take less than 10 minutes. 

During the install process, you will be required to enter a license number supplied with the system.

You will also need to create a Zetafax user account to use for sending and receiving messages.  This can be done during installation or afterwards, using the Zetafax Configuration program.  We recommend that you either choose an account name and description like "AUTOUSER" or "APIUSER", or one which is clearly connected with your company or application (e.g. "MYCO" or "MYAPP").  Note that you do not need to create a network account unless you require it for enhanced security - the Zetafax account does not need to be linked to a network login, though doing so will allow the Zetafax client to login automatically when started.

The installation steps required for the developer tools depend on the method you intend to use to integrate your application with the CommsEngine, as follows:

COM API and C language libraries:

The Zetafax API is installed as part of the Zetafax CommsEngine install to \zfax\ZFAPI. The installed folders contain libraries and include files; you should add the appropriate folders to your development tools (IDE).

API library functions communicate directly with the Zetafax server, using shared files. The API   determines the location of the server through the presence of two files - either a file called ZETAFAX.INI, typically stored in the Program Files\Zetafax Server folder, or a file called ZFCLIENT.INI, typically stored either in the Program Files\Zetafax folder or the user's Application Data folder. ZETAFAX.INI is created when the Zetafax Server is installed. ZFCLIENT.INI is generated when the Zetafax client is run for the first time; however the file can sometimes be copied from another computer if preferred. In addition, registry values can be added to help the API locate these files. These registry values are:

ZSUBMIT:

ZSUBMIT is an automatic submission program which is run automatically as part of the Zetafax server.  It scans a single folder for messages to be sent - this is zfax\SERVER\Z-TEMP by default, though the location can be changed in the Zetafax Configuration program.

To use ZSUBMIT from your application there are no specific installation requirements, other than to ensure that the server is configured to look in the folder your application will use.

Embedded addressing:

Embedded addressing commands are handled by the Zetafax Printer and Zetafax client program.  The Zetafax client must be installed on the application computer, and the Zetafax server and Zetafax client must be running before printing to the Zetafax Printer (though the Zetafax Printer will start the client automatically if set to login automatically).

DDE:

DDE commands are handled by the Zetafax client program.  The Zetafax client must be installed on the application computer, and the Zetafax server and Zetafax client must be running before initiating a DDE conversation.

Register the Zetafax API object model library (if you have not installed the Zetafax client)

If you intend to use the COM API (e.g. from a Visual Basic program), then you will need to register the object model library on the development computer.  You do this from a command prompt as follows:

• Change directory to the location of ZFAPI32.DLL
• Type the command "REGSVR32  ZFAPI32.DLL"
• A dialog box should appear confirming that the registration was successful.

Note: If you have installed the Zetafax client onto your development computer, the COM API is installed and registered automatically. It is installed by default to C:\Program Files\Common Files\Equisys.

Develop and test your custom application

Develop your application as normal.  We recommend that your test cases include a variety of error scenarios such as number busy retries; these will depend on the degree and method of integration used, and the extent to which the application is intended to cope with "normal" errors unattended.

For test purposes, devices on the Zetafax server can be configured in "demonstration mode".  In this mode of operation the server simulates sending messages without connecting to the device.  This removes the need for external connections and destination devices, and reduces the cost for high volume testing.

You configure a device for demonstration mode by editing the configuration file SETUP.INI (located in zfax\SYSTEM\Z-DB).  Find the section for the device towards the end of the file (e.g. "[FCLASS-1]"), then add the following line at the end of the section:

DemoMode: SLOW SEND

Now restart the Zetafax server, and check that the device controller reports "Demonstration mode enabled" as it starts.

Deploying your application at a customer site

Obtain a Zetafax CommsEngine product copy

When you are ready to deploy your fax-enabled solution to your customer, you will need to purchase the appropriate CommsEngine product for your application from Equisys.  You should also ensure that your customer has the appropriate hardware i.e. a PC server, fax hardware and telephone lines available prior to installation.

Install the Zetafax CommsEngine

The CommsEngine products include a CD-Rom with the software and a license number.  Please refer to the documentation supplied in your developer kit or on the CommsEngine CD-ROM for installation instructions.  During installation, the Zetafax server software will be automatically registered with Equisys.

Create a Zetafax user account to use for sending messages, using the Zetafax Configuration program.  This will typically have the same account name used when developing the application (see above), since applications written using the COM API, C language libraries or ZSUBMIT may specify the user name when they run.

Test that the CommsEngine is correctly configured by sending and receiving a fax using the client software.  Instructions are supplied in the Software Guide supplied with your Developer Kit or on the CD-ROM.

Install your custom application, including redistributable Zetafax API components

After installing your application you may need to carry out additional steps, depending on the method your application uses to integrate with the CommsEngine, as follows:

COM API and C language libraries:

Install the Zetafax client program (zfax\SYSTEM\WKSETUP.EXE), this will create a ZFCLIENT.INI file and also install the "ZFAPI32.DLL".

Or

Alternatively, you can create the ZFCLIENT.INI file by copying it from another computer if preferred and copy the following redistributable file from the Software Development kit:

File "ZFAPI32.DLL", to be copied to "%windir%\SYSTEM32"

ZSUBMIT:

There are no specific installation requirements, other than to ensure that the server is configured to look in the folder your application will use.

Embedded addressing:

If your custom application is not running on the Zetafax server computer, install the Zetafax client by running the Zetafax Workstation Setup program (zfax\SYSTEM\WKSETUP.EXE).

DDE:

If your custom application is not running on the Zetafax server computer, install the Zetafax client by running the Zetafax Workstation Setup program (zfax\SYSTEM\WKSETUP.EXE).  You may also wish to set the Zetafax client to startup automatically, by copying it to the Startup program group.

Register the ZFAPI.DLL (if you are using COM API and have not installed the Zetafax client)

If your custom application uses the COM API (e.g. from a Visual Basic program), then you will need to register the object model library on the server on which your custom application is installed. You can do this manually from a command prompt as follows:

• Change directory to the location of ZFAPI32.DLL (i.e. %windir%\SYSTEM32)
• Type the command "REGSVR32  ZFAPI32.DLL"
• A dialog box should appear confirming that the registration was successful.

Alternatively you can do this automatically by calling REGSVR32 from your install program.

Note: If you have installed the Zetafax client, the COM API is installed and registered automatically. It is installed by default to C:\Program Files\Common Files\Equisys.

References

ZTN1240-INFO Zetafax COM API FAQ

ZTN1386-HOWTO Develop and redistribute your SMS-enabled application.

Refer to the Zetafax API Guide for full information about using Zetafax developer tools, and the features available.

For further information about obtaining the Equisys Software Development Kit and reselling the Zetafax CommsEngine, please contact Equisys (for UK and North America) or your local distributor (for other countries).  Contact details may be found at http://www.equisys.com/.

Last updated: 30 July 2004 (DS/SV)