Add ArrayBuffer with user specified buffer

New API functions:
 - jerry_create_arraybuffer_external
 - jerry_get_arraybuffer_pointer

JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.u-szeged@partner.samsung.com

1 files changed, 109 insertions, 0 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 3550ffb4..87f59bb0 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -1030,6 +1030,7 @@ jerry_value_is_arraybuffer (const jerry_value_t value)
 **See also**
 
 - [jerry_create_arraybuffer](#jerry_create_arraybuffer)
+- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)
 
 
 ## jerry_value_is_boolean
@@ -2465,6 +2466,56 @@ jerry_create_arraybuffer (jerry_length_t size);
 - [jerry_release_value](#jerry_release_value)
 
 
+## jerry_create_arraybuffer_external
+
+**Summary**
+
+Creates a jerry_value_t representing an ArrayBuffer object with
+user specified back-buffer.
+
+User must pass a buffer pointer which is at least `size` big.
+After the object is not needed the GC will call the `free_cb`
+so the user can release the buffer which was provided.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_arraybuffer_external (const jerry_length_t size
+                                   uint8_t *buffer_p,
+                                   jerry_object_native_free_callback_t free_cb);
+```
+
+- `size` - size of the buffer to use **in bytes** (should not be 0)
+- `buffer_p` - the buffer used for the Array Buffer object (should not be a null pointer)
+- `free_cb` - the callback function called when the object is released
+- return value
+  - the new ArrayBuffer as a `jerry_value_t`
+  - if the `size` is zero or `buffer_p` is a null pointer will return RangeError
+
+**Example**
+
+```c
+{
+  uint8_t buffer_p[15];
+  jerry_value_t buffer_value = jerry_create_arraybuffer_external (15, buffer_p, NULL);
+
+  ... // use the array buffer
+
+  jerry_release_value (buffer_value);
+}
+```
+
+**See also**
+
+- [jerry_get_arraybuffer_pointer](#jerry_get_arraybuffer_pointer)
+- [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_object_native_free_callback_t](#jerry_object_native_free_callback_t)
+
+
 ## jerry_create_boolean
 
 **Summary**
@@ -4921,3 +4972,61 @@ jerry_arraybuffer_write (const jerry_value_t value,
 - [jerry_create_arraybuffer](#jerry_create_arraybuffer)
 - [jerry_arraybuffer_write](#jerry_arraybuffer_write)
 - [jerry_get_arraybuffer_byte_length](#jerry_get_arraybuffer_byte_length)
+
+
+## jerry_get_arraybuffer_pointer
+
+**Summary**
+
+The function allows access to the contents of the Array Buffer directly.
+Only allowed for Array Buffers which were created with
+[jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)
+function calls. In any other case this function will return `NULL`.
+
+After using the pointer the [jerry_release_value](#jerry_release_value)
+function must be called.
+
+**WARNING!** This operation is for expert use only! The programmer must
+ensure that the returned memory area is used correctly. That is
+there is no out of bounds reads or writes.
+
+**Prototype**
+
+```c
+uint8_t *
+jerry_get_arraybuffer_pointer (const jerry_value_t value);
+```
+
+- `value` - Array Buffer object.
+- return value
+  - pointer to the Array Buffer's data area.
+  - NULL if the `value` is not an Array Buffer object with external memory.
+
+**Example**
+
+```c
+{
+  jerry_value_t buffer;
+
+  // acquire buffer somewhere which was created by a jerry_create_array_buffer_external call.
+
+  uint8_t *const data = jerry_get_arraybuffer_pointer (buffer);
+
+  for (int i = 0; i < 22; i++)
+  {
+    data[i] = (uint8_t) (i + 4);
+  }
+
+  // required after jerry_get_arraybuffer_pointer call.
+  jerry_release_value (buffer);
+
+  // use the Array Buffer
+
+  // release buffer as it is not needed after this point
+  jerry_release_value (buffer);
+}
+```
+
+**See also**
+
+- [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)