Función FoldStringW (stringapiset.h)

Artículo
08/26/2023

Asigna una cadena Unicode a otra, realizando la transformación especificada. Para obtener información general sobre el uso de las funciones de cadena, consulte Cadenas.

Precaución El uso incorrecto de FoldString puede poner en peligro la seguridad de la aplicación. Las cadenas que no están asignadas correctamente pueden producir entradas no válidas. Pruebe las cadenas para asegurarse de que son válidas antes de usarlas y proporcionar controladores de errores. Para obtener más información, vea Consideraciones de seguridad: Características internacionales.

Sintaxis

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

Parámetros

[in] dwMapFlags

Marcas que especifican el tipo de transformación que se va a usar durante la asignación de cadenas. Este parámetro puede ser una combinación de los valores siguientes.

Marca	Significado
MAP_COMPOSITE	Asigne caracteres acentuados a caracteres descomponidos, es decir, caracteres en los que un carácter base y uno o más caracteres sin espaciar cada uno tienen valores de punto de código distintos. Por ejemplo, Ä se representa mediante A + ́: LETRA MAYÚSCULA LATINA A (U+0041) + COMBINACIÓN DE DIAERESIS (U+0308). Esta marca es equivalente a la normalización del formulario D en Windows Vista. Tenga en cuenta que esta marca no se puede usar con MB_PRECOMPOSED.
MAP_EXPAND_LIGATURES	Expanda todos los caracteres de ligadura para que se representen mediante su equivalente de dos caracteres. Por ejemplo, la ligadura "æ" (U+00e6) se expande a los dos caracteres "a" (U+0061) + "e" (U+0065). Este valor no se puede combinar con MAP_PRECOMPOSED o MAP_COMPOSITE.
MAP_FOLDCZONE	Dobla los caracteres de zona de compatibilidad en equivalentes Unicode estándar. Esta marca es equivalente a la normalización de KD en Windows Vista, si también se establece la marca MAP_COMPOSITE. Si la marca compuesta no está establecida (valor predeterminado), esta marca equivale a la forma de normalización KC en Windows Vista.
MAP_FOLDDIGITS	Asigne todos los dígitos a caracteres Unicode de 0 a 9.
MAP_PRECOMPOSED	Asignar caracteres acentuados a caracteres precomponidos, en los que el carácter de énfasis y base se combinan en un solo valor de carácter. Esta marca es equivalente a la normalización de C en Windows Vista. Este valor no se puede combinar con MAP_COMPOSITE.

[in] lpSrcStr

Puntero a una cadena de origen que asigna la función.

[in] cchSrc

Tamaño, en caracteres, de la cadena de origen indicada por lpSrcStr, excepto el carácter nulo de terminación. La aplicación puede establecer el parámetro en cualquier valor negativo para especificar que la cadena de origen termina en null. En este caso, la función calcula automáticamente la longitud de la cadena y finaliza la cadena asignada indicada por lpDestStr.

[out, optional] lpDestStr

Puntero a un búfer en el que esta función recupera la cadena asignada.

[in] cchDest

Tamaño, en caracteres, de la cadena de destino indicada por lpDestStr. Si se incluye espacio para un carácter nulo de terminación en cchSrc, cchDest también debe incluir espacio para un carácter nulo de terminación.

La aplicación puede establecer cchDest en 0. En este caso, la función no usa el parámetro lpDestStr y devuelve el tamaño de búfer necesario para la cadena asignada. Si se especifica la marca MAP_FOLDDIGITS, el valor devuelto es el tamaño máximo necesario, incluso si el número real de caracteres necesarios es menor que el tamaño máximo. Si no se pasa el tamaño máximo, se produce un error en la función con ERROR_INSUFFICIENT_BUFFER.

Valor devuelto

Devuelve el número de caracteres de la cadena traducida, incluido un carácter nulo de terminación, si se ejecuta correctamente. Si la función se ejecuta correctamente y el valor de cchDest es 0, el valor devuelto es el tamaño del búfer necesario para contener la cadena traducida, incluido un carácter nulo de terminación.

Esta función devuelve 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_DATA. Los datos no eran válidos.
ERROR_INVALID_FLAGS. Los valores proporcionados para las marcas no eran válidos.
ERROR_INVALID_PARAMETER. Cualquiera de los valores de parámetro no era válido.
ERROR_MOD_NOT_FOUND. No se encontró el módulo.
ERROR_OUTOFMEMORY. No había suficiente almacenamiento disponible para completar esta operación.
ERROR_PROC_NOT_FOUND. No se encontró el procedimiento necesario.

Comentarios

Los valores de los parámetros lpSrcStr y lpDestStr no deben ser los mismos. Si son iguales, se produce un error en la función con ERROR_INVALID_PARAMETER.

La zona de compatibilidad de Unicode consta de caracteres del intervalo 0xF900 a través de 0xFFEF que se asignan a caracteres de otros estándares de codificación para caracteres, pero son realmente variantes de caracteres ya en Unicode. La zona de compatibilidad se usa para admitir la asignación de ida y vuelta a estos estándares. Las aplicaciones pueden usar la marca MAP_FOLDCZONE para evitar la duplicación de caracteres en la zona de compatibilidad.

A partir de Windows Vista: Esta función admite la normalización Unicode. Se asignan todos los caracteres de compatibilidad Unicode.

A partir de Windows Vista: Las transformaciones indicadas por las marcas MAP_FOLDCZONE, MAP_PRECOMPOSED y MAP_COMPOSITE usan los formularios de normalización Unicode KC, C y D (a través de la función NormalizeString ) para realizar las asignaciones.

A partir de Windows 8: la versión ANSI de la función se declara en Winnls.h y la versión Unicode se declara en Stringapiset.h. Antes de Windows 8, ambas versiones se declararon en Winnls.h.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	stringapiset.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll