PROPVARIANT 構造体 (propidl.h)
PROPVARIANT 構造体は、プロパティ セット内のプロパティの型タグと値を定義するために、IPropertyStorage の ReadMultiple メソッドと WriteMultiple メソッドで使用されます。
PROPVARIANT 構造体は、IPropertyStore の GetValue メソッドと SetValue メソッドでも使用されます。このメソッドは、Windows Vista で項目プロパティをプログラムする主な方法として IPropertySetStorage を置き換えます。 詳細については、「 プロパティ ハンドラー」を参照してください。
メンバーは 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
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_BLOB、 VT_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_STREAM、 VT_STREAMED_OBJECT
tag_inner_PROPVARIANT.pStorage
VT_STORAGE、 VT_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_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 | "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_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は、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のデータ型で OR を使用できます。 VT_ARRAYは、VT_VECTORで OR を使用できません。 |
| VT_BYREF | 0x4000 | P* | 型インジケーターが OR 演算子によってVT_BYREFと組み合わされている場合、値は参照です。 参照型は、C++ の参照型 ("int&" など) と同様に、データへの参照として解釈されます。
VT_BYREFは、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。 これはまれに使用されます。 |
| 正の値 | 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 を含む) |