Estructura PROPVARIANT (propidl.h)
La estructura PROPVARIANT se usa en los métodos ReadMultiple y WriteMultiple de IPropertyStorage para definir la etiqueta de tipo y el valor de una propiedad en un conjunto de propiedades.
La estructura PROPVARIANT también se usa en los métodos GetValue y SetValue de IPropertyStore, que reemplaza A IPropertySetStorage como la forma principal de programar propiedades de elemento en Windows Vista. Para obtener más información, vea Controladores de propiedades.
Hay cinco miembros. El primer miembro, la etiqueta de tipo de valor y el último miembro, el valor de la propiedad, son significativos. Los tres miembros intermedios están reservados para uso futuro.
Sintaxis
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;
Miembros
tag_inner_PROPVARIANT
tag_inner_PROPVARIANT.vt
Etiqueta de tipo de valor.
tag_inner_PROPVARIANT.wReserved1
Reservado para un uso futuro.
tag_inner_PROPVARIANT.wReserved2
Reservado para un uso futuro.
tag_inner_PROPVARIANT.wReserved3
Reservado para un uso futuro.
tag_inner_PROPVARIANT.cVal
VT_I1, versión 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, versión 1
tag_inner_PROPVARIANT.uintVal
VT_UINT, versión 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, versión 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_*, versión 1
tag_inner_PROPVARIANT.cac
| VT_VECTORVT_I1, versión 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, versión 1
tag_inner_PROPVARIANT.pbVal
| VT_BYREFVT_UI1, versión 1
tag_inner_PROPVARIANT.piVal
| VT_BYREFVT_I2, versión 1
tag_inner_PROPVARIANT.puiVal
| VT_BYREFVT_UI2, versión 1
tag_inner_PROPVARIANT.plVal
| VT_BYREFVT_I4, versión 1
tag_inner_PROPVARIANT.pulVal
| VT_BYREFVT_UI4, versión 1
tag_inner_PROPVARIANT.pintVal
| VT_BYREFVT_INT, versión 1
tag_inner_PROPVARIANT.puintVal
| VT_BYREFVT_UINT, versión 1
tag_inner_PROPVARIANT.pfltVal
| VT_BYREFVT_R4, versión 1
tag_inner_PROPVARIANT.pdblVal
| VT_BYREFVT_R8, versión 1
tag_inner_PROPVARIANT.pboolVal
| VT_BYREFVT_R8, versión 1
tag_inner_PROPVARIANT.pdecVal
| VT_BYREFVT_DECIMAL, versión 1
tag_inner_PROPVARIANT.pscode
| VT_BYREFVT_ERROR, versión 1
tag_inner_PROPVARIANT.pcyVal
| VT_BYREFVT_CY, versión 1
tag_inner_PROPVARIANT.pdate
| VT_BYREFVT_DATE, versión 1
tag_inner_PROPVARIANT.pbstrVal
| VT_BYREFVT_BSTR, versión 1
tag_inner_PROPVARIANT.ppunkVal
| VT_BYREFVT_UNKNOWN, versión 1
tag_inner_PROPVARIANT.ppdispVal
| VT_BYREFVT_DISPATCH, versión 1
tag_inner_PROPVARIANT.pparray
| VT_BYREFVT_DISPATCH, versión 1
tag_inner_PROPVARIANT.pvarVal
| VT_BYREFVT_VARIANT, versión 1
decVal
| VT_BYREFVT_DECIMAL, versión 1
Comentarios
La estructura PROPVARIANT también puede contener un valor de VT_DECIMAL:
DECIMAL decVal; //VT_DECIMAL
Sin embargo, el valor de la estructura DECIMAL requiere un control especial. La estructura DECIMAL tiene el mismo tamaño que una estructura PROPVARIANT completa y no cabe en la unión que contiene todos los demás tipos de valores. En su lugar, el valor de la estructura DECIMAL ocupa toda la estructura PROPVARIANT , incluidos los campos reservados y el miembro vt . Sin embargo, el primer miembro de la estructura DECIMAL no se usa y es igual de tamaño al miembro vt de la estructura PROPVARIANT . Por lo tanto, la declaración de estructura PROPVARIANT en el archivo de encabezado Propidl.h de Win32 define el miembro decVal de tal forma que corresponde al principio de la estructura PROPVARIANT . Por lo tanto, para colocar el valor de la estructura DECIMAL en una estructura PROPVARIANT , el valor debe cargarse en el miembro decVal y el miembro vt se establece en VT_DECIMAL, igual que para cualquier otro valor.
PROPVARIANT es el tipo de datos fundamental por el que se leen y escriben los valores de propiedad a través de la interfaz IPropertyStorage .
El tipo de datos PROPVARIANT está relacionado con el tipo de datos VARIANT, definido como parte de Automation en OLE2. Se reutilizan varias definiciones de Automation, como se indica a continuación:
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;
Además, algunos tipos son únicos para la estructura 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;
Entre los tipos PROPVARIANT únicos se encuentran varios tipos de datos que definen matrices con recuento de otros tipos de datos. Los tipos de datos de todas las matrices contadas comienzan con las letras CA, por ejemplo CAUB, y tienen un valor de operador ORvt (varType del elemento y un operador OR con VT_VECTOR). La estructura de matriz con recuento tiene el siguiente formato (donde name es el nombre específico de la matriz con recuento).
#define TYPEDEF_CA(type, name)
typedef struct tag ## name {\
ULONG cElems;\
type *pElems;\
} name
| Tipo propvariante | Código | Miembro propvariante | Representación del valor |
|---|---|---|---|
| VT_EMPTY | 0 | None | Una propiedad con un indicador de tipo de VT_EMPTY no tiene datos asociados a ella; es decir, el tamaño del valor es cero. |
| VT_NULL | 1 | None | Esto es como un puntero a NULL. |
| VT_I1 | 16 | cVal | Entero con signo de 1 byte. |
| VT_UI1 | 17 | bVal | Entero sin signo de 1 byte. |
| VT_I2 | 2 | iVal | Dos bytes que representan un valor entero con signo de 2 bytes. |
| VT_UI2 | 18 | uiVal | Entero sin signo de 2 bytes. |
| VT_I4 | 3 | lVal | Valor entero con signo de 4 bytes. |
| VT_UI4 | 19 | ulVal | Entero de 4 bytes sin signo. |
| VT_INT | 22 | intVal | Valor entero con signo de 4 bytes (equivalente a VT_I4). |
| VT_UINT | 23 | uintVal | Entero sin signo de 4 bytes (equivalente a VT_UI4). |
| VT_I8 | 20 | hVal | Entero con signo de 8 bytes. |
| VT_UI8 | 21 | uhVal | Entero sin signo de 8 bytes. |
| VT_R4 | 4 | fltVal | Valor de punto flotante IEEE de 32 bits. |
| VT_R8 | 5 | dblVal | Valor de punto flotante IEEE de 64 bits. |
| VT_BOOL | 11 | boolVal (bool en diseños anteriores) | Valor booleano, una PALABRA que contiene 0 (FALSE) o -1 (TRUE). |
| VT_ERROR | 10 | scode | DWORD que contiene un código de estado. |
| VT_CY | 6 | cyVal | Entero complementario de dos bytes de 8 bytes (escalado en 10 000). Este tipo se usa normalmente para importes de moneda. |
| VT_DATE | 7 | date | Número de punto flotante de 64 bits que representa el número de días (no segundos) desde el 31 de diciembre de 1899. Por ejemplo, el 1 de enero de 1900, es 2.0, 2 de enero de 1900, es 3.0, etc. Se almacena en la misma representación que VT_R8. |
| VT_FILETIME | 64 | filetime | Estructura FILETIME de 64 bits definida por Win32. Se recomienda almacenar todas las veces en hora universal de coordenadas (UTC). |
| VT_CLSID | 72 | puuid | Puntero a un identificador de clase (CLSID) (u otro identificador único global (GUID)). |
| VT_CF | 71 | pclipdata | Puntero a una estructura CLIPDATA , descrita anteriormente. |
| VT_BSTR | 8 | bstrVal | Puntero a una cadena Unicode terminada en null. La cadena va precedida inmediatamente por un DWORD que representa el recuento de bytes, pero bstrVal apunta más allá de este DWORD al primer carácter de la cadena. BSTRdebe asignarse y liberarse mediante las llamadas SysAllocString y SysFreeString de Automation. |
| VT_BSTR_BLOB | 0xfff | bstrblobVal | Solo para uso del sistema. |
| VT_BLOB | 65 | blob | Recuento de bytes DWORD, seguido de muchos bytes de datos. El recuento de bytes no incluye los cuatro bytes para la longitud del propio recuento; un miembro de blob vacío tendría un recuento de cero, seguido de cero bytes. Esto es similar al valor VT_BSTR, pero no garantiza un byte nulo al final de los datos. |
| VT_BLOBOBJECT | 70 | blob | Miembro de blob que contiene un objeto serializado en la misma representación que aparecería en VT_STREAMED_OBJECT. Es decir, un recuento de bytes DWORD (donde el recuento de bytes no incluye el tamaño de sí mismo), que tiene el formato de un identificador de clase seguido de los datos de inicialización de esa clase.
La única diferencia significativa entre VT_BLOB_OBJECT y VT_STREAMED_OBJECT es que el primero no tiene la sobrecarga de almacenamiento de nivel de sistema que tendría este último y, por lo tanto, es más adecuado para escenarios que implican números de objetos pequeños. |
| VT_LPSTR | 30 | pszVal | Puntero a una cadena ANSI terminada en null en la página de códigos predeterminada del sistema. |
| VT_LPWSTR | 31 | pwszVal | Puntero a una cadena Unicode terminada en null en la configuración regional predeterminada del usuario. |
| VT_UNKNOWN | 13 | punkVal | Nuevo. |
| VT_DISPATCH | 9 | pdispVal | Nuevo. |
| VT_STREAM | 66 | pStream | Puntero a una interfaz IStream que representa una secuencia que es un elemento relacionado con la secuencia "Contenido". |
| VT_STREAMED_OBJECT | 68 | pStream | Como en VT_STREAM, pero indica que la secuencia contiene un objeto serializado, que es un CLSID seguido de datos de inicialización para la clase . La secuencia es un elemento relacionado con la secuencia "Contenido" que contiene el conjunto de propiedades. |
| VT_STORAGE | 67 | pStorage | Puntero a una interfaz IStorage , que representa un objeto de almacenamiento que es un elemento relacionado con la secuencia "Contenido". |
| VT_STORED_OBJECT | 69 | pStorage | Como en VT_STORAGE, pero indica que el IStorage designado contiene un objeto cargable. |
| VT_VERSIONED_STREAM | 73 | pVersionedStream | Secuencia con una versión guid. |
| VT_DECIMAL | 14 | decVal | Estructura DECIMAL . |
| VT_VECTOR | 0x1000 | Ca* | Si el indicador de tipo se combina con VT_VECTOR mediante un operador OR , el valor es uno de los valores de matriz contados. Esto crea un recuento DWORD de elementos, seguido de un puntero a las repeticiones especificadas del valor.
Por ejemplo, un indicador de tipo de VT_LPSTR VT_VECTOR| tiene un recuento de elementos DWORD, seguido de un puntero a una matriz de elementos LPSTR. VT_VECTOR puede combinarse mediante un operador OR con los siguientes tipos: 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_LPWSTRy VT_VARIANT. VT_VECTOR también se puede combinar mediante una operación OR con VT_BSTR_BLOB, pero solo es para uso del sistema. |
| VT_ARRAY | 0x2000 | Parray | Si un operador OR combina el indicador de tipo con VT_ARRAY, el valor es un puntero a SAFEARRAY. VT_ARRAY puede usar el or con los siguientes tipos de datos: 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 y VT_VARIANT. VT_ARRAY no puede usar OR con VT_VECTOR. |
| VT_BYREF | 0x4000 | P* | Si el indicador de tipo se combina con VT_BYREF por un operador OR , el valor es una referencia. Los tipos de referencia se interpretan como una referencia a los datos, de forma similar al tipo de referencia en C++ (por ejemplo, "int&").
VT_BYREF puede usar OR con los siguientes tipos: 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 y VT_VARIANT. |
| VT_VARIANT | 12 | capropvar | Indicador de tipo DWORD seguido del valor correspondiente. VT_VARIANT solo se puede usar con VT_VECTOR o VT_BYREF. |
| VT_TYPEMASK | 0xFFF | Se usa como máscara para VT_VECTOR y otros modificadores para extraer el valor de VT sin procesar. |
Los identificadores de formato del Portapapeles, almacenados con la etiqueta VT_CF, usan una de cinco representaciones, identificadas en el miembro ulClipFmt de la estructura CLIPDATA mediante el puntero pClipData al tipo de datos determinado.
| valor ulClipFmt | Valor de pClipData |
|---|---|
| -1L | DWORD que contiene un valor de formato de Portapapeles de Windows integrado. |
| -T2l | DWORD que contiene un valor de formato de Portapapeles de Macintosh. |
| -3L | GUID que contiene un identificador de formato (FMTID). Esto rara vez se usa. |
| cualquier valor positivo | Cadena terminada en null que contiene un nombre de formato de Portapapeles de Windows, uno adecuado para pasar a la función RegisterClipboardFormat . Esta función registra un nuevo formato de Portapapeles. Si ya existe un formato registrado con el nombre especificado, no se registra un nuevo formato y el valor devuelto identifica el formato existente. Esto permite que más de una aplicación copie y pegue datos con el mismo formato de Portapapeles registrado. La comparación de nombres de formato no distingue mayúsculas de minúsculas y se identifica mediante valores en el intervalo de 0xC000 a través de 0xFFFF. La página de códigos usada para los caracteres de la cadena se basa en el indicador de página de códigos. El "valor positivo" aquí es la longitud de cadena, incluido el byte nulo al final. Cuando los formatos del Portapapeles de registro se colocan en el Portapapeles o se recuperan del Portapapeles, deben estar en forma de un valor de tipo de datos HGLOBAL , que proporciona el identificador al objeto. |
| 0L | No hay datos (rara vez usados). |
Si el valor del miembro ulClipFmt es -1, los datos tienen el formato de un formato integrado de Windows. En este caso, el primer DWORD del búfer al que apunta pClipData es el identificador de formato del Portapapeles, por ejemplo, CF_METAFILEPICT. En el caso de CF_METAFILEPCT, lo siguiente es una variación en la estructura METAFILEPICT (usa WORD, en lugar de tipos de datos DWORD ). Es decir, estos datos están en el siguiente formato:
struct PACKEDMETA
{
WORD mm;
WORD xExt;
WORD yExt
WORD reserved;
};
Después de que la estructura METAFILEPICT sea los datos del metarchivo, adecuados para pasarse a la función SetMetaFileBitsEx . Esta función crea un metarchivo de formato Windows basado en memoria a partir de los datos proporcionados. Esta función se proporciona para la compatibilidad con versiones de 16 bits de Windows. Las aplicaciones basadas en Win32 deben usar la función SetEnhMetaFileBits . Esta función recupera el contenido del metarchivo de formato mejorado especificado y los copia en un búfer. Si la función se ejecuta correctamente y el puntero del búfer es NULL, el valor devuelto es el tamaño del metarchivo mejorado en bytes. Si la función se ejecuta correctamente y el puntero del búfer es un puntero válido, el valor devuelto es el número de bytes copiados en el búfer. Si la función no se realiza correctamente, el valor devuelto es cero.
Cuando los formatos del Portapapeles de registro se colocan en el Portapapeles o se recuperan del Portapapeles, deben estar en forma de un valor HGLOBAL .
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP] |
| Encabezado | propidl.h (include Propidl.h) |