ATL and MFC String Conversion Macros

Die hier besprochenen Zeichenfolgenkonvertierungsmakros sind sowohl für ATL als auch für MFC gültig. Weitere Informationen zur MFC-Zeichenfolgenkonvertierung finden Sie unter TN059: Verwenden von MFC MBCS/Unicode-Umwandlungsmakros und MFC-Makros, globale Funktionen und globale Variablen.

• ATL 7.0-Klassen und -Makros für die Zeichenfolgenkonvertierung

• ATL 3.0-Makros für die Zeichenfolgenkonvertierung

ATL 7.0-Klassen und -Makros für die Zeichenfolgenkonvertierung

ATL 7.0 führt mehrere neue Konvertierungsklassen und -makros ein, die eine maßgebliche Verbesserung gegenüber bestehenden Makros bedeuten.

Die Namen der neuen Klassen und Makros für die Zeichenfolgenkonvertierung haben das folgende Format:

CSourceType2[C]DestinationType[EX]

Dabei gilt:

• SourceType und DestinationType werden in der nachfolgenden Tabelle beschrieben.

• [C] wird angegeben, wenn der Zieltyp eine Konstante sein muss.

• [EX] wird angegeben, wenn die anfängliche Puffergröße als Vorlagenargument angegeben werden muss.

  SourceType/DestinationType	Beschreibung
  A	ANSI-Zeichenfolge.
  W	Unicode-Zeichenfolge.
  T	Allgemeine Zeichenfolge (entspricht W, wenn _UNICODE definiert ist, entspricht anderenfalls A).
  OLE	OLE-Zeichenfolge (entspricht W).

Um beispielsweise eine Unicode-Zeichenfolge in eine allgemeine Zeichenfolge zu konvertieren, ohne die konvertierte Zeichenfolge zu ändern, verwenden Sie CW2CT.

Wenn bekannt ist, dass die konvertierte Zeichenfolge sehr wahrscheinlich weniger als 64 Zeichen umfasst, kann die EX-Version wie z. B. CW2CTEX<64> verwendet werden, um Speicherplatz im Stapel zu sparen.

Die neuen Konvertierungsklassen, die einen Puffer benötigen (CA2AEX, CA2WEX, CW2AEX und CW2WEX), verwenden einen statischen Puffer mit einer festen Größe, um das Ergebnis der Konvertierung zu speichern. Wenn das Ergebnis zu groß ist, um in den statischen Puffer zu passen, weist die Klasse mittels malloc Arbeitsspeicher zu und gibt den Speicher wieder frei, wenn das Objekt sich nicht mehr im Gültigkeitsbereich befindet. Dadurch wird sichergestellt, dass, anders als bei älteren Textkonvertierungsmakros, diese Klassen auch sicher in Schleifen verwendet werden kann und nicht zu einem Stapelüberlauf führt.

Die in ATL 7.0 eingeführten Konvertierungsmakros wurden optimiert, um die NULL-Eingabezeichenfolgen zu berücksichtigen. Diese Makros geben NULL zurück, wenn der Eingabeparameter NULL ist, ohne Arbeitsspeicher zuzuweisen.

Standardmäßig verwenden die ATL-Konvertierungsklassen und -makros für die Konvertierung die ANSI-Codeseite des aktuellen Threads. Wenn Sie dieses Verhalten für eine spezifische Konvertierung mithilfe von Makros basierend auf der Klasse CA2WEX oder CW2AEX überschreiben möchten, geben Sie die Codeseite als zweiten Parameter für den Konstruktor der Klasse an.

Sicherheitshinweis
Prüfen Sie die Länge der Zeichenfolgen, bevor Sie sie an diese Makros übergeben, um mögliche Probleme durch einen Pufferüberlauf zu verhindern.Stapelüberläufe sind Ausnahmen, die auch mit try/except erfasst werden können.

Es gibt verschiedene wichtige Unterschiede zwischen den älteren Makros für die Zeichenfolgenkonvertierung und den neuen Klassen für die Zeichenfolgenkonvertierung:

