Struktur PROPVARIANT (propidlbase.h)
Struktur PROPVARIANT digunakan dalam metode ReadMultiple dan WriteMultiple dari IPropertyStorage untuk menentukan tag jenis dan nilai properti dalam kumpulan properti.
Struktur PROPVARIANT juga digunakan oleh metode GetValue dan SetValue dari IPropertyStore, yang menggantikan IPropertySetStorage sebagai cara utama untuk memprogram properti item di Windows Vista. Untuk informasi selengkapnya, lihat Penangan Properti.
Ada lima anggota. Anggota pertama, tag jenis nilai, dan anggota terakhir, nilai properti, signifikan. Tiga anggota tengah dicadangkan untuk digunakan di masa mendatang.
Sintaks
typedef struct tagPROPVARIANT {
union {
typedef struct {
VARTYPE vt;
PROPVAR_PAD1 wReserved1;
PROPVAR_PAD2 wReserved2;
PROPVAR_PAD3 wReserved3;
union {
CHAR cVal;
UCHAR bVal;
SHORT iVal;
USHORT uiVal;
LONG lVal;
ULONG ulVal;
INT intVal;
UINT uintVal;
LARGE_INTEGER hVal;
ULARGE_INTEGER uhVal;
FLOAT fltVal;
DOUBLE dblVal;
VARIANT_BOOL boolVal;
VARIANT_BOOL __OBSOLETE__VARIANT_BOOL;
SCODE scode;
CY cyVal;
DATE date;
FILETIME filetime;
CLSID *puuid;
CLIPDATA *pclipdata;
BSTR bstrVal;
BSTRBLOB bstrblobVal;
BLOB blob;
LPSTR pszVal;
LPWSTR pwszVal;
IUnknown *punkVal;
IDispatch *pdispVal;
IStream *pStream;
IStorage *pStorage;
LPVERSIONEDSTREAM pVersionedStream;
LPSAFEARRAY parray;
CAC cac;
CAUB caub;
CAI cai;
CAUI caui;
CAL cal;
CAUL caul;
CAH cah;
CAUH cauh;
CAFLT caflt;
CADBL cadbl;
CABOOL cabool;
CASCODE cascode;
CACY cacy;
CADATE cadate;
CAFILETIME cafiletime;
CACLSID cauuid;
CACLIPDATA caclipdata;
CABSTR cabstr;
CABSTRBLOB cabstrblob;
CALPSTR calpstr;
CALPWSTR calpwstr;
CAPROPVARIANT capropvar;
CHAR *pcVal;
UCHAR *pbVal;
SHORT *piVal;
USHORT *puiVal;
LONG *plVal;
ULONG *pulVal;
INT *pintVal;
UINT *puintVal;
FLOAT *pfltVal;
DOUBLE *pdblVal;
VARIANT_BOOL *pboolVal;
DECIMAL *pdecVal;
SCODE *pscode;
CY *pcyVal;
DATE *pdate;
BSTR *pbstrVal;
IUnknown **ppunkVal;
IDispatch **ppdispVal;
LPSAFEARRAY *pparray;
PROPVARIANT *pvarVal;
};
} tag_inner_PROPVARIANT, PROPVARIANT, *LPPROPVARIANT;
DECIMAL decVal;
};
} PROPVARIANT, *LPPROPVARIANT;
Anggota
tag_inner_PROPVARIANT
tag_inner_PROPVARIANT.vt
tag_inner_PROPVARIANT.wReserved1
tag_inner_PROPVARIANT.wReserved2
tag_inner_PROPVARIANT.wReserved3
tag_inner_PROPVARIANT.cVal
tag_inner_PROPVARIANT.bVal
tag_inner_PROPVARIANT.iVal
tag_inner_PROPVARIANT.uiVal
tag_inner_PROPVARIANT.lVal
tag_inner_PROPVARIANT.ulVal
tag_inner_PROPVARIANT.intVal
tag_inner_PROPVARIANT.uintVal
tag_inner_PROPVARIANT.hVal
tag_inner_PROPVARIANT.uhVal
tag_inner_PROPVARIANT.fltVal
tag_inner_PROPVARIANT.dblVal
tag_inner_PROPVARIANT.boolVal
tag_inner_PROPVARIANT.__OBSOLETE__VARIANT_BOOL
tag_inner_PROPVARIANT.scode
tag_inner_PROPVARIANT.cyVal
tag_inner_PROPVARIANT.date
tag_inner_PROPVARIANT.filetime
tag_inner_PROPVARIANT.puuid
tag_inner_PROPVARIANT.pclipdata
tag_inner_PROPVARIANT.bstrVal
tag_inner_PROPVARIANT.bstrblobVal
tag_inner_PROPVARIANT.blob
tag_inner_PROPVARIANT.pszVal
tag_inner_PROPVARIANT.pwszVal
tag_inner_PROPVARIANT.punkVal
tag_inner_PROPVARIANT.pdispVal
tag_inner_PROPVARIANT.pStream
tag_inner_PROPVARIANT.pStorage
tag_inner_PROPVARIANT.pVersionedStream
tag_inner_PROPVARIANT.parray
tag_inner_PROPVARIANT.cac
tag_inner_PROPVARIANT.caub
tag_inner_PROPVARIANT.cai
tag_inner_PROPVARIANT.caui
tag_inner_PROPVARIANT.cal
tag_inner_PROPVARIANT.caul
tag_inner_PROPVARIANT.cah
tag_inner_PROPVARIANT.cauh
tag_inner_PROPVARIANT.caflt
tag_inner_PROPVARIANT.cadbl
tag_inner_PROPVARIANT.cabool
tag_inner_PROPVARIANT.cascode
tag_inner_PROPVARIANT.cacy
tag_inner_PROPVARIANT.cadate
tag_inner_PROPVARIANT.cafiletime
tag_inner_PROPVARIANT.cauuid
tag_inner_PROPVARIANT.caclipdata
tag_inner_PROPVARIANT.cabstr
tag_inner_PROPVARIANT.cabstrblob
tag_inner_PROPVARIANT.calpstr
tag_inner_PROPVARIANT.calpwstr
tag_inner_PROPVARIANT.capropvar
tag_inner_PROPVARIANT.pcVal
tag_inner_PROPVARIANT.pbVal
tag_inner_PROPVARIANT.piVal
tag_inner_PROPVARIANT.puiVal
tag_inner_PROPVARIANT.plVal
tag_inner_PROPVARIANT.pulVal
tag_inner_PROPVARIANT.pintVal
tag_inner_PROPVARIANT.puintVal
tag_inner_PROPVARIANT.pfltVal
tag_inner_PROPVARIANT.pdblVal
tag_inner_PROPVARIANT.pboolVal
tag_inner_PROPVARIANT.pdecVal
tag_inner_PROPVARIANT.pscode
tag_inner_PROPVARIANT.pcyVal
tag_inner_PROPVARIANT.pdate
tag_inner_PROPVARIANT.pbstrVal
tag_inner_PROPVARIANT.ppunkVal
tag_inner_PROPVARIANT.ppdispVal
tag_inner_PROPVARIANT.pparray
tag_inner_PROPVARIANT.pvarVal
decVal
Keterangan
Struktur PROPVARIANT juga dapat menyimpan nilai VT_DECIMAL:
DECIMAL decVal; //VT_DECIMAL
Namun, nilai struktur DESIMAL membutuhkan penanganan khusus. Struktur DESIMAL berukuran sama dengan seluruh struktur PROPVARIANT dan tidak cocok dengan penyatuan yang menyimpan semua jenis nilai lainnya. Sebaliknya, nilai struktur DESIMAL menempati seluruh struktur PROPVARIANT , termasuk bidang yang dipesan dan anggota vt . Namun, anggota pertama struktur DESIMAL tidak digunakan dan berukuran sama dengan anggota vt struktur PROPVARIANT . Oleh karena itu, deklarasi struktur PROPVARIANT dalam file header Propidl.h Dari Win32 mendefinisikan anggota decVal sedih sehingga sesuai dengan awal struktur PROPVARIANT . Oleh karena itu, untuk menempatkan nilai struktur DESIMAL ke dalam struktur PROPVARIANT , nilai harus dimuat ke dalam anggota decVal dan anggota vt diatur ke VT_DECIMAL, sama seperti nilai lainnya.
PROPVARIANT adalah jenis data mendasar di mana nilai properti dibaca dan ditulis melalui antarmuka IPropertyStorage .
Jenis data PROPVARIANT terkait dengan VARIAN jenis data, yang didefinisikan sebagai bagian dari Automation di OLE2. Beberapa definisi digunakan kembali dari Automation, sebagai berikut:
typedef struct tagCY {
unsigned long Lo;
long Hi;
} CY;
typedef struct tagDEC {
USHORT wReserved;
BYTE scale;
BYTE sign;
ULONG Hi32;
ULONGLONG Lo64;
} DECIMAL;
typedef struct tagSAFEARRAYBOUND {
ULONG cElements;
LONG lLbound;
} SAFEARRAYBOUND;
typedef struct tagSAFEARRAY {
USHORT cDims;
USHORT fFeatures;
ULONG cbElements;
ULONG cLocks;
PVOID pvData;
SAFEARRAYBOUND rgsabound [ * ];
} SAFEARRAY;
typedef CY CURRENCY;
typedef short VARIANT_BOOL;
typedef unsigned short VARTYPE;
typedef double DATE;
typedef OLECHAR* BSTR;
Selain itu, beberapa jenis unik untuk struktur PROPVARIANT :
typedef struct tagCLIPDATA {
// cbSize is the size of the buffer pointed to
// by pClipData, plus sizeof(ulClipFmt)
ULONG cbSize;
long ulClipFmt;
BYTE* pClipData;
} CLIPDATA;
Di antara jenis PROPVARIANT yang unik adalah beberapa jenis data yang menentukan array terhitung dari jenis data lainnya. Jenis data dari semua array yang dihitung dimulai dengan huruf CA, misalnya CAUB, dan memiliki nilai vt operator OR (VarType elemen dan operator OR dengan VT_VECTOR). Struktur array yang dihitung memiliki formulir berikut (di mana nama adalah nama spesifik dari array yang dihitung).
#define TYPEDEF_CA(type, name)
typedef struct tag ## name {\
ULONG cElems;\
type *pElems;\
} name
| Jenis propvariant | Kode | Anggota propvariant | Representasi nilai |
|---|---|---|---|
| VT_EMPTY | 0 | Tidak ada | Properti dengan indikator jenis VT_EMPTY tidak memiliki data yang terkait dengannya; yaitu, ukuran nilainya adalah nol. |
| VT_NULL | 1 | Tidak ada | Ini seperti penunjuk ke NULL. |
| VT_I1 | 16 | cVal | Bilangan bulat bertanda tangan 1-byte. |
| VT_UI1 | 17 | bVal | Bilangan bulat yang tidak ditandatangani 1-byte. |
| VT_I2 | 2 | iVal | Dua byte yang mewakili nilai bilangan bulat bertanda 2 byte. |
| VT_UI2 | 18 | uiVal | Bilangan bulat yang tidak ditandatangani 2-byte. |
| VT_I4 | 3 | lVal | Nilai bilangan bulat bertanda tangan 4-byte. |
| VT_UI4 | 19 | ulVal | Bilangan bulat yang tidak ditandatangani 4-byte. |
| VT_INT | 22 | intVal | Nilai bilangan bulat bertanda tangan 4 byte (setara dengan VT_I4). |
| VT_UINT | 23 | uintVal | Bilangan bulat tidak bertanda 4 byte (setara dengan VT_UI4). |
| VT_I8 | 20 | hVal | Bilangan bulat bertanda tangan 8-byte. |
| VT_UI8 | 21 | uhVal | Bilangan bulat yang tidak ditandatangani 8-byte. |
| VT_R4 | 4 | fltVal | Nilai titik float IEEE 32-bit. |
| VT_R8 | 5 | dblVal | Nilai titik float IEEE 64-bit. |
| VT_BOOL | 11 | boolVal (bool dalam desain sebelumnya) | Nilai Boolean, WORD yang berisi 0 (FALSE) atau -1 (TRUE). |
| VT_ERROR | 10 | scode | DWORD yang berisi kode status. |
| VT_CY | 6 | cyVal | Bilangan bulat pelengkap 8-byte dua (diskalakan sebesar 10.000). Jenis ini umumnya digunakan untuk jumlah mata uang. |
| VT_DATE | 7 | date | Angka titik mengambang 64-bit yang menunjukkan jumlah hari (bukan detik) sejak 31 Desember 1899. Misalnya, 1 Januari 1900, adalah 2,0, 2 Januari 1900, adalah 3,0, dan sebagainya). Ini disimpan dalam representasi yang sama dengan VT_R8. |
| VT_FILETIME | 64 | waktu file | Struktur FILETIME 64-bit seperti yang didefinisikan oleh Win32. Disarankan agar setiap saat disimpan dalam Universal Coordinate Time (UTC). |
| VT_CLSID | 72 | puuid | Penunjuk ke pengidentifikasi kelas (CLSID) (atau pengidentifikasi unik global lainnya (GUID)). |
| VT_CF | 71 | pclipdata | Penunjuk ke struktur CLIPDATA , dijelaskan di atas. |
| VT_BSTR | 8 | bstrVal | Penunjuk ke string Unicode yang dihentikan null. String segera didahului oleh DWORD yang mewakili jumlah byte, tetapi titik bstrVal melewati DWORD ini ke karakter pertama string. BSTRharus dialokasikan dan dikosongkan menggunakan panggilan Automation SysAllocString dan SysFreeString . |
| VT_BSTR_BLOB | 0xfff | bstrblobVal | Untuk penggunaan sistem saja. |
| VT_BLOB | 65 | blob | Jumlah DWORD byte, diikuti oleh banyak byte data. Jumlah byte tidak menyertakan empat byte untuk panjang hitungan itu sendiri; anggota blob kosong akan memiliki hitungan nol, diikuti oleh nol byte. Ini mirip dengan nilai VT_BSTR, tetapi tidak menjamin byte null di akhir data. |
| VT_BLOBOBJECT | 70 | blob | Anggota blob yang berisi objek berseri dalam representasi yang sama yang akan muncul di VT_STREAMED_OBJECT. Artinya, jumlah byte DWORD (di mana jumlah byte tidak menyertakan ukuran dirinya sendiri) yang dalam format pengidentifikasi kelas diikuti dengan data inisialisasi untuk kelas tersebut.
Satu-satunya perbedaan signifikan antara VT_BLOB_OBJECT dan VT_STREAMED_OBJECT adalah bahwa yang pertama tidak memiliki overhead penyimpanan tingkat sistem yang akan dimiliki yang terakhir, dan karenanya lebih cocok untuk skenario yang melibatkan jumlah objek kecil. |
| VT_LPSTR | 30 | pszVal | Penunjuk ke string ANSI yang dihentikan null di halaman kode default sistem. |
| VT_LPWSTR | 31 | pwszVal | Penunjuk ke string Unicode yang dihentikan null di lokal default pengguna. |
| VT_UNKNOWN | 13 | punkVal | Baru. |
| VT_DISPATCH | 9 | pdispVal | Baru. |
| VT_STREAM | 66 | pStream | Penunjuk ke antarmuka IStream yang mewakili aliran yang merupakan saudara kandung dari aliran "Konten". |
| VT_STREAMED_OBJECT | 68 | pStream | Seperti dalam VT_STREAM, tetapi menunjukkan bahwa aliran berisi objek berseri, yang merupakan CLSID diikuti dengan data inisialisasi untuk kelas . Aliran adalah saudara kandung dari aliran "Konten" yang berisi kumpulan properti. |
| VT_STORAGE | 67 | pStorage | Penunjuk ke antarmuka IStorage , mewakili objek penyimpanan yang merupakan saudara kandung dari aliran "Konten". |
| VT_STORED_OBJECT | 69 | pStorage | Seperti dalam VT_STORAGE, tetapi menunjukkan bahwa IStorage yang ditunjuk berisi objek yang dapat dimuat. |
| VT_VERSIONED_STREAM | 73 | pVersionedStream | Streaming dengan versi GUID. |
| VT_DECIMAL | 14 | decVal | Struktur DESIMAL . |
| VT_VECTOR | 0x1000 | Ca* | Jika indikator jenis dikombinasikan dengan VT_VECTOR dengan menggunakan operator OR , nilainya adalah salah satu nilai array yang dihitung. Ini membuat jumlah elemen DWORD , diikuti dengan penunjuk ke pengulangan nilai yang ditentukan.
Misalnya, indikator jenis VT_LPSTR|VT_VECTOR memiliki jumlah elemen DWORD , diikuti dengan penunjuk ke array elemen LPSTR . VT_VECTOR dapat digabungkan oleh operator OR dengan jenis berikut: VT_I1, VT_UI1, VT_I2, VT_UI2, VT_BOOL, VT_I4, VT_UI4, VT_R4, VT_R8, VT_ERROR, VT_I8, VT_UI8, VT_CY, VT_DATE, VT_FILETIME, VT_CLSID, VT_CF, VT_BSTR, VT_LPSTR, VT_LPWSTR, dan VT_VARIANT. VT_VECTOR juga dapat digabungkan dengan operasi OR dengan VT_BSTR_BLOB, namun hanya untuk penggunaan sistem. |
| VT_ARRAY | 0x2000 | Parray | Jika indikator jenis dikombinasikan dengan VT_ARRAY oleh operator OR , nilainya adalah pointer ke SAFEARRAY. VT_ARRAY dapat menggunakan OR dengan jenis data berikut: VT_I1, VT_UI1, VT_I2, VT_UI2, VT_I4, VT_UI4, VT_INT, VT_UINT, VT_R4, VT_R8, VT_BOOL, VT_DECIMAL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_DISPATCH, VT_UNKNOWN, dan VT_VARIANT. VT_ARRAY tidak dapat menggunakan OR dengan VT_VECTOR. |
| VT_BYREF | 0x4000 | P* | Jika indikator jenis dikombinasikan dengan VT_BYREF oleh operator OR , nilainya adalah referensi. Jenis referensi ditafsirkan sebagai referensi ke data, mirip dengan jenis referensi di C++ (misalnya, "int&").
VT_BYREF dapat menggunakan OR dengan jenis berikut: VT_I1, VT_UI1, VT_I2, VT_UI2, VT_I4, VT_UI4, VT_INT, VT_UINT, VT_R4, VT_R8, VT_BOOL, VT_DECIMAL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_UNKNOWN, VT_DISPATCH, VT_ARRAY, dan VT_VARIANT. |
| VT_VARIANT | 12 | capropvar | Indikator jenis DWORD diikuti oleh nilai yang sesuai. VT_VARIANT hanya dapat digunakan dengan VT_VECTOR atau VT_BYREF. |
| VT_TYPEMASK | 0xFFF | Digunakan sebagai masker untuk VT_VECTOR dan pengubah lainnya untuk mengekstrak nilai VT mentah. |
Pengidentifikasi format Clipboard, disimpan dengan tag VT_CF, menggunakan salah satu dari lima representasi, yang diidentifikasi dalam anggota ulClipFmt struktur CLIPDATA menggunakan penunjuk pClipData ke jenis data tertentu.
| Nilai ulClipFmt | nilai pClipData |
|---|---|
| -1L | DWORD yang berisi nilai format clipboard Windows bawaan. |
| -2L | DWORD yang berisi nilai format clipboard Macintosh. |
| -3L | GUID yang berisi pengidentifikasi format (FMTID). Ini jarang digunakan. |
| nilai positif apa pun | String null-terminated yang berisi nama format clipboard Windows, yang cocok untuk diteruskan ke fungsi RegisterClipboardFormat . Fungsi ini mendaftarkan format clipboard baru. Jika format terdaftar dengan nama yang ditentukan sudah ada, format baru tidak terdaftar dan nilai yang dikembalikan mengidentifikasi format yang ada. Ini memungkinkan lebih dari satu aplikasi untuk menyalin dan menempelkan data menggunakan format clipboard terdaftar yang sama. Perbandingan nama format tidak peka huruf besar/kecil dan diidentifikasi oleh nilai dalam rentang dari 0xC000 hingga 0xFFFF. Halaman kode yang digunakan untuk karakter dalam string sesuai dengan indikator halaman kode. "Nilai positif" di sini adalah panjang string, termasuk byte null di akhir. Ketika mendaftarkan format clipboard ditempatkan pada atau diambil dari clipboard, format tersebut harus dalam bentuk nilai jenis data HGLOBAL , yang menyediakan handel ke objek. |
| 0L | Tidak ada data (jarang digunakan). |
Jika nilai anggota ulClipFmt adalah -1, data dalam bentuk format Windows bawaan. Dalam hal ini, DWORD pertama dari buffer yang ditunjukkan oleh pClipData adalah pengidentifikasi format clipboard, misalnya CF_METAFILEPICT. Dalam kasus CF_METAFILEPCT, apa berikut ini adalah variasi pada struktur METAFILEPICT (menggunakan WORD, bukan jenis data DWORD ). Artinya, data ini dalam bentuk berikut:
struct PACKEDMETA
{
WORD mm;
WORD xExt;
WORD yExt
WORD reserved;
};
Setelah struktur METAFILEPICT adalah data metafile, cocok untuk diteruskan ke fungsi SetMetaFileBitsEx . Fungsi ini membuat metafile format Windows berbasis memori dari data yang disediakan. Fungsi ini disediakan untuk kompatibilitas dengan Windows versi 16-bit. Aplikasi berbasis Win32 harus menggunakan fungsi SetEnhMetaFileBits . Fungsi ini mengambil konten metafile format yang disempurnakan yang ditentukan dan menyalinnya ke dalam buffer. Jika fungsi berhasil dan penunjuk buffer adalah NULL, nilai yang dikembalikan adalah ukuran metafile yang ditingkatkan dalam byte. Jika fungsi berhasil dan penunjuk buffer adalah penunjuk yang valid, nilai yang dikembalikan adalah jumlah byte yang disalin ke buffer. Jika fungsi gagal, nilai yang dikembalikan adalah nol.
Ketika mendaftarkan format clipboard ditempatkan pada atau diambil dari clipboard, mereka harus dalam bentuk nilai HGLOBAL .
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows 2000 Server [aplikasi desktop | Aplikasi UWP] |
| Header | propidlbase.h (termasuk Propidl.h) |