"О чём не пишут в книгах по Delphi" - читать интересную книгу автора (Григорьев А. Б.)

1.1.2. Как получить справку по функциям Windows API

Для тех, кто решит работать с Windows API, самым необходимым инструментом становится какая-либо документация по этим функциям. Их так много, что запомнить все совершенно нереально, поэтому работа без справочника под рукой просто невозможна.

Первоисточник информации по технологиям Microsoft для разработчика Microsoft Developer's Network (MSDN). Это отдельная справочная система, не входящая в комплект поставки Delphi. MSDN можно приобрести отдельно или воспользоваться online-версией, находящейся по адресу: http://msdn.microsoft.com (доступ к информации свободный, регистрация не требуется). MSDN содержит не только информацию об API, но и все, что может потребоваться программисту, использующему различные средства разработки от Microsoft. Кроме справочного материала, MSDN включает в себя спецификации стандартов и технологий, связанных с Windows, статьи из журналов, посвященных программированию, главы из некоторых книг. И вся эта информация крайне полезна разработчику. Кроме того, MSDN постоянно обновляется, информация в нем наиболее актуальна. Пример справки из MSDN показан на рис. 1.1.

Рис. 1.1. Online-вариант MSDN (показана справка по функции DeleteObject)

В комплект поставки Delphi входит справочная система, содержащая описание функций Windows API. Справочная система в Delphi до 7-й версии включительно была построена на основе hlp-файлов. Применительно к справке по Windows API это порождало две проблемы. Во-первых, hlp-файлы имеют ограничение по числу разделов в справочной системе, поэтому объединить в одной справке информацию и по Delphi, и по Windows API было невозможно, — эти две справки приходилось читать по очереди. Чтобы открыть файл справки по Windows API, нужно было в редакторе кода поставить курсор на название какой-либо функции API и нажать клавишу lt;F1gt;— в этом случае вместо справки по Delphi открывалась справка по Windows API. Второй вариант — в меню Программы найти папку Delphi, а в ней — папку Help\MS SDK Files и выбрать требуемый раздел. Можно также вручную открыть файл MSTools.hlp. В ранних версиях Delphi он находится в каталоге $(Delphi)\Help, в более поздних его нужно искать в $(Program Files)\Common Files. Окно старой справки показано на рис. 1.2.

Вторая проблема, связанная со справкой на основе hlp-файлов,— это то обстоятельство, что разработчики Delphi, разумеется, не сами писали эту справку, а взяли ту, которую предоставила Microsoft. Microsoft же последнюю версию справки в формате НLР выпустила в тот момент, когда уже вышла Windows 95, но еще не было Windows NT 4. Поэтому про многие функции, прекрасно работающие в NT 4, там написано, что в Windows NT они не поддерживаются, т.к. в более ранних версиях они действительно не поддерживались. В справке, поставляемой с Delphi 7 (и, возможно, с некоторыми более ранними версиями), эта информация подправлена, но даже и там отсутствуют функции, которые появились только в Windows NT 4 (как, например, CoCreateInstanceEx). И уж конечно, бесполезно искать в этой справке информацию о функциях, появившихся в Windows 98, 2000, XР. Соответственно, при работе в этих версиях Delphi даже не возникает вопрос, что предпочесть для получения информации о Windows API, — справку, поставляемую с Delphi, или MSDN. Безусловно, следует выбрать MSDN. Справка, поставляемая с Delphi, имеет только одно преимущество по сравнению с MSDN: ее можно вызывать из среды нажатием клавиши lt;F1gt;. Но риск получить неверные сведения слишком велик, чтобы это преимущество могло быть серьезным аргументом. Единственная ситуация, когда предпочтительна справка, поставляемая с Delphi, — это случай, если у вас нет достаточно быстрого доступа к Интернету для работы с online-версией MSDN и нет возможности приобрести и установить его offline-версию.

Рис. 1.2. Старая (на основе hlp-файлов) справка по Windows API (показана функция DeleteObject)

Начиная с BDS 2006, Borland/CodeGear реализовала новую справочную систему Borland Help (рис. 1.3). По интерфейсу она очень напоминает offline версию MSDN, а также использует файлы в том же формате, поэтому технологических проблем интеграции справочных систем по Delphi и по Windows API больше не существует. В справку BDS 2006 интегрирована справка по Windows API от 2002–2003 годов (разные разделы имеют разную дату) Справка Delphi 2007 содержит сведения по Windows API от 2006 года, т.е. совсем новые. Таким образом, при работе с Delphi 2007 наконец-то можно полностью отказаться от offline-версии MSDN, а к online-версии обращаться лишь изредка, когда требуется информация о самых последних изменениях в Windows API (например, о тех, которые появились в Windows Vista).

Рис. 1.3. Окно справки Delphi 2007 (функция DeleteObject)

Система Windows написана на C++, поэтому все описания функций Windows API, а также примеры их использования приведены на этом языке (это касается как MSDN, так и справки, поставляемой с Delphi). При этом, прежде всего, необходимо разобраться с типами данных. Большинство типов, имеющихся в Windows API. определены в Delphi. Соответствие между ними показано в табл. 1.1.

Таблица 1.1. Соответствие типов Delphi системным типам

Название типов указателей имеет префикс P или LP (Pointer или Long Pointer, в 16-разрядных версиях Windows были короткие и длинные указатели. В 32-разрядных все указатели длинные, поэтому оба префикса имеют одинаковый смысл). Например, LPDWORD эквивалентен типу ^DWORD, PUCHAR — ^Byte. Иногда после префикса P или LP стоит еще префикс C — он означает, что это указатель на константу. В C++ возможно объявление таких указателей, которые указывают на константное содержимое, т.е. компилятор разрешает это содержимое читать, но не модифицировать. В Delphi такие указатели отсутствуют, и при портировании эти типы заменяются обычными указателями, т.е. префикс C игнорируется.

Типы PVOID и LPVOID соответствуют нетипизированным указателям (Pointer).

Для передачи символов чаще всего используется тип TCHAR. Windows поддерживает две кодировки: ANSI (1 байт на символ) и Unicode (2 байта на символ; о поддержке Unicode в Windows мы будем говорить далее). Тип CHAR соответствует символу в кодировке ANSI, WCHAR — Unicode. Для программ, которые используют ANSI, тип TCHAR эквивалентен типу CHAR, для использующих Unicode — WCHAR. В Delphi нет прямого аналога типу TCHAR. Программист сам должен следить за тем, какой символьный тип требуется в данном месте. Строки в Windows API передаются как указатели на цепочку символов, завершающихся нулем. Поэтому указатель на TCHAR может указывать как на единичный символ, так и на строку. Чтобы было легче разобраться, где какой указатель, в Windows API есть типы LPTCHAR и LPTSTR. Они эквивалентны друг другу, но первый принято использовать там, где требуется указатель на одиночный символ, а второй — на строку. Если строка передается в функцию только для чтения, обычно используют указатель на константу, т.е. тип LPCTSTR. В Delphi это соответствует PChar для ANSI и PWideChar для Unicode. Здесь следует отметить особенность записи строковых литералов в языках C/C++. Символ \ в литерале имеет специальное значение: после него идет один или несколько управляющих символов. Например, \n означает перевод строки, \t — символ табуляции и т.п. В Delphi таких последовательностей нет, поэтому при переводе примеров из MSDN следует явно писать коды соответствующих символов. Например, литерал "а\nb" в Delphi превращается в 'a\'#13'b'. После символа \ может идти число — в этом случае оно трактуется как код символа, т.е. литерал "a\0b9" в C/C++ эквивалентен литералу 'а'#0'b'#9 в Delphi. Если нужно, чтобы строковый литерал включал в себя сам символ \, его удваивают, т.е. литерал "\\" в C++ соответствует '\' в Delphi. Кроме того, в примерах кода, приведенных в MSDN, можно нередко увидеть, что строковые литералы обрабатываются макросами TEXT или _T, которые служат для унификации записи строковых литералов в кодировках ANSI и Unicode. При переводе такого кола на Delphi эти макросы можно просто опустить. С учетом сказанного такой, например, код (взят из примера использования Named pipes):

LPTSTR lpszPipename = TEXT("\\\\.\\pipe\\mynamedpipe");

на Delphi будет выглядеть так:

var

 lpszPipeName: PChar;

...

lpszPipeName:= '\\.\pipe\mynamedpipe';

Большинство названий типов из левой части табл. 1.1 в целях совместимости описаны в модуле Windows, поэтому они допустимы наравне с обычными типами Delphi. Кроме этих типов общего назначения существуют еще специальные. Например, дескриптор окна имеет тип HWND, первый параметр сообщения — тип WPARAM (в старых 16-разрядных Windows он был эквивалентен типу Word, в 32-разрядных — LongInt). Эти специальные типы также описаны в модуле Windows.

