Node-API
[Stable: 2 - Estable]
Estable: 2 Estabilidad: 2 - Estable
Node-API (anteriormente N-API) es una API para construir Addons nativos. Es independiente del entorno de ejecución subyacente de JavaScript (por ejemplo, V8) y se mantiene como parte del propio Node.js. Esta API será una Interfaz Binaria de Aplicación (ABI) estable en todas las versiones de Node.js. Su objetivo es aislar los addons de los cambios en el motor de JavaScript subyacente y permitir que los módulos compilados para una versión principal se ejecuten en versiones principales posteriores de Node.js sin recompilación. La guía de Estabilidad ABI proporciona una explicación más detallada.
Los addons se construyen/empaquetan con el mismo enfoque/herramientas descritas en la sección titulada Addons de C++. La única diferencia es el conjunto de APIs que utiliza el código nativo. En lugar de utilizar las APIs V8 o Abstracciones Nativas para Node.js, se utilizan las funciones disponibles en Node-API.
Las APIs expuestas por Node-API se utilizan generalmente para crear y manipular valores de JavaScript. Los conceptos y operaciones generalmente se corresponden con ideas especificadas en la Especificación del Lenguaje ECMA-262. Las APIs tienen las siguientes propiedades:
- Todas las llamadas a Node-API devuelven un código de estado de tipo
napi_status. Este estado indica si la llamada a la API se realizó correctamente o falló. - El valor de retorno de la API se pasa a través de un parámetro de salida.
- Todos los valores de JavaScript se abstraen detrás de un tipo opaco llamado
napi_value. - En caso de un código de estado de error, se puede obtener información adicional utilizando
napi_get_last_error_info. Se puede encontrar más información en la sección de manejo de errores Manejo de errores.
Node-API es una API de C que asegura la estabilidad ABI en todas las versiones de Node.js y diferentes niveles de compilador. Una API de C++ puede ser más fácil de usar. Para soportar el uso de C++, el proyecto mantiene un módulo wrapper de C++ llamado node-addon-api. Este wrapper proporciona una API de C++ en línea. Los binarios construidos con node-addon-api dependerán de los símbolos para las funciones basadas en C de Node-API exportadas por Node.js. node-addon-api es una forma más eficiente de escribir código que llama a Node-API. Tomemos, por ejemplo, el siguiente código de node-addon-api. La primera sección muestra el código de node-addon-api y la segunda sección muestra lo que realmente se utiliza en el addon.
Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");napi_status status;
napi_value object, string;
status = napi_create_object(env, &object);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
status = napi_set_named_property(env, object, "foo", string);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}El resultado final es que el addon solo utiliza las APIs de C exportadas. Como resultado, aún obtiene los beneficios de la estabilidad ABI proporcionada por la API de C.
Cuando utilice node-addon-api en lugar de las APIs de C, comience con la documentación de la API documentos para node-addon-api.
El Recurso Node-API ofrece una excelente orientación y consejos para los desarrolladores que recién comienzan con Node-API y node-addon-api. Se pueden encontrar recursos multimedia adicionales en la página de Medios de Node-API.
Implicaciones de la estabilidad de ABI
Aunque Node-API proporciona una garantía de estabilidad de ABI, otras partes de Node.js no lo hacen, y ninguna biblioteca externa utilizada desde el complemento podría hacerlo. En particular, ninguna de las siguientes API proporciona una garantía de estabilidad de ABI entre versiones principales:
- Las API de C++ de Node.js disponibles a través de cualquiera de
- Las API de libuv que también se incluyen con Node.js y están disponibles a través de
- La API de V8 disponible a través de
Por lo tanto, para que un complemento siga siendo compatible con ABI entre las versiones principales de Node.js, debe usar Node-API exclusivamente restringiéndose al uso de
#include <node_api.h>y comprobando, para todas las bibliotecas externas que utiliza, que la biblioteca externa ofrece garantías de estabilidad de ABI similares a Node-API.
Construcción
A diferencia de los módulos escritos en JavaScript, el desarrollo y la implementación de complementos nativos de Node.js utilizando Node-API requieren un conjunto adicional de herramientas. Además de las herramientas básicas necesarias para desarrollar para Node.js, el desarrollador de complementos nativos requiere una cadena de herramientas que pueda compilar código C y C++ en un binario. Además, dependiendo de cómo se implemente el complemento nativo, el usuario del complemento nativo también deberá tener instalada una cadena de herramientas C/C++.
Para los desarrolladores de Linux, los paquetes de cadena de herramientas C/C++ necesarios están disponibles fácilmente. GCC se utiliza ampliamente en la comunidad de Node.js para construir y probar en una variedad de plataformas. Para muchos desarrolladores, la infraestructura del compilador LLVM también es una buena opción.
Para los desarrolladores de Mac, Xcode ofrece todas las herramientas de compilación necesarias. Sin embargo, no es necesario instalar todo el IDE de Xcode. El siguiente comando instala la cadena de herramientas necesaria:
xcode-select --installPara los desarrolladores de Windows, Visual Studio ofrece todas las herramientas de compilación necesarias. Sin embargo, no es necesario instalar todo el IDE de Visual Studio. El siguiente comando instala la cadena de herramientas necesaria:
npm install --global windows-build-toolsLas secciones siguientes describen las herramientas adicionales disponibles para desarrollar e implementar complementos nativos de Node.js.
Herramientas de compilación
Ambas herramientas que se enumeran aquí requieren que los usuarios del complemento nativo tengan instalada una cadena de herramientas de C/C++ para instalar correctamente el complemento nativo.
node-gyp
node-gyp es un sistema de compilación basado en la bifurcación gyp-next de la herramienta GYP de Google y viene incluido con npm. GYP, y por lo tanto node-gyp, requiere que Python esté instalado.
Históricamente, node-gyp ha sido la herramienta preferida para la creación de complementos nativos. Tiene una adopción y documentación generalizadas. Sin embargo, algunos desarrolladores se han topado con limitaciones en node-gyp.
CMake.js
CMake.js es un sistema de compilación alternativo basado en CMake.
CMake.js es una buena opción para proyectos que ya utilizan CMake o para desarrolladores afectados por limitaciones en node-gyp. build_with_cmake es un ejemplo de un proyecto de complemento nativo basado en CMake.
Subida de binarios precompilados
Las tres herramientas listadas aquí permiten a los desarrolladores y mantenedores de complementos nativos crear y subir binarios a servidores públicos o privados. Estas herramientas suelen integrarse con sistemas de compilación CI/CD como Travis CI y AppVeyor para compilar y subir binarios para una variedad de plataformas y arquitecturas. Estos binarios están disponibles para su descarga por los usuarios que no necesitan tener instalada una cadena de herramientas C/C++.
node-pre-gyp
node-pre-gyp es una herramienta basada en node-gyp que añade la capacidad de subir binarios a un servidor de elección del desarrollador. node-pre-gyp tiene un soporte particularmente bueno para subir binarios a Amazon S3.
prebuild
prebuild es una herramienta que soporta compilaciones utilizando tanto node-gyp como CMake.js. A diferencia de node-pre-gyp, que soporta una variedad de servidores, prebuild sube binarios únicamente a lanzamientos de GitHub. prebuild es una buena opción para proyectos de GitHub que utilizan CMake.js.
prebuildify
prebuildify es una herramienta basada en node-gyp. La ventaja de prebuildify es que los binarios construidos se incluyen con el complemento nativo cuando se sube a npm. Los binarios se descargan de npm y están disponibles de inmediato para el usuario del módulo cuando se instala el complemento nativo.
Uso
Para utilizar las funciones de Node-API, incluya el archivo node_api.h que se encuentra en el directorio src del árbol de desarrollo de node:
#include <node_api.h>Esto optará por el NAPI_VERSION predeterminado para la versión dada de Node.js. Para garantizar la compatibilidad con versiones específicas de Node-API, la versión se puede especificar explícitamente al incluir el encabezado:
#define NAPI_VERSION 3
#include <node_api.h>Esto restringe la superficie de Node-API solo a la funcionalidad que estaba disponible en las versiones especificadas (y anteriores).
Parte de la superficie de Node-API es experimental y requiere una aceptación explícita:
#define NAPI_EXPERIMENTAL
#include <node_api.h>En este caso, toda la superficie de la API, incluidas las API experimentales, estará disponible para el código del módulo.
Ocasionalmente, se introducen características experimentales que afectan a las API ya publicadas y estables. Estas características se pueden deshabilitar mediante una exclusión voluntaria:
#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>donde \<FEATURE_NAME\> es el nombre de una característica experimental que afecta tanto a las API experimentales como a las estables.
Matriz de versiones de Node-API
Hasta la versión 9, las versiones de Node-API eran aditivas y tenían versiones independientes de Node.js. Esto significaba que cualquier versión era una extensión de la versión anterior, ya que tenía todas las API de la versión anterior con algunas adiciones. Cada versión de Node.js solo admitía una única versión de Node-API. Por ejemplo, la v18.15.0 solo admite la versión 8 de Node-API. La estabilidad de la ABI se logró porque 8 era un superconjunto estricto de todas las versiones anteriores.
A partir de la versión 9, si bien las versiones de Node-API continúan teniendo versiones independientes, un complemento que se ejecutó con la versión 9 de Node-API puede necesitar actualizaciones de código para ejecutarse con la versión 10 de Node-API. Sin embargo, la estabilidad de la ABI se mantiene, ya que las versiones de Node.js que admiten versiones de Node-API superiores a 8 admitirán todas las versiones entre 8 y la versión más alta que admitan y, de forma predeterminada, proporcionarán las API de la versión 8, a menos que un complemento opte por una versión de Node-API superior. Este enfoque proporciona la flexibilidad de optimizar mejor las funciones de Node-API existentes al tiempo que se mantiene la estabilidad de la ABI. Los complementos existentes pueden seguir ejecutándose sin volver a compilarse utilizando una versión anterior de Node-API. Si un complemento necesita funcionalidad de una versión más nueva de Node-API, serán necesarios cambios en el código existente y la recompilación para utilizar esas nuevas funciones de todos modos.
En las versiones de Node.js que admiten la versión 9 de Node-API y posteriores, definir NAPI_VERSION=X y utilizar las macros de inicialización de complementos existentes incorporará la versión de Node-API solicitada que se utilizará en tiempo de ejecución en el complemento. Si no se establece NAPI_VERSION, el valor predeterminado será 8.
Es posible que esta tabla no esté actualizada en flujos más antiguos, la información más actualizada se encuentra en la documentación de API más reciente en: Matriz de versiones de Node-API
| Versión de Node-API | Compatible con |
|---|---|
| 9 | v18.17.0+, 20.3.0+, 21.0.0 y todas las versiones posteriores |
| 8 | v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 y todas las versiones posteriores |
| 7 | v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 y todas las versiones posteriores |
| 6 | v10.20.0+, v12.17.0+, 14.0.0 y todas las versiones posteriores |
| 5 | v10.17.0+, v12.11.0+, 13.0.0 y todas las versiones posteriores |
| 4 | v10.16.0+, v11.8.0+, 12.0.0 y todas las versiones posteriores |
| 3 | v6.14.2*, 8.11.2+, v9.11.0+*, 10.0.0 y todas las versiones posteriores |
| 2 | v8.10.0+, v9.3.0+, 10.0.0 y todas las versiones posteriores |
| 1 | v8.6.0+*, v9.0.0+, 10.0.0 y todas las versiones posteriores |
- Node-API era experimental.
** Node.js 8.0.0 incluía Node-API como experimental. Se lanzó como la versión 1 de Node-API, pero continuó evolucionando hasta Node.js 8.6.0. La API es diferente en las versiones anteriores a Node.js 8.6.0. Recomendamos la versión 3 o posterior de Node-API.
Cada API documentada para Node-API tendrá un encabezado denominado añadido en:, y las API que son estables tendrán el encabezado adicional versión de Node-API:. Las API son directamente utilizables cuando se utiliza una versión de Node.js que admite la versión de Node-API que se muestra en versión de Node-API: o superior. Cuando se utiliza una versión de Node.js que no admite la versión de Node-API: enumerada o si no hay ninguna versión de Node-API: enumerada, la API solo estará disponible si #define NAPI_EXPERIMENTAL precede a la inclusión de node_api.h o js_native_api.h. Si una API parece no estar disponible en una versión de Node.js que es posterior a la que se muestra en añadido en:, lo más probable es que esta sea la razón de la aparente ausencia.
Las Node-API asociadas estrictamente con el acceso a las características de ECMAScript desde código nativo se pueden encontrar por separado en js_native_api.h y js_native_api_types.h. Las API definidas en estos encabezados se incluyen en node_api.h y node_api_types.h. Los encabezados están estructurados de esta manera para permitir implementaciones de Node-API fuera de Node.js. Para esas implementaciones, las API específicas de Node.js pueden no ser aplicables.
Las partes específicas de Node.js de un complemento se pueden separar del código que expone la funcionalidad real al entorno JavaScript para que este último se pueda usar con varias implementaciones de Node-API. En el ejemplo siguiente, addon.c y addon.h se refieren solo a js_native_api.h. Esto garantiza que addon.c se pueda reutilizar para compilar con la implementación de Node.js de Node-API o con cualquier implementación de Node-API fuera de Node.js.
addon_node.c es un archivo separado que contiene el punto de entrada específico de Node.js al complemento y que crea una instancia del complemento llamando a addon.c cuando el complemento se carga en un entorno Node.js.
// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif // _ADDON_H_// addon.c
#include "addon.h"
#define NODE_API_CALL(env, call) \
do { \
napi_status status = (call); \
if (status != napi_ok) { \
const napi_extended_error_info* error_info = NULL; \
napi_get_last_error_info((env), &error_info); \
const char* err_message = error_info->error_message; \
bool is_pending; \
napi_is_exception_pending((env), &is_pending); \
/* Si ya hay una excepción pendiente, no la vuelva a generar */ \
if (!is_pending) { \
const char* message = (err_message == NULL) \
? "mensaje de error vacío" \
: err_message; \
napi_throw_error((env), NULL, message); \
} \
return NULL; \
} \
} while(0)
static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
// Haz algo útil.
return NULL;
}
napi_value create_addon(napi_env env) {
napi_value result;
NODE_API_CALL(env, napi_create_object(env, &result));
napi_value exported_function;
NODE_API_CALL(env, napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function));
NODE_API_CALL(env, napi_set_named_property(env,
result,
"doSomethingUseful",
exported_function));
return result;
}// addon_node.c
#include <node_api.h>
#include "addon.h"
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
// Se espera que el cuerpo de esta función devuelva un `napi_value`.
// Las variables `napi_env env` y `napi_value exports` se pueden usar dentro
// del cuerpo, ya que las proporciona la definición de `NAPI_MODULE_INIT()`.
return create_addon(env);
}APIs del ciclo de vida del entorno
La Sección 8.7 de la Especificación del Lenguaje ECMAScript define el concepto de un "Agente" como un entorno autocontenido en el que se ejecuta el código JavaScript. El proceso puede iniciar y terminar múltiples Agentes de forma concurrente o secuencial.
Un entorno Node.js corresponde a un Agente ECMAScript. En el proceso principal, se crea un entorno al inicio, y se pueden crear entornos adicionales en hilos separados para servir como hilos de trabajo. Cuando Node.js está incrustado en otra aplicación, el hilo principal de la aplicación también puede construir y destruir un entorno Node.js varias veces durante el ciclo de vida del proceso de la aplicación, de tal manera que cada entorno Node.js creado por la aplicación puede, a su vez, durante su ciclo de vida crear y destruir entornos adicionales como hilos de trabajo.
Desde la perspectiva de un complemento nativo, esto significa que los enlaces que proporciona pueden ser llamados varias veces, desde múltiples contextos, e incluso de forma concurrente desde múltiples hilos.
Los complementos nativos pueden necesitar asignar un estado global que utilicen durante su ciclo de vida de un entorno Node.js, de modo que el estado sea único para cada instancia del complemento.
Con este fin, Node-API proporciona una forma de asociar datos de manera que su ciclo de vida esté ligado al ciclo de vida de un entorno Node.js.
napi_set_instance_data
Añadido en: v12.8.0, v10.20.0
Versión N-API: 6
napi_status napi_set_instance_data(node_api_basic_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint);[in] env: El entorno en el que se invoca la llamada a Node-API.[in] data: El elemento de datos para que esté disponible para los enlaces de esta instancia.[in] finalize_cb: La función a la que se llama cuando se está desmontando el entorno. La función recibedatapara que pueda liberarlo.napi_finalizeproporciona más detalles.[in] finalize_hint: Sugerencia opcional para pasar a la devolución de llamada de finalización durante la recolección.
Devuelve napi_ok si la API se realizó correctamente.
Esta API asocia data con el entorno Node.js en ejecución actual. data se puede recuperar posteriormente utilizando napi_get_instance_data(). Cualquier dato existente asociado con el entorno Node.js en ejecución actual que se haya establecido mediante una llamada anterior a napi_set_instance_data() se sobrescribirá. Si la llamada anterior proporcionó una finalize_cb, no se llamará.
napi_get_instance_data
Agregado en: v12.8.0, v10.20.0
Versión N-API: 6
napi_status napi_get_instance_data(node_api_basic_env env,
void** data);[in] env: El entorno bajo el cual se invoca la llamada a Node-API.[out] data: El elemento de datos que se asoció previamente con el entorno Node.js en ejecución mediante una llamada anapi_set_instance_data().
Devuelve napi_ok si la API tuvo éxito.
Esta API recupera los datos que se asociaron previamente con el entorno Node.js en ejecución a través de napi_set_instance_data(). Si no se establecen datos, la llamada tendrá éxito y data se establecerá en NULL.
Tipos de datos básicos de Node-API
Node-API expone los siguientes tipos de datos fundamentales como abstracciones que son consumidas por las diversas API. Estas API deben tratarse como opacas, introspectables solo con otras llamadas a Node-API.
napi_status
Agregado en: v8.0.0
Versión N-API: 1
Código de estado integral que indica el éxito o el fracaso de una llamada a Node-API. Actualmente, se admiten los siguientes códigos de estado.
typedef enum {
napi_ok,
napi_invalid_arg,
napi_object_expected,
napi_string_expected,
napi_name_expected,
napi_function_expected,
napi_number_expected,
napi_boolean_expected,
napi_array_expected,
napi_generic_failure,
napi_pending_exception,
napi_cancelled,
napi_escape_called_twice,
napi_handle_scope_mismatch,
napi_callback_scope_mismatch,
napi_queue_full,
napi_closing,
napi_bigint_expected,
napi_date_expected,
napi_arraybuffer_expected,
napi_detachable_arraybuffer_expected,
napi_would_deadlock, /* no se usa */
napi_no_external_buffers_allowed,
napi_cannot_run_js
} napi_status;Si se requiere información adicional después de que una API devuelva un estado fallido, se puede obtener llamando a napi_get_last_error_info.
napi_extended_error_info
Agregado en: v8.0.0
Versión N-API: 1
typedef struct {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
} napi_extended_error_info;error_message: Cadena codificada en UTF8 que contiene una descripción del error neutral para la VM.engine_reserved: Reservado para detalles de errores específicos de la VM. Actualmente no está implementado para ninguna VM.engine_error_code: Código de error específico de la VM. Actualmente no está implementado para ninguna VM.error_code: El código de estado de Node-API que se originó con el último error.
Consulte la sección Manejo de errores para obtener información adicional.
napi_env
napi_env se utiliza para representar un contexto que la implementación subyacente de Node-API puede usar para mantener el estado específico de la VM. Esta estructura se pasa a las funciones nativas cuando se invocan, y debe devolverse al realizar llamadas a Node-API. Específicamente, el mismo napi_env que se pasó cuando se llamó a la función nativa inicial debe pasarse a cualquier llamada anidada posterior a Node-API. No se permite el almacenamiento en caché de napi_env con el propósito de la reutilización general, ni el paso de napi_env entre instancias del mismo complemento que se ejecuta en diferentes hilos Worker. napi_env se vuelve inválido cuando se descarga una instancia de un complemento nativo. La notificación de este evento se entrega a través de los retornos de llamada proporcionados a napi_add_env_cleanup_hook y napi_set_instance_data.
node_api_basic_env
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
Esta variante de napi_env se pasa a los finalizadores síncronos (node_api_basic_finalize). Existe un subconjunto de Node-APIs que aceptan un parámetro de tipo node_api_basic_env como su primer argumento. Estas APIs no acceden al estado del motor de JavaScript y, por lo tanto, es seguro llamarlas desde finalizadores síncronos. Pasar un parámetro de tipo napi_env a estas APIs está permitido, sin embargo, pasar un parámetro de tipo node_api_basic_env a APIs que acceden al estado del motor de JavaScript no está permitido. Intentar hacerlo sin una conversión producirá una advertencia del compilador o un error cuando los complementos se compilen con flags que hacen que emitan advertencias y/o errores cuando se pasan tipos de puntero incorrectos a una función. Llamar a dichas APIs desde un finalizador síncrono resultará en última instancia en la terminación de la aplicación.
napi_value
Este es un puntero opaco que se utiliza para representar un valor de JavaScript.
napi_threadsafe_function
Añadido en: v10.6.0
Versión de N-API: 4
Este es un puntero opaco que representa una función de JavaScript que puede ser llamada asincrónicamente desde múltiples hilos a través de napi_call_threadsafe_function().
napi_threadsafe_function_release_mode
Añadido en: v10.6.0
Versión de N-API: 4
Un valor que se le da a napi_release_threadsafe_function() para indicar si la función segura para hilos se debe cerrar inmediatamente (napi_tsfn_abort) o simplemente liberar (napi_tsfn_release) y, por lo tanto, estar disponible para su uso posterior a través de napi_acquire_threadsafe_function() y napi_call_threadsafe_function().
typedef enum {
napi_tsfn_release,
napi_tsfn_abort
} napi_threadsafe_function_release_mode;napi_threadsafe_function_call_mode
Añadido en: v10.6.0
Versión de N-API: 4
Un valor que se le da a napi_call_threadsafe_function() para indicar si la llamada debe bloquearse cuando la cola asociada con la función segura para hilos está llena.
typedef enum {
napi_tsfn_nonblocking,
napi_tsfn_blocking
} napi_threadsafe_function_call_mode;Tipos de gestión de memoria de la Node-API
napi_handle_scope
Esta es una abstracción utilizada para controlar y modificar el ciclo de vida de los objetos creados dentro de un ámbito particular. En general, los valores de Node-API se crean dentro del contexto de un ámbito de manejador. Cuando se llama a un método nativo desde JavaScript, existirá un ámbito de manejador predeterminado. Si el usuario no crea explícitamente un nuevo ámbito de manejador, los valores de Node-API se crearán en el ámbito de manejador predeterminado. Para cualquier invocación de código fuera de la ejecución de un método nativo (por ejemplo, durante una invocación de retorno de llamada de libuv), se requiere que el módulo cree un ámbito antes de invocar cualquier función que pueda resultar en la creación de valores de JavaScript.
Los ámbitos de manejador se crean utilizando napi_open_handle_scope y se destruyen utilizando napi_close_handle_scope. Cerrar el ámbito puede indicar al GC que ya no se hace referencia a todos los napi_value creados durante la vida útil del ámbito de manejador desde el marco de pila actual.
Para obtener más detalles, revise la gestión del ciclo de vida de los objetos.
napi_escapable_handle_scope
Agregado en: v8.0.0
Versión de N-API: 1
Los ámbitos de identificadores escapables son un tipo especial de ámbito de identificadores para devolver valores creados dentro de un ámbito de identificadores particular a un ámbito principal.
napi_ref
Agregado en: v8.0.0
Versión de N-API: 1
Esta es la abstracción que se utiliza para hacer referencia a un napi_value. Esto permite a los usuarios administrar la vida útil de los valores de JavaScript, incluida la definición explícita de sus vidas útiles mínimas.
Para obtener más detalles, revise la Administración de la vida útil de los objetos.
napi_type_tag
Agregado en: v14.8.0, v12.19.0
Versión de N-API: 8
Un valor de 128 bits almacenado como dos enteros sin signo de 64 bits. Sirve como UUID con el que los objetos JavaScript o los externos pueden ser "etiquetados" para garantizar que son de un cierto tipo. Esta es una verificación más estricta que napi_instanceof, porque esta última puede informar un falso positivo si se ha manipulado el prototipo del objeto. El etiquetado de tipo es más útil en conjunto con napi_wrap porque asegura que el puntero recuperado de un objeto envuelto se pueda convertir de forma segura al tipo nativo correspondiente a la etiqueta de tipo que se había aplicado previamente al objeto JavaScript.
typedef struct {
uint64_t lower;
uint64_t upper;
} napi_type_tag;napi_async_cleanup_hook_handle
Agregado en: v14.10.0, v12.19.0
Un valor opaco devuelto por napi_add_async_cleanup_hook. Debe pasarse a napi_remove_async_cleanup_hook cuando se completa la cadena de eventos de limpieza asíncrona.
Tipos de devolución de llamada de Node-API
napi_callback_info
Agregado en: v8.0.0
Versión N-API: 1
Tipo de datos opaco que se pasa a una función de devolución de llamada. Se puede utilizar para obtener información adicional sobre el contexto en el que se invocó la devolución de llamada.
napi_callback
Agregado en: v8.0.0
Versión N-API: 1
Tipo de puntero de función para funciones nativas proporcionadas por el usuario que se expondrán a JavaScript a través de Node-API. Las funciones de devolución de llamada deben satisfacer la siguiente firma:
typedef napi_value (*napi_callback)(napi_env, napi_callback_info);A menos que por razones discutidas en Gestión de la vida útil de objetos, no es necesario crear un manejador y/o un alcance de devolución de llamada dentro de una napi_callback.
node_api_basic_finalize
Añadido en: v21.6.0, v20.12.0, v18.20.0
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
Tipo de puntero a función para funciones proporcionadas por complementos que permiten notificar al usuario cuando los datos de propiedad externa están listos para ser limpiados porque el objeto al que estaban asociados ha sido recolectado por el recolector de basura. El usuario debe proporcionar una función que satisfaga la siguiente firma que se llamaría al recolectar el objeto. Actualmente, node_api_basic_finalize se puede usar para averiguar cuándo se recolectan los objetos que tienen datos externos.
typedef void (*node_api_basic_finalize)(node_api_basic_env env,
void* finalize_data,
void* finalize_hint);A menos que por razones discutidas en Administración del ciclo de vida de objetos, no es necesario crear un identificador y/o un alcance de devolución de llamada dentro del cuerpo de la función.
Dado que estas funciones se pueden llamar mientras el motor de JavaScript se encuentra en un estado en el que no puede ejecutar código de JavaScript, solo se pueden llamar las Node-APIs que aceptan un node_api_basic_env como su primer parámetro. node_api_post_finalizer se puede usar para programar llamadas a la Node-API que requieren acceso al estado del motor de JavaScript para que se ejecuten después de que se haya completado el ciclo de recolección de basura actual.
En el caso de node_api_create_external_string_latin1 y node_api_create_external_string_utf16, el parámetro env puede ser nulo, porque las cadenas externas se pueden recolectar durante la última parte del cierre del entorno.
Historial de cambios:
- experimental (
NAPI_EXPERIMENTAL): Solo se pueden llamar las llamadas de Node-API que aceptan unnode_api_basic_envcomo su primer parámetro; de lo contrario, la aplicación terminará con un mensaje de error apropiado. Esta función se puede desactivar definiendoNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.
napi_finalize
Agregado en: v8.0.0
Versión de N-API: 1
Tipo de puntero de función para la función proporcionada por el complemento que permite al usuario programar un grupo de llamadas a las API de Node en respuesta a un evento de recolección de basura, después de que haya finalizado el ciclo de recolección de basura. Estos punteros de función se pueden usar con node_api_post_finalizer.
typedef void (*napi_finalize)(napi_env env,
void* finalize_data,
void* finalize_hint);Historial de cambios:
- experimental (
NAPI_EXPERIMENTALestá definido): Una función de este tipo ya no se puede utilizar como finalizador, excepto connode_api_post_finalizer. En su lugar, se debe utilizarnode_api_basic_finalize. Esta función se puede desactivar definiendoNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.
napi_async_execute_callback
Agregado en: v8.0.0
Versión de N-API: 1
Puntero de función utilizado con funciones que admiten operaciones asíncronas. Las funciones de devolución de llamada deben satisfacer la siguiente firma:
typedef void (*napi_async_execute_callback)(napi_env env, void* data);Las implementaciones de esta función deben evitar realizar llamadas a la API de Node que ejecuten JavaScript o interactúen con objetos JavaScript. Las llamadas a la API de Node deben estar en napi_async_complete_callback. No utilice el parámetro napi_env, ya que es probable que provoque la ejecución de JavaScript.
napi_async_complete_callback
Agregado en: v8.0.0
Versión N-API: 1
Puntero a función utilizado con funciones que admiten operaciones asíncronas. Las funciones de retorno de llamada deben satisfacer la siguiente firma:
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);A menos que sea por razones tratadas en Administración del tiempo de vida de objetos, no es necesario crear un scope de controlador y/o de retorno de llamada dentro del cuerpo de la función.
napi_threadsafe_function_call_js
Agregado en: v10.6.0
Versión N-API: 4
Puntero a función utilizado con llamadas de función asíncronas seguras para subprocesos. La función de retorno de llamada se llamará en el subproceso principal. Su propósito es utilizar un elemento de datos que llega a través de la cola desde uno de los subprocesos secundarios para construir los parámetros necesarios para una llamada a JavaScript, generalmente a través de napi_call_function, y luego realizar la llamada a JavaScript.
Los datos que llegan desde el subproceso secundario a través de la cola se dan en el parámetro data y la función de JavaScript a la que se debe llamar se da en el parámetro js_callback.
Node-API configura el entorno antes de llamar a esta función de retorno de llamada, por lo que es suficiente llamar a la función de JavaScript a través de napi_call_function en lugar de a través de napi_make_callback.
Las funciones de retorno de llamada deben satisfacer la siguiente firma:
typedef void (*napi_threadsafe_function_call_js)(napi_env env,
napi_value js_callback,
void* context,
void* data);[in] env: El entorno que se utilizará para las llamadas API, oNULLsi la función segura para subprocesos se está cerrando y puede ser necesario liberardata.[in] js_callback: La función de JavaScript a la que se debe llamar, oNULLsi la función segura para subprocesos se está cerrando y puede ser necesario liberardata. También puede serNULLsi la función segura para subprocesos se creó sinjs_callback.[in] context: Los datos opcionales con los que se creó la función segura para subprocesos.[in] data: Datos creados por el subproceso secundario. Es responsabilidad de la función de retorno de llamada convertir estos datos nativos en valores de JavaScript (con funciones Node-API) que se pueden pasar como parámetros cuando se invocajs_callback. Este puntero es gestionado completamente por los subprocesos y esta función de retorno de llamada. Por lo tanto, esta función de retorno de llamada debería liberar los datos.
A menos que sea por razones tratadas en Administración del tiempo de vida de objetos, no es necesario crear un scope de controlador y/o de retorno de llamada dentro del cuerpo de la función.
napi_cleanup_hook
Agregado en: v19.2.0, v18.13.0
Versión N-API: 3
Puntero a función utilizado con napi_add_env_cleanup_hook. Se llamará cuando se esté desmantelando el entorno.
Las funciones de retrollamada deben cumplir con la siguiente firma:
typedef void (*napi_cleanup_hook)(void* data);[in] data: Los datos que se pasaron anapi_add_env_cleanup_hook.
napi_async_cleanup_hook
Agregado en: v14.10.0, v12.19.0
Puntero a función utilizado con napi_add_async_cleanup_hook. Se llamará cuando se esté desmantelando el entorno.
Las funciones de retrollamada deben cumplir con la siguiente firma:
typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
void* data);[in] handle: El controlador que debe pasarse anapi_remove_async_cleanup_hookdespués de la finalización de la limpieza asíncrona.[in] data: Los datos que se pasaron anapi_add_async_cleanup_hook.
El cuerpo de la función debe iniciar las acciones de limpieza asíncrona al final de las cuales handle debe pasarse en una llamada a napi_remove_async_cleanup_hook.
Manejo de errores
Node-API utiliza tanto valores de retorno como excepciones de JavaScript para el manejo de errores. Las siguientes secciones explican el enfoque para cada caso.
Valores de retorno
Todas las funciones de Node-API comparten el mismo patrón de manejo de errores. El tipo de retorno de todas las funciones de la API es napi_status.
El valor de retorno será napi_ok si la solicitud fue exitosa y no se generó ninguna excepción de JavaScript no detectada. Si ocurrió un error Y se generó una excepción, se devolverá el valor napi_status para el error. Si se generó una excepción y no ocurrió ningún error, se devolverá napi_pending_exception.
En los casos en que se devuelve un valor de retorno distinto de napi_ok o napi_pending_exception, se debe llamar a napi_is_exception_pending para verificar si hay una excepción pendiente. Consulte la sección sobre excepciones para obtener más detalles.
El conjunto completo de posibles valores napi_status se define en napi_api_types.h.
El valor de retorno napi_status proporciona una representación del error que ocurrió independiente de la VM. En algunos casos, es útil poder obtener información más detallada, incluida una cadena que represente el error, así como información específica de la VM (motor).
Para recuperar esta información, se proporciona napi_get_last_error_info, que devuelve una estructura napi_extended_error_info. El formato de la estructura napi_extended_error_info es el siguiente:
Agregado en: v8.0.0
Versión N-API: 1
typedef struct napi_extended_error_info {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
};error_message: Representación textual del error que ocurrió.engine_reserved: Identificador opaco reservado solo para uso del motor.engine_error_code: Código de error específico de la VM.error_code: Código de estado Node-API para el último error.
napi_get_last_error_info devuelve la información de la última llamada a Node-API que se realizó.
No confíe en el contenido ni en el formato de ninguna información extendida, ya que no está sujeta a SemVer y puede cambiar en cualquier momento. Está destinado únicamente a fines de registro.
napi_get_last_error_info
Agregado en: v8.0.0
Versión de N-API: 1
napi_status
napi_get_last_error_info(node_api_basic_env env,
const napi_extended_error_info** result);[in] env: El entorno bajo el cual se invoca la API.[out] result: La estructuranapi_extended_error_infocon más información sobre el error.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API recupera una estructura napi_extended_error_info con información sobre el último error que ocurrió.
El contenido de napi_extended_error_info devuelto solo es válido hasta que se llama a una función Node-API en el mismo env. Esto incluye una llamada a napi_is_exception_pending, por lo que a menudo puede ser necesario hacer una copia de la información para que pueda ser usada más tarde. El puntero devuelto en error_message apunta a una cadena definida estáticamente, por lo que es seguro usar ese puntero si lo has copiado del campo error_message (que será sobreescrito) antes de que se llame a otra función Node-API.
No confíes en el contenido o formato de ninguna de la información extendida, ya que no está sujeta a SemVer y puede cambiar en cualquier momento. Su intención es únicamente para propósitos de registro.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
Excepciones
Cualquier llamada a una función de Node-API puede resultar en una excepción de JavaScript pendiente. Este es el caso para cualquiera de las funciones de la API, incluso aquellas que pueden no causar la ejecución de JavaScript.
Si el napi_status devuelto por una función es napi_ok, entonces no hay ninguna excepción pendiente y no se requiere ninguna acción adicional. Si el napi_status devuelto es diferente de napi_ok o napi_pending_exception, para intentar recuperarse y continuar en lugar de simplemente regresar inmediatamente, se debe llamar a napi_is_exception_pending para determinar si hay una excepción pendiente o no.
En muchos casos, cuando se llama a una función de Node-API y ya hay una excepción pendiente, la función regresará inmediatamente con un napi_status de napi_pending_exception. Sin embargo, este no es el caso para todas las funciones. Node-API permite que se llame a un subconjunto de funciones para permitir una limpieza mínima antes de regresar a JavaScript. En ese caso, napi_status reflejará el estado de la función. No reflejará las excepciones pendientes anteriores. Para evitar confusiones, verifique el estado de error después de cada llamada a la función.
Cuando hay una excepción pendiente, se pueden emplear uno de los dos enfoques.
El primer enfoque es realizar cualquier limpieza apropiada y luego regresar para que la ejecución regrese a JavaScript. Como parte de la transición de regreso a JavaScript, la excepción se lanzará en el punto del código JavaScript donde se invocó el método nativo. El comportamiento de la mayoría de las llamadas de Node-API no está especificado mientras haya una excepción pendiente, y muchas simplemente devolverán napi_pending_exception, así que haga lo menos posible y luego regrese a JavaScript donde se pueda manejar la excepción.
El segundo enfoque es intentar manejar la excepción. Habrá casos en los que el código nativo pueda detectar la excepción, tomar la acción apropiada y luego continuar. Esto solo se recomienda en casos específicos donde se sepa que la excepción se puede manejar de forma segura. En estos casos, se puede usar napi_get_and_clear_last_exception para obtener y borrar la excepción. Si la operación tiene éxito, el resultado contendrá el controlador del último Object de JavaScript lanzado. Si se determina, después de recuperar la excepción, que la excepción no se puede manejar después de todo, se puede volver a lanzar con napi_throw donde error es el valor de JavaScript que se va a lanzar.
Las siguientes funciones de utilidad también están disponibles en caso de que el código nativo necesite lanzar una excepción o determinar si un napi_value es una instancia de un objeto Error de JavaScript: napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error y napi_is_error.
Las siguientes funciones de utilidad también están disponibles en caso de que el código nativo necesite crear un objeto Error: napi_create_error, napi_create_type_error, napi_create_range_error y node_api_create_syntax_error, donde resultado es el napi_value que se refiere al objeto Error de JavaScript recién creado.
El proyecto Node.js está agregando códigos de error a todos los errores generados internamente. El objetivo es que las aplicaciones usen estos códigos de error para toda la verificación de errores. Los mensajes de error asociados permanecerán, pero solo estarán destinados a ser utilizados para el registro y la visualización, con la expectativa de que el mensaje pueda cambiar sin que se aplique SemVer. Para admitir este modelo con Node-API, tanto en la funcionalidad interna como para la funcionalidad específica del módulo (ya que es una buena práctica), las funciones throw_ y create_ toman un parámetro de código opcional que es la cadena para el código que se agregará al objeto de error. Si el parámetro opcional es NULL, no se asociará ningún código con el error. Si se proporciona un código, el nombre asociado con el error también se actualiza para que sea:
originalName [código]donde originalName es el nombre original asociado con el error y código es el código que se proporcionó. Por ejemplo, si el código es 'ERR_ERROR_1' y se está creando un TypeError, el nombre será:
TypeError [ERR_ERROR_1]napi_throw
Agregado en: v8.0.0
Versión N-API: 1
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);[in] env: El entorno en el que se invoca la API.[in] error: El valor de JavaScript que se va a lanzar.
Devuelve napi_ok si la API tuvo éxito.
Esta API lanza el valor de JavaScript proporcionado.
napi_throw_error
Agregado en: v8.0.0
Versión N-API: 1
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
const char* code,
const char* msg);[in] env: El entorno en el que se invoca la API.[in] code: Código de error opcional que se establecerá en el error.[in] msg: Cadena C que representa el texto que se asociará al error.
Devuelve napi_ok si la API tuvo éxito.
Esta API lanza un Error de JavaScript con el texto proporcionado.
napi_throw_type_error
Agregado en: v8.0.0
Versión N-API: 1
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
const char* code,
const char* msg);[in] env: El entorno en el que se invoca la API.[in] code: Código de error opcional que se establecerá en el error.[in] msg: Cadena C que representa el texto que se asociará al error.
Devuelve napi_ok si la API tuvo éxito.
Esta API lanza un TypeError de JavaScript con el texto proporcionado.
napi_throw_range_error
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
const char* code,
const char* msg);[in] env: El entorno en el que se invoca la API.[in] code: Código de error opcional que se establecerá en el error.[in] msg: Cadena C que representa el texto que se asociará con el error.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API arroja un RangeError de JavaScript con el texto proporcionado.
node_api_throw_syntax_error
Agregado en: v17.2.0, v16.14.0
Versión de N-API: 9
NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
const char* code,
const char* msg);[in] env: El entorno en el que se invoca la API.[in] code: Código de error opcional que se establecerá en el error.[in] msg: Cadena C que representa el texto que se asociará con el error.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API arroja un SyntaxError de JavaScript con el texto proporcionado.
napi_is_error
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_is_error(napi_env env,
napi_value value,
bool* result);[in] env: El entorno en el que se invoca la API.[in] value: Elnapi_valueque se va a comprobar.[out] result: Valor booleano que se establece en true sinapi_valuerepresenta un error, false en caso contrario.
Devuelve napi_ok si la API se ha realizado correctamente.
Esta API consulta un napi_value para comprobar si representa un objeto de error.
napi_create_error
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_create_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] code:napi_valueopcional con la cadena para el código de error que se asociará al error.[in] msg:napi_valueque hace referencia a unastringde JavaScript que se utilizará como mensaje para elError.[out] result:napi_valueque representa el error creado.
Devuelve napi_ok si la API se ha realizado correctamente.
Esta API devuelve un Error de JavaScript con el texto proporcionado.
napi_create_type_error
Agregado en: v8.0.0
Versión N-API: 1
NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: El entorno bajo el cual se invoca la API.[in] code:napi_valueopcional con la cadena del código de error que se asociará al error.[in] msg:napi_valueque hace referencia a unastringde JavaScript que se utilizará como mensaje para elError.[out] result:napi_valueque representa el error creado.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API devuelve un TypeError de JavaScript con el texto proporcionado.
napi_create_range_error
Agregado en: v8.0.0
Versión N-API: 1
NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: El entorno bajo el cual se invoca la API.[in] code:napi_valueopcional con la cadena del código de error que se asociará al error.[in] msg:napi_valueque hace referencia a unastringde JavaScript que se utilizará como mensaje para elError.[out] result:napi_valueque representa el error creado.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API devuelve un RangeError de JavaScript con el texto proporcionado.
node_api_create_syntax_error
Agregado en: v17.2.0, v16.14.0
Versión N-API: 9
NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] code:napi_valueopcional con la cadena para el código de error que se asociará al error.[in] msg:napi_valueque hace referencia a unastringde JavaScript que se utilizará como mensaje para elError.[out] result:napi_valueque representa el error creado.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API devuelve un SyntaxError de JavaScript con el texto proporcionado.
napi_get_and_clear_last_exception
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_and_clear_last_exception(napi_env env,
napi_value* result);[in] env: El entorno en el que se invoca la API.[out] result: La excepción si hay alguna pendiente,NULLen caso contrario.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
napi_is_exception_pending
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_is_exception_pending(napi_env env, bool* result);[in] env: El entorno en el que se invoca la API.[out] result: Valor booleano que se establece en true si hay una excepción pendiente.
Devuelve napi_ok si la API tuvo éxito.
Se puede llamar a esta API incluso si hay una excepción de JavaScript pendiente.
napi_fatal_exception
Agregado en: v9.10.0
Versión de N-API: 3
napi_status napi_fatal_exception(napi_env env, napi_value err);[in] env: El entorno en el que se invoca la API.[in] err: El error que se pasa a'uncaughtException'.
Activa un 'uncaughtException' en JavaScript. Útil si una devolución de llamada asíncrona arroja una excepción sin forma de recuperarse.
Errores fatales
En caso de un error irrecuperable en un complemento nativo, se puede lanzar un error fatal para terminar el proceso de inmediato.
napi_fatal_error
Agregado en: v8.2.0
Versión de N-API: 1
NAPI_NO_RETURN void napi_fatal_error(const char* location,
size_t location_len,
const char* message,
size_t message_len);[in] location: Ubicación opcional en la que se produjo el error.[in] location_len: La longitud de la ubicación en bytes, oNAPI_AUTO_LENGTHsi termina en nulo.[in] message: El mensaje asociado con el error.[in] message_len: La longitud del mensaje en bytes, oNAPI_AUTO_LENGTHsi termina en nulo.
La llamada a la función no regresa, el proceso terminará.
Se puede llamar a esta API incluso si hay una excepción de JavaScript pendiente.
Gestión de la vida útil de los objetos
A medida que se realizan llamadas a la API de Node, los manejadores de los objetos en el heap de la VM subyacente pueden devolverse como napi_values. Estos manejadores deben mantener los objetos 'vivos' hasta que el código nativo ya no los necesite, de lo contrario, los objetos podrían recolectarse antes de que el código nativo terminara de usarlos.
A medida que se devuelven los manejadores de objetos, se asocian con un 'ámbito'. La vida útil del ámbito predeterminado está ligada a la vida útil de la llamada al método nativo. El resultado es que, de forma predeterminada, los manejadores siguen siendo válidos y los objetos asociados con estos manejadores se mantendrán vivos durante la vida útil de la llamada al método nativo.
Sin embargo, en muchos casos, es necesario que los manejadores sigan siendo válidos durante una vida útil más corta o más larga que la del método nativo. Las secciones siguientes describen las funciones de la API de Node que se pueden utilizar para cambiar la vida útil del manejador con respecto a la predeterminada.
Acortar la vida útil del manejador con respecto a la del método nativo
A menudo es necesario acortar la vida útil de los manejadores con respecto a la vida útil de un método nativo. Por ejemplo, considere un método nativo que tiene un bucle que itera a través de los elementos de un arreglo grande:
for (int i = 0; i < 1000000; i++) {
napi_value result;
napi_status status = napi_get_element(env, object, i, &result);
if (status != napi_ok) {
break;
}
// do something with element
}Esto resultaría en la creación de una gran cantidad de manejadores, consumiendo recursos sustanciales. Además, aunque el código nativo solo pudiera usar el manejador más reciente, todos los objetos asociados también se mantendrían vivos ya que todos comparten el mismo ámbito.
Para manejar este caso, la API de Node proporciona la capacidad de establecer un nuevo 'ámbito' al que se asociarán los manejadores recién creados. Una vez que esos manejadores ya no se necesiten, el ámbito puede 'cerrarse' y cualquier manejador asociado con el ámbito se invalidará. Los métodos disponibles para abrir/cerrar ámbitos son napi_open_handle_scope y napi_close_handle_scope.
La API de Node solo admite una única jerarquía anidada de ámbitos. Solo hay un ámbito activo en cualquier momento, y todos los manejadores nuevos se asociarán con ese ámbito mientras esté activo. Los ámbitos deben cerrarse en el orden inverso al que se abrieron. Además, todos los ámbitos creados dentro de un método nativo deben cerrarse antes de regresar de ese método.
Tomando el ejemplo anterior, agregar llamadas a napi_open_handle_scope y napi_close_handle_scope aseguraría que, como máximo, un solo manejador sea válido durante toda la ejecución del bucle:
for (int i = 0; i < 1000000; i++) {
napi_handle_scope scope;
napi_status status = napi_open_handle_scope(env, &scope);
if (status != napi_ok) {
break;
}
napi_value result;
status = napi_get_element(env, object, i, &result);
if (status != napi_ok) {
break;
}
// do something with element
status = napi_close_handle_scope(env, scope);
if (status != napi_ok) {
break;
}
}Al anidar ámbitos, hay casos en los que un manejador de un ámbito interno necesita vivir más allá de la vida útil de ese ámbito. La API de Node admite un 'ámbito escapable' para admitir este caso. Un ámbito escapable permite que un manejador sea 'promovido' de modo que 'escape' del ámbito actual y la vida útil del manejador cambie del ámbito actual a la del ámbito externo.
Los métodos disponibles para abrir/cerrar ámbitos escapables son napi_open_escapable_handle_scope y napi_close_escapable_handle_scope.
La solicitud para promover un manejador se realiza a través de napi_escape_handle, que solo se puede llamar una vez.
napi_open_handle_scope
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
napi_handle_scope* result);[in] env: El entorno bajo el cual se invoca la API.[out] result:napi_valueque representa el nuevo ámbito.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API abre un nuevo ámbito.
napi_close_handle_scope
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
napi_handle_scope scope);[in] env: El entorno bajo el cual se invoca la API.[in] scope:napi_valueque representa el ámbito que se va a cerrar.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API cierra el ámbito pasado. Los ámbitos deben cerrarse en el orden inverso al que fueron creados.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
napi_open_escapable_handle_scope
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status
napi_open_escapable_handle_scope(napi_env env,
napi_handle_scope* result);[in] env: El entorno bajo el cual se invoca la API.[out] result:napi_valueque representa el nuevo ámbito.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API abre un nuevo ámbito desde el cual se puede promover un objeto al ámbito exterior.
napi_close_escapable_handle_scope
Agregado en: v8.0.0
Versión N-API: 1
NAPI_EXTERN napi_status
napi_close_escapable_handle_scope(napi_env env,
napi_handle_scope scope);[in] env: El entorno bajo el cual se invoca la API.[in] scope:napi_valueque representa el ámbito que se va a cerrar.
Devuelve napi_ok si la API tuvo éxito.
Esta API cierra el ámbito pasado. Los ámbitos deben cerrarse en el orden inverso al que se crearon.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
napi_escape_handle
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_escape_handle(napi_env env,
napi_escapable_handle_scope scope,
napi_value escapee,
napi_value* result);[in] env: El entorno bajo el cual se invoca la API.[in] scope:napi_valueque representa el ámbito actual.[in] escapee:napi_valueque representa elObjectde JavaScript que se va a escapar.[out] result:napi_valueque representa el manejador delObjectescapado en el ámbito exterior.
Devuelve napi_ok si la API tuvo éxito.
Esta API promueve el manejador al objeto JavaScript para que sea válido durante la vida útil del ámbito exterior. Solo se puede llamar una vez por ámbito. Si se llama más de una vez, se devolverá un error.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
Referencias a valores con una vida útil más larga que la del método nativo
En algunos casos, un complemento necesitará poder crear y referenciar valores con una vida útil más larga que la de una única invocación de método nativo. Por ejemplo, para crear un constructor y luego usar ese constructor en una solicitud para crear instancias, debe ser posible referenciar el objeto constructor a través de muchas solicitudes diferentes de creación de instancias. Esto no sería posible con un manejador normal devuelto como napi_value como se describe en la sección anterior. La vida útil de un manejador normal es gestionada por los alcances y todos los alcances deben cerrarse antes del final de un método nativo.
Node-API proporciona métodos para crear referencias persistentes a valores. Actualmente, Node-API solo permite crear referencias para un conjunto limitado de tipos de valor, incluidos objeto, externo, función y símbolo.
Cada referencia tiene un conteo asociado con un valor de 0 o superior, que determina si la referencia mantendrá vivo el valor correspondiente. Las referencias con un conteo de 0 no impiden que se recopilen los valores. Los valores de tipo objeto (objeto, función, externo) y símbolo se están convirtiendo en referencias "débiles" y aún se puede acceder a ellos mientras no se recopilen. Cualquier conteo mayor que 0 evitará que se recopilen los valores.
Los valores de símbolo tienen diferentes sabores. El verdadero comportamiento de referencia débil solo es compatible con los símbolos locales creados con la función napi_create_symbol o las llamadas al constructor JavaScript Symbol(). Los símbolos registrados globalmente creados con la función node_api_symbol_for o las llamadas a la función JavaScript Symbol.for() permanecen siempre como referencias fuertes porque el recolector de basura no los recopila. Lo mismo ocurre con los símbolos conocidos como Symbol.iterator. El recolector de basura tampoco los recopila nunca.
Las referencias se pueden crear con un recuento de referencias inicial. El recuento se puede modificar a través de napi_reference_ref y napi_reference_unref. Si se recopila un objeto mientras el recuento de una referencia es 0, todas las llamadas posteriores para obtener el objeto asociado con la referencia napi_get_reference_value devolverán NULL para el napi_value devuelto. Un intento de llamar a napi_reference_ref para una referencia cuyo objeto ha sido recopilado resulta en un error.
Las referencias deben eliminarse una vez que el complemento ya no las necesite. Cuando se elimina una referencia, ya no evitará que se recopile el objeto correspondiente. No eliminar una referencia persistente resulta en una "fuga de memoria", ya que tanto la memoria nativa para la referencia persistente como el objeto correspondiente en el heap se retienen para siempre.
Se pueden crear múltiples referencias persistentes que se refieren al mismo objeto, cada una de las cuales mantendrá vivo el objeto o no según su recuento individual. Múltiples referencias persistentes al mismo objeto pueden resultar en el mantenimiento inesperado de memoria nativa. Las estructuras nativas para una referencia persistente deben mantenerse vivas hasta que se ejecuten los finalizadores para el objeto referenciado. Si se crea una nueva referencia persistente para el mismo objeto, los finalizadores para ese objeto no se ejecutarán y la memoria nativa apuntada por la referencia persistente anterior no se liberará. Esto se puede evitar llamando a napi_delete_reference además de napi_reference_unref cuando sea posible.
Historial de cambios:
- Experimental (
NAPI_EXPERIMENTALestá definido): Se pueden crear referencias para todos los tipos de valor. Los nuevos tipos de valor admitidos no admiten la semántica de referencia débil y los valores de estos tipos se liberan cuando el recuento de referencias se convierte en 0 y ya no se puede acceder a ellos desde la referencia.
napi_create_reference
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
napi_value value,
uint32_t initial_refcount,
napi_ref* result);[in] env: El entorno en el que se invoca la API.[in] value: Elnapi_valuepara el que se está creando una referencia.[in] initial_refcount: El recuento de referencias inicial para la nueva referencia.[out] result:napi_refque apunta a la nueva referencia.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea una nueva referencia con el recuento de referencias especificado para el valor pasado.
napi_delete_reference
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);[in] env: El entorno en el que se invoca la API.[in] ref:napi_refque se va a eliminar.
Devuelve napi_ok si la API tuvo éxito.
Esta API elimina la referencia pasada.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
napi_reference_ref
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
napi_ref ref,
uint32_t* result);[in] env: El entorno bajo el cual se invoca la API.[in] ref:napi_refpara la cual se incrementará el recuento de referencias.[out] result: El nuevo recuento de referencias.
Devuelve napi_ok si la API tuvo éxito.
Esta API incrementa el recuento de referencias para la referencia pasada y devuelve el recuento de referencias resultante.
napi_reference_unref
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
napi_ref ref,
uint32_t* result);[in] env: El entorno bajo el cual se invoca la API.[in] ref:napi_refpara la cual se decrementará el recuento de referencias.[out] result: El nuevo recuento de referencias.
Devuelve napi_ok si la API tuvo éxito.
Esta API decrementa el recuento de referencias para la referencia pasada y devuelve el recuento de referencias resultante.
napi_get_reference_value
Añadido en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
napi_ref ref,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] ref: Elnapi_refpara el que se solicita el valor correspondiente.[out] result: Elnapi_valueal que hace referencia elnapi_ref.
Devuelve napi_ok si la API se ejecutó correctamente.
Si aún es válido, esta API devuelve el napi_value que representa el valor de JavaScript asociado con el napi_ref. De lo contrario, el resultado será NULL.
Limpieza al salir del entorno actual de Node.js
Si bien un proceso de Node.js normalmente libera todos sus recursos al salir, los integradores de Node.js o el soporte futuro para Workers pueden requerir que los complementos registren ganchos de limpieza que se ejecutarán una vez que salga el entorno actual de Node.js.
Node-API proporciona funciones para registrar y anular el registro de dichas devoluciones de llamada. Cuando se ejecutan esas devoluciones de llamada, todos los recursos que mantiene el complemento deben liberarse.
napi_add_env_cleanup_hook
Agregado en: v10.2.0
Versión de N-API: 3
NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
napi_cleanup_hook fun,
void* arg);Registra fun como una función para ser ejecutada con el parámetro arg una vez que el entorno actual de Node.js se cierre.
Una función se puede especificar de forma segura varias veces con diferentes valores de arg. En ese caso, también se llamará varias veces. No se permite proporcionar los mismos valores fun y arg varias veces y hará que el proceso se aborte.
Los hooks se llamarán en orden inverso, es decir, el más recientemente agregado se llamará primero.
La eliminación de este hook se puede realizar utilizando napi_remove_env_cleanup_hook. Normalmente, eso sucede cuando el recurso para el cual se agregó este hook se está desmantelando de todos modos.
Para la limpieza asíncrona, napi_add_async_cleanup_hook está disponible.
napi_remove_env_cleanup_hook
Agregado en: v10.2.0
Versión de N-API: 3
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
void (*fun)(void* arg),
void* arg);Anula el registro de fun como una función que se ejecutará con el parámetro arg una vez que finalice el entorno actual de Node.js. Tanto el argumento como el valor de la función deben coincidir exactamente.
La función debe haberse registrado originalmente con napi_add_env_cleanup_hook, de lo contrario, el proceso se abortará.
napi_add_async_cleanup_hook
[Historial]
| Versión | Cambios |
|---|---|
| v14.10.0, v12.19.0 | Firma modificada de la devolución de llamada hook. |
| v14.8.0, v12.19.0 | Agregado en: v14.8.0, v12.19.0 |
Versión de N-API: 8
NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
node_api_basic_env env,
napi_async_cleanup_hook hook,
void* arg,
napi_async_cleanup_hook_handle* remove_handle);[in] env: El entorno en el que se invoca la API.[in] hook: El puntero de función para llamar al desmontar el entorno.[in] arg: El puntero para pasar ahookcuando se llame.[out] remove_handle: Handle opcional que hace referencia al hook de limpieza asíncrono.
Registra hook, que es una función de tipo napi_async_cleanup_hook, como una función que se ejecutará con los parámetros remove_handle y arg una vez que finalice el entorno actual de Node.js.
A diferencia de napi_add_env_cleanup_hook, se permite que el hook sea asíncrono.
De lo contrario, el comportamiento generalmente coincide con el de napi_add_env_cleanup_hook.
Si remove_handle no es NULL, se almacenará un valor opaco en él que luego deberá pasarse a napi_remove_async_cleanup_hook, independientemente de si el hook ya se ha invocado. Por lo general, eso sucede cuando el recurso para el que se agregó este hook se está desmontando de todos modos.
napi_remove_async_cleanup_hook
[Historial]
| Versión | Cambios |
|---|---|
| v14.10.0, v12.19.0 | Se eliminó el parámetro env. |
| v14.8.0, v12.19.0 | Agregado en: v14.8.0, v12.19.0 |
NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
napi_async_cleanup_hook_handle remove_handle);[in] remove_handle: El controlador de un hook de limpieza asíncrono que fue creado connapi_add_async_cleanup_hook.
Cancela el registro del hook de limpieza correspondiente a remove_handle. Esto evitará que el hook se ejecute, a menos que ya haya comenzado a ejecutarse. Esto debe ser llamado en cualquier valor napi_async_cleanup_hook_handle obtenido de napi_add_async_cleanup_hook.
Finalización en la salida del entorno de Node.js
El entorno de Node.js puede ser desmantelado en un momento arbitrario tan pronto como sea posible, con la ejecución de JavaScript deshabilitada, como en la solicitud de worker.terminate(). Cuando el entorno está siendo desmantelado, los callbacks napi_finalize registrados de objetos JavaScript, funciones seguras para subprocesos e instancias de datos del entorno se invocan de inmediato e independientemente.
La invocación de los callbacks napi_finalize se programa después de los hooks de limpieza registrados manualmente. Para asegurar un orden apropiado de la finalización del complemento durante el cierre del entorno para evitar el uso después de la liberación en el callback napi_finalize, los complementos deben registrar un hook de limpieza con napi_add_env_cleanup_hook y napi_add_async_cleanup_hook para liberar manualmente el recurso asignado en un orden apropiado.
Registro de módulos
Los módulos de Node-API se registran de manera similar a otros módulos, excepto que en lugar de usar la macro NODE_MODULE, se usa lo siguiente:
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)La siguiente diferencia es la firma del método Init. Para un módulo Node-API, es la siguiente:
napi_value Init(napi_env env, napi_value exports);El valor de retorno de Init se trata como el objeto exports para el módulo. El método Init recibe un objeto vacío a través del parámetro exports como una conveniencia. Si Init devuelve NULL, el parámetro pasado como exports es exportado por el módulo. Los módulos Node-API no pueden modificar el objeto module, pero pueden especificar cualquier cosa como la propiedad exports del módulo.
Para agregar el método hello como una función para que pueda ser llamada como un método proporcionado por el complemento:
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_property_descriptor desc = {
"hello",
NULL,
Method,
NULL,
NULL,
NULL,
napi_writable | napi_enumerable | napi_configurable,
NULL
};
status = napi_define_properties(env, exports, 1, &desc);
if (status != napi_ok) return NULL;
return exports;
}Para establecer que una función sea devuelta por require() para el complemento:
napi_value Init(napi_env env, napi_value exports) {
napi_value method;
napi_status status;
status = napi_create_function(env, "exports", NAPI_AUTO_LENGTH, Method, NULL, &method);
if (status != napi_ok) return NULL;
return method;
}Para definir una clase para que se puedan crear nuevas instancias (a menudo se usa con Object wrap):
// NOTA: ejemplo parcial, no se incluye todo el código referenciado
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_property_descriptor properties[] = {
{ "value", NULL, NULL, GetValue, SetValue, NULL, napi_writable | napi_configurable, NULL },
DECLARE_NAPI_METHOD("plusOne", PlusOne),
DECLARE_NAPI_METHOD("multiply", Multiply),
};
napi_value cons;
status =
napi_define_class(env, "MyObject", New, NULL, 3, properties, &cons);
if (status != napi_ok) return NULL;
status = napi_create_reference(env, cons, 1, &constructor);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "MyObject", cons);
if (status != napi_ok) return NULL;
return exports;
}También puede usar la macro NAPI_MODULE_INIT, que actúa como una abreviatura para NAPI_MODULE y define una función Init:
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
napi_value answer;
napi_status result;
status = napi_create_int64(env, 42, &answer);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "answer", answer);
if (status != napi_ok) return NULL;
return exports;
}Los parámetros env y exports se proporcionan al cuerpo de la macro NAPI_MODULE_INIT.
Todos los complementos de Node-API son conscientes del contexto, lo que significa que pueden cargarse varias veces. Hay algunas consideraciones de diseño al declarar dicho módulo. La documentación sobre complementos conscientes del contexto proporciona más detalles.
Las variables env y exports estarán disponibles dentro del cuerpo de la función después de la invocación de la macro.
Para obtener más detalles sobre cómo establecer propiedades en objetos, consulte la sección sobre Trabajar con propiedades de JavaScript.
Para obtener más detalles sobre la creación de módulos de complementos en general, consulte la API existente.
Trabajando con valores de JavaScript
Node-API expone un conjunto de APIs para crear todo tipo de valores de JavaScript. Algunos de estos tipos están documentados en la Sección 6 de la Especificación del Lenguaje ECMAScript.
Fundamentalmente, estas APIs se utilizan para hacer una de las siguientes cosas:
Los valores de Node-API están representados por el tipo napi_value. Cualquier llamada a Node-API que requiera un valor de JavaScript toma un napi_value. En algunos casos, la API comprueba el tipo de napi_value por adelantado. Sin embargo, para un mejor rendimiento, es mejor que la persona que llama se asegure de que el napi_value en cuestión sea del tipo de JavaScript esperado por la API.
Tipos Enum
napi_key_collection_mode
Añadido en: v13.7.0, v12.17.0, v10.20.0
Versión N-API: 6
typedef enum {
napi_key_include_prototypes,
napi_key_own_only
} napi_key_collection_mode;Describe los enums de filtro Keys/Properties:
napi_key_collection_mode limita el rango de propiedades recopiladas.
napi_key_own_only limita las propiedades recopiladas al objeto dado únicamente. napi_key_include_prototypes incluirá todas las claves de la cadena de prototipos del objeto también.
napi_key_filter
Agregado en: v13.7.0, v12.17.0, v10.20.0
Versión de N-API: 6
typedef enum {
napi_key_all_properties = 0,
napi_key_writable = 1,
napi_key_enumerable = 1 << 1,
napi_key_configurable = 1 << 2,
napi_key_skip_strings = 1 << 3,
napi_key_skip_symbols = 1 << 4
} napi_key_filter;Bits de filtro de propiedades. Se pueden combinar con un OR para construir un filtro compuesto.
napi_key_conversion
Agregado en: v13.7.0, v12.17.0, v10.20.0
Versión de N-API: 6
typedef enum {
napi_key_keep_numbers,
napi_key_numbers_to_strings
} napi_key_conversion;napi_key_numbers_to_strings convertirá los índices enteros a cadenas. napi_key_keep_numbers devolverá números para los índices enteros.
napi_valuetype
typedef enum {
// Tipos ES6 (corresponde a typeof)
napi_undefined,
napi_null,
napi_boolean,
napi_number,
napi_string,
napi_symbol,
napi_object,
napi_function,
napi_external,
napi_bigint,
} napi_valuetype;Describe el tipo de un napi_value. Esto generalmente corresponde a los tipos descritos en la Sección 6.1 de la Especificación del Lenguaje ECMAScript. Además de los tipos en esa sección, napi_valuetype también puede representar Functions y Objects con datos externos.
Un valor JavaScript de tipo napi_external aparece en JavaScript como un objeto simple tal que no se pueden establecer propiedades en él, y no tiene prototipo.
napi_typedarray_type
typedef enum {
napi_int8_array,
napi_uint8_array,
napi_uint8_clamped_array,
napi_int16_array,
napi_uint16_array,
napi_int32_array,
napi_uint32_array,
napi_float32_array,
napi_float64_array,
napi_bigint64_array,
napi_biguint64_array,
} napi_typedarray_type;Esto representa el tipo de datos escalares binarios subyacentes del TypedArray. Los elementos de esta enumeración corresponden a la Sección 22.2 de la Especificación del Lenguaje ECMAScript.
Funciones de creación de objetos
napi_create_array
Añadido en: v8.0.0
Versión de N-API: 1
napi_status napi_create_array(napi_env env, napi_value* result)[in] env: El entorno bajo el cual se invoca la llamada a Node-API.[out] result: Unnapi_valueque representa unArrayde JavaScript.
Devuelve napi_ok si la API se realizó correctamente.
Esta API devuelve un valor Node-API correspondiente a un tipo Array de JavaScript. Los arreglos de JavaScript se describen en la Sección 22.1 de la Especificación del Lenguaje ECMAScript.
napi_create_array_with_length
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_create_array_with_length(napi_env env,
size_t length,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] length: La longitud inicial delArray.[out] result: Unnapi_valueque representa unArrayde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API devuelve un valor Node-API correspondiente a un tipo Array de JavaScript. La propiedad length del Array se establece al parámetro length pasado. Sin embargo, no se garantiza que la VM preasigne el búfer subyacente cuando se crea la matriz. Ese comportamiento se deja a la implementación de la VM subyacente. Si el búfer debe ser un bloque contiguo de memoria que se puede leer y/o escribir directamente a través de C, considera usar napi_create_external_arraybuffer.
Las matrices de JavaScript se describen en la Sección 22.1 de la Especificación del Lenguaje ECMAScript.
napi_create_arraybuffer
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_create_arraybuffer(napi_env env,
size_t byte_length,
void** data,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] length: La longitud en bytes del búfer de matriz que se va a crear.[out] data: Puntero al búfer de bytes subyacente delArrayBuffer.datase puede ignorar opcionalmente pasandoNULL.[out] result: Unnapi_valueque representa unArrayBufferde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API devuelve un valor Node-API correspondiente a un ArrayBuffer de JavaScript. Los ArrayBuffer se utilizan para representar búferes de datos binarios de longitud fija. Normalmente se utilizan como búfer de respaldo para objetos TypedArray. El ArrayBuffer asignado tendrá un búfer de bytes subyacente cuyo tamaño está determinado por el parámetro length que se pasa. El búfer subyacente se devuelve opcionalmente al llamador en caso de que el llamador quiera manipular directamente el búfer. Este búfer solo se puede escribir directamente desde código nativo. Para escribir en este búfer desde JavaScript, sería necesario crear una matriz tipificada o un objeto DataView.
Los objetos ArrayBuffer de JavaScript se describen en la Sección 24.1 de la especificación del lenguaje ECMAScript.
napi_create_buffer
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_create_buffer(napi_env env,
size_t size,
void** data,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] size: Tamaño en bytes del búfer subyacente.[out] data: Puntero sin procesar al búfer subyacente.datase puede ignorar opcionalmente pasandoNULL.[out] result: Unnapi_valueque representa unnode::Buffer.
Devuelve napi_ok si la API tuvo éxito.
Esta API asigna un objeto node::Buffer. Si bien esta sigue siendo una estructura de datos totalmente compatible, en la mayoría de los casos será suficiente con utilizar un TypedArray.
napi_create_buffer_copy
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_create_buffer_copy(napi_env env,
size_t length,
const void* data,
void** result_data,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] size: Tamaño en bytes del búfer de entrada (debería ser el mismo que el tamaño del nuevo búfer).[in] data: Puntero sin procesar al búfer subyacente desde el cual copiar.[out] result_data: Puntero al búfer de datos subyacente del nuevoBuffer.result_datase puede ignorar opcionalmente pasandoNULL.[out] result: Unnapi_valueque representa unnode::Buffer.
Devuelve napi_ok si la API tuvo éxito.
Esta API asigna un objeto node::Buffer y lo inicializa con datos copiados del búfer pasado. Si bien esta sigue siendo una estructura de datos totalmente compatible, en la mayoría de los casos será suficiente con utilizar un TypedArray.
napi_create_date
Agregado en: v11.11.0, v10.17.0
Versión N-API: 5
napi_status napi_create_date(napi_env env,
double time,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] time: Valor de tiempo ECMAScript en milisegundos desde el 01 de enero de 1970 UTC.[out] result: Unnapi_valueque representa unDatede JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API no observa los segundos bisiestos; se ignoran, ya que ECMAScript se alinea con la especificación de tiempo POSIX.
Esta API asigna un objeto Date de JavaScript.
Los objetos Date de JavaScript se describen en la Sección 20.3 de la Especificación del Lenguaje ECMAScript.
napi_create_external
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_create_external(napi_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] data: Puntero sin procesar a los datos externos.[in] finalize_cb: Callback opcional que se llamará cuando se recopile el valor externo.napi_finalizeproporciona más detalles.[in] finalize_hint: Pista opcional para pasar a la callback de finalización durante la recopilación.[out] result: Unnapi_valueque representa un valor externo.
Devuelve napi_ok si la API tuvo éxito.
Esta API asigna un valor de JavaScript con datos externos adjuntos. Esto se usa para pasar datos externos a través del código JavaScript, para que el código nativo pueda recuperarlos más tarde usando napi_get_value_external.
La API agrega un callback napi_finalize que se llamará cuando el objeto JavaScript recién creado se haya recolectado como basura.
El valor creado no es un objeto y, por lo tanto, no admite propiedades adicionales. Se considera un tipo de valor distinto: llamar a napi_typeof() con un valor externo produce napi_external.
napi_create_external_arraybuffer
Agregado en: v8.0.0
Versión de N-API: 1
napi_status
napi_create_external_arraybuffer(napi_env env,
void* external_data,
size_t byte_length,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] external_data: Puntero al búfer de bytes subyacente delArrayBuffer.[in] byte_length: La longitud en bytes del búfer subyacente.[in] finalize_cb: Callback opcional para llamar cuando se recolecta elArrayBuffer.napi_finalizeproporciona más detalles.[in] finalize_hint: Sugerencia opcional para pasar al callback de finalización durante la recolección.[out] result: Unnapi_valueque representa unArrayBufferde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Algunos runtimes distintos de Node.js han eliminado el soporte para búferes externos. En runtimes distintos de Node.js, este método puede devolver napi_no_external_buffers_allowed para indicar que no se admiten búferes externos. Un runtime de este tipo es Electron, como se describe en este problema electron/issues/35801.
Para mantener la compatibilidad más amplia con todos los runtimes, puede definir NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED en su complemento antes de las inclusiones para los encabezados de node-api. Al hacerlo, se ocultarán las 2 funciones que crean búferes externos. Esto asegurará que se produzca un error de compilación si accidentalmente utiliza uno de estos métodos.
Esta API devuelve un valor de Node-API correspondiente a un ArrayBuffer de JavaScript. El búfer de bytes subyacente del ArrayBuffer se asigna y gestiona externamente. El llamador debe asegurarse de que el búfer de bytes siga siendo válido hasta que se llame al callback de finalización.
La API añade un callback napi_finalize que se llamará cuando el objeto JavaScript recién creado haya sido recolectado por el recolector de basura.
Los ArrayBuffer de JavaScript se describen en la Sección 24.1 de la Especificación del Lenguaje ECMAScript.
napi_create_external_buffer
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_create_external_buffer(napi_env env,
size_t length,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] length: Tamaño en bytes del búfer de entrada (debe ser el mismo que el tamaño del nuevo búfer).[in] data: Puntero sin formato al búfer subyacente para exponer a JavaScript.[in] finalize_cb: Retrollamada opcional para llamar cuando se está recolectando elArrayBuffer.napi_finalizeproporciona más detalles.[in] finalize_hint: Sugerencia opcional para pasar a la retrollamada de finalización durante la recolección.[out] result: Unnapi_valueque representa unnode::Buffer.
Devuelve napi_ok si la API tuvo éxito.
Algunos tiempos de ejecución distintos de Node.js han eliminado la compatibilidad con los búferes externos. En tiempos de ejecución distintos de Node.js, este método puede devolver napi_no_external_buffers_allowed para indicar que no se admiten los búferes externos. Un tiempo de ejecución de este tipo es Electron, como se describe en este problema electron/issues/35801.
Para mantener la compatibilidad más amplia con todos los tiempos de ejecución, puede definir NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED en su complemento antes de las inclusiones para los encabezados de la API de node. Esto ocultará las 2 funciones que crean búferes externos. Esto asegurará que se produzca un error de compilación si usa accidentalmente uno de estos métodos.
Esta API asigna un objeto node::Buffer y lo inicializa con datos respaldados por el búfer pasado. Si bien esta sigue siendo una estructura de datos totalmente compatible, en la mayoría de los casos, el uso de TypedArray será suficiente.
La API agrega una retrollamada napi_finalize que se llamará cuando el objeto de JavaScript recién creado haya sido recolectado por el recolector de basura.
Para Node.js >=4, los Buffers son Uint8Arrays.
napi_create_object
Añadido en: v8.0.0
Versión de N-API: 1
napi_status napi_create_object(napi_env env, napi_value* result)[in] env: El entorno bajo el que se invoca la API.[out] result: Unnapi_valueque representa unObjectde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API asigna un Object predeterminado de JavaScript. Es el equivalente a hacer new Object() en JavaScript.
El tipo Object de JavaScript se describe en la Sección 6.1.7 de la Especificación del Lenguaje ECMAScript.
napi_create_symbol
Añadido en: v8.0.0
Versión de N-API: 1
napi_status napi_create_symbol(napi_env env,
napi_value description,
napi_value* result)[in] env: El entorno bajo el que se invoca la API.[in] description:napi_valueopcional que hace referencia a unastringde JavaScript para establecerla como descripción del símbolo.[out] result: Unnapi_valueque representa unsymbolde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un valor symbol de JavaScript a partir de una cadena C codificada en UTF8.
El tipo symbol de JavaScript se describe en la Sección 19.4 de la Especificación del Lenguaje ECMAScript.
node_api_symbol_for
Agregado en: v17.5.0, v16.15.0
Versión N-API: 9
napi_status node_api_symbol_for(napi_env env,
const char* utf8description,
size_t length,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] utf8description: Cadena C UTF-8 que representa el texto que se utilizará como descripción para el símbolo.[in] length: La longitud de la cadena de descripción en bytes, oNAPI_AUTO_LENGTHsi termina en nulo.[out] result: Unnapi_valueque representa unsymbolde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API busca en el registro global un símbolo existente con la descripción dada. Si el símbolo ya existe, se devolverá; de lo contrario, se creará un nuevo símbolo en el registro.
El tipo symbol de JavaScript se describe en la Sección 19.4 de la Especificación del Lenguaje ECMAScript.
napi_create_typedarray
Añadido en: v8.0.0
Versión de N-API: 1
napi_status napi_create_typedarray(napi_env env,
napi_typedarray_type type,
size_t length,
napi_value arraybuffer,
size_t byte_offset,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] type: Tipo de datos escalar de los elementos dentro delTypedArray.[in] length: Número de elementos en elTypedArray.[in] arraybuffer:ArrayBuffersubyacente al array con tipo.[in] byte_offset: El desplazamiento en bytes dentro deArrayBufferdesde el cual se comienza a proyectar elTypedArray.[out] result: Unnapi_valueque representa unTypedArrayde JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API crea un objeto TypedArray de JavaScript sobre un ArrayBuffer existente. Los objetos TypedArray proporcionan una vista similar a un array sobre un búfer de datos subyacente donde cada elemento tiene el mismo tipo de datos escalares binarios subyacente.
Es necesario que (longitud * tamaño_de_elemento) + byte_offset sea <= al tamaño en bytes del array pasado. Si no, se genera una excepción RangeError.
Los objetos TypedArray de JavaScript se describen en la Sección 22.2 de la Especificación del Lenguaje ECMAScript.
node_api_create_buffer_from_arraybuffer
Agregado en: v23.0.0
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
napi_value arraybuffer,
size_t byte_offset,
size_t byte_length,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] arraybuffer: ElArrayBuffera partir del cual se creará el búfer.[in] byte_offset: El desplazamiento en bytes dentro delArrayBufferdesde donde se comenzará a crear el búfer.[in] byte_length: La longitud en bytes del búfer que se creará a partir delArrayBuffer.[out] result: Unnapi_valueque representa el objeto JavaScriptBuffercreado.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un objeto JavaScript Buffer a partir de un ArrayBuffer existente. El objeto Buffer es una clase específica de Node.js que proporciona una forma de trabajar con datos binarios directamente en JavaScript.
El rango de bytes [byte_offset, byte_offset + byte_length) debe estar dentro de los límites del ArrayBuffer. Si byte_offset + byte_length excede el tamaño del ArrayBuffer, se genera una excepción RangeError.
napi_create_dataview
Agregado en: v8.3.0
Versión N-API: 1
napi_status napi_create_dataview(napi_env env,
size_t byte_length,
napi_value arraybuffer,
size_t byte_offset,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] length: Número de elementos en elDataView.[in] arraybuffer:ArrayBuffersubyacente alDataView.[in] byte_offset: El desplazamiento de bytes dentro delArrayBufferdesde el cual se comienza a proyectar elDataView.[out] result: Unnapi_valueque representa unDataViewde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un objeto DataView de JavaScript sobre un ArrayBuffer existente. Los objetos DataView proporcionan una vista tipo matriz sobre un búfer de datos subyacente, pero uno que permite elementos de diferente tamaño y tipo en el ArrayBuffer.
Se requiere que byte_length + byte_offset sea menor o igual que el tamaño en bytes de la matriz pasada. Si no, se lanza una excepción RangeError.
Los objetos DataView de JavaScript se describen en la Sección 24.3 de la Especificación del Lenguaje ECMAScript.
Funciones para convertir de tipos C a Node-API
napi_create_int32
Añadido en: v8.4.0
Versión de N-API: 1
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)[in] env: El entorno bajo el que se invoca la API.[in] value: Valor entero que se representará en JavaScript.[out] result: Unnapi_valueque representa unnumberde JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API se utiliza para convertir del tipo C int32_t al tipo number de JavaScript.
El tipo number de JavaScript se describe en la Sección 6.1.6 de la Especificación del Lenguaje ECMAScript.
napi_create_uint32
Añadido en: v8.4.0
Versión de N-API: 1
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)[in] env: El entorno bajo el que se invoca la API.[in] value: Valor entero sin signo que se representará en JavaScript.[out] result: Unnapi_valueque representa unnumberde JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API se utiliza para convertir del tipo C uint32_t al tipo number de JavaScript.
El tipo number de JavaScript se describe en la Sección 6.1.6 de la Especificación del Lenguaje ECMAScript.
napi_create_int64
Agregado en: v8.4.0
Versión N-API: 1
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] value: Valor entero que se representará en JavaScript.[out] result: Unnapi_valueque representa unnumberde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API se utiliza para convertir del tipo C int64_t al tipo number de JavaScript.
El tipo number de JavaScript se describe en la Sección 6.1.6 de la Especificación del Lenguaje ECMAScript. Tenga en cuenta que el rango completo de int64_t no se puede representar con total precisión en JavaScript. Los valores enteros fuera del rango de Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) perderán precisión.
napi_create_double
Agregado en: v8.4.0
Versión N-API: 1
napi_status napi_create_double(napi_env env, double value, napi_value* result)[in] env: El entorno en el que se invoca la API.[in] value: Valor de doble precisión que se representará en JavaScript.[out] result: Unnapi_valueque representa unnumberde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API se utiliza para convertir del tipo double de C al tipo number de JavaScript.
El tipo number de JavaScript se describe en la Sección 6.1.6 de la Especificación del Lenguaje ECMAScript.
napi_create_bigint_int64
Agregado en: v10.7.0
Versión N-API: 6
napi_status napi_create_bigint_int64(napi_env env,
int64_t value,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] value: Valor entero que se representará en JavaScript.[out] result: Unnapi_valueque representa unBigIntde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API convierte el tipo int64_t de C al tipo BigInt de JavaScript.
napi_create_bigint_uint64
Agregado en: v10.7.0
Versión N-API: 6
napi_status napi_create_bigint_uint64(napi_env env,
uint64_t value,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] value: Valor entero sin signo que se representará en JavaScript.[out] result: Unnapi_valueque representa unBigIntde JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API convierte el tipo C uint64_t al tipo BigInt de JavaScript.
napi_create_bigint_words
Agregado en: v10.7.0
Versión N-API: 6
napi_status napi_create_bigint_words(napi_env env,
int sign_bit,
size_t word_count,
const uint64_t* words,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] sign_bit: Determina si elBigIntresultante será positivo o negativo.[in] word_count: La longitud del arraywords.[in] words: Un array de palabras de 64 bits little-endianuint64_t.[out] result: Unnapi_valueque representa unBigIntde JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API convierte un array de palabras sin signo de 64 bits en un único valor BigInt.
El BigInt resultante se calcula como: (–1) (words[0] × (2) + words[1] × (2) + …)
napi_create_string_latin1
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: El entorno bajo el cual se invoca la API.[in] str: Búfer de caracteres que representa una cadena codificada en ISO-8859-1.[in] length: La longitud de la cadena en bytes, oNAPI_AUTO_LENGTHsi termina en nulo.[out] result: Unnapi_valueque representa unstringde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un valor string de JavaScript a partir de una cadena C codificada en ISO-8859-1. La cadena nativa se copia.
El tipo string de JavaScript se describe en la Sección 6.1.4 de la Especificación del Lenguaje ECMAScript.
node_api_create_external_string_latin1
Añadido en: v20.4.0, v18.18.0
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
napi_status
node_api_create_external_string_latin1(napi_env env,
char* str,
size_t length,
napi_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);[in] env: El entorno bajo el cual se invoca la API.[in] str: Búfer de caracteres que representa una cadena codificada en ISO-8859-1.[in] length: La longitud de la cadena en bytes, oNAPI_AUTO_LENGTHsi termina en nulo.[in] finalize_callback: La función a llamar cuando la cadena está siendo recolectada. La función se llamará con los siguientes parámetros:[in] env: El entorno en el que se está ejecutando el complemento. Este valor puede ser nulo si la cadena se está recolectando como parte de la terminación del worker o de la instancia principal de Node.js.[in] data: Este es el valorstrcomo un punterovoid*.[in] finalize_hint: Este es el valorfinalize_hintque se le dio a la API.napi_finalizeproporciona más detalles. Este parámetro es opcional. Pasar un valor nulo significa que el complemento no necesita ser notificado cuando se recolecta la cadena de JavaScript correspondiente.
[in] finalize_hint: Pista opcional para pasar a la devolución de llamada finalize durante la recolección.[out] result: Unnapi_valueque representa unstringde JavaScript.[out] copied: Indica si la cadena se copió. Si lo fue, el finalizador ya habrá sido invocado para destruirstr.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un valor string de JavaScript a partir de una cadena C codificada en ISO-8859-1. Es posible que la cadena nativa no se copie y, por lo tanto, debe existir durante todo el ciclo de vida del valor de JavaScript.
El tipo string de JavaScript se describe en la Sección 6.1.4 de la Especificación del Lenguaje ECMAScript.
napi_create_string_utf16
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] str: Búfer de caracteres que representa una cadena codificada en UTF16-LE.[in] length: La longitud de la cadena en unidades de código de dos bytes, oNAPI_AUTO_LENGTHsi está terminada en nulo.[out] result: Unnapi_valueque representa unastringde JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API crea un valor string de JavaScript a partir de una cadena C codificada en UTF16-LE. La cadena nativa se copia.
El tipo string de JavaScript se describe en la Sección 6.1.4 de la Especificación del Lenguaje ECMAScript.
node_api_create_external_string_utf16
Agregado en: v20.4.0, v18.18.0
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
napi_status
node_api_create_external_string_utf16(napi_env env,
char16_t* str,
size_t length,
napi_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);[in] env: El entorno bajo el cual se invoca la API.[in] str: Búfer de caracteres que representa una cadena codificada en UTF16-LE.[in] length: La longitud de la cadena en unidades de código de dos bytes, oNAPI_AUTO_LENGTHsi está terminada en nulo.[in] finalize_callback: La función a la que llamar cuando se esté recopilando la cadena. Se llamará a la función con los siguientes parámetros:[in] env: El entorno en el que se ejecuta el complemento. Este valor puede ser nulo si la cadena se está recopilando como parte de la terminación del worker o la instancia principal de Node.js.[in] data: Este es el valorstrcomo un punterovoid*.[in] finalize_hint: Este es el valorfinalize_hintque se proporcionó a la API.napi_finalizeproporciona más detalles. Este parámetro es opcional. Pasar un valor nulo significa que no es necesario notificar al complemento cuando se recopile la cadena JavaScript correspondiente.
[in] finalize_hint: Sugerencia opcional para pasar a la callback de finalización durante la recopilación.[out] result: Unnapi_valueque representa unastringde JavaScript.[out] copied: Indica si se copió la cadena. Si se copió, el finalizador ya se habrá invocado para destruirstr.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API crea un valor string de JavaScript a partir de una cadena C codificada en UTF16-LE. Es posible que la cadena nativa no se copie y, por lo tanto, debe existir durante todo el ciclo de vida del valor JavaScript.
El tipo string de JavaScript se describe en la Sección 6.1.4 de la Especificación del Lenguaje ECMAScript.
napi_create_string_utf8
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_create_string_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] str: Búfer de caracteres que representa una cadena codificada en UTF8.[in] length: La longitud de la cadena en bytes, oNAPI_AUTO_LENGTHsi está terminada en nulo.[out] result: Unnapi_valueque representa unastringde JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un valor string de JavaScript a partir de una cadena C codificada en UTF8. La cadena nativa se copia.
El tipo string de JavaScript se describe en la Sección 6.1.4 de la Especificación del Lenguaje ECMAScript.
Funciones para crear claves de propiedad optimizadas
Muchos motores de JavaScript, incluido V8, utilizan cadenas internalizadas como claves para establecer y obtener valores de propiedades. Por lo general, utilizan una tabla hash para crear y buscar dichas cadenas. Si bien agrega un cierto costo por creación de clave, mejora el rendimiento posterior al permitir la comparación de punteros de cadena en lugar de las cadenas completas.
Si se pretende utilizar una nueva cadena de JavaScript como clave de propiedad, entonces, para algunos motores de JavaScript, será más eficiente utilizar las funciones de esta sección. De lo contrario, utilice las funciones de la serie napi_create_string_utf8 o node_api_create_external_string_utf8, ya que puede haber una sobrecarga adicional al crear/almacenar cadenas con los métodos de creación de claves de propiedad.
node_api_create_property_key_latin1
Agregado en: v22.9.0, v20.18.0
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: El entorno bajo el cual se invoca la API.[in] str: Búfer de caracteres que representa una cadena codificada en ISO-8859-1.[in] length: La longitud de la cadena en bytes, oNAPI_AUTO_LENGTHsi está terminada en nulo.[out] result: Unnapi_valueque representa unastringde JavaScript optimizada para ser usada como clave de propiedad para objetos.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un valor string de JavaScript optimizado a partir de una cadena C codificada en ISO-8859-1 para ser usado como clave de propiedad para objetos. La cadena nativa se copia. A diferencia de napi_create_string_latin1, las llamadas posteriores a esta función con el mismo puntero str pueden beneficiarse de una aceleración en la creación del napi_value solicitado, dependiendo del motor.
El tipo string de JavaScript se describe en la Sección 6.1.4 de la Especificación del Lenguaje ECMAScript.
node_api_create_property_key_utf16
Agregado en: v21.7.0, v20.12.0
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result);[in] env: El entorno bajo el cual se invoca la API.[in] str: Búfer de caracteres que representa una cadena codificada en UTF16-LE.[in] length: La longitud de la cadena en unidades de código de dos bytes, oNAPI_AUTO_LENGTHsi está terminada en nulo.[out] result: Unnapi_valueque representa unastringde JavaScript optimizada para ser utilizada como clave de propiedad para objetos.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un valor string de JavaScript optimizado a partir de una cadena C codificada en UTF16-LE para ser utilizado como clave de propiedad para objetos. Se copia la cadena nativa.
El tipo string de JavaScript se describe en la Sección 6.1.4 de la Especificación del Lenguaje ECMAScript.
node_api_create_property_key_utf8
Agregado en: v22.9.0, v20.18.0
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] str: Búfer de caracteres que representa una cadena codificada en UTF8.[in] length: La longitud de la cadena en unidades de código de dos bytes, oNAPI_AUTO_LENGTHsi termina en nulo.[out] result: Unnapi_valueque representa unastringoptimizada de JavaScript para ser utilizada como clave de propiedad para objetos.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un valor string de JavaScript optimizado a partir de una cadena C codificada en UTF8 para ser utilizado como clave de propiedad para objetos. La cadena nativa se copia.
El tipo string de JavaScript se describe en la Sección 6.1.4 de la Especificación del Lenguaje ECMAScript.
Funciones para convertir de Node-API a tipos C
napi_get_array_length
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_array_length(napi_env env,
napi_value value,
uint32_t* result)[in] env: El entorno bajo el cual se invoca la API.[in] value:napi_valueque representa elArrayde JavaScript cuya longitud se está consultando.[out] result:uint32que representa la longitud del array.
Devuelve napi_ok si la API tuvo éxito.
Esta API devuelve la longitud de un array.
La longitud del Array se describe en la Sección 22.1.4.1 de la Especificación del Lenguaje ECMAScript.
napi_get_arraybuffer_info
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_arraybuffer_info(napi_env env,
napi_value arraybuffer,
void** data,
size_t* byte_length)[in] env: El entorno bajo el cual se invoca la API.[in] arraybuffer:napi_valueque representa elArrayBufferque se está consultando.[out] data: El búfer de datos subyacente delArrayBuffer. Si byte_length es0, esto puede serNULLo cualquier otro valor de puntero.[out] byte_length: Longitud en bytes del búfer de datos subyacente.
Devuelve napi_ok si la API tuvo éxito.
Esta API se utiliza para recuperar el búfer de datos subyacente de un ArrayBuffer y su longitud.
ADVERTENCIA: Tenga precaución al utilizar esta API. El ciclo de vida del búfer de datos subyacente es administrado por el ArrayBuffer incluso después de que se devuelve. Una forma segura posible de utilizar esta API es en conjunto con napi_create_reference, que se puede utilizar para garantizar el control sobre el ciclo de vida del ArrayBuffer. También es seguro utilizar el búfer de datos devuelto dentro de la misma devolución de llamada siempre y cuando no haya llamadas a otras API que puedan desencadenar un GC.
napi_get_buffer_info
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_buffer_info(napi_env env,
napi_value value,
void** data,
size_t* length)[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa elnode::BufferoUint8Arrayque se está consultando.[out] data: El búfer de datos subyacente delnode::BufferoUint8Array. Si la longitud es0, esto puede serNULLo cualquier otro valor de puntero.[out] length: Longitud en bytes del búfer de datos subyacente.
Devuelve napi_ok si la API se ejecutó correctamente.
Este método devuelve los mismos data y byte_length que napi_get_typedarray_info. Y napi_get_typedarray_info también acepta un node::Buffer (un Uint8Array) como valor.
Esta API se utiliza para recuperar el búfer de datos subyacente de un node::Buffer y su longitud.
Advertencia: Tenga precaución al usar esta API ya que la vida útil del búfer de datos subyacente no está garantizada si es administrada por la VM.
napi_get_prototype
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_get_prototype(napi_env env,
napi_value object,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] object:napi_valueque representa elObjetode JavaScript cuyo prototipo se va a devolver. Esto devuelve el equivalente deObject.getPrototypeOf(que no es lo mismo que la propiedadprototypede la función).[out] result:napi_valueque representa el prototipo del objeto dado.
Devuelve napi_ok si la API tuvo éxito.
napi_get_typedarray_info
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_get_typedarray_info(napi_env env,
napi_value typedarray,
napi_typedarray_type* type,
size_t* length,
void** data,
napi_value* arraybuffer,
size_t* byte_offset)[in] env: El entorno bajo el cual se invoca la API.[in] typedarray:napi_valueque representa elTypedArraycuyas propiedades se van a consultar.[out] type: Tipo de datos escalares de los elementos dentro delTypedArray.[out] length: El número de elementos en elTypedArray.[out] data: El búfer de datos subyacente alTypedArrayajustado por el valorbyte_offsetde manera que apunte al primer elemento en elTypedArray. Si la longitud del array es0, esto puede serNULLo cualquier otro valor de puntero.[out] arraybuffer: ElArrayBuffersubyacente alTypedArray.[out] byte_offset: El desplazamiento de bytes dentro del array nativo subyacente en el que se encuentra el primer elemento de los arrays. El valor del parámetro de datos ya se ha ajustado para que los datos apunten al primer elemento del array. Por lo tanto, el primer byte del array nativo estaría endata - byte_offset.
Devuelve napi_ok si la API tuvo éxito.
Esta API devuelve varias propiedades de un array tipado.
Cualquiera de los parámetros de salida puede ser NULL si esa propiedad no es necesaria.
Advertencia: Tenga cuidado al usar esta API ya que el búfer de datos subyacente es gestionado por la VM.
napi_get_dataview_info
Añadido en: v8.3.0
Versión N-API: 1
napi_status napi_get_dataview_info(napi_env env,
napi_value dataview,
size_t* byte_length,
void** data,
napi_value* arraybuffer,
size_t* byte_offset)[in] env: El entorno en el que se invoca la API.[in] dataview:napi_valueque representa elDataViewcuyas propiedades se consultarán.[out] byte_length: Número de bytes en elDataView.[out] data: El búfer de datos subyacente alDataView. Si byte_length es0, esto puede serNULLo cualquier otro valor de puntero.[out] arraybuffer:ArrayBuffersubyacente alDataView.[out] byte_offset: El desplazamiento de bytes dentro del búfer de datos desde el cual comenzar a proyectar elDataView.
Devuelve napi_ok si la API se ejecutó correctamente.
Cualquiera de los parámetros de salida puede ser NULL si esa propiedad no es necesaria.
Esta API devuelve varias propiedades de un DataView.
napi_get_date_value
Añadido en: v11.11.0, v10.17.0
Versión N-API: 5
napi_status napi_get_date_value(napi_env env,
napi_value value,
double* result)[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa unDatede JavaScript.[out] result: Valor de tiempo como undoublerepresentado en milisegundos desde la medianoche al comienzo del 01 de enero de 1970 UTC.
Esta API no tiene en cuenta los segundos intercalares; se ignoran, ya que ECMAScript se alinea con la especificación de tiempo POSIX.
Devuelve napi_ok si la API se ejecutó correctamente. Si se pasa un napi_value que no es una fecha, devuelve napi_date_expected.
Esta API devuelve el valor primitivo C double del valor de tiempo para el Date de JavaScript dado.
napi_get_value_bool
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa unBooleande JavaScript.[out] result: Primitiva booleana C equivalente alBooleande JavaScript dado.
Devuelve napi_ok si la API se ejecutó correctamente. Si se pasa un napi_value que no es booleano, devuelve napi_boolean_expected.
Esta API devuelve la primitiva booleana C equivalente al Boolean de JavaScript dado.
napi_get_value_double
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_value_double(napi_env env,
napi_value value,
double* result)[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa unnumberde JavaScript.[out] result: Primitiva C double equivalente alnumberde JavaScript dado.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un napi_value que no es un número, devuelve napi_number_expected.
Esta API devuelve la primitiva C double equivalente al number de JavaScript dado.
napi_get_value_bigint_int64
Agregado en: v10.7.0
Versión N-API: 6
napi_status napi_get_value_bigint_int64(napi_env env,
napi_value value,
int64_t* result,
bool* lossless);[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa unBigIntde JavaScript.[out] result: Primitiva Cint64_tequivalente alBigIntde JavaScript dado.[out] lossless: Indica si el valor deBigIntse convirtió sin pérdida de información.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un valor que no es BigInt, devuelve napi_bigint_expected.
Esta API devuelve la primitiva C int64_t equivalente al BigInt de JavaScript dado. Si es necesario, truncará el valor, estableciendo lossless en false.
napi_get_value_bigint_uint64
Añadido en: v10.7.0
Versión N-API: 6
napi_status napi_get_value_bigint_uint64(napi_env env,
napi_value value,
uint64_t* result,
bool* lossless);[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa unBigIntde JavaScript.[out] result: Primitivauint64_tde C equivalente alBigIntde JavaScript dado.[out] lossless: Indica si el valorBigIntse convirtió sin pérdida.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un valor que no es BigInt, devuelve napi_bigint_expected.
Esta API devuelve la primitiva uint64_t de C equivalente al BigInt de JavaScript dado. Si es necesario, truncará el valor, estableciendo lossless en false.
napi_get_value_bigint_words
Añadido en: v10.7.0
Versión N-API: 6
napi_status napi_get_value_bigint_words(napi_env env,
napi_value value,
int* sign_bit,
size_t* word_count,
uint64_t* words);[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa unBigIntde JavaScript.[out] sign_bit: Entero que representa si elBigIntde JavaScript es positivo o negativo.[in/out] word_count: Debe inicializarse con la longitud de la matrizwords. Al regresar, se establecerá en el número real de palabras que se necesitarían para almacenar esteBigInt.[out] words: Puntero a una matriz de palabras de 64 bits preasignada.
Devuelve napi_ok si la API tuvo éxito.
Esta API convierte un único valor BigInt en un bit de signo, una matriz little-endian de 64 bits y el número de elementos en la matriz. sign_bit y words pueden establecerse ambos en NULL, para obtener solo word_count.
napi_get_value_external
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_value_external(napi_env env,
napi_value value,
void** result)[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa un valor externo de JavaScript.[out] result: Puntero a los datos envueltos por el valor externo de JavaScript.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un napi_value no externo, devuelve napi_invalid_arg.
Esta API recupera el puntero de datos externos que se pasó previamente a napi_create_external().
napi_get_value_int32
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_value_int32(napi_env env,
napi_value value,
int32_t* result)[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa unnumberde JavaScript.[out] result: Primitiva Cint32equivalente alnumberde JavaScript dado.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un napi_value que no es un número, devuelve napi_number_expected.
Esta API devuelve la primitiva C int32 equivalente al number de JavaScript dado.
Si el número excede el rango del entero de 32 bits, el resultado se trunca al equivalente de los 32 bits inferiores. Esto puede resultar en que un número positivo grande se convierta en un número negativo si el valor es > 231 - 1.
Los valores de número no finitos (NaN, +Infinity o -Infinity) establecen el resultado en cero.
napi_get_value_int64
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_value_int64(napi_env env,
napi_value value,
int64_t* result)[in] env: El entorno bajo el cual se invoca la API.[in] value:napi_valueque representa unnumberde JavaScript.[out] result: Primitiva Cint64equivalente alnumberde JavaScript dado.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un napi_value que no es un número, devuelve napi_number_expected.
Esta API devuelve la primitiva C int64 equivalente al number de JavaScript dado.
Los valores number fuera del rango de Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) perderán precisión.
Los valores numéricos no finitos (NaN, +Infinity o -Infinity) establecen el resultado en cero.
napi_get_value_string_latin1
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_value_string_latin1(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result)[in] env: El entorno bajo el cual se invoca la API.[in] value:napi_valueque representa una cadena de JavaScript.[in] buf: Búfer en el que escribir la cadena codificada en ISO-8859-1. Si se pasaNULL, la longitud de la cadena en bytes, excluyendo el terminador nulo, se devuelve enresult.[in] bufsize: Tamaño del búfer de destino. Cuando este valor es insuficiente, la cadena devuelta se trunca y se termina con un nulo.[out] result: Número de bytes copiados en el búfer, excluyendo el terminador nulo.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un napi_value que no es string, devuelve napi_string_expected.
Esta API devuelve la cadena codificada en ISO-8859-1 correspondiente al valor pasado.
napi_get_value_string_utf8
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_value_string_utf8(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result)[in] env: El entorno bajo el cual se invoca la API.[in] value:napi_valueque representa una cadena de JavaScript.[in] buf: Búfer en el que se escribirá la cadena codificada en UTF8. Si se pasaNULL, la longitud de la cadena en bytes, excluyendo el terminador nulo, se devuelve enresult.[in] bufsize: Tamaño del búfer de destino. Cuando este valor es insuficiente, la cadena devuelta se trunca y se termina en nulo.[out] result: Número de bytes copiados en el búfer, excluyendo el terminador nulo.
Devuelve napi_ok si la API se completó correctamente. Si se pasa un napi_value que no es string, devuelve napi_string_expected.
Esta API devuelve la cadena codificada en UTF8 correspondiente al valor pasado.
napi_get_value_string_utf16
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_get_value_string_utf16(napi_env env,
napi_value value,
char16_t* buf,
size_t bufsize,
size_t* result)[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa una cadena de JavaScript.[in] buf: Búfer en el que se escribirá la cadena codificada en UTF16-LE. Si se pasaNULL, se devuelve la longitud de la cadena en unidades de código de 2 bytes y excluyendo el terminador nulo.[in] bufsize: Tamaño del búfer de destino. Cuando este valor es insuficiente, la cadena devuelta se trunca y termina en nulo.[out] result: Número de unidades de código de 2 bytes copiadas en el búfer, excluyendo el terminador nulo.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un napi_value que no es de tipo string, devuelve napi_string_expected.
Esta API devuelve la cadena codificada en UTF16 correspondiente al valor pasado.
napi_get_value_uint32
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_value_uint32(napi_env env,
napi_value value,
uint32_t* result)[in] env: El entorno en el que se invoca la API.[in] value:napi_valueque representa unnumberde JavaScript.[out] result: Primitiva C equivalente alnapi_valuedado como unuint32_t.
Devuelve napi_ok si la API tuvo éxito. Si se pasa un napi_value que no es un número, devuelve napi_number_expected.
Esta API devuelve la primitiva C equivalente al napi_value dado como un uint32_t.
Funciones para obtener instancias globales
napi_get_boolean
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor booleano que se va a recuperar.[out] result:napi_valueque representa el singletonBooleande JavaScript que se va a recuperar.
Devuelve napi_ok si la API tuvo éxito.
Esta API se utiliza para devolver el objeto singleton de JavaScript que se usa para representar el valor booleano dado.
napi_get_global
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_get_global(napi_env env, napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[out] result:napi_valueque representa el objetoglobalde JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API devuelve el objeto global.
napi_get_null
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_get_null(napi_env env, napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[out] result:napi_valueque representa el objetonullde JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API devuelve el objeto null.
napi_get_undefined
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_get_undefined(napi_env env, napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[out] result:napi_valueque representa el valor Undefined de JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API devuelve el objeto Undefined.
Trabajar con valores de JavaScript y operaciones abstractas
Node-API expone un conjunto de APIs para realizar algunas operaciones abstractas sobre valores de JavaScript. Algunas de estas operaciones están documentadas en la Sección 7 de la Especificación del Lenguaje ECMAScript.
Estas APIs permiten realizar una de las siguientes acciones:
napi_coerce_to_bool
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_coerce_to_bool(napi_env env,
napi_value value,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript a coaccionar.[out] result:napi_valueque representa elBooleande JavaScript coaccionado.
Devuelve napi_ok si la API se ha ejecutado correctamente.
Esta API implementa la operación abstracta ToBoolean() tal y como se define en la Sección 7.1.2 de la Especificación del Lenguaje ECMAScript.
napi_coerce_to_number
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_coerce_to_number(napi_env env,
napi_value value,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript que se va a forzar.[out] result:napi_valueque representa elnumberde JavaScript forzado.
Devuelve napi_ok si la API tuvo éxito.
Esta API implementa la operación abstracta ToNumber() como se define en la Sección 7.1.3 de la Especificación del Lenguaje ECMAScript. Esta función potencialmente ejecuta código JS si el valor pasado es un objeto.
napi_coerce_to_object
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_coerce_to_object(napi_env env,
napi_value value,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript que se va a forzar.[out] result:napi_valueque representa elObjectde JavaScript forzado.
Devuelve napi_ok si la API tuvo éxito.
Esta API implementa la operación abstracta ToObject() como se define en la Sección 7.1.13 de la Especificación del Lenguaje ECMAScript.
napi_coerce_to_string
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_coerce_to_string(napi_env env,
napi_value value,
napi_value* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript a coaccionar.[out] result:napi_valueque representa lastringde JavaScript coaccionada.
Devuelve napi_ok si la API tuvo éxito.
Esta API implementa la operación abstracta ToString() como se define en la Sección 7.1.13 de la Especificación del Lenguaje ECMAScript. Esta función potencialmente ejecuta código JS si el valor pasado es un objeto.
napi_typeof
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript cuyo tipo se va a consultar.[out] result: El tipo del valor de JavaScript.
Devuelve napi_ok si la API tuvo éxito.
napi_invalid_argsi el tipo devalueno es un tipo ECMAScript conocido yvalueno es un valor External.
Esta API representa un comportamiento similar a invocar el operador typeof en el objeto como se define en la Sección 12.5.5 de la Especificación del Lenguaje ECMAScript. Sin embargo, existen algunas diferencias:
Si value tiene un tipo que no es válido, se devuelve un error.
napi_instanceof
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_instanceof(napi_env env,
napi_value object,
napi_value constructor,
bool* result)[in] env: El entorno bajo el cual se invoca la API.[in] object: El valor de JavaScript que se va a comprobar.[in] constructor: El objeto de función JavaScript de la función constructora contra la que se va a comprobar.[out] result: Booleano que se establece en verdadero siobject instanceof constructores verdadero.
Devuelve napi_ok si la API tuvo éxito.
Esta API representa la invocación del operador instanceof en el objeto tal como se define en la Sección 12.10.4 de la Especificación del Lenguaje ECMAScript.
napi_is_array
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_is_array(napi_env env, napi_value value, bool* result)[in] env: El entorno bajo el cual se invoca la API.[in] value: El valor de JavaScript que se va a comprobar.[out] result: Indica si el objeto dado es un array.
Devuelve napi_ok si la API tuvo éxito.
Esta API representa la invocación de la operación IsArray en el objeto tal como se define en la Sección 7.2.2 de la Especificación del Lenguaje ECMAScript.
napi_is_arraybuffer
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript a verificar.[out] result: Indica si el objeto dado es unArrayBuffer.
Devuelve napi_ok si la API tuvo éxito.
Esta API verifica si el Object pasado es un array buffer.
napi_is_buffer
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript a verificar.[out] result: Indica si elnapi_valuedado representa un objetonode::BufferoUint8Array.
Devuelve napi_ok si la API tuvo éxito.
Esta API verifica si el Object pasado es un buffer o Uint8Array. Se debe preferir napi_is_typedarray si el llamador necesita verificar si el valor es un Uint8Array.
napi_is_date
Agregado en: v11.11.0, v10.17.0
Versión N-API: 5
napi_status napi_is_date(napi_env env, napi_value value, bool* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript que se va a comprobar.[out] result: Indica si elnapi_valuedado representa un objetoDatede JavaScript.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API comprueba si el Object pasado es una fecha.
napi_is_error
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_is_error(napi_env env, napi_value value, bool* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript que se va a comprobar.[out] result: Indica si elnapi_valuedado representa un objetoError.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API comprueba si el Object pasado es un Error.
napi_is_typedarray
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)[in] env: El entorno en el que se invoca la API.[in] value: El valor de JavaScript que se va a comprobar.[out] result: Indica si elnapi_valuedado representa unTypedArray.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API comprueba si el Object pasado es un array con tipo.
napi_is_dataview
Agregado en: v8.3.0
Versión de N-API: 1
napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)[in] env: El entorno bajo el cual se invoca la API.[in] value: El valor de JavaScript a verificar.[out] result: Indica si elnapi_valuedado representa unDataView.
Devuelve napi_ok si la API tuvo éxito.
Esta API comprueba si el Object pasado es un DataView.
napi_strict_equals
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_strict_equals(napi_env env,
napi_value lhs,
napi_value rhs,
bool* result)[in] env: El entorno bajo el cual se invoca la API.[in] lhs: El valor de JavaScript a verificar.[in] rhs: El valor de JavaScript contra el que se verifica.[out] result: Indica si los dos objetosnapi_valueson iguales.
Devuelve napi_ok si la API tuvo éxito.
Esta API representa la invocación del algoritmo de Igualdad Estricta como se define en la Sección 7.2.14 de la Especificación del Lenguaje ECMAScript.
napi_detach_arraybuffer
Agregado en: v13.0.0, v12.16.0, v10.22.0
Versión de N-API: 7
napi_status napi_detach_arraybuffer(napi_env env,
napi_value arraybuffer)[in] env: El entorno en el que se invoca la API.[in] arraybuffer: ElArrayBufferde JavaScript que se va a separar.
Devuelve napi_ok si la API se ejecutó correctamente. Si se pasa un ArrayBuffer no separable, devuelve napi_detachable_arraybuffer_expected.
Generalmente, un ArrayBuffer no es separable si se ha separado antes. El motor puede imponer condiciones adicionales sobre si un ArrayBuffer es separable. Por ejemplo, V8 requiere que el ArrayBuffer sea externo, es decir, creado con napi_create_external_arraybuffer.
Esta API representa la invocación de la operación de separación de ArrayBuffer tal como se define en Sección 24.1.1.3 de la Especificación del Lenguaje ECMAScript.
napi_is_detached_arraybuffer
Agregado en: v13.3.0, v12.16.0, v10.22.0
Versión N-API: 7
napi_status napi_is_detached_arraybuffer(napi_env env,
napi_value arraybuffer,
bool* result)[in] env: El entorno en el que se invoca la API.[in] arraybuffer: ElArrayBufferde JavaScript que se va a verificar.[out] result: Indica si elarraybufferestá desasociado.
Devuelve napi_ok si la API se ejecutó correctamente.
Se considera que ArrayBuffer está desasociado si sus datos internos son null.
Esta API representa la invocación de la operación IsDetachedBuffer de ArrayBuffer, tal como se define en Sección 24.1.1.2 de la Especificación del lenguaje ECMAScript.
Trabajando con propiedades de JavaScript
Node-API expone un conjunto de API para obtener y establecer propiedades en objetos de JavaScript. Algunos de estos tipos están documentados en la Sección 7 de la Especificación del lenguaje ECMAScript.
Las propiedades en JavaScript se representan como una tupla de una clave y un valor. Fundamentalmente, todas las claves de propiedad en Node-API se pueden representar de una de las siguientes formas:
- Con nombre: una simple cadena codificada en UTF8
- Indexada por enteros: un valor de índice representado por
uint32_t - Valor de JavaScript: estos están representados en Node-API por
napi_value. Esto puede ser unnapi_valueque representa unacadena, unnúmeroo unsímbolo.
Los valores de Node-API están representados por el tipo napi_value. Cualquier llamada a Node-API que requiera un valor de JavaScript toma un napi_value. Sin embargo, es responsabilidad del llamador asegurarse de que el napi_value en cuestión sea del tipo de JavaScript esperado por la API.
Las API documentadas en esta sección proporcionan una interfaz simple para obtener y establecer propiedades en objetos arbitrarios de JavaScript representados por napi_value.
Por ejemplo, considere el siguiente fragmento de código de JavaScript:
const obj = {}
obj.myProp = 123El equivalente se puede hacer usando valores de Node-API con el siguiente fragmento:
napi_status status = napi_generic_failure;
// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Create a napi_value for 123
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;
// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status;Las propiedades indexadas se pueden establecer de manera similar. Considere el siguiente fragmento de JavaScript:
const arr = []
arr[123] = 'hello'El equivalente se puede hacer usando valores de Node-API con el siguiente fragmento:
napi_status status = napi_generic_failure;
// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// Create a napi_value for 'hello'
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;
// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status;Las propiedades se pueden recuperar utilizando las API descritas en esta sección. Considere el siguiente fragmento de JavaScript:
const arr = []
const value = arr[123]El siguiente es el equivalente aproximado de la contraparte de Node-API:
napi_status status = napi_generic_failure;
// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status;Finalmente, también se pueden definir múltiples propiedades en un objeto por razones de rendimiento. Considere el siguiente JavaScript:
const obj = {}
Object.defineProperties(obj, {
foo: { value: 123, writable: true, configurable: true, enumerable: true },
bar: { value: 456, writable: true, configurable: true, enumerable: true },
})El siguiente es el equivalente aproximado de la contraparte de Node-API:
napi_status status = napi_status_generic_failure;
// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Create napi_values for 123 and 456
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;
// Set the properties
napi_property_descriptor descriptors[] = {
{ "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
{ "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
obj,
sizeof(descriptors) / sizeof(descriptors[0]),
descriptors);
if (status != napi_ok) return status;Estructuras
napi_property_attributes
[Historial]
| Versión | Cambios |
|---|---|
| v14.12.0 | se agregaron napi_default_method y napi_default_property. |
typedef enum {
napi_default = 0,
napi_writable = 1 << 0,
napi_enumerable = 1 << 1,
napi_configurable = 1 << 2,
// Se usa con napi_define_class para distinguir las propiedades estáticas
// de las propiedades de instancia. Es ignorado por napi_define_properties.
napi_static = 1 << 10,
// Predeterminado para los métodos de clase.
napi_default_method = napi_writable | napi_configurable,
// Predeterminado para las propiedades de objetos, como en JS obj[prop].
napi_default_jsproperty = napi_writable |
napi_enumerable |
napi_configurable,
} napi_property_attributes;napi_property_attributes son flags que se utilizan para controlar el comportamiento de las propiedades establecidas en un objeto JavaScript. Aparte de napi_static, corresponden a los atributos enumerados en la Sección 6.1.7.1 de la Especificación del Lenguaje ECMAScript. Pueden ser uno o más de los siguientes bitflags:
napi_default: No se establecen atributos explícitos en la propiedad. De forma predeterminada, una propiedad es de solo lectura, no enumerable y no configurable.napi_writable: La propiedad se puede escribir.napi_enumerable: La propiedad es enumerable.napi_configurable: La propiedad es configurable como se define en la Sección 6.1.7.1 de la Especificación del Lenguaje ECMAScript.napi_static: La propiedad se definirá como una propiedad estática en una clase en lugar de una propiedad de instancia, que es el valor predeterminado. Esto solo lo utilizanapi_define_class.napi_define_propertieslo ignora.napi_default_method: Como un método en una clase JS, la propiedad es configurable y se puede escribir, pero no es enumerable.napi_default_jsproperty: Como una propiedad establecida mediante una asignación en JavaScript, la propiedad se puede escribir, es enumerable y es configurable.
napi_property_descriptor
typedef struct {
// Uno de utf8name o name debería ser NULL.
const char* utf8name;
napi_value name;
napi_callback method;
napi_callback getter;
napi_callback setter;
napi_value value;
napi_property_attributes attributes;
void* data;
} napi_property_descriptor;utf8name: Cadena opcional que describe la clave de la propiedad, codificada como UTF8. Se debe proporcionar una deutf8nameonamepara la propiedad.name:napi_valueopcional que apunta a una cadena o símbolo de JavaScript que se utilizará como clave para la propiedad. Se debe proporcionar una deutf8nameonamepara la propiedad.value: El valor que se recupera mediante un acceso de lectura a la propiedad si la propiedad es una propiedad de datos. Si se pasa esto, establezcagetter,setter,methodydataenNULL(ya que estos miembros no se usarán).getter: Una función para llamar cuando se realiza un acceso de lectura a la propiedad. Si se pasa esto, establezcavalueymethodenNULL(ya que estos miembros no se usarán). La función dada se llama implícitamente por el tiempo de ejecución cuando se accede a la propiedad desde código JavaScript (o si se realiza una lectura en la propiedad mediante una llamada a Node-API).napi_callbackproporciona más detalles.setter: Una función para llamar cuando se realiza un acceso de escritura a la propiedad. Si se pasa esto, establezcavalueymethodenNULL(ya que estos miembros no se usarán). La función dada se llama implícitamente por el tiempo de ejecución cuando se establece la propiedad desde código JavaScript (o si se realiza una escritura en la propiedad mediante una llamada a Node-API).napi_callbackproporciona más detalles.method: Establezca esto para hacer que la propiedadvaluedel objeto descriptor de propiedad sea una función JavaScript representada pormethod. Si se pasa esto, establezcavalue,getterysetterenNULL(ya que estos miembros no se usarán).napi_callbackproporciona más detalles.attributes: Los atributos asociados con la propiedad particular. Consultenapi_property_attributes.data: Los datos de devolución de llamada pasados amethod,getterysettersi se invoca esta función.
Funciones
napi_get_property_names
Añadido en: v8.0.0
Versión de N-API: 1
napi_status napi_get_property_names(napi_env env,
napi_value object,
napi_value* result);[in] env: El entorno en el que se invoca la llamada a Node-API.[in] object: El objeto del que se van a recuperar las propiedades.[out] result: Unnapi_valueque representa un arreglo de valores de JavaScript que representan los nombres de las propiedades del objeto. La API se puede usar para iterar sobreresultusandonapi_get_array_lengthynapi_get_element.
Devuelve napi_ok si la API tuvo éxito.
Esta API devuelve los nombres de las propiedades enumerables de object como un arreglo de cadenas. Las propiedades de object cuya clave sea un símbolo no se incluirán.
napi_get_all_property_names
Añadido en: v13.7.0, v12.17.0, v10.20.0
Versión de N-API: 6
napi_get_all_property_names(napi_env env,
napi_value object,
napi_key_collection_mode key_mode,
napi_key_filter key_filter,
napi_key_conversion key_conversion,
napi_value* result);[in] env: El entorno en el que se invoca la llamada a Node-API.[in] object: El objeto del que se van a recuperar las propiedades.[in] key_mode: Si también se deben recuperar las propiedades del prototipo.[in] key_filter: Qué propiedades se deben recuperar (enumerables/legibles/escribibles).[in] key_conversion: Si se deben convertir las claves de propiedades numeradas a cadenas.[out] result: Unnapi_valueque representa un arreglo de valores de JavaScript que representan los nombres de las propiedades del objeto. Se pueden usarnapi_get_array_lengthynapi_get_elementpara iterar sobreresult.
Devuelve napi_ok si la API tuvo éxito.
Esta API devuelve un arreglo que contiene los nombres de las propiedades disponibles de este objeto.
napi_set_property
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_set_property(napi_env env,
napi_value object,
napi_value key,
napi_value value);[in] env: El entorno en el que se invoca la llamada a Node-API.[in] object: El objeto en el que se establecerá la propiedad.[in] key: El nombre de la propiedad a establecer.[in] value: El valor de la propiedad.
Devuelve napi_ok si la API tuvo éxito.
Esta API establece una propiedad en el Object pasado.
napi_get_property
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_get_property(napi_env env,
napi_value object,
napi_value key,
napi_value* result);[in] env: El entorno en el que se invoca la llamada a Node-API.[in] object: El objeto del que se recuperará la propiedad.[in] key: El nombre de la propiedad a recuperar.[out] result: El valor de la propiedad.
Devuelve napi_ok si la API tuvo éxito.
Esta API obtiene la propiedad solicitada del Object pasado.
napi_has_property
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_has_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: El entorno en el que se invoca la llamada Node-API.[in] object: El objeto a consultar.[in] key: El nombre de la propiedad cuya existencia se va a comprobar.[out] result: Indica si la propiedad existe en el objeto o no.
Devuelve napi_ok si la API tuvo éxito.
Esta API comprueba si el Object pasado tiene la propiedad nombrada.
napi_delete_property
Agregado en: v8.2.0
Versión N-API: 1
napi_status napi_delete_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: El entorno en el que se invoca la llamada Node-API.[in] object: El objeto a consultar.[in] key: El nombre de la propiedad a eliminar.[out] result: Indica si la eliminación de la propiedad tuvo éxito o no.resultpuede ignorarse opcionalmente pasandoNULL.
Devuelve napi_ok si la API tuvo éxito.
Esta API intenta eliminar la propiedad propia key del object.
napi_has_own_property
Añadido en: v8.2.0
Versión N-API: 1
napi_status napi_has_own_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: El entorno bajo el que se invoca la llamada a la API de Node.[in] object: El objeto a consultar.[in] key: El nombre de la propiedad propia cuya existencia se va a comprobar.[out] result: Indica si la propiedad propia existe en el objeto o no.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API comprueba si el Object pasado tiene la propiedad propia con el nombre dado. key debe ser una string o un symbol, o se generará un error. Node-API no realizará ninguna conversión entre tipos de datos.
napi_set_named_property
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_set_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value value);[in] env: El entorno bajo el que se invoca la llamada a la API de Node.[in] object: El objeto en el que se va a establecer la propiedad.[in] utf8Name: El nombre de la propiedad que se va a establecer.[in] value: El valor de la propiedad.
Devuelve napi_ok si la API se ejecutó correctamente.
Este método es equivalente a llamar a napi_set_property con un napi_value creado a partir de la cadena pasada como utf8Name.
napi_get_named_property
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_get_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value* result);[in] env: El entorno bajo el cual se invoca la llamada a Node-API.[in] object: El objeto del cual se debe recuperar la propiedad.[in] utf8Name: El nombre de la propiedad a obtener.[out] result: El valor de la propiedad.
Devuelve napi_ok si la API tuvo éxito.
Este método es equivalente a llamar a napi_get_property con un napi_value creado a partir de la cadena pasada como utf8Name.
napi_has_named_property
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_has_named_property(napi_env env,
napi_value object,
const char* utf8Name,
bool* result);[in] env: El entorno bajo el cual se invoca la llamada a Node-API.[in] object: El objeto a consultar.[in] utf8Name: El nombre de la propiedad cuya existencia se debe verificar.[out] result: Indica si la propiedad existe en el objeto o no.
Devuelve napi_ok si la API tuvo éxito.
Este método es equivalente a llamar a napi_has_property con un napi_value creado a partir de la cadena pasada como utf8Name.
napi_set_element
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_set_element(napi_env env,
napi_value object,
uint32_t index,
napi_value value);[in] env: El entorno bajo el cual se invoca la llamada a la API de Node.[in] object: El objeto del cual se establecen las propiedades.[in] index: El índice de la propiedad que se va a establecer.[in] value: El valor de la propiedad.
Devuelve napi_ok si la API tuvo éxito.
Esta API establece un elemento en el Objeto pasado.
napi_get_element
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_get_element(napi_env env,
napi_value object,
uint32_t index,
napi_value* result);[in] env: El entorno bajo el cual se invoca la llamada a la API de Node.[in] object: El objeto del cual se recupera la propiedad.[in] index: El índice de la propiedad a obtener.[out] result: El valor de la propiedad.
Devuelve napi_ok si la API tuvo éxito.
Esta API obtiene el elemento en el índice solicitado.
napi_has_element
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_has_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);[in] env: El entorno en el que se invoca la llamada Node-API.[in] object: El objeto a consultar.[in] index: El índice de la propiedad cuya existencia se va a comprobar.[out] result: Indica si la propiedad existe en el objeto o no.
Devuelve napi_ok si la API tuvo éxito.
Esta API devuelve si el Objeto pasado tiene un elemento en el índice solicitado.
napi_delete_element
Agregado en: v8.2.0
Versión N-API: 1
napi_status napi_delete_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);[in] env: El entorno en el que se invoca la llamada Node-API.[in] object: El objeto a consultar.[in] index: El índice de la propiedad a eliminar.[out] result: Indica si la eliminación del elemento tuvo éxito o no.resultse puede ignorar opcionalmente pasandoNULL.
Devuelve napi_ok si la API tuvo éxito.
Esta API intenta eliminar el índice especificado del objeto.
napi_define_properties
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_define_properties(napi_env env,
napi_value object,
size_t property_count,
const napi_property_descriptor* properties);[in] env: El entorno en el que se invoca la llamada a Node-API.[in] object: El objeto del cual recuperar las propiedades.[in] property_count: El número de elementos en el arrayproperties.[in] properties: El array de descriptores de propiedad.
Devuelve napi_ok si la API tuvo éxito.
Este método permite la definición eficiente de múltiples propiedades en un objeto dado. Las propiedades se definen usando descriptores de propiedad (ver napi_property_descriptor). Dado un array de tales descriptores de propiedad, esta API establecerá las propiedades en el objeto una a la vez, como se define en DefineOwnProperty() (descrito en la Sección 9.1.6 de la especificación ECMA-262).
napi_object_freeze
Agregado en: v14.14.0, v12.20.0
Versión de N-API: 8
napi_status napi_object_freeze(napi_env env,
napi_value object);[in] env: El entorno bajo el cual se invoca la llamada a Node-API.[in] object: El objeto a congelar.
Devuelve napi_ok si la API tuvo éxito.
Este método congela un objeto dado. Esto evita que se agreguen nuevas propiedades, que se eliminen las propiedades existentes, evita cambiar la enumerabilidad, la configurabilidad o la capacidad de escritura de las propiedades existentes y evita que se cambien los valores de las propiedades existentes. También evita que se cambie el prototipo del objeto. Esto se describe en la Sección 19.1.2.6 de la especificación ECMA-262.
napi_object_seal
Agregado en: v14.14.0, v12.20.0
Versión de N-API: 8
napi_status napi_object_seal(napi_env env,
napi_value object);[in] env: El entorno bajo el cual se invoca la llamada a Node-API.[in] object: El objeto a sellar.
Devuelve napi_ok si la API tuvo éxito.
Este método sella un objeto dado. Esto evita que se agreguen nuevas propiedades, además de marcar todas las propiedades existentes como no configurables. Esto se describe en la Sección 19.1.2.20 de la especificación ECMA-262.
Trabajar con funciones de JavaScript
Node-API proporciona un conjunto de API que permiten que el código de JavaScript realice llamadas de vuelta al código nativo. Las API de Node que admiten llamadas de vuelta al código nativo aceptan funciones de devolución de llamada representadas por el tipo napi_callback. Cuando la MV de JavaScript llama de vuelta al código nativo, se invoca la función napi_callback proporcionada. Las API documentadas en esta sección permiten que la función de devolución de llamada haga lo siguiente:
- Obtener información sobre el contexto en el que se invocó la devolución de llamada.
- Obtener los argumentos pasados a la devolución de llamada.
- Devolver un
napi_valuedesde la devolución de llamada.
Además, Node-API proporciona un conjunto de funciones que permiten llamar a funciones de JavaScript desde código nativo. Se puede llamar a una función como una llamada de función de JavaScript regular, o como una función constructora.
Cualquier dato no NULL que se pase a esta API a través del campo data de los elementos napi_property_descriptor puede asociarse con object y liberarse cada vez que object sea recolectado por el recolector de basura pasando tanto object como los datos a napi_add_finalizer.
napi_call_function
Agregado en: v8.0.0
Versión de N-API: 1
NAPI_EXTERN napi_status napi_call_function(napi_env env,
napi_value recv,
napi_value func,
size_t argc,
const napi_value* argv,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] recv: El valorthispasado a la función llamada.[in] func:napi_valueque representa la función de JavaScript que se va a invocar.[in] argc: El recuento de elementos en el arrayargv.[in] argv: Array denapi_valuesque representan valores de JavaScript que se pasan como argumentos a la función.[out] result:napi_valueque representa el objeto de JavaScript devuelto.
Devuelve napi_ok si la API se ejecutó correctamente.
Este método permite que se llame a un objeto de función de JavaScript desde un complemento nativo. Este es el mecanismo principal para devolver la llamada desde el código nativo del complemento a JavaScript. Para el caso especial de llamar a JavaScript después de una operación asíncrona, consulta napi_make_callback.
Un caso de uso de muestra podría verse de la siguiente manera. Considera el siguiente fragmento de JavaScript:
function AddTwo(num) {
return num + 2
}
global.AddTwo = AddTwoLuego, la función anterior se puede invocar desde un complemento nativo usando el siguiente código:
// Obtiene la función llamada "AddTwo" en el objeto global
napi_value global, add_two, arg;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;
status = napi_get_named_property(env, global, "AddTwo", &add_two);
if (status != napi_ok) return;
// const arg = 1337
status = napi_create_int32(env, 1337, &arg);
if (status != napi_ok) return;
napi_value* argv = &arg;
size_t argc = 1;
// AddTwo(arg);
napi_value return_val;
status = napi_call_function(env, global, add_two, argc, argv, &return_val);
if (status != napi_ok) return;
// Convierte el resultado de nuevo a un tipo nativo
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;napi_create_function
Añadido en: v8.0.0
Versión de N-API: 1
napi_status napi_create_function(napi_env env,
const char* utf8name,
size_t length,
napi_callback cb,
void* data,
napi_value* result);[in] env: El entorno bajo el que se invoca la API.[in] utf8Name: Nombre opcional de la función codificado como UTF8. Esto es visible dentro de JavaScript como la propiedadnamedel nuevo objeto de función.[in] length: La longitud deutf8nameen bytes, oNAPI_AUTO_LENGTHsi termina en null.[in] cb: La función nativa que debe llamarse cuando se invoca este objeto de función.napi_callbackproporciona más detalles.[in] data: Contexto de datos proporcionado por el usuario. Esto se pasará de nuevo a la función cuando se invoque más adelante.[out] result:napi_valueque representa el objeto de función JavaScript para la función recién creada.
Devuelve napi_ok si la API tuvo éxito.
Esta API permite a un autor de complementos crear un objeto de función en código nativo. Este es el mecanismo principal para permitir llamadas a el código nativo del complemento desde JavaScript.
La función recién creada no es visible automáticamente desde el script después de esta llamada. En cambio, se debe establecer explícitamente una propiedad en cualquier objeto que sea visible para JavaScript, para que la función sea accesible desde el script.
Para exponer una función como parte de las exportaciones de módulos del complemento, establezca la función recién creada en el objeto de exportaciones. Un módulo de ejemplo podría verse de la siguiente manera:
napi_value SayHello(napi_env env, napi_callback_info info) {
printf("Hola\n");
return NULL;
}
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_value fn;
status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "sayHello", fn);
if (status != napi_ok) return NULL;
return exports;
}
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)Dado el código anterior, el complemento se puede usar desde JavaScript de la siguiente manera:
const myaddon = require('./addon')
myaddon.sayHello()La cadena pasada a require() es el nombre del destino en binding.gyp responsable de crear el archivo .node.
Cualquier dato no NULL que se pase a esta API a través del parámetro data se puede asociar con la función JavaScript resultante (que se devuelve en el parámetro result) y se puede liberar cuando la función se recolecta como basura pasando tanto la función JavaScript como los datos a napi_add_finalizer.
Las Functions de JavaScript se describen en la Sección 19.2 de la Especificación del Lenguaje ECMAScript.
napi_get_cb_info
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_get_cb_info(napi_env env,
napi_callback_info cbinfo,
size_t* argc,
napi_value* argv,
napi_value* thisArg,
void** data)[in] env: El entorno en el que se invoca la API.[in] cbinfo: La información de devolución de llamada pasada a la función de devolución de llamada.[in-out] argc: Especifica la longitud de la matrizargvproporcionada y recibe el recuento real de argumentos.argcse puede ignorar opcionalmente pasandoNULL.[out] argv: Matriz C denapi_values en la que se copiarán los argumentos. Si hay más argumentos que el recuento proporcionado, solo se copia el número solicitado de argumentos. Si se proporcionan menos argumentos de los reclamados, el resto deargvse llena con valoresnapi_valueque representanundefined.argvse puede ignorar opcionalmente pasandoNULL.[out] thisArg: Recibe el argumentothisde JavaScript para la llamada.thisArgse puede ignorar opcionalmente pasandoNULL.[out] data: Recibe el puntero de datos para la devolución de llamada.datase puede ignorar opcionalmente pasandoNULL.
Devuelve napi_ok si la API se realizó correctamente.
Este método se utiliza dentro de una función de devolución de llamada para recuperar detalles sobre la llamada, como los argumentos y el puntero this de una información de devolución de llamada dada.
napi_get_new_target
Agregado en: v8.6.0
Versión de N-API: 1
napi_status napi_get_new_target(napi_env env,
napi_callback_info cbinfo,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] cbinfo: La información de la devolución de llamada pasada a la función de devolución de llamada.[out] result: Elnew.targetde la llamada al constructor.
Devuelve napi_ok si la API se ejecutó correctamente.
Esta API devuelve el new.target de la llamada al constructor. Si la devolución de llamada actual no es una llamada al constructor, el resultado es NULL.
napi_new_instance
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_new_instance(napi_env env,
napi_value cons,
size_t argc,
napi_value* argv,
napi_value* result)[in] env: El entorno bajo el cual se invoca la API.[in] cons:napi_valueque representa la función de JavaScript que se invocará como constructor.[in] argc: El recuento de elementos en el arregloargv.[in] argv: Arreglo de valores de JavaScript comonapi_valueque representan los argumentos del constructor. Siargces cero, este parámetro se puede omitir pasandoNULL.[out] result:napi_valueque representa el objeto de JavaScript devuelto, que en este caso es el objeto construido.
Este método se utiliza para instanciar un nuevo valor de JavaScript utilizando un napi_value dado que representa el constructor del objeto. Por ejemplo, considere el siguiente fragmento:
function MyObject(param) {
this.param = param
}
const arg = 'hello'
const value = new MyObject(arg)Lo siguiente se puede aproximar en Node-API utilizando el siguiente fragmento:
// Obtener la función constructora MyObject
napi_value global, constructor, arg, value;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;
status = napi_get_named_property(env, global, "MyObject", &constructor);
if (status != napi_ok) return;
// const arg = "hello"
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg);
if (status != napi_ok) return;
napi_value* argv = &arg;
size_t argc = 1;
// const value = new MyObject(arg)
status = napi_new_instance(env, constructor, argc, argv, &value);Devuelve napi_ok si la API se ejecutó correctamente.
Envoltura de objetos
Node-API ofrece una manera de "envolver" clases e instancias de C++ para que el constructor de la clase y los métodos se puedan llamar desde JavaScript.
Para los objetos envueltos, puede ser difícil distinguir entre una función llamada en un prototipo de clase y una función llamada en una instancia de una clase. Un patrón común que se usa para abordar este problema es guardar una referencia persistente al constructor de la clase para posteriores comprobaciones de instanceof.
napi_value MyClass_constructor = NULL;
status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);
assert(napi_ok == status);
bool is_instance = false;
status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);
assert(napi_ok == status);
if (is_instance) {
// napi_unwrap() ...
} else {
// de lo contrario...
}La referencia debe liberarse una vez que ya no sea necesaria.
Hay ocasiones en las que napi_instanceof() es insuficiente para garantizar que un objeto JavaScript sea un envoltorio para un determinado tipo nativo. Este es el caso especialmente cuando los objetos JavaScript envueltos se pasan de nuevo al complemento a través de métodos estáticos en lugar de como el valor this de los métodos de prototipo. En tales casos, existe la posibilidad de que se desenvuelvan incorrectamente.
const myAddon = require('./build/Release/my_addon.node')
// `openDatabase()` devuelve un objeto JavaScript que envuelve un manejador de base de datos nativo.
const dbHandle = myAddon.openDatabase()
// `query()` devuelve un objeto JavaScript que envuelve un manejador de consulta nativo.
const queryHandle = myAddon.query(dbHandle, '¡Dame TODAS las cosas!')
// Hay un error accidental en la línea de abajo. El primer parámetro para
// `myAddon.queryHasRecords()` debería ser el manejador de la base de datos (`dbHandle`), no
// el manejador de la consulta (`query`), por lo que la condición correcta para el bucle while
// debería ser
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
// recuperar registros
}En el ejemplo anterior, myAddon.queryHasRecords() es un método que acepta dos argumentos. El primero es un manejador de base de datos y el segundo es un manejador de consulta. Internamente, desenreda el primer argumento y convierte el puntero resultante en un manejador de base de datos nativo. A continuación, desenvuelve el segundo argumento y convierte el puntero resultante en un manejador de consulta. Si los argumentos se pasan en el orden incorrecto, las conversiones funcionarán; sin embargo, existe una gran posibilidad de que la operación de base de datos subyacente falle o incluso provoque un acceso a memoria no válido.
Para garantizar que el puntero recuperado del primer argumento sea de hecho un puntero a un manejador de base de datos y, de manera similar, que el puntero recuperado del segundo argumento sea de hecho un puntero a un manejador de consulta, la implementación de queryHasRecords() tiene que realizar una validación de tipo. Conservar el constructor de la clase JavaScript desde el que se instanció el manejador de la base de datos y el constructor desde el que se instanció el manejador de la consulta en napi_refs puede ayudar, porque napi_instanceof() puede utilizarse entonces para asegurar que las instancias pasadas a queryHashRecords() son de hecho del tipo correcto.
Desafortunadamente, napi_instanceof() no protege contra la manipulación del prototipo. Por ejemplo, el prototipo de la instancia del manejador de la base de datos se puede establecer como el prototipo del constructor para las instancias del manejador de la consulta. En este caso, la instancia del manejador de la base de datos puede aparecer como una instancia del manejador de la consulta y superará la prueba napi_instanceof() para una instancia del manejador de la consulta, mientras que todavía contendrá un puntero a un manejador de la base de datos.
Para ello, Node-API proporciona capacidades de etiquetado de tipo.
Una etiqueta de tipo es un entero de 128 bits único para el complemento. Node-API proporciona la estructura napi_type_tag para almacenar una etiqueta de tipo. Cuando dicho valor se pasa junto con un objeto JavaScript o externo almacenado en un napi_value a napi_type_tag_object(), el objeto JavaScript se "marcará" con la etiqueta de tipo. La "marca" es invisible en el lado de JavaScript. Cuando un objeto JavaScript llega a un enlace nativo, napi_check_object_type_tag() se puede utilizar junto con la etiqueta de tipo original para determinar si el objeto JavaScript fue previamente "marcado" con la etiqueta de tipo. Esto crea una capacidad de comprobación de tipos de mayor fidelidad que la que puede proporcionar napi_instanceof(), porque dicho etiquetado de tipos sobrevive a la manipulación de prototipos y a la descarga/recarga de complementos.
Continuando con el ejemplo anterior, la siguiente implementación de complemento esqueleto ilustra el uso de napi_type_tag_object() y napi_check_object_type_tag().
// Este valor es la etiqueta de tipo para un manejador de base de datos. El comando
//
// uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// se puede utilizar para obtener los dos valores con los que inicializar la estructura.
static const napi_type_tag DatabaseHandleTypeTag = {
0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};
// Este valor es la etiqueta de tipo para un manejador de consulta.
static const napi_type_tag QueryHandleTypeTag = {
0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};
static napi_value
openDatabase(napi_env env, napi_callback_info info) {
napi_status status;
napi_value result;
// Realizar la acción subyacente que resulta en un manejador de base de datos.
DatabaseHandle* dbHandle = open_database();
// Crear un nuevo objeto JS vacío.
status = napi_create_object(env, &result);
if (status != napi_ok) return NULL;
// Etiquetar el objeto para indicar que contiene un puntero a un `DatabaseHandle`.
status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
if (status != napi_ok) return NULL;
// Almacenar el puntero a la estructura `DatabaseHandle` dentro del objeto JS.
status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
if (status != napi_ok) return NULL;
return result;
}
// Más tarde, cuando recibamos un objeto JavaScript que pretenda ser un manejador de base de datos
// podemos usar `napi_check_object_type_tag()` para asegurarnos de que sea realmente tal
// manejador.
static napi_value
query(napi_env env, napi_callback_info info) {
napi_status status;
size_t argc = 2;
napi_value argv[2];
bool is_db_handle;
status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
if (status != napi_ok) return NULL;
// Comprobar que el objeto pasado como primer parámetro tiene la etiqueta aplicada previamente.
status = napi_check_object_type_tag(env,
argv[0],
&DatabaseHandleTypeTag,
&is_db_handle);
if (status != napi_ok) return NULL;
// Lanzar un `TypeError` si no lo tiene.
if (!is_db_handle) {
// Lanzar un TypeError.
return NULL;
}
}napi_define_class
Añadido en: v8.0.0
Versión de N-API: 1
napi_status napi_define_class(napi_env env,
const char* utf8name,
size_t length,
napi_callback constructor,
void* data,
size_t property_count,
const napi_property_descriptor* properties,
napi_value* result);[in] env: El entorno en el que se invoca la API.[in] utf8name: Nombre de la función constructora de JavaScript. Para mayor claridad, se recomienda utilizar el nombre de la clase C++ al envolver una clase C++.[in] length: La longitud delutf8nameen bytes, oNAPI_AUTO_LENGTHsi está terminado en null.[in] constructor: Función de callback que maneja la construcción de instancias de la clase. Al envolver una clase C++, este método debe ser un miembro estático con la firmanapi_callback. No se puede utilizar un constructor de clase C++.napi_callbackproporciona más detalles.[in] data: Datos opcionales que se pasarán al callback del constructor como la propiedaddatade la información del callback.[in] property_count: Número de elementos en el argumento del arrayproperties.[in] properties: Array de descriptores de propiedad que describen las propiedades de datos estáticas y de instancia, los accesores y los métodos de la clase. Consultenapi_property_descriptor.[out] result: Unnapi_valueque representa la función constructora de la clase.
Devuelve napi_ok si la API tuvo éxito.
Define una clase JavaScript, que incluye:
- Una función constructora de JavaScript que tiene el nombre de la clase. Al envolver una clase C++ correspondiente, el callback pasado a través de
constructorpuede utilizarse para instanciar una nueva instancia de clase C++, que luego puede colocarse dentro de la instancia de objeto JavaScript que se está construyendo usandonapi_wrap. - Propiedades en la función constructora cuya implementación puede llamar a las propiedades de datos estáticas correspondientes, accesores y métodos de la clase C++ (definidos por descriptores de propiedad con el atributo
napi_static). - Propiedades en el objeto
prototypede la función constructora. Al envolver una clase C++, las propiedades de datos no estáticas, los accesores y los métodos de la clase C++ pueden ser llamados desde las funciones estáticas dadas en los descriptores de propiedad sin el atributonapi_staticdespués de recuperar la instancia de clase C++ colocada dentro de la instancia de objeto JavaScript usandonapi_unwrap.
Al envolver una clase C++, el callback del constructor de C++ pasado a través de constructor debe ser un método estático de la clase que llama al constructor de clase real, luego envuelve la nueva instancia C++ en un objeto JavaScript y devuelve el objeto envoltorio. Consulte napi_wrap para obtener más detalles.
La función constructora de JavaScript devuelta por napi_define_class a menudo se guarda y se utiliza más adelante para construir nuevas instancias de la clase desde código nativo, y/o para comprobar si los valores proporcionados son instancias de la clase. En ese caso, para evitar que el valor de la función sea recolectado por el recolector de basura, se puede crear una referencia persistente fuerte utilizando napi_create_reference, asegurando que el recuento de referencias se mantenga >= 1.
Cualquier dato que no sea NULL que se pase a esta API a través del parámetro data o a través del campo data de los elementos del array napi_property_descriptor puede asociarse con el constructor de JavaScript resultante (que se devuelve en el parámetro result) y liberarse siempre que la clase sea recolectada por el recolector de basura pasando tanto la función JavaScript como los datos a napi_add_finalizer.
napi_wrap
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
napi_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);[in] env: El entorno en el que se invoca la API.[in] js_object: El objeto JavaScript que será el envoltorio del objeto nativo.[in] native_object: La instancia nativa que se envolverá en el objeto JavaScript.[in] finalize_cb: Retrollamada nativa opcional que se puede usar para liberar la instancia nativa cuando el objeto JavaScript ha sido recolectado por el recolector de basura.napi_finalizeproporciona más detalles.[in] finalize_hint: Sugerencia contextual opcional que se pasa a la retrollamada finalize.[out] result: Referencia opcional al objeto envuelto.
Devuelve napi_ok si la API tuvo éxito.
Envuelve una instancia nativa en un objeto JavaScript. La instancia nativa se puede recuperar más tarde utilizando napi_unwrap().
Cuando el código JavaScript invoca un constructor para una clase que se definió utilizando napi_define_class(), se invoca la napi_callback para el constructor. Después de construir una instancia de la clase nativa, la retrollamada debe llamar a napi_wrap() para envolver la instancia recién construida en el objeto JavaScript ya creado que es el argumento this para la retrollamada del constructor. (Ese objeto this se creó a partir del prototype de la función constructora, por lo que ya tiene definiciones de todas las propiedades y métodos de instancia).
Por lo general, cuando se envuelve una instancia de clase, se debe proporcionar una retrollamada finalize que simplemente elimine la instancia nativa que se recibe como argumento data para la retrollamada finalize.
La referencia opcional devuelta es inicialmente una referencia débil, lo que significa que tiene un recuento de referencias de 0. Por lo general, este recuento de referencias se incrementaría temporalmente durante las operaciones asíncronas que requieren que la instancia siga siendo válida.
Precaución: La referencia opcional devuelta (si se obtiene) debe eliminarse a través de napi_delete_reference SÓLO en respuesta a la invocación de la retrollamada finalize. Si se elimina antes, es posible que la retrollamada finalize nunca se invoque. Por lo tanto, al obtener una referencia, también se requiere una retrollamada finalize para permitir la eliminación correcta de la referencia.
Las retrollamadas finalizer pueden diferirse, dejando una ventana donde el objeto ha sido recolectado por el recolector de basura (y la referencia débil no es válida) pero el finalizador aún no se ha llamado. Cuando se utiliza napi_get_reference_value() en referencias débiles devueltas por napi_wrap(), aún debe manejar un resultado vacío.
Llamar a napi_wrap() una segunda vez en un objeto devolverá un error. Para asociar otra instancia nativa con el objeto, utilice primero napi_remove_wrap().
napi_unwrap
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_unwrap(napi_env env,
napi_value js_object,
void** result);[in] env: El entorno bajo el cual se invoca la API.[in] js_object: El objeto asociado a la instancia nativa.[out] result: Puntero a la instancia nativa envuelta.
Devuelve napi_ok si la API tuvo éxito.
Recupera una instancia nativa que fue envuelta previamente en un objeto JavaScript usando napi_wrap().
Cuando el código JavaScript invoca un método o un descriptor de acceso de propiedad en la clase, se invoca el napi_callback correspondiente. Si la devolución de llamada es para un método de instancia o un descriptor de acceso, entonces el argumento this para la devolución de llamada es el objeto envoltorio; la instancia C++ envuelta que es el objetivo de la llamada se puede obtener entonces llamando a napi_unwrap() en el objeto envoltorio.
napi_remove_wrap
Agregado en: v8.5.0
Versión N-API: 1
napi_status napi_remove_wrap(napi_env env,
napi_value js_object,
void** result);[in] env: El entorno bajo el cual se invoca la API.[in] js_object: El objeto asociado a la instancia nativa.[out] result: Puntero a la instancia nativa envuelta.
Devuelve napi_ok si la API tuvo éxito.
Recupera una instancia nativa que fue envuelta previamente en el objeto JavaScript js_object usando napi_wrap() y elimina la envoltura. Si se asoció una devolución de llamada de finalización con la envoltura, ya no se llamará cuando el objeto JavaScript se recolecte como basura.
napi_type_tag_object
Agregado en: v14.8.0, v12.19.0
Versión N-API: 8
napi_status napi_type_tag_object(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag);[in] env: El entorno en el que se invoca la API.[in] js_object: El objeto JavaScript o externo que se va a marcar.[in] type_tag: La etiqueta con la que se va a marcar el objeto.
Devuelve napi_ok si la API se realizó correctamente.
Asocia el valor del puntero type_tag con el objeto JavaScript o externo. A continuación, se puede usar napi_check_object_type_tag() para comparar la etiqueta que se adjuntó al objeto con una que pertenezca al complemento para asegurarse de que el objeto tenga el tipo correcto.
Si el objeto ya tiene una etiqueta de tipo asociada, esta API devolverá napi_invalid_arg.
napi_check_object_type_tag
Agregado en: v14.8.0, v12.19.0
Versión N-API: 8
napi_status napi_check_object_type_tag(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag,
bool* result);[in] env: El entorno en el que se invoca la API.[in] js_object: El objeto JavaScript o externo cuya etiqueta de tipo se va a examinar.[in] type_tag: La etiqueta con la que comparar cualquier etiqueta encontrada en el objeto.[out] result: Indica si la etiqueta de tipo dada coincide con la etiqueta de tipo del objeto. También se devuelvefalsesi no se encontró ninguna etiqueta de tipo en el objeto.
Devuelve napi_ok si la API se realizó correctamente.
Compara el puntero dado como type_tag con cualquiera que se pueda encontrar en js_object. Si no se encuentra ninguna etiqueta en js_object o, si se encuentra una etiqueta pero no coincide con type_tag, entonces result se establece en false. Si se encuentra una etiqueta y coincide con type_tag, entonces result se establece en true.
napi_add_finalizer
Añadido en: v8.0.0
Versión N-API: 5
napi_status napi_add_finalizer(napi_env env,
napi_value js_object,
void* finalize_data,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);[in] env: El entorno bajo el que se invoca la API.[in] js_object: El objeto JavaScript al que se adjuntarán los datos nativos.[in] finalize_data: Datos opcionales que se pasarán afinalize_cb.[in] finalize_cb: Callback nativo que se utilizará para liberar los datos nativos cuando el objeto JavaScript haya sido recolectado por el recolector de basura.napi_finalizeproporciona más detalles.[in] finalize_hint: Sugerencia contextual opcional que se pasa al callback de finalización.[out] result: Referencia opcional al objeto JavaScript.
Devuelve napi_ok si la API tuvo éxito.
Añade un callback napi_finalize que se llamará cuando el objeto JavaScript en js_object haya sido recolectado por el recolector de basura.
Esta API se puede llamar varias veces en un solo objeto JavaScript.
Precaución: La referencia opcional devuelta (si se obtiene) debe eliminarse a través de napi_delete_reference SÓLO en respuesta a la invocación del callback de finalización. Si se elimina antes, entonces es posible que el callback de finalización nunca se invoque. Por lo tanto, cuando se obtiene una referencia, también se requiere un callback de finalización para permitir la eliminación correcta de la referencia.
node_api_post_finalizer
Agregado en: v21.0.0, v20.10.0, v18.19.0
[Estable: 1 - Experimental]
Estable: 1 Estabilidad: 1 - Experimental
napi_status node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint);[in] env: El entorno en el que se invoca la API.[in] finalize_cb: Callback nativo que se utilizará para liberar los datos nativos cuando el objeto JavaScript haya sido recolectado por el recolector de basura.napi_finalizeproporciona más detalles.[in] finalize_data: Datos opcionales que se pasarán afinalize_cb.[in] finalize_hint: Pista contextual opcional que se pasa al callback finalize.
Devuelve napi_ok si la API tuvo éxito.
Programa un callback napi_finalize para que se llame de forma asíncrona en el bucle de eventos.
Normalmente, los finalizadores se llaman mientras el GC (recolector de basura) recolecta objetos. En ese momento, llamar a cualquier Node-API que pueda causar cambios en el estado del GC se deshabilitará y Node.js fallará.
node_api_post_finalizer ayuda a solucionar esta limitación permitiendo que el complemento difiera las llamadas a dichas Node-API a un momento en el tiempo fuera de la finalización del GC.
Operaciones asíncronas simples
Los módulos de complementos a menudo necesitan aprovechar los ayudantes asíncronos de libuv como parte de su implementación. Esto les permite programar el trabajo para que se ejecute de forma asíncrona para que sus métodos puedan retornar antes de que se complete el trabajo. Esto les permite evitar el bloqueo de la ejecución general de la aplicación Node.js.
Node-API proporciona una interfaz ABI-estable para estas funciones de soporte que cubre los casos de uso asíncrono más comunes.
Node-API define la estructura napi_async_work que se utiliza para administrar los workers asíncronos. Las instancias se crean/eliminan con napi_create_async_work y napi_delete_async_work.
Las retrollamadas execute y complete son funciones que se invocarán cuando el ejecutor esté listo para ejecutarse y cuando complete su tarea, respectivamente.
La función execute debe evitar hacer cualquier llamada Node-API que pueda resultar en la ejecución de JavaScript o la interacción con objetos JavaScript. Muy a menudo, cualquier código que necesite hacer llamadas Node-API debería hacerse en la retrollamada complete. Evite usar el parámetro napi_env en la retrollamada execute ya que probablemente ejecutará JavaScript.
Estas funciones implementan las siguientes interfaces:
typedef void (*napi_async_execute_callback)(napi_env env,
void* data);
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);Cuando se invocan estos métodos, el parámetro data que se pasa será el dato void* proporcionado por el complemento que se pasó a la llamada napi_create_async_work.
Una vez creado, el worker asíncrono puede ponerse en cola para su ejecución utilizando la función napi_queue_async_work:
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);napi_cancel_async_work se puede utilizar si es necesario cancelar el trabajo antes de que haya comenzado la ejecución.
Después de llamar a napi_cancel_async_work, la retrollamada complete se invocará con un valor de estado de napi_cancelled. El trabajo no debe eliminarse antes de la invocación de la retrollamada complete, incluso cuando se haya cancelado.
napi_create_async_work
[Historial]
| Versión | Cambios |
|---|---|
| v8.6.0 | Se agregaron los parámetros async_resource y async_resource_name. |
| v8.0.0 | Agregado en: v8.0.0 |
Versión N-API: 1
napi_status napi_create_async_work(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_execute_callback execute,
napi_async_complete_callback complete,
void* data,
napi_async_work* result);[in] env: El entorno en el que se invoca la API.[in] async_resource: Un objeto opcional asociado al trabajo asíncrono que se pasará a los posibles hooksinitdeasync_hooksinithooks.[in] async_resource_name: Identificador del tipo de recurso que se proporciona para la información de diagnóstico expuesta por la APIasync_hooks.[in] execute: La función nativa que se debe llamar para ejecutar la lógica de forma asíncrona. La función dada se llama desde un hilo del pool de trabajadores y puede ejecutarse en paralelo con el hilo principal del bucle de eventos.[in] complete: La función nativa que se llamará cuando se complete la lógica asíncrona o se cancele. La función dada se llama desde el hilo principal del bucle de eventos.napi_async_complete_callbackproporciona más detalles.[in] data: Contexto de datos proporcionado por el usuario. Esto se pasará de nuevo a las funciones execute y complete.[out] result:napi_async_work*que es el identificador del trabajo asíncrono recién creado.
Devuelve napi_ok si la API tuvo éxito.
Esta API asigna un objeto de trabajo que se utiliza para ejecutar la lógica de forma asíncrona. Debe liberarse utilizando napi_delete_async_work una vez que el trabajo ya no sea necesario.
async_resource_name debe ser una cadena terminada en nulo y codificada en UTF-8.
El identificador async_resource_name es proporcionado por el usuario y debe ser representativo del tipo de trabajo asíncrono que se está realizando. También se recomienda aplicar espacios de nombres al identificador, por ejemplo, incluyendo el nombre del módulo. Consulte la documentación de async_hooks para obtener más información.
napi_delete_async_work
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_delete_async_work(napi_env env,
napi_async_work work);[in] env: El entorno bajo el cual se invoca la API.[in] work: El manejador devuelto por la llamada anapi_create_async_work.
Devuelve napi_ok si la API tuvo éxito.
Esta API libera un objeto de trabajo previamente asignado.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
napi_queue_async_work
Agregado en: v8.0.0
Versión de N-API: 1
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);[in] env: El entorno bajo el cual se invoca la API.[in] work: El manejador devuelto por la llamada anapi_create_async_work.
Devuelve napi_ok si la API tuvo éxito.
Esta API solicita que el trabajo asignado previamente se programe para su ejecución. Una vez que devuelve correctamente, esta API no se debe volver a llamar con el mismo elemento napi_async_work o el resultado será indefinido.
napi_cancel_async_work
Agregado en: v8.0.0
Versión N-API: 1
napi_status napi_cancel_async_work(node_api_basic_env env,
napi_async_work work);[in] env: El entorno en el que se invoca la API.[in] work: El manejador devuelto por la llamada anapi_create_async_work.
Devuelve napi_ok si la API tuvo éxito.
Esta API cancela el trabajo en cola si aún no se ha iniciado. Si ya ha comenzado a ejecutarse, no se puede cancelar y se devolverá napi_generic_failure. Si tiene éxito, la devolución de llamada complete se invocará con un valor de estado de napi_cancelled. El trabajo no debe eliminarse antes de la invocación de la devolución de llamada complete, incluso si se ha cancelado correctamente.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
Operaciones asíncronas personalizadas
Las API de trabajo asíncrono simples anteriores pueden no ser apropiadas para todos los escenarios. Cuando se utiliza cualquier otro mecanismo asíncrono, las siguientes API son necesarias para garantizar que el tiempo de ejecución realice un seguimiento adecuado de una operación asíncrona.
napi_async_init
Agregado en: v8.6.0
Versión N-API: 1
napi_status napi_async_init(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_context* result)[in] env: El entorno bajo el cual se invoca la API.[in] async_resource: Objeto asociado con el trabajo asíncrono que se pasará a posibles hooksinitdeasync_hooksinithooks y al que se puede acceder medianteasync_hooks.executionAsyncResource().[in] async_resource_name: Identificador para el tipo de recurso que se proporciona para información de diagnóstico expuesta por la APIasync_hooks.[out] result: El contexto asíncrono inicializado.
Devuelve napi_ok si la API tuvo éxito.
El objeto async_resource debe mantenerse activo hasta napi_async_destroy para que la API relacionada con async_hooks actúe correctamente. Para mantener la compatibilidad ABI con versiones anteriores, los napi_async_context no mantienen una referencia fuerte a los objetos async_resource para evitar la introducción de fugas de memoria. Sin embargo, si el recolector de basura del motor de JavaScript recoge async_resource antes de que napi_async_context sea destruido por napi_async_destroy, llamar a las API relacionadas con napi_async_context como napi_open_callback_scope y napi_make_callback puede causar problemas como la pérdida del contexto asíncrono al usar la API AsyncLocalStorage.
Para mantener la compatibilidad ABI con versiones anteriores, pasar NULL para async_resource no resulta en un error. Sin embargo, esto no es recomendable, ya que esto resultará en un comportamiento no deseado con los hooks init de async_hooks y async_hooks.executionAsyncResource(), ya que la implementación subyacente de async_hooks ahora requiere el recurso para proporcionar la conexión entre las devoluciones de llamada asíncronas.
napi_async_destroy
Agregado en: v8.6.0
Versión de N-API: 1
napi_status napi_async_destroy(napi_env env,
napi_async_context async_context);[in] env: El entorno bajo el cual se invoca la API.[in] async_context: El contexto asíncrono que se va a destruir.
Devuelve napi_ok si la API se realizó correctamente.
Esta API se puede llamar incluso si hay una excepción de JavaScript pendiente.
napi_make_callback
[Historial]
| Versión | Cambios |
|---|---|
| v8.6.0 | Se agregó el parámetro async_context. |
| v8.0.0 | Agregado en: v8.0.0 |
Versión de N-API: 1
NAPI_EXTERN napi_status napi_make_callback(napi_env env,
napi_async_context async_context,
napi_value recv,
napi_value func,
size_t argc,
const napi_value* argv,
napi_value* result);[in] env: El entorno bajo el cual se invoca la API.[in] async_context: Contexto para la operación asíncrona que invoca la devolución de llamada. Normalmente, este debería ser un valor obtenido previamente denapi_async_init. Para mantener la compatibilidad ABI con versiones anteriores, pasarNULLparaasync_contextno resulta en un error. Sin embargo, esto resulta en un funcionamiento incorrecto de los hooks asíncronos. Los problemas potenciales incluyen la pérdida de contexto asíncrono al usar la APIAsyncLocalStorage.[in] recv: El valorthispasado a la función llamada.[in] func:napi_valueque representa la función de JavaScript que se va a invocar.[in] argc: El recuento de elementos en el arregloargv.[in] argv: Arreglo de valores JavaScript comonapi_valueque representan los argumentos de la función. Siargces cero, este parámetro se puede omitir pasandoNULL.[out] result:napi_valueque representa el objeto JavaScript devuelto.
Devuelve napi_ok si la API se realizó correctamente.
Este método permite llamar a un objeto de función de JavaScript desde un complemento nativo. Esta API es similar a napi_call_function. Sin embargo, se utiliza para llamar desde código nativo de vuelta a JavaScript después de regresar de una operación asíncrona (cuando no hay ningún otro script en la pila). Es un envoltorio bastante simple alrededor de node::MakeCallback.
Tenga en cuenta que no es necesario usar napi_make_callback dentro de una napi_async_complete_callback; en esa situación, el contexto asíncrono de la devolución de llamada ya se ha configurado, por lo que una llamada directa a napi_call_function es suficiente y apropiada. El uso de la función napi_make_callback puede ser necesario al implementar un comportamiento asíncrono personalizado que no utiliza napi_create_async_work.
Cualquier process.nextTick o Promesas programadas en la cola de microtareas por JavaScript durante la devolución de llamada se ejecutan antes de regresar a C/C++.
napi_open_callback_scope
Agregado en: v9.6.0
Versión N-API: 3
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
napi_value resource_object,
napi_async_context context,
napi_callback_scope* result)[in] env: El entorno en el que se invoca la API.[in] resource_object: Un objeto asociado con el trabajo asíncrono que se pasará a los posibles hooksasync_hooksinit. Este parámetro ha quedado obsoleto y se ignora en tiempo de ejecución. Utilice el parámetroasync_resourceennapi_async_initen su lugar.[in] context: Contexto para la operación asíncrona que está invocando el callback. Este debe ser un valor obtenido previamente denapi_async_init.[out] result: El nuevo ámbito creado.
Hay casos (por ejemplo, resolver promesas) en los que es necesario tener el equivalente del ámbito asociado a un callback al realizar ciertas llamadas a Node-API. Si no hay otro script en la pila, las funciones napi_open_callback_scope y napi_close_callback_scope se pueden utilizar para abrir/cerrar el ámbito requerido.
napi_close_callback_scope
Agregado en: v9.6.0
Versión N-API: 3
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
napi_callback_scope scope)[in] env: El entorno bajo el cual se invoca la API.[in] scope: El ámbito a cerrar.
Se puede llamar a esta API incluso si hay una excepción de JavaScript pendiente.
Gestión de versiones
napi_get_node_version
Agregado en: v8.4.0
Versión N-API: 1
typedef struct {
uint32_t major;
uint32_t minor;
uint32_t patch;
const char* release;
} napi_node_version;
napi_status napi_get_node_version(node_api_basic_env env,
const napi_node_version** version);[in] env: El entorno bajo el cual se invoca la API.[out] version: Un puntero a la información de la versión de Node.js en sí.
Devuelve napi_ok si la API tuvo éxito.
Esta función rellena la estructura version con la versión mayor, menor y de parche de Node.js que se está ejecutando actualmente, y el campo release con el valor de process.release.name.
El búfer devuelto se asigna estáticamente y no necesita ser liberado.
napi_get_version
Añadido en: v8.0.0
Versión N-API: 1
napi_status napi_get_version(node_api_basic_env env,
uint32_t* result);[in] env: El entorno bajo el cual se invoca la API.[out] result: La versión más alta de Node-API soportada.
Devuelve napi_ok si la API tuvo éxito.
Esta API devuelve la versión más alta de Node-API soportada por el tiempo de ejecución de Node.js. Está previsto que Node-API sea aditivo, de forma que las versiones más recientes de Node.js puedan soportar funciones API adicionales. Para permitir que un complemento utilice una función más reciente cuando se ejecuta con versiones de Node.js que la soportan, a la vez que proporciona un comportamiento alternativo cuando se ejecuta con versiones de Node.js que no la soportan:
- Llama a
napi_get_version()para determinar si la API está disponible. - Si está disponible, carga dinámicamente un puntero a la función utilizando
uv_dlsym(). - Utiliza el puntero cargado dinámicamente para invocar la función.
- Si la función no está disponible, proporciona una implementación alternativa que no utilice la función.
Gestión de memoria
napi_adjust_external_memory
Añadido en: v8.5.0
Versión N-API: 1
NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
int64_t change_in_bytes,
int64_t* result);[in] env: El entorno bajo el cual se invoca la API.[in] change_in_bytes: El cambio en la memoria asignada externamente que se mantiene viva mediante objetos JavaScript.[out] result: El valor ajustado
Devuelve napi_ok si la API tuvo éxito.
Esta función le da a V8 una indicación de la cantidad de memoria asignada externamente que se mantiene viva mediante objetos JavaScript (es decir, un objeto JavaScript que apunta a su propia memoria asignada por un complemento nativo). Registrar la memoria asignada externamente activará las recolecciones de basura globales con más frecuencia de lo que lo haría de otra manera.
Promesas
Node-API proporciona facilidades para crear objetos Promise como se describe en la Sección 25.4 de la especificación ECMA. Implementa las promesas como un par de objetos. Cuando se crea una promesa mediante napi_create_promise(), se crea un objeto "diferido" y se devuelve junto con la Promise. El objeto diferido está vinculado a la Promise creada y es el único medio para resolver o rechazar la Promise usando napi_resolve_deferred() o napi_reject_deferred(). El objeto diferido que se crea mediante napi_create_promise() se libera mediante napi_resolve_deferred() o napi_reject_deferred(). El objeto Promise puede devolverse a JavaScript donde puede usarse de la manera habitual.
Por ejemplo, para crear una promesa y pasarla a un worker asíncrono:
napi_deferred deferred;
napi_value promise;
napi_status status;
// Crear la promesa.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;
// Pasar el diferido a una función que realiza una acción asíncrona.
do_something_asynchronous(deferred);
// Devolver la promesa a JS
return promise;La función anterior do_something_asynchronous() realizaría su acción asíncrona y luego resolvería o rechazaría el diferido, concluyendo así la promesa y liberando el diferido:
napi_deferred deferred;
napi_value undefined;
napi_status status;
// Crear un valor con el que concluir el diferido.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;
// Resolver o rechazar la promesa asociada con el diferido dependiendo de
// si la acción asíncrona tuvo éxito.
if (asynchronous_action_succeeded) {
status = napi_resolve_deferred(env, deferred, undefined);
} else {
status = napi_reject_deferred(env, deferred, undefined);
}
if (status != napi_ok) return NULL;
// En este punto, el diferido ha sido liberado, por lo que deberíamos asignarle NULL.
deferred = NULL;napi_create_promise
Agregado en: v8.5.0
Versión N-API: 1
napi_status napi_create_promise(napi_env env,
napi_deferred* deferred,
napi_value* promise);[in] env: El entorno bajo el cual se invoca la API.[out] deferred: Un objeto diferido recién creado que luego se puede pasar anapi_resolve_deferred()onapi_reject_deferred()para resolver o rechazar la promesa asociada, respectivamente.[out] promise: La promesa de JavaScript asociada con el objeto diferido.
Devuelve napi_ok si la API tuvo éxito.
Esta API crea un objeto diferido y una promesa de JavaScript.
napi_resolve_deferred
Agregado en: v8.5.0
Versión N-API: 1
napi_status napi_resolve_deferred(napi_env env,
napi_deferred deferred,
napi_value resolution);[in] env: El entorno bajo el cual se invoca la API.[in] deferred: El objeto diferido cuya promesa asociada se va a resolver.[in] resolution: El valor con el que se resolverá la promesa.
Esta API resuelve una promesa de JavaScript a través del objeto diferido con el que está asociado. Por lo tanto, solo se puede usar para resolver promesas de JavaScript para las cuales está disponible el objeto diferido correspondiente. Esto significa efectivamente que la promesa debe haberse creado usando napi_create_promise() y el objeto diferido devuelto por esa llamada debe haberse conservado para poder pasarlo a esta API.
El objeto diferido se libera al finalizar con éxito.
napi_reject_deferred
Agregado en: v8.5.0
Versión de N-API: 1
napi_status napi_reject_deferred(napi_env env,
napi_deferred deferred,
napi_value rejection);[in] env: El entorno en el que se invoca la API.[in] deferred: El objeto diferido cuya promesa asociada se va a rechazar.[in] rejection: El valor con el que se va a rechazar la promesa.
Esta API rechaza una promesa de JavaScript a través del objeto diferido con el que está asociada. Por lo tanto, solo se puede usar para rechazar las promesas de JavaScript para las que está disponible el objeto diferido correspondiente. Esto significa que la promesa debe haber sido creada usando napi_create_promise() y el objeto diferido devuelto por esa llamada debe haber sido retenido para poder pasarlo a esta API.
El objeto diferido se libera al finalizar correctamente.
napi_is_promise
Agregado en: v8.5.0
Versión de N-API: 1
napi_status napi_is_promise(napi_env env,
napi_value value,
bool* is_promise);[in] env: El entorno en el que se invoca la API.[in] value: El valor a examinar.[out] is_promise: Indicador que muestra sipromisees un objeto de promesa nativo (es decir, un objeto de promesa creado por el motor subyacente).
Ejecución de scripts
Node-API proporciona una API para ejecutar una cadena que contiene JavaScript utilizando el motor de JavaScript subyacente.
napi_run_script
Añadido en: v8.5.0
Versión N-API: 1
NAPI_EXTERN napi_status napi_run_script(napi_env env,
napi_value script,
napi_value* result);[in] env: El entorno bajo el que se invoca la API.[in] script: Una cadena de JavaScript que contiene el script a ejecutar.[out] result: El valor resultante de haber ejecutado el script.
Esta función ejecuta una cadena de código JavaScript y devuelve su resultado con las siguientes advertencias:
- A diferencia de
eval, esta función no permite que el script acceda al ámbito léxico actual, y por lo tanto tampoco permite acceder al ámbito del módulo, lo que significa que pseudo-globales comorequireno estarán disponibles. - El script puede acceder al ámbito global. Las declaraciones de función y
varen el script se agregarán al objetoglobal. Las declaraciones de variables hechas usandoletyconstserán visibles globalmente, pero no se agregarán al objetoglobal. - El valor de
thisesglobaldentro del script.
Bucle de eventos libuv
Node-API proporciona una función para obtener el bucle de eventos actual asociado a un napi_env específico.
napi_get_uv_event_loop
Añadido en: v9.3.0, v8.10.0
Versión N-API: 2
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
struct uv_loop_s** loop);[in] env: El entorno bajo el que se invoca la API.[out] loop: La instancia actual del bucle libuv.
Nota: Si bien libuv ha sido relativamente estable a lo largo del tiempo, no proporciona una garantía de estabilidad ABI. Se debe evitar el uso de esta función. Su uso puede resultar en un complemento que no funciona en diferentes versiones de Node.js. Los llamados asíncronos seguros para subprocesos son una alternativa para muchos casos de uso.
Llamados a funciones asíncronas seguras para subprocesos
Las funciones de JavaScript normalmente solo se pueden llamar desde el hilo principal de un complemento nativo. Si un complemento crea hilos adicionales, las funciones Node-API que requieran un napi_env, napi_value o napi_ref no deben llamarse desde esos hilos.
Cuando un complemento tiene hilos adicionales y es necesario invocar funciones de JavaScript en función del procesamiento completado por esos hilos, esos hilos deben comunicarse con el hilo principal del complemento para que el hilo principal pueda invocar la función de JavaScript en su nombre. Las API de funciones seguras para subprocesos proporcionan una manera fácil de hacer esto.
Estas API proporcionan el tipo napi_threadsafe_function, así como API para crear, destruir y llamar a objetos de este tipo. napi_create_threadsafe_function() crea una referencia persistente a un napi_value que contiene una función de JavaScript a la que se puede llamar desde varios hilos. Las llamadas se realizan de forma asíncrona. Esto significa que los valores con los que se va a llamar a la función de devolución de llamada de JavaScript se colocarán en una cola y, por cada valor de la cola, eventualmente se realizará una llamada a la función de JavaScript.
Al crear una napi_threadsafe_function, se puede proporcionar una función de devolución de llamada napi_finalize. Esta función de devolución de llamada se invocará en el hilo principal cuando la función segura para subprocesos esté a punto de ser destruida. Recibe el contexto y los datos de finalización dados durante la construcción, y brinda la oportunidad de limpiar después de los hilos, por ejemplo, llamando a uv_thread_join(). Aparte del hilo del bucle principal, ningún hilo debe usar la función segura para subprocesos después de que se complete la función de devolución de llamada de finalización.
El contexto proporcionado durante la llamada a napi_create_threadsafe_function() se puede recuperar de cualquier hilo con una llamada a napi_get_threadsafe_function_context().
Llamar a una función segura para subprocesos
Se puede utilizar napi_call_threadsafe_function() para iniciar una llamada a JavaScript. napi_call_threadsafe_function() acepta un parámetro que controla si la API se comporta de manera bloqueante. Si se establece en napi_tsfn_nonblocking, la API se comporta de manera no bloqueante, devolviendo napi_queue_full si la cola estaba llena, lo que impide que los datos se agreguen correctamente a la cola. Si se establece en napi_tsfn_blocking, la API se bloquea hasta que haya espacio disponible en la cola. napi_call_threadsafe_function() nunca se bloquea si la función segura para subprocesos se creó con un tamaño máximo de cola de 0.
No se debe llamar a napi_call_threadsafe_function() con napi_tsfn_blocking desde un subproceso de JavaScript, ya que, si la cola está llena, puede provocar un interbloqueo del subproceso de JavaScript.
La llamada real a JavaScript está controlada por la devolución de llamada proporcionada a través del parámetro call_js_cb. call_js_cb se invoca en el subproceso principal una vez por cada valor que se colocó en la cola mediante una llamada exitosa a napi_call_threadsafe_function(). Si no se proporciona dicha devolución de llamada, se utilizará una devolución de llamada predeterminada y la llamada de JavaScript resultante no tendrá argumentos. La devolución de llamada call_js_cb recibe la función de JavaScript a llamar como un napi_value en sus parámetros, así como el puntero de contexto void* utilizado al crear la napi_threadsafe_function, y el siguiente puntero de datos que fue creado por uno de los subprocesos secundarios. La devolución de llamada puede utilizar una API como napi_call_function() para llamar a JavaScript.
También se puede invocar la devolución de llamada con env y call_js_cb ambos establecidos en NULL para indicar que las llamadas a JavaScript ya no son posibles, mientras que quedan elementos en la cola que pueden necesitar ser liberados. Esto normalmente ocurre cuando el proceso de Node.js finaliza mientras todavía hay una función segura para subprocesos activa.
No es necesario llamar a JavaScript a través de napi_make_callback() porque Node-API ejecuta call_js_cb en un contexto apropiado para las devoluciones de llamada.
Se pueden invocar cero o más elementos en cola en cada ciclo del bucle de eventos. Las aplicaciones no deben depender de un comportamiento específico que no sea el progreso en la invocación de devoluciones de llamada y los eventos se invocarán a medida que avance el tiempo.
Conteo de referencias de funciones seguras para subprocesos
Se pueden agregar y eliminar subprocesos de un objeto napi_threadsafe_function durante su existencia. Por lo tanto, además de especificar un número inicial de subprocesos al crear, se puede llamar a napi_acquire_threadsafe_function para indicar que un nuevo subproceso comenzará a usar la función segura para subprocesos. De manera similar, se puede llamar a napi_release_threadsafe_function para indicar que un subproceso existente dejará de usar la función segura para subprocesos.
Los objetos napi_threadsafe_function se destruyen cuando cada subproceso que usa el objeto ha llamado a napi_release_threadsafe_function() o ha recibido un estado de retorno de napi_closing en respuesta a una llamada a napi_call_threadsafe_function. La cola se vacía antes de que se destruya la napi_threadsafe_function. napi_release_threadsafe_function() debe ser la última llamada a la API realizada junto con una napi_threadsafe_function dada, porque después de que se complete la llamada, no hay garantía de que la napi_threadsafe_function todavía esté asignada. Por la misma razón, no utilice una función segura para subprocesos después de recibir un valor de retorno de napi_closing en respuesta a una llamada a napi_call_threadsafe_function. Los datos asociados con la napi_threadsafe_function se pueden liberar en su devolución de llamada napi_finalize que se pasó a napi_create_threadsafe_function(). El parámetro initial_thread_count de napi_create_threadsafe_function marca el número inicial de adquisiciones de las funciones seguras para subprocesos, en lugar de llamar a napi_acquire_threadsafe_function varias veces en la creación.
Una vez que el número de subprocesos que utilizan una napi_threadsafe_function llega a cero, ningún otro subproceso puede comenzar a utilizarla llamando a napi_acquire_threadsafe_function(). De hecho, todas las llamadas posteriores a la API asociadas con ella, excepto napi_release_threadsafe_function(), devolverán un valor de error de napi_closing.
La función segura para subprocesos se puede "abortar" dando un valor de napi_tsfn_abort a napi_release_threadsafe_function(). Esto hará que todas las API posteriores asociadas con la función segura para subprocesos, excepto napi_release_threadsafe_function(), devuelvan napi_closing incluso antes de que su recuento de referencias llegue a cero. En particular, napi_call_threadsafe_function() devolverá napi_closing, informando así a los subprocesos que ya no es posible realizar llamadas asíncronas a la función segura para subprocesos. Esto se puede usar como un criterio para terminar el subproceso. Al recibir un valor de retorno de napi_closing de napi_call_threadsafe_function() un subproceso no debe usar la función segura para subprocesos nunca más porque ya no se garantiza que esté asignada.
Decidir si se mantiene el proceso en ejecución
De forma similar a los manejadores de libuv, las funciones seguras para subprocesos pueden ser "referenciadas" y "desreferenciadas". Una función segura para subprocesos "referenciada" hará que el bucle de eventos en el subproceso en el que se crea permanezca activo hasta que se destruya la función segura para subprocesos. Por el contrario, una función segura para subprocesos "desreferenciada" no impedirá que el bucle de eventos se cierre. Las API napi_ref_threadsafe_function y napi_unref_threadsafe_function existen para este propósito.
Tampoco napi_unref_threadsafe_function marca las funciones seguras para subprocesos como capaces de ser destruidas, ni napi_ref_threadsafe_function evita que sean destruidas.
napi_create_threadsafe_function
[Historial]
| Versión | Cambios |
|---|---|
| v12.6.0, v10.17.0 | Se hizo el parámetro func opcional con call_js_cb personalizado. |
| v10.6.0 | Agregado en: v10.6.0 |
Versión N-API: 4
NAPI_EXTERN napi_status
napi_create_threadsafe_function(napi_env env,
napi_value func,
napi_value async_resource,
napi_value async_resource_name,
size_t max_queue_size,
size_t initial_thread_count,
void* thread_finalize_data,
napi_finalize thread_finalize_cb,
void* context,
napi_threadsafe_function_call_js call_js_cb,
napi_threadsafe_function* result);[in] env: El entorno en el que se invoca la API.[in] func: Una función JavaScript opcional para llamar desde otro subproceso. Debe proporcionarse si se pasaNULLacall_js_cb.[in] async_resource: Un objeto opcional asociado con el trabajo asíncrono que se pasará a posibles ganchosinitdeasync_hooksinitganchos.[in] async_resource_name: Una cadena JavaScript para proporcionar un identificador para el tipo de recurso que se proporciona para la información de diagnóstico expuesta por la APIasync_hooks.[in] max_queue_size: Tamaño máximo de la cola.0para sin límite.[in] initial_thread_count: El número inicial de adquisiciones, es decir, el número inicial de subprocesos, incluido el subproceso principal, que utilizarán esta función.[in] thread_finalize_data: Datos opcionales para pasar athread_finalize_cb.[in] thread_finalize_cb: Función opcional para llamar cuando se está destruyendonapi_threadsafe_function.[in] context: Datos opcionales para adjuntar alnapi_threadsafe_functionresultante.[in] call_js_cb: Callback opcional que llama a la función JavaScript en respuesta a una llamada en un subproceso diferente. Esta callback se llamará en el subproceso principal. Si no se proporciona, la función JavaScript se llamará sin parámetros y conundefinedcomo su valorthis.napi_threadsafe_function_call_jsproporciona más detalles.[out] result: La función JavaScript asíncrona segura para subprocesos.
Historial de cambios:
- Experimental (se define
NAPI_EXPERIMENTAL): Las excepciones no capturadas lanzadas encall_js_cbse manejan con el evento'uncaughtException', en lugar de ser ignoradas.
napi_get_threadsafe_function_context
Añadido en: v10.6.0
Versión de N-API: 4
NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
void** result);[in] func: La función thread-safe para la que se va a recuperar el contexto.[out] result: La ubicación donde almacenar el contexto.
Esta API puede ser llamada desde cualquier hilo que utilice func.
napi_call_threadsafe_function
[Historial]
| Versión | Cambios |
|---|---|
| v14.5.0 | Se ha revertido el soporte para napi_would_deadlock. |
| v14.1.0 | Devuelve napi_would_deadlock cuando se llama con napi_tsfn_blocking desde el hilo principal o un hilo de trabajo y la cola está llena. |
| v10.6.0 | Añadido en: v10.6.0 |
Versión de N-API: 4
NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
void* data,
napi_threadsafe_function_call_mode is_blocking);[in] func: La función JavaScript asíncrona thread-safe que se va a invocar.[in] data: Datos para enviar a JavaScript a través del callbackcall_js_cbproporcionado durante la creación de la función JavaScript thread-safe.[in] is_blocking: Flag cuyo valor puede sernapi_tsfn_blockingpara indicar que la llamada debe bloquearse si la cola está llena onapi_tsfn_nonblockingpara indicar que la llamada debe retornar inmediatamente con un estado denapi_queue_fullsiempre que la cola esté llena.
Esta API no debe ser llamada con napi_tsfn_blocking desde un hilo de JavaScript, ya que, si la cola está llena, podría provocar que el hilo de JavaScript se bloquee.
Esta API retornará napi_closing si napi_release_threadsafe_function() fue llamada con abort establecido a napi_tsfn_abort desde cualquier hilo. El valor solo se añade a la cola si la API retorna napi_ok.
Esta API puede ser llamada desde cualquier hilo que utilice func.
napi_acquire_threadsafe_function
Agregado en: v10.6.0
Versión N-API: 4
NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);[in] func: La función asíncrona de JavaScript segura para subprocesos para empezar a utilizar.
Un hilo debería llamar a esta API antes de pasar func a cualquier otra API de función segura para subprocesos para indicar que va a utilizar func. Esto evita que func se destruya cuando todos los demás hilos han dejado de utilizarla.
Esta API puede ser llamada desde cualquier hilo que empiece a utilizar func.
napi_release_threadsafe_function
Agregado en: v10.6.0
Versión N-API: 4
NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
napi_threadsafe_function_release_mode mode);[in] func: La función asíncrona de JavaScript segura para subprocesos cuyo recuento de referencias se va a decrementar.[in] mode: Bandera cuyo valor puede sernapi_tsfn_releasepara indicar que el hilo actual no realizará más llamadas a la función segura para subprocesos, onapi_tsfn_abortpara indicar que, además del hilo actual, ningún otro hilo debería realizar más llamadas a la función segura para subprocesos. Si se establece ennapi_tsfn_abort, las llamadas posteriores anapi_call_threadsafe_function()devolveránnapi_closing, y no se colocarán más valores en la cola.
Un hilo debería llamar a esta API cuando deje de utilizar func. Pasar func a cualquier API segura para subprocesos después de haber llamado a esta API tiene resultados indefinidos, ya que func puede haber sido destruida.
Esta API puede ser llamada desde cualquier hilo que deje de utilizar func.
napi_ref_threadsafe_function
Agregado en: v10.6.0
Versión N-API: 4
NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);[in] env: El entorno bajo el cual se invoca la API.[in] func: La función segura para subprocesos a la que se debe hacer referencia.
Esta API se utiliza para indicar que el bucle de eventos que se ejecuta en el hilo principal no debe salir hasta que se haya destruido func. Similar a uv_ref, también es idempotente.
Ni napi_unref_threadsafe_function marca las funciones seguras para subprocesos como susceptibles de ser destruidas, ni napi_ref_threadsafe_function evita que sean destruidas. napi_acquire_threadsafe_function y napi_release_threadsafe_function están disponibles para ese propósito.
Esta API solo se puede llamar desde el hilo principal.
napi_unref_threadsafe_function
Agregado en: v10.6.0
Versión N-API: 4
NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);[in] env: El entorno bajo el cual se invoca la API.[in] func: La función segura para subprocesos de la que se debe quitar la referencia.
Esta API se utiliza para indicar que el bucle de eventos que se ejecuta en el hilo principal puede salir antes de que se destruya func. Similar a uv_unref, también es idempotente.
Esta API solo se puede llamar desde el hilo principal.
Utilidades diversas
node_api_get_module_file_name
Añadido en: v15.9.0, v14.18.0, v12.22.0
Versión de N-API: 9
NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);[in] env: El entorno bajo el cual se invoca la API.[out] result: Una URL que contiene la ruta absoluta de la ubicación desde la que se cargó el complemento. Para un archivo en el sistema de archivos local, comenzará confile://. La cadena está terminada en nulo y es propiedad deenv, por lo que no debe modificarse ni liberarse.
result puede ser una cadena vacía si el proceso de carga del complemento no logra establecer el nombre de archivo del complemento durante la carga.