diff options
author | Zsolt Borbély <zsborbely.u-szeged@partner.samsung.com> | 2018-02-01 02:14:47 +0100 |
---|---|---|
committer | yichoi <duddlf.choi@samsung.com> | 2018-02-01 10:14:47 +0900 |
commit | 38bb39e74408fe71534ab0b5c9b24b893facd89b (patch) | |
tree | b5dc8aefb5696aeeafa0c6ff9d8e81600a7386e3 | |
parent | 204b36ca0b38520d6328050fab9a886b2a1cbc02 (diff) |
Update the webpage (#2186)
JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
-rw-r--r-- | 02.API-REFERENCE.md | 191 |
1 files changed, 190 insertions, 1 deletions
diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 74fe12f2..ea839d17 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -1040,6 +1040,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 @@ -1466,13 +1467,54 @@ jerry_value_has_error_flag (const jerry_value_t value); **See also** - [jerry_value_t](#jerry_value_t) +- [jerry_value_has_abort_flag](#jerry_value_has_abort_flag) + + +## jerry_value_has_abort_flag + +**Summary** + +Returns whether the given `jerry_value_t` has the error and abort flags set. + +**Prototype** + +```c +bool +jerry_value_has_abort_flag (const jerry_value_t value); +``` + +- `value` - api value +- return value + - true, if the given `jerry_value_t` has the error and abort flags set + - false, otherwise + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + if (jerry_value_has_abort_flag (value)) + { + ... + } + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerry_value_t) +- [jerry_value_has_error_flag](#jerry_value_has_error_flag) ## jerry_value_clear_error_flag **Summary** -Clear the error flag. +Clear both the error and abort flags. **Prototype** @@ -1499,6 +1541,8 @@ jerry_value_clear_error_flag (jerry_value_t *value_p); **See also** - [jerry_value_t](#jerry_value_t) +- [jerry_value_set_error_flag](#jerry_value_set_error_flag) +- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag) ## jerry_value_set_error_flag @@ -1532,6 +1576,43 @@ jerry_value_set_error_flag (jerry_value_t *value_p); **See also** - [jerry_value_t](#jerry_value_t) +- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) +- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag) + + +## jerry_value_set_abort_flag + +**Summary** + +Set both the error and abort flags. + +**Prototype** + +```c +void +jerry_value_set_abort_flag (jerry_value_t *value_p); +``` + +- `value_p` - pointer to an api value + +**Example** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_set_abort_flag (&value); + + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerry_value_t) +- [jerry_value_clear_error_flag](#jerry_value_clear_error_flag) +- [jerry_value_set_error_flag](#jerry_value_set_error_flag) ## jerry_get_value_without_error_flag @@ -2475,6 +2556,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** @@ -4931,3 +5062,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) |