OpenSCADAWiki : Doc / VCA / part 4 / part 14

API пользовательского программирования

API пользовательского программирования движка визуализации представлено непосредственно объектами OpenSCADA, формирующие пользовательский интерфейс, а именно "Сеансом" и "Виджетами/страницами". Для пользователя эти объекты предоставляют набор функций управления:

Объект "Сеанс" ( this.ownerSess() )

string user( ) — текущий пользователь сеанса.
int alrmQuittance( int quit_tmpl, string wpath = "", bool ret = false ) — квитирование нарушений wpath с шаблоном quit_tmpl. Если wpath пустая строка то производится глобальное квитирование. В строке wpath, через символ ';', могут быть перечислены адреса нескольких виджетов. При установке ret осуществляется возврат квитирования.
int reqTm( ) — время последнего запроса.
string reqUser( ) — пользователь последнего запроса.
string reqLang( ) — язык последнего запроса.
int userActTm( ) — время последнего действия пользователя.

Объект "Виджет" (this)

TCntrNodeObj ownerSess( ) — получить объект сеанса данного виджета.
TCntrNodeObj ownerPage( ) — получить объект родительской страницы данного виджета.
TCntrNodeObj ownerWdg( bool base = false ) — получить родительский виджет данного виджета. При указании base будет возвращены и объекты страниц.
TCntrNodeObj wdgAdd( string wid, string wname, string parent ) — добавление виджета wid с именем wname на основе библиотечного виджета parent.

//Добавить новый виджет на основе виджета текстового примитива
nw = this.wdgAdd("nw", "Новый виджет", "/wlb_originals/wdg_Text");
nw.attrSet("geomX", 50).attrSet("geomY", 50);

bool wdgDel( string wid ) — удаление виджета wid.
TCntrNodeObj wdgAt( string wid, bool byPath = false ) — подключение к дочернему или глобальному, посредством пути byPath, виджету. В случае глобального подключения можно использовать абсолютный или относительный путь к виджету. Точкой отсчёта абсолютного адреса выступает объект корня модуля "VCAEngine", а значит первым элементом абсолютного адреса является идентификатор сеанса, который опускается. Относительный адрес берёт отсчёт от текущего виджета. Специальным элементом относительного адреса является элемент вышестоящего узла "..".
bool attrPresent( string attr ) — проверка атрибута виджета attr на факт присутствия.
ElTp attr( string attr, bool fromSess = false ) — получение значения атрибута виджета attr или из сеанса fromSess. Для отсутствующих атрибутов возвращается пустая строка.
TCntrNodeObj attrSet( string attr, ElTp vl, bool toSess = false ) — установка атрибута виджета attr в значение vl, или в сеанс toSess. Возвращается текущий объект для конкатенации функций установки.
string link( string attr, bool prm = false ) — получение ссылки для атрибута виджета attr. При установке prm запрашивается ссылка для группы атрибутов (параметр), представленных указанным атрибутом.
string linkSet( string attr, string vl, bool prm = false ) — установка ссылки для атрибута виджета attr. При установке prm осуществляется установка ссылка для группы атрибутов (параметр), представленных указанным атрибутом.

//Установить ссылку восьмого тренда параметром
this.linkSet("el8.name", "prm:/LogicLev/experiment/Pi", true);

string mime( string addr, string type = "" ) — получение "mime" объекта по адресу addr (прямая ссылка на ресурс или атрибут виджета с этой ссылкой) с типом в type, из таблицы сеанса или источника. Предназначено для редактирования "mime" объекта и подстановки его в контексте сеанса, например, изображений SVG.
int mimeSet( string addr, string data, string type = "" ) — установка "mime" объекта data с типом type по адресу addr.
int messDebug( string mess ); int messInfo( string mess ); int messNote( string mess ); int messWarning( string mess ); int messErr( string mess ); int messCrit( string mess ); int messAlert( string mess ); int messEmerg( string mess ); — формирование системного сообщения mess с категорией как путь к данному виджету.

Объект "Виджет", примитива "Документ" (this)

string getArhDoc( int nDoc) — получить текст документа архива на глубине nDoc (0-{aSize-1}).

Устаревшее API представляется группой функций непосредственно в модуле движка СВУ. Вызов этих функций из скриптов виджетов может осуществляться прямо по идентификатору функции, поскольку их область имён указывается для контекста скриптов виджетов:

Список виджетов (WdgList)
Описание: Возвращает список виджетов в контейнере виджетов или список дочерних виджетов. Если установлено pg, то возвращается список страниц для проектов и сеансов.
Параметры:

ID	Имя	Тип	Режим	По умолчанию
list	Список	Строка	Возврат
addr	Адрес	Строка	Вход
pg	Страницы	Bool	Вход	0

Присутствие узла (NodePresent)
Описание: Проверка на присутствие узла, включая виджеты, атрибуты и другие.
Параметры:

ID	Имя	Тип	Режим	По умолчанию
rez	Результат	Bool	Возврат
addr	Адрес	Строка	Вход

Список атрибутов (AttrList)
Описание: Возвращает список атрибутов виджета. Если установлен noUser тогда возвращаются только не пользовательские атрибуты.
Параметры:

ID	Имя	Тип	Режим	По умолчанию
list	Список	Строка	Возврат
addr	Адрес	Строка	Вход
noUser	Без пользовательских	Bool	Вход	1

Запрос атрибута (AttrGet)
Описание: Запрос значения атрибута виджета. Запрос может осуществляться как указанием полного адреса атрибута в addr, так и отдельно адреса виджета в addr, а идентификатора атрибута в attr.
Параметры:

ID	Имя	Тип	Режим	По умолчанию
val	Значение	Строка	Возврат
addr	Адрес	Строка	Вход
attr	Атрибут	Bool	Вход

Установка атрибута (AttrSet)
Описание: Установка значения атрибута виджета. Установка может осуществляться как указанием полного адреса атрибута в addr, так и отдельно адреса виджета в addr, а идентификатора атрибута в attr.
Параметры:

ID	Имя	Тип	Режим	По умолчанию
addr	Адрес	Строка	Вход
val	Значение	Строка	Вход
attr	Атрибут	Bool	Вход

Пользователь сеанса (SesUser)
Описание: Возвращает пользователя сеанса по пути к виджету сеанса.
Параметры:

ID	Имя	Тип	Режим	По умолчанию
user	Пользователь	Строка	Возврат
addr	Адрес	Строка	Вход

Сервисные интерфейсы OpenSCADA

Сервисные интерфейсы это интерфейсы доступа к системе OpenSCADA посредством интерфейса управления OpenSCADA из внешних систем. Данный механизм положен в основу всех механизмов обмена внутри OpenSCADA, реализованных посредством слабых связей и стандартного протокола обмена OpenSCADA.

Доступ к значениям атрибутов элементов визуализации (виджеты)

С целью предоставления унифицированного, группового и сравнительно быстрого доступа к значениям атрибутов визуальных элементов предусмотрена сервисная функция визуального элемента "/serv/attr" и команды получения/установки значений атрибутов: <get path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/> и <set path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/>.

Таблица. Атрибуты команд получения/установки атрибутов визуальных элементов

Id	Имя	Значение
Команда запроса визуальных атрибутов виджета: <get path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/>
tm	Время/счётчик изменений	Установка времени/счётчика изменений для запроса только изменившихся атрибутов.
<el id="{attr}" p="{a_id}">{val}</el>	Формирование дочерних элементов с результатами атрибутов	В дочернем элементе указываются: строковых идентификатор attr атрибута, индекс a_id атрибута и его значение val.
Команда установки визуальных атрибутов виджета: <set path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr"/>
<el id="{attr}">{val}</el>	Установка атрибутов	В дочерних элементах указывается идентификатор атрибута attr и его значение val.
Команда активации-создания специфичного для визуализатора атрибута: <activate path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattr/{attrId}" aNm="{Name}" aTp="{Type} aFlg="{Flags}"/>
attrId	Идентификатор атрибута
aNm	Имя атрибута
aTp	Тип атрибута
aFlg	Флаги атрибута

Групповой доступ к значениям атрибутов элементов визуализации (виджетам)

С целью оптимизации трафика сетевого взаимодействия путём исключения мелких запросов, а использования одного, но большого запроса предусмотрен групповой запрос значений атрибутов визуальных элементов. Группировка данного запроса подразумевает запрос атрибутов всей ветви виджета, включая и вложенные элементы. Для данного запроса предусмотрена сервисная команда "/serv/attrBr". Запрос данной сервисной команды эквивалентен сервисной команде "/serv/attr" и выглядит следующим образом:
<get path="/UI/VCAEngine/{wdg_addr}/%2fserv%2fattrBr"/>

tm — Время/счётчик изменений. Установка времени/счётчика изменений для запроса только изменившихся атрибутов.

Результат:

<el id="{attr}" p="{a_id}">{val}</el> — элементы с результатами атрибутов. В элементе указываются: строковый идентификатор attr атрибута, индекс a_id атрибута и его значение val.
<w id="{wid}" lnkPath="{lnk_path}">{childs+attrs}</w> — элементы с дочерними виджетами и их атрибутами. В элементе указываются идентификатор дочернего виджета wid и путь виджета на который ссылается данный виджет если он является ссылкой lnk_path.

Доступ к страницам сеанса

С целью унификации и оптимизации доступа к страницам предусмотрена сервисная функция сеанса "/serv/pg" и команды запроса перечня открытых страниц <openlist path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/>; открытия страницы <open path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/>; и закрытия страницы <close path="/UI/VCAEngine/ses_{Session}/%2fserv%2fpg"/>.

Результатом запроса перечня открытых страниц являются дочерние элементы <el>{OpPage}</el>, содержащие полный путь открытой страницы. Кроме перечня открытых страниц запрос возвращает значение текущего счётчика вычисления сеанса в атрибуте tm. Если данный атрибут устанавливается при запросе, то для каждой открытой страницы возвращается список изменённых с момента указанного значения счётчика виджетов открытой страницы.

Управление сигнализацией

Для предоставления механизма глобального контроля за сигнализацией сеанса предусмотрена сервисная функция сеанса "/serv/alarm" и команды запроса статуса сигналов <get path="/UI/VCAEngine/ses_{Session}/%2fserv%2falarm"/>; и квитирование сигналов <quittance path="/UI/VCAEngine/ses_{Session}/%2fserv%2falarm"/>.

Запрос статуса сигналов возвращает обобщённое состояние сигналов, а так-же ресурс уведомления, если атрибут "mode" равен "resource". Результатом запроса ресурса уведомления обычно является звуковой файл, для воспроизведения, в это-же время обеспечивается отслеживание последовательности сигнализации и квитирования отдельных ресурсов сообщений.

Запрос на квитирование выполняет квитирование указанного виджета, атрибут wdg, в соответствии с шаблоном, атрибут tmpl.

Манипуляция сеансами проектов

Для предоставления унифицированного механизма манипуляции сеансами визуализаторам СВУ в модуле движка СВУ (VCAEngine) предусмотрена сервисная функция "/serv/sess" и команды запроса перечня открытых сеансов, подключения/создания нового сеанса и отключения/удаления сеанса: <list path="/UI/VCAEngine/%2fserv%2fsess"/>, <connect path="/UI/VCAEngine/%2fserv%2fsess"/> и <disconnect path="/UI/VCAEngine/%2fserv%2fsess"/> соответственно.

Таблица. Атрибуты команд механизма манипуляции сеансами

Id	Имя	Значение
Команда запроса перечня открытых сеансов для проекта: <list path="/UI/VCAEngine/%2fserv%2fsess"/>
prj	Указание проекта	Указывает проект, для которого возвращать перечень открытых сеансов.
<el>{Session}</el>	Контроль перечня сеансов	В дочерних элементах указываются сеансы, открытые для запрошенного проекта.
Команда подключения/открытия сеанса: <connect path="/UI/VCAEngine/%2fserv%2fsess"/>
sess	Установка и контроль имени сеанса	Если атрибут определён, то производится подключение к существующему сеансу, иначе создание нового сеанса. В случае открытия нового сеанса в данный атрибут помещается его имя.
prj	Установка имени проекта	Используется для открытия нового сеанса для указанного проекта и если атрибут sess не указан.
Команда отключения/закрытия сеанса: <disconnect path="/UI/VCAEngine/%2fserv%2fsess"/>
sess	Установка имени сеанса	Указывает имя сеанса от которого выполняется отключение или закрытие. Сеансы, не являющиеся фоновыми и к которым ни один из визуализаторов не подключен, автоматически закрываются.

Групповой запрос дерева библиотек виджетов

С целью оптимизации производительности локального и особенно сетевого взаимодействия предусмотрена сервисная функция "/serv/wlbBr" и команда запроса дерева библиотек виджетов: <get path="/UI/VCAEngine/%2fserv%2fwlbBr"/>. Результатом запроса является дерево с элементами библиотек виджетов, теги wlb. Внутри тегов библиотек виджетов содержаться тег иконки ico и теги виджетов библиотеки w. Теги виджетов, в свою очередь, содержат тег иконки и теги дочерних виджетов cw.

OpenSCADAWiki: Doc/VCA/part4/part14 ...