Структура PROPVARIANT (propidlbase.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
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
Комментарии
Структура 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 может использовать ИЛИ со следующими типами данных: 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] |
| Верхняя часть | propidlbase.h (включая Propidl.h) |