Node-API

[Stable : 2 - Stable]

Stable : 2 Stability : 2 - Stable

Node-API (anciennement N-API) est une API pour la création d'extensions natives. Elle est indépendante du moteur JavaScript sous-jacent (par exemple, V8) et est maintenue en tant que partie intégrante de Node.js. Cette API sera stable au niveau de l'interface binaire d'application (ABI) entre les versions de Node.js. Elle vise à isoler les extensions des modifications apportées au moteur JavaScript sous-jacent et à permettre aux modules compilés pour une version majeure de s'exécuter sur des versions majeures ultérieures de Node.js sans recompilation. Le guide sur la stabilité ABI fournit une explication plus approfondie.

Les extensions sont construites/empaquetées avec la même approche/les mêmes outils que ceux décrits dans la section intitulée Extensions C++. La seule différence réside dans l'ensemble des API utilisées par le code natif. Au lieu d'utiliser les API V8 ou Native Abstractions for Node.js, les fonctions disponibles dans Node-API sont utilisées.

Les API exposées par Node-API sont généralement utilisées pour créer et manipuler des valeurs JavaScript. Les concepts et les opérations correspondent généralement aux idées spécifiées dans la spécification du langage ECMA-262. Les API possèdent les propriétés suivantes :

• Tous les appels Node-API retournent un code de statut de type napi_status. Ce statut indique si l'appel API a réussi ou a échoué.
• La valeur de retour de l'API est passée via un paramètre de sortie.
• Toutes les valeurs JavaScript sont abstraites derrière un type opaque nommé napi_value.
• En cas de code de statut d'erreur, des informations supplémentaires peuvent être obtenues à l'aide de napi_get_last_error_info. Vous trouverez plus d'informations dans la section sur la gestion des erreurs Gestion des erreurs.

Node-API est une API C qui garantit la stabilité de l'ABI entre les versions de Node.js et les différents niveaux de compilation. Une API C++ peut être plus facile à utiliser. Pour prendre en charge l'utilisation de C++, le projet maintient un module wrapper C++ appelé node-addon-api. Ce wrapper fournit une API C++ intégrable. Les binaires construits avec node-addon-api dépendront des symboles des fonctions basées sur C de Node-API exportées par Node.js. node-addon-api est un moyen plus efficace d'écrire du code qui appelle Node-API. Prenons par exemple le code node-addon-api suivant. La première section montre le code node-addon-api et la seconde section montre ce qui est réellement utilisé dans l'extension.

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;
}

Le résultat final est que l'extension n'utilise que les API C exportées. Par conséquent, elle bénéficie toujours des avantages de la stabilité ABI fournie par l'API C.

Lorsque vous utilisez node-addon-api au lieu des API C, commencez par la documentation de l'API docs pour node-addon-api.

La Ressource Node-API offre une excellente orientation et des conseils aux développeurs qui débutent avec Node-API et node-addon-api. Des ressources multimédias supplémentaires sont disponibles sur la page Médias Node-API.

Implications de la stabilité ABI

Bien que Node-API garantisse une stabilité ABI, d'autres parties de Node.js ne le font pas, et il en va de même pour les bibliothèques externes utilisées par l'addon. En particulier, aucune des API suivantes ne garantit une stabilité ABI entre les versions majeures :

• les API C++ de Node.js disponibles via
• les API libuv qui sont également incluses avec Node.js et disponibles via
• l'API V8 disponible via

Ainsi, pour qu'un addon reste compatible ABI entre les versions majeures de Node.js, il doit utiliser Node-API exclusivement en se limitant à :

#include <node_api.h>

et en vérifiant, pour toutes les bibliothèques externes qu'il utilise, que la bibliothèque externe offre des garanties de stabilité ABI similaires à Node-API.

Compilation

Contrairement aux modules écrits en JavaScript, le développement et le déploiement d'addons natifs Node.js utilisant Node-API nécessitent un ensemble d'outils supplémentaires. Outre les outils de base nécessaires au développement pour Node.js, le développeur d'addons natifs a besoin d'une chaîne d'outils capable de compiler du code C et C++ en un binaire. De plus, selon la façon dont l'addon natif est déployé, l'utilisateur de l'addon natif devra également avoir une chaîne d'outils C/C++ installée.

Pour les développeurs Linux, les packages de chaînes d'outils C/C++ nécessaires sont facilement disponibles. GCC est largement utilisé dans la communauté Node.js pour compiler et tester sur une variété de plates-formes. Pour de nombreux développeurs, l'infrastructure de compilateur LLVM est également un bon choix.

Pour les développeurs Mac, Xcode offre tous les outils de compilation nécessaires. Cependant, il n'est pas nécessaire d'installer l'IDE Xcode entier. La commande suivante installe la chaîne d'outils nécessaire :

xcode-select --install

Pour les développeurs Windows, Visual Studio offre tous les outils de compilation nécessaires. Cependant, il n'est pas nécessaire d'installer l'IDE Visual Studio entier. La commande suivante installe la chaîne d'outils nécessaire :

npm install --global windows-build-tools

Les sections ci-dessous décrivent les outils supplémentaires disponibles pour le développement et le déploiement d'addons natifs Node.js.

Outils de build

Les deux outils listés ici nécessitent que les utilisateurs de l'addon natif aient un outillage C/C++ installé pour pouvoir installer avec succès l'addon natif.

node-gyp

node-gyp est un système de build basé sur la branche gyp-next de l'outil GYP de Google (GYP) et est fourni avec npm. GYP, et donc node-gyp, nécessite que Python soit installé.

Historiquement, node-gyp a été l'outil de choix pour construire des addons natifs. Il bénéficie d'une large adoption et d'une documentation abondante. Cependant, certains développeurs ont rencontré des limitations dans node-gyp.

CMake.js

CMake.js est un système de build alternatif basé sur CMake.

CMake.js est un bon choix pour les projets qui utilisent déjà CMake ou pour les développeurs affectés par les limitations de node-gyp. build_with_cmake est un exemple de projet d'addon natif basé sur CMake.

Téléchargement de binaires précompilés

Les trois outils listés ici permettent aux développeurs et mainteneurs d'addons natifs de créer et de télécharger des binaires vers des serveurs publics ou privés. Ces outils sont généralement intégrés à des systèmes de build CI/CD comme Travis CI et AppVeyor pour construire et télécharger des binaires pour une variété de plates-formes et d'architectures. Ces binaires sont ensuite disponibles en téléchargement pour les utilisateurs qui n'ont pas besoin d'avoir un outillage C/C++ installé.

node-pre-gyp

node-pre-gyp est un outil basé sur node-gyp qui ajoute la possibilité de télécharger des binaires vers un serveur au choix du développeur. node-pre-gyp a un support particulièrement bon pour le téléchargement de binaires vers Amazon S3.

prebuild

prebuild est un outil qui supporte les builds utilisant node-gyp ou CMake.js. Contrairement à node-pre-gyp qui supporte une variété de serveurs, prebuild télécharge les binaires uniquement vers les releases GitHub. prebuild est un bon choix pour les projets GitHub utilisant CMake.js.

prebuildify

prebuildify est un outil basé sur node-gyp. L'avantage de prebuildify est que les binaires compilés sont regroupés avec l'addon natif lors de son envoi sur npm. Les binaires sont téléchargés depuis npm et sont immédiatement disponibles pour l'utilisateur du module lors de l'installation de l'addon natif.

Utilisation

Pour utiliser les fonctions Node-API, incluez le fichier node_api.h qui se trouve dans le répertoire src de l'arborescence de développement de Node :

#include <node_api.h>

Cela activera la version NAPI_VERSION par défaut pour la version donnée de Node.js. Pour assurer la compatibilité avec des versions spécifiques de Node-API, la version peut être spécifiée explicitement lors de l'inclusion de l'en-tête :

#define NAPI_VERSION 3
#include <node_api.h>

Cela restreint la surface Node-API uniquement aux fonctionnalités disponibles dans les versions spécifiées (et antérieures).

Une partie de la surface Node-API est expérimentale et nécessite une activation explicite :

#define NAPI_EXPERIMENTAL
#include <node_api.h>

Dans ce cas, toute la surface de l'API, y compris les API expérimentales, sera disponible pour le code du module.

Occasionnellement, des fonctionnalités expérimentales sont introduites qui affectent les API déjà publiées et stables. Ces fonctionnalités peuvent être désactivées par une désactivation :

#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>

où \<FEATURE_NAME\> est le nom d'une fonctionnalité expérimentale qui affecte à la fois les API expérimentales et les API stables.

Matrice de version Node-API

Jusqu'à la version 9, les versions de Node-API étaient additives et versionnées indépendamment de Node.js. Cela signifiait que chaque version était une extension de la version précédente, en ce sens qu'elle disposait de toutes les API de la version précédente avec quelques ajouts. Chaque version de Node.js ne supportait qu'une seule version de Node-API. Par exemple, la v18.15.0 ne supporte que la version 8 de Node-API. La stabilité de l'ABI a été obtenue car la version 8 était un sur-ensemble strict de toutes les versions précédentes.

À partir de la version 9, bien que les versions de Node-API continuent d'être versionnées indépendamment, un addon qui fonctionnait avec la version 9 de Node-API peut nécessiter des mises à jour de code pour fonctionner avec la version 10 de Node-API. La stabilité de l'ABI est cependant maintenue, car les versions de Node.js qui supportent les versions de Node-API supérieures à 8 supporteront toutes les versions entre 8 et la version la plus élevée qu'elles supportent et fourniront par défaut les API de la version 8 à moins qu'un addon n'opte pour une version de Node-API plus élevée. Cette approche offre la flexibilité d'une meilleure optimisation des fonctions Node-API existantes tout en maintenant la stabilité de l'ABI. Les addons existants peuvent continuer à fonctionner sans recompilation en utilisant une version antérieure de Node-API. Si un addon a besoin des fonctionnalités d'une version plus récente de Node-API, des modifications au code existant et une recompilation seront nécessaires pour utiliser ces nouvelles fonctions de toute façon.

Dans les versions de Node.js qui supportent la version 9 et les versions ultérieures de Node-API, la définition de NAPI_VERSION=X et l'utilisation des macros d'initialisation d'addon existantes intégreront la version Node-API demandée qui sera utilisée au moment de l'exécution dans l'addon. Si NAPI_VERSION n'est pas défini, il sera par défaut à 8.

Ce tableau peut ne pas être à jour dans les flux plus anciens, les informations les plus récentes se trouvent dans la dernière documentation de l'API dans : Matrice de version Node-API

Version Node-API	Supporté dans
9	v18.17.0+, 20.3.0+, 21.0.0 et toutes les versions ultérieures
8	v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 et toutes les versions ultérieures
7	v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 et toutes les versions ultérieures
6	v10.20.0+, v12.17.0+, 14.0.0 et toutes les versions ultérieures
5	v10.17.0+, v12.11.0+, 13.0.0 et toutes les versions ultérieures
4	v10.16.0+, v11.8.0+, 12.0.0 et toutes les versions ultérieures
3	v6.14.2*, 8.11.2+, v9.11.0+*, 10.0.0 et toutes les versions ultérieures
2	v8.10.0+, v9.3.0+, 10.0.0 et toutes les versions ultérieures
1	v8.6.0+*, v9.0.0+, 10.0.0 et toutes les versions ultérieures

* Node-API était expérimental.

** Node.js 8.0.0 incluait Node-API en tant qu'expérimental. Il a été publié en tant que version 1 de Node-API mais a continué à évoluer jusqu'à Node.js 8.6.0. L'API est différente dans les versions antérieures à Node.js 8.6.0. Nous recommandons la version 3 ou ultérieure de Node-API.

Chaque API documentée pour Node-API aura un en-tête nommé added in:, et les API stables auront l'en-tête supplémentaire Node-API version:. Les API sont directement utilisables lorsque vous utilisez une version de Node.js qui supporte la version Node-API indiquée dans Node-API version: ou une version supérieure. Lorsque vous utilisez une version de Node.js qui ne supporte pas la version Node-API version: indiquée ou s'il n'y a pas de Node-API version: indiqué, alors l'API ne sera disponible que si #define NAPI_EXPERIMENTAL précède l'inclusion de node_api.h ou js_native_api.h. Si une API ne semble pas être disponible sur une version de Node.js qui est postérieure à celle indiquée dans added in:, alors c'est très probablement la raison de l'absence apparente.

Les Node-API associées strictement à l'accès aux fonctionnalités ECMAScript à partir de code natif se trouvent séparément dans js_native_api.h et js_native_api_types.h. Les API définies dans ces en-têtes sont incluses dans node_api.h et node_api_types.h. Les en-têtes sont structurés de cette manière afin de permettre des implémentations de Node-API en dehors de Node.js. Pour ces implémentations, les API spécifiques à Node.js peuvent ne pas être applicables.

Les parties spécifiques à Node.js d'un addon peuvent être séparées du code qui expose les fonctionnalités réelles à l'environnement JavaScript afin que ce dernier puisse être utilisé avec plusieurs implémentations de Node-API. Dans l'exemple ci-dessous, addon.c et addon.h ne font référence qu'à js_native_api.h. Cela garantit que addon.c peut être réutilisé pour compiler contre l'implémentation Node.js de Node-API ou toute implémentation de Node-API en dehors de Node.js.

addon_node.c est un fichier séparé qui contient le point d'entrée spécifique à Node.js de l'addon et qui instancie l'addon en appelant addon.c lorsque l'addon est chargé dans un environnement 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);              \
      /* If an exception is already pending, don't rethrow it */  \
      if (!is_pending) {                                          \
        const char* message = (err_message == NULL)               \
            ? "empty error message"                               \
            : err_message;                                        \
        napi_throw_error((env), NULL, message);                   \
      }                                                           \
      return NULL;                                                \
    }                                                             \
  } while(0)

static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
  // Do something useful.
  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 */) {
  // This function body is expected to return a `napi_value`.
  // The variables `napi_env env` and `napi_value exports` may be used within
  // the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
  return create_addon(env);
}

APIs de cycle de vie de l'environnement

La section 8.7 de la spécification du langage ECMAScript définit le concept d'"Agent" comme un environnement autonome dans lequel le code JavaScript s'exécute. Plusieurs de ces Agents peuvent être démarrés et terminés, soit concurremment, soit séquentiellement par le processus.

Un environnement Node.js correspond à un Agent ECMAScript. Dans le processus principal, un environnement est créé au démarrage, et des environnements supplémentaires peuvent être créés sur des threads séparés pour servir de threads worker. Lorsque Node.js est intégré dans une autre application, le thread principal de l'application peut également construire et détruire un environnement Node.js plusieurs fois pendant le cycle de vie du processus d'application, de sorte que chaque environnement Node.js créé par l'application peut, à son tour, pendant son cycle de vie, créer et détruire des environnements supplémentaires en tant que threads worker.

Du point de vue d'un addon natif, cela signifie que les liaisons qu'il fournit peuvent être appelées plusieurs fois, à partir de plusieurs contextes, et même concurremment à partir de plusieurs threads.

Les addons natifs peuvent avoir besoin d'allouer un état global qu'ils utilisent pendant leur cycle de vie d'un environnement Node.js, de sorte que l'état puisse être unique à chaque instance de l'addon.

À cette fin, Node-API fournit un moyen d'associer des données de sorte que leur cycle de vie soit lié au cycle de vie d'un environnement Node.js.

napi_set_instance_data

Ajouté dans : v12.8.0, v10.20.0

Version 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: L'environnement sous lequel l'appel Node-API est invoqué.
• [in] data: L'élément de données à rendre disponible aux liaisons de cette instance.
• [in] finalize_cb: La fonction à appeler lorsque l'environnement est en cours de destruction. La fonction reçoit data afin de pouvoir le libérer. napi_finalize fournit plus de détails.
• [in] finalize_hint: Indice facultatif à transmettre à la fonction de finalisation lors de la collecte.

Retourne napi_ok si l'API a réussi.

Cette API associe data à l'environnement Node.js en cours d'exécution. data peut ensuite être récupéré à l'aide de napi_get_instance_data(). Toutes les données existantes associées à l'environnement Node.js en cours d'exécution qui ont été définies au moyen d'un appel précédent à napi_set_instance_data() seront écrasées. Si un finalize_cb a été fourni par l'appel précédent, il ne sera pas appelé.

napi_get_instance_data

Ajouté dans : v12.8.0, v10.20.0

Version N-API : 6

napi_status napi_get_instance_data(node_api_basic_env env,
                                   void** data);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [out] data: L'élément de données qui a été précédemment associé à l'environnement Node.js en cours d'exécution par un appel à napi_set_instance_data().

Retourne napi_ok si l'API a réussi.

Cette API récupère les données qui ont été précédemment associées à l'environnement Node.js en cours d'exécution via napi_set_instance_data(). Si aucune donnée n'est définie, l'appel réussira et data sera défini sur NULL.

Types de données Node-API de base

Node-API expose les types de données fondamentaux suivants comme des abstractions consommées par les différentes API. Ces API doivent être traitées comme opaques, introspectables uniquement avec d'autres appels Node-API.

napi_status

Ajouté dans : v8.0.0

Version N-API : 1

Code d'état intégral indiquant le succès ou l'échec d'un appel Node-API. Actuellement, les codes d'état suivants sont pris en charge.

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,  /* unused */
  napi_no_external_buffers_allowed,
  napi_cannot_run_js
} napi_status;

Si des informations supplémentaires sont nécessaires lorsqu'une API renvoie un statut d'échec, elles peuvent être obtenues en appelant napi_get_last_error_info.

napi_extended_error_info

Ajouté dans : v8.0.0

Version 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: Chaîne codée UTF8 contenant une description de l'erreur neutre pour la VM.
• engine_reserved: Réservé aux détails d'erreur spécifiques à la VM. Ceci n'est actuellement pas implémenté pour aucune VM.
• engine_error_code: Code d'erreur spécifique à la VM. Ceci n'est actuellement pas implémenté pour aucune VM.
• error_code: Le code d'état Node-API à l'origine de la dernière erreur.

Voir la section Gestion des erreurs pour plus d'informations.

napi_env

napi_env représente un contexte que l'implémentation sous-jacente de Node-API peut utiliser pour conserver un état spécifique à la VM. Cette structure est passée aux fonctions natives lorsqu'elles sont invoquées, et elle doit être renvoyée lors des appels Node-API. Plus précisément, le même napi_env qui a été passé lors de l'appel initial de la fonction native doit être passé à tous les appels Node-API imbriqués suivants. La mise en cache de napi_env dans le but d'une réutilisation générale et le passage de napi_env entre les instances du même addon s'exécutant sur différents threads Worker ne sont pas autorisés. napi_env devient invalide lorsqu'une instance d'un addon natif est déchargée. La notification de cet événement est transmise via les callbacks donnés à napi_add_env_cleanup_hook et napi_set_instance_data.

node_api_basic_env

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Cette variante de napi_env est passée aux finaliseurs synchrones (node_api_basic_finalize). Il existe un sous-ensemble d'API Node qui acceptent un paramètre de type node_api_basic_env comme premier argument. Ces API n'accèdent pas à l'état du moteur JavaScript et sont donc sûres à appeler à partir de finaliseurs synchrones. Passer un paramètre de type napi_env à ces API est autorisé, cependant, passer un paramètre de type node_api_basic_env aux API qui accèdent à l'état du moteur JavaScript n'est pas autorisé. Tenter de le faire sans cast produira un avertissement du compilateur ou une erreur lorsque les add-ons sont compilés avec des drapeaux qui les font émettre des avertissements et/ou des erreurs lorsque des types de pointeurs incorrects sont passés dans une fonction. Appeler de telles API à partir d'un finaliseur synchrone entraînera finalement la terminaison de l'application.

napi_value

Il s'agit d'un pointeur opaque utilisé pour représenter une valeur JavaScript.

napi_threadsafe_function

Ajouté dans : v10.6.0

Version N-API : 4

Il s’agit d’un pointeur opaque qui représente une fonction JavaScript pouvant être appelée de manière asynchrone à partir de plusieurs threads via napi_call_threadsafe_function().

napi_threadsafe_function_release_mode

Ajouté dans : v10.6.0

Version N-API : 4

Valeur à fournir à napi_release_threadsafe_function() pour indiquer si la fonction thread-safe doit être fermée immédiatement (napi_tsfn_abort) ou simplement libérée (napi_tsfn_release), et donc disponible pour une utilisation ultérieure via napi_acquire_threadsafe_function() et napi_call_threadsafe_function().

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

napi_threadsafe_function_call_mode

Ajouté dans : v10.6.0

Version N-API : 4

Valeur à fournir à napi_call_threadsafe_function() pour indiquer si l’appel doit bloquer lorsque la file d’attente associée à la fonction thread-safe est pleine.

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

Types de gestion de la mémoire Node-API

napi_handle_scope

Il s’agit d’une abstraction utilisée pour contrôler et modifier la durée de vie des objets créés dans une portée particulière. En général, les valeurs Node-API sont créées dans le contexte d’une portée de handle. Lorsqu’une méthode native est appelée à partir de JavaScript, une portée de handle par défaut existe. Si l’utilisateur ne crée pas explicitement une nouvelle portée de handle, les valeurs Node-API seront créées dans la portée de handle par défaut. Pour toute invocation de code en dehors de l’exécution d’une méthode native (par exemple, lors d’une invocation de rappel libuv), le module est tenu de créer une portée avant d’appeler toute fonction pouvant entraîner la création de valeurs JavaScript.

Les portées de handle sont créées à l’aide de napi_open_handle_scope et sont détruites à l’aide de napi_close_handle_scope. La fermeture de la portée peut indiquer au GC que toutes les napi_value créées pendant la durée de vie de la portée de handle ne sont plus référencées à partir de la frame de pile actuelle.

Pour plus de détails, consultez la section Gestion de la durée de vie des objets.

napi_escapable_handle_scope

Ajouté dans : v8.0.0

Version N-API : 1

Les scopes de handle escapables sont un type spécial de scope de handle permettant de renvoyer des valeurs créées au sein d'un scope de handle particulier à un scope parent.

napi_ref

Ajouté dans : v8.0.0

Version N-API : 1

Il s'agit de l'abstraction à utiliser pour référencer une napi_value. Cela permet aux utilisateurs de gérer la durée de vie des valeurs JavaScript, y compris de définir explicitement leur durée de vie minimale.

Pour plus de détails, consultez la section Gestion de la durée de vie des objets.

napi_type_tag

Ajouté dans : v14.8.0, v12.19.0

Version N-API : 8

