IoRegisterPlugPlayNotification 함수(wdm.h)

아티클
08/08/2023

IoRegisterPlugPlayNotification 루틴은 지정된 범주의 PnP 이벤트가 발생할 때 호출할 플러그 앤 플레이(PnP) 알림 콜백 루틴을 등록합니다.

구문

NTSTATUS IoRegisterPlugPlayNotification(
  [in]           IO_NOTIFICATION_EVENT_CATEGORY        EventCategory,
  [in]           ULONG                                 EventCategoryFlags,
  [in, optional] PVOID                                 EventCategoryData,
  [in]           PDRIVER_OBJECT                        DriverObject,
  [in]           PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine,
  [in, optional] __drv_aliasesMem PVOID                Context,
  [out]          PVOID                                 *NotificationEntry
);

매개 변수

[in] EventCategory

콜백 루틴이 등록되는 PnP 이벤트의 범주를 나타내는 IO_NOTIFICATION_EVENT_CATEGORY 열거형 값을 지정합니다.

[in] EventCategoryFlags

등록 작업을 수정하는 비트에 플래그를 지정합니다. 가능한 값은 다음과 같습니다.

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

EventCategoryDeviceInterfaceChange의 EventCategory에서만 유효합니다. 설정된 경우 PnP 관리자는 현재 등록되고 활성 상태인 각 디바이스 인터페이스 instance 대한 드라이버 콜백 루틴을 호출하고 향후 디바이스 인터페이스 인스턴스의 도착 또는 제거를 위해 콜백 루틴을 등록합니다.

[in, optional] EventCategoryData

CallbackRoutine이 등록되는 이벤트에 대한 추가 정보에 대한 포인터입니다. 정보는 다양한 EventCategory 값에 따라 다릅니다.

EventCategory가 EventCategoryDeviceInterfaceChange인 경우 EventCategoryData는 디바이스 인터페이스 클래스를 지정하는 GUID를 가리킵니다. CallbackRoutine 은 해당 클래스의 인터페이스를 사용하거나 제거할 때 호출됩니다.
EventCategory가 EventCategoryHardwareProfileChange인 경우 EventCategoryData는 NULL이어야 합니다.
EventCategory가 EventCategoryTargetDeviceChange인 경우 EventCategoryData는 PnP 알림이 요청된 파일 개체를 가리킵니다.

[in] DriverObject

호출자의 드라이버 개체에 대한 포인터입니다.

드라이버가 PnP 알림에 등록된 동안 로드된 상태로 유지되도록 하기 위해 이 호출은 DriverObject에서 참조 횟수를 증가합니다. 이 등록이 제거되면 PnP 관리자가 참조 수를 감소합니다.

EventCategoryTargetDeviceChange의 경우 DriverObject는 대상 디바이스의 드라이버 개체가 아니어야 합니다. 오히려 CallbackRoutine을 구현하는 드라이버의 드라이버 개체여야 합니다.

[in] CallbackRoutine

지정된 PnP 이벤트가 발생할 때 호출할 PnP 알림 콜백 루틴에 대한 포인터입니다.

이 콜백 루틴에 대한 함수 프로토타입은 다음과 같이 정의됩니다.

typedef NTSTATUS
  DRIVER_NOTIFICATION_CALLBACK_ROUTINE(
    _In_ PVOID NotificationStructure,
    _Inout_opt_ PVOID Context
    );

콜백 루틴의 NotificationStructure 는 다음 표와 같이 EventCategory 값과 관련이 있습니다.

이벤트 범주	알림 구조
EventCategoryDeviceInterfaceChange	DEVICE_INTERFACE_CHANGE_NOTIFICATION
EventCategoryHardwareProfileChange	HWPROFILE_CHANGE_NOTIFICATION
EventCategoryTargetDeviceChange	TARGET_DEVICE_REMOVAL_NOTIFICATION 자세한 내용은 PnP 알림 및 TARGET_DEVICE_CUSTOM_NOTIFICATION 사용을 참조 하세요.

