Função LCMapStringW (winnls.h)
Para uma localidade especificada pelo identificador, 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 LCMapStringW(
[in] LCID Locale,
[in] DWORD dwMapFlags,
[in] LPCWSTR lpSrcStr,
[in] int cchSrc,
[out, optional] LPWSTR lpDestStr,
[in] int cchDest
);
Parâmetros
[in] Locale
Identificador de localidade que especifica a localidade. Você pode usar a macro MAKELCID para criar um identificador de localidade ou usar um dos seguintes valores predefinidos.
Também há suporte para os seguintes identificadores de localidade personalizados.[in] dwMapFlags
Sinalizadores que especificam 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. Para obter definições detalhadas, consulte o parâmetro dwMapFlags de LCMapStringEx.
[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 igual a 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 é considerado insociável e sempre é mapeado para si mesmo.
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, se LCMapString estiver sendo usado em seu modo de mapeamento de cadeia de caracteres, a função calculará o próprio comprimento da cadeia de caracteres 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) 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 cased 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.
Valor retornado
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 mapeamento de cadeia de caracteres, 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 foi 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.
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 foi 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
Consulte Comentários para LCMapStringEx.
A versão ANSI do LCMapString mapeia cadeias de caracteres de e para Unicode com base na página de código padrão do Windows (ANSI) associada à localidade especificada. Quando a versão ANSI dessa função é usada com uma localidade somente Unicode, a função pode ser bem-sucedida porque o sistema operacional usa o valor CP_ACP, representando a página de código ANSI padrão do sistema do Windows. No entanto, caracteres indefinidos na página de código do sistema aparecem na cadeia de caracteres como um ponto de interrogação (?).
Observação
O cabeçalho winnls.h define LCMapString como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| 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 |