Metodo IWbemServices::CreateClassEnumAsync (wbemcli.h)

Articolo
08/27/2023

Il metodo IWbemServices::CreateClassEnumAsync restituisce un'enumerazione di tutte le classi supportate dal provider di classi. Il provider di classi crea ogni definizione di classe da zero e restituisce solo sottoclassi della classe richiesta. Come metodo asincrono, CreateClassEnumAsync restituisce immediatamente un messaggio di stato e quindi aggiorna il sink passato tramite il parametro pResponseHandler , se necessario.

Quando una chiamata ha esito positivo, WMI chiama AddRef sul puntatore pResponseHandler, restituisce immediatamente e quindi chiama pResponseHandler in modo asincrono: >indica da un altro thread con definizioni di classe finché la query non viene soddisfatta.

Sintassi

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

Parametri

[in] strSuperclass

Se non è NULL o vuoto, questo parametro specifica un nome di classe padre. Nell'enumeratore vengono restituite solo le classi che sono sottoclassi di questa classe. Se NULL o blank e lFlags è WBEM_FLAG_SHALLOW, vengono restituite solo le classi di primo livello, quelle senza classe padre. Se è NULL o vuoto e lFlags è WBEM_FLAG_DEEP, vengono restituite tutte le classi all'interno dello spazio dei nomi.

[in] lFlags

Uno o più dei valori seguenti sono validi.

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_BIDIRECTIONAL

Questo flag fa sì che WMI mantenga i puntatori agli oggetti dell'enumerazione fino a quando il client non rilascia l'enumeratore.

WBEM_FLAG_DEEP

Questo flag impone all'enumerazione di includere 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 di sottoclassi che forniscono proprietà non trovate in questa classe.

WBEM_FLAG_SEND_STATUS

Questo flag registra una richiesta in WMI per ricevere report di stato intermedi tramite l'implementazione client di IWbemObjectSink::SetStatus. Per modificare il comportamento, l'implementazione del provider deve supportare la creazione di report di stato intermedio per questo flag.

Nota Se strSuperclass è NULL o vuoto e viene specificato WBEM_FLAG_DEEP , vengono restituite tutte le classi.

[in] pCtx

In genere NULL. In caso contrario, si tratta di un puntatore a un oggetto IWbemContext che può essere utilizzato dal provider che restituisce le classi richieste. I valori nell'oggetto di contesto devono essere specificati nella documentazione per il provider. Per altre informazioni su questo parametro, vedere Effettuare chiamate a WMI.

[in] pResponseHandler

Puntatore all'implementazione del chiamante di IWbemObjectSink. Questo gestore riceve gli oggetti non appena diventano disponibili usando il metodo IWbemObjectSink::Indicate . Quando non sono disponibili oggetti, il metodo IWbemObjectSink::SetStatus viene chiamato da WMI. 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. WMI chiama AddRef solo sul puntatore quando WBEM_S_NO_ERROR restituisce . Quando viene restituito un codice di errore, il conteggio dei riferimenti corrisponde a nessuna voce. Per una spiegazione dettagliata di questo parametro, vedere Chiamata di un metodo.

Valore restituito

Questo metodo restituisce un valore HRESULT che indica lo stato della chiamata al metodo. In caso di errore, è possibile ottenere informazioni disponibili dalla funzione COM GetErrorInfo. I codici di errore specifici di COM possono essere restituiti se i problemi di rete causano la perdita della connessione remota a WMI. Si noti che se CreateClassEnumAsync 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. L'elenco seguente elenca il valore contenuto in hrESULT.

Commenti

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

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

Esempio

L'esempio di codice seguente illustra come implementare CreateClassEnumAsync.

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

    // Assume there is an IWbemServices pointer available (m_pSvc).
    // Retrieve an 'empty' object that will be built up
    // into the class definition.
    
    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
    {
        return hRes;
    }

    // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);

    // Now loop through the private source of class definitions
    // and create each class.
    while(hRes)
    {
        // Create the class definition elsewhere.
        // For example, call a function that creates a definition:
        // FillClassDef(pNextClass);

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

        // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);     
    }

    pClass->Release();

    // Send a finish message to WMI.

    pResponseHandler->SetStatus(0, hRes, 0, 0);

    return hRes;
}

Nell'esempio precedente il provider di classi acquisisce un thread da WMI per eseguire le operazioni necessarie. È possibile chiamare il metodo AddRef sink e creare un altro thread per recapitare 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. Se il provider sceglie la progettazione a thread singolo o la progettazione a thread doppio dipende dalla quantità di tempo prevista dal provider per l'uso del thread WMI. Non esistono regole fisse. La sperimentazione consente di determinare in che modo la progettazione influisce sulle prestazioni WMI.

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