描述

 

IWbemServices-PutInstanceAsync方法异步地创建或更新现有类的实例。通过由呼叫者实现的IWbemObjectSink接口提供更新确认或错误报告。

 

C++ 语法

 

 

PowerBASIC 语法

 

 

参数

 

pInst

 

指向要写入WMI存储库的实例的指针。呼叫者在完成此呼叫时不能对参考计数作出假设。

 

lFlags

 

指定调用者是否要在实例当前不存在的情况下创建实例。

 

实现实例提供者时，您可以选择通过返回WBEM_E_PROVIDER_NOT_CAPABLE来支持lFlags中有限数量的标志。

 

此属性可以具有以下一个或多个值。

 

 

pCtx

 

描述客户端是否请求部分实例更新或全实例更新的指针。部分实例更新修改实例属性的子集。相反，全实例更新会修改所有属性。如果为NULL，则此参数指示调用者应用程序正在请求全实例更新。否则，这是指向生成类实例的动态类提供者所需的IWbemContext对象的指针。有关此参数的更多信息，请参阅拨打电话给WMI.

 

pResponseHandler

 

指向呼叫者执行IWbemObjectSink的指针。该处理程序在使用IWbemObjectSink.SetStatus方法可用时收到此呼叫的状态。如果返回任何错误代码，则不使用提供的IWbemObjectSink指针。如果返回WBEM_S_NO_ERROR，则调用用户的IWbemObjectSink实现来指示操作的结果。如果WBEM_S_NO_ERROR返回，Windows Management只会调用该指针的AddRef.在错误代码返回的情况下，引用计数与输入相同。有关如何进行异步调用的更多信息，请参阅调用方法.

 

返回值

 

此方法返回一个HRESULT，指示方法调用的状态。下表列出了HRESULT中包含的值。

 

请注意，如果PutInstanceAsync返回WBEM_S_NO_ERROR，则WMI将等待来自响应处理程序的SetStatus方法的结果。WMI在本地连接上无限期等待，或者直到发生远程连接超时。

 

如果网络问题导致您失去与Windows Management的远程连接，也可能会返回COM特定的错误代码。

 

 

示例代码

 

以下示例介绍如何构造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;  

}

 

备注

 

调用PutInstanceAsync的客户端必须始终期望使用其IWbemObjectSink.Indicate方法报告调用的结果。

 

当pInst指向的实例属于从其他类派生的类时，PutInstanceAsync的成功取决于负责父类的提供者的成功。例如，如果pInst属于ClassB和ClassB??派生自ClassA，由ClassA提供商实施的PutInstanceAsync方法的调用必须成功，否则ClassB上的更新操作将成功。有关详细信息，请参阅IWbemServices.PutInstance中的注释。

 

实现实例提供者时，如果实例的key属性设置为NULL，则PutInstanceAsync应该选择一个保证在类中唯一的值。当WMI服务使用NULL键属性更新实例的请求时，它会内部生成GUID并将其分配给key属性。此外，当正在更新的实例属于子类时，操作的成功取决于对层级中较高级别的每个提供者负责的PutInstanceAsync调用的成功。不要返回WBEM_S_NO_ERROR，直到您确定所有其他提供程序成功。有关详细信息，请参阅IWbemServices.PutInstance.

 

支持部分更新的实例提供者必须检查是否存在__PUT_EXTENSIONS上下文值。系统上下文值是由WMI定义的具有特定含义的值，由客户端应用程序设置，并由实例提供者支持。IWbemContext接口提供对系统上下文值和其他提供者特定上下文值的访问。下表列出了支持部分实例更新操作的上下文值。

 

调用IWbemObjectSink.SetStatus方法来指示结果集的结束。如果出现错误条件，也可以调用IWbemObjectSink.Indicate而不进行任何调用。

 

因为回调可能不会以与客户端所需的相同的身份验证级别返回，所以建议您使用半异步而不是异步通信。如果需要异步通信，请参阅调用方法.

 

有关半异步使用方法的更多信息，请参阅IWbemServices.PutInstance和调用方法.

 

 

在实现实例提供程序时，您应该按照以下方式响应pCtx中的NULL属性：

 

 

 

如果pCtx不为NULL且指向有效的上下文信息，则呼叫者应用程序正在请求部分实例更新。如前所述，不支持部分实例更新的实例提供程序将通过返回WBEM_E_PROVIDER_NOT_CAPABLE来失败操作。

 

要求