Função NormalizeString (winnls.h)

Artigo
08/27/2023

Normaliza caracteres de uma cadeia de caracteres de texto de acordo com Unicode 4.0 TR#15. Para obter mais informações, consulte Usando a normalização Unicode para representar cadeias de caracteres.

Sintaxe

int NormalizeString(
  [in]            NORM_FORM NormForm,
  [in]            LPCWSTR   lpSrcString,
  [in]            int       cwSrcLength,
  [out, optional] LPWSTR    lpDstString,
  [in]            int       cwDstLength
);

Parâmetros

[in] NormForm

Formulário de normalização a ser usado. NORM_FORM especifica os formulários de normalização Unicode padrão.

[in] lpSrcString

Ponteiro para a cadeia de caracteres de origem não normalizada.

[in] cwSrcLength

Comprimento, em caracteres, do buffer que contém a cadeia de caracteres de origem. O aplicativo poderá definir esse parâmetro como -1 se a função deve assumir que a cadeia de caracteres seja terminada em nulo e calcular o comprimento automaticamente.

[out, optional] lpDstString

Ponteiro para um buffer no qual a função recupera a cadeia de caracteres de destino. Como alternativa, esse parâmetro conterá NULL se cwDstLength estiver definido como 0.

Nota A função não termina em nulo a cadeia de caracteres se o comprimento da cadeia de caracteres de entrada for especificado explicitamente sem um caractere nulo de terminação. Para encerrar nulo a cadeia de caracteres de saída, o aplicativo deve especificar -1 ou contar explicitamente o caractere nulo de terminação para a cadeia de caracteres de entrada.

[in] cwDstLength

Comprimento, em caracteres, do buffer que contém a cadeia de caracteres de destino. Como alternativa, o aplicativo pode definir esse parâmetro como 0 para solicitar que a função retorne o tamanho necessário para o buffer de destino.

Valor retornado

Retorna o comprimento da cadeia de caracteres normalizada no buffer de destino. Se cwDstLength for definido como 0, a função retornará o comprimento estimado do buffer necessário para fazer a conversão real.

Se a cadeia de caracteres no buffer de entrada for terminada em nulo ou se cwSrcLength for -1, a cadeia de caracteres gravada no buffer de destino será terminada em nulo e o comprimento da cadeia de caracteres retornado incluirá o caractere nulo de terminação.

A função retornará um valor menor ou igual a 0 se não for bem-sucedida. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar um dos seguintes códigos de erro:

ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou estava definido incorretamente como NULL.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.
ERROR_NO_UNICODE_TRANSLATION. Unicode inválido foi encontrado em uma cadeia de caracteres. O valor retornado é o negativo do índice do local do erro na cadeia de caracteres de entrada.
ERROR_SUCCESS. A ação foi concluída com êxito, mas não rendeu resultados.

Comentários

Alguns caracteres Unicode têm várias representações binárias equivalentes que consistem em conjuntos de combinação e/ou de caracteres Unicode compostos. O padrão Unicode define um processo chamado normalização que retorna uma representação binária quando recebe qualquer uma das representações binárias equivalentes de um caractere. A normalização pode ser executada com vários algoritmos, chamados formulários de normalização, que obedecem a regras diferentes, conforme descrito em Usando a normalização Unicode para representar cadeias de caracteres. O Win32 e o .NET Framework atualmente dão suporte aos formulários de normalização C, D, KC e KD, conforme definido no Anexo Padrão Unicode nº 15: Formulários de Normalização Unicode. Normalmente, as cadeias de caracteres normalizadas são avaliadas com uma comparação ordinal.

O código a seguir demonstra o uso da estimativa de comprimento do buffer:

const int maxIterations = 10;
LPWSTR strResult = NULL;
HANDLE hHeap = GetProcessHeap();

int iSizeEstimated = NormalizeString(form, strInput, -1, NULL, 0);
for (int i = 0; i < maxIterations; i++)
{
    if (strResult)
        HeapFree(hHeap, 0, strResult);
    strResult = (LPWSTR)HeapAlloc(hHeap, 0, iSizeEstimated * sizeof (WCHAR));
    iSizeEstimated = NormalizeString(form, strInput, -1, strResult, iSizeEstimated);
 
    if (iSizeEstimated > 0)
        break; // success 
 
    if (iSizeEstimated <= 0)
    {
        DWORD dwError = GetLastError();
        if (dwError != ERROR_INSUFFICIENT_BUFFER) break; // Real error, not buffer error 
 
        // New guess is negative of the return value. 
        iSizeEstimated = -iSizeEstimated;
    }
}

Windows XP, Windows Server 2003:

Não tem mais suporte.

O arquivo de cabeçalho e a DLL necessários fazem parte das APIs de Mitigação de IDN (Nome de Domínio Internacionalizado) da Microsoft, que não estão mais disponíveis para download.

Exemplos

Um exemplo mostrando o uso dessa função pode ser encontrado em NLS: Exemplo de normalização Unicode.

Requisitos


Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
DLL	Normaliz.dll
Redistribuível	APIs de mitigação de IDN (Nome de Domínio Internacionalizado) da Microsoft noWindows XP com SP2 e posterior ouWindows Server 2003 com SP1