Partager via


Structure PROPVARIANT (propidlbase.h)

La structure PROPVARIANT est utilisée dans les méthodes ReadMultiple et WriteMultiple de IPropertyStorage pour définir la balise de type et la valeur d’une propriété dans un jeu de propriétés.

La structure PROPVARIANT est également utilisée par les méthodes GetValue et SetValue de IPropertyStore, qui remplace IPropertySetStorage comme méthode principale de programmation des propriétés d’élément dans Windows Vista. Pour plus d’informations, consultez Gestionnaires de propriétés.

Il y a cinq membres. Le premier membre, la balise value-type, et le dernier membre, la valeur de la propriété, sont significatifs. Les trois membres du milieu sont réservés pour une utilisation ultérieure.

Note Le membre bool dans les définitions précédentes de cette structure a été renommé boolVal, car certains compilateurs reconnaissent désormais bool comme un mot clé.
 
Note La structure PROPVARIANT , définie ci-dessous, inclut des types qui peuvent être sérialisés dans le format de sérialisation du jeu de propriétés version 1. Le format version 1 prend en charge tous les types autorisés dans le format version 0, ainsi que certains types supplémentaires. Les types ajoutés incluent « Version 1 » dans le champ de commentaire ci-dessous. Utilisez ces types uniquement si un jeu de propriétés version 1 est prévu. Pour plus d’informations, consultez Sérialisation de l’ensemble de propriétés.
 
La structure PROPVARIANT est définie comme suit :

Syntaxe

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;

Membres

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

Remarques

La structure PROPVARIANT peut également contenir une valeur de VT_DECIMAL :

    DECIMAL       decVal;        //VT_DECIMAL

Toutefois, la valeur de la structure DECIMAL nécessite une gestion spéciale. La structure DECIMAL a la même taille qu’une structure PROPVARIANT entière et ne tient pas dans l’union qui contient tous les autres types de valeurs. Au lieu de cela, la valeur de la structure DECIMAL occupe la structure PROPVARIANT entière, y compris les champs réservés et le membre vt . Toutefois, le premier membre de la structure DECIMAL n’est pas utilisé et est de taille égale au membre vt de la structure PROPVARIANT . Par conséquent, la déclaration de structure PROPVARIANT dans le fichier d’en-tête Propidl.h de Win32 définit le membre decVal de telle sorte qu’il corresponde au début de la structure PROPVARIANT . Par conséquent, pour placer la valeur de la structure DECIMAL dans une structure PROPVARIANT , la valeur doit être chargée dans le membre decVal et le membre vt est défini sur VT_DECIMAL, comme pour toute autre valeur.

PROPVARIANT est le type de données fondamental par lequel les valeurs de propriété sont lues et écrites via l’interface IPropertyStorage .

Le type de données PROPVARIANT est lié au type de données VARIANT, défini dans le cadre d’Automation dans OLE2. Plusieurs définitions sont réutilisées à partir d’Automation, comme suit :

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;

En outre, certains types sont propres à la structure 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;

Parmi les types PROPVARIANT uniques figurent plusieurs types de données qui définissent des tableaux comptés d’autres types de données. Les types de données de tous les tableaux comptés commencent par les lettres CA, par exemple CAUB, et ont une valeur vt de l’opérateur OR (le VarType de l’élément et un opérateur OR avec VT_VECTOR). La structure de tableau comptée se présente sous la forme suivante (où name est le nom spécifique du tableau compté).

#define TYPEDEF_CA(type, name) 
 
    typedef struct tag ## name {\
        ULONG cElems;\
        type *pElems;\
        } name
