WMI_QUERY_DATABLOCK_CALLBACK 콜백 함수(wmilib.h)

아티클
02/07/2025

DpWmiQueryDataBlock 루틴은 단일 인스턴스 또는 데이터 블록의 모든 인스턴스를 반환합니다. 이 루틴은 필수입니다.

통사론

WMI_QUERY_DATABLOCK_CALLBACK WmiQueryDatablockCallback;

NTSTATUS WmiQueryDatablockCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG InstanceCount,
  [in, out] PULONG InstanceLengthArray,
  [in]      ULONG BufferAvail,
  [out]     PUCHAR Buffer
)
{...}

매개 변수

[in] DeviceObject

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

[in] Irp

IRP에 대한 포인터입니다.

[in] GuidIndex

WmiSystemControl전달된 WMILIB_CONTEXT 구조에서 드라이버가 제공한 GUID 목록에 0부터 시작하는 인덱스를 제공하여 데이터 블록을 지정합니다.

[in] InstanceIndex

DpWmiQueryDataBlockIRP_MN_QUERY_SINGLE_INSTANCE 요청에 대한 응답으로 호출되는 경우 InstanceIndex 쿼리할 지정된 데이터 블록의 인스턴스를 나타내는 0부터 시작하는 인덱스를 지정합니다. IRP_MN_QUERY_ALL_DATA 요청에 대한 응답으로 DpWmiQueryDataBlock 호출되면 InstanceIndex 0입니다.

[in] InstanceCount

DpWmiQueryDataBlockIRP_MN_QUERY_SINGLE_INSTANCE 요청에 대한 응답으로 호출되는 경우 InstanceCount 1입니다. IRP_MN_QUERY_ALL_DATA 요청에 대한 응답으로 DpWmiQueryDataBlock 호출되는 경우 InstanceCount 반환할 인스턴스 수입니다.

[in, out] InstanceLengthArray

호출자가 제공한 InstanceCount크기의 ULONG 요소 배열에 대한 포인터입니다. 드라이버는 반환된 각 인스턴스의 길이를 나타내기 위해 각 배열 요소를 채웁니다. BufferAvail 0이면 InstanceLengthArray NULL .

[in] BufferAvail

Buffer버퍼에서 데이터를 수신하는 데 사용할 수 있는 최대 바이트 수를 지정합니다. 이 값이 0이면 호출자가 WmiCompleteRequest호출에 필요한 버퍼 크기를 지정하도록 요청합니다. 자세한 내용은 설명 섹션을 참조하세요.

[out] Buffer

인스턴스 데이터를 받을 버퍼에 대한 포인터입니다. 버퍼가 모든 데이터를 수신할 수 있을 만큼 큰 경우 드라이버는 각 인스턴스가 8 바이트 경계에 정렬된 상태에서 인스턴스 데이터를 버퍼에 씁니다. 버퍼가 너무 작아서 모든 데이터를 수신할 수 없는 경우 드라이버는 BufferUsed 필요한 크기로 설정된 WmiCompleteRequest 호출합니다.

반환 값

DpWmiQueryDataBlock STATUS_SUCCESS 또는 다음과 같은 오류 상태를 반환합니다.

드라이버가 요청을 즉시 완료할 수 없는 경우 STATUS_PENDING 반환할 수 있습니다.

발언

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

드라이버는 모든 입력 인수의 유효성을 검사해야 합니다. 특히 드라이버는 다음을 수행해야 합니다.

WMILIB_CONTEXT 구조체의 GuidCount 멤버에 따라 GuidIndex 값이 0과 GuidCount-1 사이인지 확인합니다.
드라이버가 제거를 위해 지정된 데이터 블록에 플래그를 지정하지 않은지 확인합니다. 드라이버가 최근에 WMILIB_CONTEXT 구조에 포함된 WMIGUIDREGINFO 구조체에 WMIREG_FLAG_REMOVE_GUID 플래그를 지정한 경우 제거가 발생하기 전에 쿼리가 도착할 수 있습니다.
InstanceIndex 및 InstanceCount 값을 함께 지정하여 드라이버가 데이터 블록에 대해 지원하는 범위 내에 있는 여러 데이터 블록 인스턴스를 지정합니다. InstanceIndex 0이 아니면 InstanceCount 1이어야 합니다. InstanceIndex 0이면 InstanceCount 지원되는 인스턴스 수보다 크지 않아야 합니다.
Buffer 및 BufferAvail 설명한 버퍼가 데이터 블록의 요청된 모든 인스턴스를 저장할 수 있을 만큼 큰지 확인합니다. 각 인스턴스는 8바이트 경계에서 시작해야 하며 각 인스턴스 내의 데이터 항목 사이에 추가 패딩이 있을 수 있습니다.

버퍼에 인스턴스 데이터를 쓴 후 드라이버는 WmiCompleteRequest 호출하여 요청을 완료합니다. Buffer 및 BufferAvail 설명된 버퍼가 0이거나 요청된 모든 데이터를 수신하기에는 너무 작으면 WmiCompleteRequest 호출은 Status 매개 변수의 STATUS_BUFFER_TOO_SMALL BufferUsed 매개 변수에 필요한 버퍼 크기를 지정해야 합니다.

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

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