Правила обозначения прототипов функций

  • Статья

Windows SDK предоставляет прототипы функций в универсальных версиях, версиях кодовой страницы Windows и Юникода . Прототипы можно компилировать для создания прототипов кодовой страницы Windows или прототипов Юникода. Все три прототипа рассматриваются в этом разделе и проиллюстрированы примерами кода для функции SetWindowText .

Ниже приведен пример универсального прототипа.

BOOL SetWindowText(
  HWND hwnd,
  LPCTSTR lpText
);

Файл заголовка предоставляет универсальное имя функции, реализованное как макрос.

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

Препроцессор развертывает макрос на кодовую страницу Windows или имя функции Юникода. Буква "A" (ANSI) или "W" (Юникод) добавляется в конце имени универсальной функции, если это необходимо. Затем файл заголовка предоставляет два конкретных прототипа: один для кодовых страниц Windows и другой для Юникода, как показано в следующих примерах.

BOOL SetWindowTextA(
  HWND hwnd,
  LPCSTR lpText
);

BOOL SetWindowTextW(
  HWND hwnd,
  LPCWSTR lpText
);

Как описано в статье Типы данных Windows для строк, прототип универсальной функции использует тип данных LPCTSTR для текстового параметра. Однако прототип кодовой страницы Windows использует тип LPCSTR, а прототип Юникода — LPCWSTR.

Для всех функций с текстовыми аргументами приложения должны, как правило, использоваться универсальные прототипы функций. Если приложение определяет "ЮНИКОД" либо до #include инструкций для файлов заголовков, либо во время компиляции, инструкции будут скомпилированы в функции Юникода.

Примечание

Новые приложения Windows должны использовать Юникод, чтобы избежать несоответствий различных кодовых страниц и упростить локализацию. Они должны быть написаны с помощью универсальных функций и должны определять ЮНИКОД для компиляции функций в функции Юникода. В некоторых местах, где приложение должно работать с 8-разрядными символьными данными, оно может явно использовать функции для кодовых страниц Windows.

 

Приложение должно всегда использовать универсальный прототип функции с универсальными строковыми и символьными типами. Все имена функций, оканчивающиеся на заглавную «W», принимают параметры в Юникоде (расширенные символы). Некоторые функции существуют только в версиях Юникода и могут использоваться только с соответствующими типами данных. Например, LCIDToLocaleName и LocaleNameToLCID имеют только версии Юникода.

В разделе Requirements справочной документации по каждой функции Юникода и кодировки приведены сведения о версиях функций, реализованных поддерживаемыми операционными системами. Если включена строка, начинаемая с Юникода, функция имеет отдельные версии кодовой страницы в Юникоде и Windows.

Примечание

Если функция имеет параметр length для символьной строки, длина должна быть задокументирована как количество значений TCHAR в строке. Этот тип данных относится к байтам для версий кодовой страницы Windows функции или 16-разрядным словам для версий Юникода. Однако функции, которые требуют или возвращают указатели на нетипизированные блоки памяти, такие как функция GlobalAlloc , обычно принимают размер в байтах, независимо от используемого прототипа. Если выделение нетипизированной памяти предназначено для строки, приложение должно умножить число символов на sizeof(TCHAR). Дополнительные сведения см. в разделе Использование универсальных типов данных.

 

Юникод в Windows API