ATL and MFC String Conversion Macros
Le macro di conversione di stringhe presentate in questo argomento sono valide sia per ATL che per MFC. Per altre informazioni sulla conversione di stringhe MFC, vedere TN059: utilizzo di macro di conversione MFC MBCS/Unicode e Macro e funzioni globali MFC.
Classi e macro di conversione di stringhe ATL 7.0
Macro di conversione di stringhe ATL 3.0
Classi e macro di conversione di stringhe ATL 7.0
In ATL 7.0 sono state introdotte diverse nuove classi e macro di conversione, che offrono miglioramenti significativi rispetto alle macro esistenti.
I nomi delle nuove classi e macro di conversione di stringhe hanno il formato:
CSourceType2[C]DestinationType[EX]
dove:
SourceType e DestinationType vengono descritti nella tabella seguente.
[C] è presente quando il tipo di destinazione deve essere costante.
[EX] è presente quando la dimensione iniziale del buffer deve essere specificata come argomento del modello.
SourceType/DestinationType
Descrizione
A
Stringa di caratteri ANSI.
W
Stringa di caratteri Unicode.
T
Stringa di caratteri generici (equivalente a W quando _UNICODE è definito, equivalente a A negli altri casi).
OLE
Stringa di caratteri OLE (equivalente a W).
Ad esempio, per eseguire la conversione da una stringa Unicode a una stringa generica senza cambiare la stringa convertita, usare CW2CT.
Avviso
Alcune permutazioni dello schema elencate sopra non sono supportate.CA2CW e CW2CA (e CA2CWEX e CW2CAEX) non sono supportati.Per le conversioni di stringhe di caratteri OLE, sono supportati solo COLE2T e CT2OLE (e COLE2CT, COLE2TEX, COLE2CTEX, CT2COLE, CT2OLEEX e CT2COLEEX).Per informazioni dettagliate, vedere atlconv.h.
Se è noto che la stringa convertita probabilmente non supera i 64 caratteri, può essere usata la versione EX, ad esempio CW2CTEX<64>, per risparmiare spazio sullo stack.
Nota
Per la conversione verso e da stringhe BSTR, è consigliabile usare la classe CComBSTR.Per eseguire la conversione in BSTR, passare la stringa esistente al costruttore di CComBSTR.Per eseguire la conversione da BSTR, usare COLE2[C]DestinationType[EX], ad esempio COLE2T.
Le nuove classi di conversione che richiedono un buffer (CA2AEX, CA2WEX, CW2AEX e CW2WEX) usano un buffer statico di dimensione fissa per archiviare il risultato della conversione. Se il risultato è troppo grande per il buffer statico, la classe alloca memoria con malloc, liberando la memoria quando l'oggetto esce dall'ambito. Questo assicura che, diversamente dalle precedenti macro di conversione di testo, queste classi possono essere usate in sicurezza nei cicli e non eseguiranno l'overflow dello stack.
Le macro di conversione introdotte in ATL 7.0 sono ottimizzate per riconoscere le stringhe NULL di input. Queste macro restituiranno NULL se il parametro di input è NULL senza allocare memoria.
Per impostazione predefinita, le classi e le macro di conversione ATL useranno la tabella codici ANSI del thread corrente per la conversione. Per eseguire l'override di tale comportamento per una conversione specifica con macro basate sulle classi CA2WEX o CW2AEX, specificare la tabella codici come secondo parametro per il costruttore della classe.
.gif "Nota sulla sicurezza") Nota sulla sicurezza |
|---|
Controllare la lunghezza delle stringhe prima di passarle a queste macro per evitare potenziali problemi di sovraccarico del buffer.Gli overflow dello stack sono eccezioni che possono essere intercettate anche con try/except. |
Ci sono alcune importanti differenze tra le precedenti macro di conversione di stringhe e le nuove classi di conversione di stringhe:
Vecchie macro di conversione ATL 3.0 |
Nuove classi di conversione ATL 7.0 |
|---|---|
Alloca memoria nello stack. |
Usa la memoria dello stack per le stringhe piccole. Usa l'heap se lo stack non è abbastanza grande. |
La stringa viene liberata quando la funzione viene chiusa. |
La stringa viene liberata quando la variabile esce dall'ambito. |
Non può essere usata nei gestori di eccezioni. |
Può essere usata nei gestori di eccezioni. |
Non appropriata per l'uso nei cicli. L'uso della memoria aumenta fino all'uscita dalla funzione. |
Supporta l'uso nei cicli. L'ambito del ciclo assicura che la memoria venga liberata a ogni iterazione. |
Non appropriata per le stringhe grandi. Lo spazio dello stack è limitato. |
Nessun problema con le stringhe grandi. Le stringhe verranno allocate nell'heap. |
In genere è necessario definire USES_CONVERSION. |
Non è mai necessario definire USES_CONVERSION. |
Il significato di OLE dipende dalla definizione di OLE2ANSI. |
OLE è sempre equivalente a W. |
Esempio
Codice
//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);
}
Avviso relativo alle istanze di classi temporanee
Va sottolineato che il codice seguente non è valido:
LPCTSTR szr = CA2T(szReplaceFile);
Con le macro ATL 3.0, è accettabile usare:
LPCTSTR szr = A2T(szReplaceFile);
perché la memoria allocata dalle funzioni di conversione non verrà liberata fino all'uscita dalla funzione corrente. Lo stesso codice non funziona con le nuove classi.
Questo codice:
LPCTSTR szr = CA2T(szReplaceFile);
equivale a questo
LPCTSTR szr;
{
CA2T temp(szReplaceFile);
szr = temp.operator LPTSTR();
}
Mentre la memoria allocata dall'oggetto temporaneo e restituita dall'operatore di cast viene eliminata in modo permanente quando l'oggetto temporaneo viene eliminato in modo permanente, l'uso del valore in szr porterà a risultati indesiderati.
Usare invece il codice:
CA2T szr(szReplaceFile);
Con l'operatore di cast l'oggetto CA2T è simile a LPCTSTR.
Utilizzo avanzato
Le dimensioni del buffer statico predefinite sono di 128 caratteri. Se è necessario cambiare le dimensioni del buffer per una conversione specifica, usare la versione EX di una macro e specificare le dimensioni del buffer come argomento del modello.
// Example 4
// Changing the size of the buffer.
void ExampleFunction4(LPCWSTR pszW)
{
// Use a 16-character buffer.
ExampleFunctionA(CW2AEX<16>(pszW));
}
Ecco un esempio di come specificare la tabella codici come secondo parametro per il costruttore della classe.
// Example 5
// Specifying the code page.
void ExampleFunction5(LPCWSTR pszW)
{
// Convert to the Macintosh code page
ExampleFunctionA(CW2A(pszW, CP_MACCP));
}
Macro di conversione di stringhe ATL 3.0
Le macro di conversione di testo originali sono ancora disponibili e sono elencate nella tabella seguente:
Macro di conversione di stringhe ATL 3.0
A2BSTR |
OLE2A |
T2A |
W2A |
A2COLE |
OLE2BSTR |
T2BSTR |
W2BSTR |
A2CT |
OLE2CA |
T2CA (Deprecata. Usare invece T2CA_EX o CT2CA.) |
W2CA |
A2CW |
OLE2CT |
T2COLE |
W2COLE |
A2OLE |
OLE2CW |
T2CW |
W2CT |
A2T |
OLE2T |
T2OLE |
W2OLE |
A2W |
OLE2W |
T2W |
W2T |
La sintassi per l'uso di queste macro è la seguente:
MACRONAME( string_address )
Ad esempio:
A2W(lpa);
Nei nomi delle macro, il tipo di stringa di origine è a sinistra (ad esempio, A) e il tipo di stringa di destinazione è a destra (ad esempio, W). A sta per LPSTR, OLE sta per LPOLESTR, T sta per LPTSTR e W sta per LPWSTR.
Se nel nome della macro compare C, la macro esegue la conversione in una stringa const. Ad esempio, W2CA converte LPWSTR in LPCSTR.
Quindi, A2W converte LPSTR in LPWSTR, OLE2T converte LPOLESTR in LPTSTR e così via.
Il comportamento delle macro di conversione di stringhe ATL dipende da un'eventuale direttiva del compilatore attiva. Se i tipi di origine e di destinazione sono uguali, la conversione non viene eseguita. Le direttive del compilatore cambiano T e OLE come segue:
Direttiva del compilatore attiva |
T diventa |
OLE diventa |
|---|---|---|
Nessuna |
A |
W |
_UNICODE |
W |
W |
OLE2ANSI |
A |
A |
_UNICODE e OLE2ANSI |
W |
A |
La stringa di destinazione viene creata con _alloca, tranne quando il tipo di destinazione è BSTR. Con _alloca la memoria viene allocata fuori dallo stack e quindi, quando viene restituito il risultato della funzione, viene automaticamente cancellata. Per impostazione predefinita questa macro convertirà solo fino a 500 KB per volta.
Quando si usa una macro di conversione di stringhe ATL, specificare la macro USES_CONVERSION all'inizio della funzione per evitare errori del compilatore. Ad esempio:
void StringFunc(LPSTR lpsz)
{
USES_CONVERSION;
LPWSTR x = A2W(lpsz);
// Do something with x
wprintf_s(L"x is %s", x);
}
Requisiti
File di intestazione: AtlBase.h, AtlConv.h (dichiarato in AtlConv.h)
Vedere anche
Riferimenti
DEVMODE and TEXTMETRIC String Conversion Macros