COleDataSource 类

项目
10/12/2023

充当应用程序将数据放置到的缓存，应用程序将在数据传输操作（如剪贴板或拖放操作）期间提供这些数据。

语法

class COleDataSource : public CCmdTarget

成员

公共构造函数

名称	描述
COleDataSource::COleDataSource	构造 `COleDataSource` 对象。

公共方法

名称	描述
COleDataSource::CacheData	使用 `STGMEDIUM` 结构提供指定格式的数据。
COleDataSource::CacheGlobalData	使用 HGLOBAL 提供指定格式的数据。
COleDataSource::DelayRenderData	使用延迟呈现提供指定格式的数据。
COleDataSource::DelayRenderFileData	在 `CFile` 指针中提供指定格式的数据。
COleDataSource::DelaySetData	针对 `OnSetData` 中支持的每种格式调用。
COleDataSource::DoDragDrop	对数据源执行拖放操作。
COleDataSource::Empty	清空数据的 `COleDataSource` 对象。
COleDataSource::FlushClipboard	将所有数据呈现到剪贴板。
COleDataSource::GetClipboardOwner	验证放置在剪贴板上的数据是否仍在其中。
COleDataSource::OnRenderData	检索数据作为延迟呈现的一部分。
COleDataSource::OnRenderFileData	将数据检索到 `CFile` 中，作为延迟呈现的一部分。
COleDataSource::OnRenderGlobalData	将数据检索到 HGLOBAL 中，作为延迟呈现的一部分。
COleDataSource::OnSetData	调用以替换 `COleDataSource` 对象中的数据。
COleDataSource::SetClipboard	在剪贴板上放置 `COleDataSource` 对象。

备注

可以直接创建 OLE 数据源。或者，COleClientItem 和 COleServerItem 类可以创建 OLE 数据源以响应其 CopyToClipboard 和 DoDragDrop 成员函数。有关简要说明，请参阅 COleServerItem::CopyToClipboard。重写客户端项或服务器项类的 OnGetClipboardData 成员函数，以将其他剪贴板格式添加到为 CopyToClipboard 或 DoDragDrop 成员函数创建的 OLE 数据源中的数据。

每当准备要传输的数据时，都应该创建此类的一个对象，并使用最适合数据的方法在该对象中填充数据。它插入数据源的方式直接受数据是立即提供（立即呈现）还是按需提供（延迟呈现）的影响。对于通过传递所要使用的剪贴板格式（以及可选的 FORMATETC 结构）提供数据时采用的每种剪贴板格式，请调用 DelayRenderData。

有关数据源和数据传输的详细信息，请参阅数据对象和数据源 (OLE) 一文。此外，剪贴板主题一文介绍了 OLE 剪贴板机制。

继承层次结构

CObject

CCmdTarget

COleDataSource

要求

标头：afxole.h

COleDataSource::CacheData

调用此函数可指定在执行数据传输操作期间提供数据时采用的格式。

void CacheData(
    CLIPFORMAT cfFormat,
    LPSTGMEDIUM lpStgMedium,
    LPFORMATETC lpFormatEtc = NULL);

参数

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

lpStgMedium
指向包含指定格式的数据的 STGMEDIUM 结构。

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

备注

必须提供数据，因为此函数使用立即呈现来提供数据。数据将一直缓存到需要它为止。

使用 STGMEDIUM 结构提供数据。如果提供的数据量太小，以致无法使用 HGLOBAL 有效传输，则你也可以使用 CacheGlobalData 成员函数。

在调用 CacheData 后，lpFormatEtc 的 ptd 成员和 lpStgMedium 的内容将由数据对象而不是调用方所有。

若要使用延迟呈现，请调用 DelayRenderData 或 DelayRenderFileData 成员函数。有关 MFC 处理的延迟呈现的详细信息，请参阅数据对象和数据源：操作一文。

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

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

COleDataSource::CacheGlobalData

调用此函数可指定在执行数据传输操作期间提供数据时采用的格式。