콜백 루틴의 Context 매개 변수에는 등록 중에 드라이버가 제공한 컨텍스트 데이터가 포함됩니다.

SDV( 정적 드라이버 검증 도구 )의 요구 사항을 충족하는 콜백 루틴에 대한 함수 선언을 포함하는 방법에 대한 자세한 내용은 예제를 참조하세요.

PnP 관리자는 IRQL = PASSIVE_LEVEL 드라이버 콜백 루틴을 호출합니다.

[in, optional] Context

PnP 관리자가 콜백 루틴에 전달하는 컨텍스트를 포함하는 호출자 할당 버퍼에 대한 포인터입니다.

[out] NotificationEntry

등록을 식별하는 이 호출에서 반환된 불투명 값에 대한 포인터입니다. 이 값을 IoUnregisterPlugPlayNotificationEx 루틴에 전달하여 등록을 제거합니다.

반환 값

IoRegisterPlugPlayNotification은 STATUS_SUCCESS 또는 적절한 오류 상태 반환합니다.

설명

드라이버가 이벤트 범주에 등록합니다. 각 범주에는 하나 이상의 PnP 이벤트 유형이 포함됩니다.

드라이버는 다른 이벤트 범주에 대해 다른 콜백 루틴을 등록하거나 단일 콜백 루틴을 등록할 수 있습니다. 단일 콜백 루틴은 NotificationStructure 를 PLUGPLAY_NOTIFICATION_HEADER 캐스팅하고 이벤트 필드를 사용하여 알림 구조의 정확한 유형을 확인할 수 있습니다.

호출자가 PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES 지정하는 경우 운영 체제는 기존 인터페이스에 대한 단일 EventCategoryDeviceInterfaceChange 이벤트에 대해 PnP 알림 콜백 루틴을 두 번 호출할 수 있습니다. 콜백에 대한 두 번째 호출을 무시해도 됩니다. 운영 체제는 단일 이벤트에 대해 콜백을 두 번 이상 호출하지 않습니다.

PnP 알림 콜백 루틴은 이벤트를 등록한 다른 드라이버 및 애플리케이션에 알리는 지연을 방지하기 위해 가능한 한 빨리 작업을 완료하고 PnP 관리자에게 제어권을 반환해야 합니다.

드라이버가 EventCategoryTargetDeviceChange 이벤트의 알림을 등록할 때 PnP 관리자는 파일 개체에 대한 참조를 사용하지 않습니다. 드라이버의 PnP 알림 콜백 루틴에서 파일 개체에 액세스해야 하는 경우 드라이버는 IoRegisterPlugPlayNotification을 호출하기 전에 파일 개체에 대한 추가 참조를 가져와야 합니다.

일반적으로 Kernel-Mode 드라이버 프레임워크(KMDF) 드라이버는 EvtDeviceSelfManagedIoInit 콜백 함수에서 IoRegisterPlugPlayNotification을 호출해야 하며 EvtDeviceSelfManagedIoCleanup 콜백 함수에서 IoUnregisterPlugPlayNotification을 호출해야 합니다. 이러한 드라이버는 EvtDriverDeviceAdd 콜백 함수에서 IoRegisterPlugPlayNotification을 호출해서는 안 됩니다. 그렇지 않으면 PnP에서 드라이버 스택을 시작하기 전에 PnP 알림 콜백 루틴을 호출할 수 있습니다. 이 경우 드라이버가 알림을 처리할 준비가 되지 않습니다.

자세한 내용은 PnP 알림 사용을 참조하세요.

예제

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

예를 들어 라는 MyCallbackRoutinePnP 알림 콜백 루틴을 정의하려면 다음 코드 예제와 같이 DRIVER_NOTIFICATION_CALLBACK_ROUTINE 형식을 사용합니다.

DRIVER_NOTIFICATION_CALLBACK_ROUTINE MyCallbackRoutine;

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

_Use_decl_annotations_
NTSTATUS
  MyCallbackRoutine(
    PVOID NotificationStructure,
    PVOID Context
    )
  {
      // Function body
  }

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

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)