Función NormalizeString (winnls.h)

Artículo
08/27/2023

Normaliza los caracteres de una cadena de texto según Unicode 4.0 TR#15. Para obtener más información, vea Usar la normalización Unicode para representar cadenas.

Sintaxis

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

Parámetros

[in] NormForm

Formulario de normalización que se va a usar. NORM_FORM especifica los formularios de normalización Unicode estándar.

[in] lpSrcString

Puntero a la cadena de origen no normalizada.

[in] cwSrcLength

Longitud, en caracteres, del búfer que contiene la cadena de origen. La aplicación puede establecer este parámetro en -1 si la función debe asumir que la cadena está terminada en null y calcular la longitud automáticamente.

[out, optional] lpDstString

Puntero a un búfer en el que la función recupera la cadena de destino. Como alternativa, este parámetro contiene NULL si cwDstLength está establecido en 0.

Nota La función no termina en null la cadena si la longitud de la cadena de entrada se especifica explícitamente sin un carácter nulo de terminación. Para terminar en null la cadena de salida, la aplicación debe especificar -1 o contar explícitamente el carácter nulo de terminación para la cadena de entrada.

[in] cwDstLength

Longitud, en caracteres, del búfer que contiene la cadena de destino. Como alternativa, la aplicación puede establecer este parámetro en 0 para solicitar a la función que devuelva el tamaño necesario para el búfer de destino.

Valor devuelto

Devuelve la longitud de la cadena normalizada en el búfer de destino. Si cwDstLength se establece en 0, la función devuelve la longitud estimada del búfer necesaria para realizar la conversión real.

Si la cadena del búfer de entrada termina en null o si cwSrcLength es -1, la cadena escrita en el búfer de destino termina en null y la longitud de la cadena devuelta incluye el carácter nulo de terminación.

La función devuelve un valor menor o igual que 0 si no se realiza correctamente. Para obtener información de error extendida, la aplicación puede llamar a GetLastError, que puede devolver uno de los siguientes códigos de error:

ERROR_INSUFFICIENT_BUFFER. Un tamaño de búfer proporcionado no era lo suficientemente grande o se estableció incorrectamente en NULL.
ERROR_INVALID_PARAMETER. Cualquiera de los valores de parámetro no era válido.
ERROR_NO_UNICODE_TRANSLATION. Se encontró unicode no válido en una cadena. El valor devuelto es el negativo del índice de la ubicación del error en la cadena de entrada.
ERROR_SUCCESS. La acción se completó correctamente, pero no produjo ningún resultado.

Comentarios

Algunos caracteres Unicode tienen varias representaciones binarias equivalentes que constan de conjuntos de caracteres Unicode combinados o compuestos. El estándar Unicode define un proceso denominado normalización que devuelve una representación binaria cuando se da cualquiera de las representaciones binarias equivalentes de un carácter. La normalización se puede realizar con varios algoritmos, denominados formularios de normalización, que obedecen a reglas diferentes, como se describe en Uso de la normalización Unicode para representar cadenas. Win32 y .NET Framework admiten actualmente los formularios de normalización C, D, KC y KD, tal y como se define en el Anexo estándar de Unicode n.º 15: Formularios de normalización Unicode. Normalmente, las cadenas normalizadas se evalúan con una comparación ordinal.

En el código siguiente se muestra el uso de la estimación de longitud del búfer:

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:

Ya no se admite.

El archivo de encabezado y dll necesarios forman parte de las API de mitigación de nombres de dominio internacionalizados (IDN) de Microsoft, que ya no están disponibles para su descarga.

Ejemplos

Puede encontrar un ejemplo en el que se muestra el uso de esta función en NLS: Ejemplo de normalización Unicode.

Requisitos


Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winnls.h (incluye Windows.h)
Archivo DLL	Normaliz.dll
Redistribuible	API de mitigación de nombres de dominio internacionalizados (IDN) de Microsoft enWindows XP con SP2 y versiones posteriores, oWindows Server 2003 con SP1