Add 'type' argument to set/get native handle API (#1711)

Ecma-object have native handle type inside, and binding code could use type info to validate native handle's type. Related issue #1681 JerryScript-DCO-1.0-Signed-off-by: Zidong Jiang zidong.jiang@intel.com
2017-04-10 16:51:37 +08:00
parent 574dff512e
commit e522e740a7
12 changed files with 486 additions and 141 deletions
@@ -167,7 +167,9 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_

 **Summary**

-Native free callback of an object
+**Deprecated: Please use jerry_object_native_free_callback_t instead.**
+
+Native free callback of an object.

 **Prototype**

@@ -175,6 +177,34 @@ Native free callback of an object
 typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p);
 ```

+## jerry_object_native_free_callback_t
+
+**Summary**
+
+Native free callback of an object. It is used in jerry_object_native_info_t.
+
+**Prototype**
+
+```c
+typedef void (*jerry_object_native_free_callback_t) (void *native_p);
+```
+
+## jerry_object_native_info_t
+
+**Summary**
+
+The type infomation of the native pointer.
+It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed.
+
+**Prototype**
+
+```c
+typedef struct
+{
+  jerry_object_native_free_callback_t free_cb;
+} jerry_object_native_info_t;
+```
+
 ## jerry_object_property_foreach_t

 **Summary**
@@ -3173,6 +3203,8 @@ jerry_set_prototype (const jerry_value_t obj_val,

 **Summary**

+**Deprecated: Please use jerry_get_object_native_pointer instead.**
+
 Get native handle, previously associated with specified object.

 **Prototype**
@@ -3211,12 +3243,16 @@ jerry_get_object_native_handle (const jerry_value_t obj_val,

 - [jerry_create_object](#jerry_create_object)
 - [jerry_set_object_native_handle](#jerry_set_object_native_handle)
+- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
+

 ## jerry_set_object_native_handle

 **Summary**

-Set native handle and an optional free callback for the specified object
+**Deprecated: Please use jerry_set_object_native_pointer instead.**
+
+Set native handle and an optional free callback for the specified object.

 *Note*: If native handle was already set for the object, its value is updated.

@@ -3260,6 +3296,146 @@ jerry_set_object_native_handle (const jerry_value_t obj_val,

 - [jerry_create_object](#jerry_create_object)
 - [jerry_get_object_native_handle](#jerry_get_object_native_handle)
+- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
+
+
+## jerry_get_object_native_pointer
+
+**Summary**
+
+Get native pointer and its type information.
+The pointer and the type information are previously associated with the object by jerry_set_object_native_pointer.
+Users can check the pointer's type before processing it.
+
+**Prototype**
+
+```c
+bool
+jerry_get_object_native_pointer (const jerry_value_t obj_val,
+                                 void **out_native_p,
+                                 const jerry_object_native_info_t **out_info_p)
+```
+
+- `obj_val` - object value to get native pointer from.
+- `out_native_p` - native pointer (output parameter).
+- `out_info_p` - native pointer's type infomation (output parameter).
+- return value
+  - true, if there is native pointer associated with the object
+  - false, otherwise
+
+**Example**
+
+```c
+static void native_freecb (uintptr_t native_p)
+{
+  ... // free the native pointer
+}
+
+static const jerry_object_native_info_t type_info =
+{
+  .free_cb = native_freecb
+};
+
+{
+  jerry_value_t object;
+  uintptr_t native_set;
+
+  ... // receive or construct object and native_set value
+
+  jerry_set_object_native_pointer (object, native_set, &type_info);
+
+  ...
+
+  uintptr_t native_get;
+  const jerry_object_native_info_t *type_get_p;
+  bool is_there_associated_native = jerry_get_object_native_pointer (object, &native_get, &type_get_p);
+
+  if (is_there_associated_native)
+  {
+    if (out_info_p == &type_info)
+    {
+      ... // the type of object's native pointer is expected, and then process the native pointer.
+    }
+  }
+}
+```
+
+**See also**
+
+- [jerry_create_object](#jerry_create_object)
+- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
+- [jerry_object_native_info_t](#jerry_object_native_info_t)
+
+
+## jerry_set_object_native_pointer
+
+**Summary**
+
+Set native pointer and an optional type information for the specified object.
+You can get them by calling jerry_get_object_native_pointer later.
+
+*Note*: If native pointer was already set for the object, its value is updated.
+
+*Note*: If a non-NULL free callback is specified in the native type information,
+        it will be called by the garbage collector when the object is freed.
+        The type info is always overwrites the previous value, so passing
+        a NULL value deletes the current type info.
+
+**Prototype**
+
+```c
+bool
+jerry_set_object_native_pointer (const jerry_value_t obj_val,
+                                 void *native_p,
+                                 const jerry_object_native_info_t *info_p)
+```
+
+- `obj_val` - object to set native pointer in.
+- `native_p` - native pointer.
+- `info_p` - native pointer's type infomation or NULL.
+
+**Example**
+
+```c
+static void native_freecb (uintptr_t native_p)
+{
+  ... // free the native pointer
+}
+
+static const jerry_object_native_info_t type_info =
+{
+  .free_cb = native_freecb
+};
+
+{
+  jerry_value_t object;
+  uintptr_t native_set;
+
+  ... // receive or construct object and native_set value
+
+  jerry_set_object_native_pointer (object, native_set, &type_info);
+
+  ...
+
+  uintptr_t native_get;
+  const jerry_object_native_info_t *type_get_p;
+  bool is_there_associated_native = jerry_get_object_native_pointer (object, &native_get, &type_get_p);
+
+  if (is_there_associated_native)
+  {
+    if (out_info_p == &type_info)
+    {
+      ... // the type of object's native pointer is expected, and then process the native pointer.
+    }
+  }
+}
+```
+
+**See also**
+
+- [jerry_create_object](#jerry_create_object)
+- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
+- [jerry_object_native_info_t](#jerry_object_native_info_t)


 ## jerry_foreach_object_property