WMI_QUERY_REGINFO_CALLBACK 콜백 함수(wmilib.h)

아티클
08/08/2023

DpWmiQueryReginfo 루틴은 드라이버에서 등록할 데이터 블록 및 이벤트 블록에 대한 정보를 제공합니다. 이 루틴은 필수입니다.

구문

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

매개 변수

[in] DeviceObject

드라이버의 WDM DEVICE_OBJECT 구조체에 대한 포인터입니다.

[out] RegFlags

이 매개 변수는 등록 중인 모든 블록의 일반적인 특성을 나타냅니다. RegFlags에 설정된 모든 플래그는 모든 블록에 적용됩니다. 드라이버는 블록의 WMIGUIDREGINFO 구조에서 플래그를 설정하여 지정된 블록에 대한 RegFlags를 보완할 수 있습니다. 예를 들어 드라이버는 RegFlags에서 WMIREG_FLAG_EXPENSIVE 지우지만 플래그 에 설정하여 지정된 블록을 수집 비용이 많이 드는 블록으로 등록할 수 있습니다.

드라이버는 RegFlags에서 다음 플래그 중 하나를 설정합니다.

WMIREG_FLAG_INSTANCE_BASENAME

InstanceName에서 드라이버가 제공한 기본 이름에서 정적 instance 이름을 생성하도록 WMI에 요청합니다. WMI는 기본 이름에 카운터를 추가하여 instance 이름을 생성합니다.

WMIREG_FLAG_INSTANCE_PDO

PDO에 대한 디바이스 instance ID에서 정적 instance 이름을 생성하도록 WMI에 요청합니다. 드라이버가 이 플래그를 설정하는 경우 Pdo 를 드라이버의 AddDevice 루틴에 전달된 PDO로 설정해야 합니다. WMI는 PDO의 디바이스 instance 경로에서 instance 이름을 생성합니다. 이러한 이름은 고유하게 보장되므로 디바이스 instance 경로를 정적 instance 이름의 기반으로 사용하는 것이 효율적입니다. WMI는 데이터 소비자가 쿼리할 수 있는 데이터 블록의 항목으로 instance "친숙한" 이름을 자동으로 제공합니다.

드라이버는 RegFlags에서 다음 플래그 중 하나 이상을 설정할 수도 있지만 일반적으로 블록의 WMIGUIDREGINFO 구조의 플래그에서 설정합니다.

WMIREG_FLAG_EVENT_ONLY_GUID

블록은 이벤트로만 사용하거나 사용하지 않도록 설정할 수 있으며 쿼리하거나 설정할 수 없습니다. 이 플래그가 명확하면 블록을 쿼리하거나 설정할 수도 있습니다.

WMIREG_FLAG_EXPENSIVE

데이터 소비자가 데이터 블록을 처음 열 때 WMI에 IRP_MN_ENABLE_COLLECTION 요청을 보내고 마지막 데이터 소비자가 데이터 블록을 닫을 때 IRP_MN_DISABLE_COLLECTION 요청을 보냅니다. 이러한 데이터를 수집하는 것이 성능에 영향을 주는 경우 드라이버가 데이터 소비자가 블록을 열어 명시적으로 요청할 때까지 데이터를 수집할 필요가 없기 때문에 권장됩니다.

WMIREG_FLAG_REMOVE_GUID

WMI에 블록에 대한 지원을 제거하도록 요청합니다. 이 플래그는 등록 정보 업데이트 요청에 대한 응답으로만 유효합니다(IRP_MN_REGINFO 또는 Parameters.WMI.DataPath가 WMIUPDATE로 설정된 IRP_MN_REGINFO_EX).

[out] InstanceName

드라이버에서 등록할 모든 블록의 모든 인스턴스에 대한 기본 이름으로 사용되는 단일 계산 유니코드 문자열에 대한 포인터입니다. WMI는 ExFreePool을 사용하여 문자열을 해제합니다. WMIREG_FLAG_INSTANCE_BASENAME 명확하면 InstanceName 이 무시됩니다.

[out] RegistryPath

