Руководство TrueConf VideoSDK

# Встроенный HTTP сервер

# Общее описание

Поскольку VideoSDK/Room управляется удаленно c помощью клиент-серверного протокола WebSocket, в состав приложения входит HTTP сервер. Он запускается автоматически при запуске приложения. Порт для него также будет выбран автоматически и его значение можно будет получить с помощью API метода getHttpServerSettings. Но вы можете указать порт вручную. Для этого при запуске VideoSDK/Room задайте нужное значение в параметре командной строки --httpport. Если запуск HTTP сервера на указанном порту не удался, то приложение не запустится и в логи будут выведены соответствующие сообщения.

HTTP сервер используется для следующего функционала:

Каждый функционал поддерживает свой набор HTTP методов, с которым можно ознакомиться в соответствующем разделе. Все без исключения запросы должны передавать параметр token, который создается и получается:

  • в процессе авторизации – значение поля tokenForHttpServer в ответе на успешную авторизацию командой auth;

  • в процессе перехода из типа управления администратор в тип управления пользователь – значение поля tokenForHttpServer в ответе на успешное выполнение команды auth;

  • при успешном выполнении команды getTokenForHttpServer – значение поля token;

  • при установке нового типа защиты для входа в управление – значение поля tokenForHttpServer в ответе на успешное выполнение команды setAuthParams.

Время жизни токена – 5 минут, или до выключения приложения, или до получения нотификации authorizationNeeded. Если управление осуществляется с выставленной защитой По пину, тогда время жизни токена не истекает до перезагрузки приложения. Очистка токенов может быть сделана с помощью выполнения команды clearTokens.

Вы можете управлять состоянием HTTP сервера при работе VideoSDK/Room:

При смене состояния HTTP сервера будет получена нотификация httpServerStateChanged.

Также HTTP сервер может настраиваться с помощью таких команд: получение настроек (getHttpServerSettings), установка настроек (setHttpServerSettings), а также нотификация об их изменении (httpServerSettingChanged).

Все HTTP запросы имеют следующий формат:

http://room_ip:port/functionalityTag?params&token=tokenValue

Описание параметров

  • room_ip – ip адрес устройства, где запущен VideoSDK/Room

  • port – порт, по которому слушает HTTP сервер. Можно получить из:

    • значения поля embeddedHttpPort в ответе на успешное выполнение метода getAppState

    • значения поля embeddedHttpPort нотификации appStateChanged

    • объекта со значением имени поля name и его значением port в ответе на успешное выполнение команды getHttpServerSettings

    • объекта со значением имени поля name и его значением port в нотификации httpServerSettingChanged

  • functionalityTag – тег требуемого функционала

  • params – набор параметров, специфичных для конкретного функционала (тега)

  • token – токен

Далее показано, какие HTTP-запросы какого типа (GET, HEAD, POST, OPTIONS, DELETE) надо выполнять для каждой задачи.

# Получение данных об HTTP сервере

Метод OPTIONS в HTTP используется для получения информации о возможностях веб-сервера и поддерживаемых им методах. Этот запрос не изменяет состояние сервера или ресурса, а только возвращает метаданные, такие как разрешенные методы HTTP, поддерживаемые версии протокола и дополнительные заголовки, которые могут быть использованы для настройки запросов.

Выполните OPTIONS запрос формата

http://room_ip:port/files?token=tokenValue

Описание параметров

# Работа с кадрами камер

Для работы с кадрами с текущего устройства захвата видео и кадрами участников конференций используются запросы, отправленные на /frames. HTTP сервер сам собирает эти кадры и нет необходимости как-то их добавлять, обновлять или удалять – все будет сделано автоматически.

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

# Получение кадров

Выполните GET или HEAD запрос формата

http://room_ip:port/frames?peerId=requiredPeerId&token=tokenValue

