Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WindowsCreateString function

Creates a new HSTRING based on the specified source string.

Syntax


HRESULT WINAPI WindowsCreateString(
  _In_opt_ LPCWSTR sourceString,
  _In_     UINT32  length,
  _Out_    HSTRING *string
);

Parameters

sourceString [in, optional]

Type: LPCWSTR

A null-terminated string 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.

length [in]

Type: UINT32

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

string [out]

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

Return codeDescription
S_OK

The HSTRING was created successfully.

E_INVALIDARG

string is NULL.

E_OUTOFMEMORY

Failed to allocate the new HSTRING.

E_POINTER

sourceString is NULL and length is non-zero.

 

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

Minimum supported client

Windows 8 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 [desktop apps | Windows Store apps]

Minimum supported phone

Windows Phone 8.1

Header

Winstring.h

See also

WindowsCreateStringReference
WindowsDeleteString

 

 

Show:
© 2017 Microsoft