Первая программа на WinAPI

WinAPI или Windows API (Application Programming Interface) — это библиотека для создания классических приложений Windows. Сама библиотека WinAPI написана на языке C и представляет собой коллекцию функций, структур и констант. Она объявлена в определённых заголовочных файлах и реализована в статических (.lib) и динамических (.dll) библиотеках.

В данном уроке мы создадим нашу первую программу на WinAPI. Для начала создайте проект. Выберите меню File -> New -> Project:

В открытом окне в левой панели выберите Other, затем Empty Project (пустой проект). Там же доступен шаблон Windows Desktop Application, но мы напишем программу с нуля, так как шаблон по умолчанию пока слишком сложен для нас. В нижней части выберите имя проекта, его местоположение и хотите ли вы создать решение для него. Местоположение может быть любым, для меня это C:\prog\cpp\

В обозревателе решений щёлкните правой кнопкой мышки и выберите Add -> New Item.

В открывшемся окне выберите C++ File (.cpp) и введите имя файла в нижней части — main.cpp.

Перед тем как мы начнём рассматривать код, давайте поговорим о типах данных в WinAPI и соглашениях вызова (calling conventions).

Типы данных в WinAPI

WinAPI переопределяет множество стандартных типов языка C. Некоторые переопределения зависят от платформы для которой создаётся программа. Например, тип LRESULT, если его скомпилировать для x86, будет типом long. Но если скомпилировать программу для x64, то LRESULT будет типом __int64. Вот так LRESULT определяется на самом деле (он зависит от LONG_PTR, а LONG_PTR может уже быть или __int64, или long):

Соглашения по вызову (Calling Conventions) — __stdcall

В коде ниже перед именами функций вы встретите __stdcall. Это одно из соглашений по вызову функций. Соглашение по вызову функций определяет каким образом аргументы будут добавляться в стек. Для __stdcall аргументы помещаются в стек в обратном порядке — справа налево. Также, __stdcall говорит, что после того как функция завершится, она сама (а не вызывающая функция) удалит свои аргументы из стека. Все функции WinAPI используют __stdcall соглашение.

WinAPI переопределяет __stdcall в WINAPI, CALLBACK или APIENTRY, которые используются в разных ситуациях. Поэтому в примерах из MSDN вы не увидите __stdcall, но нужно помнить что именно оно будет использоваться.

Типы WinAPI пишутся в верхнем регистре.

Описатели/дескрипторы (Handles) в WinAPI

Handle на русский язык сложно перевести однозначно. Наверное, наиболее частое употребление в русском имеет слово дескриптор. По сути это ссылка на ресурс в памяти. Например, вы создаёте окно. Это окно хранится в памяти и оно имеет запись в таблице, которая хранит указатели на все созданные системные ресурсы: окна, шрифты, файлы, картинки. Указатель на ваше окно в данной таблице называется дескриптором окна (handle of the window).

Любой указатель это просто переопределение типа void*. Примеры дескрипторных типов в WinAPI: HWND, HINSTANCE, HBITMAP, HCURSOR, HFILE, HMENU.

Подытожим: дескрипторы используются для получения доступа к каким-либо системным ресурсам.

WinAPI окна

Давайте посмотрим на код самой простой WinAPI программы:

Вначале нужно добавить WinAPI: статичную библиотеку, которая содержит определения различных функций и включить заголовочный файл с объявлениями этих функций, структур и констант. user32.lib содержит основные возможности Windows — всё, что касается окон и обработки событий.

На следующей строке мы объявляем функцию обратного вызова (callback), которая будет вызываться, когда наше приложение получает какое-либо сообщение от операционной системы. Мы вернёмся к этому ниже.

Функция WinMain

WinMain — точка входа в программу, а как мы помним такая функция вызывается операционной системой.

Главная функция приложений под Windows отличается от консольной версии. Она возвращает целое число и это всегда ноль. __sdtcall говорит, что аргументы добавляются в стек в обратном порядке и WinMain сама удаляет их из стека по завершении. WinMain принимает 4 аргумента:

hInstance — дескриптор экземпляра приложения. Можете думать о нём, как о представлении вашего приложения в памяти. Он используется для создания окон.

Второй аргумент — наследие шестнадцатибитных версий Windows. Уже давно не используется.

Третий аргумент представляет аргументы командной строки. Пока мы не будем им пользоваться.

nCmdShow — специальный флаг, который можно использовать при создании окон. Он говорит о состоянии окна: должно ли оно показываться нормально, на полный экран или быть свёрнутым.

Теперь давайте посмотрим как создаются окна.

Классы окон (Window Classes)

Для создания окна нужно определить и зарегистрировать его класс. Windows создаёт свои классы таким же образом. Все стандартные элементы, которые вы видите в Windows являются классами: кнопки, поля редактирования, полосы прокрутки. Windows хранит список всех зарегистрированных классов. Обязательно нужно заполнить только три поля класса: имя класса, дескриптор экземпляра приложения (передаётся в WinAPI в виде параметра) и оконная процедура (адрес функции).

