feat: low level read API (#27)

README.md

@@ -139,7 +139,7 @@ smb2Client.rename('path\\to\\my\\file.txt', 'new\\path\\to\\my\\new-file-name.tx
 });
 ```
 
-### smb2Client.close ( )
+### smb2Client.disconnect ( )
 This function will close the open connection if opened, it will be called automatically after ```autoCloseTimeout``` ms of no SMB2 call on the server.
 
 ### smb2Client.createReadStream ( fileName, [options], callback )
@@ -168,6 +168,31 @@ smb2Client.createWriteStream('path\\to\\the\\file', function (err, readStream) {
 ### smb2Client.ensureDir ( path, callback )
 Ensures that the directory exists. If the directory structure does not exist, it is created.
 
+### Low-level API
+
+```javascript
+smb2Client.open('path\\to\\the\\file', function (err, fd) {
+    if (err) throw err;
+
+    smb2Client.read(
+        Buffer.alloc(10), // buffer where to store the data
+        0,                // offset in the buffer
+        10,               // number of bytes to read
+        0,                // offset in the file
+        function (err, bytesRead, buffer) {
+            smb2Client.close(fd, function () {})
+
+            if (err) throw cb(err)
+            console.log(bytesRead, buffer)
+        }
+    )
+})
+```
+
+> This API is modeled after Node's `fs` module.
+
+> Note: be careful of `autoCloseTimeout` with this process as it is not intended to cover multiple method calls, you should set it to `0` and manually `disconnect()`.
+
 ## Contributors
 - [Benjamin Chelli](https://github.com/bchelli)
 - [Fabrice Marsaud](https://github.com/marsaud)

lib/api/close.js

-var SMB2Connection = require('../tools/smb2-connection');
+var request = require('../tools/smb2-forge').request;
 
-/*
- * close
- * =====
- *
- * close your connection to the SMB2 server
- *
- *  - close TCP connection
- *
- */
-module.exports = function() {
-  SMB2Connection.close(this);
+module.exports = function close(file, cb) {
+  request('close', file, this, cb);
 };

lib/api/disconnect.js

+var SMB2Connection = require('../tools/smb2-connection');
+
+/*
+ * close
+ * =====
+ *
+ * close your connection to the SMB2 server
+ *
+ *  - close TCP connection
+ *
+ */
+module.exports = function() {
+  SMB2Connection.close(this);
+};

lib/api/open.js

+var request = require('../tools/smb2-forge').request;
+
+module.exports = function open(path, cb) {
+  request('open', { path: path }, this, cb);
+};

lib/api/read.js

+var assert = require('assert');
+
+var BigInt = require('../tools/bigint');
+var request = require('../tools/smb2-forge').request;
+var MAX_READ_LENGTH = require('../structures/constants').MAX_READ_LENGTH;
+
+module.exports = function read(file, buffer, offset, length, position, cb) {
+  assert(position !== null, 'null position is not supported');
+
+  var fileSize = BigInt.fromBuffer(file.EndofFile);
+  var bytesRead = 0;
+  var connection = this;
+
+  position = new BigInt(8, position);
+
+  function onRead(err, chunk) {
+    if (err != null) {
+      return cb(err, buffer, bytesRead);
+    }
+
+    chunk.copy(buffer, offset);
+
+    var n = chunk.length;
+    bytesRead += n;
+    offset += n;
+    position = position.add(n);
+
+    readChunk();
+  }
+  function readChunk() {
+    if (bytesRead >= length || position.ge(fileSize)) {
+      return cb(null, buffer, bytesRead);
+    }
+    request(
+      'read',
+      {
+        FileId: file.FileId,
+        Length: Math.min(MAX_READ_LENGTH, length - bytesRead),
+        Offset: position.toBuffer(),
+      },
+      connection,
+      onRead
+    );
+  }
+
+  process.nextTick(readChunk);
+};

lib/api/readfile.js

 var SMB2Forge = require('../tools/smb2-forge'),
   SMB2Request = SMB2Forge.request,
-  bigint = require('../tools/bigint');
+  bigint = require('../tools/bigint'),
+  MAX_READ_LENGTH = require('../structures/constants').MAX_READ_LENGTH;
 
 /*
  * readFile
@@ -30,8 +31,7 @@ module.exports = function(filename, options, cb) {
       var fileLength = 0,
         offset = new bigint(8),
         stop = false,
-        nbRemainingPackets = 0,
-        maxPacketSize = 0x00010000;
+        nbRemainingPackets = 0;
       // get file length
       for (var i = 0; i < file.EndofFile.length; i++) {
         fileLength += file.EndofFile[i] * Math.pow(2, i * 8);
@@ -72,8 +72,8 @@ module.exports = function(filename, options, cb) {
         ) {
           // process packet size
           var rest = offset.sub(fileLength).neg();
-          var packetSize = rest.gt(maxPacketSize)
-            ? maxPacketSize
+          var packetSize = rest.gt(MAX_READ_LENGTH)
+            ? MAX_READ_LENGTH
             : rest.toNumber();
           // generate buffer
           SMB2Request(

lib/smb2.js

@@ -78,7 +78,7 @@ var SMB = (module.exports = function(opt) {
  */
 var proto = (SMB.prototype = {});
 
-proto.close = require('./api/close');
+proto.disconnect = require('./api/disconnect');
 
 proto.exists = SMB2Connection.requireConnect(require('./api/exists'));
 
@@ -100,3 +100,7 @@ proto.mkdir = SMB2Connection.requireConnect(require('./api/mkdir'));
 
 proto.ensureDir = SMB2Connection.requireConnect(require('./api/ensureDir'));
 proto.getSize = SMB2Connection.requireConnect(require('./api/getSize'));
+
+proto.open = SMB2Connection.requireConnect(require('./api/open'));
+proto.read = require('./api/read');
+proto.closeFile = require('./api/closeFile');

lib/structures/constants.js

@@ -9,4 +9,7 @@ module.exports = {
   FILE_OPEN_IF: 0x00000003,
   FILE_OVERWRITE: 0x00000004,
   FILE_OVERWRITE_IF: 0x00000005,
+
+  // Where does it come from?!
+  MAX_READ_LENGTH: 0x00010000,
 };

lib/tools/smb2-connection.js

@@ -134,7 +134,7 @@ function setAutoCloseTimeout(connection) {
   clearAutoCloseTimeout(connection);
   if (connection.autoCloseTimeout != 0) {
     connection.scheduledAutoClose = setTimeout(function() {
-      connection.close();
+      SMB2Connection.close(connection);
     }, connection.autoCloseTimeout);
   }
 }