Встроенный 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 сервером

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

• получить текущий статус командой getHttpServerState;

• запустить его командой startHttpServer;

• остановить командой stopHttpServer.

При смене состояния 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

  • того же файла config.json где содержится и WebSocket порт

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

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

• token – токен

Есть возможность задать вручную другой порт с помощью команды setHttpServerSettings.

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

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

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

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

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

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

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

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

Для работы с кадрами с текущего устройства захвата видео и кадрами участников конференций используются запросы, отправленные на /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".

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

Выполните 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>

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

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

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

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 - список дополнительных заголовков с информацией о выполнении метода

• 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-запроса.

Наложение

С помощью наложения мы можете разместить изображение поверх исходящего от видеопотока.

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

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

http://room_ip:port/overlay?type=drawing&imageId=someId&token=tokenValue
http://room_ip:port/overlay?type=original_frames&peerId=someId&token=tokenValue

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

http://192.168.0.100:8766/overlay?type=drawing&imageId=42488041&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130
http://192.168.0.100:8766/overlay?type=original_frames&peerId=user1@some.server&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

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

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

• peerId – уникальный идентификатор источника кадров (участники конференции, а также свое собственное видео)

• type – нужная часть функционала Наложения

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

http://room_ip:port/overlay?type=drawing&imageId=someId&token=tokenValue

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

http://192.168.0.100:8766/overlay?type=drawing&imageId=42488041&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

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

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

• type – нужная часть функционала Наложения

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

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

http://room_ip:port/overlay?type=drawing&imageId=someId&token=tokenValue

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

http://192.168.0.100:8766/overlay?type=drawing&imageId=42488041&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

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

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

• type – нужная часть функционала Наложения

Слайдшоу

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

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

Замена фона

Загрузка файлов на HTTP сервер также требуется для использования замены фона. Перед выполнением команды setBackground требуется добавить изображение одного из поддерживаемых форматов: .jpg, .jpeg, .png, .svg как было показано выше.

Возвращаемый результат и заголовки http запросов

Абсолютно все http запросы в ответе будут возвращать дополнительные заголовки, которые будут указывать на результат выполнения.

• ErrorCode - код, обозначающий результат выполнения

• ErrorMessage - текстовое описание результата выполнения

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

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

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

• ErrorCode: 0, ErrorMessage: Success - успех, ошибок не произошло

• ErrorCode: 1, ErrorMessage: Token is not present - ошибка. Токен не был передан в запрос

• ErrorCode: 2, ErrorMessage: Invalid token - ошибка. Переданный в запрос токен - не валидный

• ErrorCode: 3, ErrorMessage: Tag is not present - ошибка. В запросе не был указан тег

• ErrorCode: 4, ErrorMessage: This method is not allowed - ошибка. Такой тип запроса не поддерживается на таком теге

• ErrorCode: 5, ErrorMessage: 'peerId' parameter is not present - ошибка. В запросе отсутствует обязательный параметр 'peerId'

• ErrorCode: 6, ErrorMessage: 'peerId' parameter must be not empty - ошибка. В запросе обязательный параметр 'peerId' пустой

• ErrorCode: 7, ErrorMessage: Avatar for such peerId was not found - ошибка. Аватар для указанного отсутствует

• ErrorCode: 8, ErrorMessage: Frame for such peerId was not found - ошибка. Кадр для указанного участника отсутствует

• ErrorCode: 9, ErrorMessage: 'presetId' parameter is not present - ошибка. В запросе отсутствует обязательный параметр 'presetId'

• ErrorCode: 10, ErrorMessage: 'presetId' parameter must be not empty - ошибка. В запросе обязательный параметр 'presetId' пустой

• ErrorCode: 11, ErrorMessage: Video capturer presets locking failure - ошибка. Внутренний сбой сервера, связанный с получением информации о пресетах (не смогли получить объект, который ими управляет)

• ErrorCode: 12, ErrorMessage: An error occurred while getting video capturer preset - ошибка. Внутренний сбой сервера, связанный с получением информации о пресетах (ошибка получения конкретного пресета)

• ErrorCode: 13, ErrorMessage: Video capturer preset doesn't contain preview image - ошибка. Внутренний сбой сервера, связанный с получением информации о пресетах (полученный пресет не содержит превью)

• ErrorCode: 14, ErrorMessage: 'fileId' parameter is not present - ошибка. В запросе отсутствует обязательный параметр 'fileId'

• ErrorCode: 15, ErrorMessage: 'fileId' parameter must be not empty - ошибка. В запросе обязательный параметр 'fileId' пустой

