WMI_QUERY_DATABLOCK_CALLBACK 콜백 함수(wmilib.h)

아티클
08/08/2023

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

구문

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

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

[in] InstanceCount

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

[in, out] InstanceLengthArray

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

[in] BufferAvail

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

[out] Buffer

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

반환 값

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

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

설명

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

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

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에서 설명하는 버퍼가 데이터 블록의 요청된 모든 인스턴스를 저장할 수 있을 만큼 큰지 확인합니다. 각 instance 8바이트 경계에서 시작해야 하며 각 instance 내의 데이터 항목 사이에 추가 패딩이 있을 수 있습니다.

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

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

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