{"id":93675,"date":"2016-06-15T07:00:00","date_gmt":"2016-06-15T21:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/?p=93675"},"modified":"2019-03-13T11:51:02","modified_gmt":"2019-03-13T18:51:02","slug":"20160615-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20160615-00\/?p=93675","title":{"rendered":"Raymond’s complete guide to HSTRING semantics"},"content":{"rendered":"

The title of today’s article is a blatant ripoff of Eric Lippert’s complete guide to BSTR semantics<\/a>. <\/p>\n

I’m going to start with a lie: An HSTRING<\/code> is a reference-counted Unicode string. <\/p>\n

Work with me here. <\/p>\n

The string is immutable, and it uses the UTF-16LE encoding, as is traditional in Windows. <\/p>\n

Here are the basic operations on HSTRING<\/code>s: <\/p>\n

WindowsCreateString<\/b> creates an HSTRING<\/code> from a UTF-16LE-encoded buffer and a specified length. The buffer does not require a terminating null. If the buffer contains embedded null characters, then the resulting HSTRING<\/code> will have embedded null characters. (In particular, if you pass a null-terminated string and you include the null terminator in the length, then the resulting string has an embedded null character. Note also that the length is in wchar_t<\/code> code units, not in bytes.) <\/p>\n

WindowsDuplicateString<\/b> increments the reference count on an HSTRING<\/code>, and returns a new HSTRING<\/code> which you should use to refer to the string. <\/p>\n

WindowsDeleteString<\/b> decrements the reference count on an HSTRING<\/code>. If the reference count drops to zero, then the string is destroyed. You shouldn’t use the HSTRING<\/code> after passing it to WindowsDeleteString<\/b>. <\/p>\n

There are a small number of string manipulation functions like WindowsSubstring<\/b> and WindowsConcatString<\/b> which create new strings from old strings. The set of operations is rather limited, however. If you want to perform fancy operations on HSTRING<\/code>s, you’ll probably need to do them yourself. (Of course, if you’re using a projected language, the HSTRING<\/code> will project as something closer to what your projected language operates on natively, at which point you will most likely have a rich collection of library functions available to do advanced manipulations.) <\/p>\n

To access the characters in the HSTRING<\/code>, use the WindowsGetStringRawBuffer<\/b> function, which gives you two things: The return value is a pointer to the first character in the HSTRING<\/code>, and the optional output parameter is the number of code units. The buffer should be treated as read-only because HSTRING<\/code>s are immutable. <\/p>\n

The string contents in the buffer are always followed by a null character (which doesn’t count toward the string length); as a result, you can treat the string buffer as if it were a null-terminated string and get away with it most of the time. <\/p>\n

The time you don’t get away with it is if the string contains embedded null characters. In that case, treating it as a null-terminated string will stop prematurely, mistaking the embedded null for the terminal null. You can use the WindowsStringHasEmbeddedNull<\/b> function to detect whether an HSTRING<\/code> contains an embedded null and reject the operation if you don’t support embedded nulls. <\/p>\n

One of the special rules for HSTRING<\/code> is similar to the corresponding rule for BSTR<\/code>, namely that a null pointer is equivalent to a zero-length string. But HSTRING<\/code> takes it further: Not only is a null pointer equivalent to a zero-length string, but in fact a null pointer is<\/i> the representation of a zero-length string. In other words, if you call WindowsCreateString<\/b> and specify that the string has length zero, then out will come a null pointer. It is legal to assume that a non-null HSTRING<\/code> represents a non-empty string. Conversely, it is legal to test an HSTRING<\/code> against a null pointer to see whether the string is empty. <\/p>\n

Okay, so now I cop to the lie: An HSTRING<\/code> is not always a reference-counted string. <\/p>\n

There are these things called fast-pass<\/a> strings. Fast-pass strings are HSTRING<\/code>s that involve no memory allocation. If you have a buffer that you want to turn into an HSTRING<\/code>, and you promise not to modify the buffer for the lifetime of your HSTRING<\/code>, then you can use the WindowsCreateStringReference<\/b> function to create an HSTRING<\/code> around<\/i> your buffer. The resulting HSTRING<\/code> is a legal HSTRING<\/code>, but instead of allocating memory on the heap for a reference-counted object, it uses the HSTRING_HEADER<\/code> structure which you passed to the WindowsCreateStringReference<\/b> function to store the metadata, and it uses the buffer you passed to the function to store the string contents. <\/p>\n

It’s called a fast-pass string because this special string doesn’t require any memory allocation, and no data copying occurs. <\/p>\n

When you are finished with a fast-pass string, you just abandon the HSTRING<\/code>. The underlying memory for the fast-pass string was provided by you, so you are still on the hook for freeing that memory as appropriate. <\/p>\n

The existence of fast-pass strings explains why the WindowsDuplicateString<\/b> function returns you another HSTRING<\/code>: If the original string is fast-pass, then the WindowsDuplicateString<\/b> function needs to convert it to a true reference-counted heap-allocated object, and then it returns an HSTRING<\/code> to that heap-allocated string. (On the other hand, if the HSTRING<\/code> is already a heap-allocated string with a reference count, then the WindowsDuplicateString<\/b> function merely increments the reference count and returns the same HSTRING<\/code> back.)¹ <\/p>\n

The rules for managing HSTRING<\/code>s therefore go like this: <\/p>\n