Сначала нужно заполнить структуру WNDCLASS. Пусть вас не смущает название WNDCLASS — это не C++ класс. В данном случае, класс — всего лишь термин используемый в WinAPI:

Здесь мы инициализируем структуру WNDCLASS нулями, определяем обязательные поля и регистрируем класс.

lpfnWndProc имеет тип WNDPROC. Как говорилось выше, это указатель на функцию WindowProc, которую мы объявили в самом начале. У каждого оконного класса должна быть своя оконная процедура.

hInstance — дескриптор экземпляра приложения. Все оконные классы должны сообщать, какое приложение их зарегистрировало. Мы используем первый параметр функции WinMain.

lpszClassName — имя класса, задаётся пользователем. В Windows все классы называются в верхнем регистре (примеры: BUTTON, EDIT, LISTBOX), мы будем делать также в наших уроках.

WNDCLASS содержит больше полей: стиль, иконка, имя меню, но мы можем пропустить их. Некоторые из них мы рассмотрим в следующих уроках. Вы можете посмотреть полный список в документации к WinAPI на MSDN (официальном сайте Microsoft с документацией).

В конце мы регистрируем наш класс с помощью функции RegisterClass. Мы передаём адрес структуры WNDCLASS. Теперь мы можем создать окно.

Первая WinAPI программа — Пустое окно

В WinAPI есть функция для создания окон — CreateWindow:

Первый параметр — имя класса. В данном случае он совпадает с именем класса, который мы зарегистрировали. Второй — имя окна, это та строка, которую пользователи программы будут видеть в заголовке. Следующий — стиль. WS_OVERLAPPEDWINDOW говорит, что WinAPI окно имеет заголовок (caption), кнопки сворачивания и разворачивания, системное меню и рамку.

Четыре числа определяют позицию левого верхнего угла окна и ширину/высоту.

Затем идут два указателя nullptr. Первый — дескриптор родительского окна, второй — меню. У нашего окна нет ни того, ни другого.

hInstance — дескриптор на экземпляр приложения, с которым связано окно.

В последний аргумент мы передаём nullptr. Он используется для специальных случаев — MDI (Multiple Document Interface ) — окно в окне.

CreateWindow возвращает дескриптор окна. Мы можем использовать его для обращения к окну в коде. Теперь мы можем показать и обновить окно.:

ShowWindow (показать окно) использует параметр nCmdShow функции WinMain для контроля начального состояния (развёрнуто на весь экран, минимизировано, обычный размер). UpdateWindow (обновить окно) мы обсудим в следующих уроках.

Главный цикл WinAPI

Далее идёт бесконечный цикл. В этом цикле мы будем реагировать на разные события, возникающие при взаимодействии пользователя с нашей программой.

Перед циклом мы объявляем переменную типа MSG (от message — сообщение) — в этой структуре Windows кодирует события. Если произошло событие WM_QUIT, то мы завершаем цикл.

Операционная система генерирует множество различных сообщений. Они генерируются, когда происходит какое-то событие: изменился размер окна, нажата клавиша мышки или клавиатуры.

Очередь сообщений (Message Queue) в WinAPI

Все оконные приложения управляются событиями (event-driven). В операционной системе существует очередь сообщений. Когда происходит какое-либо событие в любой программе, в эту очередь посылается сообщение. Также, любая программа имеет свою очередь сообщений. Windows проверяет каждое сообщение в системной очереди и посылает их в программные очереди. В действительности всё немного сложнее, так как очереди сообщений связаны с потоками, но мы обсудим это позже. На данный момент запомните, что каждое приложение имеет свою собственную очередь сообщений.

Сообщение это просто структурная переменная MSG. Давайте посмотрим на определение этой структуры:

hwnd — дескриптор окна, которому принадлежит сообщение.

message — идентификатор сообщения (UINT — unsigned integer).

wParam и lParam содержат дополнительную информацию и зависят от идентификатора сообщения.

time — понятно из названия — время, когда было создано сообщение.

pt — позиция курсора на экране в момент генерации сообщения. POINT — тип WinAPI для описания точек с координатами (x,y).

Приложение в бесконечном цикле проверяет свою очередь сообщений, смотрит на свойство message и решает, что делать с данным сообщением (как его обработать).

Функция PeekMessage проверяет очередь и берёт последнее сообщение. Затем, она берёт информацию о сообщении и помещает её в переменную msg. Последний аргумент заставляет удалить сообщение из очереди.Итак, в условии мы проверяем, содержит ли очередь сообщений приложения какое-либо сообщение. Если содержит, мы заполняем переменную msg и удаляем сообщение из очереди. Затем вызываем две функции.

TranslateMessage — генерирует дополнительное сообщение если произошёл ввод с клавиатуры (клавиша с символом была нажата или отпущена). По умолчанию, клавиатура генерирует так называемые сообщения виртуального ключа (virtual key). TranslateMessage генерирует ещё одно сообщение, которое сообщает информацию о символе. Мы поговорим об этом позже. Пока что: вызов TranslationMessage нужен, чтобы обработать ввод символов с клавиатуры.

