Função LCMapStringEx (winnls.h)

Artigo
03/08/2023

Para uma localidade especificada por nome, mapeia uma cadeia de caracteres de entrada para outra usando uma transformação especificada ou gera uma chave de classificação para a cadeia de caracteres de entrada.

Nota O aplicativo deve chamar essa função em preferência para LCMapString se projetado para ser executado somente no Windows Vista e posterior.

Sintaxe

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Parâmetros

[in, optional] lpLocaleName

Ponteiro para um nome de localidade ou um dos valores predefinidos a seguir.

[in] dwMapFlags

Sinalizador especificando o tipo de transformação a ser usado durante o mapeamento de cadeia de caracteres ou o tipo de chave de classificação a ser gerada. Esse parâmetro pode ter os valores a seguir.

Sinalizador	Significado
LCMAP_BYTEREV	Use a reversão de bytes. Por exemplo, se o aplicativo passar 0x3450 0x4822, o resultado será 0x5034 0x2248.
LCMAP_FULLWIDTH	Use caracteres Unicode (largos) quando aplicável. Esse sinalizador e LCMAP_HALFWIDTH são mutuamente exclusivos. Com esse sinalizador, o mapeamento pode usar o Formulário de Normalização C mesmo se um caractere de entrada já tiver largura total. Por exemplo, a cadeia de caracteres "は゛" (que já é de largura inteira) é normalizada para "ば". Consulte Formato de normalização Unicode.
LCMAP_HALFWIDTH	Use caracteres estreitos quando aplicável. Esse sinalizador e LCMAP_FULLWIDTH são mutuamente exclusivos.
LCMAP_HIRAGANA	Mapeie todos os caracteres katakana para hiragana. Esse sinalizador e LCMAP_KATAKANA são mutuamente exclusivos.
LCMAP_KATAKANA	Mapeie todos os caracteres hiragana para katakana. Esse sinalizador e LCMAP_HIRAGANA são mutuamente exclusivos.
LCMAP_LINGUISTIC_CASING	Use regras linguísticas para uso de maiúsculas e minúsculas, em vez de regras do sistema de arquivos (padrão). Esse sinalizador é válido apenas com LCMAP_LOWERCASE ou LCMAP_UPPERCASE.
LCMAP_LOWERCASE	Para localidades e scripts capazes de lidar com maiúsculas e minúsculas, mapeie todos os caracteres para letras minúsculas.
LCMAP_HASH	Retornar um hash dos pesos brutos de classificação de uma cadeia de caracteres. As cadeias de caracteres que aparecem equivalentes normalmente retornam o mesmo hash (por exemplo, "hello" e "HELLO" com LCMAP_IGNORECASE). No entanto, alguns casos complexos, como idiomas do Leste Asiático, podem ter cadeias de caracteres semelhantes com pesos idênticos que se comparam como iguais, mas não retornam o mesmo hash. LCMAP_HASH requer que o buffer de saída seja de sizeof(int)
LCMAP_SIMPLIFIED_CHINESE	Mapeie caracteres tradicionais chineses para caracteres chineses simplificados. Esse sinalizador e LCMAP_TRADITIONAL_CHINESE são mutuamente exclusivos.
LCMAP_SORTHANDLE O uso de um identificador de classificação resulta em melhorias mínimas de desempenho e é desencorajado.	Retornar um token que representa os parâmetros de classificação resolvidos para a localidade (como o nome da localidade), para que chamadas futuras possam passar `NULL` para o nome de classificação e passar o identificador de classificação consultado anteriormente como o último parâmetro (sortHandle) em chamadas subsequentes para CompareStringEx ou LCMapStringEx. LCMAP_SORTHANDLE requer que o buffer de saída seja de sizeof(lparam)
LCMAP_SORTKEY	Produza uma chave de classificação normalizada. Se o sinalizador LCMAP_SORTKEY não for especificado, a função executará o mapeamento de cadeia de caracteres. Para obter detalhes de classificação de geração de chave e mapeamento de cadeia de caracteres, consulte a seção Comentários.
LCMAP_TITLECASE	Windows 7: mapeie todos os caracteres para a caixa de título, na qual a primeira letra de cada palavra principal é maiúscula.
LCMAP_TRADITIONAL_CHINESE	Mapeie caracteres chineses simplificados para caracteres tradicionais chineses. Esse sinalizador e LCMAP_SIMPLIFIED_CHINESE são mutuamente exclusivos.
LCMAP_UPPERCASE	Para localidades e scripts capazes de lidar com maiúsculas e minúsculas, mapeie todos os caracteres para maiúsculas.

