Función WdfIoTargetWdmGetTargetFileHandle (wdfiotarget.h)

[Se aplica a KMDF y UMDF]

El método WdfIoTargetWdmGetTargetFileHandle devuelve un identificador al archivo asociado a un destino de E/S remoto especificado.

Sintaxis

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Parámetros

[in] IoTarget

Identificador de un objeto de destino de E/S remoto. Este identificador se obtuvo de una llamada anterior a WdfIoTargetCreate.

Valor devuelto

Si el controlador especificó un nombre de objeto cuando llamó a WdfIoTargetOpen, WdfIoTargetWdmGetTargetFileHandle devuelve el identificador de archivo asociado al destino de E/S especificado. De lo contrario , WdfIoTargetWdmGetTargetFileHandle devuelve NULL.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Para KMDF, el identificador de archivo devuelto es un identificador en modo kernel que es válido en un contexto de subproceso arbitrario. Para obtener información sobre cómo un controlador puede usar este identificador de archivo, vea Usar un identificador de archivo.

El identificador de archivo que devuelve el método WdfIoTargetWdmGetTargetFileHandle es válido hasta que el controlador llama a WdfIoTargetClose o WdfIoTargetCloseForQueryRemove, o hasta que se elimine el objeto de destino de E/S remoto. Si el controlador proporciona una función EvtCleanupCallback para el objeto de destino de E/S remoto y si el objeto se elimina antes de cerrar el destino de E/S remota, el puntero es válido hasta que la función EvtCleanupCallback devuelve.

Si el controlador intenta acceder al objeto de dispositivo WDM después de quitarlo, el controlador puede hacer que el sistema se bloquee. El ejemplo toastmon muestra cómo el controlador puede proporcionar una función de devolución de llamada EvtIoTargetQueryRemove para que se notifique si se quita el destino de E/S.

Para UMDF, WdfIoTargetWdmGetTargetFileHandle devuelve un IDENTIFICADOR win32 válido solo en el proceso actual. Un controlador UMDF heredado (versión 1.x) llama a IWDFDevice::RetrieveDeviceName para obtener el nombre del dispositivo en modo kernel subyacente y, a continuación, abre un identificador con CreateFile. Después, el controlador puede enviar E/S directamente a los dispositivos inferiores mediante DeviceIoControl. A partir de UMDF 2.15, los controladores de UMDF v2 pueden abrir el destino de E/S local por archivo (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) y recuperar el identificador de archivo mediante WdfIoTargetWdmGetTargetFileHandle. El marco se abre y cierra el identificador de archivo cuando se cierra o elimina el destino remoto. El identificador de archivo sigue siendo válido dentro del contrato de WdfIoTargetWdmGetTargetFileHandle descrito anteriormente.

Advertencia

Si un controlador de UMDF v2 llama a WdfIoTargetWdmGetTargetFileHandle para obtener el identificador win32 de un destino remoto abierto mediante WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, no envíe E/S superpuesta/asincrónica con API como DeviceIoControl. Si lo hace, puede bloquear el proceso que hospeda el controlador. Si el controlador debe enviar E/S superpuesta, también debe establecer el bit de orden bajo del miembro hEvent de la estructura SUPERPUESTA . Esto se debe a que el marco enlaza internamente el identificador a un puerto de finalización de E/S. Un identificador de eventos válido cuyo bit de orden bajo se establece impide que la finalización de E/S se pone en cola al puerto de finalización.

Para obtener más información sobre WdfIoTargetWdmGetTargetFileHandle, vea Obtener información sobre un destino de E/S general.

Para obtener más información sobre los destinos de E/S, consulte Uso de destinos de E/S.

Ejemplos

En el ejemplo de código siguiente se obtiene un identificador para el archivo asociado a un destino de E/S remoto especificado.

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

Un controlador UMDF heredado (versión 1.x) llama a IWDFDevice::RetrieveDeviceName para obtener el nombre del dispositivo en modo kernel subyacente y, a continuación, abre un identificador con CreateFile. A continuación, el controlador envía E/S directamente al dispositivo mediante DeviceIoControl.

A partir de UMDF 2.15, el controlador abre el destino de E/S local por archivo y recupera su identificador. El marco se abre y cierra el identificador de archivo. El identificador de archivo sigue siendo válido dentro del contrato de WdfIoTargetWdmGetTargetFileHandle.

NTSTATUS status;

WDF_IO_TARGET_OPEN_PARAMS params;

WDFIOTARGET ioTarget = NULL;

HANDLE handle = NULL;

status = WdfIoTargetCreate(Device, &attr, &ioTarget);

if (!NT_SUCCESS(status)) {

    // error handling

}

WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE(&params, NULL);

status = WdfIoTargetOpen(ioTarget, &params);

if (!NT_SUCCESS(status)) {

    // error handling

}

handle = WdfIoTargetWdmGetTargetFileHandle(ioTarget);

if (handle == NULL) {

    // error handling

}

if (ioTarget != NULL) {
    WdfIoTargetClose(ioTarget);
}
// You can now call DeviceIoControl(handle, ...) etc.
// NOTE: See Warning above on submitting overlapped or asynchronous I/O

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.15
Encabezado	wdfiotarget.h (incluya Wdf.h)
Library	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte también

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject