Труконф

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

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

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

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

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

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

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

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

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

В результате выполнения запросов возвращаются определённые коды и сообщения, которые рассмотрены ниже.

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

# Управление HTTP сервером

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

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

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

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

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

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

  • room_ip – ip адрес устройства, где запущен TrueConf 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

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

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

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

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

При успешной загрузке в ответе будет содержаться идентификатор / идентификаторы, которые присвоились файлу / файлам на 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 - ошибка. Внутренний сбой сервера, связанный с работой функционала Наложения (не смогли получить объект, который им управляет)

См. также:

Наложение

Last Updated: 09.10.2025