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

Macros de conversão de cadeia de caracteres discutidos aqui são válidos para ATL e MFC.Para obter mais informações sobre a conversão de cadeia de caracteres MFC, consulte TN059: Usando macros de conversão MFC MBCS/Unicode e Macros MFC e Globais.

• Classes e macros de conversão de cadeia de caracteres de ATL 7,0

• Macros de conversão de cadeia de caracteres de ATL 3,0

Classes e macros de conversão de cadeia de caracteres de ATL 7,0

ATL 7,0 apresenta diversas novas classes e macros de conversão, fornecendo aprimoramentos significativos nas macros existentes.

Os nomes das novas classes e macros de conversão de cadeia de caracteres assume a forma:

CSourceType2[C]DestinationType[EX]

onde:

• SourceType e DestinationType são descritos na tabela abaixo.

• [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
  A	Cadeia de caracteres ANSI.
  W	Cadeia de caracteres Unicode.
  T	Cadeia de caracteres genérico (equivalente ao _UNICODE W quando é definido, equivalente ao contrário.)
  O OLE	Cadeia de caracteres OLE (equivalente a W).

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

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

Observação
A maneira recomendada para converter e de cadeias de caracteres de BSTR é usar a classe de CComBSTR .Para converter um BSTR, passe a cadeia de caracteres existente para o construtor de CComBSTR. Para converter de um BSTR, use COLE2[C]DestinationType[EX], como COLE2T.

As novas classes de conversão que exigem um uso do buffer (CA2AEX, CA2WEX, CW2AEX, e) CW2WEXum buffer estático de tamanho fixo armazenar o resultado da conversão.Se o resultado é muito grande caber no buffer estático, a classe aloca memória usando malloc, liberando memória quando o objeto sai do escopo.Isso garante que, ao invés de macros mais antigos de conversão de texto, essas classes são seguras de usar em loop e não transbordem a pilha.

Macros de conversão introduzidos em ATL 7,0 são otimizados para estar cientes de cadeias de caracteres de NULO de entrada.Esses NULO macros retornará se o parâmetro de entrada é NULO sem atribuir qualquer memória.

Por padrão, as classes de conversão de ATL e macros usarão a página de código ANSI atual da thread para a conversão.Se você deseja sobrescrever o comportamento de uma conversão específica usando as macros baseados em classes CA2WEX ou CW2AEX, especifica a página de código como o segundo parâmetro para o construtor para a classe.

Observação de segurança
Verifique o comprimento de cadeias de caracteres antes de transmitir a esses macros para evitar problemas potenciais de estouro de buffer.Os estouros de pilha são as exceções que podem também ser detectadas com try/catch para exceto.

Há várias diferenças importantes entre as macros mais antigos de conversão de cadeia de caracteres e as novas classes de conversão de cadeia de caracteres:

Macros antigos de conversão de ATL 3,0	Novas classes de conversão de ATL 7,0
Aloca memória na pilha.	Memória de pilha usos para cadeias de caracteres pequenas.Usa o heap se a pilha não é grande o suficiente.
a cadeia de caracteres é liberada quando a função é saída.	A cadeia de caracteres é liberada quando a variável sai do escopo.
Não pode ser usado em manipuladores de exceção.	Pode ser usado em manipuladores de exceção.
Não é adequado para uso em loop.O uso de memória cresce até que a função está saída.	Suporta usam em loop.O escopo do loop garante que a memória é liberada em cada iteração.
Não bom para grandes cadeias de caracteres.O espaço de pilha é limitado.	Quaisquer problemas com grandes cadeias de caracteres.As cadeias de caracteres atribuídas serão no heap.
Geralmente requer USES_CONVERSION para ser definido.	Nunca requer USES_CONVERSION para ser definido.
O significado do OLE depende da definição de OLE2ANSI.	O 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);
}

Um aviso sobre as instâncias de classe temporários

Deve-se forçar que não é um bom o seguinte código:

LPCTSTR szr = CA2T(szReplaceFile);

Usando macros de ATL 3,0, era aceitável usar:

LPCTSTR szr = A2T(szReplaceFile);   

porque a memória alocada as funções de conversão não será liberada até que a função atual é saída.O mesmo código não funciona com as novas classes.

Esse código:

LPCTSTR szr = CA2T(szReplaceFile);   

é equivalente a isso:

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

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

Em vez de isso, use esse código:

CA2T szr(szReplaceFile);   

O operador cast faz o objeto de CA2T parecer com LPCTSTR.

Uso avançado

O tamanho do buffer estático padrão é 128 caracteres.Se o tamanho do buffer deve ser alterado para uma conversão específica, use a versão EX de uma macro, e especificar 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 especificar a página de código como o segundo parâmetro para o construtor para a 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 de ATL 3,0

Macros de conversão do texto original ainda estão disponíveis e são listados na tabela abaixo:

Macros de conversão de cadeia de caracteres de ATL 3,0

A2BSTR	OLE2A	T2A	W2A
A2COLE	OLE2BSTR	T2BSTR	W2BSTR
A2CT	OLE2CA	T2CA (substituído.Use T2CA_EX ou CT2CA em vez de isso.)	W2CA
A2CW	OLE2CT	T2COLE	W2COLE
A2OLE	OLE2CW	T2CW	W2CT
A2T	OLE2T	T2OLE	W2OLE
A2W	OLE2W	T2W	W2T

A sintaxe para usar esses macros é o seguinte:

MACRONAME( string_address )

Por exemplo:

A2W(lpa);

Em nomes macros, o tipo cadeia de caracteres de origem é à esquerda (por exemplo, A) e o tipo cadeia de caracteres de destino estiverem à direita (por exemplo, W).A representa LPSTR, OLE representa LPOLESTR, T representa LPTSTR, e suporte de W para LPWSTR.

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

Assim, A2W converte LPSTR a LPWSTR, OLE2T converte LPOLESTR a LPTSTR, e assim por diante.

O comportamento de macros de conversão de cadeia de caracteres de ATL depende da diretiva de compilador aplicado, se houver.Se os tipos de origem e de destino são os mesmos, nenhuma conversão ocorre.Alteração T e OLE das diretivas de compilador como segue:

Diretiva de compilador aplicado	Se torna t	Se torna o OLE
Nenhum	A	W
_UNICODE	W	W
OLE2ANSI	A	A
_UNICODE e OLE2ANSI	W	A

A cadeia de caracteres de destino é criada usando oalloca_, exceto quando o tipo de destino é BSTR.Usar o _alloca aloca memória para fora da pilha, de modo que quando a função retorna, é removida automaticamente.Por padrão converter-se-&z este macro até 500KB ao mesmo tempo.

A o usar uma macro de conversão de cadeia de caracteres de ATL, especifique a macro de USES_CONVERSION no início da função para evitar erros de 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

Header file: AtlBase.h, AtlConv.h (declarada 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