Places a pointer to a specific data object onto the clipboard. This makes the data object accessible to the OleGetClipboard function.
HRESULT OleSetClipboard( IN LPDATAOBJECT 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.
This function returns S_OK on success. Other possible values include the following.
||The OpenClipboard function used within OleSetClipboard failed.|
||The EmptyClipboard function used within OleSetClipboard failed.|
||The CloseClipboard function used within OleSetClipboard failed.|
||The SetClipboardData function used within OleSetClipboard failed.|
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.
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.
|Minimum supported client||Windows 2000 Professional [desktop apps only]|
|Minimum supported server||Windows 2000 Server [desktop apps only]|