Os sinalizadores a seguir podem ser usados sozinhos, uns com os outros ou com os sinalizadores de LCMAP_SORTKEY e/ou LCMAP_BYTEREV. No entanto, eles não podem ser combinados com os outros sinalizadores listados acima.

Sinalizador	Significado
NORM_IGNORENONSPACE	Ignorar caracteres sem espaçamento. Para muitos scripts (especialmente scripts latinos), NORM_IGNORENONSPACE coincide com LINGUISTIC_IGNOREDIACRITIC. Nota NORM_IGNORENONSPACE ignora qualquer distinção secundária, seja ela diacrítica ou não. Scripts para idiomas coreano, japonês, chinês e índice, entre outros, usam essa distinção para fins diferentes de diacríticos. LINGUISTIC_IGNOREDIACRITIC faz com que a função ignore apenas os diacríticos reais, em vez de ignorar o segundo peso de classificação.
NORM_IGNORESYMBOLS	Ignorar símbolos e pontuação.

Sinalizador

Significado

NORM_IGNORENONSPACE

Ignorar caracteres sem espaçamento. Para muitos scripts (especialmente scripts latinos), NORM_IGNORENONSPACE coincide com LINGUISTIC_IGNOREDIACRITIC.

Nota NORM_IGNORENONSPACE ignora qualquer distinção secundária, seja ela diacrítica ou não. Scripts para idiomas coreano, japonês, chinês e índice, entre outros, usam essa distinção para fins diferentes de diacríticos. LINGUISTIC_IGNOREDIACRITIC faz com que a função ignore apenas os diacríticos reais, em vez de ignorar o segundo peso de classificação.

NORM_IGNORESYMBOLS

Ignorar símbolos e pontuação.

Os sinalizadores listados abaixo são usados apenas com o sinalizador LCMAP_SORTKEY.

Sinalizador	Significado
LINGUISTIC_IGNORECASE	Ignorar maiúsculas e minúsculas, conforme linguisticamente apropriado.
LINGUISTIC_IGNOREDIACRITIC	Ignore caracteres sem espaçamento, conforme linguisticamente apropriado. Nota Esse sinalizador nem sempre produz resultados previsíveis quando usado com caracteres decompostos, ou seja, caracteres em que um caractere base e um ou mais caracteres não espaçados têm valores de ponto de código distintos.
NORM_IGNORECASE	Ignorar maiúsculas e minúsculas. Para muitos scripts (especialmente scripts latinos), NORM_IGNORECASE coincide com LINGUISTIC_IGNORECASE. Nota NORM_IGNORECASE ignora qualquer distinção terciária, seja realmente caso linguístico ou não. Por exemplo, em scripts árabes e índices, esse sinalizador distingue formas alternativas de um caractere, mas as diferenças não correspondem a maiúsculas e minúsculas linguísticas. LINGUISTIC_IGNORECASE faz com que a função ignore apenas maiúsculas e minúsculas linguísticas reais, em vez de ignorar o terceiro peso de classificação. Nota Para localidades DBCS (conjunto de caracteres de dois bytes), NORM_IGNORECASE tem um efeito em todos os caracteres Unicode, bem como caracteres estreitos (um byte), incluindo caracteres gregos e cirílicos.
NORM_IGNOREKANATYPE	Não diferencie entre caracteres hiragana e katakana. Os caracteres hiragana e katakana correspondentes são comparados como iguais.
NORM_IGNOREWIDTH	Ignore a diferença entre caracteres de meia largura e largura total, por exemplo, C a t == cat. A forma de largura total é uma distinção de formatação usada em scripts em chinês e japonês.
NORM_LINGUISTIC_CASING	Use regras linguísticas para uso de maiúsculas e minúsculas, em vez de regras do sistema de arquivos (padrão).
SORT_DIGITSASNUMBERS	Windows 7: Trate dígitos como números durante a classificação, por exemplo, classifique "2" antes de "10".
SORT_STRINGSORT	Trate a pontuação da mesma forma que os símbolos.

[in] lpSrcStr

Ponteiro para uma cadeia de caracteres de origem que a função mapeia ou usa para geração de chave de classificação. Essa cadeia de caracteres não pode ter um tamanho de 0.

[in] cchSrc

Tamanho, em caracteres, da cadeia de caracteres de origem indicada por lpSrcStr. O tamanho da cadeia de caracteres de origem pode incluir o caractere nulo de terminação, mas não precisa. Se o caractere nulo de terminação for incluído, o comportamento de mapeamento da função não será muito afetado porque o caractere nulo de terminação será considerado não classificável e sempre será mapeado para si mesmo.

