OleSetClipboard function (ole2.h)

  • Article

Places a pointer to a specific data object onto the clipboard. This makes the data object accessible to the OleGetClipboard function.

Syntax

HRESULT OleSetClipboard(
  [in] LPDATAOBJECT pDataObj
);

Parameters

[in] pDataObj

Pointer to the IDataObject interface on the data object from which the data to be placed on the clipboard can be obtained. This parameter can be NULL; in which case the clipboard is emptied.

Return value

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 OleSetClipboard failed.
CLIPBRD_E_CANT_EMPTY
 The EmptyClipboard function used within OleSetClipboard failed.
CLIPBRD_E_CANT_CLOSE
 The CloseClipboard function used within OleSetClipboard failed.
CLIPBRD_E_CANT_SET
 The SetClipboardData function used within OleSetClipboard failed.

Remarks

If you are writing an application that can act as the source of a clipboard operation, you must do the following:

  • Create a data object (on which is the IDataObject interface) for the data being copied or cut to the clipboard. This object should be the same object used in OLE drag-and-drop operations.
  • Call OleSetClipboard to place the IDataObject pointer onto the clipboard, so it is accessible to the OleGetClipboard function. OleSetClipboard also calls the IUnknown::AddRef method on your data object.
  • If you wish, release the data object after you have placed it on the clipboard to free the IUnknown::AddRef counter in your application.
  • If the user is cutting data (deleting it from the document and putting it on to the clipboard), remove the data from the document.
All formats are offered on the clipboard using delayed rendering (the clipboard contains only a pointer to the data object unless a call to OleFlushClipboard renders the data onto the clipboard). The formats necessary for OLE 1 compatibility are synthesized from the OLE 2 formats that are present and are also put on the clipboard.

The OleSetClipboard function assigns ownership of the clipboard to an internal OLE window handle. The reference count of the data object is increased by 1, to enable delayed rendering. The reference count is decreased by a call to the OleFlushClipboard function or by a subsequent call to OleSetClipboard specifying NULL as the parameter value (which clears the clipboard).

When an application opens the clipboard (either directly or indirectly by calling the OpenClipboard function), the clipboard cannot be used by any other application until it is closed. If the clipboard is currently open by another application, OleSetClipboard fails. The internal OLE window handle satisfies WM_RENDERFORMAT messages by delegating them to the IDataObject implementation on the data object that is on the clipboard.

Specifying NULL as the parameter value for OleSetClipboard empties the current clipboard. If the contents of the clipboard are the result of a previous OleSetClipboard call and the clipboard has been released, the IDataObject pointer that was passed to the previous call is released. The clipboard owner should use this as a signal that the data it previously offered is no longer on the clipboard.

If you need to leave the data on the clipboard after your application is closed, you should call OleFlushClipboard rather than calling OleSetClipboard with a NULL parameter value.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header ole2.h
Library Ole32.lib
DLL Ole32.dll
API set ext-ms-win-com-ole32-l1-1-5 (introduced in Windows 10, version 10.0.15063)

See also

OleFlushClipboard

OleGetClipboard

OleIsCurrentClipboard