IWbemServices：:P utInstance 方法 (wbemcli.h)

项目
03/03/2024

IWbemServices：:P utInstance 方法创建或更新现有类的实例。将该实例写入 WMI 存储库。

语法

HRESULT PutInstance(
  [in]  IWbemClassObject *pInst,
  [in]  long             lFlags,
  [in]  IWbemContext     *pCtx,
  [out] IWbemCallResult  **ppCallResult
);

参数

[in] pInst

指向要写入的实例的指针。调用方无法在完成此调用时对引用计数做出假设。

[in] lFlags

可以设置以下一个或多个值。

WBEM_FLAG_CREATE_OR_UPDATE

如果实例不存在，则此标志会导致创建该实例;如果实例已存在，则将其覆盖。

WBEM_FLAG_UPDATE_ONLY

此标志会导致此调用更新。实例必须存在，这样调用才能成功。

WBEM_FLAG_CREATE_ONLY

此标志仅用于创建。如果实例已存在，则调用失败。

WBEM_FLAG_RETURN_IMMEDIATELY

此标志导致此为半同步调用。有关详细信息，请参阅调用方法。

WBEM_FLAG_USE_AMENDED_QUALIFIERS

如果设置了此标志，WMI 不会存储任何具有修改后的风格的限定符。如果未设置此标志，则假定此对象未本地化，并且所有限定符都存储在此实例中。

[in] pCtx

通常为 NULL，指示实例中的每个属性都将更新。否则，这是指向包含实例详细信息的 IWbemContext 对象的指针。上下文对象中的数据必须由负责实例的提供程序记录。非 NULLIWbemContext 对象可以指示是否存在对部分实例更新的支持。

有关如何支持完整和部分实例更新的详细信息，请参阅 IWbemServices：:P utInstanceAsync。有关请求完整或部分实例更新操作的详细信息，请参阅修改实例属性。

[out] ppCallResult

如果 为 NULL，则不使用此参数。如果 lFlags 参数包含 WBEM_FLAG_RETURN_IMMEDIATELY，此调用将立即返回 并WBEM_S_NO_ERROR。然后 ，ppCallResult 参数接收指向新的 IWbemCallResult 对象的指针，可以使用 IWbemCallResult：：GetCallStatus 轮询该对象以获取结果。

返回值

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

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

注解

应用程序和提供程序调用 PutInstance 来创建或更新现有类的实例。根据 pCtx 参数的设置方式，将更新实例的某些或所有属性。有关如何支持部分实例更新的详细信息，请参阅 IWbemServices：:P utInstanceAsync。有关请求部分实例更新的详细信息，请参阅修改实例属性。

PutInstance 方法仅支持创建实例和更新实例。它不支持移动实例。也就是说，调用方不能将 pInst 参数设置为具有与同级类中的另一个实例相同的键的实例。例如，假设 ClassA 是 ClassB 和 ClassC 的基类。 ClassA 类将 KeyProp 属性定义为其键，而 ClassB 具有将 KeyProp 设置为 1 的实例。若要创建将 KeyProp 设置为 1 的 ClassC 实例，应用程序必须先通过调用 DeleteInstance 删除 ClassB 实例，然后使用 PutInstance 保存 ClassC 实例。

当 pInst 指向的实例属于子类时，Windows 管理会调用负责从中派生子类的类的所有提供程序。所有这些提供程序都必须成功，原始 PutInstance 请求才能成功。首先调用支持层次结构中最顶端的类的提供程序。调用顺序与最顶层类的子类一起继续，并从上到下继续，直到 Windows 管理到达拥有 pInst 指向的实例的类的提供程序。

Windows 管理不会为实例的任何子类调用提供程序。因此，如果应用程序想要更改继承属性的值，则应用程序必须在子类的完整实例上调用 PutInstance ，而不是父类的相应实例。

当应用程序必须更新属于类层次结构的实例时， pInst 参数必须指向包含要修改的属性的实例。也就是说，假设有一个属于 ClassB 的目标实例。 ClassB 实例派生自 ClassA，而 ClassA 定义属性 PropA。如果应用程序想要更改 ClassB 实例中的 PropA 值，则必须将 pInst 设置为该实例，而不是 ClassA 的实例。

不允许对抽象类的实例调用 PutInstance 。

要求

要求	值
最低受支持的客户端	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