Connection Class - NICE DCV
Methods
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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

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.
Name Type Attributes Description
displayId number <optional> The ID of the display.
displayDivName The name of the display div.

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 NICE DCV server and closes the connection.

Returns:

Type

void

disconnectCollaborator(connectionId) → {void}

Requests disconnect of collaborator connected with the provided connection id (since NICE 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

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 NICE 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 NICE DCV server.

Returns:

Information about the server software.

Type

serverInfo

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 NICE DCV server.

Returns:

Information about the streaming statistics.

Type

stats

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 NICE 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 NICE DCV Web Client SDK 1.2.0 and NICE 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 NICE 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.
Name Type Description
sequence Array.<Object> The keyboard shortcut to register.
Name Type Description
key KeyboardEvent.key The value of the key pressed by the user. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key.
location KeyboardEvent.location The array of keys to send. The location of the key on the keyboard. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/location.
output Array.<Object> The intended action to be performed by the shortcut.
Name Type Description
key KeyboardEvent.key The value of the key pressed by the user. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key.
location KeyboardEvent.location The array of keys to send. The location of the key on the keyboard. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/location.

Returns:

Type

void

requestDisplayConfig(highColorAccuracy) → {Promise|Promise.<{code: DisplayConfigErrorCode, message: string}>}

Requests an updated display config from the NICE DCV Server. Available since NICE DCV Web Client SDK 1.1.0 and NICE 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 NICE 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/KeyboardEvent. Valid Keyboard events include: keydown, 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.
Name Type Description
key KeyboardEvent.key The value of the key pressed by the user. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key.
location KeyboardEvent.location The array of keys to send. The location of the key on the keyboard. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/location.

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 NICE 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.
Name Type Description
macOptionToAlt boolean To map the Option key to Alt for macOS, specify true. Otherwise, specify false.
macCommandToControl boolean To map the Command key to Ctrl for macOS, specify true. Otherwise, specify false.

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

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 | Promise.<{code: WebcamErrorCode, message: string}>

syncClipboards() → {boolean}

Synchronizes the local client clipboard with the remote NICE 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