Описание параметров

  • room_ip, port, token - стандартные параметры, описанные выше

  • peerId - идентификатор участника конференции, чей кадр нужно получить. Для получения кадров из устройства захвата видео следует передать одно из значений:

    • #self:0, которое будет валидным в любом состоянии приложения (залогинено или нет, онлайн или в конференции и т.п.)

    • идентификатор, с которым произведена авторизация на сервере. Его можно узнать, например, из значения поля peerId, полученного в результате успешного выполнения метода getLogin или нотификации login.

# Аватары пользователей

Для работы с аватарами пользователей используются запросы, отправленные на /avatars. HTTP сервер сам собирает их и нет необходимости как-то их добавлять, обновлять или удалять – все будет сделано автоматически. Обновление аватара можно отследить путем обработки нотификации updateAvatar.

# Получение аватаров

Выполните GET или HEAD запрос формата

http://room_ip:port/avatars?peerId=requiredPeerId&token=tokenValue

Описание параметров

  • room_ip, port, token - стандартные параметры, описанные выше

  • peerId - идентификатор пользователя, чей аватар нужно получить

# Пресеты устройства захвата видео

При каждом сохранении пресета командой addPresetFromCurrentVideoCapturer на HTTP сервере также сохраняется скриншот с текущего устройства захвата видео. Для работы с пресетами используются запросы, отправленные на /videoCapturerPresets. HTTP сервер сам собирает их и нет необходимости как-то их добавлять, обновлять или удалять – все будет сделано автоматически, при работе с пресетами через API-команды.

# Получение кадра пресета

Выполните GET или HEAD запрос формата

http://room_ip:port/videoCapturerPresets?presetId=requiredPresetId&token=tokenValue

Описание параметров

  • room_ip, port, token – стандартные параметры, описанные выше

  • presetId – идентификатор пресета, чей скриншот нужно получить

# Файлы

HTTP сервер умеет работать с файлами. Это может понадобиться для разных целей: передача файлов в чате, показ слайдшоу, замена фона и т.п. Работа с ними организована с помощью уникальных идентификаторов – fileId. Это позволяет хранить и работать с абсолютно одинаковыми файлами. Список всех доступных файлов можно получить, выполнив API команду getFileList

# Получение файла

Выполните GET запрос формата

http://room_ip:port/files?fileId=requiredFileId&token=tokenValue

Пример запроса

http://192.168.0.100:8766/files?fileId=42488041&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

Описание параметров

  • room_ip, port, token – стандартные параметры, описанные выше

  • fileId – идентификатор файла, который нужно получить

Также в ответе в заголовках будет указано оригинальное имя файла, например, Content-Disposition: attachment; filename="Screenshot_20221205_062944.png". Помимо стандартных возвращаемых кодов в ответе могут быть дополнительные заголовки с информацией о причине ошибки при её возникновении. Пример:

Access-Control-Expose-Headers: ErrorMessage, ErrorCode
ErrorCode: 3
ErrorMessage: FileId is not present

ErrorCode и ErrorMessage выдаются взаимосвязанными парами и могут принимать следующие значения:

  • ErrorCode: 3
    ErrorMessage: FileId is not present

  • ErrorCode: 12
    ErrorMessage: Uploaded files directory is no created

  • ErrorCode: 13
    ErrorMessage: There is no file with such id

  • ErrorCode: 14
    ErrorMessage: Some internal error

  • ErrorCode: 15
    ErrorMessage: File id conversion error

  • ErrorCode: 16
    ErrorMessage: Empty file id parameter

# Загрузка файлов на веб-сервер

Выполните POST запрос формата

http://room_ip:port/files?token=tokenValue

При этом в HTML надо будет указать формат multipart/form-data и указать путь к файлу. При использовании утилиты curl (opens new window) надо будет указать ключ --form.

Пример загрузки файла с использованием утилиты curl (opens new window)

curl --form 'file=@"/home/user/image.png"' http://192.168.0.100:8766/files?token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

Пример формы на html-странице

