Embedded HTTP Server

TrueConfAbout 21 min

Embedded HTTP Server

General Overview

Since TrueConf Room API is remotely managed using the client-server WebSocket protocol, the application includes an HTTP server. It starts automatically when the application is launched. The port for it is also selected automatically, and its value can be obtained using the API method getHttpServerSettings. However, you can specify the port manually. To do this, set the desired value using the command line parameter --httpport when starting TrueConf Room API. If the HTTP server fails to start on the specified port, the application will not launch, and appropriate messages will be logged.

The HTTP server is used for the following functionality:

Each feature supports its own set of HTTP methods, which can be reviewed in the respective section. All requests, without exception, must include the token parameter, which is created and obtained as follows:

  • during the authorization process – the value of the tokenForHttpServer field in the response to a successful authorization with the auth command;

  • during the transition from administrator management type to user management type, the tokenForHttpServer field value is included in the response upon successful execution of the auth command;

  • Upon successful execution of the getTokenForHttpServer command, the value of the token field;

  • when setting a new type of protection for management access, the value of the tokenForHttpServer field is returned in response to the successful execution of the setAuthParams command.

As a result of the queries, specific codes and messages are returned, which are discussed below.

The token lifetime is 5 minutes, or until the application is closed, or until a authorizationNeeded notification is received. If management is set with PIN protection enabled, then the token lifetime does not expire until the application is restarted. Tokens can be cleared by executing the clearTokens command.

Managing the HTTP Server

You can manage the HTTP server status while operating TrueConf Room API:

When the HTTP server state changes, a httpServerStateChanged notification will be received.

Additionally, the HTTP server can be configured using the following commands: retrieve settings (getHttpServerSettings), apply settings (setHttpServerSettings), and receive notifications about changes (httpServerSettingChanged).

All HTTP requests follow this format:

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

Parameters description

  • room_ip – the IP address of the device where it's running TrueConf Room API

  • port - the port that the HTTP server listens on. It can be obtained from:

    • The values of the embeddedHttpPort field in the response to the successful execution of the getAppState method.

    • Values of the embeddedHttpPort field in the appStateChanged notification

    • An object with the field name name and its value port is included in the response after the successful execution of the getHttpServerSettings command.

    • of the object with the field name name and its value port in the httpServerSettingChanged notification

    • the same config.json file where the WebSocket port is also contained

  • functionalityTag – tag for the required functionality

  • params – a set of parameters specific to a particular functionality (tag)

  • token - Token

You can manually set a different port using the setHttpServerSettings command.

The following shows which type of HTTP requests (GET, HEAD, POST, OPTIONS, DELETE) should be executed for each task.

Retrieving data about the HTTP server

The HTTP OPTIONS method is used to obtain information about the capabilities of a web server and the methods it supports. This request does not alter the state of the server or resource but simply returns metadata, such as allowed HTTP methods, supported protocol versions, and additional headers that can be used to customize requests.

Perform an OPTIONS request format

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

Description of Parameters

Working with camera frames

Requests sent to /frames are used to work with frames from the current video capture device and conference participants' frames. The HTTP server automatically collects these frames, so there is no need to manually add, update, or delete them—it will all be handled automatically.

For each conference participant, only the last frame is retained, meaning they are not accumulated. Once the event concludes, participants' frames are deleted, but your own frames (from the TrueConf Room API camera) are preserved.

Capturing Frames

Execute a GET or HEAD request of the format

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

Description of Parameters

  • room_ip, port, token are standard parameters, described above.

  • peerId - the identifier of the conference participant whose frame needs to be obtained. To receive frames from the video capture device TrueConf Room API, you should pass one of the following values:

    • #self:0, which will be valid in any application state (logged in or not, online or in a conference, etc.)

    • The identifier used for authentication on the server. You can find it out, for example, from the peerId field obtained after successfully executing the getLogin method or the login notification.

User avatars

Requests sent to /avatars are used for working with user avatars. The HTTP server handles them automatically, so there's no need to manually add, update, or delete them—everything is done automatically. You can track avatar updates by processing the updateAvatar notification.

Retrieving avatars

Execute a GET or HEAD request of the format

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

Description of Parameters

  • room_ip, port, token are standard parameters, described above.

  • peerId - the identifier of the user whose avatar needs to be retrieved

Video Capture Device Presets

Each time a preset is saved using the addPresetFromCurrentVideoCapturer command, a screenshot from the current video capture device is also saved on the HTTP server. To manage presets, requests are sent to /videoCapturerPresets. The HTTP server handles these automatically, so there is no need to manually add, update, or delete them—everything is managed automatically when working with presets through API commands.

Getting the preset frame

Execute a GET or HEAD request of the format

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

Description of Parameters

  • room_ip, port, token – standard parameters, described above

  • presetId – the identifier of the preset for which you need to obtain a screenshot

Files

The HTTP server is capable of handling files. This can be useful for various purposes: file transfer in chat, displaying slideshows, background replacement, and more. File management is organized using unique identifiers - fileId. This allows for storing and working with identical files. You can obtain a list of all available files by executing the API command getFileList.

Retrieving a file

Execute a GET request in the format

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

Request example

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

Description of Parameters

  • room_ip, port, token – standard parameters, described above

  • fileId – the identifier of the file that needs to be retrieved

The response headers will also include the original file name, for example, Content-Disposition: attachment; filename="Screenshot_20221205_062944.png".

Uploading Files to the Web Server

Execute a POST request in the format

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

In HTML, you need to specify the multipart/form-data format and provide the file path. When using the curl utility, you must include the --form option.

Example of file upload using the curl utility

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

Example of a Form on an HTML Page

<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>

Description of Parameters

If the upload is successful, the response will include the identifier(s) assigned to the file(s) on the HTTP server, which should be used later in interactions with them (particularly in the 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

Description of Parameters

  • Access-Control-Expose-Headers - a list of additional headers containing information about the execution of the method

  • fileId - the file identifier on the server. This is present only if the uploaded file corresponds to a single file on the server.

  • UnpackedFilesId - file identifiers on the server. This is only present if the uploaded file is unpacked into several others, for example, when uploading slides from a Microsoft PowerPoint presentation file or a presentation file created in TrueConf Client.

Additionally, a POST request can be used to delete files from an HTTP server using the "old format."

URL request format

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

Description of Parameters

  • room_ip, port, token - standard parameters as described above
  • fileId - the identifier of the file to be deleted
  • action=DELETE indicates that we need to delete the file.

Deleting a file

To delete a file, you need to execute a DELETE request in the following form:

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

Description of Parameters

  • fileId - the identifier (ID) of the file to be deleted. You can obtain a list of all available files and their identifiers by executing the getFileList API command. The ID is also returned upon successful file upload via a POST request.

Overlay

With overlay, you can place an image over the outgoing video stream from TrueConf Room API.

Retrieving a file

Execute a GET or HEAD request of the format

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

Request example

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

Description of Parameters

  • imageId – the identifier of the file to overlay on the video stream

  • peerId - a unique identifier for the video frame source (conference participants, as well as your own video)

  • type – the required part of the Overlay functionality

Uploading files to the web server

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

Request example

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

Description of Parameters

  • imageId – the identifier of the file to overlay on the video stream

  • type – the required part of the Overlay functionality

Deleting a file

To delete a file, you need to execute a DELETE request in the following form:

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

Request example

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

Description of Parameters

  • imageId – identifier of the file to be deleted

  • type – the required part of the Overlay functionality

Slideshow

The same functions are implemented as when working with files, but in the requests, the slides tag is used instead of files. This is used to prepare a slideshow for sharing during a conference or call.

When uploading a file, it will be checked for usability: supported formats include images .jpg, .jpeg, .png, .webp, .gif, as well as Microsoft PowerPoint presentation files .ppt, .pptx and the special format .slides (see the client application documentationTrueConf for details on obtaining these). If the file type is not supported, an error 422 Unprocessable Entity will be returned. When uploading a presentation file, it will be unpacked into separate slide files, and their list will be provided in the UnpackedFilesId header in the response.

Background Replacement

Uploading files to the HTTP server is also necessary for background replacement. Before executing the setBackground command, you need to add an image in one of the supported formats: .jpg, .jpeg, .png, .svg as shown above.

Returned result and HTTP request headers

All HTTP requests in the response will return additional headers indicating the execution result.

  • ErrorCode - the code indicating the execution result

  • ErrorMessage - textual description of the execution result

  • ExtraErrorCode is an additional code indicating the execution result and pointing to the server's internal state in exceptional situations. It can be used to analyze issues during request execution.

  • ExtraErrorDescription - an additional textual description of the execution result, indicating the outcome and reflecting the internal state of the server in exceptional situations. It can be used to analyze issues when a request is executed.

ErrorCode and ErrorMessage are provided as interrelated pairs and can have the following values:

  • ErrorCode: 0, ErrorMessage: Success - success, no errors occurred

  • ErrorCode: 1, ErrorMessage: Token is not present - error. The token was not included in the request.

  • ErrorCode: 2, ErrorMessage: Invalid token - error. The token provided in the request is invalid.

  • ErrorCode: 3, ErrorMessage: Tag is not present - error. The request did not specify the tag.

  • ErrorCode: 4, ErrorMessage: This method is not allowed - error. This type of request is not supported on this tag.

  • ErrorCode: 5, ErrorMessage: 'peerId' parameter is not present - error. The required 'peerId' parameter is missing from the request.

  • ErrorCode: 6, ErrorMessage: 'peerId' parameter must not be empty - error. The 'peerId' parameter in the request is mandatory but is empty.

  • ErrorCode: 7, ErrorMessage: Avatar for such peerId was not found - error. The avatar for the specified peerId is missing.

  • ErrorCode: 8, ErrorMessage: Frame for such peerId was not found - error. Frame for the specified participant is missing.

  • ErrorCode: 9, ErrorMessage: 'presetId' parameter is not present - error. The required parameter 'presetId' is missing in the request.

  • ErrorCode: 10, ErrorMessage: 'presetId' parameter must be not empty - error. The 'presetId' parameter in the request is mandatory and cannot be empty.

  • ErrorCode: 11, ErrorMessage: Video capturer presets locking failure - error. An internal server failure occurred related to retrieving preset information (unable to obtain the object that manages them).

  • ErrorCode: 12, ErrorMessage: An error occurred while getting video capturer preset - error. An internal server failure related to retrieving information about presets (error in obtaining a specific preset).

  • ErrorCode: 13, ErrorMessage: Video capturer preset doesn't contain preview image - error. Internal server failure related to retrieving preset information (the obtained preset does not contain a preview).

  • ErrorCode: 14, ErrorMessage: 'fileId' parameter is not present - error. The required 'fileId' parameter is missing from the request.

  • ErrorCode: 15, ErrorMessage: 'fileId' parameter must be not empty - error. The required 'fileId' parameter in the request is empty.

  • ErrorCode: 16, ErrorMessage: An error occurred while getting information about the file by its id - error. Internal server failure related to retrieving file information by its identifier.

  • ErrorCode: 17, ErrorMessage: An error occurred while creating response content callback - error. Internal server failure related to request processing (unable to create response structure)

  • ErrorCode: 18, ErrorMessage: An error occurred while creating Request struct - error. Internal server failure related to request processing (unable to create request structure).

  • ErrorCode: 19, ErrorMessage: An error occurred while creating RequestInfo struct - error. Internal server failure related to request processing (failed to create request information structure).

  • ErrorCode: 20, ErrorMessage: file.good check failure - error. Internal server failure related to file system operation (file status flags check).

  • ErrorCode: 21, ErrorMessage: file.tellg check failure - error. Internal server failure related to file system operations (working with the position of the current character in the input stream).

  • ErrorCode: 22, ErrorMessage: An error occurred while creating PostConnectionInfo struct - error. Internal server failure related to processing the POST request (failed to create the request information structure).

  • ErrorCode: 23, ErrorMessage: An error occurred while creating post processor - error. Internal server failure related to processing the POST request (failed to create request processing object).

  • ErrorCode: 24, ErrorMessage: An error occurred while processing post request - error. Internal server failure related to processing a POST request (internal library error)

  • ErrorCode: 25, ErrorMessage: AfterDownloadFileValidationFunction returned failure - an error occurred. After the file was downloaded, it was checked according to the specific tag's rules and conditions, and it failed this validation.

  • ErrorCode: 26, ErrorMessage: remove_all call failure - error. Internal server failure related to file system operations (error deleting the working temporary directory)

  • ErrorCode: 27, ErrorMessage: File key is not present - error. The request is missing the required 'file' parameter.

  • ErrorCode: 28, ErrorMessage: 'fileName' parameter is not present - error. The required 'fileName' parameter is missing in the request.

  • ErrorCode: 29, ErrorMessage: 'fileName' parameter must be not empty - error. The required 'fileName' parameter in the request is empty.

  • ErrorCode: 30, ErrorMessage: PreDownloadFileValidationFunctionFailure returned failure - error. Before starting the download, the file was checked according to the rules and conditions of a specific tag and failed this validation.

  • ErrorCode: 31, ErrorMessage: An error occurred while creating path for file - error. Internal server failure related to file system operations (error in creating a directory involved in processing logic).

  • ErrorCode: 32, ErrorMessage: An error occurred because of unopened file - error. An internal server failure related to the file system operation (error opening the required file).

  • ErrorCode: 33, ErrorMessage: 'imageId' parameter is not present - error. The request is missing the required 'imageId' parameter.

  • ErrorCode: 34, ErrorMessage: 'imageId' parameter must be not empty - error. The 'imageId' parameter in the request is mandatory and cannot be empty.

  • ErrorCode: 35, ErrorMessage: An error occurred while loading png for overlay functionality - error. Internal server failure related to processing the png file (internal library error).

  • ErrorCode: 36, ErrorMessage: Loaded png file for overlay functionality has an invalid size - error. The file provided has an invalid size for the Overlay functionality.

  • ErrorCode: 37, ErrorMessage: An error occurred while adding png file to overlay functionality - error. The overlay functionality object returned an error when adding a new file.

  • ErrorCode: 38, ErrorMessage: An error occurred while deleting png file from overlay functionality - This error indicates that the overlay functionality encountered an issue when attempting to delete the file.

  • ErrorCode: 39, ErrorMessage: Internal error - couldn't lock overlay video processing - error. Internal server failure related to Overlay functionality (unable to obtain the object that manages it).

See also:

Overlay