Macros de conversão de cadeia de caracteres de ATL e de MFC

Artigo
06/09/2015

As macros de conversão de cadeia de caracteres discutidas neste documento são válidas para ATL e MFC. Para obter mais informações sobre conversão de cadeia de caracteres MFC, consulte TN059: Usando Macros de Conversão MFC MBCS/Unicode e Macros e Globais MFC.

Macros e classes de conversão de cadeia de caracteres ATL 7.0
Macros de conversão de cadeia de caracteres ATL 3.0

Macros e classes de conversão de cadeia de caracteres ATL 7.0

A ATL 7.0 apresenta diversas novas macros e classes de conversão, fornecendo melhorias significativas sobre as macros existentes.

Os nomes das novas macros e classes de conversão de cadeia de caracteres assumem o formato:

CSourceType2[C]DestinationType[EX]

onde:

SourceType e DestinationType são descritos na tabela a seguir.
[C] está presente quando o tipo de destino deve ser constante.

[EX] está presente quando o tamanho inicial do buffer deve ser especificado como um argumento de modelo.

SourceType/DestinationType	Descrição
Um	Cadeia de caracteres ANSI.
W	Cadeia de caracteres Unicode.
T	Cadeia de caracteres genérica (equivalente a W quando _UNICODE for definido, caso contrário, equivalente a A).
OLE	Cadeia de caracteres OLE (equivalente a W).

Por exemplo, para converter uma cadeia de caracteres Unicode em uma cadeia de caracteres genérica sem alterar a cadeia convertida, use CW2CT.

Aviso

Algumas permutações do padrão relacionado acima não têm suporte.CA2CW e CW2CA (e CA2CWEX e CW2CAEX) não têm suporte.Para conversões de cadeia de caracteres OLE, apenas COLE2T e CT2OLE (e COLE2CT, COLE2TEX, COLE2CTEX, CT2COLE, CT2OLEEX e CT2COLEEX) têm suporte.Para obter mais detalhes, consulte atlconv.h.

Se for conhecido que é improvável a cadeia de caracteres convertida ter mais de 64 caracteres, a versão EX, como a CW2CTEX<64>, pode ser usada para economizar espaço na pilha.

Dica

A maneira recomendável de converter para e de cadeias de caracteres BSTR é usar a classe CComBSTR.Para converter para BSTR, passe a cadeia de caracteres existente ao construtor de CComBSTR.Para converter de BSTR, use COLE2[C]DestinationType[EX], como COLE2T.

As novas classes de conversão que exigem buffer (CA2AEX, CA2WEX, CW2AEX e CW2WEX) usam um buffer estático de tamanho fixo para armazenar o resultado da conversão. Se o resultado for muito grande para caber no buffer estático, a classe aloca memória usando malloc, liberando a memória quando o objeto sair do escopo. Isso garante que, diferente de macros de conversão de texto mais antigas, é seguro usar essas classes em loops e não estouram a pilha.

As macros de conversão apresentadas na ATL 7.0 são otimizadas para detectar cadeias de caracteres de entrada NULL. Essas macros retornam NULL se o parâmetro de entrada for NULL sem alocar qualquer memória.

Por padrão, as macros e classes de conversão ATL usam a página de código ANSI dos threads atuais para a conversão. Se desejar substituir esse comportamento para uma conversão específica usando macros com base nas classes CA2WEX ou CW2AEX, especifique a página de código como o segundo parâmetro para o construtor da classe.

Observação de segurança
Verifique o comprimento das cadeias de caracteres antes de passar para essas macros para evitar problemas de saturação de buffer potenciais.Estouros de pilha são exceções que também podem ser capturadas com try/except.

Existem diversas diferenças importantes entre as macros de conversão de cadeia mais antigas e as novas classes de conversão de cadeia de caracteres:

Macros de Conversão ATL 3.0 Antigas	Novas Classes de Conversão ATL 7.0
Aloca memória na pilha.	Usa memória de pilha para pequenas cadeias de caracteres. Usa o heap se a pilha não for grande o suficiente.
A cadeia de caracteres é liberada quando a função é fechada.	A cadeia de caracteres é liberada quando a variável sai do escopo.
Não pode ser usada em manipuladores de exceção.	Pode ser usada em manipuladores de exceção.
Não adequado para uso em loops. O uso de memória cresce até a função ser fechada.	Oferece suporte ao uso em loops. O escopo do loop garante que a memória será liberada em cada iteração.
Não adequado para cadeias de caracteres grandes. O espaço em pilha é limitado.	Sem problemas com cadeias de caracteres grandes. Cadeias de caracteres serão alocadas no heap.
Geralmente exige definir USES_CONVERSION.	Nunca exige definir USES_CONVERSION.
O significado de OLE depende da definição de OLE2ANSI.	OLE é sempre equivalente a W.

Exemplo

Código

//Example 1 
// Convert LPCWSTR to LPCSTR. 
void ExampleFunction1(LPCWSTR pszW)
{
   // Create an instance of CW2A, called pszA, 
   // and initialize it with pszW.
   CW2A pszA(pszW);
   // pszA works like an LPCSTR, and can be used thus:
   ExampleFunctionA(pszA);  
   // Note: pszA will become invalid when it goes out of scope.
}

// Example 2 
// Use a temporary instance of CW2A. 
void ExampleFunction2(LPCWSTR pszW)
{
   // Create a temporary instance of CW2A, 
   // and initialize it with pszW.
   ExampleFunctionA(CW2A(pszW));
   // Note: the temporary instance becomes invalid  
   // after the execution of the statement above.
}

