IDataObject

データ転送とデータ変更の通知を可能にします。

ソースとなるデータオブジェクトからデータを取得するために、データコンシューマーによって呼び出されます。

このメソッドは成功時に S_OK を返します。その他に返される可能性がある値は次のとおりです。

戻り値	説明
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_FORMATETC	pformatetcIn の値が無効です。
DV_E_TYMED	tymed の値が無効です。
DV_E_DVASPECT	dwAspect の値が無効です。
OLE_E_NOTRUNNING	オブジェクトのアプリケーションが実行されていません。
STG_E_MEDIUMFULL	媒体の割り当て時にエラーが発生しました。
E_UNEXPECTED	予期しないエラーが発生しました。
E_INVALIDARG	dwDirection の値が無効です。
E_OUTOFMEMORY	この操作に十分なメモリがありませんでした。

データコンシューマーは、STGMEDIUM 構造体で定義された記憶媒体を介して伝達されるデータをデータオブジェクトから取得するために、GetData を呼び出します。

呼び出し側への注意

ブール OR 演算子を使用して、複数の許容可能な tymed 媒体を指定できます。GetData は、OR で結合された値の中からデータを最もよく表現する媒体を選択し、割り当てを行い、媒体を解放する責任の所在を示さなければなりません。

ストリームを介して転送されるデータは、ストリームポインターの位置ゼロから、現在のストリームポインター(すなわち、終了時のストリームポインターの位置)の直前の位置までにわたります。

実装者への注意

GetData は、FORMATETC 構造体のすべてのフィールドをチェックしなければなりません。GetData が要求されたアスペクトをレンダリングし、可能であれば要求された媒体を使用することが重要です。データオブジェクトが FORMATETC で指定された情報に従えない場合、このメソッドは DV_E_FORMATETC を返す必要があります。媒体の割り当ての試みが失敗した場合、このメソッドは STG_E_MEDIUMFULL を返す必要があります。STGMEDIUM 構造体のすべてのフィールドを埋めることが重要です。

呼び出し側はデータを返す媒体を複数指定できますが、GetData が提供できる媒体は 1 つだけです。選択した媒体で最初の転送が失敗した場合、エラーを返す前に、指定された他の媒体の 1 つを試すようにこのメソッドを実装することができます。

ソースとなるデータオブジェクトからデータを取得するために、データコンシューマーによって呼び出されます。このメソッドは、呼び出し側が指定の記憶媒体を割り当てて解放しなければならない点で GetData メソッドと異なります。

このメソッドは成功時に S_OK を返します。その他に返される可能性がある値は次のとおりです。

戻り値	説明
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_FORMATETC	pformatetc の値が無効です。
DV_E_TYMED	tymed の値が無効です。
DV_E_DVASPECT	dwAspect の値が無効です。
OLE_E_NOTRUNNING	オブジェクトのアプリケーションが実行されていません。
STG_E_MEDIUMFULL	媒体の割り当て時にエラーが発生しました。
E_UNEXPECTED	予期しないエラーが発生しました。
E_INVALIDARG	dwDirection パラメーターが無効です。
E_OUTOFMEMORY	この操作に十分なメモリがありませんでした。

GetDataHere メソッドは IDataObject::GetData に似ていますが、pmedium で指定された媒体の割り当てと解放の両方を呼び出し側が行わなければならない点が異なります。GetDataHere は FORMATETC 構造体で記述されたデータをレンダリングし、そのデータを呼び出し側が用意した STGMEDIUM 構造体にコピーします。たとえば、媒体が TYMED_HGLOBAL の場合、このメソッドは媒体のサイズを変更したり、新しい hGlobal を割り当てたりすることはできません。

メタファイルなどの GDI 型を含め、一部の媒体は GetDataHere の呼び出しには適していません。GetDataHere メソッドは、呼び出し側が用意したメタファイルにデータを格納することはできません。一般に、このメソッドでサポートする必要がある記憶媒体は TYMED_ISTORAGE、TYMED_ISTREAM、および TYMED_FILE のみです。

