OleSetClipboard  CLFKQD

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

WINOLEAPI OleSetClipboard(

Parameter

pDataObj

[in] Pointer to the IDataObjectZHWNNR 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 Values

S_OK

The IDataObject pointer was placed on the clipboard.

CLIPBRD_E_CANT_OPEN

The Windows OpenClipboard function used within OleSetClipboard failed.

CLIPBRD_E_CANT_EMPTY

The Windows EmptyClipboard function used within OleSetClipboard failed.

CLIPBRD_E_CANT_CLOSE

The Windows CloseClipboard 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:

  1.  Create a data object (on which is the IDataObjectZHWNNR 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.

  2.  Call OleSetClipboard to place the IDataObject pointer onto the clipboard, so it is accessible to the OleGetClipboardKCS835 function. OleSetClipboard also calls the IUnknown::AddRef method on your data object.

  3.  If you wish, release the data object once you have placed it on the clipboard to free the IUnknown::AddRef counter in your application.

  4.  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 OleFlushClipboardHDB2_Z 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 Win32 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 IDataObjectZHWNNR 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 instead of OleSetClipboard.

See Also