FaxDevVirtualDeviceCreation function (faxdev.h)

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

Syntax

BOOL FaxDevVirtualDeviceCreation(
  [out] LPDWORD   DeviceCount,
  [out] LPWSTR    DeviceNamePrefix,
  [out] LPDWORD   DeviceIdPrefix,
  [in]  HANDLE    CompletionPort,
  [in]  ULONG_PTR CompletionKey
);

Parameters

[out] DeviceCount

Type: LPDWORD

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

[out] DeviceNamePrefix

Type: LPWSTR

Pointer to a variable that receives a null-terminated Unicode character string, limited to 128 WCHAR characters. The FSP 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.

[out] DeviceIdPrefix

Type: LPDWORD

Pointer to an unsigned DWORD variable that receives a nonzero value. The FSP 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.

[in] CompletionPort

Type: HANDLE

Specifies a handle that the FSP 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 TAPI 2.x LINEMESSAGE structure. The FSP must allocate memory for the structure with LocalAlloc(LPTR, sizeof(LINEMESSAGE)). The fax service provider must pass the size of the memory allocated (which is sizeof(LINEMESSAGE) in this case) to the dwNumberOfBytesTransferred parameter of the PostQueuedCompletionStatus method. The fax service frees any memory allocated for the completion packet structure.

The FSP must set the members of the structure as follows.

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.

[in] CompletionKey

Type: ULONG_PTR

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

Return value

Type: BOOL

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 FSP DLL for the FaxDevVirtualDeviceCreation function during initialization. If the FSP 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 an FSP that presents virtual fax devices, and one that does not present them.

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

Requirements

See also

Creating a Completion Packet

Fax Service Provider Functions

FaxDevInitialize

FaxDevStartJob

LINEMESSAGE

PostQueuedCompletionStatus

Using a Virtual Device to Transmit a Fax

Using the Fax Service Provider API

Virtual Fax Devices