Une valeur 128 bits stockée sous forme de deux entiers non signés sur 64 bits. Elle sert d'UUID avec lequel les objets JavaScript ou les externes peuvent être « étiquetés » afin de garantir qu'ils sont d'un certain type. Il s'agit d'une vérification plus stricte que napi_instanceof, car cette dernière peut signaler un faux positif si le prototype de l'objet a été manipulé. L'étiquetage de type est plus utile conjointement avec napi_wrap car il garantit que le pointeur récupéré à partir d'un objet encapsulé peut être converti en toute sécurité vers le type natif correspondant à l'étiquette de type qui avait été précédemment appliquée à l'objet JavaScript.

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag;

napi_async_cleanup_hook_handle

Ajouté dans : v14.10.0, v12.19.0

Une valeur opaque renvoyée par napi_add_async_cleanup_hook. Elle doit être passée à napi_remove_async_cleanup_hook lorsque la chaîne d'événements de nettoyage asynchrone est terminée.

Types de callback Node-API

napi_callback_info

Ajouté dans : v8.0.0

Version N-API : 1

Type de données opaque passé à une fonction de rappel. Il peut être utilisé pour obtenir des informations supplémentaires sur le contexte dans lequel le rappel a été invoqué.

napi_callback

Ajouté dans : v8.0.0

Version N-API : 1

Type de pointeur de fonction pour les fonctions natives fournies par l'utilisateur qui doivent être exposées à JavaScript via Node-API. Les fonctions de rappel doivent satisfaire la signature suivante :

typedef napi_value (*napi_callback)(napi_env, napi_callback_info);

Sauf pour les raisons discutées dans Gestion de la durée de vie des objets, la création d'un handle et/ou d'un scope de rappel à l'intérieur d'un napi_callback n'est pas nécessaire.

node_api_basic_finalize

Ajouté dans : v21.6.0, v20.12.0, v18.20.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Type de pointeur de fonction pour les fonctions fournies par les modules complémentaires qui permettent à l’utilisateur d’être informé lorsque des données détenues en externe sont prêtes à être nettoyées parce que l’objet auquel elles étaient associées a été ramassé par le garbage collector. L’utilisateur doit fournir une fonction répondant à la signature suivante qui sera appelée lors de la collecte de l’objet. Actuellement, node_api_basic_finalize peut être utilisé pour savoir quand les objets ayant des données externes sont collectés.

typedef void (*node_api_basic_finalize)(node_api_basic_env env,
                                      void* finalize_data,
                                      void* finalize_hint);

Sauf pour les raisons discutées dans Gestion du cycle de vie des objets, la création d’un handle et/ou d’une portée de rappel à l’intérieur du corps de la fonction n’est pas nécessaire.

Étant donné que ces fonctions peuvent être appelées alors que le moteur JavaScript est dans un état où il ne peut pas exécuter de code JavaScript, seules les API Node qui acceptent un node_api_basic_env comme premier paramètre peuvent être appelées. node_api_post_finalizer peut être utilisé pour planifier les appels d’API Node qui nécessitent l’accès à l’état du moteur JavaScript pour s’exécuter une fois que le cycle de ramassage des ordures en cours est terminé.

Dans le cas de node_api_create_external_string_latin1 et node_api_create_external_string_utf16, le paramètre env peut être nul, car les chaînes externes peuvent être collectées pendant la dernière partie de l’arrêt de l’environnement.

Historique des modifications :

• expérimental (NAPI_EXPERIMENTAL) : Seuls les appels d’API Node qui acceptent un node_api_basic_env comme premier paramètre peuvent être appelés, sinon l’application sera terminée avec un message d’erreur approprié. Cette fonctionnalité peut être désactivée en définissant NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.

napi_finalize

Ajouté dans : v8.0.0

Version N-API : 1

Type de pointeur de fonction pour une fonction fournie par le module complémentaire qui permet à l’utilisateur de planifier un groupe d’appels aux API Node en réponse à un événement de garbage collection, une fois le cycle de garbage collection terminé. Ces pointeurs de fonction peuvent être utilisés avec node_api_post_finalizer.

typedef void (*napi_finalize)(napi_env env,
                              void* finalize_data,
                              void* finalize_hint);

Historique des modifications :

• expérimental (NAPI_EXPERIMENTAL est défini) : une fonction de ce type peut ne plus être utilisée comme finaliseur, sauf avec node_api_post_finalizer. node_api_basic_finalize doit être utilisé à la place. Cette fonctionnalité peut être désactivée en définissant NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.

napi_async_execute_callback

Ajouté dans : v8.0.0

Version N-API : 1

Pointeur de fonction utilisé avec les fonctions prenant en charge les opérations asynchrones. Les fonctions de rappel doivent satisfaire la signature suivante :

typedef void (*napi_async_execute_callback)(napi_env env, void* data);

Les implémentations de cette fonction doivent éviter d’effectuer des appels d’API Node qui exécutent du JavaScript ou interagissent avec des objets JavaScript. Les appels d’API Node doivent se trouver dans napi_async_complete_callback à la place. N’utilisez pas le paramètre napi_env car cela entraînera probablement l’exécution de JavaScript.

napi_async_complete_callback

Ajouté dans : v8.0.0

Version N-API : 1

Pointeur de fonction utilisé avec les fonctions prenant en charge les opérations asynchrones. Les fonctions de rappel doivent satisfaire la signature suivante :

typedef void (*napi_async_complete_callback)(napi_env env,
                                             napi_status status,
                                             void* data);

Sauf pour les raisons discutées dans Gestion de la durée de vie des objets, la création d’une poignée et/ou d’une portée de rappel à l’intérieur du corps de la fonction n’est pas nécessaire.

napi_threadsafe_function_call_js

Ajouté dans : v10.6.0

Version N-API : 4

Pointeur de fonction utilisé avec les appels de fonction asynchrones et thread-safe. Le rappel sera appelé sur le thread principal. Son but est d’utiliser un élément de données arrivant via la file d’attente depuis l’un des threads secondaires pour construire les paramètres nécessaires à un appel vers JavaScript, généralement via napi_call_function, puis d’effectuer l’appel vers JavaScript.

Les données arrivant du thread secondaire via la file d’attente sont fournies dans le paramètre data et la fonction JavaScript à appeler est fournie dans le paramètre js_callback.

Node-API configure l’environnement avant d’appeler ce rappel, il suffit donc d’appeler la fonction JavaScript via napi_call_function plutôt que via napi_make_callback.

Les fonctions de rappel doivent satisfaire la signature suivante :

typedef void (*napi_threadsafe_function_call_js)(napi_env env,
                                                 napi_value js_callback,
                                                 void* context,
                                                 void* data);

• [in] env: L’environnement à utiliser pour les appels API, ou NULL si la fonction thread-safe est en cours de destruction et que data peut avoir besoin d’être libéré.
• [in] js_callback: La fonction JavaScript à appeler, ou NULL si la fonction thread-safe est en cours de destruction et que data peut avoir besoin d’être libéré. Elle peut également être NULL si la fonction thread-safe a été créée sans js_callback.
• [in] context: Les données facultatives avec lesquelles la fonction thread-safe a été créée.
• [in] data: Données créées par le thread secondaire. Il est de la responsabilité du rappel de convertir ces données natives en valeurs JavaScript (avec les fonctions Node-API) qui peuvent être passées comme paramètres lors de l’appel de js_callback. Ce pointeur est entièrement géré par les threads et ce rappel. Ainsi, ce rappel doit libérer les données.

Sauf pour les raisons décrites dans Gestion de la durée de vie des objets, la création d’un handle et/ou d’une portée de rappel à l’intérieur du corps de la fonction n’est pas nécessaire.

napi_cleanup_hook

Ajouté dans : v19.2.0, v18.13.0

Version N-API : 3

Pointeur de fonction utilisé avec napi_add_env_cleanup_hook. Il sera appelé lors de la destruction de l'environnement.

Les fonctions de rappel doivent satisfaire la signature suivante :

typedef void (*napi_cleanup_hook)(void* data);

• [in] data: Les données qui ont été passées à napi_add_env_cleanup_hook.

napi_async_cleanup_hook

Ajouté dans : v14.10.0, v12.19.0

Pointeur de fonction utilisé avec napi_add_async_cleanup_hook. Il sera appelé lors de la destruction de l'environnement.

Les fonctions de rappel doivent satisfaire la signature suivante :

typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
                                        void* data);

• [in] handle: Le handle qui doit être passé à napi_remove_async_cleanup_hook après l'achèvement du nettoyage asynchrone.
• [in] data: Les données qui ont été passées à napi_add_async_cleanup_hook.

Le corps de la fonction doit initier les actions de nettoyage asynchrones, à la fin desquelles handle doit être passé dans un appel à napi_remove_async_cleanup_hook.

Gestion des erreurs

Node-API utilise à la fois les valeurs de retour et les exceptions JavaScript pour la gestion des erreurs. Les sections suivantes expliquent l'approche pour chaque cas.

Valeurs de retour

Toutes les fonctions Node-API partagent le même modèle de gestion des erreurs. Le type de retour de toutes les fonctions de l'API est napi_status.

La valeur de retour sera napi_ok si la requête a réussi et qu'aucune exception JavaScript non interceptée n'a été levée. Si une erreur s'est produite ET qu'une exception a été levée, la valeur napi_status de l'erreur sera renvoyée. Si une exception a été levée et qu'aucune erreur ne s'est produite, napi_pending_exception sera renvoyé.

Dans les cas où une valeur de retour autre que napi_ok ou napi_pending_exception est renvoyée, napi_is_exception_pending doit être appelé pour vérifier si une exception est en attente. Voir la section sur les exceptions pour plus de détails.

L'ensemble complet des valeurs napi_status possibles est défini dans napi_api_types.h.

La valeur de retour napi_status fournit une représentation indépendante de la VM de l'erreur qui s'est produite. Dans certains cas, il est utile d'obtenir des informations plus détaillées, y compris une chaîne représentant l'erreur ainsi que des informations spécifiques à la VM (moteur).

Afin de récupérer ces informations, napi_get_last_error_info est fourni, qui renvoie une structure napi_extended_error_info. Le format de la structure napi_extended_error_info est le suivant :

Ajouté dans : v8.0.0

Version 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: Représentation textuelle de l'erreur survenue.
• engine_reserved: Handle opaque réservé à l'utilisation du moteur uniquement.
• engine_error_code: Code d'erreur spécifique à la VM.
• error_code: Code de statut Node-API pour la dernière erreur.

napi_get_last_error_info renvoie les informations pour le dernier appel Node-API effectué.

Ne vous fiez pas au contenu ou au format des informations étendues, car il n'est pas soumis à SemVer et peut changer à tout moment. Il est uniquement destiné à des fins de journalisation.

napi_get_last_error_info

Ajouté dans : v8.0.0

Version N-API : 1

napi_status
napi_get_last_error_info(node_api_basic_env env,
                         const napi_extended_error_info** result);

• [in] env: L'environnement dans lequel l'API est appelée.
• [out] result: La structure napi_extended_error_info contenant plus d'informations sur l'erreur.

Retourne napi_ok si l'API a réussi.

Cette API récupère une structure napi_extended_error_info contenant des informations sur la dernière erreur survenue.

Le contenu de la structure napi_extended_error_info retournée n'est valide que jusqu'à ce qu'une fonction Node-API soit appelée sur le même env. Cela inclut un appel à napi_is_exception_pending, il peut donc souvent être nécessaire de faire une copie des informations afin de pouvoir les utiliser plus tard. Le pointeur retourné dans error_message pointe vers une chaîne définie statiquement, il est donc sûr d'utiliser ce pointeur si vous l'avez copié depuis le champ error_message (qui sera écrasé) avant qu'une autre fonction Node-API ne soit appelée.

Ne vous fiez pas au contenu ou au format des informations étendues, car il n'est pas soumis à SemVer et peut changer à tout moment. Il est uniquement destiné à des fins de journalisation.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

Exceptions

Tout appel de fonction Node-API peut entraîner une exception JavaScript en attente. C'est le cas pour toutes les fonctions de l'API, même celles qui peuvent ne pas entraîner l'exécution de JavaScript.

Si le napi_status retourné par une fonction est napi_ok, aucune exception n'est en attente et aucune action supplémentaire n'est requise. Si le napi_status retourné est autre chose que napi_ok ou napi_pending_exception, afin d'essayer de récupérer et de continuer au lieu de simplement retourner immédiatement, napi_is_exception_pending doit être appelé afin de déterminer si une exception est en attente ou non.

Dans de nombreux cas, lorsqu'une fonction Node-API est appelée et qu'une exception est déjà en attente, la fonction retournera immédiatement avec un napi_status de napi_pending_exception. Cependant, ce n'est pas le cas pour toutes les fonctions. Node-API permet d'appeler un sous-ensemble de fonctions pour permettre un nettoyage minimal avant de retourner à JavaScript. Dans ce cas, napi_status reflétera le statut de la fonction. Il ne reflétera pas les exceptions en attente précédentes. Pour éviter toute confusion, vérifiez le statut d'erreur après chaque appel de fonction.

Lorsqu'une exception est en attente, deux approches peuvent être employées.

La première approche consiste à effectuer tout nettoyage approprié, puis à retourner afin que l'exécution retourne à JavaScript. Dans le cadre de la transition vers JavaScript, l'exception sera levée au point du code JavaScript où la méthode native a été invoquée. Le comportement de la plupart des appels Node-API n'est pas spécifié lorsqu'une exception est en attente, et beaucoup retourneront simplement napi_pending_exception, alors faites le moins de choses possible, puis retournez à JavaScript où l'exception peut être gérée.

La deuxième approche consiste à essayer de gérer l'exception. Il y aura des cas où le code natif peut intercepter l'exception, prendre les mesures appropriées, puis continuer. Ceci n'est recommandé que dans des cas spécifiques où il est connu que l'exception peut être gérée en toute sécurité. Dans ces cas, napi_get_and_clear_last_exception peut être utilisé pour obtenir et effacer l'exception. En cas de succès, result contiendra le handle du dernier Object JavaScript lancé. S'il est déterminé, après avoir récupéré l'exception, que l'exception ne peut pas être gérée après tout, elle peut être relancée avec napi_throw où error est la valeur JavaScript à lancer.

Les fonctions utilitaires suivantes sont également disponibles au cas où le code natif aurait besoin de lancer une exception ou de déterminer si une napi_value est une instance d'un objet Error JavaScript : napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error et napi_is_error.

Les fonctions utilitaires suivantes sont également disponibles au cas où le code natif aurait besoin de créer un objet Error : napi_create_error, napi_create_type_error, napi_create_range_error et node_api_create_syntax_error, où result est la napi_value qui fait référence au nouvel objet Error JavaScript créé.

Le projet Node.js ajoute des codes d'erreur à toutes les erreurs générées en interne. L'objectif est que les applications utilisent ces codes d'erreur pour toutes les vérifications d'erreur. Les messages d'erreur associés resteront, mais ne seront destinés qu'à être utilisés pour la journalisation et l'affichage, avec l'attente que le message puisse changer sans que SemVer ne s'applique. Afin de prendre en charge ce modèle avec Node-API, à la fois dans les fonctionnalités internes et pour les fonctionnalités spécifiques aux modules (car c'est une bonne pratique), les fonctions throw_ et create_ prennent un paramètre de code facultatif qui est la chaîne du code à ajouter à l'objet d'erreur. Si le paramètre facultatif est NULL, aucun code ne sera associé à l'erreur. Si un code est fourni, le nom associé à l'erreur est également mis à jour pour être :

originalName [code]

où originalName est le nom original associé à l'erreur et code est le code qui a été fourni. Par exemple, si le code est 'ERR_ERROR_1' et qu'un TypeError est créé, le nom sera :

TypeError [ERR_ERROR_1]

napi_throw

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] error: La valeur JavaScript à lever.

Retourne napi_ok si l'API a réussi.

Cette API lève la valeur JavaScript fournie.

napi_throw_error

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_throw_error(napi_env env,
                                         const char* code,
                                         const char* msg);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] code: Code d'erreur optionnel à définir sur l'erreur.
• [in] msg: Chaîne C représentant le texte à associer à l'erreur.

Retourne napi_ok si l'API a réussi.

Cette API lève une erreur JavaScript Error avec le texte fourni.

napi_throw_type_error

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
                                              const char* code,
                                              const char* msg);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] code: Code d'erreur optionnel à définir sur l'erreur.
• [in] msg: Chaîne C représentant le texte à associer à l'erreur.

Retourne napi_ok si l'API a réussi.

Cette API lève une erreur JavaScript TypeError avec le texte fourni.

napi_throw_range_error

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
                                               const char* code,
                                               const char* msg);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] code: Code d'erreur optionnel à définir sur l'erreur.
• [in] msg: Chaîne C représentant le texte à associer à l'erreur.

Retourne napi_ok si l'API a réussi.

Cette API lève une erreur JavaScript RangeError avec le texte fourni.

node_api_throw_syntax_error

Ajouté dans : v17.2.0, v16.14.0

Version N-API : 9

NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
                                                    const char* code,
                                                    const char* msg);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] code: Code d'erreur optionnel à définir sur l'erreur.
• [in] msg: Chaîne C représentant le texte à associer à l'erreur.

Retourne napi_ok si l'API a réussi.

Cette API lève une SyntaxError JavaScript avec le texte fourni.

napi_is_error

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_is_error(napi_env env,
                                      napi_value value,
                                      bool* result);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La napi_value à vérifier.
• [out] result: Valeur booléenne définie sur vrai si napi_value représente une erreur, faux sinon.

Retourne napi_ok si l'API a réussi.

Cette API interroge une napi_value pour vérifier si elle représente un objet erreur.

napi_create_error

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_create_error(napi_env env,
                                          napi_value code,
                                          napi_value msg,
                                          napi_value* result);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] code: napi_value optionnelle avec la chaîne pour le code d'erreur à associer à l'erreur.
• [in] msg: napi_value qui référence une chaîne JavaScript à utiliser comme message pour l'erreur.
• [out] result: napi_value représentant l'erreur créée.

Retourne napi_ok si l'API a réussi.

Cette API retourne une Error JavaScript avec le texte fourni.

napi_create_type_error

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] code: napi_value optionnelle avec la chaîne pour le code d'erreur à associer à l'erreur.
• [in] msg: napi_value qui référence une chaîne JavaScript à utiliser comme message pour l'erreur.
• [out] result: napi_value représentant l'erreur créée.

Retourne napi_ok si l'API a réussi.

Cette API retourne une TypeError JavaScript avec le texte fourni.

napi_create_range_error

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] code: napi_value optionnel avec la chaîne de caractères pour le code d'erreur à associer à l'erreur.
• [in] msg: napi_value qui fait référence à une chaîne de caractères JavaScript à utiliser comme message pour l'Error.
• [out] result: napi_value représentant l'erreur créée.

Retourne napi_ok si l'API a réussi.

Cette API retourne une RangeError JavaScript avec le texte fourni.

node_api_create_syntax_error

Ajouté dans : v17.2.0, v16.14.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] code: napi_value optionnel avec la chaîne de caractères pour le code d'erreur à associer à l'erreur.
• [in] msg: napi_value qui fait référence à une chaîne de caractères JavaScript à utiliser comme message pour l'Error.
• [out] result: napi_value représentant l'erreur créée.

Retourne napi_ok si l'API a réussi.

Cette API retourne une SyntaxError JavaScript avec le texte fourni.

napi_get_and_clear_last_exception

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [out] result: L'exception s'il y en a une en attente, NULL sinon.

Retourne napi_ok si l'API a réussi.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

napi_is_exception_pending

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_is_exception_pending(napi_env env, bool* result);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [out] result: Valeur booléenne qui est définie sur vrai s'il y a une exception en attente.

Retourne napi_ok si l'API a réussi.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

napi_fatal_exception

Ajouté dans : v9.10.0

Version N-API : 3

napi_status napi_fatal_exception(napi_env env, napi_value err);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] err: L'erreur qui est passée à 'uncaughtException'.

Déclenche un 'uncaughtException' en JavaScript. Utile si un rappel asynchrone lève une exception sans moyen de récupération.

Erreurs fatales

En cas d'erreur irrécupérable dans un addon natif, une erreur fatale peut être levée pour terminer immédiatement le processus.

napi_fatal_error

Ajouté dans : v8.2.0

Version 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: Emplacement optionnel où l'erreur s'est produite.
• [in] location_len: La longueur de l'emplacement en octets, ou NAPI_AUTO_LENGTH s'il est terminé par un caractère nul.
• [in] message: Le message associé à l'erreur.
• [in] message_len: La longueur du message en octets, ou NAPI_AUTO_LENGTH s'il est terminé par un caractère nul.

L'appel de fonction ne retourne rien, le processus sera terminé.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

Gestion du cycle de vie des objets

Au fur et à mesure que les appels Node-API sont effectués, les handles vers les objets dans le tas pour la machine virtuelle sous-jacente peuvent être renvoyés en tant que napi_values. Ces handles doivent maintenir les objets « vivants » jusqu'à ce qu'ils ne soient plus nécessaires par le code natif, sinon les objets pourraient être collectés avant que le code natif n'ait fini de les utiliser.

Lorsque les handles d'objets sont renvoyés, ils sont associés à un « scope ». La durée de vie du scope par défaut est liée à la durée de vie de l'appel de méthode native. Il en résulte que, par défaut, les handles restent valides et les objets associés à ces handles seront maintenus en vie pendant la durée de vie de l'appel de méthode native.

Dans de nombreux cas, cependant, il est nécessaire que les handles restent valides pour une durée de vie plus courte ou plus longue que celle de la méthode native. Les sections qui suivent décrivent les fonctions Node-API qui peuvent être utilisées pour modifier la durée de vie du handle par rapport à la valeur par défaut.

Rendre la durée de vie des handles inférieure à celle de la méthode native

Il est souvent nécessaire de rendre la durée de vie des handles plus courte que celle d'une méthode native. Par exemple, considérons une méthode native ayant une boucle qui itère sur les éléments d'un grand tableau :

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;
  }
  // faire quelque chose avec l'élément
}

Cela entraînerait la création d'un grand nombre de handles, consommant des ressources importantes. De plus, même si le code natif ne pouvait utiliser que le handle le plus récent, tous les objets associés seraient également maintenus en vie car ils partagent tous la même portée.

Pour gérer ce cas, Node-API fournit la possibilité d'établir une nouvelle « portée » à laquelle les handles nouvellement créés seront associés. Une fois que ces handles ne sont plus nécessaires, la portée peut être « fermée » et tous les handles associés à la portée sont invalidés. Les méthodes disponibles pour ouvrir/fermer les portées sont napi_open_handle_scope et napi_close_handle_scope.

