{"id":105737,"date":"2021-09-28T07:00:00","date_gmt":"2021-09-28T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=105737"},"modified":"2021-09-28T06:35:04","modified_gmt":"2021-09-28T13:35:04","slug":"20210928-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20210928-00\/?p=105737","title":{"rendered":"The subtleties of Create­Stream­On­HGlobal<\/CODE>, part 1: Introduction and basic usage"},"content":{"rendered":"

The Create\u00adStream\u00adOn\u00adHGlobal<\/code> function lets you create a COM IStream<\/code> that uses an HGLOBAL<\/code> memory block as its backing store. It takes two input parameters: an optional HGLOBAL<\/code> that represents the memory block to use, and a flag called fDelete\u00adOn\u00adRelease = FALSE<\/code> that controls whether the stream object frees the HGLOBAL<\/code> when it is destroyed. The initial contents and size of the stream correspond to the initial contents and size of the HGLOBAL<\/code>; if you don’t pass one, then then the function will create its own from scratch and start with an empty stream.<\/p>\n

Sounds simple, right?<\/p>\n

It stops being simple when you start exploring the dark corners.<\/p>\n

But let’s start in the brightly-lit area: The normal case where you pass fDelete\u00adOn\u00adRelease = TRUE<\/code>.<\/p>\n

Passing fDelete\u00adOn\u00adRelease = TRUE<\/code> represents an ownership transfer. The stream assumes ownership of the HGLOBAL<\/code> you pass in (assuming you passed one at all), and it is free to do with it whatever it likes. When the stream is destroyed, it frees the HGLOBAL<\/code>, too.<\/p>\n

The rule in this case is simple: Once you give an HGLOBAL<\/code> to the Create\u00adStream\u00adOn\u00adHGlobal<\/code> function, it’s not yours any more. Correct usage would be something like this:<\/p>\n

HGLOBAL hglobal = CreateInitialContents();\r\n\r\nIStream* stream = NULL;\r\nif (SUCCEEDED(CreateStreamOnHGlobal(\r\n        hglobal, TRUE, &stream))) {\r\n    hglobal = NULL;     \/\/ Not our HGLOBAL any more\r\n}\r\n<\/pre>\n
If you’re using a smart pointer library, you would perform what is commonly known in Windows as a Detach<\/code> operation, but which the C++ standard library calls release<\/code>, which is not the same as a COM Release, so don’t get confused.<\/p>\n
wil::unique_hglobal hglobal = CreateInitialContents();\r\n\r\nwil::com_ptr<IStream> stream;\r\nif (SUCCEEDED(CreateStreamOnHGlobal(\r\n        hglobal.get(), TRUE, &stream))) {\r\n    hglobal.release();     \/\/ Not our HGLOBAL any more\r\n}\r\n<\/pre>\n
The stream object assumes ownership of the HGLOBAL<\/code> and will treat it as its own personal property. If somebody writes to the stream, it will write to the HGLOBAL<\/code>. If the write extends beyond the end of the HGLOBAL<\/code>, or if somebody calls IStream::SetSize<\/code> to change the size of the stream, then it will resize the HGLOBAL<\/code> correspondingly. But that’s okay, because you gave up that HGLOBAL<\/code> back when you created the stream. Whatever the stream does with the HGLOBAL<\/code> is no longer your business.<\/p>\n
That’s the easy case.<\/p>\n
Next time, we’ll start looking at the hard case where you pass fDelete\u00adOn\u00adRelease = FALSE<\/code>.<\/p>\n
Bonus chatter<\/b>: Why does the Create\u00adStream\u00adOn\u00adHGlobal<\/code> function have such dark and shady corners? This function dates back to Windows 3.1, back when a powerful computer had 4MB of memory, and your typical computer had much less. Software development kits cost thousands of dollars, and the expectation was that if you bought one, it was because you were a professional developer who understood how the system worked down to a very low level. Programming was hard because nobody expected it to be easy.<\/p>\n","protected":false},"excerpt":{"rendered":"
Developing the mental model.<\/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-105737","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Developing the mental model.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105737","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=105737"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105737\/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=105737"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=105737"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=105737"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}