Функция DispatchMessage посылает сообщение в функцию WindowProc.

Оконная процедура (Window Procedure) WindowProc

Оконная процедура — это специальная функция в которой мы обрабатываем сообщения. В данный момент нам нужно обработать только одно важное сообщение, а для всех остальных выполнить стандартное действие. Давайте посмотрим на наш вариант WindowProc:

Обратите внимание, что мы сами нигде не вызываем WindowProc. Оконная процедура привязана к классу окна. И когда мы вызываем DispatchMessage, система сама вызывает оконную процедуру, связанную с окном. Такие функции называются функциями обратного вызова (callback functions) — они не вызываются напрямую. Также обратите внимание, что данная функция получает только часть свойств MSG структуры.

Внутри WindowProc мы проверяем поле message структуры MSG. Оно содержит идентификатор сообщения. В Windows определено много констант для разных сообщений. В данной программе мы проверяем WM_DESTROY. Это сообщение посылается, когда окно уничтожается, в момент, когда оно уже удалено с экрана. В ответ на это сообщение мы вызываем PostQuitMessage — она говорит системе, что приложение будет закрыто и посылает сообщение WM_QUIT в очередь сообщений программы (не в системную).

Если пришло сообщение, которое мы не хотим обрабатывать сами, мы передаём его в DefWindowProc — действие по умолчанию.

Заключение

В данном уроке мы создали пустое но полностью функциональное стандартное окно операционной системы Windows. В следующих уроках мы обсудим разные части WinAPI, а шаблон из данного урока станет основой для наших программ на DirectX и OpenGL.

Введение в Windows API

API (Application Programming Interface) — это интерфейс программирования приложений, термин, часто упоминаемый разработчиками программного обеспечения. Если разрабатываемое вами приложение имеет функцию, позволяющую обращаться к нему из других приложений, то это — API вашего приложения. Параметры, которые принимает ваша функция, образуют её API, так как они являются средством, при помощи которого другие приложения взаимодействуют с данной функцией.

Операционная система Windows предоставляет большой набор функций, позволяющих различным приложениям, в том числе и приложениям Visual FoxPro, обмениваться информацией с Windows на достаточно низком уровне. Эти функции принято называть Windows API. Использование Windows API в приложениях Visual FoxPro позволяет реализовать возможности, недостижимые стандартными средствами языка.

Объявление Windows API функций в Visual FoxPro

Функции Windows API скомпонованы в динамически связанные библиотеки (Dynamic Link Library, DLL). Как правило, файлы таких библиотек имеют расширение dll. Перед тем, как использовать Windows API функцию в вашем приложении, вы должны её объявить. Для объявления функции применяется команда DECLARE..DLL:

cFunctionType
необязательный параметр, указывает тип данных, возвращаемых функцией:

cFunctionType	Размер, байт	Описание
Short	16-ти разрядное целое число
Integer, Long	4	32-х разрядное целое число
Single	4	32-х разрядное вещественное число
Double	8	64-х разрядное вещественное число
String	—	Строка символов

FunctionName
имя функции в DLL-библиотеке. Имя функции чувствительно к регистру символов, то есть GetDC и GETDC — это имена совершенно разных функций.

LibraryName
наименование DLL-библиотеки, в которой находится функция. Для библиотек Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll и Advapi32.dll можно использовать синоним WIN32API.

AliasName
необязательный параметр, позволяет вместо имени функции использовать придуманный вами псевдоним. Написание псевдонима, в отличие от имени функции, не чувствительно к регистру символов. Как правило, псевдоним используется, когда имя API функции совпадает с именем встроенной (или вашей) функции Visual FoxPro.

cParamType
указывает тип данных передаваемого функции значения:

cParamType	Размер, байт	Описание
Integer, Long	4	32-х разрядное целое число
Single	4	32-х разрядное вещественное число
Double	8	64-х разрядное вещественное число
String	—	Строка символов

Параметр может передаваться как по значению, так и по ссылке. Для указания того, что параметр передаётся по ссылке, используется символ «@».

С точки зрения Visual FoxPro не существует никакой разницы между типами данных Long и Integer. Обычно тип Integer применяется для обозначения целых чисел со знаком, а тип Long — целых чисел без знака.

ParamName
необязательный параметр, носит чисто описательный характер и, как правило, игнорируется.

Все функции Windows API, как, впрочем, и сама Windows, написаны на языке программирования Си. Поэтому для того, чтобы понять, как правильно использовать API функции в Visual FoxPro (который, кстати, так же написан на Си, по крайней мере, его ядро), познакомимся, какие типы данных применяются в Си и Windows, и, что не менее важно, разберёмся с такими типами данных, как перечисления, структуры и указатели. Кроме того, вы узнаете, что такое прототипы функций в Си, и как, основываясь на описании прототипа функции в MSDN, правильно объявить её в команде DECLARE..DLL.

Базовые типы данных Си

Если вы знакомы с языком программирования Си, то знаете, как легко в нём можно создавать различные типы данных. Достаточно написать следующий код:

и вот у вас новый тип INT32, который полностью соответствует типу int. Но, с точки зрения Си, это совершенно разные типы, и попытка присвоить переменной типа INT32 значение переменной типа int приведёт к ошибке!

Изобилие типов данных заставляет многих разработчиков думать, что программирование с использованием API является трудным. Но это не так! В Си в основном используются следующие типы данных:

тип char — символ в формате ANSI. Имеет длину 8 разрядов (один байт).

тип wchar — символ в формате Unicode. Имеет длину 16 разрядов (два байта).

тип int — целые числа. Они делятся в Си на три типа: int, short int и long int. Последние обычно сокращаются до short и long. Тип short — это 16-ти разрядное, а типы int и long — 32-х разрядные целые числа.

тип float — вещественные числа, имеющие дробную часть. Имеют длину 32 разряда (4 байта).

тип double — вещественные числа двойной точности. Имеют длину 64 разряда (8 байт).

тип enum — перечисляемый тип данных.

тип void используется для обозначения величин, имеющих нулевую длину и не имеющих значения.

тип pointer — указатель; он не содержит информацию в общепринятом смысле — как другие типы Си; вместо этого, в каждом указателе находится адрес ячейки памяти, где хранятся реальные данные. Имеет длину 32 разряда (4 байта).

Как ни странно, строковый тип в Си отсутствует. На самом деле все строки представлены в Си как массивы символов.

Некоторые типы могут объявляться как беззнаковые. Модификатор unsigned (без знака) используется со следующими типами данных: char, short, int и long.

Например, следующее объявление переменной в Си:

означает, что эта переменная — целое 32-х разрядное целое без знака.

Модификатор const указывает, что переменная указанного типа является константой, то есть её значение не может быть изменено.

Перечисляемый тип enum связывает с переменной набор именованных констант, называемых перечисляемыми константами. Объявление перечисляемого типа выглядит так:

Если поле_тега опускается, то после закрывающей фигурной скобки необходимо указать переменную. Если поле_тега указано, то не указывается переменная.

Исторически сложилось так, что тип enum равнозначен типу int — то есть переменная перечисляемого типа занимает в памяти 4 байта. Каждая перечисляемая константа имеет значение, определяемое её порядковым номером в списке; нумерация начинается с нуля. Рассмотрим перечисление CombineMode:

В этом перечислении константа CombineModeReplace имеет значение 0, константа CombineModeIntersect имеет значение 1, и так далее; константа CombineModeComplement имеет значение 5.

Значения перечисляемых констант могут быть указаны явно, как, например, в следующем примере:

Перечисленные типы данных покрывают 99% всех типов данных, используемых в программировании Windows API. Это звучит слишком просто, не так ли? Почему же описания API функций содержат все эти типы — HWND, HINSTANCE, POINT и им подобные?

Причиной тому является то, что Cи имеет особенность, называемую strict-typing. Однажды появившись, переменная одного типа может принимать только те значения, которые соответствуют ее типу. Вы не можете сначала сохранить в переменной строку, а затем присвоить ей число. В Visual FoxPro мы обычно стараемся симулировать подобное путем соглашения о наименованиях. Например, cName представляет собой переменную символьного типа, тогда как nCount — числовую. Strict-typing позволяет создать новый тип данных, присвоив существующему типу данных новое имя. Каждый новый тип представляется отличным от других типов, несмотря на то, что внутренне они хранят одно и то же.

Windows усложняет использование этой концепции. К примеру, тип LONG в действительности представляет собой long int, а тип UINT — unsigned int. Оба типа являются 32-разрядными целыми числами. Производные типы данных определяются в различных include-файлах (файлы с расширением .h). Если вы приобрели Visual Studio.NET, то можете найти эти файлы в папке ..\VC7\PlatformSDK\Include\.

Типы данных Windows

Определение того, какой из базовых типов Си действительно представляет тип данных, используемый в API функции, является одной из тяжелейших задач в программировании API. Используйте следующее правило: если вы не можете найти слово float, double, char или str где-либо в имени функции или параметра, тогда это обычно 32-разрядное целое. Потребуется некоторое время для понимания и выработки навыков, но потом вы будете запросто преобразовывать типы данных. В следующей таблице приведены основные типы данных Windows и соответствующие им типы, используемые при объявлении функции в Visual FoxPro:

Тип данных Windows	Тип в объявлении функции	Описание
BOOL	Long	32-х разрядное целое число. 0 означает false, все остальное означает true.
BOOLEAN	Long	тоже самое, что и BOOL.
BYTE	String	8-ми разрядное целое число
CHAR	String	8-ми разрядное целое число
CLSID	String	128-разрядное число (16 байт)
COLORREF	Long	32-х разрядное целое число
DWORD	Long	32-х разрядное целое число
DOUBLE	Double	64-х разрядное вещественное число
FLOAT	Single	32-х разрядное вещественное число
GUID	String	128-разрядное число (16 байт)
HANDLE	Long	32-х разрядное целое число без знака
HBITMAP	Long	32-х разрядное целое число без знака
HDC	Long	32-х разрядное целое число без знака
HICON	Long	32-х разрядное целое число без знака
HGLOBAL	Long	32-х разрядное целое число без знака
HKL	Long	32-х разрядное целое число без знака
HLOCAL	Long	32-х разрядное целое число без знака
HINSTANCE	Long	32-х разрядное целое число без знака
HRESULT	Long	32-х разрядное целое число без знака
HWND	Long	32-х разрядное целое число без знака
LONG	Long	32-х разрядное целое число
LPARAM	Long	32-х разрядное целое число без знака
SHORT	Integer	16-ти разрядное целое число
SIZE_T	Long	32-х разрядное целое число без знака
TCHAR	String	Соответствует типу CHAR для строк формата ANSI и WCHAR для строк формата Unicode
UCHAR	String	Символ в ANSI кодировке
UINT	Long	32-х разрядное целое число без знака
ULONG	Long	32-х разрядное целое число без знака
USHORT	Integer	16-ти разрядное целое число без знака
UUID	String	128-разрядное число (16 байт)
VOID	нет	Не имеет значения
WCHAR	String	UNICODE character
WNDPROC	Long	32-х разрядное целое число без знака
WORD	Integer	16-ти разрядное целое число без знака
WPARAM	Long	32-х разрядное целое число без знака

Указатели

Другой концепцией, широко используемой в Си, являются указатели (pointers). Указатель представляет собой переменную, которая содержит адрес области памяти, по которому хранятся данные. Тип указателя всегда определяется типом данных, на которые он указывает; его размер всегда равен четырём байтам. Например, указатель на переменную типа SHORT представляет собой 32-разрядное целое число, как и указатель на любой другой тип данных. Описание указателя, принятое в программировании Windows API, начинается с символов «LP», что означет Long Pointer, или «длинный указатель», работающий с 32-х разрядной моделью памяти. Затем может следовать символ «C» (const), указывающий, что данные не должны изменяться. Далее следует описание типа данных переменной, адрес которой хранится в указателе. Например, LPDWORD — указатель на переменную типа DWORD.

Указатели на числовые данные при объявлении Windows API функции передаются по ссылке. Как пример рассмотрим функцию GetFileSize. Вот её прототип (подробнее о прототипах функций буде рассказано ниже):

Второй параметр, передаваемый функции — указатель на переменную типа DWORD, в которую функция поместит значение размера файла в байтах.

Объявление этой функции в Visual FoxPro:

Как видите, параметр FileSizeHight передаётся функции по ссылке, потому что передача по ссылке — это и есть передача указателя.

Сложнее обстоит дело со строками. Как уже говорилось, символьные строки в Cи — это массивы, поэтому в программировании API функций применяется тип str, определяющий массив символов типа CHAR (соответственно, тип wstr определяет массив символов типа WCHAR). В следующей таблице показаны типы указателей на символьные строки:

Тип указателя на строку	Описание
LPSTR	Указатель на модифицируемую нуль-терминированную строку ANSI-формата. Передаётся по ссылке
LPCSTR	Указатель на немодифицируемую нуль-терминированную строку ANSI-формата. Передаётся по значению
LPTSTR	Соответствует типу LPSTR для строк формата ANSI и типу LPWSTR для строк формата UNICODE. Передаётся по ссылке.
LPCTSTR	Соответствует типу LPSTR для строк формата ANSI и типу LPWSTR для строк формата UNICODE. Передаётся по значению.
LPWSTR	Указатель на модифицируемую нуль-терминированную строку UNICODE. Передаётся по ссылке
LPCWSTR	Указатель на немодифицируемую нуль-терминированную строку UNICODE. Передаётся по значению

Указатели на символьные данные могут передаваться как по ссылке, так и по значению — тип String в объявлении функции в Visual FoxPro всегда передаёт указатель на переменную, содержащую символьные данные. Используйте передачу символьных данных по ссылке только тогда, когда API функция должна изменить значение параметра.

Структуры

Структуру можно рассматривать как набор переменных различных типов, образующих единое целое. В Си структура создаётся при помощи ключевого слова struct, за которым следует необязательное поле тега (tag) и список элементов структуры:

Возможно и такое объявление структуры:

В этом объявлении отсутствует поле тега и создаётся так называемый анонимный структурный тип; такой синтаксис позволяет связать с этим структурным типом одну или несколько переменных, как, например, в следующем примере:

Структуры очень похожи на записи таблиц Visual FoxPro. Так, если запись таблицы personal содержит поля fio, address, tlfnumber и email, то для обращения к полю tlfnumber используется следующий синтаксис:

Так же выглядит и обращение к полю структуры:

Для формирования структур в Visual FoxPro используются переменные, содержащие строки символов. Например, для рассмотренной выше структуры SYSTEMTIME вам понадобится переменная длиной 16 байт. В первые два байта этой переменной заносится значение поля wYear, в следующие два байта — значение поля wMonth, в следующие два байта — значение поля wDayOfWeek, и так далее, пока структура не будет полностью сформирована. А при объявлении API функции в Visual FoxPro тип параметра, в котором передаётся переменная, содержащая структуру, должен быть типа String. Как записать в строковую переменную числовые данные, вы узнаете чуть позже.

При программировании Windows API на Си описание указателя на структуру начинается с символов LP (Long Pointer), за которыми следует наименование структуры. Так, указатель нас структуру SYSTEMTIME будет иметь тип LPSYSTEMTIME, указатель на структуру POINT будет иметь тип LPPOINT, и так далее. Как видите, ничего сложного, но, благодаря этой концепции, существует чрезвычайно большое количество типов указателей на структуры.

Если данные в передаваемой структуре не должны изменяться, то указатель на такую структуру объявляется так:

Здесь модификатор CONST означает, что данные в структуре не должны меняться, а символ (*) после имени структуры означает, что вся эта строка есть описание указателя на структуру. В следующем примере показан прототип функции CopyRect, которая копирует одну структуру в другую:

Описание прототипов функций в MSDN

Теперь, когда с типами данных всё стало более-менее понятно, познакомимся подробнее с таким понятием Си, как прототипы функций.

Согласно стандарта ANSI, все функции в Си должны иметь прототипы. Прототип функции достаточно прост:

Если в прототипе указан тип VOID как возвращаемый_тип, то это означает, что функция не возвращает никаких значений. Если тип VOID указан как тип_параметра, то это означает, что функция не имеет параметров.

Информацию о прототипах Windows API функций, включенных в библиотеки Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll и Advapi32.dll, в MSDN для Visual Studio.NET вы можете найти, последовательно открывая следующие разделы оглавления (Contents) справки:

В разделе Reference вы можете посмотреть описания функций, открыв один из следующих подразделов:

Наименование раздела MSDN	Что можно посмотреть
Windows Data Types	Здесь находится информация о типах данных Windows
Functions By Category	Здесь приводится список Win32 API функций по категориям
Function In Alphabetical Order	Здесь приводится список Win32 API функций в алфавитном порядке

Вот ещё один адрес в MSDN, по которому так же имеется информация об API функциях:

На следующем рисунке показан фрагмент окна справочной системы MSDN:

Вот как, например, описана в MSDN функция CopyRect:

The CopyRect function copies the coordinates of one rectangle to another.

BOOL CopyRect(
LPRECT lprcDst, // destination rectangle
CONST RECT* lprcSrc // source rectangle
);

lprcDst
[out] Pointer to the RECT structure that receives the logical coordinates of the source rectangle.
lprcSrc
[in] Pointer to the RECT structure whose coordinates are to be copied in logical units.

If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.
Windows NT/2000/XP: To get extended error information, call GetLastError.

Because applications can use rectangles for different purposes, the rectangle functions do not use an explicit unit of measure. Instead, all rectangle coordinates and dimensions are given in signed, logical values. The mapping mode and the function in which the rectangle is used determine the units of measure.

Windows NT/2000/XP: Included in Windows NT 3.1 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.

Как видите, информация достаточно исчерпывающая. Функция возвращает значение типа BOOL, ей передаются два параметра: типа LPRECT и CONST RECT* — указатели на структуры типа RECT. При объявлении этой функции в Visual FoxPro вы должны указать, что первый параметр передаётся по ссылке, а второй — по значению:

А как я определил, что эта функция находится в библиотеке User32.dll? Очень просто. В разделе рекомендаций (Requirements ) пункт Library гласит: Use User32.lib. Подставьте вместо расширения lib расширение dll — и всё! Кстати, там же, в пункте Header, сообщается, в каком include-файле содержится описание прототипа функции.

Но это ещё не всё! Так как функция работает со структурами, то в её описании присутствует гиперссылка на структуру RECT. Щёлкните мышью по этой гиперссылке, и на экране появится подробное описание структуры.

Формирование структур в Visual FoxPro

В девятой версии Visual FoxPro существенно расширены возможности встроенных функций BINTOC и CTOBIN. Теперь эти функции можно применять для преобразования числовых данных в формат, пригодный для использования в структурах. Напомню, что функция BINTOC выполняет преобразование числа в строку, а функция CTOBIN — строки в число.

Синтаксис функции BINTOC:

nExpression	преобразуемое числовое значение
eFlag	тип преобразования

Из всех возможных значений, которые может принимать параметр eFlag, нас интересуют следующие:

eFlag	Описание
«2RS»	Преобразует 16-ти разрядное целое число в двухбайтовую строку
«4RS»	Преобразует 32-х разрядное целое число в четырёхбайтовую строку
«F»	Преобразует 32-х разрядное вещественное число в четырёхбайтовую строку
«B»	Преобразует 64-х разрядное вещественное число в восьмибайтовую строку

Синтаксис функции CTOBIN:

cExpression	преобразуемая строка символов
eFlag	тип преобразования

Возможные значения параметра eFlag:

eFlag	Описание
«2RS»	Преобразует двухбайтовую строку в 16-ти разрядное целое число
«4RS»	Преобразует четырёхбайтовую строку в 32-х разрядное целое число
«4N»	Преобразует четырёхбайтовую строку в 32-х разрядное вещественное число
«8N»	Преобразует восьмибайтовую строку в 64-х разрядное вещественное число

Ниже показаны примеры использования этих функций:

В качестве примера запишем в переменную Visual FoxPro структуру RECT. Эта структура используется в рассмотренной ранее функции CopyRect для описания координат прямоугольной области. Вот как эта структура описывается в MSDN:

Как видите, структура RECT содержит четыре поля, в каждом из которых хранится значение типа LONG. Для её формирования в Visual FoxPro понадобится строка длиной 16 байт.

Ниже показан код, в котором объявляется функция CopyRect, формируются структуры Dst и Src для передачи их как параметров функции, и затем выполняется копирование одной структуры в другую. В примере используется функция BINTOC для преобразования числа в строку:

В следующем примере показано, как, используя функцию CTOBIN, можно «разобрать» структуру, получив числовые значения её полей:

Структуры, содержащие указатели

Достаточно часто встречается ситуация, когда передаваемая Windows API функции структура содержит указатели. В качестве примера рассмотрим функцию StartDoc, создающую документ для печати на принтере. Вот её прототип:

Как видите, второй передаваемый функции параметр — это указатель на структуру DOCINFO. Вот эта структура:

Первое поле структуры, cbSize, содержит значение длины структуры в байтах. А вот следующие три поля — это указатели на переменные, содержащие символьные данные. В частности, поле lpszDocName содержит указатель на строку с наименованием печатаемого документа (это то самое имя документа, которое вы видите, просматривая очередь печатаемых документов).

В Visual FoxPro достаточно сложно сформировать структуру, содержащую указатели. Во-первых, нужно выделить блок памяти и получить указатель на него. Во-вторых, необходимо переписать в эту память значение переменной Visual FoxPro — таким образом, у нас будет полностью реализован механизм указателей. Последнее, что остаётся сделать — это поместить значение указателя в структуру. При этом нужно выполнить одно существенное требование: выделенная память не должна быть перемещаемой — иначе может оказаться, что наш указатель в какой-то момент будет показывать на область, к которой наши данные не имеют никакого отношения!

Есть несколько возможностей получить блок памяти. Можно взять «кусочек» как из общей памяти Windows, так и из памяти, выделенной процессу (то есть вашему приложению). Второй способ имеет более высокое быстродействие, тем не менее здесь мы рассмотрим способ работы с памятью Windows как более простой.

Функция GlobalAlloc получает у Windows блок памяти указанного размера и возвращает указатель на него. Вот прототип этой функции:

Параметр uFlags определяет, как будет распределяться память. В MSDN написано, что он может принимать одно из следующих значений:

uFlag	Описание
GHND	Комбинация значений GMEM_MOVEABLE и GMEM_ZEROINIT
GMEM_FIXED	Распределяется фиксированная (неперемещаемая) область памяти
GMEM_MOVEABLE	Распределяется перемещаемая память
GMEM_ZEROINIT	Выделенный блок памяти заполняется нулями
GPTR	Комбинация значений GMEM_FIXED и GMEM_ZEROINIT

Из таблицы следует, что для параметра uFlags следует использовать значение GPTR. Но как узнать, какое это значение? Найдите в MSDN описание функции GlobalAlloc и в разделе Requirements посмотрите, в каком include-файле находится её прототип. Это файл Winbase.h. Именно в нём и следует искать описание значений констант. Вот фрагмент этого файла, в котором определяются перечисленные в таблице константы:

Следовательно, GPTR = GMEM_FIXED + GMEM_ZEROINIT = 0x0000 + 0x0040 = 0x0040.

Какой размер должен иметь выделяемый блок памяти? Конечно, равный длине строки, в которой хранится наименование документа. В следующем примере показаны действия, начиная с объявления API функции и заканчивая выделением блока памяти:

Следующая задача — переписать содержимое переменной cDocumentName в полученный блок памяти. Воспользуемся для этого встроенной функцией Visual FoxPro SYS(2600). Вот её синтаксис:

Функция ведёт себя по разному в зависимости от того, указан параметр cNewString или нет.

Если параметр cNewString указан, то функция копирует nLenght байт из переменной cNewString в память по адресу, указанному в dwAddress.

Если параметр cNewString не указан, то функция возвращает nLenght байт из памяти по адресу, указанному в dwAddress.