Node-API ne prend en charge qu'une seule hiérarchie imbriquée de portées. Il n'y a qu'une seule portée active à tout moment, et tous les nouveaux handles seront associés à cette portée tant qu'elle est active. Les portées doivent être fermées dans l'ordre inverse de leur ouverture. De plus, toutes les portées créées dans une méthode native doivent être fermées avant de retourner de cette méthode.

Prenant l'exemple précédent, l'ajout d'appels à napi_open_handle_scope et napi_close_handle_scope garantirait qu'au plus un seul handle est valide tout au long de l'exécution de la boucle :

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;
  }
  // faire quelque chose avec l'élément
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
}

Lors de l'imbrication des portées, il existe des cas où un handle d'une portée interne doit survivre à la durée de vie de cette portée. Node-API prend en charge une « portée échappable » afin de gérer ce cas. Une portée échappable permet à un handle d'être « promu » afin qu'il « échappe » à la portée actuelle et que la durée de vie du handle passe de la portée actuelle à celle de la portée externe.

Les méthodes disponibles pour ouvrir/fermer les portées échappables sont napi_open_escapable_handle_scope et napi_close_escapable_handle_scope.

La demande de promotion d'un handle est effectuée via napi_escape_handle qui ne peut être appelée qu'une seule fois.

napi_open_handle_scope

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
                                               napi_handle_scope* result);

• [in] env: L'environnement sous lequel l'API est invoquée.
• [out] result: napi_value représentant la nouvelle portée.

Retourne napi_ok si l'API a réussi.

Cette API ouvre une nouvelle portée.

napi_close_handle_scope

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope);

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] scope: napi_value représentant la portée à fermer.

Retourne napi_ok si l'API a réussi.

Cette API ferme la portée passée en paramètre. Les portées doivent être fermées dans l'ordre inverse de leur création.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

napi_open_escapable_handle_scope

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status
    napi_open_escapable_handle_scope(napi_env env,
                                     napi_handle_scope* result);

• [in] env: L'environnement sous lequel l'API est invoquée.
• [out] result: napi_value représentant la nouvelle portée.

Retourne napi_ok si l'API a réussi.

Cette API ouvre une nouvelle portée depuis laquelle un objet peut être promu vers la portée externe.

napi_close_escapable_handle_scope

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope);

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] scope: napi_value représentant la portée à fermer.

Retourne napi_ok si l'API a réussi.

Cette API ferme la portée passée en paramètre. Les portées doivent être fermées dans l'ordre inverse de leur création.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

napi_escape_handle

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_escape_handle(napi_env env,
                               napi_escapable_handle_scope scope,
                               napi_value escapee,
                               napi_value* result);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] scope: napi_value représentant la portée actuelle.
• [in] escapee: napi_value représentant l'objet JavaScript à échapper.
• [out] result: napi_value représentant le handle de l'objet échappé dans la portée externe.

Retourne napi_ok si l'API a réussi.

Cette API promeut le handle vers l'objet JavaScript afin qu'il soit valide pendant toute la durée de vie de la portée externe. Elle ne peut être appelée qu'une seule fois par portée. Si elle est appelée plus d'une fois, une erreur sera renvoyée.

Cette API peut être appelée même s'il existe une exception JavaScript en attente.

Références aux valeurs ayant une durée de vie supérieure à celle de la méthode native

Dans certains cas, un addon devra être capable de créer et de référencer des valeurs ayant une durée de vie supérieure à celle d'une seule invocation de méthode native. Par exemple, pour créer un constructeur et utiliser ensuite ce constructeur dans une requête pour créer des instances, il doit être possible de référencer l'objet constructeur à travers de nombreuses requêtes de création d'instances différentes. Cela ne serait pas possible avec un handle normal renvoyé en tant que napi_value comme décrit dans la section précédente. La durée de vie d'un handle normal est gérée par les portées et toutes les portées doivent être fermées avant la fin d'une méthode native.

Node-API fournit des méthodes pour créer des références persistantes aux valeurs. Actuellement, Node-API autorise uniquement la création de références pour un ensemble limité de types de valeurs, notamment objet, externe, fonction et symbole.

Chaque référence a un compteur associé avec une valeur de 0 ou plus, qui détermine si la référence maintiendra la valeur correspondante en vie. Les références avec un compteur de 0 n'empêchent pas les valeurs d'être collectées. Les valeurs de type objet (objet, fonction, externe) et symbole deviennent des références « faibles » et restent accessibles tant qu'elles ne sont pas collectées. Tout compteur supérieur à 0 empêchera les valeurs d'être collectées.

Les valeurs de symbole ont différentes variantes. Le véritable comportement de référence faible n'est pris en charge que par les symboles locaux créés avec la fonction napi_create_symbol ou les appels du constructeur JavaScript Symbol(). Les symboles enregistrés globalement créés avec la fonction node_api_symbol_for ou les appels de la fonction JavaScript Symbol.for() restent toujours des références fortes car le garbage collector ne les collecte pas. Il en va de même pour les symboles bien connus tels que Symbol.iterator. Ils ne sont jamais collectés par le garbage collector.

Les références peuvent être créées avec un nombre de références initial. Le nombre peut ensuite être modifié via napi_reference_ref et napi_reference_unref. Si un objet est collecté alors que le nombre pour une référence est 0, tous les appels suivants pour obtenir l'objet associé à la référence napi_get_reference_value retourneront NULL pour la napi_value renvoyée. Une tentative d'appel de napi_reference_ref pour une référence dont l'objet a été collecté entraîne une erreur.

Les références doivent être supprimées une fois qu'elles ne sont plus nécessaires par l'addon. Lorsqu'une référence est supprimée, elle n'empêchera plus l'objet correspondant d'être collecté. La non-suppression d'une référence persistante entraîne une « fuite de mémoire » avec la mémoire native pour la référence persistante et l'objet correspondant sur le tas étant conservés indéfiniment.

Il peut y avoir plusieurs références persistantes créées qui référencent le même objet, chacune gardant ou non l'objet en vie en fonction de son nombre individuel. Plusieurs références persistantes au même objet peuvent entraîner le maintien inattendu de la mémoire native en vie. Les structures natives d'une référence persistante doivent rester actives jusqu'à ce que les finaliseurs de l'objet référencé soient exécutés. Si une nouvelle référence persistante est créée pour le même objet, les finaliseurs de cet objet ne seront pas exécutés et la mémoire native pointée par la référence persistante précédente ne sera pas libérée. Cela peut être évité en appelant napi_delete_reference en plus de napi_reference_unref lorsque cela est possible.

Historique des modifications :

• Expérimental (NAPI_EXPERIMENTAL est défini) : Des références peuvent être créées pour tous les types de valeurs. Les nouveaux types de valeurs pris en charge ne prennent pas en charge la sémantique de référence faible et les valeurs de ces types sont libérées lorsque le nombre de références devient 0 et ne peuvent plus être accessibles à partir de la référence.

napi_create_reference

Ajouté dans : v8.0.0

Version 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: L'environnement sous lequel l'API est invoquée.
• [in] value: La napi_value pour laquelle une référence est créée.
• [in] initial_refcount: Nombre de références initial pour la nouvelle référence.
• [out] result: napi_ref pointant vers la nouvelle référence.

Retourne napi_ok si l'API a réussi.

Cette API crée une nouvelle référence avec le nombre de références spécifié pour la valeur passée en paramètre.

napi_delete_reference

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] ref: napi_ref à supprimer.

Retourne napi_ok si l'API a réussi.

Cette API supprime la référence passée en paramètre.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

napi_reference_ref

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
                                           napi_ref ref,
                                           uint32_t* result);

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] ref: napi_ref pour lequel le nombre de références sera incrémenté.
• [out] result: Le nouveau nombre de références.

Retourne napi_ok si l'API a réussi.

Cette API incrémente le nombre de références pour la référence passée en paramètre et retourne le nombre de références résultant.

napi_reference_unref

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
                                             napi_ref ref,
                                             uint32_t* result);

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] ref: napi_ref pour lequel le nombre de références sera décrémenté.
• [out] result: Le nouveau nombre de références.

Retourne napi_ok si l'API a réussi.

Cette API décrémente le nombre de références pour la référence passée en paramètre et retourne le nombre de références résultant.

napi_get_reference_value

Ajouté dans : v8.0.0

Version N-API : 1

NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
                                                 napi_ref ref,
                                                 napi_value* result);

• [in] env: L'environnement sous lequel l'API est appelée.
• [in] ref: La napi_ref pour laquelle la valeur correspondante est demandée.
• [out] result: La napi_value référencée par la napi_ref.

Retourne napi_ok si l'API a réussi.

Si elle est toujours valide, cette API retourne la napi_value représentant la valeur JavaScript associée à la napi_ref. Sinon, result sera NULL.

Nettoyage à la sortie de l'environnement Node.js actuel

Bien qu'un processus Node.js libère généralement toutes ses ressources lors de sa sortie, les intégrateurs de Node.js, ou la prise en charge future des Workers, peuvent nécessiter que les modules complémentaires enregistrent des hooks de nettoyage qui seront exécutés une fois que l'environnement Node.js actuel aura quitté.

Node-API fournit des fonctions pour enregistrer et désenregistrer ces callbacks. Lorsque ces callbacks sont exécutés, toutes les ressources détenues par le module complémentaire doivent être libérées.

napi_add_env_cleanup_hook

Ajouté dans : v10.2.0

Version N-API : 3

NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
                                                  napi_cleanup_hook fun,
                                                  void* arg);

Enregistre fun comme fonction à exécuter avec le paramètre arg une fois que l'environnement Node.js actuel aura quitté.

Une fonction peut être spécifiée en toute sécurité plusieurs fois avec différentes valeurs arg. Dans ce cas, elle sera appelée plusieurs fois également. Fournir les mêmes valeurs fun et arg plusieurs fois n'est pas autorisé et entraînera l'arrêt du processus.

Les hooks seront appelés dans l'ordre inverse, c'est-à-dire que le plus récemment ajouté sera appelé en premier.

La suppression de ce hook peut être effectuée à l'aide de napi_remove_env_cleanup_hook. Typiquement, cela se produit lorsque la ressource pour laquelle ce hook a été ajouté est de toute façon détruite.

Pour un nettoyage asynchrone, napi_add_async_cleanup_hook est disponible.

napi_remove_env_cleanup_hook

Ajouté dans : v10.2.0

Version N-API : 3

NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
                                                     void (*fun)(void* arg),
                                                     void* arg);

Désoriente fun en tant que fonction à exécuter avec le paramètre arg une fois que l'environnement Node.js actuel se termine. L'argument et la valeur de la fonction doivent correspondre exactement.

La fonction doit avoir été initialement enregistrée avec napi_add_env_cleanup_hook, sinon le processus s'arrêtera.

napi_add_async_cleanup_hook

[Historique]

Version	Modifications
v14.10.0, v12.19.0	Signature du rappel hook modifiée.
v14.8.0, v12.19.0	Ajouté dans : v14.8.0, v12.19.0

Version 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: L'environnement sous lequel l'API est appelée.
• [in] hook: Le pointeur de fonction à appeler lors de la fermeture de l'environnement.
• [in] arg: Le pointeur à passer à hook lorsqu'il est appelé.
• [out] remove_handle: Gestionnaire facultatif qui fait référence au crochet de nettoyage asynchrone.

Enregistre hook, qui est une fonction de type napi_async_cleanup_hook, en tant que fonction à exécuter avec les paramètres remove_handle et arg une fois que l'environnement Node.js actuel se termine.

Contrairement à napi_add_env_cleanup_hook, le crochet peut être asynchrone.

Sinon, le comportement correspond généralement à celui de napi_add_env_cleanup_hook.

Si remove_handle n'est pas NULL, une valeur opaque y sera stockée et devra ensuite être passée à napi_remove_async_cleanup_hook, que le crochet ait déjà été invoqué ou non. Cela se produit généralement lorsque la ressource pour laquelle ce crochet a été ajouté est de toute façon en cours de suppression.

napi_remove_async_cleanup_hook

[Historique]

Version	Modifications
v14.10.0, v12.19.0	Paramètre env supprimé.
v14.8.0, v12.19.0	Ajouté dans : 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: Le handle d'un crochet de nettoyage asynchrone créé avec napi_add_async_cleanup_hook.

Désinscrit le crochet de nettoyage correspondant à remove_handle. Cela empêchera l'exécution du crochet, sauf s'il a déjà commencé à s'exécuter. Ceci doit être appelé sur toute valeur napi_async_cleanup_hook_handle obtenue à partir de napi_add_async_cleanup_hook.

Finalisation à la sortie de l'environnement Node.js

L'environnement Node.js peut être détruit à tout moment dès que possible, l'exécution JavaScript étant interdite, comme sur demande de worker.terminate(). Lorsque l'environnement est en cours de destruction, les callbacks napi_finalize enregistrés des objets JavaScript, des fonctions thread-safe et des données d'instance d'environnement sont appelés immédiatement et indépendamment.

L'appel des callbacks napi_finalize est planifié après les crochets de nettoyage enregistrés manuellement. Afin de garantir un ordre correct de finalisation des addons lors de l'arrêt de l'environnement pour éviter une utilisation après libération dans le callback napi_finalize, les addons doivent enregistrer un crochet de nettoyage avec napi_add_env_cleanup_hook et napi_add_async_cleanup_hook pour libérer manuellement la ressource allouée dans un ordre approprié.

Enregistrement du module

Les modules Node-API sont enregistrés de manière similaire aux autres modules, sauf qu'au lieu d'utiliser la macro NODE_MODULE, la suivante est utilisée :

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

La différence suivante concerne la signature de la méthode Init. Pour un module Node-API, elle est la suivante :

napi_value Init(napi_env env, napi_value exports);

La valeur de retour de Init est traitée comme l'objet exports du module. La méthode Init reçoit un objet vide via le paramètre exports pour plus de commodité. Si Init retourne NULL, le paramètre passé en tant que exports est exporté par le module. Les modules Node-API ne peuvent pas modifier l'objet module mais peuvent spécifier n'importe quoi comme propriété exports du module.

Pour ajouter la méthode hello en tant que fonction afin qu'elle puisse être appelée en tant que méthode fournie par l'addon :

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;
}

Pour définir une fonction à retourner par require() pour l'addon :

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;
}

Pour définir une classe afin que de nouvelles instances puissent être créées (souvent utilisée avec Encapsulation d'objet) :

// NOTE : exemple partiel, tout le code référencé n'est pas inclus
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;
}

Vous pouvez également utiliser la macro NAPI_MODULE_INIT, qui sert d'abréviation pour NAPI_MODULE et la définition d'une fonction 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;
}

Les paramètres env et exports sont fournis au corps de la macro NAPI_MODULE_INIT.

Tous les addons Node-API sont conscients du contexte, ce qui signifie qu'ils peuvent être chargés plusieurs fois. Il existe quelques considérations de conception lors de la déclaration d'un tel module. La documentation sur les addons conscients du contexte fournit plus de détails.

Les variables env et exports seront disponibles à l'intérieur du corps de la fonction suivant l'invocation de la macro.

Pour plus de détails sur la définition de propriétés sur les objets, consultez la section sur Travailler avec les propriétés JavaScript.

Pour plus de détails sur la création de modules addon en général, reportez-vous à l'API existante.

Travailler avec les valeurs JavaScript

Node-API expose un ensemble d'API pour créer tous les types de valeurs JavaScript. Certains de ces types sont documentés à la Section 6 de la Spécification du langage ECMAScript.

Fondamentalement, ces API sont utilisées pour effectuer l'une des opérations suivantes :

Les valeurs Node-API sont représentées par le type napi_value. Tout appel Node-API qui nécessite une valeur JavaScript prend en entrée une napi_value. Dans certains cas, l'API vérifie le type de la napi_value au préalable. Cependant, pour de meilleures performances, il est préférable que l'appelant s'assure que la napi_value en question est du type JavaScript attendu par l'API.

Types d'énumération

napi_key_collection_mode

Ajouté dans : v13.7.0, v12.17.0, v10.20.0

Version N-API : 6

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode;

Décrit les énumérations de filtre Clés/Propriétés :

napi_key_collection_mode limite la plage des propriétés collectées.

napi_key_own_only limite les propriétés collectées à l'objet donné uniquement. napi_key_include_prototypes inclura également toutes les clés de la chaîne de prototype de l'objet.

napi_key_filter

Ajouté dans : v13.7.0, v12.17.0, v10.20.0

Version 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 filtre de propriété. Ils peuvent être combinés avec le ou pour construire un filtre composite.

napi_key_conversion

Ajouté dans : v13.7.0, v12.17.0, v10.20.0

Version N-API : 6

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion;

napi_key_numbers_to_strings convertira les index entiers en chaînes. napi_key_keep_numbers renverra des nombres pour les index entiers.

napi_valuetype

typedef enum {
  // Types ES6 (correspond à typeof)
  napi_undefined,
  napi_null,
  napi_boolean,
  napi_number,
  napi_string,
  napi_symbol,
  napi_object,
  napi_function,
  napi_external,
  napi_bigint,
} napi_valuetype;

Décrit le type d'une napi_value. Cela correspond généralement aux types décrits à la Section 6.1 de la spécification du langage ECMAScript. En plus des types de cette section, napi_valuetype peut également représenter les fonctions et les objets avec des données externes.

Une valeur JavaScript de type napi_external apparaît en JavaScript sous la forme d'un objet simple tel qu'aucune propriété ne peut y être définie, et aucun prototype.

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;

Ceci représente le type de données scalaire binaire sous-jacent du TypedArray. Les éléments de cette énumération correspondent à la Section 22.2 de la spécification du langage ECMAScript.

Fonctions de création d'objets

napi_create_array

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_array(napi_env env, napi_value* result)

• [in] env : L’environnement dans lequel l’appel Node-API est invoqué.
• [out] result : Une napi_value représentant un tableau JavaScript.

Retourne napi_ok si l’API a réussi.

Cette API retourne une valeur Node-API correspondant à un type de tableau JavaScript. Les tableaux JavaScript sont décrits dans la section 22.1 de la spécification du langage ECMAScript.

napi_create_array_with_length

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_array_with_length(napi_env env,
                                          size_t length,
                                          napi_value* result)

• [in] env : L’environnement dans lequel l’API est invoquée.
• [in] length : La longueur initiale du tableau.
• [out] result : Une napi_value représentant un tableau JavaScript.

Retourne napi_ok si l’API a réussi.

Cette API retourne une valeur Node-API correspondant à un type de tableau JavaScript. La propriété length du tableau est définie sur le paramètre de longueur passé en entrée. Cependant, la mémoire tampon sous-jacente n’est pas garantie d’être pré-allouée par la VM lors de la création du tableau. Ce comportement est laissé à l’implémentation de la VM sous-jacente. Si la mémoire tampon doit être un bloc de mémoire contiguë qui peut être lu et/ou écrit directement via C, pensez à utiliser napi_create_external_arraybuffer.

Les tableaux JavaScript sont décrits dans la section 22.1 de la spécification du langage ECMAScript.

napi_create_arraybuffer

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_arraybuffer(napi_env env,
                                    size_t byte_length,
                                    void** data,
                                    napi_value* result)

• [in] env : L’environnement dans lequel l’API est appelée.
• [in] length : La longueur en octets du tampon de tableau à créer.
• [out] data : Pointeur vers le tampon d’octets sous-jacent de l’ArrayBuffer. data peut être ignoré facultativement en passant NULL.
• [out] result : Une napi_value représentant un ArrayBuffer JavaScript.

Retourne napi_ok si l’API a réussi.

Cette API retourne une valeur Node-API correspondant à un ArrayBuffer JavaScript. Les ArrayBuffer sont utilisés pour représenter des tampons de données binaires de longueur fixe. Ils sont normalement utilisés comme tampon de sauvegarde pour les objets TypedArray. L’ArrayBuffer alloué aura un tampon d’octets sous-jacent dont la taille est déterminée par le paramètre length passé. Le tampon sous-jacent est facultativement renvoyé à l’appelant au cas où l’appelant souhaite manipuler directement le tampon. Ce tampon ne peut être écrit directement que depuis le code natif. Pour écrire dans ce tampon depuis JavaScript, un tableau typé ou un objet DataView devrait être créé.

Les objets ArrayBuffer JavaScript sont décrits dans la section 24.1 de la spécification du langage ECMAScript.

napi_create_buffer

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_buffer(napi_env env,
                               size_t size,
                               void** data,
                               napi_value* result)

• [in] env : L’environnement dans lequel l’API est appelée.
• [in] size : Taille en octets du tampon sous-jacent.
• [out] data : Pointeur brut vers le tampon sous-jacent. data peut être ignoré facultativement en passant NULL.
• [out] result : Une napi_value représentant un node::Buffer.

Retourne napi_ok si l’API a réussi.

Cette API alloue un objet node::Buffer. Bien qu’il s’agisse toujours d’une structure de données entièrement prise en charge, dans la plupart des cas, l’utilisation d’un TypedArray suffira.

napi_create_buffer_copy

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] size: Taille en octets du tampon d'entrée (doit être la même que la taille du nouveau tampon).
• [in] data: Pointeur brut vers le tampon sous-jacent à copier.
• [out] result_data: Pointeur vers le tampon de données sous-jacent du nouveau Buffer. result_data peut être facultativement ignoré en passant NULL.
• [out] result: Une napi_value représentant un node::Buffer.

Retourne napi_ok si l'API a réussi.

Cette API alloue un objet node::Buffer et l'initialise avec des données copiées depuis le tampon passé en entrée. Bien qu'il s'agisse toujours d'une structure de données entièrement prise en charge, dans la plupart des cas, l'utilisation d'un TypedArray suffira.

napi_create_date

Ajouté dans : v11.11.0, v10.17.0

Version N-API : 5

napi_status napi_create_date(napi_env env,
                             double time,
                             napi_value* result);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] time: Valeur temporelle ECMAScript en millisecondes depuis le 1er janvier 1970 UTC.
• [out] result: Une napi_value représentant un objet Date JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API n'observe pas les secondes intercalaires ; elles sont ignorées, car ECMAScript s'aligne sur la spécification temporelle POSIX.

Cette API alloue un objet Date JavaScript.

Les objets Date JavaScript sont décrits dans la section 20.3 de la spécification du langage ECMAScript.

