Приложения

Приложение А. Функции, константы и структуры RDS

Описываются сервисные функции, экспортированные из модуля «rds.exe», используемые в них структуры и константы. Применение этих функций для создании моделей блоков описывается в главе 2 руководства программиста, для создания модулей автоматической компиляции моделей – в главе 3 там же.

А.1. Типы параметров

Описываются основные типы, используемые в моделях и дополнительных модулях для взаимодействия с RDS.

А.1.1. Идентификаторы объектов и вспомогательные типы

Схема в RDS состоит из множества различных объектов: блоков, связей, переменных, таймеров и т.п. Каждый из таких объектов имеет уникальный идентификатор, который нужно указывать в сервисных функциях для ссылки на конкретный объект, с которым нужно произвести то или иное действие. Большинство этих идентификаторов представляют собой указатели на какие-либо данные (тип LPVOID Windows API), но, для лучшей читаемости исходных текстов программ, в файле «RdsDef.h» для них оператором typedef введены специальные типы:

Тип	Объект
RDS_BHANDLE	Блок в схеме, независимо от его типа (простой блок, подсистема, внешний вход или выход, ввод шины). Используется во всех сервисных функциях, получающих или устанавливающих параметры блоков. Модель блока всегда имеет доступ к идентификатору своего блока и его родительской подсистемы через структуру данных блока RDS_BLOCKDATA.
RDS_CHANDLE	Связь или шина в схеме. Используется во всех сервисных функциях, получающих или устанавливающих параметры связей и шин.
RDS_TIMERID	Программируемый таймер блока. Используется в функциях работы с таймерами, в реакциях на событие RDS_BFM_TIMER и RDS_BFM_WINREFRESH.
RDS_MENUITEM	Пункт системного или контекстного меню, добавленный моделью блока. Используется в сервисных функциях работы с меню.
RDS_VHANDLE	Статическая или динамическая переменная блока. Используется в некоторых сервисных функциях для получения описания переменных и их редактирования. Для доступа к значениям переменных, как правило, не используется (см. §2.5 и §2.6 руководства программиста).
RDS_HOBJECT	Вспомогательный объект RDS. Вспомогательные объекты служат для различных целей: редактирования связей, разбора текста, открытия окон и т.п., но все они имеют этот тип.
RDS_NETSTATION	Одна из машин с запущенной копией RDS, подключенная к серверу. Используется для указания машины при отправке данных по сети конкретному блоку функцией rdsNetSendData и в реакциях на события RDS_BFM_NETDATARECEIVED и RDS_BFM_NETERROR.
RDS_NETBLOCK	Блок на одной из машин с запущенной копией RDS, подключенной к серверу. Используется для указания блока при отправке данных по сети конкретному блоку функцией rdsNetSendData и в реакциях на события RDS_BFM_NETDATARECEIVED и RDS_BFM_NETERROR. Не взаимозаменяем с RDS_BHANDLE – последний может использоваться только в качестве идентификатора блока в пределах одной схемы на одной машине.
RDS_COMPHANDLE	Модуль автоматической компиляции. Используется в сервисных функциях, работающих с автокомпилируемой моделью, для указания конкретного модуля.
RDS_MODELHANDLE	Автоматически компилируемая модель. Используется в сервисных функциях, работающих с автокомпилируемой моделью, для указания конкретной модели.

Для взаимодействия с Windows API многие сервисные функции и структуры работают со значениями следующих, стандартных для Windows, типов (а также и их «псевдонимов», введенных специально для RDS):

