diff options
author | Péter Gál <pgal.u-szeged@partner.samsung.com> | 2018-01-11 20:36:08 +0100 |
---|---|---|
committer | László Langó <llango.u-szeged@partner.samsung.com> | 2018-01-11 20:36:08 +0100 |
commit | ded0d5a846679699d5767d1122b0c320a0b3d637 (patch) | |
tree | a8d4958bcbc0a37d00d359a097f58d422b6890de /docs | |
parent | b9560b7c70f3191f1a06318108afe680c3805ec0 (diff) |
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
Diffstat (limited to 'docs')
-rw-r--r-- | docs/02.API-REFERENCE.md | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index ce9c1813..3550ffb4 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -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) |