napi_create_external

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] data: Pointeur brut vers les données externes.
• [in] finalize_cb: Rappel facultatif à appeler lorsque la valeur externe est en cours de collecte. napi_finalize fournit plus de détails.
• [in] finalize_hint: Indication facultative à transmettre au rappel de finalisation lors de la collecte.
• [out] result: Une napi_value représentant une valeur externe.

Retourne napi_ok si l'API a réussi.

Cette API alloue une valeur JavaScript avec des données externes qui y sont attachées. Ceci est utilisé pour passer des données externes via le code JavaScript, afin qu'elles puissent être récupérées plus tard par le code natif à l'aide de napi_get_value_external.

L'API ajoute un rappel napi_finalize qui sera appelé lorsque l'objet JavaScript qui vient d'être créé a été collecté par le garbage collector.

La valeur créée n'est pas un objet et ne prend donc pas en charge les propriétés supplémentaires. Elle est considérée comme un type de valeur distinct : appeler napi_typeof() avec une valeur externe donne napi_external.

napi_create_external_arraybuffer

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est appelée.
• [in] external_data: Pointeur vers le buffer d'octets sous-jacent de l'ArrayBuffer.
• [in] byte_length: La longueur en octets du buffer sous-jacent.
• [in] finalize_cb: Callback optionnel à appeler lorsque l'ArrayBuffer est collecté. napi_finalize fournit plus de détails.
• [in] finalize_hint: Indication optionnelle à passer au callback de finalisation lors de la collecte.
• [out] result: Une napi_value représentant un ArrayBuffer JavaScript.

Retourne napi_ok si l'API a réussi.

Certains runtimes autres que Node.js ont abandonné la prise en charge des buffers externes. Sur les runtimes autres que Node.js, cette méthode peut retourner napi_no_external_buffers_allowed pour indiquer que les buffers externes ne sont pas pris en charge. Electron est un de ces runtimes, comme décrit dans ce problème electron/issues/35801.

Afin de maintenir la plus large compatibilité avec tous les runtimes, vous pouvez définir NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED dans votre addon avant les inclusions des en-têtes node-api. Cela cachera les 2 fonctions qui créent des buffers externes. Cela garantira qu'une erreur de compilation se produit si vous utilisez accidentellement l'une de ces méthodes.

Cette API retourne une valeur Node-API correspondant à un ArrayBuffer JavaScript. Le buffer d'octets sous-jacent de l'ArrayBuffer est alloué et géré en externe. L'appelant doit s'assurer que le buffer d'octets reste valide jusqu'à ce que le callback de finalisation soit appelé.

L'API ajoute un callback napi_finalize qui sera appelé lorsque l'objet JavaScript qui vient d'être créé a été collecté par le garbage collector.

Les ArrayBuffer JavaScript sont décrits dans la Section 24.1 de la spécification du langage ECMAScript.

napi_create_external_buffer

Ajouté dans : v8.0.0

Version 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: L'environnement sous lequel l'API est invoquée.
• [in] length: Taille en octets du buffer d'entrée (doit être la même que la taille du nouveau buffer).
• [in] data: Pointeur brut vers le buffer sous-jacent à exposer à JavaScript.
• [in] finalize_cb: Callback optionnel à appeler lorsque le ArrayBuffer est collecté. napi_finalize fournit plus de détails.
• [in] finalize_hint: Indication optionnelle à transmettre au callback de finalisation lors de la collecte.
• [out] result: Une napi_value représentant un node::Buffer.

Retourne napi_ok si l'API a réussi.

Certains runtimes autres que Node.js ont abandonné la prise en charge des buffers externes. Sur les runtimes autres que Node.js, cette méthode peut retourner napi_no_external_buffers_allowed pour indiquer que les buffers externes ne sont pas pris en charge. Electron est un de ces runtimes, comme décrit dans ce problème electron/issues/35801.

Afin de maintenir la compatibilité la plus large avec tous les runtimes, vous pouvez définir NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED dans votre addon avant les inclusions des en-têtes node-api. Cela permettra de masquer les 2 fonctions qui créent des buffers externes. Cela garantira qu'une erreur de compilation se produit si vous utilisez accidentellement l'une de ces méthodes.

Cette API alloue un objet node::Buffer et l'initialise avec des données sauvegardées par le buffer passé. Bien qu'il s'agisse toujours d'une structure de données entièrement prise en charge, dans la plupart des cas, l'utilisation d'un TypedArray suffira.

L'API ajoute un callback napi_finalize qui sera appelé lorsque l'objet JavaScript nouvellement créé aura été collecté par le garbage collector.

Pour Node.js >=4, les Buffers sont des Uint8Array.

napi_create_object

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_object(napi_env env, napi_value* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [out] result: Une napi_value représentant un objet JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API alloue un objet JavaScript par défaut. C'est l'équivalent de new Object() en JavaScript.

Le type Objet JavaScript est décrit dans la Section 6.1.7 de la spécification du langage ECMAScript.

napi_create_symbol

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_symbol(napi_env env,
                               napi_value description,
                               napi_value* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] description: napi_value optionnelle qui fait référence à une chaîne JavaScript à définir comme description du symbole.
• [out] result: Une napi_value représentant un symbole JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de symbole JavaScript à partir d'une chaîne C codée en UTF8.

Le type symbole JavaScript est décrit dans la Section 19.4 de la spécification du langage ECMAScript.

node_api_symbol_for

Ajouté dans : v17.5.0, v16.15.0

Version N-API : 9

napi_status node_api_symbol_for(napi_env env,
                                const char* utf8description,
                                size_t length,
                                napi_value* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] utf8description: Chaîne C UTF-8 représentant le texte à utiliser comme description du symbole.
• [in] length: La longueur de la chaîne de description en octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.
• [out] result: Une napi_value représentant un symbole JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API recherche dans le registre global un symbole existant avec la description donnée. Si le symbole existe déjà, il sera renvoyé, sinon un nouveau symbole sera créé dans le registre.

Le type symbole JavaScript est décrit dans la Section 19.4 de la spécification du langage ECMAScript.

napi_create_typedarray

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est appelée.
• [in] type: Type de données scalaire des éléments dans le TypedArray.
• [in] length: Nombre d'éléments dans le TypedArray.
• [in] arraybuffer: ArrayBuffer sous-jacent au tableau typé.
• [in] byte_offset: Le décalage en octets dans le ArrayBuffer à partir duquel commencer la projection du TypedArray.
• [out] result: Une napi_value représentant un TypedArray JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API crée un objet TypedArray JavaScript sur un ArrayBuffer existant. Les objets TypedArray fournissent une vue de type tableau sur un buffer de données sous-jacent où chaque élément a le même type de données scalaire binaire sous-jacent.

Il est requis que (length * size_of_element) + byte_offset soit <= la taille en octets du tableau passé en paramètre. Sinon, une exception RangeError est levée.

Les objets TypedArray JavaScript sont décrits dans la Section 22.2 de la spécification du langage ECMAScript.

node_api_create_buffer_from_arraybuffer

Ajouté dans : v23.0.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

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: L'environnement dans lequel l'API est appelée.
• [in] arraybuffer: Le ArrayBuffer à partir duquel le buffer sera créé.
• [in] byte_offset: Le décalage en octets dans le ArrayBuffer à partir duquel commencer la création du buffer.
• [in] byte_length: La longueur en octets du buffer à créer à partir du ArrayBuffer.
• [out] result: Une napi_value représentant l'objet Buffer JavaScript créé.

Retourne napi_ok si l'API a réussi.

Cette API crée un objet Buffer JavaScript à partir d'un ArrayBuffer existant. L'objet Buffer est une classe spécifique à Node.js qui fournit un moyen de travailler directement avec les données binaires en JavaScript.

La plage d'octets [byte_offset, byte_offset + byte_length) doit être dans les limites du ArrayBuffer. Si byte_offset + byte_length dépasse la taille du ArrayBuffer, une exception RangeError est levée.

napi_create_dataview

Ajouté dans : v8.3.0

Version 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: L'environnement dans lequel l'API est appelée.
• [in] length: Nombre d'éléments dans le DataView.
• [in] arraybuffer: ArrayBuffer sous-jacent au DataView.
• [in] byte_offset: Le décalage en octets dans le ArrayBuffer à partir duquel commencer la projection du DataView.
• [out] result: Une napi_value représentant un DataView JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API crée un objet DataView JavaScript sur un ArrayBuffer existant. Les objets DataView fournissent une vue de type tableau sur un buffer de données sous-jacent, mais qui permet des éléments de taille et de type différents dans le ArrayBuffer.

Il est nécessaire que byte_length + byte_offset soit inférieur ou égal à la taille en octets du tableau passé en paramètre. Sinon, une exception RangeError est levée.

Les objets DataView JavaScript sont décrits dans la Section 24.3 de la spécification du langage ECMAScript.

Fonctions de conversion des types C vers Node-API

napi_create_int32

Ajouté dans : v8.4.0

Version N-API : 1

napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: Valeur entière à représenter en JavaScript.
• [out] result: Une napi_value représentant un number JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API est utilisée pour convertir le type C int32_t en type number JavaScript.

Le type number JavaScript est décrit dans la Section 6.1.6 de la spécification du langage ECMAScript.

napi_create_uint32

Ajouté dans : v8.4.0

Version N-API : 1

napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: Valeur entière non signée à représenter en JavaScript.
• [out] result: Une napi_value représentant un number JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API est utilisée pour convertir le type C uint32_t en type JavaScript number.

Le type JavaScript number est décrit dans la Section 6.1.6 de la spécification du langage ECMAScript.

napi_create_int64

Ajouté dans : v8.4.0

Version N-API : 1

napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: Valeur entière à représenter en JavaScript.
• [out] result: Une napi_value représentant un number JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API est utilisée pour convertir le type C int64_t en type JavaScript number.

Le type JavaScript number est décrit dans la Section 6.1.6 de la spécification du langage ECMAScript. Notez que la plage complète de int64_t ne peut pas être représentée avec une précision totale en JavaScript. Les valeurs entières en dehors de la plage de Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) perdront en précision.

napi_create_double

Ajouté dans : v8.4.0

Version N-API : 1

napi_status napi_create_double(napi_env env, double value, napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: Valeur double précision à représenter en JavaScript.
• [out] result: Une napi_value représentant un number JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API est utilisée pour convertir le type C double en type JavaScript number.

Le type JavaScript number est décrit dans la Section 6.1.6 de la spécification du langage ECMAScript.

napi_create_bigint_int64

Ajouté dans : v10.7.0

Version N-API : 6

napi_status napi_create_bigint_int64(napi_env env,
                                     int64_t value,
                                     napi_value* result);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: Valeur entière à représenter en JavaScript.
• [out] result: Une napi_value représentant un BigInt JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API convertit le type C int64_t en type JavaScript BigInt.

napi_create_bigint_uint64

Ajouté dans : v10.7.0

Version N-API : 6

napi_status napi_create_bigint_uint64(napi_env env,
                                      uint64_t value,
                                      napi_value* result);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: Valeur entière non signée à représenter en JavaScript.
• [out] result: Une napi_value représentant un BigInt JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API convertit le type C uint64_t en type JavaScript BigInt.

napi_create_bigint_words

Ajouté dans : v10.7.0

Version 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: L'environnement dans lequel l'API est appelée.
• [in] sign_bit: Détermine si le BigInt résultant sera positif ou négatif.
• [in] word_count: La longueur du tableau words.
• [in] words: Un tableau de mots 64 bits little-endian uint64_t.
• [out] result: Une napi_value représentant un BigInt JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API convertit un tableau de mots non signés de 64 bits en une seule valeur BigInt.

Le BigInt résultant est calculé comme : (–1)^sign_bit (words[0] × (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)

napi_create_string_latin1

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_string_latin1(napi_env env,
                                      const char* str,
                                      size_t length,
                                      napi_value* result);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] str: Buffer de caractères représentant une chaîne codée en ISO-8859-1.
• [in] length: La longueur de la chaîne en octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.
• [out] result: Une napi_value représentant une chaîne JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de chaîne JavaScript à partir d'une chaîne C codée en ISO-8859-1. La chaîne native est copiée.

Le type de chaîne JavaScript est décrit dans la section 6.1.4 de la spécification du langage ECMAScript.

node_api_create_external_string_latin1

Ajouté dans : v20.4.0, v18.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

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: L'environnement dans lequel l'API est appelée.

• [in] str: Buffer de caractères représentant une chaîne codée en ISO-8859-1.

• [in] length: La longueur de la chaîne en octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.

• [in] finalize_callback: La fonction à appeler lorsque la chaîne est collectée. La fonction sera appelée avec les paramètres suivants :

  • [in] env: L'environnement dans lequel l'extension s'exécute. Cette valeur peut être nulle si la chaîne est collectée dans le cadre de la terminaison du worker ou de l'instance principale Node.js.
  • [in] data: C'est la valeur str en tant que pointeur void*.
  • [in] finalize_hint: C'est la valeur finalize_hint qui a été donnée à l'API. napi_finalize fournit plus de détails. Ce paramètre est facultatif. Passer une valeur nulle signifie que l'extension n'a pas besoin d'être notifiée lorsque la chaîne JavaScript correspondante est collectée.

• [in] finalize_hint: Indication facultative à transmettre à la fonction de finalisation lors de la collecte.

• [out] result: Une napi_value représentant une chaîne JavaScript.

• [out] copied: Si la chaîne a été copiée. Si c'est le cas, la fonction de finalisation a déjà été appelée pour détruire str.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de chaîne JavaScript à partir d'une chaîne C codée en ISO-8859-1. La chaîne native peut ne pas être copiée et doit donc exister pendant tout le cycle de vie de la valeur JavaScript.

Le type de chaîne JavaScript est décrit dans la section 6.1.4 de la spécification du langage ECMAScript.

napi_create_string_utf16

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_string_utf16(napi_env env,
                                     const char16_t* str,
                                     size_t length,
                                     napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] str: Buffer de caractères représentant une chaîne codée UTF16-LE.
• [in] length: La longueur de la chaîne en unités de code de deux octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.
• [out] result: Une napi_value représentant une chaîne JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de chaîne JavaScript à partir d'une chaîne C codée UTF16-LE. La chaîne native est copiée.

Le type de chaîne JavaScript est décrit dans la section 6.1.4 de la spécification du langage ECMAScript.

node_api_create_external_string_utf16

Ajouté dans : v20.4.0, v18.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

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: L'environnement dans lequel l'API est appelée.

• [in] str: Buffer de caractères représentant une chaîne codée UTF16-LE.

• [in] length: La longueur de la chaîne en unités de code de deux octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.

• [in] finalize_callback: La fonction à appeler lorsque la chaîne est collectée. La fonction sera appelée avec les paramètres suivants :

  • [in] env: L'environnement dans lequel le module complémentaire s'exécute. Cette valeur peut être nulle si la chaîne est collectée dans le cadre de la terminaison du worker ou de l'instance principale de Node.js.
  • [in] data: C'est la valeur str en tant que pointeur void*.
  • [in] finalize_hint: C'est la valeur finalize_hint qui a été donnée à l'API. napi_finalize fournit plus de détails. Ce paramètre est facultatif. Passer une valeur nulle signifie que le module complémentaire n'a pas besoin d'être averti lorsque la chaîne JavaScript correspondante est collectée.

• [in] finalize_hint: Indication facultative à passer à la fonction de finalisation lors de la collecte.

• [out] result: Une napi_value représentant une chaîne JavaScript.

• [out] copied: Indique si la chaîne a été copiée. Si c'est le cas, la fonction de finalisation aura déjà été appelée pour détruire str.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de chaîne JavaScript à partir d'une chaîne C codée UTF16-LE. La chaîne native peut ne pas être copiée et doit donc exister pendant tout le cycle de vie de la valeur JavaScript.

Le type de chaîne JavaScript est décrit dans la section 6.1.4 de la spécification du langage ECMAScript.

napi_create_string_utf8

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_create_string_utf8(napi_env env,
                                    const char* str,
                                    size_t length,
                                    napi_value* result)

• [in] env: L'environnement sous lequel l'API est appelée.
• [in] str: Buffer de caractères représentant une chaîne codée en UTF8.
• [in] length: La longueur de la chaîne en octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.
• [out] result: Une napi_value représentant une chaîne JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de chaîne JavaScript à partir d'une chaîne C codée en UTF8. La chaîne native est copiée.

Le type de chaîne JavaScript est décrit dans la Section 6.1.4 de la spécification du langage ECMAScript.

Fonctions pour créer des clés de propriétés optimisées

De nombreux moteurs JavaScript, y compris V8, utilisent des chaînes internalisées comme clés pour définir et obtenir des valeurs de propriétés. Ils utilisent généralement une table de hachage pour créer et rechercher ces chaînes. Bien que cela ajoute un certain coût par création de clé, cela améliore les performances par la suite en permettant la comparaison de pointeurs de chaînes au lieu des chaînes entières.

Si une nouvelle chaîne JavaScript est destinée à être utilisée comme clé de propriété, alors pour certains moteurs JavaScript, il sera plus efficace d'utiliser les fonctions de cette section. Sinon, utilisez les fonctions de la série napi_create_string_utf8 ou node_api_create_external_string_utf8 car il peut y avoir des frais généraux supplémentaires lors de la création/du stockage de chaînes avec les méthodes de création de clés de propriétés.

node_api_create_property_key_latin1

Ajouté dans : v22.9.0, v20.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
                                                           const char* str,
                                                           size_t length,
                                                           napi_value* result);

• [in] env: L'environnement sous lequel l'API est appelée.
• [in] str: Buffer de caractères représentant une chaîne codée en ISO-8859-1.
• [in] length: La longueur de la chaîne en octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.
• [out] result: Une napi_value représentant une chaîne JavaScript optimisée à utiliser comme clé de propriété pour les objets.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de chaîne JavaScript optimisée à partir d'une chaîne C codée en ISO-8859-1 à utiliser comme clé de propriété pour les objets. La chaîne native est copiée. Contrairement à napi_create_string_latin1, les appels suivants à cette fonction avec le même pointeur str peuvent bénéficier d'une accélération dans la création de la napi_value demandée, selon le moteur.

Le type de chaîne JavaScript est décrit dans la Section 6.1.4 de la spécification du langage ECMAScript.

node_api_create_property_key_utf16

Ajouté dans : v21.7.0, v20.12.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

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: L'environnement dans lequel l'API est appelée.
• [in] str: Buffer de caractères représentant une chaîne codée en UTF16-LE.
• [in] length: La longueur de la chaîne en unités de code à deux octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.
• [out] result: Une napi_value représentant une chaîne JavaScript optimisée à utiliser comme clé de propriété pour les objets.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de chaîne JavaScript optimisée à partir d'une chaîne C codée en UTF16-LE à utiliser comme clé de propriété pour les objets. La chaîne native est copiée.

Le type de chaîne JavaScript est décrit dans la section 6.1.4 de la spécification du langage ECMAScript.

node_api_create_property_key_utf8

Ajouté dans : v22.9.0, v20.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
                                                         const char* str,
                                                         size_t length,
                                                         napi_value* result);

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] str: Buffer de caractères représentant une chaîne codée en UTF8.
• [in] length: La longueur de la chaîne en unités de code à deux octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère nul.
• [out] result: Une napi_value représentant une chaîne JavaScript optimisée à utiliser comme clé de propriété pour les objets.

Retourne napi_ok si l'API a réussi.

Cette API crée une valeur de chaîne JavaScript optimisée à partir d'une chaîne C codée en UTF8 à utiliser comme clé de propriété pour les objets. La chaîne native est copiée.

Le type de chaîne JavaScript est décrit dans la section 6.1.4 de la spécification du langage ECMAScript.

Fonctions de conversion de Node-API vers les types C

napi_get_array_length

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_array_length(napi_env env,
                                  napi_value value,
                                  uint32_t* result)

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] value: napi_value représentant le tableau JavaScript dont la longueur est interrogée.
• [out] result: uint32 représentant la longueur du tableau.

Retourne napi_ok si l'API a réussi.

Cette API retourne la longueur d'un tableau.

La longueur du tableau est décrite dans la section 22.1.4.1 de la spécification du langage ECMAScript.

napi_get_arraybuffer_info

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_arraybuffer_info(napi_env env,
                                      napi_value arraybuffer,
                                      void** data,
                                      size_t* byte_length)

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] arraybuffer: napi_value représentant le ArrayBuffer interrogé.
• [out] data: Le buffer de données sous-jacent du ArrayBuffer. Si byte_length est 0, cela peut être NULL ou toute autre valeur de pointeur.
• [out] byte_length: Longueur en octets du buffer de données sous-jacent.

Retourne napi_ok si l'API a réussi.

Cette API est utilisée pour récupérer le buffer de données sous-jacent d'un ArrayBuffer et sa longueur.

_AVERTISSEMENT _: Soyez prudent lors de l'utilisation de cette API. La durée de vie du buffer de données sous-jacent est gérée par le ArrayBuffer même après son retour. Une façon sûre d'utiliser cette API consiste à l'utiliser conjointement avec napi_create_reference, qui peut être utilisée pour garantir le contrôle de la durée de vie du ArrayBuffer. Il est également sûr d'utiliser le buffer de données retourné dans le même rappel tant qu'il n'y a pas d'appels à d'autres API qui pourraient déclencher un ramasse-miettes.

napi_get_buffer_info

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_buffer_info(napi_env env,
                                 napi_value value,
                                 void** data,
                                 size_t* length)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: napi_value représentant le node::Buffer ou le Uint8Array interrogé.
• [out] data: Le buffer de données sous-jacent du node::Buffer ou du Uint8Array. Si length est 0, cela peut être NULL ou toute autre valeur de pointeur.
• [out] length: Longueur en octets du buffer de données sous-jacent.

Retourne napi_ok si l'API a réussi.

Cette méthode retourne les mêmes data et byte_length que napi_get_typedarray_info. Et napi_get_typedarray_info accepte aussi un node::Buffer (un Uint8Array) comme valeur.

Cette API est utilisée pour récupérer le buffer de données sous-jacent d'un node::Buffer et sa longueur.

_Avertissement _: Soyez prudent lors de l'utilisation de cette API car la durée de vie du buffer de données sous-jacent n'est pas garantie s'il est géré par la VM.

