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

Artikel
08/27/2023

Die IWbemServices::P utInstanceAsync-Methode erstellt oder aktualisiert asynchron einen instance einer vorhandenen Klasse. Die Aktualisierungsbestätigung oder Fehlerberichterstattung wird über die vom Aufrufer implementierte IWbemObjectSink-Schnittstelle bereitgestellt.

Syntax

HRESULT PutInstanceAsync(
  [in] IWbemClassObject *pInst,
  [in] long             lFlags,
  [in] IWbemContext     *pCtx,
  [in] IWbemObjectSink  *pResponseHandler
);

Parameter

[in] pInst

Zeiger auf den instance, der in das WMI-Repository geschrieben werden soll. Der Aufrufer kann bei Abschluss dieses Aufrufs keine Annahmen über die Verweisanzahl treffen.

[in] lFlags

Gibt an, ob der Aufrufer die instance erstellen möchte, wenn die instance derzeit nicht vorhanden ist.

Wenn Sie einen instance Anbieter implementieren, können Sie eine begrenzte Anzahl der Flags in lFlags unterstützen, indem Sie WBEM_E_PROVIDER_NOT_CAPABLE zurückgeben.

Diese Eigenschaft kann mindestens einen der folgenden Werte aufweisen.

WBEM_FLAG_CREATE_OR_UPDATE

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

WBEM_FLAG_UPDATE_ONLY

Updates eine vorhandene instance.

WBEM_FLAG_CREATE_ONLY

Dieses Flag ist nur für instance Erstellung vorgesehen. Der Aufruf schlägt fehl, wenn die Klasse bereits vorhanden ist.

WBEM_FLAG_SEND_STATUS

Dieses Flag registriert bei der Windows-Verwaltung eine Anforderung zum Empfangen von zwischengeschalteten status Berichten über die Clientimplementierung von IWbemObjectSink::SetStatus. Die Anbieterimplementierung muss die Berichterstellung für zwischengeschaltete status unterstützen, damit dieses Flag das Verhalten ändern kann.

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

Zeiger, der beschreibt, ob der Client ein partielles instance Update oder ein vollständiges update instance anfordert. Ein partielles instance Update ändert eine Teilmenge der Eigenschaften des instance. Im Gegensatz dazu ändert ein vollständiges instance Update alle Eigenschaften. Bei NULL gibt dieser Parameter an, dass die Aufruferanwendung ein vollständiges instance Update anfordert. Andernfalls ist dies ein Zeiger auf ein IWbemContext-Objekt , das vom dynamischen Klassenanbieter benötigt wird, der die Klasseninstanzen erzeugt. Weitere Informationen zu diesem Parameter finden Sie unter Tätigen von Aufrufen von WMI.

[in] pResponseHandler

Zeiger auf die Implementierung von IWbemObjectSink durch den Aufrufer. Dieser Handler empfängt die status dieses Aufrufs, wenn er mit der IWbemObjectSink::SetStatus-Methode verfügbar wird. Wenn Fehlercode zurückgegeben wird, wird der angegebene IWbemObjectSink-Zeiger nicht verwendet. Wenn WBEM_S_NO_ERROR zurückgegeben wird, wird die IWbemObjectSink-Implementierung des Benutzers aufgerufen, um das Ergebnis des Vorgangs anzugeben. Die Windows-Verwaltung ruft AddRef nur auf dem Zeiger auf, wenn WBEM_S_NO_ERROR zurückgegeben wird. In Fällen, in denen ein Fehlercode zurückgegeben wird, ist die Verweisanzahl identisch mit der beim Eintrag. Weitere Informationen zum Tätigen asynchroner Aufrufe finden Sie unter Aufrufen einer Methode.

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.

Beachten Sie, dass WMI auf ein Ergebnis der SetStatus-Methode des Antworthandlers wartet, wenn PutInstanceAsyncWBEM_S_NO_ERROR zurückgibt. WMI wartet auf unbegrenzte Zeit bei einer lokalen Verbindung oder bis ein Timeout der Remoteverbindung auftritt.

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

Hinweise

Clients, die PutInstanceAsync aufrufen, müssen immer erwarten, dass die Ergebnisse des Aufrufs mit ihrer IWbemObjectSink::Indicate-Methode gemeldet werden.

Wenn die instance, auf die pInst verweist, zu einer Klasse gehört, die von anderen Klassen abgeleitet ist, hängt der Erfolg von PutInstanceAsync vom Erfolg der Anbieter ab, die für die übergeordneten Klassen verantwortlich sind. Wenn pInst beispielsweise zu ClassB gehört und ClassB von ClassA abgeleitet wird, muss ein Aufruf der PutInstanceAsync-Methode , die vom Anbieter für ClassA implementiert wurde, erfolgreich sein, damit der Aktualisierungsvorgang für ClassB erfolgreich ist. Weitere Informationen finden Sie unter Hinweise in IWbemServices::P utInstance.

