Função SHUnicodeToAnsi (shlwapi.h)

Artigo
03/05/2024

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

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

Sintaxe

int SHUnicodeToAnsi(
  [in]  PCWSTR pwszSrc,
  [out] PSTR   pszDst,
        int    cchBuf
);

Parâmetros

[in] pwszSrc

Tipo: PCWSTR

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

[out] pszDst

Tipo: PSTR

Um ponteiro para um buffer que, quando essa função retorna com êxito, recebe os caracteres convertidos. O buffer deve ser grande o suficiente para conter o número de caracteres CHAR especificado pelo parâmetro cchBuf , incluindo espaço para um caractere nulo de terminação.

cchBuf

Tipo: int

O número de valores CHAR que podem ser contidos pelo buffer apontado por pszDst. O valor atribuído ao parâmetro deve ser maior que zero.

Retornar valor

Tipo: int

Retorna o número de valores CHAR gravados no buffer de saída, 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 pszDst não for grande o suficiente para conter o número de caracteres especificado por cchBuf, poderá ocorrer um estouro 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, um estouro de buffer pode permitir que um invasor injete código executável em seu processo, especialmente se pszDst for um buffer baseado em pilha. Além disso, a cadeia de caracteres de saída será truncada silenciosamente se for muito grande para o buffer. Isso pode causar canonicalização ou outras vulnerabilidades de segurança.

Se o buffer pszDst 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 será terminada em nulo, mesmo que tenha sido truncada. Essa função tem o cuidado de não truncar entre os bytes de lead e trail de um par de caracteres DBCS. Nesse caso, somente os caracteres cchBuf-1 são retornados.

Se os buffers pwszSrc e pszDst 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.

SHTCharToAnsi é definido como sendo o mesmo que SHUnicodeToAnsi.

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)