napi_get_prototype

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_prototype(napi_env env,
                               napi_value object,
                               napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] object: napi_value représentant l'objet JavaScript Object dont le prototype doit être retourné. Cela retourne l'équivalent de Object.getPrototypeOf (qui n'est pas le même que la propriété prototype de la fonction).
• [out] result: napi_value représentant le prototype de l'objet donné.

Retourne napi_ok si l'API a réussi.

napi_get_typedarray_info

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est appelée.
• [in] typedarray: napi_value représentant le TypedArray dont les propriétés doivent être interrogées.
• [out] type: Type de données scalaire des éléments dans le TypedArray.
• [out] length: Le nombre d'éléments dans le TypedArray.
• [out] data: Le buffer de données sous-jacent au TypedArray ajusté par la valeur byte_offset afin qu'il pointe vers le premier élément du TypedArray. Si la longueur du tableau est 0, cela peut être NULL ou toute autre valeur de pointeur.
• [out] arraybuffer: L'ArrayBuffer sous-jacent au TypedArray.
• [out] byte_offset: Le décalage en octets dans le tableau natif sous-jacent où se trouve le premier élément des tableaux. La valeur du paramètre data a déjà été ajustée afin que data pointe vers le premier élément du tableau. Par conséquent, le premier octet du tableau natif serait à data - byte_offset.

Retourne napi_ok si l'API a réussi.

Cette API retourne diverses propriétés d'un tableau typé.

N'importe lequel des paramètres de sortie peut être NULL si cette propriété n'est pas nécessaire.

_Avertissement _: Soyez prudent lors de l'utilisation de cette API car le buffer de données sous-jacent est géré par la VM.

napi_get_dataview_info

Ajouté dans : v8.3.0

Version 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: L'environnement dans lequel l'API est appelée.
• [in] dataview: napi_value représentant le DataView dont les propriétés doivent être interrogées.
• [out] byte_length: Nombre d'octets dans le DataView.
• [out] data: Le buffer de données sous-jacent au DataView. Si byte_length est 0, cela peut être NULL ou toute autre valeur de pointeur.
• [out] arraybuffer: ArrayBuffer sous-jacent au DataView.
• [out] byte_offset: Le décalage d'octet dans le buffer de données à partir duquel commencer la projection du DataView.

Retourne napi_ok si l'API a réussi.

N'importe lequel des paramètres de sortie peut être NULL si cette propriété n'est pas nécessaire.

Cette API retourne diverses propriétés d'un DataView.

napi_get_date_value

Ajouté dans : v11.11.0, v10.17.0

Version N-API : 5

napi_status napi_get_date_value(napi_env env,
                                napi_value value,
                                double* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: napi_value représentant une date JavaScript.
• [out] result: Valeur temporelle en tant que double représentée en millisecondes depuis minuit au début du 1er janvier 1970 UTC.

Cette API n'observe pas les secondes intercalaires ; elles sont ignorées, car ECMAScript s'aligne sur la spécification de l'heure POSIX.

Retourne napi_ok si l'API a réussi. Si une napi_value qui n'est pas une date est passée en paramètre, elle retourne napi_date_expected.

Cette API retourne le type primitif C double de la valeur temporelle pour la date JavaScript donnée.

napi_get_value_bool

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: napi_value représentant un booléen JavaScript.
• [out] result: Équivalent primitif booléen C du booléen JavaScript donné.

Retourne napi_ok si l'API a réussi. Si une napi_value qui n'est pas un booléen est passée en paramètre, elle retourne napi_boolean_expected.

Cette API retourne l'équivalent primitif booléen C du booléen JavaScript donné.

napi_get_value_double

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_value_double(napi_env env,
                                  napi_value value,
                                  double* result)

• [in] env : L'environnement dans lequel l'API est appelée.
• [in] value : napi_value représentant un nombre JavaScript.
• [out] result : équivalent primitif double C du nombre JavaScript donné.

Retourne napi_ok si l'API a réussi. Si une napi_value qui n'est pas un nombre est passée en paramètre, elle retourne napi_number_expected.

Cette API retourne l'équivalent primitif double C du nombre JavaScript donné.

napi_get_value_bigint_int64

Ajouté dans : v10.7.0

Version N-API : 6

napi_status napi_get_value_bigint_int64(napi_env env,
                                        napi_value value,
                                        int64_t* result,
                                        bool* lossless);

• [in] env : L'environnement dans lequel l'API est appelée.
• [in] value : napi_value représentant un BigInt JavaScript.
• [out] result : équivalent primitif C int64_t du BigInt JavaScript donné.
• [out] lossless : Indique si la valeur BigInt a été convertie sans perte.

Retourne napi_ok si l'API a réussi. Si un élément autre qu'un BigInt est passé en paramètre, elle retourne napi_bigint_expected.

Cette API retourne l'équivalent primitif C int64_t du BigInt JavaScript donné. Si nécessaire, elle tronquera la valeur, en définissant lossless sur false.

napi_get_value_bigint_uint64

Ajouté dans : v10.7.0

Version N-API : 6

napi_status napi_get_value_bigint_uint64(napi_env env,
                                        napi_value value,
                                        uint64_t* result,
                                        bool* lossless);

• [in] env : L'environnement dans lequel l'API est appelée.
• [in] value : napi_value représentant un BigInt JavaScript.
• [out] result : équivalent primitif C uint64_t du BigInt JavaScript donné.
• [out] lossless : Indique si la valeur BigInt a été convertie sans perte.

Retourne napi_ok si l'API a réussi. Si un élément autre qu'un BigInt est passé en paramètre, elle retourne napi_bigint_expected.

Cette API retourne l'équivalent primitif C uint64_t du BigInt JavaScript donné. Si nécessaire, elle tronquera la valeur, en définissant lossless sur false.

napi_get_value_bigint_words

Ajouté dans : v10.7.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] value: napi_value représentant un BigInt JavaScript.
• [out] sign_bit: Entier représentant si le BigInt JavaScript est positif ou négatif.
• [in/out] word_count: Doit être initialisé à la longueur du tableau words. Au retour, il sera mis à jour avec le nombre réel de mots nécessaires pour stocker ce BigInt.
• [out] words: Pointeur vers un tableau de mots 64 bits pré-alloué.

Retourne napi_ok si l'API a réussi.

Cette API convertit une seule valeur BigInt en un bit de signe, un tableau 64 bits little-endian, et le nombre d'éléments dans le tableau. sign_bit et words peuvent tous deux être définis sur NULL afin d'obtenir uniquement word_count.

napi_get_value_external

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_value_external(napi_env env,
                                    napi_value value,
                                    void** result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: napi_value représentant une valeur externe JavaScript.
• [out] result: Pointeur vers les données encapsulées par la valeur externe JavaScript.

Retourne napi_ok si l'API a réussi. Si une napi_value non externe est passée, elle retourne napi_invalid_arg.

Cette API récupère le pointeur de données externes qui a été précédemment passé à napi_create_external().

napi_get_value_int32

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_value_int32(napi_env env,
                                 napi_value value,
                                 int32_t* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: napi_value représentant un number JavaScript.
• [out] result: Primitive C int32 équivalente au number JavaScript donné.

Retourne napi_ok si l'API a réussi. Si une napi_value qui n'est pas un nombre est passée, retourne napi_number_expected.

Cette API retourne la primitive C int32 équivalente au number JavaScript donné.

Si le nombre dépasse la plage de l'entier 32 bits, le résultat est tronqué à l'équivalent des 32 bits inférieurs. Cela peut entraîner la conversion d'un grand nombre positif en un nombre négatif si la valeur est > 2³² - 1.

Les valeurs numériques non finies (NaN, +Infinity ou -Infinity) définissent le résultat sur zéro.

napi_get_value_int64

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_value_int64(napi_env env,
                                 napi_value value,
                                 int64_t* result)

• [in] env : L'environnement dans lequel l'API est appelée.
• [in] value : napi_value représentant un nombre JavaScript.
• [out] result : Primitive C int64 équivalente au nombre JavaScript donné.

Retourne napi_ok si l'API a réussi. Si une napi_value qui n'est pas un nombre est passée en paramètre, elle retourne napi_number_expected.

Cette API retourne la primitive C int64 équivalente au nombre JavaScript donné.

Les valeurs number en dehors de la plage de Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) perdront en précision.

Les valeurs numériques non finies (NaN, +Infinity ou -Infinity) définissent le résultat sur zéro.

napi_get_value_string_latin1

Ajouté dans : v8.0.0

Version 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 : L'environnement dans lequel l'API est appelée.
• [in] value : napi_value représentant une chaîne JavaScript.
• [in] buf : Buffer dans lequel écrire la chaîne codée ISO-8859-1. Si NULL est passé, la longueur de la chaîne en octets, sans le terminateur nul, est retournée dans result.
• [in] bufsize : Taille du buffer de destination. Lorsque cette valeur est insuffisante, la chaîne renvoyée est tronquée et terminée par un caractère nul.
• [out] result : Nombre d'octets copiés dans le buffer, sans le terminateur nul.

Retourne napi_ok si l'API a réussi. Si une napi_value qui n'est pas une string est passée en paramètre, elle retourne napi_string_expected.

Cette API retourne la chaîne codée ISO-8859-1 correspondant à la valeur passée en paramètre.

napi_get_value_string_utf8

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] value: napi_value représentant une chaîne JavaScript.
• [in] buf: Buffer dans lequel écrire la chaîne codée en UTF8. Si NULL est passé, la longueur de la chaîne en octets, sans le terminateur nul, est renvoyée dans result.
• [in] bufsize: Taille du buffer de destination. Si cette valeur est insuffisante, la chaîne renvoyée est tronquée et terminée par un caractère nul.
• [out] result: Nombre d'octets copiés dans le buffer, sans le terminateur nul.

Renvoie napi_ok si l'API a réussi. Si une napi_value qui n'est pas une string est passée, elle renvoie napi_string_expected.

Cette API renvoie la chaîne codée en UTF8 correspondant à la valeur passée.

napi_get_value_string_utf16

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] value: napi_value représentant une chaîne JavaScript.
• [in] buf: Buffer dans lequel écrire la chaîne codée en UTF16-LE. Si NULL est passé, la longueur de la chaîne en unités de code de 2 octets, sans le terminateur nul, est renvoyée.
• [in] bufsize: Taille du buffer de destination. Si cette valeur est insuffisante, la chaîne renvoyée est tronquée et terminée par un caractère nul.
• [out] result: Nombre d'unités de code de 2 octets copiées dans le buffer, sans le terminateur nul.

Renvoie napi_ok si l'API a réussi. Si une napi_value qui n'est pas une string est passée, elle renvoie napi_string_expected.

Cette API renvoie la chaîne codée en UTF16 correspondant à la valeur passée.

napi_get_value_uint32

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_value_uint32(napi_env env,
                                  napi_value value,
                                  uint32_t* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: napi_value représentant un nombre JavaScript.
• [out] result: Équivalent primitif C de la napi_value donnée sous forme de uint32_t.

Retourne napi_ok si l'API a réussi. Si une napi_value qui n'est pas un nombre est passée en paramètre, elle retourne napi_number_expected.

Cette API retourne l'équivalent primitif C de la napi_value donnée sous forme de uint32_t.

Fonctions pour obtenir les instances globales

napi_get_boolean

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] value: La valeur booléenne à récupérer.
• [out] result: napi_value représentant le singleton Boolean JavaScript à récupérer.

Retourne napi_ok si l'API a réussi.

Cette API est utilisée pour retourner l'objet singleton JavaScript utilisé pour représenter la valeur booléenne donnée.

