DCV module - Amazon DCV
MethodsMembersType and callback definitions

DCV module

A module that implements the client side of the DCV protocol.

Methods

authenticate(authParams) → {Authentication}

Starts the authentication process for the specified Amazon DCV server endpoint.

Parameters:

Name Type Description
url string The host name and port of the running Amazon DCV server in the following format: https://dcv_host_address:port. For example: https://my-dcv-server:8443.
authenticationToken string The authentication token to use for authentication.
callbacks authenticationCallbacks The callbacks that are available to be called during the authentication process.

Returns:

- The Authentication object.

Type

Authentication

connect(config) → {Promise.<Connection>|Promise.<{code: ConnectionErrorCode, message: string}>}

Connects to the specified Amazon DCV server endpoint. If connection succeeds, it returns a Connection object. If connection fails, it returns an error object.

Parameters:

Name Type Description
config ConnectionConfig The ConnectionConfig object.

Returns:

- A Connection object, or an error object.

Type

Promise.<Connection> | Promise.<{code: ConnectionErrorCode, message: string}>

setLogHandler(handler) → {void}

Sets a custom log handler function. When overriding the default log handler, the original log entry position will be lost when debugging with the browser console.

Parameters:

Name Type Description
handler function The custom log handler function. The handler function contains level (number), levelName (string), domain (string), and message (string).

Returns:

Type

void

setLogLevel(level) → {void}

Sets the log level. This is required only if the default log handler is used.

Parameters:

Name Type Description
level LogLevel The log level to use.

Returns:

Type

void

Members

(constant) AudioError :AudioErrorCode

The AudioError codes enum.

Type:

(constant) AuthenticationError :AuthenticationErrorCode

The AuthenticationError codes enum.

Type:

(constant) ChannelError :ChannelErrorCode

The ChannelError codes enum.

Type:

(constant) ClosingReasonError :ClosingReasonErrorCode

The ClosingReasonError codes enum.

Type:

(constant) ConnectionError :ConnectionErrorCode

The ConnectionError codes enum.

Type:

(constant) CustomChannelError :CustomChannelErrorCode

The CustomChannelError codes enum.

Type:

(constant) DisplayConfigError :DisplayConfigErrorCode

The DisplayConfigError codes enum.

Type:

(constant) FileStorageError :FileStorageErrorCode

The FileStorageError codes enum.

Type:

(constant) LogLevel :LogLevel

The available SDK log levels.

Type:

(constant) MultiMonitorError :MultiMonitorErrorCode

The MultiMonitorError codes enum.

Type:

(constant) ResolutionError :ResolutionErrorCode

The ResolutionError codes enum.

Type:

(constant) TimezoneRedirectionError :TimezoneRedirectionErrorCode

The TimezoneRedirectionError codes enum.

Type:

(constant) TimezoneRedirectionSetting :TimezoneRedirectionSettingCode

The TimezoneRedirectionSetting codes enum.

Type:

(constant) TimezoneRedirectionStatus :TimezoneRedirectionStatusCode

The TimezoneRedirectionStatus codes enum.

Type:

(constant) version

The Amazon DCV version with major, minor, patch, revision, extended, and versionStr.

Properties:

Name Type Description
major integer The major version number.
minor integer The minor version number.
patch integer The patch version number.
revision integer The revision number.
extended string The extended string.
versionStr string A concatenation of the major, minor, patch, and revision numbers in the form major.minor.patch+build.revision.

(constant) ScreenshotError :ScreenshotErrorCode

The ScreenshotError codes enum.

Type:

(constant) WebcamError :WebcamErrorCode

The WebcamError codes enum.

Type:

Type and callback definitions

AudioErrorCode

The AudioError code enums available in the DCV module

  • SETTING_AUDIO_FAILED

  • CHANNEL_NOT_AVAILABLE

Type:

  • number

authenticationCallbacks

Authentication callbacks

Type:

  • Object

Properties:

Name Type Description
promptCredentials authPromptCredentialsCallback The callback function to be called when the user is challenged for credentials.
error authErrorCallback The callback function to be called when authentication fails.
success authSuccessCallback The callback function to be called when authentication succeeds.
httpExtraSearchParamsCallback httpExtraSearchParamsCallback The callback function to be called in the authenticate method to inject custom query parameters into the authentication URL before initiating the request. It can also be used in the connect method to customize the URL that's used when establishing a WebSocket connection to the DCV server.

AuthenticationErrorCode

The AuthenticationError code enums available in the DCV module

  • INVALID_MESSAGE

  • UNKNOWN_AUTH_MODE

  • SESSION_NOT_AVAILABLE

  • NO_SESSIONS

  • WRONG_CREDENTIALS

  • SASL_CHALLENGE

  • SASL_AUTH_MECHANISM

  • FAILED_COMMUNICATION

  • AUTHENTICATION_REJECTED

  • GENERIC_ERROR

  • WRONG_CREDENTIALS_FORMAT

  • WRONG_CREDENTIALS_TYPE

  • UNREQUESTED_CREDENTIALS

  • MISSING_CREDENTIAL

Type:

  • number

authErrorCallback(authentication, error)

The callback function to be called when authentication fails.

Parameters:

Name Type Description
authentication Authentication The Authentication object.
error Object The error object raised by the authentication process.
Name Type Description
code AuthenticationErrorCode The error code.
message string The error message.

authPromptCredentialsCallback(authentication, challenge)

The callback function to be called when the user is challenged for credentials. The user must answer the challenge by providing the requested credentials.

Parameters:

Name Type Description
authentication Authentication The Authentication object.
challenge Object The challenge.
Name Type Description
requiredCredentials Array.<Object> An array of requested credential objects.
Name Type Description
name string The name of the requested credential.
type string The type of the requested credential.

authSuccessCallback(authentication, authenticationData)

The callback function to be called when authentication succeeds.

Parameters:

Name Type Description
authentication Authentication The Authentication object.
authenticationData Array.<Object> An array of objects that include Amazon DCV session IDs and authentication tokens.
Name Type Description
sessionId string The Amazon DCV session ID.
authToken string The authentication token for the Amazon DCV session.

Channel

The available channels that can be specified.

Type:

  • "clipboard" | "display" | "input" | "audio" | "filestorage"

ChannelErrorCode

The ChannelError code enums available in the DCV module

  • ALREADY_OPEN

  • INITIALIZATION_FAILED

  • REJECTED

Type:

  • number

clipboardEventCallback(event)

The callback function to be called when a clipboardEvent is generated.

Parameters:

Name Type Description
event Object Information about the clipboard event.
Name Type Attributes Description
name established | copy | paste | dataSizeAlert | autoCopyDone | newDataAvailable | autoPasteDone | remoteError | pasteAvailableData Always present. The name of the event.
clipboardData Object | string The data in the clipboard.
autoCopy boolean <optional> Indicates whether automatic copying from the session clipboard to the local client clipboard is enabled.
maxDataSize number <optional> The maximum amount of data that can be placed in the clipboard.
error string <optional> Error information if applicable.

ClosingReasonErrorCode

The ClosingReasonError code enums available in the DCV module

  • TRANSPORT_ERROR

  • NO_ERROR

  • GENERIC_ERROR

  • INTERNAL_SERVER_ERROR

  • PROTOCOL_ERROR

  • AUTHORIZATION_DENIED

  • AUTHORIZATION_REVOKED

  • ACCESS_REJECTED

  • IDLE_TIMEOUT_EXPIRED

  • DISCONNECT_BY_OWNER

  • DISCONNECT_BY_USER

  • EVICTED

  • EXTERNAL_PROTOCOL_CONNECTION_EVICTED

  • DISCONNECTION_REQUESTED

Type:

  • number

Colorspace

The available colorspaces that can be specified.

Type:

  • "RGB" | "YUV_REC601" | "YUV_REC709"

connectionCallbacks

The callbacks that are available to be called in the event of a connection error.

Type:

  • Object

Properties:

