OpenSCADAWiki: Doc/API/part19
 

19. API модулей модульных подсистем

Модули в системе OpenSCADA реализуются в виде разделяемых библиотек. Как уже ранее упоминалось, одна такая библиотека может содержать множество модулей подсистем OpenSCADA, фактически выступая в роли контейнера.

Первым шагом при подключении разделяемых (SO — shared object) библиотек является подключение функций инициализации. Эти функции должны быть определены как обычные “С” функции для исключения искажения имен функций. Обычно это делается следующим образом:
//================== CUT =========================
extern "C"
{
#ifdef MOD_INCL
    //Нужно указывать только в случае поддержки модулем возможности
    //влинковки в ядро OpenSCADA
    TModule::SAt bd_DBF_module( int n_mod )
#else
    TModule::SAt module( int n_mod )
#endif
    {
    //Формирование описателей модулей из списка
    //доступных в разделяемой библиотеке.
    }

#ifdef MOD_INCL
    //Нужно указывать только в случае поддержки модулем возможности
    //влинковки в ядро OpenSCADA
    TModule *bd_Tmpl_attach( const TModule::SAt &AtMod, const string &source )
#else
    TModule *attach( const TModule::SAt &AtMod, const string &source )
#endif
    {
    //Подключить указанный модуль
    }
}
//================== CUT =========================


Функции для работы с разделяемой библиотекой:
TModule::SAt module( int n_mod );
Функция предназначена для последовательного опроса информации о модулях, содержащихся в SO библиотеке. Параметр n_mod указывает на порядковый номер запрашиваемого модуля и должен перебираться, начиная с нуля. В случае отсутствия модуля с данным идентификатором функция должна возвращать структуру с именем модуля нулевой длины, что и служит окончанием процесса сканирования.

TModule *attach( const TModule::SAt &AtMod, const string &source );
Подключение к указанному модулю.

Практически все функции и данные системы сведены в API-системы, описываемого в данном документе. Однако для упрощения и ускорения процесса написания модулей основные функции, переопределяемые в модулях, приведены в таблице 22.

Таблица 22. Основные функции, использующиеся при создании модулей
Общее API
API объекта (TCntrNode):
  • virtual void load_( ); — Загрузка объекта из хранилища.
  • virtual void save_( ); — Сохранение объекта в хранилище.
Общее API модулей (TModule):
Атрибуты:
  • string mId; — Идентификатор модуля.
  • string mName; — Имя модуля.
  • string mDescr; — Описание модуля.
  • string mType; — Тип модуля.
  • string mVers; — Версия модуля.
  • string mAutor; — Автор модуля.
  • string mLicense; — Лицензия модуля.
  • string mSource; — Источник/происхождение модуля.
Методы:
  • virtual void modStart( ); — Запуск модуля.
  • virtual void modStop( ); — Останов модуля.
  • virtual void modInfo( vector<string> &list ); — Список доступных элементов информации о модуле. Предусмотрены следующие информационные элементы:
    Module — идентификатор модуля;
    Name — локализованное имя модуля;
    Type — тип модуля;
    Source — источник модуля (контейнер);
    Version — версия модуля;
    Author — автора модуля;
    Description — описание модуля;
    License — лицензия модуля.
  • virtual string modInfo( const string &name ); — Запрос указанного элемента информации.
  • virtual void perSYSCall( unsigned int cnt ); — Вызов из системного потока, с периодичностью 10 секунд и секундным счётчиком cnt.
  • void postEnable( int flag ); — Подключение модуля к динамическому дереву объектов.
  • void modFuncReg( ExpFunc *func ); — Регистрация экспортируемой функции.
API модулей подсистемы “БД”.
Тип БД (потомок от TTypeBD):
  • virtual TBD *openBD( const string &id ); — Открыть/создать БД.
