Metode IWbemServices::CreateClassEnumAsync (wbemcli.h)

Artikel
03/08/2023

Metode IWbemServices::CreateClassEnumAsync mengembalikan enumerasi semua kelas yang didukung penyedia kelas. Penyedia kelas membuat setiap definisi kelas dari awal dan hanya mengembalikan subkelas kelas yang diminta. Sebagai metode asinkron, CreateClassEnumAsync segera mengembalikan pesan status dan kemudian memperbarui sink yang diteruskan melalui parameter pResponseHandler —jika perlu.

Ketika panggilan berhasil, WMI memanggil AddRef pada pointer pResponseHandler, segera kembali, dan kemudian secara asinkron memanggil pResponseHandler– >Menunjukkan dari utas lain dengan definisi kelas hingga kueri terpenuhi.

Sintaks

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

Parameter

[in] strSuperclass

Jika tidak NULL atau kosong, parameter ini menentukan nama kelas induk. Hanya kelas yang merupakan subkelas kelas ini yang dikembalikan dalam enumerator. Jika NULL atau kosong, dan lFlagsWBEM_FLAG_SHALLOW, hanya kelas tingkat atas—yang tidak memiliki kelas induk—yang dikembalikan. Jika NULL atau kosong dan lFlagsWBEM_FLAG_DEEP, semua kelas dalam namespace akan dikembalikan.

[in] lFlags

Satu atau beberapa nilai berikut ini valid.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Jika bendera ini diatur, Windows Management Instrumentation (WMI) mengambil kualifikasi yang diubah yang disimpan di namespace layanan lokal dari lokal koneksi saat ini. Jika tidak diatur, hanya kualifikasi yang disimpan di namespace langsung yang diambil.

WBEM_FLAG_BIDIRECTIONAL

Bendera ini menyebabkan WMI mempertahankan pointer ke objek enumerasi hingga klien merilis enumerator.

WBEM_FLAG_DEEP

Bendera ini memaksa enumerasi untuk menyertakan ini dan semua subkelas dalam hierarki.

WBEM_FLAG_SHALLOW

Bendera ini memaksa enumerasi untuk hanya menyertakan instans murni dari kelas ini, tidak termasuk semua instans subkelas yang menyediakan properti yang tidak ditemukan di kelas ini.

WBEM_FLAG_SEND_STATUS

Bendera ini mendaftarkan permintaan di WMI untuk menerima laporan status perantara melalui implementasi klien IWbemObjectSink::SetStatus. Implementasi penyedia harus mendukung pelaporan status menengah agar bendera ini mengubah perilaku.

Catatan Jika strSuperclassNULL atau kosong dan WBEM_FLAG_DEEP ditentukan, semua kelas dikembalikan.

[in] pCtx

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

[in] pResponseHandler

Arahkan ke implementasi pemanggil IWbemObjectSink. Handler ini menerima objek saat tersedia dengan menggunakan metode IWbemObjectSink::Indicate . Ketika tidak ada objek yang tersedia, metode IWbemObjectSink::SetStatus dipanggil oleh WMI. Jika ada kode kesalahan yang dikembalikan, maka penunjuk IWbemObjectSink yang disediakan tidak digunakan. Jika WBEM_S_NO_ERROR dikembalikan, maka implementasi IWbemObjectSink pengguna dipanggil untuk menunjukkan hasil operasi. WMI hanya memanggil AddRef pada pointer saat WBEM_S_NO_ERROR kembali. Saat kode kesalahan kembali, jumlah referensi sama dengan tanpa entri. Untuk penjelasan terperinci tentang parameter ini, lihat Memanggil Metode.

Mengembalikan nilai

Metode ini mengembalikan HRESULT yang menunjukkan status panggilan metode. Jika gagal, Anda dapat memperoleh informasi yang tersedia dari fungsi COM GetErrorInfo. Kode kesalahan khusus COM dapat dikembalikan jika masalah jaringan menyebabkan Anda kehilangan koneksi jarak jauh ke WMI. Perhatikan bahwa jika CreateClassEnumAsync mengembalikan WBEM_S_NO_ERROR, WMI menunggu hasil dari metode SetStatus dari handler respons. WMI menunggu tanpa batas waktu pada koneksi lokal atau sampai waktu koneksi jarak jauh habis. Daftar berikut mencantumkan nilai yang terkandung dalam HRESULT.

Keterangan

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::CreateClassEnum dan Memanggil Metode.

Contoh

Contoh kode berikut menunjukkan cara mengimplementasikan 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;
}

Dalam contoh sebelumnya, penyedia kelas memperoleh utas dari WMI untuk melakukan operasi yang diperlukan. Anda mungkin ingin memanggil metode AddRef sink dan membuat utas lain untuk mengirimkan objek dalam tataan hasil. Membuat utas lain memungkinkan utas saat ini untuk kembali ke WMI tanpa menguras kumpulan utas. Apakah penyedia memilih desain utas tunggal atau desain utas ganda tergantung pada jumlah waktu penyedia berencana untuk menggunakan utas WMI. Tidak ada aturan tetap. Eksperimen dapat membantu Anda menentukan bagaimana desain Anda memengaruhi performa WMI.

Persyaratan


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