Función ZwDeviceIoControlFile (ntifs.h)
La rutina ZwDeviceIoControlFile envía un código de control directamente a un controlador de dispositivo especificado, lo que hace que el controlador correspondiente realice la operación especificada.
Sintaxis
NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG IoControlCode,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
Parámetros
[in] FileHandle
Identificador devuelto por ZwCreateFile o ZwOpenFile para el objeto de archivo que representa el dispositivo al que se debe proporcionar la información de control o desde la que se debe devolver la información. El objeto de archivo debe haberse abierto para E/S asincrónica si el autor de la llamada especifica un evento, ApcRoutine y un contexto de APC (en ApcContext) o un contexto de finalización (en ApcContext). Para la E/S a un dispositivo de almacenamiento masivo subyacente, el objeto de archivo debe haberse abierto para el acceso directo al dispositivo de almacenamiento (DASD).
[in, optional] Event
Identificador de un evento creado por el autor de la llamada. Si se proporciona este parámetro, el autor de la llamada se colocará en un estado de espera hasta que se complete la operación solicitada y el evento especificado se establezca en el estado Signaled. Este parámetro es opcional y puede ser NULL. Debe ser NULL si el autor de la llamada esperará a que FileHandle se establezca en el estado Signaled.
[in, optional] ApcRoutine
Dirección de una rutina de APC opcional proporcionada por el autor de la llamada que se llamará cuando se complete la operación solicitada. Este parámetro puede ser NULL. Debe ser NULL si hay un objeto de finalización de E/S asociado al objeto de archivo.
[in, optional] ApcContext
Puntero a un área de contexto determinada por el autor de la llamada. Este valor de parámetro se usa como contexto de APC si el autor de la llamada proporciona un APC o se usa como contexto de finalización si se ha asociado un objeto de finalización de E/S con el objeto de archivo. Cuando se completa la operación, el contexto de APC se pasa al APC, si se especificó uno o el contexto de finalización se incluye como parte del mensaje de finalización que el Administrador de E/S envía al objeto de finalización de E/S asociado.
Este parámetro es opcional y puede ser NULL. Debe ser NULL si ApcRoutine es NULL y no hay ningún objeto de finalización de E/S asociado al objeto de archivo.
[out] IoStatusBlock
Puntero a una variable que recibe el estado de finalización final e información sobre la operación. Para llamadas correctas que devuelven datos, el número de bytes escritos en OutputBuffer se devuelve en el miembro Information .
[in] IoControlCode
IOCTL_XXX código que indica en qué operación de control de E/S del dispositivo se va a llevar a cabo, normalmente por el controlador de dispositivo subyacente. El valor de este parámetro determina el formato y la longitud necesaria de InputBuffer y OutputBuffer, así como cuál de los siguientes pares de parámetros son necesarios. Para obtener información detallada sobre los códigos IOCTL_XXX específicos del tipo de dispositivo definidos por el sistema, consulte la sección específica de la tecnología del dispositivo de la documentación del Kit de controladores de Microsoft Windows (WDK) y los códigos de entrada y control de salida del dispositivo en la documentación de Microsoft Windows SDK.
[in, optional] InputBuffer
Puntero a un búfer de entrada asignado por el autor de la llamada que contiene información específica del dispositivo que se va a proporcionar al dispositivo de destino. Si IoControlCode especifica una operación que no requiere datos de entrada, este puntero puede ser NULL.
[in] InputBufferLength
Tamaño, en bytes, del búfer en InputBuffer. Si InputBuffer es NULL, establezca InputBufferLength en cero.
[out, optional] OutputBuffer
Puntero a un búfer de salida asignado por el autor de la llamada en el que se devuelve información del dispositivo de destino. Si IoControlCode especifica una operación que no genera datos de salida, este puntero puede ser NULL.
[in] OutputBufferLength
Tamaño, en bytes, del búfer en OutputBuffer. Si OutputBuffer es NULL, establezca OutputBufferLength en cero.
Valor devuelto
ZwDeviceIoControlFile devuelve STATUS_SUCCESS si los controladores subyacentes realizaron correctamente la operación solicitada. De lo contrario, el valor devuelto puede ser un código de estado de error propagado desde un controlador subyacente. Entre los posibles códigos de estado de error se incluyen los siguientes:
Comentarios
ZwDeviceIoControlFile proporciona una vista coherente de los datos de entrada y salida al sistema y a los controladores en modo kernel, al tiempo que proporciona aplicaciones y controladores subyacentes con un método dependiente del dispositivo de especificar una interfaz de comunicaciones.
Para obtener más información sobre los códigos IOCTL_XXX definidos por el sistema y sobre cómo definir valores de IOCTL_XXX o FSCTL_XXX específicos del controlador, vea Using I/O Control Codes in the Kernel Mode Architecture Guide and Device Input and Output Control Codes en la documentación de Microsoft Windows SDK.
Si el autor de la llamada abrió el archivo para E/S asincrónica (con ninguna FILE_SYNCHRONOUS_XXX create/open option set), el evento especificado, si existe, se establecerá en el estado señalado cuando se complete la operación de control de dispositivo. De lo contrario, el objeto de archivo especificado por FileHandle se establecerá en el estado señalado. Si se especificó una instancia de ApcRoutine , se llama con los punteros ApcContext e IoStatusBlock .
Los minifiltros deben usar FltDeviceIoControlFile en lugar de ZwDeviceIoControlFile.
Los autores de llamadas de ZwDeviceIoControlFile deben ejecutarse en IRQL = PASSIVE_LEVEL y con las API de kernel especiales habilitadas.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000. |
| Plataforma de destino | Universal |
| Encabezado | ntifs.h (include Ntifs.h, Ntddk.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (consulte la sección Comentarios) |
| Reglas de cumplimiento de DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |
Consulte también
Usar códigos de control de E/S
Uso de las versiones Nt y Zw de las rutinas nativas de System Services