HSTRING

Дескриптор строки среда выполнения Windows.

typedef HSTRING__* HSTRING;

Комментарии

Используйте HSTRING для представления неизменяемых строк в среда выполнения Windows.

JavaScript и другие языки, такие как C# и Microsoft Visual Basic, могут использовать строки, представленные с помощью HSTRING. В следующей таблице показано, как HSTRING представлен на других языках.

Язык программирования	Строковое представление
C++/WinRT	Класс winrt::hstring
Расширения компонентов Visual C++ (C++/CX)	Класс Platform::String
JavaScript	String - объект
.NET Framework	Класс System.String

 

Дескриптор HSTRING является стандартным типом дескрипторов. Семантически HSTRING , содержащий значение NULL , представляет пустую строку, состоящую из нулевых символов содержимого и завершающего символа NULL . Создание строки с помощью WindowsCreateString с нулевыми символами приведет к получению значения дескриптора NULL. При вызове WindowsGetStringRawBuffer со значением NULL возвращается указатель на пустую строку, за которой следует только символ конца NUL . Не существует отдельного значения для представления неинициализированного HSTRING .

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

Скопируйте HSTRING, вызвав функцию WindowsDuplicateString .

Сцепление двух строк путем вызова функции WindowsConcatString .

Получите доступ к памяти резервной строки, вызвав функцию WindowsGetStringRawBuffer .

HSTRING может хранить и использовать внедренные символы NUL . Используйте функцию WindowsStringHasEmbeddedNull, чтобы проверка внедренных символов NUL перед использованием функций, которые могут привести к непредвиденным результатам. Например, большинство функций Windows используют LPCWSTR в качестве входного параметра и вычисляют длину строки только до тех пор, пока не будет обнаружен первый NUL .

Резервная строка должна оставаться неизменяемой и завершаться null. При вызове кода создается ссылка на строку с помощью функции WindowsCreateStringReference , память, содержащая представление резервной строки, принадлежит вызывающей стороне. В среда выполнения Windows содержимое исходной строки остается неизменным. При передаче ссылки на строку в среда выполнения Windows вызывающий объект несет ответственность за то, чтобы содержимое строки не изменялось и значение NUL было завершено на протяжении всего вызова. При возврате вызова среда выполнения Windows освобождает все ссылки на строку.

При получении HSTRING в качестве параметра out рекомендуется задать для дескриптора значение NULL по завершении работы с ним.

Вызовите функцию WindowsPreallocateStringBuffer , чтобы выделить изменяемый буфер строк, который можно использовать для создания неизменяемого HSTRING. Завершив заполнение буфера, вызывается функция WindowsPromoteStringBuffer для создания HSTRING. Этот двухэтапный шаблон построения включает функции, аналогичные "строкового построителя".

Требования

Требование	Значение
Минимальная версия клиента	Windows 8
Минимальная версия сервера	Windows Server 2012
Заголовок	Hstring.h

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

WindowsCreateString

WindowsDeleteString

WindowsDuplicateString

WindowsPreallocateStringBuffer