Introduce the Array Buffer C API (#2161)

Add C API to work with Array Buffers. The following methods are added: - jerry_value_is_arraybuffer - jerry_create_arraybuffer - jerry_arraybuffer_write - jerry_arraybuffer_read - jerry_get_arraybuffer_byte_length JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.u-szeged@partner.samsung.com
2018-01-11 20:36:08 +01:00
parent b9560b7c70
commit ded0d5a846
4 changed files with 693 additions and 0 deletions
@@ -993,6 +993,44 @@ jerry_value_is_array (const jerry_value_t value)

 - [jerry_release_value](#jerry_release_value)

+## jerry_value_is_arraybuffer
+
+**Summary**
+
+Returns whether the given `jerry_value_t` is an ArrayBuffer object.
+
+**Prototype**
+
+```c
+bool
+jerry_value_is_arraybuffer (const jerry_value_t value)
+```
+
+- `value` - api value
+- return value
+  - true, if the given `jerry_value_t` is an ArrayBuffer object.
+  - false, otherwise
+
+**Example**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  if (jerry_value_is_arraybuffer (value))
+  {
+    ...
+  }
+
+  jerry_release_value (value);
+}
+```
+
+**See also**
+
+- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
+

 ## jerry_value_is_boolean

@@ -2391,6 +2429,42 @@ jerry_create_array (uint32_t size);
 - [jerry_get_property_by_index](#jerry_get_property_by_index)


+## jerry_create_arraybuffer
+
+**Summary**
+
+Create a jerry_value_t representing an ArrayBuffer object.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_arraybuffer (jerry_length_t size);
+```
+
+ - `size` - size of the ArrayBuffer to create **in bytes**
+ - return value - the new ArrayBuffer as a `jerry_value_t`
+
+**Example**
+
+```c
+{
+  jerry_value_t buffer_value = jerry_create_arraybuffer (15);
+
+  ... // use the ArrayBuffer
+
+  jerry_release_value (buffer_value);
+}
+```
+
+**See also**
+
+- [jerry_arraybuffer_read](#jerry_arraybuffer_read)
+- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
+- [jerry_value_is_arraybuffer](#jerry_value_is_arraybuffer)
+- [jerry_release_value](#jerry_release_value)
+
+
 ## jerry_create_boolean

 **Summary**
@@ -4679,3 +4753,171 @@ main (void)
 - [jerry_parse](#jerry_parse)
 - [jerry_run](#jerry_run)
 - [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t)
+
+
+# ArrayBuffer and TypedArray functions
+
+## jerry_get_arraybuffer_byte_length
+
+**Summary**
+
+Get the byte length property of the ArrayBuffer. This is the
+same value which was passed to the ArrayBuffer constructor call.
+
+**Prototype**
+
+```c
+jerry_length_t
+jerry_get_arraybuffer_byte_length (const jerry_value_t value);
+```
+
+- `value` - ArrayBuffer object
+- return value
+  - size of the ArrayBuffer in bytes
+  - 0 if the `value` parameter is not an ArrayBuffer
+
+**Example**
+
+```c
+{
+  jerry_value_t buffer = jerry_create_arraybuffer (15);
+  jerry_length_t length = jerry_get_arraybuffer_byte_length (buffer);
+  // length should be 15
+
+  jerry_release_value (buffer);
+}
+```
+
+**See also**
+- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
+
+
+## jerry_arraybuffer_read
+
+**Summary**
+
+Copy the portion of the ArrayBuffer into a user provided buffer.
+The start offset of the read operation can be specified.
+
+The number bytes to be read can be specified via the `buf_size`
+parameter. It is not possible to read more than the length of
+the ArrayBuffer.
+
+Function returns the number of bytes read from the ArrayBuffer
+(and written to the buffer parameter). This value is
+calculated in the following way: `min(array buffer length - offset, buf_size)`.
+
+**Prototype**
+
+```c
+jerry_length_t
+jerry_arraybuffer_read (const jerry_value_t value,
+                        jerry_length_t offset,
+                        uint8_t *buf_p,
+                        jerry_length_t buf_size);
+```
+
+- `value` - ArrayBuffer to read from
+- `offset` - start offset of the read operation
+- `buf_p` - buffer to read the data to
+- `buf_size` - maximum number of bytes to read into the buffer
+- return value
+  - number of bytes written into the buffer (read from the ArrayBuffer)
+  - 0 if the `value` is not an ArrayBuffer object
+  - 0 if the `buf_size` is zero or there is nothing to read
+
+**Example**
+
+```c
+{
+  uint8_t data[20];
+  jerry_value_t buffer;
+  // ... create the ArrayBuffer or acuiqre it from somewhere.
+
+  jerry_value_t bytes_read;
+
+  // read 10 bytes from the start of the ArrayBuffer.
+  bytes_read = jerry_arraybuffer_read (buffer, 0, data, 10);
+  // read the next 10 bytes
+  bytes_read += jerry_arraybuffer_read (buffer, bytes_read, data + bytes_read, 10);
+
+  // process the data variable
+
+  jerry_release_value (buffer);
+}
+```
+
+**See also**
+
+- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
+- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
+- [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length)
+
+
+## jerry_arraybuffer_write
+
+**Summary**
+
+Copy the contents of a buffer into the ArrayBuffer.
+The start offset of the write operation can be specified.
+
+The number bytes to be written can be specified via the `buf_size`
+parameter. It is not possible to write more than the length of
+the ArrayBuffer.
+
+Function returns the number of bytes written into the ArrayBuffer
+(and read from the buffer parameter). This value is
+calculated in the following way: `min(array buffer length - offset, buf_size)`.
+
+**Prototype**
+
+```c
+jerry_length_t
+jerry_arraybuffer_write (const jerry_value_t value,
+                         jerry_length_t offset,
+                         const uint8_t *buf_p,
+                         jerry_length_t buf_size);
+```
+
+- `value` - ArrayBuffer to write to
+- `offset` - start offset of the write operation
+- `buf_p` - buffer to read the data from
+- `buf_size` - maximum number of bytes to write into the ArrayBuffer
+- return value
+  - number of bytes written into the ArrayBuffer (read from the buffer parameter)
+  - 0 if the `value` is not an ArrayBuffer object
+  - 0 if the `buf_size` is zero or there is nothing to write
+
+**Example**
+
+```c
+{
+  uint8_t data[20];
+
+  // fill the data with values
+  for (int i = 0; i < 20; i++)
+  {
+    data[i] = (uint8_t) (i * 2);
+  }
+
+  jerry_value_t buffer;
+  // ... create the ArrayBuffer or acquire it from somewhere.
+
+  jerry_value_t bytes_written;
+
+  // write 10 bytes from to the start of the ArrayBuffer.
+  bytes_written = jerry_arraybuffer_write (buffer, 0, data, 10);
+  // read the next 10 bytes
+  bytes_written += jerry_arraybuffer_write (buffer, bytes_written, data + bytes_written, 10);
+
+  // use the ArrayBuffer
+
+  jerry_release_value (buffer);
+}
+```
+
+**See also**
+
+- [jerry_create_arraybuffer](#jerry_create_arraybuffer)
+- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
+- [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length)