napi_get_global

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_global(napi_env env, napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [out] result: napi_value représentant l'objet global JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API retourne l'objet global.

napi_get_null

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_null(napi_env env, napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [out] result: napi_value représentant l'objet null JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API retourne l'objet null.

napi_get_undefined

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_undefined(napi_env env, napi_value* result)

• [in] env: L'environnement dans lequel l'API est appelée.
• [out] result: napi_value représentant la valeur Undefined JavaScript.

Retourne napi_ok si l'API a réussi.

Cette API retourne l'objet Undefined.

Travailler avec les valeurs JavaScript et les opérations abstraites

Node-API expose un ensemble d'API pour effectuer certaines opérations abstraites sur les valeurs JavaScript. Certaines de ces opérations sont documentées à la Section 7 de la spécification du langage ECMAScript.

Ces API permettent de faire l'une des opérations suivantes :

napi_coerce_to_bool

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_coerce_to_bool(napi_env env,
                                napi_value value,
                                napi_value* result)

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] value: La valeur JavaScript à convertir.
• [out] result: napi_value représentant le Boolean JavaScript converti.

Retourne napi_ok si l'API a réussi.

Cette API implémente l'opération abstraite ToBoolean() telle que définie à la Section 7.1.2 de la spécification du langage ECMAScript.

napi_coerce_to_number

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_coerce_to_number(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] value: La valeur JavaScript à convertir.
• [out] result: napi_value représentant le number JavaScript converti.

Retourne napi_ok si l'API a réussi.

Cette API implémente l'opération abstraite ToNumber() telle que définie à la Section 7.1.3 de la spécification du langage ECMAScript. Cette fonction peut exécuter du code JS si la valeur passée est un objet.

napi_coerce_to_object

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_coerce_to_object(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] value: La valeur JavaScript à convertir.
• [out] result: napi_value représentant l' Object JavaScript converti.

Retourne napi_ok si l'API a réussi.

Cette API implémente l'opération abstraite ToObject() telle que définie à la Section 7.1.13 de la spécification du langage ECMAScript.

napi_coerce_to_string

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_coerce_to_string(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env : L’environnement sous lequel l’API est invoquée.
• [in] value : La valeur JavaScript à forcer.
• [out] result : napi_value représentant la chaîne JavaScript forcée.

Retourne napi_ok si l’API a réussi.

Cette API implémente l’opération abstraite ToString() telle que définie dans la section 7.1.13 de la spécification du langage ECMAScript. Cette fonction peut exécuter du code JS si la valeur passée est un objet.

napi_typeof

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)

• [in] env : L’environnement sous lequel l’API est invoquée.
• [in] value : La valeur JavaScript dont le type doit être interrogé.
• [out] result : Le type de la valeur JavaScript.

Retourne napi_ok si l’API a réussi.

• napi_invalid_arg si le type de value n’est pas un type ECMAScript connu et que value n’est pas une valeur externe.

Cette API représente un comportement similaire à l’invocation de l’opérateur typeof sur l’objet tel que défini dans la section 12.5.5 de la spécification du langage ECMAScript. Cependant, il existe quelques différences :

Si value a un type invalide, une erreur est retournée.

napi_instanceof

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_instanceof(napi_env env,
                            napi_value object,
                            napi_value constructor,
                            bool* result)

• [in] env : L’environnement sous lequel l’API est invoquée.
• [in] object : La valeur JavaScript à vérifier.
• [in] constructor : L’objet fonction JavaScript de la fonction constructeur à vérifier.
• [out] result : Booléen qui est défini sur true si object instanceof constructor est true.

Retourne napi_ok si l’API a réussi.

Cette API représente l’invocation de l’opérateur instanceof sur l’objet tel que défini dans la section 12.10.4 de la spécification du langage ECMAScript.

napi_is_array

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_is_array(napi_env env, napi_value value, bool* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La valeur JavaScript à vérifier.
• [out] result: Si l'objet donné est un tableau.

Retourne napi_ok si l'API a réussi.

Cette API représente l'invocation de l'opération IsArray sur l'objet tel que défini dans la Section 7.2.2 de la spécification du langage ECMAScript.

napi_is_arraybuffer

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La valeur JavaScript à vérifier.
• [out] result: Si l'objet donné est un ArrayBuffer.

Retourne napi_ok si l'API a réussi.

Cette API vérifie si l'objet passé est un ArrayBuffer.

napi_is_buffer

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La valeur JavaScript à vérifier.
• [out] result: Si la napi_value donnée représente un objet node::Buffer ou Uint8Array.

Retourne napi_ok si l'API a réussi.

Cette API vérifie si l'objet passé est un buffer ou un Uint8Array. napi_is_typedarray devrait être préféré si l'appelant a besoin de vérifier si la valeur est un Uint8Array.

napi_is_date

Ajouté dans : v11.11.0, v10.17.0

Version N-API : 5

napi_status napi_is_date(napi_env env, napi_value value, bool* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La valeur JavaScript à vérifier.
• [out] result: Si la napi_value donnée représente un objet JavaScript Date.

Retourne napi_ok si l'API a réussi.

Cette API vérifie si l'objet passé est une date.

napi_is_error

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_is_error(napi_env env, napi_value value, bool* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La valeur JavaScript à vérifier.
• [out] result: Indique si la napi_value donnée représente un objet Error.

Retourne napi_ok si l'API a réussi.

Cette API vérifie si l'objet passé en paramètre est une erreur (Error).

napi_is_typedarray

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La valeur JavaScript à vérifier.
• [out] result: Indique si la napi_value donnée représente un TypedArray.

Retourne napi_ok si l'API a réussi.

Cette API vérifie si l'objet passé en paramètre est un tableau typé.

napi_is_dataview

Ajouté dans : v8.3.0

Version N-API : 1

napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La valeur JavaScript à vérifier.
• [out] result: Indique si la napi_value donnée représente un DataView.

Retourne napi_ok si l'API a réussi.

Cette API vérifie si l'objet passé en paramètre est un DataView.

napi_strict_equals

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_strict_equals(napi_env env,
                               napi_value lhs,
                               napi_value rhs,
                               bool* result)

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] lhs: La valeur JavaScript à vérifier.
• [in] rhs: La valeur JavaScript contre laquelle comparer.
• [out] result: Indique si les deux objets napi_value sont égaux.

Retourne napi_ok si l'API a réussi.

Cette API représente l'invocation de l'algorithme d'égalité stricte tel que défini dans la section 7.2.14 de la spécification du langage ECMAScript.

napi_detach_arraybuffer

Ajouté dans : v13.0.0, v12.16.0, v10.22.0

Version N-API : 7

napi_status napi_detach_arraybuffer(napi_env env,
                                    napi_value arraybuffer)

• [in] env : L’environnement sous lequel l’API est invoquée.
• [in] arraybuffer : Le ArrayBuffer JavaScript à détacher.

Retourne napi_ok si l’API a réussi. Si un ArrayBuffer non détachable est passé en paramètre, il retourne napi_detachable_arraybuffer_expected.

En général, un ArrayBuffer est non détachable s’il a déjà été détaché. Le moteur peut imposer des conditions supplémentaires sur la possibilité de détacher un ArrayBuffer. Par exemple, V8 exige que le ArrayBuffer soit externe, c’est-à-dire créé avec napi_create_external_arraybuffer.

Cette API représente l’invocation de l’opération de détachement de ArrayBuffer telle que définie dans la section 24.1.1.3 de la spécification du langage ECMAScript.

napi_is_detached_arraybuffer

Ajouté dans : v13.3.0, v12.16.0, v10.22.0

Version N-API : 7

napi_status napi_is_detached_arraybuffer(napi_env env,
                                         napi_value arraybuffer,
                                         bool* result)

• [in] env : L’environnement sous lequel l’API est invoquée.
• [in] arraybuffer : Le ArrayBuffer JavaScript à vérifier.
• [out] result : Indique si le arraybuffer est détaché.

Retourne napi_ok si l’API a réussi.

Le ArrayBuffer est considéré comme détaché si ses données internes sont null.

Cette API représente l’invocation de l’opération IsDetachedBuffer de ArrayBuffer telle que définie dans la section 24.1.1.2 de la spécification du langage ECMAScript.

Utilisation des propriétés JavaScript

Node-API expose un ensemble d’API pour obtenir et définir des propriétés sur les objets JavaScript. Certains de ces types sont documentés à la section 7 de la spécification du langage ECMAScript.

Les propriétés en JavaScript sont représentées comme un tuple d’une clé et d’une valeur. Fondamentalement, toutes les clés de propriété dans Node-API peuvent être représentées sous l’une des formes suivantes :

• Nommée : une simple chaîne codée en UTF8.
• Indexée par entier : une valeur d’index représentée par uint32_t.
• Valeur JavaScript : celles-ci sont représentées dans Node-API par napi_value. Cela peut être une napi_value représentant une string, un number ou un symbol.

Les valeurs Node-API sont représentées par le type napi_value. Tout appel Node-API qui nécessite une valeur JavaScript prend une napi_value. Cependant, il incombe à l’appelant de s’assurer que la napi_value en question est du type JavaScript attendu par l’API.

Les API documentées dans cette section fournissent une interface simple pour obtenir et définir des propriétés sur des objets JavaScript arbitraires représentés par napi_value.

Par exemple, considérez l’extrait de code JavaScript suivant :

const obj = {}
obj.myProp = 123

L’équivalent peut être fait en utilisant les valeurs Node-API avec l’extrait suivant :

napi_status status = napi_generic_failure;

// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// Créer une napi_value pour 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;

Les propriétés indexées peuvent être définies de manière similaire. Considérez l’extrait de code JavaScript suivant :

const arr = []
arr[123] = 'hello'

L’équivalent peut être fait en utilisant les valeurs Node-API avec l’extrait suivant :

napi_status status = napi_generic_failure;

// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// Créer une napi_value pour '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;

Les propriétés peuvent être récupérées à l’aide des API décrites dans cette section. Considérez l’extrait de code JavaScript suivant :

const arr = []
const value = arr[123]

Voici l’équivalent approximatif du pendant 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;

Enfin, plusieurs propriétés peuvent également être définies sur un objet pour des raisons de performances. Considérez le JavaScript suivant :

const obj = {}
Object.defineProperties(obj, {
  foo: { value: 123, writable: true, configurable: true, enumerable: true },
  bar: { value: 456, writable: true, configurable: true, enumerable: true },
})

Voici l’équivalent approximatif du pendant 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;

// Créer des napi_values pour 123 et 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;

// Définir les propriétés
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;

Structures

napi_property_attributes

[Historique]

Version	Modifications
v14.12.0	Ajout de napi_default_method et napi_default_property.

typedef enum {
  napi_default = 0,
  napi_writable = 1 << 0,
  napi_enumerable = 1 << 1,
  napi_configurable = 1 << 2,

  // Utilisé avec napi_define_class pour distinguer les propriétés statiques
  // des propriétés d'instance. Ignoré par napi_define_properties.
  napi_static = 1 << 10,

  // Valeur par défaut pour les méthodes de classe.
  napi_default_method = napi_writable | napi_configurable,

  // Valeur par défaut pour les propriétés d'objet, comme dans JS obj[prop].
  napi_default_jsproperty = napi_writable |
                          napi_enumerable |
                          napi_configurable,
} napi_property_attributes;

napi_property_attributes sont des indicateurs utilisés pour contrôler le comportement des propriétés définies sur un objet JavaScript. Excepté napi_static, ils correspondent aux attributs listés dans la Section 6.1.7.1 de la spécification du langage ECMAScript. Ils peuvent être une combinaison des indicateurs suivants :

• napi_default: Aucun attribut explicite n'est défini sur la propriété. Par défaut, une propriété est en lecture seule, non énumérable et non configurable.
• napi_writable: La propriété est modifiable.
• napi_enumerable: La propriété est énumérable.
• napi_configurable: La propriété est configurable comme défini dans la Section 6.1.7.1 de la spécification du langage ECMAScript.
• napi_static: La propriété sera définie comme une propriété statique sur une classe par opposition à une propriété d'instance, qui est la valeur par défaut. Ceci est utilisé uniquement par napi_define_class. Il est ignoré par napi_define_properties.
• napi_default_method: Comme une méthode dans une classe JS, la propriété est configurable et modifiable, mais non énumérable.
• napi_default_jsproperty: Comme une propriété définie via une affectation en JavaScript, la propriété est modifiable, énumérable et configurable.

napi_property_descriptor

typedef struct {
  // `utf8name` ou `name` doit être 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 : Chaîne facultative décrivant la clé de la propriété, encodée en UTF8. utf8name ou name doit être fourni pour la propriété.
• name : napi_value facultatif qui pointe vers une chaîne JavaScript ou un symbole à utiliser comme clé pour la propriété. utf8name ou name doit être fourni pour la propriété.
• value : La valeur récupérée par un accès en lecture de la propriété si la propriété est une propriété de données. Si cette valeur est passée, définissez getter, setter, method et data sur NULL (car ces membres ne seront pas utilisés).
• getter : Fonction à appeler lors d'un accès en lecture de la propriété. Si cette valeur est passée, définissez value et method sur NULL (car ces membres ne seront pas utilisés). La fonction donnée est appelée implicitement par le runtime lorsque la propriété est accédée depuis le code JavaScript (ou si une lecture de la propriété est effectuée à l'aide d'un appel Node-API). napi_callback fournit plus de détails.
• setter : Fonction à appeler lors d'un accès en écriture de la propriété. Si cette valeur est passée, définissez value et method sur NULL (car ces membres ne seront pas utilisés). La fonction donnée est appelée implicitement par le runtime lorsque la propriété est définie depuis le code JavaScript (ou si une écriture sur la propriété est effectuée à l'aide d'un appel Node-API). napi_callback fournit plus de détails.
• method : Définissez ceci pour que la propriété value de l'objet descripteur de propriété soit une fonction JavaScript représentée par method. Si cette valeur est passée, définissez value, getter et setter sur NULL (car ces membres ne seront pas utilisés). napi_callback fournit plus de détails.
• attributes : Les attributs associés à la propriété particulière. Voir napi_property_attributes.
• data : Les données de rappel passées à method, getter et setter si cette fonction est invoquée.

Fonctions

napi_get_property_names

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_property_names(napi_env env,
                                    napi_value object,
                                    napi_value* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet duquel récupérer les propriétés.
• [out] result: Une napi_value représentant un tableau de valeurs JavaScript qui représentent les noms de propriétés de l'objet. L'API peut être utilisée pour itérer sur result en utilisant napi_get_array_length et napi_get_element.

Retourne napi_ok si l'API a réussi.

Cette API retourne les noms des propriétés énumérables de object sous forme de tableau de chaînes de caractères. Les propriétés de object dont la clé est un symbole ne seront pas incluses.

napi_get_all_property_names

Ajouté dans : v13.7.0, v12.17.0, v10.20.0

Version 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: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet duquel récupérer les propriétés.
• [in] key_mode: Indique s'il faut également récupérer les propriétés du prototype.
• [in] key_filter: Quelles propriétés récupérer (énumérables/lisibles/inscriptibles).
• [in] key_conversion: Indique s'il faut convertir les clés de propriétés numérotées en chaînes de caractères.
• [out] result: Une napi_value représentant un tableau de valeurs JavaScript qui représentent les noms de propriétés de l'objet. napi_get_array_length et napi_get_element peuvent être utilisés pour itérer sur result.

Retourne napi_ok si l'API a réussi.

Cette API retourne un tableau contenant les noms des propriétés disponibles de cet objet.

napi_set_property

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_set_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value value);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet sur lequel définir la propriété.
• [in] key: Le nom de la propriété à définir.
• [in] value: La valeur de la propriété.

Retourne napi_ok si l'API a réussi.

Cette API définit une propriété sur l'objet passé en paramètre.

napi_get_property

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet duquel récupérer la propriété.
• [in] key: Le nom de la propriété à récupérer.
• [out] result: La valeur de la propriété.

Retourne napi_ok si l'API a réussi.

Cette API récupère la propriété demandée depuis l'objet passé en paramètre.

napi_has_property

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_has_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              bool* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet à interroger.
• [in] key: Le nom de la propriété dont l'existence doit être vérifiée.
• [out] result: Indique si la propriété existe sur l'objet ou non.

Retourne napi_ok si l'API a réussi.

Cette API vérifie si l'objet passé en paramètre possède la propriété nommée.

napi_delete_property

Ajouté dans : v8.2.0

Version N-API : 1

napi_status napi_delete_property(napi_env env,
                                 napi_value object,
                                 napi_value key,
                                 bool* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet à interroger.
• [in] key: Le nom de la propriété à supprimer.
• [out] result: Indique si la suppression de la propriété a réussi ou non. result peut être optionnellement ignoré en passant NULL.

Retourne napi_ok si l'API a réussi.

Cette API tente de supprimer la propriété propre key de object.

napi_has_own_property

Ajouté dans : v8.2.0

Version N-API : 1

napi_status napi_has_own_property(napi_env env,
                                  napi_value object,
                                  napi_value key,
                                  bool* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet à interroger.
• [in] key: Le nom de la propriété propre dont l'existence doit être vérifiée.
• [out] result: Indique si la propriété propre existe sur l'objet ou non.

Retourne napi_ok si l'API a réussi.

Cette API vérifie si l'objet passé en paramètre possède la propriété propre nommée. key doit être une chaîne de caractères ou un symbole, sinon une erreur sera levée. Node-API n'effectuera aucune conversion entre les types de données.

napi_set_named_property

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet sur lequel définir la propriété.
• [in] utf8Name: Le nom de la propriété à définir.
• [in] value: La valeur de la propriété.

Retourne napi_ok si l'API a réussi.

Cette méthode équivaut à appeler napi_set_property avec une napi_value créée à partir de la chaîne de caractères passée en paramètre utf8Name.

napi_get_named_property

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet duquel récupérer la propriété.
• [in] utf8Name: Le nom de la propriété à récupérer.
• [out] result: La valeur de la propriété.

Retourne napi_ok si l'API a réussi.

Cette méthode équivaut à appeler napi_get_property avec une napi_value créée à partir de la chaîne de caractères passée en paramètre utf8Name.

napi_has_named_property

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_has_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    bool* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet à interroger.
• [in] utf8Name: Le nom de la propriété dont l'existence doit être vérifiée.
• [out] result: Indique si la propriété existe sur l'objet ou non.

Retourne napi_ok si l'API a réussi.

Cette méthode est équivalente à l'appel de napi_has_property avec une napi_value créée à partir de la chaîne passée en utf8Name.

napi_set_element

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_set_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value value);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet duquel définir les propriétés.
• [in] index: L'index de la propriété à définir.
• [in] value: La valeur de la propriété.

Retourne napi_ok si l'API a réussi.

Cette API définit un élément sur l'objet passé en paramètre.

napi_get_element

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet duquel récupérer la propriété.
• [in] index: L'index de la propriété à obtenir.
• [out] result: La valeur de la propriété.

Retourne napi_ok si l'API a réussi.

Cette API obtient l'élément à l'index demandé.

napi_has_element

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_has_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             bool* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet à interroger.
• [in] index: L'index de la propriété dont l'existence doit être vérifiée.
• [out] result: Indique si la propriété existe sur l'objet ou non.

Retourne napi_ok si l'API a réussi.

Cette API retourne si l'objet passé en paramètre possède un élément à l'index demandé.

napi_delete_element

Ajouté dans : v8.2.0

Version N-API : 1

napi_status napi_delete_element(napi_env env,
                                napi_value object,
                                uint32_t index,
                                bool* result);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet à interroger.
• [in] index: L'index de la propriété à supprimer.
• [out] result: Indique si la suppression de l'élément a réussi ou non. result peut être ignoré en passant NULL.

Retourne napi_ok si l'API a réussi.

Cette API tente de supprimer l'index spécifié de object.

napi_define_properties

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet duquel récupérer les propriétés.
• [in] property_count: Le nombre d'éléments dans le tableau properties.
• [in] properties: Le tableau des descripteurs de propriété.

Retourne napi_ok si l'API a réussi.

Cette méthode permet la définition efficace de plusieurs propriétés sur un objet donné. Les propriétés sont définies à l'aide de descripteurs de propriété (voir napi_property_descriptor). Étant donné un tableau de ces descripteurs de propriété, cette API définira les propriétés sur l'objet une par une, comme défini par DefineOwnProperty() (décrit dans la Section 9.1.6 de la spécification ECMA-262).

napi_object_freeze

Ajouté dans : v14.14.0, v12.20.0

Version N-API : 8

napi_status napi_object_freeze(napi_env env,
                               napi_value object);

• [in] env: L'environnement dans lequel l'appel Node-API est invoqué.
• [in] object: L'objet à figer.

Retourne napi_ok si l'API a réussi.

Cette méthode fige un objet donné. Cela empêche l'ajout de nouvelles propriétés, la suppression de propriétés existantes, la modification de l'énumérabilité, de la configurabilité ou de l'écriture des propriétés existantes, et empêche la modification des valeurs des propriétés existantes. Cela empêche également la modification du prototype de l'objet. Ceci est décrit dans la Section 19.1.2.6 de la spécification ECMA-262.

napi_object_seal

Ajouté dans : v14.14.0, v12.20.0

Version N-API : 8

napi_status napi_object_seal(napi_env env,
                             napi_value object);

• [in] env: L'environnement dans lequel l'appel Node-API est effectué.
• [in] object: L'objet à sceller.

Retourne napi_ok si l'API a réussi.

Cette méthode scelle un objet donné. Cela empêche l'ajout de nouvelles propriétés, et marque toutes les propriétés existantes comme non configurables. Ceci est décrit dans la Section 19.1.2.20 de la spécification ECMA-262.

Utilisation des fonctions JavaScript

Node-API fournit un ensemble d'API permettant au code JavaScript d'appeler du code natif. Les API Node-API qui prennent en charge les appels au code natif utilisent une fonction de rappel représentée par le type napi_callback. Lorsque la machine virtuelle JavaScript effectue un appel au code natif, la fonction napi_callback fournie est invoquée. Les API documentées dans cette section permettent à la fonction de rappel de faire ce qui suit :

• Obtenir des informations sur le contexte dans lequel le rappel a été invoqué.
• Obtenir les arguments passés au rappel.
• Retourner une valeur napi_value depuis le rappel.

De plus, Node-API fournit un ensemble de fonctions permettant d'appeler des fonctions JavaScript depuis du code natif. On peut appeler une fonction comme un appel de fonction JavaScript régulier, ou comme une fonction constructeur.

Toute donnée non NULL passée à cette API via le champ data des éléments napi_property_descriptor peut être associée à object et libérée lorsque object est ramassé par le garbage collector en passant object et les données à napi_add_finalizer.

napi_call_function

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] recv: La valeur this passée à la fonction appelée.
• [in] func: napi_value représentant la fonction JavaScript à invoquer.
• [in] argc: Le nombre d'éléments dans le tableau argv.
• [in] argv: Tableau de napi_values représentant les valeurs JavaScript passées en arguments à la fonction.
• [out] result: napi_value représentant l'objet JavaScript retourné.

Retourne napi_ok si l'API a réussi.

Cette méthode permet d'appeler un objet fonction JavaScript depuis un add-on natif. C'est le mécanisme principal pour effectuer un appel depuis le code natif de l'add-on vers JavaScript. Pour le cas particulier d'un appel à JavaScript après une opération asynchrone, voir napi_make_callback.

Un exemple d'utilisation pourrait ressembler à ceci. Considérons l'extrait JavaScript suivant :

function AddTwo(num) {
  return num + 2
}
global.AddTwo = AddTwo

Ensuite, la fonction ci-dessus peut être invoquée depuis un add-on natif en utilisant le code suivant :

// Obtenir la fonction nommée "AddTwo" sur l'objet 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;

// Convertir le résultat en un type natif
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;

napi_create_function

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] utf8Name: Nom facultatif de la fonction encodé en UTF8. Ceci est visible en JavaScript comme la propriété name du nouvel objet fonction.
• [in] length: La longueur de utf8name en octets, ou NAPI_AUTO_LENGTH si elle est terminée par un null.
• [in] cb: La fonction native qui doit être appelée lorsque cet objet fonction est invoqué. napi_callback fournit plus de détails.
• [in] data: Contexte de données fourni par l'utilisateur. Il sera renvoyé à la fonction lorsqu'elle sera invoquée ultérieurement.
• [out] result: napi_value représentant l'objet fonction JavaScript pour la fonction nouvellement créée.

Retourne napi_ok si l'API a réussi.

Cette API permet à un auteur d'extension de créer un objet fonction dans le code natif. C'est le mécanisme principal pour permettre d'appeler le code natif de l'extension depuis JavaScript.

La fonction nouvellement créée n'est pas automatiquement visible depuis le script après cet appel. Au lieu de cela, une propriété doit être explicitement définie sur tout objet visible par JavaScript, afin que la fonction soit accessible depuis le script.

Afin d'exposer une fonction dans le cadre des exportations du module de l'extension, définissez la fonction nouvellement créée sur l'objet des exportations. Un exemple de module pourrait ressembler à ceci :

napi_value SayHello(napi_env env, napi_callback_info info) {
  printf("Hello\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)

Étant donné le code ci-dessus, l'extension peut être utilisée à partir de JavaScript comme suit :

const myaddon = require('./addon')
myaddon.sayHello()

La chaîne passée à require() est le nom de la cible dans binding.gyp responsable de la création du fichier .node.

Toute donnée non NULL passée à cette API via le paramètre data peut être associée à la fonction JavaScript résultante (qui est renvoyée dans le paramètre result) et libérée dès que la fonction est collectée par le garbage collector en passant à la fois la fonction JavaScript et les données à napi_add_finalizer.

Les fonctions JavaScript sont décrites dans la section 19.2 de la spécification du langage ECMAScript.

napi_get_cb_info

Ajouté dans : v8.0.0

Version 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: L'environnement sous lequel l'API est invoquée.
• [in] cbinfo: Les informations de rappel passées à la fonction de rappel.
• [in-out] argc: Spécifie la longueur du tableau argv fourni et reçoit le nombre réel d'arguments. argc peut être ignoré en passant NULL.
• [out] argv: Tableau C de napi_value dans lequel les arguments seront copiés. S'il y a plus d'arguments que le nombre fourni, seul le nombre d'arguments demandé est copié. S'il y a moins d'arguments fournis que réclamé, le reste de argv est rempli avec des valeurs napi_value qui représentent undefined. argv peut être ignoré en passant NULL.
• [out] thisArg: Reçoit l'argument JavaScript this pour l'appel. thisArg peut être ignoré en passant NULL.
• [out] data: Reçoit le pointeur de données pour le rappel. data peut être ignoré en passant NULL.

Retourne napi_ok si l'API a réussi.

Cette méthode est utilisée dans une fonction de rappel pour récupérer des détails sur l'appel, tels que les arguments et le pointeur this, à partir d'informations de rappel données.

napi_get_new_target

Ajouté dans : v8.6.0

Version N-API : 1

napi_status napi_get_new_target(napi_env env,
                                napi_callback_info cbinfo,
                                napi_value* result)

• [in] env: L'environnement sous lequel l'API est invoquée.
• [in] cbinfo: Les informations de rappel passées à la fonction de rappel.
• [out] result: Le new.target de l'appel du constructeur.

Retourne napi_ok si l'API a réussi.

Cette API retourne le new.target de l'appel du constructeur. Si le rappel actuel n'est pas un appel de constructeur, le résultat est NULL.

napi_new_instance

Ajouté dans : v8.0.0

Version 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: L'environnement sous lequel l'API est invoquée.
• [in] cons: napi_value représentant la fonction JavaScript à invoquer comme constructeur.
• [in] argc: Le nombre d'éléments dans le tableau argv.
• [in] argv: Tableau de valeurs JavaScript en tant que napi_value représentant les arguments du constructeur. Si argc est nul, ce paramètre peut être omis en passant NULL.
• [out] result: napi_value représentant l'objet JavaScript retourné, qui dans ce cas est l'objet construit.

Cette méthode est utilisée pour instancier une nouvelle valeur JavaScript en utilisant une napi_value donnée qui représente le constructeur de l'objet. Par exemple, considérons l'extrait suivant :

function MyObject(param) {
  this.param = param
}

const arg = 'hello'
const value = new MyObject(arg)

Ce qui suit peut être approximé dans Node-API en utilisant l'extrait suivant :

// Obtenir la fonction constructeur 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);

Retourne napi_ok si l'API a réussi.

Encapsulation d'objet

Node-API offre un moyen d'"encapsuler" les classes et les instances C++ afin que le constructeur et les méthodes de la classe puissent être appelés depuis JavaScript.

Pour les objets encapsulés, il peut être difficile de distinguer entre une fonction appelée sur un prototype de classe et une fonction appelée sur une instance d'une classe. Un motif courant utilisé pour résoudre ce problème consiste à enregistrer une référence persistante au constructeur de la classe pour des vérifications instanceof ultérieures.

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 {
  // sinon...
}

La référence doit être libérée lorsqu'elle n'est plus nécessaire.

Il y a des occasions où napi_instanceof() est insuffisant pour garantir qu'un objet JavaScript est un wrapper pour un certain type natif. C'est le cas notamment lorsque les objets JavaScript encapsulés sont renvoyés à l'addon via des méthodes statiques plutôt que comme valeur this des méthodes de prototype. Dans de tels cas, il y a une chance qu'ils puissent être déballés incorrectement.

const myAddon = require('./build/Release/my_addon.node')

// `openDatabase()` renvoie un objet JavaScript qui encapsule un handle de base de données natif.
// handle.
const dbHandle = myAddon.openDatabase()

// `query()` renvoie un objet JavaScript qui encapsule un handle de requête natif.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')

// Il y a une erreur accidentelle dans la ligne ci-dessous. Le premier paramètre de
// `myAddon.queryHasRecords()` doit être le handle de la base de données (`dbHandle`), pas
// le handle de la requête (`query`), donc la condition correcte pour la boucle while
// devrait être
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
  // récupérer les enregistrements
}

Dans l'exemple ci-dessus, myAddon.queryHasRecords() est une méthode qui accepte deux arguments. Le premier est un handle de base de données et le second est un handle de requête. En interne, il déballe le premier argument et effectue un cast du pointeur résultant vers un handle de base de données natif. Il déballe ensuite le deuxième argument et effectue un cast du pointeur résultant vers un handle de requête. Si les arguments sont passés dans le mauvais ordre, les casts fonctionneront, cependant, il y a de fortes chances que l'opération de base de données sous-jacente échoue, ou même provoque un accès mémoire invalide.

Pour s'assurer que le pointeur récupéré à partir du premier argument est bien un pointeur vers un handle de base de données et, de même, que le pointeur récupéré à partir du deuxième argument est bien un pointeur vers un handle de requête, l'implémentation de queryHasRecords() doit effectuer une validation de type. La conservation du constructeur de classe JavaScript à partir duquel le handle de base de données a été instancié et du constructeur à partir duquel le handle de requête a été instancié dans les napi_ref peut aider, car napi_instanceof() peut alors être utilisé pour s'assurer que les instances passées dans queryHashRecords() sont bien du type correct.

Malheureusement, napi_instanceof() ne protège pas contre la manipulation du prototype. Par exemple, le prototype de l'instance du handle de base de données peut être défini sur le prototype du constructeur pour les instances du handle de requête. Dans ce cas, l'instance du handle de base de données peut apparaître comme une instance du handle de requête, et elle passera le test napi_instanceof() pour une instance du handle de requête, tout en contenant toujours un pointeur vers un handle de base de données.

À cette fin, Node-API fournit des capacités d'étiquetage de type.

Une étiquette de type est un entier de 128 bits unique à l'addon. Node-API fournit la structure napi_type_tag pour stocker une étiquette de type. Lorsqu'une telle valeur est passée avec un objet JavaScript ou externe stocké dans une napi_value à napi_type_tag_object(), l'objet JavaScript sera "marqué" avec l'étiquette de type. La "marque" est invisible du côté JavaScript. Lorsqu'un objet JavaScript arrive dans une liaison native, napi_check_object_type_tag() peut être utilisé avec l'étiquette de type originale pour déterminer si l'objet JavaScript a été précédemment "marqué" avec l'étiquette de type. Cela crée une capacité de vérification de type d'une fidélité supérieure à celle que napi_instanceof() peut fournir, car un tel étiquetage de type survit à la manipulation du prototype et au déchargement/rechargement de l'addon.

En poursuivant l'exemple ci-dessus, l'implémentation d'addon squelette suivante illustre l'utilisation de napi_type_tag_object() et napi_check_object_type_tag().

// Cette valeur est l'étiquette de type pour un handle de base de données. La commande
//
//   uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// peut être utilisée pour obtenir les deux valeurs avec lesquelles initialiser la structure.
static const napi_type_tag DatabaseHandleTypeTag = {
  0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};

// Cette valeur est l'étiquette de type pour un handle de requête.
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;

  // Effectuer l'action sous-jacente qui aboutit à un handle de base de données.
  DatabaseHandle* dbHandle = open_database();

  // Créer un nouvel objet JS vide.
  status = napi_create_object(env, &result);
  if (status != napi_ok) return NULL;

  // Étiqueter l'objet pour indiquer qu'il contient un pointeur vers un `DatabaseHandle`.
  status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
  if (status != napi_ok) return NULL;

  // Stocker le pointeur vers la structure `DatabaseHandle` à l'intérieur de l'objet JS.
  status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
  if (status != napi_ok) return NULL;

  return result;
}

// Plus tard, lorsque nous recevons un objet JavaScript prétendant être un handle de base de données
// nous pouvons utiliser `napi_check_object_type_tag()` pour nous assurer qu'il s'agit bien d'un tel
// handle.

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;

  // Vérifier que l'objet passé comme premier paramètre possède l'étiquette précédemment
  // appliquée.
  status = napi_check_object_type_tag(env,
                                      argv[0],
                                      &DatabaseHandleTypeTag,
                                      &is_db_handle);
  if (status != napi_ok) return NULL;

  // Lever une `TypeError` si ce n'est pas le cas.
  if (!is_db_handle) {
    // Lever une TypeError.
    return NULL;
  }
}

napi_define_class

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] utf8name: Nom de la fonction constructrice JavaScript. Pour plus de clarté, il est recommandé d'utiliser le nom de la classe C++ lors de l'encapsulation d'une classe C++.
• [in] length: Longueur de utf8name en octets, ou NAPI_AUTO_LENGTH si elle est terminée par un caractère null.
• [in] constructor: Fonction de rappel qui gère la construction des instances de la classe. Lors de l'encapsulation d'une classe C++, cette méthode doit être un membre statique avec la signature napi_callback. Un constructeur de classe C++ ne peut pas être utilisé. napi_callback fournit plus de détails.
• [in] data: Données facultatives à transmettre à la fonction de rappel du constructeur en tant que propriété data des informations de rappel.
• [in] property_count: Nombre d'éléments dans l'argument du tableau properties.
• [in] properties: Tableau de descripteurs de propriétés décrivant les propriétés de données statiques et d'instance, les accesseurs et les méthodes de la classe. Voir napi_property_descriptor.
• [out] result: Une napi_value représentant la fonction constructrice de la classe.

Retourne napi_ok si l'API a réussi.

Définit une classe JavaScript, incluant :

• Une fonction constructrice JavaScript qui porte le nom de la classe. Lors de l'encapsulation d'une classe C++ correspondante, la fonction de rappel passée via constructor peut être utilisée pour instancier une nouvelle instance de classe C++, qui peut ensuite être placée à l'intérieur de l'instance d'objet JavaScript en cours de construction à l'aide de napi_wrap.
• Des propriétés sur la fonction constructrice dont l'implémentation peut appeler les propriétés de données, les accesseurs et les méthodes statiques correspondantes de la classe C++ (définies par les descripteurs de propriétés avec l'attribut napi_static).
• Des propriétés sur l'objet prototype de la fonction constructrice. Lors de l'encapsulation d'une classe C++, les propriétés de données, les accesseurs et les méthodes non statiques de la classe C++ peuvent être appelés à partir des fonctions statiques données dans les descripteurs de propriétés sans l'attribut napi_static après la récupération de l'instance de classe C++ placée à l'intérieur de l'instance d'objet JavaScript à l'aide de napi_unwrap.

