Função LCMapStringA (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 LCMapStringA(
  [in]            LCID   Locale,
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  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 valores predefinidos a seguir.

• LOCALE_INVARIANT
• LOCALE_SYSTEM_DEFAULT
• LOCALE_USER_DEFAULT

• LOCALE_CUSTOM_DEFAULT
• LOCALE_CUSTOM_UI_DEFAULT
• LOCALE_CUSTOM_UNSPECIFIED

[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 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 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 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.

[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 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.

• 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

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 ter êxito 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, os caracteres indefinidos na página de código do sistema aparecem na cadeia de caracteres como um ponto de interrogação (?).

Requisitos

Confira também

CompareString

FindNLSString

GetNLSVersion

Manipulando a classificação em seus aplicativos

LCMapStringEx

Suporte a idiomas nacionais

Funções de suporte à linguagem nacional