agc-node-rdp - npm explorer

node-rdp
========

[![NPM version][npm-version-image]][npm-url]
[![Apache License][license-image]][license-url]
[![NPM downloads][npm-downloads-image]][npm-url]

_Microsoft Remote Desktop Protocol wrapper for NodeJS_

Install via npm:

``shell $ npm install node-rdp --save`You can also use node-rdp as a shell command if you install it globally with the--globalmodifier. IMPORTANT: Windows is the only platform currently supported. I'm already working on adding Mac OS X support.

`Command Line Usage`

The

node-rdp

 usage follows the syntax:

shell

$ node-rdp -a 123.45.67.89:1337 -u DOMAIN\username -p thepassword





The needed parameters are:



*

-a

, --address

 (address to connect to)

*

-u , --username

 (username to use for connection)

*

-p , --password

 (password to use for connection)



Optional parameters are:



*

--colors

 (color depth in bits)

*

--launch

 (launch application after connection)

*

--launchdir

 (working directory for the application to be launched)

*

--no-clean

 (don't remove credentials and temporary files after disconnection)

*

--no-autoreconnect

 (don't auto-reconnect after an erroneous disconnection)

*

--no-fullscreen

 (don't launch as a fullscreen application)

*

--no-printers

 (disable printers)

*

--no-clipboard

 (disable clipboard)

*

--no-drives

 (disable all drives)



You can also use:



*

-h, --help

 (output usage information)

*

-V, --version

 (output the version number)



NPM Module Usage



Simply require the

node-rdp

 module and call the returned function with a configuration object as a single parameter.

The return value will be a

Promise

 object that will be resolved as soon as the connection is terminated.



The configuration object can contain the following parameters:



*

address: address to connect to (defaults to the empty string ''

)

*

username: username to use for connection (defaults to the empty string ''

)

*

password: password to use for connection (defaults to the empty string ''

)

*

deleteCredentialsAfter: deletes credentials and temporary files after disconnection (defaults to true

)

*

safeMode: enables a "safe mode" for handling the connection (see caveats) (defaults to false

)

*

autoReconnect: auto-reconnect after an erroneous disconnection (defaults to true

)

*

fullscreen: launch as a fullscreen application (defaults to true

)

*

colors: color depth in bits (defaults to 32

)

*

compression: determines if the connection must be compressed (defaults to true

)

*

connectionType: the type of the connection, can be one of 'modem', 'low', 'satellite', 'high', 'wan', 'lan', 'auto' (defaults to 'auto'

)

*

networkAutoDetect: set some connection parameters automatically depending on the detected network type (defaults to true

)

*

bandwidthAutoDetect: set some connection parameters automatically depending on the detected bandwidth type (defaults to true

)

*

showWallpaper: show the wallpaper on the remote computer (defaults to false

)

*

fontSmoothing: enable font smoothing (defaults to false

)

*

desktopComposition: enable desktop composition, useful for Aero (defaults to false

)

*

showDraggedWindow: show full window contents while dragging (defaults to false

)

*

showMenuAnimations: show menu animations (defaults to false

)

*

showThemes: show themes (defaults to true

)

*

showBlinkingCursor: show blinking cursor on input controls (defaults to true

)

*

audioPlayMode: determine which audio stream is played, can be one of 'local', 'remote', 'none' (defaults to 'local'

)

*

audioCaptureMode: enable capturing audio on the local computer (defaults to false

)

*

enableLocalPrinters: enable local printers on the remote computer (defaults to true

)

*

enableLocalCOMPorts: enable local COM ports on the remote computer (defaults to false

)

*

enableSmartCards: enable local smart cards on the remote computer (defaults to true

)

*

enableClipboard: enable clipboard sharing between the local and remote computers (defaults to true

enablePlugAndPlayDevices: determine a subset of Plug And Play devices (separated by a semi-colon ;) based on the specified HIDs or the wildcard (defaults to the empty string ''

enableDrives: determine a subset of local drives (separated by a semi-colon ;) for use on the remote computer, based on the labels or the wildcard (defaults to the empty string ''

)

*

enablePos: enable local Point of Service on the remote computer (defaults to false

)

*

launch: application to launch upon connection (defaults to the empty string ''

)

*

launchWorkingDirectory: working directory for the application to be launched upon connection (defaults to the empty string ''

)



The basic usage is shown below:

javascript

var rdp = require('node-rdp');



rdp({

  address: '123.45.67.89:1337',

  username: 'DOMAIN\username',

  password: 'thepassword'

}).then(function() {

  console.log('At this, point, the connection has terminated.');

});





All other options are pretty straightforward:

if you want to see all of your local computer's drives among the remote computer's ones, just do:

javascript

var rdp = require('node-rdp');



rdp({

  address: '123.45.67.89:1337',

  username: 'DOMAIN\username',

  password: 'thepassword',

  enableDrives: '*'

}).then(function() {

  console.log('At this, point, the connection has terminated.');

});







Hooplas Involving Circus Tricks (Caveats and Their Friends)



After saving the connection credentials in the system key store, the main RDP connection process is launched.

Sometimes, somehow, the launched process doesn't terminate by itself when the RDP window is closed by the user, causing

the returned promise to never be resolved. Eventually, after a timespan that ranges between a few seconds up to a solid

minute, the process finally closes, returning control to the Node process.



!I know, right?



_I know, right?_



If you need absolute certainty about the handling of the process you can enable

safeMode

 among the configuration

parameters; this mode won't resolve the

Promise with a simple object, but with a Deferred

 one as soon as the

connection is initiated, meaning you can manually resolve it whenever you want (e.g. you can prompt the user to press

some keys to manually terminate the process instead of relying on the window closing).

Also, when this deferred object is resolved, the RDP process will be force-killed by the

node-rdp

 module.



The following example implements a simple system that will force-close the connection after a minute.

javascript

var rdp = require('node-rdp');



rdp({

  address: '123.45.67.89:1337',

  username: 'DOMAIN\username',

  password: 'thepassword',

  safeMode: true

}).then(function(deferred) {

  // this function is entered as soon as the connection is initiated

  setTimeout(function() {

    // by forcing the rejection of the deferred, the connection will be terminated

    console.error('Timeout expired, force-killing the connection')

    deferred.reject();

  }, 1000 * 60);

});





The safe mode is not implemented in the

node-rdp

 global CLI, since you can simply force-close the process to terminate

all of its children, including the RDP client.



License



   Copyright 2015 Francesco Pontillo



   Licensed under the Apache License, Version 2.0 (the "License");

   you may not use this file except in compliance with the License.

   You may obtain a copy of the License at



       http://www.apache.org/licenses/LICENSE-2.0



   Unless required by applicable law or agreed to in writing, software

   distributed under the License is distributed on an "AS IS" BASIS,

   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

   See the License for the specific language governing permissions and

   limitations under the License.

``

[license-image]: http://img.shields.io/badge/license-Apache_2.0-blue.svg?style=flat
[license-url]: LICENSE

[npm-url]: https://npmjs.org/package/node-rdp
[npm-version-image]: http://img.shields.io/npm/v/node-rdp.svg?style=flat
[npm-downloads-image]: http://img.shields.io/npm/dm/node-rdp.svg?style=flat

Command Line Usage

The

usage follows the syntax:

shell
$ node-rdp -a 123.45.67.89:1337 -u DOMAIN\username -p thepassword

The needed parameters are:

*

, --address

 (address to connect to)

*

-u , --username

 (username to use for connection)

*

-p , --password

 (password to use for connection)



Optional parameters are:



*

--colors

 (color depth in bits)

*

--launch

 (launch application after connection)

*

--launchdir

 (working directory for the application to be launched)

*

--no-clean

 (don't remove credentials and temporary files after disconnection)

*

--no-autoreconnect

 (don't auto-reconnect after an erroneous disconnection)

*

--no-fullscreen

 (don't launch as a fullscreen application)

*

--no-printers

 (disable printers)

*

--no-clipboard

 (disable clipboard)

*

--no-drives

 (disable all drives)



You can also use:



*

-h, --help

 (output usage information)

*

-V, --version

 (output the version number)



NPM Module Usage



Simply require the

node-rdp

 module and call the returned function with a configuration object as a single parameter.

The return value will be a

Promise

 object that will be resolved as soon as the connection is terminated.



The configuration object can contain the following parameters:



*

address: address to connect to (defaults to the empty string ''

)

*

username: username to use for connection (defaults to the empty string ''

)

*

password: password to use for connection (defaults to the empty string ''

)

*

deleteCredentialsAfter: deletes credentials and temporary files after disconnection (defaults to true

)

*

safeMode: enables a "safe mode" for handling the connection (see caveats) (defaults to false

)

*

autoReconnect: auto-reconnect after an erroneous disconnection (defaults to true

)

*

fullscreen: launch as a fullscreen application (defaults to true

)

*

colors: color depth in bits (defaults to 32

)

*

compression: determines if the connection must be compressed (defaults to true

)

*

connectionType: the type of the connection, can be one of 'modem', 'low', 'satellite', 'high', 'wan', 'lan', 'auto' (defaults to 'auto'

)

*

networkAutoDetect: set some connection parameters automatically depending on the detected network type (defaults to true

)

*

bandwidthAutoDetect: set some connection parameters automatically depending on the detected bandwidth type (defaults to true

)

*

showWallpaper: show the wallpaper on the remote computer (defaults to false

)

*

fontSmoothing: enable font smoothing (defaults to false

)

*

desktopComposition: enable desktop composition, useful for Aero (defaults to false

)

*

showDraggedWindow: show full window contents while dragging (defaults to false

)

*

showMenuAnimations: show menu animations (defaults to false

)

*

showThemes: show themes (defaults to true

)

*

showBlinkingCursor: show blinking cursor on input controls (defaults to true

)

*

audioPlayMode: determine which audio stream is played, can be one of 'local', 'remote', 'none' (defaults to 'local'

)

*

audioCaptureMode: enable capturing audio on the local computer (defaults to false

)

*

enableLocalPrinters: enable local printers on the remote computer (defaults to true

)

*

enableLocalCOMPorts: enable local COM ports on the remote computer (defaults to false

)

*

enableSmartCards: enable local smart cards on the remote computer (defaults to true

)

*

enableClipboard: enable clipboard sharing between the local and remote computers (defaults to true

enablePlugAndPlayDevices: determine a subset of Plug And Play devices (separated by a semi-colon ;) based on the specified HIDs or the wildcard (defaults to the empty string ''

enableDrives: determine a subset of local drives (separated by a semi-colon ;) for use on the remote computer, based on the labels or the wildcard (defaults to the empty string ''

)

*

enablePos: enable local Point of Service on the remote computer (defaults to false

)

*

launch: application to launch upon connection (defaults to the empty string ''

)

*

launchWorkingDirectory: working directory for the application to be launched upon connection (defaults to the empty string ''

)



The basic usage is shown below:

javascript

var rdp = require('node-rdp');



rdp({

  address: '123.45.67.89:1337',

  username: 'DOMAIN\username',

  password: 'thepassword'

}).then(function() {

  console.log('At this, point, the connection has terminated.');

});





All other options are pretty straightforward:

if you want to see all of your local computer's drives among the remote computer's ones, just do:

javascript

var rdp = require('node-rdp');



rdp({

  address: '123.45.67.89:1337',

  username: 'DOMAIN\username',

  password: 'thepassword',

  enableDrives: '*'

}).then(function() {

  console.log('At this, point, the connection has terminated.');

});







Hooplas Involving Circus Tricks (Caveats and Their Friends)



After saving the connection credentials in the system key store, the main RDP connection process is launched.

Sometimes, somehow, the launched process doesn't terminate by itself when the RDP window is closed by the user, causing

the returned promise to never be resolved. Eventually, after a timespan that ranges between a few seconds up to a solid

minute, the process finally closes, returning control to the Node process.



!I know, right?



_I know, right?_



If you need absolute certainty about the handling of the process you can enable

safeMode

 among the configuration

parameters; this mode won't resolve the

Promise with a simple object, but with a Deferred

 one as soon as the

connection is initiated, meaning you can manually resolve it whenever you want (e.g. you can prompt the user to press

some keys to manually terminate the process instead of relying on the window closing).

Also, when this deferred object is resolved, the RDP process will be force-killed by the

node-rdp

 module.



The following example implements a simple system that will force-close the connection after a minute.

javascript

var rdp = require('node-rdp');



rdp({

  address: '123.45.67.89:1337',

  username: 'DOMAIN\username',

  password: 'thepassword',

  safeMode: true

}).then(function(deferred) {

  // this function is entered as soon as the connection is initiated

  setTimeout(function() {

    // by forcing the rejection of the deferred, the connection will be terminated

    console.error('Timeout expired, force-killing the connection')

    deferred.reject();

  }, 1000 * 60);

});





The safe mode is not implemented in the

node-rdp

 global CLI, since you can simply force-close the process to terminate

all of its children, including the RDP client.



License



   Copyright 2015 Francesco Pontillo



   Licensed under the Apache License, Version 2.0 (the "License");

   you may not use this file except in compliance with the License.

   You may obtain a copy of the License at



       http://www.apache.org/licenses/LICENSE-2.0



   Unless required by applicable law or agreed to in writing, software

   distributed under the License is distributed on an "AS IS" BASIS,

   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

   See the License for the specific language governing permissions and

   limitations under the License.