Função NormalizeString (winnls.h)

Normaliza caracteres de uma cadeia de caracteres de texto de acordo com o Unicode 4.0 TR#15. Para obter mais informações, consulte Como usar 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 pode definir esse parâmetro como -1 se a função deve assumir que a cadeia de caracteres será 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.

[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 de retorno

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 retorna um valor menor ou igual a 0 se não tiver êxito. 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 foi 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.

Observações

Alguns caracteres Unicode têm várias representações binárias equivalentes que consistem em conjuntos de caracteres Unicode combinados e/ou compostos. O padrão Unicode define um processo chamado normalização que retorna uma representação binária quando determinada 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 no uso da normalização Unicode para representar cadeias de caracteres. No momento, o Win32 e o .NET Framework 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, 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 há mais suporte.

O arquivo de cabeçalho necessário e a DLL fazem parte das APIs de Mitigação do 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 no NLS: Exemplo de Normalização Unicode.

Requirements

Consulte também

IsNormalizedString

NORM_FORM

de Suporte à Linguagem Nacional

funções de suporte à linguagem nacional

Usando a normalização unicode para representar cadeias de caracteres