{"id":105967,"date":"2021-11-25T07:00:00","date_gmt":"2021-11-25T15:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=105967"},"modified":"2021-11-25T06:16:48","modified_gmt":"2021-11-25T14:16:48","slug":"20211125-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20211125-00\/?p=105967","title":{"rendered":"How do I pass an array of variable-sized PROPSHEETPAGE<\/CODE> structures to PropertySheet<\/CODE>?"},"content":{"rendered":"

Last time, we noted that you can add your own custom data to the end of the PROPSHEETPAGE<\/code><\/a>, and if you set the dwSize<\/code> to include the custom data, then the system will copy that custom data into the HPROPSHEETPAGE<\/code>.<\/p>\n

This technique comes in handy if you need to create a property sheet page with Create\u00adProp\u00adSheet\u00adPage<\/code>, since it gives you a way to store more data than just the single lParam<\/code> that comes with the PROPSHEETPAGE<\/code> structure.<\/p>\n

When you fill out a PROPSHEETHEADER<\/code> structure, you can choose whether you’re passing an array of HPROPSHEETPAGE<\/code> handles (created by Create\u00adProp\u00adSheet\u00adPage<\/code>) or an array of PROPSHEETPAGE<\/code> structures. Passing an array of HPROPSHEETPAGE<\/code> handles isn’t a problem, since all HPROPSHEETPAGE<\/code> handles are the same size, regardless of the size of the PROPSHEETPAGE<\/code> lurking inside them. But passing an array of variable-sized PROPSHEETPAGE<\/code> structures is a trickier business.<\/p>\n

What we want to do is lay out the memory like this:<\/p>\n

<\/p>\n\n\n\n\n\n\n\n\n
page1.dwSize<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage1
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n
page2.dwSize<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage2
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n
page3.dwSize<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage3
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

We can do this by manufacturing a structure to hold the three extended PROPSHEETPAGE<\/code> structures.<\/p>\n

struct ThreePages\r\n{\r\n    Page1Data page1;\r\n    Page2Data page2;\r\n    Page3Data page3;\r\n};\r\n\r\nThreePages pages;\r\n<\/pre>\n
The na\u00efve say of setting the dwSize<\/code> members is to set each one to the size of the corresponding structure.<\/p>\n
pages.page1.dwSize = sizeof(pages.page1);\r\npages.page2.dwSize = sizeof(pages.page2);\r\npages.page3.dwSize = sizeof(pages.page3);\r\n<\/pre>\n
This assumes that the three structures can be laid out next to each other without any inter-member padding. But that may not be true if the structures have different alignment requirements, say, if one of them contains a __mi128<\/code>.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n
sizeof(page1)<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage1
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n
oops<\/td>\n <\/td>\n(padding?)<\/td>\n<\/tr>\n
sizeof(page2)<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage2
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n
oops<\/td>\n <\/td>\n(padding?)<\/td>\n<\/tr>\n
sizeof(page3)<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage3
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\n <\/td>\n(padding?)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
In the presence of padding, we have a shortfall between the size of each page and the start of the next page, resulting in an “oops” gap highlighted above.<\/p>\n
In order to accommodate varying alignment requirements, the dwSize<\/code> must include the padding so that the property sheet manager can find the next structure.\u00b9 I’ve marked some key addresses in the diagram below:<\/p>\n\n\n\n\n\n\n\n\n\n\n
page1.dwSize<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n		\u2190 &page1<\/code><\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage1
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\n(padding?)<\/td>\n<\/tr>\n
page2.dwSize<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n		\u2190 &page2<\/code><\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage2
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n
page3.dwSize<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n		\u2190 &page3<\/code><\/td>\n<\/tr>\n
 <\/td>\n <\/td>\npage3
\n\u00a0extra
\n\u00a0\u00a0data<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\n <\/td>\n <\/td>\n\u2190 &pages + 1<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
pages.page1.dwSize = static_cast<DWORD>(\r\n    reinterpret_cast<DWORD_PTR>(std::addressof(pages.page2)) -\r\n    reinterpret_cast<DWORD_PTR>(std::addressof(pages.page1)));\r\npages.page2.dwSize = static_cast<DWORD>(\r\n    reinterpret_cast<DWORD_PTR>(std::addressof(pages.page3)) -\r\n    reinterpret_cast<DWORD_PTR>(std::addressof(pages.page2)));\r\npages.page3.dwSize = static_cast<DWORD>(\r\n    reinterpret_cast<DWORD_PTR>(std::addressof(pages + 1)) -\r\n    reinterpret_cast<DWORD_PTR>(std::addressof(pages.page3)));\r\n<\/pre>\n
This is quite a mouthful, but the idea is that we want to measure the distance to the next thing. We use std::addressof<\/code> instead of the traditional &<\/code> operator to protect against the possibility that the &<\/code> operator has been overloaded.\u00b2<\/p>\n
Yes, this is quite annoying, but it’s also probably not something you’re likely to be doing, because you could just use a pointer to a stack-allocated object which will remain valid until Property\u00adSheet<\/code> returns. The main value of the PROPSHEETPAGE<\/code> payload is in the case where you need to produce an HPROPSHEETPAGE<\/code>, since the HPROPSHEETPAGE<\/code> is probably going to outlive any stack variables.<\/p>\n
But it’s there if you need it.<\/p>\n
\u00b9 Don’t even think of using #pragma pack(1)<\/code> to remove the padding. This will misalign the next structure and result in crashes on alignment-sensitive platforms.<\/p>\n
\u00b2 Overloading the &<\/code> operator is something that annoys C++ library authors, although it’s still nowhere as annoying as  overloading the comma operator<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
It’s “just” an array of variable-sized structures.<\/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-105967","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
It’s “just” an array of variable-sized structures.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105967","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=105967"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105967\/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=105967"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=105967"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=105967"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}