• ErrorCode: 16, ErrorMessage: An error occurred while getting information about the file by its id - ошибка. Внутренний сбой сервера, связанный с получением информации о файле по его идентификатору

• ErrorCode: 17, ErrorMessage: An error occurred while creating response content callback - ошибка. Внутренний сбой сервера, связанный с обработкой запроса (не смогли создать структуру ответа)

• ErrorCode: 18, ErrorMessage: An error occurred while creating Request struct - ошибка. Внутренний сбой сервера, связанный с обработкой запроса (не смогли создать структуру запроса)

• ErrorCode: 19, ErrorMessage: An error occurred while creating RequestInfo struct - ошибка. Внутренний сбой сервера, связанный с обработкой запроса (не смогли создать структуру информации запроса)

• ErrorCode: 20, ErrorMessage: file.good check failure - ошибка. Внутренний сбой сервера, связанный с работой с файловой системой (проверка флагов состояния файла)

• ErrorCode: 21, ErrorMessage: file.tellg check failure - ошибка. Внутренний сбой сервера, связанный с работой с файловой системой (работа с позицией текущего символа во входном потоке)

• ErrorCode: 22, ErrorMessage: An error occurred while creating PostConnectionInfo struct - ошибка. Внутренний сбой сервера, связанный с обработкой POST запроса (не смогли создать структуру с информацией о запросе)

• ErrorCode: 23, ErrorMessage: An error occurred while creating post processor - ошибка. Внутренний сбой сервера, связанный с обработкой POST запроса (не смогли создать объект обработки запроса)

• ErrorCode: 24, ErrorMessage: An error occurred while processing post request - ошибка. Внутренний сбой сервера, связанный с обработкой POST запроса (внутренняя ошибка библиотеки)

• ErrorCode: 25, ErrorMessage: AfterDownloadFileValidationFunction returned failure - ошибка. После загрузки файл был проверен в соответствии с правилами и условиями конкретного тега и эту проверку не прошел

• ErrorCode: 26, ErrorMessage: remove_all call failure - ошибка. Внутренний сбой сервера, связанный с работой с файловой системой (ошибка удаления рабочей временной директории)

• ErrorCode: 27, ErrorMessage: File key is not present - ошибка. В запросе отсутствует обязательный параметр 'file'

• ErrorCode: 28, ErrorMessage: 'fileName' parameter is not present - ошибка. В запросе отсутствует обязательный параметр 'fileName'

• ErrorCode: 29, ErrorMessage: 'fileName' parameter must be not empty - ошибка. В запросе обязательный параметр 'fileName' пустой

• ErrorCode: 30, ErrorMessage: PreDownloadFileValidationFunctionFailure returned failure - ошибка. Перед началом загрузки файл был проверен в соответствии с правилами и условиями конкретного тега и эту проверку не прошел

• ErrorCode: 31, ErrorMessage: An error occurred while creating path for file - ошибка. Внутренний сбой сервера, связанный с работой с файловой системой (ошибка создания директории, которая учавствует в логике обработки)

• ErrorCode: 32, ErrorMessage: An error occurred because of unopened file - ошибка. Внутренний сбой сервера, связанный с работой с файловой системой (ошибка открытия требуемого файла)

• ErrorCode: 33, ErrorMessage: 'imageId' parameter is not present - ошибка. В запросе отсутствует обязательный параметр 'imageId'

• ErrorCode: 34, ErrorMessage: 'imageId' parameter must be not empty - ошибка. В запросе обязательный параметр 'imageId' пустой

• ErrorCode: 35, ErrorMessage: An error occurred while loading png for overlay functionality - ошибка. Внутренний сбой сервера, связанный с обработкой png файла (внутренняя ошибка библиотеки)

• ErrorCode: 36, ErrorMessage: Loaded png file for overlay functionality have invalid size - ошибка. Переданный файл имеет невалидный размер для функционала Наложения

• ErrorCode: 37, ErrorMessage: An error occurred while adding png file to overlay functionality - ошибка. Объект работы с функционалом Наложения вернул ошибку при добавлении нового файла

• ErrorCode: 38, ErrorMessage: An error occurred while deleting png file from overlay functionality - ошибка. Объект работы с функционалом Наложения вернул ошибку при удалении файла

• ErrorCode: 39, ErrorMessage: Internal error - couldn't lock overlay video processing - ошибка. Внутренний сбой сервера, связанный с работой функционала Наложения (не смогли получить объект, который им управляет)

См. также:

Наложение