IWbemServices::P utInstance-Methode (wbemcli.h)

Artikel
03/03/2024

Die IWbemServices::P utInstance-Methode erstellt oder aktualisiert eine instance einer vorhandenen Klasse. Die Instanz wird in das WMI-Repository geschrieben.

Syntax

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

Parameter

[in] pInst

Zeiger auf die zu schreibende instance. Der Aufrufer kann bei Abschluss dieses Aufrufs keine Annahmen über die Verweisanzahl treffen.

[in] lFlags

Mindestens einer der folgenden Werte kann festgelegt werden.

WBEM_FLAG_CREATE_OR_UPDATE

Dieses Flag bewirkt, dass die instance erstellt wird, wenn sie nicht vorhanden ist, oder wenn sie bereits vorhanden ist, überschrieben wird.

WBEM_FLAG_UPDATE_ONLY

Dieses Flag bewirkt, dass dieser Aufruf aktualisiert wird. Die Instanz muss vorhanden sein, damit der Aufruf erfolgreich ist.

WBEM_FLAG_CREATE_ONLY

Dieses Flag wird nur für die Erstellung verwendet. Der Aufruf ist nicht erfolgreich, wenn die Instanz bereits vorhanden ist.

WBEM_FLAG_RETURN_IMMEDIATELY

Dieses Flag bewirkt, dass es sich um einen semisynchronen Aufruf handelt. Weitere Informationen finden Sie unter Aufrufen einer Methode.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Wenn dieses Flag festgelegt ist, speichert WMI keine Qualifizierer mit der geänderten Variante. Wenn dieses Flag nicht festgelegt ist, wird davon ausgegangen, dass dieses Objekt nicht lokalisiert ist und alle Qualifizierer mit diesem instance gespeichert werden.

[in] pCtx

In der Regel NULL, der angibt, dass jede Eigenschaft in der instance aktualisiert werden soll. Andernfalls ist dies ein Zeiger auf ein IWbemContext-Objekt, das weitere Informationen zum instance enthält. Die Daten im Kontextobjekt müssen vom für die instance verantwortlichen Anbieter dokumentiert werden. Ein IWbemContext-Objekt ohne NULL kann angeben, ob Unterstützung für teilweise instance-Updates vorhanden ist.

Weitere Informationen zur Unterstützung vollständiger und teilweiser instance Updates finden Sie unter IWbemServices::P utInstanceAsync. Weitere Informationen zum Anfordern eines vollständigen oder teilweisen instance Aktualisierungsvorgangs finden Sie unter Ändern einer Instanzeigenschaft.

[out] ppCallResult

Bei NULL wird dieser Parameter nicht verwendet. Wenn der lFlags-ParameterWBEM_FLAG_RETURN_IMMEDIATELY enthält, wird dieser Aufruf sofort mit WBEM_S_NO_ERROR zurückgegeben. Der ppCallResult-Parameter empfängt dann einen Zeiger auf ein neues IWbemCallResult-Objekt , das mit IWbemCallResult::GetCallStatus abgefragt werden kann, um das Ergebnis zu erhalten.

Rückgabewert

Diese Methode gibt ein HRESULT zurück, das den Status des Methodenaufrufs angibt. Die folgende Liste listet den Wert auf, der in einem HRESULT enthalten ist.

COM-spezifische Fehlercodes können auch zurückgegeben werden, wenn Netzwerkprobleme dazu führen, dass die Remoteverbindung mit der Windows-Verwaltung verloren geht.

Hinweise

Anwendungen und Anbieter rufen PutInstance auf, um eine instance einer vorhandenen Klasse zu erstellen oder zu aktualisieren. Je nachdem, wie der pCtx-Parameter festgelegt wird, werden entweder einige oder alle Eigenschaften des instance aktualisiert. Weitere Informationen zur Unterstützung teilweiser instance Updates finden Sie unter IWbemServices::P utInstanceAsync. Weitere Informationen zum Anfordern einer teilweisen instance Aktualisierung finden Sie unter Ändern einer Instanzeigenschaft.

Die PutInstance-Methode unterstützt nur das Erstellen von Instanzen und das Aktualisieren von Instanzen. Das Verschieben von Instanzen wird nicht unterstützt. Das heißt, ein Aufrufer kann den pInst-Parameter nicht auf einen instance festlegen, der über einen Schlüssel verfügt, der mit einem anderen instance in einer geschwisterlichen Klasse identisch ist. Angenommen, ClassA ist die Basisklasse für ClassB und ClassC. Die ClassA-Klasse definiert die KeyProp-Eigenschaft als ihren Schlüssel, und ClassB verfügt über eine instance, für die KeyProp auf 1 festgelegt ist. Um eine instance von ClassC zu erstellen, wobei KeyProp auf 1 festgelegt ist, muss eine Anwendung zuerst die ClassB-instance löschen, indem Sie DeleteInstance aufruft und dann die ClassC-instance mit PutInstance speichern.

Wenn die instance, auf die pInst verweist, zu einer Unterklasse gehört, ruft die Windows-Verwaltung alle Anbieter auf, die für die Klassen verantwortlich sind, von denen die Unterklasse abgeleitet wird. Alle diese Anbieter müssen erfolgreich sein, damit die ursprüngliche PutInstance-Anforderung erfolgreich ist. Der Anbieter, der die oberste Klasse in der Hierarchie unterstützt, wird zuerst aufgerufen. Die aufrufende Reihenfolge wird mit der Unterklasse der obersten Klasse fortgesetzt und wird von oben nach unten fortgesetzt, bis die Windows-Verwaltung den Anbieter für die Klasse erreicht, die die von pInst angegebene instance besitzt.

Die Windows-Verwaltung ruft keine Anbieter für eine der untergeordneten Klassen einer Instanz auf. Wenn eine Anwendung daher die Werte der geerbten Eigenschaften ändern möchte, muss die Anwendung PutInstance für den vollständigen instance der untergeordneten Klasse aufrufen und nicht für einen entsprechenden instance der übergeordneten Klasse.

Wenn eine Anwendung einen instance aktualisieren muss, der zu einer Klassenhierarchie gehört, muss der pInst-Parameter auf den instance zeigen, der 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-instance ändern möchte, muss sie pInst auf diesen instance und nicht auf einen instance von ClassA festlegen.

Das Aufrufen von PutInstance für eine instance einer abstrakten Klasse ist nicht zulässig.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	wbemcli.h (include Wbemidl.h)
Bibliothek	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