O aplicativo pode definir esse parâmetro como qualquer valor negativo para especificar que a cadeia de caracteres de origem é terminada em nulo. Nesse caso, se LCMapStringEx estiver sendo usado em seu modo de mapeamento de cadeia de caracteres, a função calculará o comprimento da cadeia de caracteres em si e encerrará nulo a cadeia de caracteres mapeada indicada por lpDestStr.

O aplicativo não pode definir esse parâmetro como 0.

[out, optional] lpDestStr

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

Se o aplicativo estiver usando a função para gerar uma chave de classificação (LCMAP_SORTKEY):

A chave de classificação é armazenada no buffer e tratada como uma matriz opaca de bytes. Os valores armazenados podem incluir 0 bytes inseridos em qualquer posição.
A cadeia de caracteres de destino pode conter um número ímpar de bytes. O sinalizador LCMAP_BYTEREV reverte apenas um número par de bytes. O último byte (ímpar posicionado) na chave de classificação não é invertido.

Se o chamador solicitar explicitamente um subconjunto da cadeia de caracteres, a cadeia de caracteres de destino não incluirá um caractere nulo de terminação, a menos que o chamador o tenha especificado em cchDest.

Se essa função falhar, o buffer de destino poderá conter resultados parciais ou nenhum resultado. Nesse caso, todos os resultados devem ser considerados inválidos.

Observação

Ao definir LCMAP_UPPERCASE ou LCMAP_LOWERCASE, a cadeia de caracteres de destino pode usar o mesmo buffer que a cadeia de caracteres de origem. No entanto, isso é altamente desencorajado, pois algumas condições podem fazer com que a cadeia de caracteres com maiúsculas e minúsculas retornada tenha um comprimento diferente.

[in] cchDest

Tamanho, em caracteres, da cadeia de caracteres de destino indicada por lpDestStr. Se o aplicativo estiver usando a função para mapeamento de cadeia de caracteres, ele fornecerá uma contagem de caracteres para esse parâmetro. 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.

Se o aplicativo estiver usando a função para gerar uma chave de classificação, ele fornecerá uma contagem de bytes para o tamanho. Essa contagem de bytes deve incluir espaço para a chave de classificação 0x00 terminador.

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 ou a chave de classificação.

[in, optional] lpVersionInformation

Ponteiro para uma estrutura NLSVERSIONINFOEX que contém as informações de versão sobre a funcionalidade de NLS relevante; geralmente recuperado de GetNLSVersionEx.

Windows Vista, Windows 7: Reservados; deve definir como NULL.

[in, optional] lpReserved

Reservados; deve ser NULL.

[in, optional] sortHandle

Reservados; deve ser 0.

Observação

CompareStringEx e LCMapStringEx podem especificar um identificador de classificação (se o nome da localidade for nulo). Esse uso não é recomendado para a maioria dos aplicativos.

Retornar valor

Se a função for bem-sucedida quando usada para mapeamento de cadeia de caracteres, ela retornará o número de caracteres na cadeia de caracteres traduzida (consulte cchSrc e cchDest para obter mais detalhes).

Se a função for bem-sucedida quando usada para gerar uma chave de classificação, ela retornará o número de bytes na chave de classificaçã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_FLAGS. Os valores fornecidos para sinalizadores não eram válidos.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.

Comentários

O aplicativo pode usar LCMapString ou LCMapStringEx para gerar uma chave de classificação. Para fazer isso, o aplicativo especifica LCMAP_SORTKEY para o parâmetro dwMapFlags . Para obter mais informações, consulte Manipulando a classificação em seus aplicativos.

Observação

As chaves de classificação são fluxos de bytes opacos. Os chamadores devem tratá-los como uma matriz de bytes do comprimento retornado pela API e não depender de nenhuma estrutura interna que possa parecer estar presente. Zero, um ou mais bytes na chave de classificação retornada podem ser 0. Ausência ou presença de um byte zero não deve ser esperada.

Outra maneira de seu aplicativo usar LCMapString ou LCMapStringEx é em cadeias de caracteres de mapeamento. Nesse caso, o aplicativo não especifica LCMAP_SORTKEY para o parâmetro dwMapFlags , mas fornece alguma outra combinação de sinalizadores. Para obter mais informações, consulte Manipulando a classificação em seus aplicativos.

A partir do Windows Vista: Essa função pode manipular dados de localidades personalizadas. Não há garantia de que os dados sejam iguais de computador para computador ou entre execuções de um aplicativo. Se o aplicativo precisar persistir ou transmitir dados, consulte Usando dados de localidade persistente.

Começando no Windows 8: se o aplicativo passar marcas de idioma para essa função do namespace Windows.Globalization, ele deverá primeiro converter as marcas chamando ResolveLocaleName.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll