Поделиться через

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

  • Статья

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

Синтаксис

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

Параметры

sourceString

Тип: [in] PCWSTR

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

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

length

Тип: [in] UINT32

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

hstringHeader

Тип: [out] HSTRING_HEADER*

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

string

Тип: [out] HSTRING*

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

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

Тип: HRESULT

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

Код возврата Описание
S_OK
 HSTRING успешно создан.
E_INVALIDARG
 Либо строка , либо hstringHeader имеет значение NULL, либо строка не завершается null.
E_OUTOFMEMORY
 Не удалось выделить новый HSTRING.
E_POINTER
 sourceString имеет значение NULL , а длина не равна нулю.

Комментарии

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

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

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

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

Требования

   
Минимальная версия клиента Windows 8 [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2012 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header winstring.h

См. также раздел

WindowsCreateString

WindowsDeleteString