PutInstanceWmi-Funktion

  • Artikel

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

Siehe auch