void CacheGlobalData(
    CLIPFORMAT cfFormat,
    HGLOBAL hGlobal,
    LPFORMATETC lpFormatEtc = NULL);

参数

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

hGlobal
包含指定格式的数据的全局内存块的句柄。

注解

此函数使用立即呈现来提供数据，因此在调用该函数时必须提供数据；数据将一直缓存到需要它为止。如果你要提供大量数据或需要结构化存储媒体，请使用 CacheData 成员函数。

若要使用延迟呈现，请调用 DelayRenderData 或 DelayRenderFileData 成员函数。有关 MFC 处理的延迟呈现的详细信息，请参阅数据对象和数据源：操作一文。

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

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

COleDataSource::COleDataSource

构造 COleDataSource 对象。

COleDataSource();

COleDataSource::DelayRenderData

调用此函数可指定在执行数据传输操作期间提供数据时采用的格式。

void DelayRenderData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

参数

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

备注

此函数使用延迟呈现来提供数据，因此不会立即提供数据。调用 OnRenderData 或 OnRenderGlobalData 成员函数来请求数据。

如果你不打算通过 CFile 对象提供数据，请使用此函数。如果你要通过 CFile 对象提供数据，请调用 DelayRenderFileData 成员函数。有关 MFC 处理的延迟呈现的详细信息，请参阅数据对象和数据源：操作一文。

若要使用立即呈现，请调用 CacheData 或 CacheGlobalData 成员函数。

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

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

COleDataSource::DelayRenderFileData

调用此函数可指定在执行数据传输操作期间提供数据时采用的格式。

void DelayRenderFileData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

参数

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

备注

此函数使用延迟呈现来提供数据，因此不会立即提供数据。调用 OnRenderFileData 成员函数来请求数据。

如果你要使用 CFile 对象来提供数据，请使用此函数。如果你不打算使用 CFile 对象，请调用 DelayRenderData 成员函数。有关 MFC 处理的延迟呈现的详细信息，请参阅数据对象和数据源：操作一文。

若要使用立即呈现，请调用 CacheData 或 CacheGlobalData 成员函数。

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

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

COleDataSource::DelaySetData

调用此函数可以支持更改数据源的内容。

void DelaySetData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

参数

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

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

注解

发生这种情况时，框架将调用 OnSetData。仅当框架从 COleServerItem::GetDataSource 返回数据源时才使用它。如果未调用 DelaySetData，则永远不会调用 OnSetData 函数。应针对支持的每种剪贴板或 FORMATETC 格式调用 DelaySetData。

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

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

COleDataSource::DoDragDrop

调用 DoDragDrop 成员函数可对此数据源执行拖放操作（通常在 CWnd::OnLButtonDown 处理程序中）。

DROPEFFECT DoDragDrop(
    DWORD dwEffects = DROPEFFECT_COPY|DROPEFFECT_MOVE|DROPEFFECT_LINK,
    LPCRECT lpRectStartDrag = NULL,
    COleDropSource* pDropSource = NULL);

参数

dwEffects
允许对此数据源执行的拖放操作。可以是以下一项或多项：

DROPEFFECT_COPY：可执行复制操作。
DROPEFFECT_MOVE：可执行移动操作。
DROPEFFECT_LINK：可建立从已放置的数据到原始数据的链接。
DROPEFFECT_SCROLL：指示可能发生拖动滚动操作。

lpRectStartDrag
指向定义拖动实际开始位置的矩形的指针。有关更多信息，请参见下面的“备注”部分。

pDropSource
指向放置源。如果为 NULL，则将使用 COleDropSource 的默认实现。

返回值

返回拖放操作生成的放置效果；否则，如果操作因为用户在退出提供的矩形之前松开了鼠标按钮而从未开始，则返回 DROPEFFECT_NONE。

备注

拖放操作不会立即启动。它等待鼠标光标离开 lpRectStartDrag 指定的矩形，或者直到经过了指定的毫秒数。如果 lpRectStartDrag 为 NULL，则矩形的大小为一个像素。