Beispiel

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

Warnung hinsichtlich temporärer Klasseninstanzen

Bei dem Folgenden handelt es sich nicht um guten Code:

LPCTSTR szr = CA2T(szReplaceFile);

Bei ATL 3.0-Makros war die Nutzung von Folgendem akzeptabel:

LPCTSTR szr = A2T(szReplaceFile);   

, da der von den Konvertierungsfunktionen zugewiesene Arbeitsspeicher erst freigegeben werden würde, nachdem die aktuelle Funktion beendet wird. Der gleiche Code funktioniert nicht mit den neuen Klassen.

Dieser Code:

LPCTSTR szr = CA2T(szReplaceFile);   

entspricht:

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

Da der vom temporären Objekt zugewiesene und vom Umwandlungsoperator zurückgegebene Arbeitsspeicher zerstört wird, wenn das temporäre Objekt zerstört wird, führt die Nutzung des Werts in szr zu unerwünschten Ergebnissen.

Verwenden Sie stattdessen diesen Code:

CA2T szr(szReplaceFile);   

Der Umwandlungsoperator lässt das CA2T-Objekt wie einen LPCTSTR aussehen.

Erweiterte Nutzung

Die standardmäßige Größe des statischen Puffers ist 128 Zeichen. Wenn die Puffergröße für eine spezifische Konvertierung geändert werden muss, verwenden Sie die EX-Version eines Makros, und geben Sie die Puffergröße als Vorlagenargument an.

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

Im Folgenden finden Sie ein Beispiel für die Angabe der Codeseite als zweiten Parameter des Konstruktors für die Klasse.

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

ATL 3.0-Makros für die Zeichenfolgenkonvertierung

Die ursprünglichen Textkonvertierungsmakros sind weiterhin verfügbar und werden in der nachfolgenden Tabelle aufgelistet:

ATL 3.0-Makros für die Zeichenfolgenkonvertierung

Die Syntax für die Nutzung dieser Makros lautet folgendermaßen:

MACRONAME( string_address )

Beispiel:

A2W(lpa);

In den Makronamen befindet sich der Quellzeichenfolgentyp links (z. B. A) und der Zielzeichenfolgentyp rechts (z. B. W). A steht für LPSTR, OLE steht für LPOLESTR, T steht für LPTSTR und W steht für LPWSTR.

Wenn der Makroname ein C enthält, wird das Makro in eine const-Zeichenfolge konvertiert. Beispiel: W2CA konvertiert einen LPWSTR in einen LPCSTR.

Daher konvertiert A2W einen LPSTR in einen LPWSTR, OLE2T konvertiert einen LPOLESTR in einen LPTSTR usw.

Das Verhalten der ATL-Makros zur Zeichenfolgenkonvertierung ist von der geltenden Compiler-Diretive, sofern vorhanden, abhängig. Wenn die Quell- und Zieltypen gleich sind, findet keine Konvertierung statt. Mithilfe von Compiler-Direktiven werden T und OLE folgendermaßen geändert:

Die Zielzeichenfolge wird mithilfe von _alloca erstellt, es sei denn der Zieltyp ist ein BSTR. Bei _alloca wird Arbeitsspeicher vom Stapel zugewiesen, sodass er bei Rückgabe der Funktion automatisch bereinigt wird. Standardmäßig konvertiert dieses Makro nur bis zu 500 KB gleichzeitig.

Geben Sie bei Nutzung eines ATL-Makros zur Zeichenfolgenkonvertierung das Makro USES_CONVERSION zu Beginn Ihrer Funktion an, um Compiler-Fehler zu vermeiden. Beispiel:

void StringFunc(LPSTR lpsz)
{
   USES_CONVERSION;

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

Anforderungen

Headerdatei: AtlBase.h, AtlConv.h (deklariert in AtlConv.h)

Siehe auch

Referenz

DEVMODE and TEXTMETRIC String Conversion Macros

Weitere Ressourcen

ATL-Makros