Partager via

Macros de conversion de chaînes ATL et MFC

  • Article

Les macros de conversion de chaînes présentées ici sont valides à la fois pour ATL et pour MFC. Pour plus d'informations sur la conversion des chaînes de MFC, consultez TN059 : Using MFC MBCS/Unicode Conversion Macros et MFC Macros and Globals.

  • Classes et macros de conversion de chaînes ATL 7.0

  • Macros de conversion de chaînes ATL 3.0

Classes et macros de conversion de chaînes ATL 7.0

ATL 7.0 introduit plusieurs nouvelles classes et macros de conversion, fournissant ainsi des améliorations significatives par rapport aux macros existantes.

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

CType_source2[C]Type_de_destination[EX]

où :

  • Type_source et Type_de_destination sont décrits dans le tableau ci-dessous.

  • [C] est présent quand le type de destination doit être constant.

  • [EX] est présent quand la taille initiale de la mémoire tampon doit être spécifiée comme argument de modèle.

    Type_source/Type_de_destination

    Description

    A

    Chaîne de caractères ANSI.

    W

    Chaîne de caractères Unicode.

    T

    Chaîne de caractères générique (équivalente à W quand _UNICODE est défini, sinon équivalente à A).

    OLE

    Chaîne de caractères OLE (équivalente à W).

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

Avertissement

Certaines des permutations du modèle répertoriées plus haut ne sont pas prises en charge.CA2CW et CW2CA (et CA2CWEX et CW2CAEX) ne sont pas pris en charge.Pour les conversions de chaînes de caractères OLE, seuls COLE2T et CT2OLE (et COLE2CT, COLE2TEX, COLE2CTEX, CT2COLE, CT2OLEEX et CT2COLEEX) sont pris en charge.Pour des détails, consultez atlconv.h.

S'il est peu probable que la chaîne convertie dépasse 64 caractères, la version de EX, comme CW2CTEX<64>, peut être utilisée pour gagner de l'espace sur la pile.

Notes

Le moyen recommandé de convertir vers et depuis des chaînes BSTR est d'utiliser la classe CComBSTR.Pour convertir vers une chaîne BSTR, passez la chaîne existante au constructeur de CComBSTR.Pour convertir depuis une chaîne BSTR, utilisez COLE2[C]DestinationType[EX], comme COLE2T.

Les nouvelles classes de conversion qui nécessitent une mémoire tampon (CA2AEX, CA2WEX, CW2AEX et CW2WEX) utilisent une mémoire tampon statique de taille fixe pour stocker le résultat de la conversion. Si le résultat est trop grand pour tenir dans la mémoire tampon statique, la classe alloue de la mémoire avec malloc et libère la mémoire quand l'objet passe en dehors de l'étendue. Ceci garantit que, au contraire des anciennes macros de conversion de texte, l'utilisation de ces classes dans des boucles est sécurisée et ne provoquera pas un dépassement de capacité de la pile.

Les macros de conversion introduites dans ATL 7.0 sont optimisées pour la prise en compte de l'entrée de chaînes NULL. Ces macros retournent NULL si le paramètre d'entrée est NULL sans allouer de mémoire.

Par défaut, les classes et macros de conversion ATL utilisent la page de codes ANSI du thread actif pour la conversion. Si vous voulez remplacer ce comportement pour une conversion spécifique en utilisant des macros basées sur les classes CA2WEX ou CW2AEX, spécifiez la page de codes comme second paramètre du constructeur pour la classe.

Note de sécuritéNote de sécurité

Vérifiez la longueur des chaînes avant de les passer à ces macros, pour éviter des problèmes potentiels de dépassement de capacité de la mémoire tampon.Les dépassements de capacité de la pile sont des exceptions qui peuvent aussi être interceptées avec try/except.

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

Anciennes macros de conversion ATL 3.0

Nouvelles classes de conversion ATL 7.0

Alloue de la mémoire sur la pile.

Utilise la mémoire de la pile pour les petites chaînes. Utilise le tas si la pile n'est pas assez grande.

La chaîne est libérée quand la fonction se termine.

La chaîne est libérée quand la variable passe en dehors de l'étendue.

