Função LCMapStringEx (winnls.h)
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.
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.
Os sinalizadores listados abaixo são usados apenas com o sinalizador LCMAP_SORTKEY.
[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 |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de