nf-ole2-olegetclipboard.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name	req.apiset
NF:ole2.OleGetClipboard	OleGetClipboard function (ole2.h)	Retrieves a data object that you can use to access the contents of the clipboard.	OleGetClipboard OleGetClipboard function [COM] _ole_OleGetClipboard com.olegetclipboard ole2/OleGetClipboard	com\olegetclipboard.htm	com	c5e7badb-339b-48d5-8c9a-3950e2ffe6bf	12/05/2018	OleGetClipboard, OleGetClipboard function [COM], _ole_OleGetClipboard, com.olegetclipboard, ole2/OleGetClipboard	ole2.h		Windows	Windows 2000 Professional [desktop apps only]	Windows 2000 Server [desktop apps only]										Ole32.lib	Ole32.dll		Windows			19H1	OleGetClipboard ole2/OleGetClipboard	c++	APIRef kbSyntax	DllExport	Ole32.dll API-MS-Win-RTCore-OLE32-clipboard-l1-1-0.dll ie_shims.dll ext-ms-win-ole32-clipboard-ie-l1-1-0.dll API-MS-Win-RTCore-Ole32-Clipboard-L1-1-1.dll	OleGetClipboard	ext-ms-win-com-ole32-l1-1-5 (introduced in Windows 10, version 10.0.15063)

OleGetClipboard function

-description

Retrieves a data object that you can use to access the contents of the clipboard.

-parameters

-param ppDataObj [out]

Address of IDataObject pointer variable that receives the interface pointer to the clipboard data object.

-returns

This function returns S_OK on success. Other possible values include the following.

Return code	Description
CLIPBRD_E_CANT_OPEN	The OpenClipboard function used within OleFlushClipboard failed.
CLIPBRD_E_CANT_CLOSE	The CloseClipboard function used within OleFlushClipboard failed.

-remarks

Caution  Clipboard data is not trusted. Parse the data carefully before using it in your application.

 

If you are writing an application that can accept data from the clipboard, call the OleGetClipboard function to get a pointer to the IDataObject interface that you can use to retrieve the contents of the clipboard.

OleGetClipboard handles three cases:

• The application that placed data on the clipboard with the OleSetClipboard function is still running.
• The application that placed data on the clipboard with the OleSetClipboard function has subsequently called the OleFlushClipboard function.
• There is data from a non-OLE application on the clipboard.

In the first case, the clipboard data object returned by OleGetClipboard may forward calls as necessary to the original data object placed on the clipboard and, thus, can potentially make RPC calls.

In the second case, OLE creates a default data object and returns it to the user. Because the data on the clipboard originated from an OleSetClipboard call, the OLE-provided data object contains more accurate information about the type of data on the clipboard. In particular, the original medium (TYMED) on which the data was offered is known. Thus, if a data-source application offers a particular clipboard format, for example cfFOO, on a storage object and calls the OleFlushClipboard function, the storage object is copied into memory and the hglobal memory handle is put on the clipboard. Then, when the OleGetClipboard function creates its default data object, the hglobal from the clipboard again becomes an IStorage object. Furthermore, the FORMATETC enumerator and the IDataObject::QueryGetData method would all correctly indicate that the original clipboard format (cfFOO) is again available on a TYMED_ISTORAGE.

In the third case, OLE still creates a default data object, but there is no special information about the data in the clipboard formats (particularly for application-defined Clipboard formats). Thus, if an hGlobal-based storage medium were put on the clipboard directly by a call to the SetClipboardData function, the FORMATETC enumerator and the IDataObject::QueryGetData method would not indicate that the data was available on a storage medium. A call to the IDataObject::GetData method for TYMED_ISTORAGE would succeed, however. Because of these limitations, it is strongly recommended that OLE-aware applications interact with the clipboard using the OLE clipboard functions.

The clipboard data object created by the OleGetClipboard function has a fairly extensive IDataObject implementation. The OLE-provided data object can convert OLE 1 clipboard format data into the representation expected by an OLE 2 caller. Also, any structured data is available on any structured or flat medium, and any flat data is available on any flat medium. However, GDI objects (such as metafiles and bitmaps) are only available on their respective mediums.

Note that the tymed member of the FORMATETC structure used in the FORMATETC enumerator contains the union of supported mediums. Applications looking for specific information (such as whether CF_TEXT is available on TYMED_HGLOBAL) should do the appropriate bitmasking when checking this value.

If you call the OleGetClipboard function, you should only hold on to the returned IDataObject for a very short time. It consumes resources in the application that offered it.

-see-also

OleSetClipboard