Export (0) Print
Expand All

HSTRING

A handle to a Windows Runtime string.


typedef HSTRING__* HSTRING;

Remarks

Use HSTRING to represent immutable strings in the Windows Runtime.

JavaScript and other languages, such as C#, and Microsoft Visual Basic, can use strings that are represented by using HSTRING. The following table shows how an HSTRING is represented in other languages.

Programming LanguageString Representation
Visual C++ component extensions (C++/CX)Platform::String class
JavaScriptString object
.NET FrameworkSystem.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."

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Header

Hstring.h

See also

WindowsCreateString
WindowsDeleteString
WindowsDuplicateString
WindowsPreallocateStringBuffer

 

 

Community Additions

ADD
Show:
© 2014 Microsoft