From 536fedb60cafe75878934ef31a54f00e3d85c3ec Mon Sep 17 00:00:00 2001
From: Ruben Ayrapetyan <r.ayrapetyan@samsung.com>
Date: Sun, 14 Jun 2015 15:30:35 +0300
Subject: [PATCH] Update API description.

---
 03.api.md | 769 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 635 insertions(+), 134 deletions(-)

diff --git a/03.api.md b/03.api.md
index 147e6503b..b8cd1a96f 100644
--- a/03.api.md
+++ b/03.api.md
@@ -7,6 +7,39 @@ permalink: /API/
 * toc
 {:toc}
 
+# jerry_run_simple
+
+**Summary**
+The simplest way to run JavaScript.
+
+**Prototype**
+```cpp
+jerry_completion_code_t
+jerry_run_simple (const char *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 performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`).
+
+
+**See also**
+- [jerry_init](#jerry_init)
+- [jerry_cleanup](#jerry_cleanup)
+- [jerry_parse](#jerry_parse)
+- [jerry_run](#jerry_run)
+
+**Example**
+```cpp
+{
+  const char *script = "print ('Hello, World!');";
+
+  jerry_run_simple (script, strlen (script), JERRY_FLAG_EMPTY);
+}
+```
+
 # jerry_init
 
 **Summary**
@@ -14,9 +47,9 @@ permalink: /API/
 Initializes JerryScript engine, making possible to run JavaScript code and perform operations on JavaScript values.
 
 **Prototype**
-
 ```cpp
-void jerry_init (jerry_flag_t flags);
+void
+jerry_init (jerry_flag_t flags);
 ```
 
 `flags` - combination of various engine configuration flags:
@@ -27,15 +60,15 @@ void jerry_init (jerry_flag_t flags);
 - `JERRY_FLAG_EMPTY` - no flags, just initialize in default configuration.
 
 **See also**
-
 - [jerry_cleanup](#jerry_cleanup)
 
 **Example**
-
 ```cpp
 {
   jerry_init (JERRY_FLAG_ENABLE_LOG);
+
   // ...
+
   jerry_cleanup ();
 }
 ```
@@ -44,17 +77,18 @@ void jerry_init (jerry_flag_t flags);
 
 **Summary**
 
-Finish JavaScript engine execution, freeing memory and JavaScript values. JavaScript values, received from engine, are inaccessible after the cleanup.
+Finish JavaScript engine execution, freeing memory and JavaScript values.
+
+JavaScript values, received from engine, are inaccessible after the cleanup.
 
 **Prototype**
-
 ```cpp
-void jerry_cleanup (void);
+void
+jerry_cleanup (void);
 ```
 
 **See also**
-
-- [jerry_init]({{ site.baseurl }}/API#jerry_init)
+- [jerry_init](#jerry_init)
 
 # jerry_parse
 
@@ -65,52 +99,49 @@ Current API doesn't permit replacement or modification of Global scope's code wi
 so `jerry_parse` could be invoked only once between `jerry_init` and `jerry_cleanup`.
 
 **Prototype**
-
 ```cpp
-bool jerry_parse (const char* source_p, size_t source_size);
+bool
+jerry_parse (const char* source_p, size_t source_size);
 ```
-
 - `source_p` - string, containing source code to parse;
 - `source_size` - size of the string, in bytes.
 
 **See also**
-
-- [jerry_run]({{ site.baseurl }}/API#jerry_run)
+- [jerry_run](#jerry_run)
 
 **Example**
-
 ```cpp
- {
-   jerry_init (JERRY_FLAG_ENABLE_LOG);
+{
+  jerry_init (JERRY_FLAG_ENABLE_LOG);
 
-   char script [] = "print ('Hello, World!');";
-   jerry_parse (script, strlen (script));
+  char script [] = "print ('Hello, World!');";
+  jerry_parse (script, strlen (script));
 
-   jerry_run ();
+  jerry_run ();
 
-   jerry_cleanup ();
- }
+  jerry_cleanup ();
+}
 ```
 
 # jerry_run
 
 **Summary**
-Run Global scope's code. The code should be previously registered through `jerry_parse`.
+Run code of Global scope.
+
+The code should be previously registered through `jerry_parse`.
 
 **Prototype**
-
 ```cpp
-jerry_completion_code_t jerry_run (void);
+jerry_completion_code_t
+jerry_run (void);
 ```
 
-Returned completion code indicates whether run performed successfully (`JERRY_COMPLETION_CODE_OK`), or an unhandled JavaScript exception occurred (`JERRY_COMPLETION_CODE_UNHANDLED_EXCEPTION`).
+- 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`).
 
 **See also**
-
-- [jerry_parse]({{ site.baseurl }}/API#jerry_parse)
+- [jerry_parse](#jerry_parse)
 
 **Example**
-
 ```cpp
 {
   jerry_init (JERRY_FLAG_ENABLE_LOG);
@@ -128,6 +159,7 @@ Returned completion code indicates whether run performed successfully (`JERRY_CO
 
 **Summary**
 The data type represents any JavaScript value that can be sent to / 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_UNDEFINED` - JavaScript undefined;
@@ -155,20 +187,19 @@ typedef struct jerry_api_value_t
 
     union
     {
-      jerry_api_string_t* v_string;
-      jerry_api_object_t* v_object;
+      jerry_api_string_t *v_string;
+      jerry_api_object_t *v_object;
     };
   };
 } jerry_api_value_t;
 ```
 
 **See also**
-
-- [jerry_api_string_t]({{ site.baseurl }}/API#jerry_api_string_t)
-- [jerry_api_object_t]({{ site.baseurl }}/API#jerry_api_object_t)
-- [jerry_api_eval]({{ site.baseurl }}/API#jerry_api_eval)
-- [jerry_api_call_function]({{ site.baseurl }}/API#jerry_api_call_function)
-- [jerry_api_construct_object]({{ site.baseurl }}/API#jerry_api_construct_object)
+- [jerry_api_string_t](#jerry_api_string_t)
+- [jerry_api_object_t](#jerry_api_object_t)
+- [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
@@ -177,29 +208,28 @@ typedef struct jerry_api_value_t
 Perform JavaScript `eval`.
 
 **Prototype**
-
 ```cpp
 jerry_completion_code_t
-jerry_api_eval (const char* source_p,
+jerry_api_eval (const char *source_p,
                 size_t source_size,
                 bool is_direct,
                 bool is_strict,
-                jerry_api_value_t* retval_p);
+                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).
+- `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`).
 
 **See also**
-
-- [jerry_api_create_external_function]({{ site.baseurl }}/API#jerry_api_create_external_function)
-- [jerry_api_value_t]({{ site.baseurl }}/API#jerry_api_value_t)
+- [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)
 
 **Example**
-
 ```cpp
 {
   jerry_api_value_t ret_val;
@@ -216,61 +246,126 @@ jerry_api_eval (const char* source_p,
 **Summary**
 Create new JavaScript string.
 
-Upon the JavaScript string becomes unused, all pointers to it should be released using [jerry_api_release_string]({{ site.baseurl }}/API#jerry_api_release_string).
+Upon the JavaScript string becomes unused, all pointers to it should be released using [jerry_api_release_string](#jerry_api_release_string).
 
 **Prototype**
-
 ```cpp
-jerry_api_string_t* jerry_api_create_string (const char* v);
+jerry_api_string_t*
+jerry_api_create_string (const char *v);
 ```
 
 - `v` - value of string to create;
 - returned value is pointer to created string.
 
-
 **See also**
-
-- [jerry_api_acquire_string]({{ site.baseurl }}/API#jerry_api_acquire_string)
-- [jerry_api_release_string]({{ site.baseurl }}/API#jerry_api_release_string)
+- [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)
 
 **Example**
-
 ```cpp
 {
-  jerry_api_string_t* string_p = jerry_api_create_string ("abc");
-  // ...
+  jerry_api_string_t *string_p = jerry_api_create_string ("abc");
+
+  ...
+
   jerry_api_release_string (string_p);
 }
 ```
 
+# jerry_api_string_to_char_buffer
+
+**Summary**
+Copy string characters to specified buffer, append zero character at end of the buffer.
+
+**Prototype**
+```cpp
+ssize_t
+jerry_api_string_to_char_buffer (const jerry_api_string_t *string_p,
+                                 char *buffer_p,
+                                 ssize_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 insuficcient) - negative number, which is calculated as negation of buffer size, that is required to hold characters.
+
+**See also**
+- [jerry_api_create_string](#jerry_api_create_string)
+- [jerry_api_value_t](#jerry_api_value_t)
+
+**Example**
+```cpp
+{
+  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
+      ssize_t neg_req_sz = jerry_api_string_to_char_buffer (val.string_p,
+                                                            NULL,
+                                                            0);
+      char *str_buf_p = (char*) malloc (-neg_req_sz);
+
+      // sz would be -neg_req_sz
+      size_t sz = jerry_api_string_to_char_buffer (val.string_p,
+                                                   str_buf_p,
+                                                   -neg_req_sz);
+
+      printf ("%s", str_buf_p);
+
+      free (str_buf_p);
+    }
+
+    jerry_api_release_value (&val);
+  }
+
+  jerry_api_release_object (obj_p);
+}
+```
+
 # 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]({{ site.baseurl }}/API#jerry_api_release_string).
+
+The acquired pointer should be released with [jerry_api_release_string](#jerry_api_release_string).
 
 **Prototype**
-
 ```cpp
-jerry_api_string_t* jerry_api_acquire_string (jerry_api_string_t* string_p);
+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.
 
 **See also**
-- [jerry_api_release_string]({{ site.baseurl }}/API#jerry_api_release_string)
-- [jerry_api_create_string]({{ site.baseurl }}/API#jerry_api_create_string)
+- [jerry_api_release_string](#jerry_api_release_string)
+- [jerry_api_create_string](#jerry_api_create_string)
 
 **Example**
-
 ```cpp
 {
-  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_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
+
+  ... // usage of str_ptr2_p pointer
+
   jerry_api_release_string (str_ptr2_p);
 }
 ```
@@ -278,29 +373,32 @@ jerry_api_string_t* jerry_api_acquire_string (jerry_api_string_t* string_p);
 # jerry_api_release_string
 
 **Summary**
-
 Release specified pointer to the string.
 
 **Prototype**
-
 ```cpp
-void jerry_api_release_string (jerry_api_string_t* string_p);
+void
+jerry_api_release_string (jerry_api_string_t *string_p);
 ```
 
-**See also**
+- `string_p` - pointer to the string.
 
-- [jerry_api_acquire_string]({{ site.baseurl }}/API#jerry_api_acquire_string)
-- [jerry_api_create_string]({{ site.baseurl }}/API#jerry_api_create_string)
+**See also**
+- [jerry_api_acquire_string](#jerry_api_acquire_string)
+- [jerry_api_create_string](#jerry_api_create_string)
 
 **Example**
-
 ```cpp
 {
-  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_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
+
+  ... // usage of str_ptr2_p pointer
+
   jerry_api_release_string (str_ptr2_p);
 }
 ```
@@ -308,15 +406,14 @@ void jerry_api_release_string (jerry_api_string_t* string_p);
 # 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]({{ site.baseurl }}/API#jerry_api_release_object).
+Upon the JavaScript object becomes unused, all pointers to it should be released using [jerry_api_release_object](#jerry_api_release_object).
 
 **Prototype**
-
 ```cpp
-jerry_api_object_t* jerry_api_create_object (const char* v);
+jerry_api_object_t*
+jerry_api_create_object (const char *v);
 ```
 
 - `v` - value of object to create;
@@ -324,16 +421,22 @@ jerry_api_object_t* jerry_api_create_object (const char* v);
 
 
 **See also**
-
-- [jerry_api_acquire_object]({{ site.baseurl }}/API#jerry_api_acquire_object)
-- [jerry_api_release_object]({{ site.baseurl }}/API#jerry_api_release_object)
+- [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)
 
 **Example**
-
 ```cpp
 {
-  jerry_api_object_t* object_p = jerry_api_create_object ("abc");
-  // ...
+  jerry_api_object_t *object_p = jerry_api_create_object ("abc");
+
+  ...
+
   jerry_api_release_object (object_p);
 }
 ```
@@ -342,31 +445,34 @@ jerry_api_object_t* jerry_api_create_object (const char* v);
 
 **Summary**
 Acquire new pointer to the object for usage outside of the engine.
-The acquired pointer should be released with [jerry_api_release_object]({{ site.baseurl }}/API#jerry_api_release_object).
+
+The acquired pointer should be released with [jerry_api_release_object](#jerry_api_release_object).
 
 **Prototype**
-
 ```cpp
-jerry_api_object_t* jerry_api_acquire_object (jerry_api_object_t* object_p);
+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.
 
 **See also**
-
-- [jerry_api_release_object]({{ site.baseurl }}/API#jerry_api_release_object)
-- [jerry_api_create_object]({{ site.baseurl }}/API#jerry_api_create_object)
+- [jerry_api_release_object](#jerry_api_release_object)
+- [jerry_api_create_object](#jerry_api_create_object)
 
 **Example**
-
 ```cpp
 {
-  jerry_api_object_t* obj_ptr1_p = jerry_api_create_object ("abc");
-  jerry_api_object_t* obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p);
-  // ... // usage of both pointers
+  jerry_api_object_t *obj_ptr1_p = jerry_api_create_object ("abc");
+  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
+
+  ... // usage of obj_ptr2_p pointer
+
   jerry_api_release_object (obj_ptr2_p);
 }
 ```
@@ -377,55 +483,327 @@ jerry_api_object_t* jerry_api_acquire_object (jerry_api_object_t* object_p);
 Release specified pointer to the object.
 
 **Prototype**
-
 ```cpp
-void jerry_api_release_object (jerry_api_object_t* object_p);
+void
+jerry_api_release_object (jerry_api_object_t *object_p);
 ```
 
-**See also**
+- `object_p` - pointer to the object.
 
-- [jerry_api_acquire_object]({{ site.baseurl }}/API#jerry_api_acquire_object)
-- [jerry_api_create_object]({{ site.baseurl }}/API#jerry_api_create_object)
+**See also**
+- [jerry_api_acquire_object](#jerry_api_acquire_object)
+- [jerry_api_create_object](#jerry_api_create_object)
 
 **Example**
-
 ```cpp
 {
-  jerry_api_object_t* obj_ptr1_p = jerry_api_create_object ("abc");
-  jerry_api_object_t* obj_ptr2_p = jerry_api_acquire_object (obj_ptr1_p);
-  // ... // usage of both pointers
+  jerry_api_object_t *obj_ptr1_p = jerry_api_create_object ("abc");
+  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
+
+  ... // usage of obj_ptr2_p pointer
+
   jerry_api_release_object (obj_ptr2_p);
 }
 ```
 
+# jerry_api_get_global
+
+**Summary**
+Get the Global object.
+
+**Prototype**
+```cpp
+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.
+
+**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)
+
+**Example**
+```cpp
+{
+  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);
+}
+```
+
+# jerry_api_add_object_field
+
+**Summary**
+Create field (named data property) in an object
+
+**Prototype**
+```cpp
+bool
+jerry_api_add_object_field (jerry_api_object_t *object_p,
+                            const char *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.
+
+**See also**
+- [jerry_api_value_t](#jerry_api_value_t)
+- [jerry_api_create_object](/#jerry_api_create_object)
+
+**Example**
+```cpp
+{
+  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);
+}
+```
+
+# jerry_api_delete_object_field
+
+**Summary**
+Delete field (property) in the specified object
+
+**Prototype**
+```cpp
+bool
+jerry_api_delete_object_field (jerry_api_object_t *object_p,
+                               const char *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.
+
+**See also**
+- [jerry_api_value_t](#jerry_api_value_t)
+- [jerry_api_create_object](/#jerry_api_create_object)
+
+**Example**
+```cpp
+{
+  jerry_api_object_t* obj_p;
+  ... // receive or construct obj_p
+
+  jerry_api_delete_object_field (obj_p, "some_field_name");
+}
+```
+
+# jerry_api_get_object_field_value
+
+**Summary**
+Get value of field (property) in the specified object, i.e. perform [[Get]] operation.
+
+**Prototype**
+```cpp
+bool
+jerry_api_get_object_field_value (jerry_api_object_t *object_p,
+                                  const char *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_value just when it becomes unnecessary.
+
+**See also**
+- [jerry_api_value_t](#jerry_api_value_t)
+- [jerry_api_create_object](/#jerry_api_create_object)
+
+**Example**
+```cpp
+{
+  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);
+  }
+}
+```
+
+# jerry_api_set_object_field_value
+
+**Summary**
+Set value of a field (property) in the specified object, i.e. perform [[Put]] operation.
+
+**Prototype**
+```cpp
+bool
+jerry_api_set_object_field_value (jerry_api_object_t *object_p,
+                                  const char *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.
+
+**See also**
+- [jerry_api_value_t](#jerry_api_value_t)
+- [jerry_api_create_object](/#jerry_api_create_object)
+
+**Example**
+```cpp
+{
+  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);
+}
+```
+
+# jerry_api_get_object_native_handle
+
+**Summary**
+
+Get native handle, previously associated with specified object.
+
+**Prototype**
+```cpp
+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.
+
+**See also**
+- [jerry_api_create_object](/#jerry_api_create_object)
+- [jerry_api_set_object_native_handle](/#jerry_api_set_object_native_handle)
+
+**Example**
+```cpp
+{
+  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);
+}
+```
+
+# 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**
+```cpp
+bool
+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).
+
+**See also**
+- [jerry_api_create_object](/#jerry_api_create_object)
+- [jerry_api_get_object_native_handle](/#jerry_api_get_object_native_handle)
+
+**Example**
+```cpp
+{
+  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);
+}
+```
+
 # jerry_api_is_function
 
 **Summary**
 Check whether the specified object is a function object.
 
 **Prototype**
-
 ```cpp
-bool jerry_api_is_function (const jerry_api_object_t* object_p);
+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.
 
 **See also**
-
-- [jerry_api_value_t]({{ site.baseurl }}/API#jerry_api_value_t)
-- [jerry_api_is_constructor]({{ site.baseurl }}/API#jerry_api_is_constructor)
-- [jerry_api_call_function]({{ site.baseurl }}/API#jerry_api_call_function)
+- [jerry_api_value_t](#jerry_api_value_t)
+- [jerry_api_is_constructor](#jerry_api_is_constructor)
+- [jerry_api_call_function](#jerry_api_call_function)
 
 **Example**
-
 ```cpp
 {
   jerry_api_value_t val;
-  // ... // receiving val
+
+  ... // receiving val
 
   if (val.type == JERRY_API_DATA_TYPE_OBJECT) {
     if (jerry_api_is_function (val.v_object)) {
@@ -441,25 +819,26 @@ bool jerry_api_is_function (const jerry_api_object_t* object_p);
 Check whether the specified object is a constructor function object.
 
 **Prototype**
-
 ```cpp
-bool jerry_api_is_constructor (const jerry_api_object_t* object_p);
+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.
 
 **See also**
-- [jerry_api_value_t]({{ site.baseurl }}/API#jerry_api_value_t)
-- [jerry_api_is_function]({{ site.baseurl }}/API#jerry_api_is_function)
-- [jerry_api_construct_object]({{ site.baseurl }}/API#jerry_api_construct_object)
+- [jerry_api_value_t](#jerry_api_value_t)
+- [jerry_api_is_function](#jerry_api_is_function)
+- [jerry_api_construct_object](#jerry_api_construct_object)
 
 **Example**
-
 ```cpp
 {
   jerry_api_value_t val;
-  // ... // receiving val
+
+  ... // receiving val
+
   if (val.type == JERRY_API_DATA_TYPE_OBJECT) {
     if (jerry_api_is_constructor (val.v_object)) {
       // the object is constructor function object
@@ -474,12 +853,11 @@ bool jerry_api_is_constructor (const jerry_api_object_t* object_p);
 Call function object.
 
 **Prototype**
-
 ```cpp
 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,
+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);
 ```
@@ -492,19 +870,20 @@ jerry_api_call_function (jerry_api_object_t* function_object_p,
   - 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_value]({{ site.baseurl }}/API#jerry_api_release_value) just when it becomes unnecessary.
+ If call was performed successfully, returned value should be freed with [jerry_api_release_value](#jerry_api_release_value) just when it becomes unnecessary.
 
 **See also**
-
-- [jerry_api_is_function]({{ site.baseurl }}/API#jerry_api_is_function)
-- [jerry_api_value_t]({{ site.baseurl }}/API#jerry_api_value_t)
+- [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)
 
 **Example**
-
 ```cpp
 {
   jerry_api_value_t val;
-  // ... // receiving val
+
+  ... // receiving val
+
   if (val.type == JERRY_API_DATA_TYPE_OBJECT) {
     if (jerry_api_is_function (val.v_object)) {
       jerry_api_value_t ret_val;
@@ -514,8 +893,7 @@ If call was performed successfully, returned value should be freed with [jerry_a
                                             &ret_val,
                                             NULL, 0);
 
-      if (is_ok)
-      {
+      if (is_ok) {
         ... // handle return value
 
         jerry_api_release_value (&ret_val);
@@ -524,3 +902,126 @@ If call was performed successfully, returned value should be freed with [jerry_a
   }
 }
 ```
+
+# jerry_api_construct_object
+
+**Summary**
+Construct object invoking specified function object as constructor.
+
+**Prototype**
+```cpp
+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_value|API#jerry_api_release_value]] just when it becomes unnecessary.
+
+**See also**
+ - [jerry_api_is_constructor](#jerry_api_is_constructor)
+ - [jerry_api_value_t](#jerry_api_value_t)
+
+**Example**
+```cpp
+{
+  jerry_api_value_t val;
+
+  ... // receiving val
+
+  if (val.type == JERRY_API_DATA_TYPE_OBJECT) {
+    if (jerry_api_is_constructor (val.v_object)) {
+      jerry_api_value_t ret_val;
+
+      bool is_ok = jerry_api_construct_object (val.v_object,
+                                               &ret_val,
+                                               NULL, 0);
+
+      if (is_ok) {
+        ... // handle return value
+
+        jerry_api_release_value (&ret_val);
+      }
+    }
+  }
+}
+```
+
+# jerry_external_handler_t
+
+**Summary**
+
+The data type represents pointer to call handler of a native function object.
+
+**Structure**
+```cpp
+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**
+```cpp
+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.
+
+**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)
+
+**Example**
+```cpp
+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->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.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);
+}
+```