Função SHAnsiToUnicode (shlwapi.h)

Artigo
03/02/2024

[Essa função está disponível por meio do Windows XP e do Windows Server 2003. Ele pode estar alterado ou indisponível nas versões subsequentes do Windows.]

Converte uma cadeia de caracteres da página de código ANSI para a página de código Unicode.

Sintaxe

int SHAnsiToUnicode(
  [in]  PCSTR pszSrc,
  [out] PWSTR pwszDst,
        int   cwchBuf
);

Parâmetros

[in] pszSrc

Tipo: PCSTR

Um ponteiro para uma cadeia de caracteres ANSI terminada em nulo a ser convertida em Unicode.

[out] pwszDst

Tipo: PWSTR

Um ponteiro para um buffer que, quando essa função retorna com êxito, recebe a cadeia de caracteres especificada por pszSrc, depois que os caracteres ANSI são convertidos em Unicode (WCHAR). O buffer deve ser grande o suficiente para conter o número de caracteres Unicode especificados pelo parâmetro cwchBuf , incluindo um caractere nulo de terminação.

cwchBuf

Tipo: int

O número de caracteres Unicode que podem ser contidos pelo buffer apontado por pwszDst. Esse parâmetro deve ser maior que zero.

Retornar valor

Tipo: int

Retorna o número de caracteres Unicode gravados em pwszDst, incluindo o caractere nulo de terminação. Retorna 0 se não tiver êxito.

Comentários

Aviso de segurança: Usar essa função incorretamente pode comprometer a segurança do aplicativo. Por exemplo, se o buffer pwszDst não for grande o suficiente para conter o número de caracteres especificado por cwchBuf, poderá ocorrer uma sobrecarga de buffer. Os estouros de buffer podem causar um ataque de negação de serviço contra um aplicativo se ocorrer uma violação de acesso. Na pior das hipóteses, uma sobrecarga de buffer pode permitir que um invasor injete código executável em seu processo, especialmente se pwszDst for um buffer baseado em pilha. Ao copiar uma cadeia de caracteres inteira, observe que sizeof retorna o número de bytes, que não é o valor correto a ser usado para o parâmetro cwchBuf . Em vez disso, use sizeof(pwszDst)/sizeof(WCHAR). Observe que essa técnica pressupõe que pwszDst é uma matriz, não um ponteiro.

Se o buffer pwszDst não for grande o suficiente para conter toda a cadeia de caracteres de saída convertida, a cadeia de caracteres será truncada para caber no buffer. Não há como detectar que a cadeia de caracteres de retorno foi truncada. A cadeia de caracteres é sempre terminada em nulo, mesmo que tenha sido truncada. Isso garante que não mais do que os caracteres cwchBuf sejam copiados para pwszDst. Nenhuma tentativa é feita para evitar truncar a cadeia de caracteres no meio de um par alternativo Unicode.

Se os buffers pszSrc e pwszDst se sobrepõem, o comportamento da função será indefinido.

Nota Não suponha que a função não tenha alterado nenhum dos caracteres no buffer de saída que seguem o caractere nulo de terminação da cadeia de caracteres. O conteúdo do buffer de saída após o caractere nulo de terminação da cadeia de caracteres é indefinido, até e incluindo o último caractere no buffer.

SHAnsiToTChar é definido como o mesmo que SHAnsiToUnicode.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server, Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shlwapi.h
DLL	Shlwapi.dll (versão 5.0 ou posterior)