Wenn beim Implementieren eines instance-Anbieters für die instance eine Schlüsseleigenschaft auf NULL festgelegt ist, sollte PutInstanceAsync einen Wert auswählen, der innerhalb der Klasse garantiert eindeutig ist. Wenn WMI eine Anforderung zum Aktualisieren eines instance mit einer NULL-Schlüsseleigenschaft sendet, generiert es intern eine GUID und weist sie der Schlüsseleigenschaft zu. Wenn die instance, die aktualisiert wird, zu einer untergeordneten Klasse gehört, hängt der Erfolg des Vorgangs vom Erfolg eines PutInstanceAsync-Aufrufs bei jedem der Anbieter ab, die für die Klassen höher in der Hierarchie verantwortlich sind. Geben Sie erst WBEM_S_NO_ERROR zurück, wenn Sie sicher sind, dass alle anderen Anbieter erfolgreich sind. Weitere Informationen finden Sie unter IWbemServices::P utInstance.

Instanzanbieter, die eine partielle Aktualisierung unterstützen, müssen überprüfen, ob der __PUT_EXTENSIONS Kontextwert vorhanden ist. Ein Systemkontextwert ist ein von WMI definierter Wert für bestimmte Bedeutungen, wird von der Clientanwendung festgelegt und von einem instance Anbieter unterstützt. Die IWbemContext-Schnittstelle bietet Zugriff auf die Systemkontextwerte und andere anbieterspezifische Kontextwerte. In der folgenden Liste sind die Kontextwerte aufgeführt, die teilweise instance Updatevorgänge unterstützen.

Die IWbemObjectSink::SetStatus-Methode wird aufgerufen, um das Ende des Resultsets anzugeben. Es kann auch ohne eingreifende Aufrufe von IWbemObjectSink::Geben Sie an, ob Fehlerbedingungen auftreten.

Da der Rückruf möglicherweise nicht auf der gleichen Authentifizierungsebene zurückgegeben wird, die der Client benötigt, wird empfohlen, die semisynchrone Kommunikation anstelle der asynchronen Kommunikation zu verwenden. Wenn Sie eine asynchrone Kommunikation benötigen, finden Sie weitere Informationen unter Aufrufen einer Methode.

Weitere Informationen zur semisynchronen Verwendung von Methoden finden Sie unter IWbemServices::P utInstance und Aufrufen einer Methode.

Systemkontextwert	BESCHREIBUNG
__PUT_EXTENSIONS (VT_BOOL)	Die Clientanwendung hat mindestens einen der anderen Systemkontextwerte festgelegt, um weitere Informationen zum Aktualisierungsvorgang bereitzustellen.
__PUT_EXT_STRICT_NULLS (VT_BOOL)	Der instance Anbieter muss erzwingen, dass die Einstellung der Eigenschaften gegebenenfalls VT_NULL und bei Einem Fehler einen Fehler auslöst.
__PUT_EXT_PROPERTIES (VT_ARRAY \| VT_BSTR)	Enthält eine Liste der zu aktualisierenden Eigenschaften. Der instance Anbieter sollte alle anderen Eigenschaften ignorieren.
__PUT_EXT_ATOMIC (VT_BOOL)	Alle Updates müssen erfolgreich sein, oder der instance Anbieter muss rückgängig machen zurück. Ein Teilerfolg ist nicht zulässig.

Wenn Sie einen instance-Anbieter implementieren, sollten Sie auf eine NULL-Eigenschaft in pCtx wie folgt reagieren:

Wenn der Eigenschaftstyp VT_NULL ist, kann der Anbieter die Eigenschaft entweder ignorieren, ohne eine Änderung vorzunehmen, oder der Vorgang fehlschlägt.
Wenn der Eigenschaftstyp nicht VT_NULL ist und die Eigenschaft nicht aktualisiert werden kann, sollte der Anbieter einen Fehler zurückgeben, da der Anbieter verpflichtet ist, die Eigenschaft mit dem neuen Wert zu aktualisieren.

Wenn pCtx nicht NULL ist und auf gültige Kontextinformationen verweist, fordert die Aufruferanwendung eine teilweise instance Aktualisierung an. Wie zuvor sollte ein instance-Anbieter, der keine partielle instance-Aktualisierung unterstützt, den Vorgang fehlschlagen, indem WBEM_E_PROVIDER_NOT_CAPABLE zurückgegeben wird.

Beim Implementieren eines asynchronen Vorgangs wird der asynchrone Vorgang erst abgeschlossen, wenn Sie addRef's freigeben, die Sie auf pResponseHandler ausgeführt haben. Dies ist auch dann der Fall, wenn Sie SetStatus auf pResponseHander aufrufen. Wenn pResponseHandler durchgesickert ist, werden alle Synchronisierungs- oder Semisynchronisierungsclients ebenfalls nicht abgeschlossen und reagieren möglicherweise nicht mehr, je nach Implementierung.

Selbst in schwerwiegenden Fällen müssen Sie die Verweise für entkoppelte Anbieter freigeben. Dies liegt daran, dass in Synchronisierungs- und Semisynchronisierungsfällen der WMI-Dienst die Implementierung von pResponseHandler besitzt: Selbst wenn der Prozess Ihres entkoppelten Anbieters beendet wird, reagieren die Clients immer noch nicht.

Beispiele

Im folgenden Beispiel wird beschrieben, wie PutInstanceAsync strukturiert wird.

HRESULT CStdProvider::PutInstanceAsync( 
            /* [in] */ IWbemClassObject __RPC_FAR *pInst,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
   // You must implement the InstanceIsValid method
   // to check to see if the instance in the pInst variable
   // is valid.
   if (InstanceIsValid(lFlags, pInst)) 
   {
       return WBEM_S_NO_ERROR;
   }

   return WBEM_E_PROVIDER_NOT_CAPABLE;   
}

Anforderungen


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