PROPVARIANT 構造体 (propidl.h)

PROPVARIANT 構造体は、プロパティ セット内のプロパティの型タグと値を定義するために、IPropertyStorageReadMultiple メソッドと WriteMultiple メソッドで使用されます。

PROPVARIANT 構造体は、IPropertyStoreGetValue メソッドと SetValue メソッドでも使用されます。このメソッドは、Windows Vista で項目プロパティをプログラムする主な方法として IPropertySetStorage を置き換えます。 詳細については、「 プロパティ ハンドラー」を参照してください。

メンバーは 5 人です。 最初のメンバー、値型タグ、および最後のメンバー (プロパティの値) は重要です。 中央の 3 つのメンバーは、将来の使用のために予約されています。

メモ この構造体の以前の定義の bool メンバーの名前が boolVal に変更されました。これは、一部のコンパイラが bool をキーワードとして認識するようになったためです。
 
メモ 以下に定義されている PROPVARIANT 構造体には、バージョン 1 プロパティ セットのシリアル化形式でシリアル化できる型が含まれています。 バージョン 1 形式では、バージョン 0 形式で許可されるすべての型と、いくつかの追加の型がサポートされています。 追加された型には、以下のコメント フィールドに "Version 1" が含まれます。 これらの型は、バージョン 1 のプロパティ セットが意図されている場合にのみ使用してください。 詳細については、「 プロパティ セットのシリアル化」を参照してください。
 
PROPVARIANT 構造体は次のように定義されます。

構文

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;

メンバー

tag_inner_PROPVARIANT

tag_inner_PROPVARIANT.vt

値型タグ。

tag_inner_PROPVARIANT.wReserved1

将来使用するために予約されています。

tag_inner_PROPVARIANT.wReserved2

将来使用するために予約されています。

tag_inner_PROPVARIANT.wReserved3

将来使用するために予約されています。

tag_inner_PROPVARIANT.cVal

VT_I1、バージョン 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 バージョン 1

tag_inner_PROPVARIANT.uintVal

VT_UINT バージョン 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_BLOBVT_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 バージョン 1

tag_inner_PROPVARIANT.pStream

VT_STREAMVT_STREAMED_OBJECT

tag_inner_PROPVARIANT.pStorage

VT_STORAGEVT_STORED_OBJECT

tag_inner_PROPVARIANT.pVersionedStream

VT_VERSIONED_STREAM

tag_inner_PROPVARIANT.parray

| VT_ARRAYVT_*、バージョン 1

tag_inner_PROPVARIANT.cac

| VT_VECTORVT_I1 バージョン 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 バージョン 1

tag_inner_PROPVARIANT.pbVal

| VT_BYREFVT_UI1 バージョン 1

tag_inner_PROPVARIANT.piVal

| VT_BYREFVT_I2 バージョン 1

tag_inner_PROPVARIANT.puiVal

| VT_BYREFVT_UI2 バージョン 1

tag_inner_PROPVARIANT.plVal

| VT_BYREFVT_I4 バージョン 1

tag_inner_PROPVARIANT.pulVal

| VT_BYREFVT_UI4 バージョン 1

tag_inner_PROPVARIANT.pintVal

| VT_BYREFVT_INT バージョン 1

tag_inner_PROPVARIANT.puintVal

| VT_BYREFVT_UINT バージョン 1

tag_inner_PROPVARIANT.pfltVal

| VT_BYREFVT_R4、バージョン 1

tag_inner_PROPVARIANT.pdblVal

| VT_BYREFVT_R8 バージョン 1

tag_inner_PROPVARIANT.pboolVal

| VT_BYREFVT_R8 バージョン 1

tag_inner_PROPVARIANT.pdecVal

| VT_BYREFVT_DECIMAL バージョン 1

tag_inner_PROPVARIANT.pscode

| VT_BYREFVT_ERROR バージョン 1

tag_inner_PROPVARIANT.pcyVal

| VT_BYREFVT_CY バージョン 1

tag_inner_PROPVARIANT.pdate

| VT_BYREFVT_DATE、バージョン 1

tag_inner_PROPVARIANT.pbstrVal

| VT_BYREFVT_BSTR バージョン 1

tag_inner_PROPVARIANT.ppunkVal

| VT_BYREFVT_UNKNOWN バージョン 1

