PROPVARIANT 構造体 (propidl.h)

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

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

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

メモこの構造体の以前の定義の bool メンバーの名前が boolVal に変更されました。一部のコンパイラでは bool がキーワード (keyword)として認識されるようになりました。
 
メモ 以下に定義されている 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 のオートメーションの一部として定義されているデータ型 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
プロバリアント型 コード プロパティのメンバー 値表現
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 "コンテンツ" ストリームの兄弟であるストリームを表す IStream インターフェイスへのポインター。
VT_STREAMED_OBJECT 68 pStream VT_STREAMと同様ですが、ストリームにシリアル化されたオブジェクト (CLSID の後に クラスの初期化データが続く) が含まれていることを示します。 ストリームは、プロパティ セットを含む "コンテンツ" ストリームの兄弟です。
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_UI4VT_R4VT_R8VT_ERRORVT_I8VT_UI8VT_CYVT_DATEVT_FILETIMEVT_CLSIDVT_CFVT_BSTRVT_LPSTRVT_LPWSTRVT_VARIANTVT_VECTORは、VT_BSTR_BLOBを持つOR 操作によって組み合わせることもできますが、システムでのみ使用されます。

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

VT_BYREFは、VT_I1VT_UI1VT_I2、VT_UI2VT_I4、VT_UI4VT_INT、VT_UINT、VT_R4VT_R8VT_BOOLVT_DECIMAL、VT_ERROR、VT_CYVT_DATEVT_BSTR、VT_UNKNOWNVT_DISPATCHVT_ARRAYVT_VARIANTの各種類で OR を使用できます。

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 アプリ]
Header propidl.h (Propidl.h を含む)