Struttura PROPVARIANT (propidlbase.h)
La struttura PROPVARIANT viene utilizzata nei metodi ReadMultiple e WriteMultiple di IPropertyStorage per definire il tag di tipo e il valore di una proprietà in un set di proprietà.
La struttura PROPVARIANT viene usata anche dai metodi GetValue e SetValue di IPropertyStore, che sostituisce IPropertySetStorage come metodo principale per programmare le proprietà degli elementi in Windows Vista. Per altre informazioni, vedere Gestori delle proprietà.
Ci sono cinque membri. Il primo membro, il tag di tipo valore e l'ultimo membro, il valore della proprietà, sono significativi. I tre membri intermedi sono riservati per un uso futuro.
Sintassi
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;
Members
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
Commenti
La struttura PROPVARIANT può contenere anche un valore di VT_DECIMAL:
DECIMAL decVal; //VT_DECIMAL
Tuttavia, il valore della struttura DECIMAL richiede una gestione speciale. La struttura DECIMAL è la stessa dimensione di un'intera struttura PROPVARIANT e non rientra nell'unione che contiene tutti gli altri tipi di valori. Il valore della struttura DECIMAL occupa invece l'intera struttura PROPVARIANT , inclusi i campi riservati e il membro vt . Tuttavia, il primo membro della struttura DECIMAL non viene utilizzato ed è uguale alla dimensione del membro vt della struttura PROPVARIANT . Pertanto, la dichiarazione di struttura PROPVARIANT nel file di intestazione Propidl.h di Win32 definisce il membro decVal in modo che corrisponda all'inizio della struttura PROPVARIANT . Pertanto, per inserire il valore della struttura DECIMAL in una struttura PROPVARIANT , il valore deve essere caricato nel membro decVal e il membro vt è impostato su VT_DECIMAL, esattamente come per qualsiasi altro valore.
PROPVARIANT è il tipo di dati fondamentale in base al quale i valori delle proprietà vengono letti e scritti tramite l'interfaccia IPropertyStorage .
Il tipo di dati PROPVARIANT è correlato al tipo di dati VARIANT, definito come parte dell'automazione in OLE2. Diverse definizioni vengono riutilizzate dall'automazione, come indicato di seguito:
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;
Inoltre, alcuni tipi sono univoci per la struttura 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;
Tra i tipi PROPVARIANT univoci sono diversi tipi di dati che definiscono matrici conteggiate di altri tipi di dati. I tipi di dati di tutte le matrici con conteggio iniziano con le lettere CA, ad esempio CAUB, e hanno un valore vt dell'operatore OR (varType dell'elemento e un operatore OR con VT_VECTOR). La struttura della matrice con conteggiata ha il formato seguente (dove name è il nome specifico della matrice con conteggiata).
#define TYPEDEF_CA(type, name)
typedef struct tag ## name {\
ULONG cElems;\
type *pElems;\
} name
| Tipo propvariante | Codice | Membro propvariante | Rappresentazione del valore |
|---|---|---|---|
| VT_EMPTY | 0 | nessuno | Una proprietà con un indicatore di tipo di VT_EMPTY non dispone di dati associati; ovvero la dimensione del valore è zero. |
| VT_NULL | 1 | nessuno | Si tratta di un puntatore a NULL. |
| VT_I1 | 16 | cVal | Intero con segno a 1 byte. |
| VT_UI1 | 17 | bVal | Intero senza segno a 1 byte. |
| VT_I2 | 2 | iVal | Due byte che rappresentano un valore intero con segno a 2 byte. |
| VT_UI2 | 18 | uiVal | Intero senza segno a 2 byte. |
| VT_I4 | 3 | lVal | Valore intero con segno a 4 byte. |
| VT_UI4 | 19 | ulVal | Intero senza segno a 4 byte. |
| VT_INT | 22 | intVal | Valore intero con segno a 4 byte (equivalente a VT_I4). |
| VT_UINT | 23 | uintVal | Intero senza segno a 4 byte (equivalente a VT_UI4). |
| VT_I8 | 20 | hVal | Intero con segno a 8 byte. |
| VT_UI8 | 21 | uhVal | Intero senza segno a 8 byte. |
| VT_R4 | 4 | fltVal | Valore a virgola mobile IEEE a 32 bit. |
| VT_R8 | 5 | dblVal | Valore a virgola mobile IEEE a 64 bit. |
| VT_BOOL | 11 | boolVal (bool nelle progettazioni precedenti) | Valore booleano , word contenente 0 (FALSE) o -1 (TRUE). |
| VT_ERROR | 10 | scode | DWORD contenente un codice di stato. |
| VT_CY | 6 | cyVal | Intero di complemento di 8 byte (scalato da 10.000). Questo tipo viene comunemente usato per gli importi di valuta. |
| VT_DATE | 7 | date | Numero a virgola mobile a 64 bit che rappresenta il numero di giorni (non secondi) dal 31 dicembre 1899. Ad esempio, il 1° gennaio 1900, è 2,0, 2 gennaio 1900, è 3,0 e così via. Questa operazione viene archiviata nella stessa rappresentazione di VT_R8. |
| VT_FILETIME | 64 | Filetime | Struttura FILETIME a 64 bit definita da Win32. È consigliabile archiviare tutte le volte in ora UTC (Universal Coordinate Time). |
| VT_CLSID | 72 | puuid | Puntatore a un identificatore di classe (CLSID) o ad altri identificatori univoci globali (GUID). |
| VT_CF | 71 | pclipdata | Puntatore a una struttura CLIPDATA , descritta in precedenza. |
| VT_BSTR | 8 | bstrVal | Puntatore a una stringa Unicode con terminazione null. La stringa è immediatamente preceduta da una DWORD che rappresenta il conteggio dei byte, ma bstrVal punta al primo carattere della stringa. BSTRs deve essere allocato e liberato usando le chiamate SysAllocString e SysFreeString di Automazione. |
| VT_BSTR_BLOB | 0xfff | bstrblobVal | Solo per l'uso del sistema. |
| VT_BLOB | 65 | Blob | Numero di byte DWORD, seguito da molti byte di dati. Il conteggio dei byte non include i quattro byte per la lunghezza del conteggio stesso; un membro BLOB vuoto avrà un conteggio pari a zero, seguito da zero byte. È simile al valore VT_BSTR, ma non garantisce un byte Null alla fine dei dati. |
| VT_BLOBOBJECT | 70 | Blob | Membro BLOB che contiene un oggetto serializzato nella stessa rappresentazione visualizzata in VT_STREAMED_OBJECT. Ovvero, un conteggio byte DWORD (in cui il conteggio dei byte non include le dimensioni di se stesso) che è nel formato di un identificatore di classe seguito da dati di inizializzazione per tale classe.
L'unica differenza significativa tra VT_BLOB_OBJECT e VT_STREAMED_OBJECT è che l'ex non ha il sovraccarico di archiviazione a livello di sistema che quest'ultimo avrebbe, ed è quindi più adatto per scenari che coinvolgono numeri di oggetti di piccole dimensioni. |
| VT_LPSTR | 30 | pszVal | Puntatore a una stringa ANSI con terminazione null nella tabella codici predefinita del sistema. |
| VT_LPWSTR | 31 | pwszVal | Puntatore a una stringa Unicode con terminazione null nelle impostazioni locali predefinite dell'utente. |
| VT_UNKNOWN | 13 | punkVal | Nuovo. |
| VT_DISPATCH | 9 | pdispVal | Nuovo. |
| VT_STREAM | 66 | pStream | Puntatore a un'interfaccia IStream che rappresenta un flusso che è un elemento pari al flusso "Contenuto". |
| VT_STREAMED_OBJECT | 68 | pStream | Come in VT_STREAM, ma indica che il flusso contiene un oggetto serializzato, che è un CLSID seguito da dati di inizializzazione per la classe. Il flusso è un flusso di pari livello al flusso "Contenuto" che contiene il set di proprietà. |
| VT_STORAGE | 67 | pStorage | Puntatore a un'interfaccia IStorage che rappresenta un oggetto di archiviazione pari al flusso "Contenuto". |
| VT_STORED_OBJECT | 69 | pStorage | Come in VT_STORAGE, ma indica che l'oggetto IStorage designato contiene un oggetto caricabile. |
| VT_VERSIONED_STREAM | 73 | pVersionedStream | Flusso con una versione GUID. |
| VT_DECIMAL | 14 | decVal | Struttura DECIMALe . |
| VT_VECTOR | 0x1000 | Ca* | Se l'indicatore di tipo viene combinato con VT_VECTOR usando un operatore OR , il valore è uno dei valori della matrice conteggiata. In questo modo viene creato un conteggio DWORD degli elementi, seguito da un puntatore alle ripetizioni specificate del valore.
Ad esempio, un indicatore di tipo di VT_LPSTR VT_VECTOR| ha un conteggio degli elementi DWORD, seguito da un puntatore a una matrice di elementi LPSTR. VT_VECTOR può essere combinato da un operatore OR con i tipi seguenti: VT_I1, VT_UI1, VT_I2, VT_UI2, VT_BOOL, VT_I4 VT_UI4, VT_R4, 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 può essere combinato anche da un'operazione OR con VT_BSTR_BLOB, ma è solo per l'uso del sistema. |
| VT_ARRAY | 0x2000 | Parray | Se l'indicatore di tipo viene combinato con VT_ARRAY da un operatore OR , il valore è un puntatore a un SAFEARRAY. VT_ARRAY può usare l'OR con i tipi di dati seguenti: 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 non può usare OR con VT_VECTOR. |
| VT_BYREF | 0x4000 | P* | Se l'indicatore di tipo viene combinato con VT_BYREF da un operatore OR , il valore è un riferimento. I tipi di riferimento vengono interpretati come riferimento ai dati, simili al tipo di riferimento in C++ (ad esempio "int&").
VT_BYREF può usare OR con i tipi seguenti: 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_DECIMAL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_UNKNOWN, VT_DISPATCH, VT_ARRAY e VT_VARIANT. |
| VT_VARIANT | 12 | capropvar | Indicatore di tipo DWORD seguito dal valore corrispondente. VT_VARIANT può essere usato solo con VT_VECTOR o VT_BYREF. |
| VT_TYPEMASK | 0xFFF | Usato come maschera per VT_VECTOR e altri modificatori per estrarre il valore VT non elaborato. |
Gli identificatori di formato degli Appunti, archiviati con il tag VT_CF, usano una delle cinque rappresentazioni identificate nel membro ulClipFmt della struttura CLIPDATA usando il puntatore pClipData al tipo di dati specifico.
| valore ulClipFmt | valore pClipData |
|---|---|
| -1L | DWORD che contiene un valore di formato degli Appunti di Windows predefinito. |
| -2L | DWORD che contiene un valore di formato appunti Macintosh. |
| -3L | GUID contenente un identificatore di formato (FMTID). Questa operazione viene usata raramente. |
| qualsiasi valore positivo | Stringa con terminazione null che contiene un nome di formato degli Appunti di Windows, uno adatto per passare alla funzione RegisterClipboardFormat . Questa funzione registra un nuovo formato degli Appunti. Se esiste già un formato registrato con il nome specificato, un nuovo formato non è registrato e il valore restituito identifica il formato esistente. Ciò consente a più applicazioni di copiare e incollare i dati usando lo stesso formato registrato negli Appunti. Il confronto tra nomi di formato è senza distinzione tra maiuscole e minuscole e viene identificato dai valori nell'intervallo compreso tra 0xC000 e 0xFFFF. La tabella codici utilizzata per i caratteri nella stringa è in base all'indicatore della tabella codici. Il "valore positivo" è la lunghezza della stringa, incluso il byte Null alla fine. Quando i formati degli Appunti di registrazione vengono inseriti negli Appunti o recuperati dagli Appunti, devono essere sotto forma di valore di tipo di dati HGLOBAL , che fornisce l'handle all'oggetto. |
| 0L | Nessun dato (raramente usato). |
Se il valore del membro ulClipFmt è -1, i dati sono sotto forma di formato Windows predefinito. In questo caso, il primo DWORD del buffer a cui fa riferimento pClipData è l'identificatore di formato degli Appunti, ad esempio CF_METAFILEPICT. Nel caso di CF_METAFILEPCT, ciò che segue è una variante della struttura METAFILEPICT (usa WORD, anziché tipi di dati DWORD ). Ovvero, questi dati si trovano nel formato seguente:
struct PACKEDMETA
{
WORD mm;
WORD xExt;
WORD yExt
WORD reserved;
};
Dopo che la struttura METAFILEPICT è i dati metafile, adatti per essere passati alla funzione SetMetaFileBitsEx . Questa funzione crea un metafile in formato Windows basato sulla memoria dai dati forniti. Questa funzione viene fornita per la compatibilità con le versioni a 16 bit di Windows. Le applicazioni basate su Win32 devono usare la funzione SetEnhMetaFileBits . Questa funzione recupera il contenuto del metafile di formato avanzato specificato e li copia in un buffer. Se la funzione ha esito positivo e il puntatore del buffer è NULL, il valore restituito è la dimensione del metafile avanzato in byte. Se la funzione ha esito positivo e il puntatore del buffer è un puntatore valido, il valore restituito è il numero di byte copiati nel buffer. Se la funzione ha esito negativo, il valore restituito è zero.
Quando i formati degli Appunti di registrazione vengono inseriti negli Appunti o recuperati dagli Appunti, devono essere sotto forma di valore HGLOBAL .
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [app desktop | App UWP] |
| Server minimo supportato | Windows 2000 Server [app desktop | App UWP] |
| Intestazione | propidlbase.h (include Propidl.h) |