Freigeben über


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.

Hinweis Das bool-Element in früheren Definitionen dieser Struktur wurde in boolVal umbenannt, da einige Compiler bool jetzt als Schlüsselwort (keyword) erkennen.
 
Hinweis Die unten definierte PROPVARIANT-Struktur enthält Typen, die im Serialisierungsformat für Den -Eigenschaftssatz der Version 1 serialisiert werden können. Das Format der Version 1 unterstützt alle Typen, die im Format version 0 zulässig sind, sowie einige zusätzliche Typen. Die hinzugefügten Typen enthalten "Version 1" im Kommentarfeld unten. Verwenden Sie diese Typen nur, wenn ein Eigenschaftssatz der Version 1 vorgesehen ist. Weitere Informationen finden Sie unter Serialisierung von Eigenschaftensatz.
 
Die PROPVARIANT-Struktur ist wie folgt definiert:

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)