COleDataObject 类

在数据传输中用于从剪贴板、通过拖放或从嵌入 OLE 项检索各种格式的数据。

语法

class COleDataObject

成员

公共构造函数

名称	描述
COleDataObject::COleDataObject	构造 COleDataObject 对象。

公共方法

名称	描述
COleDataObject::Attach	将指定的 OLE 数据对象附加到 COleDataObject。
COleDataObject::AttachClipboard	附加剪贴板上的数据对象。
COleDataObject::BeginEnumFormats	准备一个或多个后续 GetNextFormat 调用。
COleDataObject::Detach	分离关联的 IDataObject 对象。
COleDataObject::GetData	以指定的格式从附加的 OLE 数据对象复制数据。
COleDataObject::GetFileData	以指定的格式将数据从附加的 OLE 数据对象复制到 CFile 指针中。
COleDataObject::GetGlobalData	以指定的格式将数据从附加的 OLE 数据对象复制到 HGLOBAL 中。
COleDataObject::GetNextFormat	返回下一种可用数据格式。
COleDataObject::IsDataAvailable	检查数据是否以指定的格式提供。
COleDataObject::Release	分离并释放关联的 IDataObject 对象。

注解

COleDataObject 没有基类。

这些类型的数据传输包括源和目标。 数据源实现为 COleDataSource 类的对象。 每当目标应用程序中放入了数据或者它需要从剪贴板执行粘贴操作时，都必须创建 COleDataObject 类的对象。

使用此类可以确定数据是否以指定的格式存在。 还可以枚举可用的数据格式或检查给定的格式是否可用，然后以首选格式检索数据。 可通过多种不同的方式完成对象检索，包括使用 CFile、HGLOBAL 或 STGMEDIUM 结构。

有关详细信息，请参阅 Windows SDK 中的 STGMEDIUM 结构。

有关在应用程序中使用数据对象的详细信息，请参阅数据对象和数据源 (OLE) 一文。

继承层次结构

COleDataObject

要求

标头：afxole.h

COleDataObject::Attach

调用此函数可将 COleDataObject 对象与 OLE 数据对象相关联。

void Attach(
    LPDATAOBJECT lpDataObject,
    BOOL bAutoRelease = TRUE);

参数

lpDataObject
指向 OLE 数据对象。

bAutoRelease
如果在销毁 COleDataObject 对象时应释放 OLE 数据对象，则为 TRUE；否则为 FALSE。

备注

有关详细信息，请参阅 Windows SDK 中的 IDataObject。

COleDataObject::AttachClipboard

调用此函数可将剪贴板上当前的数据对象附加到 COleDataObject 对象。

BOOL AttachClipboard();

返回值

如果成功，则不为 0；否则为 0。

注解

注意

调用此函数可锁定剪贴板，直到释放此数据对象。 数据对象在 COleDataObject 的析构函数中释放。 有关详细信息，请参阅 Win32 文档中的 OpenClipboard 和 CloseClipboard。

COleDataObject::BeginEnumFormats

调用此函数可准备后续的 GetNextFormat 调用以从项中检索数据格式列表。

void BeginEnumFormats();

备注

调用 BeginEnumFormats 后，将存储此数据对象支持的第一种格式的位置。 连续调用 GetNextFormat 会枚举数据对象中可用格式的列表。

若要检查给定格式的数据的可用性，请使用 COleDataObject::IsDataAvailable。

有关详细信息，请参阅 Windows SDK 中的 IDataObject::EnumFormatEtc。

COleDataObject::COleDataObject

构造 COleDataObject 对象。

COleDataObject();

注解

必须先调用 COleDataObject::Attach 或 COleDataObject::AttachClipboard，然后再调用其他 COleDataObject 函数。

注意

由于拖放处理程序的参数之一是指向 COleDataObject 的指针，因此无需调用此构造函数即可支持拖放。

COleDataObject::Detach

调用此函数可将 COleDataObject 对象与其关联的 OLE 数据对象相分离，而无需释放该数据对象。

LPDATAOBJECT Detach();

返回值

指向已分离的 OLE 数据对象的指针。

注解

COleDataObject::GetData

调用此函数可从指定格式的项中检索数据。

BOOL GetData(
    CLIPFORMAT cfFormat,
    LPSTGMEDIUM lpStgMedium,
    LPFORMATETC lpFormatEtc = NULL);

参数

cfFormat
返回数据的格式。 此参数可以是预定义的剪贴板格式之一，也可以是本机 Windows RegisterClipboardFormat 函数返回的值。

lpStgMedium
指向接收数据的 STGMEDIUM 结构。

lpFormatEtc
指向描述所要返回的数据的格式的 FORMATETC 结构。 如果你希望指定由 cfFormat 指定的剪贴板格式以外的其他格式信息，请为此参数提供值。 如果此参数为 NULL，则默认值将用于 FORMATETC 结构中的其他字段。

返回值

