Função LCMapStringA (winnls.h)

Artigo
11/20/2024

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.

Observação Por motivos de interoperabilidade, o aplicativo deve preferir a função LCMapStringEx para LCMapString porque a Microsoft está migrando para o uso de nomes de localidade em vez de identificadores de localidade para novas localidades. Essa recomendação se aplica especialmente a localidades personalizadas, incluindo aquelas criadas pela Microsoft. Qualquer aplicativo que será executado somente no Windows Vista e posterior deve usar LCMapStringEx.

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 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 classificar a geração de chave. 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 é considerado inválido 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 seja encerrada 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 só reverte 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.

Nota

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 for 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 de retorno

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.

Observações

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 padrão do Windows ANSI do sistema. No entanto, caracteres que são indefinidos na página de código do sistema aparecem na cadeia de caracteres como um ponto de interrogação (?).

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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