SetClipboardData function

Places data on the clipboard in a specified clipboard format. The window must be the current clipboard owner, and the application must have called the OpenClipboard function. (When responding to the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages, the clipboard owner must not call OpenClipboard before calling SetClipboardData.)

Syntax


HANDLE WINAPI SetClipboardData(
  _In_      UINT uFormat,
  _In_opt_  HANDLE hMem
);

Parameters

uFormat [in]

Type: UINT

The clipboard format. This parameter can be a registered format or any of the standard clipboard formats. For more information, see Standard Clipboard Formats and Registered Clipboard Formats.

hMem [in, optional]

Type: HANDLE

A handle to the data in the specified format. This parameter can be NULL, indicating that the window provides data in the specified clipboard format (renders the format) upon request. If a window delays rendering, it must process the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages.

If SetClipboardData succeeds, the system owns the object identified by the hMem parameter. The application may not write to or free the data once ownership has been transferred to the system, but it can lock and read from the data until the CloseClipboard function is called. (The memory must be unlocked before the Clipboard is closed.) If the hMem parameter identifies a memory object, the object must have been allocated using the function with the GMEM_MOVEABLE flag.

Return value

Type: HANDLE

If the function succeeds, the return value is the handle to the data.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Windows 8: Bitmaps to be shared with Windows Store app apps must be in the CF_BITMAP format (device-dependent bitmap).

If an application calls SetClipboardData in response to WM_RENDERFORMAT or WM_RENDERALLFORMATS, the application should not use the handle after SetClipboardData has been called.

If an application calls OpenClipboard with hwnd set to NULL, EmptyClipboard sets the clipboard owner to NULL; this causes SetClipboardData to fail.

The system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand. For more information, see Synthesized Clipboard Formats.

Examples

For an example, see Copying Information to the Clipboard.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winuser.h (include Windows.h)

Library

User32.lib

DLL

User32.dll

See also

Reference
CloseClipboard
GetClipboardData
OpenClipboard
RegisterClipboardFormat
WM_RENDERFORMAT
WM_RENDERALLFORMATS
Conceptual
Clipboard

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.