Name Type Description
disconnect disconnectCallback The callback function to be called when the connection ends.
displayLayout displayLayoutCallback The callback function to be called when the display layout or resolution is changed.
displayAvailability displayAvailabilityCallback The callback function to be called when a display's availability changes.
firstFrame firstFrameCallback The callback function to be called when the first frame is received from the Amazon DCV server.
filePrinted filePrintedCallback The callback function to be called when a file is printed on the Amazon DCV server.
fileDownload fileDownloadCallback The callback function to be called when a file is ready to be downloaded from the Amazon DCV server.
dataChannel dataChannelCallback The callback function to be called when the Amazon DCV server sends a notification about the availability of a data channel.
licenseNotification licenseNotificationCallback The callback function to be called when the Amazon DCV server sends a notification about the license state.
idleWarningNotification idleWarningNotificationCallback The callback function to be called when the Amazon DCV server sends an idle timeout warning.
collaboratorList collaboratorListCallback The callback function to be called when the Amazon DCV server sends the list of collaborators (since Amazon DCV Web Client SDK version 1.1.0).
qualityIndicatorState qualityIndicatorStateCallback The callback function to be called when the connection quality indicator changes state.
filestorageEnabled filestorageEnabledCallback The callback function to be called when file storage is enabled or disabled.
featuresUpdate featuresUpdateCallback The callback function to be called when a feature's status changes.
clipboardEvent clipboardEventCallback The callback function to be called when a clipboardEvent is generated.
deviceChangeEvent deviceChangeEventCallback The callback function to be called when an deviceChange event is triggered.
screenshot screenshotCallback The callback function to be called when a screenshot is available.
httpExtraSearchParamsCallback httpExtraSearchParamsCallback The callback function to be called to customize the URL when establishing a WebSocket connection to the Amazon DCV server. Note that this callback can also be used with the authenticate method to dynamically append query parameters to the authentication URL before the SDK sends the request.
httpExtraHeadersCallback httpExtraHeadersCallback The callback function to be called to add custom headers to the HTTP request during connection establishment.

ConnectionConfig

The configuration for a Amazon DCV connection.

Type:

  • Object

Properties:

Name Type Description
url string The host name and port of the running Amazon DCV server in the following format: https://dcv_host_address:port. For example: https://my-dcv-server:8443.
sessionId string The Amazon DCV session ID.
authToken string The authentication token to use when connecting to the server.
baseUrl string The absolute or relative URL from which to load SDK files.
resourceBaseUrl string The absolute or relative URL from which to access DCV resources.
enabledChannels Array.<Channel> Indicates the list of channels that can be enabled. If not specified or an empty array is provided, it defaults to all the available channels.
losslessColorspace Colorspace Indicates the colorspace that will be used. If not specified, it defaults to "RGB".
divId string The ID of the div object in the HTML DOM where SDK should create the canvas with the remote stream.
volumeLevel integer The preferred volume level. The valid range is 0 to 100.
clipboardAutoSync boolean Indicates whether automatic copying from the Amazon DCV session clipboard to the local client clipboard is enabled for compatible web browsers.
dynamicAudioTuning boolean Indicates whether to dynamically tune the audio based on the Amazon DCV server audio settings when a connection is established.
clientHiDpiScaling boolean Indicates whether to scale the canvas based on the client's DPI.
highColorAccuracy boolean Indicates whether high color accuracy should be used if available. If not specified, it defaults to false.
enableWebCodecs Boolean Indicates whether WebCodecs should be used if available. Defaults to false if not specified.
observers connectionCallbacks The callback functions to call for events that are related to the connection.
callbacks connectionCallbacks The same as the observers property, but each callback includes the Connection object as the first parameter.

ConnectionErrorCode

The ConnectionError code enums available in the DCV module

  • ALREADY_OPEN

  • INVALID_CONFIG

  • INITIALIZATION_FAILED

  • REJECTED

  • MAIN_CHANNEL_ALREADY_OPEN

  • GENERIC_ERROR (since DCV Server 2021.0)

  • INTERNAL_SERVER_ERROR (since DCV Server 2021.0)

  • AUTHENTICATION_FAILED (since DCV Server 2021.0)

  • PROTOCOL_ERROR (since DCV Server 2021.0)

  • INVALID_SESSION_ID (since DCV Server 2021.0)

  • INVALID_CONNECTION_ID (since DCV Server 2021.0)

  • CONNECTION_LIMIT_REACHED (since DCV Server 2021.0)

  • SERVER_UNREACHABLE (since DCV Server 2022.1)

  • GATEWAY_BUSY

  • UNSUPPORTED_CREDENTIAL (since DCV Server 2022.2)

  • TRANSPORT_ERROR