如果成功，则不为 0；否则为 0。

注解

有关详细信息，请参阅 Windows SDK 中的 IDataObject::GetData、STGMEDIUM 和 FORMATETC。

有关详细信息，请参阅 Windows SDK 中的 RegisterClipboardFormat。

COleDataObject::GetFileData

调用此函数可创建 CFile 或 CFile 派生对象，并将指定格式的数据检索到 CFile 指针中。

CFile* GetFileData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

参数

cfFormat
返回数据的格式。 此参数可以是预定义的剪贴板格式之一，也可以是本机 Windows RegisterClipboardFormat 函数返回的值。

lpFormatEtc
指向描述所要返回的数据的格式的 FORMATETC 结构。 如果你希望指定由 cfFormat 指定的剪贴板格式以外的其他格式信息，请为此参数提供值。 如果此参数为 NULL，则默认值将用于 FORMATETC 结构中的其他字段。

返回值

如果成功，则返回指向包含数据的新 CFile 或 CFile 派生对象的指针；否则返回 NULL。

注解

根据用于存储数据的媒体，返回值指向的实际类型可能是 CFile、CSharedFile 或 COleStreamFile。

注意

此函数的返回值访问的 CFile 对象由调用方拥有。 调用方负责对 CFile 对象运行 delete，从而关闭文件。

有关详细信息，请参阅 Windows SDK 中的 FORMATETC。

有关详细信息，请参阅 Windows SDK 中的 RegisterClipboardFormat。

COleDataObject::GetGlobalData

调用此函数可分配一个全局内存块，并将指定格式的数据检索到 HGLOBAL 中。

HGLOBAL GetGlobalData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

参数

cfFormat
返回数据的格式。 此参数可以是预定义的剪贴板格式之一，也可以是本机 Windows RegisterClipboardFormat 函数返回的值。

lpFormatEtc
指向描述所要返回的数据的格式的 FORMATETC 结构。 如果你希望指定由 cfFormat 指定的剪贴板格式以外的其他格式信息，请为此参数提供值。 如果此参数为 NULL，则默认值将用于 FORMATETC 结构中的其他字段。

返回值

如果成功，则返回包含数据的全局内存块的句柄；否则返回 NULL。

注解

有关详细信息，请参阅 Windows SDK 中的 FORMATETC。

有关详细信息，请参阅 Windows SDK 中的 RegisterClipboardFormat。

COleDataObject::GetNextFormat

反复调用此函数可获取可用于从项中检索数据的所有格式。

BOOL GetNextFormat(LPFORMATETC lpFormatEtc);

参数

lpFormatEtc
指向函数调用返回时接收格式信息的 FORMATETC 结构。

返回值

如果另一种格式可用，则返回非零值；否则返回 0。

备注

调用 COleDataObject::BeginEnumFormats 后，将存储此数据对象支持的第一种格式的位置。 连续调用 GetNextFormat 会枚举数据对象中可用格式的列表。 使用这些函数可列出可用的格式。

若要检查给定格式的可用性，请调用 COleDataObject::IsDataAvailable。

有关详细信息，请参阅 Windows SDK 中的 IEnumXXXX::Next。

COleDataObject::IsDataAvailable

调用此函数可确定特定的格式是否可用于从 OLE 项中检索数据。

BOOL IsDataAvailable(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

参数

cfFormat
要在 lpFormatEtc 指向的结构中使用的剪贴板数据格式。 此参数可以是预定义的剪贴板格式之一，也可以是本机 Windows RegisterClipboardFormat 函数返回的值。

lpFormatEtc
指向描述所需格式的 FORMATETC 结构。 只有当你希望指定由 cfFormat 指定的剪贴板格式以外的其他格式信息时，才为此参数提供值。 如果此参数为 NULL，则默认值将用于 FORMATETC 结构中的其他字段。

返回值

如果数据以指定的格式提供，则返回非零值；否则返回 0。

备注

在调用 GetData、GetFileData 或 GetGlobalData 之前，此函数很有用。

有关详细信息，请参阅 Windows SDK 中的 IDataObject::QueryGetData 和 FORMATETC。

有关详细信息，请参阅 Windows SDK 中的 RegisterClipboardFormat。

示例

请参阅 CRichEditView::QueryAcceptData 的示例。

COleDataObject::Release

调用此函数可释放先前与 COleDataObject 对象关联的 IDataObject 对象的所有权。

void Release();

备注

已通过显式调用 Attach 或 AttachClipboard 或者通过框架将 IDataObject 与 COleDataObject 相关联。 如果 Attach 的 bAutoRelease 参数为 FALSE，则不会释放 IDataObject 对象。 在这种情况下，调用方负责通过调用 IUnknown::Release 来释放 IDataObject。

另请参阅

MFC 示例 HIERSVR
MFC 示例 OCLIENT
层次结构图
COleDataSource 类
COleClientItem 类
COleServerItem 类