Инструкция по использованию SDK TERA

Аннотация

SDK TERA применяется для протокола TERA версии 7.0 и выше.

SDK TERA предоставляет API для интеграции с протоколом TERA и позволяет организовать двусторонний обмен данными между TERA-сервером и TERA-клиентом.

Пакеты установки SDK TERA размещены в Интернет-репозитории: https://repos.termidesk.ru/. При использовании ОС Astra Linux Special Edition возможно подключение Интернет-репозитория в ОС (см. подраздел Получение пакетов установки).

Начало работы

Для работы с API через SDK TERA нужно подготовить среду функционирования:

Поддерживаемые ОС для установки SDK TERA совпадают с ОС, поддерживаемыми в протоколе TERA.

  • на узле TERA-сервера:

    • установить протокол удаленного доступа TERA на поддерживаемую ОС (см. подразделы ОС Astra Linux Special Edition и ОС Microsoft Windows);

    • ОС Linux: установить пакеты libtera-sdk и libtera-sdk-dev;

    • ОС Microsoft Windows: установить пакет tera-sdk;

  • на узле TERA-клиента:

    • установить компонент «Клиент» и ПО Termidesk Viewer на поддерживаемую ОС (см. примеры команд установки в подразделах ОС Astra Linux Special Edition и ОС Microsoft Windows);

    • ОС Linux: установить пакеты libtera-sdk и libtera-sdk-dev;

    • ОС Microsoft Windows: установить пакет tera-sdk.

Для установки на ОС Astra Linux Special Edition нужно выполнить:

sudo apt install <путь_к_пакету_tera-port>

Для установки на ОС Microsoft Windows нужно:

  • запустить установочный файл TERA tera-sdk и нажать экранную кнопку [Далее];

  • принять лицензионное соглашение и нажать экранную кнопку [Далее] (см. рисунок Лицензионное соглашение);

image
Рисунок 1. Лицензионное соглашение

  • выбрать каталог установки или оставить значение по умолчанию и нажать экранную кнопку [Далее] (см. рисунок Каталог установки);

image
Рисунок 2. Каталог установки
image
Рисунок 3. Подтверждение установки

  • в окне запроса контроля учетных записей нажать экранную кнопку [Да];

  • дождаться завершения установки и нажать экранную кнопку [Готово].

Настройка SDK TERA

Для корректной работы SDK TERA на узле TERA-сервера нужно выполнить настройки:

  • для ОС Astra Linux Special Edition:

    • при использовании протокола TERA в среде ВМ - отредактировать файл /etc/X11/xorg.conf.d/30-teraqxl.xorg.conf и указать количество используемых последовательных портов в параметре TeraPortCount (см. подраздел Конфигурационный файл 30-teraqxl.xorg.conf);

    • при использовании протокола TERA в среде физической машины - отредактировать файл /etc/xdg/x11tera/x11tera.conf и указать количество используемых последовательных портов в параметре port-count (см. подраздел Конфигурационный файл x11tera.conf);

  • для ОС Microsoft Windows:

Использование SDK TERA

Исходный код службы tera-port-service предназначен для демонстрации механизмов интеграции протокола TERA, может использоваться в качестве шаблона при разработке пользовательских служб, а также применяться в тестовых целях.

Для использования SDK TERA нужно:

  • запустить службу tera-port-service на узле TERA-сервера:

tera-port-service vrm 0

где:

vrm - аргумент для запуска службы на узле TERA-сервера;

0 - количество используемых последовательных портов;

В среде ОС Microsoft Windows вызов команды должен содержать путь к исполняемому файлу tera-port-service.exe. Пример:

"C:\Program Files\UVEON\TERA SDK\tera-port-service.exe" vrm 0

  • запустить службу tera-port-service на узле TERA-клиента:

tera-port-service arm 0

где:

arm - аргумент для запуска службы на узле TERA-клиента;

0 - количество используемых последовательных портов;

  • убедиться в доступности перенаправленных портов. Для этого в интерфейсе командной строки ввести произвольные символы и отправить их нажатием клавиши <Enter>;

  • пример сообщения об успешной отправке данных:

sent 33 of 33 bytes

  • пример сообщения об успешном получении данных:

got '<значение>' len 33

Доступные функции API для перенаправления портов

Открытие последовательного порта TERA-сервера

Код функции:

TeraPort* tera_port_open (const TeraPortData* data);

Функция открывает последовательный порт TERA-сервера и начинает ожидание входящих подключений.

Параметры функции:

  • data - параметр указывает на структуру TeraPortData.

Возвращаемые значения:

  • указывает на экземпляр TeraPort при успешном открытии;

  • в случае ошибки возвращает значение NULL.

Обработка событий:

  • при возникновении ошибки срабатывает обратный вызов структуры TeraPortData;

  • при подключении или отключении TERA-клиента срабатывает обратный вызов функций подключения или отключения.

Открытие последовательного порта TERA-клиента

Код функции:

TeraPort* tera_port_connect (const TeraPortData* data);

Функция открывает последовательный порт TERA-клиента и устанавливает соединение с TERA-сервером по заданным параметрам.

Параметры функции:

  • data - параметр указывает на структуру TeraPortData.

Возвращаемые значения:

  • указывает на экземпляр TeraPort при успешном подключении;

  • в случае ошибки возвращает значение NULL.

Обработка событий:

  • при возникновении ошибки срабатывает обратный вызов функции обработки ошибок;

  • при подключении или отключении TERA-сервера срабатывает обратный вызов функций подключения или отключения.

Передача данных

Код функции:

ssize_t tera_port_send (TeraPort* port, const char* data, size_t len);

Функция организует передачу данных через активное соединение.

Параметры функции:

  • port - указывает на экземпляр TeraPort при активном соединении;

  • data - буфер с передаваемыми данными;

  • len - количество передаваемых данных (в байтах).

Возвращаемые значения:

  • положительное число - количество переданных данных (в байтах);

  • отрицательное число - код ошибки.

Получение данных

Код функции:

ssize_t tera_port_recv (TeraPort* port, char* data, size_t len);

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

Параметры функции:

  • port - указывает на экземпляр TeraPort при активном соединении;

  • data - буфер для записи полученных данных;

  • len - количество полученных данных (в байтах).

Возвращаемые значения:

  • положительное число - количество полученных данных (в байтах);

  • отрицательное число - код ошибки.

Закрытие порта

Код функции:

int tera_port_close (TeraPort* port);

Функция закрывает последовательный порт TERA-сервера или TERA-клиента.

Параметры функции:

  • port - указывает на экземпляр TeraPort, подлежащий закрытию.

Возвращаемые значения:

  • 0 - порт успешно закрыт;

  • отрицательное число - код ошибки.