WindowsCreateStringReference function (winstring.h)

Creates a new string reference based on the specified string.


HRESULT WindowsCreateStringReference(
  PCWSTR         sourceString,
  UINT32         length,
  HSTRING_HEADER *hstringHeader,
  HSTRING        *string



Type: [in] PCWSTR

A null-terminated string to use as the source for the new HSTRING.

A value of NULL represents the empty string, if the value of length is 0. Should be allocated on the stack frame.


Type: [in] UINT32

The length of sourceString, in Unicode characters. Must be 0 if sourceString is NULL. If greater than 0, sourceString must have a terminating null character.



A pointer to a structure that the Windows Runtime uses to identify string as a string reference, or fast-pass string.


Type: [out] HSTRING*

A pointer to the newly created string, or NULL if an error occurs. Any existing content in string is overwritten. The HSTRING is a standard handle type.

Return value


This function can return one of these values.

Return code Description
The [**HSTRING**](/windows/win32/winrt/hstring) was created successfully.
Either string or hstringHeader is NULL, or string is not null-terminated.
Failed to allocate the new [**HSTRING**](/windows/win32/winrt/hstring).
sourceString is NULL and length is non-zero.


Use the WindowsCreateStringReference function to create an HSTRING from an existing string. This kind of HSTRING is named a fast-pass string. Unlike an HSTRING created by the WindowsCreateString function, the lifetime of the backing buffer in the new HSTRING is not managed by the Windows Runtime. The caller allocates sourceString on the stack frame, together with an uninitialized HSTRING_HEADER, to avoid a heap allocation and eliminate the risk of a memory leak. The caller must ensure that sourceString and the contents of hstringHeader remain unchanged during the lifetime of the attached HSTRING.

You don't need to call the WindowsDeleteString function to de-allocate a fast-pass HSTRING created by the WindowsCreateStringReference function.

To create an empty HSTRING, pass NULL for sourceString and 0 for length.

The Windows Runtime tracks a fast-pass string by using an HSTRING_HEADER structure, which is returned in the hstringHeader out parameter. Do not change the contents of the HSTRING_HEADER.


Minimum supported client Windows 8 [desktop apps | UWP apps]
Minimum supported server Windows Server 2012 [desktop apps | UWP apps]
Target Platform Windows
Header winstring.h

See also