// Example 3 
// Incorrect use of conversion macros. 
void ExampleFunction3(LPCWSTR pszW)
{
   // Create a temporary instance of CW2A, 
   // save a pointer to it and then delete 
   // the temportary instance.
   LPCSTR pszA = CW2A(pszW);
   // The pszA in the following line is an invalid pointer, 
   // as the instance of CW2A has gone out of scope.
   ExampleFunctionA(pszA);
}

Uma advertência em relação a instâncias de classe temporária

Deve ser testado se o código a seguir não é bom:

LPCTSTR szr = CA2T(szReplaceFile);

Usando macros ATL 3.0, era aceitável usar:

LPCTSTR szr = A2T(szReplaceFile);

pois a memória alocada pelas funções de conversão não será liberada até a função atual ser fechada. O mesmo código não funciona com as novas classes.

Este código:

LPCTSTR szr = CA2T(szReplaceFile);

equivale a isto:

LPCTSTR szr;
{
   CA2T temp(szReplaceFile);
   szr = temp.operator LPTSTR();
}

Como a memória alocada pelo objeto temporário e retornado do operador cast é destruída quando o objeto temporário é destruído, usar o valor em szr terá resultados indesejados.

Ao invés, use este código:

CA2T szr(szReplaceFile);

O operador cast faz o objeto CA2T parecer uma LPCTSTR.

Uso Avançado

O tamanho padrão do buffer estático é de 128 caracteres. Se for necessário alterar o tamanho do buffer para uma conversão específica, use a versão EX de uma macro e especifique o tamanho do buffer como um argumento de modelo.

// Example 4 
// Changing the size of the buffer. 
void ExampleFunction4(LPCWSTR pszW)
{
   // Use a 16-character buffer.
   ExampleFunctionA(CW2AEX<16>(pszW));
}

Aqui está um exemplo de especificação da página de código como o segundo parâmetro para o construtor da classe.

// Example 5 
// Specifying the code page. 
void ExampleFunction5(LPCWSTR pszW)
{
   // Convert to the Macintosh code page
   ExampleFunctionA(CW2A(pszW, CP_MACCP));
}

Macros de conversão de cadeia de caracteres ATL 3.0

As macros originais de conversão de texto ainda estão disponíveis e são listadas na tabela a seguir:

Macros de conversão de cadeia de caracteres ATL 3.0

A2BSTR	OLE2A	T2A	W2A
A2COLE	OLE2BSTR	T2BSTR	W2BSTR
A2CT	OLE2CA	T2CA (Preterido. Use T2CA_EX ou CT2CA ao invés.)	W2CA
A2CW	OLE2CT	T2COLE	W2COLE
A2OLE	OLE2CW	T2CW	W2CT
A2T	OLE2T	T2OLE	W2OLE
A2W	OLE2W	T2W	W2T

A sintaxe para uso dessas macros é a seguinte:

MACRONAME( string_address )

Por exemplo:

A2W(lpa);

Nos nomes das macros, o tipo de cadeia de caracteres de origem está à esquerda (por exemplo, A) e o tipo de cadeia de caracteres de destino está à direita (por exemplo, W). A significa LPSTR, OLE significa LPOLESTR, T significa LPTSTR e W significa LPWSTR.

Se houver um C no nome da macro, a macro converte para uma cadeia de caracteres const. Por exemplo, W2CA converte uma LPWSTR em uma LPCSTR.

Logo, A2W converte uma LPSTR em uma LPWSTR, OLE2T converte uma LPOLESTR em uma LPTSTR e assim por diante.

O comportamento das macros de conversão de cadeia de caracteres ATL depende da diretriz do compilador em vigor, quando houver. Se os tipos de origem e de destino forem o mesmo, a conversão não ocorre. Diretrizes do compilador alteram T e OLE da seguinte maneira:

Diretriz do compilador em vigor	T torna-se	OLE torna-se
Nenhum	A	W
_UNICODE	W	W
OLE2ANSI	A	A
_UNICODE e OLE2ANSI	W	A

A cadeia de caracteres de destino é criada usando _alloca, exceto quando o tipo de destino for BSTR. Usar _alloca aloca memória fora da pilha, para quando a função retornar, ser limpa automaticamente. Por padrão, essa macro apenas converterá até 500 KB de cada vez.

Ao usar uma macro de conversão de cadeia de caracteres ATL, especifique a macro USES_CONVERSION no início da função para evitar erros do compilador. Por exemplo:

void StringFunc(LPSTR lpsz)
{
   USES_CONVERSION;

   LPWSTR x = A2W(lpsz);
   // Do something with x
   wprintf_s(L"x is %s", x);
}

Requisitos

Arquivo de cabeçalho: AtlBase.h, AtlConv.h (declarado em AtlConv.h)

Consulte também

Referência

Macros de conversão de cadeia de caracteres de DEVMODE e de TEXTMETRIC

Outros recursos

Macros de ATL

Compartilhar via

Macros de conversão de cadeia de caracteres de ATL e de MFC

Macros e classes de conversão de cadeia de caracteres ATL 7.0

Exemplo

Código

Uma advertência em relação a instâncias de classe temporária

Uso Avançado

Macros de conversão de cadeia de caracteres ATL 3.0

Requisitos

Consulte também

Referência

Outros recursos

Recursos adicionais