Lors de l'encapsulation d'une classe C++, la fonction de rappel du constructeur C++ passée via constructor doit être une méthode statique de la classe qui appelle le constructeur de classe réel, puis encapsule la nouvelle instance C++ dans un objet JavaScript, et retourne l'objet encapsulé. Voir napi_wrap pour plus de détails.

La fonction constructrice JavaScript retournée par napi_define_class est souvent sauvegardée et utilisée plus tard pour construire de nouvelles instances de la classe à partir du code natif, et/ou pour vérifier si les valeurs fournies sont des instances de la classe. Dans ce cas, pour empêcher la valeur de la fonction d'être collectée par le garbage collector, une référence persistante forte peut être créée à l'aide de napi_create_reference, garantissant que le nombre de références est maintenu >= 1.

Toute donnée non NULL qui est passée à cette API via le paramètre data ou via le champ data des éléments du tableau napi_property_descriptor peut être associée au constructeur JavaScript résultant (qui est retourné dans le paramètre result) et libérée chaque fois que la classe est collectée par le garbage collector en passant à la fois la fonction JavaScript et les données à napi_add_finalizer.

napi_wrap

Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] js_object: L'objet JavaScript qui servira d'enveloppe pour l'objet natif.
• [in] native_object: L'instance native qui sera encapsulée dans l'objet JavaScript.
• [in] finalize_cb: Callback natif optionnel qui peut être utilisé pour libérer l'instance native lorsque l'objet JavaScript a été ramassé par le garbage collector. napi_finalize fournit plus de détails.
• [in] finalize_hint: Indication contextuelle optionnelle passée au callback de finalisation.
• [out] result: Référence optionnelle à l'objet encapsulé.

Retourne napi_ok si l'API a réussi.

Encapsule une instance native dans un objet JavaScript. L'instance native peut être récupérée plus tard à l'aide de napi_unwrap().

Lorsque le code JavaScript appelle un constructeur pour une classe qui a été définie à l'aide de napi_define_class(), le napi_callback du constructeur est invoqué. Après avoir construit une instance de la classe native, le callback doit alors appeler napi_wrap() pour encapsuler l'instance nouvellement construite dans l'objet JavaScript déjà créé qui est l'argument this du callback du constructeur. (Cet objet this a été créé à partir du prototype de la fonction constructeur, il possède donc déjà les définitions de toutes les propriétés et méthodes de l'instance.)

En général, lors de l'encapsulation d'une instance de classe, un callback de finalisation doit être fourni qui supprime simplement l'instance native reçue en tant qu'argument data du callback de finalisation.

La référence retournée optionnelle est initialement une référence faible, ce qui signifie qu'elle a un compteur de référence de 0. Typiquement, ce compteur de référence serait incrémenté temporairement pendant les opérations asynchrones qui nécessitent que l'instance reste valide.

Attention : La référence retournée optionnelle (si obtenue) doit être supprimée via napi_delete_reference UNIQUEMENT en réponse à l'appel du callback de finalisation. Si elle est supprimée avant cela, le callback de finalisation peut ne jamais être invoqué. Par conséquent, lors de l'obtention d'une référence, un callback de finalisation est également requis afin de permettre une élimination correcte de la référence.

Les callbacks de finalisation peuvent être différés, laissant une fenêtre où l'objet a été ramassé par le garbage collector (et la référence faible est invalide) mais le finaliseur n'a pas encore été appelé. Lorsque vous utilisez napi_get_reference_value() sur les références faibles retournées par napi_wrap(), vous devez toujours gérer un résultat vide.

Appeler napi_wrap() une deuxième fois sur un objet renverra une erreur. Pour associer une autre instance native à l'objet, utilisez d'abord napi_remove_wrap().

napi_unwrap

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_unwrap(napi_env env,
                        napi_value js_object,
                        void** result);

• [in] env : L’environnement sous lequel l’API est invoquée.
• [in] js_object : L’objet associé à l’instance native.
• [out] result : Pointeur vers l’instance native encapsulée.

Retourne napi_ok si l’API a réussi.

Récupère une instance native qui a été précédemment encapsulée dans un objet JavaScript à l’aide de napi_wrap().

Lorsque le code JavaScript invoque une méthode ou un accesseur de propriété sur la classe, le napi_callback correspondant est invoqué. Si le rappel est pour une méthode ou un accesseur d’instance, alors l’argument this du rappel est l’objet wrapper ; l’instance C++ encapsulée qui est la cible de l’appel peut alors être obtenue en appelant napi_unwrap() sur l’objet wrapper.

napi_remove_wrap

Ajouté dans : v8.5.0

Version N-API : 1

napi_status napi_remove_wrap(napi_env env,
                             napi_value js_object,
                             void** result);

• [in] env : L’environnement sous lequel l’API est invoquée.
• [in] js_object : L’objet associé à l’instance native.
• [out] result : Pointeur vers l’instance native encapsulée.

Retourne napi_ok si l’API a réussi.

Récupère une instance native qui a été précédemment encapsulée dans l’objet JavaScript js_object à l’aide de napi_wrap() et supprime l’encapsulation. Si un rappel de finalisation était associé à l’encapsulation, il ne sera plus appelé lorsque l’objet JavaScript sera ramassé par le garbage collector.

napi_type_tag_object

Ajouté dans : v14.8.0, v12.19.0

Version N-API : 8

napi_status napi_type_tag_object(napi_env env,
                                 napi_value js_object,
                                 const napi_type_tag* type_tag);

• [in] env : L’environnement sous lequel l’API est invoquée.
• [in] js_object : L’objet JavaScript ou externe à marquer.
• [in] type_tag : La balise avec laquelle l’objet doit être marqué.

Retourne napi_ok si l’API a réussi.

Associe la valeur du pointeur type_tag à l’objet JavaScript ou externe. napi_check_object_type_tag() peut ensuite être utilisé pour comparer la balise qui a été attachée à l’objet avec celle détenue par l’addon afin de s’assurer que l’objet a le bon type.

Si l’objet possède déjà une balise de type associée, cette API retournera napi_invalid_arg.

napi_check_object_type_tag

Ajouté dans : v14.8.0, v12.19.0

Version 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 : L'environnement dans lequel l'API est invoquée.
• [in] js_object : L'objet JavaScript ou externe dont la balise de type doit être examinée.
• [in] type_tag : La balise à comparer avec toute balise trouvée sur l'objet.
• [out] result : Si la balise de type donnée correspond à la balise de type de l'objet. false est également renvoyé si aucune balise de type n'a été trouvée sur l'objet.

Renvoie napi_ok si l'API a réussi.

Compare le pointeur donné en tant que type_tag avec ceux qui peuvent être trouvés sur js_object. Si aucune balise n'est trouvée sur js_object ou si une balise est trouvée mais qu'elle ne correspond pas à type_tag, alors result est défini sur false. Si une balise est trouvée et qu'elle correspond à type_tag, alors result est défini sur true.

napi_add_finalizer

Ajouté dans : v8.0.0

Version 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 : L'environnement dans lequel l'API est invoquée.
• [in] js_object : L'objet JavaScript auquel les données natives seront attachées.
• [in] finalize_data : Données facultatives à passer à finalize_cb.
• [in] finalize_cb : Callback natif qui sera utilisé pour libérer les données natives lorsque l'objet JavaScript a été ramassé par le garbage collector. napi_finalize fournit plus de détails.
• [in] finalize_hint : Indication contextuelle facultative qui est passée au callback de finalisation.
• [out] result : Référence facultative à l'objet JavaScript.

Renvoie napi_ok si l'API a réussi.

Ajoute un callback napi_finalize qui sera appelé lorsque l'objet JavaScript dans js_object a été ramassé par le garbage collector.

Cette API peut être appelée plusieurs fois sur un seul objet JavaScript.

Attention : La référence renvoyée facultative (si obtenue) doit être supprimée via napi_delete_reference UNIQUEMENT en réponse à l'appel du callback de finalisation. Si elle est supprimée avant, le callback de finalisation peut ne jamais être invoqué. Par conséquent, lors de l'obtention d'une référence, un callback de finalisation est également requis afin de permettre une élimination correcte de la référence.

node_api_post_finalizer

Ajouté dans : v21.0.0, v20.10.0, v18.19.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

napi_status node_api_post_finalizer(node_api_basic_env env,
                                    napi_finalize finalize_cb,
                                    void* finalize_data,
                                    void* finalize_hint);

• [in] env : L'environnement dans lequel l'API est invoquée.
• [in] finalize_cb : Callback natif qui sera utilisé pour libérer les données natives lorsque l'objet JavaScript a été ramassé par le garbage collector. napi_finalize fournit plus de détails.
• [in] finalize_data : Données optionnelles à passer à finalize_cb.
• [in] finalize_hint : Indication contextuelle optionnelle passée au callback de finalisation.

Retourne napi_ok si l'API a réussi.

Planifie un callback napi_finalize à appeler de manière asynchrone dans la boucle d'événements.

Normalement, les finaliseurs sont appelés pendant que le GC (garbage collector) collecte les objets. À ce moment-là, l'appel de toute Node-API pouvant entraîner des modifications de l'état du GC sera désactivé et entraînera le plantage de Node.js.

node_api_post_finalizer permet de contourner cette limitation en permettant au module complémentaire de différer les appels à ces Node-API à un moment donné en dehors de la finalisation du GC.

Opérations asynchrones simples

Les modules complémentaires ont souvent besoin de tirer parti des assistants asynchrones de libuv dans le cadre de leur implémentation. Cela leur permet de planifier le travail à exécuter de manière asynchrone afin que leurs méthodes puissent retourner avant la fin du travail. Cela leur permet d'éviter de bloquer l'exécution globale de l'application Node.js.

Node-API fournit une interface ABI stable pour ces fonctions de support qui couvre les cas d'utilisation asynchrones les plus courants.

Node-API définit la structure napi_async_work qui est utilisée pour gérer les travailleurs asynchrones. Les instances sont créées/supprimées avec napi_create_async_work et napi_delete_async_work.

Les callbacks execute et complete sont des fonctions qui seront invoquées lorsque l'exécuteur est prêt à exécuter et lorsqu'il termine sa tâche respectivement.

La fonction execute doit éviter de faire des appels Node-API qui pourraient entraîner l'exécution de JavaScript ou l'interaction avec des objets JavaScript. Le plus souvent, tout code qui doit effectuer des appels Node-API doit être effectué dans le callback complete à la place. Évitez d'utiliser le paramètre napi_env dans le callback execute car il exécutera probablement JavaScript.

Ces fonctions implémentent les interfaces suivantes :

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);

Lorsque ces méthodes sont invoquées, le paramètre data passé sera les données void* fournies par le module complémentaire qui ont été passées à l'appel napi_create_async_work.

Une fois créé, le travailleur asynchrone peut être mis en file d'attente pour exécution à l'aide de la fonction napi_queue_async_work :

napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

napi_cancel_async_work peut être utilisé si le travail doit être annulé avant le début de l'exécution du travail.

Après avoir appelé napi_cancel_async_work, le callback complete sera invoqué avec une valeur de statut de napi_cancelled. Le travail ne doit pas être supprimé avant l'invocation du callback complete, même s'il a été annulé.

napi_create_async_work

[Historique]

Version	Modifications
v8.6.0	Ajout des paramètres async_resource et async_resource_name.
v8.0.0	Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] async_resource: Un objet optionnel associé au travail asynchrone qui sera passé aux éventuels hooks async_hooks init.
• [in] async_resource_name: Identifiant du type de ressource fourni pour les informations de diagnostic exposées par l'API async_hooks.
• [in] execute: La fonction native qui doit être appelée pour exécuter la logique de manière asynchrone. La fonction donnée est appelée à partir d'un thread du pool de travailleurs et peut s'exécuter en parallèle avec le thread de la boucle d'événements principale.
• [in] complete: La fonction native qui sera appelée lorsque la logique asynchrone est terminée ou annulée. La fonction donnée est appelée à partir du thread de la boucle d'événements principale. napi_async_complete_callback fournit plus de détails.
• [in] data: Contexte de données fourni par l'utilisateur. Il sera renvoyé dans les fonctions execute et complete.
• [out] result: napi_async_work* qui est le handle du travail asynchrone nouvellement créé.

Retourne napi_ok si l'API a réussi.

Cette API alloue un objet de travail utilisé pour exécuter la logique de manière asynchrone. Il doit être libéré à l'aide de napi_delete_async_work une fois que le travail n'est plus nécessaire.

async_resource_name doit être une chaîne terminée par un caractère null et codée en UTF-8.

L'identifiant async_resource_name est fourni par l'utilisateur et doit être représentatif du type de travail asynchrone effectué. Il est également recommandé d'appliquer une notation de nommage à l'identifiant, par exemple en incluant le nom du module. Consultez la documentation async_hooks pour plus d'informations.

napi_delete_async_work

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_delete_async_work(napi_env env,
                                   napi_async_work work);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] work: Le handle renvoyé par l'appel à napi_create_async_work.

Renvoie napi_ok si l'API a réussi.

Cette API libère un objet de travail précédemment alloué.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

napi_queue_async_work

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] work: Le handle renvoyé par l'appel à napi_create_async_work.

Renvoie napi_ok si l'API a réussi.

Cette API demande que le travail précédemment alloué soit planifié pour l'exécution. Une fois qu'elle a renvoyé avec succès, cette API ne doit plus être appelée avec le même élément napi_async_work ou le résultat sera indéfini.

napi_cancel_async_work

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_cancel_async_work(node_api_basic_env env,
                                   napi_async_work work);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] work: Le handle renvoyé par l'appel à napi_create_async_work.

Renvoie napi_ok si l'API a réussi.

Cette API annule le travail mis en file d'attente s'il n'a pas encore été démarré. S'il a déjà commencé à s'exécuter, il ne peut pas être annulé et napi_generic_failure sera renvoyé. En cas de succès, le rappel complete sera invoqué avec une valeur de statut de napi_cancelled. Le travail ne doit pas être supprimé avant l'invocation du rappel complete, même s'il a été annulé avec succès.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

Opérations asynchrones personnalisées

Les API de travail asynchrone simples ci-dessus peuvent ne pas convenir à tous les scénarios. Lorsque vous utilisez un autre mécanisme asynchrone, les API suivantes sont nécessaires pour garantir qu'une opération asynchrone est correctement suivie par le runtime.

napi_async_init

Ajouté dans : v8.6.0

Version 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: L'environnement sous lequel l'API est invoquée.
• [in] async_resource: Objet associé au travail asynchrone qui sera passé aux éventuels hooks init async_hooks et qui peut être accessible par async_hooks.executionAsyncResource().
• [in] async_resource_name: Identifiant du type de ressource fournie pour les informations de diagnostic exposées par l'API async_hooks.
• [out] result: Le contexte asynchrone initialisé.

Retourne napi_ok si l'API a réussi.

L'objet async_resource doit rester actif jusqu'à napi_async_destroy pour que l'API async_hooks fonctionne correctement. Afin de conserver la compatibilité ABI avec les versions précédentes, les napi_async_context ne maintiennent pas de référence forte sur les objets async_resource afin d'éviter les fuites de mémoire. Cependant, si async_resource est ramassé par le garbage collector du moteur JavaScript avant que napi_async_context ne soit détruit par napi_async_destroy, l'appel d'API liées à napi_async_context telles que napi_open_callback_scope et napi_make_callback peut entraîner des problèmes tels que la perte de contexte asynchrone lors de l'utilisation de l'API AsyncLocalStorage.

Afin de conserver la compatibilité ABI avec les versions précédentes, le passage de NULL pour async_resource ne génère pas d'erreur. Cependant, ceci n'est pas recommandé car cela entraînera un comportement indésirable avec les hooks init async_hooks et async_hooks.executionAsyncResource() car la ressource est désormais requise par l'implémentation sous-jacente de async_hooks afin de fournir le lien entre les callbacks asynchrones.

napi_async_destroy

Ajouté dans : v8.6.0

Version N-API : 1

napi_status napi_async_destroy(napi_env env,
                               napi_async_context async_context);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] async_context: Le contexte asynchrone à détruire.

Retourne napi_ok si l'API a réussi.

Cette API peut être appelée même s'il y a une exception JavaScript en attente.

napi_make_callback

[Historique]

Version	Modifications
v8.6.0	Paramètre async_context ajouté.
v8.0.0	Ajouté dans : v8.0.0

Version 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: L'environnement dans lequel l'API est invoquée.
• [in] async_context: Contexte pour l'opération asynchrone qui appelle la fonction de rappel. Cela devrait normalement être une valeur obtenue précédemment à partir de napi_async_init. Afin de conserver la compatibilité ABI avec les versions précédentes, passer NULL pour async_context ne génère pas d'erreur. Cependant, cela entraîne un fonctionnement incorrect des hooks asynchrones. Les problèmes potentiels incluent la perte du contexte asynchrone lors de l'utilisation de l'API AsyncLocalStorage.
• [in] recv: La valeur this passée à la fonction appelée.
• [in] func: napi_value représentant la fonction JavaScript à invoquer.
• [in] argc: Le nombre d'éléments dans le tableau argv.
• [in] argv: Tableau de valeurs JavaScript en tant que napi_value représentant les arguments de la fonction. Si argc est égal à zéro, ce paramètre peut être omis en passant NULL.
• [out] result: napi_value représentant l'objet JavaScript retourné.

Retourne napi_ok si l'API a réussi.

Cette méthode permet d'appeler un objet fonction JavaScript à partir d'un module natif. Cette API est similaire à napi_call_function. Cependant, elle est utilisée pour appeler depuis le code natif vers JavaScript après le retour d'une opération asynchrone (lorsqu'il n'y a pas d'autre script sur la pile). C'est un wrapper assez simple autour de node::MakeCallback.

Notez qu'il n'est pas nécessaire d'utiliser napi_make_callback depuis une napi_async_complete_callback ; dans ce cas, le contexte asynchrone de la fonction de rappel a déjà été configuré, donc un appel direct à napi_call_function est suffisant et approprié. L'utilisation de la fonction napi_make_callback peut être nécessaire lors de l'implémentation d'un comportement asynchrone personnalisé qui n'utilise pas napi_create_async_work.

Tous les process.nextTick ou les Promises planifiés sur la file d'attente des microtâches par JavaScript pendant la fonction de rappel sont exécutés avant le retour en C/C++.

napi_open_callback_scope

Ajouté dans : v9.6.0

Version 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: L'environnement dans lequel l'API est appelée.
• [in] resource_object: Un objet associé au travail asynchrone qui sera passé aux éventuels hooks init async_hooks. Ce paramètre est obsolète et ignoré lors de l'exécution. Utilisez plutôt le paramètre async_resource dans napi_async_init.
• [in] context: Contexte de l'opération asynchrone qui appelle la fonction de rappel. Il doit s'agir d'une valeur obtenue précédemment à partir de napi_async_init.
• [out] result: La portée nouvellement créée.

Il existe des cas (par exemple, la résolution des promesses) où il est nécessaire d'avoir l'équivalent de la portée associée à une fonction de rappel en place lors de certains appels Node-API. S'il n'y a pas d'autre script sur la pile, les fonctions napi_open_callback_scope et napi_close_callback_scope peuvent être utilisées pour ouvrir/fermer la portée requise.

napi_close_callback_scope

Ajouté dans : v9.6.0

Version N-API : 3

NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
                                                  napi_callback_scope scope)

• [in] env: L'environnement dans lequel l'API est appelée.
• [in] scope: La portée à fermer.

Cette API peut être appelée même s'il existe une exception JavaScript en attente.

Gestion des versions

napi_get_node_version

Ajouté dans : v8.4.0

Version 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: L'environnement dans lequel l'API est appelée.
• [out] version: Un pointeur vers les informations de version de Node.js lui-même.

Retourne napi_ok si l'API a réussi.

Cette fonction remplit la structure version avec les versions majeure, mineure et corrective de Node.js en cours d'exécution, et le champ release avec la valeur de process.release.name.

