At the core of VBFax is a series of interoperating objects using COM object technology. These objects are available to the user of VBFax as an OLE Automation library. The following diagram illustrates the objects and their relationships. Solid boxes represent objects, dashed lines indicate collections.
An object is an entity which can be represented by a single variable reference and contains both information and functions which can be performed on the data. The information contained in an object is made available through properties. Operations which the object may perform (the functions) are called methods. Both properties and methods are referenced in an object using a dot notation of the form object.property or object.method.
Collections are objects of a special type. Each collection holds other objects. Visual Basic has specially defined functions (such as For Each) to access the objects contained within a collection.
The VBFaxQueue object is the root object in the object library. This object provides a collection of fax servers through its Servers property. Every Fax Server known to VBFax will appear in this collection. The Active property of each server in the collection may be used to determine which of these servers are available for use.
Fax jobs on each server may be obtained through a collection on each server. The servers Jobs property returns a collection of VBFaxJob objects. To create a new fax job on a server, use the Add method on the Jobs collection. This method will return a new VBFaxJob object and add it to the current collection. At this point the job has not yet been sent, but is available to the application. Once properties of the job are set, the application program uses the Send method to signal the server to transmit the fax.
A fax job is addressed for sending by adding recipients to the Recipients collection of the job. On creation, a job has no recipients and transmission will fail if at least one recipient is not added. Each recipient contains a VBFaxAddress object accessed through the Address property of the recipient. This object has properties including phone number, name, and address. Once the fax job is sent, the status of individual recipients may be checked using the various Status properties of the recipient.
The Sender property of a job is used to set up information describing the originator of the fax. This information is then made available for inclusion on cover pages along with the recipient information. The sender is a VBFaxAddress object and contains identical properties to the Address property of the recipient.
Fax attachments are called Documents in VBFax. The Documents collection of the job contains one VBFaxDocument object for each attachment to be sent. Similar to the way the recipients collection works, the application must use the Add method to create a new document within the Documents collection. The Filename property of the document can then be set to the image file to be sent.
The VBFax Automation Library can be used with any language which supports OLE Automation (Delphi, Java, etc.). This manual will use Visual Basic to illustrate usage.
To start programming with the VBFax library, first create a VBFaxQueue object.
Creating a VBFaxQueue object can be done in one of two ways:
Using the CreateObject command
Referencing the OLE object library and using the Dim As New VBFaxQueue sequence
Dim queue As Object
Set queue = CreateObject("VBFAX32.VBFaxQueue")
The object queue can then be used as described below.
Setup the reference to the object library
Create the object using Dim As New
To setup the reference to the object library, perform the following steps:
Select Tools from the Visual Basic menu
Select References from the drop-down menu
Scroll through the list of Available References in the References dialog to find the Pronexus VBFax OLE Automation & COM Library
Select this item and ensure the check box is marked
Open a Visual Basic module and use the following code
Dim queue As New VBFaxQueue
The second method of referencing the object library is recommended as it provides for more readable Visual Basic code and enables the use of constants described in the object library. Additional type checking on the objects is also provided to ensure that variables of one object type are not assigned objects of another type. This feature greatly reduces programming errors.
The second method may not be available in all programming environments where OLE Automation objects can be used. All languages which support OLE Automation, will have some equivalent of the CreateObject command used in method 1. For further information on using object libraries with Visual Basic see: OLE Automation objects, References Dialog Box, Dim Statement, and CreateObject in the Visual Basic online help.
For this example we will use method 2 above to create a VBFaxQueue object and reference the object library, assume the following code is used.
Dim queue As New VBFaxQueue
For purpose of example, get the first server from the queue for use:
Dim server As VBFaxServer
Set server = queue.Servers[1]
Create a new job in the Jobs collection of this server:
Dim job As VBFaxJob
Set job = server.Jobs.Add
Properties and collections of object job may now be used to address and send a fax job. This process is outlined below. Note the difference in the Dim statements: the VBFaxQueue is Dimed using Dim New to tell Visual Basic to create a new object of this type. The other Dim statements do not create objects and so do not use New. In the last two Dim statements, the object is empty until the Set statement is used to obtain the value returned from the collections.
Once a job is created, as above, the application must fill in the job properties, add recipients to address the fax, and add documents (attachments) to be transmitted.
Continuing with the previous example, specify job properties as follows:
job.Subject = "Hello World from VBFax"
job.CoverPage = True
job.Resolution = vbfResolutionFine
job.Priority = vbfPriorityNormal
job.MaxRetries = 3
job.Sender.Name = "Me"
job.Sender.FaxNumber = "555-1234"
Dim recip as VBFaxRecipient
Set recip = job.Recipients.Add
recip.Name = "Somebody at Pronexus"
recip.Organization =
"Pronexus"
recip.FaxNumber = "613-839-0035"
recip.VoiceNumber = "613-839-0033"
Dim doc As VBFaxDocument
Set doc = job.Documents.Add
doc.Filename = "c:\test.dcx"
doc.DocumentName = "Test
Document"
doc.Remote = False
Additional properties are available and may be set as desired. See the detailed Object Reference for property information.
The above sample will create a fax with a generated coverpage with Subject text of "Hello World from VBFax" from Me at 555-1234, to Pronexus. It will transmit one attachment, that being the image in the file c:\test.dcx.
To send the fax job created in the above sample perform the following:
job.Send
The fax job will now be transmitted to the server and scheduled for delivery using the properties set in the job.
To obtain up-to-date status information on this job it is necessary to update the jobs collection for the server. This can be done manually, or can be performed at intervals using a Timer control in Visual Basic. The code which must be executed either on timer event or manually to update status is:
server.Jobs.Refresh
This will refresh all of the status information in all jobs and recipients for the server.
To check on the job status, use the jobs properties as follows:
If job.Status = vbfStatusDelivered Then
Debug.Print "Your fax
was sent successfully."
End If
If job.Status =
vbfStatusFailed Then
Debug.Print "Your fax could not be
delivered."
Debug.Print "Error: " & job.StatusText
Debug.Print "Reason: " & job.StatusReasonText
End If
To determine which recipient caused the problem, the application could perform further error handling as follows:
For Each recip In job.Recipients
If recip.Status = vbfStatusFailed
Then
Debug.Print "Recip: " & recip.Address.Name &
" Failed."
Debug.Print "Error: " &
recip.StatusText
Debug.Print "Reason: " &
recip.StatusReasonText
End If
Next recip
VBFaxQueue provides access to the tree of objects contained in this Object Library. This is similar in nature to the Application object seen in many other libraries. To use the VBFaxQueue object, first create an instance of the object in your application code. The Servers property will now return a collection of all available VBFaxServer objects configured on the current machine.
The Servers property returns a collection of VBFaxServer objects. This collection supports Count and Item properties and allows for iteration over all of the contained servers. Visual Basic supports the syntax For Each to allow for iteration over collections.
EXAMPLE
For Each server in queue.Servers
<perform some operation on
VBFaxServer object server>
Next server
VBFaxServers Collection Hierarchy
This collection object contains all of the VBFaxServer objects for a VBFaxQueue. On any given machine, this collection will contain objects representing all of the servers which have been configured. This collection may be iterated over using the Visual Basic for each instruction.
Update the collection with new servers added or servers removed via the VBFaxQueues configuration interface.
Make all servers in the collection inactive.
(Integer, read-only)
Return the number of servers in this collection.
(VBFaxServer, read-only)
Return servers by numeric index.
The VBFaxServer object provides for application interaction with a local or remote fax server or device. Applications should check the Active property to determine the state of the server before using it. The Jobs property provides access to all jobs on the server including new, waiting, sending, and delivered faxes.
The Jobs property returns a VBFaxJobs collection object. This collection supports iterating over existing jobs, adding new fax jobs, and removing jobs from the server.
The Refresh method updates the collection. New fax jobs submitted by other client machines will appear after a refresh. This method also updates job status information and recipient status information for all jobs contained in the collection.
(boolean)
The present operating status of the fax server to which this object refers. If the fax server or device is not available on the network or local computer, then this property is False.
(String, read-only)
The UNC network name where the server is to be found.
(String, read-only)
The name assigned to the server when the configuration entry was added to the configuration of the VBFax library.
Sets the default page header for all faxes sent from this server. Each recipient can override the default page header.See Cover Page.
(Integer)
Where fax servers are capable of automatically refreshing job information, this is the interval between automatic refreshes in milliseconds.
(Integer, read-only)
Often used during problem determination when talking to vendor technical support, the build number accurately identifies which binary libraries are currently installed and operating. For various reasons including interim updates and bug fixes, the build number may change while the software major and minor version numbers do not.
(Integer, read-only)
A number referring to the version number assigned to the server software by the fax software vendor.
(Integer, read-only)
The second part of the version number as assigned by the vendor. For example: version 2.1, 2 is the major version as described above while 1 is the minor version number (sometimes referred to as release).
(String, read-only)
The name of the fax server package.
(String, read-only)
The name of the software vendor of the server to which VBFax is connected.
(String, read-only)
A vendor specific status string returned by the fax server software.
VBFaxJobs Collection Hierarchy
The VBFaxJobs collection provides access to all of the jobs on a given server. It is of particular importance, since it provides the means by which new jobs are created for transmission on a given server and removed from the server once complete.
(returns VBFaxJob)
The Add method returns a new empty VBFaxJob object which can then be filled out by the application and sent.
The Refresh method updates status information for all jobs in the collection and for all recipients belonging for those jobs. A queue browsing application might use a Timer control to call this refresh method before updating the queue list.
(VBFaxJob)
Fax jobs submitted to a server reside there until they are removed by the application. An individual job may not remove itself from the server. Instead, the application may remove the job from the Jobs collection. In so doing, the job is also removed from the server. To remove a job, specify the job object as the parameter to the remove method.
(Integer, read-only)
Returns the number of jobs in the collection.
(VBFaxJob, read-only)
Returns the VBFaxJob object indexed by an Integer.
Each VBFaxJob contains the information to be used in transmitting a group of documents plus (possibly) a cover page to one or more recipients. The Recipients property of this object returns the collection of VBFaxRecipient objects for the job. To address a fax to a destination, a recipient must be added to the Recipients collection using its Add method. The Documents property contains the file attachments or documents to be sent. These documents must be of a type supported by the selected fax server.
The Documents property returns a collection of VBFaxDocument objects. Each document in this collection is a file attachment to be sent when the fax is transmitted to a destination.
This property provides access to a collection of VBFaxRecipient objects. Each recipient in this collection has an address to which the fax is to be sent along with status information indicating progress in transmitting the fax to this address.
(Integer, read-only)
The number of times the fax server attempted to send the fax because there was a busy signal at the destination. This property returns Retries at present and is provided for future use.
(String)
This is the date and time to be displayed on the cover page for the job. If not set, this property will default to the current time/date when the job is scheduled.
(boolean)
This boolean property is set to True to cause VBFax to transmit a generated cover page. Generated cover pages use the cover page template specified in the server software configuration, and may use the Sender, Recipient, and Fax properties set here, such as CoverText and Subject.
(String)
Set this to the filename of an image file to use in place of the default cover page. If only a filename is supplied with no path, the default directory for the cover page file will be assumed.
This should be a path name on the local machine. If a filename or relative path name is supplied, this will be relative to the VBVoice directory.
(String)
Cover page templates often contain a section for general notes to the receiver of the fax. This text may be set using the CoverText property.
(boolean)
Set this boolean property to True to send the fax only during the time period indicated by DeferPeriodStart and DeferPeriodEnd. Note, if set to False, individual recipients may still be deferred by setting their Defer property to True. The recipients will then use the jobs defer period to determine scheduling. One possible use for this feature is to selectively send to overseas recipients after hours while sending local faxes immediately.
(Date)
The end of the time period for sending deferred faxes. After this time, deferred faxes will not begin transmission. Faxes presently being transmitted at this time will complete transmission normally.
(Date)
The start of the time period at which deferred faxes will be allowed to begin transmission.
(String, read-only)
If the fax is delivered successfully for all recipients, this is the latest of the DeliveredDate's for all recipients and is the time and date at which the last fax transmission was started for this job.
(Integer)
This property is not presently supported, but is included for future use.
(Integer)
This property is not presently supported, but is included for future use.
(Integer)
Use this property to set the maximum number of times a fax transmission will be retried before failing. This property sets the maximum retries for each recipient in the job.
(Integer, read-only)
The number of times the fax server attempted to send the fax because there was no answer at the destination. This property returns the value of Retries at present and is provided for future use.
(Boolean)
This property controls whether the last page of ASCII text is padded to the end of the page. It is available only on Dialogic. Default is True. Set to False if you wish to send short faxes of less than one page.
(String)
This property sets the default page header for all recipients of this fax. It defaults to the value of the VBFaxServer PageHeader property. Individual recipients can have different headers using the VBFaxRecipient PageHeader property.
(FaxPriorityConstants)
This property provides the ability to queue a job on the server ahead of or after existing jobs depending on their relative priorities. This feature allows for both bulk fax transmissions and normal office fax use on the same fax server. Bulk faxing can be specified with vbfPriorityLow, while office faxing can use vbfPriorityNormal. This feature also allows fax broadcast and separate call fax-on-demand applications to share a common fax server with minimal contention. See FaxPriorityConstants for details.
(FaxResolutionConstants)
The preferred resolution for fax transmission. Resolution is negotiated on transmission between sender and receiving fax machine. If the receiving fax machine is not capable of the specified resolution a lower resolution may be chosen. Values for this property come from the FaxResolutionConstants enumeration and are available if using the VBFax object library as a referenced library. All VBFax constants begin with vbf. The default resolution is vbfResolutionFine. See FaxResolutionConstants for details.
(Integer, read-only)
The number of times the fax server attempted to send the fax to a destination. This is the maximum of the retry counts for all recipients.
(Date, read-only)
This property will indicate either the current time and date, or the start of the deferred period if the fax job is deferred. It is the minimum of ScheduledDate for all recipients and therefore will be the current date/time if at least one fax is being transmitted immediately in this job. When a fax job fails and must be retried, the ScheduledDate is updated to reflect the next planned time of transmission.
(VBFaxAddress object, read-only)
The Sender property returns a VBFaxAddress object which is then used to specify the address of the originator of the fax. For example, a job sent from Pronexus might have job.Sender.Name = 'Gordon', job.Sender.Company = 'Pronexus'. See VBFaxAddress for details of the properties of the address returned.
Note, the meaning of read-only for this property. The Sender property is read-only indicating that a user may not assign a VBFaxAddress object to this property. The properties of the VBFaxAddress object returned on the other hand are read-write and may be set under program control.
(String)
This property sets the CSID of the sending fax server for this job. Only Dialogic fax servers support changing the CSID dynamically.
(FaxStatusConstants, read-only)
The current state of the fax job as of the last refresh. Note that refreshing the Jobs collection has the effect of updating the status of every job and recipient in the collection.
(FaxStatusReasonConstants, read-only)
The StatusReason is used to determine the reason a job is in a particular status state. If the fax transmission failed, this property will give additional information on why the failure occurred. This property is only valid once all specified retries have been attempted. See FaxStatusReasonConstants.
(String, read-only)
An additional text description of the reason code.
(String, read-only)
An additional text description of the state of the job. This property is used to provide informational messages back to the user.
(String)
The subject text to appear on the cover page of this fax when transmitted.
(Variant)
The UserData field is an OLE Variant which can be used by the application to store arbitrary data for a fax job. Note that this information is not transmitted to the server and is not persistent across VBFax sessions.
VBFaxRecipients Collection Hierarchy
This collection object contains the VBFaxRecipient objects for a fax job. Of particular importance is the Add method which is used to create all new recipients within a fax job.
(returns VBFaxRecipient)
Use the Add method to create a new recipient for a fax job. This method returns the object as its result. The returned object is initially empty until the application fills out the Address information.
Forces an update of the status for the recipients contained in this collection.
(Integer, read-only)
Returns the number of recipients in this collection.
(VBFaxRecipient, read-only)
Provides indexed access to recipients in this collection.
VBFaxRecipient Object Hierarchy
A VBFaxRecipient is a single destination for the transmission of a fax. Each fax job is addressed to one or more recipients. A recipient has an Address property returning a VBFaxAddress object which specifies the location to which the transmit will be transmitted. This object also has status properties which enable the application to check progress of the transmission to individual locations. Many fax transmission problems occur at this level. Within any job it is possible to transmit successfully to many recipients while faxes to specific recipients fail. When the job status indicates failure it indicates that at least one recipient failed. The application may then iterate through the recipient objects and use their status and reason properties to diagnose the error. An individual recipient fax may also be paused, sent, and resent as appropriate based on the status.
(VBFaxAddress, read-only)
Returns a VBFaxAddress object which is then used to specify the location to which this recipient fax will be transmitted. The property is read-only, however the properties of the returned object, are read-write and may be set in application code.
(Integer, read-only)
Presently returns the same value as Retries.
(boolean)
This property is the same as the Defer property for VBFaxJob except it can be used to override the value specified in the job. If the job is deferred, individual recipients may not override this property. If the job is not deferred, then this property can be used to selectively submit recipients for off-peak transmission. This could be used for example to selectively send overseas faxes at off-peak times in a fax broadcast application.
(Date, read-only)
If the recipient is transmitted successfully, this property indicates the time at which the successful fax transmission started.
(Integer, read-only)
Presently returns zero. As support for other devices and servers becomes available this property will be used to indicate the time in seconds for fax transmission to the recipient.
(Integer, read-only)
Presently returns the same value as Retries.
(String)
Defines the page header for this fax. For a fax with multiple recipients, each recipient can have a different page header. The default is set from the Server PageHeader property.
(Integer, read-only)
The number of pages successfully sent to the destination.
(Integer, read-only)
The total number of pages to be sent.
(String, read-only)
RemoteID is the CSID of the remote fax machine. For a received fax, this is the ID of the sending fax, and for a fax sent by VBFax, it is the ID of the receiving fax machine.
(Integer, read-only)
The number of retries required so far in sending to this location.
(Date, read-only)
This is either the current date/time or the start of the deferral period if the recipient is deferred. When the job is transmitting, this property indicates the start time of the current try.
(String)
StationID is the CSID of the recipient of the fax. For received faxes, this CSID is the CSID transmitted to the sender of the fax during the initial fax send negotiation. For faxes sent by VBFax, the StationID is sent to the receiving fax machine. Not all fax servers support dynamically changing the local CSID.
(FaxStatusConstants, read-only)
The current state of the fax job as of the last refresh. Note that refreshing the Jobs collection has the effect of updating the status of every job and recipient in the collection. See FaxStatusConstants.
(String, read-only)
An additional text description of the state of the job. This property is used to provide informational messages back to the user.
(FaxStatusReasonConstants, read-only)
The StatusReason is used to determine the reason a job is in a particular status state. If the fax transmission failed, this property will give additional information on why the failure occurred. This property is only valid once all specified retries have been attempted. See FaxStatusReasonConstants.
(String)
The StatusReasonText is used to provide additional information on the reason for failure.
(Integer, read-only)
TransmissionRate is the rate at which the fax is transmitted or received, in bits per second.
(Variant)
A Variant variable available to the application to use as necessary. This property is not stored on the server and is not persistent between VBFax sessions. This property can be used to link additional application data with individual fax recipients.
The VBFaxAddress object is a generic address used to specify information about
the sender of a fax and for the recipients of the fax. The Sender property of the fax job and the Address property of the recipient object both return objects of this type. All properties may be set and used by application code. The FaxNumber must be specified for recipients and is the phone number used when dialling out to transmit the fax.
(String)
The city in which this address resides.
(String)
The country in which this address resides.
(String)
The department within the organization, if applicable.
(String)
A free-form text field in which an email address may be specified.
(String)
The fax number to be dialled to send the fax. Or the senders fax number.
(String)
The full name of the person or group to whom the fax is addressed or from whom the fax is being sent.
(String)
The organization or company name to be printed on the cover page.
(String)
The postal or zip code corresponding to the street address.
(String)
The state, province, or territory in which this address resides.
(String)
The first line of street address information.
(String)
A second line of street address information.
(String)
The voice telephone number of either the sender or recipient of the fax. This number is usually specified as it provides an alternate number in case of fax transmission problems or incorrect fax numbers.
VBFaxDocuments Collection Hierarchy
This collection holds the VBFaxDocument objects for a fax job. To create a new attachment on a fax job use the Add method to obtain a new VBFaxDocument object from the collection, and then fill out its properties as appropriate.
(returns VBFaxDocument)
Creates a new VBFaxDocument object within this collection and returns it to the application.
Updates the list of documents in the collection.
(Integer, read-only)
Returns the number of documents in the collection.
(VBFaxDocument, read-only)
Returns the document object indexed by an integer.
VBFaxDocument Object Hierarchy
The VBFaxDocument object is used to specify an attachment to a fax job. Documents have properties allowing the user to set the filename to be attached, along with a user defined name for the document. The filename specified may be local, or may reside on the server. To specify a local file, the Remote property must be False.
(String)
This is a name which can be assigned to a document. It is stored at the server and is available to all VBFax client code operating against a server. VBFax makes no special use of this string and this property may be freely used by the application.
(String)
The filename to the document file to be used. The extension defines the file type and must be of a type supported by the server in use. See Fax File Formats. Files with unknown extensions are assumed to be text files.
The filename can be either a fully qualified path, or a partial path, in which case it will be assumed to be relative to the FaxDirIn or FaxDirOut directory for receivefax and sendfax respectively. This directory is set from an ini setting.
(boolean)
When set to True, indicates that the Filename property refers to the directory on the Server machine. When set to False, indicates that the Filename refers to the local directory. Local files are transmitted to the server as part of sending the fax job. Remote files do not require transmission over the network and may provide performance benefits to an application.
(Variant)
The UserData property is a Variant provided to the application. This property is not persistent and is available only for the current VBFax session. The user is free to use this property in application code. This property may be used to link application information for documents to the document being sent.
This collection is only available from the IFaxConfiguration alternate interface for VBFaxQueue. Refer to IFaxConfiguration for details on gaining access to this collection. This collection contains strings describing the types of servers which may be configured for VBFax. Each supporting fax library registered can add new supported server types.
(Integer, read-only)
The number of types of servers currently supported by this system.
(String, read-only)
Indexed access to the server type strings.
The IFaxConfiguration interface is an alternate interface for the VBFaxQueue object. To perform system configuration functions on the VBFax library, assign the VBFaxQueue object to a variable of type IFaxConfiguration and then use the methods and properties above.
EXAMPLE
Dim queue As New VBFaxQueue
Dim config As IFaxConfiguration
Set
config = queue
config.AddServer Test, Pronexus Fax Server
When adding a new fax server to the VBFax configuration, the application must supply a type string. These are descriptive English phrases describing the particular type of fax server. To determine which types of fax servers are available on your system, use the ServerTypes collection to obtain a collection of fax server type strings.
The following example will demonstrate how to get a list of these strings:
Dim queue As New VBFaxQueue
Dim config As IFaxConfiguration
Set
config = queue
For Each typeString in config.ServerTypes
Debug.Print typeString
next typeString
AddServer(Name as String, ByVal Type as String)
Specify the name and type of the server to be added. In this version of VBFax the name and location of a fax server are the same. The name should be the same as the network name of the computer on which the fax server software resides. For example, suppose your local machine is named MIKE. The following would Setup your machine for use with a fax server running on the same machine as the client application:
config.AddServer MIKE, Pronexus Fax Server
RemoveServer(name as String)
As network names change it becomes necessary to remove references to non-existent servers from the fax configuration. The RemoveServer method can be used to remove a server previously created by AddServer. To remove the server added above from the configuration:
config.RemoveServer MIKE