転送媒体がストリームの場合、OLE はデータが返される場所とストリームのシークポインターの位置について仮定を行います。GetData の呼び出しでは、返されるデータはストリームの位置ゼロから、ストリームの現在のシークポインター(すなわち、終了時の位置)の直前までです。GetDataHere では、返されるデータは開始時のストリーム位置から、終了時の位置の直前までです。

データオブジェクトが指定されたとおりにデータをレンダリングできるかどうかを判定します。貼り付けやドロップの操作を試みるオブジェクトは、IDataObject::GetData を呼び出す前にこのメソッドを呼び出すことで、その操作が成功する可能性があるかどうかを事前に知ることができます。

このメソッドは成功時に S_OK を返します。その他に返される可能性がある値は次のとおりです。

戻り値	説明
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_FORMATETC	pformatetc の値が無効です。
DV_E_TYMED	tymed の値が無効です。
DV_E_DVASPECT	dwAspect の値が無効です。
OLE_E_NOTRUNNING	オブジェクトのアプリケーションが実行されていません。
E_UNEXPECTED	予期しないエラーが発生しました。
E_INVALIDARG	dwDirection の値が無効です。
E_OUTOFMEMORY	この操作に十分なメモリがありません。

データオブジェクトのクライアントは、指定された FORMATETC 構造体を後続の IDataObject::GetData 呼び出しに渡した場合に成功する可能性が高いかどうかを判定するために、QueryGetData を呼び出します。このメソッドが成功を返しても、その後の貼り付けやドロップの操作の成功が必ずしも保証されるわけではありません。

論理的に等価でありながら異なる可能性のある FORMATETC 構造体を提供します。このメソッドは、2 つの異なる FORMATETC 構造体が同じデータを返すかどうかを判定し、重複したレンダリングの必要性をなくすために使用します。

このメソッドは次の値を返すことがあります。

戻り値	説明
S_OK	返された FORMATETC 構造体は、渡されたものと異なります。
DATA_S_SAMEFORMATETC	FORMATETC 構造体は同一であり、pformatetcOut には NULL が返されます。
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_FORMATETC	pformatetc の値が無効です。
OLE_E_NOTRUNNING	オブジェクトのアプリケーションが実行されていません。
E_UNEXPECTED	予期しないエラーが発生しました。
E_INVALIDARG	dwDirection パラメーターが無効です。
E_OUTOFMEMORY	この操作に十分なメモリがありませんでした。

データオブジェクトが複数の要求された FORMATETC 構造体に対してまったく同じデータを提供できる場合、GetCanonicalFormatEtc は、より複雑な FORMATETC 構造体の集合と同じレンダリングを与える「正規の」、すなわち標準的な FORMATETC を提供できます。たとえば、それ以外は類似している一連の FORMATETC 構造体のいずれかで指定されたターゲットデバイスに対して、返されるデータが影響を受けないことはよくあります。

呼び出し側への注意

このメソッドの呼び出しにより、2 つの異なる FORMATETC 構造体を指定したデータオブジェクトへの 2 回の IDataObject::GetData 呼び出しが実際に同じレンダリングを生成するかどうかを判定でき、2 回目の呼び出しを不要にしてパフォーマンスを向上させることができます。GetCanonicalFormatEtc の呼び出しによって正規形式が pformatetcOut パラメーターに書き込まれた場合、呼び出し側はその構造体を後続の IDataObject::GetData 呼び出しで使用します。

実装者への注意

概念的には、FORMATETC 構造体を、各グループメンバーと同じ結果を提供する正規の FORMATETC によって定義されるグループにまとめて考えることができます。正規の FORMATETC を構築する際は、特定のレンダリングを生成しつつも可能な限り一般的な情報を含むようにする必要があります。

デバイス固有のレンダリングを一切提供しないデータオブジェクトの場合、このメソッドの最も単純な実装は、入力の FORMATETC を出力の FORMATETC にコピーし、出力の FORMATETC の ptd メンバーに NULL を格納し、DATA_S_SAMEFORMATETC を返すことです。

データソースを含むオブジェクトから、このメソッドを実装するオブジェクトへデータを転送するために呼び出されます。

このメソッドは成功時に S_OK を返します。その他に返される可能性がある値は次のとおりです。

