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 de length 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.
Retornar valor
Tipo: HRESULT
Essa função pode retornar um desses valores.
| Código de retorno | Descrição |
|---|---|
|
O HSTRING foi criado com êxito. |
|
A cadeia de caracteres ou hstringHeader é NULL ou a cadeia de caracteres não é terminada em nulo. |
|
Falha ao alocar o novo HSTRING. |
|
sourceString é NULL e o comprimento não é zero. |
Comentários
Use a função WindowsCreateStringReference para criar um HSTRING de uma cadeia de caracteres existente. Esse tipo de HSTRING é chamado de 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.
Requisitos
| Cliente mínimo com suporte | Windows 8 [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winstring.h |