БД (потомок от TBD):
  • virtual void enable( ); — Включение БД.
  • virtual void disable( ); — Отключение БД.
  • virtual void allowList( vector<string> &list ) const; — Перечень таблиц в БД.
  • virtual void sqlReq( const string &req, vector< vector<string> > *tbl = NULL, char intoTrans = EVAL_BOOL ); — Отправка SQL-запроса req на БД и получение результата в виде таблицы tbl. При установке intoTrans в true для запроса будет открыта транзакция, в false будет закрыта.
  • virtual void transCloseCheck( ) — Периодически вызываемая функция для проверки транзакций и закрытия старых или содержащих много запросов.
  • virtual TTable *openTable( const string &table, bool create ); — Открыть/создать таблицу.
Таблица (потомок от TTable):
  • virtual void fieldStruct( TConfig &cfg ); — Получение структуры таблицы.
  • virtual bool fieldSeek( int row, TConfig &cfg ); — Последовательное сканирование записей таблицы.
  • virtual void fieldGet( TConfig &cfg ); — Получение указанной записи.
  • virtual void fieldSet( TConfig &cfg ); — Установка указанной записи.
  • virtual void fieldDel( TConfig &cfg ); — Удаление указанной записи.
API модулей подсистемы "Транспорты".
Тип транспорта (потомок от TTypeTransport):
  • virtual TTransportIn *In( const string &name, const string &db ); — Создать/открыть новый "Входящий" транспорт.
  • virtual TTransportOut *Out( const string &name, const string &db ); — Создать/открыть новый "Исходящий" транспорт.
Входящий транспорт (потомок от TTransportIn):
  • virtual string getStatus( ); — Статус интерфейса.
  • virtual void setAddr( const string &addr ); — Установка адреса транспорта. Может переопределяться для обработки и проверки специфического для модуля формата адреса транспорта.
  • virtual void start(); — Запуск транспорта.
  • virtual void stop(); — Останов транспорта.
Исходящий транспорт (потомок от TTransportOut):
  • virtual string getStatus( ); — Статус интерфейса.
  • virtual void setAddr( const string &addr ); — Установка адреса транспорта. Может переопределяться для обработки и проверки специфического для модуля формата адреса транспорта.
  • virtual void start( ); — Запуск транспорта.
  • virtual void stop( ); — Останов транспорта.
  • virtual int messIO( const char *obuf, int len_ob, char *ibuf = NULL, int len_ib = 0, int time = 0 ); — Отправка данных через транспорт. Время ожидания time соединения указывается в миллисекундах.
API модулей подсистемы "Протоколы".
Протокол (потомок от TProtocol):
  • virtual void itemListIn( vector<string> &ls, const string &curIt = "" ); — Перечень подєлементов у входящего протокола, если протокол их предусматривает. Используется при выборе в конфигурации объекта входящего транспорта.
  • virtual void outMess( XMLNode &io, TTransportOut &tro ); — Передача данных в дереве XML in удалённой системе посредством транспорта tro и текущего исходящего протокола.
  • virtual TProtocolIn *in_open( const string &name ) — Открыть/создать входной протокол.
Входной протокол (потомок от TProtocolIn):
  • virtual bool mess( const string &request, string &answer, const string &sender ); — Передача неструктурированного сообщения в протокол.
API модулей подсистемы “Сбор данных”.
Тип контроллера (потомок от TTypeDAQ):
  • virtual void compileFuncLangs( vector<string> &ls ); — Перечень языков пользовательского программирования, поддерживаемых модулем.
  • virtual void compileFuncSynthHighl( const string &lang, XMLNode &shgl ); — Запрос правил подсветки синтаксиса shgl указанного языка пользовательского программирования lang.
  • virtual string compileFunc( const string &lang, TFunction &fnc_cfg, const string &prog_text ); — Компиляция пользовательской процедуры и создания объекта исполнения функции для указанного языка пользовательского программирования.
  • virtual bool redntAllow( ); — Признак поддержки механизмов резервирования модулем. Должен просто переопределяться и возвращать true.
  • virtual TController *ContrAttach( const string &name, const string &daq_db ); — Открытие/подключение контроллера.
