Функция WindowsCreateStringReference (winstring.h)

Создает новую ссылку на строку на основе указанной строки.

Синтаксис

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

Параметры

sourceString

Тип: [in] PCWSTR

Строка, завершающаяся значением NULL, используемая в качестве источника для нового HSTRING.

Значение NULL представляет пустую строку, если значение длины равно 0. Следует выделить на кадре стека.

length

Тип: [in] UINT32

Длина sourceString в символах Юникода. Должно быть равно 0, если sourceString имеет значение NULL. Если больше 0, sourceString должен иметь конечный символ NULL.

hstringHeader

Тип: [out] HSTRING_HEADER*

Указатель на структуру, которую среда выполнения Windows использует для идентификации строки в виде строки ссылки или строки быстрого передачи.

string

Тип: [out] HSTRING*

Указатель на только что созданную строку или NULL , если возникает ошибка. Любое существующее содержимое строки перезаписывается. HSTRING — это стандартный тип дескриптора.

Возвращаемое значение

Тип: HRESULT

Эта функция может возвращать одно из этих значений.

Замечания

Используйте функцию WindowsCreateStringReference для создания HSTRING из существующей строки. Этот вид HSTRING называется строкой быстрого передачи. В отличие от HSTRING , созданного функцией WindowsCreateString , время существования резервного буфера в новом HSTRING не управляется средой выполнения Windows. Вызывающий объект выделяет sourceString на кадре стека вместе с неинициализированным HSTRING_HEADER, чтобы избежать выделения кучи и исключить риск утечки памяти. Вызывающий объект должен убедиться, что sourceString и содержимое hstringHeader остаются неизменными в течение времени существования присоединенного HSTRING.

Вам не нужно вызывать функцию WindowsDeleteString для отмены выделения быстрой передачи HSTRING , созданной функцией WindowsCreateStringReference .

Чтобы создать пустой HSTRING, передайте значение NULL для sourceString и 0 для длины.

Среда выполнения Windows отслеживает строку быстрого передачи с помощью HSTRING_HEADER структуры , которая возвращается в параметре hstringHeader out. Не изменяйте содержимое HSTRING_HEADER.

Требования

См. также

WindowsCreateString

WindowsDeleteString