Поделиться через


Структура PROPVARIANT (propidl.h)

Структура PROPVARIANT используется в методах ReadMultiple и WriteMultipleiPropertyStorage для определения тега типа и значения свойства в наборе свойств.

Структура PROPVARIANT также используется методами GetValue и SetValueiPropertyStore, который заменяет IPropertySetStorage в качестве основного способа программирования свойств элементов в Windows Vista. Дополнительные сведения см. в разделе Обработчики свойств.

Есть пять членов. Первый элемент, тег типа значения и последний элемент, значение свойства, являются значимыми. Средние три элемента зарезервированы для использования в будущем.

Примечание Элемент bool в предыдущих определениях этой структуры был переименован в boolVal, так как некоторые компиляторы теперь распознают bool как ключевое слово.
 
Примечание Структура PROPVARIANT , определенная ниже, включает типы, которые можно сериализовать в формате сериализации набора свойств версии 1. Формат версии 1 поддерживает все типы, разрешенные в формате версии 0, а также некоторые дополнительные типы. Добавленные типы включают "Версия 1" в поле комментария ниже. Используйте эти типы, только если предназначен набор свойств версии 1. Дополнительные сведения см. в разделе Сериализация набора свойств.
 
Структура PROPVARIANT определяется следующим образом:

Синтаксис

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;

Члены

tag_inner_PROPVARIANT

tag_inner_PROPVARIANT.vt

Тег типа значения.

tag_inner_PROPVARIANT.wReserved1

Зарезервировано для будущего использования.

tag_inner_PROPVARIANT.wReserved2

Зарезервировано для будущего использования.

tag_inner_PROPVARIANT.wReserved3

Зарезервировано для будущего использования.

tag_inner_PROPVARIANT.cVal

VT_I1 версии 1

tag_inner_PROPVARIANT.bVal

VT_UI1

tag_inner_PROPVARIANT.iVal

VT_I2

tag_inner_PROPVARIANT.uiVal

VT_UI2

tag_inner_PROPVARIANT.lVal

VT_I4

tag_inner_PROPVARIANT.ulVal

VT_UI4

tag_inner_PROPVARIANT.intVal

VT_INT, версия 1

tag_inner_PROPVARIANT.uintVal

VT_UINT, версия 1

tag_inner_PROPVARIANT.hVal

VT_I8

tag_inner_PROPVARIANT.uhVal

VT_UI8

tag_inner_PROPVARIANT.fltVal

VT_R4

tag_inner_PROPVARIANT.dblVal

VT_R8

tag_inner_PROPVARIANT.boolVal

VT_BOOL

tag_inner_PROPVARIANT.__OBSOLETE__VARIANT_BOOL

tag_inner_PROPVARIANT.scode

VT_ERROR

tag_inner_PROPVARIANT.cyVal

VT_CY

tag_inner_PROPVARIANT.date

VT_DATE

tag_inner_PROPVARIANT.filetime

VT_FILETIME

tag_inner_PROPVARIANT.puuid

VT_CLSID

tag_inner_PROPVARIANT.pclipdata

VT_CF

tag_inner_PROPVARIANT.bstrVal

VT_BSTR

tag_inner_PROPVARIANT.bstrblobVal

VT_BSTR_BLOB

tag_inner_PROPVARIANT.blob

VT_BLOB, VT_BLOBOBJECT

tag_inner_PROPVARIANT.pszVal

VT_LPSTR

tag_inner_PROPVARIANT.pwszVal

VT_LPWSTR

tag_inner_PROPVARIANT.punkVal

VT_UNKNOWN

tag_inner_PROPVARIANT.pdispVal

VT_DISPATCH, версия 1

tag_inner_PROPVARIANT.pStream

VT_STREAM, VT_STREAMED_OBJECT

tag_inner_PROPVARIANT.pStorage

VT_STORAGE, VT_STORED_OBJECT

tag_inner_PROPVARIANT.pVersionedStream