Type propvariant Code Membre propvariant Représentation de valeur
VT_EMPTY 0 None Aucune donnée n’est associée à une propriété avec un indicateur de type VT_EMPTY ; autrement dit, la taille de la valeur est égale à zéro.
VT_NULL 1 None Il s’agit d’un pointeur vers NULL.
VT_I1 16 cVal Entier signé de 1 octet.
VT_UI1 17 bVal Entier non signé de 1 octet.
VT_I2 2 iVal Deux octets représentant une valeur entière signée de 2 octets.
VT_UI2 18 uiVal Entier non signé de 2 octets.
VT_I4 3 lVal Valeur entière signée de 4 octets.
VT_UI4 19 ulVal Entier non signé de 4 octets.
VT_INT 22 intVal Valeur entière signée de 4 octets (équivalente à VT_I4).
VT_UINT 23 uintVal Entier non signé de 4 octets (équivalent à VT_UI4).
VT_I8 20 hVal Entier signé de 8 octets.
VT_UI8 21 uhVal Entier non signé de 8 octets.
VT_R4 4 fltVal Valeur à virgule flottante IEEE 32 bits.
VT_R8 5 dblVal Valeur à virgule flottante IEEE 64 bits.
VT_BOOL 11 boolVal (bool dans les conceptions antérieures) Valeur booléenne, word qui contient 0 (FALSE) ou -1 (TRUE).
VT_ERROR 10 scode DWORD qui contient un code status.
VT_CY 6 cyVal Entier de complément de 8 octets deux (mis à l’échelle de 10 000). Ce type est couramment utilisé pour les montants monétaires.
VT_DATE 7 date Nombre à virgule flottante 64 bits représentant le nombre de jours (et non de secondes) depuis le 31 décembre 1899. Par exemple, le 1er janvier 1900 est 2.0, le 2 janvier 1900, est 3.0, et ainsi de suite). Il est stocké dans la même représentation que VT_R8.
VT_FILETIME 64 filetime Structure FILETIME 64 bits telle que définie par Win32. Il est recommandé de stocker toutes les heures dans l’heure de coordonnées universelles (UTC).
VT_CLSID 72 puuid Pointeur vers un identificateur de classe (CLSID) (ou un autre identificateur global unique (GUID)).
VT_CF 71 pclipdata Pointeur vers une structure CLIPDATA , décrite ci-dessus.
VT_BSTR 8 bstrVal Pointeur vers une chaîne Unicode terminée par null. La chaîne est immédiatement précédée d’un DWORD représentant le nombre d’octets, mais bstrVal pointe au-delà de ce DWORD au premier caractère de la chaîne. Les BSTRdoivent être alloués et libérés à l’aide des appels Automation SysAllocString et SysFreeString .
VT_BSTR_BLOB 0xfff bstrblobVal Utilisation réservée au système.
VT_BLOB 65 objet BLOB Nombre DWORD d’octets, suivi de ce nombre d’octets de données. Le nombre d’octets n’inclut pas les quatre octets pour la longueur du nombre lui-même ; un membre d’objet blob vide aurait un nombre de zéro, suivi de zéro octets. Cela est similaire à la valeur VT_BSTR, mais ne garantit pas un octet null à la fin des données.
VT_BLOBOBJECT 70 objet BLOB Membre d’objet blob qui contient un objet sérialisé dans la même représentation que celle qui apparaîtrait dans VT_STREAMED_OBJECT. Autrement dit, un nombre d’octets DWORD (où le nombre d’octets n’inclut pas la taille de lui-même) qui est au format d’un identificateur de classe suivi des données d’initialisation pour cette classe.

La seule différence significative entre VT_BLOB_OBJECT et VT_STREAMED_OBJECT est que le premier n’a pas la surcharge de stockage au niveau du système que le second aurait, et est donc plus adapté aux scénarios impliquant un nombre d’objets de petite taille.

VT_LPSTR 30 pszVal Pointeur vers une chaîne ANSI terminée par null dans la page de code par défaut du système.
VT_LPWSTR 31 pwszVal Pointeur vers une chaîne Unicode terminée par null dans les paramètres régionaux par défaut de l’utilisateur.
VT_UNKNOWN 13 punkVal Nouveauté
VT_DISPATCH 9 pdispVal Nouveauté
VT_STREAM 66 pStream Pointeur vers une interface IStream qui représente un flux qui est un frère du flux « Contenu ».
VT_STREAMED_OBJECT 68 pStream Comme dans VT_STREAM, mais indique que le flux contient un objet sérialisé, qui est un CLSID suivi des données d’initialisation pour la classe. Le flux est un frère du flux « Contents » qui contient l’ensemble de propriétés.
VT_STORAGE 67 pStorage Pointeur vers une interface IStorage , représentant un objet de stockage qui est un frère du flux « Contenu ».
VT_STORED_OBJECT 69 pStorage Comme dans VT_STORAGE, mais indique que l’IStorage désigné contient un objet chargeable.
VT_VERSIONED_STREAM 73 pVersionedStream Flux avec une version GUID.
VT_DECIMAL 14 decVal Structure décimale .
VT_VECTOR 0x1000 ca* Si l’indicateur de type est combiné à VT_VECTOR à l’aide d’un opérateur OR , la valeur est l’une des valeurs de tableau comptabilisées. Cela crée un nombre DWORD d’éléments, suivi d’un pointeur vers les répétitions spécifiées de la valeur.

Par exemple, un indicateur de type de VT_LPSTR|VT_VECTOR a un nombre d’éléments DWORD , suivi d’un pointeur vers un tableau d’éléments LPSTR .

