Conventions pour les prototypes de fonctions

  • Article

Le Kit de développement logiciel (SDK) Windows fournit des prototypes de fonction dans les versions génériques, de page de codes Windows et d’Unicode . Les prototypes peuvent être compilés pour produire des prototypes de pages de codes Windows ou des prototypes Unicode. Les trois prototypes sont décrits dans cette rubrique et sont illustrés par des exemples de code pour la fonction SetWindowText .

Voici un exemple de prototype générique.

BOOL SetWindowText(
  HWND hwnd,
  LPCTSTR lpText
);

Le fichier d'en-tête fournit le nom de la fonction générique implémentée comme macro.

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

Le préprocesseur développe la macro dans la page de codes Windows ou le nom de la fonction Unicode. La lettre « A » (ANSI) ou « W » (Unicode) est ajoutée à la fin du nom de la fonction générique, le cas échéant. Le fichier d’en-tête fournit ensuite deux prototypes spécifiques, l’un pour les pages de codes Windows et l’autre pour Unicode, comme illustré dans les exemples suivants.

BOOL SetWindowTextA(
  HWND hwnd,
  LPCSTR lpText
);

BOOL SetWindowTextW(
  HWND hwnd,
  LPCWSTR lpText
);

Comme expliqué dans Types de données Windows pour les chaînes, le prototype de fonction générique utilise le type de données LPCTSTR pour le paramètre text. Toutefois, le prototype de page de codes Windows utilise le type LPCSTR, et le prototype Unicode utilise LPCWSTR.

Pour toutes les fonctions avec des arguments de texte, les applications doivent normalement utiliser les prototypes des fonctions génériques. Si une application définit « UNICODE » avant les instructions #include pour les fichiers d’en-tête ou pendant la compilation, les instructions sont compilées en fonctions Unicode.

Notes

Les nouvelles applications Windows doivent utiliser Unicode pour éviter les incohérences des pages de codes variées et faciliter la localisation. Ils doivent être écrits avec des fonctions génériques et doivent définir unicode pour compiler les fonctions en fonctions Unicode. Dans les quelques endroits où une application doit fonctionner avec des données de caractères 8 bits, elle peut utiliser explicitement les fonctions pour les pages de codes Windows.

 

Votre application doit toujours utiliser un prototype de fonction générique avec la chaîne et les types de caractères génériques. Tous les noms de fonctions qui se terminent par un « W » majuscule utilisent Unicode, c.-à-d. des paramètres à caractère large. Certaines fonctions existent uniquement dans les versions Unicode et peuvent être utilisées uniquement avec les types de données appropriés. Par exemple, LCIDToLocaleName et LocaleNameToLCID ont uniquement des versions Unicode.

La section Exigences de la documentation de référence pour chaque fonction Unicode et jeu de caractères fournit des informations sur les versions de fonction implémentées par les systèmes d’exploitation pris en charge. Si une ligne commençant par « Unicode » est incluse, la fonction a des versions de page de codes Unicode et Windows distinctes.

Notes

Lorsqu’une fonction a un paramètre de longueur pour une chaîne de caractères, la longueur doit être documentée sous la forme d’un nombre de valeurs TCHAR dans la chaîne. Ce type de données fait référence à des octets pour les versions de page de codes Windows de la fonction ou à des mots 16 bits pour les versions Unicode. Toutefois, les fonctions qui nécessitent ou retournent des pointeurs vers des blocs de mémoire non typés, comme la fonction GlobalAlloc , prennent généralement une taille en octets, quel que soit le prototype utilisé. Si l’allocation de mémoire non typée est destinée à une chaîne, l’application doit multiplier le nombre de caractères par sizeof(TCHAR). Pour plus d’informations, consultez Utilisation de types de données génériques.

 

Unicode dans l'API Windows