Función IoBuildDeviceIoControlRequest (wdm.h)
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) |