Metodo IWbemServices::P utInstanceAsync (wbemcli.h)

Articolo
03/08/2023

Il metodo IWbemServices::P utInstanceAsync crea o aggiorna in modo asincrono un'istanza di una classe esistente. La conferma dell'aggiornamento o la segnalazione degli errori viene fornita tramite l'interfaccia IWbemObjectSink implementata dal chiamante.

Sintassi

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

Parametri

[in] pInst

Puntatore all'istanza da scrivere nel repository WMI. Il chiamante non può fare ipotesi sul conteggio dei riferimenti al completamento di questa chiamata.

[in] lFlags

Specifica se il chiamante desidera creare l'istanza se l'istanza non esiste attualmente.

Quando si implementa un provider di istanze, è possibile scegliere di supportare un numero limitato di flag in lFlag restituendo WBEM_E_PROVIDER_NOT_CAPABLE.

Questa proprietà può avere uno o più dei valori seguenti.

WBEM_FLAG_CREATE_OR_UPDATE

Questo flag determina la creazione di questa istanza se non esiste o viene sovrascritta se esiste già.

WBEM_FLAG_UPDATE_ONLY

Aggiornamenti un'istanza esistente.

WBEM_FLAG_CREATE_ONLY

Questo flag è solo per la creazione dell'istanza. La chiamata ha esito negativo se la classe esiste già.

WBEM_FLAG_SEND_STATUS

Questo flag viene registrato con Gestione Windows una richiesta di ricezione di rapporti di stato intermedi tramite l'implementazione dei client di IWbemObjectSink::SetStatus. Per modificare il comportamento, l'implementazione del provider deve supportare la creazione di report di stato intermedio per questo flag.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Se questo flag è impostato, WMI non archivia alcun qualificatore con il sapore modificato . Se questo flag non è impostato, si presuppone che questo oggetto non sia localizzato e che tutti i qualificatori vengano archiviati con questa istanza.

[in] pCtx

Puntatore che descrive se il client richiede un aggiornamento parziale dell'istanza o un aggiornamento completo dell'istanza. Un aggiornamento parziale dell'istanza modifica un subset delle proprietà dell'istanza. Al contrario, un aggiornamento completo dell'istanza modifica tutte le proprietà. Se NULL, questo parametro indica che l'applicazione chiamante richiede un aggiornamento completo dell'istanza. In caso contrario, si tratta di un puntatore a un oggetto IWbemContext richiesto dal provider di classi dinamiche che produce le istanze della classe. Per altre informazioni su questo parametro, vedere Effettuare chiamate a WMI.

[in] pResponseHandler

Puntatore all'implementazione del chiamante di IWbemObjectSink. Questo gestore riceve lo stato di questa chiamata quando diventa disponibile usando il metodo IWbemObjectSink::SetStatus . Se viene restituito un codice di errore, il puntatore IWbemObjectSink fornito non viene usato. Se viene restituito WBEM_S_NO_ERROR, viene chiamata l'implementazione IWbemObjectSink dell'utente per indicare il risultato dell'operazione. Gestione Windows chiama solo AddRef sul puntatore nei casi in cui WBEM_S_NO_ERROR restituisce . Nei casi in cui viene restituito un codice di errore, il conteggio dei riferimenti corrisponde a quello della voce. Per altre informazioni su come effettuare chiamate asincrone, vedere Chiamata di un metodo.

Valore restituito

Questo metodo restituisce un valore HRESULT che indica lo stato della chiamata al metodo. L'elenco seguente elenca il valore contenuto in hrESULT.

Si noti che se PutInstanceAsync restituisce WBEM_S_NO_ERROR, WMI attende un risultato dal metodo SetStatus del gestore di risposta. WMI attende per un periodo illimitato su una connessione locale o fino a quando non si verifica un timeout della connessione remota.

I codici di errore specifici di COM possono anche essere restituiti se i problemi di rete causano la perdita della connessione remota a Gestione Windows.

Commenti

I client che chiamano PutInstanceAsync devono sempre prevedere che i risultati della chiamata vengano segnalati usando il metodo IWbemObjectSink::Indicate .

Quando l'istanza a cui punta pInst appartiene a una classe derivata da altre classi, l'esito positivo di PutInstanceAsync dipende dall'esito positivo dei provider responsabili delle classi padre. Ad esempio, se pInst appartiene a ClassB e ClassB deriva da ClassA, una chiamata al metodo PutInstanceAsync implementato dal provider per ClassA deve avere esito positivo affinché l'operazione di aggiornamento in ClassB abbia esito positivo. Per altre informazioni, vedere Osservazioni in IWbemServices::P utInstance.