tag_inner_PROPVARIANT.ppdispVal

| VT_BYREFVT_DISPATCH バージョン 1

tag_inner_PROPVARIANT.pparray

| VT_BYREFVT_DISPATCH バージョン 1

tag_inner_PROPVARIANT.pvarVal

| VT_BYREFVT_VARIANT バージョン 1

decVal

| VT_BYREFVT_DECIMAL バージョン 1

注釈

PROPVARIANT 構造体は、VT_DECIMALの値を保持することもできます。

    DECIMAL       decVal;        //VT_DECIMAL

ただし、 DECIMAL 構造体の値には特別な処理が必要です。 DECIMAL 構造体は PROPVARIANT 構造体全体と同じサイズであり、他のすべての型の値を保持する共用体には収まりません。 代わりに、DECIMAL 構造体の値は、予約フィールドと vt メンバーを含む PROPVARIANT 構造体全体を占有します。 ただし、DECIMAL 構造体の最初のメンバーは使用されず、PROPVARIANT 構造体の vt メンバーのサイズが等しくなります。 したがって、Win32 の Propidl.h ヘッダー ファイルの PROPVARIANT 構造体宣言は、PROPVARIANT 構造体の先頭に対応するように decVal メンバーを定義します。 したがって、 DECIMAL 構造体の値を PROPVARIANT 構造体に配置するには、値を decVal メンバーに読み込む必要があり、 vt メンバーは他の値と同様 にVT_DECIMALに設定されます。

PROPVARIANT は、プロパティ値が IPropertyStorage インターフェイスを介して読み取りおよび書き込まれる基本的なデータ型です。

データ型 PROPVARIANT は、OLE2 の Automation の一部として定義されたデータ型 VARIANT に関連しています。 次のように、複数の定義が Automation から再利用されます。

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;

さらに、一部の型は 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;

一意の PROPVARIANT 型の中には、他のデータ型のカウント配列を定義するいくつかのデータ型があります。 カウントされたすべての配列のデータ型は、CA (CAUB など) で始まり、OR 演算子 vt 値 (要素の VarType と、VT_VECTORを持つ OR 演算子) を持ちます。 カウントされた配列構造には、次の形式があります ( name はカウントされた配列の特定の名前です)。

#define TYPEDEF_CA(type, name) 
 
    typedef struct tag ## name {\
        ULONG cElems;\
        type *pElems;\
        } name
プロパティバリアント型 コード Propvariant メンバー 値表現
VT_EMPTY 0 なし VT_EMPTYの型インジケーターを持つプロパティには、関連付けられているデータがありません。つまり、値のサイズは 0 です。
VT_NULL 1 なし これは NULL へのポインターのようなものです。
VT_I1 16 cVal 1 バイト符号付き整数。
VT_UI1 17 bVal 1 バイト符号なし整数。
VT_I2 2 iVal 2 バイト符号付き整数値を表す 2 バイト。
VT_UI2 18 uiVal 2 バイト符号なし整数。
VT_I4 3 lVal 4 バイト符号付き整数値。
VT_UI4 19 ulVal 4 バイト符号なし整数。
VT_INT 22 intVal 4 バイト符号付き整数値 ( VT_I4と同等)。
VT_UINT 23 uintVal 4 バイト符号なし整数 ( VT_UI4に相当)。
VT_I8 20 hVal 8 バイト符号付き整数。
VT_UI8 21 uhVal 8 バイト符号なし整数。
VT_R4 4 fltVal 32 ビット IEEE 浮動小数点値。
VT_R8 5 dblVal 64 ビット IEEE 浮動小数点値。
VT_BOOL 11 boolVal (以前の設計では bool ) ブール値。0 (FALSE) または -1 (TRUE) を含む WORD
VT_ERROR 10 Scode 状態コードを含む DWORD
VT_CY 6 cyVal 8 バイトの 2 の補数整数 (10,000 でスケーリング)。 この種類は、一般的に通貨金額に使用されます。
VT_DATE 7 date 1899 年 12 月 31 日以降の日数 (秒ではない) を表す 64 ビット浮動小数点数。 たとえば、1900 年 1 月 1 日は 2.0、1900 年 1 月 2 日は 3.0 などです)。 これは、 VT_R8と同じ表現で格納されます。
VT_FILETIME 64 filetime Win32 で定義されている 64 ビット FILETIME 構造体。 すべての時刻を世界協定時刻 (UTC) に格納することをお勧めします。
VT_CLSID 72 puuid クラス識別子 (CLSID) (またはその他のグローバル一意識別子 (GUID) へのポインター)。
VT_CF 71 pclipdata 上で説明した CLIPDATA 構造体へのポインター。
VT_BSTR 8 bstrVal null で終わる Unicode 文字列へのポインター。 文字列の直前にはバイト数を表す DWORD が付きますが、 bstrVal はこの DWORD を超えて文字列の最初の文字を指します。 BSTRは、Automation SysAllocString 呼び出しと SysFreeString 呼び出しを使用して割り当ておよび解放する必要があります。
VT_BSTR_BLOB 0xfff bstrblobVal システムでの使用専用です。
VT_BLOB 65 blob (blob) DWORD のバイト数。その後に多数のデータバイトが続きます。 バイト数には、カウント自体の長さの 4 バイトは含まれません。空の BLOB メンバーのカウントは 0 で、その後に 0 バイトが続きます。 これは VT_BSTR値に似ていますが、データの末尾に null バイトが保証されるわけではありません。
VT_BLOBOBJECT 70 blob (blob) VT_STREAMED_OBJECTに表示されるのと同じ表現でシリアル化されたオブジェクトを含む BLOB メンバー。 つまり、 DWORD バイト数 (バイト数にはそれ自体のサイズは含まれません) です。これは、クラス識別子の形式で、そのクラスの初期化データが続きます。

