Condividi tramite


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.

Nota Il membro bool nelle definizioni precedenti di questa struttura è stato rinominato boolVal, perché alcuni compilatori ora riconoscono bool come parola chiave.
 
Nota La struttura PROPVARIANT , definita di seguito, include i tipi che possono essere serializzati nel formato di serializzazione del set di proprietà della versione 1. Il formato versione 1 supporta tutti i tipi consentiti nel formato versione 0 più alcuni tipi aggiuntivi. I tipi aggiunti includono "Versione 1" nel campo del commento riportato di seguito. Usare questi tipi solo se è previsto un set di proprietà versione 1. Per altre informazioni, vedere Serializzazione dei set di proprietà.
 
La struttura PROPVARIANT è definita come segue:

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)