VT_VERSIONED_STREAM

tag_inner_PROPVARIANT.parray

| VT_ARRAYVT_*, версия 1

tag_inner_PROPVARIANT.cac

| VT_VECTORVT_I1 версии 1

tag_inner_PROPVARIANT.caub

| VT_VECTORVT_UI1

tag_inner_PROPVARIANT.cai

| VT_VECTORVT_I2

tag_inner_PROPVARIANT.caui

| VT_VECTORVT_UI2

tag_inner_PROPVARIANT.cal

| VT_VECTORVT_I4

tag_inner_PROPVARIANT.caul

| VT_VECTORVT_UI4

tag_inner_PROPVARIANT.cah

| VT_VECTORVT_I8

tag_inner_PROPVARIANT.cauh

| VT_VECTORVT_UI8

tag_inner_PROPVARIANT.caflt

| VT_VECTORVT_R4

tag_inner_PROPVARIANT.cadbl

| VT_VECTORVT_R8

tag_inner_PROPVARIANT.cabool

| VT_VECTORVT_BOOL

tag_inner_PROPVARIANT.cascode

| VT_VECTORVT_ERROR

tag_inner_PROPVARIANT.cacy

| VT_VECTORVT_CY

tag_inner_PROPVARIANT.cadate

| VT_VECTORVT_DATE

tag_inner_PROPVARIANT.cafiletime

| VT_VECTORVT_FILETIME

tag_inner_PROPVARIANT.cauuid

| VT_VECTORVT_CLSID

tag_inner_PROPVARIANT.caclipdata

| VT_VECTORVT_CF

tag_inner_PROPVARIANT.cabstr

| VT_VECTORVT_BSTR

tag_inner_PROPVARIANT.cabstrblob

| VT_VECTORVT_BSTR

tag_inner_PROPVARIANT.calpstr

| VT_VECTORVT_LPSTR

tag_inner_PROPVARIANT.calpwstr

| VT_VECTORVT_LPWSTR

tag_inner_PROPVARIANT.capropvar

| VT_VECTORVT_VARIANT

tag_inner_PROPVARIANT.pcVal

| VT_BYREFVT_I1 версии 1

tag_inner_PROPVARIANT.pbVal

| VT_BYREFVT_UI1, версия 1

tag_inner_PROPVARIANT.piVal

| VT_BYREFVT_I2, версия 1

tag_inner_PROPVARIANT.puiVal

| VT_BYREFVT_UI2, версия 1

tag_inner_PROPVARIANT.plVal

| VT_BYREFVT_I4, версия 1

tag_inner_PROPVARIANT.pulVal

| VT_BYREFVT_UI4, версия 1

tag_inner_PROPVARIANT.pintVal

| VT_BYREFVT_INT, версия 1

tag_inner_PROPVARIANT.puintVal

| VT_BYREFVT_UINT, версия 1

tag_inner_PROPVARIANT.pfltVal

| VT_BYREFVT_R4 версии 1

tag_inner_PROPVARIANT.pdblVal

| VT_BYREFVT_R8, версия 1

tag_inner_PROPVARIANT.pboolVal

| VT_BYREFVT_R8, версия 1

tag_inner_PROPVARIANT.pdecVal

| VT_BYREFVT_DECIMAL, версия 1

tag_inner_PROPVARIANT.pscode

| VT_BYREFVT_ERROR, версия 1

tag_inner_PROPVARIANT.pcyVal

| VT_BYREFVT_CY, версия 1

tag_inner_PROPVARIANT.pdate

| VT_BYREFVT_DATE версии 1

tag_inner_PROPVARIANT.pbstrVal

| VT_BYREFVT_BSTR, версия 1

tag_inner_PROPVARIANT.ppunkVal

| VT_BYREFVT_UNKNOWN, версия 1

tag_inner_PROPVARIANT.ppdispVal

| VT_BYREFVT_DISPATCH, версия 1

