WdfWmiInstanceCreate 함수(wdfwmi.h)

아티클
08/08/2023

[KMDF에만 적용]

WdfWmiInstanceCreate 메서드는 WMI 데이터 공급자의 instance 나타내는 WMI instance 개체를 만듭니다.

구문

NTSTATUS WdfWmiInstanceCreate(
  [in]            WDFDEVICE                Device,
  [in]            PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES   InstanceAttributes,
  [out, optional] WDFWMIINSTANCE           *Instance
);

매개 변수

[in] Device

instance 만드는 디바이스를 나타내는 프레임워크 디바이스 개체에 대한 핸들입니다. 디바이스 개체는 컨트롤 디바이스 개체일 수 없습니다.

[in] InstanceConfig

WMI 데이터 공급자의 instance 대한 구성 정보를 포함하는 호출자 초기화된 WDF_WMI_INSTANCE_CONFIG 구조체에 대한 포인터입니다.

[in, optional] InstanceAttributes

새 WMI instance 개체에 대한 드라이버 제공 개체 특성을 포함하는 호출자가 할당한 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 구조체의 ParentObject 멤버는 NULL이어야 합니다. 이 매개 변수는 선택 사항이며 WDF_NO_OBJECT_ATTRIBUTES 수 있습니다.

[out, optional] Instance

새 WMI instance 개체에 대한 핸들을 수신하는 위치에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

반환 값

WdfWmiInstanceCreate 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 감지되었습니다.
STATUS_INFO_LENGTH_MISMATCH	InstanceConfig 매개 변수가 가리키는 WDF_WMI_INSTANCE_CONFIG 구조체의 크기가 잘못되었습니다.
STATUS_INSUFFICIENT_RESOURCES	메모리가 부족했습니다.
STATUS_INTEGER_OVERFLOW	드라이버는 WDF_WMI_INSTANCE_CONFIG 구조체의 UseContextForQuery 멤버를 TRUE로 설정했지만 InstanceAttributes 매개 변수의 WDF_OBJECT_ATTRIBUTES 구조에서 ULONG_MAX 보다 큰 컨텍스트 공간 크기를 지정했습니다.

WdfWmiInstanceCreate 메서드가 반환할 수 있는 다른 반환 값 목록은 프레임워크 개체 만들기 오류를 참조하세요.

이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.

드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.

설명

드라이버가 공급자의 여러 인스턴스를 만드는 경우 드라이버는 WdfWmiInstanceCreate를 호출하기 전에 WdfWmiProviderCreate를 호출하여 공급자 개체를 만들어야 합니다. 드라이버는 WDF_WMI_INSTANCE_CONFIG 구조체에 핸들을 배치하여 공급자 개체의 핸들을 WdfWmiInstanceCreate에 전달합니다. 드라이버가 공급자 개체 핸들을 제공하는 경우 Device 매개 변수는 사용되지 않으며 NULL일 수 있습니다.

드라이버가 공급자의 단일 instance 만드는 경우 WdfWmiInstanceCreate를 호출하기 전에 WdfWmiInstanceCreate를 호출할 필요가 없습니다. 이 경우 WdfWmiInstanceCreate 는 WMI 공급자 개체도 만듭니다. 따라서 드라이버의 WDF_WMI_INSTANCE_CONFIG 구조에는 WMI 데이터 공급자를 설명하는 WDF_WMI_PROVIDER_CONFIG 구조체에 대한 포인터가 포함되어야 합니다.

프레임워크는 WMI에 드라이버의 PDO(물리적 디바이스 개체)의 디바이스 instance ID에서 애플리케이션에서 사용할 수 있는 동적 instance 이름을 만들도록 지시합니다. (프레임워크는 WDM(Windows 드라이버 모델) 드라이버가 IRP_MN_REGINFO 또는 IRP_MN_REGINFO_EX 구조에 설정한 정적 instance 이름을 지원하지 않습니다.

WMI instance 개체의 부모는 WMI 공급자 개체입니다. 드라이버는 이 부모를 변경할 수 없으며 ParentObject 멤버 또는 WDF_OBJECT_ATTRIBUTES 구조체는 NULL이어야 합니다.

드라이버가 WdfWmiInstanceCreate를 호출한 후 WdfWmiInstanceGetProvider 를 호출하여 부모 공급자 개체에 대한 핸들을 가져오고 WdfWmiInstanceGetDevice 를 호출하여 공급자의 디바이스에 대한 핸들을 가져올 수 있습니다.

WdfWmiInstanceCreate 메서드에 대한 자세한 내용은 Framework-Based 드라이버에서 WMI 지원을 참조하세요.

InstanceConfig가 가리키는 WDF_WMI_INSTANCE_CONFIG 구조체의 Register 멤버가 TRUE이면 WdfWmiInstanceCreate는 이 메서드가 IRQL = instance PASSIVE_LEVEL 호출되고 IRQL > PASSIVE_LEVEL 호출되는 경우 비동기적으로 공급자를 동기적으로 등록합니다(즉, 반환하기 전에).

예제

다음 코드 예제는 PCIDRV 샘플 드라이버에서 가져옵니다. 이 예제에서는 디바이스에 대한 MOF 리소스 이름을 등록하고, WDF_WMI_PROVIDER_CONFIG 구조체와 WDF_WMI_INSTANCE_CONFIG 구조를 초기화하고, WdfWmiInstanceCreate를 호출합니다.

NTSTATUS
PciDrvWmiRegistration(
    WDFDEVICE  Device
    )
{
    WDF_WMI_PROVIDER_CONFIG  providerConfig;
    WDF_WMI_INSTANCE_CONFIG  instanceConfig;
    NTSTATUS  status;
    DECLARE_CONST_UNICODE_STRING(mofRsrcName, MOFRESOURCENAME);

    status = WdfDeviceAssignMofResourceName(
                                            Device,
                                            &mofRsrcName
                                            );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    WDF_WMI_PROVIDER_CONFIG_INIT(
                                 &providerConfig,
                                 &PCIDRV_WMI_STD_DATA_GUID
                                 );
    providerConfig.MinInstanceBufferSize = sizeof(PCIDRV_WMI_STD_DATA);

    WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG(
                                                 &instanceConfig,
                                                 &providerConfig
                                                 );
    instanceConfig.Register = TRUE;
    instanceConfig.EvtWmiInstanceQueryInstance = EvtWmiDeviceInfoQueryInstance;
    instanceConfig.EvtWmiInstanceSetInstance = EvtWmiDeviceInfoSetInstance;

    status = WdfWmiInstanceCreate(
                                  Device,
                                  &instanceConfig,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  WDF_NO_HANDLE
                                  );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return status;
}

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
머리글	wdfwmi.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(프레임워크 라이브러리 버전 관리 참조)
IRQL	<=DISPATCH_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)