Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

OleSetClipboard function

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

pDataObj [in]

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 codeDescription
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.

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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Ole2.h

Library

Ole32.lib

DLL

Ole32.dll

See also

OleFlushClipboard
OleGetClipboard
OleIsCurrentClipboard

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.