proton-c/bindings/javascript/data-binary.js - qpid-proton - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you 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.
  *
  */

 /*****************************************************************************/
 /*                                                                           */
 /*                             proton.Data.Binary                            */
 /*                                                                           */
 /*****************************************************************************/

 /**
  * Create a proton.Data.Binary. This constructor takes one or two parameters.
  * The first parameter may serve different purposes depending on its type;
  * If value is a number then it represents the size of the Binary data buffer,
  * if it is a string then we copy the string to the buffer, if it is an Array
  * or a TypedArray then we copy the data to the buffer. The optional second
  * parameter is a pointer to the data in an internal data store. If start is
  * not specified then the number of bytes specified in the first parameter
  * will be allocated in the internal data store and start will point to the
  * start of that block of data.
  * @classdesc
  * This class represents an AMQP Binary type. This class allows us to create and
  * use raw binary data and map it efficiently between JavaScript client code and
  * the underlying implementation, where all data is managed on a "virtual heap".
  * <p>
  * Client applications should generally not have to care about memory management
  * as, for most common use cases, client applications would "transfer ownership"
  * to a "container" which would then "own" the underlying data and free the data
  * held by the {@link proton.Data.Binary}.
  * <p>
  * As an example one common use-case would be where client application creates a
  * {@link proton.Data.Binary} specifying the required size. It would usually then
  * call getBuffer() to access the underlying Uint8Array. At this point the client
  * "owns" the data and so would have to call free() if it did nothing more with
  * the Binary, however when {@link proton.Data.putBINARY} is called the ownership
  * of the raw data on the virtual heap transfers from the Binary to the Data and
  * the client no longer needs to call free() itself. In this case the putBINARY()
  * call transfers ownership and can then safely call free() on the Binary.
  * <p>
  * Conversely a common use-case when receiving data is where a Binary may be
  * created by {@link proton.Data#getBINARY}. In this case the Binary is simply a
  * "view" onto the bytes owned by the Data instance. A client application can
  * safely access the bytes from the view, but if it wishes to use the bytes beyond
  * the scope of the Data instance (e.g. after the next {@link proton.Messenger#get}
  * call then the client must explicitly *copy* the bytes into a new buffer, for
  * example via copyBuffer().
  * <p>
  * Most of the {@link proton.Data} methods that take {@link proton.Data.Binary}
  * as a parameter "consume" the underlying data and take responsibility for
  * freeing it from the heap e.g. {@link proton.Data#putBINARY}, {@link proton.Data#decode}.
  * For the methods that return a {@link proton.Data.Binary} the call to
  * {@link proton.Data#getBINARY}, which is the most common case, returns a Binary
  * that has a "view" of the underlying data that is actually owned by the Data
  * instance and thus doesn't need to be explicitly freed on the Binary. The call
  * to {@link proton.Data#encode} however returns a Binary that represents a *copy*
  * of the underlying data, in this case (like a client calling new proton.Data.Binary)
  * the client takes responsibility for freeing the data, unless of course it is
  * subsequently passed to a method that will consume the data (putBINARY/decode).
  * @constructor proton.Data.Binary
  * @param {(number|string|Array|TypedArray)} value If value is a number then it
  *        represents the size of the Binary data buffer, if it is a string then
  *        we copy the string to the buffer, if it is an Array or a TypedArray
  *        then we copy the data to the buffer. N.B. although convenient do bear
  *        in mind that using a mechanism other than constructing with a simple
  *        size will result in some form of additional data copy.
  * @param {number} start an optional pointer to the start of the Binary data buffer.
  */
 Data['Binary'] = function(value, start) { // Data.Binary Constructor.
     /**
      * If the start pointer is specified then the underlying binary data is owned
      * by another object, so we set the call to free to be a null function. If
      * the start pointer is not passed then we allocate storage of the specified
      * size on the emscripten heap and set the call to free to free the data from
      * the emscripten heap.
      */
     var size = value;
     if (start) {
         this['free'] = function() {};
     } else { // Create Binary from Array, ArrayBuffer or TypedArray.
         var hasArrayBuffer = (typeof ArrayBuffer === 'function');
         if (Data.isArray(value) ||
             (hasArrayBuffer && value instanceof ArrayBuffer) ||
             (value.buffer && hasArrayBuffer && value.buffer instanceof ArrayBuffer)) {
             value = new Uint8Array(value);
             size = value.length;
             start = _malloc(size); // Allocate storage from emscripten heap.
             Module['HEAPU8'].set(value, start); // Copy the data to the emscripten heap.
         } else if (Data.isString(value)) { // Create Binary from native string
             value = unescape(encodeURIComponent(value)); // Create a C-like UTF representation.
             size = value.length;
             start = _malloc(size); // Allocate storage from emscripten heap.
             for (var i = 0; i < size; i++) {
                 setValue(start + i, value.charCodeAt(i), 'i8', 1);
             }
         } else { // Create unpopulated Binary of specified size.
             // If the type is not a number by this point then an unrecognised data
             // type has been passed so we create a zero length Binary.
             size = Data.isNumber(size) ? size : 0;
             start = _malloc(size); // Allocate storage from emscripten heap.
         }
         this['free'] = function() {
             _free(this.start);
             this.size = 0;
             this.start = 0;
             // Set free to a null function to prevent possibility of a "double free".
             this['free'] = function() {};
         };
     }

     this.size = size;
     this.start = start;
 };

 /**
  * Get a Uint8Array view of the data. N.B. this is just a *view* of the data,
  * which will go out of scope on the next call to {@link proton.Messenger.get}. If
  * a client wants to retain the data then copy should be used to explicitly
  * create a copy of the data which the client then owns to do with as it wishes.
  * @method getBuffer
  * @returns {Uint8Array} a new Uint8Array view of the data.
  * @memberof! proton.Data.Binary#
  */
 Data['Binary'].prototype['getBuffer'] = function() {
     return new Uint8Array(HEAPU8.buffer, this.start, this.size);
 };

 /**
  * Explicitly create a *copy* of the Binary, copying the underlying binary data too.
  * @method copy
  * @param {number} offset an optional offset into the underlying buffer from
  *        where we want to copy the data, default is zero.
  * @param {number} n an optional number of bytes to copy, default is this.size - offset.
  * @returns {proton.Data.Binary} a new {@link proton.Data.Binary} created by copying the underlying binary data.
  * @memberof! proton.Data.Binary#
  */
 Data['Binary'].prototype['copy'] = function(offset, n) {
     offset = offset | 0;
     n = n ? n : (this.size - offset);

     if (offset >= this.size) {
         offset = 0;
         n = 0;
     } else if ((offset + n) > this.size) {
         n = this.size - offset; // Clamp length
     }

     var start = _malloc(n); // Allocate storage from emscripten heap.
     _memcpy(start, this.start + offset, n); // Copy the raw data to new buffer.

     return new Data['Binary'](n, start);
 };

 /**
  * Converts the {@link proton.Data.Binary} to a string. This is clearly most
  * useful when the binary data is actually a binary representation of a string
  * such as a C style ASCII string.
  * @method toString
  * @memberof! proton.Data.Binary#
  * @returns {string} the String form of a {@link proton.Data.Binary}.
  */
 Data['Binary'].prototype.toString = Data['Binary'].prototype.valueOf = function() {
     // Create a native JavaScript String from the start/size information.
     return Pointer_stringify(this.start, this.size);
 };
	/*
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you 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.
	*
	*/

	/*****************************************************************************/
	/* */
	/* proton.Data.Binary */
	/* */
	/*****************************************************************************/

	/**
	* Create a proton.Data.Binary. This constructor takes one or two parameters.
	* The first parameter may serve different purposes depending on its type;
	* If value is a number then it represents the size of the Binary data buffer,
	* if it is a string then we copy the string to the buffer, if it is an Array
	* or a TypedArray then we copy the data to the buffer. The optional second
	* parameter is a pointer to the data in an internal data store. If start is
	* not specified then the number of bytes specified in the first parameter
	* will be allocated in the internal data store and start will point to the
	* start of that block of data.
	* @classdesc
	* This class represents an AMQP Binary type. This class allows us to create and
	* use raw binary data and map it efficiently between JavaScript client code and
	* the underlying implementation, where all data is managed on a "virtual heap".
	* <p>
	* Client applications should generally not have to care about memory management
	* as, for most common use cases, client applications would "transfer ownership"
	* to a "container" which would then "own" the underlying data and free the data
	* held by the {@link proton.Data.Binary}.
	* <p>
	* As an example one common use-case would be where client application creates a
	* {@link proton.Data.Binary} specifying the required size. It would usually then
	* call getBuffer() to access the underlying Uint8Array. At this point the client
	* "owns" the data and so would have to call free() if it did nothing more with
	* the Binary, however when {@link proton.Data.putBINARY} is called the ownership
	* of the raw data on the virtual heap transfers from the Binary to the Data and
	* the client no longer needs to call free() itself. In this case the putBINARY()
	* call transfers ownership and can then safely call free() on the Binary.
	* <p>
	* Conversely a common use-case when receiving data is where a Binary may be
	* created by {@link proton.Data#getBINARY}. In this case the Binary is simply a
	* "view" onto the bytes owned by the Data instance. A client application can
	* safely access the bytes from the view, but if it wishes to use the bytes beyond
	* the scope of the Data instance (e.g. after the next {@link proton.Messenger#get}
	* call then the client must explicitly copy the bytes into a new buffer, for
	* example via copyBuffer().
	* <p>
	* Most of the {@link proton.Data} methods that take {@link proton.Data.Binary}
	* as a parameter "consume" the underlying data and take responsibility for
	* freeing it from the heap e.g. {@link proton.Data#putBINARY}, {@link proton.Data#decode}.
	* For the methods that return a {@link proton.Data.Binary} the call to
	* {@link proton.Data#getBINARY}, which is the most common case, returns a Binary
	* that has a "view" of the underlying data that is actually owned by the Data
	* instance and thus doesn't need to be explicitly freed on the Binary. The call
	* to {@link proton.Data#encode} however returns a Binary that represents a copy
	* of the underlying data, in this case (like a client calling new proton.Data.Binary)
	* the client takes responsibility for freeing the data, unless of course it is
	* subsequently passed to a method that will consume the data (putBINARY/decode).
	* @constructor proton.Data.Binary
	* @param {(number\|string\|Array\|TypedArray)} value If value is a number then it
	* represents the size of the Binary data buffer, if it is a string then
	* we copy the string to the buffer, if it is an Array or a TypedArray
	* then we copy the data to the buffer. N.B. although convenient do bear
	* in mind that using a mechanism other than constructing with a simple
	* size will result in some form of additional data copy.
	* @param {number} start an optional pointer to the start of the Binary data buffer.
	*/
	Data['Binary'] = function(value, start) { // Data.Binary Constructor.
	/**
	* If the start pointer is specified then the underlying binary data is owned
	* by another object, so we set the call to free to be a null function. If
	* the start pointer is not passed then we allocate storage of the specified
	* size on the emscripten heap and set the call to free to free the data from
	* the emscripten heap.
	*/
	var size = value;
	if (start) {
	this['free'] = function() {};
	} else { // Create Binary from Array, ArrayBuffer or TypedArray.
	var hasArrayBuffer = (typeof ArrayBuffer === 'function');
	if (Data.isArray(value) \|\|
	(hasArrayBuffer && value instanceof ArrayBuffer) \|\|
	(value.buffer && hasArrayBuffer && value.buffer instanceof ArrayBuffer)) {
	value = new Uint8Array(value);
	size = value.length;
	start = _malloc(size); // Allocate storage from emscripten heap.
	Module['HEAPU8'].set(value, start); // Copy the data to the emscripten heap.
	} else if (Data.isString(value)) { // Create Binary from native string
	value = unescape(encodeURIComponent(value)); // Create a C-like UTF representation.
	size = value.length;
	start = _malloc(size); // Allocate storage from emscripten heap.
	for (var i = 0; i < size; i++) {
	setValue(start + i, value.charCodeAt(i), 'i8', 1);
	}
	} else { // Create unpopulated Binary of specified size.
	// If the type is not a number by this point then an unrecognised data
	// type has been passed so we create a zero length Binary.
	size = Data.isNumber(size) ? size : 0;
	start = _malloc(size); // Allocate storage from emscripten heap.
	}
	this['free'] = function() {
	_free(this.start);
	this.size = 0;
	this.start = 0;
	// Set free to a null function to prevent possibility of a "double free".
	this['free'] = function() {};
	};
	}

	this.size = size;
	this.start = start;
	};

	/**
	* Get a Uint8Array view of the data. N.B. this is just a view of the data,
	* which will go out of scope on the next call to {@link proton.Messenger.get}. If
	* a client wants to retain the data then copy should be used to explicitly
	* create a copy of the data which the client then owns to do with as it wishes.
	* @method getBuffer
	* @returns {Uint8Array} a new Uint8Array view of the data.
	* @memberof! proton.Data.Binary#
	*/
	Data['Binary'].prototype['getBuffer'] = function() {
	return new Uint8Array(HEAPU8.buffer, this.start, this.size);
	};

	/**
	* Explicitly create a copy of the Binary, copying the underlying binary data too.
	* @method copy
	* @param {number} offset an optional offset into the underlying buffer from
	* where we want to copy the data, default is zero.
	* @param {number} n an optional number of bytes to copy, default is this.size - offset.
	* @returns {proton.Data.Binary} a new {@link proton.Data.Binary} created by copying the underlying binary data.
	* @memberof! proton.Data.Binary#
	*/
	Data['Binary'].prototype['copy'] = function(offset, n) {
	offset = offset \| 0;
	n = n ? n : (this.size - offset);

	if (offset >= this.size) {
	offset = 0;
	n = 0;
	} else if ((offset + n) > this.size) {
	n = this.size - offset; // Clamp length
	}

	var start = _malloc(n); // Allocate storage from emscripten heap.
	_memcpy(start, this.start + offset, n); // Copy the raw data to new buffer.

	return new Data['Binary'](n, start);
	};

	/**
	* Converts the {@link proton.Data.Binary} to a string. This is clearly most
	* useful when the binary data is actually a binary representation of a string
	* such as a C style ASCII string.
	* @method toString
	* @memberof! proton.Data.Binary#
	* @returns {string} the String form of a {@link proton.Data.Binary}.
	*/
	Data['Binary'].prototype.toString = Data['Binary'].prototype.valueOf = function() {
	// Create a native JavaScript String from the start/size information.
	return Pointer_stringify(this.start, this.size);
	};