Edit

Share via

COleDataObject Class

  • Article

Used in data transfers for retrieving data in various formats from the Clipboard, through drag and drop, or from an embedded OLE item.

Syntax

class COleDataObject

Members

Public Constructors

Name Description
COleDataObject::COleDataObject Constructs a COleDataObject object.

Public Methods

Name Description
COleDataObject::Attach Attaches the specified OLE data object to the COleDataObject.
COleDataObject::AttachClipboard Attaches the data object that is on the Clipboard.
COleDataObject::BeginEnumFormats Prepares for one or more subsequent GetNextFormat calls.
COleDataObject::Detach Detaches the associated IDataObject object.
COleDataObject::GetData Copies data from the attached OLE data object in a specified format.
COleDataObject::GetFileData Copies data from the attached OLE data object into a CFile pointer in the specified format.
COleDataObject::GetGlobalData Copies data from the attached OLE data object into an HGLOBAL in the specified format.
COleDataObject::GetNextFormat Returns the next data format available.
COleDataObject::IsDataAvailable Checks whether data is available in a specified format.
COleDataObject::Release Detaches and releases the associated IDataObject object.

Remarks

COleDataObject does not have a base class.

These kinds of data transfers include a source and a destination. The data source is implemented as an object of the COleDataSource class. Whenever a destination application has data dropped in it or is asked to perform a paste operation from the Clipboard, an object of the COleDataObject class must be created.

This class enables you to determine whether the data exists in a specified format. You can also enumerate the available data formats or check whether a given format is available and then retrieve the data in the preferred format. Object retrieval can be accomplished in several different ways, including the use of a CFile, an HGLOBAL, or an STGMEDIUM structure.

For more information, see the STGMEDIUM structure in the Windows SDK.

For more information about using data objects in your application, see the article Data Objects and Data Sources (OLE).

Inheritance Hierarchy

COleDataObject

Requirements

Header: afxole.h

COleDataObject::Attach

Call this function to associate the COleDataObject object with an OLE data object.

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

Parameters

lpDataObject
Points to an OLE data object.

bAutoRelease
TRUE if the OLE data object should be released when the COleDataObject object is destroyed; otherwise FALSE.

Remarks

For more information, see IDataObject in the Windows SDK.

COleDataObject::AttachClipboard

Call this function to attach the data object that is currently on the Clipboard to the COleDataObject object.

BOOL AttachClipboard();

Return Value

Nonzero if successful; otherwise 0.

Remarks

Note

Calling this function locks the Clipboard until this data object is released. The data object is released in the destructor for the COleDataObject. For more information, see OpenClipboard and CloseClipboard in the Win32 documentation.

COleDataObject::BeginEnumFormats

Call this function to prepare for subsequent calls to GetNextFormat for retrieving a list of data formats from the item.

void BeginEnumFormats();

Remarks

After a call to BeginEnumFormats, the position of the first format supported by this data object is stored. Successive calls to GetNextFormat will enumerate the list of available formats in the data object.

To check on the availability of data in a given format, use COleDataObject::IsDataAvailable.

For more information, see IDataObject::EnumFormatEtc in the Windows SDK.

COleDataObject::COleDataObject

Constructs a COleDataObject object.

COleDataObject();

Remarks

A call to COleDataObject::Attach or COleDataObject::AttachClipboard must be made before calling other COleDataObject functions.

Note

Since one of the parameters to the drag-and-drop handlers is a pointer to a COleDataObject, there is no need to call this constructor to support drag and drop.

COleDataObject::Detach

Call this function to detach the COleDataObject object from its associated OLE data object without releasing the data object.

LPDATAOBJECT Detach();

Return Value

A pointer to the OLE data object that was detached.

Remarks

COleDataObject::GetData

Call this function to retrieve data from the item in the specified format.

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

Parameters

cfFormat
The format in which data is to be returned. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

lpStgMedium
Points to a STGMEDIUM structure that will receive data.

