PutInstanceWmi 函数
创建或更新现有类的实例。 将该实例写入 WMI 存储库。
注意
此 API 仅供内部使用。 不应从开发人员代码中使用。
语法
HRESULT PutInstanceWmi (
[in] IWbemClassObject* pInst,
[in] long lFlags,
[in] IWbemContext* pCtx,
[out] IWbemCallResult** ppCallResult
);
参数
pInst
[in] 指向要写入的实例的指针。
lFlags
[in] 影响此函数的行为的标志组合。 以下值是在 WbemCli.h 头文件中定义，也可以将它们定义为代码中的常数：
| 常数 | Value | 说明 |
|---|---|---|
WBEM_FLAG_USE_AMENDED_QUALIFIERS |
0x20000 | 如果设置，WMI 不会存储任何带有修改后特色信息的限定符。 如果未设置，则假定此对象未本地化，并且所有限定符都与此实例一起存储。 |
WBEM_FLAG_CREATE_OR_UPDATE |
0 | 创建实例（如果该实例不存在）或覆盖它（如果它已存在）。 |
WBEM_FLAG_UPDATE_ONLY |
1 | 更新实例。 实例必须存在，这样调用才能成功。 |
WBEM_FLAG_CREATE_ONLY |
2 | 创建该实例。 如果实例已存在，则调用失败。 |
WBEM_FLAG_RETURN_IMMEDIATELY |
0x10 | 此标志会导致半同步调用。 |
pCtx
[in] 通常，此值为 null。 否则，它是一个指向 IWbemContext 实例的指针，提供请求的类的提供程序可使用该实例。
ppCallResult
[out] 如果为 null，则不使用此参数。 如果 lFlags 包含 WBEM_FLAG_RETURN_IMMEDIATELY，函数会立即返回并出现 WBEM_S_NO_ERROR。 ppCallResult 参数接收指向新的 IWbemCallResult 对象的指针。
返回值
此函数返回的以下值是在 WbemCli.h 头文件中定义的，你也可以在代码中将这些值定义为常数：
| 常数 | Value | 说明 |
|---|---|---|
WBEM_E_ACCESS_DENIED |
0x80041003 | 用户无权更新指定类的实例。 |
WBEM_E_FAILED |
0x80041001 | 发生了未知错误。 |
WBEM_E_INVALID_CLASS |
0x80041010 | 支持此实例的类无效。 |
WBEM_E_ILLEGAL_NULL |
0x80041028 | 为不能为 null 的属性指定了 null，例如，由 Indexed 或 Not_Null 限定符标记的属性。 |
WBEM_E_INVALID_OBJECT |
0x8004100f | 指定的实例无效。 （例如，使用类调用 PutInstanceWmi 会返回此值。） |
WBEM_E_INVALID_PARAMETER |
0x80041008 | 参数无效。 |
WBEM_E_ALREADY_EXISTS |
0x80041019 | 已指定 WBEM_FLAG_CREATE_ONLY 标志，但该实例已存在。 |
WBEM_E_NOT_FOUND |
0x80041002 | 已在 lFlags 中指定了 WBEM_FLAG_UPDATE_ONLY，但该实例不存在。 |
WBEM_E_OUT_OF_MEMORY |
0x80041006 | 没有足够的可用内存来完成该操作。 |
WBEM_E_SHUTTING_DOWN |
0x80041033 | WMI 可能已停止并重启。 再次调用 ConnectServerWmi。 |
WBEM_E_TRANSPORT_FAILURE |
0x80041015 | 当前进程和 WMI 之间的远程过程调用 (RPC) 链接已失败。 |
WBEM_S_NO_ERROR |
0 | 函数调用成功。 |
注解
此函数包装对 IWbemServices::PutInstance 方法的调用。
PutInstanceWmi 函数仅支持创建实例和更新现有类的实例。 根据 pCtx 参数的设置方式，将更新实例的部分或全部属性。
当 pInst 指向的实例属于子类时，Windows 管理会调用负责从中派生子类的类的所有提供程序。 所有这些提供程序必须成功，这样原始 PutInstanceWmi 请求才能成功。 首先调用支持层次结构中最顶端的类的提供程序。 调用顺序继续使用最顶端的类的子类，并从上到下继续，直到 Windows 管理到达拥有 pInst 指向的类的提供程序为止。
Windows 管理不会为实例的任何子类调用提供程序。
当应用程序必须更新属于类层次结构的实例时，pInst 参数必须指向包含要修改的属性的实例。 也就是说，假设有一个属于 ClassB 的目标实例。 ClassB 实例派生自 ClassA，而 ClassA 定义属性 PropA。 如果应用程序要对 ClassB 实例中的 PropA 值进行更改，它必须将 pInst 设置为该实例，而不是 ClassA 的实例。
不允许在抽象类的实例上调用 PutInstanceWmi。
如果该函数调用失败，你可以通过调用 GetErrorInfo 函数获取额外的错误信息。
要求
平台：请参阅系统要求。
标头：WMINet_Utils.idl
.NET Framework 版本：自 4.7.2 起可用