延迟时间由注册表项设置指定。可以通过调用 CWinApp::WriteProfileString 或 CWinApp::WriteProfileInt 来更改延迟时间。如果未指定延迟时间，则使用默认值 200 毫秒。拖动延迟时间存储如下：

Windows NT 拖动延迟时间存储在 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\NT\CurrentVersion\IniFileMapping\win.ini\Windows\DragDelay 中。
Windows 3.x 拖动延迟时间存储在 [Windows} 部分下的 WIN.INI 文件中。
Windows 95/98 拖动延迟时间存储在 WIN.INI 的缓存版本中。

有关如何将拖动延迟信息存储在注册表或 .INI 文件中的详细信息，请参阅 Windows SDK 中的 WriteProfileString。

有关详细信息，请参阅 OLE 拖放一文。

COleDataSource::Empty

调用此函数可清空数据的 COleDataSource 对象。

void Empty();

备注

将清空缓存呈现格式和延迟呈现格式，使其可供重复使用。

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

COleDataSource::FlushClipboard

呈现剪贴板上的数据，然后让你在应用程序关闭后粘贴剪贴板中的数据。

static void PASCAL FlushClipboard();

备注

使用 SetClipboard 将数据放在剪贴板上。

COleDataSource::GetClipboardOwner

确定自上次调用 SetClipboard 以来剪贴板上的数据是否已更改，如果是，则标识当前所有者。

static COleDataSource* PASCAL GetClipboardOwner();

返回值

返回剪贴板上的当前数据源；如果剪贴板上没有任何内容或剪贴板不由调用方应用程序拥有，则返回 NULL。

COleDataSource::OnRenderData

由框架调用，以检索采用指定格式的数据。

virtual BOOL OnRenderData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium);

参数

lpFormatEtc
指向 FORMATETC 结构，该结构指定请求的信息的格式。

lpStgMedium
指向要在其中返回数据的 STGMEDIUM 结构。

返回值

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

注解

指定的格式是先前使用用于延迟呈现的 DelayRenderData 或 DelayRenderFileData 成员函数放入 COleDataSource 对象中的一种格式。如果提供的存储媒体是文件或内存，则此函数的默认实现将调用 OnRenderFileData 或 OnRenderGlobalData。如果未提供上述任一格式，则默认实现将返回 0 且不执行任何操作。有关 MFC 处理的延迟呈现的详细信息，请参阅数据对象和数据源：操作一文。

如果 lpStgMedium->tymed 为 TYMED_NULL，则应按照 lpFormatEtc->tymed 的指定分配和填充 STGMEDIUM。如果它不是 TYMED_NULL，则应就地使用数据填充 STGMEDIUM。

这是一个高级可重写函数。重写此函数以便以请求的格式和媒体提供数据。根据数据，可能需要改为替代此函数的其他版本之一。如果数据很小且大小固定，请替代 OnRenderGlobalData。如果数据在文件中或大小可变，请重写 OnRenderFileData。

有关详细信息，请参阅 Windows SDK 中的 STGMEDIUM 和 FORMATETC 结构、TYMED 枚举类型以及 IDataObject::GetData。

COleDataSource::OnRenderFileData

当指定的存储媒体为文件时由框架调用，以检索采用指定格式的数据。

virtual BOOL OnRenderFileData(
    LPFORMATETC lpFormatEtc,
    CFile* pFile);

参数

lpFormatEtc
指向 FORMATETC 结构，该结构指定请求的信息的格式。

pFile
指向要在其中呈现数据的 CFile 对象。

返回值

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

注解

指定的格式是先前使用用于延迟呈现的 DelayRenderData 成员函数放入 COleDataSource 对象中的一种格式。此函数的默认实现只会返回 FALSE。

这是一个高级可重写函数。重写此函数以便以请求的格式和媒体提供数据。根据数据，可能需要改为替代此函数的其他版本之一。如果你想要处理多个存储媒体，请重写 OnRenderData。如果数据在文件中或大小可变，请重写 OnRenderFileData。有关 MFC 处理的延迟呈现的详细信息，请参阅数据对象和数据源：操作一文。

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

