WindowsCreateString function (winstring.h)

Creates a new HSTRING based on the specified source string.

Syntax

HRESULT WindowsCreateString(
  PCNZWCH sourceString,
  UINT32  length,
  HSTRING *string
);

Parameters

sourceString

Type: [in, optional] LPCWSTR

The UTF-16LE-encoded text buffer to use as the source for the new HSTRING. To create a new, empty, or NULL string, pass NULL for sourceString and 0 for length.

This buffer is not required to be null-terminated. WindowsCreateString will copy its contents and add a null-terminator in the new buffer backing the returned HSTRING.

length

Type: [in] UINT32

The length of sourceString, in Unicode characters. Must be 0 if sourceString is NULL.

string

Type: [out] HSTRING*

A pointer to the newly created HSTRING, 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.

Remarks

Use the WindowsCreateString function to allocate a new HSTRING. The Windows Runtime copies string to the backing buffer of the new HSTRING and manages the buffer lifetime by using a reference count. Call the WindowsCreateStringReference function to create a fast-pass string, which uses an existing string without copying it.

Call the WindowsDeleteString function to de-allocate the HSTRING. Each call to the WindowsCreateString function must be matched by a call to WindowsDeleteString.

To create a new, empty, or NULL string, pass NULL for sourceString and 0 for length.

If sourceString has embedded null characters, the WindowsCreateString function copies all characters to the terminating null character.

Requirements

See also

WindowsCreateStringReference

WindowsDeleteString