Overview

 

---

 

Introduction

 

This document tells you how to  configure and use the COM API.

 

Registration

 

Like all COM components ZfAPI32.dll must  be registered before it can be used. This is done using the program regsvr32 as follows:

 

 

Using the COM API in Visual Basic

 

The COM API is primarily intended for  people using Visual Basic. There are two ways of doing this:

 

•The recommended way is to add the Zfapi32 type library as a reference to your project. This enables early binding and access to all the constants and interfaces:  

 

' Create new Zetafax object and Logon  

Dim oZfAPI as New ZfLib.ZfAPI  

Dim oUserSession as ZfLib.UserSession  

Set oUserSession = oZfAPI.Logon("ADMINIST", False)

 

•You can also use the IDispatch interface and create objects using CreateObject and the ProgID:  

 

' Create new Zetafax OBJECT USING CreateObject and Logon  

DIM oZfAPI AS OBJECT  

DIM oUserSession AS OBJECT  

Set oZfAPI = CreateObject("ZfAPI32.ZfAPI")  

Set oUserSession = oZfAPI.Logon("ADMINIST", FALSE)

 

Using the COM API in Visual C++

 

There are three ways of accessing COM  objects in Visual C++:

 

•Win32 API. (Only for those who like to do it the hard way!)

•MFC OLE can be used to generate class wrappers for the ZfAPI32 type library using the Class Wizard.

•People using version 5.0 and later of Visual C++ can use the #import compiler directive to import ZfAPI32.dll. The compiler generates header files containing classes wrapping the interfaces, smart pointers, and the typdefs for the enumerations. This is the recommended way to use the COM API in Visual C++.

 

For example:  

 

// Import Zetafax DLL without the ZfLib  namespace this will  

// generate two header files, ZfAPI32.tlh and ZfAPI32.tli,

// which contain the definitions of the interfaces and enums  

#import "ZfAPI32.dll" no_namespace

 

void DoSomething()  

