Función FaxDevVirtualDeviceCreation (faxdev.h)

2023-08-23

El servicio de fax llama a la función FaxDevVirtualDeviceCreation durante la inicialización para permitir que el proveedor de servicios de fax (FSP) presente dispositivos de fax virtuales. Cada FSP que presente dispositivos de fax virtual al servicio de fax debe exportar la función FaxDevVirtualDeviceCreation .

Sintaxis

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

Parámetros

[out] DeviceCount

Tipo: LPDWORD

Puntero a una variable DWORD sin firmar que recibe el número de dispositivos de fax virtuales que el servicio de fax debe crear para el FSP. Si el FSP establece este parámetro en cero, se producirá un error en la inicialización del proveedor.

[out] DeviceNamePrefix

Tipo: LPWSTR

Puntero a una variable que recibe una cadena de caracteres Unicode terminada en null, limitada a 128 caracteres WCHAR . El FSP debe establecer esta cadena en el prefijo de nombre del dispositivo de fax virtual. El servicio de fax anexa el valor del parámetro DeviceIdPrefix a esta cadena. El resultado es un nombre de dispositivo único para cada dispositivo de fax virtual que crea el servicio de fax.

[out] DeviceIdPrefix

Tipo: LPDWORD

Puntero a una variable DWORD sin signo que recibe un valor distinto de cero. El FSP debe establecer este miembro en un valor numérico único que identifique el dispositivo de fax virtual. El servicio de fax agrega este valor a un número secuencial, empezando por cero para el primer dispositivo virtual. El resultado es un identificador de dispositivo único para cada dispositivo de fax virtual que crea el servicio de fax.

[in] CompletionPort

Tipo: HANDLE

Especifica un identificador que el FSP debe usar para publicar paquetes de puerto de finalización de E/S en el servicio de fax para eventos de estado de línea asincrónica. Actualmente, la función FaxDevVirtualDeviceCreation solo admite el evento que señala una llamada entrante.

El paquete de puerto de finalización debe ser una estructura LINEMESSAGE TAPI 2.x. El FSP debe asignar memoria para la estructura con LocalAlloc(LPTR, sizeof(LINEMESSAGE))). El proveedor de servicios de fax debe pasar el tamaño de la memoria asignada (que es sizeof(LINEMESSAGE) en este caso) al parámetro dwNumberOfBytesTransferred del método PostQueuedCompletionStatus . El servicio de fax libera cualquier memoria asignada para la estructura de paquetes de finalización.

El FSP debe establecer los miembros de la estructura de la siguiente manera.

Miembro	Contenido
hDevice	Establecer en DeviceId desde FaxDevStartJob
dwMessageID	Establecer en 0
dwCallbackInstance	Establecer en 0
dwParam1	Establézcalo en LINEDEVSTATE_RINGING
dwParam2	Establecer en 0
dwParam1	Establecer en 0

Para obtener información sobre los eventos de estado de línea, consulte LINEDEVSTATE_ Constantes en la documentación de TAPI. Para obtener información sobre los puertos de finalización de E/S, consulte Puertos de finalización de E/S.

[in] CompletionKey

Tipo: ULONG_PTR

Especifica un valor de clave de finalización. El FSP debe usar este valor cuando el proveedor publique paquetes de puerto de finalización en el servicio de fax. El FSP debe pasar este valor opaco a la función PostQueuedCompletionStatus .

Valor devuelto

Tipo: BOOL

Si la función se ejecuta correctamente, el valor devuelto es un valor distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, el servicio de fax llama a GetLastError.

Comentarios

El servicio de fax comprueba el archivo DLL de FSP para la función FaxDevVirtualDeviceCreation durante la inicialización. Si el FSP exporta la función, el servicio de fax supone que el proveedor presentará dispositivos de fax virtuales. El servicio de fax controla los dispositivos de fax virtual de la misma manera que controla los dispositivos de fax físicos. Después de la inicialización no hay ninguna diferencia entre la funcionalidad o el funcionamiento de un FSP que presenta dispositivos de fax virtual, y uno que no los presenta.

Cuando un FSP usa dispositivos de fax físicos, el TAPI y el proveedor de servicios de telefonía (TSP) enumeran los dispositivos para el servicio de fax. Si el FSP no tiene dispositivos de fax físicos y solo presenta dispositivos de fax virtuales, no existirá un TSP y TAPI no enumerará los dispositivos. En este caso, FaxDevVirtualDeviceCreation proporciona la enumeración del dispositivo de fax virtual para el servicio de fax.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	faxdev.h