tag_inner_PROPVARIANT.pparray

| VT_BYREFVT_DISPATCH, версия 1

tag_inner_PROPVARIANT.pvarVal

| VT_BYREFVT_VARIANT, версия 1

decVal

| VT_BYREFVT_DECIMAL, версия 1

Комментарии

Структура PROPVARIANT также может содержать значение VT_DECIMAL:

    DECIMAL       decVal;        //VT_DECIMAL

Однако значение структуры DECIMAL требует специальной обработки. Структура DECIMAL имеет тот же размер, что и вся структура PROPVARIANT , и не вписывается в объединение, в котором содержатся все остальные типы значений. Вместо этого значение структуры DECIMAL занимает всю структуру PROPVARIANT , включая зарезервированные поля и член vt . Однако первый элемент структуры DECIMAL не используется и по размеру равен члену vt структуры PROPVARIANT . Поэтому объявление структуры PROPVARIANT в файле заголовка Propidl.h Win32 определяет элемент decVal таким образом, чтобы он соответствовал началу структуры PROPVARIANT . Таким образом, чтобы поместить значение структуры DECIMAL в структуру PROPVARIANT , значение должно быть загружено в элемент decVal , а для элемента vt задано значение VT_DECIMAL, как и для любого другого значения.

PROPVARIANT — это базовый тип данных, с помощью которого значения свойств считываются и записываются через интерфейс IPropertyStorage .

Тип данных PROPVARIANT связан с типом данных VARIANT, определенным как часть автоматизации в OLE2. Несколько определений повторно используются из службы автоматизации следующим образом:

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;

Кроме того, некоторые типы являются уникальными для структуры 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;

Среди уникальных типов PROPVARIANT есть несколько типов данных, которые определяют подсчитываемые массивы других типов данных. Типы данных всех подсчитываемых массивов начинаются с букв ЦС, например CAUB, и имеют значение оператора ORvt (VarType элемента и оператор OR с VT_VECTOR). Структура подсчитываемого массива имеет следующую форму (где name — это конкретное имя подсчитываемого массива).

#define TYPEDEF_CA(type, name) 
 
    typedef struct tag ## name {\
        ULONG cElems;\
        type *pElems;\
        } name
Тип propvariant Код Элемент Propvariant Представление значения
VT_EMPTY 0 None Свойство с индикатором типа VT_EMPTY не имеет связанных с ним данных; то есть размер значения равен нулю.
VT_NULL 1 None Это похоже на указатель на NULL.
VT_I1 16 cVal 1-байтовое целое число со знаком.
VT_UI1 17 bVal 1-байтовое целое число без знака.
VT_I2 2 iVal Два байта, представляющие 2-байтовое целое число со знаком.
VT_UI2 18 uiVal 2-байтовое целое число без знака.
VT_I4 3 lVal 4-байтовое целое число со знаком.
VT_UI4 19 Ulval 4-байтовое целое число без знака.
VT_INT 22 intVal 4-байтовое целое число со знаком ( эквивалентно VT_I4).
VT_UINT 23 uintVal 4-байтовое целое число без знака ( эквивалентно VT_UI4).
VT_I8 20 hVal 8-байтовое целое число со знаком.
VT_UI8 21 uhVal 8-байтовое целое число без знака.
VT_R4 4 fltVal 32-разрядное значение с плавающей запятой IEEE.
VT_R8 5 dblVal 64-разрядное значение с плавающей запятой IEEE.
VT_BOOL 11 boolVal (bool в более ранних версиях) Логическое значение, слово WORD , содержащее 0 (FALSE) или -1 (TRUE).
VT_ERROR 10 scode DWORD, содержащий код состояния.
VT_CY 6 cyVal 8-байтовое целое число дополнения двух (масштабируется на 10 000). Этот тип обычно используется для денежных сумм.
VT_DATE 7 date 64-разрядное число с плавающей запятой, представляющее количество дней (не секунд) с 31 декабря 1899 года. Например, 1 января 1900 г. — 2,0, 2 января 1900 г., — 3,0 и т. д.). Он хранится в том же представлении, что и VT_R8.
VT_FILETIME 64 Filetime 64-разрядная структура FILETIME , определенная в Win32. Рекомендуется хранить все время в формате UTC.
VT_CLSID 72 пууид Указатель на идентификатор класса (CLSID) (или другой глобальный уникальный идентификатор (GUID)).
VT_CF 71 pclipdata Указатель на структуру CLIPDATA , описанную выше.
VT_BSTR 8 bstrVal Указатель на строку Юникода, завершаемую null. Строке непосредственно предшествует DWORD , представляющее число байтов, но bstrVal указывает после этого DWORD на первый символ строки. BSTRдолжны быть выделены и освобождены с помощью вызовов SysAllocString и SysFreeString службы автоматизации.
VT_BSTR_BLOB 0xfff bstrblobVal Только для системного использования.
VT_BLOB 65 BLOB-объект Число DWORD в байтах, за которым следует это количество байтов данных. Число байтов не включает четыре байта для длины самого счетчика; Пустой член большого двоичного объекта будет иметь ноль, за которым следует ноль байтов. Это похоже на значение VT_BSTR, но не гарантирует нулевой байт в конце данных.
VT_BLOBOBJECT 70 BLOB-объект Большой двоичный объект, содержащий сериализованный объект в том же представлении, которое будет отображаться в VT_STREAMED_OBJECT. То есть число байтов DWORD (где число байтов не включает сам размер), которое имеет формат идентификатора класса, за которым следуют данные инициализации для этого класса.

