Macros de conversion de chaînes ATL et MFC

Les macros de conversion de chaînes traitées ici sont valides pour ATL et MFC.Pour plus d'informations sur la conversion de chaînes MFC, consultez TN059 : Utilisation des macros de conversion MFC MBCS/Unicode et le macro MFC et Globals.

• ATL 7,0 classes et macros de conversion de chaînes

• ATL 3,0 macros de conversion de chaînes

ATL 7,0 classes et macros de conversion de chaînes

ATL 7,0 présente plusieurs nouvelles classes et macros de conversion, apportant des améliorations significatives sur les macros existantes.

Les noms des nouvelles classes et macros de conversion de chaînes prennent la forme :

CSourceType2C[] []EXDestinationType

où :

• SourceType et DestinationType sont décrits dans le tableau ci-dessous.

• []Cest le présent lorsque le type de destination doit être constant.

• []EXest le présent lorsque la taille de la mémoire tampon doit être spécifiée comme argument template.

  SourceType/DestinationType	Description
  A	Chaîne de caractères ANSI.
  W	Chaîne de caractères Unicode.
  T	Chaîne de caractères génériques (équivalente à W _UNICODE lorsque le est défini, équivalente à sinon).
  OLE	OLE chaîne de caractères (équivalente à W).

Par exemple, pour convertir d'une chaîne Unicode en une chaîne générique sans modifier la chaîne convertie, utilisez CW2CT.

Si on sait que la chaîne convertie est peu susceptible d'être plus de 64 caractères, la version de EX , telle que CW2CTEX<64>, peut être utilisée pour économiser de l'espace sur la pile.

[!REMARQUE]

La méthode recommandée pour convertir vers et depuis des chaînes BSTR est d'utiliser la classe de CComBSTR .Pour convertir BSTR, passez la chaîne existante au constructeur de CComBSTR. Pour convertir BSTR, utilisez COLE2CDestinationType[] []EX, telles que COLE2T.

Les nouvelles classes de conversion qui requièrent une utilisation de la mémoire tampon (CA2AEX, CA2WEX, CW2AEX, et CW2WEX) un tampon statique de taille fixe d'enregistrer le résultat de la conversion.Si le résultat est trop grand pour s'insérer dans la mémoire tampon statique, la classe alloue de la mémoire à malloc, libération de la mémoire lorsque l'objet est hors de portée.Cela garantit que, contrairement aux macros plus anciennes de conversion de texte, ces classes sont sécurisées pour les utiliser dans les boucles et ne déborderont pas la pile.

Les macros de conversion introduites dans ATL 7,0 sont optimisées pour connaître les chaînes d'entrée de NULL .Ces macros retournent NULL si le paramètre d'entrée est NULL sans allouer toute mémoire.

Par défaut, les classes de conversion ATL et les macros utilisent la page de codes ANSI du thread actuel de la conversion.Si vous souhaitez substituer ce comportement pour une conversion spécifique à l'aide de macros en fonction de les classes CA2WEX ou CW2AEX, spécifiez la page de codes comme second paramètre au constructeur de la classe.

Note de sécurité
Vérifiez la longueur des chaînes avant de les passer à ces macros pour éviter les dépassements de mémoire tampon potentiels.Le dépassement de capacité de la pile sont des exceptions qui peuvent également être interceptées au test/exception.

Il existe plusieurs différences importantes entre les macros de conversion de chaînes plus anciennes et nouvelles classes de conversion de chaînes :

Exemple

Code

//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);
}

Un avertissement concernant les instances de classe temporaires

Il doit noter que les éléments suivants n'est pas beaucoup de code :

LPCTSTR szr = CA2T(szReplaceFile);

À l'aide de ATL 3,0 macros, il est acceptable d'utiliser :

LPCTSTR szr = A2T(szReplaceFile);   

lorsque la mémoire allouée par les fonctions de conversion n'est pas libérée jusqu'à ce que la fonction active a été quittée.Le même code ne fonctionne pas avec les nouvelles classes.

Ce code :

LPCTSTR szr = CA2T(szReplaceFile);   

équivaut à ceci :

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

Comme mémoire allouée par l'objet temporaire et retournée par l'opérateur de cast est perdu lorsque l'objet temporaire est détruit, à l'aide de la valeur dans szr aura des résultats indésirables.

À la place, utilisez le code suivant :

CA2T szr(szReplaceFile);   

L'opérateur de cast est le ressembler d'objet de CA2T à LPCTSTR.

Utilisation avancée

La taille de mémoire tampon statique par défaut est 128 caractères.Si la taille de la mémoire tampon doit être modifiée pour une conversion spécifique, utilisez la version EX d'une macro, puis spécifiez la taille de mémoire tampon comme argument template.

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

Voici un exemple de spécifier la page de codes comme second paramètre au constructeur de la classe.

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

ATL 3,0 macros de conversion de chaînes

Les macros de conversion de texte d'origine sont toujours disponibles et sont répertoriées dans le tableau ci-dessous :

ATL 3,0 macros de conversion de chaînes

La syntaxe d'utilisation de ces macros est la suivante :

MACRONAME( string_address )

Par exemple :

A2W(lpa);

Dans les noms de macros, le type chaîne source est située à gauche (par exemple, Un) et le type de chaîne de destination est à droite (par exemple, W).A représente LPSTR, OLE représente LPOLESTR, T représente LPTSTR, et en charge par W pour LPWSTR.

S'il existe C dans le nom de la macro, la macro convertit en chaîne const .Par exemple, W2CA convertit LPWSTR à LPCSTR.

Ainsi, A2W convertit LPSTR à LPWSTR, OLE2T convertit LPOLESTR à LPTSTR, et ainsi de suite.

Le comportement des macros de conversion de chaînes ATL en dépend de la directive du compilateur en effet, le cas échéant.Si la source et les types de destination sont identiques, aucune conversion n'a lieu.Modification T et OLE de directives de compilateur comme suit :

La chaîne de destination est créée en utilisant _alloca, sauf lorsque le type de destination est BSTR.Utilisation du _alloca alloue de la mémoire en dehors de la pile, de sorte que lorsque votre fonction, elle soit automatiquement nettoyée.Par défaut cette macro convertira uniquement jusqu'à 500KB en même temps.

Lorsque vous utilisez une macro de conversion de chaînes ATL, spécifiez la macro d' USES_CONVERSION au début de la fonction pour éviter des erreurs du compilateur.Par exemple :

void StringFunc(LPSTR lpsz)
{
   USES_CONVERSION;

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

Configuration requise

Header file: AtlBase.h, AtlConv.h (déclaré dans AtlConv.h)

Voir aussi

Référence

Macros de conversion de chaînes de DEVMODE et de TEXTMETRIC

Autres ressources

Macros ATL