Metode IWbemServices::P utInstanceAsync (wbemcli.h)
Metode IWbemServices::P utInstanceAsync secara asinkron membuat atau memperbarui instans kelas yang ada. Konfirmasi pembaruan atau pelaporan kesalahan disediakan melalui antarmuka IWbemObjectSink yang diterapkan oleh pemanggil.
Sintaks
HRESULT PutInstanceAsync(
[in] IWbemClassObject *pInst,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
Parameter
[in] pInst
Arahkan ke instans yang akan ditulis ke repositori WMI. Penelepon tidak dapat membuat asumsi tentang jumlah referensi pada penyelesaian panggilan ini.
[in] lFlags
Menentukan apakah penelepon ingin instans dibuat jika instans saat ini tidak ada.
Saat menerapkan penyedia instans, Anda dapat memilih untuk mendukung sejumlah bendera terbatas di lFlags dengan mengembalikan WBEM_E_PROVIDER_NOT_CAPABLE.
Properti ini bisa memiliki satu atau beberapa nilai berikut.
WBEM_FLAG_CREATE_OR_UPDATE
Bendera ini menyebabkan instans ini dibuat jika belum ada atau ditimpa jika sudah ada.
WBEM_FLAG_UPDATE_ONLY
Updates instans yang ada.
WBEM_FLAG_CREATE_ONLY
Bendera ini hanya untuk pembuatan instans. Panggilan gagal jika kelas sudah ada.
WBEM_FLAG_SEND_STATUS
Bendera ini mendaftar dengan Manajemen Windows permintaan untuk menerima laporan status perantara melalui implementasi klien IWbemObjectSink::SetStatus. Implementasi penyedia harus mendukung pelaporan status perantara agar bendera ini dapat mengubah perilaku.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
Jika bendera ini diatur, WMI tidak menyimpan kualifikasi apa pun dengan rasa Diubah . Jika bendera ini tidak diatur, diasumsikan bahwa objek ini tidak dilokalkan, dan semua kualifikasi disimpan dengan instans ini.
[in] pCtx
Pointer yang menjelaskan apakah klien meminta pembaruan instans parsial atau pembaruan instans penuh. Pembaruan instans parsial memodifikasi subset properti instans. Sebaliknya, pembaruan instans lengkap memodifikasi semua properti. Jika NULL, parameter ini menunjukkan bahwa aplikasi pemanggil meminta pembaruan instans penuh. Jika tidak, ini adalah penunjuk ke objek IWbemContext yang diperlukan oleh penyedia kelas dinamis yang memproduksi instans kelas. Untuk informasi selengkapnya tentang parameter ini, lihat Melakukan Panggilan ke WMI.
[in] pResponseHandler
Arahkan ke implementasi pemanggil IWbemObjectSink. Handler ini menerima status panggilan ini ketika tersedia menggunakan metode IWbemObjectSink::SetStatus . 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 pada penunjuk jika WBEM_S_NO_ERROR kembali. Dalam kasus di mana kode kesalahan kembali, jumlah referensi sama dengan pada entri. Untuk informasi selengkapnya tentang cara melakukan panggilan asinkron, lihat Memanggil Metode.
Nilai kembali
Metode ini mengembalikan HRESULT yang menunjukkan status panggilan metode. Daftar berikut mencantumkan nilai yang terkandung dalam HRESULT.
Perhatikan bahwa jika PutInstanceAsync 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.
Kode kesalahan khusus COM juga dapat dikembalikan jika masalah jaringan menyebabkan Anda kehilangan koneksi jarak jauh ke Manajemen Windows.
Keterangan
Klien yang memanggil PutInstanceAsync harus selalu mengharapkan hasil panggilan dilaporkan menggunakan metode IWbemObjectSink::Indicate mereka.
Ketika instans yang ditunjukkan oleh pInst milik kelas yang berasal dari kelas lain, keberhasilan PutInstanceAsync tergantung pada keberhasilan penyedia yang bertanggung jawab atas kelas induk. Misalnya, jika pInst milik ClassB dan ClassB berasal dari ClassA, panggilan ke metode PutInstanceAsync yang diterapkan oleh penyedia untuk ClassA harus berhasil agar operasi pembaruan pada ClassB berhasil. Untuk informasi selengkapnya, lihat Keterangan di IWbemServices::P utInstance.
Saat menerapkan penyedia instans, jika instans memiliki properti kunci yang diatur ke NULL, PutInstanceAsync harus memilih nilai yang dijamin unik dalam kelas . Ketika WMI melayani permintaan untuk memperbarui instans dengan properti kunci NULL , WMI secara internal menghasilkan GUID dan menetapkannya ke properti kunci. Selanjutnya, ketika instans yang diperbarui milik kelas anak, keberhasilan operasi tergantung pada keberhasilan panggilan PutInstanceAsync ke setiap penyedia yang bertanggung jawab atas kelas yang lebih tinggi dalam hierarki. Jangan kembali WBEM_S_NO_ERROR sampai Anda yakin bahwa semua penyedia lain telah berhasil. Untuk informasi selengkapnya, lihat IWbemServices::P utInstance.
Penyedia instans yang mendukung pembaruan parsial harus memeriksa keberadaan nilai konteks __PUT_EXTENSIONS . Nilai konteks sistem adalah nilai yang ditentukan oleh WMI untuk memiliki arti tertentu, ditetapkan oleh aplikasi klien, dan didukung oleh penyedia instans. Antarmuka IWbemContext menyediakan akses ke nilai konteks sistem dan nilai konteks khusus penyedia lainnya. Daftar berikut mencantumkan nilai konteks yang mendukung operasi pembaruan instans parsial.
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::P utInstance dan Memanggil Metode.
| Nilai konteks sistem | Deskripsi |
|---|---|
|
__PUT_EXTENSIONS
(VT_BOOL) |
Aplikasi klien telah menetapkan satu atau beberapa nilai konteks sistem lainnya untuk memberikan informasi lebih lanjut tentang operasi pembaruan. |
|
__PUT_EXT_STRICT_NULLS
(VT_BOOL) |
Penyedia instans harus memaksa pengaturan properti untuk VT_NULL jika sesuai dan memunculkan kesalahan pada kegagalan. |
|
__PUT_EXT_PROPERTIES
(VT_ARRAY | VT_BSTR) |
Berisi daftar properti yang akan diperbarui. Penyedia instans harus mengabaikan semua properti lainnya. |
|
__PUT_EXT_ATOMIC
(VT_BOOL) |
Semua pembaruan harus berhasil atau penyedia instans harus kembali. Tidak mungkin ada keberhasilan parsial. |
Saat menerapkan penyedia instans, Anda harus menanggapi properti NULL di pCtx dengan cara berikut:
- Jika jenis properti VT_NULL, penyedia dapat mengabaikan properti tanpa membuat perubahan atau gagal operasi.
- Jika jenis properti tidak VT_NULL dan properti tidak dapat diperbarui, penyedia harus mengembalikan kesalahan, karena penyedia wajib memperbarui properti dengan nilai baru.
Saat menerapkan operasi asinkron, operasi asinkron tidak selesai sampai Anda merilis AddRef yang telah Anda lakukan di pResponseHandler. Ini adalah kasus bahkan jika Anda memanggil SetStatus di pResponseHander. Jika pResponseHandler bocor, klien sinkronisasi atau semi-sinkronisasi apa pun juga tidak akan selesai dan mungkin berhenti merespons, tergantung pada implementasi Anda.
Bahkan dalam kasus bencana, Anda harus merilis referensi untuk penyedia yang diputuskan. Ini karena dalam kasus sinkronisasi dan semi-sinkronisasi, layanan WMI memiliki implementasi pResponseHandler: bahkan jika proses penyedia yang dipisahkan keluar, klien masih tidak akan merespons.
Contoh
Contoh berikut menjelaskan cara menyusun PutInstanceAsync.
HRESULT CStdProvider::PutInstanceAsync(
/* [in] */ IWbemClassObject __RPC_FAR *pInst,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
// You must implement the InstanceIsValid method
// to check to see if the instance in the pInst variable
// is valid.
if (InstanceIsValid(lFlags, pInst))
{
return WBEM_S_NO_ERROR;
}
return WBEM_E_PROVIDER_NOT_CAPABLE;
}
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 |