Ne peut pas être utilisée dans des gestionnaires d'exceptions.

Peut être utilisée dans les gestionnaires d'exceptions.

Ne convient pas à une utilisation dans des boucles. L'utilisation de la mémoire croît jusqu'à ce que la fonction se termine.

Prend en charge une utilisation dans des boucles. L'étendue des boucles garantit que la mémoire est libérée à chaque itération.

Ne convient pas pour les chaînes de grande taille. L'espace de la pile est limité.

Pas de problèmes avec les chaînes de grande taille. Les chaînes feront l'objet d'une allocation sur le tas.

Requiert généralement USES_CONVERSION pour être définie.

Ne requiert jamais USES_CONVERSION pour être définie.

La signification d'OLE dépend de sa définition d'OLE2ANSI.

OLE est toujours équivalent à W.

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

Avertissement concernant les instances des classes temporaires

Nous voulons insister sur le fait que le code suivant n'est pas du bon code :

LPCTSTR szr = CA2T(szReplaceFile);

Avec les macros ATL 3.0, il était acceptable d'utiliser :

LPCTSTR szr = A2T(szReplaceFile);

car la mémoire allouée par les fonctions de conversion n'étaient pas libérées jusqu'à ce que la fonction se termine. Le même code ne fonctionne pas avec les nouvelles classes.

Ce code :

LPCTSTR szr = CA2T(szReplaceFile);

équivaut au code :

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

Comme la mémoire allouée par l'objet temporaire et retournée depuis l'opérateur de cast est détruite quand l'objet temporaire est détruit, l'utilisation de la valeur dans szr produira des résultats indésirables.

Utilisez ce code à la place :

CA2T szr(szReplaceFile);

L'opérateur de cast fait que l'objet CA2T ressemble à un type LPCTSTR.

Utilisation avancée

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

// 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écification de la page de codes comme second paramètre pour un 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));
}

Macros de conversion de chaînes ATL 3.0

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

Macros de conversion de chaînes ATL 3.0

A2BSTR

OLE2A

T2A

W2A

A2COLE

OLE2BSTR

T2BSTR

W2BSTR

A2CT

OLE2CA

T2CA (Obsolète. Utilisez à la place T2CA_EX ou CT2CA.)

W2CA

A2CW

OLE2CT

T2COLE

W2COLE

A2OLE

OLE2CW

T2CW

W2CT

A2T

OLE2T

T2OLE

W2OLE

A2W

OLE2W

T2W

W2T

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

MACRONAME( string_address )

Par exemple :

A2W(lpa);

Dans les noms des macros, le type de la chaîne source se trouve à gauche (par exemple A) et le type de la chaîne de destination se trouve à droite (par exemple W). A représente LPSTR, OLE représente LPOLESTR, T représente LPTSTR et W représente LPWSTR.

S'il existe un C dans le nom de la macro, cela signifie que la macro convertit en une chaîne const. Par exemple, W2CA convertit un type LPWSTR en un type LPCSTR.

Ainsi, A2W convertit un type LPSTR en un type LPWSTR, OLE2T convertit un type LPOLESTR en un type LPTSTR, etc.

Le comportement des macros de conversion de chaînes ATL dépend de la directive du compilateur qui est appliquée, le cas échéant. Si les types source et de destination sont les mêmes, aucune conversion n'est effectuée. Les directives du compilateur changent T et OLE comme suit :

Directive du compilateur appliquée

T devient

OLE devient

Aucun

A

W

_UNICODE

W

W

OLE2ANSI

A

A

_UNICODE et OLE2ANSI

W

A

La chaîne de destination est créée avec _alloca, sauf quand le type de destination est BSTR. L'utilisation de _alloca alloue de la mémoire en dehors de la pile. Ainsi, quand votre fonction se termine, elle est automatiquement nettoyée. Par défaut, cette macro convertit jusqu'à 500 Ko en une fois.

Quand vous utilisez une macro de conversion de chaînes ATL, spécifiez la macro USES_CONVERSION au début de votre fonction pour éviter les erreurs de compilation. Par exemple :

void StringFunc(LPSTR lpsz)
{
   USES_CONVERSION;

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

Spécifications

Fichier d'en-tête : 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