{"id":97015,"date":"2017-09-13T07:00:00","date_gmt":"2017-09-13T21:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/?p=97015"},"modified":"2019-03-13T01:16:46","modified_gmt":"2019-03-13T08:16:46","slug":"20170913-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20170913-00\/?p=97015","title":{"rendered":"What is the correct way of using the string buffer returned by the WindowsPreallocateStringBuffer function?"},"content":{"rendered":"

The most common way of creating an HSTRING<\/code> is to call Windows­Create­String<\/code><\/a>, but there is also a two-phase creation pattern: First you call Windows­Preallocate­String­Buffer<\/code> to create a buffer for a future string. You then fill the buffer with stringy goodness and then call Windows­Promote­String­Buffer<\/code> to convert it to a real HSTRING<\/code>. (Or you can call Windows­Delete­String­Buffer<\/code> to change your mind and pretend it never happened.) <\/p>\n

The rule for managing the buffer returned by Windows­Preallocate­String­Buffer<\/code> is that you are expected to write exactly<\/i> length<\/code> code units into the buffer. No more. No less. The system already put a terminating null after the end of the buffer; your job is to fill the buffer with the string contents. <\/p>\n

For example, if you want to use two-phase creation to create the string hello<\/code>, you would call Windows­Preallocate­String­Buffer<\/code> and pass length = 5<\/code>. Into the resulting buffer, you write the characters h<\/code>, e<\/code>, l<\/code>, l<\/code>, and o<\/code>, and that’s all. The system already stored the terminating null. <\/p>\n

This particular formulation of the rules is important in the case that length = 0<\/code>.¹ Since the representation of an HSTRING<\/code> of length zero is the null pointer, there is no actual buffer. What happens is that the system uses a single preallocated buffer (consisting of just a null terminator) to represent the buffer for all zero-length strings. If you call Windows­Preallocate­String­Buffer<\/code>, you get a pointer to that preallocated buffer.² Since you passed a length of zero, you are expected to write zero characters to the buffer; in other words, you are expected to do nothing at all with the buffer. <\/p>\n

And of course since HSTRING<\/code>s are immutable, your permission to modify the buffer ends once you promote the buffer to a string. Once it’s been promoted to a string, the entire buffer becomes read-only. <\/p>\n

¹ Another way of interpreting this corner case is to say “Don’t bother calling Windows­Preallocate­String­Buffer<\/code> with a string of length zero. Otherwise, go ahead and call it, and you can write that null terminator if you like.” <\/p>\n

² Arguably, to accommodate the possibiltiy of somebody writing that null terminator, it should return a preallocated writable<\/i> buffer just large enough to hold that null terminator. It could be the high 16 bits of the length<\/code> field itself! <\/p>\n","protected":false},"excerpt":{"rendered":"

Write the characters you allocated, but only those characters.<\/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-97015","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"

Write the characters you allocated, but only those characters.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/97015","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=97015"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/97015\/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=97015"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=97015"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=97015"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}