A handle to a Windows Runtime string.
Use HSTRING to represent immutable strings in the Windows Runtime.
|Programming Language||String Representation|
|Visual C++ component extensions (C++/CX)||Platform::String class|
|.NET Framework||System.String class|
The HSTRING handle is a standard handle type. Semantically, a NULLHSTRING is the same as the empty string. Passing NULL as an HSTRING argument is the same as passing a string with no characters except the terminating NUL character.
Call the WindowsCreateString function to create a new HSTRING, and call the WindowsDeleteString function to release the reference to the backing string memory. Call the WindowsCreateStringReference function to create a string reference, which is also called a fast-pass string. Every call to WindowsCreateString and WindowsCreateStringReference must be matched with a corresponding call to WindowsDeleteString.
Copy an HSTRING by calling the WindowsDuplicateString function.
Concatenate two strings by calling the WindowsConcatString function.
Access the backing string memory by calling the WindowsGetStringRawBuffer function.
HSTRING can store and use embedded NUL characters. Use the WindowsStringHasEmbeddedNull function to check for embedded NUL characters before using any functions which may produce unexpected results. For example, most of the Windows functions use LPCWSTR as an input parameter, and they compute the length of the string only until the first NUL is encountered.
The backing string must remain immutable and null-terminated. When calling code creates a string reference by using the WindowsCreateStringReference function, the memory containing the backing string representation is owned by the caller. The Windows Runtime relies on the contents of the original string to remain unchanged. When passing a string reference into the Windows Runtime, it is the caller’s responsibility to ensure that the string’s contents are unchanging and NUL terminated for the duration of the call. The Windows Runtime releases all references to the string reference when the call returns.
When you receive an HSTRING as an out parameter, it is good practice to set the handle to NULL when you are finished with it.
Call the WindowsPreallocateStringBuffer function to allocate a mutable string buffer that you can use to create an immutable HSTRING. When you have finished populating the buffer, you call the WindowsPromoteStringBuffer function to create the HSTRING. This two-phase construction pattern enables functionality that is similar to a "string builder."
Minimum supported client
Minimum supported server
|Windows Server 2012|
Build date: 5/16/2013