Funzione NormalizeString (winnls.h)

Articolo
08/27/2023

Normalizza i caratteri di una stringa di testo in base a Unicode 4.0 TR#15. Per altre informazioni, vedere Uso della normalizzazione Unicode per rappresentare le stringhe.

Sintassi

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

Parametri

[in] NormForm

Modulo di normalizzazione da utilizzare. NORM_FORM specifica i moduli di normalizzazione Unicode standard.

[in] lpSrcString

Puntatore alla stringa di origine non normalizzata.

[in] cwSrcLength

Lunghezza, in caratteri, del buffer contenente la stringa di origine. L'applicazione può impostare questo parametro su -1 se la funzione deve presupporre che la stringa sia con terminazione Null e calcolare automaticamente la lunghezza.

[out, optional] lpDstString

Puntatore a un buffer in cui la funzione recupera la stringa di destinazione. In alternativa, questo parametro contiene NULL se cwDstLength è impostato su 0.

Nota La funzione non termina null-terminate la stringa se la lunghezza della stringa di input viene specificata in modo esplicito senza un carattere Null di terminazione. Per terminare null la stringa di output, l'applicazione deve specificare -1 o contare in modo esplicito il carattere Null di terminazione per la stringa di input.

[in] cwDstLength

Lunghezza, in caratteri, del buffer contenente la stringa di destinazione. In alternativa, l'applicazione può impostare questo parametro su 0 per richiedere alla funzione di restituire le dimensioni necessarie per il buffer di destinazione.

Valore restituito

Restituisce la lunghezza della stringa normalizzata nel buffer di destinazione. Se cwDstLength è impostato su 0, la funzione restituisce la lunghezza stimata del buffer necessaria per eseguire la conversione effettiva.

Se la stringa nel buffer di input è con terminazione Null o se cwSrcLength è -1, la stringa scritta nel buffer di destinazione è con terminazione Null e la lunghezza della stringa restituita include il carattere null di terminazione.

La funzione restituisce un valore minore o uguale a 0 se non riesce. Per ottenere informazioni estese sull'errore, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

ERROR_INSUFFICIENT_BUFFER. Le dimensioni del buffer fornite non sono sufficienti o non sono state impostate correttamente su NULL.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.
ERROR_NO_UNICODE_TRANSLATION. È stato trovato Unicode non valido in una stringa. Il valore restituito è il valore negativo dell'indice della posizione dell'errore nella stringa di input.
ERROR_SUCCESS. L'azione è stata completata correttamente, ma non ha restituito risultati.

Commenti

Alcuni caratteri Unicode hanno più rappresentazioni binarie equivalenti costituite da set di caratteri Unicode combinati e/o compositi. Lo standard Unicode definisce un processo denominato normalizzazione che restituisce una rappresentazione binaria quando viene specificata una delle rappresentazioni binarie equivalenti di un carattere. La normalizzazione può essere eseguita con diversi algoritmi, detti moduli di normalizzazione, che rispettano regole diverse, come descritto in Uso della normalizzazione Unicode per rappresentare le stringhe. Win32 e .NET Framework supportano attualmente i moduli di normalizzazione C, D, KC e KD, come definito nell'allegato standard Unicode #15: Moduli di normalizzazione Unicode. Le stringhe normalizzate vengono in genere valutate con un confronto ordinale.

Il codice seguente illustra l'uso della stima della lunghezza del 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:

Non più supportata.

Il file di intestazione e la DLL necessari fanno parte delle API di mitigazione IDN (Internationalized Domain Name) Microsoft, che non sono più disponibili per il download.

Esempio

Un esempio che mostra l'uso di questa funzione è disponibile in NLS: Unicode Normalization Sample.

Requisiti


Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winnls.h (include Windows.h)
DLL	Normaliz.dll
Componente ridistribuibile	API di mitigazione IDN (Internationalized Domain Name) Microsoft inWindows XP con SP2 e versioni successive oppureWindows Server 2003 con SP1