Compartilhar via


Estrutura PROPVARIANT (propidlbase.h)

A estrutura PROPVARIANT é usada nos métodos ReadMultiple e WriteMultiple de IPropertyStorage para definir a marca de tipo e o valor de uma propriedade em um conjunto de propriedades.

A estrutura PROPVARIANT também é usada pelos métodos GetValue e SetValue de IPropertyStore, que substitui IPropertySetStorage como a principal maneira de programar propriedades de item no Windows Vista. Para obter mais informações, consulte Manipuladores de propriedade.

Há cinco membros. O primeiro membro, a marca de tipo de valor e o último membro, o valor da propriedade, são significativos. Os três membros do meio são reservados para uso futuro.

Nota O membro bool nas definições anteriores dessa estrutura foi renomeado para boolVal, pois alguns compiladores agora reconhecem bool como um palavra-chave.
 
Nota A estrutura PROPVARIANT , definida abaixo, inclui tipos que podem ser serializados no formato de serialização do conjunto de propriedades da versão 1. O formato versão 1 dá suporte a todos os tipos permitidos no formato versão 0, além de alguns tipos adicionais. Os tipos adicionados incluem "Versão 1" no campo de comentário abaixo. Use esses tipos somente se um conjunto de propriedades da versão 1 for pretendido. Para obter mais informações, consulte Serialização do conjunto de propriedades.
 
A estrutura PROPVARIANT é definida da seguinte maneira:

Sintaxe

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;

Membros

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

Comentários

A estrutura PROPVARIANT também pode conter um valor de VT_DECIMAL:

    DECIMAL       decVal;        //VT_DECIMAL

No entanto, o valor da estrutura DECIMAL requer tratamento especial. A estrutura DECIMAL tem o mesmo tamanho de uma estrutura PROPVARIANT inteira e não se encaixa na união que contém todos os outros tipos de valores. Em vez disso, o valor da estrutura DECIMAL ocupa toda a estrutura PROPVARIANT , incluindo os campos reservados e o membro vt . No entanto, o primeiro membro da estrutura DECIMAL não é usado e é igual ao membro vt da estrutura PROPVARIANT . Portanto, a declaração de estrutura PROPVARIANT no arquivo de cabeçalho Propidl.h do Win32 define o membro decVal de forma que corresponda ao início da estrutura PROPVARIANT . Portanto, para colocar o valor da estrutura DECIMAL em uma estrutura PROPVARIANT , o valor deve ser carregado no membro decVal e o membro vt é definido como VT_DECIMAL, assim como para qualquer outro valor.

PROPVARIANT é o tipo de dados fundamental pelo qual os valores de propriedade são lidos e gravados por meio da interface IPropertyStorage .

O tipo de dados PROPVARIANT está relacionado ao tipo de dados VARIANT, definido como parte da Automação no OLE2. Várias definições são reutilizados da Automação, da seguinte maneira:

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;

Além disso, alguns tipos são exclusivos da estrutura 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 os tipos PROPVARIANT exclusivos estão vários tipos de dados que definem matrizes contadas de outros tipos de dados. Os tipos de dados de todas as matrizes contadas começam com as letras CA, por exemplo, CAUB, e têm um valor vt do operador OR (o VarType do elemento e um operador OR com VT_VECTOR). A estrutura da matriz contada tem o seguinte formato (em que name é o nome específico da matriz contada).

#define TYPEDEF_CA(type, name) 
 
    typedef struct tag ## name {\
        ULONG cElems;\
        type *pElems;\
        } name
