OpenSCADAWiki: Doc/API/part2 ...

2. Общая структура системы. Модульность (TSubSYS, TModule)

Корнем, от которого строится вся система, является объект TSYS. Корень содержит подсистемы (TSubSYS). Подсистемы могут быть: обычными и модульными. Отличие модульных подсистем четко прослеживается на рис. 1. Так, модульные подсистемы обязательно содержат список модульных объектов (TModule), например подсистема архивы TArchiveS содержит модульные объекты TTipArchivator. В тоже время обычная подсистема таких объектов не содержит. Например, подсистема безопасности TSeсurity (рис.2).

Рис. 2. Иерархическая структура системы OpenSCADA.

В процессе инициализации корня (TSYS) определяется глобальная переменная SYS. Переменная SYS может использоваться для прямого обращения к корню системы из любого её узла. Инициализация корня выполняется единожды из главной вызывающей функции. После запуска управление захватывается объектом системы до остановки. Корневой объект концентрирует все общесистемные функции системы OpenSCADA.

Продолжением корневого объекта (TSYS), выполняющего функции обслуживания потока системных сообщений, выступает объект TMess. Объект доступен посредством глобальной переменной Mess, которая инициализируется корнем системы. Объект содержит функции кодирования, декодирования и локализации сообщений.

В подсистемах (TSubSYS) реализуются функции характерные для каждой подсистемы индивидуально, с общим для всех подсистем доступом, через объект TSubSYS. Модульная подсистема имеет возможность расширять функциональность посредством модулей. Для этой цели модульная подсистема предоставляет доступ к модулям своего типа в виде модульных объектов.

Модуль - составная часть модульной подсистемы. В общем, для всех модулей и их подсистем, модуль предоставляет информацию о себе, своём происхождении и экспортируемых функциях. Отдельно взятый модуль реализует функциональность в соответствии со своими потребностями.

2.1. Корневой объект системы (TSYS)

Данные:
Информационные переменные программы:

• PACKAGE_LICENSE - Лицензия распространения программы
• PACKAGE_DESCR - Краткое описание программы
• PACKAGE_AUTHOR - Автор программы
• PACKAGE_SITE - Web сайт поддержки программы

Способы кодирования символьных последовательностей (enum - TSYS::Code):

• PathEl - элемент пути (символы: '/' и '%' к виду '%2f');
• HttpURL - адрес браузера (http url);
• Html - специальных символов для использования в html;
• JavaSc - символов конца строки для JavaScript;
• SQL - значения SQL-запросов;
• Custom - выборочное кодирование указанных символов;
• base64 - Mime кодирование в стандарте Base64;
• FormatPrint - Кодирование/экранирование элементов форматирования для функций вроде "printf";
• oscdID - Кодирование идентификаторов узлов.
• Bin - Кодирование бинарных данных в текст и обратно.
• Reverse - Инверсия порядка символов в строке.
• ShieldSimb - Кодирование экранированных символов вроде "\n" в реальные коды.

Виды представления целого в функциях TSYS::int2str() и TSYS::ll2str() (enum - TSYS::IntView):

• Dec - десятичное;
• Oct - восьмеричное;
• Hex - шестнадцатеричное.

Стандартные коды ошибок в системе OpenSCADA (enum - TSYS::Errors):

• DBInit (1) - Ошибка инициализации БД;
• DBConn (2) - Ошибка подключения к БД;
• DBInernal (3) - Внутрення ошибка БД;
• DBRequest (4) - Ошибка в запросе к БД;
• DBOpen (5) - Ошибка открытия БД;
• DBOpenTable (6) - Ошибка открытия таблицы;
• DBClose (7) - Ошибка закрытия БД;
• DBTableEmpty (8) - Таблица БД пуста;
• DBRowNoPresent (9) - Запись в таблице отсутствует.

Шаблоны:

• TO_FREE - Значение свободного объекта (NULL).
• STR_BUF_LEN - Стандартная длина строковых буферов в OpenSCADA (3000).
• STD_WAIT_DELAY - Стандартный квант времени циклов ожидания (100мс).
• STD_WAIT_TM - Стандартный интервал ожидания события.
• __func__ - Полное имя вызывающей функции.
• vmin(a,b) - Определение минимального значения.
• vmax(a,b) - Определение максимального значения.

Публичные методы:

• TSYS( int argi, char **argb, char **env ); — Инициализирующий конструктор.
• int start( ); — Запуск системы. Функция завершается только с завершением работы системы. Возвращается код возврата.
• void stop( ); — Команда остановки системы.
• int stopSignal( ); — Код возврата в случае останова системы. Может использоваться как признак «Останов системы» различными подсистемами.
• string id( ); — Идентификатор станции.
• string name( ); — Локализованное имя станции.
• string user( ); — Системный пользователь от имени которого запущена система.
• string host( ); — Имя хоста на котором исполняется станция.
• void list( vector<string> &list ); — Список подсистем зарегистрированных в системе.
• bool present( const string &name ); — Проверка на наличие указанной подсистемы.
• void add( TSubSYS *sub ); — Добавление/регистрация подсистемы.
• void del( const string &name ); — Удаление подсистемы.
• AutoHD<TSubSYS> at( const string &name ); — Подключение к указанной подсистеме.
• AutoHD<TUIS> ui( ); — Прямой доступ к подсистеме «Пользовательские интерфейсы».
• AutoHD<TArchiveS> archive( ); — Прямой доступ к подсистеме «Архивы».
• AutoHD<TBDS> db( ); — Прямой доступ к подсистеме «Базы данных».
• AutoHD<TControllerS> daq( ); — Прямой доступ к подсистеме «Сбор данных».
• AutoHD<TProtocolS> protocol( ); — Прямой доступ к подсистеме «Протоколы».
• AutoHD<TTransportS> transport( ); — Прямой доступ к подсистеме «Транспорты».
• AutoHD<TSpecialS> special( ); — Прямой доступ к подсистеме «Специальные».
• AutoHD<TModSchedul> modSchedul( ); — Прямой доступ к подсистеме «Управление модулями».
• AutoHD<TSeсurity> seсurity( ); — Прямой доступ к подсистеме «Безопасность».
• string workDir( ); — Рабочая директория станции.
• string icoDir( ); — Директория иконок OpenSCADA.
• string modDir( ); — Директория модулей OpenSCADA.
• void setWorkDir( const string &wdir ); — Установка рабочей директории станции.
• void setIcoDir( const string &idir ); — Установка директории иконок OpenSCADA.
• void setModDir( const string &mdir ); — Установка директории модулей OpenSCADA.
• string cfgFile( ); — Имя конфигурационного файла системы.
• XMLNode &cfgRoot( ); — Разобранная структура конфигурационного файла.
• XMLNode *cfgNode( const string &path, bool create = false ); — Получение узла конфигурации по его пути <path>. Создавать элементы пути в случае их отсутствии <create>.
• void modifCfg( ); — Отметка модификации конфигурации, для последующего сохранения в файл.
• string workDB( ); — Полное имя рабочей БД.
• string selDB( ); — Выбранная БД. Используется для избирательной загрузки из указанной БД, в подсистеме "БД".
• bool chkSelDB( const string& wDB ); — Функция проверки на соответствие указанной БД <wDB> выбранной в selDB( ).
• void setWorkDB( const string &wdb ); — Установка полного имени рабочей БД.
• void setSelDB( const string &vl ); — Установка выбранной БД для избирательной загрузки.
• bool saveAtExit( ); — Признак - "Сохранять конфигурацию системы при выходе".
• void setSaveAtExit( bool vl ); — Установка признака - "Сохранять конфигурацию системы при выходе".
• int savePeriod( ); — Периодичность автоматического сохранения станции в БД (секунд).
• void setSavePeriod( int vl ); — Установка периодичности автоматического сохранения станции в БД (секунд).
• string optDescr( ); — Локализованная помощь по опциям командной строки и параметрам конфигурационного файла.
• static void sighandler( int signal ); — Функция стандартного обработчика сигналов системы в целом.
• unsigned long long sysClk( ); — Расчётная частота процессора на котором функционирует система (Гц).
• void clkCalc( ); — Расчёт частоты процессора на котором работает система. Вызывается периодически для систем с переменной частотой процессора.
• unsigned long long shrtCnt( ); — Функция замера малых интервалов времени по счетчику тактов процессора. Возвращает значение счетчика тактов процессора.
• static long HZ( ); — Время системного тика процессора.
• bool cntrEmpty( ); — Проверка на отсутствие счётчиков отладки.
• double cntrGet( const string &id ); — Получение счётчика отладки <id>.
• void cntrSet( const string &id, double vl ); — Установка счетчика отладки <id> в значение <vl>.
• void cntrIter( const string &id, double vl ); — Итерация счётчика отладки <id> на значение <vl>.
• void taskCreate( const string &path, int priority, void *(*start_routine)(void *), void *arg, int wtm = 5, pthread_attr_t *pAttr = NULL, bool *startSt = NULL ); — Создание задачи (потока) с идентификатором <path>, приоритетом <priority> (-1...99), функцией задачи <start_routine> и её аргументов <arg>, а так-же ожиданием запуска пользовательской процедуры по признаку <startSt>.
• void taskDestroy( const string &path, bool *endrunCntr = NULL, int wtm = 5, bool noSignal = false ); — Удаление задачи с идентификатором <path> и командой останова <endrunCntr>. Используйте <noSignal> для предотвращения отправки задаче сигнала SIGALRM.
• static int sysSleep( float tm ); — Функция системного засыпания потока на время в секундах, вплоть до наносекунд (1e-9).
• static long long curTime(); — Текущее время в микросекундах с начала эпохи (01.01.1970).
• static void taskSleep( long long per, time_t cron = 0 ); — Функция засыпания потока по сетке абсолютного времени с периодом <per> в наносекундах или до запланированного времени <cron>.
• static time_t cron( const string &vl, time_t base = 0 ); — Планирование времени исполнения по формату стандарта Cron <vl>, начиная от базового времени <base> или от текущего времени, если база не указана.
• static bool eventWait( bool &m_mess_r_stat, bool exempl, const string &loc, time_t time = 0 ); — Функция ожидания события <exempl> для переменной <m_mess_r_stat> в течение указанного интервала времени <time> для источника <loc>.
• static string int2str( int val, IntView view = Dec ); — Преобразование целого знакового в строку вида <view>.
• static string uint2str( unsigned val, IntView view = Dec ); — Преобразования целого беззнакового в строку вида <view>.
• static string ll2str( long long val, IntView view = Dec ); — Преобразования длинного целого (64бит) в строку вида view.
• static string real2str( double val, int prec = 15, char tp = 'g' ); — Преобразования вещественного с точностью <prec> знаков и типом <tp> в строку.
• static double realRound( double val, int dig = 0, bool toint = false ); — Округление вещественного числа до указанного знака <dig> после запятой с возможностью преобразования к целому после округления <toint>.
• static string time2str( time_t tm, const string &format ); — Преобразование UNIX времени <tm> в строку, в соответствии с форматом <format> POSIX-функции strftime().
• static string time2str( double utm ); — Преобразование интервала времени, в микросекундах, в строку вида "1час 23мин 10сек".
• static string cpct2str( double cnt ); — Преобразование счётчика трафика <cnt> (байт) в строки вида "12.5КиБ".
• static string addr2str( void *addr ); — Преобразование адреса в строку.
• static void *str2addr( const string &str ); — Преобразование строки в адрес.
• static string strNoSpace( const string &val ); — Удаляет из исходной строки <val> пустые символы в начале и в конце.
• static string strSepParse( const string &path, int level, char sep, int *off = NULL ); — Разбор строки <path> на составляющие, отделённые разделительным символом <sep>, начиная со смещения <off> и контролируя смещение конца элемента в нём же.
• static string strParse( const string &str, int level, const string &sep, int *off = NULL, bool mergeSepSymb = false ); — Расширеная версия функции разбора строки strSepParse() позволяющая использовать многосимвольные разделители и объединять односимвольные.
• static string strLine( const string &str, int level, int *off = NULL ); — Разбор текста по строкам для разных способов окончания строки (CR, LF и CR/LF).
• static string pathLev( const string &path, int level, bool encode = true, int *off = NULL ); — Выделение элементов пути <path> с возможностью их декодирования, начиная со смещения <off> и контролируя смещение конца элемента в нём же.
• static string path2sepstr( const string &path, char sep = '.' ); — Преобразование пути в строку с разделителем <sep> элементов.
• static string sepstr2path( const string &str, char sep = '.' ); — Преобразование строки с разделителем <sep> элементов в путь.
• static string strEncode( const string &in, Code tp, const string &symb = " \t\n"); — Кодирование строки по указанному правилу <tp>.
• static string strDecode( const string &in, Code tp = Custom ); — Декодирование строки по указанному правилу <tp>.
• static string strMess( const char *fmt, ... ); — Формирование стоки по шаблону <fmt> и аргументам. Реализован на основе printf.
• string strCompr( const string &in, int lev = -1 ); — Компрессия строки <in> с уровнем компрессии <lev>.
• string strUncompr( const string &in ); — Декомпрессия строки <in>.
• static inline uint16_t getUnalign16(const void *p); — Невыравненное чтение беззнакового целого в 16-разрядов из буфера по смещению.
• static inline uint32_t getUnalign32(const void *p); — Невыравненное чтение беззнакового целого в 32-разряда из буфера по смещению.
• static inline uint64_t getUnalign64(const void *p); — Невыравненное чтение беззнакового целого в 64-разряда из буфера по смещению.
• static inline int getUnalignInt(const void *p); — Невыравненное чтение знакового целого из буфера по смещению.
• static inline float getUnalignFloat(const void *p); — Невыравненное чтение вещественного "float" из буфера по смещению.
• static inline double getUnalignDbl(const void *p); — Невыравненное чтение вещественного "double" из буфера по смещению.
• static float floatLE(float in); — Преобразование вещественного числа "float" из внутреннего представления в формат IEEE754 Little-Endian (LE).
• static float floatLErev(float in); — Преобразование вещественного числа "float" из формата IEEE754 Little-Endian (LE) во внутреннее представление.
• static double doubleLE(double in); — Преобразование вещественного числа "double" из внутреннего представления в формат IEEE754 Little-Endian (LE).
• static double doubleLErev(double in); — Преобразование вещественного числа "double" из формата IEEE754 Little-Endian (LE) во внутреннее представление.

Публичные атрибуты:

• static bool finalKill - Признак "Финальное разрушение объектов". Используется для принудительного отключения заблокированных объектов на финальной стадии выключения.
• const int argc - Счётчик аргументов командной строки.
• const char **argv - Буфер аргументов командной строки.
• const char **envp - Указатель на список параметров окружения.

2.2. Объект сообщений системы (TMess)

Данные:
Типы (уровни) сообщений (enum - TMess::Type):

• Debug - отладка;
• Info - информация;
• Notice - замечание;
• Warning - предупреждение;
• Error - ошибка;
• Crit - критическая ситуация;
• Alert - тревога;
• Emerg - авария.

Структура сообщения (class - TMess::SRec):

• time_t time; - время сообщения;
• int utime; - микросекунды времени сообщения;
• string categ; - категория сообщения (обычно путь внутри системы);
• Type level; - уровень сообщения;
• string mess; - сообщение.

Шаблоны:

• _(mess) - Обёртка над функцией трансляции сообщений для предоставления принятого во многих программах вызова перевода сообщений.
• FTM(rec) - Получения полного времени сообщения в микросекундах, используя два поля времени структуры сообщения.
• message(cat,lev,fmt,args...) - Формироване полного сообщения.
• mess_debug(cat,fmt,args...) - Формирование отладочного сообщения.
• mess_info(cat,fmt,args...) - Формирование информационного сообщения.
• mess_note(cat,fmt,args...) - Формирования сообщения - замечания.
• mess_warning(cat,fmt,args...) - Формирование предупредительного сообщения.
• mess_err(cat,fmt,args...) - Формирование сообщения ошибки.
• mess_crit(cat,fmt,args...) - Формирование сообщения критического состояния.
• mess_alert(cat,fmt,args...) - Формирование сообщения тревоги.
• mess_emerg(cat,fmt,args...) - Формирование сообщения аварии.

Публичные методы:

• void load( ); - Загрузка.
• void save( ); - Сохранение.
• string codeConv( const string &fromCH, const string &toCH, const string &mess); - Конвертация кодировки сообщения.
• string codeConvIn( const string &fromCH, const string &mess); - Конвертация кодировки сообщения во внутреннюю кодировку системы.
• string codeConvOut( const string &toCH, const string &mess); - Конвертация кодировки сообщения из внутренней кодировки системы.
• static const char *I18N( const char *mess, const char *d_name = NULL ); - Получение сообщения на языке системы.
• static string I18Ns( const string &mess, const char *d_name = NULL ); - Получение сообщения на языке системы.
• string lang( ); - Язык системы, в виде en_US.UTF-8.
• string lang2Code( ); - Язык системы в двухсимвольной кодировке (en).
• string lang2CodeBase( ); - Язык базовых сообщений текстовых переменных в двухсимвольной кодировке (en).
• string &charset( ); - Системная кодировка.
• int logDirect( ); - Приемники, которым направляются системные сообщения (stdout, stderr, syslog, archive);
• int messLevel( ); - Уровень, ниже которого сообщения игнорируются.
• bool isUTF8( ); - Внутренняя кодировка UTF-8.
• void setLang( const string &lang ); - Установка языка системы (локализации).
• void setLang2CodeBase( const string &vl ); - Установка языка базовых сообщений текстовых переменных в двухсимвольной кодировке (en).
• void setLogDirect( int dir ); - Установка приемников которым направляются системные сообщения. Для <dir> используется битовая маска. Где:
  1 – в syslog;
  2 – в stdout;
  4 – в stderr;
  8 – в архив.
  
• void setMessLevel( int level ); - Установка минимального уровня обрабатываемых сообщений.
• void put( const char *categ, int8_t level, const char *fmt, ... ); - Сформировать сообщение за текущее время.
• void get( time_t b_tm, time_t e_tm, vector<TMess::SRec> &recs, const string &category = "", int8_t level = Debug ); - Запросить сообщения из архива за промежуток времени <b_tm> - e_tm в соответствии с шаблоном категории <category> и минимальным уровнем <level>.

2.3. Объект подсистемы (TSubSYS)

Публичные методы:

• TSubSYS( const char *id, const char *name, bool mod = false ); — Инициализирующий конструктор. Признак <mod> указывает, что подсистема модульная.
• string subId( ); — Идентификатор подсистемы.
• string subName( ); — Локализованное имя подсистемы.
• bool subStartStat( ); — Признак исполнения подсистемы.
• bool subModule( ); — Признак модульности подсистемы.
• virtual int subVer( ); — Версия подсистемы.
• virtual void subStart( ); — Запуск подсистемы.
• virtual void subStop( ); — Останов подсистемы.
• void modList( vector<string> &list ); — Список <list> модулей модульной подсистемы.
• bool modPresent( const string &name ); — Проверка на наличие указанного модуля <name>.
• void modAdd( TModule *modul ); — Добавление/регистрация модуля <modul>.
• void modDel( const string &name ); — Удаление модуля <name>.
• AutoHD<TModule> modAt( const string &name ); — Подключение к модулю <name>.
• virtual void perSYSCall( unsigned int cnt ); — Периодичный вызов из системного потока, с периодичностью 10 секунд и секундным счётчиком <cnt>.
• TSYS &owner( ); — Система - владелец подсистемы.

2.4. Объект модуля (TModule)

Данные:
Структура данных идентифицирующая модуль (class - TModule::SAt):

• SAt( const string &iid, const string &itype = "", int itver = 0 ); - инициализирующий конструктор;
• bool operator==( const TModule::SAt &amst ) const; - функция сравнения идентификаторов модулей;
• string id; - идентификатор модуля;
• string type; - тип модуля (подсистема);
• int t_ver; - версия типа модуля (подсистемы) для которой модуль разработан.

Структура экспортируемых функций (class - TModule::ExpFunc):

• string prot; - прототип функции;
• string dscr; - локализованное описание функции;
• void (TModule::*ptr)(); - относительный адрес функции (относительно объекта модуля).

Публичные методы:

• TModule( const string &id ); - Инициализирующий конструктор модуля <id>.
• string modId( ); - Идентификатор модуля.
• string modName( ); - Локализованное имя модуля.
• virtual void modStart( ); - Запуск модуля.
• virtual void modStop( ); - Останов модуля.
• virtual void modInfo( vector<string> &list ); - Список <list> информационных элементов модуля.
• virtual string modInfo( const string &name ); - Получение содержимого указанного информационного элемента <name>.
• virtual void perSYSCall( unsigned int cnt ); — Периодичный вызов из системного потока, с периодичностью 10 секунд и секундным счётчиком <cnt>.
• void modFuncList( vector<string> &list ); - Список <list> экспортируемых функций модуля.
• bool modFuncPresent( const string &prot ); - Проверка на наличие указанной функции по её прототипу <prot>.
• ExpFunc &modFunc( const string &prot ); - Получить информацию об экспортируемой функции модуля <prot>.
• void modFunc( const string &prot, void (TModule::**offptr)() ); - Получение относительного адреса <offptr> экспортируемой функции <prot>.
• const char *I18N( const char *mess ); - Локализация модульного сообщения <mess> в соответствии с текущей локалью.
• TSubSYS &owner( ); - Подсистема - владелец модуля.

Защищённые атрибуты:

• string mName; - Имя модуля.
• string mDescr; - Описание модуля.
• string mType; - Тип модуля.
• string mVers; - Версия модуля.
• string mAutor; - Автор модуля.
• string mLicense; - Лицензия модуля.
• string mSource; - Источник/происхождение модуля.

Защищённые методы:

• void modFuncReg( ExpFunc *func ); - Регистрация экспортируемых модулем функций.