# Встроенный 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:
получить текущий статус командой getHttpServerState;
запустить его командой startHttpServer;
остановить командой stopHttpServer.
При смене состояния HTTP сервера будет получена нотификация httpServerStateChanged.
Также HTTP сервер может настраиваться с помощью таких команд: получение настроек (getHttpServerSettings), установка настроек (setHttpServerSettings), а также нотификация об их изменении (httpServerSettingChanged).
Все HTTP запросы имеют следующий формат:
http://room_ip:port/functionalityTag?params&token=tokenValue
Описание параметров
room_ip
– ip адрес устройства, где запущен VideoSDK/Roomport
– порт, по которому слушает 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
Описание параметров
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"
. Помимо стандартных возвращаемых кодов в ответе могут быть дополнительные заголовки с информацией о причине ошибки при её возникновении. Пример:
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>
Описание параметров
room_ip
,port
,token
- стандартные параметры, описанные выше
При успешной загрузке в ответе будет содержаться идентификатор / идентификаторы, которые присвоились файлу / файлам на 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
будет выдан их список.