Type:

  • number

createDirectory(path)

Parameters:

Name Type Description
path string The absolute path on the server where we want to create a directory. It should also include the name of the target directory.

CustomChannelErrorCode

The CustomChannelError code enums available in the DCV module

  • TRANSPORT_ERROR

Type:

  • number

dataChannelCallback(info)

The callback function to be called when the Amazon DCV server sends a notification about the availability of a data channel.

Parameters:

Name Type Description
info Object Information about the data channel.
Name Type Description
name string The name of the data channel.
token string The authentication token for the data channel.

deleteFile(path)

Parameters:

Name Type Description
path string The absolute path on the server identifying the file we want to delete.

deviceChangeEventCallback()

The callback function to be called when an deviceChange event is triggered.

disconnectCallback(reason)

The callback function to be called when the connection ends.

Parameters:

Name Type Description
reason Object The reason for the disconnection.
Name Type Description
code number The reason code.
message string The reason message.

displayAvailabilityCallback(status, displayId)

The callback function to be called when a display's availability changes.

Parameters:

Name Type Description
status Object The status of the display.
Name Type Description
enabled boolean Indicates if the display is enabled.
closed boolean Indicates if the display is closed.
displayId number The identifier for the display.

DisplayConfigErrorCode

The DisplayConfigError code enums available in the DCV module

  • INVALID_ARGUMENT

  • UNSUPPORTED_OPERATION

  • NO_CHANNEL

Type:

  • number

displayLayoutCallback(serverWidth, serverHeight, heads)

The callback function to be called when the display layout or resolution is changed.

Parameters:

Name Type Description
serverWidth number The width (in pixels) of the primary display.
serverHeight number The height (in pixels) of the primary display.
heads Array.<Monitor> The display heads supported by the Amazon DCV server.

feature

The feature values.

  • display - Indicates the availability of a single-display video stream.

  • display-multi - Indicates the availability of a multi-display video stream.

  • high-color-accuracy - Indicates the availability of high color accuracy (since Amazon DCV Web Client SDK version 1.1.0).

  • mouse - Indicates the availability of mouse functionality.

  • keyboard - Indicates the availability of keyboard functionality.

  • keyboard-sas - Indicates the availability of SAS sequence (Control + Alt + Delete) functionality.

  • relative-mouse - Indicates the availability of relative mouse mode.

  • clipboard-copy - Indicates the availability of clipboard copy functionality from Amazon DCV server to the client.

  • clipboard-paste - Indicates the availability of clipboard paste functionality from the client to the Amazon DCV server.

  • audio-in - Indicates the availability of audio input functionality using the microphone.

  • audio-out - Indicates the availability of audio playback functionality.

  • webcam - Indicates the availability of webcam streaming functionality.

  • file-download - Indicates availability of file download functionality from the Amazon DCV server to the client.

  • file-upload - Indicates availability of file upload functionality from the client to the Amazon DCV server.

  • timezone-redirection - Indicates the availability of timezone redirection functionality (since Amazon DCV Web Client SDK version 1.3.0).

Type:

  • string

featuresUpdateCallback(featuresList)

The callback function to be called when a feature's status changes.

Parameters:

Name Type Description
featuresList Array.<feature> An array of features that have changed.

fileDownloadCallback(fileResource)

The callback function to be called when a file is ready to be downloaded from the Amazon DCV server.

Parameters:

Name Type Description
fileResource Object Information about the file that is ready for download.
Name Type Description
id string The identifier for the file.
url string The URL to use to download the file.
domain string The resource domain.
token string The authentication token to use to download the file. The token is also included in the URL.

filePrintedCallback(printResource)

The callback function to be called when a file is printed on the Amazon DCV server.

Parameters:

Name Type Description
printResource Object Information about the printed file.
Name Type Description
id string The identifier for the printed file.
url string The URL to use to download the printed file.
domain string The resource domain. In this case, printer.
token string The authentication token to use to download the printed file. The token is also included in the URL.

filestorage

Object that allows for exploring and performing actions on the file system.

Type:

  • Object

Properties:

Name Type Description
list list Function that allows to list the items (files and directories) present at the supplied path on the server.
createDirectory createDirectory Function that allows to create a directory at the specified path on the server.
retrieveFile retrieveFile Function that allows to locally download a file at the specified path on the server.
deleteFile deleteFile Function that allows to delete a file at the specified path on the server.
renameFile renameFile Function that allows to rename a file from the specified source path to the specified destination path.
renameDirectory renameDirectory Function that allows to rename a directory from the specified source path to the absolute destination path.
storeFile storeFile Function that allows to upload a local file to the supplied path on the server.

filestorageEnabledCallback(enabled)

The callback function to be called when file storage is enabled. Lazy channel on Internet Explorer 11 only.

Parameters:

Name Type Description
enabled boolean Indicates whether file storage is enabled.

FileStorageErrorCode

The FileStorageError code enums available in the DCV module

  • CANCELLED

  • ABORTED

  • INVALID_ARGUMENT

  • NOT_IMPLEMENTED

  • ERROR

  • ALREADY_EXIST

  • NOT_FOUND

Type:

  • number

firstFrameCallback(resizeEnabled, relativeMouseModeEnabled, displayId)

The callback function to be called when the first frame is received from the Amazon DCV server. Emitted for each display.

Parameters:

Name Type Description
resizeEnabled boolean Indicates whether the server supports resizing the client display layout.
relativeMouseModeEnabled boolean Indicates whether the server supports relative mouse mode.
displayId number The identifier for the display.

idleWarningNotificationCallback(disconnectionDateTime)

The callback function to be called when the Amazon DCV server sends an idle timeout warning.

Parameters:

Name Type Description
disconnectionDateTime Date The date and time of the disconnection.

collaboratorListCallback(collaborators)

The callback function to be called when the Amazon DCV server sends the list of collaborators.

Parameters:

Name Type Description
collaborators Array.<Object> A list of objects containing information on collaborators.
Name Type Description
username string The username of the collaborator.
owner boolean Indicates whether the collaborator is the session owner.
connectionId number Indicates the ID assigned by the server to the connection.

licenseNotificationCallback(notification)

The callback function to be called when the Amazon DCV server sends a notification about the license state.

Parameters:

Name Type Description
notification Object The notification.
Name Type Description
product string The DCV product.
status string The status of the license.
message string A message.
leftDays number The number of days before the license expires.
isDemo boolean Indicates if the license is a demo license.
numUnlicensed number The number of unlicensed connections.
licensingMode string The licensing mode.
documentationUrl string The URL for the documentation.

list(path)

Parameters:

Name Type Description
path string The absolute path on the server of which we want to list the content.

LogLevel

The available SDK log levels.

Type:

  • TRACE | DEBUG | INFO | WARN | ERROR | SILENT

Monitor

Type:

  • Object

Properties:

Name Type Description
name string The name of the display head.
rect Object Information about the display head.
Name Type Description
x number The initial x coordinate for the display head.
y number The initial y coordinate for the display head.
width number The width (in pixels) of the display head.
height number The height (in pixels) of the display head.
primary boolean Indicates whether the display head is the primary display head. This is determined from the remote operating system if available.
dpi number The DPI of the display head.

MultiMonitorErrorCode

The MultiMonitorError code enums available in the DCV module

  • NO_DISPLAY_CHANNEL

  • MAX_DISPLAY_NUMBER_REACHED

  • INVALID_ARGUMENT

  • DISPLAY_NOT_OPENED_BY_SERVER

  • REQUEST_TIMEOUT

  • GENERIC_ERROR

  • NO_ERROR

Type:

  • number

qualityIndicatorStateCallback(state)

The callback function to be called when the connection quality indicator changes state.

Parameters:

Name Type Description
state Array.<Object> Information about the connection quality.
Name Type Description
name string The name of the indicator.
status NORMAL | WARNING | CRITICAL Description of the status.
changed boolean Indicates whether the status changed.

renameDirectory(src, dest)

Parameters:

Name Type Description
src string The absolute source path on the server identifying the directory we want to rename.
dest string The absolute destination path on the server specifying the target path and directory name.

renameFile(src, dest)

Parameters:

Name Type Description
src string The absolute source path on the server identifying the file we want to rename.
dest string The absolute destination path on the server specifying the target path and file name.

ResolutionErrorCode

The ResolutionError code enums available in the DCV module

  • INVALID_ARGUMENT

  • NO_CHANNEL

  • NOT_IMPLEMENTED

Type:

  • number

retrieveFile(path)

Parameters:

Name Type Description
path string The absolute path on the server identifying the file we want to download locally.

screenshotCallback(screenshot)

The callback function to be called when a screenshot is available.

Parameters:

Name Type Description
screenshot byte[] Screenshot buffer in PNG format, or null if screenshot retrieval failed.

ScreenshotErrorCode

The ScreenshotError code enums available in the DCV module

  • NO_CHANNEL

  • GENERIC_ERROR

Type:

  • number

serverInfo

Type:

  • Object

Properties:

Name Type Description
name string The name of the software.
version Object The software version number.
Name Type Description
major number The major version number.
minor number The minor version number.
revision number The revision version number.
os string The OS.
arch string The architecture.
hostname string The hostname.

stats

Type:

  • Object

Properties:

Name Type Description
fps number The current frames per second.
traffic number The current traffic in bit/s.
peakTraffic number The peak of traffic in bit/s since the connection was established.
latency number The current latency in ms.
currentChannels number The number of channels that have been opened since the connection was established.
openedChannels number The number of currently opened channels.
channelErrors number The number of channels which have reported an error.

storeFile(file, dir)

Parameters:

Name Type Description
file File The file object (for more information see https://developer.mozilla.org/en-US/docs/Web/API/File) we want to upload to the server.
dir string The absolute path on the server where we want to upload the file.

TimezoneRedirectionErrorCode

The TimezoneRedirectionError code enums available in the DCV module

  • INVALID_ARGUMENT

  • NO_CHANNEL

  • USER_CANNOT_CHANGE

Type:

  • number

TimezoneRedirectionSettingCode

The TimezoneRedirectionSetting code enums available in the DCV module

  • ALWAYS_OFF

  • ALWAYS_ON

  • CLIENT_DECIDES

Type:

  • number

TimezoneRedirectionStatusCode

The TimezoneRedirectionStatus code enums available in the DCV module

  • SUCCESS

  • PERMISSION_ERROR

  • GENERIC_ERROR

Type:

  • number

WebcamErrorCode

The WebcamError code enums available in the DCV module

  • SETTING_WEBCAM_FAILED

  • CHANNEL_NOT_AVAILABLE

Type:

  • number

httpExtraSearchParamsCallback(method, url, body)

The callback function to be called to inject custom query parameters into URLs during authentication and connection establishment. This enables advanced integration scenarios, including the ability to append custom query parameters and add AWS Signature Version 4 (SigV4) signed values to secure and authorize connections through external systems.

This callback is also used to customize the URL that's used when establishing a WebSocket connection to the Amazon DCV server.

Parameters:

Name Type Description
method string The HTTP method being used for the request.
url string The URL that will be used for the request.
body string The request body content.

Returns:

URLSearchParams object containing the custom query parameters to be appended to the URL.

Type

URLSearchParams

httpExtraHeadersCallback(method, url, body)

The callback function to be called to insert custom headers (such as Authorization) to the HTTP request during connection establishment.

Parameters:

Name Type Description
method string The HTTP method being used for the request.
url string The URL that will be used for the request.
body string The request body content.

Returns:

Object containing key-value pairs representing the custom headers to be added to the HTTP request.

Type

Object