Контроллер (потомок от TController):
  • virtual string getStatus( ); — Вызов для получения специфического статуса контроллера.
  • virtual void enable_( ); — Включение контроллера.
  • virtual void disable_( ); — Отключение контроллера.
  • virtual void start_( ); — Запуск контроллера.
  • virtual void stop_( ); — Останов контроллера.
  • virtual void redntDataUpdate( bool firstArchiveSync = false ); — Выполнение операции получения данных из резервной станции. Вызывается автоматически задачей обслуживания схемы резервирования и перед запуском для синхронизации архивов с установленным параметром firstArchiveSync.
  • virtual TParamContr *ParamAttach( const string &name, int type ); — Создание/открытие нового параметра.
Параметр контроллера (потомок от TParamContr->TValue):
  • virtual void enable( ); — Включить параметр.
  • virtual void disable( ); — Отключить параметр.
  • virtual void setType( const string &tpId ); — Вызывается для смены типа параметра tpId и может быть обработан в объекте модуля, для смены собственных данных.
  • virtual TVal* vlNew( ); — Вызывается при создании нового атрибута. Может быть переопределён для реализации особого поведения в рамках своего, наследованного от TVal, класса при доступе к атрибуту.
  • virtual void vlSet( TVal &val, const TVariant &pvl ); — Вызывается для атрибута с прямым режимом записи TVal::DirWrite (синхронный режим или запись во внутренний буфер объекта) при установке значения, с целью непосредственной записи значения в физический контроллер или буфер объекта.
  • virtual void vlGet( TVal &val ); — Вызывается для атрибута с прямым режимом чтения TVal::DirRead (синхронный режим или чтение из внутреннего буфера объекта) при чтении значения, с целью непосредственного чтения значения из физического контроллера или буфера объекта.
  • virtual void vlArchMake( TVal &val ); — Вызывается при создании архива значений с атрибутом val в качестве источника с целью инициализации качественных характеристик буфера архива согласно особенностям источника данных и их опроса.
API модулей подсистемы "Архивы".
Тип архиватора (потомок от TTypeArchivator):
  • virtual TMArchivator *AMess(const string &id, const string &db ); — Создание архиватора сообщений.
  • virtual TVArchivator *AVal(const string &id, const string &db ); — Создание архиватора значений.
Архиватор сообщений (потомок от TMArchivator):
  • virtual void start( ); — Старт архиватора.
  • virtual void stop( ); — Останов архиватора.
  • virtual time_t begin( ); — Начало данных в архиваторе.
  • virtual time_t end( ); — Конец данных в архиваторе.
  • virtual void put( vector<TMess::SRec> &mess ); — Передать сообщение архиватору.
  • virtual void get( time_t b_tm, time_t e_tm, vector<TMess::SRec> &mess, const string &category = "", char level = 0, time_t upTo = 0 ); — Запросить сообщение из архиватора.
Архиватор значений (потомок от TVArchivator):
  • virtual void setValPeriod( double per ); — Установить периодичность значений архиватора.
  • virtual void setArchPeriod( int per ); — Установить периодичность архивирования.
  • virtual void start( ); — Запустить архиватор.
  • virtual void stop( bool full_del = false ); — Остановить архиватор с возможностью полного удаления, если установлен full_del.
  • virtual TVArchEl *getArchEl( TVArchive &arch ); — Получение архива arch, обслуживаемого архиватором.
Архивный элемент значений (потомок от TVArchEl):
  • virtual void fullErase( ); — Полное удаление части архива в архиваторе.
  • virtual int64_t end( ); — Время окончания архива в архиваторе.
  • virtual int64_t begin( ); — Время начала архива в архиваторе.
  • virtual TVariant getValProc( long long *tm, bool up_ord ); — Функция обработки запроса одного значения из архива.
  • virtual void getValsProc( TValBuf &buf, int64_t beg, int64_t end ); — Функция обработки запроса модулем на получение данных группы значений buf за указанный промежуток времени.
  • virtual void setValsProc( TValBuf &buf, int64_t beg, int64_t end ); — Функция обработки запроса модулем на установку данных группы значений buf за указанный промежуток времени.
API модулей подсистемы "Пользовательские интерфейсы".
Пользовательский интерфейс (потомок от TUI):
Не содержит специфических функций!
API модулей подсистемы "Специальные”.
Специальные (потомок от TSpecial):
Не содержит специфических функций!