IWbemServices::P utInstanceAsync 메서드(wbemcli.h)

  • 아티클

IWbemServices::P utInstanceAsync 메서드는 기존 클래스의 instance 비동기적으로 만들거나 업데이트합니다. 업데이트 확인 또는 오류 보고는 호출자가 구현한 IWbemObjectSink 인터페이스를 통해 제공됩니다.

구문

HRESULT PutInstanceAsync(
  [in] IWbemClassObject *pInst,
  [in] long             lFlags,
  [in] IWbemContext     *pCtx,
  [in] IWbemObjectSink  *pResponseHandler
);

매개 변수

[in] pInst

WMI 리포지토리에 쓸 instance 대한 포인터입니다. 호출자는 이 호출이 완료될 때 참조 횟수에 대해 가정할 수 없습니다.

[in] lFlags

instance 현재 없는 경우 호출자가 instance 만들 것인지 여부를 지정합니다.

instance 공급자를 구현할 때 WBEM_E_PROVIDER_NOT_CAPABLE 반환하여 lFlags의 제한된 수의 플래그를 지원하도록 선택할 수 있습니다.

이 속성에는 다음 값 중 하나 이상이 있을 수 있습니다.

WBEM_FLAG_CREATE_OR_UPDATE

이 플래그는 존재하지 않는 경우 이 instance 만들거나 이미 있는 경우 덮어씁니다.

WBEM_FLAG_UPDATE_ONLY

기존 instance 업데이트.

WBEM_FLAG_CREATE_ONLY

이 플래그는 instance 만들기 전용입니다. 클래스가 이미 있는 경우 호출이 실패합니다.

WBEM_FLAG_SEND_STATUS

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

WBEM_FLAG_USE_AMENDED_QUALIFIERS

이 플래그가 설정된 경우 WMI는 수정된 버전이 있는 한정자를 저장하지 않습니다. 이 플래그가 설정되지 않은 경우 이 개체가 지역화되지 않고 모든 한정자는 이 instance 함께 저장됩니다.

[in] pCtx

클라이언트가 부분 instance 업데이트 또는 전체 instance 업데이트를 요청하는지 여부를 설명하는 포인터입니다. 부분 instance 업데이트는 instance 속성의 하위 집합을 수정합니다. 반면, 전체 instance 업데이트는 모든 속성을 수정합니다. NULL인 경우 이 매개 변수는 호출자 애플리케이션이 전체 instance 업데이트를 요청하고 있음을 나타냅니다. 그렇지 않으면 클래스 인스턴스를 생성하는 동적 클래스 공급자에 필요한 IWbemContext 개체에 대한 포인터입니다. 이 매개 변수에 대한 자세한 내용은 WMI 호출을 참조하세요.

[in] pResponseHandler

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

반환 값

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

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

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

설명

PutInstanceAsync를 호출하는 클라이언트는 항상 IWbemObjectSink::Indicate 메서드를 사용하여 호출 결과를 보고해야 합니다.

pInst에서 가리키는 instance 다른 클래스에서 파생된 클래스에 속하는 경우 PutInstanceAsync의 성공은 부모 클래스를 담당하는 공급자의 성공에 따라 달라집니다. 예를 들어 pInst가 ClassB에 속하고 ClassB가 ClassA에서 파생되는 경우 ClassA에 대해 공급자가 구현한 PutInstanceAsync 메서드에 대한 호출이 성공해야 ClassB의 업데이트 작업이 성공합니다. 자세한 내용은 IWbemServices::P utInstance의 설명을 참조하세요.

instance 공급자를 구현할 때 instance 키 속성이 NULL로 설정된 경우 PutInstanceAsync는 클래스 내에서 고유하도록 보장되는 값을 선택해야 합니다. WMI는 NULL 키 속성으로 instance 업데이트하는 요청을 서비스하는 경우 내부적으로 GUID를 생성하고 키 속성에 할당합니다. 또한 업데이트되는 instance 자식 클래스에 속하는 경우 작업의 성공은 계층 구조에서 더 높은 클래스를 담당하는 각 공급자에 대한 PutInstanceAsync 호출의 성공에 따라 달라집니다. 다른 모든 공급자가 성공했는지 확인할 때까지 WBEM_S_NO_ERROR 반환하지 마세요. 자세한 내용은 IWbemServices::P utInstance를 참조하세요.

