1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: add version info for types

Browse Source 
Add version info for types in N-API doc.

PR-URL: https://github.com/nodejs/node/pull/27754
Fixes: https://github.com/nodejs/node/issues/27486
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Rich Trott <rtrott@gmail.com>
This commit is contained in:
Michael Dawson 2019-05-17 15:56:28 -04:00 committed by Rich Trott
parent 956e08e6f0
commit dd6481a183
1 changed files with 56 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/api/n-api.md
View File

@ -222,6 +222,10 @@ consumed by the various APIs. These APIs should be treated as opaque,
introspectable only with other N-API calls. introspectable only with other N-API calls.
### napi_status ### napi_status
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
Integral status code indicating the success or failure of a N-API call. Integral status code indicating the success or failure of a N-API call.
Currently, the following status codes are supported. Currently, the following status codes are supported.
```C ```C
@ -251,6 +255,10 @@ If additional information is required upon an API returning a failed status,
it can be obtained by calling `napi_get_last_error_info`. it can be obtained by calling `napi_get_last_error_info`.
### napi_extended_error_info ### napi_extended_error_info
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
```C ```C
typedef struct { typedef struct {
const char* error_message; const char* error_message;
@ -283,12 +291,20 @@ not allowed.
This is an opaque pointer that is used to represent a JavaScript value. This is an opaque pointer that is used to represent a JavaScript value.
### napi_threadsafe_function ### napi_threadsafe_function
<!-- YAML
added: v10.6.0
napiVersion: 4
-->
This is an opaque pointer that represents a JavaScript function which can be This is an opaque pointer that represents a JavaScript function which can be
called asynchronously from multiple threads via called asynchronously from multiple threads via
`napi_call_threadsafe_function()`. `napi_call_threadsafe_function()`.
### napi_threadsafe_function_release_mode ### napi_threadsafe_function_release_mode
<!-- YAML
added: v10.6.0
napiVersion: 4
-->
A value to be given to `napi_release_threadsafe_function()` to indicate whether A value to be given to `napi_release_threadsafe_function()` to indicate whether
the thread-safe function is to be closed immediately (`napi_tsfn_abort`) or the thread-safe function is to be closed immediately (`napi_tsfn_abort`) or
@ -302,6 +318,10 @@ typedef enum {
``` ```
### napi_threadsafe_function_call_mode ### napi_threadsafe_function_call_mode
<!-- YAML
added: v10.6.0
napiVersion: 4
-->
A value to be given to `napi_call_threadsafe_function()` to indicate whether A value to be given to `napi_call_threadsafe_function()` to indicate whether
the call should block whenever the queue associated with the thread-safe the call should block whenever the queue associated with the thread-safe
@ -333,10 +353,18 @@ longer referenced from the current stack frame.
For more details, review the [Object Lifetime Management][]. For more details, review the [Object Lifetime Management][].
#### napi_escapable_handle_scope #### napi_escapable_handle_scope
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
Escapable handle scopes are a special type of handle scope to return values Escapable handle scopes are a special type of handle scope to return values
created within a particular handle scope to a parent scope. created within a particular handle scope to a parent scope.
#### napi_ref #### napi_ref
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
This is the abstraction to use to reference a `napi_value`. This allows for This is the abstraction to use to reference a `napi_value`. This allows for
users to manage the lifetimes of JavaScript values, including defining their users to manage the lifetimes of JavaScript values, including defining their
minimum lifetimes explicitly. minimum lifetimes explicitly.
@ -345,11 +373,19 @@ For more details, review the [Object Lifetime Management][].
### N-API Callback types ### N-API Callback types
#### napi_callback_info #### napi_callback_info
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
Opaque datatype that is passed to a callback function. It can be used for Opaque datatype that is passed to a callback function. It can be used for
getting additional information about the context in which the callback was getting additional information about the context in which the callback was
invoked. invoked.
#### napi_callback #### napi_callback
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
Function pointer type for user-provided native functions which are to be Function pointer type for user-provided native functions which are to be
exposed to JavaScript via N-API. Callback functions should satisfy the exposed to JavaScript via N-API. Callback functions should satisfy the
following signature: following signature:
@ -358,6 +394,10 @@ typedef napi_value (*napi_callback)(napi_env, napi_callback_info);
``` ```
#### napi_finalize #### napi_finalize
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
Function pointer type for add-on provided functions that allow the user to be Function pointer type for add-on provided functions that allow the user to be
notified when externally-owned data is ready to be cleaned up because the notified when externally-owned data is ready to be cleaned up because the
object with which it was associated with, has been garbage-collected. The user object with which it was associated with, has been garbage-collected. The user
@ -372,6 +412,10 @@ typedef void (*napi_finalize)(napi_env env,
``` ```
#### napi_async_execute_callback #### napi_async_execute_callback
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
Function pointer used with functions that support asynchronous Function pointer used with functions that support asynchronous
operations. Callback functions must satisfy the following signature: operations. Callback functions must satisfy the following signature:
@ -385,6 +429,10 @@ JavaScript objects. Most often, any code that needs to make N-API
calls should be made in `napi_async_complete_callback` instead. calls should be made in `napi_async_complete_callback` instead.
#### napi_async_complete_callback #### napi_async_complete_callback
<!-- YAML
added: v8.0.0
napiVersion: 1
-->
Function pointer used with functions that support asynchronous Function pointer used with functions that support asynchronous
operations. Callback functions must satisfy the following signature: operations. Callback functions must satisfy the following signature:
@ -395,6 +443,10 @@ typedef void (*napi_async_complete_callback)(napi_env env,
``` ```
#### napi_threadsafe_function_call_js #### napi_threadsafe_function_call_js
<!-- YAML
added: v10.6.0
napiVersion: 4
-->
Function pointer used with asynchronous thread-safe function calls. The callback Function pointer used with asynchronous thread-safe function calls. The callback
will be called on the main thread. Its purpose is to use a data item arriving will be called on the main thread. Its purpose is to use a data item arriving
@ -460,6 +512,10 @@ In order to retrieve this information [`napi_get_last_error_info`][]
is provided which returns a `napi_extended_error_info` structure. is provided which returns a `napi_extended_error_info` structure.
The format of the `napi_extended_error_info` structure is as follows: The format of the `napi_extended_error_info` structure is as follows:
<!-- YAML
added: v10.6.0
napiVersion: 4
-->
```C ```C
typedef struct napi_extended_error_info { typedef struct napi_extended_error_info {
const char* error_message; const char* error_message;