https://github.com/jaganathanb/node-usbspy
An event based node.js c++ addon/binding to retrive the connected usb storage devices and detect the storage device insertion/removal and notifify the subscribed apps.
https://github.com/jaganathanb/node-usbspy
addon cpp javascript n-api nodejs
Last synced: about 2 months ago
JSON representation
An event based node.js c++ addon/binding to retrive the connected usb storage devices and detect the storage device insertion/removal and notifify the subscribed apps.
- Host: GitHub
- URL: https://github.com/jaganathanb/node-usbspy
- Owner: jaganathanb
- Created: 2017-12-29T13:38:12.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-07-17T11:39:37.000Z (almost 8 years ago)
- Last Synced: 2025-04-03T12:48:10.799Z (about 1 year ago)
- Topics: addon, cpp, javascript, n-api, nodejs
- Language: C++
- Homepage:
- Size: 66.4 KB
- Stars: 1
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: ReadMe.md
Awesome Lists containing this project
README
##### Note: Designed for Windows
# node-usbspy
An event based node.js c++ addon/binding to retrive the connected usb storage devices and detect the storage device insertion/removal and notifify the subscribed apps.
## Prerequisties for installation
Before installing this package, make sure you have Node.js addon build tool [node-gyp](https://github.com/nodejs/node-gyp) installed in your machine.
As `node-gyp` uses `Python 2.x`, make sure it is installed in your machine and it is on your EVN path.
If you dont have the python installed, then it is recommanded to install the `windows-build-tools`. To installl windows build tool, open CLI as adminstrator and execute the below command as per the issue discussed [here](https://github.com/felixrieseberg/windows-build-tools/issues/56).
```
npm --add-python-to-path='true' --debug install --global windows-build-tools
```
The above command would install pythin 2.x and build tools needed for windows. It would take few mins to complete the installation.
## Installation
To install `node-usbspy` execute the below command
if you prefer `npm`
```
npm install node-usbspy
```
for `yarn`,
```
yarn add node-usbspy
```
Upon installation, `node-gyp` would start generating the c++ addon project as per the configuration we set in `binding.gyp` and compile the same. If the compilation is successfull, it would have generated the executable lib files in the `build`folder with `Release` configuration.
## How to use it
`require('node-usbspy')` would populate the usbspy object which is of event type.
### Activating the detection(spying on the usb controller)
```
var usbspy = require('node-usbspy');
usbspy.spyOn().then(() => {
...
})
```
### Deactivating the detection
```
usbspy.spyOff() // would stop listening for the usb detection.
```
### Listening for change
There is an event `change` which would be emitted when a usb device is inserted or removed. You can subscribe for the event and do necessory action upon the event.
```
usbspy.on('change', (device) => {
console.log(device);
/* { device_number: 1,
device_status: 1,
device_letter: 'D:\\',
vendor_id: 'SanDisk ',
serial_number: '4C530001250818',
product_id: 'Cruze'
} */
});
usbspy.on('end', () => {
// would be triggered when you call `spyOff` function.
})
```
## API
### Properties
When an usb device is inserted, an `Device` object would be generated and emitted.
`Device` object has,
* `device_status` - It is an integer type property. The possible values for this property is 0 or 1 when 0 indicates the device is been removed from the system and the 1 indicated the device is been added.
* `device_letter` - It is an string type property. The letter assigned to device by the operating system when the usb device is inserted.
* `device_number` - It is an integer type property. The unique number assigned to every usb storage device inserted into the system by OS. Number starts from 1.
* `serial_number` - It is an string type property. The unique albha-numeric assigned to the usb storage device by the manufacturer.
* `vendor_id` - It is an string type property. The vendor id is assigned by the USB Implementers Forum to a specific company.
* `product_id` - It is an string type property. The product id is assigned by the company for the individual product.
### Methods
There are four methods available in `usbspy`.
#### spyOn([callback])
`spyOn` method takes a callback as parameter and returns a promise object. Here `callback` is optional. Since spyOn returns promise, you can use `then` to kick start the detection.
When the addon is ready, `callback` would be called with `true` which indicates everything is OK if passed otherwise the promise would be resolve/rejected.
#### spyOff()
`spyOff` should be called when you wanted to stop listening for the usb device change.
#### getAvailableUSBStorageDevices()
`getAvailableUSBStorageDevices` would written list of `Device` objects if available otherwise empty list would be returned. This method does not take any arguments.
#### getUSBStorageDeviceByPropertyName(propertyName, value)
This method takes two arguments. The `propertyName` could be any of the `Device` properties. The `value` should be the actual value of the property. This method returns `Device` object if the property/value passed matches any of the available usb storage devices.
### Events
There are two events emitted from the `usbspy` module.
#### change - usbspy.on('change' callback(device))
When any usb storage device is been inserted/removed into/from the machine, `change` event would be triggered with the `Device` object.
#### end - usbspy.on('end', callback)
When the `spyOff` method is called, the `end` event would be triggered.
## Example
You can have a look into `example/test.js` for usage and example.
```
var usbspy = require('../index');
usbspy.spyOn().then(function() {
usbspy.on('change', function(data) {
console.log(data);
});
usbspy.on('end', function(data) {
console.log(data);
});
console.log(usbspy.getAvailableUSBStorageDevices());
console.log(usbspy.getUSBStorageDeviceByPropertyName('device_letter', 'D:\\'));
console.log(usbspy.getUSBStorageDeviceByPropertyName('device_number', 1));
});
setTimeout(() => {
usbspy.spyOff();
}, 5000); // after 5 secs, would stop wathcing for device change.
```
##### Note:
When you DEBUG the c++ code, you have to comment the line#18 in the `usbspy.h`