Structure PROPVARIANT (propidl.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.
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
Balise de type valeur.
tag_inner_PROPVARIANT.wReserved1
Réservé à un usage ultérieur.
tag_inner_PROPVARIANT.wReserved2
Réservé à un usage ultérieur.
tag_inner_PROPVARIANT.wReserved3
Réservé à un usage ultérieur.
tag_inner_PROPVARIANT.cVal
VT_I1, version 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, version 1
tag_inner_PROPVARIANT.uintVal
VT_UINT, version 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, version 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_*, version 1
tag_inner_PROPVARIANT.cac
| VT_VECTORVT_I1, version 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_BYREFVT_I1, version 1
tag_inner_PROPVARIANT.pbVal
| VT_BYREFVT_UI1, version 1
tag_inner_PROPVARIANT.piVal
| VT_BYREFVT_I2, version 1
tag_inner_PROPVARIANT.puiVal
| VT_BYREFVT_UI2, version 1
tag_inner_PROPVARIANT.plVal
| VT_BYREFVT_I4, version 1
tag_inner_PROPVARIANT.pulVal
| VT_BYREFVT_UI4, version 1
tag_inner_PROPVARIANT.pintVal
| VT_BYREFVT_INT, version 1
tag_inner_PROPVARIANT.puintVal
| VT_BYREFVT_UINT, version 1
tag_inner_PROPVARIANT.pfltVal
| VT_BYREFVT_R4, version 1
tag_inner_PROPVARIANT.pdblVal
| VT_BYREFVT_R8, version 1
tag_inner_PROPVARIANT.pboolVal
| VT_BYREFVT_R8, version 1
tag_inner_PROPVARIANT.pdecVal
| VT_BYREFVT_DECIMAL, version 1
tag_inner_PROPVARIANT.pscode
| VT_BYREFVT_ERROR, version 1
tag_inner_PROPVARIANT.pcyVal
| VT_BYREFVT_CY, version 1
tag_inner_PROPVARIANT.pdate
| VT_BYREFVT_DATE, version 1
tag_inner_PROPVARIANT.pbstrVal
| VT_BYREFVT_BSTR, version 1
tag_inner_PROPVARIANT.ppunkVal
| VT_BYREFVT_UNKNOWN, version 1
tag_inner_PROPVARIANT.ppdispVal
| VT_BYREFVT_DISPATCH, version 1
tag_inner_PROPVARIANT.pparray
| VT_BYREFVT_DISPATCH, version 1
tag_inner_PROPVARIANT.pvarVal
| VT_BYREFVT_VARIANT, version 1
decVal
| VT_BYREFVT_DECIMAL, version 1
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 en temps 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, approprié pour passer à la fonction RegisterClipboardFormat . Cette fonction enregistre un nouveau format de Presse-papiers. Si un format inscrit avec le nom spécifié existe déjà, un nouveau format n’est pas enregistré 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 de 0xC000 à 0xFFFF. La page de codes utilisée pour les caractères dans la chaîne est en fonction de l’indicateur de page de codes. La « valeur positive » est ici la longueur de chaîne, y compris l’octet Null à la fin. Lorsque les formats du Presse-papiers du registre 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 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 par 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 des types de données WORD plutôt que DWORD ). Autrement dit, ces données se présentent sous la forme suivante :
struct PACKEDMETA
{
WORD mm;
WORD xExt;
WORD yExt
WORD reserved;
};
Une fois que la structure METAFILEPICT est les données du métafichier, il convient de passer à 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 au format amélioré spécifié et les copie dans une mémoire tampon. Si la fonction réussit et que le pointeur de la mémoire tampon est NULL, la valeur de retour est la taille du métafichier amélioré en octets. Si la fonction réussit et que le pointeur de mémoire tampon est un pointeur valide, la valeur de retour est le nombre d’octets copiés dans la mémoire tampon. Si la fonction échoue, la valeur de retour est égale à zéro.
Lorsque les formats du Presse-papiers du registre 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 | propidl.h (include Propidl.h) |