Tipo propvariante Código Membro propvariante Representação de valor
VT_EMPTY 0 Nenhum Uma propriedade com um indicador de tipo de VT_EMPTY não tem dados associados a ela; ou seja, o tamanho do valor é zero.
VT_NULL 1 Nenhum Isso é como um ponteiro para NULL.
VT_I1 16 cVal Inteiro com sinal de 1 byte.
VT_UI1 17 bVal Inteiro sem sinal de 1 byte.
VT_I2 2 iVal Dois bytes que representam um valor inteiro com sinal de 2 bytes.
VT_UI2 18 uiVal Inteiro sem sinal de 2 bytes.
VT_I4 3 lVal Valor inteiro com sinal de 4 bytes.
VT_UI4 19 ulVal Inteiro sem sinal de 4 bytes.
VT_INT 22 intVal Valor inteiro com sinal de 4 bytes (equivalente a VT_I4).
VT_UINT 23 uintVal Inteiro sem sinal de 4 bytes (equivalente a VT_UI4).
VT_I8 20 hVal Inteiro com sinal de 8 bytes.
VT_UI8 21 uhVal Inteiro sem sinal de 8 bytes.
VT_R4 4 fltVal Valor de ponto flutuante IEEE de 32 bits.
VT_R8 5 dblVal Valor de ponto flutuante IEEE de 64 bits.
VT_BOOL 11 boolVal (bool em designs anteriores) Valor booliano, um WORD que contém 0 (FALSE) ou -1 (TRUE).
VT_ERROR 10 scode Um DWORD que contém um código status.
VT_CY 6 cyVal Inteiro de complemento de dois bytes de 8 bytes (dimensionado em 10.000). Esse tipo é comumente usado para valores de moeda.
VT_DATE 7 date Um número de ponto flutuante de 64 bits que representa o número de dias (não segundos) desde 31 de dezembro de 1899. Por exemplo, 1º de janeiro de 1900 é 2,0, 2 de janeiro de 1900, é 3,0 e assim por diante). Isso é armazenado na mesma representação que VT_R8.
VT_FILETIME 64 filetime Estrutura FILETIME de 64 bits, conforme definido pelo Win32. É recomendável que todas as vezes sejam armazenadas em UTC (Tempo de Coordenada Universal).
VT_CLSID 72 puuid Ponteiro para um CLSID (identificador de classe) (ou outro GUID (identificador global exclusivo)).
VT_CF 71 pclipdata Ponteiro para uma estrutura CLIPDATA , descrita acima.
VT_BSTR 8 bstrVal Ponteiro para uma cadeia de caracteres Unicode terminada em nulo. A cadeia de caracteres é imediatamente precedida por um DWORD que representa a contagem de bytes, mas bstrVal aponta além desse DWORD para o primeiro caractere da cadeia de caracteres. OS BSTRsdevem ser alocados e liberados usando as chamadas SysAllocString e SysFreeString de Automação.
VT_BSTR_BLOB 0xfff bstrblobVal Somente para uso do sistema.
VT_BLOB 65 blob Contagem DWORD de bytes, seguida por muitos bytes de dados. A contagem de bytes não inclui os quatro bytes para o comprimento da própria contagem; um membro de blob vazio teria uma contagem de zero, seguido por zero bytes. Isso é semelhante ao valor VT_BSTR, mas não garante um byte nulo no final dos dados.
VT_BLOBOBJECT 70 blob Um membro de blob que contém um objeto serializado na mesma representação que apareceria no VT_STREAMED_OBJECT. Ou seja, uma contagem de bytes DWORD (em que a contagem de bytes não inclui o tamanho de si mesma) que está no formato de um identificador de classe seguido por dados de inicialização para essa classe.

A única diferença significativa entre VT_BLOB_OBJECT e VT_STREAMED_OBJECT é que o primeiro não tem a sobrecarga de armazenamento no nível do sistema que este último teria e, portanto, é mais adequado para cenários que envolvem números de objetos pequenos.

VT_LPSTR 30 pszVal Um ponteiro para uma cadeia de caracteres ANSI terminada em nulo na página de código padrão do sistema.
VT_LPWSTR 31 pwszVal Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo na localidade padrão do usuário.
VT_UNKNOWN 13 punkVal Novo.
VT_DISPATCH 9 pdispVal Novo.
VT_STREAM 66 pStream Um ponteiro para uma interface IStream que representa um fluxo que é irmão do fluxo "Conteúdo".
VT_STREAMED_OBJECT 68 pStream Como no VT_STREAM, mas indica que o fluxo contém um objeto serializado, que é um CLSID seguido por dados de inicialização para a classe . O fluxo é um irmão do fluxo "Conteúdo" que contém o conjunto de propriedades.
VT_STORAGE 67 pStorage Um ponteiro para uma interface IStorage , representando um objeto de armazenamento que é irmão do fluxo "Conteúdo".
VT_STORED_OBJECT 69 pStorage Como no VT_STORAGE, mas indica que o IStorage designado contém um objeto carregável.
VT_VERSIONED_STREAM 73 pVersionedStream Um fluxo com uma versão guid.
VT_DECIMAL 14 decVal Uma estrutura DECIMAL .
VT_VECTOR 0x1000 Ca* Se o indicador de tipo for combinado com VT_VECTOR usando um operador OR , o valor será um dos valores de matriz contados. Isso cria uma contagem DWORD de elementos, seguida por um ponteiro para as repetições especificadas do valor.

