PROPVARIANT-Struktur (propidlbase.h)
Die PROPVARIANT-Struktur wird in den Methoden ReadMultiple und WriteMultiple von IPropertyStorage verwendet, um das Typtag und den Wert einer Eigenschaft in einem Eigenschaftensatz zu definieren.
Die PROPVARIANT-Struktur wird auch von den Methoden GetValue und SetValue von IPropertyStore verwendet, die IPropertySetStorage als primäre Methode zum Programmieren von Elementeigenschaften in Windows Vista ersetzt. Weitere Informationen finden Sie unter Eigenschaftenhandler.
Es gibt fünf Mitglieder. Der erste Member, das Werttyptag und der letzte Member, der Wert der Eigenschaft, sind signifikant. Die mittleren drei Member sind für die zukünftige Verwendung reserviert.
Syntax
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;
Member
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
Hinweise
Die PROPVARIANT-Struktur kann auch den Wert VT_DECIMAL enthalten:
DECIMAL decVal; //VT_DECIMAL
Der Wert der DECIMAL-Struktur erfordert jedoch eine spezielle Behandlung. Die DECIMAL-Struktur hat die gleiche Größe wie eine gesamte PROPVARIANT-Struktur und passt nicht in die Union, die alle anderen Wertetypen enthält. Stattdessen belegt der Wert der DECIMAL-Struktur die gesamte PROPVARIANT-Struktur , einschließlich der reservierten Felder und des vt-Elements . Das erste Element der DECIMAL-Struktur wird jedoch nicht verwendet und ist gleich dem vt-Member der PROPVARIANT-Struktur . Daher definiert die PROPVARIANT-Strukturdeklaration in der Propidl.h-Headerdatei von Win32 den decVal-Member so, dass es dem Anfang der PROPVARIANT-Struktur entspricht. Um den Wert der DECIMAL-Struktur in eine PROPVARIANT-Struktur zu setzen, muss der Wert daher in den decVal-Member geladen werden, und das vt-Element wird auf VT_DECIMAL festgelegt, genau wie bei jedem anderen Wert.
PROPVARIANT ist der grundlegende Datentyp, mit dem Eigenschaftswerte über die IPropertyStorage-Schnittstelle gelesen und geschrieben werden.
Der Datentyp PROPVARIANT bezieht sich auf den Datentyp VARIANT, der als Teil der Automatisierung in OLE2 definiert ist. In Automation werden mehrere Definitionen wie folgt wiederverwendet:
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;
Darüber hinaus sind einige Typen für die PROPVARIANT-Struktur eindeutig:
typedef struct tagCLIPDATA {
// cbSize is the size of the buffer pointed to
// by pClipData, plus sizeof(ulClipFmt)
ULONG cbSize;
long ulClipFmt;
BYTE* pClipData;
} CLIPDATA;
Zu den eindeutigen PROPVARIANT-Typen gehören mehrere Datentypen, die gezählte Arrays anderer Datentypen definieren. Die Datentypen aller gezählten Arrays beginnen mit den Buchstaben CA, z. B. CAUB, und haben einen OR-Operator vt-Wert (der VarType des Elements und ein OR-Operator mit VT_VECTOR). Die gezählte Arraystruktur hat die folgende Form (wobei name der spezifische Name des gezählten Arrays ist).
#define TYPEDEF_CA(type, name)
typedef struct tag ## name {\
ULONG cElems;\
type *pElems;\
} name
| Propvarianter Typ | Code | Propvarianter Member | Wertdarstellung |
|---|---|---|---|
| VT_EMPTY | 0 | Keine | Einer Eigenschaft mit einem Typindikator von VT_EMPTY sind keine Daten zugeordnet. Das heißt, die Größe des Werts ist null. |
| VT_NULL | 1 | Keine | Dies ist wie ein Zeiger auf NULL. |
| VT_I1 | 16 | cVal | 1-Byte-Ganzzahl mit Vorzeichen. |
| VT_UI1 | 17 | bVal | Ganze Zahl mit 1 Byte ohne Vorzeichen. |
| VT_I2 | 2 | iVal | Zwei Bytes, die einen 2-Byte-Ganzzahlwert mit Vorzeichen darstellen. |
| VT_UI2 | 18 | uiVal | 2-Byte-Ganzzahl ohne Vorzeichen. |
| VT_I4 | 3 | lVal | 4-Byte-Ganzzahlwert mit Vorzeichen. |
| VT_UI4 | 19 | ulVal | 4-Byte-Ganzzahl ohne Vorzeichen. |
| VT_INT | 22 | intVal | 4-Byte-Ganzzahlwert mit Vorzeichen (entspricht VT_I4). |
| VT_UINT | 23 | uintVal | 4-Byte-Ganzzahl ohne Vorzeichen (entspricht VT_UI4). |
| VT_I8 | 20 | hVal | 8-Byte-Ganzzahl mit Vorzeichen. |
| VT_UI8 | 21 | uhVal | 8-Byte-Ganzzahl ohne Vorzeichen. |
| VT_R4 | 4 | fltVal | 32-Bit-IEEE-Gleitkommawert. |
| VT_R8 | 5 | dblVal | 64-Bit-IEEE-Gleitkommawert. |
| VT_BOOL | 11 | boolVal (bool in früheren Designs) | Boolescher Wert, ein WORD-Wert , der 0 (FALSE) oder -1 (TRUE) enthält. |
| VT_ERROR | 10 | scode | Ein DWORD, das einen status Code enthält. |
| VT_CY | 6 | cyVal | 8-Byte two's complement integer (skaliert um 10.000). Dieser Typ wird häufig für Währungsbeträge verwendet. |
| VT_DATE | 7 | date | Eine 64-Bit-Gleitkommazahl, die die Anzahl der Tage (nicht Sekunden) seit dem 31. Dezember 1899 darstellt. Beispiel: 1. Januar 1900 ist 2.0, 2. Januar 1900, 3.0 usw.). Dies wird in derselben Darstellung wie VT_R8 gespeichert. |
| VT_FILETIME | 64 | Filetime | 64-Bit-FILETIME-Struktur, wie von Win32 definiert. Es wird empfohlen, alle Zeiten in der Weltkoordinatenzeit (UTC) zu speichern. |
| VT_CLSID | 72 | puuid | Zeiger auf einen Klassenbezeichner (CLSID) (oder einen anderen global eindeutigen Bezeichner (GUID)). |
| VT_CF | 71 | pclipdata | Zeiger auf eine CLIPDATA-Struktur , oben beschrieben. |
| VT_BSTR | 8 | bstrVal | Zeiger auf eine Unicode-Zeichenfolge mit Null-Beendigung. Der Zeichenfolge wird sofort ein DWORD vorangestellt, das die Byteanzahl darstellt, aber bstrVal zeigt über dieses DWORD auf das erste Zeichen der Zeichenfolge. BSTRs müssen mithilfe der Aufrufe Automation SysAllocString und SysFreeString zugeordnet und freigegeben werden. |
| VT_BSTR_BLOB | 0xfff | bstrblobVal | Nur zur Verwendung durch das System. |
| VT_BLOB | 65 | Blob | DWORD-Anzahl von Bytes, gefolgt von so vielen Bytes an Daten. Die Byteanzahl enthält nicht die vier Bytes für die Länge der Anzahl selbst. ein leeres Blobelement hätte die Anzahl null, gefolgt von null Bytes. Dies ähnelt dem Wert VT_BSTR, garantiert aber kein NULL-Byte am Ende der Daten. |
| VT_BLOBOBJECT | 70 | Blob | Ein Blobelement , das ein serialisiertes Objekt in derselben Darstellung enthält, die in VT_STREAMED_OBJECT angezeigt wird. Das heißt, eine DWORD-Byteanzahl (wobei die Byteanzahl nicht die Größe von sich selbst enthält), die sich im Format eines Klassenbezeichners befindet, gefolgt von Initialisierungsdaten für diese Klasse.
Der einzige signifikante Unterschied zwischen VT_BLOB_OBJECT und VT_STREAMED_OBJECT besteht darin, dass erstere nicht über den Speicheraufwand auf Systemebene verfügt, den letzteres hätte, und eignet sich daher besser für Szenarien mit der Anzahl kleiner Objekte. |
| VT_LPSTR | 30 | pszVal | Ein Zeiger auf eine NULL-beendete ANSI-Zeichenfolge auf der Standardcodepage des Systems. |
| VT_LPWSTR | 31 | pwszVal | Ein Zeiger auf eine Unicode-Zeichenfolge mit Null-Beendigung im Standardgebietsschema des Benutzers. |
| VT_UNKNOWN | 13 | PunkVal | Neu |
| VT_DISPATCH | 9 | pdispVal | Neu |
| VT_STREAM | 66 | pStream | Ein Zeiger auf eine IStream-Schnittstelle , die einen Stream darstellt, der mit dem Datenstrom "Contents" gleichgeordnet ist. |
| VT_STREAMED_OBJECT | 68 | pStream | Wie in VT_STREAM, gibt aber an, dass der Stream ein serialisiertes Objekt enthält, bei dem es sich um eine CLSID gefolgt von Initialisierungsdaten für die Klasse handelt. Der Stream ist ein gleichgeordnetes Element des Inhaltsdatenstroms, der den Eigenschaftssatz enthält. |
| VT_STORAGE | 67 | pStorage | Ein Zeiger auf eine IStorage-Schnittstelle , der ein Speicherobjekt darstellt, das dem "Contents"-Stream gleichgeordnet ist. |
| VT_STORED_OBJECT | 69 | pStorage | Wie in VT_STORAGE, gibt aber an, dass der angegebene IStorage ein ladebares Objekt enthält. |
| VT_VERSIONED_STREAM | 73 | pVersionedStream | Ein Stream mit einer GUID-Version. |
| VT_DECIMAL | 14 | decVal | Eine DECIMAL-Struktur . |
| VT_VECTOR | 0x1000 | Ca* | Wenn der Typindikator mit VT_VECTOR mithilfe eines OR-Operators kombiniert wird, ist der Wert einer der gezählten Arraywerte. Dadurch wird eine DWORD-Anzahl von Elementen erstellt, gefolgt von einem Zeiger auf die angegebenen Wiederholungen des Werts.
Beispielsweise weist ein Typindikator VT_LPSTR|VT_VECTOR eine DWORD-Elementanzahl auf, gefolgt von einem Zeiger auf ein Array von LPSTR-Elementen . VT_VECTOR können von einem OR-Operator mit den folgenden Typen kombiniert werden: 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 und VT_VARIANT. VT_VECTOR kann auch durch einen OR-Vorgang mit VT_BSTR_BLOB kombiniert werden, ist jedoch nur für die Systemnutzung vorgesehen. |
| VT_ARRAY | 0x2000 | Parray | Wenn der Typindikator mit VT_ARRAY von einem OR-Operator kombiniert wird, ist der Wert ein Zeiger auf ein SAFEARRAY. VT_ARRAY können das OR mit den folgenden Datentypen verwenden: 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 und VT_VARIANT. VT_ARRAY können OR nicht mit VT_VECTOR verwenden. |
| VT_BYREF | 0x4000 | P* | Wenn der Typindikator mit VT_BYREF von einem OR-Operator kombiniert wird, ist der Wert ein Verweis. Verweistypen werden als Verweis auf Daten interpretiert, ähnlich dem Verweistyp in C++ (z. B. "int&").
VT_BYREF können OR mit den folgenden Typen verwenden: 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 und VT_VARIANT. |
| VT_VARIANT | 12 | capropvar | Ein Indikator vom Typ DWORD gefolgt vom entsprechenden Wert. VT_VARIANT kann nur mit VT_VECTOR oder VT_BYREF verwendet werden. |
| VT_TYPEMASK | 0xFFF | Wird als Maske für VT_VECTOR und andere Modifizierer verwendet, um den unformatierten VT-Wert zu extrahieren. |
Zwischenablageformatbezeichner, die mit dem Tag VT_CF gespeichert werden, verwenden eine von fünf Darstellungen, die im ulClipFmt-Member der CLIPDATA-Struktur mithilfe des pClipData-Zeigers auf den jeweiligen Datentyp identifiziert werden.
| ulClipFmt-Wert | pClipData-Wert |
|---|---|
| -1L | Ein DWORD-Wert , der einen integrierten Windows-Zwischenablageformatwert enthält. |
| -2L | Ein DWORD-Wert , der einen Macintosh-Zwischenablageformatwert enthält. |
| -3L | Eine GUID, die einen Formatbezeichner (FMTID) enthält. Dies wird selten verwendet. |
| jeder positive Wert | Eine null-beendete Zeichenfolge, die einen Windows-Zwischenablageformatnamen enthält, der zum Übergeben an die RegisterClipboardFormat-Funktion geeignet ist. Diese Funktion registriert ein neues Zwischenablageformat. Wenn bereits ein registriertes Format mit dem angegebenen Namen vorhanden ist, wird kein neues Format registriert, und der Rückgabewert identifiziert das vorhandene Format. Dadurch können mehrere Anwendungen Daten mit demselben registrierten Zwischenablageformat kopieren und einfügen. Beim Formatnamenvergleich wird die Groß-/Kleinschreibung nicht beachtet und durch Werte im Bereich von 0xC000 bis 0xFFFF identifiziert. Die codepage, die für Zeichen in der Zeichenfolge verwendet wird, entspricht dem Codepageindikator. Der "positive Wert" ist hier die Zeichenfolgenlänge, einschließlich des NULL-Byte am Ende. Wenn Register-Zwischenablageformate in der Zwischenablage platziert oder aus der Zwischenablage abgerufen werden, müssen sie in Form eines HGLOBAL-Datentypwerts vorliegen, der das Handle für das Objekt bereitstellt. |
| 0L | Keine Daten (selten verwendet). |
Wenn der Wert des ulClipFmt-Members -1 ist, sind die Daten in Form eines integrierten Windows-Formats. In diesem Fall ist das erste DWORD des Puffers, auf den pClipData verweist, der Zwischenablageformatbezeichner, z. B. CF_METAFILEPICT. Im Fall von CF_METAFILEPCT folgt eine Variation der METAFILEPICT-Struktur (sie verwendet WORD anstelle von DWORD-Datentypen ). Das heißt, diese Daten haben die folgende Form:
struct PACKEDMETA
{
WORD mm;
WORD xExt;
WORD yExt
WORD reserved;
};
Nach der METAFILEPICT-Struktur sind die Metadatendaten, die für die Übergabe an die SetMetaFileBitsEx-Funktion geeignet sind. Diese Funktion erstellt eine speicherbasierte Metadatei im Windows-Format aus den bereitgestellten Daten. Diese Funktion wird zur Kompatibilität mit 16-Bit-Versionen von Windows bereitgestellt. Win32-basierte Anwendungen sollten die SetEnhMetaFileBits-Funktion verwenden. Diese Funktion ruft den Inhalt der angegebenen Metadatei im erweiterten Format ab und kopiert sie in einen Puffer. Wenn die Funktion erfolgreich ist und der Pufferzeiger NULL ist, entspricht der Rückgabewert der Größe der erweiterten Metadatei in Bytes. Wenn die Funktion erfolgreich ist und der Pufferzeiger ein gültiger Zeiger ist, ist der Rückgabewert die Anzahl der in den Puffer kopierten Bytes. Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null.
Wenn Register-Zwischenablageformate in der Zwischenablage platziert oder aus der Zwischenablage abgerufen werden, müssen sie in Form eines HGLOBAL-Werts vorliegen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [Desktop-Apps | UWP-Apps] |
| Kopfzeile | propidlbase.h (include Propidl.h) |