# 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:
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 valueport
in the response to the successful execution of the getHttpServerSettings commandObject with field name
name
and its valueport
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 abovepeerId
- 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 abovepeerId
- 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 abovepresetId
- 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 abovefileId
- 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
andErrorMessage
- 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 aMicrosoft PowerPoint
presentation file or a presentation file made inTrueConf 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 abovefileId
- 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.