Compartir a través de


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.

Nota El miembro bool de las definiciones anteriores de esta estructura se ha cambiado a boolVal, porque algunos compiladores ahora reconocen bool como palabra clave.
 
Nota La estructura PROPVARIANT , definida a continuación, incluye tipos que se pueden serializar en el formato de serialización del conjunto de propiedades de la versión 1. El formato de la versión 1 admite todos los tipos permitidos en el formato de la versión 0 más algunos tipos adicionales. Los tipos agregados incluyen "Versión 1" en el campo de comentario siguiente. Use estos tipos solo si está previsto un conjunto de propiedades de la versión 1. Para obtener más información, vea Serialización del conjunto de propiedades.
 
La estructura PROPVARIANT se define de la siguiente manera:

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)