Структура PROPVARIANT (propidl.h)
Структура PROPVARIANT используется в методах ReadMultiple и WriteMultipleiPropertyStorage для определения тега типа и значения свойства в наборе свойств.
Структура PROPVARIANT также используется методами GetValue и SetValueiPropertyStore, который заменяет IPropertySetStorage в качестве основного способа программирования свойств элементов в Windows Vista. Дополнительные сведения см. в разделе Обработчики свойств.
Есть пять членов. Первый элемент, тег типа значения и последний элемент, значение свойства, являются значимыми. Средние три элемента зарезервированы для использования в будущем.
Синтаксис
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) |