Por exemplo, um indicador de tipo de VT_LPSTR|VT_VECTOR tem uma contagem de elementos DWORD , seguido por um ponteiro para uma matriz de elementos LPSTR .

VT_VECTOR pode ser combinado por um operador OR com os seguintes 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_LPWSTR e VT_VARIANT. VT_VECTOR também pode ser combinado por uma operação OR com VT_BSTR_BLOB, no entanto, é apenas para uso do sistema.

VT_ARRAY 0x2000 Parray Se o indicador de tipo for combinado com VT_ARRAY por um operador OR , o valor será um ponteiro para um SAFEARRAY. VT_ARRAY pode usar o OR com os seguintes tipos de dados: 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 e VT_VARIANT. VT_ARRAY não pode usar OR com VT_VECTOR.
VT_BYREF 0x4000 P* Se o indicador de tipo for combinado com VT_BYREF por um operador OR , o valor será uma referência. Os tipos de referência são interpretados como uma referência aos dados, semelhante ao tipo de referência em C++ (por exemplo, "int&").

VT_BYREF pode usar OR com os seguintes 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 e VT_VARIANT.

VT_VARIANT 12 capropvar Um indicador de tipo DWORD seguido pelo valor correspondente. VT_VARIANT pode ser usado somente com VT_VECTOR ou VT_BYREF.
VT_TYPEMASK 0xFFF   Usado como uma máscara para VT_VECTOR e outros modificadores para extrair o valor bruto da VT.
 

Identificadores de formato de área de transferência, armazenados com a marca VT_CF, usam uma das cinco representações, identificadas no membro ulClipFmt da estrutura CLIPDATA usando o ponteiro pClipData para o tipo de dados específico.

valor ulClipFmt valor de pClipData
-1L Um DWORD que contém um valor interno de formato de área de transferência do Windows.
-2L Um DWORD que contém um valor de formato de área de transferência do Macintosh.
-3L Um GUID que contém um FMTID (identificador de formato). Isso raramente é usado.
qualquer valor positivo Uma cadeia de caracteres terminada em nulo que contém um nome de formato de área de transferência do Windows, um adequado para passar para a função RegisterClipboardFormat . Essa função registra um novo formato de área de transferência. Se já existir um formato registrado com o nome especificado, um novo formato não será registrado e o valor retornado identificará o formato existente. Isso permite que mais de um aplicativo copie e cole dados usando o mesmo formato de área de transferência registrado. A comparação de nome de formato não diferencia maiúsculas de minúsculas e é identificada por valores no intervalo de 0xC000 a 0xFFFF. A página de código usada para caracteres na cadeia de caracteres é de acordo com o indicador de página de código. O "valor positivo" aqui é o comprimento da cadeia de caracteres, incluindo o byte nulo no final. Quando os formatos de área de transferência de registro são colocados ou recuperados da área de transferência, eles devem estar na forma de um valor de tipo de dados HGLOBAL , que fornece o identificador para o objeto.
0L Nenhum dado (raramente usado).
 

Se o valor do membro ulClipFmt for -1, os dados serão na forma de um formato interno do Windows. Nesse caso, o primeiro DWORD do buffer apontado por pClipData é o identificador de formato da área de transferência, por exemplo, CF_METAFILEPICT. No caso de CF_METAFILEPCT, o que se segue é uma variação na estrutura METAFILEPICT (ela usa WORD, em vez de tipos de dados DWORD ). Ou seja, esses dados estão no seguinte formato:

struct PACKEDMETA
{
    WORD mm;
    WORD xExt;
    WORD yExt
    WORD reserved;
};

Depois que a estrutura METAFILEPICT for os dados de meta-arquivo, adequados para serem passados para a função SetMetaFileBitsEx . Essa função cria um meta-arquivo no formato Windows baseado em memória com base nos dados fornecidos. Essa função é fornecida para compatibilidade com versões de 16 bits do Windows. Os aplicativos baseados em Win32 devem usar a função SetEnhMetaFileBits . Essa função recupera o conteúdo do metarquivo de formato aprimorado especificado e os copia em um buffer. Se a função for bem-sucedida e o ponteiro do buffer for NULL, o valor retornado será o tamanho do meta-arquivo aprimorado em bytes. Se a função for bem-sucedida e o ponteiro do buffer for um ponteiro válido, o valor retornado será o número de bytes copiados para o buffer. Se a função falhar, o valor retornado será zero.

Quando os formatos de área de transferência de registro são colocados ou recuperados da área de transferência, eles devem estar na forma de um valor HGLOBAL .

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Cabeçalho propidlbase.h (inclua Propidl.h)