戻り値	説明
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_FORMATETC	pformatetc の値が無効です。
DV_E_TYMED	tymed の値が無効です。
DV_E_DVASPECT	dwAspect の値が無効です。
OLE_E_NOTRUNNING	オブジェクトのアプリケーションが実行されていません。
E_FAIL	操作が失敗しました。
E_UNEXPECTED	予期しないエラーが発生しました。
E_INVALIDARG	dwDirection の値が無効です。
E_OUTOFMEMORY	この操作に十分なメモリがありませんでした。

SetData は、別のオブジェクトが実装側のデータオブジェクトにデータを送信しようとすることを可能にします。データオブジェクトは、別のオブジェクトからのデータの受信をサポートする場合にこのメソッドを実装します。これをサポートしない場合は、E_NOTIMPL を返すように実装する必要があります。

呼び出し側は、データが渡される pmedium パラメーターで示される記憶媒体を割り当てます。呼び出された側のデータオブジェクトは、データを正常に受信してエラーコードが返されるまで、データの所有権を取得しません。fRelease パラメーターの値は、呼び出しから戻った後の媒体の所有権を示します。FALSE は、呼び出し側が引き続き媒体を所有し、データオブジェクトは呼び出しの間だけそれを使用することを示します。TRUE は、データオブジェクトが媒体を所有するようになり、不要になったときにそれを解放しなければならないことを示します。

pformatetc パラメーターと pmedium パラメーターで指定される媒体の種類は同一でなければなりません。たとえば、一方がグローバルハンドルで他方がストリームであってはなりません。

データオブジェクトがサポートする形式を列挙するオブジェクトを作成します。

このメソッドは成功時に 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 を直接呼び出さなければなりません。

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

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

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

FORMATETC の tymed メンバーは、多くの場合、複数の種類の記憶媒体が許容可能であることを示します。ブール OR 演算子を使用して、これを常にマスクしてテストする必要があります。

アドバイスシンクをサポートするオブジェクトによって、データオブジェクトとアドバイスシンクの間の接続を作成するために呼び出されます。これにより、アドバイスシンクはオブジェクトのデータの変更を通知されるようになります。

このメソッドは成功時に S_OK を返します。その他に返される可能性がある値は次のとおりです。

戻り値	説明
E_NOTIMPL	このメソッドはデータオブジェクトに実装されていません。
DV_E_LINDEX	lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_FORMATETC	pformatetc の値が無効です。
OLE_E_ADVISENOTSUPPORTED	データオブジェクトは変更通知をサポートしていません。

DAdvise は、データオブジェクトと呼び出し側の間に変更通知接続を作成します。呼び出し側は、オブジェクトのデータが変更されたときに通知を送信できるアドバイザリシンクを提供します。

単純にデータ転送に使用されるオブジェクトは、通常アドバイザリ通知をサポートせず、DAdvise から OLE_E_ADVISENOTSUPPORTED を返します。

呼び出し側への注意

アドバイスシンクをサポートするオブジェクトは、渡す FORMATETC 構造体に関心のある形式、アスペクト、媒体、および/またはターゲットデバイスを指定して、接続を設定するために DAdvise を呼び出します。データオブジェクトが要求された属性の 1 つ以上をサポートしていない場合、または通知の送信をまったくサポートしていない場合、OLE_E_ADVISENOTSUPPORTED を返すことで接続を拒否できます。

リンクされたオブジェクトのコンテナーは、バインドされたリンクソースと直接、または接続を管理する標準の OLE リンクオブジェクトを通じて間接的にアドバイザリ接続を設定できます。バインドされたリンクソースで設定された接続は自動的には削除されません。コンテナーは、アドバイザリ接続を削除するために、バインドされたリンクソース上で IDataObject::DUnadvise を明示的に呼び出さなければなりません。IOleLink インターフェイスを通じて操作される OLE リンクオブジェクトは、既定のハンドラーに実装されています。OLE リンクオブジェクトを通じて設定された接続は、リンクオブジェクトが削除されたときに破棄されます。

