PROPVARIANT 構造体 (propidlbase.h)
PROPVARIANT 構造体は、IPropertyStorage の ReadMultiple メソッドと WriteMultiple メソッドで使用され、プロパティ セット内のプロパティの型タグと値を定義します。
PROPVARIANT 構造体は、IPropertyStore の GetValue メソッドと SetValue メソッドでも使用されます。これにより、IPropertySetStorage が Windows Vista の項目プロパティをプログラムする主な方法として置き換えられます。 詳細については、「 プロパティ ハンドラー」を参照してください。
メンバーは 5 人です。 最初のメンバー、値型タグ、および最後のメンバー (プロパティの値) は重要です。 中央の 3 つのメンバーは、将来の使用のために予約されています。
構文
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
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
注釈
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
| プロバリアント型 | コード | 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_OBJECTとVT_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_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、 VT_VARIANT。 VT_VECTORは、VT_BSTR_BLOBを持つOR 操作によって組み合わせることもできますが、システムでのみ使用されます。 |
| VT_ARRAY | 0x2000 | Parray | 型インジケーターが OR 演算子によってVT_ARRAYと組み合わされている場合、値は SAFEARRAY へのポインターです。 VT_ARRAYは、OR を、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、VT_VARIANTのデータ型で使用できます。 VT_ARRAYVT_VECTORでOR を使用することはできません。 |
| VT_BYREF | 0x4000 | P* | 型インジケーターが OR 演算子によってVT_BYREFと組み合わされている場合、値は参照です。 参照型は、C++ の参照型 ("int&" など) と同様に、データへの参照として解釈されます。
VT_BYREFでは、ORは、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、VT_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。 これはまれに使用されます。 |
| 正の値 | Windows クリップボード形式名を含む null で終わる文字列。 RegisterClipboardFormat 関数への渡しに適しています。 この関数は、新しいクリップボード形式を登録します。 指定した名前の登録済み形式が既に存在する場合、新しい形式は登録されず、戻り値によって既存の形式が識別されます。 これにより、複数のアプリケーションで、同じ登録済みクリップボード形式を使用してデータをコピーして貼り付けることができます。 形式名の比較では大文字と小文字が区別されず、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 | propidlbase.h (Propidl.h を含む) |