Записи (record) в C/C++ называются структурами и объявляются с помощью слова struct. Из-за особенностей описания структур на языке С структуры в Windows API получают два имени: одно основное имя, составленное из главных букв, которое затем и используется, и одно вспомогательное, получающееся из основного добавлением префикса tag. Начиная с четвертой версии Delphi приняты следующие правила именования таких типов: простое и вспомогательное имена остаются без изменений и еще добавляется новое имя, получающееся из основного присоединением общеупотребительного в Delphi префикса T. Например, в функции CreatePenIndirect одни из параметром имеет тип LOGPEN. Это основное имя данного типа, а вспомогательное — tagLOGPEN. Соответственно, в модуле Windows определена запись tagLOGPEN и ее синонимы — LOGPEN и TLogPen. Эти три идентификатора в Delphi взаимозаменяемы. Вспомогательное имя встречается редко, программисты, в зависимости от личных предпочтений, выбирают либо основное имя типа, либо имя с префиксом T.

Описанные здесь правила именования типов могут внести некоторую путаницу при использовании VCL. Например, для описания растра в Windows API определен тип BITMAP (он же— tagBITMAP). В Delphi соответствующий тип имеет еще одно имя — TBitmap. Но такое же имя имеет класс TBitmap, описанный в модуле Graphics. В коде, который Delphi создает автоматически, модуль Graphics находится в списке uses после модуля Windows, поэтому идентификатор TBitmap воспринимается компилятором как Graphics.TBitmap, а не как Windows.TBitmap. Чтобы использовать Windows.ТBitmap, нужно явно указать имя модуля или воспользоваться одним из альтернативных имен. В более ранних версиях Delphi были другие правила именования типов. Например. в Delphi 2 существовал тип BITMAP, но не было TBitmap и tagBITMAP, а в Delphi 3 из этих трех типов был только TBitmap.

Все структуры в Windows API описаны без выравнивания, т.е. компилятор не вставляет между полями неиспользуемые байты, чтобы границы полей приходились на начало двойного или четверного слова, поэтому в Delphi для описания соответствующих структур предусмотрено слово packed, запрещающее выравнивание.

При описании структур Windows API можно иногда встретить ключевое слово union (см., например, структуру in_addr). Объединение нескольких полей с помощью этого слова означает, что все они будут размещены по одному адресу. В Delphi это соответствует вариантным записям (т. е. использованию сазе в record). Объединения в C/C++ гибче, чем вариантные записи Delphi, т.к. позволяют размещать вариантную часть в любом месте структуры, а не только в конце. При переносе таких структур в Delphi иногда приходится вводить дополнительные типы.

Теперь рассмотрим синтаксис описания самой функции в C++ (листинг 1.1).

lt;Тип функцииgt; lt;Имя функцииgt; ' ('

 [lt;Тип параметраgt; {lt;Имя параметраgt;}

  (',' lt;Тип параметраgt; {lt;Имя параметраgt;} }

 ]

')';

Как видно из листинга 1.1, при объявлении функции существует возможность указывать только типы параметров и не указывать их имена. Однако это считается устаревшим и применяется крайне редко (если не считать "параметров" типа VOID, о которых написано далее).

Необходимо помнить, что в C/C++ различаются верхний и нижний регистры, поэтому HDC, hdc, hDC и т.д. — это разные идентификаторы (автор С очень любил краткость и хотел, чтобы можно было делать не 26, а 52 переменные с именем из одной буквы). Поэтому часто можно встретить, что имя параметра и его тип совпадают с точностью до регистра. К счастью, при описании функции в Delphi мы не обязаны сохранять имена параметров, значение имеют лишь их типы и порядок следования. С учетом всего этого функция, описанная в справке как

HMETAFILE CopyMetaFile(HMETAFILE hmfSrc, LPCTSTR lpszFile);

в Delphi имеет вид

function СоруМеtaFile(hnfSrc: HMETAFILE; lpszFile: LPCTSTR): HMETAFILE;

или, что то же самое.

function CopyMetaFile(hnfSrc: HMETAFILE; lpszFile: PChar): HMETAFILE;

Несколько особняком стоит тип VOID (или void, что то же самое, но в Windows API этот идентификатор встречается существенно реже). Если функции имеет такой тип, то в Паскале она описывается как процедура. Если вместо параметров у функции в скобках указан void, это означает, что функция не имеет параметров. Например, функция

VOID CloseLogFile(VOID);

в Delphi описывается как

procedure CloseLogFile;

Когда тип параметра является указателем на другой тип (обычно начинается с букв LP), при описании этой функции в Delphi можно пользоваться параметром-переменной, т.к. в этом случае функции передается указатель. Например, функция

int GetRgnBox(HRGN hrgn, LPRECT lprc);

в модуле Windows описана как

function GetRgnBox(RGN: HRGN; var p2: TRec): Integer;

