IoBuildDeviceIoControlRequest 함수(wdm.h)

아티클
08/08/2023

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

요청에 사용할 IOCTL(I/O 제어 코드)을 제공합니다. 디바이스 유형별 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로 설정할 수 있습니다. 그러나 Event 가 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를 호출하여 완료해야 합니다. IoCompleteRequest가 호출된 후 I/O 관리자가 이러한 동기 IRP를 해제하므로 IoBuildDeviceIoControlRequest를 호출하는 드라이버는 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)