Metode IWbemServices::ExecQueryAsync (wbemcli.h)
Metode IWbemServices::ExecQueryAsync menjalankan kueri untuk mengambil objek secara asinkron.
Sintaks
HRESULT ExecQueryAsync(
[in] const BSTR strQueryLanguage,
[in] const BSTR strQuery,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
Parameter
[in] strQueryLanguage
BSTR valid yang berisi salah satu bahasa kueri yang didukung Windows Management Instrumentation (WMI). Ini harus "WQL".
[in] strQuery
BSTR valid yang berisi teks kueri. Ini tidak boleh NULL. Saat Anda menerapkan penyedia instans, penyedia Anda dapat menolak kueri karena terlalu kompleks. Saat penyedia menentukan bahwa kueri terlalu kompleks, WMI dapat mencoba kembali penyedia dengan kueri sederhana, atau memilih untuk mengambil dan menghitung superset instans kueri.
Untuk informasi selengkapnya tentang membangun string kueri WMI, lihat Mengkueri dengan WQL dan referensi WQL .
[in] lFlags
Parameter ini bisa menjadi salah satu nilai berikut.
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_BIDIRECTIONAL
Bendera ini menyebabkan WMI mempertahankan pointer ke objek enumerasi hingga klien merilis enumerator.
WBEM_FLAG_SEND_STATUS
Bendera ini mendaftarkan permintaan dengan WMI untuk menerima laporan status perantara melalui implementasi klien IWbemObjectSink::SetStatus. Implementasi penyedia harus mendukung pelaporan status menengah agar bendera ini berubah.
WBEM_FLAG_ENSURE_LOCATABLE
Bendera ini memastikan bahwa objek yang dikembalikan memiliki informasi yang cukup di dalamnya sehingga properti sistem, seperti __PATH, __RELPATH, dan __SERVER, bukan NULL.
WBEM_FLAG_PROTOTYPE
Bendera ini digunakan untuk pembuatan prototipe. Ini tidak menjalankan kueri, tetapi mengembalikan objek yang terlihat seperti objek hasil umum.
WBEM_FLAG_DIRECT_READ
Bendera ini menyebabkan akses langsung ke penyedia untuk kelas yang ditentukan tanpa memperhatikan kelas atau subkelas induknya.
[in] pCtx
Biasanya NULL. Jika tidak, ini adalah penunjuk ke objek IWbemContext yang dapat digunakan penyedia untuk mengembalikan kelas atau instans 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 dalam tataan hasil kueri saat tersedia. 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. Windows Management Instrumentation (WMI) memanggil IWbemObjectSink::Menunjukkan dengan objek berapa kali, diikuti dengan satu panggilan ke IWbemObjectSink::SetStatus untuk menunjukkan status akhir.
WMI hanya memanggil AddRef ke pointer saat WBEM_S_NO_ERROR kembali. Saat kode kesalahan kembali, jumlah referensi sama dengan pada entri. Untuk penjelasan terperinci tentang metode panggilan asinkron, lihat Memanggil Metode.
Mengembalikan nilai
Metode ini mengembalikan HRESULT yang menunjukkan status panggilan metode. Daftar berikut mencantumkan nilai yang terkandung dalam HRESULT.
Ketika ada kegagalan, Anda dapat memperoleh informasi dari fungsi COM GetErrorInfo.
Kode kesalahan lainnya dikembalikan ke sink objek yang ditentukan oleh parameter pResponseHandler .
Kode kesalahan khusus COM mungkin dikembalikan jika masalah jaringan menyebabkan Anda kehilangan koneksi jarak jauh ke WMI.
Setelah selesai, penyedia instans dapat melaporkan keberhasilan atau kegagalan dengan kode pengembalian dari ExecQueryAsync atau melalui panggilan ke SetStatus yang dilakukan melalui pResponseHandler. Jika Anda memilih untuk memanggil SetStatus, kode pengembalian yang dikirim melalui pResponseHandler lebih diutamakan.
Keterangan
Ada batasan jumlah kata kunci AND dan OR yang dapat digunakan dalam kueri WQL. Sejumlah besar kata kunci WQL yang digunakan dalam kueri kompleks dapat menyebabkan WMI mengembalikan kode kesalahan WBEM_E_QUOTA_VIOLATION sebagai nilai HRESULT . Batas kata kunci WQL tergantung pada seberapa kompleks kuerinya.
Metode IWbemObjectSink::Menunjukkan penelepon dapat dipanggil untuk melaporkan status terputus-putus. Metode IWbemObjectSink::SetStatus dipanggil untuk menunjukkan akhir tataan hasil.
Ketika penyedia tidak mendukung pemrosesan kueri, WMI dapat mendukungnya. Namun, implementasi penyedia pemrosesan kueri mungkin lebih efisien daripada versi WMI. Untuk mendukung kueri, penyedia instans Anda harus menerapkan metode ExecQueryAsync . Jika penyedia mendukung ExecQueryAsync, WMI mengirimkan kueri SELECT unary sederhana langsung ke penyedia melalui parameter strQuery dan penyedia harus mengurai kueri dan mengembalikan instans yang relevan. Penyedia harus mengurai kueri karena WMI tidak mengubah kueri—bahkan ketika kueri ditulis dalam WQL.
Untuk menggunakan WMI untuk pemrosesan kueri, jangan atur properti QuerySupportLevels di __InstanceProviderRegistration Anda. Saat Anda melakukan ini, WMI memanggil implementasi CreateInstanceEnumAsync dan posting memfilter hasilnya sehingga penelepon hanya mendapatkan instans yang memenuhi kriteria kueri.
Contoh berikut menunjukkan implementasi penyedia instans khas ExecQueryAsync. 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, lihat IWbemServices::ExecQuery dan Memanggil Metode.
HRESULT CStdProvider::ExecQueryAsync(
/* [in] */ BSTR strQueryLanguage,
/* [in] */ BSTR strQuery,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
IWbemClassObject *pClass = 0;
// Parse the query.
// You must implement ParseQuery().
if (!ParseQuery(strQuery)) return WBEM_E_PROVIDER_NOT_CAPABLE;
// Assume there is an IWbemServices pointer (m_pSvc) available to
// retrieve the class definition.
HRESULT hRes = m_pSvc->GetObject(L"ClassName", 0, NULL, &pClass, 0);
if (FAILED(hRes))
return hRes;
// Call a method to determine number of instances returned.
// You need to implement the GetNumberInst function.
int iNumInst = GetNumberInst();
// Now loop through the private source and create each
// instance which is part of the result set of the query.
for (int iCnt = 0 ; iCnt < iNumInst ; iCnt++)
{
// Prepare an empty object to receive the class definition.
IWbemClassObject *pNextInst = 0;
hRes = pClass->SpawnInstance(0, &pNextInst);
// Create the instance.
// You must implement FillInst().
/*FillInst(pNextInst, iCnt);*/
// Deliver the class to WMI.
pResponseHandler->Indicate(1, &pNextInst);
pNextInst->Release( );
}
// Clean up memory
pClass->Release();
// Send finish message to WMI.
pResponseHandler->SetStatus(0, hRes, 0, 0);
return hRes;
}
Dalam contoh sebelumnya, penyedia instans memperoleh utas dari WMI untuk melakukan operasi sinkronisasi yang diperlukan. Anda dapat memanggil metode AddRef sink dan membuat utas lain untuk mengirimkan objek dalam tataan hasil. Membuat utas lain memungkinkan utas saat ini kembali ke WMI tanpa menguras kumpulan utas. Apakah penyedia memilih desain utas tunggal atau desain utas ganda tergantung pada berapa lama penyedia berencana untuk menggunakan utas WMI. Tidak ada aturan tetap. Eksperimen dapat membantu Anda menentukan bagaimana desain Anda memengaruhi performa WMI.
// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
WBEM_REQUIREMENTS_START_POSTFILTER, 0, 0);
// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
WBEM_REQUIREMENTS_STOP_POSTFILTER, 0, 0);
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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk