From OpenSCADAWiki
Jump to: navigation, search
This page is a translated version of the page Modules/HTTP and the translation is 97% complete.

Other languages:
English • ‎mRussian • ‎Українська
Модуль Имя Версия Лицензия Источник Языки Платформы Тип Автор Описание
HTTP HTTP-реализация 3.8 GPL2 prot_HTTP.so en,uk,ru,de x86,x86_64,ARM Protocol Roman Savochenko
  Maxim Lysenko (2009) — the page initial translation
Provides support for the HTTP protocol for WWW-based user interfaces.
- implementation the HEAD request for true support the "HTTP range requests".

Модуль транспортного протокола HTTP предназначен для реализации поддержки сетевого протокола HTTP(Hypertext Transfer Protocol) в OpenSCADA.

Протокол HTTP используется для передачи содержимого WWW. Так, через HTTP передаются следующие типы документов: html, xhtml, png, javascript и многие другие. Поддержка HTTP в OpenSCADA, в комплексе с транспортом Sockets, позволяет реализовывать различные пользовательские функции на основе WWW интерфейса. Модуль реализует два основных метода протокола HTTP: GET и POST. Модуль обеспечивает контроль целостности HTTP-запросов и, совместно с транспортом Sockets, позволяет "собирать" целостные запросы из их фрагментов, а также обеспечивать удержание соединения "живым" (Keep-Alive).

Для гибкого подключения пользовательских интерфейсов к данному модулю, используется модульный механизм в рамках самого этого модуля. В роли модулей используются модули подсистемы "Пользовательские интерфейсы" с дополнительным информационным полем "SubType", имеющим значение "WWW".

В запросах к Web ресурсам принято использовать URL(Universal Resource Locator). Следовательно, URL передаётся как основной параметр через HTTP. Первый элемент запрашиваемого URL используется для идентификации модуля UI. Например, URL "http://localhost:10002/WebCfg" означает обращение к модулю "WebCfg" на хосте "http://localhost:10002". В случае ошибочного указания идентификатора модуля, или при обращении вообще без идентификатора, модуль генерирует информационный диалог о входе и выбор одного из доступных пользовательских интерфейсов. Пример диалога показан на рисунке 1.

Рис.1. Диалог выбора модуля WWW-интерфейса.

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

Язык конечного пользователя интерфейса определяется путём и в последовательности:

  • URL параметр "lang".
  • Язык пользователя, который вошёл.
  • Язык Web-браузера из HTTP свойства "Accept-Language".
  • Общий язык процесса OpenSCADA.

Полученный таким образом язык используется для построения интерфейсов этого модуля и передаётся WWW под-модулям в HTTP свойстве "oscd_lang", через аргумент "vars" функций "GET" и "POST".

Для конфигурации и управления этим модулем, предоставляется конфигурационная страница интерфейса управления OpenSCADA (Рис.3) где Вы можете осуществлять:

  • Контроль за активными сеансами аутентификации.
  • Конфигурацию:
    • Правила доступа для запрета и разрешения. Каждая строка является отдельным правилом и в каждом правиле доступа Вы можете использовать шаблоны, вроде "*/WebVision/*", и регулярные выражения, вроде "/[^/]+/WebVision/.+/". Полезные записи для:
      • Запрещено:
      • Разрешено:
        • "*" — всё, исключая запрещённое;
        • "/^[^/]+/[^/]*$/" — страницы модуля со всеми их ресурсами;
        • "*/login/*" — страница авторизации-входа;
        • "/^[^/]+/WebVision/[^/]*($|\?)/" — основная страница модуля WebVision без доступа к проектам СВУ;
        • "/^[^/]+/WebVision/.+_aviariesOril\d*/.*/" — проект СВУ "aviariesOril" модуля WebVision.
    • HTML-шаблон пользовательского интерфейса и пользовательской главной страницы. В полях HTML-шаблона должен указываться адрес к файлу HTML/XHTML, который будет использован при формировании внутренних-сервисных интерфейсов и главной страницы. Внутренние-сервисные интерфейсы, это например: выбор модулей, страница авторизации и подобное у WEB-модулей. От шаблона требуется корректность XHTML, которая позволяет разобрать файл XML-парсером, а также наличие метки "#####CONTEXT#####" в месте размещения динамического содержимого, что обязательно для внутренних-сервисных интерфейсов. Ресурсные файлы шаблонов представлены изображениями, CSS и JavaScript файлами, и которые ищутся от директории в которой указано размещение файла шаблона и от текущей директории. В случае обнаружения ошибок в шаблоне, будет использован стандартный встроенный интерфейс. Для другого, по языку, файла шаблона, Вы можете добавить суффикс языка в конец этого файла "{Мой Шаблон}_{язык}.html", однако выбирать в конфигурационных полях основной-базовый файл шаблона "{Мой Шаблон}.html". В качестве примера шаблонов Вы можете посмотреть такие наиболее используемые:
    • БД активных сеансов аутентификации предусматривает внешнюю таблицу активных сеансов аутентификации — "HTTP_AuthSessions", которая включается для непустого значения и предоставляет возможность совместного использования аутентификации между разными станциями OpenSCADA и её короткого сохранения на время выключения станции.
    • Пространство генерации UID аутентификации, доступное с совместной таблицей сеансов аутентификации для гарантирования отличия "печенья" (cookie) для различных процессов OpenSCADA.
    • Время жизни, перечень пользователей разрешённых к аутентификации и установка автоматического входа.
Рис.3. Страница настройки модуля.

1 Аутентификация

Модулем поддерживается аутентификация в OpenSCADA при предоставлении доступа к модулям WEB-интерфейсов (рис.2).

Рис.2. Диалог авторизации в OpenSCADA.

Аутентификация этим модулем осуществляется "печеньем" (cookies) с динамическим названием и пространством ИД пользователя, где название "печенья" (cookie) "oscd_UID" и используется пространство ИД пользователя в работе с совместной таблицей сеансов аутентификации, и название "oscd_UID_{PrjNm}" в роботі без неё.

Для облегчения работы с Web-интерфейсами модуль предусматривает возможность автоматического входа от имени указанного пользователя. Конфигурация автоматического входа осуществляется на странице настройки модуля (рис.3). Автоматический вход осуществляется по совпадению адреса, указанного в колонке "Адреса", и от имени пользователя, указанного в колонке "Пользователь".

Для большей безопасности Вы можете определить только Web-пользователей, в перечне пользователей разрешённых к аутентификации.

2 Модули WEB-интерфейса

Модули пользовательского интерфейса (UI), предназначенные для совместной работы с модулем HTTP, должны устанавливать информационное поле "SubType" значением "WWW" и поле "Auth" значением "1", если модуль требует аутентификации при входе. Для связи модуля HTTP и модулей UI используется расширенный механизм коммуникации. Этот механизм предусматривает экспорт интерфейсных функций. В данном случае, UI модули должны экспортировать функции:

  • void HTTP_GET(const string &url, string &page, vector<string> &vars, const string &user, TProtocolIn *iprt); ИЛИ
void HttpGet( const string &url, string &page, const string &sender, vector<string> &vars, const string &user ); — Метод GET c параметрами:
url — адрес запроса;
page — страница с ответом;
sender — адрес отправителя;
vars — переменные запроса;
user — пользователь, может содержать предыдущего пользователя во второй строке;
iprt — ссылка на объект входной части протокола.
  • void HTTP_POST(const string &url, string &page, vector<string> &vars, const string &user, TProtocolIn *iprt); ИЛИ
void HttpPost( const string &url, string &page, const string &sender, vector<string> &vars, const string &user ); — метод POST c параметрами:
url — адрес запроса;
page — страница с ответом и содержимым тела запроса POST;
sender — адрес отправителя;
vars — переменные запроса;
user — пользователь, может содержать предыдущего пользователя во второй строке;
iprt — ссылка на объект входной части протокола.

Далее, в случае поступления HTTP запроса "GET" будет вызываться функция "HTTP_GET" или "HttpGet", а в случае запроса "POST" будет вызываться функция "HTTP_POST" или "HttpPost", в соответствующем модуле UI.

3 Функция выходных запросов пользовательского API

Функция исходящих запросов (messIO()) оперирует обменом содержимым HTTP-запросов, завёрнутыми в XML-пакеты. Структура запроса имеет вид:

<req Host="host" URI="uri">
  <prm id="pId">pVal</prm>
  <cnt name="cName" filename="cFileName">
    <prm id="cpId">cpVal</prm>
    cVal
  </cnt>
  reqVal
</req>
Где:
  • req — метод запроса, поддерживаются методы "GET" и "POST".
  • host — адрес узла http-сервера в формате {HostAddr}:{HostIp}. Если данное поле опущено то используется адрес узла, указанный в поле адреса транспорта.
  • uri — адрес ресурса на http-сервере, обычно файл или директория.
  • pId, pVal — идентификатор и значение дополнительного http-параметра. Http-параметров может быть указано множество, отдельными prm тегами.
  • cName, cFileName, cVal — имя, имя-файла и значение элемента содержимого POST-запроса. Элементов содержимого может быть указано множество, отдельными cnt тегами.
  • cpId, cpVal — идентификатор и значение дополнительного параметра содержимого. Параметров содержимого может быть указано множество, отдельными prm тегами;
  • reqVal — одиночное содержимое POST запроса.

Результатом запроса является ответ со структурой:

<req Host="host" URI="uri" err="err" Protocol="prt" RezCod="rCod" RezStr="rStr">
  <prm id="pId">pVal</prm>
  respVal
</req>
Где:
  • req — метод запроса.
  • host — адрес узла http-сервера.
  • uri — адрес ресурса.
  • err — ошибка, возникшая во время запроса. В случае успешного запроса это поле пустое.
  • RezCod, RezStr — результат запроса в виде кода и текста.
  • pId, pVal — идентификатор и значение дополнительного http-параметра ответа. Http-параметров может быть множество, определённые отдельными prm тегами.
  • respVal — содержимое ответа.

Приведём формирование GET и POST запросов на языке JavaLikeCalc.JavaScript, в качестве примера использования данной функции в пользовательских процедурах:

//GET запрос HTML страницы
req = SYS.XMLNode("GET");
req.setAttr("URI","/");
SYS.Transport.Sockets.out_testHTTP.messIO(req,"HTTP");
test = req.text();

//GET запрос и сохранение файла
req = SYS.XMLNode("GET");
req.setAttr("URI","/oscadaArch/Work/openscada-0.9-r2188.tar.lzma");
SYS.Transport.Sockets.out_testHTTP.messIO(req,"HTTP");
if(!req.attr("err").length) SYS.fileWrite("/var/tmp/recvFile.tmp", req.text());

//POST запрос
req = SYS.XMLNode("POST");
req.setAttr("URI","/WebUser/FlowTec.txt");
cntNode = req.childAdd("cnt").setAttr("name","pole0").setAttr("filename","Object2-k001-100309-17.txt");
cntNode.childAdd("prm").setAttr("id","Content-Type").setText("text/plain");
cntText = "Object2-k001\r\n";
cntText += "\r\n";
cntText += "v002\r\n";
cntText += " n1\r\n";
cntText += "  09.03.10 16   Polnyj    7155.25    216.0  32.000  17.5\r\n";
cntText += "v005\r\n";
cntText += " n1\r\n";
cntText += "  09.03.10 16   Polnyj     188.81    350.0   4.000  40.0\r\n";
cntText += "\r\n";
cntNode.setText(cntText);
SYS.Transport.Sockets.out_testHTTP.messIO(req,"HTTP");

//POST запрос с одиночным содержимым
req = SYS.XMLNode("POST");
req.setAttr("URI","/WebUser/FlowTec.txt");
req.childAdd("prm").setAttr("id","Content-Type").setText("text/plain");
cntText = "Object2-k001\r\n";
cntText += "\r\n";
cntText += "v002\r\n";
cntText += " n1\r\n";
cntText += "  09.03.10 16   Polnyj    7155.25    216.0  32.000  17.5\r\n";
cntText += "v005\r\n";
cntText += " n1\r\n";
cntText += "  09.03.10 16   Polnyj     188.81    350.0   4.000  40.0\r\n";
cntText += "\r\n";
req.setText(cntText);
SYS.Transport.Sockets.out_testHTTP.messIO(req,"HTTP");

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

Входная часть объекта модуля (SYS.Protocol.HTTP.{In})

  • bool setUser( string user ) — меняет пользователя связанного с идентификатором сеанса аутентификации.
    • user — пользователя для смены.
  • bool pgAccess(string URL) — проверяет доступность страницы, определённой в URL.
    • URL — URL страницы, которая проверяется.
  • string pgCreator(string cnt, string rcode = "200 OK", string httpattrs = "Content-Type: text/html;charset={SYS}", string htmlHeadEls = "", string forceTmplFile = "") — формирует страницу или ресурс из содержимого cnt, обёрнутого в HTTP с результатом rcode, с дополнительными атрибутами HTTP httpattrs, дополнительным элементом заголовка HTML htmlHeadEls и использованием файла шаблона forceTmplFile.
    • cnt — содержимое страницы или ресурса (изображения, XML, CSS, JavaScript, ...);
    • rcode — результирующий код HTTP, вроде "200 OK"; пустое значение выключает добавление HTTP заголовка;
    • httpattrs — дополнительные атрибуты HTTP, в основном это "Content-Type" со значением по умолчанию "text/html;charset={SYS}"; только для "Content-Type: text/html" будет осуществляться заворачивание во внутренний/сервисный, или определённый forceTmplFile, HTML-шаблон;
    • htmlHeadEls — дополнительный тег заголовка HTML, в основном это META с "Refresh" для указанного URL;
    • forceTmplFile — файл прямо определённого шаблона для перекрытия внутреннего/сервисного или главной страницы.