Função WindowsCreateStringReference (winstring.h)

Cria uma nova referência de cadeia de caracteres com base na cadeia de caracteres especificada.

Sintaxe

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

Parâmetros

sourceString

Tipo: [in] PCWSTR

Uma cadeia de caracteres terminada em nulo a ser usada como a origem do novo HSTRING.

Um valor NULL representa a cadeia de caracteres vazia, se o valor do comprimento for 0. Deve ser alocado no quadro de pilha.

length

Tipo: [in] UINT32

O comprimento de sourceString, em caracteres Unicode. Deve ser 0 se sourceString for NULL. Se for maior que 0, sourceString deverá ter um caractere nulo de terminação.

hstringHeader

Tipo: [out] HSTRING_HEADER*

Um ponteiro para uma estrutura que o Windows Runtime usa para identificar a cadeia de caracteres como uma referência de cadeia de caracteres ou uma cadeia de caracteres de passagem rápida.

string

Tipo: [out] HSTRING*

Um ponteiro para a cadeia de caracteres recém-criada ou NULL se ocorrer um erro. Qualquer conteúdo existente na cadeia de caracteres é substituído. O HSTRING é um tipo de identificador padrão.

Valor de retorno

Tipo: HRESULT

Essa função pode retornar um desses valores.

Observações

Use a função WindowsCreateStringReference para criar um HSTRING de uma cadeia de caracteres existente. Esse tipo de HSTRING é denominado uma cadeia de caracteres de passagem rápida. Ao contrário de um HSTRING criado pela função WindowsCreateString , o tempo de vida do buffer de backup no novo HSTRING não é gerenciado pelo Windows Runtime. O chamador aloca sourceString no quadro de pilha, juntamente com um HSTRING_HEADER não inicializado, para evitar uma alocação de heap e eliminar o risco de um vazamento de memória. O chamador deve garantir que sourceString e o conteúdo de hstringHeader permaneçam inalterados durante o tempo de vida do HSTRING anexado.

Você não precisa chamar a função WindowsDeleteString para desalocar um HSTRING de passagem rápida criado pela função WindowsCreateStringReference .

Para criar um HSTRING vazio, passe NULL para sourceString e 0 para comprimento.

O Windows Runtime rastreia uma cadeia de caracteres de passagem rápida usando uma estrutura HSTRING_HEADER , que é retornada no parâmetro hstringHeader out. Não altere o conteúdo do HSTRING_HEADER.

Requirements

Consulte também

windowsCreateString

WindowsDeleteString