Freigeben über

ATL and MFC String Conversion Macros

  • Artikel

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.

Warnung

Einige der Permutationen des oben genannten Musters werden nicht unterstützt.CA2CW und CW2CA (und CA2CWEX und CW2CAEX) werden nicht unterstützt.Für OLE-Zeichenfolgenkonvertierungen werden nur COLE2T und CT2OLE (und COLE2CT, COLE2TEX, COLE2CTEX, CT2COLE, CT2OLEEX und CT2COLEEX) unterstützt.Einzelheiten finden Sie unter atlconv.h.

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.

Hinweis

Die empfohlene Methode, um BSTR-Zeichenfolgen zu konvertieren (beide Richtungen), besteht darin, die CComBSTR-Klasse zu verwenden.Übergeben Sie die bestehende Zeichenfolge an den Konstruktor von CComBSTR, um in einen BSTR zu konvertieren.Verwenden Sie COLE2[C]DestinationType[EX], wie z. B. COLE2T, um aus einem BSTR zu konvertieren.

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.

SicherheitshinweisSicherheitshinweis

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:

Alte ATL 3.0-Konvertierungsmakros

Neue ATL 7.0-Konvertierungsklassen

Belegt Speicher für den Stapel.

Verwendet für kurze Zeichenfolgen Stapelspeicher. Verwendet den Heap, wenn der Stapel nicht groß genug ist.

Die Zeichenfolge wird freigegeben, wenn die Funktion beendet wird.

Die Zeichenfolge wird freigegeben, wenn diese Variable den Gültigkeitsbereich verlässt.

Kann nicht in Ausnahmehandlern verwendet werden.

Kann in Ausnahmehandlern verwendet werden.

Nicht für den Gebrauch in Schleifen geeignet. Speichernutzung wächst, bis die Funktion beendet wird.

Unterstützt die Nutzung in Schleifen. Schleifenbereich sorgt dafür, dass bei jeder Iteration Speicher freigegeben wird.

Nicht geeignet für lange Zeichenfolgen. Stapelspeicherplatz ist begrenzt.

Keine Probleme mit langen Zeichenfolgen. Zeichenfolgen werden auf dem Heap zugeordnet.

USES_CONVERSION muss in der Regel definiert sein.

USES_CONVERSION muss niemals definiert sein.

Bedeutung von OLE ist von der Definition von OLE2ANSI abhängig.

OLE entspricht immer W.

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

A2BSTR

OLE2A

T2A

W2A

A2COLE

OLE2BSTR

T2BSTR

W2BSTR

A2CT

OLE2CA

T2CA (Veraltet. Verwenden Sie stattdessen T2CA_EX oder CT2CA.)

W2CA

A2CW

OLE2CT

T2COLE

W2COLE

A2OLE

OLE2CW

T2CW

W2CT

A2T

OLE2T

T2OLE

W2OLE

A2W

OLE2W

T2W

W2T

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:

Geltende Compiler-Direktive

T wird zu

OLE wird zu

Keine

A

W

_UNICODE

W

W

OLE2ANSI

A

A

_UNICODE und OLE2ANSI

W

A

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