SetClipboardData Function (User32) - Windows API Reference

Function

The SetClipboardData function opens the clipboard for examination and eliminates, discards, or changes the contents of the clipboard. The system determines the appropriate format for the clipboard data.

Syntax

BOOL SetClipboardData(
  UINT  uFormat,
  HANDLE  hMem
);

Parameters

uFormat
[in]
The data format for the clipboard. This parameter can be a standard clipboard format, or a registered clipboard format.
- CF_BITMAP
- CF_DIB
- CF_DIBV5
- CF_ENHMETAFILE
- CF_HDROP
- CF_LOCALE
- CF_METAFILEPICT
- CF_OWNERDISPLAY
- CF_PALETTE
- CF_PENDING
- CF_TEXT
- CF_UNICODETEXT
- CF_ENHMETAFILE
hMem
[in, optional]
A handle to the memory object that contains the clipboard data. If this parameter is NULL, the clipboard is cleared for the specified format.

If hMem is a handle to a memory object created with the GMEM_MOVEABLE flag, the system will move the object in global memory. If hMem is a handle to a memory object created with the GMEM_FIXED flag, the system will not move the object.

The application must own the memory block specified by hMem. The clipboard owns the memory object after this function returns. The application must not allocate or free the memory object.

Return Value

If the function succeeds, the return value is a handle to a global memory object that contains the data to be added to the clipboard.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Before calling SetClipboardData, you must open the clipboard by calling the OpenClipboard function; otherwise, the function will fail.
After calling SetClipboardData, you must call the CloseClipboard function.
If hMem is a handle to a memory object created with the GMEM_MOVEABLE flag, you must not use the handle after calling SetClipboardData, as the system might move the memory object.
If hMem is NULL, the function clears the clipboard for the specified format.
If hMem is not NULL, the system automatically allocates memory for the clipboard data and copies the data into that memory. The application should not allocate or free the memory object specified by hMem.
The system automatically frees the clipboard memory object when the clipboard is emptied or reset by a subsequent call to EmptyClipboard or SetClipboardData.
If uFormat is CF_OWNERDISPLAY, the hMem parameter must be a handle to a window that will process the clipboard data.

Examples

For more information and code examples, refer to the Clipboard Programming Example.

Example: Setting text to the clipboard

// Assume hClipboard is a handle to the clipboard
// Assume lpString is a null-terminated string to be copied

HGLOBAL hGlobal = GlobalAlloc(GMEM_MOVEABLE, lstrlen(lpString) + 1);
if (hGlobal != NULL) {
    LPSTR lpData = (LPSTR)GlobalLock(hGlobal);
    if (lpData != NULL) {
        strcpy(lpData, lpString);
        GlobalUnlock(hGlobal);
        if (SetClipboardData(CF_TEXT, hGlobal) == NULL) {
            // Handle error
            GlobalFree(hGlobal); // Free if SetClipboardData fails
        } else {
            // Data successfully set, system now owns hGlobal
        }
    } else {
        // Handle GlobalLock error
        GlobalFree(hGlobal);
    }
} else {
    // Handle GlobalAlloc error
}

SetClipboardData