Função FoldStringA (winnls.h)

Artigo
03/04/2024

Mapeia uma cadeia de caracteres Unicode para outra, executando a transformação especificada. Para obter uma visão geral do uso das funções de cadeia de caracteres, consulte Cadeias de caracteres.

Cuidado Usar FoldString incorretamente pode comprometer a segurança do aplicativo. Cadeias de caracteres que não são mapeadas corretamente podem produzir entrada inválida. Testar cadeias de caracteres para garantir que elas sejam válidas antes de usá-las e fornecer manipuladores de erro. Para obter mais informações, consulte Considerações de segurança: recursos internacionais.

Sintaxe

int FoldStringA(
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  lpDestStr,
  [in]            int    cchDest
);

Parâmetros

[in] dwMapFlags

Sinalizadores que especificam o tipo de transformação a ser usado durante o mapeamento de cadeia de caracteres. Esse parâmetro pode ser uma combinação dos seguintes valores.

Sinalizador	Significado
MAP_COMPOSITE	Mapeie caracteres acentuados para caracteres decompostos, ou seja, caracteres em que um caractere base e um ou mais caracteres não espaçados têm valores distintos de ponto de código. Por exemplo, Ä é representado por A + ̈: LATIN CAPITAL LETTER A (U+0041) + COMBINING DIAERESIS (U+0308). Esse sinalizador é equivalente à forma de normalização D no Windows Vista. Observe que esse sinalizador não pode ser usado com MB_PRECOMPOSED.
MAP_EXPAND_LIGATURES	Expanda todos os caracteres de ligadura para que eles sejam representados por seu equivalente de dois caracteres. Por exemplo, a ligatura "æ" (U+00e6) se expande para os dois caracteres "a" (U+0061) + "e" (U+0065). Esse valor não pode ser combinado com MAP_PRECOMPOSED ou MAP_COMPOSITE.
MAP_FOLDCZONE	Dobre os caracteres da zona de compatibilidade em equivalentes Unicode padrão. Esse sinalizador será equivalente à KD do formulário de normalização no Windows Vista, se o sinalizador MAP_COMPOSITE também estiver definido. Se o sinalizador composto não estiver definido (padrão), esse sinalizador será equivalente ao formato de normalização KC no Windows Vista.
MAP_FOLDDIGITS	Mapeie todos os dígitos para caracteres Unicode de 0 a 9.
MAP_PRECOMPOSED	Mapeie caracteres acentuados para caracteres pré-representados, nos quais o acento e o caractere base são combinados em um único valor de caractere. Esse sinalizador é equivalente à forma de normalização C no Windows Vista. Esse valor não pode ser combinado com MAP_COMPOSITE.

[in] lpSrcStr

Ponteiro para uma cadeia de caracteres de origem que a função mapeia.

[in] cchSrc

Tamanho, em caracteres, da cadeia de caracteres de origem indicada por lpSrcStr, excluindo o caractere nulo de terminação. O aplicativo pode definir o parâmetro como qualquer valor negativo para especificar que a cadeia de caracteres de origem é terminada em nulo. Nesse caso, a função calcula o comprimento da cadeia de caracteres automaticamente e termina em nulo a cadeia de caracteres mapeada indicada por lpDestStr.

[out, optional] lpDestStr

Ponteiro para um buffer no qual essa função recupera a cadeia de caracteres mapeada.

[in] cchDest

Tamanho, em caracteres, da cadeia de caracteres de destino indicada por lpDestStr. Se o espaço para um caractere nulo de terminação estiver incluído em cchSrc, cchDest também deverá incluir espaço para um caractere nulo de terminação.

O aplicativo pode definir cchDest como 0. Nesse caso, a função não usa o parâmetro lpDestStr e retorna o tamanho do buffer necessário para a cadeia de caracteres mapeada. Se o sinalizador MAP_FOLDDIGITS for especificado, o valor retornado será o tamanho máximo necessário, mesmo que o número real de caracteres necessário seja menor que o tamanho máximo. Se o tamanho máximo não for passado, a função falhará com ERROR_INSUFFICIENT_BUFFER.

Retornar valor

Retorna o número de caracteres na cadeia de caracteres traduzida, incluindo um caractere nulo de terminação, se bem-sucedido. Se a função for bem-sucedida e o valor de cchDest for 0, o valor retornado será o tamanho do buffer necessário para manter a cadeia de caracteres traduzida, incluindo um caractere nulo de terminação.

Essa função retornará 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_DATA. Os dados eram inválidos.
ERROR_INVALID_FLAGS. Os valores fornecidos para sinalizadores não eram válidos.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.
ERROR_MOD_NOT_FOUND. O módulo não foi encontrado.
ERROR_OUTOFMEMORY. Não havia armazenamento suficiente disponível para concluir esta operação.
ERROR_PROC_NOT_FOUND. O procedimento necessário não foi encontrado.

Comentários

Os valores dos parâmetros lpSrcStr e lpDestStr não devem ser os mesmos. Se forem iguais, a função falhará com ERROR_INVALID_PARAMETER.

A zona de compatibilidade em Unicode consiste em caracteres no intervalo 0xF900 até 0xFFEF que são atribuídos a caracteres de outros padrões de codificação para caracteres, mas na verdade são variantes de caracteres que já estão em Unicode. A zona de compatibilidade é usada para dar suporte ao mapeamento de ida e volta para esses padrões. Os aplicativos podem usar o sinalizador MAP_FOLDCZONE para evitar dar suporte à duplicação de caracteres na zona de compatibilidade.

Começando com o Windows Vista: Essa função dá suporte à normalização Unicode. Todos os caracteres de compatibilidade Unicode são mapeados.

Começando com o Windows Vista: As transformações indicadas pelos sinalizadores MAP_FOLDCZONE, MAP_PRECOMPOSED e MAP_COMPOSITE usam as formas de normalização Unicode KC, C e D (por meio da função NormalizeString ) para fazer os mapeamentos.

Começando com Windows 8: a versão ANSI da função é declarada em Winnls.h e a versão Unicode é declarada em Stringapiset.h. Antes Windows 8, ambas as versões eram declaradas em Winnls.h.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll