diff --git a/02.how-to.md b/02.how-to.md index 2537d8f01..0d8ab27e9 100644 --- a/02.how-to.md +++ b/02.how-to.md @@ -35,7 +35,7 @@ These tools are required for development: {% highlight bash %} sudo apt-get install gcc g++ -sudo apt-get install gcc-arm-none-eabi g++-arm-none-eabi +sudo apt-get install gcc-arm-none-eabi sudo apt-get install cmake sudo apt-get install libpcre3 libpcre3-dev sudo apt-get install tcl8.6 tcl8.6-dev tk8.6-dev libboost-all-dev diff --git a/03.api.md b/03.api.md index c5d278e01..069dfd9b4 100644 --- a/03.api.md +++ b/03.api.md @@ -310,7 +310,7 @@ jerry_api_string_to_char_buffer (const jerry_api_string_t * string_p, - `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. + - 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** @@ -441,17 +441,16 @@ Upon the JavaScript object becomes unused, all pointers to it should be released {% highlight cpp %} jerry_api_object_t* -jerry_api_create_object (const char * v); +jerry_api_create_object (); {% endhighlight %} -- `v` - value of object to create; - returned value is pointer to the created object. **Example** {% highlight cpp %} { - jerry_api_object_t * object_p = jerry_api_create_object ("abc"); + jerry_api_object_t * object_p = jerry_api_create_object (); ... @@ -491,7 +490,7 @@ jerry_api_acquire_object (jerry_api_object_t * object_p); {% highlight cpp %} { - jerry_api_object_t * obj_ptr1_p = jerry_api_create_object ("abc"); + 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 @@ -527,7 +526,7 @@ jerry_api_release_object (jerry_api_object_t * object_p); {% highlight cpp %} { - jerry_api_object_t * obj_ptr1_p = jerry_api_create_object ("abc"); + 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 @@ -802,7 +801,7 @@ If native handle or "free" callback were already set for the object, correspondi **Prototype** {% highlight cpp %} -bool +void jerry_api_set_object_native_handle (jerry_api_object_t * object_p, uintptr_t handle, jerry_object_free_callback_t freecb_p); @@ -1099,3 +1098,228 @@ handler (const jerry_api_object_t * function_obj_p, - [jerry_api_is_function](#jerryapiisfunction) - [jerry_api_call_function](#jerryapicallfunction) - [jerry_api_release_object](#jerryapireleaseobject) + +# 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](#jerryapireleaseobject). + +**Prototype** + +{% highlight cpp %} +jerry_api_object_t* +jerry_api_create_array_object (jerry_api_size_t array_size); +{% endhighlight %} + + - `array_size` - size of array; + - returned value is pointer to the created array object. + + **Example** + +{% highlight cpp %} +{ + jerry_api_object_t * array_object_p = jerry_api_create_array_object (10); + + ... + + jerry_api_release_object (array_object_p); +} +{% endhighlight %} + +**See also** + +- [jerry_api_acquire_object](#jerryapiacquireobject) +- [jerry_api_release_object](#jerryapireleaseobject) +- [jerry_api_set_array_index_value](#jerryapisetarrayindexvalue) +- [jerry_api_get_array_index_value](#jerryapigetarrayindexvalue) +- [jerry_api_add_object_field](#jerryapiaddobjectfield) +- [jerry_api_delete_object_field](#jerryapideleteobjectfield) +- [jerry_api_get_object_field_value](#jerryapigetobjectfieldvalue) +- [jerry_api_set_object_field_value](#jerryapisetobjectfieldvalue) +- [jerry_api_get_object_native_handle](#jerryapigetobjectnativehandle) +- [jerry_api_set_object_native_handle](#jerryapisetobjectnativehandle) + +# jerry_api_set_array_index_value + +**Summary** +Set value of an indexed element in the specified array object. + +**Prototype** + +{% highlight cpp %} +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); +{% endhighlight %} + +- `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** + +{% highlight cpp %} +{ + 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); +} +{% endhighlight %} + +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_array_object](#jerryapicreatearrayobject) + +# jerry_api_get_array_index_value + +**Summary** +Get value of an indexed element in the specified array object. + +**Prototype** + +{% highlight cpp %} +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); +{% endhighlight %} + +- `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** + +{% highlight cpp %} +{ + 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' + } +} +{% endhighlight %} + +**See also** + +- [jerry_api_value_t](#jerryapivaluet) +- [jerry_api_create_array_object](#jerryapicreatearrayobject) + +# jerry_api_release_value + +**Summary** +Release specified pointer to the value. + +**Prototype** + +{% highlight cpp %} +void +jerry_api_release_value (jerry_api_value_t * value_p); +{% endhighlight %} + +- `value_p` - pointer to the value. + +**Example** +{% highlight cpp %} +{ + jerry_api_value_t val1; + jerry_api_value_t val2; + + val1.type = JERRY_API_DATA_TYPE_OBJECT; + val1.v_object = jerry_api_create_object (); + + val2.type = JERRY_API_DATA_TYPE_STRING; + val2.v_string = jerry_api_create_string ("abc"); + + ... // usage of val1 + + jerry_api_release_value (&val1); + + ... // usage of val2 + + jerry_api_release_value (&val2); +} +{% endhighlight %} + +**See also** + +- [jerry_api_value_t](#jerryapivaluet) + +# jerry_api_create_error + +**Summary** +Create new JavaScript error object. +it should be throwed inside of handle attached to external function object. + +**Prototype** + +{% highlight cpp %} +jerry_api_object_t* +jerry_api_create_error (jerry_api_error_t error_type, + const jerry_api_char_t * message_p); +{% endhighlight %} + +- `error_type` - error type of object; +- `message_p` - human-readable description of the error; +- returned value is pointer to the created error object. + +**Example** + +{% highlight 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) +{ + 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->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.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); +} +{% endhighlight %} + +**See also** +- [jerry_external_handler_t](#jerryexternalhandlert) +- [jerry_api_is_function](#jerryapiisfunction) +- [jerry_api_call_function](#jerryapicallfunction) +- [jerry_api_release_object](#jerryapireleaseobject) +- [jerry_api_create_external_function](#jerryapicreateexternalfunction)