부분 업데이트를 지원하는 인스턴스 공급자는 __PUT_EXTENSIONS 컨텍스트 값이 있는지 검사 합니다. 시스템 컨텍스트 값은 특정 의미를 갖도록 WMI에서 정의한 값이며 클라이언트 애플리케이션에서 설정되며 instance 공급자에서 지원됩니다. IWbemContext 인터페이스는 시스템 컨텍스트 값 및 기타 공급자별 컨텍스트 값에 대한 액세스를 제공합니다. 다음 목록에는 부분 instance 업데이트 작업을 지원하는 컨텍스트 값이 나열되어 있습니다.

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

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

메서드를 반동적으로 사용하는 방법에 대한 자세한 내용은 IWbemServices::P utInstance 및 메서드 호출을 참조하세요.

시스템 컨텍스트 값 Description
__PUT_EXTENSIONS

(VT_BOOL)

 클라이언트 애플리케이션은 업데이트 작업에 대한 자세한 정보를 제공하기 위해 하나 이상의 다른 시스템 컨텍스트 값을 설정했습니다.
__PUT_EXT_STRICT_NULLS

(VT_BOOL)

 instance 공급자는 적절한 경우 속성 설정을 강제로 VT_NULL 오류 발생 시 오류를 발생시켜야 합니다.
__PUT_EXT_PROPERTIES

(VT_ARRAY | VT_BSTR)

 업데이트할 속성의 목록을 포함합니다. instance 공급자는 다른 모든 속성을 무시해야 합니다.
__PUT_EXT_ATOMIC

(VT_BOOL)

 모든 업데이트가 성공하거나 instance 공급자가 다시 되돌리기 합니다. 부분적인 성공은 있을 수 없습니다.
 

instance 공급자를 구현하는 경우 다음과 같은 방식으로 pCtx의 NULL 속성에 응답해야 합니다.

  • 속성 형식이 VT_NULL 경우 공급자는 변경하지 않고 속성을 무시하거나 작업에 실패할 수 있습니다.
  • 속성 형식이 VT_NULL 않고 속성을 업데이트할 수 없는 경우 공급자가 속성을 새 값으로 업데이트해야 하므로 공급자가 오류를 반환해야 합니다.
pCtx가 NULL이 아니고 유효한 컨텍스트 정보를 가리키는 경우 호출자 애플리케이션은 부분 instance 업데이트를 요청합니다. 이전과 마찬가지로 부분 instance 업데이트를 지원하지 않는 instance 공급자는 WBEM_E_PROVIDER_NOT_CAPABLE 반환하여 작업에 실패해야 합니다.

비동기 작업을 구현할 때 pResponseHandler에서 수행한 AddRef를 해제할 때까지 비동기 작업이 완료되지 않습니다. pResponseHander에서 SetStatus를 호출하는 경우에도 마찬가지입니다. pResponseHandler가 유출되면 동기화 또는 반 동기화 클라이언트도 완료되지 않고 구현에 따라 응답을 중지할 수 있습니다.

치명적인 경우에도 분리된 공급자에 대한 참조를 해제해야 합니다. 이는 동기화 및 반 동기화 사례에서 WMI 서비스가 pResponseHandler의 구현을 소유하기 때문입니다. 분리된 공급자의 프로세스가 종료되더라도 클라이언트는 여전히 응답하지 않습니다.

예제

다음 예제에서는 PutInstanceAsync를 구성하는 방법을 설명합니다.

HRESULT CStdProvider::PutInstanceAsync( 
            /* [in] */ IWbemClassObject __RPC_FAR *pInst,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
   // You must implement the InstanceIsValid method
   // to check to see if the instance in the pInst variable
   // is valid.
   if (InstanceIsValid(lFlags, pInst)) 
   {
       return WBEM_S_NO_ERROR;
   }

   return WBEM_E_PROVIDER_NOT_CAPABLE;   
}

요구 사항

   
지원되는 최소 클라이언트 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

추가 정보

메서드 호출

인스턴스 만들기

IWbemContext

IWbemServices