How to Develop and distribute your fax-enabled application

 

---

 

Developing your application

 

1) Request an Equisys API Developer Kit

The Equisys API Developer 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/

 

2) Install the Zetafax API and developer tools

The Zetafax API 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, which enables both the server and development tools.

 

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 API, as follows:

 

COM API and C language libraries:

The Zetafax API is installed as part of the Zetafax API 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.

 

3) 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.DLLType 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.

 

4) 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

 

1) Obtain a Zetafax API product copy

When you are ready to deploy your fax-enabled solution to your customer, you will need to purchase the appropriate API 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.

 

2) Install the Zetafax API

The Zetafax API typically includes a 1 user, 1 line Zetafax server, with special licensing to enable the API options.  The API 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 API 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 API 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.

 

3)  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 API, 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 API Developer 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.

 

4) 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.