VT_VECTOR peut être combiné par un opérateur OR avec les types suivants : 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 et VT_VARIANT. VT_VECTOR peut également être combiné par une opération OR avec VT_BSTR_BLOB, mais il s’agit uniquement d’une utilisation système.

VT_ARRAY 0x2000 Parray Si l’indicateur de type est combiné à VT_ARRAY par un opérateur OR , la valeur est un pointeur vers un SAFEARRAY. VT_ARRAY pouvez utiliser l’or avec les types de données suivants : 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 et VT_VARIANT. VT_ARRAY ne peut pas utiliser OR avec VT_VECTOR.
VT_BYREF 0x4000 P* Si l’indicateur de type est combiné à VT_BYREF par un opérateur OR , la valeur est une référence. Les types de référence sont interprétés comme une référence à des données, comme le type de référence en C++ (par exemple, « int& »).

VT_BYREF pouvez utiliser OR avec les types suivants : 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 et VT_VARIANT.

VT_VARIANT 12 capropvar Indicateur de type DWORD suivi de la valeur correspondante. VT_VARIANT ne peut être utilisé qu’avec VT_VECTOR ou VT_BYREF.
VT_TYPEMASK 0xFFF   Utilisé comme masque pour VT_VECTOR et d’autres modificateurs afin d’extraire la valeur VT brute.
 

Les identificateurs de format du Presse-papiers, stockés avec la balise VT_CF, utilisent l’une des cinq représentations identifiées dans le membre ulClipFmt de la structure CLIPDATA à l’aide du pointeur pClipData vers le type de données particulier.

valeur ulClipFmt valeur pClipData
-1L DWORD qui contient une valeur de format de Presse-papiers Windows intégrée.
-2L DWORD qui contient une valeur de format de Presse-papiers Macintosh.
-3L GUID qui contient un identificateur de format (FMTID). C’est rarement utilisé.
toute valeur positive Chaîne terminée par null qui contient un nom de format de Presse-papiers Windows, adapté à la fonction RegisterClipboardFormat . Cette fonction enregistre un nouveau format de Presse-papiers. Si un format inscrit portant le nom spécifié existe déjà, un nouveau format n’est pas inscrit et la valeur de retour identifie le format existant. Cela permet à plusieurs applications de copier et coller des données à l’aide du même format de Presse-papiers inscrit. La comparaison des noms de format ne respecte pas la casse et est identifiée par des valeurs de la plage comprise entre 0xC000 et 0xFFFF. La page de code utilisée pour les caractères de la chaîne est en fonction de l’indicateur de page de code. La « valeur positive » est ici la longueur de la chaîne, y compris l’octet null à la fin. Lorsque des formats de Presse-papiers d’inscription sont placés dans le Presse-papiers ou récupérés à partir du Presse-papiers, ils doivent se présenter sous la forme d’une valeur de type de données HGLOBAL , qui fournit le handle à l’objet.
0L Aucune donnée (rarement utilisée).
 

Si la valeur du membre ulClipFmt est -1, les données sont sous la forme d’un format Windows intégré. Dans ce cas, le premier DWORD de la mémoire tampon pointée vers pClipData est l’identificateur de format du Presse-papiers, par exemple CF_METAFILEPICT. Dans le cas de CF_METAFILEPCT, il s’agit d’une variation de la structure METAFILEPICT (elle utilise word plutôt que les types de données DWORD ). Autrement dit, ces données sont sous la forme suivante :

struct PACKEDMETA
{
    WORD mm;
    WORD xExt;
    WORD yExt
    WORD reserved;
};

Une fois que la structure METAFILEPICT correspond aux données de métafichier, appropriées pour être transmises à la fonction SetMetaFileBitsEx . Cette fonction crée un métafichier au format Windows basé sur la mémoire à partir des données fournies. Cette fonction est fournie pour la compatibilité avec les versions 16 bits de Windows. Les applications win32 doivent utiliser la fonction SetEnhMetaFileBits . Cette fonction récupère le contenu du métafichier de format amélioré spécifié et les copie dans une mémoire tampon. Si la fonction réussit et que le pointeur de mémoire tampon a la valeur NULL, la valeur de retour correspond à la taille du métafichier amélioré en octets. Si la fonction réussit et que le pointeur de la mémoire tampon est un pointeur valide, la valeur de retour correspond au nombre d’octets copiés dans la mémoire tampon. Si la fonction échoue, la valeur de retour est égale à zéro.

Lorsque des formats de Presse-papiers d’inscription sont placés dans le Presse-papiers ou récupérés à partir du Presse-papiers, ils doivent être sous la forme d’une valeur HGLOBAL .

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau | Applications UWP]
En-tête propidlbase.h (inclure Propidl.h)