lpFormatEtc
Points to a FORMATETC structure describing the format in which data is to be returned. Provide a value for this parameter if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, the default values are used for the other fields in the FORMATETC structure.

Return Value

Nonzero if successful; otherwise 0.

Remarks

For more information, see IDataObject::GetData, STGMEDIUM, and FORMATETC in the Windows SDK.

For more information, see RegisterClipboardFormat in the Windows SDK.

COleDataObject::GetFileData

Call this function to create a CFile or CFile-derived object and to retrieve data in the specified format into a CFile pointer.

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

Parameters

cfFormat
The format in which data is to be returned. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

lpFormatEtc
Points to a FORMATETC structure describing the format in which data is to be returned. Provide a value for this parameter if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, the default values are used for the other fields in the FORMATETC structure.

Return Value

Pointer to the new CFile or CFile-derived object containing the data if successful; otherwise NULL.

Remarks

Depending on the medium the data is stored in, the actual type pointed to by the return value may be CFile, CSharedFile, or COleStreamFile.

Note

The CFile object accessed by the return value of this function is owned by the caller. It is the responsibility of the caller to delete the CFile object, thereby closing the file.

For more information, see FORMATETC in the Windows SDK.

For more information, see RegisterClipboardFormat in the Windows SDK.

COleDataObject::GetGlobalData

Call this function to allocate a global memory block and to retrieve data in the specified format into an HGLOBAL.

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

Parameters

cfFormat
The format in which data is to be returned. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

lpFormatEtc
Points to a FORMATETC structure describing the format in which data is to be returned. Provide a value for this parameter if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, the default values are used for the other fields in the FORMATETC structure.

Return Value

The handle of the global memory block containing the data if successful; otherwise NULL.

Remarks

For more information, see FORMATETC in the Windows SDK.

For more information, see RegisterClipboardFormat in the Windows SDK.

COleDataObject::GetNextFormat

Call this function repeatedly to obtain all the formats available for retrieving data from the item.

BOOL GetNextFormat(LPFORMATETC lpFormatEtc);

Parameters

lpFormatEtc
Points to the FORMATETC structure that receives the format information when the function call returns.

Return Value

Nonzero if another format is available; otherwise 0.

Remarks

After a call to COleDataObject::BeginEnumFormats, the position of the first format supported by this data object is stored. Successive calls to GetNextFormat will enumerate the list of available formats in the data object. Use these functions to list the available formats.

To check for the availability of a given format, call COleDataObject::IsDataAvailable.

For more information, see IEnumXXXX::Next in the Windows SDK.

COleDataObject::IsDataAvailable

Call this function to determine if a particular format is available for retrieving data from the OLE item.

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

Parameters

cfFormat
The Clipboard data format to be used in the structure pointed to by lpFormatEtc. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

lpFormatEtc
Points to a FORMATETC structure describing the format desired. Provide a value for this parameter only if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, the default values are used for the other fields in the FORMATETC structure.

Return Value

Nonzero if data is available in the specified format; otherwise 0.

Remarks

This function is useful before calling GetData, GetFileData, or GetGlobalData.

For more information, see IDataObject::QueryGetData and FORMATETC in the Windows SDK.

For more information, see RegisterClipboardFormat in the Windows SDK.

Example

See the example for CRichEditView::QueryAcceptData.

COleDataObject::Release

Call this function to release ownership of the IDataObject object that was previously associated with the COleDataObject object.

void Release();

Remarks

The IDataObject was associated with the COleDataObject by calling Attach or AttachClipboard explicitly or by the framework. If the bAutoRelease parameter of Attach is FALSE, the IDataObject object will not be released. In this case, the caller is responsible for releasing the IDataObject by calling IUnknown::Release.

See also

MFC Sample HIERSVR
MFC Sample OCLIENT
Hierarchy Chart
COleDataSource Class
COleClientItem Class
COleServerItem Class