Как видите, параметр dwAddress — это указатель.

Запишем содержимое строки cDocumentName в выделенную функцией GlobalAlloc память:

Вот полный код формирования структуры DOCINFO:

Структура формируется в переменной cDocInfo. В первые четыре байта записываем число 20 — это размер структуры (поле cbSize). Следующие четыре байта, добавляемые в переменную, — это указатель на область памяти, в которую переписано содержимое переменной cDocumentName — наименование документа. Затем к переменной добавляются ещё двенадцать нулевых байтов — это поля структуры lpszOutput, lpszDatatype и fwType, которые, согласно документации, могут игнорироваться; это означает, что поля должны иметь нулевые значения. Таким образом, получилась строка длиной 20 байтов — что и требовалось.

Особенности использования памяти

Применяя в ваших приложениях функции Windows API, вы должны помнить о том, Visual FoxPro не может управлять памятью, резервируемой этими функциями. Поэтому, если вы распределяете память, например, при помощи функции GlobalAlloc, то вы обязательно должны после использования вернуть эту память Windows, вызвав функцию GlobalFree. Для каждой API функции, резервирующей память, имеется функция — антипод, освобождающая зарезервированную память.

Вот прототип функции GlobalFree:

Функция получает только один параметр — указатель на блок памяти. Вот её объявление и использование в Visual FoxPro:

здесь hGlobal — указатель на блок памяти, возвращаемый функцией GlobalAlloc.

Если вы будете забывать возвращать распределённую память, то тогда вы рискуете столкнуться с проблемой, называемой утечкой памяти. Последствия такой утечки могут быть весьма печальны — от резкого замедления работы вашего приложения, вызванного фрагментацией памяти, до краха операционной системы.

Передача в функцию массивов

Массив с точки зрения Си — это переменная, содержащая несколько элементов одного типа. Доступ к каждому отдельному элементу массива осуществляется при помощи индекса. Все элементы массива имеют одинаковый размер, нельзя описывать массивы со смешанными типами данных. Все элементы массива хранятся в памяти последовательно, один за другим, при этом минимальное значение индекса соответствует первому элементу, а максимальное — последнему.

Массив Visual FoxPro имеет совершенно другую организацию, которая позволяет хранить в его элементах совершенно разные типы данных. Поэтому невозможно передать массив из Visual FoxPro в Windows API функцию, просто указав его имя как параметр. Более того, в команде DECLARE..DLL нет такого типа данных, как массивы.

Тем не менее выход из этого положения есть. Как и для структур, для передачи массивов используются символьные переменные. Числовые данные из массива должны быть преобразованы в строку, которую вы и передаёте как параметр в Windows API функцию. В следующем примере показан код функции ArrayToString, формирующей строку из массива. Функция получает получает массив taArray (по ссылке) и флаг tlTypeOfValue, указывающий, как нужно преобразовать значения элементов массива — как целые (tlTypeOfValue=.F.) или вещественные (tlTypeOfValue=.T.) числа:

Функция работает как с одномерными, так и с двумерными массивами.

Кодировка символьных данных: форматы ANSI и UNICODE

В кодировке ANSI (применяемой в Visual FoxPro) каждый символ определяется одним байтом, то есть максимальное количество символов равно 256, что, конечно, очень мало. Например, при русификации часть стандартных символов ANSI заменяется на символы кириллицы. А в некоторых алфавитах, например, японской кане, столько символов, что одного байта для их кодировки просто недостаточно. Для поддержки таких языков, и, что более важно, для облегчения «перевода» программ на другие языки, была разработана кодировка Unicode. Каждый символ в Unicode состоит из двух байтов, что позволило расширить набор допустимых символов до 65536.

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

Встроенная функция Visual FoxPro STRCONV выполняет конвертирование строк как из формата ANSI в UNICODE, так и обратно. Вот её синтаксис:

Параметр cExpression — это строка, которую необходимо конвертировать. Параметр nConversionSetting указывает характер конвертирования. Из всех его возможных значений нас интересуют только два:

• 5 — конвертирование из ANSI в UNICODE
• 6 — конвертирование из UNICODE в ANSI

Необязательные параметры nRegionalIdentifier и nRegionalIDType определяют дополнительные региональные настройки и могут быть безболезненно проигнорированы.

Ниже показаны примеры использования функции STRCONV:

Возможно, при прочтении этого раздела у вас сложилось впечатление, что работать с Windows API функциями в Visual FoxPro достаточно просто. И да, и нет. Например, некоторые API функции используют типы данных, не поддерживаемые в команде DECLARE..DLL, например, 64-х разрядные целые числа. Так же есть ряд функций, называемых функциями обратного вызова. В прототипе такой функции перед описанием возвращаемого типа присутствует модификатор CALLBACK. К сожалению, вы не можете использовать такие функции, по крайней мере, напрямую. Так же бывает, что структура содержит указатель на функцию — такие API в Visual FoxPro так же нельзя использовать.