Текущий раздел:

Описания RDS

Приложения

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

А.2. События блока и связанные с ними описания

А.2.2. Главная функция DLL

# Приложения

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

### А.2. События блока и связанные с ними описания

#### А.2.2. Главная функция DLL

Динамически подключаемая библиотека (DLL) с функциями моделей блоков RDS, как и любая другая DLL в Windows, должна иметь главную функцию (точку входа), которая вызывается при загрузке библиотеки в память и ее выгрузке. Чаще всего эта функция имеет имя DllMain или DllEntryPoint (имя главной функции DLL обычно указывается в описании используемого для создания библиотек компилятора). В главной функции обычно выполняются действия, общие для всех моделей блоков в данной библиотеке:

- получение доступа к сервисным функциям RDS;
- регистрация функций блоков;
- проверка соответствия версии RDS версии библиотеки, если это необходимо.

Эти действия не обязательно выполнять именно в главной функции DLL – она просто предоставляет для них удобное место вызова. Написание главной функции DLL подробно рассмотрено в §2.2 руководства программиста.

Главная функция DLL имеет следующий вид:

      int WINAPI DllMain(
        HINSTANCE hinst,      // Дескриптор модуля DLL
        unsigned long reason, // Причина вызова главной функции
        void *lpReserved      // Зарезервировано
      );

Параметры функции

hinst(HINSTANCE)
  Дескриптор модуля загруженной DLL. Его можно использовать для доступа к различным ресурсам (изображениям, строкам и т.п.), хранящимся в файле DLL вместе с функциями, а также для определения пути к файлу DLL функцией Windows API GetModuleFileName.
reason(unsigned long)
  Причина вызова главной функции DLL (одна из четырех констант Windows API):

  DLL_PROCESS_ATTACH | Процесс (в данном случае – «rds.exe» или «rds64.exe») загрузил данную DLL в память. Обычно в этот момент выполняются все действия по инициализации глобальных переменных, с которыми работают функции этой DLL.
  DLL_THREAD_ATTACH | Процесс создал новый поток (в DLL с моделями блоков обычно не используется).
  DLL_THREAD_DETACH | Поток завершился (в DLL с моделями блоков обычно не используется).
  DLL_PROCESS_DETACH | Процесс выгружает данную DLL из памяти. В этот момент выполняются действия по очистке глобальных данных, если это необходимо.

lpReserved(void*)
  Указывает на способ загрузки или выгрузки библиотеки. При создании DLL с моделями блоков или модулями автоматической компиляции для RDS этот параметр не используется.

Возвращаемые значения

При вызове главной функции при загрузке DLL в память процесса (при этом параметр reason равен DLL_PROCESS_ATTACH) возврат ненулевого значения сигнализирует об успешности инициализации, возврат нулевого – об ошибках. В остальных случаях возвращаемое значение не используется.

Пример

Главная функция, обеспечивающая моделям блоков доступ ко всем сервисным функциям RDS с помощью макросов из файла «RdsFunc.h».

      #include <windows.h>
      #include <RdsDef.h>

      // Подготовка описаний сервисных функций
      #define RDS_SERV_FUNC_BODY GetInterfaceFunctions
      #include <RdsFunc.h>

      // Главная функция DLL
      int WINAPI DllMain(HINSTANCE /*hinst*/,
                         unsigned long reason,
                         void* /*lpReserved*/)
      { if(reason==DLL_PROCESS_ATTACH) // Загрузка DLL
          { // Получение доступа к функциям
            if(!GetInterfaceFunctions())
              RDS_SERV_ERROR_MSGW // Сообщение: старая версия RDS
          }
        return 1;
      }