HSTRING

Um identificador para uma cadeia de caracteres Windows Runtime.

typedef HSTRING__* HSTRING;

Comentários

Use HSTRING para representar cadeias de caracteres imutáveis no Windows Runtime.

O JavaScript e outras linguagens, como C#e Microsoft Visual Basic, podem usar cadeias de caracteres representadas usando HSTRING. A tabela a seguir mostra como um HSTRING é representado em outras linguagens.

Linguagem de programação	Representação de cadeia de caracteres
C++/WinRT	Classe winrt::hstring
Extensões de componente do Visual C++ (C++/CX)	Classe Platform::String
JavaScript	Objeto String
.NET Framework	Classe System.String

 

O identificador HSTRING é um tipo de identificador padrão. Semanticamente, um HSTRING que contém o valor NULL representa a cadeia de caracteres vazia, que consiste em zero caracteres de conteúdo e um caractere NULL de terminação. Criar uma cadeia de caracteres por meio de WindowsCreateString com zero caracteres produzirá o valor de identificador NULL. Ao chamar WindowsGetStringRawBuffer com o valor NULL, um ponteiro para uma cadeia de caracteres vazia seguida apenas pelo caractere de terminação NUL será retornado. Não existe nenhum valor distinto para representar um HSTRING que não seja inicializado.

Chame a função WindowsCreateString para criar um HSTRING e chame a função WindowsDeleteString para liberar a referência à memória da cadeia de caracteres de suporte. Chame a função WindowsCreateStringReference para criar uma referência de cadeia de caracteres, que também é chamada de cadeia de caracteres de passagem rápida.

Copie um HSTRING chamando a função WindowsDuplicateString .

Concatene duas cadeias de caracteres chamando a função WindowsConcatString .

Acesse a memória da cadeia de caracteres de suporte chamando a função WindowsGetStringRawBuffer .

O HSTRING pode armazenar e usar caracteres NUL inseridos. Use a função WindowsStringHasEmbeddedNull para marcar para caracteres NUL inseridos antes de usar quaisquer funções que possam produzir resultados inesperados. Por exemplo, a maioria das funções do Windows usa LPCWSTR como um parâmetro de entrada e calculam o comprimento da cadeia de caracteres somente até que o primeiro NUL seja encontrado.

A cadeia de caracteres de suporte deve permanecer imutável e terminada em nulo. Ao chamar código cria uma referência de cadeia de caracteres usando a função WindowsCreateStringReference , a memória que contém a representação de cadeia de caracteres de suporte pertence ao chamador. O Windows Runtime depende do conteúdo da cadeia de caracteres original para permanecer inalterado. Ao passar uma referência de cadeia de caracteres para o Windows Runtime, é responsabilidade do chamador garantir que o conteúdo da cadeia de caracteres esteja inalterado e o NUL seja encerrado durante a chamada. O Windows Runtime libera todas as referências à referência de cadeia de caracteres quando a chamada retorna.

Quando você recebe um HSTRING como um parâmetro out, é uma boa prática definir o identificador como NULL quando você terminar de fazer isso.

Chame a função WindowsPreallocateStringBuffer para alocar um buffer de cadeia de caracteres mutável que você pode usar para criar um HSTRING imutável. Quando terminar de preencher o buffer, você chamará a função WindowsPromoteStringBuffer para criar o HSTRING. Esse padrão de construção em duas fases permite uma funcionalidade semelhante a um "construtor de cadeias de caracteres".

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8
Servidor mínimo com suporte	Windows Server 2012
Cabeçalho	Hstring.h

Confira também

WindowsCreateString

WindowsDeleteString

WindowsDuplicateString

WindowsPreallocateStringBuffer