Тип	Объект
BOOL	Логическое значение, может принимать значения TRUE (истина) или FALSE (ложь). Этот тип эквивалентен стандартному типу C «int».
BYTE	Целая переменная, занимающая один байт. Этот тип эквивалентен стандартному типу C «unsigned char». Может принимать значения от 0 до 255.
COLORREF	Тридцатидвухбитное целое число, описывающее цвет. Младший байт числа содержит интенсивность красного канала (в диапазоне от 0 до 255), второй байт – интенсивность зеленого, третий байт – интенсивность синего, четвертый (старший) байт всегда нулевой. Таким образом, число 0xFF0000 соответствует синему цвету, 0xFFFFFF – белому, 0 – черному.
DWORD	Тридцатидвухбитное беззнаковое целое число (unsigned long). Может принимать значения от 0 до 4294967295. В RDS достаточно часто используется для хранения различных битовых флагов или размеров областей памяти.
HBITMAP	Дескриптор загруженного в память растрового рисунка. В RDS используется только в функции rdsRegisterWindow.
HDC	Контекст устройства (device context) Windows. Контексты устройств используются в графических функциях Windows API для указания объекта (например, окна), на котором производится построение изображения.
HINSTANCE	Дескриптор загруженного в память модуля, например, DLL. Фактически, это базовый адрес модуля, но в функциях Windows API он часто используется просто как идентификатор этого модуля.
HWND	Дескриптор окна Windows. Такие дескрипторы используются в функциях Windows API, выполняющих различные действия с окнами.
LOGFONT, LOGFONTA, LOGFONTW	Структура, содержащая описание шрифта Windows. Ее поля подробно описаны в руководстве по Windows API. В RDS она используется не очень широко.
LPSTR, RDSSTR, RDSVSTR, RDSCSTR	Указатель на строку байтов, завершающуюся нулевым байтом. Первые три типа эквивалентны стандартному типу C «char». Тип «RDSCSTR» эквивалентен типу «const char». В RDS строки этих типов всегда считаются имеющими кодировку UTF8. Следует помнить, что для символов национальных алфавитов один символ может занимать несколько последовательных байтов.
LPWSTR, RDSWSTR, RDSWVSTR, RDSWCSTR	Указатель на строку в кодировке UTF16, завершающуюся нулевым кодом. Первые три типа эквивалентны стандартному типу C «wchar_t». Тип «RDSWCSTR» эквивалентен типу «const wchar_t».
RDSXSTR, RDSXVSTR, RDSXCSTR	Указатель на строку в кодировке UTF8 или UTF16 в зависимости от наличия макроопределения RDS_UTF16DEFAULT (см. приложение А.1.3). В типе «RDSXCSTR» к строке добавлен модификатор «const».
RDSXCHAR	Один символ текста в кодировке UTF8 или UTF16 в зависимости от наличия макроопределения RDS_UTF16DEFAULT. Эквивалентен типу «char», если кодировка по умолчанию – UTF8, и «wchar_t», если кодировка – UTF16.
LPVOID	Указатель на некоторый объект в памяти без уточнения типа этого объекта. Этот тип эквивалентен стандартному типу C «void*».
POINT	Структура, описывающая точку с двумя целыми координатами (поля x и y).
RECT	Структура, описывающая прямоугольник через целые координаты его левой верхней (поля left и top) и правой нижней (поля right и bottom) точек.

В сервисных функциях и структурах RDS также используются следующие обозначения-синонимы для стандартных типов Windows и языка C:

Описание в RDS	Стандартное описание	Назначение
RDSBYTES	BYTE, unsigned char	Указатель на массив байтов.
RDSINT32	int	Целая переменная со знаком, занимающая тридцать два бита (четыре байта).
RDSCALL	CALLBACK, APIENTRY, __stdcall	Тип вызова всех сервисных функций RDS и всех функций обратного вызова, используемых в моделях блоков и модулях автокомпиляции. Аргументы функции передаются в стеке справа налево, стек освобождается вызванной функцией.
RDS_SHORT	short int	Двухбайтовое целое число со знаком. В RDS предусмотрен такой тип переменных блока, больше этот тип нигде не используется.
RDS_PCOLORREF	COLORREF*, LPCOLORREF	Указатель на тридцатидвухбитное число, описывающее цвет (COLORREF).