{"id":5763,"date":"2012-12-24T07:00:00","date_gmt":"2012-12-24T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2012\/12\/24\/what-is-the-proper-handling-of-wm_renderformat-and-wm_renderallformats\/"},"modified":"2024-07-15T07:37:07","modified_gmt":"2024-07-15T14:37:07","slug":"20121224-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20121224-00\/?p=5763","title":{"rendered":"What is the proper handling of WM_RENDERFORMAT and WM_RENDERALLFORMATS?"},"content":{"rendered":"

Jeremy points out that the documentation for Set\u00adClipboard\u00adData<\/code> says that the clipboard owner must not call Open\u00adClipboard<\/code> when responding to the WM_RENDER\u00adFORMAT<\/code> and WM_RENDER\u00adALL\u00adFORMATS<\/code> messages. On the other hand, the documentation for WM_RENDER\u00adALL\u00adFORMATS<\/code> says that the owner must call Open\u00adClipboard<\/code> and Empty\u00adClipboard<\/code>. Which is it<\/a>?<\/p>\n

It’s none of them!<\/p>\n

Let’s start with WM_RENDER\u00adFORMAT<\/code>. The reference implementation for a WM_RENDER\u00adFORMAT<\/code> handler goes like this, with all error handling deleted for expository purposes:<\/p>\n

case WM_RENDERFORMAT:\r\n CLIPFORMAT cf = (CLIPFORMAT)wParam;\r\n hData = GenerateFormat(cf);\r\n SetClipboardData(cf, hData);\r\n return 0;\r\n<\/pre>\n
In response to WM_RENDER\u00adFORMAT<\/code>, you simply place the format on the clipboard. No opening is required. In fact, attempting to open will fail<\/i> because the clipboard is already open: It has been opened by the application whose call to Get\u00adClipboard\u00adData<\/code> triggered the delay-render!<\/p>\n
Next comes WM_RENDER\u00adALL\u00adFORMATS<\/code>. The original reference implementation goes like this, again with error checking deleted:<\/p>\n
\/\/ code in italics is wrong -- see discussion below\r\ncase WM_RENDERALLFORMATS:\r\n OpenClipboard(hwnd);\r\n SendMessage(hwnd, WM_RENDERFORMAT, CF_FORMAT1, 0);\r\n SendMessage(hwnd, WM_RENDERFORMAT, CF_FORMAT2, 0);\r\n CloseClipboard();<\/i>\r\n return 0;\r\n<\/pre>\n
In response to WM_RENDER\u00adALL\u00adFORMATS<\/code>, you open the clipboard, then render all your formats into it, and then close the clipboard. And one way to render your formats is simply to send yourself a fake WM_RENDER\u00adFORMAT<\/code> message, which gets the code in the earlier code block to generate the format and place it on the clipboard.<\/p>\n
So you see that everybody is wrong!<\/p>\n
The WM_RENDER\u00adALL\u00adFORMATS<\/code> handler does<\/i> call Open\u00adClipboard<\/code>\u2014if you tried it without the Open\u00adClipboard<\/code> call, you’d notice that the data never made it to the clipboard\u2014and it doesn’t<\/i> call Empty\u00adClipboard<\/code>. (If you did, you’d notice that the Empty\u00adClipboard<\/code> would have wiped out your non-delay-rendered data!)<\/p>\n
Where did I get these reference implementations from? I got them from the Windows 3.1 SDK<\/i>. (And that explains the bug; read on.)<\/p>\n
In real life, you probably would also listen for the WM_DESTROY\u00adCLIPBOARD<\/code> message so you would know that you are no longer the clipboard owner, in which case you wouldn’t bother rendering anything.<\/p>\n
I haven’t written code in a while, so let’s write some code. Start with our  scratch program<\/a> and make these changes. We’ll start by writing it incorrectly:<\/p>\n
BOOL\r\nOnCreate(HWND hwnd, LPCREATESTRUCT lpcs)\r\n{\r\n if (OpenClipboard(hwnd)) {              <\/span>\r\n  EmptyClipboard();                      <\/span>\r\n  SetClipboardData(CF_UNICODETEXT, NULL);<\/span>\r\n  CloseClipboard();                      <\/span>\r\n }                                       <\/span>\r\n return TRUE;\r\n}\r\n\r\nconst WCHAR c_szText[] = L\"hello\";                            <\/span>\r\n\u00a0                                                             <\/span>\r\nHANDLE                                                        <\/span>\r\nOnRenderFormat(HWND hwnd, UINT fmt)                           <\/span>\r\n{                                                             <\/span>\r\n if (fmt == CF_UNICODETEXT)                                   <\/span>\r\n {                                                            <\/span>\r\n  HGLOBAL hglob;                                              <\/span>\r\n  if (SUCCEEDED(CreateHGlobalFromBlob<\/a>(                        <\/span>\r\n                            c_szText, sizeof(c_szText),       <\/span>\r\n                            GMEM_MOVEABLE, &hglob))) {        <\/span>\r\n   if (!SetClipboardData(fmt, hglob)) GlobalFree(hglob);      <\/span>\r\n  }                                                           <\/span>\r\n }                                                            <\/span>\r\n return 0;                                                    <\/span>\r\n}                                                             <\/span>\r\n\u00a0                                                             <\/span>\r\nvoid                                                          <\/span>\r\nOnRenderAllFormats(HWND hwnd)                                 <\/span>\r\n{                                                             <\/span>\r\n if (OpenClipboard(hwnd)) {                                   <\/span>\r\n  OnRenderFormat(hwnd, CF_UNICODETEXT);<\/i>                       <\/span>\r\n  CloseClipboard();                                           <\/span>\r\n }                                                            <\/span>\r\n}                                                             <\/span>\r\n\u00a0                                                             <\/span>\r\n    HANDLE_MSG(hwnd, WM_RENDERFORMAT, OnRenderFormat);        <\/span>\r\n    HANDLE_MSG(hwnd, WM_RENDERALLFORMATS, OnRenderAllFormats);<\/span>\r\n<\/pre>\n
There’s a tiny race condition in that implementation above, though. What if somebody takes ownership of the clipboard while you’re trying to render all your formats<\/i>? Let’s force the race condition. Set a breakpoint on the On\u00adRender\u00adAll\u00adFormats<\/code> function, run the program, and close the window. The breakpoint will hit.<\/p>\n
Switch away from the debugger and open Notepad. Type 123<\/tt> into Notepad, then select it and type Ctrl<\/kbd>+C<\/kbd> to copy it to the clipboard.<\/p>\n
Notepad will hang for a while, since the window manager is trying to send a WM_DESTROY\u00adCLIPBOARD<\/code> message to tell the previous clipboard owner that it is no longer responsible for the data on the clipboard. Let the call time out, at which point Notepad will wake back up and put 123<\/tt> text on the clipboard. Now resume execution of the scratch program, so that it puts the Unicode word hello<\/tt> onto the clipboard.<\/p>\n
Okay, go back to Notepad and hit Ctrl<\/kbd>+V<\/kbd>. Look, it pasted hello<\/tt> instead of 123<\/tt>. Oops, our delay-rendering program destroyed the clipboard as it exited. If the application had put something more complicated on the clipboard, then our scratch program would have created a mishmash of old and new data.<\/p>\n
To protect against this race condition, make the following small change:<\/p>\n
void\r\nOnRenderAllFormats(HWND hwnd)\r\n{\r\n if (OpenClipboard(hwnd)) {\r\n  if (GetClipboardOwner() == hwnd) {<\/span>\r\n    OnRenderFormat(hwnd, CF_UNICODETEXT);\r\n  }                                 <\/span>\r\n  CloseClipboard();\r\n }\r\n}\r\n<\/pre>\n
After opening the clipboard, we check if we are still the window responsible for the clipboard contents. Only if so do we render our delay-rendered formats.<\/p>\n
Exercise<\/b>: Why is the Get\u00adClipboard\u00adOwner<\/code> test done after<\/i> the Open\u00adClipboard<\/code>? Wouldn’t it be better to bail out quickly if we are not the clipboard owner and avoid opening the clipboard in the first place?<\/p>\n
Answer to exercise<\/b>: Moving the Get\u00adClipboard\u00adOwner<\/code> test ahead of the Open\u00adClipboard<\/code> reintroduces the race condition we are trying to fix. The program might be the clipboard owner at the start of the function, but then it gets pre-empted after Get\u00adClipboard\u00adOwner<\/code> and before Open\u00adClipboard<\/code> and takes a long time to page in; say, because it’s running over the network or some other slow medium. During that time, the same scenario occurs that we are trying to defend against.<\/p>\n
But all is not lost. We can do a Get\u00adClipboard\u00adOwner<\/code> as an early-out, but do another one after the Open\u00adClipboard<\/code> just to be sure.<\/p>\n","protected":false},"excerpt":{"rendered":"
Contradictory documentation.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-5763","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Contradictory documentation.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/5763","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=5763"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/5763\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=5763"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=5763"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=5763"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
This program puts delay-rendered text on the clipboard  when it starts up<\/a>, When the request for text arrives, we just return the word hello<\/tt>. If we are asked to render all our formats, we render all our formats by calling our internal function once for each format we support. (All one of them.)<\/p>\n