다음을 통해 공유

DRIVER_DISPATCH 콜백 함수(wdm.h)

  • 아티클

콜백 루틴은 다양한 IRP를 서비스합니다. 함수 코드 목록은 비고를 참조하세요.

구문

DRIVER_DISPATCH DriverDispatch;

NTSTATUS DriverDispatch(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

매개 변수

[in, out] DeviceObject

DEVICE_OBJECT 구조체에 대한 호출자 제공 포인터입니다. 이는 이전에 드라이버의 AddDevice 루틴에서 만든 대상 디바이스의 디바이스 개체입니다.

[in, out] Irp

요청된 I/O 작업을 설명하는 IRP 구조체에 대한 호출자 제공 포인터입니다.

반환 값

루틴이 성공하면 STATUS_SUCCESS 반환해야 합니다. 그렇지 않으면 Ntstatus.h에 정의된 오류 상태 값 중 하나를 반환해야 합니다.

설명

모든 디스패치 루틴에 대한 입력 매개 변수는 Irp가 가리키는 IRP 구조에 제공됩니다. 추가 매개 변수는 드라이버의 연결된 I/O 스택 위치에 제공됩니다. 이 위치는 IO_STACK_LOCATION 구조체에서 설명하고 IoGetCurrentIrpStackLocation을 호출하여 가져올 수 있습니다.

일반적으로 모든 디스패치 루틴은 IRQL = PASSIVE_LEVEL 임의 스레드 컨텍스트에서 실행되지만 예외가 있습니다. 자세한 내용은 디스패치 루틴 및 IRQL을 참조하세요.

디스패치 루틴에 대한 자세한 내용은 디스패치 루틴 작성을 참조하세요. IRP에 대한 자세한 내용은 IRP 처리를 참조하세요.

IRP 콜백 구현 정보
IRP_MJ_CLEANUP 드라이버의 DispatchCleanup 루틴 이름은 XxxDispatchCleanup이어야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchCleanup 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_CLEANUP]에 저장해야 합니다.
IRP_MJ_CLOSE 드라이버의 DispatchClose 루틴 이름은 XxxDispatchClose여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchClose 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_CLOSE]에 저장해야 합니다.
IRP_MJ_CREATE 드라이버의 DispatchCreate 루틴의 이름은 XxxDispatchCreate여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchCreate 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_CREATE]에 저장해야 합니다.
IRP_MJ_CREATE 또는 IRP_MJ_CLOSE 드라이버는 별도의 DispatchCreate 및 DispatchClose 루틴 대신 단일 DispatchCreateClose 루틴을 제공할 수 있습니다.

드라이버의 DispatchCreateClose 루틴의 이름은 XxxDispatchCreateClose여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchCreateClose 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_CREATE] 및DriverObject-MajorFunction>[IRP_MJ_CLOSE]에 저장해야 합니다.
IRP_MJ_DEVICE_CONTROL 드라이버의 DispatchDeviceControl 루틴의 이름은 XxxDispatchDeviceControl이어야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchDeviceControl 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL]에 저장해야 합니다.

시스템은 I/O 컨트롤 코드의 FILE_XXX 플래그를 사용하여 IRP 보낸 사람에게 IRP를 디바이스 개체로 보낼 수 있는 권한이 있는지 여부를 확인합니다. Windows Server 2003 이상 버전의 Windows용 드라이버는 IoValidateDeviceIoControlAccess 루틴을 사용하여 DispatchDeviceControl 내에서 더 엄격한 액세스 검사를 수행할 수 있습니다.
IRP_MJ_FLUSH_BUFFERS 드라이버의 DispatchFlushBuffers 루틴의 이름은 XxxDispatchFlushBuffers여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchFlushBuffers 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS]에 저장해야 합니다.
IRP_MJ_INTERNAL_DEVICE_CONTROL 드라이버의 DispatchInternalDeviceControl 루틴의 이름은 XxxDispatchInternalDeviceControl이어야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchInternalDeviceControl 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL]에 저장해야 합니다.
IRP_MJ_PNP 드라이버의 DispatchPnP 루틴 이름은 XxxDispatchPnP여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchPnP 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_PNP]에 저장해야 합니다.
IRP_MJ_POWER 드라이버의 DispatchPower 루틴 이름은 XxxDispatchPower여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchPower 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_POWER]에 저장해야 합니다.
IRP_MJ_QUERY_INFORMATION 드라이버의 DispatchQueryInformation 루틴의 이름은 XxxDispatchQueryInformation이어야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchQueryInformation 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_QUERY_INFORMATION]에 저장해야 합니다.
IRP_MJ_READ 드라이버의 DispatchRead 루틴 이름은 XxxDispatchRead여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchRead 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_READ]에 저장해야 합니다.
IRP_MJ_READ 또는 IRP_MJ_WRITE 드라이버는 별도의 DispatchRead 및 DispatchWrite 루틴 대신 단일 DispatchReadWrite 루틴을 제공할 수 있습니다.