Такая замена целесообразна в том случае, если значение параметра не может быть нулевым указателем, потому что при использовании var передать такой указатель будет невозможно. Нулевой указатель в C/C++ обозначается константой NULL. NULL и 0 в этих языках взаимозаменяемы, поэтому в справке можно и про целочисленный параметр встретить указание, что он может быть равен NULL.

И наконец, если не удается понять, как функция, описанная в справке, должна быть переведена на Паскаль, можно попытаться найти описание этой функции в исходных текстах модулей, поставляемых вместе с Delphi. Эти модули находятся в каталоге $(DELPHI)\Source\RTL\Win (до Delphi 7) или $(BDS)\Source\Win32\RTL\Win (BDS 2006 и выше). Можно также воспользоваться подсказкой, которая всплывает в редакторе Delphi после того, как будет набрано имя функции.

Если посмотреть справку, например, по функции GetSystemMetrics, то видно, что эта функция должна иметь один целочисленный параметр. Однако далее в справке предлагается при вызове этой функции подставлять в качестве параметра не числа, a SM_ARRANGE, SM_CLEANBOOT и т.д. Подобная ситуация и со многими другими функциями Windows API. Все эти SM_ARRANGE, SM_CLEANBOOT и т.д. являются именами числовых констант. Эти константы описаны в том же модуле, в котором описана функция, использующая их, поэтому можно не выяснять численные значения этих констант, а указывать при вызове функций их имена, например, GetSystemMetrics(SM_ARRANGE);. Если по каким-то причинам все-таки потребовалось выяснить численные значения, то в справочной системе их искать не стоит — их там нет. Их можно узнать из исходных текстов модулей Delphi, в которых эти константы описаны. Так, например, просматривая Windows.pas, можно узнать, что SM_ARRANGE = 56.

В справке, поставляемой вместе с Delphi до 7-й версии включительно, в описании многих функций Windows API вверху можно увидеть три ссылки: QuickInfo, Overview и Group. Первая дает краткую информацию о функции: какой библиотекой реализуется, в каких версиях Windows работает и т.п. (напоминаю, что к информации о версиях в этой справке нужно относиться очень критично). Overview — это обзор какой-то большой темы. Например, для любой функции, работающей с растровыми изображениями, обзор будет объяснять, зачем в принципе нужны эти самые растровые изображения и как они устроены. Страница, на которую ведет ссылка Overview обычно содержит весьма лаконичные сведения, но, нажав кнопку gt;gt;, расположенную в верхней части окна, можно получить продолжение обзора. И, наконец, Group. Эта ссылка приводит к списку всех функций, родственных данной. Например, для функции CreateRectRgn группу будут составлять все функции, имеющие отношение к регионам. Если теперь нажимать на кнопку lt;lt;, то будут появляться страницы с кратким описанием возможных применений объектов, с которыми работают функции (в приведенном примере — описание возможностей регионов). Чтобы читать их в нормальной последовательности, лучше всего нажать на кнопку lt;lt; столько раз, сколько возможно, а затем пойти в противоположном направлении с помощью кнопки gt;gt;.

MSDN (а также справка BDS 2006 и выше) предоставляет еще больше полезной информации. В нижней части описания каждой функции есть раздел Requirements, в котором написано, какая библиотека и какая версия Windows требуется для ее использования. В самом низу описания функции расположены ссылки See also. Первая ссылка — обзор соответствующей темы (например, для уже упоминавшейся функции CreateRectRgn — она называется Regions Overview). Вторая список родственных функций (Region Functions в данном случае). Она ведет на страницу, где перечислены все функции, родственные выбранной. После этих двух обязательных ссылок идут ссылки на описание функций и типов, которые обычно используются совместно с данной функцией.

Основные типы, константы и функции Windows API объявлены в модулях Windows и Messages. Но многие функции объявлены в других модулях, которые не подключаются к программе по умолчанию, программист должен сам выяснить, в каком модуле находится требуемый ему идентификатор, и подключить этот модуль. Ни справка, поставляемая с Delphi, ни MSDN, разумеется, не могут дать необходимую информацию. Чтобы выяснить, в каком модуле объявлен нужный идентификатор, можно воспользоваться поиском по всем файлам с расширением pas, находящимся в папке с исходными кодами стандартных модулей. Этим методом можно, например, выяснить, что весьма популярная функция ShellExecute находится в модуле ShellAPI, CoCreateInstance — в модуле ActiveX (а также в модуле Ole2, оставленном для совместимости со старыми версиями Delphi).

Еще несколько слов о числовых константах. В справке можно встретить числа вида, например, 0xC56F или 0x3341. Префикс 0х в C/C++ означает шестнадцатеричное число. В Delphi его следует заменить на $, т.е. эти числа должны быть записаны как $C56F и $3341 соответственно.