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 se 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.
Observaciones
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, consulte Using a File Handle.
El identificador de archivo que devuelve el método WdfIoTargetWdmGetFileHandle 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 EvtCleanupCall back para el objeto de destino de E/S remoto y, si el objeto se elimina antes de que se cierre el destino de E/S remoto, el puntero es válido hasta que se devuelve la función EvtCleanupCallback.
Si el controlador intenta acceder al objeto de dispositivo WDM después de quitarlo, el controlador puede hacer que el sistema se bloquee. El toastmon muestra cómo el controlador puede proporcionar un EvtIoTargetQueryRemove función de devolución de llamada 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 permanece 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 o 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 de la hEvent miembro del estructura de SUPERPUESTA. Esto se debe a que el marco enlaza internamente el identificador a un puerto de finalización de E/S. Un controlador de eventos válido cuyo bit de orden bajo se establece impide que la E/S finalice en cola hasta el 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, abrir 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 permanece 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(¶ms, NULL);
status = WdfIoTargetOpen(ioTarget, ¶ms);
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 | Valor |
|---|---|
| de la plataforma de destino de | Universal |
| versión mínima de KMDF | 1.0 |
| versión mínima de UMDF | 2.15 |
| encabezado | wdfiotarget.h (incluya Wdf.h) |
| Biblioteca | 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) |