<form action="http://192.168.0.100:8766/files?token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130" enctype="multipart/form-data" method="POST">
<div>
   <label for="file">Choose file to upload</label>
   <input type="file" id="file" name="file" multiple>
 </div>
 <div>
   <button>Submit</button>
 </div>
</form>

Описание параметров

При успешной загрузке в ответе будет содержаться идентификатор / идентификаторы, которые присвоились файлу / файлам на HTTP сервере и должны использоваться далее при работе с ними (в часности, в API). В случае ошибки помимо стандартных возвращаемых кодов и заголовков в ответе может быть дополнительная информация о её причине (ErrorCode: 0 означает отсутствие ошибок). Пример:

Access-Control-Expose-Headers: FileId, ErrorMessage, ErrorCode
ErrorCode: 0
ErrorMessage: Success
FileId: 50627163

Access-Control-Expose-Headers: UnpackedFilesId, ErrorMessage, ErrorCode
ErrorCode: 0
ErrorMessage: Success
UnpackedFilesId: 153153427,153154947,153154948,153154949,153154950

Описание параметров

  • Access-Control-Expose-Headers - список дополнительных заголовков с информацией о выполнении метода

  • ErrorCode и ErrorMessage - код и описание ошибки соответственно. Выдаются взаимосвязанными парами и могут принимать следующие значения:

    • ErrorCode: 8
      ErrorMessage: Couldn't create PostConnectionInfo in POST request

    • ErrorCode: 9
      ErrorMessage: Couldn't create postprocessor in POST request

    • ErrorCode: 11
      ErrorMessage: Couldn't parse and process POST data

    • ErrorCode: 1
      ErrorMessage: Invalid key

    • ErrorCode: 17
      ErrorMessage: Filename is not present

    • ErrorCode: 2
      ErrorMessage: Filename is empty

    • ErrorCode: 5
      ErrorMessage: Couldn't create path for file

    • ErrorCode: 6
      ErrorMessage: Couldn't open file by file name

    • ErrorCode: 7
      ErrorMessage: Couldn't write data in file

    • ErrorCode: 0
      ErrorMessage: Success

  • fileId - идентификатор файла на сервере. Присутствует только если загружаемому файлу будет соответствовать один файл на сервере

  • UnpackedFilesId - идентификаторы файлов на сервере. Присутствует только если загружаемый файл распаковывается в несколько других, например при загрузке слайдов из файла презентации Microsoft PowerPoint или файла презентации, сделанного в TrueConf Client

Также POST запрос может использоваться для удаления файлов с HTTP сервера, используя "старый формат".

Формат url запроса

http://room_ip:port/files?fileId=requiredFileId&action=DELETE

Описание параметров

  • room_ip, port, token - стандартные параметры, описанные выше
  • fileId - идентификатор файла, который нужно удалить
  • action=DELETE - указание на то, что мы должны удалить файл

# Удаление файла

Для удаления файла требуется выполнить DELETE-запрос вида:

http://room_ip:port/files?fileId=requiredFileId&token=tokenValue

Описание параметров

  • fileId – идентификатор (ID) файла, который нужно удалить. Список всех доступных файлов и их идентификаторов можно получить, выполнив API команду getFileList. Также ID возвращается при успешной загрузке файла с помощью POST-запроса.

# Слайдшоу

Реализованы те же функции, что и при работе с файлами, но в запросах подставляется тег slides вместо files. Используется для подготовки слайдшоу, чтобы передавать его во время конференции или звонка.

При загрузке файла он будет проверен на возможность использования: поддерживаются изображения .jpg, .jpeg, .png, а также файлы презентаций Microsoft PowerPoint .ppt, .pptx и специального формата .slides (как их получить смотрите в документации клиентского приложения TrueConf). Если такой тип файла не поддерживается, вернется ошибка 422 Unprocessable Entity. При загрузке файла презентации он будет распакован в отдельные файлы-слайды, а в ответе в заголовке UnpackedFilesId будет выдан их список.