IDataObject::EnumFormatEtc メソッド (objidl.h)

[アーティクル]
08/25/2023

データオブジェクトでサポートされている形式を列挙するオブジェクトを作成します。

構文

HRESULT EnumFormatEtc(
  [in]  DWORD          dwDirection,
  [out] IEnumFORMATETC **ppenumFormatEtc
);

パラメーター

[in] dwDirection

データの方向。指定できる値は、DATADIR 列挙体から取得されます。

DATADIR_GET値は、 IDataObject::GetData の呼び出しに渡すことができる形式を列挙します。 DATADIR_SET値は、 IDataObject::SetData の呼び出しに渡すことができる形式を列挙します。

[out] ppenumFormatEtc

新しい列挙子オブジェクトへのインターフェイスポインターを受け取る IEnumFORMATETC ポインター変数へのポインター。

戻り値

このメソッドは、成功したS_OKを返します。その他の可能な値は次のとおりです。

リターンコード	説明
E_INVALIDARG	指定された dwDirection が無効です。
E_OUTOFMEMORY	この操作で使用できるメモリが不足しています。
E_NOTIMPL	dwDirection で指定された方向はサポートされていません。
OLE_S_USEREG	OLE がレジストリから形式を列挙するように要求します。

注釈

EnumFormatEtc は、データオブジェクトが FORMATETC 構造体内のデータを記述するすべての方法を決定するために使用できる列挙子オブジェクトを作成し、その IEnumFORMATETC インターフェイスへのポインターを提供します。これは、標準の列挙子インターフェイスの 1 つです。

呼び出し元へのメモ

ポインターを取得した後、呼び出し元は IEnumFORMATETC の列挙メソッドを呼び出すことによって FORMATETC 構造体を列挙できます。形式は時間の経過と同時に変更される可能性があるため、列挙形式が現在サポートされている保証はありません。形式は時間の経過と同時に変更される可能性があるためです。したがって、アプリケーションでは、列挙型を渡すことができる形式の型のヒントとして扱う必要があります。呼び出し元は、列挙子が終了したときに Release を呼び出す役割を担います。

EnumFormatEtc は、次のいずれかのアクションが発生したときに呼び出されます。

アプリケーションは OleSetClipboard を呼び出します。 OLE では、クリップボードに配置するデータと、OLE 1 互換性形式をクリップボードに配置する必要があるかどうかを判断する必要があります。
データがクリップボードから貼り付けされているか、削除されています。アプリケーションでは、最初に受け入れられる形式が使用されます。
[ 形式を選択して貼り付け ] ダイアログボックスが表示されます。ターゲットアプリケーションは、FORMATETC エントリから形式の一覧をビルドします。

実装者へのメモ

形式は、レジストリに静的に登録することも、オブジェクトの初期化中に動的に登録することもできます。オブジェクトに変更のない形式の一覧があり、これらの形式がレジストリに登録されている場合、OLE は、レジストリ内の特定の CLSID に登録されている形式を列挙できる FORMATETC 列挙オブジェクトの実装を提供します。 IEnumFORMATETC インターフェイスへのポインターは、ヘルパー関数 OleRegEnumFormatEtc の呼び出しを通じて使用できます。そのため、この状況では、この関数を呼び出すだけで EnumFormatEtc メソッドを実装できます。

EXE アプリケーションでは、メソッドを実装して値OLE_S_USEREGを返すことで、実質的に同じことを行うことができます。この戻り値は、 OleRegEnumFormatEtc を呼び出すように既定のオブジェクトハンドラーに指示します。 DLL オブジェクトアプリケーションとして実装されているオブジェクトアプリケーションは、OLE_S_USEREGを返すことができないため、 OleRegEnumFormatEtc を直接呼び出す必要があります。

プライベート形式は、レジストリの RequestDataFormats キーまたは SetDataFormats キーに登録されている場合、OLE 1 オブジェクトに対して列挙できます。また、プライベート形式は、GETDataFormats キーまたは SetDataFormats キーに登録されている場合、OLE オブジェクト (OLE 1 以降のすべてのバージョン) に対して列挙できます。

サーバーに RequestDataFormats または SetDataFormats 情報が登録されていない OLE 1 オブジェクトの場合、 enumFormatEtc を呼び出してDATADIR_GETを渡すと、これらの形式がサポートされているかどうかに関係なく、ネイティブ形式とメタファイル形式のみが列挙されます。このようなオブジェクトでDATADIR_SETを渡す EnumFormatEtc を呼び出すと、オブジェクトが他の形式で設定されているかどうかに関係なく、ネイティブのみが列挙されます。

列挙型によって返される FORMATETC 構造体は、通常 、NULL ターゲットデバイス (ptd) を示します。これは、 FORMATETC の他のメンバーとは異なり、ターゲットデバイスが SetData 呼び出しまたは GetData 呼び出しでデータを受け入れるか提供できるかに関するオブジェクトの決定に関与しないため、適切です。

FORMATETCの tymed メンバーは、多くの場合、複数の種類のストレージメディアが許容されることを示します。ブール OR 演算子を使用して、これを常にマスクしてテストする必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	objidl.h