Función IoBuildDeviceIoControlRequest (wdm.h)

Artículo
08/08/2023

La rutina IoBuildDeviceIoControlRequest asigna y configura un IRP para una solicitud de control de dispositivo procesada sincrónicamente.

Sintaxis

__drv_aliasesMem PIRP IoBuildDeviceIoControlRequest(
  [in]            ULONG            IoControlCode,
  [in]            PDEVICE_OBJECT   DeviceObject,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength,
  [in]            BOOLEAN          InternalDeviceIoControl,
  [in, optional]  PKEVENT          Event,
  [out]           PIO_STATUS_BLOCK IoStatusBlock
);

Parámetros

[in] IoControlCode

Proporciona el código de control de E/S (IOCTL) que se usará en la solicitud. Para obtener información sobre los códigos de control de E/S específicos del tipo de dispositivo, consulta las secciones específicas del tipo de dispositivo en el Kit de controladores de Windows (WDK).

[in] DeviceObject

Proporciona un puntero a la estructura DEVICE_OBJECT para el objeto de dispositivo del controlador siguiente inferior, que representa el dispositivo de destino.

[in, optional] InputBuffer

Proporciona un puntero a un búfer de entrada que se pasará al controlador inferior o NULL si la solicitud no pasa datos de entrada a controladores inferiores.

[in] InputBufferLength

Proporciona la longitud, en bytes, del búfer de entrada. Si InputBuffer es NULL, InputBufferLength debe ser cero.

[out, optional] OutputBuffer

Proporciona un puntero a un búfer de salida en el que el controlador inferior va a devolver datos, o NULL si la solicitud no requiere controladores inferiores para devolver datos.

[in] OutputBufferLength

Proporciona la longitud, en bytes, del búfer de salida. Si OutputBuffer es NULL, OutputBufferLength debe ser cero.

[in] InternalDeviceIoControl

Si es TRUE, la rutina establece el código de función principal del IRP en IRP_MJ_INTERNAL_DEVICE_CONTROL. De lo contrario, la rutina establece el código de función principal del IRP en IRP_MJ_DEVICE_CONTROL.

[in, optional] Event

Proporciona un puntero a un objeto de evento asignado por el autor de la llamada e inicializado. El administrador de E/S establece el evento en el estado Signaled cuando un controlador de nivel inferior completa la operación solicitada. Después de llamar a IoCallDriver, el controlador puede esperar al objeto de evento. El parámetro Event es opcional y se puede establecer en NULL. Sin embargo, si Event es NULL, el autor de la llamada debe proporcionar una rutina de IoCompletion para que el IRP notifique al autor de la llamada cuando se complete la operación.

[out] IoStatusBlock

Especifica un bloque de estado de E/S que se va a establecer cuando los controladores inferiores completan la solicitud.

Valor devuelto

Si la operación se realiza correctamente, IoBuildDeviceIoControlRequest devuelve un puntero a un IRP, con la ubicación de pila de E/S del controlador siguiente inferior configurada a partir de los parámetros proporcionados. De lo contrario, la rutina devuelve NULL.

Comentarios

Un controlador puede llamar a IoBuildDeviceIoControlRequest para configurar IRP para las solicitudes de control de dispositivos que envía de forma sincrónica a controladores de nivel inferior.

Después de llamar a IoBuildDeviceIoControlRequest para crear una solicitud, el controlador debe llamar a IoCallDriver para enviar la solicitud al controlador siguiente inferior. Si IoCallDriver devuelve STATUS_PENDING, el controlador debe esperar a que se complete el IRP llamando a KeWaitForSingleObject en el evento especificado. La mayoría de los controladores no necesitan establecer una rutina de IoCompletion para irP.

Las IRP creadas por IoBuildDeviceIoControlRequest deben completarse mediante la llamada de un controlador a IoCompleteRequest. Un controlador que llama a IoBuildDeviceIoControlRequest no debe llamar a IoFreeIrp, porque el administrador de E/S libera estos IRP sincrónicos después de llamar a IoCompleteRequest .

IoBuildDeviceIoControlRequest pone en cola los IRP que crea en una cola IRP específica del subproceso actual. Si se cierra el subproceso, el administrador de E/S cancela el IRP.

Si el autor de la llamada proporciona un parámetro InputBuffer o OutputBuffer , este parámetro debe apuntar a un búfer que reside en la memoria del sistema. El autor de la llamada es responsable de validar los valores de parámetro que copia en el búfer de entrada desde un búfer en modo de usuario. El búfer de entrada puede contener valores de parámetro que se interpretan de forma diferente en función de si el originador de la solicitud es una aplicación en modo de usuario o un controlador en modo kernel. En el IRP que devuelve IoBuildDeviceIoControlRequest , el campo RequestorMode siempre se establece en KernelMode. Este valor indica que la solicitud y cualquier información contenida en la solicitud procede de un componente de modo kernel de confianza.

Si el autor de la llamada no puede validar los valores de parámetro que copia de un búfer en modo de usuario en el búfer de entrada, o si estos valores no se deben interpretar como procedentes de un componente en modo kernel, el autor de la llamada debe establecer el campo RequestorMode del IRP en UserMode. Esta configuración informa al controlador que controla la solicitud de control de E/S de que el búfer contiene datos en modo de usuario que no son de confianza.

El método real por el que el contenido de los parámetros InputBuffer y OutputBuffer se almacenan en irP depende del valor TransferType del IOCTL. Para obtener más información sobre este valor, vea Descripciones del búfer para códigos de control de E/S.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 2000.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoBuildDeviceControlNoFree(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent(wdm), IrqlIoPassive1(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)