Metode IWbemServices::GetObjectAsync (wbemcli.h)

Artikel
03/13/2024

Metode IWbemServices::GetObjectAsync mengambil objek, baik definisi kelas atau instans, berdasarkan jalurnya. Ini mirip dengan IWbemServices::GetObject kecuali bahwa panggilan segera kembali, dan objek disediakan ke sink objek yang disediakan.

Saat ini, metode ini mengambil objek hanya dari namespace yang terkait dengan penunjuk IWbemServices .

Sintaks

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

Parameter

[in] strObjectPath

Jalur objek yang akan diambil. Untuk penyedia instans, StrObjectPath dapat dalam format berikut:

Namespace:Class.Key = "Value"
Namespace:Class = "Value"
Namespace:Class.Key = "Value", Key2 = "Value2"

Menentukan namespace sebelum kelas bersifat opsional. Jalur objek tanpa namespace mengacu pada instans di namespace saat ini. Jika perlu, Anda dapat mengganti karakter tanda kutip tunggal (') untuk karakter tanda kutip ganda (") untuk memisahkan awal dan akhir jenis properti string.

Jika ini ADALAH NULL, objek kosong, yang dapat menjadi kelas baru, dikembalikan. Untuk informasi selengkapnya, lihat Membuat Kelas.

[in] lFlags

Bendera berikut memengaruhi perilaku metode ini.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Jika bendera ini diatur, WMI mengambil kualifikasi yang diubah yang disimpan di namespace layanan lokal koneksi saat ini. Jika tidak diatur, hanya kualifikasi yang disimpan di namespace langsung yang diambil.

WBEM_FLAG_DIRECT_READ

Bendera ini menyebabkan akses langsung ke penyedia untuk kelas yang ditentukan tanpa memperhatikan kelas atau subkelas induknya.

WBEM_FLAG_SEND_STATUS

Mendaftarkan permintaan untuk menerima laporan status perantara melalui implementasi klien IWbemObjectSink::SetStatus. Implementasi penyedia harus mendukung pelaporan status perantara agar bendera ini dapat mengubah perilaku.

[in] pCtx

Biasanya NULL. Jika tidak, ini adalah penunjuk ke objek IWbemContext yang dapat digunakan oleh penyedia yang menghasilkan kelas atau instans yang diminta. Nilai dalam objek konteks harus ditentukan dalam dokumentasi untuk penyedia yang bersangkutan. Untuk informasi selengkapnya tentang parameter ini, lihat Melakukan Panggilan ke WMI.

[in] pResponseHandler

Arahkan ke implementasi pemanggil IWbemObjectSink. Handler ini menerima objek yang diminta ketika tersedia melalui metode IWbemObjectSink::Indicate . Parameter pObjParam berisi objek . Jika ada kode kesalahan yang dikembalikan, maka pointer IWbemObjectSink yang disediakan tidak digunakan. Jika WBEM_S_NO_ERROR dikembalikan, maka implementasi IWbemObjectSink pengguna dipanggil untuk menunjukkan hasil operasi. Manajemen Windows hanya memanggil AddRef ke penunjuk jika WBEM_S_NO_ERROR kembali. Dalam kasus di mana kode kesalahan kembali, jumlah referensi sama dengan pada entri. Untuk informasi selengkapnya tentang parameter ini, lihat Memanggil Metode.

Nilai kembali

Metode ini mengembalikan HRESULT yang menunjukkan status panggilan metode. Daftar berikut mencantumkan nilai yang terkandung dalam HRESULT.

Jika gagal, Anda dapat memperoleh informasi yang tersedia dari fungsi COM GetErrorInfoGetErrorInfo.

Kode kesalahan khusus COM juga dapat dikembalikan jika masalah jaringan menyebabkan Anda kehilangan koneksi jarak jauh ke Manajemen Windows.

Keterangan

Saat menerapkan penyedia instans, Anda harus menggunakan kode sampel pengurai jalur objek di bagian WMI dari PSDK untuk mengurai jalur objek untuk mengenali objek mana yang diminta klien. Selanjutnya, penyedia yang mendukung kelas turunan hanya perlu menyediakan nilai untuk properti lokal kelas , bukan properti yang diwariskan. WMI meminta penyedia kelas dasar menangani properti yang diwariskan.

Saat menerapkan penyedia kelas, GetObjectAsync harus menentukan kelas mana yang diminta dengan mengurai jalur objek nama kelas yang disimpan dalam parameter strObjectPath . Metode GetObjectAsync kemudian membangun kelas secara dinamis atau mengambil kelas dari cache privat. Kemudian, GetObjectAsync mengirim kelas ke WMI menggunakan pointer IWbemObjectSink yang ditunjukkan oleh parameter pResponseHandler . Metode IWbemObjectSink::SetStatus dipanggil untuk menunjukkan akhir tataan hasil. Ini juga dapat dipanggil tanpa intervensi panggilan ke IWbemObjectSink::Menunjukkan apakah kondisi kesalahan terjadi.

Karena panggilan balik mungkin tidak dikembalikan pada tingkat autentikasi yang sama dengan yang dibutuhkan klien, disarankan agar Anda menggunakan semisinkron alih-alih komunikasi asinkron. Jika Anda memerlukan komunikasi asinkron, lihat Memanggil Metode.

Untuk informasi selengkapnya tentang menggunakan metode secara semisinkron, lihat IWbemServices::GetObject dan Memanggil Metode.

Contoh

Contoh berikut menjelaskan cara mengimplementasikan GetObjectAsync untuk penyedia instans.

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

Contoh berikut menunjukkan bagaimana penyedia kelas umum mengimplementasikan 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;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Server minimum yang didukung	Windows Server 2008
Target Platform	Windows
Header	wbemcli.h (termasuk Wbemidl.h)
Pustaka	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