From dd6481a183d38c7b48864c558ca5383164825b01 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 17 May 2019 15:56:28 -0400 Subject: [PATCH] doc: add version info for types 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 Reviewed-By: Rich Trott --- doc/api/n-api.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 7da89152c252a9..904ee88875d104 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -222,6 +222,10 @@ consumed by the various APIs. These APIs should be treated as opaque, introspectable only with other N-API calls. ### napi_status + Integral status code indicating the success or failure of a N-API call. Currently, the following status codes are supported. ```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`. ### napi_extended_error_info + ```C typedef struct { const char* error_message; @@ -283,12 +291,20 @@ not allowed. This is an opaque pointer that is used to represent a JavaScript value. ### napi_threadsafe_function + This is an opaque pointer that represents a JavaScript function which can be called asynchronously from multiple threads via `napi_call_threadsafe_function()`. ### napi_threadsafe_function_release_mode + 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 @@ -302,6 +318,10 @@ typedef enum { ``` ### napi_threadsafe_function_call_mode + 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 @@ -333,10 +353,18 @@ longer referenced from the current stack frame. For more details, review the [Object Lifetime Management][]. #### napi_escapable_handle_scope + Escapable handle scopes are a special type of handle scope to return values created within a particular handle scope to a parent scope. #### napi_ref + 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 minimum lifetimes explicitly. @@ -345,11 +373,19 @@ For more details, review the [Object Lifetime Management][]. ### N-API Callback types #### napi_callback_info + 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 invoked. #### napi_callback + Function pointer type for user-provided native functions which are to be exposed to JavaScript via N-API. Callback functions should satisfy the following signature: @@ -358,6 +394,10 @@ typedef napi_value (*napi_callback)(napi_env, napi_callback_info); ``` #### napi_finalize + 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 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 + Function pointer used with functions that support asynchronous 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. #### napi_async_complete_callback + Function pointer used with functions that support asynchronous 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 + 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 @@ -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. The format of the `napi_extended_error_info` structure is as follows: + ```C typedef struct napi_extended_error_info { const char* error_message;