Platform SDK: Fax Services

IFaxServer

The IFaxServer dual interface is used by a fax client application to manage a connection to the fax service. The interface retrieves and sets information about FaxServer objects; for example, settings for retransmission, branding, archiving and cover pages; discount rate periods; and the status of the fax server queue. The IFaxServer interface includes the following methods:

Methods to initiate and terminate connections with a fax server.
Property methods to retrieve and set individual property values of FaxServer objects.
Methods to create FaxJobs, FaxPorts and FaxDoc objects.

Note A fax client application must call the IFaxServer::Connect method to initiate a connection with an active fax server before accessing most interfaces that begin with IFax. (A fax server connection is not required to access an IFaxTiff interface.)

When to Implement

You should not implement this interface. The Microsoft® standard implementation provides complete functionality.

When to Use

Use the IFaxServer interface to connect to and disconnect from an active fax server. Also use the interface to retrieve and set the properties of FaxServer objects, and to create the objects listed in the following steps.

To connect to a fax server, and create other fax client objects, perform the following steps:

Call the CoCreateInstance function to retrieve a pointer to an IFaxServer interface and create an instance of a FaxServer object.
Call the IFaxServer::Connect method to initiate a connection with an active fax server.
After you obtain a connection, call the following methods to create the objects you need:
- The IFaxServer::GetJobs method to create a FaxJobs object. Use this object to create FaxJob objects and enumerate the fax jobs associated with a connected fax server.
- The IFaxServer::GetPorts method to create a FaxPorts object. Use this object to create FaxPort objects and enumerate fax port configuration information for a connection to a fax server.
- The IFaxServer::CreateDocument method to create a FaxDoc object. Use this object to transmit a fax and to retrieve and set the properties of FaxDoc objects.
Call the IFaxServer::Disconnect method to disconnect from the fax server.
Call the IUnknown::Release method for each object to allow the object to deallocate itself. Call the method again, if necessary, to destroy the IFaxPorts or the IFaxJobs interface pointers.

Note that a client application should not call the CoCreateInstance function to create FaxJobs, FaxPorts or FaxDoc objects, or objects derived from these objects. For more information about creating and deallocating fax client objects, see the steps that are listed with each individual interface topic and the hierarchical diagram included in The Fax Client Object Model.

The property methods of the IFaxServer interface retrieve or set the properties described following. If the property supports read access, the IFaxServer interface includes a get_PropertyName method. If the property supports write access, the interface includes a put_PropertyName method.

Following are the properties associated with a FaxServer object. You can find a complete list of IFaxServer interface methods in Vtable order following the list of properties.

Property	Type	Access	Description
ArchiveDirectory	BSTR	R/W	Location at which the fax server archives outgoing fax transmissions.
ArchiveOutboundFaxes	BOOL	R/W	Flag that indicates whether the fax server archives a copy of all outgoing fax transmissions.
Branding	BOOL	R/W	Flag that indicates whether the fax server generates a brand (banner) at the top of a fax transmission.
DirtyDays	LONG	R/W	Number of days the fax server retains an unsent job in the fax job queue.
DiscountRateEndHour	SHORT	R/W	Hour the discount period ends for outgoing fax transmissions.
DiscountRateEndMinute	SHORT	R/W	Minute the discount period ends for outgoing fax transmissions.
DiscountRateStartHour	SHORT	R/W	Hour the discount period begins for outgoing fax transmissions.
DiscountRateStartMinute	SHORT	R/W	Minute the discount period begins for outgoing fax transmissions.
PauseServerQueue	BOOL	R/W	Flag that indicates whether the fax server should pause the outbound job queue.
Retries	LONG	R/W	Number of times the fax server attempts to retransmit an outgoing fax, when the initial transmission fails.
RetryDelay	LONG	R/W	Number of minutes that elapse between retransmission attempts by the fax server.
ServerCoverpage	BOOL	R/W	Flag that indicates whether fax client applications can include a user-designed cover page with the fax transmission.
ServerMapiProfile	BSTR	R/W	MAPI user profile the fax server uses for routing incoming fax transmissions.
UseDeviceTsid	BOOL	R/W	Flag that indicates whether the fax server uses the device's transmitting station identifier (TSID) instead of a user-specified TSID.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

IFaxServer Methods

Method	Description
Connect	Connects a fax client application to an active fax server.
Disconnect	Terminates a connection to a fax server.
GetPorts	Creates a FaxPorts object. The object allows enumeration of fax port configuration information for the connected fax server.
CreateDocument	Creates a FaxDoc object. The object allows a user to create and send a fax document to one or more recipients.
GetJobs	Creates a FaxJobs object. The object allows enumeration of the queued jobs for the connected fax server.
get_Retries put_Retries	Retrieves or sets a new value for the number of times the fax server attempts to retransmit an outgoing fax, when the initial transmission fails.
get_RetryDelay put_RetryDelay	Retrieves or sets a new value for the time interval, in minutes, that the fax server waits before attempting to retransmit an outbound fax job.
get_DirtyDays put_DirtyDays	Retrieves or sets a new value for the number of days the fax server retains an unsent job in the fax job queue.
get_Branding put_Branding	Retrieves or sets a new value for the flag that indicates whether the fax server generates a brand (banner) at the top of fax transmissions.
get_UseDeviceTsid put_UseDeviceTsid	Retrieves or sets a new value for the flag that indicates whether the fax server uses the device's transmitting station identifier (TSID) instead of a user-specified TSID.
get_ServerCoverpage put_ServerCoverpage	Retrieves or sets a new value for the flag that indicates whether the fax service permits the use of common cover pages only.
get_PauseServerQueue put_PauseServerQueue	Retrieves a value that indicates whether the fax server has paused the outbound fax job queue, or whether the queue is active. Setting this property pauses or resumes the outbound fax job queue.
get_ArchiveOutboundFaxes put_ArchiveOutboundFaxes	Retrieves or sets a new value for the flag that indicates whether the fax server archives outgoing transmissions.
get_ArchiveDirectory put_ArchiveDirectory	Retrieves or sets a new value for the location at which the fax server stores archived outbound faxes.
get_ServerMapiProfile put_ServerMapiProfile	Retrieves or sets a new value for the MAPI user profile that the fax server uses for routing incoming fax transmissions, and for sending delivery reports (DRs) and nondelivery reports (NDRs).
get_DiscountRateStartHour put_DiscountRateStartHour	Retrieves or sets a new value for the hour the discount period begins for outgoing transmissions.
get_DiscountRateStartMinute put_DiscountRateStartMinute	Retrieves or sets a new value for the minute the discount period begins for outgoing transmissions.
get_DiscountRateEndHour put_DiscountRateEndHour	Retrieves or sets a new value for the hour the discount period ends for outgoing transmissions.
get_DiscountRateEndMinute put_DiscountRateEndMinute	Retrieves or sets a new value for the minute the discount period ends for outgoing transmissions.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in faxcom.h.
  Import Library: Included as a resource in faxcom.dll.

IFaxServer

When to Implement

When to Use

Methods in Vtable Order

Requirements

See Also