Metodo IWbemServices::GetObjectAsync (wbemcli.h)

Articolo
03/08/2023

Il metodo IWbemServices::GetObjectAsync recupera un oggetto, una definizione di classe o un'istanza, in base al relativo percorso. Simile a IWbemServices::GetObject , ad eccezione del fatto che la chiamata restituisce immediatamente e l'oggetto viene fornito al sink di oggetti fornito.

Attualmente, questo metodo recupera oggetti solo dallo spazio dei nomi associato al puntatore IWbemServices .

Sintassi

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

Parametri

[in] strObjectPath

Percorso dell'oggetto da recuperare. Per un provider di istanze , StrObjectPath può essere nel formato seguente:

Spazio dei nomi:Class.Key = "Value"
Spazio dei nomi:Class = "Value"
Spazio dei nomi:Class.Key = "Value", Key2 = "Value2"

Specificare lo spazio dei nomi prima che la classe sia facoltativa. I percorsi degli oggetti senza spazi dei nomi fanno riferimento alle istanze nello spazio dei nomi corrente. Se necessario, è possibile sostituire il carattere di virgolette singole (') per il carattere di virgolette doppie (") per delimitare l'inizio e la fine dei tipi di proprietà stringa.

Se si tratta di NULL, viene restituito un oggetto vuoto, che può diventare una nuova classe. Per altre informazioni, vedere Creazione di una classe.

[in] lFlags

I flag seguenti influiscono sul comportamento di questo metodo.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Se questo flag è impostato, WMI 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_DIRECT_READ

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

WBEM_FLAG_SEND_STATUS

Registra una richiesta per ricevere report sullo stato intermedio tramite l'implementazione del client di IWbemObjectSink::SetStatus. L'implementazione del provider deve supportare la segnalazione dello stato intermedio per questo flag per modificare il comportamento.

[in] pCtx

In genere NULL. In caso contrario, si tratta di un puntatore a un oggetto IWbemContext che può essere usato dal provider che produce la classe o l'istanza richiesta. I valori nell'oggetto contesto devono essere specificati nella documentazione del provider in questione. Per altre informazioni su questo parametro, vedere Creazione di chiamate a WMI.

[in] pResponseHandler

Puntatore all'implementazione del chiamante di IWbemObjectSink. Questo gestore riceve l'oggetto richiesto quando diventa disponibile tramite il metodo IWbemObjectSink::Indicate . Il parametro pObjParam contiene l'oggetto . Se viene restituito un codice di errore, il puntatore IWbemObjectSink specificato 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 al 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 su questo parametro, vedere Chiamata di un metodo.

Valore restituito

Questo metodo restituisce un 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 tutte le informazioni disponibili dalla funzione COM GetErrorInfoGetErrorInfo.

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.

Commenti

Quando si implementa un provider di istanze, è necessario usare il codice di esempio del parser del percorso dell'oggetto nella sezione WMI del PSDK per analizzare il percorso dell'oggetto per riconoscere quale oggetto richiede il client. Inoltre, un provider che supporta una classe derivata deve fornire solo i valori per le proprietà locali della classe, anziché le proprietà ereditate. WMI richiede che il provider della classe di base gestisca le proprietà ereditate.

Quando si implementa un provider di classi, GetObjectAsync deve determinare quale classe viene richiesta analizzando il percorso dell'oggetto nome classe archiviato nel parametro strObjectPath . Il metodo GetObjectAsync compila quindi la classe dinamicamente o accetta la classe da una cache privata. GetObjectAsync invia quindi la classe a WMI usando il puntatore IWbemObjectSink a cui punta il parametro pResponseHandler. Il metodo IWbemObjectSink::SetStatus viene chiamato per indicare la fine del set di risultati. Può essere chiamato anche 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. Se è necessaria la comunicazione asincrona, vedere Chiamata di un metodo.

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

Esempio

Nell'esempio seguente viene descritto come implementare GetObjectAsync per un provider di istanze.

SCODE CInstPro::GetObjectAsync (BSTR ObjectPath, 
                                long lFlags, IWbemContext *pCtx,
                                IWbemObjectSink FAR* pHandler)
{
    ULONG cRef;         // Reference count
    SCODE sc;
    BOOL bOK = FALSE;

    IWbemServices *  m_pNamespace;
    IWbemClassObject FAR* pObj;

    // Check arguments.

    if(ObjectPath == NULL || pHandler == NULL ||
        m_pNamespace == NULL)
        return WBEM_E_INVALID_PARAMETER;

    
    // Based on the object path, produce an empty instance
    // of the class and gather required data,
    // setting the instance's property values accordingly.
    // This example assumes that GetByPath is implemented
    // by the provider to do this.
    // The IWbemPath interface can be used to parse
    // the object path, separating the namespace and class name.

    sc = GetByPath (ObjectPath, &pObj, pCtx);
    if(sc == S_OK) 
    {
        pHandler->Indicate (1, &pObj);
        pObj->Release();
        bOK = TRUE;
    }

    sc = (bOK) ? S_OK : WBEM_E_NOT_FOUND;

    // Set status.

    pHandler->SetStatus(0,sc, NULL, NULL);

    // Free memory resources.

    SysFreeString(ObjectPath);
    m_pNamespace->Release();
    pObj->Release();

    return sc;
  
}

Nell'esempio seguente viene illustrato come un provider di classi tipico implementa GetObjectAsync.

HRESULT CStdProvider::GetObjectAsync( 
            /* [in] */ BSTR strObjectPath,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{

    IWbemClassObject *pClass = 0;

// Assume there is an IWbemServices pointer available.
// Retrieve an 'empty' object which is built up
// into the class definition.

    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

// Parse the object path and determine which class is   
// required. The path string is the required class name.
// Fill in the properties required for the class definition
// using pClass->Put(...), and so on.

    
    // ...

    // Send the class definition back to WMI.
    pResponseHandler->Indicate(1, &pClass);

// Indicate that it is now finished.

    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);
    SysFreeString(strObjectPath);
    m_pSvc->Release();
    pClass->Release();  // This is no longer needed.
    return WBEM_S_NO_ERROR;
}

Requisiti

Requisito	Valore
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