n-api: restrict exports by version
* Move `napi_get_uv_event_loop` into the `NAPI_VERSION >= 2` section * Move `napi_open_callback_scope`, `napi_close_callback_scope`, `napi_fatal_exception`, `napi_add_env_cleanup_hook`, and `napi_remove_env_cleanup_hook` into the `NAPI_VERSION >= 3` section * Added a missing `added` property to `napi_get_uv_event_loop` in the docs * Added a `napiVersion` property to the docs and updated the parser and generator to use it. * Added usage documentation PR-URL: https://github.com/nodejs/node/pull/19962 Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
This commit is contained in:
Kyle Farnung
parent
a64b2f2b94
commit
8476053c13
162
doc/api/n-api.md
162
doc/api/n-api.md
@ -42,6 +42,8 @@ for the N-API C based functions exported by Node.js. These wrappers are not
|
||||
part of N-API, nor will they be maintained as part of Node.js. One such
|
||||
example is: [node-addon-api](https://github.com/nodejs/node-addon-api).
|
||||
|
||||
## Usage
|
||||
|
||||
In order to use the N-API functions, include the file
|
||||
[`node_api.h`](https://github.com/nodejs/node/blob/master/src/node_api.h)
|
||||
which is located in the src directory in the node development tree:
|
||||
@ -50,6 +52,41 @@ which is located in the src directory in the node development tree:
|
||||
#include <node_api.h>
|
||||
```
|
||||
|
||||
This will opt into the default `NAPI_VERSION` for the given release of Node.js.
|
||||
In order to ensure compatibility with specific versions of N-API, the version
|
||||
can be specified explicitly when including the header:
|
||||
|
||||
```C
|
||||
#define NAPI_VERSION 3
|
||||
#include <node_api.h>
|
||||
```
|
||||
|
||||
This restricts the N-API surface to just the functionality that was available in
|
||||
the specified (and earlier) versions.
|
||||
|
||||
Some of the N-API surface is considered experimental and requires explicit
|
||||
opt-in to access those APIs:
|
||||
|
||||
```C
|
||||
#define NAPI_EXPERIMENTAL
|
||||
#include <node_api.h>
|
||||
```
|
||||
|
||||
In this case the entire API surface, including any experimental APIs, will be
|
||||
available to the module code.
|
||||
|
||||
## N-API Version Matrix
|
||||
|
||||
| | 1 | 2 | 3 |
|
||||
|:-----:|:-------:|:--------:|:--------:|
|
||||
| v4.x | | | |
|
||||
| v6.x | | | v6.14.2* |
|
||||
| v8.x | v8.0.0* | v8.10.0* | |
|
||||
| v9.x | v9.0.0* | v9.3.0* | v9.11.0* |
|
||||
| v10.x | | | v10.0.0 |
|
||||
|
||||
\* Indicates that the N-API version was released as experimental
|
||||
|
||||
## Basic N-API Data Types
|
||||
|
||||
N-API exposes the following fundamental datatypes as abstractions that are
|
||||
@ -326,6 +363,7 @@ logging purposes.
|
||||
#### napi_get_last_error_info
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status
|
||||
@ -424,6 +462,7 @@ TypeError [ERR_ERROR_1]
|
||||
#### napi_throw
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);
|
||||
@ -438,6 +477,7 @@ This API throws the JavaScript value provided.
|
||||
#### napi_throw_error
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
|
||||
@ -456,6 +496,7 @@ This API throws a JavaScript `Error` with the text provided.
|
||||
#### napi_throw_type_error
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
|
||||
@ -474,6 +515,7 @@ This API throws a JavaScript `TypeError` with the text provided.
|
||||
#### napi_throw_range_error
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
|
||||
@ -492,6 +534,7 @@ This API throws a JavaScript `RangeError` with the text provided.
|
||||
#### napi_is_error
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_is_error(napi_env env,
|
||||
@ -510,6 +553,7 @@ This API queries a `napi_value` to check if it represents an error object.
|
||||
#### napi_create_error
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_create_error(napi_env env,
|
||||
@ -531,6 +575,7 @@ This API returns a JavaScript `Error` with the text provided.
|
||||
#### napi_create_type_error
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
|
||||
@ -552,6 +597,7 @@ This API returns a JavaScript `TypeError` with the text provided.
|
||||
#### napi_create_range_error
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
|
||||
@ -573,6 +619,7 @@ This API returns a JavaScript `RangeError` with the text provided.
|
||||
#### napi_get_and_clear_last_exception
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_and_clear_last_exception(napi_env env,
|
||||
@ -591,6 +638,7 @@ This API can be called even if there is a pending JavaScript exception.
|
||||
#### napi_is_exception_pending
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_is_exception_pending(napi_env env, bool* result);
|
||||
@ -608,7 +656,9 @@ This API can be called even if there is a pending JavaScript exception.
|
||||
#### napi_fatal_exception
|
||||
<!-- YAML
|
||||
added: v9.10.0
|
||||
napiVersion: 3
|
||||
-->
|
||||
|
||||
```C
|
||||
napi_status napi_fatal_exception(napi_env env, napi_value err);
|
||||
```
|
||||
@ -627,6 +677,7 @@ thrown to immediately terminate the process.
|
||||
#### napi_fatal_error
|
||||
<!-- YAML
|
||||
added: v8.2.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_NO_RETURN void napi_fatal_error(const char* location,
|
||||
@ -740,6 +791,7 @@ can only be called once.
|
||||
#### napi_open_handle_scope
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
|
||||
@ -755,6 +807,7 @@ This API open a new scope.
|
||||
#### napi_close_handle_scope
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
|
||||
@ -773,6 +826,7 @@ This API can be called even if there is a pending JavaScript exception.
|
||||
#### napi_open_escapable_handle_scope
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status
|
||||
@ -790,6 +844,7 @@ to the outer scope.
|
||||
#### napi_close_escapable_handle_scope
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status
|
||||
@ -809,6 +864,7 @@ This API can be called even if there is a pending JavaScript exception.
|
||||
#### napi_escape_handle
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_escape_handle(napi_env env,
|
||||
@ -874,6 +930,7 @@ individual count.
|
||||
#### napi_create_reference
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
|
||||
@ -896,6 +953,7 @@ to the `Object` passed in.
|
||||
#### napi_delete_reference
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);
|
||||
@ -913,6 +971,7 @@ This API can be called even if there is a pending JavaScript exception.
|
||||
#### napi_reference_ref
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
|
||||
@ -931,6 +990,7 @@ passed in and returns the resulting reference count.
|
||||
#### napi_reference_unref
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
|
||||
@ -949,6 +1009,7 @@ passed in and returns the resulting reference count.
|
||||
#### napi_get_reference_value
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
|
||||
@ -982,7 +1043,9 @@ should be freed up.
|
||||
#### napi_add_env_cleanup_hook
|
||||
<!-- YAML
|
||||
added: v10.2.0
|
||||
napiVersion: 3
|
||||
-->
|
||||
|
||||
```C
|
||||
NODE_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env,
|
||||
void (*fun)(void* arg),
|
||||
@ -1007,7 +1070,9 @@ is being torn down anyway.
|
||||
#### napi_remove_env_cleanup_hook
|
||||
<!-- YAML
|
||||
added: v10.2.0
|
||||
napiVersion: 3
|
||||
-->
|
||||
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env,
|
||||
void (*fun)(void* arg),
|
||||
@ -1196,6 +1261,7 @@ Elements of this enum correspond to
|
||||
#### napi_create_array
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_array(napi_env env, napi_value* result)
|
||||
@ -1213,6 +1279,7 @@ JavaScript arrays are described in
|
||||
#### napi_create_array_with_length
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_array_with_length(napi_env env,
|
||||
@ -1241,6 +1308,7 @@ JavaScript arrays are described in
|
||||
#### napi_create_arraybuffer
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_arraybuffer(napi_env env,
|
||||
@ -1272,6 +1340,7 @@ JavaScript `ArrayBuffer` objects are described in
|
||||
#### napi_create_buffer
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_buffer(napi_env env,
|
||||
@ -1293,6 +1362,7 @@ fully-supported data structure, in most cases using a `TypedArray` will suffice.
|
||||
#### napi_create_buffer_copy
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_buffer_copy(napi_env env,
|
||||
@ -1318,6 +1388,7 @@ structure, in most cases using a `TypedArray` will suffice.
|
||||
#### napi_create_external
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_external(napi_env env,
|
||||
@ -1350,6 +1421,7 @@ an external value yields `napi_external`.
|
||||
#### napi_create_external_arraybuffer
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status
|
||||
@ -1384,6 +1456,7 @@ JavaScript `ArrayBuffer`s are described in
|
||||
#### napi_create_external_buffer
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_external_buffer(napi_env env,
|
||||
@ -1415,6 +1488,7 @@ For Node.js >=4 `Buffers` are `Uint8Array`s.
|
||||
#### napi_create_function
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_function(napi_env env,
|
||||
@ -1448,6 +1522,7 @@ of the ECMAScript Language Specification.
|
||||
#### napi_create_object
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_object(napi_env env, napi_value* result)
|
||||
@ -1468,6 +1543,7 @@ ECMAScript Language Specification.
|
||||
#### napi_create_symbol
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_symbol(napi_env env,
|
||||
@ -1491,6 +1567,7 @@ of the ECMAScript Language Specification.
|
||||
#### napi_create_typedarray
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_typedarray(napi_env env,
|
||||
@ -1526,6 +1603,7 @@ JavaScript `TypedArray` objects are described in
|
||||
#### napi_create_dataview
|
||||
<!-- YAML
|
||||
added: v8.3.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
|
||||
```C
|
||||
@ -1560,6 +1638,7 @@ JavaScript `DataView` objects are described in
|
||||
#### napi_create_int32
|
||||
<!-- YAML
|
||||
added: v8.4.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)
|
||||
@ -1580,6 +1659,7 @@ The JavaScript `Number` type is described in
|
||||
#### napi_create_uint32
|
||||
<!-- YAML
|
||||
added: v8.4.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)
|
||||
@ -1600,6 +1680,7 @@ The JavaScript `Number` type is described in
|
||||
#### napi_create_int64
|
||||
<!-- YAML
|
||||
added: v8.4.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)
|
||||
@ -1626,6 +1707,7 @@ outside the range of
|
||||
#### napi_create_double
|
||||
<!-- YAML
|
||||
added: v8.4.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_double(napi_env env, double value, napi_value* result)
|
||||
@ -1646,6 +1728,7 @@ The JavaScript `Number` type is described in
|
||||
#### napi_create_string_latin1
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_string_latin1(napi_env env,
|
||||
@ -1671,6 +1754,7 @@ The JavaScript `String` type is described in
|
||||
#### napi_create_string_utf16
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_string_utf16(napi_env env,
|
||||
@ -1696,6 +1780,7 @@ The JavaScript `String` type is described in
|
||||
#### napi_create_string_utf8
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_string_utf8(napi_env env,
|
||||
@ -1722,6 +1807,7 @@ The JavaScript `String` type is described in
|
||||
#### napi_get_array_length
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_array_length(napi_env env,
|
||||
@ -1745,6 +1831,7 @@ of the ECMAScript Language Specification.
|
||||
#### napi_get_arraybuffer_info
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_arraybuffer_info(napi_env env,
|
||||
@ -1774,6 +1861,7 @@ trigger a GC.
|
||||
#### napi_get_buffer_info
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_buffer_info(napi_env env,
|
||||
@ -1798,6 +1886,7 @@ lifetime is not guaranteed if it's managed by the VM.
|
||||
#### napi_get_prototype
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_prototype(napi_env env,
|
||||
@ -1816,6 +1905,7 @@ Returns `napi_ok` if the API succeeded.
|
||||
#### napi_get_typedarray_info
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_typedarray_info(napi_env env,
|
||||
@ -1852,6 +1942,7 @@ is managed by the VM.
|
||||
#### napi_get_dataview_info
|
||||
<!-- YAML
|
||||
added: v8.3.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
|
||||
```C
|
||||
@ -1879,6 +1970,7 @@ This API returns various properties of a `DataView`.
|
||||
#### napi_get_value_bool
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)
|
||||
@ -1898,6 +1990,7 @@ This API returns the C boolean primitive equivalent of the given JavaScript
|
||||
#### napi_get_value_double
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_double(napi_env env,
|
||||
@ -1919,6 +2012,7 @@ This API returns the C double primitive equivalent of the given JavaScript
|
||||
#### napi_get_value_external
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_external(napi_env env,
|
||||
@ -1939,6 +2033,7 @@ This API retrieves the external data pointer that was previously passed to
|
||||
#### napi_get_value_int32
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_int32(napi_env env,
|
||||
@ -1967,6 +2062,7 @@ result to zero.
|
||||
#### napi_get_value_int64
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_int64(napi_env env,
|
||||
@ -1997,6 +2093,7 @@ result to zero.
|
||||
#### napi_get_value_string_latin1
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_string_latin1(napi_env env,
|
||||
@ -2024,6 +2121,7 @@ in.
|
||||
#### napi_get_value_string_utf8
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_string_utf8(napi_env env,
|
||||
@ -2050,6 +2148,7 @@ This API returns the UTF8-encoded string corresponding the value passed in.
|
||||
#### napi_get_value_string_utf16
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_string_utf16(napi_env env,
|
||||
@ -2076,6 +2175,7 @@ This API returns the UTF16-encoded string corresponding the value passed in.
|
||||
#### napi_get_value_uint32
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_value_uint32(napi_env env,
|
||||
@ -2098,6 +2198,7 @@ This API returns the C primitive equivalent of the given `napi_value` as a
|
||||
#### napi_get_boolean
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)
|
||||
@ -2116,6 +2217,7 @@ represent the given boolean value.
|
||||
#### napi_get_global
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_global(napi_env env, napi_value* result)
|
||||
@ -2131,6 +2233,7 @@ This API returns the `global` object.
|
||||
#### napi_get_null
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_null(napi_env env, napi_value* result)
|
||||
@ -2146,6 +2249,7 @@ This API returns the `null` object.
|
||||
#### napi_get_undefined
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_undefined(napi_env env, napi_value* result)
|
||||
@ -2174,6 +2278,7 @@ These APIs support doing one of the following:
|
||||
### napi_coerce_to_bool
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_coerce_to_bool(napi_env env,
|
||||
@ -2195,6 +2300,7 @@ This API can be re-entrant if getters are defined on the passed-in `Object`.
|
||||
### napi_coerce_to_number
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_coerce_to_number(napi_env env,
|
||||
@ -2216,6 +2322,7 @@ This API can be re-entrant if getters are defined on the passed-in `Object`.
|
||||
### napi_coerce_to_object
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_coerce_to_object(napi_env env,
|
||||
@ -2237,6 +2344,7 @@ This API can be re-entrant if getters are defined on the passed-in `Object`.
|
||||
### napi_coerce_to_string
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_coerce_to_string(napi_env env,
|
||||
@ -2258,6 +2366,7 @@ This API can be re-entrant if getters are defined on the passed-in `Object`.
|
||||
### napi_typeof
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)
|
||||
@ -2279,6 +2388,7 @@ If `value` has a type that is invalid, an error is returned.
|
||||
### napi_instanceof
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_instanceof(napi_env env,
|
||||
@ -2304,6 +2414,7 @@ of the ECMAScript Language Specification.
|
||||
### napi_is_array
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_is_array(napi_env env, napi_value value, bool* result)
|
||||
@ -2322,6 +2433,7 @@ of the ECMAScript Language Specification.
|
||||
### napi_is_arraybuffer
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)
|
||||
@ -2338,6 +2450,7 @@ This API checks if the `Object` passed in is an array buffer.
|
||||
### napi_is_buffer
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)
|
||||
@ -2355,6 +2468,7 @@ This API checks if the `Object` passed in is a buffer.
|
||||
### napi_is_error
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_is_error(napi_env env, napi_value value, bool* result)
|
||||
@ -2371,6 +2485,7 @@ This API checks if the `Object` passed in is an `Error`.
|
||||
### napi_is_typedarray
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)
|
||||
@ -2387,6 +2502,7 @@ This API checks if the `Object` passed in is a typed array.
|
||||
### napi_is_dataview
|
||||
<!-- YAML
|
||||
added: v8.3.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
|
||||
```C
|
||||
@ -2404,6 +2520,7 @@ This API checks if the `Object` passed in is a `DataView`.
|
||||
### napi_strict_equals
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_strict_equals(napi_env env,
|
||||
@ -2636,6 +2753,7 @@ this function is invoked.
|
||||
#### napi_get_property_names
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_property_names(napi_env env,
|
||||
@ -2659,6 +2777,7 @@ included.
|
||||
#### napi_set_property
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_set_property(napi_env env,
|
||||
@ -2679,6 +2798,7 @@ This API set a property on the `Object` passed in.
|
||||
#### napi_get_property
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_property(napi_env env,
|
||||
@ -2699,6 +2819,7 @@ This API gets the requested property from the `Object` passed in.
|
||||
#### napi_has_property
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_has_property(napi_env env,
|
||||
@ -2719,6 +2840,7 @@ This API checks if the `Object` passed in has the named property.
|
||||
#### napi_delete_property
|
||||
<!-- YAML
|
||||
added: v8.2.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_delete_property(napi_env env,
|
||||
@ -2740,6 +2862,7 @@ This API attempts to delete the `key` own property from `object`.
|
||||
#### napi_has_own_property
|
||||
<!-- YAML
|
||||
added: v8.2.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_has_own_property(napi_env env,
|
||||
@ -2762,6 +2885,7 @@ any conversion between data types.
|
||||
#### napi_set_named_property
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_set_named_property(napi_env env,
|
||||
@ -2783,6 +2907,7 @@ created from the string passed in as `utf8Name`.
|
||||
#### napi_get_named_property
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_named_property(napi_env env,
|
||||
@ -2804,6 +2929,7 @@ created from the string passed in as `utf8Name`.
|
||||
#### napi_has_named_property
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_has_named_property(napi_env env,
|
||||
@ -2825,6 +2951,7 @@ created from the string passed in as `utf8Name`.
|
||||
#### napi_set_element
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_set_element(napi_env env,
|
||||
@ -2845,6 +2972,7 @@ This API sets and element on the `Object` passed in.
|
||||
#### napi_get_element
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_element(napi_env env,
|
||||
@ -2865,6 +2993,7 @@ This API gets the element at the requested index.
|
||||
#### napi_has_element
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_has_element(napi_env env,
|
||||
@ -2886,6 +3015,7 @@ requested index.
|
||||
#### napi_delete_element
|
||||
<!-- YAML
|
||||
added: v8.2.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_delete_element(napi_env env,
|
||||
@ -2907,6 +3037,7 @@ This API attempts to delete the specified `index` from `object`.
|
||||
#### napi_define_properties
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_define_properties(napi_env env,
|
||||
@ -2950,6 +3081,7 @@ function.
|
||||
### napi_call_function
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_call_function(napi_env env,
|
||||
@ -3016,6 +3148,7 @@ if (status != napi_ok) return;
|
||||
### napi_create_function
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_function(napi_env env,
|
||||
@ -3083,6 +3216,7 @@ responsible for creating the `.node` file.
|
||||
### napi_get_cb_info
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_cb_info(napi_env env,
|
||||
@ -3113,6 +3247,7 @@ call like the arguments and the `this` pointer from a given callback info.
|
||||
### napi_get_new_target
|
||||
<!-- YAML
|
||||
added: v8.6.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_new_target(napi_env env,
|
||||
@ -3132,6 +3267,7 @@ callback is not a constructor call, the result is `NULL`.
|
||||
### napi_new_instance
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_new_instance(napi_env env,
|
||||
@ -3227,6 +3363,7 @@ The reference must be freed once it is no longer needed.
|
||||
### napi_define_class
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_define_class(napi_env env,
|
||||
@ -3283,6 +3420,7 @@ reference count is kept >= 1.
|
||||
### napi_wrap
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_wrap(napi_env env,
|
||||
@ -3343,6 +3481,7 @@ first.
|
||||
### napi_unwrap
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_unwrap(napi_env env,
|
||||
@ -3368,6 +3507,7 @@ then by calling `napi_unwrap()` on the wrapper object.
|
||||
### napi_remove_wrap
|
||||
<!-- YAML
|
||||
added: v8.5.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_remove_wrap(napi_env env,
|
||||
@ -3444,6 +3584,7 @@ callback invocation, even when it was cancelled.
|
||||
### napi_create_async_work
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
changes:
|
||||
- version: v8.6.0
|
||||
pr-url: https://github.com/nodejs/node/pull/14697
|
||||
@ -3491,6 +3632,7 @@ the [`async_hooks` documentation][async_hooks `type`] for more information.
|
||||
### napi_delete_async_work
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_delete_async_work(napi_env env,
|
||||
@ -3509,6 +3651,7 @@ This API can be called even if there is a pending JavaScript exception.
|
||||
### napi_queue_async_work
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_queue_async_work(napi_env env,
|
||||
@ -3526,6 +3669,7 @@ for execution.
|
||||
### napi_cancel_async_work
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_cancel_async_work(napi_env env,
|
||||
@ -3555,6 +3699,7 @@ the runtime.
|
||||
### napi_async_init
|
||||
<!-- YAML
|
||||
added: v8.6.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_async_init(napi_env env,
|
||||
@ -3576,6 +3721,7 @@ Returns `napi_ok` if the API succeeded.
|
||||
### napi_async_destroy
|
||||
<!-- YAML
|
||||
added: v8.6.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_async_destroy(napi_env env,
|
||||
@ -3592,6 +3738,7 @@ This API can be called even if there is a pending JavaScript exception.
|
||||
### napi_make_callback
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
changes:
|
||||
- version: v8.6.0
|
||||
description: Added `async_context` parameter.
|
||||
@ -3638,6 +3785,7 @@ may be required when implementing custom async behavior that does not use
|
||||
### napi_open_callback_scope
|
||||
<!-- YAML
|
||||
added: v9.6.0
|
||||
napiVersion: 3
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
|
||||
@ -3663,6 +3811,7 @@ the required scope.
|
||||
### napi_close_callback_scope
|
||||
<!-- YAML
|
||||
added: v9.6.0
|
||||
napiVersion: 3
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
|
||||
@ -3678,6 +3827,7 @@ This API can be called even if there is a pending JavaScript exception.
|
||||
### napi_get_node_version
|
||||
<!-- YAML
|
||||
added: v8.4.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
|
||||
```C
|
||||
@ -3706,6 +3856,7 @@ The returned buffer is statically allocated and does not need to be freed.
|
||||
### napi_get_version
|
||||
<!-- YAML
|
||||
added: v8.0.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_get_version(napi_env env,
|
||||
@ -3736,6 +3887,7 @@ support it:
|
||||
### napi_adjust_external_memory
|
||||
<!-- YAML
|
||||
added: v8.5.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env,
|
||||
@ -3815,6 +3967,7 @@ deferred = NULL;
|
||||
### napi_create_promise
|
||||
<!-- YAML
|
||||
added: v8.5.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_create_promise(napi_env env,
|
||||
@ -3835,6 +3988,7 @@ This API creates a deferred object and a JavaScript promise.
|
||||
### napi_resolve_deferred
|
||||
<!-- YAML
|
||||
added: v8.5.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_resolve_deferred(napi_env env,
|
||||
@ -3858,6 +4012,7 @@ The deferred object is freed upon successful completion.
|
||||
### napi_reject_deferred
|
||||
<!-- YAML
|
||||
added: v8.5.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_reject_deferred(napi_env env,
|
||||
@ -3881,6 +4036,7 @@ The deferred object is freed upon successful completion.
|
||||
### napi_is_promise
|
||||
<!-- YAML
|
||||
added: v8.5.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
napi_status napi_is_promise(napi_env env,
|
||||
@ -3901,6 +4057,7 @@ underlying JavaScript engine.
|
||||
### napi_run_script
|
||||
<!-- YAML
|
||||
added: v8.5.0
|
||||
napiVersion: 1
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_run_script(napi_env env,
|
||||
@ -3919,7 +4076,10 @@ a specific `napi_env`.
|
||||
|
||||
### napi_get_uv_event_loop
|
||||
<!-- YAML
|
||||
added: v9.3.0
|
||||
added:
|
||||
- v8.10.0
|
||||
- v9.3.0
|
||||
napiVersion: 2
|
||||
-->
|
||||
```C
|
||||
NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env,
|
||||
|
||||
@ -7,6 +7,16 @@
|
||||
|
||||
struct uv_loop_s; // Forward declaration.
|
||||
|
||||
#ifndef NAPI_VERSION
|
||||
#ifdef NAPI_EXPERIMENTAL
|
||||
// Use INT_MAX, this should only be consumed by the pre-processor anyway.
|
||||
#define NAPI_VERSION 2147483647
|
||||
#else
|
||||
// The baseline version for N-API
|
||||
#define NAPI_VERSION 3
|
||||
#endif
|
||||
#endif
|
||||
|
||||
#ifdef _WIN32
|
||||
#ifdef BUILDING_NODE_EXTENSION
|
||||
#ifdef EXTERNAL_NAPI
|
||||
@ -118,19 +128,10 @@ EXTERN_C_START
|
||||
|
||||
NAPI_EXTERN void napi_module_register(napi_module* mod);
|
||||
|
||||
NAPI_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env,
|
||||
void (*fun)(void* arg),
|
||||
void* arg);
|
||||
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env,
|
||||
void (*fun)(void* arg),
|
||||
void* arg);
|
||||
|
||||
NAPI_EXTERN napi_status
|
||||
napi_get_last_error_info(napi_env env,
|
||||
const napi_extended_error_info** result);
|
||||
|
||||
NAPI_EXTERN napi_status napi_fatal_exception(napi_env env, napi_value err);
|
||||
|
||||
NAPI_EXTERN NAPI_NO_RETURN void napi_fatal_error(const char* location,
|
||||
size_t location_len,
|
||||
const char* message,
|
||||
@ -443,14 +444,6 @@ NAPI_EXTERN napi_status napi_escape_handle(napi_env env,
|
||||
napi_value escapee,
|
||||
napi_value* result);
|
||||
|
||||
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
|
||||
napi_value resource_object,
|
||||
napi_async_context context,
|
||||
napi_callback_scope* result);
|
||||
|
||||
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
|
||||
napi_callback_scope scope);
|
||||
|
||||
// Methods to support error handling
|
||||
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);
|
||||
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
|
||||
@ -610,11 +603,38 @@ NAPI_EXTERN napi_status napi_run_script(napi_env env,
|
||||
napi_value script,
|
||||
napi_value* result);
|
||||
|
||||
#if NAPI_VERSION >= 2
|
||||
|
||||
// Return the current libuv event loop for a given environment
|
||||
NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env,
|
||||
struct uv_loop_s** loop);
|
||||
|
||||
#endif // NAPI_VERSION >= 2
|
||||
|
||||
#if NAPI_VERSION >= 3
|
||||
|
||||
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
|
||||
napi_value resource_object,
|
||||
napi_async_context context,
|
||||
napi_callback_scope* result);
|
||||
|
||||
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
|
||||
napi_callback_scope scope);
|
||||
|
||||
NAPI_EXTERN napi_status napi_fatal_exception(napi_env env, napi_value err);
|
||||
|
||||
NAPI_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env,
|
||||
void (*fun)(void* arg),
|
||||
void* arg);
|
||||
|
||||
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env,
|
||||
void (*fun)(void* arg),
|
||||
void* arg);
|
||||
|
||||
#endif // NAPI_VERSION >= 3
|
||||
|
||||
#ifdef NAPI_EXPERIMENTAL
|
||||
|
||||
// Calling into JS from other threads
|
||||
NAPI_EXTERN napi_status
|
||||
napi_create_threadsafe_function(napi_env env,
|
||||
@ -652,6 +672,7 @@ NAPI_EXTERN napi_status
|
||||
napi_ref_threadsafe_function(napi_env env, napi_threadsafe_function func);
|
||||
|
||||
#endif // NAPI_EXPERIMENTAL
|
||||
|
||||
EXTERN_C_END
|
||||
|
||||
#endif // SRC_NODE_API_H_
|
||||
|
||||
@ -25,6 +25,10 @@ function extractAndParseYAML(text) {
|
||||
meta.added = arrify(meta.added);
|
||||
}
|
||||
|
||||
if (meta.napiVersion) {
|
||||
meta.napiVersion = arrify(meta.napiVersion);
|
||||
}
|
||||
|
||||
if (meta.deprecated) {
|
||||
// Treat deprecated like added for consistency.
|
||||
meta.deprecated = arrify(meta.deprecated);
|
||||
|
||||
@ -261,6 +261,10 @@ function parseYAML(text) {
|
||||
html += `${added.description}${deprecated.description}\n`;
|
||||
}
|
||||
|
||||
if (meta.napiVersion) {
|
||||
html += `<span>N-API version: ${meta.napiVersion.join(', ')}</span>\n`;
|
||||
}
|
||||
|
||||
html += '</div>';
|
||||
return html;
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user