PutInstanceWmi-Funktion
Erstellt oder aktualisiert eine Instanz einer vorhandenen Klasse. Die Instanz wird in das WMI-Repository geschrieben.
Hinweis
Diese API ist ausschließlich für die interne Verwendung vorgesehen. Sie ist nicht für die Verwendung im Entwicklercode vorgesehen.
Syntax
HRESULT PutInstanceWmi (
[in] IWbemClassObject* pInst,
[in] long lFlags,
[in] IWbemContext* pCtx,
[out] IWbemCallResult** ppCallResult
);
Parameter
pInst
[in] Ein Zeiger auf die Instanz, die geschrieben werden soll.
lFlags
[in] Eine Kombination aus Flags, die das Verhalten dieser Funktion beeinflussen. Die folgenden Werte werden in der Headerdatei WbemCli.h definiert. Alternativ dazu können Sie sie als Konstanten im Code definieren:
| Konstante | Wert | BESCHREIBUNG |
|---|---|---|
WBEM_FLAG_USE_AMENDED_QUALIFIERS |
0x20000 | Wenn dieser Wert festgelegt ist, speichert WMI keine Qualifizierer mit der Variante Amended. Wenn dieser Wert nicht festgelegt ist, wird davon ausgegangen, dass dieses Objekt nicht lokalisiert ist, und alle Qualifizierer werden mit dieser Instanz gespeichert. |
WBEM_FLAG_CREATE_OR_UPDATE |
0 | Erstellen Sie die Instanz, wenn sie nicht vorhanden ist, oder überschreiben Sie sie, wenn sie bereits vorhanden ist. |
WBEM_FLAG_UPDATE_ONLY |
1 | Aktualisieren Sie die Instanz. Die Instanz muss vorhanden sein, damit der Aufruf erfolgreich ist. |
WBEM_FLAG_CREATE_ONLY |
2 | Erstellen Sie die Instanz. Der Aufruf ist nicht erfolgreich, wenn die Instanz bereits vorhanden ist. |
WBEM_FLAG_RETURN_IMMEDIATELY |
0x10 | Das Flag verursacht einen halbsynchronen Aufruf. |
pCtx
[in] In der Regel ist dieser Wert null. Andernfalls handelt es sich um einen Zeiger auf eine IWbemContext-Instanz, die von dem Anbieter verwendet werden kann, der die angeforderten Klassen bereitstellt.
ppCallResult
[out] Wenn dieser Wert null ist, wird dieser Parameter nicht verwendet. Wenn lFlags die Konstante WBEM_FLAG_RETURN_IMMEDIATELY enthält, wird die Funktion sofort mit WBEM_S_NO_ERROR zurückgegeben. Der ppCallResult-Parameter empfängt einen Zeiger auf ein neues IWbemCallResult-Objekt.
Rückgabewert
Die folgenden von dieser Funktion zurückgegebenen Werte werden in der Headerdatei WbemCli.h definiert. Alternativ dazu können Sie sie als Konstanten im Code definieren:
| Konstante | Wert | Beschreibung |
|---|---|---|
WBEM_E_ACCESS_DENIED |
0x80041003 | Der Benutzer/die Benutzerin verfügt nicht über die Berechtigung, eine Instanz der angegebenen Klasse zu aktualisieren. |
WBEM_E_FAILED |
0x80041001 | Ein unbekannter Fehler ist aufgetreten. |
WBEM_E_INVALID_CLASS |
0x80041010 | Die Klasse, die diese Instanz unterstützt, ist ungültig. |
WBEM_E_ILLEGAL_NULL |
0x80041028 | null wurde für eine Eigenschaft angegeben, die nicht null sein kann, z. B. eine Eigenschaft, die durch einen Indexed- oder Not_Null-Qualifizierer gekennzeichnet ist. |
WBEM_E_INVALID_OBJECT |
0x8004100f | Die angegebene Instanz ist ungültig. (Beispielsweise gibt das Aufrufen von PutInstanceWmi mit einer Klasse diesen Wert zurück.) |
WBEM_E_INVALID_PARAMETER |
0x80041008 | Ein Parameter ist nicht gültig. |
WBEM_E_ALREADY_EXISTS |
0x80041019 | Das WBEM_FLAG_CREATE_ONLY-Flag wurde angegeben, aber die Instanz ist bereits vorhanden. |
WBEM_E_NOT_FOUND |
0x80041002 | WBEM_FLAG_UPDATE_ONLY wurde in lFlags angegeben, aber die Instanz ist nicht vorhanden. |
WBEM_E_OUT_OF_MEMORY |
0x80041006 | Es ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen. |
WBEM_E_SHUTTING_DOWN |
0x80041033 | WMI wurde wahrscheinlich beendet und startet neu. Rufen Sie ConnectServerWmi erneut auf. |
WBEM_E_TRANSPORT_FAILURE |
0x80041015 | Fehler bei der RPC-Verbindung (Remote Procedure Call, Remoteprozeduraufruf) zwischen dem aktuellen Prozess und WMI. |
WBEM_S_NO_ERROR |
0 | Der Funktionsaufruf war erfolgreich. |
Bemerkungen
Diese Funktion umschließt einen Aufruf der IWbemServices::PutInstance-Methode.
Die PutInstanceWmi-Funktion unterstützt das Erstellen von Instanzen und das Aktualisieren von Instanzen nur bei vorhandenen Klassen. Je nachdem, wie der pCtx-Parameter festgelegt ist, werden entweder einige oder alle Eigenschaften der Instanz aktualisiert.
Wenn die Instanz, auf die pInst zeigt, zu einer Unterklasse gehört, ruft die Windows-Verwaltung alle Anbieter auf, die für die Klassen zuständig sind, von denen die Unterklasse abgeleitet ist. Alle diese Anbieter müssen erfolgreich aufgerufen werden, damit die ursprüngliche PutInstanceWmi-Anforderung erfolgreich ausgeführt werden kann. Der Anbieter, der die oberste Klasse in der Hierarchie unterstützt, wird zuerst aufgerufen. Die Aufrufreihenfolge wird mit der Unterklasse der obersten Klasse und dann weiter von oben nach unten fortgesetzt, bis die Windows-Verwaltung den Anbieter für die Klasse erreicht, die die Instanz besitzt, auf die pInst zeigt.
Die Windows-Verwaltung ruft keine Anbieter für eine der untergeordneten Klassen einer Instanz auf.
Wenn eine Anwendung eine Instanz aktualisieren muss, die zu einer Klassenhierarchie gehört, muss der Parameter pInst auf die Instanz zeigen, die die zu ändernden Eigenschaften enthält. Ein Beispiel: Eine Zielinstanz gehört zu ClassB. Die ClassB-Instanz ist von ClassA abgeleitet, und ClassA definiert die Eigenschaft PropA. Wenn eine Anwendung den Wert von PropA in der ClassB-Instanz ändern möchte, muss sie pInst auf diese Instanz festlegen, nicht auf eine Instanz von ClassA.
Das Aufrufen von PutInstanceWmi für eine Instanz einer abstrakten Klasse ist nicht zulässig.
Wenn der Funktionsaufruf nicht erfolgreich ist, können Sie durch Aufruf der GetErrorInfo-Funktion zusätzliche Fehlerinformationen abrufen.
Anforderungen
Plattformen: Informationen finden Sie unter Systemanforderungen.
Header: WMINet_Utils.idl
.NET Framework-Versionen: seit Version 4.7.2 verfügbar
