Struttura PROPVARIANT (propidl.h)
La struttura PROPVARIANT viene usata 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 modo primario per programmare le proprietà dell'elemento 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 l'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 del tipo di valore.
tag_inner_PROPVARIANT.wReserved1
Riservato per usi futuri.
tag_inner_PROPVARIANT.wReserved2
Riservato per usi futuri.
tag_inner_PROPVARIANT.wReserved3
Riservato per usi futuri.
tag_inner_PROPVARIANT.cVal
VT_I1, versione 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, versione 1
tag_inner_PROPVARIANT.uintVal
VT_UINT, versione 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 versione 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_*, versione 1
tag_inner_PROPVARIANT.cac
| VT_VECTORVT_I1, versione 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_BYREF | VT_I1, versione 1
tag_inner_PROPVARIANT.pbVal
VT_BYREF | VT_UI1, versione 1
tag_inner_PROPVARIANT.piVal
VT_BYREF | VT_I2 versione 1
tag_inner_PROPVARIANT.puiVal
VT_BYREF | VT_UI2 versione 1
tag_inner_PROPVARIANT.plVal
VT_BYREF | VT_I4 versione 1
tag_inner_PROPVARIANT.pulVal
VT_BYREF | VT_UI4 versione 1
tag_inner_PROPVARIANT.pintVal
VT_BYREF | VT_INT, versione 1
tag_inner_PROPVARIANT.puintVal
VT_BYREF | VT_UINT, versione 1
tag_inner_PROPVARIANT.pfltVal
VT_BYREF | VT_R4, versione 1
tag_inner_PROPVARIANT.pdblVal
VT_BYREF | VT_R8, versione 1
tag_inner_PROPVARIANT.pboolVal
VT_BYREF | VT_R8, versione 1
tag_inner_PROPVARIANT.pdecVal
VT_BYREF | VT_DECIMAL versione 1
tag_inner_PROPVARIANT.pscode
VT_BYREF | VT_ERROR versione 1
tag_inner_PROPVARIANT.pcyVal
VT_BYREF | VT_CY, versione 1
tag_inner_PROPVARIANT.pdate
VT_BYREF | VT_DATE, versione 1
tag_inner_PROPVARIANT.pbstrVal
VT_BYREF | VT_BSTR, versione 1
tag_inner_PROPVARIANT.ppunkVal
VT_BYREF | VT_UNKNOWN, versione 1
tag_inner_PROPVARIANT.ppdispVal
VT_BYREF | VT_DISPATCH, versione 1
tag_inner_PROPVARIANT.pparray
VT_BYREF | VT_DISPATCH, versione 1
tag_inner_PROPVARIANT.pvarVal
VT_BYREF | VT_VARIANT, versione 1
decVal
VT_BYREF | VT_DECIMAL versione 1
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 si adatta all'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 che contiene un codice di stato. |
| VT_CY | 6 | cyVal | Intero complemento a 8 byte (scalato di 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). 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 nell'ora UTC (Universal Coordinate Time). |
| VT_CLSID | 72 | puuid | Puntatore a un identificatore di classe (CLSID) o a un altro identificatore univoco globale (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 | propidl.h (include Propidl.h) |