Quando si implementa un provider di istanze, se l'istanza ha una proprietà chiave impostata su NULL, PutInstanceAsync deve scegliere un valore che sia univoco all'interno della classe . Quando WMI esegue la richiesta di aggiornare un'istanza con una proprietà di chiave NULL , genera internamente un GUID e lo assegna alla proprietà key. Inoltre, quando l'istanza da aggiornare appartiene a una classe figlio, l'esito positivo dell'operazione dipende dall'esito positivo di una chiamata PutInstanceAsync a ognuno dei provider responsabili delle classi superiori nella gerarchia. Non restituire WBEM_S_NO_ERROR finché non si è certi che tutti gli altri provider abbiano avuto esito positivo. Per altre informazioni, vedere IWbemServices::P utInstance.

I provider di istanze che supportano un aggiornamento parziale devono verificare l'esistenza del valore di contesto __PUT_EXTENSIONS . Un valore di contesto di sistema è un valore definito da WMI per avere significati specifici, viene impostato dall'applicazione client ed è supportato da un provider di istanze. L'interfaccia IWbemContext consente di accedere ai valori del contesto di sistema e ad altri valori di contesto specifici del provider. Nell'elenco seguente sono elencati i valori di contesto che supportano operazioni di aggiornamento a istanza parziale.

Il metodo IWbemObjectSink::SetStatus viene chiamato per indicare la fine del set di risultati. Può anche essere chiamato senza chiamate intermedie a IWbemObjectSink::Indicate se si verificano condizioni di errore.

Poiché il callback potrebbe non essere restituito allo stesso livello di autenticazione richiesto dal client, è consigliabile usare semisynchrono anziché la comunicazione asincrona. Se è necessaria la comunicazione asincrona, vedere Chiamata di un metodo.

Per altre informazioni sull'uso semisynchronously dei metodi, vedere IWbemServices::P utInstance e Chiamata di un metodo.

Valore del contesto di sistema	Descrizione
__PUT_EXTENSIONS (VT_BOOL)	L'applicazione client ha impostato uno o più valori del contesto di sistema per fornire altre informazioni sull'operazione di aggiornamento.
__PUT_EXT_STRICT_NULLS (VT_BOOL)	Il provider di istanze deve forzare l'impostazione delle proprietà per VT_NULL quando appropriato e generare un errore in caso di errore.
__PUT_EXT_PROPERTIES (VT_ARRAY \| VT_BSTR)	Contiene un elenco delle proprietà da aggiornare. Il provider di istanze deve ignorare tutte le altre proprietà.
__PUT_EXT_ATOMIC (VT_BOOL)	Tutti gli aggiornamenti devono avere esito positivo o ripristinare il provider di istanze. Non può verificarsi un esito positivo parziale.

Quando si implementa un provider di istanze, è necessario rispondere a una proprietà NULL in pCtx nel modo seguente:

Se il tipo di proprietà è VT_NULL, il provider può ignorare la proprietà senza apportare alcuna modifica o interrompere l'operazione.
Se il tipo di proprietà non è VT_NULL e la proprietà non può essere aggiornata, il provider deve restituire un errore, perché il provider è obbligato ad aggiornare la proprietà con il nuovo valore.

Se pCtx non è NULL e punta a informazioni di contesto valide, l'applicazione chiamante richiede un aggiornamento parziale dell'istanza. Come in precedenza, i provider di istanze che non supportano l'aggiornamento parziale dell'istanza devono interrompere l'operazione restituendo WBEM_E_PROVIDER_NOT_CAPABLE.

Quando si implementa un'operazione asincrona, l'operazione asincrona non viene completata fino a quando non si rilascia qualsiasi componente AddRef eseguito su pResponseHandler. Questo è il caso anche se chiami SetStatus su pResponseHander. Se pResponseHandler viene persa , anche tutti i client di sincronizzazione o semi-sincronizzazione non verranno completati e potrebbero smettere di rispondere, a seconda dell'implementazione.

Anche in casi irreversibili, è necessario rilasciare i riferimenti per i provider disaccoppiati. Ciò è dovuto al fatto che nei casi di sincronizzazione e semi-sincronizzazione il servizio WMI è proprietario dell'implementazione di pResponseHandler: anche se il processo disaccoppiato del provider viene chiuso, i client non risponderanno ancora.

Esempio

Nell'esempio seguente viene descritto come strutturare PutInstanceAsync.

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;   
}

Requisiti


Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	wbemcli.h (include Wbemidl.h)
Libreria	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