IWbemServices：:P utInstanceAsync 方法 (wbemcli.h)
IWbemServices：:P utInstanceAsync 方法异步创建或更新现有类的实例。 更新确认或错误报告是通过调用方实现的 IWbemObjectSink 接口提供的。
语法
HRESULT PutInstanceAsync(
[in] IWbemClassObject *pInst,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
参数
[in] pInst
指向要写入 WMI 存储库的实例的指针。 调用方无法在完成此调用时对引用计数做出假设。
[in] lFlags
指定调用方是否希望在实例当前不存在时创建实例。
实现实例提供程序时，可以通过返回WBEM_E_PROVIDER_NOT_CAPABLE选择支持 lFlags 中有限数量的 标志。
此属性可以具有以下一个或多个值。
WBEM_FLAG_CREATE_OR_UPDATE
如果此实例不存在，则此标志会导致创建该实例;如果此实例已存在，则将被覆盖。
WBEM_FLAG_UPDATE_ONLY
汇报现有实例。
WBEM_FLAG_CREATE_ONLY
此标志仅用于创建实例。 如果类已存在，则调用失败。
WBEM_FLAG_SEND_STATUS
此标志向 Windows 管理注册通过 IWbemObjectSink：：SetStatus 的客户端实现接收中间状态报告的请求。 提供程序实现必须支持此标志的中间状态报告才能更改行为。
WBEM_FLAG_USE_AMENDED_QUALIFIERS
如果设置了此标志，WMI 不会存储任何具有 修改 后的风格的限定符。 如果未设置此标志，则假定此对象未本地化，并且所有限定符都存储在此实例中。
[in] pCtx
描述客户端是请求部分实例更新还是完整实例更新的指针。 部分实例更新修改实例属性的子集。 相反，完整实例更新会修改所有属性。 如果 为 NULL，则此参数指示调用方应用程序正在请求完整实例更新。 否则，这是指向生成类实例的动态类提供程序所需的 IWbemContext 对象的指针。 有关此参数的详细信息，请参阅 调用 WMI。
[in] pResponseHandler
指向 调用方 IWbemObjectSink 实现的指针。 此处理程序在使用 IWbemObjectSink：：SetStatus 方法可用时接收此调用的状态。 如果返回任何错误代码，则不使用提供的 IWbemObjectSink 指针。 如果返回 WBEM_S_NO_ERROR ，则调用用户的 IWbemObjectSink 实现来指示操作的结果。 Windows 管理仅在返回WBEM_S_NO_ERROR时对指针调用 AddRef。 在错误代码返回的情况下，引用计数与输入时相同。 有关如何进行异步调用的详细信息，请参阅 调用方法。
返回值
此方法返回指示方法调用状态的 HRESULT。 以下列表列出了 HRESULT 中包含的值。
请注意，如果 PutInstanceAsync 返回 WBEM_S_NO_ERROR，则 WMI 将等待响应处理程序的 SetStatus 方法的结果。 WMI 将无限期地等待本地连接或远程连接超时。
如果网络问题导致你失去与 Windows 管理的远程连接，也可能会返回特定于 COM 的错误代码。
注解
调用 PutInstanceAsync 的客户端必须始终期望使用其 IWbemObjectSink：：Indicate 方法报告调用结果。
当 pInst 指向的实例属于派生自其他类的类时， PutInstanceAsync 的成功取决于负责父类的提供程序是否成功。 例如，如果 pInst 属于 ClassB，而 ClassB 派生自 ClassA，则对由 ClassA 提供程序实现的 PutInstanceAsync 方法的调用必须成功，ClassB 上的更新操作才能成功。 有关详细信息，请参阅 IWbemServices：:P utInstance 中的备注。
实现实例提供程序时，如果实例的键属性设置为 NULL， PutInstanceAsync 应选择保证在 类中唯一的值。 当 WMI 处理使用 NULL 键属性更新实例的请求时，它会在内部生成 GUID 并将其分配给密钥属性。 此外，当正在更新的实例属于子类时，操作的成功取决于对负责层次结构中较高类的每个提供程序的 PutInstanceAsync 调用是否成功。 在确定所有其他提供程序都成功之前，请不要返回 WBEM_S_NO_ERROR 。 有关详细信息，请参阅 IWbemServices：:P utInstance。
支持部分更新的实例提供程序必须检查是否存在__PUT_EXTENSIONS上下文值。 系统上下文值是由 WMI 定义的具有特定含义的值，由客户端应用程序设置，并受实例提供程序支持。 IWbemContext 接口提供对系统上下文值和其他特定于提供程序的上下文值的访问权限。 以下列表列出了支持部分实例更新操作的上下文值。
调用 IWbemObjectSink：：SetStatus 方法以指示结果集的结束。 也可以调用它，而无需对 IWbemObjectSink：：指示 是否发生错误条件。
由于回调可能不会在客户端要求的相同身份验证级别返回，因此建议使用半同步通信而不是异步通信。 如果需要异步通信，请参阅 调用方法。
有关以半同步方式使用方法的详细信息，请参阅 IWbemServices：:P utInstance 和 调用方法。
| 系统上下文值 | 说明 |
|---|---|
|
__PUT_EXTENSIONS
(VT_BOOL) |
客户端应用程序已设置一个或多个其他系统上下文值，以提供有关更新操作的详细信息。 |
|
__PUT_EXT_STRICT_NULLS
(VT_BOOL) |
实例提供程序必须强制属性设置在适当时 VT_NULL ，并在失败时引发错误。 |
|
__PUT_EXT_PROPERTIES
(VT_ARRAY | VT_BSTR) |
包含要更新的属性的列表。 实例提供程序应忽略所有其他属性。 |
|
__PUT_EXT_ATOMIC
(VT_BOOL) |
所有更新都必须成功，或者实例提供程序必须还原回来。 不能有部分成功。 |
实现实例提供程序时，应按以下方式响应 pCtx 中的 NULL 属性：
- 如果属性类型 VT_NULL，则提供程序可以忽略属性而不进行更改或使操作失败。
- 如果属性类型未 VT_NULL 且属性无法更新，则提供程序应返回错误，因为提供程序必须使用新值更新属性。
实现异步操作时，在释放对 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) |
| Library | 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 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