Estructura PROPVARIANT (propidlbase.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
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
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 manera 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 los valores de propiedad se leen y escriben 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 exclusivos de 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 hay varios tipos de datos que definen matrices contadas 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 or operator vt (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 de valores |
|---|---|---|---|
| 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 sin signo de 4 bytes. |
| 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 tanto, es más adecuado para escenarios que implican el número 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 los datos de inicialización de la clase . La secuencia es un elemento relacionado con la secuencia "Contents" que contiene el conjunto de propiedades. |
| VT_STORAGE | 67 | pStorage | Puntero a una interfaz IStorage , que representa un objeto de almacenamiento relacionado con la secuencia "Contents". |
| 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 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 un operador OR combina el indicador de tipo con VT_BYREF, el valor es una referencia. Los tipos de referencia se interpretan como una referencia a los datos, de forma similar al tipo de referencia de 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 formato. |
Los identificadores de formato del Portapapeles, almacenados con la etiqueta VT_CF, usan una de las cinco representaciones identificadas en el miembro ulClipFmt de la estructura CLIPDATA mediante el puntero pClipData al tipo de datos concreto.
| valor ulClipFmt | Valor de pClipData |
|---|---|
| -1L | DWORD que contiene un valor de formato integrado del Portapapeles de Windows. |
| -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 del intervalo de 0xC000 a 0xFFFF. La página de códigos utilizada 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 la 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 de Windows integrado. 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 la forma siguiente:
struct PACKEDMETA
{
WORD mm;
WORD xExt;
WORD yExt
WORD reserved;
};
Después de que la estructura METAFILEPICT sea los datos del metarchivo, adecuado 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 por 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 | propidlbase.h (include Propidl.h) |
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de