ATL und Makros für MFC-Zeichenfolgenkonvertierung

Die Makros für Zeichenfolgenkonvertierung, die hier erläutert werden, sind für ATL und MFC gültig.Weitere Informationen zu MFC-Zeichenfolgenkonvertierung, finden Sie unter TN059: Verwenden der Konvertierungs-Makros MFC MBCS/Unicode und MFC-Makros und -globale Werte.

• ATL 7.0-Zeichenkonvertierungs-Klassen und Makros

• ATL 3.0-Makros für Zeichenfolgenkonvertierung

ATL 7.0-Zeichenkonvertierungs-Klassen und Makros

ATL 7.0 stellt mehrere neue Konvertierungsklassen und Makros vor und bietet erhebliche Verbesserungen über den vorhandenen Makros bereit.

Die Namen der neuen Zeichenkonvertierungsklassen und Makros nehmen die Form:

CSourceType2[C]DestinationType[EX]

Dabei gilt:

• SourceType und DestinationType sind in der folgenden Tabelle beschrieben.

• [C] ist vorhanden, wenn der Zieltyp konstant sein muss.

• [EX] ist vorhanden, wenn die ursprüngliche Größe des Puffers als Vorlagenargument angegeben werden muss.

  SourceType/DestinationType	Description
  A	ANSI-Zeichen-Zeichenkette.
  W	Unicode-Zeichenfolge.
  T	Generische Zeichenfolge (entspricht W, wenn _UNICODE definiert ist, entspricht einem andernfalls).
  OLE	OLE-Zeichenfolge (entspricht W).

Von einer Unicode-Zeichenfolge konvertieren zu einer generischen Zeichenfolge, ohne die konvertierte Zeichenfolge zu ändern, verwenden Sie CW2CT.

Wenn es bekannt ist, dass die konvertierte Zeichenfolge zu erwarten ist, mehr als 64 Zeichen sein, kann die EX-Version, wie CW2CTEX<64>, verwendet werden, um Platz auf dem Stapel zu speichern.

Hinweis
Die empfohlene Möglichkeit zur Konvertierung in und aus BSTR-Zeichenfolgen ist, die CComBSTR-Klasse zu verwenden.Um ein BSTR zu konvertieren, übergeben Sie die vorhandene Zeichenfolge an den Konstruktor von CComBSTR. Um von einem BSTR zu konvertieren, verwenden Sie COLE2[C]DestinationType[EX], beispielsweise COLE2T.

Die neuen Konvertierungsklassen, die eine Verwendung des Puffers (CA2AEX, CA2WEX, CW2AEX, und CW2WEX) ein statischer Puffer fester Größe benötigen, das Ergebnis der Konvertierung zu speichern.Wenn das Ergebnis zu groß ist, in den statischen Puffer passt, belegt die Klasse mithilfe malloc Speicher und gibt den Arbeitsspeicher frei, wenn das Objekt den Gültigkeitsbereich verlässt.Dadurch wird sichergestellt, dass, anders als die älteren Textkonvertierungsmakros, diese Klassen sicher, in Schleifen zu verwenden sind und nicht der Hookfunktion werden.

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

Standardmäßig verwenden die ATL-Konvertierungsklassen und Makros die aktuelle ANSI-Codepage des Threads für die Konvertierung.Wenn Sie dieses Verhalten für eine bestimmte Konvertierung mithilfe der Makros auf Grundlage der Klassen CA2WEX oder CW2AEX überschreiben möchten, geben Sie die Codepage als zweiten Parameter an den Konstruktor für die Klasse.

Sicherheitshinweis
Überprüfen Sie die Länge der Zeichenfolgen, bevor Sie sie diesen Makros übergeben, um mögliche Pufferüberlaufprobleme zu vermeiden.Stapelüberläufe sind Ausnahmen, die mit Versuch/außer auch abgefangen werden können.

Es gibt einige wichtige Unterschiede zwischen den älteren Makros Zeichenfolgenkonvertierung für und den neuen Zeichenkonvertierungsklassen:

Die alten ATL 3.0-Konvertierungs-Makros	Neue ATL 7.0-Konvertierungs-Klassen
Belegt Speicher für den Stapel.	Verwendungsstapelarbeitsspeicher für kleine Zeichenfolgen.Verwendet den Heap, wenn der Stapel nicht groß genug ist.
Die Zeichenfolge wird aufgehoben, wenn die Funktion beendet wird.	Die Zeichenfolge wird aufgehoben, wenn die Variable den Gültigkeitsbereich verlässt.
Kann nicht in den Ausnahmehandlern verwendet werden.	Kann in den Ausnahmehandlern verwendet werden.
Nicht geeignet für die Verwendung in Schleifen.Arbeitsspeicherverwendung vergrößert, bis die Funktion abgeschlossen ist.	Unterstützung verwendet in Schleifen.Schleifenbereich wird sichergestellt, dass Arbeitsspeicher in jeder Iteration freigegeben wird.
Nicht gut für umfangreiche Zeichenfolgen.Stapelspeicher ist eingeschränkt.	Keine Probleme mit großen Zeichenfolgen.Zeichenfolgen werden auf dem Heap zugeordnet.
Benötigen Sie normalerweise USES_CONVERSION definiert werden.	Benötigen Sie nie USES_CONVERSION definiert werden.
Bedeutung von OLE hängt von der Definition von OLE2ANSI ab.	OLE ist immer mit W entsprechend.

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

