IoBuildDeviceIoControlRequest 함수(wdm.h)
IoBuildDeviceIoControlRequest 루틴은 동기적으로 처리된 디바이스 제어 요청에 대한 IRP를 할당하고 설정합니다.
통사론
__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
);
매개 변수
[in] IoControlCode
요청에 사용할 I/O 제어 코드(IOCTL)를 제공합니다. 디바이스 유형별 I/O 제어 코드에 대한 자세한 내용은 WDK(Windows 드라이버 키트)의 디바이스 유형별 섹션을 참조하세요.
[in] DeviceObject
대상 디바이스를 나타내는 다음 하위 드라이버의 디바이스 개체에 대한 DEVICE_OBJECT 구조체에 대한 포인터를 제공합니다.
[in, optional] InputBuffer
하위 드라이버에 전달할 입력 버퍼에 대한 포인터를 제공하거나 요청이 입력 데이터를 낮은 드라이버에 전달하지 않으면 NULL .
[in] InputBufferLength
입력 버퍼의 길이(바이트)를 제공합니다. InputBuffer NULL 경우 InputBufferLength 0이어야 합니다.
[out, optional] OutputBuffer
낮은 드라이버가 데이터를 반환하는 출력 버퍼에 대한 포인터를 제공하거나, 요청에 낮은 드라이버가 데이터를 반환할 필요가 없는 경우 NULL .
[in] OutputBufferLength
출력 버퍼의 길이(바이트)를 제공합니다. OutputBuffer NULL 경우 outputBufferLength 0이어야 합니다.
[in] InternalDeviceIoControl
TRUE 경우 루틴은 IRP의 주요 함수 코드를 IRP_MJ_INTERNAL_DEVICE_CONTROL설정합니다. 그렇지 않으면 루틴은 IRP의 주요 함수 코드를 IRP_MJ_DEVICE_CONTROL설정합니다.
[in, optional] Event
호출자가 할당하고 초기화된 이벤트 개체에 대한 포인터를 제공합니다. I/O 관리자는 하위 수준 드라이버가 요청된 작업을 완료할 때 이벤트를 Signaled 상태로 설정합니다. IoCallDriver호출한 후 드라이버는 이벤트 개체를 기다릴 수 있습니다. Event 매개 변수는 선택 사항이며 NULL로 설정할 수 있습니다. 그러나 이벤트 NULL인 경우 호출자는 작업이 완료되면 호출자에게 알리기 위해 IRP에 대한 IoCompletion 루틴을 제공해야 합니다.
[out] IoStatusBlock
낮은 드라이버에서 요청을 완료할 때 설정할 I/O 상태 블록을 지정합니다.
반환 값
작업이 성공하면 IoBuildDeviceIoControlRequest 제공된 매개 변수에서 다음 하위 드라이버의 I/O 스택 위치가 설정된 IRP대한 포인터를 반환합니다. 그렇지 않으면 루틴은 NULL반환합니다.
발언
드라이버는 IoBuildDeviceIoControlRequest 호출하여 하위 수준 드라이버에 동기적으로 보내는 디바이스 제어 요청에 대한 IRP를 설정할 수 있습니다.
IoBuildDeviceIoControlRequest 호출하여 요청을 만든 후 드라이버는 IoCallDriver 호출하여 다음 하위 드라이버로 요청을 보내야 합니다. IoCallDriver STATUS_PENDING 반환하는 경우 드라이버는 지정된 이벤트KeWaitForSingleObject 호출하여 IRP가 완료될 때까지 기다려야 합니다. 대부분의 드라이버는 IRP에 대한 IoCompletion 루틴을 설정할 필요가 없습니다.
IoBuildDeviceIoControlRequest 만든 IRP는 드라이버가 IoCompleteRequest호출하여 완료해야 합니다. IoBuildDeviceIoControlRequest 호출하는 드라이버는 IoCompleteRequest 호출된 후 I/O 관리자가 이러한 동기 IRP를 해제하므로 IoFreeIrp호출해서는 안 됩니다.
IoBuildDeviceIoControlRequest 현재 스레드와 관련된 IRP 큐에 만드는 IRP를 큐에 추가합니다. 스레드가 종료되면 I/O 관리자가 IRP를 취소합니다.
호출자가 InputBuffer 또는 outputBuffer 매개 변수를 경우 이 매개 변수는 시스템 메모리에 있는 버퍼를 가리킵니다. 호출자는 사용자 모드 버퍼에서 입력 버퍼에 복사하는 매개 변수 값의 유효성을 검사합니다. 입력 버퍼에는 요청의 시작자가 사용자 모드 애플리케이션인지 커널 모드 드라이버인지에 따라 다르게 해석되는 매개 변수 값이 포함될 수 있습니다. IoBuildDeviceIoControlRequest 반환하는 IRP에서 RequestorMode 필드는 항상 KernelMode 설정됩니다. 이 값은 요청과 요청에 포함된 모든 정보가 신뢰할 수 있는 커널 모드 구성 요소에서 온 것임을 나타냅니다.
호출자가 사용자 모드 버퍼에서 입력 버퍼로 복사하는 매개 변수 값의 유효성을 검사할 수 없거나 이러한 값을 커널 모드 구성 요소에서 가져오는 것으로 해석하지 않아야 하는 경우 호출자는 IRP의 RequestorMode 필드를 설정하여 UserMode 합니다. 이 설정은 버퍼에 신뢰할 수 없는 사용자 모드 데이터가 포함되어 있음을 I/O 컨트롤 요청을 처리하는 드라이버에 알릴 수 있습니다.
InputBuffer 및 OutputBuffer 매개 변수의 내용이 IRP에 저장되는 실제 메서드는 IOCTL에 대한 TransferType 값에 따라 달라집니다. 이 값에 대한 자세한 내용은 I/O 컨트롤 코드 대한버퍼 설명을 참조하세요.
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000부터 사용할 수 있습니다. |
| 대상 플랫폼 | 보편적 |
| 헤더 | wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함) |
| 라이브러리 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| DDI 규정 준수 규칙 | HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoBuildDeviceControlNoFree(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent() wdm), IrqlIoPassive1(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm) |