드라이버의 DispatchReadWrite 루틴의 이름은 XxxDispatchReadWrite여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchReadWrite 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_READ] 및DriverObject-MajorFunction>[IRP_MJ_WRITE]에 저장해야 합니다.
IRP_MJ_SET_INFORMATION 드라이버의 DispatchSetInformation 루틴의 이름은 XxxDispatchSetInformation이어야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchSetInformation 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_SET_INFORMATION]에 저장해야 합니다.
IRP_MJ_SHUTDOWN 드라이버의 DispatchShutdown 루틴 이름은 XxxDispatchShutdown이어야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchShutdown 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN]에 저장해야 합니다.

또한 IRP_MJ_SHUTDOWN 요청을 받으려면 드라이버가 IoRegisterShutdownNotification 또는 IoRegisterLastChanceShutdownNotification 을 호출하여 디스패치Shutdown 루틴을 시스템에 등록해야 합니다.
IRP_MJ_SYSTEM_CONTROL 드라이버의 DispatchSystemControl 루틴의 이름은 XxxDispatchSystemControl이어야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchSystemControl 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL]에 저장해야 합니다.
IRP_MJ_WRITE 드라이버의 DispatchWrite 루틴 이름은 XxxDispatchWrite여야 합니다. 여기서 Xxx 는 드라이버별 접두사입니다. 드라이버의 DriverEntry 루틴은 DispatchWrite 루틴의 주소를 DriverObject-MajorFunction>[IRP_MJ_WRITE]에 저장해야 합니다.

예제

콜백 루틴을 정의하려면 먼저 정의하려는 콜백 루틴의 유형을 식별하는 함수 선언을 제공해야 합니다. Windows는 드라이버에 대한 콜백 함수 형식 집합을 제공합니다. 콜백 함수 형식을 사용하여 함수를 선언하면 드라이버에 대한 코드 분석, SDV( 정적 드라이버 검증 도구 ) 및 기타 확인 도구에서 오류를 찾을 수 있으며 Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.

예를 들어 이름이 인 MyDispatchCleanupDispatchCleanup 콜백 루틴을 정의하려면 다음 코드 예제와 같이 DRIVER_DISPATCH 형식을 사용합니다.

DRIVER_DISPATCH MyDispatchCleanup;

그런 다음 다음과 같이 콜백 루틴을 구현합니다.

_Use_decl_annotations_
NTSTATUS
  MyDispatchCleanup(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

DRIVER_DISPATCH 함수 형식은 Wdm.h 헤더 파일에 정의되어 있습니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 the_Use_decl_annotations_annotation 추가해야 합니다. The_Use_decl_annotations_annotation 헤더 파일의 DRIVER_DISPATCH 함수 형식에 적용되는 주석이 사용되는지 확인합니다. 함수 선언에 대한 요구 사항에 대한 자세한 내용은 WDM 드라이버에 함수 역할 형식을 사용하여 함수 선언을 참조하세요. Use_decl_annotations 대한 자세한 내용은 함수 동작 주석 지정을 참조하세요.

요구 사항

요구 사항 값
대상 플랫폼 데스크톱
헤더 wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
IRQL PASSIVE_LEVEL 호출됩니다(설명 섹션 참조).