OLE の既定のリンクオブジェクトは、OLE が最後の変更時刻を維持できるように、リンクソースとの「ワイルドカードアドバイズ」を作成します。このアドバイズは、何かが変更された時刻を記録するために特に使用されます。OLE は変更された可能性のあるすべてのデータ形式を無視し、最後の変更時刻のみを記録します。ワイルドカードアドバイズを許可するには、DAdvise を呼び出す前に FORMATETC のメンバーを次のように設定します。

cf == 0; 
ptd == NULL; 
dwAspect == -1; 
lindex == -1 
tymed == -1;

アドバイズフラグには ADVF_NODATA も含める必要があります。OLE からのワイルドカードアドバイズは、アプリケーションによって常に受け入れられるべきです。

実装者への注意

通知をサポートする IDataObject の DAdvise およびその他の通知メソッド(DUnadvise と EnumDAdvise)の実装を簡素化するために、OLE は通知の登録と送信を管理するアドバイズホルダーオブジェクトを提供します。このオブジェクトへのポインターを取得するには、DAdvise の最初の呼び出し時にヘルパー関数 CreateDataAdviseHolder を呼び出します。これにより、オブジェクトの IDataAdviseHolder インターフェイスへのポインターが提供されます。次に、呼び出しをデータアドバイズホルダー内の IDataAdviseHolder::Advise メソッドに委譲します。このメソッドが要求された接続を作成し、以後管理します。

以前に設定された通知接続を破棄します。

このメソッドは成功時に S_OK を返します。その他に返される可能性がある値は次のとおりです。

戻り値	説明
OLE_E_NOCONNECTION	指定された dwConnection の値は有効な接続ではありません。
OLE_E_ADVISENOTSUPPORTED	この IDataObject の実装は通知をサポートしていません。

このメソッドは、IDataObject::DAdvise メソッドの呼び出しによって作成された通知を破棄します。

削除するアドバイザリ接続が、当初 IDataObject::DAdvise の呼び出しを IDataAdviseHolder::Advise に委譲することで設定された場合、それを削除するにはこの呼び出しを IDataAdviseHolder::Unadvise に委譲しなければなりません。

現在のアドバイザリ接続を列挙するために使用できるオブジェクトを作成します。

このメソッドは、列挙子オブジェクトが正常にインスタンス化された場合、または接続が存在しない場合に S_OK を返します。その他に返される可能性がある値は次のとおりです。

戻り値	説明
E_OUTOFMEMORY	この操作に十分なメモリがありません。
OLE_E_ADVISENOTSUPPORTED	このオブジェクトはアドバイザリ通知をサポートしていません。

このメソッドによって作成される列挙子オブジェクトは、IEnumSTATDATA インターフェイスを実装します。IEnumSTATDATA は、STATDATA 構造体の配列に格納されたデータの列挙を可能にします。これらの各構造体は単一のアドバイザリ接続に関する情報を提供し、FORMATETC および ADVF の情報に加えて、アドバイスシンクへのポインターと接続を表すトークンを含みます。

呼び出し側への注意

アドバイザリ接続を扱うには、OLE のデータアドバイズホルダーオブジェクトを使用することをお勧めします。CreateDataAdviseHolder の呼び出しを通じて取得したポインターを使用すれば、IDataObject::EnumDAdvise の実装は、呼び出しを IDataAdviseHolder::EnumAdvise に委譲するだけの単純なものになります。これにより列挙子が作成され、OLE による IEnumSTATDATA の実装へのポインターが提供されます。その時点で、そのメソッドを呼び出して現在のアドバイザリ接続を列挙できます。

#define global IID_IDataObject "{0000010E-0000-0000-C000-000000000046}"
#usecom global IDataObject IID_IDataObject "{}"
#comfunc global IDataObject_GetData                3 var,var
#comfunc global IDataObject_GetDataHere            4 var,var
#comfunc global IDataObject_QueryGetData           5 var
#comfunc global IDataObject_GetCanonicalFormatEtc  6 var,var
#comfunc global IDataObject_SetData                7 var,var,int
#comfunc global IDataObject_EnumFormatEtc          8 int,sptr
#comfunc global IDataObject_DAdvise                9 var,int,sptr,var
#comfunc global IDataObject_DUnadvise              10 int
#comfunc global IDataObject_EnumDAdvise            11 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。