{

 // Create new Zetafax object and Logon

 IZfAPIPtr pZfAPI(_T("ZfAPI32.ZfAPI"));        

 IZfUserSessionPtr pUser(pZfAPI->Logon(_T("ADMINIST"), false);

 ...

}

 

Using the COM API in .NET

 

1. From within Visual Studio select the add a reference option. The following menu will appear:

 

 

2. Select the COM tab option

 

3. Move to the end of the list, and search for the Zfapi32 1.4 Type library component. Select it by ensuring the component is selected and clicking on the Ok button.

 

Should the Zfapi32 1.4 Type library component not be present, then select the browse option to search for the *.dll file. In a standard Zetafaxsetup, this file is found in the following location:

 

C:\Program Files\Zetafax Server\ZFAPI\LIB\I386\Microsoft

 

4. You can now call functions present in the Zetafax library, by using references to the Zflib namespace within your code for example:

 

Zf­Lib.­ZAPI

 

5. Ensure you distribute the interop.zflib.dll file found in the build directory of your code.

 

Code Samples

 

The following samples are written in C# and Visual Basic .NET. The other .NET languages (Managed C++, Visual J#) are very similar and these examples can easily be adapted for use in these environments.

 

Note:  To avoid the usage of long  type-names  declare the following namespace at the top of the file:

using ZfLib;

 

The API fully supports exception handling  and it is recommended that you use the try-catch mechanism to receive meaningful error messages and descriptions from the Zetafax COM API . (The examples below demonstrate this).

 

1.        The following example demonstrates sending a fax using the COM API:

 

VB.NET:

 

' Declare objects

    Dim oZfAPI As New ZfLib.ZfAPI

    Dim oUserSession As ZfLib.UserSession

    Dim oNewMessage As ZfLib.NewMessage

 

     Try

 

        ' Logon and create NewMessage:

         oUserSession = oZfAPI.Logon("ADMINIST", False)

         oNewMessage = oUserSession.CreateNewMsg

 

        ' Set properties:

         oNewMessage.Recipients.AddFaxRecipient("Sam Smith", _

                                                "ACME plc", _

                                                "020 7123 4567")

         oNewMessage.Text = "I am a fax!"

         oNewMessage.Priority = ZfLib.PriorityEnum.zfPriorityUrgent

 

        ' Send!

         oNewMessage.Send()

 

     Catch ex As Exception

         System.Windows.Forms.MessageBox.Show(ex.Message,

    "ZetaFax Error",

    MessageBoxButtons.OK,

    MessageBoxIcon.Error)

    End Try

 

C#:

 // Declare objects

 ZfAPIClass oZfAPI = new ZfAPIClass();

 UserSession                 oUserSession;

 ZfLib.NewMessage oNewMessage;

 

 try

 {

         // Logon and create NewMessage:

         oUserSession = oZfAPI.Logon("ADMINIST", false);

         oNewMessage  = oUserSession.CreateNewMsg();

 

         // Set properties:

         oNewMessage.Recipients.AddFaxRecipient("Sam Smith",        //TO

                                                            "ACME plc",        //Organization

                                                            "020 7123 4567");//Fax number

         oNewMessage.Text = "I am a fax!";

         oNewMessage.Priority = ZfLib.PriorityEnum.zfPriorityUrgent;

 

         // Send!

         oNewMessage.Send();

 }

 catch (System.Runtime.InteropServices.COMException ex)

 {

         System.Windows.Forms.MessageBox.Show(ex.Message,

"ZetaFax Error", MessageBoxButtons.OK, MessageBoxIcon.Error);

 }

 

 

2.        The code below demonstrates message information handling:

 

VB.NET:

 

    ' Declare objects:

    Dim strBody As String

    Dim oZfAPI As New ZfLib.ZfAPI

    Dim oUserSession As ZfLib.UserSession

    Dim oMessage As ZfLib.Message

    Dim oMsgHist As ZfLib.MessageHistory

 

     Try

         strBody = "~ZAPI001"

 

        ' Logon and get message:

         oUserSession = oZfAPI.Logon("ADMINIST", False)

         oMessage = oUserSession.Outbox.GetMsg(strBody)

 

        ' Display information about the message

        With oMessage.GetMsgInfo()

             txtCaption.Text = .Body

             txtSubject.Text = .Subject

             txtComment.Text = .Comment

        End With

 

        ' Display the number and call duration for each recipient:

        Dim MessageHistoryEnum As IEnumerator

         MessageHistoryEnum = oMessage.GetMsgHistories.GetEnumerator()

 

        While MessageHistoryEnum.MoveNext

             oMsgHist = MessageHistoryEnum.Current

             lstHistory.Items.Add("To: " & oMsgHist.Name & _

                      " Time Taken:" & oMsgHist.Date.ToString())

        End While

 

     Catch ex As Exception

         System.Windows.Forms.MessageBox.Show(ex.Message,

"ZetaFax Error", MessageBoxButtons.OK, MessageBoxIcon.Error)

    End Try

 

C#:

 // Declare objects:

 string strBody;

 ZfAPIClass oZfAPI = new ZfAPIClass();

 UserSession oUserSession;

 ZfLib.Message oMessage;

 ZfLib.MessageHistory oMsgHist;

 

 try

 {

         strBody = "~ZAPI001";

 

         // Logon and get message:

         oUserSession = oZfAPI.Logon("ADMINIST", false);

         oMessage = oUserSession.Outbox.GetMsg(strBody);

 

         // Display information about the message

         txtCaption.Text = oMessage.GetMsgInfo().Body;

         txtSubject.Text = oMessage.GetMsgInfo().Subject;

         txtComment.Text = oMessage.GetMsgInfo().Comment;

         

         // Display the number and call duration for each recipient:

         string szFormattedHistoryItem;

       IEnumerator MessageHistoryEnum = oMessage.GetMsgHistories().GetEnumerator( );

                         

         while (MessageHistoryEnum.MoveNext())

         {

                 oMsgHist = (ZfLib.MessageHistory) MessageHistoryEnum.Current;

                 szFormattedHistoryItem = string.Format("To:{0} TimeTaken:{1}",

                 oMsgHist.Name,

                 oMsgHist.Date.ToString());

                 lstHistory.Items.Add(szFormattedHistoryItem);

         }

 }

 catch (System.Runtime.InteropServices.COMException ex)

 {

         System.Windows.Forms.MessageBox.Show(ex.Message,

"ZetaFax Error", MessageBoxButtons.OK, MessageBoxIcon.Error);

 }

 

3.        The following code demonstrates how to  retrieve Zetafax device information:

 

VB.NET:

 

    ' Declare objects:

    Dim oZfAPI As New ZfLib.ZfAPI

    Dim oUserSession As ZfLib.UserSession

    Dim oDevices As ZfLib.Devices

    Dim oDevice As ZfLib.Device

 

     Try

        ' Logon and get devices:

         oUserSession = oZfAPI.Logon("ADMINIST", False)

         oDevices = oUserSession.Server.GetServerInfo().Devices

 

        ' Enumerate devices adding information to Listbox:

        Dim DeviceEnum As IEnumerator

         DeviceEnum = oDevices.GetEnumerator()

 

        While DeviceEnum.MoveNext

            'Iterate through the devices

             oDevice = DeviceEnum.Current

             lstDevices.Items.Add(oDevice.Name & " " & oDevice.User)

        End While

     Catch ex As Exception

         System.Windows.Forms.MessageBox.Show(ex.Message,

"Zetafax Error", MessageBoxButtons.OK,

MessageBoxIcon.Error)

    End Try

 

C#:

 

 // Declare objects:

 ZfAPIClass oZfAPI = new ZfAPIClass();

 UserSession                oUserSession;

 ZfLib.Devices        oDevices;

 ZfLib.Device        oDevice;

 

 try

 {

         // Logon and get devices:

         oUserSession = oZfAPI.Logon("ADMINIST", false);

         oDevices = oUserSession.Server.GetServerInfo().Devices;

 

         // Enumerate devices adding information to Listbox:

         IEnumerator DeviceEnum = oDevices.GetEnumerator();

 

         while(DeviceEnum.MoveNext())

         {

                 oDevice = (ZfLib.Device)DeviceEnum.Current;

                 lstDevices.Items.Add(oDevice.Name + " " + oDevice.User);

         }

 }

 catch (System.Runtime.InteropServices.COMException ex)

 {

         System.Windows.Forms.MessageBox.Show(ex.Message,

               "ZetaFax Error",

               MessageBoxButtons.OK,

               MessageBoxIcon.Error);

 }

 

 

 

 

The Zetafax Object Model

 

This diagram shows the various  objects in the Zetafax object model, and how they are linked. Normal  rectangles represent objects, shaded rectangles represent  collections.

 

The ZfAPI object is the only object that can be created  directly. All others can only be accessed by traversing the object  tree.

 

Examples of the use of the COM API

 

Add the name of each device and the person using it into a list box:

 

' Declare objects:  

 

Dim oZfAPI As New ZfLib.ZfAPI  

Dim oUserSession As ZfLib.UserSession  

Dim oDevices As ZfLib.Devices  

Dim oDevice As ZfLib.Device  

 

' Logon and get devices:  

Set oUserSession = oZfAPI.Logon("ADMINIST", False)  

Set oDevices = oUserSession.Server.ServerInfo.Devices

 

' Enumerate devices adding information to Listbox:  

For Each oDevice In oDevices

 DevicesList.AddItem oDevice.Name & " " & oDevice.User  

Next

 

Display information about a specific message:

 

' Declare objects:  

Dim strBody As String  

Dim oZfAPI As New ZfLib.ZfAPI  

Dim oUserSession As ZfLib.UserSession  

Dim oMessage As ZfLib .Message  

Dim oMsgHist As ZfLib.MessageHistory  

 

strBody = "~ZAPI001"

 

' Logon and get message:  

Set oUserSession = oZfAPI.Logon("ADMINIST", False)  

Set oMessage = oUserSession.Outbox.GetMsg(strBody)

 

' Display information about the message  

With oMessage

 msgForm.Caption = .Body

 txtSubject = .Subject

 txtComment = .Comment  

End With

 

' Display the number and call duration for each recipient:

For Each oMsgHist

In oMessage.GetMsgHistories

 lstHistory.AddItem

 "To: " & oMsgHist.AddrNum & _  

         " Time Taken:"        & oMsgHist.Connection  

Next

 

Send a fax:

 

' Declare objects  

Dim oZfAPI As New ZfLib.ZfAPI  

Dim oUserSession As ZfLib.UserSession  

Dim oNewMessage As ZfLib.NewMessage  

 

' Logon and create NewMessage:  

Set oUserSession = oZfAPI.Logon("ADMINIST", False)  

Set oNewMessage = oZfAPI.CreateNewMsg

 

'Set properties:

oNewMessage.Recipients.AddFaxRecipient "Sam Smith", _  

 "ACME plc", "020 7123 4567"  

oNewMessage.Text = "I am a fax!"  

oNewMessage.Priority = zfPriorityUrgent

 

' Send!  

oNewMessage.Send