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.
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) |