Единственное существенное различие между VT_BLOB_OBJECT и VT_STREAMED_OBJECT заключается в том, что первый из них не имеет накладных расходов на хранилище на уровне системы, что и, следовательно, больше подходит для сценариев с количеством небольших объектов.

VT_LPSTR 30 pszVal Указатель на строку ANSI, завершаемую null, на системной кодовой странице по умолчанию.
VT_LPWSTR 31 pwszVal Указатель на строку Юникода, завершаемую null, в пользовательском языковом стандарте по умолчанию.
VT_UNKNOWN 13 punkVal Новый.
VT_DISPATCH 9 pdispVal Новый.
VT_STREAM 66 pStream Указатель на интерфейс IStream , представляющий поток, который является одноуровневым для потока Contents.
VT_STREAMED_OBJECT 68 pStream Как и в VT_STREAM, но указывает, что поток содержит сериализованный объект, который является идентификатором CLSID, за которым следуют данные инициализации для класса . Поток является одноуровневой для потока Contents, который содержит набор свойств.
VT_STORAGE 67 pStorage Указатель на интерфейс IStorage , представляющий объект хранилища, который является одноуровневым элементом потока Contents.
VT_STORED_OBJECT 69 pStorage Как и в VT_STORAGE, но указывает, что указанный IStorage содержит загружаемый объект.
VT_VERSIONED_STREAM 73 pVersionedStream Поток с версией GUID.
VT_DECIMAL 14 decVal Структура DECIMAL .
VT_VECTOR 0x1000 Ca* Если индикатор типа объединяется с VT_VECTOR с помощью оператора OR , значением является одно из подсчитываемых значений массива. При этом создается число элементов DWORD , за которым следует указатель на указанные повторения значения.

Например, индикатор типа VT_LPSTR|VT_VECTOR содержит число элементов DWORD , за которым следует указатель на массив элементов LPSTR .

VT_VECTOR можно объединить с помощью оператора OR со следующими типами: 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 и VT_VARIANT. VT_VECTOR также можно объединить с помощью операции OR с VT_BSTR_BLOB, но только для системного использования.

