Connection Class
The Connection Class obtained by calling the connect
method of the dcv module. For an example showing how to use it,
see the Getting started section.
Exposes
Methods
List
- attachDisplay(win, displayConf) → {Promise.<number>|Promise.<{code: MultiMonitorErrorCode, message: string}>}
- captureClipboardEvents(enabled, win, displayId) → {void}
- detachDisplay(displayId) → {void}
- disconnect() → {void}
- disconnectCollaborator(connectionId) → {void}
- enableDisplayQualityUpdates(enable) → {void}
- enableHighPixelDensity(enable) → {void}
- enableTimezoneRedirection(enable) → {Promise|Promise.<{code: TimezoneRedirectionErrorCode, message: string}>}
- enterRelativeMouseMode() → {void}
- getConnectedDevices() → {Promise.<Array.<MediaDeviceInfo>>|Promise.<{message: string}>}
- getFileExplorer() → {Promise.<filestorage>|Promise.<{code: ChannelErrorCode, message: string}>}
- getServerInfo() → {serverInfo}
- getScreenshot() → {Promise|Promise.<{code: ScreenshotErrorCode, message: string}>}
- getStats() → {stats}
- latchModifierKey(key, location, isDown) → {boolean}
- openChannel(name, authToken, callbacks, namespace) → {Promise|Promise.<{code: ChannelErrorCode, message: string}>}
- queryFeature(featureName) → {Promise.<{enabled: boolean, remote?: string, autoCopy?: boolean, autoPaste?: boolean, serviceStatus?: string, available?: boolean}>|Promise.<{message: string}>}
- registerKeyboardShortcuts(shortcuts) → {void}
- requestDisplayConfig(highColorAccuracy) → {Promise|Promise.<{code: DisplayConfigErrorCode, message: string}>}
- requestDisplayLayout(layout) → {Promise|Promise.<{code: ResolutionErrorCode, message: string}>}
- requestResolution(width, height) → {Promise|Promise.<{code: ResolutionErrorCode, message: string}>}
- sendKeyboardEvent(event) → {boolean}
- sendKeyboardShortcut(shortcut) → {void}
- setDisplayQuality(min, maxopt) → {void}
- setDisplayScale(scaleRatio, displayId) → {Promise|Promise.<{code: ResolutionErrorCode, message: string}>} (DEPRECATED)
- setKeyboardQuirks(quirks) → {void}
- setMaxDisplayResolution(maxWidth, maxHeight) → {void}
- setMicrophone(enable) → {Promise|Promise.<{code: AudioErrorCode, message: string}>}
- setMinDisplayResolution(minWidth, minHeight) → {void}
- setUploadBandwidth(value) → {number}
- setVolume(volume) → {void}
- setMicrophone(enable, deviceId) → {Promise|Promise.<{code: AudioErrorCode, message: string}>}
- setWebcam(enable, deviceId) → {Promise|Promise.<{code: WebcamErrorCode, message: string}>}
- syncClipboards() → {boolean}
attachDisplay(win, displayConf) → {Promise.<number>|Promise.<{code: MultiMonitorErrorCode, message: string}>}
Attaches a specific display to a window. You can't attach the
main display. If successful, the function returns the
displayId.
Parameters:
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
win
|
Object | The window to which the display must be attached. | ||||||||||||
displayConf
|
Object |
The configuration of the display.
|
Returns:
Promise. If rejected, the promise returns an error object.
- Type
-
Promise.<number> | Promise.<{code: MultiMonitorErrorCode, message: string}>
captureClipboardEvents(enabled, win, displayId) → {void}
Starts or stops listening to copy-paste events. In the case of interactive clipboards (always in the case of paste) we need to start listening to the copy/paste events. It could be useful to start and stop listening only when it is needed, for example, when a modal is shown.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
enabled
|
boolean |
To start listening to events, specify
true. To stop listening to
events, specify false.
|
|
win
|
Object | <optional> | The window in which to listen for events. If omitted, the default window is used. |
displayId
|
number | <optional> | The ID of the display that should listen the events. If omitted, the default display of the window is used. |
Returns:
- Type
-
void
detachDisplay(displayId) → {void}
Detaches a specific display. The main display cannot be detached.
Parameters:
| Name | Type | Description |
|---|---|---|
displayId
|
number | The ID of the display to detach. |
Returns:
- Type
-
void
disconnect() → {void}
Disconnects from the Amazon DCV server and closes the connection.
Returns:
- Type
-
void
disconnectCollaborator(connectionId) → {void}
Requests disconnect of collaborator connected with the provided connection id (since Amazon DCV Web Client SDK version 1.1.0).
Parameters:
| Name | Type | Description |
|---|---|---|
connectionId
|
boolean | The id of the connection that will be disconnected. |
Returns:
- Type
-
void
enableDisplayQualityUpdates(enable) → {void}
Enables or disables display quality updates for streaming areas that do not receive updates. Disabling display quality updates reduces bandwidth usage, but it also decreases the display quality.
Parameters:
| Name | Type | Description |
|---|---|---|
enable
|
boolean |
To enable display quality updates, specify
true. To disable display quality
updates, specify false.
|
Returns:
- Type
-
void
enableHighPixelDensity(enable) → {void}
Enables or disables high pixel density on the client.
Parameters:
| Name | Type | Description |
|---|---|---|
enable
|
boolean | Whether or not high pixel density should be enabled. |
Returns:
- Type
-
void
enableTimezoneRedirection(enable) → {Promise|Promise.<{code: TimezoneRedirectionErrorCode, message: string}>}
Enables or disables timezone redirection. Once it is enabled, the client requests the server to make the server desktop timezone match the client timezone.
Parameters:
| Name | Type | Description |
|---|---|---|
enable
|
boolean |
To enable timezone redirection, specify true.
To disable timezone redirection, specify false.
|
Returns:
Promise. If rejected, the promise returns an error object.
- Type
-
Promise.<number> | Promise.<{code: TimezoneRedirectionErrorCode, message: string}>
enterRelativeMouseMode() → {void}
Enables relative mouse mode.
Returns:
- Type
-
void
getConnectedDevices() → {Promise.<Array.<MediaDeviceInfo>>|Promise.<{message: string}>}
Requests a list of the media devices connected to the client computer.
Returns:
If successful, it returns a Promise that resolves to an array of MediaDeviceInfo objects. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo. If rejected, the promise returns an error object.
- Type
-
Promise.<Array.<MediaDeviceInfo>> | Promise.<{message: string}>
getFileExplorer() → {Promise.<filestorage>|Promise.<{code: ChannelErrorCode, message: string}>}
Gets an object to manage the Amazon DCV server's file storage.
Returns:
Promise. Resolves to the file explorer object if fulfilled, or an error object if rejected.
- Type
-
Promise.<filestorage> | Promise.<{code: ChannelErrorCode, message: string}>
getServerInfo() → {serverInfo}
Gets information about the Amazon DCV server.
Returns:
Information about the server software.
- Type
getScreenshot() → {Promise|Promise.<{code: ScreenshotErrorCode, message: string}>}
Retrieves the screenshot of the remote desktop in PNG format.
The screenshot will be returned in the screenshotCallback observer. null will be returned instead in case of failures.
Returns:
Promise that resolves if the request is processed. If rejected we receive an error object.
- Type
-
Promise | Promise.<{code: ScreenshotErrorCode, message: string}>
getStats() → {stats}
Gets statistics about the Amazon DCV server.
Returns:
Information about the streaming statistics.
- Type
latchModifierKey(key, location, isDown) → {boolean}
Sends a single keyboard keydown or
keyup event for an allowed modifier.
Parameters:
| Name | Type | Description |
|---|---|---|
key
|
Control | Alt | AltGraph | Meta | OS | Shift | The key to send. |
location
|
KeyboardEvent.location | The key's location. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/location. |
isDown
|
boolean |
If the key event to inject is a keydown
(true) or a keyup
(false).
|
Returns:
If the requested combination is valid, the function returns
true, otherwise it returns
false.
- Type
-
boolean
openChannel(name, authToken, callbacks, namespace) → {Promise|Promise.<{code: ChannelErrorCode, message: string}>}
Opens a custom data channel on the connection if it was created on the Amazon DCV Server.
Parameters:
| Name | Type | Description |
|---|---|---|
name
|
string | The name of the channel. |
authToken
|
string | The authentication token to use to connect to the channel. |
callbacks
|
Object | The onMessage and onClose callbacks functions to call. |
namespace
|
string | The namespace of the channel. Available since Amazon DCV Web Client SDK 1.2.0 and Amazon DCV Server 2022.1. |
Returns:
Promise. If rejected we receive an error object.
- Type
-
Promise | Promise.<{code: ChannelErrorCode, message: string}>
queryFeature(featureName) → {Promise.<{enabled: boolean, remote?: string, autoCopy?: boolean, autoPaste?: boolean, serviceStatus?: string, available?: boolean}>|Promise.<{message: string}>}
Queries the status of a specific Amazon DCV server feature.
Parameters:
| Name | Type | Description |
|---|---|---|
featureName
|
feature | The name of the feature to query. |
Returns:
Promise. If resolved, the function returns a
status object that always containes an
enabled property, and possibly also
other properties. If rejected, the
function returns an error object.
- Type
-
{Promise.<{enabled: boolean, remote?: string, autoCopy?: boolean, autoPaste?: boolean, serviceStatus?: string, available?: boolean}> | Promise.<{message: string}>
registerKeyboardShortcuts(shortcuts) → {void}
Registers keyboard shortcuts.
Parameters:
| Name | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
shortcuts
|
Array.<Object> |
The array of keys and mappings to register.
|
Returns:
- Type
-
void
requestDisplayConfig(highColorAccuracy) → {Promise|Promise.<{code: DisplayConfigErrorCode, message: string}>}
Requests an updated display config from the Amazon DCV Server. Available since Amazon DCV Web Client SDK 1.1.0 and Amazon DCV Server 2022.0.
Parameters:
| Name | Type | Description |
|---|---|---|
highColorAccuracy
|
boolean | Whether or not high color accuracy should be requested. |
Returns:
Promise. If rejected, the promise returns an error object.
- Type
-
Promise | Promise.<{code: DisplayConfigErrorCode, message: string}>
requestDisplayLayout(layout) → {Promise|Promise.<{code: ResolutionErrorCode, message: string}>}
Requests an updated display layout for the connection.
Parameters:
| Name | Type | Description |
|---|---|---|
layout
|
Array.<Monitor> | The requested displays in the layout. |
Returns:
Promise. If rejected we receive an error object.
- Type
-
Promise | Promise.<{code: ResolutionErrorCode, message: string}>
requestResolution(width, height) → {Promise|Promise.<{code: ResolutionErrorCode, message: string}>}
Requests an updated display resolution from the Amazon DCV server.
Parameters:
| Name | Type | Description |
|---|---|---|
width
|
number |
The width to request in pixels. The minimum allowed
value is 0.
|
height
|
number |
The height to request in pixels. The minimum allowed
value is 0.
|
Returns:
Promise. If rejected, the promise returns an error object.
- Type
-
Promise | Promise.<{code: ResolutionErrorCode, message: string}>
sendKeyboardEvent(event) → {boolean}
Sends a keyboard shortcut event. For more information about keyboard events,
see
https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEventkeydown, keypress, and
keyup. For more information about these events, see
https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent#events
Parameters:
| Name | Type | Description |
|---|---|---|
event
|
KeyboardEvent | The keyboard event to send. |
Returns:
If the event is not valid, the function returns
false. If the event is valid, the
function returns true.
- Type
-
boolean
sendKeyboardShortcut(shortcut) → {void}
Sends a keyboard shortcut. Use this function to send a full
keydown or keyup
sequence. For example, sending Ctrl + Alt + Del sends the
keydown events for all the keys followed by
the keyup events. Use this function even if
you want to send a single key.
Parameters:
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
shortcut
|
Array.<Object> |
The array of keys to send.
|
Returns:
- Type
-
void
setDisplayQuality(min, maxopt) → {void}
Sets the image quality to use for the connection. Valid range
is 0 to 100, with
1 being the lowest image quality and
100 being the highest image quality.
Specify 0 to retain the current value.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
min
|
number | The minimum image quality. | |
max
|
number | <optional> | The maximum image quality. |
Returns:
- Type
-
void
setDisplayScale(scaleRatio, displayId) → {Promise|Promise.<{code: ResolutionErrorCode, message: string}>} (DEPRECATED)
Deprecated since version 1.3.0. There is no need to set the display scale anymore. Mouse coordinates will be managed automatically internally.
Notifies the Amazon DCV that the display is scaled on the client side. Use this to notify the server that it needs to scale mouse events to match the client's display ratio.
Parameters:
| Name | Type | Description |
|---|---|---|
scaleRatio
|
float | The scaling ratio to use. Must be a strictly positive number. |
displayId
|
number | The ID of the display to scale. |
Returns:
Promise. If rejected, the promise returns an error object.
- Type
-
Promise | Promise.<{code: ResolutionErrorCode, message: string}>
setKeyboardQuirks(quirks) → {void}
Sets keyboard quirks for the client computer.
Parameters:
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
quirks
|
Object |
The keyboard quirks to enable or disable.
|
Returns:
- Type
-
void
setMaxDisplayResolution(maxWidth, maxHeight) → {void}
Sets the maximum display resolution to use for the connection.
Parameters:
| Name | Type | Description |
|---|---|---|
maxWidth
|
number |
The maximum display width in pixels. The minimum
allowed value is 0.
|
maxHeight
|
number |
The maximum display height in pixels. The minimum
allowed value is 0.
|
Returns:
- Type
-
void
setMicrophone(enable) → {Promise|Promise.<{code: AudioErrorCode, message: string}>}
Enables or disables the microphone.
Parameters:
| Name | Type | Description |
|---|---|---|
enable
|
boolean |
To enable the microphone, specify
true. To disable the microphone,
specify false.
|
Returns:
Promise. If rejected, the promise returns an error object.
- Type
-
Promise | Promise.<{code: AudioErrorCode, message: string}>
setMinDisplayResolution(minWidth, minHeight) → {void}
Sets the minimum display resolution to use for the connection. Some applications might require a minimum display resolution. If the minimum required resolution is larger than the maximum resolution supported by the client, a resize strategy is used. Use this function carefully. The resize strategy could cause a less precise mouse and touch input system.
Parameters:
| Name | Type | Description |
|---|---|---|
minWidth
|
number |
The minimum display width in pixels. The minimum
allowed value is 0.
|
minHeight
|
number |
The minimum display height in pixels. The minimum
allowed value is 0.
|
Returns:
- Type
-
void
setUploadBandwidth(value) → {number}
Sets the maxmimum bandwidth to use for uploading files to the Amazon DCV server.
Parameters:
| Name | Type | Description |
|---|---|---|
value
|
number | The maximum bandwidth limit in kbps. Valid range is 1024 kbps to 102400 kbps. |
Returns:
- The set bandwidth limit. null if the
file storage feature is disabled on the server.
- Type
-
number
setVolume(volume) → {void}
Sets the volume level to use for audio. Valid range is 0 to 100, with 0 being the lowest volume and 100 being the highest volume.
Parameters:
| Name | Type | Description |
|---|---|---|
volume
|
number | The volume level to use. |
Returns:
- Type
-
void
setMicrophone(enable, deviceId) → {Promise|Promise.<{code: AudioErrorCode, message: string}>}
[Experimental - might change in the future] Enables or disables the microphone.
Parameters:
| Name | Type | Description |
|---|---|---|
enable
|
boolean |
To enable the microphone, specify
true. To disable the microphone,
specify false.
|
deviceId
|
string |
The device ID of the microphone. If no deviceId is provided, the default deviceId is used.
|
Returns:
Promise. If rejected, the promise returns an error object.
- Type
-
Promise | Promise.<{code: AudioErrorCode, message: string}>
setWebcam(enable, deviceId) → {Promise|Promise.<{code: WebcamErrorCode, message: string}>}
Enables or disables the webcam.
Parameters:
| Name | Type | Description |
|---|---|---|
enable
|
boolean |
To enable the webcam, specify
true. To disable the webcam,
specify false.
|
deviceId
|
string | The device ID of the webcam. |
Returns:
Promise that, if successful, resolves to the attached/detached webcam deviceId. If rejected, the promise returns an error object.
- Type
-
Promise.<string> | Promise.<{code: WebcamErrorCode, message: string}>
syncClipboards() → {boolean}
Synchronizes the local client clipboard with the remote Amazon DCV server clipboard. Autocopy must be supported by the browser.
Returns:
If the clipboards have been synchronized, the function
returns true. If the clipboards have not
been sycnhronized, or if the browser does not support
autocopy, the function returns false.
- Type
-
boolean
