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; — Источник/происхождение модуля.
Методы: |
API модулей подсистемы “БД”. |
Тип БД (потомок от TTypeBD): - virtual TBD *openBD( const string &id ); — Открыть/создать БД.
|
БД (потомок от TBD): - virtual void enable( ); — Включение БД.
- virtual void disable( ); — Отключение БД.
- virtual void allowList( vector<string> &list ); — Перечень таблиц в БД.
- 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 модулей подсистемы "Транспорты". |
Тип транспорта (потомок от TTipTransport): - 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, bool noRes = false ); — Отправка данных через транспорт. Время ожидания <time> соединения указывается в милисекундах. <noRes> используется протоколами для монопольного блокирования транспорта на время работы с ним и исключения собственной блокировки функцией.
|
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 модулей подсистемы "Архивы". |
Тип архиватора (потомок от TTipArсhivator): - 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):
Не содержит специфических функций! |