Metodo IWbemServices::CreateInstanceEnumAsync (wbemcli.h)

Il metodo IWbemServices::CreateInstanceEnumAsync crea un enumeratore che restituisce in modo asincrono le istanze di una classe specificata in base ai criteri di selezione specificati dall'utente. Questo metodo supporta query WQL (WMI Query Language) semplici. È possibile elaborare query più complesse usando il metodo IWbemServices::ExecQueryAsync .

Sintassi

HRESULT CreateInstanceEnumAsync(
  [in] const BSTR      strFilter,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

Parametri

[in] strFilter

BSTR valido contenente il nome della classe per cui sono desiderate le istanze. Questo parametro non può essere NULL.

[in] lFlags

Questo parametro può avere uno dei valori seguenti.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Se questo flag è impostato, Strumentazione gestione Windows recupera i qualificatori modificati archiviati nello spazio dei nomi localizzato delle impostazioni locali della connessione corrente. Se non è impostato, vengono recuperati solo i qualificatori archiviati nello spazio dei nomi immediato.

WBEM_FLAG_DEEP

Questo flag impone all'enumerazione di includere istanze di questa e tutte le sottoclassi nella gerarchia.

WBEM_FLAG_SHALLOW

Questo flag impone all'enumerazione di includere solo istanze pure di questa classe, escluse tutte le istanze delle sottoclassi, che non sono disponibili in questa classe.

WBEM_FLAG_SEND_STATUS

Questo flag registra una richiesta di gestione di Windows per ricevere report di stato intermedi tramite l'implementazione dei client di IWbemObjectSink::SetStatus. L'implementazione del provider deve supportare la segnalazione dello stato intermedio per questo flag per modificare il comportamento.

WBEM_FLAG_BIDIRECTIONAL

Questo flag causa la conservazione dei puntatori a oggetti dell'enumerazione fino a quando il client rilascia l'enumeratore.

WBEM_FLAG_DIRECT_READ

Questo flag causa l'accesso diretto al provider per la classe specificata senza alcun riguardo alla classe padre o alle sottoclassi.

[in] pCtx

In genere NULL. In caso contrario, si tratta di un puntatore a un oggetto IWbemContext che può essere usato dal provider che restituisce le istanze richieste. I valori nell'oggetto contesto devono essere specificati nella documentazione del provider in questione. Per altre informazioni, vedere Creazione di chiamate a WMI.

[in] pResponseHandler

Puntatore all'implementazione del chiamante di IWbemObjectSink. Questo gestore riceve gli oggetti quando diventano disponibili. Se viene restituito un codice di errore, il puntatore IWbemObjectSink specificato non viene usato. Se WBEM_S_NO_ERROR viene restituito, verrà chiamata l'implementazione IWbemObjectSink dell'utente per indicare il risultato dell'operazione. Gestione Windows chiama solo AddRef nel 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 alla voce. Per altre informazioni, 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 un HRESULT.

In caso di errore, è possibile ottenere altre informazioni dalla funzione COM GetErrorInfo.

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

Un provider di istanze può segnalare l'esito positivo o negativo con il codice restituito da CreateInstanceEnumAsync o tramite una chiamata a SetStatus effettuata tramite pResponseHandler. Se si sceglie di chiamare SetStatus, il codice restituito inviato tramite pResponseHandler ha la precedenza.

Se CreateInstanceEnumAsync restituisce WBEM_S_NO_ERROR, WMI attende un risultato dal metodo SetStatus del gestore di risposta. WMI attende in modo indefinito una connessione locale o fino a quando non si verifica un timeout di connessione remota.

Commenti

Il metodo IWbemObjectSink::SetStatus viene chiamato per indicare la fine del set di risultati. Può anche essere chiamato senza chiamate di intervento a IWbemObjectSink::Indica 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.

Per altre informazioni, vedere IWbemServices::CreateInstanceEnum e Chiamata di un metodo.

Esempio

Nell'esempio seguente viene illustrato come implementare CreateInstanceEnumAsync.

#define NUM_OF_INSTANCES 3

HRESULT CStdProvider::CreateInstanceEnumAsync( 
            /* [in] */ BSTR strClass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0; 
    IWbemClassObject *pNextInst = 0;

    // Assume there is an IWbemServices pointer available to
    // retrieve the class definition.
    HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

    // Now loop through the private source and create each instance.
    for (int i = 0; i < NUM_OF_INSTANCES; i++)
    {
         // Prepare an empty object to receive the class definition.
         pClass->SpawnInstance(0, &pNextInst);

         // Create the instance.
         // For example, create the instance in a
         // FillInst method you implement:
         /*FillInst(pNextInst);*/

         // Deliver the class to WMI.
         pResponseHandler->Indicate(1, &pNextInst);
         pNextInst->Release();
    }

    // Send a finish message to WMI.
    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);

    // Free memory resources.
    SysFreeString(strClass);
    pClass->Release();
    m_pSvc->Release();

    return WBEM_S_NO_ERROR;
}

Nell'esempio precedente il provider di istanze acquisisce un thread da WMI per eseguire tutte le operazioni necessarie. È possibile chiamare il metodo AddRef sink e creare un altro thread per distribuire gli oggetti nel set di risultati. La creazione di un altro thread consente al thread corrente di tornare a WMI senza svuotare il pool di thread. Indipendentemente dal fatto che il provider scelga la progettazione a thread singolo rispetto alla progettazione del doppio thread dipende dalla durata del piano del provider per l'uso del thread WMI. Non sono presenti regole fisse. La sperimentazione consente di determinare in che modo la progettazione influisce sulle prestazioni WMI.

Requisiti

Vedi anche

Chiamata di un metodo

Iwbemservices

IWbemServices::CreateInstanceEnum