드라이버의 DriverEntry 루틴에 전달된 레지스트리 경로를 지정하는 계산된 유니코드 문자열에 대한 포인터에 대한 포인터입니다.

[out] MofResourceName

드라이버의 이진 이미지 파일에 연결된 MOF 리소스의 이름을 나타내는 계산된 단일 유니코드 문자열에 대한 포인터입니다. 일반적으로 이 문자열은 드라이버에서 정의한 정적 문자열입니다. WMI는 드라이버가 이 루틴에서 반환된 후 이 문자열의 복사본을 만듭니다. 이 문자열은 드라이버에서 동적으로 할당할 수 있습니다. 할당된 문자열의 경우 드라이버는 WmiSystemControl 이 반환된 후 수행해야 하는 문자열을 해제해야 합니다. 드라이버에 MOF 리소스가 연결되어 있지 않으면 MofResourceName 을 변경하지 않고 그대로 둘 수 있습니다.

[out] Pdo

드라이버의 AddDevice 루틴에 전달된 PDO(물리적 디바이스 개체)에 대한 포인터입니다. WMIREG_FLAG_INSTANCE_PDO 설정된 경우 WMI는 이 PDO의 디바이스 instance 경로를 기본으로 사용하여 정적 instance 이름을 생성합니다. WMIREG_FLAG_INSTANCE_PDO 명확하면 WMI는 Pdo를 무시합니다.

반환 값

DpWmiQueryReginfo 는 항상 STATUS_SUCCESS 반환합니다.

설명

WMI는 드라이버가 IRP_MN_REGINFO 또는 IRP_MN_REGINFO_EX 요청에 대한 응답으로 WmiSystemControl을 호출한 후 드라이버의 DpWmiQueryReginfo 루틴을 호출합니다. 드라이버는 DpWmiQueryReginfo 루틴의 주소를 WmiSystemControl에 전달하는 WMILIB_CONTEXT 구조에 배치해야 합니다.

WMI는 드라이버가 WMIREG_ACTION_REGISTER, WMIREG_ACTION_REREGISTER 또는 WMIREG_ACTION_UPDATE 사용하여 IoWMIRegistrationControl 을 호출한 후 IRP를 보냅니다. WMI는 드라이버를 대신하여 IRP_MN_REGINFOIRP_MN_REGINFO_EX 간의 차이점을 투명하게 처리합니다.

WMI는 드라이버에서 추가 정보가 필요하지 않으므로 드라이버가 WMIREG_ACTION_DEREGISTERIoWMIRegistrationControl 을 호출한 후에는 IRP_MN_REGINFO 또는 IRP_MN_REGINFO_EX 요청을 보내지 않습니다. 드라이버는 일반적으로 IRP_MN_REMOVE_DEVICE 요청에 대한 응답으로 블록을 등록 취소합니다.

드라이버는 WmiSystemControl에 전달하는 WMILIB_CONTEXT 구조에서 개별 블록에 대한 신규 또는 업데이트된 등록 정보를 제공하거나 제거할 블록을 나타냅니다. 드라이버의 레지스트리 경로와 MOF 리소스 이름을 설정하는 초기 호출 후 드라이버의 DpWmiQueryReginfo 루틴은 모든 드라이버 블록에 공통 플래그를 변경하거나, instance 이름을 생성하는 데 사용되는 다른 기본 이름 문자열을 제공하거나, 문자열에서 PDO의 디바이스 instance 경로로 instance 이름에 대한 기초를 변경할 수 있습니다.

드라이버는 STATUS_PENDING 반환하거나 요청을 차단해서는 안 합니다. 드라이버는 DpWmiQueryReginfo 루틴에서 WmiCompleteRequest를 호출하거나 WmiSystemControl이 반환된 후 IoCompleteRequest를 호출하여 요청을 완료해서는 안 됩니다.

이 루틴은 페이지 가능할 수 있습니다.

이 루틴을 구현하는 방법에 대한 자세한 내용은 WMI IRP 처리를 위해 WmiSystemControl 호출을 참조하세요.