• Built-in HTTP server
  • Overview
  • Getting information about the HTTP server
  • Working with camera frames
    • Getting Started
  • User Avatars
    • Getting avatars
  • Video capture device presets
    • Getting preset frame
  • Files
    • Getting file
    • Loading files to web server
    • Delete file
  • Slideshow

Built-in HTTP server

Overview

Since VideoSDK/Room is remotely managed using the client-server WebSocket protocol, the application includes an HTTP server. It is automatically launched when the application is started. The port for it will also be automatically selected and its value can be obtained using the API method getHttpServerSettings. But you can specify the port manually. To do this, when launching VideoSDK/Room, specify the desired value in the command-line parameter --httpport. If launching the HTTP server on the specified port fails, the application will not start and corresponding messages will be output to the logs.

HTTP server is used for the following functionality:

• Getting frames from the current video capture device and conference participants' video

• User Avatars

• Files

• Slide Show

• Video capture device presets

Each functionality supports its own set of HTTP methods, which can be found in the corresponding section. All requests must pass the token parameter, which is created and obtained:

• During the authorization process, the value of the tokenForHttpServer field in the response to a successful authorization command auth is of importance.

• During the transition from the administrator management type to the user management type, the value of the tokenForHttpServer field in the response to a successful execution of the auth command is changed.

• When successfully executing the getTokenForHttpServer command, the value of the token field.

• During the installation of a new type of protection for accessing management, the value of the tokenForHttpServer field in response to the successful execution of the setAuthParams command.

Token lifetime - 5 minutes, or until the application is turned off, or until receiving a notification authorizationNeeded. If management is carried out with pin protection Set, then the token lifetime does not expire until the application is restarted. Tokens can be cleared by executing the command clearTokens.

You can manage the HTTP server status while working with VideoSDK/Room.

• Get the current status with the command getHttpServerState;

• Start it with the command startHttpServer;

• Stop with the command stopHttpServer.

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

Also, the HTTP server can be configured using the following commands: getting settings (getHttpServerSettings), setting settings (setHttpServerSettings), and notifying of their changes (httpServerSettingChanged).

All HTTP requests have the following format:

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

Parameters Description

• room_ip - device's IP address where VideoSDK/Room is running.

• port - the port on which the HTTP server listens. Can be obtained from:

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

  • The value of the embeddedHttpPort field in the appStateChanged notification.

  • an object with the value of the name field and its value port in the response to the successful execution of the getHttpServerSettings command

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

• functionalityTag - the tag of the required functionality.

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

• token - Token

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

Getting information about the HTTP server

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

Perform an OPTIONS request of the format

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

Parameters Description

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

Working with camera frames

To work with frames from the current video capture device and frames of conference participants, requests sent to /frames are used. The HTTP server itself collects these frames, and there is no need to add, update, or delete them in any way - everything will be done automatically.

For each conference participant, only one last frame is saved, so they do not accumulate. After the event ends, the frames of the participants are deleted, but their own remain (from the camera ).

Getting Started

Perform a GET or HEAD request for the format

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

Parameters Description

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

• peerId - identifier of the conference participant whose frame needs to be obtained. To obtain frames from a video capture device , one of the following values should be passed:

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

  • The identifier with which the authorization was performed on the server. It can be found, for example, from the value of the peerId field obtained as a result of successfully executing the getLogin method or the login notification.

User Avatars

To work with user avatars, requests are sent to /avatars. The HTTP server automatically collects them, so there is no need to add, update, or delete them manually. Updating an avatar can be tracked by processing the notification updateAvatar.

Getting avatars

Perform a GET or HEAD request for the format

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

Parameters Description

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

• peerId - user identifier whose avatar needs to be obtained

Video capture device presets

Every time a preset is saved using the addPresetFromCurrentVideoCapturer command, a screenshot from the current video capture device is also saved on the HTTP server. Requests to /videoCapturerPresets are used to work with presets. The HTTP server automatically collects and manages them, so there's no need to manually add, update, or delete them when working with presets through API commands.

Getting preset frame

Perform a GET or HEAD request for the format

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

Parameters Description

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

• presetId - the identifier of the preset for which you need to get a screenshot.

Files

The HTTP server is capable of working with files. This may be necessary for various purposes: transferring files in a chat, displaying a slideshow, replacing the background, and so on. Working with them is organized using unique identifiers - fileId. This allows you to store and work with absolutely identical files. The list of all available files can be obtained by executing the API command getFileList.

Getting file

Perform 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

Parameters Description

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

• fileId - the identifier of the file to be obtained

Also, in the response headers, the original filename will be specified, for example, Content-Disposition: attachment; filename="Screenshot_20221205_062944.png". In addition to the standard return codes, the response may contain additional headers with information about the cause of the error. Example:

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

ErrorCode and ErrorMessage are interrelated pairs and can take the following values:

• 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

Loading files to web server

Perform a POST request in the following format:

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

Please make sure to specify the multipart/form-data format and the file path in HTML. When using the curl utility (opens new window), use the --form flag.

**Example of file upload using curl utility (opens new window) **

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>

Parameters Description

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

When successfully uploaded, the response will contain the identifier(s) assigned to the file(s) on the HTTP server, which should be used when working with them (in particular, in the API). In case of an error, in addition to the standard return codes and headers, there may be additional information about its cause (ErrorCode: 0 means there are no errors). Example:

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

Parameters Description

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

• ErrorCode and ErrorMessage - code and error description respectively. They are issued as associated pairs and can take the following values:

  • 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 - file identifier on the server. It is present only if the uploaded file corresponds to one file on the server.

• UnpackedFilesId - File IDs on the server. Present only if the uploaded file is unpacked into several others, for example, when loading slides from a Microsoft PowerPoint presentation file or a presentation file made in TrueConf Client.

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

Request URL Format

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

Parameters Description

• room_ip, port, token - standard parameters described above
• fileId - the ID of the file to be deleted.
• action=DELETE - instruction to delete a file

Delete file

To delete a file, you need to make a DELETE request of the following format:

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

Parameters Description

• fileId - the identifier (ID) of the file that needs to be deleted. The list of all available files and their IDs can be obtained by executing the API command getFileList. Also, the ID is returned upon successful file upload using the POST request.

Slideshow

The same functions as when working with files are implemented, but the slides tag is substituted instead of files in requests. Used to prepare slideshows to transmit during a conference or call.

When a file is uploaded, it will be checked for compatibility: supported formats are images .jpg, .jpeg, .png, as well as Microsoft PowerPoint presentations .ppt, .pptx and a special format .slides (see how to obtain them in the client application TrueConf documentation). If a file of this 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 a list of them will be returned in the UnpackedFilesId header of the response.