ZwDeviceIoControlFile 함수(ntddk.h)
ZwDeviceIoControlFile 루틴은 지정된 디바이스 드라이버에 직접 제어 코드를 보내 해당 드라이버가 지정된 작업을 수행하도록 합니다.
구문
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
);
매개 변수
[in] FileHandle
컨트롤 정보를 제공해야 하거나 정보를 반환해야 하는 디바이스를 나타내는 파일 개체에 대해 ZwCreateFile 또는 ZwOpenFile 에서 반환된 핸들입니다. 호출자가 Event, ApcRoutine 및 APC 컨텍스트( ApcContext) 또는 완료 컨텍스트( ApcContext)를 지정하는 경우 비동기 I/O에 대해 파일 개체를 열어야 합니다. 기본 대용량 스토리지 디바이스에 대한 I/O의 경우 DASD(스토리지 디바이스에 직접 액세스) 액세스를 위해 파일 개체를 열어야 합니다.
[in, optional] Event
호출자가 만든 이벤트에 대한 핸들입니다. 이 매개 변수가 제공되면 요청된 작업이 완료되고 지정된 이벤트가 Signaled 상태로 설정될 때까지 호출자가 대기 상태로 전환됩니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 호출자가 FileHandle이 신호됨 상태로 설정될 때까지 대기하는 경우 NULL이어야 합니다.
[in, optional] ApcRoutine
요청된 작업이 완료될 때 호출할 선택적 호출자 제공 APC 루틴의 주소입니다. 이 매개 변수는 NULL일 수 있습니다. 파일 개체와 연결된 I/O 완료 개체가 있는 경우 NULL 이어야 합니다.
[in, optional] ApcContext
호출자가 결정한 컨텍스트 영역에 대한 포인터입니다. 이 매개 변수 값은 호출자가 APC를 제공하는 경우 APC 컨텍스트로 사용되거나 I/O 완료 개체가 파일 개체와 연결된 경우 완료 컨텍스트로 사용됩니다. 작업이 완료되면 APC 컨텍스트가 APC에 전달되거나, 지정한 경우 완료 컨텍스트가 I/O 관리자가 연결된 I/O 완료 개체에 게시하는 완료 메시지의 일부로 포함됩니다.
이 매개 변수는 선택 사항이며 NULL일 수 있습니다. ApcRoutine이 NULL이고 파일 개체와 연결된 I/O 완료 개체가 없는 경우 NULL이어야 합니다.
[out] IoStatusBlock
최종 완료 상태 수신하는 변수 및 작업에 대한 정보를 가리키는 포인터입니다. 데이터를 반환하는 성공적인 호출의 경우 OutputBuffer 에 기록된 바이트 수가 정보 멤버에 반환됩니다.
[in] IoControlCode
IOCTL_XXX 코드는 일반적으로 기본 디바이스 드라이버에서 수행할 디바이스 I/O 제어 작업을 나타냅니다. 이 매개 변수의 값은 InputBuffer 및 OutputBuffer의 형식 및 필수 길이와 다음 매개 변수 쌍을 결정합니다. 시스템 정의 디바이스 유형별 IOCTL_XXX 코드에 대한 자세한 내용은 Microsoft Windows SDK 설명서의 Microsoft WDK(Windows 드라이버 키트) 설명서 및 디바이스 입력 및 출력 제어 코드의 디바이스기술별 섹션을 참조하세요.
[in, optional] InputBuffer
대상 디바이스에 제공될 디바이스별 정보를 포함하는 호출자가 할당한 입력 버퍼에 대한 포인터입니다. IoControlCode가 입력 데이터가 필요하지 않은 작업을 지정하는 경우 이 포인터는 NULL일 수 있습니다.
[in] InputBufferLength
InputBuffer의 버퍼 크기(바이트)입니다. InputBuffer가 NULL인 경우 InputBufferLength를 0으로 설정합니다.
[out, optional] OutputBuffer
대상 디바이스에서 정보가 반환되는 호출자가 할당한 출력 버퍼에 대한 포인터입니다. IoControlCode가 출력 데이터를 생성하지 않는 작업을 지정하는 경우 이 포인터는 NULL일 수 있습니다.
[in] OutputBufferLength
OutputBuffer의 버퍼 크기(바이트)입니다. OutputBuffer가 NULL이면 OutputBufferLength를 0으로 설정합니다.
반환 값
ZwDeviceIoControlFile 은 기본 드라이버가 요청된 작업을 성공적으로 수행한 경우 STATUS_SUCCESS 반환합니다. 그렇지 않으면 반환 값은 기본 드라이버에서 전파된 코드 상태 오류일 수 있습니다. 가능한 오류 상태 코드에는 다음이 포함됩니다.
설명
ZwDeviceIoControlFile 은 시스템 및 커널 모드 드라이버에 대한 입력 및 출력 데이터의 일관된 보기를 제공하는 동시에 애플리케이션 및 기본 드라이버에 통신 인터페이스를 지정하는 디바이스 종속 메서드를 제공합니다.
시스템 정의 IOCTL_XXX 코드에 대한 자세한 내용과 드라이버별 IOCTL_XXX 또는 FSCTL_XXX 값 정의에 대한 자세한 내용은 커널 모드 아키텍처 가이드에서 I/O 제어 코드 사용 및 Microsoft Windows SDK 설명서의 디바이스 입력 및 출력 제어 코드를 참조하세요.
호출자가 비동기 I/O에 대한 파일을 연 경우(FILE_SYNCHRONOUS_XXX 만들기/열기 옵션 집합 없음) 지정된 이벤트가 있는 경우 디바이스 제어 작업이 완료될 때 신호를 받은 상태로 설정됩니다. 그렇지 않으면 FileHandle 로 지정된 파일 개체가 신호 상태로 설정됩니다. ApcRoutine을 지정한 경우 ApcContext 및 IoStatusBlock 포인터를 사용하여 호출됩니다.
미니필터는 ZwDeviceIoControlFile 대신 FltDeviceIoControlFile을 사용해야 합니다.
ZwDeviceIoControlFile의 호출자는 IRQL = PASSIVE_LEVEL 및 특수 커널 APC를 사용하도록 설정된 상태에서 실행되어야 합니다.
ZwDeviceIoControlFile 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwDeviceIoControlFile" 대신 "NtDeviceIoControlFile" 이름을 사용해야 합니다.
커널 모드 드라이버에서 호출하는 경우 Windows 네이티브 시스템 서비스 루틴의 NtXxx 및 ZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 대상 플랫폼 | 유니버설 |
| 헤더 | ntddk.h(Ntifs.h, Ntddk.h 포함) |
| 라이브러리 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL(설명 섹션 참조) |
| DDI 규정 준수 규칙 | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |