Haha-Yes/node_modules/ref/lib/ref.js
2018-09-09 21:20:36 +02:00

1463 lines
39 KiB
JavaScript

var assert = require('assert')
var inspect = require('util').inspect
var debug = require('debug')('ref')
exports = module.exports = require('bindings')('binding')
/**
* A `Buffer` that references the C NULL pointer. That is, its memory address
* points to 0. Its `length` is 0 because accessing any data from this buffer
* would cause a _segmentation fault_.
*
* ```
* console.log(ref.NULL);
* <SlowBuffer@0x0 >
* ```
*
* @name NULL
* @type Buffer
*/
/**
* A string that represents the native endianness of the machine's processor.
* The possible values are either `"LE"` or `"BE"`.
*
* ```
* console.log(ref.endianness);
* 'LE'
* ```
*
* @name endianness
* @type String
*/
/**
* Accepts a `Buffer` instance and returns the memory address of the buffer
* instance.
*
* ```
* console.log(ref.address(new Buffer(1)));
* 4320233616
*
* console.log(ref.address(ref.NULL)));
* 0
* ```
*
* @param {Buffer} buffer The buffer to get the memory address of.
* @return {Number} The memory address the buffer instance.
* @name address
* @type method
*/
/**
* Accepts a `Buffer` instance and returns _true_ if the buffer represents the
* NULL pointer, _false_ otherwise.
*
* ```
* console.log(ref.isNull(new Buffer(1)));
* false
*
* console.log(ref.isNull(ref.NULL));
* true
* ```
*
* @param {Buffer} buffer The buffer to check for NULL.
* @return {Boolean} true or false.
* @name isNull
* @type method
*/
/**
* Reads a JavaScript Object that has previously been written to the given
* _buffer_ at the given _offset_.
*
* ```
* var obj = { foo: 'bar' };
* var buf = ref.alloc('Object', obj);
*
* var obj2 = ref.readObject(buf, 0);
* console.log(obj === obj2);
* true
* ```
*
* @param {Buffer} buffer The buffer to read an Object from.
* @param {Number} offset The offset to begin reading from.
* @return {Object} The Object that was read from _buffer_.
* @name readObject
* @type method
*/
/**
* Reads a Buffer instance from the given _buffer_ at the given _offset_.
* The _size_ parameter specifies the `length` of the returned Buffer instance,
* which defaults to __0__.
*
* ```
* var buf = new Buffer('hello world');
* var pointer = ref.alloc('pointer');
*
* var buf2 = ref.readPointer(pointer, 0, buf.length);
* console.log(buf.toString());
* 'hello world'
* ```
*
* @param {Buffer} buffer The buffer to read a Buffer from.
* @param {Number} offset The offset to begin reading from.
* @param {Number} length (optional) The length of the returned Buffer. Defaults to 0.
* @return {Buffer} The Buffer instance that was read from _buffer_.
* @name readPointer
* @type method
*/
/**
* Returns a JavaScript String read from _buffer_ at the given _offset_. The
* C String is read until the first NULL byte, which indicates the end of the
* String.
*
* This function can read beyond the `length` of a Buffer.
*
* ```
* var buf = new Buffer('hello\0world\0');
*
* var str = ref.readCString(buf, 0);
* console.log(str);
* 'hello'
* ```
*
* @param {Buffer} buffer The buffer to read a Buffer from.
* @param {Number} offset The offset to begin reading from.
* @return {String} The String that was read from _buffer_.
* @name readCString
* @type method
*/
/**
* Returns a big-endian signed 64-bit int read from _buffer_ at the given
* _offset_.
*
* If the returned value will fit inside a JavaScript Number without losing
* precision, then a Number is returned, otherwise a String is returned.
*
* ```
* var buf = ref.alloc('int64');
* ref.writeInt64BE(buf, 0, '9223372036854775807');
*
* var val = ref.readInt64BE(buf, 0)
* console.log(val)
* '9223372036854775807'
* ```
*
* @param {Buffer} buffer The buffer to read a Buffer from.
* @param {Number} offset The offset to begin reading from.
* @return {Number|String} The Number or String that was read from _buffer_.
* @name readInt64BE
* @type method
*/
/**
* Returns a little-endian signed 64-bit int read from _buffer_ at the given
* _offset_.
*
* If the returned value will fit inside a JavaScript Number without losing
* precision, then a Number is returned, otherwise a String is returned.
*
* ```
* var buf = ref.alloc('int64');
* ref.writeInt64LE(buf, 0, '9223372036854775807');
*
* var val = ref.readInt64LE(buf, 0)
* console.log(val)
* '9223372036854775807'
* ```
*
* @param {Buffer} buffer The buffer to read a Buffer from.
* @param {Number} offset The offset to begin reading from.
* @return {Number|String} The Number or String that was read from _buffer_.
* @name readInt64LE
* @type method
*/
/**
* Returns a big-endian unsigned 64-bit int read from _buffer_ at the given
* _offset_.
*
* If the returned value will fit inside a JavaScript Number without losing
* precision, then a Number is returned, otherwise a String is returned.
*
* ```
* var buf = ref.alloc('uint64');
* ref.writeUInt64BE(buf, 0, '18446744073709551615');
*
* var val = ref.readUInt64BE(buf, 0)
* console.log(val)
* '18446744073709551615'
* ```
*
* @param {Buffer} buffer The buffer to read a Buffer from.
* @param {Number} offset The offset to begin reading from.
* @return {Number|String} The Number or String that was read from _buffer_.
* @name readUInt64BE
* @type method
*/
/**
* Returns a little-endian unsigned 64-bit int read from _buffer_ at the given
* _offset_.
*
* If the returned value will fit inside a JavaScript Number without losing
* precision, then a Number is returned, otherwise a String is returned.
*
* ```
* var buf = ref.alloc('uint64');
* ref.writeUInt64LE(buf, 0, '18446744073709551615');
*
* var val = ref.readUInt64LE(buf, 0)
* console.log(val)
* '18446744073709551615'
* ```
*
* @param {Buffer} buffer The buffer to read a Buffer from.
* @param {Number} offset The offset to begin reading from.
* @return {Number|String} The Number or String that was read from _buffer_.
* @name readUInt64LE
* @type method
*/
/**
* Writes the _input_ Number or String as a big-endian signed 64-bit int into
* _buffer_ at the given _offset_.
*
* ```
* var buf = ref.alloc('int64');
* ref.writeInt64BE(buf, 0, '9223372036854775807');
* ```
*
* @param {Buffer} buffer The buffer to write to.
* @param {Number} offset The offset to begin writing from.
* @param {Number|String} input This String or Number which gets written.
* @name writeInt64BE
* @type method
*/
/**
* Writes the _input_ Number or String as a little-endian signed 64-bit int into
* _buffer_ at the given _offset_.
*
* ```
* var buf = ref.alloc('int64');
* ref.writeInt64LE(buf, 0, '9223372036854775807');
* ```
*
* @param {Buffer} buffer The buffer to write to.
* @param {Number} offset The offset to begin writing from.
* @param {Number|String} input This String or Number which gets written.
* @name writeInt64LE
* @type method
*/
/**
* Writes the _input_ Number or String as a big-endian unsigned 64-bit int into
* _buffer_ at the given _offset_.
*
* ```
* var buf = ref.alloc('uint64');
* ref.writeUInt64BE(buf, 0, '18446744073709551615');
* ```
*
* @param {Buffer} buffer The buffer to write to.
* @param {Number} offset The offset to begin writing from.
* @param {Number|String} input This String or Number which gets written.
* @name writeUInt64BE
* @type method
*/
/**
* Writes the _input_ Number or String as a little-endian unsigned 64-bit int
* into _buffer_ at the given _offset_.
*
* ```
* var buf = ref.alloc('uint64');
* ref.writeUInt64LE(buf, 0, '18446744073709551615');
* ```
*
* @param {Buffer} buffer The buffer to write to.
* @param {Number} offset The offset to begin writing from.
* @param {Number|String} input This String or Number which gets written.
* @name writeUInt64LE
* @type method
*/
/**
* Returns a new clone of the given "type" object, with its
* `indirection` level incremented by **1**.
*
* Say you wanted to create a type representing a `void *`:
*
* ```
* var voidPtrType = ref.refType(ref.types.void);
* ```
*
* @param {Object|String} type The "type" object to create a reference type from. Strings get coerced first.
* @return {Object} The new "type" object with its `indirection` incremented by 1.
*/
exports.refType = function refType (type) {
var _type = exports.coerceType(type)
var rtn = Object.create(_type)
rtn.indirection++
if (_type.name) {
Object.defineProperty(rtn, 'name', {
value: _type.name + '*',
configurable: true,
enumerable: true,
writable: true
})
}
return rtn
}
/**
* Returns a new clone of the given "type" object, with its
* `indirection` level decremented by 1.
*
* @param {Object|String} type The "type" object to create a dereference type from. Strings get coerced first.
* @return {Object} The new "type" object with its `indirection` decremented by 1.
*/
exports.derefType = function derefType (type) {
var _type = exports.coerceType(type)
if (_type.indirection === 1) {
throw new Error('Cannot create deref\'d type for type with indirection 1')
}
var rtn = Object.getPrototypeOf(_type)
if (rtn.indirection !== _type.indirection - 1) {
// slow case
rtn = Object.create(_type)
rtn.indirection--
}
return rtn
}
/**
* Coerces a "type" object from a String or an actual "type" object. String values
* are looked up from the `ref.types` Object. So:
*
* * `"int"` gets coerced into `ref.types.int`.
* * `"int *"` gets translated into `ref.refType(ref.types.int)`
* * `ref.types.int` gets translated into `ref.types.int` (returns itself)
*
* Throws an Error if no valid "type" object could be determined. Most `ref`
* functions use this function under the hood, so anywhere a "type" object is
* expected, a String may be passed as well, including simply setting the
* `buffer.type` property.
*
* ```
* var type = ref.coerceType('int **');
*
* console.log(type.indirection);
* 3
* ```
*
* @param {Object|String} type The "type" Object or String to coerce.
* @return {Object} A "type" object
*/
exports.coerceType = function coerceType (type) {
var rtn = type
if (typeof rtn === 'string') {
rtn = exports.types[type]
if (rtn) return rtn
// strip whitespace
rtn = type.replace(/\s+/g, '').toLowerCase()
if (rtn === 'pointer') {
// legacy "pointer" being used :(
rtn = exports.refType(exports.types.void) // void *
} else if (rtn === 'string') {
rtn = exports.types.CString // special char * type
} else {
var refCount = 0
rtn = rtn.replace(/\*/g, function () {
refCount++
return ''
})
// allow string names to be passed in
rtn = exports.types[rtn]
if (refCount > 0) {
if (!(rtn && 'size' in rtn && 'indirection' in rtn)) {
throw new TypeError('could not determine a proper "type" from: ' + JSON.stringify(type))
}
for (var i = 0; i < refCount; i++) {
rtn = exports.refType(rtn)
}
}
}
}
if (!(rtn && 'size' in rtn && 'indirection' in rtn)) {
throw new TypeError('could not determine a proper "type" from: ' + JSON.stringify(type))
}
return rtn
}
/**
* Returns the "type" property of the given Buffer.
* Creates a default type for the buffer when none exists.
*
* @param {Buffer} buffer The Buffer instance to get the "type" object from.
* @return {Object} The "type" object from the given Buffer.
*/
exports.getType = function getType (buffer) {
if (!buffer.type) {
debug('WARN: no "type" found on buffer, setting default "type"', buffer)
buffer.type = {}
buffer.type.size = buffer.length
buffer.type.indirection = 1
buffer.type.get = function get () {
throw new Error('unknown "type"; cannot get()')
}
buffer.type.set = function set () {
throw new Error('unknown "type"; cannot set()')
}
}
return exports.coerceType(buffer.type)
}
/**
* Calls the `get()` function of the Buffer's current "type" (or the
* passed in _type_ if present) at the given _offset_.
*
* This function handles checking the "indirection" level and returning a
* proper "dereferenced" Bufffer instance when necessary.
*
* @param {Buffer} buffer The Buffer instance to read from.
* @param {Number} offset (optional) The offset on the Buffer to start reading from. Defaults to 0.
* @param {Object|String} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer.
* @return {?} Whatever value the "type" used when reading returns.
*/
exports.get = function get (buffer, offset, type) {
if (!offset) {
offset = 0
}
if (type) {
type = exports.coerceType(type)
} else {
type = exports.getType(buffer)
}
debug('get(): (offset: %d)', offset, buffer)
assert(type.indirection > 0, '"indirection" level must be at least 1')
if (type.indirection === 1) {
// need to check "type"
return type.get(buffer, offset)
} else {
// need to create a deref'd Buffer
var size = type.indirection === 2 ? type.size : exports.sizeof.pointer
var reference = exports.readPointer(buffer, offset, size)
reference.type = exports.derefType(type)
return reference
}
}
/**
* Calls the `set()` function of the Buffer's current "type" (or the
* passed in _type_ if present) at the given _offset_.
*
* This function handles checking the "indirection" level writing a pointer rather
* than calling the `set()` function if the indirection is greater than 1.
*
* @param {Buffer} buffer The Buffer instance to write to.
* @param {Number} offset The offset on the Buffer to start writing to.
* @param {?} value The value to write to the Buffer instance.
* @param {Object|String} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer.
*/
exports.set = function set (buffer, offset, value, type) {
if (!offset) {
offset = 0
}
if (type) {
type = exports.coerceType(type)
} else {
type = exports.getType(buffer)
}
debug('set(): (offset: %d)', offset, buffer, value)
assert(type.indirection >= 1, '"indirection" level must be at least 1')
if (type.indirection === 1) {
type.set(buffer, offset, value)
} else {
exports.writePointer(buffer, offset, value)
}
}
/**
* Returns a new Buffer instance big enough to hold `type`,
* with the given `value` written to it.
*
* ``` js
* var intBuf = ref.alloc(ref.types.int)
* var int_with_4 = ref.alloc(ref.types.int, 4)
* ```
*
* @param {Object|String} type The "type" object to allocate. Strings get coerced first.
* @param {?} value (optional) The initial value set on the returned Buffer, using _type_'s `set()` function.
* @return {Buffer} A new Buffer instance with it's `type` set to "type", and (optionally) "value" written to it.
*/
exports.alloc = function alloc (_type, value) {
var type = exports.coerceType(_type)
debug('allocating Buffer for type with "size"', type.size)
var size
if (type.indirection === 1) {
size = type.size
} else {
size = exports.sizeof.pointer
}
var buffer = new Buffer(size)
buffer.type = type
if (arguments.length >= 2) {
debug('setting value on allocated buffer', value)
exports.set(buffer, 0, value, type)
}
return buffer
}
/**
* Returns a new `Buffer` instance with the given String written to it with the
* given encoding (defaults to __'utf8'__). The buffer is 1 byte longer than the
* string itself, and is NUL terminated.
*
* ```
* var buf = ref.allocCString('hello world');
*
* console.log(buf.toString());
* 'hello world\u0000'
* ```
*
* @param {String} string The JavaScript string to be converted to a C string.
* @param {String} encoding (optional) The encoding to use for the C string. Defaults to __'utf8'__.
* @return {Buffer} The new `Buffer` instance with the specified String wrtten to it, and a trailing NUL byte.
*/
exports.allocCString = function allocCString (string, encoding) {
if (null == string || (Buffer.isBuffer(string) && exports.isNull(string))) {
return exports.NULL
}
var size = Buffer.byteLength(string, encoding) + 1
var buffer = new Buffer(size)
exports.writeCString(buffer, 0, string, encoding)
buffer.type = charPtrType
return buffer
}
/**
* Writes the given string as a C String (NULL terminated) to the given buffer
* at the given offset. "encoding" is optional and defaults to __'utf8'__.
*
* Unlike `readCString()`, this function requires the buffer to actually have the
* proper length.
*
* @param {Buffer} buffer The Buffer instance to write to.
* @param {Number} offset The offset of the buffer to begin writing at.
* @param {String} string The JavaScript String to write that will be written to the buffer.
* @param {String} encoding (optional) The encoding to read the C string as. Defaults to __'utf8'__.
*/
exports.writeCString = function writeCString (buffer, offset, string, encoding) {
assert(Buffer.isBuffer(buffer), 'expected a Buffer as the first argument')
assert.equal('string', typeof string, 'expected a "string" as the third argument')
if (!offset) {
offset = 0
}
if (!encoding) {
encoding = 'utf8'
}
var size = buffer.length - offset
var len = buffer.write(string, offset, size, encoding)
buffer.writeUInt8(0, offset + len) // NUL terminate
}
exports['readInt64' + exports.endianness] = exports.readInt64
exports['readUInt64' + exports.endianness] = exports.readUInt64
exports['writeInt64' + exports.endianness] = exports.writeInt64
exports['writeUInt64' + exports.endianness] = exports.writeUInt64
var opposite = exports.endianness == 'LE' ? 'BE' : 'LE'
var int64temp = new Buffer(exports.sizeof.int64)
var uint64temp = new Buffer(exports.sizeof.uint64)
exports['readInt64' + opposite] = function (buffer, offset) {
for (var i = 0; i < exports.sizeof.int64; i++) {
int64temp[i] = buffer[offset + exports.sizeof.int64 - i - 1]
}
return exports.readInt64(int64temp, 0)
}
exports['readUInt64' + opposite] = function (buffer, offset) {
for (var i = 0; i < exports.sizeof.uint64; i++) {
uint64temp[i] = buffer[offset + exports.sizeof.uint64 - i - 1]
}
return exports.readUInt64(uint64temp, 0)
}
exports['writeInt64' + opposite] = function (buffer, offset, value) {
exports.writeInt64(int64temp, 0, value)
for (var i = 0; i < exports.sizeof.int64; i++) {
buffer[offset + i] = int64temp[exports.sizeof.int64 - i - 1]
}
}
exports['writeUInt64' + opposite] = function (buffer, offset, value) {
exports.writeUInt64(uint64temp, 0, value)
for (var i = 0; i < exports.sizeof.uint64; i++) {
buffer[offset + i] = uint64temp[exports.sizeof.uint64 - i - 1]
}
}
/**
* `ref()` accepts a Buffer instance and returns a new Buffer
* instance that is "pointer" sized and has its data pointing to the given
* Buffer instance. Essentially the created Buffer is a "reference" to the
* original pointer, equivalent to the following C code:
*
* ``` c
* char *buf = buffer;
* char **ref = &buf;
* ```
*
* @param {Buffer} buffer A Buffer instance to create a reference to.
* @return {Buffer} A new Buffer instance pointing to _buffer_.
*/
exports.ref = function ref (buffer) {
debug('creating a reference to buffer', buffer)
var type = exports.refType(exports.getType(buffer))
return exports.alloc(type, buffer)
}
/**
* Accepts a Buffer instance and attempts to "dereference" it.
* That is, first it checks the `indirection` count of _buffer_'s "type", and if
* it's greater than __1__ then it merely returns another Buffer, but with one
* level less `indirection`.
*
* When _buffer_'s indirection is at __1__, then it checks for `buffer.type`
* which should be an Object with its own `get()` function.
*
* ```
* var buf = ref.alloc('int', 6);
*
* var val = ref.deref(buf);
* console.log(val);
* 6
* ```
*
*
* @param {Buffer} buffer A Buffer instance to dereference.
* @return {?} The returned value after dereferencing _buffer_.
*/
exports.deref = function deref (buffer) {
debug('dereferencing buffer', buffer)
return exports.get(buffer)
}
/**
* Attaches _object_ to _buffer_ such that it prevents _object_ from being garbage
* collected until _buffer_ does.
*
* @param {Buffer} buffer A Buffer instance to attach _object_ to.
* @param {Object|Buffer} object An Object or Buffer to prevent from being garbage collected until _buffer_ does.
* @api private
*/
exports._attach = function _attach (buf, obj) {
if (!buf._refs) {
buf._refs = []
}
buf._refs.push(obj)
}
/**
* Same as `ref.writeObject()`, except that this version does not _attach_ the
* Object to the Buffer, which is potentially unsafe if the garbage collector
* runs.
*
* @param {Buffer} buffer A Buffer instance to write _object_ to.
* @param {Number} offset The offset on the Buffer to start writing at.
* @param {Object} object The Object to be written into _buffer_.
* @api private
*/
exports._writeObject = exports.writeObject
/**
* Writes a pointer to _object_ into _buffer_ at the specified _offset.
*
* This function "attaches" _object_ to _buffer_ to prevent it from being garbage
* collected.
*
* ```
* var buf = ref.alloc('Object');
* ref.writeObject(buf, 0, { foo: 'bar' });
*
* ```
*
* @param {Buffer} buffer A Buffer instance to write _object_ to.
* @param {Number} offset The offset on the Buffer to start writing at.
* @param {Object} object The Object to be written into _buffer_.
*/
exports.writeObject = function writeObject (buf, offset, obj, persistent) {
debug('writing Object to buffer', buf, offset, obj, persistent)
exports._writeObject(buf, offset, obj, persistent)
exports._attach(buf, obj)
}
/**
* Same as `ref.writePointer()`, except that this version does not attach
* _pointer_ to _buffer_, which is potentially unsafe if the garbage collector
* runs.
*
* @param {Buffer} buffer A Buffer instance to write _pointer to.
* @param {Number} offset The offset on the Buffer to start writing at.
* @param {Buffer} pointer The Buffer instance whose memory address will be written to _buffer_.
* @api private
*/
exports._writePointer = exports.writePointer
/**
* Writes the memory address of _pointer_ to _buffer_ at the specified _offset_.
*
* This function "attaches" _object_ to _buffer_ to prevent it from being garbage
* collected.
*
* ```
* var someBuffer = new Buffer('whatever');
* var buf = ref.alloc('pointer');
* ref.writePointer(buf, 0, someBuffer);
* ```
*
* @param {Buffer} buffer A Buffer instance to write _pointer to.
* @param {Number} offset The offset on the Buffer to start writing at.
* @param {Buffer} pointer The Buffer instance whose memory address will be written to _buffer_.
*/
exports.writePointer = function writePointer (buf, offset, ptr) {
debug('writing pointer to buffer', buf, offset, ptr)
exports._writePointer(buf, offset, ptr)
exports._attach(buf, ptr)
}
/**
* Same as `ref.reinterpret()`, except that this version does not attach
* _buffer_ to the returned Buffer, which is potentially unsafe if the
* garbage collector runs.
*
* @param {Buffer} buffer A Buffer instance to base the returned Buffer off of.
* @param {Number} size The `length` property of the returned Buffer.
* @param {Number} offset The offset of the Buffer to begin from.
* @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and the requested _size_.
* @api private
*/
exports._reinterpret = exports.reinterpret
/**
* Returns a new Buffer instance with the specified _size_, with the same memory
* address as _buffer_.
*
* This function "attaches" _buffer_ to the returned Buffer to prevent it from
* being garbage collected.
*
* @param {Buffer} buffer A Buffer instance to base the returned Buffer off of.
* @param {Number} size The `length` property of the returned Buffer.
* @param {Number} offset The offset of the Buffer to begin from.
* @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and the requested _size_.
*/
exports.reinterpret = function reinterpret (buffer, size, offset) {
debug('reinterpreting buffer to "%d" bytes', size)
var rtn = exports._reinterpret(buffer, size, offset || 0)
exports._attach(rtn, buffer)
return rtn
}
/**
* Same as `ref.reinterpretUntilZeros()`, except that this version does not
* attach _buffer_ to the returned Buffer, which is potentially unsafe if the
* garbage collector runs.
*
* @param {Buffer} buffer A Buffer instance to base the returned Buffer off of.
* @param {Number} size The number of sequential, aligned `NULL` bytes that are required to terminate the buffer.
* @param {Number} offset The offset of the Buffer to begin from.
* @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and a variable `length` that is terminated by _size_ NUL bytes.
* @api private
*/
exports._reinterpretUntilZeros = exports.reinterpretUntilZeros
/**
* Accepts a `Buffer` instance and a number of `NULL` bytes to read from the
* pointer. This function will scan past the boundary of the Buffer's `length`
* until it finds `size` number of aligned `NULL` bytes.
*
* This is useful for finding the end of NUL-termintated array or C string. For
* example, the `readCString()` function _could_ be implemented like:
*
* ```
* function readCString (buf) {
* return ref.reinterpretUntilZeros(buf, 1).toString('utf8')
* }
* ```
*
* This function "attaches" _buffer_ to the returned Buffer to prevent it from
* being garbage collected.
*
* @param {Buffer} buffer A Buffer instance to base the returned Buffer off of.
* @param {Number} size The number of sequential, aligned `NULL` bytes are required to terminate the buffer.
* @param {Number} offset The offset of the Buffer to begin from.
* @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and a variable `length` that is terminated by _size_ NUL bytes.
*/
exports.reinterpretUntilZeros = function reinterpretUntilZeros (buffer, size, offset) {
debug('reinterpreting buffer to until "%d" NULL (0) bytes are found', size)
var rtn = exports._reinterpretUntilZeros(buffer, size, offset || 0)
exports._attach(rtn, buffer)
return rtn
}
// the built-in "types"
var types = exports.types = {}
/**
* The `void` type.
*
* @section types
*/
types.void = {
size: 0
, indirection: 1
, get: function get (buf, offset) {
debug('getting `void` type (returns `null`)')
return null
}
, set: function set (buf, offset, val) {
debug('setting `void` type (no-op)')
}
}
/**
* The `int8` type.
*/
types.int8 = {
size: exports.sizeof.int8
, indirection: 1
, get: function get (buf, offset) {
return buf.readInt8(offset || 0)
}
, set: function set (buf, offset, val) {
if (typeof val === 'string') {
val = val.charCodeAt(0)
}
return buf.writeInt8(val, offset || 0)
}
}
/**
* The `uint8` type.
*/
types.uint8 = {
size: exports.sizeof.uint8
, indirection: 1
, get: function get (buf, offset) {
return buf.readUInt8(offset || 0)
}
, set: function set (buf, offset, val) {
if (typeof val === 'string') {
val = val.charCodeAt(0)
}
return buf.writeUInt8(val, offset || 0)
}
}
/**
* The `int16` type.
*/
types.int16 = {
size: exports.sizeof.int16
, indirection: 1
, get: function get (buf, offset) {
return buf['readInt16' + exports.endianness](offset || 0)
}
, set: function set (buf, offset, val) {
return buf['writeInt16' + exports.endianness](val, offset || 0)
}
}
/**
* The `uint16` type.
*/
types.uint16 = {
size: exports.sizeof.uint16
, indirection: 1
, get: function get (buf, offset) {
return buf['readUInt16' + exports.endianness](offset || 0)
}
, set: function set (buf, offset, val) {
return buf['writeUInt16' + exports.endianness](val, offset || 0)
}
}
/**
* The `int32` type.
*/
types.int32 = {
size: exports.sizeof.int32
, indirection: 1
, get: function get (buf, offset) {
return buf['readInt32' + exports.endianness](offset || 0)
}
, set: function set (buf, offset, val) {
return buf['writeInt32' + exports.endianness](val, offset || 0)
}
}
/**
* The `uint32` type.
*/
types.uint32 = {
size: exports.sizeof.uint32
, indirection: 1
, get: function get (buf, offset) {
return buf['readUInt32' + exports.endianness](offset || 0)
}
, set: function set (buf, offset, val) {
return buf['writeUInt32' + exports.endianness](val, offset || 0)
}
}
/**
* The `int64` type.
*/
types.int64 = {
size: exports.sizeof.int64
, indirection: 1
, get: function get (buf, offset) {
return buf['readInt64' + exports.endianness](offset || 0)
}
, set: function set (buf, offset, val) {
return buf['writeInt64' + exports.endianness](val, offset || 0)
}
}
/**
* The `uint64` type.
*/
types.uint64 = {
size: exports.sizeof.uint64
, indirection: 1
, get: function get (buf, offset) {
return buf['readUInt64' + exports.endianness](offset || 0)
}
, set: function set (buf, offset, val) {
return buf['writeUInt64' + exports.endianness](val, offset || 0)
}
}
/**
* The `float` type.
*/
types.float = {
size: exports.sizeof.float
, indirection: 1
, get: function get (buf, offset) {
return buf['readFloat' + exports.endianness](offset || 0)
}
, set: function set (buf, offset, val) {
return buf['writeFloat' + exports.endianness](val, offset || 0)
}
}
/**
* The `double` type.
*/
types.double = {
size: exports.sizeof.double
, indirection: 1
, get: function get (buf, offset) {
return buf['readDouble' + exports.endianness](offset || 0)
}
, set: function set (buf, offset, val) {
return buf['writeDouble' + exports.endianness](val, offset || 0)
}
}
/**
* The `Object` type. This can be used to read/write regular JS Objects
* into raw memory.
*/
types.Object = {
size: exports.sizeof.Object
, indirection: 1
, get: function get (buf, offset) {
return buf.readObject(offset || 0)
}
, set: function set (buf, offset, val) {
return buf.writeObject(val, offset || 0)
}
}
/**
* The `CString` (a.k.a `"string"`) type.
*
* CStrings are a kind of weird thing. We say it's `sizeof(char *)`, and
* `indirection` level of 1, which means that we have to return a Buffer that
* is pointer sized, and points to a some utf8 string data, so we have to create
* a 2nd "in-between" buffer.
*/
types.CString = {
size: exports.sizeof.pointer
, alignment: exports.alignof.pointer
, indirection: 1
, get: function get (buf, offset) {
var _buf = exports.readPointer(buf, offset)
if (exports.isNull(_buf)) {
return null
}
return exports.readCString(_buf, 0)
}
, set: function set (buf, offset, val) {
var _buf
if (Buffer.isBuffer(val)) {
_buf = val
} else {
// assume string
_buf = exports.allocCString(val)
}
return exports.writePointer(buf, offset, _buf)
}
}
// alias Utf8String
var utfstringwarned = false
Object.defineProperty(types, 'Utf8String', {
enumerable: false
, configurable: true
, get: function () {
if (!utfstringwarned) {
utfstringwarned = true
console.error('"Utf8String" type is deprecated, use "CString" instead')
}
return types.CString
}
})
/**
* The `bool` type.
*
* Wrapper type around `types.uint8` that accepts/returns `true` or
* `false` Boolean JavaScript values.
*
* @name bool
*
*/
/**
* The `byte` type.
*
* @name byte
*/
/**
* The `char` type.
*
* @name char
*/
/**
* The `uchar` type.
*
* @name uchar
*/
/**
* The `short` type.
*
* @name short
*/
/**
* The `ushort` type.
*
* @name ushort
*/
/**
* The `int` type.
*
* @name int
*/
/**
* The `uint` type.
*
* @name uint
*/
/**
* The `long` type.
*
* @name long
*/
/**
* The `ulong` type.
*
* @name ulong
*/
/**
* The `longlong` type.
*
* @name longlong
*/
/**
* The `ulonglong` type.
*
* @name ulonglong
*/
/**
* The `size_t` type.
*
* @name size_t
*/
// "typedef"s for the variable-sized types
;[ 'bool', 'byte', 'char', 'uchar', 'short', 'ushort', 'int', 'uint', 'long'
, 'ulong', 'longlong', 'ulonglong', 'size_t' ].forEach(function (name) {
var unsigned = name === 'bool'
|| name === 'byte'
|| name === 'size_t'
|| name[0] === 'u'
var size = exports.sizeof[name]
assert(size >= 1 && size <= 8)
var typeName = 'int' + (size * 8)
if (unsigned) {
typeName = 'u' + typeName
}
var type = exports.types[typeName]
assert(type)
exports.types[name] = Object.create(type)
})
// set the "alignment" property on the built-in types
Object.keys(exports.alignof).forEach(function (name) {
if (name === 'pointer') return
exports.types[name].alignment = exports.alignof[name]
assert(exports.types[name].alignment > 0)
})
// make the `bool` type work with JS true/false values
exports.types.bool.get = (function (_get) {
return function get (buf, offset) {
return _get(buf, offset) ? true : false
}
})(exports.types.bool.get)
exports.types.bool.set = (function (_set) {
return function set (buf, offset, val) {
if (typeof val !== 'number') {
val = val ? 1 : 0
}
return _set(buf, offset, val)
}
})(exports.types.bool.set)
/*!
* Set the `name` property of the types. Used for debugging...
*/
Object.keys(exports.types).forEach(function (name) {
exports.types[name].name = name
})
/*!
* This `char *` type is used by "allocCString()" above.
*/
var charPtrType = exports.refType(exports.types.char)
/*!
* Set the `type` property of the `NULL` pointer Buffer object.
*/
exports.NULL.type = exports.types.void
/**
* `NULL_POINTER` is a pointer-sized `Buffer` instance pointing to `NULL`.
* Conceptually, it's equivalent to the following C code:
*
* ``` c
* char *null_pointer;
* null_pointer = NULL;
* ```
*
* @type Buffer
*/
exports.NULL_POINTER = exports.ref(exports.NULL)
/**
* All these '...' comment blocks below are for the documentation generator.
*
* @section buffer
*/
Buffer.prototype.address = function address () {
return exports.address(this, 0)
}
/**
* ...
*/
Buffer.prototype.hexAddress = function hexAddress () {
return exports.hexAddress(this, 0)
}
/**
* ...
*/
Buffer.prototype.isNull = function isNull () {
return exports.isNull(this, 0)
}
/**
* ...
*/
Buffer.prototype.ref = function ref () {
return exports.ref(this)
}
/**
* ...
*/
Buffer.prototype.deref = function deref () {
return exports.deref(this)
}
/**
* ...
*/
Buffer.prototype.readObject = function readObject (offset) {
return exports.readObject(this, offset)
}
/**
* ...
*/
Buffer.prototype.writeObject = function writeObject (obj, offset) {
return exports.writeObject(this, offset, obj)
}
/**
* ...
*/
Buffer.prototype.readPointer = function readPointer (offset, size) {
return exports.readPointer(this, offset, size)
}
/**
* ...
*/
Buffer.prototype.writePointer = function writePointer (ptr, offset) {
return exports.writePointer(this, offset, ptr)
}
/**
* ...
*/
Buffer.prototype.readCString = function readCString (offset) {
return exports.readCString(this, offset)
}
/**
* ...
*/
Buffer.prototype.writeCString = function writeCString (string, offset, encoding) {
return exports.writeCString(this, offset, string, encoding)
}
/**
* ...
*/
Buffer.prototype.readInt64BE = function readInt64BE (offset) {
return exports.readInt64BE(this, offset)
}
/**
* ...
*/
Buffer.prototype.writeInt64BE = function writeInt64BE (val, offset) {
return exports.writeInt64BE(this, offset, val)
}
/**
* ...
*/
Buffer.prototype.readUInt64BE = function readUInt64BE (offset) {
return exports.readUInt64BE(this, offset)
}
/**
* ...
*/
Buffer.prototype.writeUInt64BE = function writeUInt64BE (val, offset) {
return exports.writeUInt64BE(this, offset, val)
}
/**
* ...
*/
Buffer.prototype.readInt64LE = function readInt64LE (offset) {
return exports.readInt64LE(this, offset)
}
/**
* ...
*/
Buffer.prototype.writeInt64LE = function writeInt64LE (val, offset) {
return exports.writeInt64LE(this, offset, val)
}
/**
* ...
*/
Buffer.prototype.readUInt64LE = function readUInt64LE (offset) {
return exports.readUInt64LE(this, offset)
}
/**
* ...
*/
Buffer.prototype.writeUInt64LE = function writeUInt64LE (val, offset) {
return exports.writeUInt64LE(this, offset, val)
}
/**
* ...
*/
Buffer.prototype.reinterpret = function reinterpret (size, offset) {
return exports.reinterpret(this, size, offset)
}
/**
* ...
*/
Buffer.prototype.reinterpretUntilZeros = function reinterpretUntilZeros (size, offset) {
return exports.reinterpretUntilZeros(this, size, offset)
}
/**
* `ref` overwrites the default `Buffer#inspect()` function to include the
* hex-encoded memory address of the Buffer instance when invoked.
*
* This is simply a nice-to-have.
*
* **Before**:
*
* ``` js
* console.log(new Buffer('ref'));
* <Buffer 72 65 66>
* ```
*
* **After**:
*
* ``` js
* console.log(new Buffer('ref'));
* <Buffer@0x103015490 72 65 66>
* ```
*/
var inspectSym = inspect.custom || 'inspect'
Buffer.prototype[inspectSym] = overwriteInspect(Buffer.prototype[inspectSym])
// does SlowBuffer inherit from Buffer? (node >= v0.7.9)
if (!(exports.NULL instanceof Buffer)) {
debug('extending SlowBuffer\'s prototype since it doesn\'t inherit from Buffer.prototype')
/*!
* SlowBuffer convenience methods.
*/
var SlowBuffer = require('buffer').SlowBuffer
SlowBuffer.prototype.address = Buffer.prototype.address
SlowBuffer.prototype.hexAddress = Buffer.prototype.hexAddress
SlowBuffer.prototype.isNull = Buffer.prototype.isNull
SlowBuffer.prototype.ref = Buffer.prototype.ref
SlowBuffer.prototype.deref = Buffer.prototype.deref
SlowBuffer.prototype.readObject = Buffer.prototype.readObject
SlowBuffer.prototype.writeObject = Buffer.prototype.writeObject
SlowBuffer.prototype.readPointer = Buffer.prototype.readPointer
SlowBuffer.prototype.writePointer = Buffer.prototype.writePointer
SlowBuffer.prototype.readCString = Buffer.prototype.readCString
SlowBuffer.prototype.writeCString = Buffer.prototype.writeCString
SlowBuffer.prototype.reinterpret = Buffer.prototype.reinterpret
SlowBuffer.prototype.reinterpretUntilZeros = Buffer.prototype.reinterpretUntilZeros
SlowBuffer.prototype.readInt64BE = Buffer.prototype.readInt64BE
SlowBuffer.prototype.writeInt64BE = Buffer.prototype.writeInt64BE
SlowBuffer.prototype.readUInt64BE = Buffer.prototype.readUInt64BE
SlowBuffer.prototype.writeUInt64BE = Buffer.prototype.writeUInt64BE
SlowBuffer.prototype.readInt64LE = Buffer.prototype.readInt64LE
SlowBuffer.prototype.writeInt64LE = Buffer.prototype.writeInt64LE
SlowBuffer.prototype.readUInt64LE = Buffer.prototype.readUInt64LE
SlowBuffer.prototype.writeUInt64LE = Buffer.prototype.writeUInt64LE
SlowBuffer.prototype[inspectSym] = overwriteInspect(SlowBuffer.prototype[inspectSym])
}
function overwriteInspect (inspect) {
if (inspect.name === 'refinspect') {
return inspect
} else {
return function refinspect () {
var v = inspect.apply(this, arguments)
return v.replace('Buffer', 'Buffer@0x' + this.hexAddress())
}
}
}