FaxDevVirtualDeviceCreation

The fax service calls the FaxDevVirtualDeviceCreation function during initialization to allow the fax service provider to present virtual fax devices. Each fax service provider that presents virtual fax devices to the fax service must export the FaxDevVirtualDeviceCreation function.

BOOL WINAPI FaxDevVirtualDeviceCreation(
  LPDWORD DeviceCount,     // number of virtual devices 
  LPWSTR DeviceNamePrefix, // device name prefix 
  LPDWORD DeviceIdPrefix,  // device identifier prefix 
  HANDLE CompletionPort,   // completion port handle for ring events
  ULONG_PTR CompletionKey  // completion port key for ring events 
);

Parameters

DeviceCount

[out] Pointer to an unsigned DWORD variable that receives the number of virtual fax devices the fax service must create for the fax service provider. If the fax service provider sets this parameter to zero, the initialization of the provider will fail.

DeviceNamePrefix

[out] Pointer to a variable that receives a null-terminated Unicode character string. The fax service provider must set this string to the name prefix for the virtual fax device. The fax service appends the value of the DeviceIdPrefix parameter to this string. The result is a unique device name for each virtual fax device the fax service creates.

DeviceIdPrefix

[out] Pointer to an unsigned DWORD variable that receives a nonzero value. The fax service provider must set this member to a unique numeric value that identifies the virtual fax device. The fax service adds this value to a sequential number, beginning with zero for the first virtual device. The result is a unique device identifier for each virtual fax device the fax service creates.

CompletionPort

[in] Specifies a handle that the fax service provider must use to post I/O completion port packets to the fax service for asynchronous line status events. Currently the FaxDevVirtualDeviceCreation function supports only the event that signals an incoming call.

The completion port packet must be a LINEMESSAGE structure. The fax service provider must allocate memory for the structure from the heap indicated by the HeapHandle parameter passed to the FaxDevInitialize function. The fax service frees any memory allocated for the completion packet structure. For more information, see Allocating Memory.

The fax service provider must set the members of the structure as follows.

Member	Contents
hDevice	Set to DeviceId from FaxDevStartJob
dwMessageID	Set to 0
dwCallbackInstance	Set to 0
dwParam1	Set to LINEDEVSTATE_RINGING
dwParam2	Set to 0
dwParam3	Set to 0

For information about line status events, see LINEDEVSTATE_ Constants in the TAPI documentation. For information about I/O completion ports, see I/O Completion Ports.

CompletionKey

[in] Specifies a completion key value. The fax service provider must use this value when the provider posts completion port packets to the fax service. The fax service provider should pass this opaque value to the PostQueuedCompletionStatus function.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, the fax service calls GetLastError.

Remarks

The fax service checks the fax service provider DLL for the FaxDevVirtualDeviceCreation function during initialization. If the fax service provider exports the function, the fax service assumes that the provider will present virtual fax devices. The fax service handles virtual fax devices the same way it handles physical fax devices. After initialization there is no difference between the functionality or operation of a fax service provider that presents virtual fax devices, and one that does not present them.

When a fax service provider uses physical fax devices, the Telephony Application Programming Interface (TAPI) and the telephony service provider enumerate the devices for the fax service. If the fax service provider does not have physical fax devices, and it presents only virtual fax devices, a telephony service provider will not exist, and TAPI will not enumerate the devices. In this instance, FaxDevVirtualDeviceCreation provides the virtual fax device enumeration for the fax service.

For more information, see Virtual Fax Devices, Using a Virtual Device to Transmit a Fax, and Creating a Completion Packet.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in faxdev.h.
  Import Library: User-defined.

See Also

Fax Service Provider Application Programming Interface Overview, Fax Service Provider Functions, FaxDevStartJob, FaxDevInitialize, PostQueuedCompletionStatus, LINEMESSAGE