COleDataSource 類別

發行項
08/04/2024

做為快取，應用程式在此放置資料，以便在資料傳輸作業 (例如剪貼簿或拖放作業) 期間提供。

語法

class COleDataSource : public CCmdTarget

成員

公用建構函式

名稱	描述
COleDataSource：：COleDataSource	建構 `COleDataSource` 物件。

公用方法

名稱	描述
COleDataSource：：CacheData	使用 `STGMEDIUM` 結構，以指定的格式提供數據。
COleDataSource：：CacheGlobalData	使用 HGLOBAL 以指定的格式提供數據。
COleDataSource：:D elayRenderData	使用延遲轉譯，以指定的格式提供數據。
COleDataSource：:D elayRenderFileData	以指標中的 `CFile` 指定格式提供數據。
COleDataSource：:D elaySetData	針對中 `OnSetData`支援的每個格式呼叫。
COleDataSource：:D oDragDrop	使用數據源執行拖放作業。
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 ptd 成員lpFormatEtc之後，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：:D elayRenderData

呼叫此函式，以指定在資料傳輸作業期間提供數據的格式。

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：:D elayRenderFileData

呼叫此函式，以指定在資料傳輸作業期間提供數據的格式。

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

參數

cfFormat
要提供數據的剪貼簿格式。此參數可以是其中一個預先定義的剪貼簿格式，或原生 Windows RegisterClipboardFormat 函式所傳回的值。

備註

此函式會使用延遲轉譯來提供數據，因此不會立即提供數據。呼叫 OnRenderFileData 成員函式以要求數據。

如果您要使用 CFile 物件來提供數據，請使用此函式。如果您不打算使用 CFile 物件，請呼叫 DelayRenderData 成員函式。如需 MFC 所處理之延遲轉譯的詳細資訊，請參閱數據對象和數據源：操作一文。

若要使用立即轉譯，請呼叫 CacheData 或 CacheGlobalData 成員函式。

如需詳細資訊，請參閱 Windows SDK 中的 FORMATETC 結構。

如需詳細資訊，請參閱 Windows SDK 中的 RegisterClipboardFormat 。

COleDataSource：:D elaySetData

呼叫此函式以支援變更數據源的內容。

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

參數

cfFormat
要放置數據的剪貼簿格式。此參數可以是其中一個預先定義的剪貼簿格式，或原生 Windows RegisterClipboardFormat 函式所傳回的值。

lpFormatEtc
指向 FORMATETC 結構，描述要取代數據的格式。如果您想要指定 cfFormat 所指定之剪貼簿格式以外的其他格式資訊，請提供此參數的值。如果是 NULL，則會針對結構中的其他 FORMATETC 欄位使用預設值。

備註

發生此情況時，架構會呼叫 OnSetData 。只有當架構從 COleServerItem：：GetDataSource 傳回數據源時，才會使用此方法。如果未 DelaySetData 呼叫，則永遠不會呼叫您的 OnSetData 函式。 DelaySetData 應該針對您支援的每個剪貼簿或 FORMATETC 格式呼叫。

如需詳細資訊，請參閱 Windows SDK 中的 FORMATETC 結構。

如需詳細資訊，請參閱 Windows SDK 中的 RegisterClipboardFormat 。

COleDataSource：:D oDragDrop

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 拖曳延遲時間會儲存在 WIN 中。INI 檔案，位於 [Windows}] 區段底下。
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。

備註

指定的格式是先前使用DelayRenderData或 DelayRenderFileData成員函式放置於物件中COleDataSource，以供延遲轉譯。如果提供的儲存媒體分別是檔案或記憶體，則此函式的預設實作會呼叫 OnRenderFileData 或 OnRenderGlobalData 。如果未提供這些格式，則預設實作會傳回 0，而且不會執行任何動作。如需 MFC 所處理之延遲轉譯的詳細資訊，請參閱數據對象和數據源：操作一文。

如果 lpStgMedium-tymed> 是TYMED_NULL，STGMEDIUM則應該依照 lpFormatEtc-tymed> 所指定來配置並填入。如果它不是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。

備註

指定的格式是先前使用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。

備註

指定的格式是先前使用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。

備註

在成功取得數據之前，數據源不會取得數據的擁有權。也就是說，如果 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：:D elayRenderData

參數

備註

COleDataSource：:D elayRenderFileData

參數

備註

COleDataSource：:D elaySetData

參數

備註

COleDataSource：:D oDragDrop

參數

傳回值

備註

COleDataSource：：Empty

備註

COleDataSource：：FlushClipboard

備註

COleDataSource：：GetClipboardOwner

傳回值

COleDataSource：：OnRenderData

參數

傳回值

備註

COleDataSource：：OnRenderFileData

參數

傳回值

備註

COleDataSource：：OnRenderGlobalData

參數

傳回值

備註

COleDataSource：：OnSetData

參數

傳回值

備註

COleDataSource：：SetClipboard

另請參閱

意見反應

其他資源