diff --git a/docs/API-EXAMPLE.md b/docs/API-EXAMPLE.md index 2bb08d38a..08c40d380 100644 --- a/docs/API-EXAMPLE.md +++ b/docs/API-EXAMPLE.md @@ -594,4 +594,4 @@ Value of x is 17 ## Further steps -For further API description, please look at [API Reference](/docs/API-REFERENCE.md). +For further API description, please visit [API Reference page](https://samsung.github.io/jerryscript/API/) on [JerryScript home page](https://samsung.github.io/jerryscript/). diff --git a/docs/API-REFERENCE.md b/docs/API-REFERENCE.md index e6ee62bcd..61cd735de 100644 --- a/docs/API-REFERENCE.md +++ b/docs/API-REFERENCE.md @@ -1,1361 +1 @@ -# jerry_run_simple - -**Summary** -The simplest way to run JavaScript. - -**Prototype** - -```c -jerry_completion_code_t -jerry_run_simple (const jerry_api_char_t *script_source, - size_t script_source_size, - jerry_flag_t flags); -``` - -- `script_source` - source code; -- `script_source_size` - size of source code buffer, in bytes; -- returned value - completion code that indicates whether run was performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`). - -**Example** - -```c -{ - const jerry_api_char_t *script = "print ('Hello, World!');"; - - jerry_run_simple (script, strlen ((const char *) script), JERRY_FLAG_EMPTY); -} -``` - -**See also** - -- [jerry_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) -- [jerry_parse](#jerry_parse) -- [jerry_run](#jerry_run) - -# jerry_init - -**Summary** - -Initializes JerryScript engine, making possible to run JavaScript code and perform operations on JavaScript values. - -**Prototype** - -```c -void -jerry_init (jerry_flag_t flags); -``` - -`flags` - combination of various engine configuration flags: - -- `JERRY_FLAG_EMPTY` - no flags, just initialize in default configuration; -- `JERRY_FLAG_SHOW_OPCODES` - print compiled byte-code; -- `JERRY_FLAG_MEM_STATS` - dump memory statistics; -- `JERRY_FLAG_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse; -- `JERRY_FLAG_ENABLE_LOG` - enable logging; - -**Example** - -```c -{ - jerry_init (JERRY_FLAG_ENABLE_LOG); - - // ... - - jerry_cleanup (); -} -``` - -**See also** - -- [jerry_cleanup](#jerry_cleanup) - -# jerry_cleanup - -**Summary** - -Finish JavaScript engine execution, freeing memory and JavaScript values. - -JavaScript values, received from engine, are inaccessible after the cleanup. - -**Prototype** - -```c -void -jerry_cleanup (void); -``` - -**See also** - -- [jerry_init](#jerry_init) - -# jerry_parse - -**Summary** -Parse specified script to execute in Global scope. - -Current API doesn't permit replacement or modification of Global scope's code without engine restart, -so `jerry_parse` could be invoked only once between `jerry_init` and `jerry_cleanup`. - -**Prototype** - -```c -bool -jerry_parse (const jerry_api_char_t *source_p, - size_t source_size, - jerry_api_object_t **error_obj_p); -``` -- `source_p` - string, containing source code to parse; -- `source_size` - size of the string, in bytes. -- `error_obj_p` - error object (output parameter) - -**Example** - -```c -{ - jerry_init (JERRY_FLAG_EMPTY); - - char script [] = "print ('Hello, World!');"; - size_t script_size = strlen ((const char *) script); - - jerry_api_object_t *error_object_p = NULL; - if (!jerry_parse (script, script_size, &error_object_p)) - { - /* Error object must be freed, if parsing failed */ - jerry_api_release_object (error_object_p); - } - - jerry_cleanup (); -} -``` - -**See also** - -- [jerry_run](#jerry_run) - -# jerry_run - -**Summary** -Run code of Global scope. - -The code should be previously registered through `jerry_parse`. - -**Prototype** - -```c -jerry_completion_code_t -jerry_run (jerry_api_value_t *error_value_p); -``` -- `error_value_p` - error value (output parameter) -- returned value - completion code that indicates whether run performed successfully - - `JERRY_COMPLETION_CODE_OK` - successful completion - - `JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION` - an unhandled JavaScript exception occurred - - `JERRY_COMPLETION_CODE_INVALID_SNAPSHOT_VERSION` - snapshot version mismatch - - `JERRY_COMPLETION_CODE_INVALID_SNAPSHOT_FORMAT` - snapshot format is not valid - -**Example** - -```c -{ - const jerry_api_char_t script[] = "print ('Hello, World!');"; - size_t script_size = strlen ((const char *) script); - - /* Initialize engine */ - jerry_init (JERRY_FLAG_EMPTY); - - /* Setup Global scope code */ - jerry_api_object_t *error_object_p = NULL; - if (!jerry_parse (script, script_size, &error_object_p)) - { - /* Error object must be freed, if parsing failed */ - jerry_api_release_object (error_object_p); - } - else - { - /* Execute Global scope code - * - * Note: - * Initialization of 'error_value' is not mandatory here. - */ - jerry_api_value_t error_value = jerry_api_create_void_value (); - jerry_completion_code_t return_code = jerry_run (&error_value); - - if (return_code == JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION) - { - /* Error value must be freed, if 'jerry_run' returns with an unhandled exception */ - jerry_api_release_value (&error_value); - } - } - - jerry_cleanup (); -} -``` - -**See also** - -- [jerry_parse](#jerry_parse) - -# jerry_api_value_t - -**Summary** -The data type represents any JavaScript value that can be sent to or received from the engine. - -Type of value is identified by `jerry_api_value_t::type`, and can be one of the following: - -- `JERRY_API_DATA_TYPE_VOID` - no return value -- `JERRY_API_DATA_TYPE_UNDEFINED` - JavaScript undefined; -- `JERRY_API_DATA_TYPE_NULL` - JavaScript null; -- `JERRY_API_DATA_TYPE_BOOLEAN` - boolean; -- `JERRY_API_DATA_TYPE_FLOAT32` - number; -- `JERRY_API_DATA_TYPE_FLOAT64` - number; -- `JERRY_API_DATA_TYPE_UINT32` - number; -- `JERRY_API_DATA_TYPE_STRING` - string; -- `JERRY_API_DATA_TYPE_OBJECT` - reference to JavaScript object. - -**Structure** - -```c -typedef struct jerry_api_value_t -{ - jerry_api_data_type_t type; - - union - { - bool v_bool; - - float v_float32; - double v_float64; - - uint32_t v_uint32; - - jerry_api_string_t v_string; - jerry_api_object_t v_object; - } u; -} jerry_api_value_t; -``` - -**See also** - -- [jerry_api_eval](#jerry_api_eval) -- [jerry_api_call_function](#jerry_api_call_function) -- [jerry_api_construct_object](#jerry_api_construct_object) - -# jerry_api_eval - -**Summary** -Perform JavaScript `eval`. - -**Prototype** - -```c -jerry_completion_code_t -jerry_api_eval (const jerry_api_char_t *source_p, - size_t source_size, - bool is_direct, - bool is_strict, - jerry_api_value_t *retval_p); -``` - -- `source_p` - source code to evaluate; -- `source_size` - length of the source code; -- `is_direct` - whether to perform `eval` in "direct" mode (possible only if `eval` invocation is performed from native function, called from JavaScript); -- `is_strict` - perform `eval` as it is called from "strict mode" code; -- `retval_p` - value, returned by `eval` (output parameter); -- returned value - completion code that indicates whether run performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`). - -**Example** - -```c -{ - jerry_api_value_t ret_val; - - jerry_completion_code_t status = jerry_api_eval (str_to_eval, - strlen (str_to_eval), - false, false, - &ret_val); -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_create_external_function](#jerry_api_create_external_function) -- [jerry_external_handler_t](#jerry_external_handler_t) - -# jerry_api_create_string - -**Summary** -Create new JavaScript string. - -Upon the JavaScript string becomes unused, all pointers to it should be released using [jerry_api_release_string](#jerry_api_release_string). - -**Prototype** - -```c -jerry_api_string_t * -jerry_api_create_string (const jerry_api_char_t *v); -``` - -- `v` - value of string to create; -- returned value is pointer to created string. - -**Example** - -```c -{ - jerry_api_string_t *string_p = jerry_api_create_string ("abc"); - - ... - - jerry_api_release_string (string_p); -} -``` - -**See also** - -- [jerry_api_acquire_string](#jerry_api_acquire_string) -- [jerry_api_release_string](#jerry_api_release_string) -- [jerry_api_string_to_char_buffer](#jerry_api_string_to_char_buffer) - -# jerry_api_string_to_char_buffer - -**Summary** -Copy string characters to specified buffer, append zero character at end of the buffer. - -**Prototype** - -```c -jerry_api_size_t -jerry_api_string_to_char_buffer (const jerry_api_string_t *string_p, - jerry_api_char_t *buffer_p, - jerry_api_size_t buffer_size); -``` - -- `string_p` - pointer to a string; -- `buffer_p` - pointer to output buffer (can be NULL, is `buffer_size` is 0); -- `buffer_size` - size of the buffer; -- returned value: - - number of bytes, actually copied to the buffer - if characters were copied successfully; - - otherwise (in case size of buffer is insufficient) - negative number, which is calculated as negation of buffer size, that is required to hold characters. - -**Example** - -```c -{ - jerry_api_object_t *obj_p = jerry_api_get_global (); - jerry_api_value_t val; - - bool is_ok = jerry_api_get_object_field_value (obj_p, - "field_with_string_value", - &val); - - if (is_ok) - { - bool is_string = (val.type == JERRY_API_DATA_TYPE_STRING); - - if (is_string) - { - // neg_req_sz would be negative, as zero-size buffer is insufficient for any string - jerry_api_size_t req_sz = jerry_api_get_string_size (val.string_p); - jerry_api_char_t *str_buf_p = (jerry_api_char_t *) malloc (req_sz); - - // sz would be -neg_req_sz - jerry_api_size_t sz = jerry_api_string_to_char_buffer (val.string_p, - str_buf_p, - req_sz); - - printf ("%s", str_buf_p); - - free (str_buf_p); - } - - jerry_api_release_value (&val); - } - - jerry_api_release_object (obj_p); -} -``` - -**See also** - -- [jerry_api_create_string](#jerry_api_create_string) -- [jerry_api_value_t](#jerry_api_value_t) - -# jerry_api_acquire_string - -**Summary** -Acquire new pointer to the string for usage outside of the engine. - -The acquired pointer should be released with [jerry_api_release_string](#jerry_api_release_string). - -**Prototype** - -```c -jerry_api_string_t * -jerry_api_acquire_string (jerry_api_string_t *string_p); -``` - -- `string_p` - pointer to the string; -- returned value - new pointer to the string. - -**Example** - -```c -{ - jerry_api_string_t *str_ptr1_p = jerry_api_create_string ("abc"); - jerry_api_string_t *str_ptr2_p = jerry_api_acquire_string (str_ptr1_p); - - ... // usage of both pointers - - jerry_api_release_string (str_ptr1_p); - - ... // usage of str_ptr2_p pointer - - jerry_api_release_string (str_ptr2_p); -} -``` - -**See also** - -- [jerry_api_release_string](#jerry_api_release_string) -- [jerry_api_create_string](#jerry_api_create_string) - -# jerry_api_release_string - -**Summary** -Release specified pointer to the string. - -**Prototype** - -```c -void -jerry_api_release_string (jerry_api_string_t *string_p); -``` - -- `string_p` - pointer to the string. - -**Example** - -```c -{ - jerry_api_string_t *str_ptr1_p = jerry_api_create_string ("abc"); - jerry_api_string_t *str_ptr2_p = jerry_api_acquire_string (str_ptr1_p); - - ... // usage of both pointers - - jerry_api_release_string (str_ptr1_p); - - ... // usage of str_ptr2_p pointer - - jerry_api_release_string (str_ptr2_p); -} -``` - -**See also** - -- [jerry_api_acquire_string](#jerry_api_acquire_string) -- [jerry_api_create_string](#jerry_api_create_string) - -# jerry_api_create_object - -**Summary** -Create new JavaScript object, like with `new Object()`. - -Upon the JavaScript object becomes unused, all pointers to it should be released using [jerry_api_release_object](#jerry_api_release_object). - -**Prototype** - -```c -jerry_api_object_t * -jerry_api_create_object (); -``` - -- returned value is pointer to the created object. - -**Example** - -```c -{ - jerry_api_object_t *object_p = jerry_api_create_object (); - - ... - - jerry_api_release_object (object_p); -} -``` - -**See also** - -- [jerry_api_acquire_object](#jerry_api_acquire_object) -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_add_object_field](#jerry_api_add_object_field) -- [jerry_api_delete_object_field](#jerry_api_delete_object_field) -- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) -- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) -- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) -- [jerry_api_set_object_native_handle](#jerry_api_set_object_native_handle) - -# jerry_api_acquire_object - -**Summary** -Acquire new pointer to the object for usage outside of the engine. - -The acquired pointer should be released with [jerry_api_release_object](#jerry_api_release_object). - -**Prototype** - -```c -jerry_api_object_t * -jerry_api_acquire_object (jerry_api_object_t *object_p); -``` - -- `object_p` - pointer to the object; -- returned value - new pointer to the object. - -**Example** - -```c -{ - jerry_api_object_t *obj_ptr1_p = jerry_api_create_object (); - jerry_api_object_t *obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p); - - ... // usage of both pointers - - jerry_api_release_object (obj_ptr1_p); - - ... // usage of obj_ptr2_p pointer - - jerry_api_release_object (obj_ptr2_p); -} -``` - -**See also** - -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_create_object](#jerry_api_create_object) - -# jerry_api_release_object - -**Summary** -Release specified pointer to the object. - -**Prototype** - -```c -void -jerry_api_release_object (jerry_api_object_t *object_p); -``` - -- `object_p` - pointer to the object. - -**Example** - -```c -{ - jerry_api_object_t *obj_ptr1_p = jerry_api_create_object (); - jerry_api_object_t *obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p); - - ... // usage of both pointers - - jerry_api_release_object (obj_ptr1_p); - - ... // usage of obj_ptr2_p pointer - - jerry_api_release_object (obj_ptr2_p); -} -``` - -**See also** - -- [jerry_api_acquire_object](#jerry_api_acquire_object) -- [jerry_api_create_object](#jerry_api_create_object) - -# jerry_api_get_global - -**Summary** -Get the Global object. - -**Prototype** - -```c -jerry_api_object_t * -jerry_api_get_global (void); -``` - -- returned value - pointer to the Global object. - -Received pointer should be released with [jerry_api_release_object](#jerry_api_release_object), just when the value becomes unnecessary. - -**Example** - -```c -{ - jerry_api_object_t *glob_obj_p = jerry_api_get_global (); - - jerry_api_value_t val; - bool is_ok = jerry_api_get_object_field_value (glob_obj_p, "some_field_name", &val); - if (is_ok) - { - ... // usage of 'val' - - jerry_api_release_value (&val); - } - - jerry_api_release_object (glob_obj_p); -} -``` - -**See also** - -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_add_object_field](#jerry_api_add_object_field) -- [jerry_api_delete_object_field](#jerry_api_delete_object_field) -- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) -- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) - -# jerry_api_add_object_field - -**Summary** -Create field (named data property) in an object - -**Prototype** - -```c -bool -jerry_api_add_object_field (jerry_api_object_t *object_p, - const jerry_api_char_t *field_name_p, - const jerry_api_value_t *field_value_p, - bool is_writable); -``` - -- `object_p` - object to add field at; -- `field_name_p` - name of the field; -- `field_value_p` - value of the field; -- `is_writable` - flag indicating whether the created field should be writable. -- returned value - true, if field was created successfully, i.e. upon the call: - - there is no field with same name in the object; - - the object is extensible. - -**Example** - -```c -{ - jerry_api_object_t *obj_p = jerry_api_create_object (); - - jerry_api_value_t val; - - ... // initialize val - - // Make new constant field - jerry_api_add_object_field (obj_p, "some_field_name", &val, false); -} -``` - - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_create_object](#jerry_api_create_object) - -# jerry_api_delete_object_field - -**Summary** -Delete field (property) in the specified object - -**Prototype** - -```c -bool -jerry_api_delete_object_field (jerry_api_object_t *object_p, - const jerry_api_char_t *field_name_p); -``` - -- `object_p` - object to delete field at; -- `field_name_p` - name of the field. -- returned value - true, if field was deleted successfully, i.e. upon the call: - - there is field with specified name in the object. - -**Example** - -```c -{ - jerry_api_object_t *obj_p; - ... // receive or construct obj_p - - jerry_api_delete_object_field (obj_p, "some_field_name"); -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_create_object](#jerry_api_create_object) - -# jerry_api_get_object_field_value - -**Summary** -Get value of field (property) in the specified object, i.e. perform [[Get]] operation. - -**Prototype** - -```c -bool -jerry_api_get_object_field_value (jerry_api_object_t *object_p, - const jerry_api_char_t *field_name_p, - jerry_api_value_t *field_value_p); -``` - -- `object_p` - object; -- `field_name_p` - name of the field; -- `field_value_p` - retrieved field value (output parameter). -- returned value - true, if field value was retrieved successfully, i.e. upon the call: - - there is field with specified name in the object. - -If value was retrieved successfully, it should be freed with [jerry_api_release_object](#jerry_api_release_object) just when it becomes unnecessary. - -**Example** - -```c -{ - jerry_api_object_t *obj_p; - ... // receive or construct obj_p - - jerry_api_value_t val; - bool is_ok = jerry_api_get_object_field_value (obj_p, "some_field_name", &val); - if (is_ok) - { - ... // usage of 'val' - - jerry_api_release_value (&val); - } -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_create_object](#jerry_api_create_object) - -# jerry_api_set_object_field_value - -**Summary** -Set value of a field (property) in the specified object, i.e. perform [[Put]] operation. - -**Prototype** - -```c -bool -jerry_api_set_object_field_value (jerry_api_object_t *object_p, - const jerry_api_char_t *field_name_p, - jerry_api_value_t *field_value_p); -``` - -- `object_p` - object; -- `field_name_p` - name of the field; -- `field_value_p` - field value to set. -- returned value - true, if field value was set successfully, i.e. upon the call: - - field value is writable. - -**Example** - -```c -{ - jerry_api_object_t *obj_p; - jerry_api_value_t val; - - ... // receive or construct obj_p and val - - bool is_ok = jerry_api_set_object_field_value (obj_p, "some_field_name", &val); -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_create_object](#jerry_api_create_object) - -# jerry_api_get_object_native_handle - -**Summary** - -Get native handle, previously associated with specified object. - -**Prototype** - -```c -bool -jerry_api_get_object_native_handle (jerry_api_object_t *object_p, - uintptr_t *out_handle_p); -``` - -- `object_p` - object to get handle from; -- `out_handle_p` - handle value (output parameter); -- returned value - true, if there is handle associated with the object. - -**Example** - -```c -{ - jerry_api_object_t *obj_p; - uintptr_t handle_set; - - ... // receive or construct obj_p and handle_set value - - jerry_api_set_object_native_handle (obj_p, handle_set, NULL); - - ... - - uintptr_t handle_get; - bool is_there_associated_handle = jerry_api_get_object_native_handle (obj_p, - &handle_get); -} -``` - -**See also** - -- [jerry_api_create_object](#jerry_api_create_object) -- [jerry_api_set_object_native_handle](#jerry_api_set_object_native_handle) - -# jerry_api_set_object_native_handle - -**Summary** - -Set native handle and, optionally, "free" callback for the specified object. - -If native handle or "free" callback were already set for the object, corresponding value is updated. - -**Prototype** - -```c -void -jerry_api_set_object_native_handle (jerry_api_object_t *object_p, - uintptr_t handle, - jerry_object_free_callback_t freecb_p); -``` - -- `object_p` - object to set handle in; -- `handle` - handle value; -- `freecb_p` - pointer to "free" callback or NULL (if not NULL the callback would be called upon GC of the object). - -**Example** - -```c -{ - jerry_api_object_t *obj_p; - uintptr_t handle_set; - - ... // receive or construct obj_p and handle_set value - - jerry_api_set_object_native_handle (obj_p, handle_set, NULL); - - ... - - uintptr_t handle_get; - bool is_there_associated_handle = jerry_api_get_object_native_handle (obj_p, - &handle_get); -} -``` - -**See also** - -- [jerry_api_create_object](#jerry_api_create_object) -- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) - -# jerry_api_is_function - -**Summary** -Check whether the specified object is a function object. - -**Prototype** - -```c -bool -jerry_api_is_function (const jerry_api_object_t *object_p); -``` - -- `object_p` - object to check; -- returned value - just boolean, indicating whether the specified object can be called as function. - -**Example** - -```c -{ - jerry_api_value_t val; - - ... // receiving val - - if (val.type == JERRY_API_DATA_TYPE_OBJECT) - { - if (jerry_api_is_function (val.u.v_object)) - { - // the object is function object - } - } -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_is_constructor](#jerry_api_is_constructor) -- [jerry_api_call_function](#jerry_api_call_function) - -# jerry_api_is_constructor - -**Summary** -Check whether the specified object is a constructor function object. - -**Prototype** - -```c -bool -jerry_api_is_constructor (const jerry_api_object_t *object_p); -``` - -- `object_p` - object to check; -- returned value - just boolean, indicating whether the specified object can be called as constructor. - -**Example** - -```c -{ - jerry_api_value_t val; - - ... // receiving val - - if (val.type == JERRY_API_DATA_TYPE_OBJECT) - { - if (jerry_api_is_constructor (val.u.v_object)) - { - // the object is constructor function object - } - } -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_is_function](#jerry_api_is_function) -- [jerry_api_construct_object](#jerry_api_construct_object) - -# jerry_api_call_function - -**Summary** -Call function object. - -**Prototype** - -```c -bool -jerry_api_call_function (jerry_api_object_t *function_object_p, - jerry_api_object_t *this_arg_p, - jerry_api_value_t *retval_p, - const jerry_api_value_t args_p[], - uint16_t args_count); -``` - -- `function_object_p` - the function object to call; -- `this_arg_p` - object to use as 'this' during the invocation, or NULL - to set the Global object as 'this'; -- `retval_p` - function's return value (output parameter); -- `args_p`, `args_count` - array of arguments and number of them; -- returned value - true, if call was performed successfully, i.e.: - - specified object is a function object (see also jerry_api_is_function); - - no unhandled exceptions were thrown in connection with the call. - - If call was performed successfully, returned value should be freed with [jerry_api_release_object](#jerry_api_release_object) just when it becomes unnecessary. - -**Example** - -```c -{ - jerry_api_value_t val; - - ... // receiving val - - if (val.type == JERRY_API_DATA_TYPE_OBJECT) - { - if (jerry_api_is_function (val.u.v_object)) - { - jerry_api_value_t ret_val; - - bool is_ok = jerry_api_call_function (val.u.v_object, - NULL, - &ret_val, - NULL, 0); - - if (is_ok) - { - ... // handle return value - - jerry_api_release_value (&ret_val); - } - } - } -} -``` - -**See also** - -- [jerry_api_is_function](#jerry_api_is_function) -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_create_external_function](#jerry_api_create_external_function) - -# jerry_api_construct_object - -**Summary** -Construct object invoking specified function object as constructor. - -**Prototype** - -```c -bool -jerry_api_construct_object (jerry_api_object_t *function_object_p, - jerry_api_value_t *retval_p, - const jerry_api_value_t args_p[], - uint16_t args_count); -``` - -- `function_object_p` - the function object to invoke; -- `retval_p` - return value of function invoked as constructor, i.e. like with 'new' operator (output parameter); -- `args_p`, `args_count` - array of arguments and number of them; -- returned value - true, if call was performed successfully, i.e.: - - specified object is a constructor function object; - - no unhandled exceptions were thrown in connection with the call. - -If call was performed successfully, returned value should be freed with [jerry_api_release_object](#jerry_api_release_object) just when it becomes unnecessary. - -**Example** - -```c -{ - jerry_api_value_t val; - - ... // receiving val - - if (val.type == JERRY_API_DATA_TYPE_OBJECT) - { - if (jerry_api_is_constructor (val.u.v_object)) - { - jerry_api_value_t ret_val; - - bool is_ok = jerry_api_construct_object (val.u.v_object, - &ret_val, - NULL, 0); - - if (is_ok) - { - ... // handle return value - - jerry_api_release_value (&ret_val); - } - } - } -} -``` - -**See also** - - - [jerry_api_is_constructor](#jerry_api_is_constructor) - - [jerry_api_value_t](#jerry_api_value_t) - -# jerry_external_handler_t - -**Summary** - -The data type represents pointer to call handler of a native function object. - -**Structure** - -```c -typedef bool (* jerry_external_handler_t) (const jerry_api_object_t *function_obj_p, - const jerry_api_value_t *this_p, - jerry_api_value_t *ret_val_p, - const jerry_api_value_t args_p[], - const uint16_t args_count); -``` - -**See also** - -- [jerry_api_create_external_function](#jerry_api_create_external_function) - -# jerry_api_create_external_function - -**Summary** -Create an external function object. - -**Prototype** - -```c -jerry_api_object_t * -jerry_api_create_external_function (jerry_external_handler_t handler_p); -``` - -- `handler_p` - pointer to native handler of the function object; -- returned value - pointer to constructed external function object. - -Received pointer should be released with [jerry_api_release_object](#jerry_api_release_object), just when the value becomes unnecessary. - -**Example** - -```c -static bool -handler (const jerry_api_object_t *function_obj_p, - const jerry_api_value_t *this_p, - jerry_api_value_t *ret_val_p, - const jerry_api_value_t args_p[], - const uint16_t args_cnt) -{ - printf ("native handler called!\n"); - - ret_val_p->type = JERRY_API_DATA_TYPE_BOOLEAN; - ret_val_p->u.v_bool = true; -} - -{ - jerry_api_object_t *obj_p = jerry_api_create_external_function (handler); - jerry_api_object_t *glob_obj_p = jerry_api_get_global (); - - jerry_api_value_t val; - val.type = JERRY_API_DATA_TYPE_OBJECT; - val.u.v_object = obj_p; - - // after this, script can invoke the native handler through "handler_field (1, 2, 3);" - jerry_api_set_object_field_value (glob_obj_p, "handler_field", &val); - - jerry_api_release_object (glob_obj_p); - jerry_api_release_object (obj_p); -} -``` - -**See also** - -- [jerry_external_handler_t](#jerry_external_handler_t) -- [jerry_api_is_function](#jerry_api_is_function) -- [jerry_api_call_function](#jerry_api_call_function) -- [jerry_api_release_object](#jerry_api_release_object) - -# jerry_api_create_array_object - -**Summary** -Create new JavaScript array object. - -Upon the JavaScript array object becomes unused, all pointers to it should be released using [jerry_api_release_object](#jerry_api_release_object). - -**Prototype** - -```c -jerry_api_object_t * -jerry_api_create_array_object (jerry_api_size_t array_size); -``` - - - `array_size` - size of array; - - returned value is pointer to the created array object. - - **Example** - -```c -{ - jerry_api_object_t *array_object_p = jerry_api_create_array_object (10); - - ... - - jerry_api_release_object (array_object_p); -} -``` - -**See also** - -- [jerry_api_acquire_object](#jerry_api_acquire_object) -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_set_array_index_value](#jerry_api_set_array_index_value) -- [jerry_api_get_array_index_value](#jerry_api_get_array_index_value) -- [jerry_api_add_object_field](#jerry_api_add_object_field) -- [jerry_api_delete_object_field](#jerry_api_delete_object_field) -- [jerry_api_get_object_field_value](#jerry_api_get_object_field_value) -- [jerry_api_set_object_field_value](#jerry_api_set_object_field_value) -- [jerry_api_get_object_native_handle](#jerry_api_get_object_native_handle) -- [jerry_api_set_object_native_handle](#jerry_api_set_object_native_handle) - -# jerry_api_set_array_index_value - -**Summary** -Set value of an indexed element in the specified array object. - -**Prototype** - -```c -bool -jerry_api_set_array_index_value (jerry_api_object_t *array_object_p, - jerry_api_length_t index, - jerry_api_value_t *value_p); -``` - -- `array_object_p` - pointer to the array object; -- `index` - index of the array element; -- `value_p` - indexed value to set; -- returned value - true, if value was set successfully. - -**Example** - -```c -{ - jerry_api_object_t *array_object_p = jerry_api_create_array_object (10); - jerry_api_value_t val; - - ... // receive or construct val - - jerry_api_set_array_index_value (array_object_p, 5, &val); - - jerry_api_release_object (array_object_p); -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_create_array_object](#jerry_api_create_array_object) - -# jerry_api_get_array_index_value - -**Summary** -Get value of an indexed element in the specified array object. - -**Prototype** - -```c -bool -jerry_api_get_array_index_value (jerry_api_object_t *array_object_p, - jerry_api_length_t index, - jerry_api_value_t *value_p); -``` - -- `array_object_p` - pointer to the array object; -- `index` - index of the array element; -- `value_p` - retrieved indexed value (output parameter); -- returned value - true, if value was retrieved successfully. - -**Example** - -```c -{ - jerry_api_object_t *array_object_p; - ... // receive or construct array_object_p - - jerry_api_value_t val; - bool is_ok = jerry_api_get_array_index_value (array_object_p, 5, &val); - if (is_ok) - { - ... // usage of 'val' - } -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) -- [jerry_api_create_array_object](#jerry_api_create_array_object) - -# jerry_api_release_value - -**Summary** -Release specified pointer to the value. - -**Prototype** - -```c -void -jerry_api_release_value (jerry_api_value_t *value_p); -``` - -- `value_p` - pointer to the value. - -**Example** -```c -{ - jerry_api_value_t val1; - jerry_api_value_t val2; - - val1.type = JERRY_API_DATA_TYPE_OBJECT; - val1.u.v_object = jerry_api_create_object (); - - val2.type = JERRY_API_DATA_TYPE_STRING; - val2.u.v_string = jerry_api_create_string ("abc"); - - ... // usage of val1 - - jerry_api_release_value (&val1); - - ... // usage of val2 - - jerry_api_release_value (&val2); -} -``` - -**See also** - -- [jerry_api_value_t](#jerry_api_value_t) - -# jerry_api_create_error - -**Summary** -Create new JavaScript error object. -it should be throwed inside of handle attached to external function object. - -**Prototype** - -```c -jerry_api_object_t * -jerry_api_create_error (jerry_api_error_t error_type, - const jerry_api_char_t *message_p); -``` - -- `error_type` - error type of object; -- `message_p` - human-readable description of the error; -- returned value is pointer to the created error object. - -**Example** - -```c -static bool -handler (const jerry_api_object_t *function_obj_p, - const jerry_api_value_t *this_p, - jerry_api_value_t *ret_val_p, - const jerry_api_value_t args_p[], - const uint16_t args_cnt) -{ - jerry_api_object_t *error_p = jerry_api_create_error (JERRY_API_ERROR_TYPE, - (jerry_api_char_t * ) "error"); - - jerry_api_acquire_object (error_p); - ret_val_p->type = JERRY_API_DATA_TYPE_OBJECT; - ret_val_p->u.v_object = error_p; - - jerry_api_release_object (error_p); - - return false; -} - -{ - jerry_api_object_t *throw_obj_p = jerry_api_create_external_function (handler); - jerry_api_object_t *glob_obj_p = jerry_api_get_global (); - - jerry_api_value_t val; - val.type = JERRY_API_DATA_TYPE_OBJECT; - val.u.v_object = throw_obj_p; - - // after this, script can invoke the native handler through "error_func ();" - // and "error_func" throw a error on called - jerry_api_set_object_field_value (glob_obj_p, "error_func", &val); - - jerry_api_release_object (glob_obj_p); - jerry_api_release_object (throw_obj_p); -} -``` - -**See also** -- [jerry_external_handler_t](#jerry_external_handler_t) -- [jerry_api_is_function](#jerry_api_is_function) -- [jerry_api_call_function](#jerry_api_call_function) -- [jerry_api_release_object](#jerry_api_release_object) -- [jerry_api_create_external_function](#jerry_api_create_external_function) +See JerryScript API documentation on [JerryScript home page](https://samsung.github.io/jerryscript/API/). \ No newline at end of file