VT_BLOB_OBJECTVT_STREAMED_OBJECTの唯一の大きな違いは、前者にはシステム レベルのストレージ オーバーヘッドがないため、少数の小さなオブジェクトを含むシナリオに適しています。

VT_LPSTR 30 pszVal システムの既定のコード ページで null で終わる ANSI 文字列へのポインター。
VT_LPWSTR 31 pwszVal ユーザーの既定のロケールで null で終わる Unicode 文字列へのポインター。
VT_UNKNOWN 13 punkVal 新しいトピック。
VT_DISPATCH 9 pdispVal 新しいトピック。
VT_STREAM 66 pStream "Contents" ストリームの兄弟であるストリームを表す IStream インターフェイスへのポインター。
VT_STREAMED_OBJECT 68 pStream VT_STREAMのように、ストリームにシリアル化されたオブジェクト (CLSID の後にクラスの初期化データが続く) が含まれていることを示します。 ストリームは、プロパティ セットを含む "Contents" ストリームの兄弟です。
VT_STORAGE 67 pStorage "Contents" ストリームの兄弟であるストレージ オブジェクトを表す IStorage インターフェイスへのポインター。
VT_STORED_OBJECT 69 pStorage VT_STORAGEと同様に、指定された IStorage に読み込み可能なオブジェクトが含まれていることを示します。
VT_VERSIONED_STREAM 73 pVersionedStream GUID バージョンを持つストリーム。
VT_DECIMAL 14 decVal DECIMAL 構造体。
VT_VECTOR 0x1000 Ca* OR 演算子を使用して型インジケーターをVT_VECTORと組み合わせる場合、値はカウントされた配列値のいずれかになります。 これにより、 要素の DWORD 数が作成され、その後に、指定した値の繰り返しへのポインターが作成されます。

たとえば、VT_LPSTR VT_VECTOR|の型インジケーターには DWORD 要素数があり、その後に LPSTR 要素の配列へのポインターが続きます。

VT_VECTORは、OR 演算子と次の型を組み合わせることができます: VT_I1VT_UI1VT_I2VT_UI2VT_BOOLVT_I4VT_UI4 VT_R4VT_R8VT_ERRORVT_I8VT_UI8VT_CYVT_DATEVT_FILETIMEVT_CLSIDVT_CFVT_BSTRVT_LPSTRVT_LPWSTRVT_VARIANT. VT_VECTORは、VT_BSTR_BLOBを使用した OR 操作でも組み合わせることができますが、システム専用です。

