Convenzioni per prototipi di funzione

  • Articolo

Windows SDK fornisce prototipi di funzioni in versioni generiche, tabella codici di Windows e Unicode . I prototipi possono essere compilati per produrre prototipi della tabella codici di Windows o prototipi Unicode. Tutti e tre i prototipi sono descritti in questo argomento e sono illustrati dagli esempi di codice per la funzione SetWindowText .

Di seguito è riportato un esempio di prototipo generico:

BOOL SetWindowText(
  HWND hwnd,
  LPCTSTR lpText
);

Il file di intestazione fornisce il nome della funzione generica implementato come macro.

#ifdef UNICODE
#define SetWindowText SetWindowTextW
#else
#define SetWindowText SetWindowTextA
#endif // !UNICODE

Il preprocessore espande la macro nella tabella codici di Windows o nel nome della funzione Unicode. La lettera "A" (ANSI) o "W" (Unicode) viene aggiunta alla fine del nome della funzione generica, in base alle esigenze. Il file di intestazione fornisce quindi due prototipi specifici, uno per le tabelle codici di Windows e uno per Unicode, come illustrato negli esempi seguenti.

BOOL SetWindowTextA(
  HWND hwnd,
  LPCSTR lpText
);

BOOL SetWindowTextW(
  HWND hwnd,
  LPCWSTR lpText
);

Come illustrato in Tipi di dati Windows per stringhe, il prototipo di funzione generica usa il tipo di dati LPCTSTR per il parametro text. Tuttavia, il prototipo della tabella codici di Windows utilizza il tipo LPCSTR e il prototipo Unicode utilizza LPCWSTR.

Per tutte le funzioni con argomenti di testo, le applicazioni devono in genere utilizzare i prototipi di funzione generici. Se un'applicazione definisce "UNICODE" prima delle istruzioni #include per i file di intestazione o durante la compilazione, le istruzioni verranno compilate in funzioni Unicode.

Nota

Le nuove applicazioni Windows devono usare Unicode per evitare le incoerenze di tabelle codici diverse e per facilitare la localizzazione. Devono essere scritti con funzioni generica e devono definire UNICODE per compilare le funzioni in funzioni Unicode. Nei pochi punti in cui un'applicazione deve funzionare con i dati di tipo carattere a 8 bit, può usare esplicitamente le funzioni per le tabelle codici di Windows.

 

L'applicazione deve sempre utilizzare un prototipo di funzione generico con tipi di carattere e di stringa generici. Tutti i nomi di funzione che terminano con una "W" maiuscola accettano Unicode, ovvero parametri con caratteri wide. Alcune funzioni esistono solo nelle versioni Unicode e possono essere usate solo con i tipi di dati appropriati. Ad esempio, LCIDToLocaleName e LocaleNameToLCID hanno solo versioni Unicode.

La sezione Requisiti nella documentazione di riferimento per ogni funzione Unicode e set di caratteri fornisce informazioni sulle versioni delle funzioni implementate dai sistemi operativi supportati. Se viene inclusa una riga che inizia con "Unicode", la funzione include versioni separate della tabella codici Unicode e Windows.

Nota

Quando una funzione ha un parametro di lunghezza per una stringa di caratteri, la lunghezza deve essere documentata come conteggio dei valori TCHAR nella stringa. Questo tipo di dati fa riferimento ai byte per le versioni della tabella codici di Windows della funzione o parole a 16 bit per le versioni Unicode. Tuttavia, le funzioni che richiedono o restituiscono puntatori a blocchi di memoria non tipizzati, ad esempio la funzione GlobalAlloc , in genere accettano una dimensione in byte, indipendentemente dal prototipo usato. Se l'allocazione della memoria non tipificata è relativa a una stringa, l'applicazione deve moltiplicare il numero di caratteri per sizeof(TCHAR). Per altre informazioni, vedere Uso di tipi di dati generici.

 

Unicode nell'API Windows