Fungsi VariantClear (oleauto.h)

Menghapus varian.

Sintaks

HRESULT VariantClear(
  [in, out] VARIANTARG *pvarg
);

Parameter

[in, out] pvarg

Varian untuk dihapus.

Nilai kembali

Fungsi ini dapat mengembalikan salah satu nilai ini.

Menampilkan kode	Deskripsi
S_OK	Berhasil.
DISP_E_ARRAYISLOCKED	Varian berisi array yang dikunci.
DISP_E_BADVARTYPE	Jenis varian bukan jenis varian yang valid.
E_INVALIDARG	Salah satu argumen tidak valid.

Keterangan

Gunakan fungsi ini untuk menghapus variabel jenis VARIANTARG (atau VARIANANT) sebelum memori yang berisi VARIANTARG dikosongkan (seperti ketika variabel lokal keluar dari cakupan).

Fungsi menghapus VARIANTARG dengan mengatur bidang vt ke VT_EMPTY. Konten VARIANTARG saat ini dirilis terlebih dahulu. Jika vtfield VT_BSTR, string akan dikosongkan. Jika vtfield VT_DISPATCH, objek dilepaskan. Jika bidang vt memiliki set bit VT_ARRAY, array akan dibebaskan.

Jika varian yang akan dibersihkan adalah objek COM yang diteruskan oleh referensi, vtfield pvargparameter VT_DISPATCH | VT_BYREF atau VT_UNKNOWN | VT_BYREF. Dalam hal ini, VariantClear tidak merilis objek . Karena varian yang dibersihkan adalah penunjuk ke referensi ke objek, VariantClear tidak memiliki cara untuk menentukan apakah perlu untuk melepaskan objek. Oleh karena itu, pemanggil bertanggung jawab untuk melepaskan objek atau tidak, sebagaimana mewajibkan.

Dalam kasus tertentu, mungkin lebih baik untuk menghapus varian dalam kode tanpa memanggil VariantClear. Misalnya, Anda dapat mengubah jenis varian VT_I4 ke jenis lain tanpa memanggil fungsi ini. Safearrays dari BSTR akan memiliki SysFreeString yang dipanggil pada setiap elemen bukan VariantClear. Namun, Anda harus memanggil VariantClear jika VT_type diterima tetapi tidak dapat ditangani. Safearrays varian juga akan memiliki VariantClear yang dipanggil pada setiap anggota. Menggunakan VariantClear dalam kasus ini memastikan bahwa kode akan terus berfungsi jika Automation menambahkan jenis varian baru di masa mendatang.

Jangan gunakan VariantClear pada varian yang tidak diinisialisasi; gunakan VariantInit untuk menginisialisasi VARIANTARG atau VARIAN BARU.

Varian yang berisi array dengan referensi yang luar biasa tidak dapat dibersihkan. Upaya untuk melakukannya akan mengembalikan HRESULT yang berisi DISP_E_ARRAYISLOCKED.

Contoh

Contoh berikut menunjukkan cara menghapus array varian, di mana celt adalah jumlah elemen dalam array.

for(int i = 0; i < celt; ++i)
   VariantClear(&rgvar[i]);

Persyaratan

Persyaratan	Nilai
Target Platform	Windows
Header	oleauto.h
Pustaka	OleAut32.lib
DLL	OleAut32.dll

Lihat juga

Fungsi Manipulasi Varian