Приложения

Приложение А. Функции, константы и структуры 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;
  }