VT_ARRAY 0x2000 Паррей Если индикатор типа сочетается с VT_ARRAY оператором OR , значение является указателем на SAFEARRAY. VT_ARRAY можно использовать OR со следующими типами данных: 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 и VT_VARIANT. VT_ARRAY нельзя использовать OR с VT_VECTOR.
VT_BYREF 0x4000 P* Если индикатор типа объединяется с VT_BYREF оператором OR , значением является ссылка. Ссылочные типы интерпретируются как ссылка на данные, как и ссылочный тип в C++ (например, "int&").

VT_BYREF можно использовать OR со следующими типами: 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 и VT_VARIANT.

VT_VARIANT 12 капропвар Индикатор типа DWORD , за которым следует соответствующее значение. VT_VARIANT можно использовать только с VT_VECTOR или VT_BYREF.
VT_TYPEMASK 0xFFF   Используется в качестве маски для VT_VECTOR и других модификаторов для извлечения необработанного значения VT.
 

Идентификаторы формата буфера обмена, хранящиеся с тегом VT_CF, используют одно из пяти представлений, определенных в элементе ulClipFmt структуры CLIPDATA с помощью указателя pClipData на конкретный тип данных.

Значение ulClipFmt Значение pClipData
-1L DWORD, содержащий значение встроенного формата буфера обмена Windows.
-2L Значение DWORD, содержащее значение формата буфера обмена Macintosh.
-3L Идентификатор GUID, содержащий идентификатор формата (FMTID). Используется редко.
любое положительное значение Строка, завершающаяся значением NULL, которая содержит имя формата буфера обмена Windows, которое подходит для передачи в функцию RegisterClipboardFormat . Эта функция регистрирует новый формат буфера обмена. Если зарегистрированный формат с указанным именем уже существует, новый формат не регистрируется, а возвращаемое значение определяет существующий формат. Это позволяет нескольким приложениям копировать и вставлять данные, используя один и тот же зарегистрированный формат буфера обмена. Сравнение имен форматов не учитывает регистр и определяется значениями в диапазоне от 0xC000 до 0xFFFF. Кодовая страница, используемая для символов в строке, соответствует индикатору кодовой страницы. Здесь "положительное значение" — это длина строки, включая пустой байт в конце. Когда форматы буфера обмена регистра помещаются в буфер обмена или извлекаются из этого буфера, они должны иметь вид значения типа данных HGLOBAL , которое предоставляет дескриптор для объекта .
0L Нет данных (редко используются).
 

Если значение элемента ulClipFmt равно -1, данные имеют вид встроенного формата Windows. В этом случае первым DWORD буфера, на который указывает pClipData , является идентификатор формата буфера обмена, например CF_METAFILEPICT. В случае CF_METAFILEPCT ниже приведен вариант структуры METAFILEPICT (в ней используются типы данных WORD, а не DWORD ). То есть эти данные представлены в следующей форме:

struct PACKEDMETA
{
    WORD mm;
    WORD xExt;
    WORD yExt
    WORD reserved;
};

После структуры METAFILEPICT есть данные метафайла, подходящие для передачи в функцию SetMetaFileBitsEx . Эта функция создает метафайл в формате Windows на основе памяти из предоставленных данных. Эта функция предоставляется для совместимости с 16-разрядными версиями Windows. Приложения на основе Win32 должны использовать функцию SetEnhMetaFileBits . Эта функция извлекает содержимое указанного метафайла расширенного формата и копирует его в буфер. Если функция выполняется успешно и указатель буфера имеет значение NULL, возвращаемое значение — это размер расширенного метафайла в байтах. Если функция выполняется успешно и указатель буфера является допустимым указателем, возвращаемым значением будет количество байтов, скопированных в буфер. Если функция выполняется неудачно, возвращается нулевое значение.

Если форматы буфера обмена регистра помещаются в буфер обмена или извлекаются из этого буфера, они должны иметь вид значения HGLOBAL .

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Профессиональная [классические приложения | Приложения UWP]
Минимальная версия сервера Windows 2000 Server [классические приложения | Приложения UWP]
Верхняя часть propidl.h (включая Propidl.h)