COleDataSource::OnRenderGlobalData

当指定的存储媒体为全局内存时由框架调用，以检索采用指定格式的数据。

virtual BOOL OnRenderGlobalData(
    LPFORMATETC lpFormatEtc,
    HGLOBAL* phGlobal);

参数

lpFormatEtc
指向 FORMATETC 结构，该结构指定请求的信息的格式。

phGlobal
指向要在其中返回数据的全局内存的句柄。如果尚未分配句柄，则此参数可为 NULL。

返回值

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

注解

指定的格式是先前使用用于延迟呈现的 DelayRenderData 成员函数放入 COleDataSource 对象中的一种格式。此函数的默认实现只会返回 FALSE。

如果 phGlobal 为 NULL，则应分配并在 phGlobal 中返回一个新的 HGLOBAL。否则，应使用数据填充 phGlobal 指定的 HGLOBAL。放在 HGLOBAL 中的数据量不得超过内存块的当前大小。此外，不能将块重新分配为更大的大小。

这是一个高级可重写函数。重写此函数以便以请求的格式和媒体提供数据。根据数据，可能需要改为替代此函数的其他版本之一。如果你想要处理多个存储媒体，请重写 OnRenderData。如果数据在文件中或大小可变，请重写 OnRenderFileData。有关 MFC 处理的延迟呈现的详细信息，请参阅数据对象和数据源：操作一文。

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

COleDataSource::OnSetData

由框架调用，以便以指定的格式设置或替换 COleDataSource 对象中的数据。

virtual BOOL OnSetData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium,
    BOOL bRelease);

参数

lpFormatEtc
指向 FORMATETC 结构，该结构指定要替换的数据采用的格式。

lpStgMedium
指向 STGMEDIUM 结构，该结构包含用于替换 COleDataSource 对象当前内容的数据。

bRelease
指示完成函数调用后存储媒体由谁拥有。调用方决定谁负责释放代表存储媒体分配的资源。调用方通过设置 bRelease 来做出此决定。如果 bRelease 不为零，则数据源将取得所有权，并在使用完媒体后释放媒体。如果 bRelease 为 0，则调用方将保留所有权，数据源只能在调用持续时间内使用存储媒体。

返回值

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

备注

数据源在成功获取数据之前不会取得数据的所有权。也就是说，如果 OnSetData 返回 0，则不会取得所有权。如果数据源取得所有权，它将通过调用 ReleaseStgMedium 函数来释放存储媒体。

默认实现不执行任何操作。重写此函数以替换采用指定格式的数据。这是一个高级可重写函数。

有关详细信息，请参阅 Windows SDK 中的 STGMEDIUM 和 FORMATETC 结构，以及 ReleaseStgMedium 和 IDataObject::GetData 函数。

COleDataSource::SetClipboard

调用以下函数之一后，将 COleDataSource 对象中包含的数据放在剪贴板上：CacheData、CacheGlobalData、DelayRenderData 或 DelayRenderFileData。

void SetClipboard();

另请参阅

MFC 示例 HIERSVR
MFC 示例 OCLIENT
CCmdTarget 类
 层次结构图
 COleDataObject 类

通过

COleDataSource 类

语法

成员

公共构造函数

公共方法

备注

继承层次结构

要求

COleDataSource::CacheData

参数

备注

COleDataSource::CacheGlobalData

参数

注解

COleDataSource::COleDataSource

COleDataSource::DelayRenderData

参数

备注

COleDataSource::DelayRenderFileData

参数

备注

COleDataSource::DelaySetData

参数

注解

COleDataSource::DoDragDrop

参数

返回值

备注

COleDataSource::Empty

备注

COleDataSource::FlushClipboard

备注

COleDataSource::GetClipboardOwner

返回值

COleDataSource::OnRenderData

参数

返回值

注解

COleDataSource::OnRenderFileData

参数

返回值

注解

COleDataSource::OnRenderGlobalData

参数

返回值

注解

COleDataSource::OnSetData

参数

返回值

备注

COleDataSource::SetClipboard

另请参阅

反馈

其他资源