Metodo IWbemServices::P utInstance (wbemcli.h)

Il metodo IWbemServices::P utInstance crea o aggiorna un'istanza di una classe esistente. L'istanza viene scritta nel repository WMI.

Sintassi

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

Parametri

[in] pInst

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

[in] lFlags

È possibile impostare uno o più dei valori seguenti.

WBEM_FLAG_CREATE_OR_UPDATE

Questo flag fa sì che l'istanza venga creata se non esiste o sovrascritta se esiste già.

WBEM_FLAG_UPDATE_ONLY

Questo flag causa l'aggiornamento della chiamata. L'istanza deve esistere affinché la chiamata venga completata correttamente.

WBEM_FLAG_CREATE_ONLY

Questo flag viene usato solo per la creazione. La chiamata ha esito negativo se l'istanza esiste già.

WBEM_FLAG_RETURN_IMMEDIATELY

Questo flag fa sì che si tratta di una chiamata semiincrona. Per altre informazioni, vedere Chiamata di un metodo.

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

In genere NULL, che indica che ogni proprietà nell'istanza deve essere aggiornata. In caso contrario, si tratta di un puntatore a un oggetto IWbemContext contenente altre informazioni sull'istanza. I dati nell'oggetto di contesto devono essere documentati dal provider responsabile dell'istanza. Un oggetto IWbemContext non NULL può indicare se esiste il supporto per gli aggiornamenti di istanze parziali.

Per altre informazioni su come supportare gli aggiornamenti completi e parziali dell'istanza, vedere IWbemServices::P utInstanceAsync. Per altre informazioni sulla richiesta di un'operazione di aggiornamento completa o parziale, vedere Modifica di una proprietà dell'istanza.

[out] ppCallResult

Se NULL, questo parametro non viene usato. Se il parametro lFlags contiene WBEM_FLAG_RETURN_IMMEDIATELY, questa chiamata restituisce immediatamente con WBEM_S_NO_ERROR. Il parametro ppCallResult riceve quindi un puntatore a un nuovo oggetto IWbemCallResult , che può essere sottoposto a polling con IWbemCallResult::GetCallStatus per ottenere il risultato.

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.

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

Le applicazioni e i provider chiamano PutInstance per creare o aggiornare un'istanza di una classe esistente. A seconda della modalità di impostazione del parametro pCtx , vengono aggiornate alcune o tutte le proprietà dell'istanza. Per altre informazioni su come supportare l'aggiornamento parziale dell'istanza, vedere IWbemServices::P utInstanceAsync. Per altre informazioni sulla richiesta di un aggiornamento parziale dell'istanza, vedere Modifica di una proprietà dell'istanza.

Il metodo PutInstance supporta solo la creazione di istanze e l'aggiornamento delle istanze. Non supporta lo spostamento di istanze. Ovvero, un chiamante non può impostare il parametro pInst su un'istanza con una chiave uguale a un'altra istanza di una classe di pari livello. Si supponga, ad esempio, che ClassA sia la classe base di ClassB e ClassC. La classe ClassA definisce la proprietà KeyProp come chiave e ClassB ha un'istanza con KeyProp impostata su 1. Per creare un'istanza di ClassC con KeyProp impostato su 1, un'applicazione deve prima eliminare l'istanza classB chiamando DeleteInstance e quindi salvare l'istanza ClassC con PutInstance.

Quando l'istanza a cui punta pInst appartiene a una sottoclasse, Gestione Windows chiama tutti i provider responsabili delle classi da cui deriva la sottoclasse. Tutti questi provider devono avere esito positivo affinché la richiesta PutInstance originale abbia esito positivo. Il provider che supporta la classe più alta nella gerarchia viene chiamato per primo. L'ordine chiamante continua con la sottoclasse della classe topmost e procede dall'alto verso il basso fino a quando Gestione Windows non raggiunge il provider per la classe proprietaria dell'istanza a cui punta pInst.

Gestione Windows non chiama i provider per nessuna delle classi figlio di un'istanza. Pertanto, se un'applicazione vuole modificare i valori delle proprietà ereditate, l'applicazione deve chiamare PutInstance nell'istanza completa della classe figlio anziché un'istanza corrispondente della classe padre.

Quando un'applicazione deve aggiornare un'istanza appartenente a una gerarchia di classi, il parametro pInst deve puntare all'istanza contenente le proprietà da modificare. Si consideri quindi un'istanza di destinazione appartenente a ClassB. L'istanza ClassB deriva da ClassA e ClassA definisce la proprietà PropA. Se un'applicazione vuole apportare una modifica al valore di PropA nell'istanza ClassB , deve impostare pInst su tale istanza anziché su un'istanza di ClassA.

La chiamata a PutInstance in un'istanza di una classe astratta non è consentita.

Requisiti

Vedi anche

Creazione di un'istanza

IWbemCallResult

Iwbemservices

IWbemServices::P utInstanceAsync

Recupero di un codice di errore