VT_ARRAY 0x2000 Parray 型インジケーターが OR 演算子によってVT_ARRAYと組み合わされている場合、値は SAFEARRAY へのポインターです。 VT_ARRAYは、VT_I1、VT_UI1、VT_I2VT_UI2VT_I4VT_UI4、VT_INT、VT_UINTVT_R4、VT_R8、VT_BOOLVT_DECIMAL、VT_ERROR、VT_CYVT_DATEVT_BSTRVT_DISPATCHVT_UNKNOWNVT_VARIANTのデータ型で OR を使用できます。 VT_ARRAYは、VT_VECTOROR を使用できません。
VT_BYREF 0x4000 P* 型インジケーターが OR 演算子によってVT_BYREFと組み合わされている場合、値は参照です。 参照型は、C++ の参照型 ("int&" など) と同様に、データへの参照として解釈されます。

VT_BYREFは、VT_I1VT_UI1VT_I2VT_UI2VT_I4、VT_UI4VT_INTVT_UINTVT_R4VT_R8VT_BOOLVT_DECIMALVT_ERRORVT_CYVT_DATEVT_BSTR、VT_UNKNOWNVT_DISPATCHVT_ARRAYVT_VARIANTの各種類で使用できます

VT_VARIANT 12 capropvar DWORD 型インジケーターの後に対応する値が続きます。 VT_VARIANT は、 VT_VECTOR または VT_BYREFでのみ使用できます。
VT_TYPEMASK 0xFFF   生 VT 値を抽出するための VT_VECTOR およびその他の修飾子のマスクとして使用されます。
 

タグ VT_CFと共に格納されるクリップボード形式識別子は、特定のデータ型への pClipData ポインターを使用して CLIPDATA 構造体の ulClipFmt メンバーで識別される 5 つの表現のいずれかを使用します。

ulClipFmt pClipData
-1L 組み込みの Windows クリップボード形式の値を含む DWORD
-2L Macintosh クリップボード形式の値を含む DWORD
-3L 形式識別子 (FMTID) を含む GUID。 これはまれに使用されます。
正の値 RegisterClipboardFormat 関数への渡しに適した Windows クリップボード形式名を含む null で終わる文字列。 この関数は、新しいクリップボード形式を登録します。 指定した名前の登録済み形式が既に存在する場合、新しい形式は登録されず、戻り値によって既存の形式が識別されます。 これにより、複数のアプリケーションが、同じ登録済みのクリップボード形式を使用してデータをコピーして貼り付けることができます。 書式名の比較では大文字と小文字が区別されず、0xC000から0xFFFFまでの範囲の値によって識別されます。 文字列内の文字に使用されるコード ページは、コード ページインジケーターに従います。 ここでの "正の値" は、末尾の null バイトを含む文字列の長さです。 クリップボードの登録形式をクリップボードに配置またはクリップボードから取得する場合は、オブジェクトへのハンドルを提供する HGLOBAL データ型の値の形式である必要があります。
0L データなし (まれに使用されます)。
 

ulClipFmt メンバーの値が -1 の場合、データは組み込みの Windows 形式になります。 この場合、pClipData が指すバッファーの最初の DWORD はクリップボード形式識別子です (例: CF_METAFILEPICT)。 CF_METAFILEPCTの場合、次に示すのは METAFILEPICT 構造体のバリエーションです (DWORD データ型ではなく WORD を使用します)。 つまり、このデータは次の形式になります。

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

METAFILEPICT 構造体がメタファイル データの後に、SetMetaFileBitsEx 関数に渡されるのに適しています。 この関数は、指定されたデータからメモリ ベースの Windows 形式のメタファイルを作成します。 この関数は、16 ビット バージョンの Windows との互換性のために提供されます。 Win32 ベースのアプリケーションでは 、SetEnhMetaFileBits 関数を使用する必要があります。 この関数は、指定された拡張形式メタファイルの内容を取得し、バッファーにコピーします。 関数が成功し、バッファー ポインターが NULL の場合、戻り値は拡張メタファイルのサイズ (バイト単位) です。 関数が成功し、バッファー ポインターが有効なポインターである場合、戻り値はバッファーにコピーされたバイト数です。 関数が失敗した場合は、0 を返します。

クリップボードの登録形式をクリップボードに配置またはクリップボードから取得する場合は、 HGLOBAL 値の形式である必要があります。

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリ |UWP アプリ]
ヘッダー propidl.h (Propidl.h を含む)