IWbemServices::CreateInstanceEnumAsync 메서드(wbemcli.h)

아티클
08/27/2023

IWbemServices::CreateInstanceEnumAsync 메서드는 사용자가 지정한 선택 조건에 따라 지정된 클래스의 인스턴스를 비동기적으로 반환하는 열거자를 만듭니다. 이 메서드는 간단한 WQL(WMI 쿼리 언어) 쿼리를 지원합니다. IWbemServices::ExecQueryAsync 메서드를 사용하여 더 복잡한 쿼리를 처리할 수 있습니다.

구문

HRESULT CreateInstanceEnumAsync(
  [in] const BSTR      strFilter,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

매개 변수

[in] strFilter

인스턴스가 필요한 클래스의 이름을 포함하는 유효한 BSTR 입니다. 이 매개 변수는 NULL일 수 없습니다.

[in] lFlags

이 매개 변수는 다음 값 중 하나일 수 있습니다.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

이 플래그가 설정되면 WMI(Windows Management Instrumentation)는 현재 연결 로캘의 지역화된 네임스페이스에 저장된 수정된 한정자를 검색합니다. 설정하지 않으면 직접 네임스페이스에 저장된 한정자만 검색됩니다.

WBEM_FLAG_DEEP

이 플래그는 열거형에 이 인스턴스와 계층의 모든 하위 클래스를 포함하도록 강제합니다.

WBEM_FLAG_SHALLOW

이 플래그는 이 클래스에서 찾을 수 없는 속성을 제공하는 서브클래스의 모든 인스턴스를 제외하고 이 클래스의 순수 인스턴스만 포함하도록 열거형을 강제로 적용합니다.

WBEM_FLAG_SEND_STATUS

이 플래그는 IWbemObjectSink::SetStatus의 클라이언트 구현을 통해 중간 상태 보고서를 수신하라는 요청을 Windows Management에 등록합니다. 공급자 구현은 동작을 변경하려면 이 플래그에 대한 중간 상태 보고를 지원해야 합니다.

WBEM_FLAG_BIDIRECTIONAL

이 플래그를 사용하면 클라이언트가 열거자를 해제할 때까지 Windows Management에서 열거형 개체에 대한 포인터를 유지합니다.

WBEM_FLAG_DIRECT_READ

이 플래그는 부모 클래스 또는 서브클래스에 관계없이 지정된 클래스에 대한 공급자에 직접 액세스합니다.

[in] pCtx

일반적으로 NULL입니다. 그렇지 않으면 요청된 인스턴스를 반환하는 공급자가 사용할 수 있는 IWbemContext 개체에 대한 포인터입니다. 컨텍스트 개체의 값은 해당 공급자에 대한 설명서에 지정해야 합니다. 자세한 내용은 WMI 호출을 참조하세요.

[in] pResponseHandler

호출자의 IWbemObjectSink 구현에 대한 포인터입니다. 이 처리기는 개체를 사용할 수 있게 되면 수신합니다. 오류 코드가 반환되면 제공된 IWbemObjectSink 포인터가 사용되지 않습니다. WBEM_S_NO_ERROR 반환되면 작업의 결과를 나타내기 위해 사용자의 IWbemObjectSink 구현이 호출됩니다. Windows Management는 WBEM_S_NO_ERROR 반환되는 경우 포인터에서만 AddRef를 호출합니다. 오류 코드가 반환되는 경우 참조 수는 항목에서와 동일합니다. 자세한 내용은 메서드 호출을 참조하세요.

반환 값

이 메서드는 메서드 호출의 상태를 나타내는 HRESULT를 반환합니다. 다음 목록에는 HRESULT에 포함된 값이 나열되어 있습니다.

오류가 발생하면 COM 함수 GetErrorInfo에서 자세한 정보를 얻을 수 있습니다.

네트워크 문제로 인해 Windows Management에 대한 원격 연결이 끊어지는 경우에도 COM 관련 오류 코드가 반환될 수 있습니다.

instance 공급자는 CreateInstanceEnumAsync의 반환 코드 또는 pResponseHandler를 통해 만들어진 SetStatus 호출을 통해 성공 또는 실패를 보고할 수 있습니다. SetStatus를 호출하도록 선택하는 경우 pResponseHandler를 통해 전송된 반환 코드가 우선합니다.

CreateInstanceEnumAsync가 WBEM_S_NO_ERROR 반환하는 경우 WMI는 응답 처리기의 SetStatus 메서드에서 결과를 기다립니다. WMI는 로컬 연결에서 또는 원격 연결 제한 시간이 발생할 때까지 무기한 대기합니다.

설명

결과 집합의 끝을 나타내기 위해 IWbemObjectSink::SetStatus 메서드가 호출됩니다. IWbemObjectSink::오류 조건이 발생하는지 여부를 나타내기 위한 중간 호출 없이 호출될 수도 있습니다.

콜백은 클라이언트가 요구하는 것과 동일한 인증 수준에서 반환되지 않을 수 있으므로 비동기 통신 대신 반동기를 사용하는 것이 좋습니다.

자세한 내용은 IWbemServices::CreateInstanceEnum 및 메서드 호출을 참조하세요.

예제

다음 예제에서는 CreateInstanceEnumAsync를 구현하는 방법을 보여줍니다.

#define NUM_OF_INSTANCES 3

HRESULT CStdProvider::CreateInstanceEnumAsync( 
            /* [in] */ BSTR strClass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0; 
    IWbemClassObject *pNextInst = 0;

    // Assume there is an IWbemServices pointer available to
    // retrieve the class definition.
    HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

    // Now loop through the private source and create each instance.
    for (int i = 0; i < NUM_OF_INSTANCES; i++)
    {
         // Prepare an empty object to receive the class definition.
         pClass->SpawnInstance(0, &pNextInst);

         // Create the instance.
         // For example, create the instance in a
         // FillInst method you implement:
         /*FillInst(pNextInst);*/

         // Deliver the class to WMI.
         pResponseHandler->Indicate(1, &pNextInst);
         pNextInst->Release();
    }

    // Send a finish message to WMI.
    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);

    // Free memory resources.
    SysFreeString(strClass);
    pClass->Release();
    m_pSvc->Release();

    return WBEM_S_NO_ERROR;
}

이전 예제에서 instance 공급자는 WMI에서 스레드를 획득하여 필요한 작업을 수행합니다. 싱크 AddRef 메서드를 호출하고 결과 집합에서 개체를 배달하기 위한 다른 스레드를 만들 수 있습니다. 다른 스레드를 만들면 현재 스레드가 스레드 풀을 고갈하지 않고 WMI로 돌아갈 수 있습니다. 공급자가 이중 스레드 디자인에 대해 단일 스레드 디자인을 선택하는지 여부는 공급자가 WMI 스레드를 사용할 계획에 따라 달라집니다. 고정된 규칙이 없습니다. 실험은 디자인이 WMI 성능에 미치는 영향을 결정하는 데 도움이 될 수 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista
지원되는 최소 서버	Windows Server 2008
대상 플랫폼	Windows
헤더	wbemcli.h(Wbemidl.h 포함)
라이브러리	Wbemuuid.lib
DLL	Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll

추가 정보

메서드 호출

IWbemServices

IWbemServices::CreateInstanceEnum