Skip to main content
WindowsCreateStringReference function

Creates a new string reference based on the specified string.

Syntax


HRESULT WINAPI WindowsCreateStringReference(
  _In_   PCWSTR sourceString,
  _In_   UINT32 length,
  _Out_  HSTRING_HEADER *hstringHeader,
  _Out_  HSTRING *string
);

Parameters

sourceString [in]

Type: 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.

length [in]

Type: 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.

hstringHeader [out]

Type: HSTRING_HEADER*

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

string [out]

Type: 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

Type: HRESULT

This function can return one of these values.

Return codeDescription
S_OK

The HSTRING was created successfully.

E_INVALIDARG

Either string or hstringHeader is NULL, or string is not null-terminated.

E_OUTOFMEMORY

Failed to allocate the new HSTRING.

E_POINTER

sourceString is NULL and length is non-zero.

 

Remarks

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 HSTRINGcreated 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.

Windows Phone 8: This API is supported.

Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows 8 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 [desktop apps | Windows Store apps]

Header

Winstring.h

See also

WindowsCreateString
WindowsDeleteString