PROPVARIANT

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

PROPVARIANT 構造体は、IPropertyStore の GetValue メソッドおよび SetValue メソッドでも使用されます。IPropertyStore は、Windows Vista において項目のプロパティをプログラムから扱う主要な手段として IPropertySetStorage を置き換えるものです。詳細については、プロパティ ハンドラーを参照してください。

メンバーは 5 つあります。最初のメンバーである値の型タグと、最後のメンバーであるプロパティの値が意味を持ちます。中間の 3 つのメンバーは将来の使用のために予約されています。

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

    DECIMAL       decVal;        //VT_DECIMAL

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

PROPVARIANT は、 IPropertyStorage インターフェイスを通じてプロパティ値の読み取りと書き込みを行うための基本的なデータ型です。

データ型 PROPVARIANT は、OLE2 のオートメーションの一部として定義されているデータ型 VARIANT と関連があります。次に示すように、いくつかの定義はオートメーションから再利用されています。

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 に固有の型の中には、他のデータ型の要素数付き配列 (counted array) を定義するデータ型がいくつかあります。要素数付き配列のデータ型はすべて CA という文字で始まり (たとえば CAUB)、vt の値は OR 演算子で組み合わせたもの (要素の VarType と VT_VECTOR とのビット単位のOR) になります。要素数付き配列の構造体は次の形式になります (name は、その要素数付き配列の固有の名前です)。

#define TYPEDEF_CA(type, name) 
 
    typedef struct tag ## name {\
        ULONG cElems;\
        type *pElems;\
        } name

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

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 値の形式でなければなりません。