Le tampon renvoyé est alloué statiquement et n'a pas besoin d'être libéré.

napi_get_version

Ajouté dans : v8.0.0

Version N-API : 1

napi_status napi_get_version(node_api_basic_env env,
                             uint32_t* result);

• [in] env: L'environnement sous lequel l'API est invoquée.
• [out] result: La version la plus élevée de Node-API prise en charge.

Retourne napi_ok si l'API a réussi.

Cette API retourne la version la plus élevée de Node-API prise en charge par le runtime Node.js. Node-API est prévu pour être additif de sorte que les nouvelles versions de Node.js peuvent prendre en charge des fonctions API supplémentaires. Afin de permettre à un addon d'utiliser une fonction plus récente lorsqu'il fonctionne avec des versions de Node.js qui la prennent en charge, tout en fournissant un comportement de secours lorsqu'il fonctionne avec des versions de Node.js qui ne la prennent pas en charge :

• Appelez napi_get_version() pour déterminer si l'API est disponible.
• Si disponible, chargez dynamiquement un pointeur vers la fonction à l'aide de uv_dlsym().
• Utilisez le pointeur chargé dynamiquement pour appeler la fonction.
• Si la fonction n'est pas disponible, fournissez une implémentation alternative qui n'utilise pas la fonction.

Gestion de la mémoire

napi_adjust_external_memory

Ajouté dans : v8.5.0

Version 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: L'environnement sous lequel l'API est invoquée.
• [in] change_in_bytes: Le changement dans la mémoire allouée en externe qui est maintenue en vie par les objets JavaScript.
• [out] result: La valeur ajustée

Retourne napi_ok si l'API a réussi.

Cette fonction donne à V8 une indication de la quantité de mémoire allouée en externe qui est maintenue en vie par les objets JavaScript (c'est-à-dire un objet JavaScript qui pointe vers sa propre mémoire allouée par un addon natif). L'enregistrement de la mémoire allouée en externe déclenchera des collectes de déchets globales plus souvent qu'il ne le ferait autrement.

Promesses

Node-API fournit des outils pour créer des objets Promise comme décrit dans la Section 25.4 de la spécification ECMA. Il implémente les promesses comme une paire d'objets. Lorsqu'une promesse est créée par napi_create_promise(), un objet « différé » est créé et retourné avec la Promise. L'objet différé est lié à la Promise créée et est le seul moyen de résoudre ou de rejeter la Promise à l'aide de napi_resolve_deferred() ou napi_reject_deferred(). L'objet différé créé par napi_create_promise() est libéré par napi_resolve_deferred() ou napi_reject_deferred(). L'objet Promise peut être retourné à JavaScript où il peut être utilisé de la manière habituelle.

Par exemple, pour créer une promesse et la transmettre à un travailleur asynchrone :

napi_deferred deferred;
napi_value promise;
napi_status status;

// Créer la promesse.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;

// Passer le différé à une fonction qui effectue une action asynchrone.
do_something_asynchronous(deferred);

// Retourner la promesse à JS
return promise;

La fonction ci-dessus do_something_asynchronous() effectuerait son action asynchrone, puis elle résoudrait ou rejetterait le différé, concluant ainsi la promesse et libérant le différé :

napi_deferred deferred;
napi_value undefined;
napi_status status;

// Créer une valeur avec laquelle conclure le différé.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;

// Résoudre ou rejeter la promesse associée au différé selon que
// l'action asynchrone a réussi ou non.
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;

// À ce stade, le différé a été libéré, nous devons donc lui assigner NULL.
deferred = NULL;

napi_create_promise

Ajouté dans : v8.5.0

Version N-API : 1

napi_status napi_create_promise(napi_env env,
                                napi_deferred* deferred,
                                napi_value* promise);

• [in] env : L’environnement dans lequel l’API est invoquée.
• [out] deferred : Un objet différé nouvellement créé qui peut plus tard être passé à napi_resolve_deferred() ou napi_reject_deferred() pour résoudre ou rejeter respectivement la promesse associée.
• [out] promise : La promesse JavaScript associée à l’objet différé.

Retourne napi_ok si l’API a réussi.

Cette API crée un objet différé et une promesse JavaScript.

napi_resolve_deferred

Ajouté dans : v8.5.0

Version N-API : 1

napi_status napi_resolve_deferred(napi_env env,
                                  napi_deferred deferred,
                                  napi_value resolution);

• [in] env : L’environnement dans lequel l’API est invoquée.
• [in] deferred : L’objet différé dont la promesse associée doit être résolue.
• [in] resolution : La valeur avec laquelle résoudre la promesse.

Cette API résout une promesse JavaScript au moyen de l’objet différé auquel elle est associée. Ainsi, elle ne peut être utilisée que pour résoudre les promesses JavaScript pour lesquelles l’objet différé correspondant est disponible. Cela signifie effectivement que la promesse doit avoir été créée à l’aide de napi_create_promise() et que l’objet différé retourné par cet appel doit avoir été conservé afin d’être passé à cette API.

L’objet différé est libéré après une exécution réussie.

napi_reject_deferred

Ajouté dans : v8.5.0

Version N-API : 1

napi_status napi_reject_deferred(napi_env env,
                                 napi_deferred deferred,
                                 napi_value rejection);

• [in] env : L’environnement dans lequel l’API est invoquée.
• [in] deferred : L’objet différé dont la promesse associée doit être résolue.
• [in] rejection : La valeur avec laquelle rejeter la promesse.

Cette API rejette une promesse JavaScript au moyen de l’objet différé auquel elle est associée. Ainsi, elle ne peut être utilisée que pour rejeter les promesses JavaScript pour lesquelles l’objet différé correspondant est disponible. Cela signifie effectivement que la promesse doit avoir été créée à l’aide de napi_create_promise() et que l’objet différé retourné par cet appel doit avoir été conservé afin d’être passé à cette API.

L’objet différé est libéré après une exécution réussie.

napi_is_promise

Ajouté dans : v8.5.0

Version N-API : 1

napi_status napi_is_promise(napi_env env,
                            napi_value value,
                            bool* is_promise);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] value: La valeur à examiner.
• [out] is_promise: Indicateur booléen précisant si promise est un objet Promise natif (c'est-à-dire un objet Promise créé par le moteur sous-jacent).

Exécution de script

Node-API fournit une API pour exécuter une chaîne de caractères contenant du JavaScript à l'aide du moteur JavaScript sous-jacent.

napi_run_script

Ajouté dans : v8.5.0

Version N-API : 1

NAPI_EXTERN napi_status napi_run_script(napi_env env,
                                        napi_value script,
                                        napi_value* result);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [in] script: Une chaîne de caractères JavaScript contenant le script à exécuter.
• [out] result: La valeur résultant de l'exécution du script.

Cette fonction exécute une chaîne de code JavaScript et renvoie son résultat avec les mises en garde suivantes :

• Contrairement à eval, cette fonction ne permet pas au script d'accéder à la portée lexicale actuelle, et donc, n'autorise pas non plus l'accès à la portée du module, ce qui signifie que les pseudo-globaux tels que require ne seront pas disponibles.
• Le script peut accéder à la portée globale. Les déclarations de fonction et var dans le script seront ajoutées à l'objet global. Les déclarations de variables effectuées à l'aide de let et const seront visibles globalement, mais ne seront pas ajoutées à l'objet global.
• La valeur de this est global dans le script.

Boucle d'événements libuv

Node-API fournit une fonction permettant d'obtenir la boucle d'événements actuelle associée à un napi_env spécifique.

napi_get_uv_event_loop

Ajouté dans : v9.3.0, v8.10.0

Version N-API : 2

NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
                                               struct uv_loop_s** loop);

• [in] env: L'environnement dans lequel l'API est invoquée.
• [out] loop: L'instance de boucle libuv actuelle.

Remarque : bien que libuv ait été relativement stable au fil du temps, il ne fournit pas de garantie de stabilité ABI. L'utilisation de cette fonction doit être évitée. Son utilisation peut entraîner un module complémentaire qui ne fonctionne pas sur plusieurs versions de Node.js. Les appels de fonction asynchrones et thread-safe constituent une alternative pour de nombreux cas d'utilisation.

Appels de fonctions asynchrones et thread-safe

Les fonctions JavaScript ne peuvent normalement être appelées que depuis le thread principal d'un addon natif. Si un addon crée des threads supplémentaires, les fonctions Node-API nécessitant un napi_env, napi_value ou napi_ref ne doivent pas être appelées depuis ces threads.

Lorsqu'un addon possède des threads supplémentaires et que des fonctions JavaScript doivent être invoquées en fonction du traitement effectué par ces threads, ces threads doivent communiquer avec le thread principal de l'addon afin que le thread principal puisse invoquer la fonction JavaScript en leur nom. Les API de fonctions thread-safe offrent un moyen simple de le faire.

Ces API fournissent le type napi_threadsafe_function ainsi que des API pour créer, détruire et appeler des objets de ce type. napi_create_threadsafe_function() crée une référence persistante à une napi_value qui contient une fonction JavaScript pouvant être appelée à partir de plusieurs threads. Les appels sont asynchrones. Cela signifie que les valeurs avec lesquelles la fonction de rappel JavaScript doit être appelée seront placées dans une file d'attente, et, pour chaque valeur de la file d'attente, un appel sera éventuellement effectué à la fonction JavaScript.

Lors de la création d'une napi_threadsafe_function, une fonction de rappel napi_finalize peut être fournie. Cette fonction de rappel sera invoquée sur le thread principal lorsque la fonction thread-safe est sur le point d'être détruite. Elle reçoit le contexte et les données de finalisation fournies lors de la construction, et offre la possibilité de nettoyer après les threads, par exemple en appelant uv_thread_join(). Mis à part le thread de la boucle principale, aucun thread ne doit utiliser la fonction thread-safe après la fin de la fonction de rappel de finalisation.

Le context fourni lors de l'appel à napi_create_threadsafe_function() peut être récupéré depuis n'importe quel thread avec un appel à napi_get_threadsafe_function_context().

Appel d'une fonction thread-safe

napi_call_threadsafe_function() peut être utilisé pour initier un appel à JavaScript. napi_call_threadsafe_function() accepte un paramètre qui contrôle si l'API se comporte de manière bloquante. S'il est défini sur napi_tsfn_nonblocking, l'API se comporte de manière non bloquante, renvoyant napi_queue_full si la file d'attente était pleine, empêchant les données d'être ajoutées avec succès à la file d'attente. S'il est défini sur napi_tsfn_blocking, l'API bloque jusqu'à ce qu'il y ait de la place dans la file d'attente. napi_call_threadsafe_function() ne bloque jamais si la fonction thread-safe a été créée avec une taille de file d'attente maximale de 0.

napi_call_threadsafe_function() ne doit pas être appelé avec napi_tsfn_blocking depuis un thread JavaScript car, si la file d'attente est pleine, cela peut entraîner un blocage du thread JavaScript.

L'appel réel à JavaScript est contrôlé par la fonction de rappel fournie via le paramètre call_js_cb. call_js_cb est invoqué sur le thread principal une fois pour chaque valeur qui a été placée dans la file d'attente par un appel réussi à napi_call_threadsafe_function(). Si une telle fonction de rappel n'est pas fournie, une fonction de rappel par défaut sera utilisée, et l'appel JavaScript résultant n'aura aucun argument. La fonction de rappel call_js_cb reçoit la fonction JavaScript à appeler sous forme de napi_value dans ses paramètres, ainsi que le pointeur de contexte void* utilisé lors de la création de la napi_threadsafe_function, et le prochain pointeur de données qui a été créé par l'un des threads secondaires. La fonction de rappel peut ensuite utiliser une API telle que napi_call_function() pour appeler JavaScript.

La fonction de rappel peut également être invoquée avec env et call_js_cb tous deux définis sur NULL pour indiquer que les appels à JavaScript ne sont plus possibles, tandis que des éléments restent dans la file d'attente et peuvent avoir besoin d'être libérés. Cela se produit normalement lorsque le processus Node.js se termine alors qu'une fonction thread-safe est toujours active.

Il n'est pas nécessaire d'appeler JavaScript via napi_make_callback() car Node-API exécute call_js_cb dans un contexte approprié pour les fonctions de rappel.

Zéro ou plusieurs éléments en file d'attente peuvent être invoqués à chaque tick de la boucle d'événements. Les applications ne doivent pas dépendre d'un comportement spécifique autre que le progrès de l'invocation des fonctions de rappel sera fait et les événements seront invoqués au fur et à mesure que le temps avance.

Comptage de références des fonctions thread-safe

Des threads peuvent être ajoutés et supprimés d'un objet napi_threadsafe_function durant son existence. Ainsi, en plus de spécifier un nombre initial de threads lors de la création, napi_acquire_threadsafe_function peut être appelé pour indiquer qu'un nouveau thread va commencer à utiliser la fonction thread-safe. De même, napi_release_threadsafe_function peut être appelé pour indiquer qu'un thread existant va cesser d'utiliser la fonction thread-safe.

Les objets napi_threadsafe_function sont détruits lorsque chaque thread qui utilise l'objet a appelé napi_release_threadsafe_function() ou a reçu un statut de retour de napi_closing en réponse à un appel à napi_call_threadsafe_function. La queue est vidée avant que napi_threadsafe_function ne soit détruit. napi_release_threadsafe_function() doit être le dernier appel API effectué en conjonction avec un napi_threadsafe_function donné, car après l'exécution de l'appel, il n'y a aucune garantie que napi_threadsafe_function est encore alloué. Pour la même raison, n'utilisez pas une fonction thread-safe après avoir reçu une valeur de retour de napi_closing en réponse à un appel à napi_call_threadsafe_function. Les données associées à napi_threadsafe_function peuvent être libérées dans son rappel napi_finalize qui a été passé à napi_create_threadsafe_function(). Le paramètre initial_thread_count de napi_create_threadsafe_function marque le nombre initial d'acquisitions des fonctions thread-safe, au lieu d'appeler napi_acquire_threadsafe_function plusieurs fois lors de la création.

Une fois que le nombre de threads utilisant un napi_threadsafe_function atteint zéro, aucun autre thread ne peut commencer à l'utiliser en appelant napi_acquire_threadsafe_function(). En fait, tous les appels API suivants qui lui sont associés, excepté napi_release_threadsafe_function(), retourneront une valeur d'erreur de napi_closing.

La fonction thread-safe peut être "arrêtée" en donnant une valeur de napi_tsfn_abort à napi_release_threadsafe_function(). Cela fera que tous les API suivants associés à la fonction thread-safe, excepté napi_release_threadsafe_function(), retourneront napi_closing même avant que son compteur de références n'atteigne zéro. En particulier, napi_call_threadsafe_function() retournera napi_closing, informant ainsi les threads qu'il n'est plus possible d'effectuer des appels asynchrones à la fonction thread-safe. Cela peut être utilisé comme critère pour terminer le thread. Lors de la réception d'une valeur de retour de napi_closing de la part de napi_call_threadsafe_function(), un thread ne doit plus utiliser la fonction thread-safe car il n'est plus garanti qu'elle soit allouée.

Décider si le processus doit rester actif

De manière similaire aux handles libuv, les fonctions thread-safe peuvent être "référencées" et "déréférencées". Une fonction thread-safe "référencée" maintiendra la boucle d'événements du thread sur lequel elle est créée active jusqu'à ce que la fonction thread-safe soit détruite. En revanche, une fonction thread-safe "déréférencée" n'empêchera pas la boucle d'événements de se terminer. Les API napi_ref_threadsafe_function et napi_unref_threadsafe_function existent à cette fin.

Ni napi_unref_threadsafe_function ne marque les fonctions thread-safe comme pouvant être détruites, ni napi_ref_threadsafe_function ne l'empêche.

napi_create_threadsafe_function

[Historique]

Version	Modifications
v12.6.0, v10.17.0	Le paramètre func est devenu optionnel avec call_js_cb personnalisé.
v10.6.0	Ajouté dans : v10.6.0

Version 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: L'environnement sous lequel l'API est invoquée.
• [in] func: Une fonction JavaScript optionnelle à appeler depuis un autre thread. Elle doit être fournie si NULL est passé à call_js_cb.
• [in] async_resource: Un objet optionnel associé au travail asynchrone qui sera passé aux éventuels hooks init async_hooks.
• [in] async_resource_name: Une chaîne JavaScript pour fournir un identifiant au type de ressource fourni pour les informations de diagnostic exposées par l'API async_hooks.
• [in] max_queue_size: Taille maximale de la file d'attente. 0 pour aucune limite.
• [in] initial_thread_count: Le nombre initial d'acquisitions, c'est-à-dire le nombre initial de threads, y compris le thread principal, qui utiliseront cette fonction.
• [in] thread_finalize_data: Données optionnelles à passer à thread_finalize_cb.
• [in] thread_finalize_cb: Fonction optionnelle à appeler lorsque la fonction napi_threadsafe_function est détruite.
• [in] context: Données optionnelles à attacher à la fonction napi_threadsafe_function résultante.
• [in] call_js_cb: Callback optionnel qui appelle la fonction JavaScript en réponse à un appel sur un autre thread. Ce callback sera appelé sur le thread principal. S'il n'est pas fourni, la fonction JavaScript sera appelée sans paramètres et avec undefined comme valeur this. napi_threadsafe_function_call_js fournit plus de détails.
• [out] result: La fonction JavaScript asynchrone thread-safe.

Historique des modifications :

• Expérimental (NAPI_EXPERIMENTAL est défini) : Les exceptions non interceptées levées dans call_js_cb sont gérées avec l'événement 'uncaughtException', au lieu d'être ignorées.

napi_get_threadsafe_function_context

Ajouté dans : v10.6.0

Version N-API : 4

NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
                                     void** result);

• [in] func: La fonction thread-safe pour laquelle récupérer le contexte.
• [out] result: L'emplacement où stocker le contexte.

Cette API peut être appelée depuis n'importe quel thread qui utilise func.

napi_call_threadsafe_function

[Historique]

Version	Modifications
v14.5.0	La prise en charge de napi_would_deadlock a été rétablie.
v14.1.0	Retourne napi_would_deadlock lorsqu'elle est appelée avec napi_tsfn_blocking depuis le thread principal ou un thread de travailleur et que la file d'attente est pleine.
v10.6.0	Ajouté dans : v10.6.0

Version 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 fonction JavaScript asynchrone thread-safe à invoquer.
• [in] data: Données à envoyer dans JavaScript via le rappel call_js_cb fourni lors de la création de la fonction JavaScript thread-safe.
• [in] is_blocking: Indicateur dont la valeur peut être soit napi_tsfn_blocking pour indiquer que l'appel doit bloquer si la file d'attente est pleine, soit napi_tsfn_nonblocking pour indiquer que l'appel doit retourner immédiatement avec un statut de napi_queue_full lorsque la file d'attente est pleine.

Cette API ne doit pas être appelée avec napi_tsfn_blocking depuis un thread JavaScript car, si la file d'attente est pleine, cela peut entraîner un blocage du thread JavaScript.

Cette API retournera napi_closing si napi_release_threadsafe_function() a été appelée avec abort défini sur napi_tsfn_abort depuis n'importe quel thread. La valeur n'est ajoutée à la file d'attente que si l'API retourne napi_ok.

Cette API peut être appelée depuis n'importe quel thread qui utilise func.

napi_acquire_threadsafe_function

Ajouté dans : v10.6.0

Version N-API : 4

NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);

• [in] func: La fonction JavaScript asynchrone thread-safe à commencer à utiliser.

Un thread doit appeler cette API avant de passer func à d'autres API de fonction thread-safe pour indiquer qu'il utilisera func. Cela empêche func d'être détruit lorsque tous les autres threads ont cessé de l'utiliser.

Cette API peut être appelée depuis n'importe quel thread qui commencera à utiliser func.

napi_release_threadsafe_function

Ajouté dans : v10.6.0

Version N-API : 4

NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);

• [in] func : La fonction JavaScript asynchrone thread-safe dont le nombre de références doit être décrémenté.
• [in] mode : Indicateur dont la valeur peut être soit napi_tsfn_release pour indiquer que le thread actuel ne fera plus d’appels à la fonction thread-safe, soit napi_tsfn_abort pour indiquer qu’en plus du thread actuel, aucun autre thread ne doit faire d’autres appels à la fonction thread-safe. Si la valeur est définie sur napi_tsfn_abort, les appels ultérieurs à napi_call_threadsafe_function() renverront napi_closing, et aucune autre valeur ne sera placée dans la file d’attente.

Un thread doit appeler cette API lorsqu’il cesse d’utiliser func. Passer func à des API thread-safe après avoir appelé cette API produit des résultats indéfinis, car func peut avoir été détruit.

Cette API peut être appelée à partir de n’importe quel thread qui cessera d’utiliser func.

napi_ref_threadsafe_function

Ajouté dans : v10.6.0

Version N-API : 4

NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);

• [in] env : L’environnement dans lequel l’API est appelée.
• [in] func : La fonction thread-safe à référencer.

Cette API sert à indiquer que la boucle d’événements s’exécutant sur le thread principal ne doit pas se terminer tant que func n’a pas été détruit. Semblable à uv_ref, elle est également idempotente.

Ni napi_unref_threadsafe_function ne marque les fonctions thread-safe comme pouvant être détruites, ni napi_ref_threadsafe_function ne l’empêche. napi_acquire_threadsafe_function et napi_release_threadsafe_function sont disponibles à cette fin.

Cette API ne peut être appelée que depuis le thread principal.

napi_unref_threadsafe_function

Ajouté dans : v10.6.0

Version N-API : 4

NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);

• [in] env : L’environnement dans lequel l’API est appelée.
• [in] func : La fonction thread-safe à désabonner.

Cette API sert à indiquer que la boucle d’événements s’exécutant sur le thread principal peut se terminer avant que func ne soit détruit. Semblable à uv_unref, elle est également idempotente.

Cette API ne peut être appelée que depuis le thread principal.

Utilitaires divers

node_api_get_module_file_name

Ajouté dans : v15.9.0, v14.18.0, v12.22.0

Version N-API : 9

NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);

• [in] env: L'environnement dans lequel l'API est appelée.
• [out] result: Une URL contenant le chemin absolu de l'emplacement depuis lequel le module complémentaire a été chargé. Pour un fichier sur le système de fichiers local, il commencera par file://. La chaîne est terminée par un caractère null et appartient à env ; elle ne doit donc pas être modifiée ou libérée.

result peut être une chaîne vide si le processus de chargement du module complémentaire ne parvient pas à établir le nom du fichier du module complémentaire pendant le chargement.