Eine Warnung bezüglich temporäre Klasseninstanzen

Es sollte belastet werden, dass das folgende nicht guter Code ist:

LPCTSTR szr = CA2T(szReplaceFile);

Verwenden 3.0-Makros ATL verwenden war zulässig:

LPCTSTR szr = A2T(szReplaceFile);   

seit dem Arbeitsspeicher, der durch die Konvertierungsfunktionen zugeordnet wurde, nicht freigegeben wird, bis die aktuelle Funktion beendet war.Der gleiche Code funktioniert nicht mit den neuen Klassen.

Dieser Code:

LPCTSTR szr = CA2T(szReplaceFile);   

entspricht der Folgenden:

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

Wenn der Arbeitsspeicher, der durch das temporäre Objekt zugeordnet und wird vom Umwandlungsoperator zurückgegeben wird, wird, wenn das temporäre Objekt zerstört wird, mit dem Wert in szr hat unerwünschte Ergebnisse zerstört.

Stattdessen verwenden Sie diesen Code:

CA2T szr(szReplaceFile);   

Der Umwandlungsoperator können das CA2T-Objekt wie LPCTSTR aussehen.

Erweiterte Verwendung

Die standardmäßige statische Puffergröße ist 128 Zeichen.Wenn die Puffergröße für eine bestimmte 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 ein Beispiel zum Angeben der Codepage als zweiten Parameter an den Konstruktor 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 Zeichenfolgenkonvertierung

Die Originaltextkonvertierungsmakros sind weiterhin verfügbar und werden in der folgenden Tabelle aufgelistet:

ATL 3.0-Makros für Zeichenfolgenkonvertierung

A2BSTR	OLE2A	T2A	W2A
A2COLE	OLE2BSTR	T2BSTR	W2BSTR
A2CT	OLE2CA	T2CA (veraltet.Verwendung T2CA_EX oder CT2CA stattdessen.)	W2CA
A2CW	OLE2CT	T2COLE	W2COLE
A2OLE	OLE2CW	T2CW	W2CT
A2T	OLE2T	T2OLE	W2OLE
A2W	OLE2W	T2W	W2T

Die Syntax für die Verwendung dieser Makros ist, wie folgt:

MACRONAME( string_address )

Beispiel:

A2W(lpa);

In den Makronamen ist der Quellzeichenfolgentyp links (beispielsweise, A) und der Zielzeichenfolgentyp ist auf der rechten Seite (beispielsweise, W).A wird für LPSTR, wird OLE für LPOLESTR, wird T für LPTSTR und W Stände für LPWSTR.

Wenn es C im Makronamen gibt, die Makrobekehrten zu einer const Zeichenfolge.Beispielsweise konvertiert W2CALPWSTR zu LPCSTR.

Somit konvertiert A2WLPSTR zu LPWSTR, OLE2T konvertiert LPOLESTR zu LPTSTR, u. a.

Das Verhalten der Makros für ATL-Zeichenfolgenkonvertierung hängt von den Compilerdirektiven gültig, wenn eine ab.Wenn Quelle und die Zieltypen identisch sind, findet keine Konvertierung statt.Compilerdirektivenänderung T und OLE, wie folgt:

Compilerdirektiven wirksam	T wird	OLE wird
Kein	A	W
_UNICODE	W	W
OLE2ANSI	A	A
_UNICODE und OLE2ANSI	W	A

Die Zielzeichenfolge wird mithilfe von _alloca, außer erstellt, wenn der Zieltyp BSTR ist.Verwenden des _belegt alloca vom Stapel auf Speicher, damit, wenn die Funktion zurückgibt, sie automatisch bereinigt wird.Standardmäßig konvertiert dieses Makro nur bis zu 500KB gleichzeitig.

Wenn Sie ein Makro für ATL-Zeichenfolgenkonvertierung verwenden, geben Sie die USES_CONVERSION-Makro am Anfang der Funktion an, um Compilerfehler 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

Header file: AtlBase.h, AtlConv.h (deklariert in AtlConv.h)

Siehe auch

Referenz

DEVMODE- und TEXTMETRIC-Makros für Zeichenfolgenkonvertierung

Weitere Ressourcen

ATL-Makros