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.
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) |