Estrutura PROPVARIANT (propidl.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 propriedades.
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.
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
Marca de tipo de valor.
tag_inner_PROPVARIANT.wReserved1
Reservado para uso futuro.
tag_inner_PROPVARIANT.wReserved2
Reservado para uso futuro.
tag_inner_PROPVARIANT.wReserved3
Reservado para uso futuro.
tag_inner_PROPVARIANT.cVal
VT_I1, versão 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, versão 1
tag_inner_PROPVARIANT.uintVal
VT_UINT, versão 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, versão 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_ARRAY | VT_*, versão 1
tag_inner_PROPVARIANT.cac
VT_VECTOR | VT_I1, versão 1
tag_inner_PROPVARIANT.caub
VT_VECTOR | VT_UI1
tag_inner_PROPVARIANT.cai
VT_VECTOR | VT_I2
tag_inner_PROPVARIANT.caui
VT_VECTOR | VT_UI2
tag_inner_PROPVARIANT.cal
VT_VECTOR | VT_I4
tag_inner_PROPVARIANT.caul
VT_VECTOR | VT_UI4
tag_inner_PROPVARIANT.cah
VT_VECTOR | VT_I8
tag_inner_PROPVARIANT.cauh
VT_VECTOR | VT_UI8
tag_inner_PROPVARIANT.caflt
VT_VECTOR | VT_R4
tag_inner_PROPVARIANT.cadbl
VT_VECTOR | VT_R8
tag_inner_PROPVARIANT.cabool
VT_VECTOR | VT_BOOL
tag_inner_PROPVARIANT.cascode
VT_VECTOR | VT_ERROR
tag_inner_PROPVARIANT.cacy
VT_VECTOR | VT_CY
tag_inner_PROPVARIANT.cadate
VT_VECTOR | VT_DATE
tag_inner_PROPVARIANT.cafiletime
VT_VECTOR | VT_FILETIME
tag_inner_PROPVARIANT.cauuid
VT_VECTOR | VT_CLSID
tag_inner_PROPVARIANT.caclipdata
VT_VECTOR | VT_CF
tag_inner_PROPVARIANT.cabstr
VT_VECTOR | VT_BSTR
tag_inner_PROPVARIANT.cabstrblob
VT_VECTOR | VT_BSTR
tag_inner_PROPVARIANT.calpstr
VT_VECTOR | VT_LPSTR
tag_inner_PROPVARIANT.calpwstr
VT_VECTOR | VT_LPWSTR
tag_inner_PROPVARIANT.capropvar
VT_VECTOR | VT_VARIANT
tag_inner_PROPVARIANT.pcVal
VT_BYREF | VT_I1, versão 1
tag_inner_PROPVARIANT.pbVal
VT_BYREF | VT_UI1, versão 1
tag_inner_PROPVARIANT.piVal
VT_BYREF | VT_I2, versão 1
tag_inner_PROPVARIANT.puiVal
VT_BYREF | VT_UI2, versão 1
tag_inner_PROPVARIANT.plVal
VT_BYREF | VT_I4, versão 1
tag_inner_PROPVARIANT.pulVal
VT_BYREF | VT_UI4, versão 1
tag_inner_PROPVARIANT.pintVal
VT_BYREF | VT_INT, versão 1
tag_inner_PROPVARIANT.puintVal
VT_BYREF | VT_UINT, versão 1
tag_inner_PROPVARIANT.pfltVal
VT_BYREF | VT_R4, versão 1
tag_inner_PROPVARIANT.pdblVal
VT_BYREF | VT_R8, versão 1
tag_inner_PROPVARIANT.pboolVal
VT_BYREF | VT_R8, versão 1
tag_inner_PROPVARIANT.pdecVal
VT_BYREF | VT_DECIMAL, versão 1
tag_inner_PROPVARIANT.pscode
VT_BYREF | VT_ERROR, versão 1
tag_inner_PROPVARIANT.pcyVal
VT_BYREF | VT_CY, versão 1
tag_inner_PROPVARIANT.pdate
VT_BYREF | VT_DATE, versão 1
tag_inner_PROPVARIANT.pbstrVal
VT_BYREF | VT_BSTR, versão 1
tag_inner_PROPVARIANT.ppunkVal
VT_BYREF | VT_UNKNOWN, versão 1
tag_inner_PROPVARIANT.ppdispVal
VT_BYREF | VT_DISPATCH, versão 1
tag_inner_PROPVARIANT.pparray
VT_BYREF | VT_DISPATCH, versão 1
tag_inner_PROPVARIANT.pvarVal
VT_BYREF | VT_VARIANT, versão 1
decVal
VT_BYREF | VT_DECIMAL, versão 1
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 toda uma estrutura PROPVARIANT 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 em tamanho 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 para a 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 AC, 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 formulário a seguir (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 nomes 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 de á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 na seguinte forma:
struct PACKEDMETA
{
WORD mm;
WORD xExt;
WORD yExt
WORD reserved;
};
Depois que a estrutura METAFILEPICT for os dados de metafile, adequados para serem passados para a função SetMetaFileBitsEx . Essa função cria um metarquivo de formato windows baseado em memória dos 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 de buffer for NULL, o valor retornado será o tamanho do metafile aprimorado em bytes. Se a função for bem-sucedida e o ponteiro de 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 | propidl.h (inclua Propidl.h) |