Node-API

[Stabil: 2 - Stabil]

Node-API (früher N-API) ist eine API zum Erstellen nativer Addons. Sie ist unabhängig von der zugrunde liegenden JavaScript-Laufzeitumgebung (z. B. V8) und wird als Teil von Node.js selbst verwaltet. Diese API wird über verschiedene Node.js-Versionen hinweg eine stabile Application Binary Interface (ABI) aufweisen. Sie soll Addons von Änderungen in der zugrunde liegenden JavaScript-Engine isolieren und ermöglichen, dass Module, die für eine Hauptversion kompiliert wurden, ohne Neukompilierung auf späteren Hauptversionen von Node.js ausgeführt werden können. Der Leitfaden zur ABI-Stabilität bietet eine detailliertere Erklärung.

Addons werden mit dem gleichen Ansatz/den gleichen Tools erstellt/verpackt, die im Abschnitt mit dem Titel C++ Addons beschrieben sind. Der einzige Unterschied besteht in den APIs, die vom nativen Code verwendet werden. Anstatt die V8- oder Native Abstractions for Node.js APIs zu verwenden, werden die in Node-API verfügbaren Funktionen verwendet.

Die von Node-API bereitgestellten APIs werden im Allgemeinen verwendet, um JavaScript-Werte zu erstellen und zu manipulieren. Konzepte und Operationen entsprechen im Allgemeinen den in der ECMA-262-Sprachspezifikation angegebenen Ideen. Die APIs haben die folgenden Eigenschaften:

Alle Node-API-Aufrufe geben einen Statuscode vom Typ napi_status zurück. Dieser Status gibt an, ob der API-Aufruf erfolgreich war oder fehlgeschlagen ist.
Der Rückgabewert der API wird über einen Ausgabeparameter übergeben.
Alle JavaScript-Werte werden hinter einem opaken Typ namens napi_value abstrahiert.
Im Falle eines Fehlerstatuscodes können zusätzliche Informationen mit napi_get_last_error_info abgerufen werden. Weitere Informationen finden Sie im Abschnitt zur Fehlerbehandlung Fehlerbehandlung.

Node-API ist eine C-API, die die ABI-Stabilität über Node.js-Versionen und verschiedene Compilerstufen hinweg gewährleistet. Eine C++-API kann einfacher zu verwenden sein. Um die Verwendung von C++ zu unterstützen, verwaltet das Projekt ein C++-Wrapper-Modul namens node-addon-api. Dieser Wrapper bietet eine inlinefähige C++-API. Mit node-addon-api erstellte Binärdateien hängen von den Symbolen für die von Node.js exportierten C-basierten Funktionen der Node-API ab. node-addon-api ist eine effizientere Methode zum Schreiben von Code, der Node-API aufruft. Betrachten Sie beispielsweise den folgenden node-addon-api-Code. Der erste Abschnitt zeigt den node-addon-api-Code und der zweite Abschnitt zeigt, was tatsächlich im Addon verwendet wird.

C++

Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");

C++

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

Das Endergebnis ist, dass das Addon nur die exportierten C-APIs verwendet. Daher profitiert es weiterhin von der ABI-Stabilität, die die C-API bietet.

Wenn Sie node-addon-api anstelle der C-APIs verwenden, beginnen Sie mit der API-Dokumentation für node-addon-api.

Die Node-API-Ressource bietet eine hervorragende Orientierung und Tipps für Entwickler, die gerade erst mit Node-API und node-addon-api beginnen. Zusätzliche Medienressourcen finden Sie auf der Seite Node-API-Medien.

Auswirkungen der ABI-Stabilität

Obwohl Node-API eine ABI-Stabilitätsgarantie bietet, gilt dies nicht für andere Teile von Node.js, und möglicherweise auch nicht für externe Bibliotheken, die vom Addon verwendet werden. Insbesondere bieten keine der folgenden APIs eine ABI-Stabilitätsgarantie über Hauptversionen hinweg:

die Node.js C++-APIs, die über verfügbar sind
die libuv-APIs, die ebenfalls in Node.js enthalten und über verfügbar sind
die V8-API, die über verfügbar ist

Damit ein Addon über Node.js-Hauptversionen hinweg ABI-kompatibel bleibt, muss es ausschließlich Node-API verwenden, indem es sich darauf beschränkt,

#include <node_api.h>

zu verwenden und für alle externen Bibliotheken, die es verwendet, zu überprüfen, ob die externe Bibliothek ähnliche ABI-Stabilitätsgarantien wie Node-API bietet.

Build

Im Gegensatz zu in JavaScript geschriebenen Modulen erfordert die Entwicklung und Bereitstellung von Node.js-nativen Addons mit Node-API einen zusätzlichen Satz von Tools. Neben den grundlegenden Tools, die für die Entwicklung für Node.js erforderlich sind, benötigt der Entwickler nativer Addons eine Toolchain, die C- und C++-Code in eine Binärdatei kompilieren kann. Darüber hinaus benötigt der Benutzer des nativen Addons, je nachdem, wie das native Addon bereitgestellt wird, ebenfalls eine C/C++-Toolchain.

Für Linux-Entwickler sind die notwendigen C/C++-Toolchain-Pakete leicht verfügbar. GCC wird in der Node.js-Community weit verbreitet verwendet, um plattformübergreifend zu bauen und zu testen. Für viele Entwickler ist die LLVM-Compiler-Infrastruktur ebenfalls eine gute Wahl.

Für Mac-Entwickler bietet Xcode alle erforderlichen Compiler-Tools. Es ist jedoch nicht notwendig, die gesamte Xcode-IDE zu installieren. Der folgende Befehl installiert die notwendige Toolchain:

bash

xcode-select --install

Für Windows-Entwickler bietet Visual Studio alle erforderlichen Compiler-Tools. Es ist jedoch nicht notwendig, die gesamte Visual Studio-IDE zu installieren. Der folgende Befehl installiert die notwendige Toolchain:

bash

npm install --global windows-build-tools

Die folgenden Abschnitte beschreiben die zusätzlichen Tools, die für die Entwicklung und Bereitstellung von Node.js-nativen Addons verfügbar sind.

Build-Tools

Die hier aufgeführten Tools setzen voraus, dass Benutzer des nativen Addons über eine C/C++-Toolchain verfügen, um das native Addon erfolgreich zu installieren.

node-gyp

node-gyp ist ein Build-System, das auf dem gyp-next-Fork von Googles GYP-Tool basiert und mit npm gebündelt ist. GYP und damit node-gyp erfordern die Installation von Python.

Historisches war node-gyp das bevorzugte Tool zum Erstellen nativer Addons. Es ist weit verbreitet und gut dokumentiert. Einige Entwickler sind jedoch auf Einschränkungen in node-gyp gestoßen.

CMake.js

CMake.js ist ein alternatives Build-System, das auf CMake basiert.

CMake.js ist eine gute Wahl für Projekte, die bereits CMake verwenden, oder für Entwickler, die von den Einschränkungen in node-gyp betroffen sind. build_with_cmake ist ein Beispiel für ein CMake-basiertes natives Addon-Projekt.

Hochladen vorkompilierter Binärdateien

Die drei hier aufgeführten Tools ermöglichen es Entwicklern und Betreuern nativer Addons, Binärdateien zu erstellen und auf öffentliche oder private Server hochzuladen. Diese Tools werden typischerweise in CI/CD-Build-Systeme wie Travis CI und AppVeyor integriert, um Binärdateien für eine Vielzahl von Plattformen und Architekturen zu erstellen und hochzuladen. Diese Binärdateien stehen dann Benutzern zum Download zur Verfügung, die keine C/C++-Toolchain installieren müssen.

node-pre-gyp

node-pre-gyp ist ein Tool, das auf node-gyp basiert und die Möglichkeit bietet, Binärdateien auf einen Server der Wahl des Entwicklers hochzuladen. node-pre-gyp bietet besonders gute Unterstützung für das Hochladen von Binärdateien auf Amazon S3.

prebuild

prebuild ist ein Tool, das Builds mit node-gyp oder CMake.js unterstützt. Im Gegensatz zu node-pre-gyp, das eine Vielzahl von Servern unterstützt, lädt prebuild Binärdateien nur auf GitHub Releases hoch. prebuild ist eine gute Wahl für GitHub-Projekte, die CMake.js verwenden.

prebuildify

prebuildify ist ein auf node-gyp basierendes Tool. Der Vorteil von prebuildify besteht darin, dass die erstellten Binärdateien beim Hochladen des Native Addons zu npm mit diesem gebündelt werden. Die Binärdateien werden von npm heruntergeladen und stehen dem Modulbenutzer beim Installieren des Native Addons sofort zur Verfügung.

Verwendung

Um die Node-API-Funktionen zu verwenden, schließen Sie die Datei node_api.h ein, die sich im src-Verzeichnis im Node-Entwicklungsbaum befindet:

#include <node_api.h>

Dies aktiviert die Standard-NAPI_VERSION für die gegebene Node.js-Version. Um die Kompatibilität mit bestimmten Versionen der Node-API sicherzustellen, kann die Version beim Einschließen der Headerdatei explizit angegeben werden:

#define NAPI_VERSION 3
#include <node_api.h>

Dies schränkt die Node-API-Oberfläche auf die Funktionalität ein, die in den angegebenen (und früheren) Versionen verfügbar war.

Ein Teil der Node-API-Oberfläche ist experimentell und erfordert ein explizites Opt-in:

#define NAPI_EXPERIMENTAL
#include <node_api.h>

In diesem Fall steht die gesamte API-Oberfläche, einschließlich aller experimentellen APIs, dem Modulcode zur Verfügung.

Gelegentlich werden experimentelle Funktionen eingeführt, die sich auf bereits veröffentlichte und stabile APIs auswirken. Diese Funktionen können durch ein Opt-out deaktiviert werden:

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

wobei \<FEATURE_NAME\> der Name einer experimentellen Funktion ist, die sich sowohl auf experimentelle als auch auf stabile APIs auswirkt.

Node-API Versionsmatrix

Bis Version 9 waren die Node-API-Versionen additiv und wurden unabhängig von Node.js versioniert. Dies bedeutete, dass jede Version eine Erweiterung der vorherigen Version war, da sie alle APIs der vorherigen Version mit einigen Ergänzungen enthielt. Jede Node.js-Version unterstützte nur eine einzige Node-API-Version. Beispielsweise unterstützt v18.15.0 nur Node-API-Version 8. Die ABI-Stabilität wurde erreicht, da 8 eine strikte Obermenge aller vorherigen Versionen war.

Ab Version 9, während Node-API-Versionen weiterhin unabhängig versioniert werden, kann ein Add-on, das mit Node-API-Version 9 ausgeführt wurde, Code-Updates benötigen, um mit Node-API-Version 10 ausgeführt zu werden. Die ABI-Stabilität wird jedoch beibehalten, da Node.js-Versionen, die Node-API-Versionen höher als 8 unterstützen, alle Versionen zwischen 8 und der höchsten von ihnen unterstützten Version unterstützen und standardmäßig die Version 8-APIs bereitstellen, es sei denn, ein Add-on aktiviert eine höhere Node-API-Version. Dieser Ansatz bietet die Flexibilität, bestehende Node-API-Funktionen besser zu optimieren und gleichzeitig die ABI-Stabilität zu gewährleisten. Bestehende Add-ons können weiterhin ohne Neukompilierung mit einer früheren Version der Node-API ausgeführt werden. Wenn ein Add-on Funktionen einer neueren Node-API-Version benötigt, sind Änderungen am bestehenden Code und eine Neukompilierung erforderlich, um diese neuen Funktionen zu verwenden.

In Versionen von Node.js, die Node-API-Version 9 und höher unterstützen, wird durch Definieren von NAPI_VERSION=X und Verwenden der vorhandenen Add-on-Initialisierungsmakros die angeforderte Node-API-Version, die zur Laufzeit verwendet wird, in das Add-on eingebrannt. Wenn NAPI_VERSION nicht gesetzt ist, wird standardmäßig 8 verwendet.

Diese Tabelle ist möglicherweise in älteren Streams nicht aktuell. Die aktuellsten Informationen finden Sie in der neuesten API-Dokumentation unter: Node-API Versionsmatrix

Node-API Version	Unterstützt in
9	v18.17.0+, 20.3.0+, 21.0.0 und alle späteren Versionen
8	v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 und alle späteren Versionen
7	v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 und alle späteren Versionen
6	v10.20.0+, v12.17.0+, 14.0.0 und alle späteren Versionen
5	v10.17.0+, v12.11.0+, 13.0.0 und alle späteren Versionen
4	v10.16.0+, v11.8.0+, 12.0.0 und alle späteren Versionen
3	v6.14.2, 8.11.2+, v9.11.0+, 10.0.0 und alle späteren Versionen
2	v8.10.0+, v9.3.0+, 10.0.0 und alle späteren Versionen
1	v8.6.0+*, v9.0.0+, 10.0.0 und alle späteren Versionen

* Node-API war experimentell.

** Node.js 8.0.0 enthielt Node-API als experimentell. Es wurde als Node-API-Version 1 veröffentlicht, entwickelte sich aber bis Node.js 8.6.0 weiter. Die API unterscheidet sich in Versionen vor Node.js 8.6.0. Wir empfehlen Node-API Version 3 oder höher.

Jede für Node-API dokumentierte API hat eine Überschrift mit dem Namen added in:, und stabile APIs haben die zusätzliche Überschrift Node-API Version:. APIs sind direkt verwendbar, wenn eine Node.js-Version verwendet wird, die die in Node-API Version: angegebene Node-API-Version oder höher unterstützt. Wenn eine Node.js-Version verwendet wird, die die aufgeführte Node-API Version: nicht unterstützt, oder wenn keine Node-API Version: aufgeführt ist, ist die API nur verfügbar, wenn #define NAPI_EXPERIMENTAL dem Einschließen von node_api.h oder js_native_api.h vorangestellt wird. Wenn eine API in einer Version von Node.js, die später als die in added in: angegebene ist, nicht verfügbar zu sein scheint, ist dies höchstwahrscheinlich der Grund für das scheinbare Fehlen.

Die Node-APIs, die sich ausschließlich auf den Zugriff auf ECMAScript-Funktionen aus nativem Code beziehen, finden Sie separat in js_native_api.h und js_native_api_types.h. Die in diesen Headerdateien definierten APIs sind in node_api.h und node_api_types.h enthalten. Die Headerdateien sind so strukturiert, um Implementierungen von Node-API außerhalb von Node.js zu ermöglichen. Für diese Implementierungen sind die Node.js-spezifischen APIs möglicherweise nicht anwendbar.

Die Node.js-spezifischen Teile eines Add-ons können vom Code getrennt werden, der die eigentliche Funktionalität der JavaScript-Umgebung verfügbar macht, so dass letztere mit mehreren Implementierungen von Node-API verwendet werden kann. Im folgenden Beispiel verweisen addon.c und addon.h nur auf js_native_api.h. Dies stellt sicher, dass addon.c wiederverwendet werden kann, um entweder gegen die Node.js-Implementierung von Node-API oder jede Implementierung von Node-API außerhalb von Node.js zu kompilieren.

addon_node.c ist eine separate Datei, die den Node.js-spezifischen Einstiegspunkt zum Add-on enthält und das Add-on instanziiert, indem es addon.c aufruft, wenn das Add-on in eine Node.js-Umgebung geladen wird.

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

Umgebungslebenszyklus-APIs

Abschnitt 8.7 hier der ECMAScript-Sprachspezifikation definiert den Begriff "Agent" als eine in sich geschlossene Umgebung, in der JavaScript-Code ausgeführt wird. Mehrere solcher Agents können entweder gleichzeitig oder sequenziell vom Prozess gestartet und beendet werden.

Eine Node.js-Umgebung entspricht einem ECMAScript-Agent. Im Hauptprozess wird beim Start eine Umgebung erstellt, und zusätzliche Umgebungen können in separaten Threads erstellt werden, um als Worker-Threads zu fungieren. Wenn Node.js in eine andere Anwendung eingebettet ist, kann der Hauptthread der Anwendung auch mehrmals während des Lebenszyklus des Anwendungsprozesses eine Node.js-Umgebung erstellen und zerstören, so dass jede von der Anwendung erstellte Node.js-Umgebung wiederum während ihres Lebenszyklus zusätzliche Umgebungen als Worker-Threads erstellen und zerstören kann.

Aus der Sicht eines nativen Addons bedeutet dies, dass die von ihm bereitgestellten Bindungen mehrmals, aus mehreren Kontexten und sogar gleichzeitig von mehreren Threads aufgerufen werden können.

Native Addons müssen möglicherweise einen globalen Zustand zuweisen, den sie während ihres Lebenszyklus einer Node.js-Umgebung verwenden, so dass der Zustand für jede Instanz des Addons eindeutig sein kann.

Zu diesem Zweck bietet Node-API eine Möglichkeit, Daten zu assoziieren, so dass ihr Lebenszyklus an den Lebenszyklus einer Node.js-Umgebung gebunden ist.

`napi_set_instance_data`

Hinzugefügt in: v12.8.0, v10.20.0

N-API-Version: 6

napi_status napi_set_instance_data(node_api_basic_env env,
                                   void* data,
                                   napi_finalize finalize_cb,
                                   void* finalize_hint);

[in] env: Die Umgebung, unter der der Node-API-Aufruf aufgerufen wird.
[in] data: Das Datenelement, das den Bindungen dieser Instanz zur Verfügung gestellt werden soll.
[in] finalize_cb: Die Funktion, die aufgerufen wird, wenn die Umgebung abgebaut wird. Die Funktion empfängt data, damit sie es freigeben kann. napi_finalize bietet weitere Details.
[in] finalize_hint: Optionaler Hinweis, der während der Sammlung an den Finalisierung-Callback übergeben wird.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API assoziiert data mit der aktuell laufenden Node.js-Umgebung. data kann später mit napi_get_instance_data() abgerufen werden. Alle vorhandenen Daten, die mit der aktuell laufenden Node.js-Umgebung assoziiert sind und durch einen vorherigen Aufruf von napi_set_instance_data() gesetzt wurden, werden überschrieben. Wenn ein finalize_cb durch den vorherigen Aufruf bereitgestellt wurde, wird er nicht aufgerufen.

`napi_get_instance_data`

Hinzugefügt in: v12.8.0, v10.20.0

N-API-Version: 6

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[out] data: Der Datenelement, der zuvor mit der aktuell laufenden Node.js-Umgebung durch einen Aufruf von napi_set_instance_data() verknüpft wurde.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API ruft Daten ab, die zuvor über napi_set_instance_data() mit der aktuell laufenden Node.js-Umgebung verknüpft wurden. Wenn keine Daten gesetzt sind, ist der Aufruf erfolgreich und data wird auf NULL gesetzt.

Grundlegende Node-API-Datentypen

Node-API stellt die folgenden grundlegenden Datentypen als Abstraktionen bereit, die von den verschiedenen APIs verwendet werden. Diese APIs sollten als opak behandelt werden und nur mit anderen Node-API-Aufrufen inspizierbar sein.

`napi_status`

Hinzugefügt in: v8.0.0

N-API-Version: 1

Ganzzahliger Statuscode, der den Erfolg oder Misserfolg eines Node-API-Aufrufs anzeigt. Derzeit werden die folgenden Statuscodes unterstützt.

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;

Wenn nach der Rückgabe eines fehlgeschlagenen Status durch eine API zusätzliche Informationen benötigt werden, können diese durch Aufrufen von napi_get_last_error_info abgerufen werden.

`napi_extended_error_info`

Hinzugefügt in: v8.0.0

N-API-Version: 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: UTF8-codierte Zeichenkette, die eine VM-neutrale Beschreibung des Fehlers enthält.
engine_reserved: Reserviert für VM-spezifische Fehlerdetails. Dies ist derzeit für keine VM implementiert.
engine_error_code: VM-spezifischer Fehlercode. Dies ist derzeit für keine VM implementiert.
error_code: Der Node-API-Statuscode, der mit dem letzten Fehler entstanden ist.

Siehe den Abschnitt Fehlerbehandlung für weitere Informationen.

`napi_env`

napi_env repräsentiert einen Kontext, den die zugrunde liegende Node-API-Implementierung verwenden kann, um VM-spezifischen Zustand persistent zu speichern. Diese Struktur wird an native Funktionen übergeben, wenn diese aufgerufen werden, und muss bei Aufrufen der Node-API zurückgegeben werden. Insbesondere muss dasselbe napi_env, das beim Aufruf der anfänglichen nativen Funktion übergeben wurde, an alle nachfolgenden, verschachtelten Node-API-Aufrufe übergeben werden. Das Zwischenspeichern von napi_env zum Zweck der allgemeinen Wiederverwendung und das Übergeben von napi_env zwischen Instanzen desselben Add-ons, die auf verschiedenen Worker-Threads laufen, ist nicht zulässig. napi_env wird ungültig, wenn eine Instanz eines nativen Add-ons entladen wird. Eine Benachrichtigung über dieses Ereignis erfolgt über die Callbacks, die an napi_add_env_cleanup_hook und napi_set_instance_data übergeben werden.

`node_api_basic_env`

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Diese Variante von napi_env wird an synchrone Finalizer (node_api_basic_finalize) übergeben. Es gibt eine Teilmenge von Node-APIs, die einen Parameter vom Typ node_api_basic_env als erstes Argument akzeptieren. Diese APIs greifen nicht auf den Zustand der JavaScript-Engine zu und können daher sicher aus synchronen Finalizern aufgerufen werden. Die Übergabe eines Parameters vom Typ napi_env an diese APIs ist zulässig, die Übergabe eines Parameters vom Typ node_api_basic_env an APIs, die auf den Zustand der JavaScript-Engine zugreifen, ist jedoch nicht zulässig. Der Versuch, dies ohne Cast durchzuführen, führt zu einer Compilerwarnung oder einem Fehler, wenn Add-ons mit Flags kompiliert werden, die dazu führen, dass sie Warnungen und/oder Fehler ausgeben, wenn falsche Zeigertypen an eine Funktion übergeben werden. Der Aufruf solcher APIs aus einem synchronen Finalizer führt letztendlich zur Beendigung der Anwendung.

`napi_value`

Dies ist ein opaker Zeiger, der verwendet wird, um einen JavaScript-Wert darzustellen.

`napi_threadsafe_function`

Hinzugefügt in: v10.6.0

N-API Version: 4

Dies ist ein undurchsichtiger Zeiger, der eine JavaScript-Funktion repräsentiert, die asynchron über napi_call_threadsafe_function() von mehreren Threads aufgerufen werden kann.

`napi_threadsafe_function_release_mode`

Hinzugefügt in: v10.6.0

N-API Version: 4

Ein Wert, der an napi_release_threadsafe_function() übergeben wird, um anzugeben, ob die threadsichere Funktion sofort geschlossen (napi_tsfn_abort) oder lediglich freigegeben (napi_tsfn_release) und somit für die spätere Verwendung über napi_acquire_threadsafe_function() und napi_call_threadsafe_function() verfügbar sein soll.

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

`napi_threadsafe_function_call_mode`

Hinzugefügt in: v10.6.0

N-API Version: 4

Ein Wert, der an napi_call_threadsafe_function() übergeben wird, um anzugeben, ob der Aufruf blockieren soll, wenn die mit der threadsicheren Funktion verknüpfte Warteschlange voll ist.

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

Node-API Speicherverwaltungstypen

`napi_handle_scope`

Dies ist eine Abstraktion zur Steuerung und Modifizierung der Lebensdauer von Objekten, die innerhalb eines bestimmten Bereichs erstellt werden. Im Allgemeinen werden Node-API-Werte im Kontext eines Handle-Bereichs erstellt. Wenn eine native Methode von JavaScript aufgerufen wird, existiert ein Standard-Handle-Bereich. Wenn der Benutzer keinen neuen Handle-Bereich explizit erstellt, werden Node-API-Werte im Standard-Handle-Bereich erstellt. Für alle Aufrufe von Code außerhalb der Ausführung einer nativen Methode (z. B. während eines libuv-Callback-Aufrufs) muss das Modul einen Bereich erstellen, bevor es Funktionen aufruft, die zur Erstellung von JavaScript-Werten führen können.

Handle-Bereiche werden mit napi_open_handle_scope erstellt und mit napi_close_handle_scope zerstört. Das Schließen des Bereichs kann dem GC signalisieren, dass alle napi_values, die während der Lebensdauer des Handle-Bereichs erstellt wurden, nicht mehr vom aktuellen Stack-Frame referenziert werden.

Weitere Informationen finden Sie unter Objekt-Lebensdauerverwaltung.

`napi_escapable_handle_scope`

Hinzugefügt in: v8.0.0

N-API-Version: 1

Escapable Handle Scopes sind eine spezielle Art von Handle Scope, um Werte, die innerhalb eines bestimmten Handle Scopes erstellt wurden, an einen übergeordneten Scope zurückzugeben.

`napi_ref`

Hinzugefügt in: v8.0.0

N-API-Version: 1

Dies ist die Abstraktion, die verwendet wird, um auf einen napi_value zu verweisen. Dies ermöglicht es Benutzern, die Lebensdauer von JavaScript-Werten zu verwalten, einschließlich der expliziten Definition ihrer minimalen Lebensdauer.

Weitere Details finden Sie unter Objekt-Lebenszyklusverwaltung.

`napi_type_tag`

Hinzugefügt in: v14.8.0, v12.19.0

N-API-Version: 8

Ein 128-Bit-Wert, der als zwei vorzeichenlose 64-Bit-Ganzzahlen gespeichert wird. Er dient als UUID, mit der JavaScript-Objekte oder Externals "getaggt" werden können, um sicherzustellen, dass sie einen bestimmten Typ haben. Dies ist eine stärkere Prüfung als napi_instanceof, da letztere einen falsch positiven Wert melden kann, wenn der Prototyp des Objekts manipuliert wurde. Die Typ-Tagging ist besonders nützlich in Verbindung mit napi_wrap, da sie sicherstellt, dass der von einem gekapselten Objekt abgerufene Zeiger sicher in den nativen Typ umgewandelt werden kann, der dem Typ-Tag entspricht, das zuvor auf das JavaScript-Objekt angewendet wurde.

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

`napi_async_cleanup_hook_handle`

Hinzugefügt in: v14.10.0, v12.19.0

Ein undurchsichtiger Wert, der von napi_add_async_cleanup_hook zurückgegeben wird. Er muss an napi_remove_async_cleanup_hook übergeben werden, wenn die Kette asynchroner Bereinigungsereignisse abgeschlossen ist.

Node-API-Rückruffunktionstypen

`napi_callback_info`

Hinzugefügt in: v8.0.0

N-API-Version: 1

Undurchsichtiger Datentyp, der an eine Rückruffunktion übergeben wird. Er kann verwendet werden, um zusätzliche Informationen über den Kontext zu erhalten, in dem die Rückruffunktion aufgerufen wurde.

`napi_callback`

Hinzugefügt in: v8.0.0

N-API-Version: 1

Funktionszeigertyp für vom Benutzer bereitgestellte native Funktionen, die über Node-API für JavaScript verfügbar gemacht werden sollen. Rückruffunktionen sollten die folgende Signatur erfüllen:

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

Sofern nicht aus Gründen, die in Objekt-Lebenszyklusverwaltung erläutert werden, ist das Erstellen eines Handle- und/oder Callback-Scopes innerhalb eines napi_callback nicht erforderlich.

`node_api_basic_finalize`

Hinzugefügt in: v21.6.0, v20.12.0, v18.20.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Funktionszeigertyp für vom Add-on bereitgestellte Funktionen, die es dem Benutzer ermöglichen, benachrichtigt zu werden, wenn extern verwaltete Daten bereinigt werden können, weil das Objekt, dem sie zugeordnet waren, garbage-collected wurde. Der Benutzer muss eine Funktion mit der folgenden Signatur bereitstellen, die beim Sammeln des Objekts aufgerufen wird. Derzeit kann node_api_basic_finalize verwendet werden, um herauszufinden, wann Objekte mit externen Daten gesammelt werden.

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

Sofern nicht aus den in Object Lifetime Management beschriebenen Gründen, ist die Erstellung eines Handles und/oder Callback-Bereichs innerhalb des Funktionskörpers nicht notwendig.

Da diese Funktionen aufgerufen werden können, während sich die JavaScript-Engine in einem Zustand befindet, in dem sie keinen JavaScript-Code ausführen kann, dürfen nur Node-APIs aufgerufen werden, die ein node_api_basic_env als ersten Parameter akzeptieren. node_api_post_finalizer kann verwendet werden, um Node-API-Aufrufe zu planen, die Zugriff auf den Zustand der JavaScript-Engine benötigen, um nach Abschluss des aktuellen Garbage-Collection-Zyklus ausgeführt zu werden.

Im Fall von node_api_create_external_string_latin1 und node_api_create_external_string_utf16 kann der Parameter env null sein, da externe Strings während des späteren Teils des Umgebungs-Shutdowns gesammelt werden können.

Änderungsverlauf:

experimentell (NAPI_EXPERIMENTAL): Es dürfen nur Node-API-Aufrufe aufgerufen werden, die ein node_api_basic_env als ersten Parameter akzeptieren; andernfalls wird die Anwendung mit einer entsprechenden Fehlermeldung beendet. Diese Funktion kann durch Definieren von NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT deaktiviert werden.

`napi_finalize`

Hinzugefügt in: v8.0.0

N-API Version: 1

Funktionszeigertyp für vom Add-on bereitgestellte Funktionen, die es dem Benutzer ermöglichen, eine Gruppe von Aufrufen an Node-APIs als Antwort auf ein Garbage-Collection-Ereignis zu planen, nachdem der Garbage-Collection-Zyklus abgeschlossen ist. Diese Funktionszeiger können mit node_api_post_finalizer verwendet werden.

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

Änderungsverlauf:

experimentell (NAPI_EXPERIMENTAL ist definiert): Eine Funktion dieses Typs darf nicht mehr als Finalizer verwendet werden, außer mit node_api_post_finalizer. node_api_basic_finalize muss stattdessen verwendet werden. Diese Funktion kann durch Definieren von NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT deaktiviert werden.

`napi_async_execute_callback`

Hinzugefügt in: v8.0.0

N-API Version: 1

Funktionszeiger, der mit Funktionen verwendet wird, die asynchrone Operationen unterstützen. Callback-Funktionen müssen die folgende Signatur erfüllen:

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

Implementierungen dieser Funktion müssen vermeiden, Node-API-Aufrufe zu tätigen, die JavaScript ausführen oder mit JavaScript-Objekten interagieren. Node-API-Aufrufe sollten stattdessen in napi_async_complete_callback erfolgen. Verwenden Sie den Parameter napi_env nicht, da dies wahrscheinlich zur Ausführung von JavaScript führt.

`napi_async_complete_callback`

Hinzugefügt in: v8.0.0

N-API Version: 1

Funktionszeiger, der mit Funktionen verwendet wird, die asynchrone Operationen unterstützen. Callback-Funktionen müssen die folgende Signatur erfüllen:

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

Sofern nicht aus den in Object Lifetime Management beschriebenen Gründen, ist das Erstellen eines Handles und/oder Callback-Scopes innerhalb des Funktionskörpers nicht notwendig.

`napi_threadsafe_function_call_js`

Hinzugefügt in: v10.6.0

N-API-Version: 4

Funktionszeiger, der mit asynchronen threadsicheren Funktionsaufrufen verwendet wird. Der Rückruf wird im Hauptthread aufgerufen. Sein Zweck ist es, ein über die Queue von einem der sekundären Threads ankommendes Datenelement zu verwenden, um die für einen Aufruf in JavaScript, normalerweise über napi_call_function, notwendigen Parameter zu konstruieren und dann den Aufruf in JavaScript durchzuführen.

Die vom sekundären Thread über die Queue ankommenden Daten werden im Parameter data übergeben, und die aufzurufende JavaScript-Funktion wird im Parameter js_callback übergeben.

Node-API richtet die Umgebung vor dem Aufruf dieses Rückrufs ein, daher ist es ausreichend, die JavaScript-Funktion über napi_call_function anstelle von napi_make_callback aufzurufen.

Rückruffunktionen müssen die folgende Signatur erfüllen:

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

[in] env: Die für API-Aufrufe zu verwendende Umgebung oder NULL, wenn die threadsichere Funktion abgebaut wird und data möglicherweise freigegeben werden muss.
[in] js_callback: Die aufzurufende JavaScript-Funktion oder NULL, wenn die threadsichere Funktion abgebaut wird und data möglicherweise freigegeben werden muss. Sie kann auch NULL sein, wenn die threadsichere Funktion ohne js_callback erstellt wurde.
[in] context: Die optionalen Daten, mit denen die threadsichere Funktion erstellt wurde.
[in] data: Vom sekundären Thread erstellte Daten. Es liegt in der Verantwortung des Rückrufs, diese nativen Daten in JavaScript-Werte (mit Node-API-Funktionen) umzuwandeln, die als Parameter übergeben werden können, wenn js_callback aufgerufen wird. Dieser Zeiger wird vollständig von den Threads und diesem Rückruf verwaltet. Daher sollte dieser Rückruf die Daten freigeben.

Sofern nicht aus den in Lebenszyklusverwaltung von Objekten beschriebenen Gründen, ist das Erstellen eines Handles und/oder Callback-Bereichs innerhalb des Funktionskörpers nicht notwendig.

`napi_cleanup_hook`

Hinzugefügt in: v19.2.0, v18.13.0

N-API-Version: 3

Funktionszeiger, der mit napi_add_env_cleanup_hook verwendet wird. Er wird aufgerufen, wenn die Umgebung abgebaut wird.

Rückruffunktionen müssen die folgende Signatur erfüllen:

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

[in] data: Die Daten, die an napi_add_env_cleanup_hook übergeben wurden.

`napi_async_cleanup_hook`

Hinzugefügt in: v14.10.0, v12.19.0

Funktionszeiger, der mit napi_add_async_cleanup_hook verwendet wird. Er wird aufgerufen, wenn die Umgebung abgebaut wird.

Rückruffunktionen müssen die folgende Signatur erfüllen:

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

[in] handle: Der Handle, der nach Abschluss der asynchronen Bereinigung an napi_remove_async_cleanup_hook übergeben werden muss.
[in] data: Die Daten, die an napi_add_async_cleanup_hook übergeben wurden.

Der Funktionskörper sollte die asynchronen Bereinigungsaktionen initiieren, an deren Ende handle in einem Aufruf an napi_remove_async_cleanup_hook übergeben werden muss.

Fehlerbehandlung

Node-API verwendet sowohl Rückgabewerte als auch JavaScript-Ausnahmen für die Fehlerbehandlung. Die folgenden Abschnitte erläutern den Ansatz für jeden Fall.

Rückgabewerte

Alle Node-API-Funktionen teilen das gleiche Fehlerbehandlungsmuster. Der Rückgabetyp aller API-Funktionen ist napi_status.

Der Rückgabewert ist napi_ok, wenn die Anfrage erfolgreich war und keine unaufgefangene JavaScript-Ausnahme ausgelöst wurde. Wenn ein Fehler aufgetreten ist UND eine Ausnahme ausgelöst wurde, wird der napi_status-Wert für den Fehler zurückgegeben. Wenn eine Ausnahme ausgelöst wurde und kein Fehler aufgetreten ist, wird napi_pending_exception zurückgegeben.

In Fällen, in denen ein anderer Rückgabewert als napi_ok oder napi_pending_exception zurückgegeben wird, muss napi_is_exception_pending aufgerufen werden, um zu prüfen, ob eine Ausnahme aussteht. Weitere Einzelheiten finden Sie im Abschnitt über Ausnahmen.

Der vollständige Satz möglicher napi_status-Werte ist in napi_api_types.h definiert.

Der napi_status-Rückgabewert bietet eine VM-unabhängige Darstellung des aufgetretenen Fehlers. In einigen Fällen ist es nützlich, detailliertere Informationen zu erhalten, einschließlich einer Zeichenkette, die den Fehler darstellt, sowie VM (Engine)-spezifische Informationen.

Um diese Informationen abzurufen, wird napi_get_last_error_info bereitgestellt, das eine Struktur napi_extended_error_info zurückgibt. Das Format der Struktur napi_extended_error_info ist wie folgt:

Hinzugefügt in: v8.0.0

N-API-Version: 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: Textuelle Darstellung des aufgetretenen Fehlers.
engine_reserved: Opak handle, reserviert für die Engine-Nutzung.
engine_error_code: VM-spezifischer Fehlercode.
error_code: Node-API-Statuscode für den letzten Fehler.

napi_get_last_error_info gibt die Informationen für den letzten Node-API-Aufruf zurück, der durchgeführt wurde.

Verlassen Sie sich nicht auf den Inhalt oder das Format der erweiterten Informationen, da diese nicht SemVer unterliegen und sich jederzeit ändern können. Sie sind nur für Protokollierungszwecke vorgesehen.

`napi_get_last_error_info`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: Die napi_extended_error_info-Struktur mit weiteren Informationen zum Fehler.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API ruft eine napi_extended_error_info-Struktur mit Informationen zum zuletzt aufgetretenen Fehler ab.

Der Inhalt der zurückgegebenen napi_extended_error_info ist nur gültig, bis eine Node-API-Funktion in derselben env aufgerufen wird. Dies beinhaltet einen Aufruf von napi_is_exception_pending, daher ist es oft notwendig, eine Kopie der Informationen zu erstellen, damit sie später verwendet werden können. Der in error_message zurückgegebene Zeiger verweist auf eine statisch definierte Zeichenkette, daher ist es sicher, diesen Zeiger zu verwenden, wenn Sie ihn aus dem Feld error_message kopiert haben (das überschrieben wird), bevor eine weitere Node-API-Funktion aufgerufen wurde.

Verlassen Sie sich nicht auf den Inhalt oder das Format der erweiterten Informationen, da diese keiner SemVer-Version unterliegen und sich jederzeit ändern können. Sie sind nur für Protokollierungszwecke vorgesehen.

Diese API kann aufgerufen werden, selbst wenn eine ausstehende JavaScript-Exception vorliegt.

Ausnahmen

Jeder Node-API-Funktionsaufruf kann zu einer ausstehenden JavaScript-Exception führen. Dies gilt für alle API-Funktionen, auch für solche, die möglicherweise keine Ausführung von JavaScript verursachen.

Wenn der von einer Funktion zurückgegebene napi_status napi_ok ist, dann ist keine Ausnahme ausstehend und keine zusätzliche Aktion erforderlich. Wenn der zurückgegebene napi_status etwas anderes als napi_ok oder napi_pending_exception ist, muss napi_is_exception_pending aufgerufen werden, um festzustellen, ob eine Ausnahme aussteht oder nicht, um zu versuchen, sich zu erholen und fortzufahren, anstatt einfach sofort zurückzukehren.

In vielen Fällen, wenn eine Node-API-Funktion aufgerufen wird und bereits eine Ausnahme aussteht, gibt die Funktion sofort mit einem napi_status von napi_pending_exception zurück. Dies ist jedoch nicht bei allen Funktionen der Fall. Node-API erlaubt es, eine Teilmenge der Funktionen aufzurufen, um eine minimale Bereinigung zu ermöglichen, bevor an JavaScript zurückgegeben wird. In diesem Fall spiegelt napi_status den Status der Funktion wider. Ausstehende Ausnahmen werden nicht widergespiegelt. Um Verwirrung zu vermeiden, überprüfen Sie den Fehlerstatus nach jedem Funktionsaufruf.

Wenn eine Ausnahme aussteht, können zwei Ansätze angewendet werden.

Der erste Ansatz besteht darin, alle entsprechenden Bereinigungen durchzuführen und dann zurückzukehren, damit die Ausführung an JavaScript zurückgegeben wird. Als Teil des Übergangs zurück zu JavaScript wird die Ausnahme an der Stelle im JavaScript-Code ausgelöst, an der die native Methode aufgerufen wurde. Das Verhalten der meisten Node-API-Aufrufe ist nicht spezifiziert, während eine Ausnahme aussteht, und viele geben einfach napi_pending_exception zurück. Daher sollte so wenig wie möglich getan und dann zu JavaScript zurückgekehrt werden, wo die Ausnahme behandelt werden kann.

Der zweite Ansatz besteht darin, zu versuchen, die Ausnahme zu behandeln. Es wird Fälle geben, in denen der native Code die Ausnahme abfangen, die entsprechende Aktion durchführen und dann fortfahren kann. Dies wird nur in bestimmten Fällen empfohlen, in denen bekannt ist, dass die Ausnahme sicher behandelt werden kann. In diesen Fällen kann napi_get_and_clear_last_exception verwendet werden, um die Ausnahme abzurufen und zu löschen. Bei Erfolg enthält result das Handle zum zuletzt geworfenen JavaScript Object. Wenn festgestellt wird, dass die Ausnahme nach dem Abrufen nicht behandelt werden kann, kann sie mit napi_throw erneut ausgelöst werden, wobei error der auszulösende JavaScript-Wert ist.

Die folgenden Hilfsfunktionen sind ebenfalls verfügbar, falls nativer Code eine Ausnahme auslösen oder feststellen muss, ob ein napi_value eine Instanz eines JavaScript Error-Objekts ist: napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error und napi_is_error.

Die folgenden Hilfsfunktionen sind auch verfügbar, falls nativer Code ein Error-Objekt erstellen muss: napi_create_error, napi_create_type_error, napi_create_range_error und node_api_create_syntax_error, wobei result der napi_value ist, der auf das neu erstellte JavaScript Error-Objekt verweist.

Das Node.js-Projekt fügt allen intern generierten Fehlern Fehlercodes hinzu. Das Ziel ist, dass Anwendungen diese Fehlercodes für alle Fehlerprüfungen verwenden. Die zugehörigen Fehlermeldungen bleiben erhalten, sind aber nur für die Protokollierung und Anzeige gedacht, wobei davon ausgegangen wird, dass sich die Meldung ohne Anwendung von SemVer ändern kann. Um dieses Modell mit Node-API zu unterstützen, sowohl in der internen Funktionalität als auch für modul-spezifische Funktionalität (da dies eine gute Praxis ist), nehmen die Funktionen throw_ und create_ einen optionalen Code-Parameter entgegen, der die Zeichenkette für den Code ist, der dem Fehlerobjekt hinzugefügt werden soll. Wenn der optionale Parameter NULL ist, wird dem Fehler kein Code zugeordnet. Wenn ein Code angegeben wird, wird der Name, der dem Fehler zugeordnet ist, auch aktualisiert zu:

text

originalName [code]

wobei originalName der ursprüngliche Name ist, der dem Fehler zugeordnet ist, und code der angegebene Code ist. Wenn der Code beispielsweise 'ERR_ERROR_1' ist und ein TypeError erstellt wird, lautet der Name:

text

TypeError [ERR_ERROR_1]

`napi_throw`

Hinzugefügt in: v8.0.0

N-API Version: 1

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] error: Der zu werfende JavaScript-Wert.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wirft den bereitgestellten JavaScript-Wert.

`napi_throw_error`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] code: Optionaler Fehlercode, der für den Fehler gesetzt werden soll.
[in] msg: C-String, der den mit dem Fehler zu verknüpfenden Text darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wirft einen JavaScript Error mit dem bereitgestellten Text.

`napi_throw_type_error`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] code: Optionaler Fehlercode, der für den Fehler gesetzt werden soll.
[in] msg: C-String, der den mit dem Fehler zu verknüpfenden Text darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wirft einen JavaScript TypeError mit dem bereitgestellten Text.

`napi_throw_range_error`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] code: Optionaler Fehlercode, der für den Fehler gesetzt werden soll.
[in] msg: C-String, der den mit dem Fehler zu verknüpfenden Text darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wirft einen JavaScript RangeError mit dem bereitgestellten Text.

`node_api_throw_syntax_error`

Hinzugefügt in: v17.2.0, v16.14.0

N-API Version: 9

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] code: Optionaler Fehlercode, der im Fehler gesetzt werden soll.
[in] msg: C-String, der den mit dem Fehler verknüpften Text darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API löst einen JavaScript SyntaxError mit dem bereitgestellten Text aus.

`napi_is_error`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu überprüfende napi_value.
[out] result: Boolean-Wert, der auf true gesetzt wird, wenn napi_value einen Fehler darstellt, andernfalls false.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API fragt einen napi_value ab, um zu überprüfen, ob er ein Fehlerobjekt darstellt.

`napi_create_error`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] code: Optionaler napi_value mit dem String für den Fehlercode, der dem Fehler zugeordnet werden soll.
[in] msg: napi_value, der auf einen JavaScript-string verweist, der als Meldung für den Error verwendet werden soll.
[out] result: napi_value, der den erstellten Fehler darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt einen JavaScript Error mit dem bereitgestellten Text zurück.

`napi_create_type_error`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] code: Optionaler napi_value mit dem String für den Fehlercode, der dem Fehler zugeordnet werden soll.
[in] msg: napi_value, der auf einen JavaScript-string verweist, der als Meldung für den Error verwendet werden soll.
[out] result: napi_value, der den erstellten Fehler darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt einen JavaScript TypeError mit dem bereitgestellten Text zurück.

`napi_create_range_error`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] code: Optionaler napi_value mit dem String für den Fehlercode, der dem Fehler zugeordnet werden soll.
[in] msg: napi_value, der auf einen JavaScript-string verweist, der als Nachricht für den Error verwendet werden soll.
[out] result: napi_value, der den erstellten Fehler darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt einen JavaScript RangeError mit dem angegebenen Text zurück.

`node_api_create_syntax_error`

Hinzugefügt in: v17.2.0, v16.14.0

N-API Version: 9

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] code: Optionaler napi_value mit dem String für den Fehlercode, der dem Fehler zugeordnet werden soll.
[in] msg: napi_value, der auf einen JavaScript-string verweist, der als Nachricht für den Error verwendet werden soll.
[out] result: napi_value, der den erstellten Fehler darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt einen JavaScript SyntaxError mit dem angegebenen Text zurück.

`napi_get_and_clear_last_exception`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: Die Ausnahme, falls eine aussteht, andernfalls NULL.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API kann auch dann aufgerufen werden, wenn eine JavaScript-Ausnahme aussteht.

`napi_is_exception_pending`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_is_exception_pending(napi_env env, bool* result);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: Boolescher Wert, der auf true gesetzt wird, wenn eine Ausnahme aussteht.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API kann aufgerufen werden, selbst wenn eine ausstehende JavaScript-Ausnahme vorhanden ist.

`napi_fatal_exception`

Hinzugefügt in: v9.10.0

N-API Version: 3

napi_status napi_fatal_exception(napi_env env, napi_value err);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] err: Der Fehler, der an 'uncaughtException' übergeben wird.

Lößt eine 'uncaughtException' in JavaScript aus. Nützlich, wenn ein asynchroner Rückruf eine Ausnahme auslöst, ohne dass eine Möglichkeit zur Wiederherstellung besteht.

Fatale Fehler

Im Falle eines nicht wiederherstellbaren Fehlers in einem nativen Addon kann ein fataler Fehler ausgelöst werden, um den Prozess sofort zu beenden.

`napi_fatal_error`

Hinzugefügt in: v8.2.0

N-API Version: 1

NAPI_NO_RETURN void napi_fatal_error(const char* location,
                                     size_t location_len,
                                     const char* message,
                                     size_t message_len);

[in] location: Optionale Position, an der der Fehler aufgetreten ist.
[in] location_len: Die Länge der Position in Bytes oder NAPI_AUTO_LENGTH, wenn sie null-terminiert ist.
[in] message: Die dem Fehler zugeordnete Nachricht.
[in] message_len: Die Länge der Nachricht in Bytes oder NAPI_AUTO_LENGTH, wenn sie null-terminiert ist.

Der Funktionsaufruf gibt nicht zurück, der Prozess wird beendet.

Diese API kann aufgerufen werden, selbst wenn eine ausstehende JavaScript-Ausnahme vorhanden ist.

Objekt-Lebenszyklusverwaltung

Wenn Node-API-Aufrufe getätigt werden, können Handles für Objekte im Heap der zugrunde liegenden VM als napi_values zurückgegeben werden. Diese Handles müssen die Objekte „am Leben“ halten, bis sie vom nativen Code nicht mehr benötigt werden, da sonst die Objekte gesammelt werden könnten, bevor der native Code mit ihrer Verwendung fertig ist.

Wenn Objekthandles zurückgegeben werden, werden sie einem „Scope“ zugeordnet. Die Lebensdauer des Standardscopes ist an die Lebensdauer des nativen Methodenaufrufs gebunden. Das Ergebnis ist, dass Handles standardmäßig gültig bleiben und die diesen Handles zugeordneten Objekte für die Lebensdauer des nativen Methodenaufrufs am Leben gehalten werden.

In vielen Fällen ist es jedoch notwendig, dass die Handles entweder für eine kürzere oder längere Lebensdauer als die der nativen Methode gültig bleiben. In den folgenden Abschnitten werden die Node-API-Funktionen beschrieben, mit denen die Lebensdauer des Handles vom Standardwert geändert werden kann.

Verkürzung der Lebensdauer von Handles im Vergleich zur nativen Methode

Oft ist es notwendig, die Lebensdauer von Handles kürzer zu gestalten als die Lebensdauer einer nativen Methode. Betrachten Sie beispielsweise eine native Methode mit einer Schleife, die die Elemente in einem großen Array durchläuft:

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;
  }
  // etwas mit dem Element tun
}

Dies würde zu einer großen Anzahl erstellter Handles führen und erhebliche Ressourcen verbrauchen. Obwohl der native Code nur das aktuellste Handle verwenden könnte, würden auch alle zugehörigen Objekte am Leben gehalten, da sie denselben Gültigkeitsbereich teilen.

Um dies zu behandeln, bietet Node-API die Möglichkeit, einen neuen „Scope“ zu erstellen, dem neu erstellte Handles zugeordnet werden. Sobald diese Handles nicht mehr benötigt werden, kann der Scope „geschlossen“ werden und alle dem Scope zugeordneten Handles werden ungültig. Die Methoden zum Öffnen/Schließen von Scopes sind napi_open_handle_scope und napi_close_handle_scope.

Node-API unterstützt nur eine einzige verschachtelte Hierarchie von Scopes. Es gibt jederzeit nur einen aktiven Scope, und alle neuen Handles werden diesem Scope zugeordnet, solange er aktiv ist. Scopes müssen in umgekehrter Reihenfolge geschlossen werden, als sie geöffnet wurden. Darüber hinaus müssen alle innerhalb einer nativen Methode erstellten Scopes geschlossen werden, bevor von dieser Methode zurückgegeben wird.

Im vorherigen Beispiel würde das Hinzufügen von Aufrufen von napi_open_handle_scope und napi_close_handle_scope sicherstellen, dass während der Ausführung der Schleife maximal ein Handle gültig ist:

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;
  }
  // etwas mit dem Element tun
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
}

Beim Verschachteln von Scopes gibt es Fälle, in denen ein Handle aus einem inneren Scope über die Lebensdauer dieses Scopes hinaus existieren muss. Node-API unterstützt einen „escapable scope“, um dies zu ermöglichen. Ein escapable scope erlaubt es, ein Handle zu „fördern“, so dass es dem aktuellen Scope „entkommt“ und die Lebensdauer des Handles sich vom aktuellen Scope auf den äußeren Scope ändert.

Die Methoden zum Öffnen/Schließen von escapable Scopes sind napi_open_escapable_handle_scope und napi_close_escapable_handle_scope.

Die Anforderung zum Fördern eines Handles erfolgt über napi_escape_handle, das nur einmal aufgerufen werden kann.

`napi_open_handle_scope`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: napi_value, das den neuen Scope darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API öffnet einen neuen Scope.

`napi_close_handle_scope`

Hinzugefügt in: v8.0.0

N-API Version: 1

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] scope: napi_value, das den zu schließenden Scope darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API schließt den übergebenen Scope. Scopes müssen in umgekehrter Reihenfolge ihrer Erstellung geschlossen werden.

Diese API kann auch dann aufgerufen werden, wenn eine ausstehende JavaScript-Ausnahme vorliegt.

`napi_open_escapable_handle_scope`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: napi_value, das den neuen Scope darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API öffnet einen neuen Scope, von dem ein Objekt in den äußeren Scope befördert werden kann.

`napi_close_escapable_handle_scope`

Hinzugefügt in: v8.0.0

N-API Version: 1

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] scope: napi_value, das den zu schließenden Scope darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API schließt den übergebenen Scope. Scopes müssen in umgekehrter Reihenfolge ihrer Erstellung geschlossen werden.

Diese API kann auch dann aufgerufen werden, wenn eine ausstehende JavaScript-Ausnahme vorliegt.

`napi_escape_handle`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] scope: napi_value, die den aktuellen Scope darstellt.
[in] escapee: napi_value, die das zu escapende JavaScript-Object darstellt.
[out] result: napi_value, die den Handle zum escaped Object im äußeren Scope darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API hebt den Handle zum JavaScript-Objekt so hervor, dass er für die Lebensdauer des äußeren Scopes gültig ist. Sie kann nur einmal pro Scope aufgerufen werden. Wenn sie mehr als einmal aufgerufen wird, wird ein Fehler zurückgegeben.

Diese API kann auch aufgerufen werden, wenn eine ausstehende JavaScript-Ausnahme vorliegt.

Referenzen auf Werte mit einer längeren Lebensdauer als die der nativen Methode

In einigen Fällen muss ein Addon Werte erstellen und referenzieren können, deren Lebensdauer länger ist als die eines einzelnen nativen Methodenaufrufs. Um beispielsweise einen Konstruktor zu erstellen und diesen später in einer Anfrage zur Erstellung von Instanzen zu verwenden, muss es möglich sein, auf das Konstruktorobjekt über viele verschiedene Instanzerstellungsanforderungen hinweg zu verweisen. Dies wäre mit einem normalen Handle, das als napi_value zurückgegeben wird, wie im vorherigen Abschnitt beschrieben, nicht möglich. Die Lebensdauer eines normalen Handles wird durch Scopes verwaltet, und alle Scopes müssen vor dem Ende einer nativen Methode geschlossen werden.

Node-API bietet Methoden zum Erstellen persistenter Referenzen auf Werte. Derzeit erlaubt Node-API nur das Erstellen von Referenzen für eine begrenzte Anzahl von Werttypen, darunter Objekt, extern, Funktion und Symbol.

Jede Referenz hat eine zugehörige Anzahl mit einem Wert von 0 oder höher, der bestimmt, ob die Referenz den entsprechenden Wert am Leben erhält. Referenzen mit einer Anzahl von 0 verhindern nicht, dass Werte gesammelt werden. Werte der Typen Objekt (Objekt, Funktion, extern) und Symbol werden zu „schwachen“ Referenzen und können weiterhin zugegriffen werden, solange sie nicht gesammelt werden. Jede Anzahl größer als 0 verhindert, dass die Werte gesammelt werden.

Symbolwerte haben verschiedene Ausprägungen. Das Verhalten einer echten schwachen Referenz wird nur von lokalen Symbolen unterstützt, die mit der Funktion napi_create_symbol oder den Aufrufen des JavaScript-Symbol()-Konstruktors erstellt wurden. Global registrierte Symbole, die mit der Funktion node_api_symbol_for oder den Aufrufen der JavaScript-Symbol.for()-Funktion erstellt wurden, bleiben immer starke Referenzen, da der Garbage Collector sie nicht sammelt. Das gleiche gilt für bekannte Symbole wie Symbol.iterator. Sie werden ebenfalls niemals vom Garbage Collector gesammelt.

Referenzen können mit einer anfänglichen Referenzzählung erstellt werden. Die Zählung kann dann durch napi_reference_ref und napi_reference_unref geändert werden. Wenn ein Objekt gesammelt wird, während die Zählung für eine Referenz 0 ist, geben alle nachfolgenden Aufrufe zum Abrufen des Objekts, das der Referenz zugeordnet ist napi_get_reference_value, NULL für den zurückgegebenen napi_value zurück. Ein Versuch, napi_reference_ref für eine Referenz aufzurufen, deren Objekt gesammelt wurde, führt zu einem Fehler.

Referenzen müssen gelöscht werden, sobald sie vom Addon nicht mehr benötigt werden. Wenn eine Referenz gelöscht wird, verhindert sie nicht mehr, dass das entsprechende Objekt gesammelt wird. Das Nichtlöschen einer persistenten Referenz führt zu einem „Speicherleck“, wobei sowohl der native Speicher für die persistente Referenz als auch das entsprechende Objekt auf dem Heap für immer beibehalten werden.

Es können mehrere persistente Referenzen erstellt werden, die auf dasselbe Objekt verweisen, von denen jede das Objekt entweder am Leben erhält oder nicht, abhängig von ihrer individuellen Zählung. Mehrere persistente Referenzen auf dasselbe Objekt können dazu führen, dass nativer Speicher unerwartet am Leben erhalten wird. Die nativen Strukturen für eine persistente Referenz müssen so lange am Leben erhalten werden, bis die Finalizer für das referenzierte Objekt ausgeführt werden. Wenn eine neue persistente Referenz für dasselbe Objekt erstellt wird, werden die Finalizer für dieses Objekt nicht ausgeführt und der native Speicher, auf den die frühere persistente Referenz zeigt, wird nicht freigegeben. Dies kann vermieden werden, indem napi_delete_reference zusätzlich zu napi_reference_unref aufgerufen wird, wenn möglich.

Änderungsverlauf:

Experimentell (NAPI_EXPERIMENTAL ist definiert): Referenzen können für alle Werttypen erstellt werden. Die neu unterstützten Werttypen unterstützen keine Semantik schwacher Referenzen, und die Werte dieser Typen werden freigegeben, wenn die Referenzzählung 0 wird, und können nicht mehr über die Referenz zugegriffen werden.

`napi_create_reference`

Hinzugefügt in: v8.0.0

N-API Version: 1

NAPI_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              uint32_t initial_refcount,
                                              napi_ref* result);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der napi_value, für den eine Referenz erstellt wird.
[in] initial_refcount: Der anfängliche Referenzzähler für die neue Referenz.
[out] result: napi_ref, der auf die neue Referenz zeigt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt eine neue Referenz mit dem angegebenen Referenzzähler für den übergebenen Wert.

`napi_delete_reference`

Hinzugefügt in: v8.0.0

N-API Version: 1

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] ref: napi_ref, der gelöscht werden soll.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API löscht die übergebene Referenz.

Diese API kann auch dann aufgerufen werden, wenn eine ausstehende JavaScript-Ausnahme vorliegt.

`napi_reference_ref`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] ref: napi_ref, für den der Referenzzähler erhöht wird.
[out] result: Der neue Referenzzähler.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erhöht den Referenzzähler für die übergebene Referenz und gibt den resultierenden Referenzzähler zurück.

`napi_reference_unref`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] ref: napi_ref, für den der Referenzzähler dekrementiert wird.
[out] result: Der neue Referenzzähler.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API dekrementiert den Referenzzähler für die übergebene Referenz und gibt den resultierenden Referenzzähler zurück.

`napi_get_reference_value`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] ref: Der napi_ref, für den der entsprechende Wert angefordert wird.
[out] result: Der napi_value, auf den napi_ref verweist.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Wenn noch gültig, gibt diese API den napi_value zurück, der den mit dem napi_ref verknüpften JavaScript-Wert darstellt. Andernfalls ist result NULL.

Bereinigung beim Beenden der aktuellen Node.js-Umgebung

Während ein Node.js-Prozess beim Beenden typischerweise alle seine Ressourcen freigibt, müssen Einbetter von Node.js oder zukünftige Worker-Unterstützung möglicherweise Addons die Registrierung von Bereinigungs-Hooks erfordern, die einmal beim Beenden der aktuellen Node.js-Umgebung ausgeführt werden.

Node-API stellt Funktionen zum Registrieren und Aufheben der Registrierung solcher Callbacks bereit. Wenn diese Callbacks ausgeführt werden, sollten alle vom Addon gehaltenen Ressourcen freigegeben werden.

`napi_add_env_cleanup_hook`

Hinzugefügt in: v10.2.0

N-API Version: 3

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

Registriert fun als Funktion, die mit dem Parameter arg ausgeführt wird, sobald die aktuelle Node.js-Umgebung beendet wird.

Eine Funktion kann sicher mehrmals mit verschiedenen arg-Werten angegeben werden. In diesem Fall wird sie auch mehrmals aufgerufen. Das mehrmalige Angeben der gleichen fun und arg Werte ist nicht erlaubt und führt zum Abbruch des Prozesses.

Die Hooks werden in umgekehrter Reihenfolge aufgerufen, d. h. der zuletzt hinzugefügte wird zuerst aufgerufen.

Das Entfernen dieses Hooks kann mit napi_remove_env_cleanup_hook erfolgen. Dies geschieht typischerweise, wenn die Ressource, für die dieser Hook hinzugefügt wurde, ohnehin abgebaut wird.

Für die asynchrone Bereinigung steht napi_add_async_cleanup_hook zur Verfügung.

`napi_remove_env_cleanup_hook`

Hinzugefügt in: v10.2.0

N-API Version: 3

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

Hebt die Registrierung von fun als Funktion auf, die mit dem Parameter arg ausgeführt werden soll, sobald die aktuelle Node.js-Umgebung beendet wird. Sowohl das Argument als auch der Funktionswert müssen exakt übereinstimmen.

Die Funktion muss ursprünglich mit napi_add_env_cleanup_hook registriert worden sein, andernfalls wird der Prozess abgebrochen.

`napi_add_async_cleanup_hook`

[Verlauf]

Version	Änderungen
v14.10.0, v12.19.0	Signatur des `hook`-Callbacks geändert.
v14.8.0, v12.19.0	Hinzugefügt in: v14.8.0, v12.19.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] hook: Der Funktionszeiger, der beim Herunterfahren der Umgebung aufgerufen werden soll.
[in] arg: Der Zeiger, der an hook übergeben werden soll, wenn er aufgerufen wird.
[out] remove_handle: Optionaler Handle, der auf den asynchronen Cleanup-Hook verweist.

Registriert hook, eine Funktion vom Typ napi_async_cleanup_hook, als Funktion, die mit den Parametern remove_handle und arg ausgeführt werden soll, sobald die aktuelle Node.js-Umgebung beendet wird.

Im Gegensatz zu napi_add_env_cleanup_hook darf der Hook asynchron sein.

Andernfalls entspricht das Verhalten im Allgemeinen dem von napi_add_env_cleanup_hook.

Wenn remove_handle nicht NULL ist, wird ein undurchsichtiger Wert darin gespeichert, der später an napi_remove_async_cleanup_hook übergeben werden muss, unabhängig davon, ob der Hook bereits aufgerufen wurde. Dies geschieht in der Regel, wenn die Ressource, für die dieser Hook hinzugefügt wurde, ohnehin abgebaut wird.

`napi_remove_async_cleanup_hook`

[Verlauf]

Version	Änderungen
v14.10.0, v12.19.0	Parameter `env` entfernt.
v14.8.0, v12.19.0	Hinzugefügt in: 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: Der Handle zu einem asynchronen Cleanup-Hook, der mit napi_add_async_cleanup_hook erstellt wurde.

Hebt die Registrierung des Cleanup-Hooks auf, der remove_handle entspricht. Dies verhindert die Ausführung des Hooks, es sei denn, die Ausführung wurde bereits gestartet. Dies muss für jeden napi_async_cleanup_hook_handle-Wert aufgerufen werden, der von napi_add_async_cleanup_hook erhalten wurde.

Finalisierung beim Beenden der Node.js-Umgebung

Die Node.js-Umgebung kann jederzeit so schnell wie möglich abgebaut werden, sobald die JavaScript-Ausführung nicht mehr zulässig ist, beispielsweise auf Anfrage von worker.terminate(). Wenn die Umgebung abgebaut wird, werden die registrierten napi_finalize-Callbacks von JavaScript-Objekten, threadsicheren Funktionen und Umgebungsinstanzdaten sofort und unabhängig voneinander aufgerufen.

Der Aufruf von napi_finalize-Callbacks wird nach den manuell registrierten Cleanup-Hooks geplant. Um eine korrekte Reihenfolge der Addon-Finalisierung während des Herunterfahrens der Umgebung zu gewährleisten und Use-after-Free im napi_finalize-Callback zu vermeiden, sollten Addons einen Cleanup-Hook mit napi_add_env_cleanup_hook und napi_add_async_cleanup_hook registrieren, um die zugeordneten Ressourcen in der richtigen Reihenfolge manuell freizugeben.

Modulregistrierung

Node-API-Module werden ähnlich wie andere Module registriert, außer dass anstelle des NODE_MODULE-Makros Folgendes verwendet wird:

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

Der nächste Unterschied ist die Signatur für die Init-Methode. Für ein Node-API-Modul lautet sie wie folgt:

napi_value Init(napi_env env, napi_value exports);

Der Rückgabewert von Init wird als exports-Objekt für das Modul behandelt. Die Init-Methode erhält als Komfort ein leeres Objekt über den exports-Parameter. Wenn Init NULL zurückgibt, wird der als exports übergebene Parameter vom Modul exportiert. Node-API-Module können das module-Objekt nicht ändern, können aber beliebige Werte als exports-Eigenschaft des Moduls angeben.

So fügen Sie die Methode hello als Funktion hinzu, damit sie als vom Addon bereitgestellte Methode aufgerufen werden kann:

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

So legen Sie eine Funktion fest, die vom require() für das Addon zurückgegeben werden soll:

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

So definieren Sie eine Klasse, damit neue Instanzen erstellt werden können (oft verwendet mit Object wrap):

// HINWEIS: Teilausschnitt, nicht der gesamte referenzierte Code ist enthalten
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;
}

Sie können auch das NAPI_MODULE_INIT-Makro verwenden, das als Abkürzung für NAPI_MODULE und die Definition einer Init-Funktion dient:

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

Die Parameter env und exports werden dem Funktionskörper nach dem Makroaufruf bereitgestellt.

Alle Node-API-Addons sind kontextabhängig, d. h. sie können mehrmals geladen werden. Bei der Deklaration eines solchen Moduls gibt es einige Designüberlegungen. Die Dokumentation zu kontextabhängigen Addons enthält weitere Details.

Die Variablen env und exports stehen innerhalb des Funktionskörpers nach dem Makroaufruf zur Verfügung.

Weitere Informationen zum Festlegen von Eigenschaften für Objekte finden Sie im Abschnitt Arbeiten mit JavaScript-Eigenschaften.

Weitere Informationen zum Erstellen von Addon-Modulen im Allgemeinen finden Sie in der vorhandenen API.

Arbeiten mit JavaScript-Werten

Node-API stellt einen Satz von APIs bereit, um alle Arten von JavaScript-Werten zu erstellen. Einige dieser Typen sind unter Abschnitt 6 der ECMAScript-Sprachspezifikation dokumentiert.

Grundsätzlich werden diese APIs verwendet, um eines der folgenden Dinge zu tun:

Node-API-Werte werden durch den Typ napi_value repräsentiert. Jeder Node-API-Aufruf, der einen JavaScript-Wert benötigt, verwendet einen napi_value. In einigen Fällen prüft die API den Typ des napi_value im Voraus. Für eine bessere Performance ist es jedoch besser, wenn der Aufrufer sicherstellt, dass der napi_value vom JavaScript-Typ ist, der von der API erwartet wird.

Enum-Typen

`napi_key_collection_mode`

Hinzugefügt in: v13.7.0, v12.17.0, v10.20.0

N-API-Version: 6

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode;

Beschreibt die Keys/Properties-Filter-Enums:

napi_key_collection_mode begrenzt den Bereich der gesammelten Eigenschaften.

napi_key_own_only beschränkt die gesammelten Eigenschaften auf das gegebene Objekt. napi_key_include_prototypes beinhaltet auch alle Schlüssel der Prototypenkette des Objekts.

`napi_key_filter`

Hinzugefügt in: v13.7.0, v12.17.0, v10.20.0

N-API-Version: 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;

Eigenschaftsfilter-Bits. Sie können mit OR verknüpft werden, um einen zusammengesetzten Filter zu erstellen.

`napi_key_conversion`

Hinzugefügt in: v13.7.0, v12.17.0, v10.20.0

N-API-Version: 6

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion;

napi_key_numbers_to_strings konvertiert Integer-Indizes in Strings. napi_key_keep_numbers gibt Zahlen für Integer-Indizes zurück.

`napi_valuetype`

typedef enum {
  // ES6-Typen (entspricht typeof)
  napi_undefined,
  napi_null,
  napi_boolean,
  napi_number,
  napi_string,
  napi_symbol,
  napi_object,
  napi_function,
  napi_external,
  napi_bigint,
} napi_valuetype;

Beschreibt den Typ eines napi_value. Dies entspricht im Allgemeinen den in Abschnitt 6.1 der ECMAScript-Sprachspezifikation beschriebenen Typen. Zusätzlich zu den Typen in diesem Abschnitt kann napi_valuetype auch Functions und Objects mit externen Daten darstellen.

Ein JavaScript-Wert vom Typ napi_external erscheint in JavaScript als einfaches Objekt, so dass keine Eigenschaften gesetzt und kein Prototyp verwendet werden kann.

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

Dies stellt den zugrunde liegenden binären skalaren Datentyp des TypedArray dar. Elemente dieses Enumerations entsprechen Abschnitt 22.2 der ECMAScript Language Specification.

Objekt-Erstellungsfunktionen

`napi_create_array`

Hinzugefügt in: v8.0.0

N-API-Version: 1

napi_status napi_create_array(napi_env env, napi_value* result)

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[out] result: Ein napi_value, der ein JavaScript Array darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt einen Node-API-Wert zurück, der einem JavaScript Array-Typ entspricht. JavaScript-Arrays werden in Abschnitt 22.1 der ECMAScript Language Specification beschrieben.

`napi_create_array_with_length`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] length: Die anfängliche Länge des Array.
[out] result: Ein napi_value, der ein JavaScript Array darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt einen Node-API-Wert zurück, der einem JavaScript Array-Typ entspricht. Die length-Eigenschaft des Array wird auf den übergebenen Längenparameter gesetzt. Der zugrunde liegende Puffer wird jedoch nicht garantiert von der VM vorab zugewiesen, wenn das Array erstellt wird. Dieses Verhalten bleibt der zugrunde liegenden VM-Implementierung überlassen. Wenn der Puffer ein zusammenhängender Speicherblock sein muss, der direkt über C gelesen und/oder geschrieben werden kann, sollten Sie napi_create_external_arraybuffer verwenden.

JavaScript-Arrays werden in Abschnitt 22.1 der ECMAScript Language Specification beschrieben.

`napi_create_arraybuffer`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] length: Die Länge in Bytes des zu erstellenden ArrayBuffers.
[out] data: Zeiger auf den zugrundeliegenden Byte-Buffer des ArrayBuffer. data kann optional ignoriert werden, indem NULL übergeben wird.
[out] result: Ein napi_value, das ein JavaScript ArrayBuffer darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt einen Node-API-Wert zurück, der einem JavaScript ArrayBuffer entspricht. ArrayBuffers werden verwendet, um festlängen Binär-Daten-Buffer darzustellen. Sie werden normalerweise als Backing-Buffer für TypedArray-Objekte verwendet. Der zugewiesene ArrayBuffer wird einen zugrundeliegenden Byte-Buffer haben, dessen Größe durch den übergebenen length-Parameter bestimmt wird. Der zugrundeliegende Buffer wird optional an den Aufrufer zurückgegeben, falls dieser den Buffer direkt manipulieren möchte. Dieser Buffer kann nur direkt aus nativem Code beschrieben werden. Um von JavaScript aus in diesen Buffer zu schreiben, müsste ein Typed Array oder ein DataView-Objekt erstellt werden.

JavaScript ArrayBuffer-Objekte werden in Abschnitt 24.1 der ECMAScript Language Specification beschrieben.

`napi_create_buffer`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] size: Größe in Bytes des zugrundeliegenden Buffers.
[out] data: Roher Zeiger auf den zugrundeliegenden Buffer. data kann optional ignoriert werden, indem NULL übergeben wird.
[out] result: Ein napi_value, das ein node::Buffer darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API weist ein node::Buffer-Objekt zu. Obwohl dies immer noch eine vollständig unterstützte Datenstruktur ist, reicht in den meisten Fällen die Verwendung eines TypedArray aus.

`napi_create_buffer_copy`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_create_buffer_copy(napi_env env,
                                    size_t length,
                                    const void* data,
                                    void** result_data,
                                    napi_value* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] size: Größe des Eingabepuffers in Bytes (sollte identisch mit der Größe des neuen Puffers sein).
[in] data: Rohzeiger auf den zugrundeliegenden Puffer, von dem kopiert werden soll.
[out] result_data: Zeiger auf den zugrundeliegenden Datenpuffer des neuen Buffer. result_data kann optional ignoriert werden, indem NULL übergeben wird.
[out] result: Ein napi_value, das einen node::Buffer darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API allokiert ein node::Buffer-Objekt und initialisiert es mit Daten, die aus dem übergebenen Puffer kopiert wurden. Obwohl dies immer noch eine voll unterstützte Datenstruktur ist, reicht in den meisten Fällen die Verwendung eines TypedArray aus.

`napi_create_date`

Hinzugefügt in: v11.11.0, v10.17.0

N-API Version: 5

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] time: ECMAScript-Zeitwert in Millisekunden seit dem 01. Januar 1970 UTC.
[out] result: Ein napi_value, das ein JavaScript Date darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API beachtet keine Schaltsekunden; sie werden ignoriert, da ECMAScript mit der POSIX-Zeitspezifikation übereinstimmt.

Diese API allokiert ein JavaScript Date-Objekt.

JavaScript Date-Objekte werden in Abschnitt 20.3 der ECMAScript-Sprachspezifikation beschrieben.

`napi_create_external`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_create_external(napi_env env,
                                 void* data,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] data: Rohzeiger auf die externen Daten.
[in] finalize_cb: Optionaler Rückruf, der aufgerufen wird, wenn der externe Wert gesammelt wird. napi_finalize liefert weitere Details.
[in] finalize_hint: Optionaler Hinweis, der während der Sammlung an den finalize-Rückruf übergeben wird.
[out] result: Ein napi_value, das einen externen Wert darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API allokiert einen JavaScript-Wert mit daran angehängten externen Daten. Dies wird verwendet, um externe Daten über JavaScript-Code zu übergeben, so dass sie später von nativem Code mit napi_get_value_external abgerufen werden können.

Die API fügt einen napi_finalize-Rückruf hinzu, der aufgerufen wird, wenn das gerade erstellte JavaScript-Objekt garbage collected wurde.

Der erstellte Wert ist kein Objekt und unterstützt daher keine zusätzlichen Eigenschaften. Er wird als eigenständiger Werttyp betrachtet: Ein Aufruf von napi_typeof() mit einem externen Wert liefert napi_external.

`napi_create_external_arraybuffer`

Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] external_data: Zeiger auf den zugrunde liegenden Byte-Puffer des ArrayBuffer.
[in] byte_length: Die Länge in Bytes des zugrunde liegenden Puffers.
[in] finalize_cb: Optionaler Rückruf, der aufgerufen wird, wenn der ArrayBuffer gesammelt wird. napi_finalize bietet weitere Details.
[in] finalize_hint: Optionaler Hinweis, der während der Sammlung an den Finalisierungs-Rückruf übergeben wird.
[out] result: Ein napi_value, der einen JavaScript ArrayBuffer darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Einige andere Laufzeiten als Node.js haben die Unterstützung für externe Puffer eingestellt. In anderen Laufzeiten als Node.js gibt diese Methode möglicherweise napi_no_external_buffers_allowed zurück, um anzugeben, dass externe Puffer nicht unterstützt werden. Eine solche Laufzeit ist Electron, wie in diesem Issue beschrieben electron/issues/35801.

Um die breiteste Kompatibilität mit allen Laufzeiten zu gewährleisten, können Sie NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED in Ihrem Addon definieren, bevor Sie die Node-API-Header einbinden. Dadurch werden die beiden Funktionen, die externe Puffer erstellen, ausgeblendet. Dies stellt sicher, dass ein Kompilierungsfehler auftritt, wenn Sie versehentlich eine dieser Methoden verwenden.

Diese API gibt einen Node-API-Wert zurück, der einem JavaScript ArrayBuffer entspricht. Der zugrunde liegende Byte-Puffer des ArrayBuffer wird extern zugeordnet und verwaltet. Der Aufrufer muss sicherstellen, dass der Byte-Puffer gültig bleibt, bis der Finalisierungs-Rückruf aufgerufen wird.

Die API fügt einen napi_finalize-Rückruf hinzu, der aufgerufen wird, wenn das gerade erstellte JavaScript-Objekt garbage collected wurde.

JavaScript ArrayBuffers werden in Abschnitt 24.1 der ECMAScript Language Specification beschrieben.

`napi_create_external_buffer`

Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] length: Größe des Eingabepuffers in Bytes (sollte mit der Größe des neuen Puffers übereinstimmen).
[in] data: Roher Zeiger auf den zugrunde liegenden Puffer, der JavaScript zur Verfügung gestellt werden soll.
[in] finalize_cb: Optionaler Rückruf, der aufgerufen wird, wenn der ArrayBuffer freigegeben wird. napi_finalize bietet weitere Details.
[in] finalize_hint: Optionaler Hinweis, der während der Freigabe an den Finalisierungs-Rückruf übergeben wird.
[out] result: Ein napi_value, der einen node::Buffer darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Einige andere Laufzeiten als Node.js haben die Unterstützung für externe Puffer eingestellt. In anderen Laufzeiten als Node.js kann diese Methode napi_no_external_buffers_allowed zurückgeben, um anzuzeigen, dass externe Puffer nicht unterstützt werden. Eine solche Laufzeit ist Electron, wie in diesem Issue beschrieben electron/issues/35801.

Um die breiteste Kompatibilität mit allen Laufzeiten zu gewährleisten, können Sie NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED in Ihrem Addon vor den Includes für die Node-API-Header definieren. Dies blendet die beiden Funktionen aus, die externe Puffer erstellen. Dadurch wird sichergestellt, dass ein Kompilierungsfehler auftritt, wenn Sie versehentlich eine dieser Methoden verwenden.

Diese API allokiert ein node::Buffer-Objekt und initialisiert es mit Daten, die vom übergebenen Puffer unterstützt werden. Obwohl dies immer noch eine vollständig unterstützte Datenstruktur ist, reicht in den meisten Fällen die Verwendung eines TypedArray aus.

Die API fügt einen napi_finalize-Rückruf hinzu, der aufgerufen wird, wenn das gerade erstellte JavaScript-Objekt garbage collected wurde.

Für Node.js >=4 sind Buffers Uint8Arrays.

`napi_create_object`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_create_object(napi_env env, napi_value* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: Ein napi_value, der ein JavaScript Object darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API alloziert ein standardmäßiges JavaScript Object. Es entspricht new Object() in JavaScript.

Der JavaScript Object-Typ wird in Abschnitt 6.1.7 der ECMAScript Language Specification beschrieben.

`napi_create_symbol`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] description: Optionaler napi_value, der auf einen JavaScript string verweist, der als Beschreibung für das Symbol gesetzt werden soll.
[out] result: Ein napi_value, der ein JavaScript symbol darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen JavaScript symbol-Wert aus einem UTF8-kodierten C-String.

Der JavaScript symbol-Typ wird in Abschnitt 19.4 der ECMAScript Language Specification beschrieben.

`node_api_symbol_for`

Hinzugefügt in: v17.5.0, v16.15.0

N-API Version: 9

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] utf8description: UTF-8 C-String, der den Text darstellt, der als Beschreibung für das Symbol verwendet werden soll.
[in] length: Die Länge des Beschreibungsstrings in Bytes oder NAPI_AUTO_LENGTH, wenn er null-terminiert ist.
[out] result: Ein napi_value, der ein JavaScript symbol darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API sucht in der globalen Registrierung nach einem bestehenden Symbol mit der gegebenen Beschreibung. Wenn das Symbol bereits existiert, wird es zurückgegeben, andernfalls wird ein neues Symbol in der Registrierung erstellt.

Der JavaScript symbol-Typ wird in Abschnitt 19.4 der ECMAScript Language Specification beschrieben.

`napi_create_typedarray`

Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] type: Skalardatentyp der Elemente innerhalb des TypedArray.
[in] length: Anzahl der Elemente im TypedArray.
[in] arraybuffer: ArrayBuffer, der dem Typed Array zugrunde liegt.
[in] byte_offset: Der Byte-Offset innerhalb des ArrayBuffer, von dem aus die Projektion des TypedArray beginnen soll.
[out] result: Ein napi_value, das ein JavaScript TypedArray repräsentiert.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt ein JavaScript TypedArray-Objekt über einen bestehenden ArrayBuffer. TypedArray-Objekte bieten eine arrayähnliche Ansicht über einen zugrunde liegenden Datenpuffer, wobei jedes Element den gleichen zugrunde liegenden binären Skalardatentyp hat.

Es ist erforderlich, dass (length * size_of_element) + byte_offset <= die Größe in Bytes des übergebenen Arrays ist. Andernfalls wird eine RangeError-Ausnahme ausgelöst.

JavaScript TypedArray-Objekte werden in Abschnitt 22.2 der ECMAScript Language Specification beschrieben.

`node_api_create_buffer_from_arraybuffer`

Hinzugefügt in: v23.0.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

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: Die Umgebung, unter der die API aufgerufen wird.
[in] arraybuffer: Der ArrayBuffer, aus dem der Puffer erstellt wird.
[in] byte_offset: Der Byte-Offset innerhalb des ArrayBuffer, von dem aus die Erstellung des Puffers beginnen soll.
[in] byte_length: Die Länge in Bytes des Puffers, der aus dem ArrayBuffer erstellt werden soll.
[out] result: Ein napi_value, das das erstellte JavaScript Buffer-Objekt repräsentiert.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt ein JavaScript Buffer-Objekt aus einem bestehenden ArrayBuffer. Das Buffer-Objekt ist eine Node.js-spezifische Klasse, die eine Möglichkeit bietet, direkt mit binären Daten in JavaScript zu arbeiten.

Der Bytebereich [byte_offset, byte_offset + byte_length) muss innerhalb der Grenzen des ArrayBuffer liegen. Wenn byte_offset + byte_length die Größe des ArrayBuffer überschreitet, wird eine RangeError-Ausnahme ausgelöst.

`napi_create_dataview`

Hinzugefügt in: v8.3.0

N-API-Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] length: Anzahl der Elemente in der DataView.
[in] arraybuffer: ArrayBuffer, der der DataView zugrunde liegt.
[in] byte_offset: Der Byte-Offset innerhalb des ArrayBuffer, von dem aus die DataView projiziert werden soll.
[out] result: Ein napi_value, das eine JavaScript DataView darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt ein JavaScript DataView-Objekt über einen bestehenden ArrayBuffer. DataView-Objekte bieten eine array-ähnliche Sicht auf einen zugrunde liegenden Datenpuffer, jedoch eine, die Elemente unterschiedlicher Größe und Typs im ArrayBuffer zulässt.

Es ist erforderlich, dass byte_length + byte_offset kleiner oder gleich der Größe in Bytes des übergebenen Arrays ist. Andernfalls wird eine RangeError-Ausnahme ausgelöst.

JavaScript DataView-Objekte werden in Abschnitt 24.3 der ECMAScript Language Specification beschrieben.

Funktionen zur Konvertierung von C-Typen zu Node-API

`napi_create_int32`

Hinzugefügt in: v8.4.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Integer-Wert, der in JavaScript dargestellt werden soll.
[out] result: Ein napi_value, das eine JavaScript number darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wird verwendet, um vom C int32_t-Typ zum JavaScript number-Typ zu konvertieren.

Der JavaScript number-Typ wird in Abschnitt 6.1.6 der ECMAScript Language Specification beschrieben.

`napi_create_uint32`

Hinzugefügt in: v8.4.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Vorzeichenloser ganzzahliger Wert, der in JavaScript dargestellt werden soll.
[out] result: Ein napi_value, der eine JavaScript number darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wird verwendet, um von dem C uint32_t-Typ in den JavaScript number-Typ zu konvertieren.

Der JavaScript number-Typ wird in Abschnitt 6.1.6 der ECMAScript Language Specification beschrieben.

`napi_create_int64`

Hinzugefügt in: v8.4.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Ganzzahliger Wert, der in JavaScript dargestellt werden soll.
[out] result: Ein napi_value, der eine JavaScript number darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wird verwendet, um von dem C int64_t-Typ in den JavaScript number-Typ zu konvertieren.

Der JavaScript number-Typ wird in Abschnitt 6.1.6 der ECMAScript Language Specification beschrieben. Beachten Sie, dass der vollständige Bereich von int64_t nicht mit voller Genauigkeit in JavaScript dargestellt werden kann. Ganzzahlen außerhalb des Bereichs von Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) verlieren an Genauigkeit.

`napi_create_double`

Hinzugefügt in: v8.4.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Wert mit doppelter Genauigkeit, der in JavaScript dargestellt werden soll.
[out] result: Ein napi_value, der eine JavaScript number darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wird verwendet, um von dem C double-Typ in den JavaScript number-Typ zu konvertieren.

Der JavaScript number-Typ wird in Abschnitt 6.1.6 der ECMAScript Language Specification beschrieben.

`napi_create_bigint_int64`

Hinzugefügt in: v10.7.0

N-API Version: 6

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Integer-Wert, der in JavaScript dargestellt werden soll.
[out] result: Ein napi_value, der ein JavaScript BigInt darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API konvertiert den C int64_t-Typ in den JavaScript BigInt-Typ.

`napi_create_bigint_uint64`

Hinzugefügt in: v10.7.0

N-API Version: 6

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Vorzeichenloser Integer-Wert, der in JavaScript dargestellt werden soll.
[out] result: Ein napi_value, der ein JavaScript BigInt darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API konvertiert den C uint64_t-Typ in den JavaScript BigInt-Typ.

`napi_create_bigint_words`

Hinzugefügt in: v10.7.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] sign_bit: Bestimmt, ob der resultierende BigInt positiv oder negativ sein wird.
[in] word_count: Die Länge des words-Arrays.
[in] words: Ein Array von uint64_t Little-Endian 64-Bit-Wörtern.
[out] result: Ein napi_value, der ein JavaScript BigInt darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API konvertiert ein Array von vorzeichenlosen 64-Bit-Wörtern in einen einzelnen BigInt-Wert.

Der resultierende BigInt wird berechnet als: (–1)^sign_bit(words[0] × (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)

`napi_create_string_latin1`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] str: Zeichenpuffer, der eine ISO-8859-1-kodierte Zeichenkette darstellt.
[in] length: Die Länge der Zeichenkette in Bytes oder NAPI_AUTO_LENGTH, wenn sie nullterminiert ist.
[out] result: Ein napi_value, der einen JavaScript-string darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen JavaScript-string-Wert aus einer ISO-8859-1-kodierten C-Zeichenkette. Die native Zeichenkette wird kopiert.

Der JavaScript-string-Typ wird in Abschnitt 6.1.4 der ECMAScript Language Specification beschrieben.

`node_api_create_external_string_latin1`

Hinzugefügt in: v20.4.0, v18.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

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: Die Umgebung, unter der die API aufgerufen wird.
[in] str: Zeichenpuffer, der eine ISO-8859-1-kodierte Zeichenkette darstellt.
[in] length: Die Länge der Zeichenkette in Bytes oder NAPI_AUTO_LENGTH, wenn sie nullterminiert ist.
[in] finalize_callback: Die Funktion, die aufgerufen wird, wenn die Zeichenkette gesammelt wird. Die Funktion wird mit den folgenden Parametern aufgerufen:
- [in] env: Die Umgebung, in der das Add-on ausgeführt wird. Dieser Wert kann null sein, wenn die Zeichenkette im Rahmen der Beendigung des Workers oder der Hauptinstanz von Node.js gesammelt wird.
- [in] data: Dies ist der Wert str als void*-Zeiger.
- [in] finalize_hint: Dies ist der Wert finalize_hint, der der API übergeben wurde. napi_finalize bietet weitere Details. Dieser Parameter ist optional. Das Übergeben eines Nullwerts bedeutet, dass das Add-on nicht benachrichtigt werden muss, wenn die entsprechende JavaScript-Zeichenkette gesammelt wird.
[in] finalize_hint: Optionaler Hinweis, der während des Sammelns an den Finalisierung-Callback übergeben wird.
[out] result: Ein napi_value, der einen JavaScript-string darstellt.
[out] copied: Ob die Zeichenkette kopiert wurde. Wenn ja, wurde der Finalizer bereits aufgerufen, um str zu zerstören.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen JavaScript-string-Wert aus einer ISO-8859-1-kodierten C-Zeichenkette. Die native Zeichenkette wird möglicherweise nicht kopiert und muss daher für den gesamten Lebenszyklus des JavaScript-Werts existieren.

Der JavaScript-string-Typ wird in Abschnitt 6.1.4 der ECMAScript Language Specification beschrieben.

`napi_create_string_utf16`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] str: Zeichenpuffer, der eine UTF16-LE-kodierte Zeichenkette darstellt.
[in] length: Die Länge der Zeichenkette in Zweibyte-Codeeinheiten oder NAPI_AUTO_LENGTH, wenn sie nullterminiert ist.
[out] result: Ein napi_value, der eine JavaScript-string darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen JavaScript-string-Wert aus einer UTF16-LE-kodierten C-Zeichenkette. Die native Zeichenkette wird kopiert.

Der JavaScript-string-Typ wird in Abschnitt 6.1.4 der ECMAScript Language Specification beschrieben.

`node_api_create_external_string_utf16`

Hinzugefügt in: v20.4.0, v18.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

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: Die Umgebung, unter der die API aufgerufen wird.
[in] str: Zeichenpuffer, der eine UTF16-LE-kodierte Zeichenkette darstellt.
[in] length: Die Länge der Zeichenkette in Zweibyte-Codeeinheiten oder NAPI_AUTO_LENGTH, wenn sie nullterminiert ist.
[in] finalize_callback: Die Funktion, die aufgerufen wird, wenn die Zeichenkette gesammelt wird. Die Funktion wird mit den folgenden Parametern aufgerufen:
- [in] env: Die Umgebung, in der das Add-on ausgeführt wird. Dieser Wert kann null sein, wenn die Zeichenkette im Rahmen der Beendigung des Workers oder der Hauptinstanz von Node.js gesammelt wird.
- [in] data: Dies ist der Wert str als void*-Zeiger.
- [in] finalize_hint: Dies ist der Wert finalize_hint, der der API übergeben wurde. napi_finalize bietet weitere Details. Dieser Parameter ist optional. Das Übergeben eines Nullwerts bedeutet, dass das Add-on nicht benachrichtigt werden muss, wenn die entsprechende JavaScript-Zeichenkette gesammelt wird.
[in] finalize_hint: Optionaler Hinweis, der während des Sammelns an die finalize-Callback-Funktion übergeben wird.
[out] result: Ein napi_value, der eine JavaScript-string darstellt.
[out] copied: Ob die Zeichenkette kopiert wurde. Wenn ja, wurde der Finalizer bereits aufgerufen, um str zu zerstören.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen JavaScript-string-Wert aus einer UTF16-LE-kodierten C-Zeichenkette. Die native Zeichenkette wird möglicherweise nicht kopiert und muss daher während des gesamten Lebenszyklus des JavaScript-Werts existieren.

Der JavaScript-string-Typ wird in Abschnitt 6.1.4 der ECMAScript Language Specification beschrieben.

`napi_create_string_utf8`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] str: Zeichenpuffer, der eine UTF8-codierte Zeichenkette darstellt.
[in] length: Die Länge der Zeichenkette in Bytes oder NAPI_AUTO_LENGTH, wenn sie nullterminiert ist.
[out] result: Ein napi_value, das eine JavaScript-string darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen JavaScript-string-Wert aus einer UTF8-codierten C-Zeichenkette. Die native Zeichenkette wird kopiert.

Der JavaScript-string-Typ wird in Abschnitt 6.1.4 der ECMAScript Language Specification beschrieben.

Funktionen zum Erstellen optimierter Eigenschaftsschlüssel

Viele JavaScript-Engines, einschließlich V8, verwenden internalisierte Zeichenketten als Schlüssel zum Setzen und Abrufen von Eigenschaftswerten. Sie verwenden typischerweise eine Hash-Tabelle, um solche Zeichenketten zu erstellen und nachzuschlagen. Obwohl dies pro Schlüsselerstellung einige Kosten verursacht, verbessert es die Leistung danach, indem der Vergleich von Zeichenkettenzeigern anstelle der gesamten Zeichenketten ermöglicht wird.

Wenn eine neue JavaScript-Zeichenkette als Eigenschaftsschlüssel verwendet werden soll, ist es für einige JavaScript-Engines effizienter, die Funktionen in diesem Abschnitt zu verwenden. Andernfalls verwenden Sie die Funktionen der napi_create_string_utf8- oder node_api_create_external_string_utf8-Serie, da bei den Methoden zur Erstellung von Eigenschaftsschlüsseln möglicherweise zusätzlicher Aufwand beim Erstellen/Speichern von Zeichenketten anfällt.

`node_api_create_property_key_latin1`

Hinzugefügt in: v22.9.0, v20.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] str: Zeichenpuffer, der eine ISO-8859-1-codierte Zeichenkette darstellt.
[in] length: Die Länge der Zeichenkette in Bytes oder NAPI_AUTO_LENGTH, wenn sie nullterminiert ist.
[out] result: Ein napi_value, das einen optimierten JavaScript-string darstellt, der als Eigenschaftsschlüssel für Objekte verwendet werden soll.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen optimierten JavaScript-string-Wert aus einer ISO-8859-1-codierten C-Zeichenkette, der als Eigenschaftsschlüssel für Objekte verwendet werden soll. Die native Zeichenkette wird kopiert. Im Gegensatz zu napi_create_string_latin1 können nachfolgende Aufrufe dieser Funktion mit demselben str-Zeiger je nach Engine von einer Geschwindigkeitsverbesserung bei der Erstellung des angeforderten napi_value profitieren.

Der JavaScript-string-Typ wird in Abschnitt 6.1.4 der ECMAScript Language Specification beschrieben.

`node_api_create_property_key_utf16`

Hinzugefügt in: v21.7.0, v20.12.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

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: Die Umgebung, unter der die API aufgerufen wird.
[in] str: Zeichenpuffer, der eine UTF16-LE-codierte Zeichenkette darstellt.
[in] length: Die Länge der Zeichenkette in Zweibyte-Codeeinheiten oder NAPI_AUTO_LENGTH, wenn sie nullterminiert ist.
[out] result: Ein napi_value, das eine optimierte JavaScript-string-Variable darstellt, die als Eigenschaftsschlüssel für Objekte verwendet werden soll.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen optimierten JavaScript string-Wert aus einer UTF16-LE-codierten C-Zeichenkette, der als Eigenschaftsschlüssel für Objekte verwendet werden soll. Die native Zeichenkette wird kopiert.

Der JavaScript string-Typ wird in Abschnitt 6.1.4 der ECMAScript Language Specification beschrieben.

`node_api_create_property_key_utf8`

Hinzugefügt in: v22.9.0, v20.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] str: Zeichenpuffer, der eine UTF8-codierte Zeichenkette darstellt.
[in] length: Die Länge der Zeichenkette in Zweibyte-Codeeinheiten oder NAPI_AUTO_LENGTH, wenn sie nullterminiert ist.
[out] result: Ein napi_value, das eine optimierte JavaScript-string-Variable darstellt, die als Eigenschaftsschlüssel für Objekte verwendet werden soll.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt einen optimierten JavaScript string-Wert aus einer UTF8-codierten C-Zeichenkette, der als Eigenschaftsschlüssel für Objekte verwendet werden soll. Die native Zeichenkette wird kopiert.

Der JavaScript string-Typ wird in Abschnitt 6.1.4 der ECMAScript Language Specification beschrieben.

Funktionen zur Konvertierung von Node-API zu C-Typen

`napi_get_array_length`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der das JavaScript-Array darstellt, dessen Länge abgefragt wird.
[out] result: uint32, der die Länge des Arrays darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt die Länge eines Arrays zurück.

Die Länge des Array wird in Abschnitt 22.1.4.1 der ECMAScript-Sprachspezifikation beschrieben.

`napi_get_arraybuffer_info`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] arraybuffer: napi_value, der den abzufragenden ArrayBuffer darstellt.
[out] data: Der zugrunde liegende Datenpuffer des ArrayBuffer. Wenn byte_length 0 ist, kann dies NULL oder ein beliebiger anderer Zeigerwert sein.
[out] byte_length: Länge in Bytes des zugrunde liegenden Datenpuffers.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wird verwendet, um den zugrunde liegenden Datenpuffer eines ArrayBuffer und dessen Länge abzurufen.

WARNUNG: Seien Sie vorsichtig bei der Verwendung dieser API. Die Lebensdauer des zugrunde liegenden Datenpuffers wird vom ArrayBuffer verwaltet, auch nachdem er zurückgegeben wurde. Eine möglicherweise sichere Möglichkeit, diese API zu verwenden, ist die Verwendung in Verbindung mit napi_create_reference, mit der die Kontrolle über die Lebensdauer des ArrayBuffer gewährleistet werden kann. Es ist auch sicher, den zurückgegebenen Datenpuffer innerhalb desselben Callbacks zu verwenden, solange keine Aufrufe anderer APIs erfolgen, die einen GC auslösen könnten.

`napi_get_buffer_info`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der den abzufragenden node::Buffer oder Uint8Array darstellt.
[out] data: Der zugrunde liegende Datenpuffer des node::Buffer oder Uint8Array. Wenn die Länge 0 ist, kann dies NULL oder ein beliebiger anderer Zeigerwert sein.
[out] length: Länge in Bytes des zugrunde liegenden Datenpuffers.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode gibt identische data und byte_length wie napi_get_typedarray_info zurück. Und napi_get_typedarray_info akzeptiert auch einen node::Buffer (ein Uint8Array) als Wert.

Diese API wird verwendet, um den zugrunde liegenden Datenpuffer eines node::Buffer und dessen Länge abzurufen.

Warnung: Seien Sie vorsichtig bei der Verwendung dieser API, da die Lebensdauer des zugrunde liegenden Datenpuffers nicht garantiert ist, wenn er von der VM verwaltet wird.

`napi_get_prototype`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] object: napi_value, der das JavaScript-Object darstellt, dessen Prototype zurückgegeben werden soll. Dies gibt das Äquivalent von Object.getPrototypeOf zurück (was nicht dasselbe ist wie die prototype-Eigenschaft der Funktion).
[out] result: napi_value, der den Prototype des gegebenen Objekts darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

`napi_get_typedarray_info`

Hinzugefügt in: v8.0.0

N-API-Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] typedarray: napi_value, der das TypedArray darstellt, dessen Eigenschaften abgefragt werden sollen.
[out] type: Skalardatentyp der Elemente innerhalb des TypedArray.
[out] length: Die Anzahl der Elemente im TypedArray.
[out] data: Der Datenpuffer, der dem TypedArray zugrunde liegt, angepasst um den Wert byte_offset, so dass er auf das erste Element im TypedArray zeigt. Wenn die Länge des Arrays 0 ist, kann dies NULL oder ein beliebiger anderer Zeigerwert sein.
[out] arraybuffer: Der ArrayBuffer, der dem TypedArray zugrunde liegt.
[out] byte_offset: Der Byte-Offset innerhalb des zugrunde liegenden nativen Arrays, an dem sich das erste Element des Arrays befindet. Der Wert für den Datenparameter wurde bereits so angepasst, dass data auf das erste Element im Array zeigt. Daher wäre das erste Byte des nativen Arrays bei data - byte_offset.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt verschiedene Eigenschaften eines Typisierten Arrays zurück.

Jeder der Ausgabeparameter kann NULL sein, wenn diese Eigenschaft nicht benötigt wird.

Warnung: Seien Sie vorsichtig bei der Verwendung dieser API, da der zugrunde liegende Datenpuffer von der VM verwaltet wird.

`napi_get_dataview_info`

Hinzugefügt in: v8.3.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] dataview: napi_value, der das DataView repräsentiert, dessen Eigenschaften abgefragt werden sollen.
[out] byte_length: Anzahl der Bytes im DataView.
[out] data: Der Datenpuffer, der dem DataView zugrunde liegt. Wenn byte_length 0 ist, kann dies NULL oder ein beliebiger anderer Zeigerwert sein.
[out] arraybuffer: ArrayBuffer, der dem DataView zugrunde liegt.
[out] byte_offset: Der Byte-Offset innerhalb des Datenpuffers, von dem aus die Projektion des DataView beginnen soll.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Jeder der Ausgabeparameter kann NULL sein, wenn diese Eigenschaft nicht benötigt wird.

Diese API gibt verschiedene Eigenschaften eines DataView zurück.

`napi_get_date_value`

Hinzugefügt in: v11.11.0, v10.17.0

N-API Version: 5

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der ein JavaScript Date repräsentiert.
[out] result: Zeitwert als double, dargestellt als Millisekunden seit Mitternacht am Anfang des 01. Januar 1970 UTC.

Diese API beachtet keine Schaltsekunden; diese werden ignoriert, da ECMAScript mit der POSIX-Zeitspezifikation übereinstimmt.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein nicht-Datum napi_value übergeben wird, gibt sie napi_date_expected zurück.

Diese API gibt den C double-Primitiv des Zeitwerts für das gegebene JavaScript Date zurück.

`napi_get_value_bool`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der ein JavaScript Boolean repräsentiert.
[out] result: C boolean-Primitiv, das dem gegebenen JavaScript Boolean entspricht.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein nicht-boolescher napi_value übergeben wird, gibt sie napi_boolean_expected zurück.

Diese API gibt das C boolean-Primitiv, das dem gegebenen JavaScript Boolean entspricht, zurück.

`napi_get_value_double`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der eine JavaScript-number darstellt.
[out] result: C double-Primitiv, das dem gegebenen JavaScript-number entspricht.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein Nicht-Number napi_value übergeben wird, gibt sie napi_number_expected zurück.

Diese API gibt das C double-Primitiv-Äquivalent der gegebenen JavaScript-number zurück.

`napi_get_value_bigint_int64`

Hinzugefügt in: v10.7.0

N-API Version: 6

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der eine JavaScript-BigInt darstellt.
[out] result: C int64_t-Primitiv, das dem gegebenen JavaScript-BigInt entspricht.
[out] lossless: Gibt an, ob der BigInt-Wert verlustfrei konvertiert wurde.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein Nicht-BigInt übergeben wird, gibt sie napi_bigint_expected zurück.

Diese API gibt das C int64_t-Primitiv-Äquivalent des gegebenen JavaScript-BigInt zurück. Falls nötig, wird der Wert abgeschnitten und lossless auf false gesetzt.

`napi_get_value_bigint_uint64`

Hinzugefügt in: v10.7.0

N-API Version: 6

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der eine JavaScript-BigInt darstellt.
[out] result: C uint64_t-Primitiv, das dem gegebenen JavaScript-BigInt entspricht.
[out] lossless: Gibt an, ob der BigInt-Wert verlustfrei konvertiert wurde.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein Nicht-BigInt übergeben wird, gibt sie napi_bigint_expected zurück.

Diese API gibt das C uint64_t-Primitiv-Äquivalent des gegebenen JavaScript-BigInt zurück. Falls nötig, wird der Wert abgeschnitten und lossless auf false gesetzt.

`napi_get_value_bigint_words`

Hinzugefügt in: v10.7.0

N-API Version: 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: Die Umgebung, in der die API aufgerufen wird.
[in] value: napi_value, das ein JavaScript BigInt darstellt.
[out] sign_bit: Ganzzahl, die angibt, ob das JavaScript BigInt positiv oder negativ ist.
[in/out] word_count: Muss auf die Länge des words-Arrays initialisiert werden. Nach der Rückgabe wird es auf die tatsächliche Anzahl der Wörter gesetzt, die zur Speicherung dieses BigInt benötigt würden.
[out] words: Zeiger auf ein vorab zugewiesenes 64-Bit-Wortarray.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API konvertiert einen einzelnen BigInt-Wert in ein Vorzeichenbit, ein 64-Bit-Little-Endian-Array und die Anzahl der Elemente im Array. sign_bit und words können beide auf NULL gesetzt werden, um nur word_count zu erhalten.

`napi_get_value_external`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, in der die API aufgerufen wird.
[in] value: napi_value, das einen externen JavaScript-Wert darstellt.
[out] result: Zeiger auf die Daten, die vom externen JavaScript-Wert gekapselt werden.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein nicht-externer napi_value übergeben wird, wird napi_invalid_arg zurückgegeben.

Diese API ruft den externen Datenzeiger ab, der zuvor an napi_create_external() übergeben wurde.

`napi_get_value_int32`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, in der die API aufgerufen wird.
[in] value: napi_value, das eine JavaScript number darstellt.
[out] result: C int32-Primitiv, das dem gegebenen JavaScript number entspricht.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein Nicht-Number napi_value übergeben wird, wird napi_number_expected zurückgegeben.

Diese API gibt das C int32-Primitiv, das dem gegebenen JavaScript number entspricht, zurück.

Wenn die Zahl den Bereich der 32-Bit-Ganzzahl überschreitet, wird das Ergebnis auf das Äquivalent der unteren 32 Bits gekürzt. Dies kann dazu führen, dass eine große positive Zahl zu einer negativen Zahl wird, wenn der Wert > 2³¹ - 1 ist.

Nicht-endliche Zahlenwerte (NaN, +Infinity oder -Infinity) setzen das Ergebnis auf null.

`napi_get_value_int64`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, das eine JavaScript-number darstellt.
[out] result: C int64-Primitiv, das dem gegebenen JavaScript-number entspricht.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein nicht-numerischer napi_value übergeben wird, wird napi_number_expected zurückgegeben.

Diese API gibt das C int64-Primitiv zurück, das dem gegebenen JavaScript-number entspricht.

number-Werte außerhalb des Bereichs von Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) verlieren an Genauigkeit.

Nicht-endliche Zahlenwerte (NaN, +Infinity oder -Infinity) setzen das Ergebnis auf null.

`napi_get_value_string_latin1`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_get_value_string_latin1(napi_env env,
                                         napi_value value,
                                         char* buf,
                                         size_t bufsize,
                                         size_t* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, das eine JavaScript-Zeichenkette darstellt.
[in] buf: Puffer zum Schreiben der ISO-8859-1-kodierten Zeichenkette. Wenn NULL übergeben wird, wird die Länge der Zeichenkette in Bytes ohne den Null-Terminator in result zurückgegeben.
[in] bufsize: Größe des Zielpuffers. Wenn dieser Wert unzureichend ist, wird die zurückgegebene Zeichenkette abgeschnitten und mit Null terminiert.
[out] result: Anzahl der in den Puffer kopierten Bytes, ohne den Null-Terminator.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein nicht-string napi_value übergeben wird, wird napi_string_expected zurückgegeben.

Diese API gibt die ISO-8859-1-kodierte Zeichenkette zurück, die dem übergebenen Wert entspricht.

`napi_get_value_string_utf8`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_get_value_string_utf8(napi_env env,
                                       napi_value value,
                                       char* buf,
                                       size_t bufsize,
                                       size_t* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der einen JavaScript-String darstellt.
[in] buf: Puffer zum Schreiben des UTF8-codierten Strings. Wenn NULL übergeben wird, wird die Länge des Strings in Bytes ohne Null-Terminator in result zurückgegeben.
[in] bufsize: Größe des Zielpuffers. Wenn dieser Wert nicht ausreicht, wird die zurückgegebene Zeichenkette abgeschnitten und mit Null terminiert.
[out] result: Anzahl der Bytes, die in den Puffer kopiert wurden, ohne den Null-Terminator.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein nicht-string napi_value übergeben wird, wird napi_string_expected zurückgegeben.

Diese API gibt den UTF8-codierten String zurück, der dem übergebenen Wert entspricht.

`napi_get_value_string_utf16`

Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, der einen JavaScript-String darstellt.
[in] buf: Puffer zum Schreiben des UTF16-LE-codierten Strings. Wenn NULL übergeben wird, wird die Länge des Strings in 2-Byte-Codeeinheiten ohne Null-Terminator zurückgegeben.
[in] bufsize: Größe des Zielpuffers. Wenn dieser Wert nicht ausreicht, wird die zurückgegebene Zeichenkette abgeschnitten und mit Null terminiert.
[out] result: Anzahl der 2-Byte-Codeeinheiten, die in den Puffer kopiert wurden, ohne den Null-Terminator.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein nicht-string napi_value übergeben wird, wird napi_string_expected zurückgegeben.

Diese API gibt den UTF16-codierten String zurück, der dem übergebenen Wert entspricht.

`napi_get_value_uint32`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: napi_value, das eine JavaScript-Zahl (number) darstellt.
[out] result: C-Primitiv-Äquivalent des gegebenen napi_value als uint32_t.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein napi_value, der keine Zahl ist, übergeben wird, gibt sie napi_number_expected zurück.

Diese API gibt das C-Primitiv-Äquivalent des gegebenen napi_value als uint32_t zurück.

Funktionen zum Abrufen globaler Instanzen

`napi_get_boolean`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der Wert des abzurufenden Booleans.
[out] result: napi_value, das das abzurufende JavaScript-Boolean-Singleton darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API wird verwendet, um das JavaScript-Singleton-Objekt zurückzugeben, das verwendet wird, um den gegebenen Boolean-Wert darzustellen.

`napi_get_global`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_get_global(napi_env env, napi_value* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: napi_value, das das JavaScript-global-Objekt darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt das global-Objekt zurück.

`napi_get_null`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_get_null(napi_env env, napi_value* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: napi_value, das das JavaScript-null-Objekt darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt das null-Objekt zurück.

`napi_get_undefined`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_get_undefined(napi_env env, napi_value* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: napi_value, das den JavaScript-undefined-Wert darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt das undefined-Objekt zurück.

Arbeiten mit JavaScript-Werten und abstrakten Operationen

Node-API stellt einen Satz von APIs bereit, um einige abstrakte Operationen an JavaScript-Werten durchzuführen. Einige dieser Operationen sind in Abschnitt 7 der ECMAScript Language Specification dokumentiert.

Diese APIs unterstützen die Durchführung einer der folgenden Aktionen:

`napi_coerce_to_bool`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der JavaScript-Wert, der konvertiert werden soll.
[out] result: napi_value, der den konvertierten JavaScript Boolean darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API implementiert die abstrakte Operation ToBoolean(), wie in Abschnitt 7.1.2 der ECMAScript Language Specification definiert.

`napi_coerce_to_number`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der JavaScript-Wert, der konvertiert werden soll.
[out] result: napi_value, der den konvertierten JavaScript number darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API implementiert die abstrakte Operation ToNumber(), wie in Abschnitt 7.1.3 der ECMAScript Language Specification definiert. Diese Funktion führt möglicherweise JS-Code aus, wenn der übergebene Wert ein Objekt ist.

`napi_coerce_to_object`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der JavaScript-Wert, der konvertiert werden soll.
[out] result: napi_value, der das konvertierte JavaScript Object darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API implementiert die abstrakte Operation ToObject(), wie in Abschnitt 7.1.13 der ECMAScript Language Specification definiert.

`napi_coerce_to_string`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der JavaScript-Wert, der konvertiert werden soll.
[out] result: napi_value, der den konvertierten JavaScript-string darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API implementiert die abstrakte Operation ToString(), wie in Abschnitt 7.1.13 der ECMAScript-Sprachspezifikation definiert. Diese Funktion führt möglicherweise JS-Code aus, wenn der übergebene Wert ein Objekt ist.

`napi_typeof`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der JavaScript-Wert, dessen Typ abgefragt werden soll.
[out] result: Der Typ des JavaScript-Werts.

Gibt napi_ok zurück, wenn die API erfolgreich war.

napi_invalid_arg, wenn der Typ von value kein bekannter ECMAScript-Typ ist und value kein externer Wert ist.

Diese API stellt ein ähnliches Verhalten dar wie der Aufruf des typeof-Operators für das Objekt, wie in Abschnitt 12.5.5 der ECMAScript-Sprachspezifikation definiert. Es gibt jedoch einige Unterschiede:

Wenn value einen ungültigen Typ hat, wird ein Fehler zurückgegeben.

`napi_instanceof`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] object: Der zu prüfende JavaScript-Wert.
[in] constructor: Das JavaScript-Funktionsobjekt der zu prüfenden Konstruktorfunktion.
[out] result: Boolean, der auf true gesetzt wird, wenn object instanceof constructor true ist.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API stellt den Aufruf des instanceof-Operators für das Objekt dar, wie in Abschnitt 12.10.4 der ECMAScript-Sprachspezifikation definiert.

`napi_is_array`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu überprüfende JavaScript-Wert.
[out] result: Ob das gegebene Objekt ein Array ist.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API repräsentiert den Aufruf der IsArray-Operation auf dem Objekt, wie in Abschnitt 7.2.2 der ECMAScript Language Specification definiert.

`napi_is_arraybuffer`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu überprüfende JavaScript-Wert.
[out] result: Ob das gegebene Objekt ein ArrayBuffer ist.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API prüft, ob das übergebene Object ein ArrayBuffer ist.

`napi_is_buffer`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu überprüfende JavaScript-Wert.
[out] result: Ob der gegebene napi_value ein node::Buffer oder Uint8Array Objekt repräsentiert.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API prüft, ob das übergebene Object ein Buffer oder Uint8Array ist. napi_is_typedarray sollte bevorzugt werden, wenn der Aufrufer prüfen muss, ob der Wert ein Uint8Array ist.

`napi_is_date`

Hinzugefügt in: v11.11.0, v10.17.0

N-API Version: 5

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu überprüfende JavaScript-Wert.
[out] result: Ob der gegebene napi_value ein JavaScript Date Objekt repräsentiert.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API prüft, ob das übergebene Object ein Datum ist.

`napi_is_error`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu prüfende JavaScript-Wert.
[out] result: Ob der gegebene napi_value ein Error-Objekt darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API prüft, ob das übergebene Object ein Error ist.

`napi_is_typedarray`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu prüfende JavaScript-Wert.
[out] result: Ob der gegebene napi_value ein TypedArray darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API prüft, ob das übergebene Object ein Typed Array ist.

`napi_is_dataview`

Hinzugefügt in: v8.3.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu prüfende JavaScript-Wert.
[out] result: Ob der gegebene napi_value ein DataView darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API prüft, ob das übergebene Object ein DataView ist.

`napi_strict_equals`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] lhs: Der zu prüfende JavaScript-Wert.
[in] rhs: Der JavaScript-Wert, mit dem verglichen werden soll.
[out] result: Ob die beiden napi_value-Objekte gleich sind.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API repräsentiert den Aufruf des Strict Equality Algorithmus, wie er in Abschnitt 7.2.14 der ECMAScript Language Specification definiert ist.

`napi_detach_arraybuffer`

Hinzugefügt in: v13.0.0, v12.16.0, v10.22.0

N-API Version: 7

napi_status napi_detach_arraybuffer(napi_env env,
                                    napi_value arraybuffer)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] arraybuffer: Der JavaScript ArrayBuffer, der getrennt werden soll.

Gibt napi_ok zurück, wenn die API erfolgreich war. Wenn ein nicht trennbarer ArrayBuffer übergeben wird, wird napi_detachable_arraybuffer_expected zurückgegeben.

Im Allgemeinen ist ein ArrayBuffer nicht trennbar, wenn er zuvor bereits getrennt wurde. Die Engine kann zusätzliche Bedingungen dafür festlegen, ob ein ArrayBuffer trennbar ist. Beispielsweise erfordert V8, dass der ArrayBuffer extern ist, d. h. mit napi_create_external_arraybuffer erstellt wurde.

Diese API stellt den Aufruf der ArrayBuffer-Trennoperation dar, wie in Abschnitt 24.1.1.3 der ECMAScript-Sprachspezifikation definiert.

`napi_is_detached_arraybuffer`

Hinzugefügt in: v13.3.0, v12.16.0, v10.22.0

N-API Version: 7

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] arraybuffer: Der zu überprüfende JavaScript ArrayBuffer.
[out] result: Ob der arraybuffer getrennt ist.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Der ArrayBuffer gilt als getrennt, wenn seine internen Daten null sind.

Diese API stellt den Aufruf der ArrayBuffer IsDetachedBuffer-Operation dar, wie in Abschnitt 24.1.1.2 der ECMAScript-Sprachspezifikation definiert.

Arbeiten mit JavaScript-Eigenschaften

Node-API stellt einen Satz von APIs bereit, um Eigenschaften von JavaScript-Objekten abzurufen und festzulegen. Einige dieser Typen sind unter Abschnitt 7 der ECMAScript-Sprachspezifikation dokumentiert.

Eigenschaften in JavaScript werden als Tupel aus Schlüssel und Wert dargestellt. Grundsätzlich können alle Eigenschaftsschlüssel in Node-API in einer der folgenden Formen dargestellt werden:

Benannt: eine einfache UTF8-kodierte Zeichenkette
Integer-indiziert: ein Indexwert, der durch uint32_t dargestellt wird
JavaScript-Wert: Diese werden in Node-API durch napi_value dargestellt. Dies kann ein napi_value sein, der eine string, number oder symbol darstellt.

Node-API-Werte werden durch den Typ napi_value dargestellt. Jeder Node-API-Aufruf, der einen JavaScript-Wert erfordert, nimmt einen napi_value entgegen. Es liegt jedoch in der Verantwortung des Aufrufers, sicherzustellen, dass der betreffende napi_value vom JavaScript-Typ ist, der von der API erwartet wird.

Die in diesem Abschnitt dokumentierten APIs bieten eine einfache Schnittstelle zum Abrufen und Festlegen von Eigenschaften beliebiger JavaScript-Objekte, die durch napi_value dargestellt werden.

Betrachten Sie beispielsweise den folgenden JavaScript-Code-Snippet:

const obj = {}
obj.myProp = 123

Das Äquivalent kann mit Node-API-Werten mit dem folgenden Snippet durchgeführt werden:

napi_status status = napi_generic_failure;

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

// Create a napi_value for 123
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;

// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status;

Indizierte Eigenschaften können auf ähnliche Weise gesetzt werden. Betrachten Sie den folgenden JavaScript-Snippet:

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

Das Äquivalent kann mit Node-API-Werten mit dem folgenden Snippet durchgeführt werden:

napi_status status = napi_generic_failure;

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

// Create a napi_value for 'hello'
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;

// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status;

Eigenschaften können mit den in diesem Abschnitt beschriebenen APIs abgerufen werden. Betrachten Sie den folgenden JavaScript-Snippet:

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

Das Folgende ist das ungefähre Äquivalent des Node-API-Gegenstücks:

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;

Schließlich können aus Performancegründen auch mehrere Eigenschaften für ein Objekt definiert werden. Betrachten Sie das folgende JavaScript:

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

Das Folgende ist das ungefähre Äquivalent des Node-API-Gegenstücks:

napi_status status = napi_status_generic_failure;

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

// Create napi_values for 123 and 456
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;

// Set the properties
napi_property_descriptor descriptors[] = {
  { "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
  { "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
                                obj,
                                sizeof(descriptors) / sizeof(descriptors[0]),
                                descriptors);
if (status != napi_ok) return status;

Strukturen

`napi_property_attributes`

[Historie]

Version	Änderungen
v14.12.0	`napi_default_method` und `napi_default_property` hinzugefügt.

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

  // Wird mit napi_define_class verwendet, um statische Eigenschaften
  // von Instanzeigenschaften zu unterscheiden. Wird von napi_define_properties ignoriert.
  napi_static = 1 << 10,

  // Standard für Klassenmethoden.
  napi_default_method = napi_writable | napi_configurable,

  // Standard für Objekteigenschaften, wie in JS obj[prop].
  napi_default_jsproperty = napi_writable |
                          napi_enumerable |
                          napi_configurable,
} napi_property_attributes;

napi_property_attributes sind Flags, die verwendet werden, um das Verhalten von Eigenschaften zu steuern, die auf einem JavaScript-Objekt gesetzt werden. Abgesehen von napi_static entsprechen sie den in Abschnitt 6.1.7.1 der ECMAScript Language Specification aufgeführten Attributen. Sie können eines oder mehrere der folgenden Bitflags sein:

napi_default: Es werden keine expliziten Attribute auf die Eigenschaft gesetzt. Standardmäßig ist eine Eigenschaft schreibgeschützt, nicht aufzählbar und nicht konfigurierbar.
napi_writable: Die Eigenschaft ist schreibbar.
napi_enumerable: Die Eigenschaft ist aufzählbar.
napi_configurable: Die Eigenschaft ist konfigurierbar, wie in Abschnitt 6.1.7.1 der ECMAScript Language Specification definiert.
napi_static: Die Eigenschaft wird als statische Eigenschaft einer Klasse im Gegensatz zu einer Instanzeigenschaft definiert, was die Standardeinstellung ist. Dies wird nur von napi_define_class verwendet. Es wird von napi_define_properties ignoriert.
napi_default_method: Wie eine Methode in einer JS-Klasse ist die Eigenschaft konfigurierbar und schreibbar, aber nicht aufzählbar.
napi_default_jsproperty: Wie eine Eigenschaft, die über eine Zuweisung in JavaScript gesetzt wird, ist die Eigenschaft schreibbar, aufzählbar und konfigurierbar.

`napi_property_descriptor`

typedef struct {
  // Einer von utf8name oder name sollte NULL sein.
  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: Optionale Zeichenkette, die den Schlüssel für die Eigenschaft beschreibt, codiert als UTF8. Einer von utf8name oder name muss für die Eigenschaft angegeben werden.
name: Optionaler napi_value, der auf einen JavaScript-String oder ein Symbol verweist, das als Schlüssel für die Eigenschaft verwendet werden soll. Einer von utf8name oder name muss für die Eigenschaft angegeben werden.
value: Der Wert, der bei einem Lesezugriff auf die Eigenschaft abgerufen wird, wenn die Eigenschaft eine Dateneigenschaft ist. Wenn dieser Wert übergeben wird, setzen Sie getter, setter, method und data auf NULL (da diese Member nicht verwendet werden).
getter: Eine Funktion, die aufgerufen wird, wenn ein Lesezugriff auf die Eigenschaft durchgeführt wird. Wenn dieser Wert übergeben wird, setzen Sie value und method auf NULL (da diese Member nicht verwendet werden). Die angegebene Funktion wird implizit von der Laufzeit aufgerufen, wenn auf die Eigenschaft aus JavaScript-Code zugegriffen wird (oder wenn ein Lesezugriff auf die Eigenschaft mit einem Node-API-Aufruf durchgeführt wird). napi_callback enthält weitere Details.
setter: Eine Funktion, die aufgerufen wird, wenn ein Schreibzugriff auf die Eigenschaft durchgeführt wird. Wenn dieser Wert übergeben wird, setzen Sie value und method auf NULL (da diese Member nicht verwendet werden). Die angegebene Funktion wird implizit von der Laufzeit aufgerufen, wenn die Eigenschaft aus JavaScript-Code gesetzt wird (oder wenn ein Schreibzugriff auf die Eigenschaft mit einem Node-API-Aufruf durchgeführt wird). napi_callback enthält weitere Details.
method: Setzen Sie dies, um die value-Eigenschaft des Eigenschaftsbeschreibungsobjekts zu einer JavaScript-Funktion zu machen, die durch method dargestellt wird. Wenn dieser Wert übergeben wird, setzen Sie value, getter und setter auf NULL (da diese Member nicht verwendet werden). napi_callback enthält weitere Details.
attributes: Die Attribute, die der jeweiligen Eigenschaft zugeordnet sind. Siehe napi_property_attributes.
data: Die Rückruffunktionsdaten, die an method, getter und setter übergeben werden, wenn diese Funktion aufgerufen wird.

Funktionen

`napi_get_property_names`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, von dem die Eigenschaften abgerufen werden sollen.
[out] result: Ein napi_value, das ein Array von JavaScript-Werten darstellt, die die Eigenschaftsnamen des Objekts repräsentieren. Die API kann verwendet werden, um mit napi_get_array_length und napi_get_element über result zu iterieren.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt die Namen der aufzählbaren Eigenschaften von object als ein Array von Strings zurück. Die Eigenschaften von object, deren Schlüssel ein Symbol ist, werden nicht enthalten sein.

`napi_get_all_property_names`

Hinzugefügt in: v13.7.0, v12.17.0, v10.20.0

N-API Version: 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: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, von dem die Eigenschaften abgerufen werden sollen.
[in] key_mode: Ob auch Prototyp-Eigenschaften abgerufen werden sollen.
[in] key_filter: Welche Eigenschaften abgerufen werden sollen (aufzählbar/lesbar/beschreibbar).
[in] key_conversion: Ob nummerierte Eigenschaften-Schlüssel in Strings konvertiert werden sollen.
[out] result: Ein napi_value, das ein Array von JavaScript-Werten darstellt, die die Eigenschaftsnamen des Objekts repräsentieren. napi_get_array_length und napi_get_element können verwendet werden, um über result zu iterieren.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt ein Array zurück, das die Namen der verfügbaren Eigenschaften dieses Objekts enthält.

`napi_set_property`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, dem die Eigenschaft hinzugefügt werden soll.
[in] key: Der Name der Eigenschaft.
[in] value: Der Wert der Eigenschaft.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API setzt eine Eigenschaft auf dem übergebenen Object.

`napi_get_property`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, aus dem die Eigenschaft abgerufen werden soll.
[in] key: Der Name der Eigenschaft, die abgerufen werden soll.
[out] result: Der Wert der Eigenschaft.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API ruft die angeforderte Eigenschaft aus dem übergebenen Object ab.

`napi_has_property`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das abzufragende Objekt.
[in] key: Der Name der Eigenschaft, deren Existenz geprüft werden soll.
[out] result: Ob die Eigenschaft im Objekt existiert oder nicht.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API prüft, ob das übergebene Object die benannte Eigenschaft besitzt.

`napi_delete_property`

Hinzugefügt in: v8.2.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das abzufragende Objekt.
[in] key: Der Name der zu löschenden Eigenschaft.
[out] result: Ob das Löschen der Eigenschaft erfolgreich war oder nicht. result kann optional ignoriert werden, indem NULL übergeben wird.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API versucht, die eigene Eigenschaft key aus object zu löschen.

`napi_has_own_property`

Hinzugefügt in: v8.2.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das abzufragende Objekt.
[in] key: Der Name der eigenen Eigenschaft, deren Existenz geprüft werden soll.
[out] result: Ob die eigene Eigenschaft im Objekt vorhanden ist oder nicht.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API prüft, ob das übergebene Object die benannte eigene Eigenschaft besitzt. key muss ein string oder ein symbol sein, andernfalls wird ein Fehler ausgelöst. Node-API führt keine Typkonvertierung durch.

`napi_set_named_property`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, auf dem die Eigenschaft gesetzt werden soll.
[in] utf8Name: Der Name der zu setzenden Eigenschaft.
[in] value: Der Wert der Eigenschaft.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode entspricht einem Aufruf von napi_set_property mit einem napi_value, das aus dem als utf8Name übergebenen String erstellt wurde.

`napi_get_named_property`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, aus dem die Eigenschaft abgerufen werden soll.
[in] utf8Name: Der Name der abzurufenden Eigenschaft.
[out] result: Der Wert der Eigenschaft.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode entspricht einem Aufruf von napi_get_property mit einem napi_value, das aus dem als utf8Name übergebenen String erstellt wurde.

`napi_has_named_property`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das abzufragende Objekt.
[in] utf8Name: Der Name der Eigenschaft, deren Existenz geprüft werden soll.
[out] result: Ob die Eigenschaft im Objekt vorhanden ist oder nicht.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode entspricht dem Aufruf von napi_has_property mit einem napi_value, der aus der als utf8Name übergebenen Zeichenkette erstellt wurde.

`napi_set_element`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, aus dem die Eigenschaften gesetzt werden sollen.
[in] index: Der Index der zu setzenden Eigenschaft.
[in] value: Der Wert der Eigenschaft.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API setzt ein Element im übergebenen Object.

`napi_get_element`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, aus dem die Eigenschaft abgerufen werden soll.
[in] index: Der Index der abzurufenden Eigenschaft.
[out] result: Der Wert der Eigenschaft.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API ruft das Element am angeforderten Index ab.

`napi_has_element`

Hinzugefügt in: v8.0.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der der Node-API-Aufruf ausgeführt wird.
[in] object: Das abzufragende Objekt.
[in] index: Der Index der Eigenschaft, deren Existenz geprüft werden soll.
[out] result: Ob die Eigenschaft im Objekt vorhanden ist oder nicht.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt zurück, ob das übergebene Object ein Element am angeforderten Index hat.

`napi_delete_element`

Hinzugefügt in: v8.2.0

N-API Version: 1

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

[in] env: Die Umgebung, in der der Node-API-Aufruf ausgeführt wird.
[in] object: Das abzufragende Objekt.
[in] index: Der Index der zu löschenden Eigenschaft.
[out] result: Ob das Löschen des Elements erfolgreich war oder nicht. result kann optional ignoriert werden, indem NULL übergeben wird.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API versucht, den angegebenen index aus object zu löschen.

`napi_define_properties`

Hinzugefügt in: v8.0.0

N-API Version: 1

napi_status napi_define_properties(napi_env env,
                                   napi_value object,
                                   size_t property_count,
                                   const napi_property_descriptor* properties);

[in] env: Die Umgebung, in der der Node-API-Aufruf ausgeführt wird.
[in] object: Das Objekt, aus dem die Eigenschaften abgerufen werden sollen.
[in] property_count: Die Anzahl der Elemente im properties-Array.
[in] properties: Das Array der Eigenschaftsdeskriptoren.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode ermöglicht die effiziente Definition mehrerer Eigenschaften für ein gegebenes Objekt. Die Eigenschaften werden mithilfe von Eigenschaftsdeskriptoren definiert (siehe napi_property_descriptor). Angesichts eines Arrays solcher Eigenschaftsdeskriptoren setzt diese API die Eigenschaften nacheinander auf das Objekt, wie von DefineOwnProperty() definiert (beschrieben in Abschnitt 9.1.6 der ECMA-262-Spezifikation).

`napi_object_freeze`

Hinzugefügt in: v14.14.0, v12.20.0

N-API Version: 8

napi_status napi_object_freeze(napi_env env,
                               napi_value object);

[in] env: Die Umgebung, in der der Node-API-Aufruf ausgeführt wird.
[in] object: Das einzufrierende Objekt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode friert ein gegebenes Objekt ein. Dies verhindert, dass neue Eigenschaften hinzugefügt, vorhandene Eigenschaften entfernt oder die Aufzählbarkeit, Konfigurierbarkeit oder Schreibfähigkeit vorhandener Eigenschaften geändert werden, und verhindert, dass die Werte vorhandener Eigenschaften geändert werden. Es verhindert auch, dass der Prototyp des Objekts geändert wird. Dies wird in Abschnitt 19.1.2.6 der ECMA-262-Spezifikation beschrieben.

`napi_object_seal`

Hinzugefügt in: v14.14.0, v12.20.0

N-API-Version: 8

napi_status napi_object_seal(napi_env env,
                             napi_value object);

[in] env: Die Umgebung, unter der der Node-API-Aufruf erfolgt.
[in] object: Das zu versiegelnde Objekt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode versiegelt ein gegebenes Objekt. Dies verhindert das Hinzufügen neuer Eigenschaften und markiert alle vorhandenen Eigenschaften als nicht konfigurierbar. Dies wird in Abschnitt 19.1.2.20 der ECMA-262-Spezifikation beschrieben.

Arbeiten mit JavaScript-Funktionen

Node-API bietet einen Satz von APIs, die es JavaScript-Code ermöglichen, in nativen Code zurückzurufen. Node-APIs, die das Zurückrufen in nativen Code unterstützen, nehmen Callback-Funktionen entgegen, die durch den Typ napi_callback dargestellt werden. Wenn die JavaScript-VM in nativen Code zurückruft, wird die bereitgestellte napi_callback-Funktion aufgerufen. Die in diesem Abschnitt dokumentierten APIs ermöglichen es der Callback-Funktion Folgendes zu tun:

Informationen über den Kontext abrufen, in dem der Callback aufgerufen wurde.
Die an den Callback übergebenen Argumente abrufen.
Einen napi_value vom Callback zurückgeben.

Zusätzlich bietet Node-API eine Reihe von Funktionen, die das Aufrufen von JavaScript-Funktionen aus nativem Code ermöglichen. Man kann eine Funktion entweder wie einen regulären JavaScript-Funktionsaufruf oder als Konstruktorfunktion aufrufen.

Alle Nicht-NULL-Daten, die über das data-Feld der napi_property_descriptor-Elemente an diese API übergeben werden, können mit object verknüpft und freigegeben werden, wenn object durch die Garbage Collection freigegeben wird, indem sowohl object als auch die Daten an napi_add_finalizer übergeben werden.

`napi_call_function`

Hinzugefügt in: v8.0.0

N-API-Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] recv: Der this-Wert, der an die aufgerufene Funktion übergeben wird.
[in] func: napi_value, die die aufzurufende JavaScript-Funktion darstellt.
[in] argc: Die Anzahl der Elemente im argv-Array.
[in] argv: Array von napi_values, die JavaScript-Werte darstellen, die als Argumente an die Funktion übergeben werden.
[out] result: napi_value, die das zurückgegebene JavaScript-Objekt darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode ermöglicht den Aufruf eines JavaScript-Funktionsobjekts von einem nativen Add-on aus. Dies ist der primäre Mechanismus, um vom nativen Code des Add-ons zurück in JavaScript zu rufen. Für den Sonderfall des Aufrufs in JavaScript nach einer asynchronen Operation siehe napi_make_callback.

Ein Beispiel-Anwendungsfall könnte wie folgt aussehen. Betrachten Sie das folgende JavaScript-Snippet:

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

Dann kann die obige Funktion von einem nativen Add-on mit folgendem Code aufgerufen werden:

// Ruft die Funktion "AddTwo" im globalen Objekt ab
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;

// Konvertiert das Ergebnis zurück in einen nativen Typ
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;

`napi_create_function`

Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] utf8Name: Optionaler Name der Funktion, codiert als UTF8. Dieser ist in JavaScript als name-Eigenschaft des neuen Funktionsobjekts sichtbar.
[in] length: Die Länge von utf8name in Bytes oder NAPI_AUTO_LENGTH, wenn es null-terminiert ist.
[in] cb: Die native Funktion, die aufgerufen werden soll, wenn dieses Funktionsobjekt aufgerufen wird. napi_callback bietet weitere Details.
[in] data: Vom Benutzer bereitgestellter Datenkontext. Dieser wird später beim Aufruf der Funktion zurückgegeben.
[out] result: napi_value, die das JavaScript-Funktionsobjekt für die neu erstellte Funktion darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API ermöglicht es einem Add-on-Autor, ein Funktionsobjekt in nativem Code zu erstellen. Dies ist der primäre Mechanismus, um das Aufrufen von in den nativen Code des Add-ons von JavaScript aus zu ermöglichen.

Die neu erstellte Funktion ist nach diesem Aufruf nicht automatisch aus dem Skript sichtbar. Stattdessen muss eine Eigenschaft explizit für jedes Objekt gesetzt werden, das für JavaScript sichtbar ist, damit die Funktion aus dem Skript zugänglich ist.

Um eine Funktion als Teil der Modulexporte des Add-ons verfügbar zu machen, setzen Sie die neu erstellte Funktion auf das Export-Objekt. Ein Beispielmodul könnte wie folgt aussehen:

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)

Mit dem obigen Code kann das Add-on wie folgt aus JavaScript verwendet werden:

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

Die Zeichenkette, die an require() übergeben wird, ist der Name des Ziels in binding.gyp, das für die Erstellung der .node-Datei verantwortlich ist.

Alle nicht-NULL-Daten, die über den Parameter data an diese API übergeben werden, können dem resultierenden JavaScript-Funktionsobjekt (das im Parameter result zurückgegeben wird) zugeordnet und freigegeben werden, wenn die Funktion durch die Garbage Collection freigegeben wird, indem sowohl die JavaScript-Funktion als auch die Daten an napi_add_finalizer übergeben werden.

JavaScript Functions werden in Abschnitt 19.2 der ECMAScript-Sprachspezifikation beschrieben.

`napi_get_cb_info`

Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] cbinfo: Die Callback-Informationen, die an die Callback-Funktion übergeben werden.
[in-out] argc: Gibt die Länge des bereitgestellten argv-Arrays an und empfängt die tatsächliche Anzahl der Argumente. argc kann optional ignoriert werden, indem NULL übergeben wird.
[out] argv: C-Array von napi_values, in das die Argumente kopiert werden. Wenn mehr Argumente als die angegebene Anzahl vorhanden sind, werden nur die angeforderte Anzahl von Argumenten kopiert. Wenn weniger Argumente als angegeben bereitgestellt werden, wird der Rest von argv mit napi_value-Werten gefüllt, die undefined darstellen. argv kann optional ignoriert werden, indem NULL übergeben wird.
[out] thisArg: Empfängt das JavaScript this-Argument für den Aufruf. thisArg kann optional ignoriert werden, indem NULL übergeben wird.
[out] data: Empfängt den Datenzeiger für den Callback. data kann optional ignoriert werden, indem NULL übergeben wird.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode wird innerhalb einer Callback-Funktion verwendet, um Details über den Aufruf wie die Argumente und den this-Zeiger aus gegebenen Callback-Informationen abzurufen.

`napi_get_new_target`

Hinzugefügt in: v8.6.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] cbinfo: Die Callback-Informationen, die an die Callback-Funktion übergeben werden.
[out] result: Das new.target des Konstruktoraufrufs.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt das new.target des Konstruktoraufrufs zurück. Wenn der aktuelle Callback kein Konstruktoraufruf ist, ist das Ergebnis NULL.

`napi_new_instance`

Hinzugefügt in: v8.0.0

N-API-Version: 1

napi_status napi_new_instance(napi_env env,
                              napi_value cons,
                              size_t argc,
                              napi_value* argv,
                              napi_value* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] cons: napi_value, der die JavaScript-Funktion darstellt, die als Konstruktor aufgerufen werden soll.
[in] argc: Die Anzahl der Elemente im argv-Array.
[in] argv: Array von JavaScript-Werten als napi_value, die die Argumente des Konstruktors darstellen. Wenn argc null ist, kann dieser Parameter durch Übergabe von NULL weggelassen werden.
[out] result: napi_value, der das zurückgegebene JavaScript-Objekt darstellt, in diesem Fall das konstruierte Objekt.

Diese Methode wird verwendet, um einen neuen JavaScript-Wert unter Verwendung eines gegebenen napi_value zu instanziieren, der den Konstruktor für das Objekt darstellt. Betrachten Sie beispielsweise das folgende Snippet:

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

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

Das Folgende kann in Node-API mit dem folgenden Snippet approximiert werden:

// Ruft die Konstruktorfunktion MyObject ab
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);

Gibt napi_ok zurück, wenn die API erfolgreich war.

Objekt-Wrapping

Node-API bietet eine Möglichkeit, C++-Klassen und -Instanzen zu "wrappen", so dass der Klassenkonstruktor und die Methoden von JavaScript aus aufgerufen werden können.

Bei gewrapten Objekten kann es schwierig sein, zwischen einer Funktion, die auf einem Klassenprototyp aufgerufen wird, und einer Funktion, die auf einer Instanz einer Klasse aufgerufen wird, zu unterscheiden. Ein gängiges Muster, um dieses Problem zu beheben, besteht darin, eine persistente Referenz auf den Klassenkonstruktor für spätere instanceof-Prüfungen zu speichern.

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

Die Referenz muss freigegeben werden, sobald sie nicht mehr benötigt wird.

Es gibt Fälle, in denen napi_instanceof() nicht ausreicht, um sicherzustellen, dass ein JavaScript-Objekt ein Wrapper für einen bestimmten nativen Typ ist. Dies ist insbesondere dann der Fall, wenn gewrapte JavaScript-Objekte über statische Methoden an das Addon zurückgegeben werden und nicht als this-Wert von Prototypenmethoden. In solchen Fällen besteht die Möglichkeit, dass sie falsch entpackt werden.

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

// `openDatabase()` gibt ein JavaScript-Objekt zurück, das einen nativen Datenbank-
// Handle wrapped.
const dbHandle = myAddon.openDatabase()

// `query()` gibt ein JavaScript-Objekt zurück, das einen nativen Query-Handle wrapped.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')

// Es gibt einen versehentlichen Fehler in der Zeile unten. Der erste Parameter von
// `myAddon.queryHasRecords()` sollte der Datenbank-Handle (`dbHandle`) sein, nicht
// der Query-Handle (`query`), daher sollte die korrekte Bedingung für die while-Schleife
// lauten:
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
  // Datensätze abrufen
}

Im obigen Beispiel ist myAddon.queryHasRecords() eine Methode, die zwei Argumente akzeptiert. Das erste ist ein Datenbank-Handle und das zweite ist ein Query-Handle. Intern entpackt es das erste Argument und konvertiert den resultierenden Zeiger in einen nativen Datenbank-Handle. Dann entpackt es das zweite Argument und konvertiert den resultierenden Zeiger in einen Query-Handle. Wenn die Argumente in der falschen Reihenfolge übergeben werden, funktionieren die Konvertierungen, es besteht jedoch eine gute Chance, dass die zugrunde liegende Datenbankoperation fehlschlägt oder sogar einen ungültigen Speicherzugriff verursacht.

Um sicherzustellen, dass der vom ersten Argument abgerufene Zeiger tatsächlich ein Zeiger auf einen Datenbank-Handle ist und ähnlich, dass der vom zweiten Argument abgerufene Zeiger tatsächlich ein Zeiger auf einen Query-Handle ist, muss die Implementierung von queryHasRecords() eine Typvalidierung durchführen. Das Beibehalten des JavaScript-Klassenkonstruktors, von dem der Datenbank-Handle instanziiert wurde, und des Konstruktors, von dem der Query-Handle instanziiert wurde, in napi_refs kann hilfreich sein, da napi_instanceof() dann verwendet werden kann, um sicherzustellen, dass die an queryHashRecords() übergebenen Instanzen tatsächlich vom richtigen Typ sind.

Leider schützt napi_instanceof() nicht vor Prototypenmanipulation. Beispielsweise kann der Prototyp der Datenbank-Handle-Instanz auf den Prototyp des Konstruktors für Query-Handle-Instanzen gesetzt werden. In diesem Fall kann die Datenbank-Handle-Instanz als Query-Handle-Instanz erscheinen und den napi_instanceof()-Test für eine Query-Handle-Instanz bestehen, während sie immer noch einen Zeiger auf einen Datenbank-Handle enthält.

Zu diesem Zweck bietet Node-API Typ-Tagging-Funktionen.

Ein Typ-Tag ist eine 128-Bit-Ganzzahl, die für das Addon eindeutig ist. Node-API stellt die Struktur napi_type_tag zum Speichern eines Typ-Tags bereit. Wenn ein solcher Wert zusammen mit einem JavaScript-Objekt oder externen Wert, der in einem napi_value gespeichert ist, an napi_type_tag_object() übergeben wird, wird das JavaScript-Objekt mit dem Typ-Tag "gekennzeichnet". Die "Markierung" ist auf der JavaScript-Seite unsichtbar. Wenn ein JavaScript-Objekt in ein natives Binding gelangt, kann napi_check_object_type_tag() zusammen mit dem ursprünglichen Typ-Tag verwendet werden, um festzustellen, ob das JavaScript-Objekt zuvor mit dem Typ-Tag "gekennzeichnet" wurde. Dies schafft eine Typprüfungsfähigkeit mit einer höheren Genauigkeit als napi_instanceof() bieten kann, da ein solches Typ-Tagging die Prototypenmanipulation und das Entladen/Neuladen des Addons überdauert.

Im folgenden Beispiel wird die Verwendung von napi_type_tag_object() und napi_check_object_type_tag() veranschaulicht.

// Dieser Wert ist das Typ-Tag für einen Datenbank-Handle. Der Befehl
//
//   uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// kann verwendet werden, um die beiden Werte zu erhalten, mit denen die Struktur initialisiert werden soll.
static const napi_type_tag DatabaseHandleTypeTag = {
  0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};

// Dieser Wert ist das Typ-Tag für einen Query-Handle.
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;

  // Führt die zugrunde liegende Aktion aus, die zu einem Datenbank-Handle führt.
  DatabaseHandle* dbHandle = open_database();

  // Erstellt ein neues, leeres JS-Objekt.
  status = napi_create_object(env, &result);
  if (status != napi_ok) return NULL;

  // Markiert das Objekt, um anzuzeigen, dass es einen Zeiger auf einen `DatabaseHandle` enthält.
  status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
  if (status != napi_ok) return NULL;

  // Speichert den Zeiger auf die `DatabaseHandle`-Struktur im JS-Objekt.
  status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
  if (status != napi_ok) return NULL;

  return result;
}

// Später, wenn wir ein JavaScript-Objekt erhalten, das angeblich ein Datenbank-Handle ist,
// können wir `napi_check_object_type_tag()` verwenden, um sicherzustellen, dass es tatsächlich ein solches Handle ist.

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;

  // Überprüft, ob das als erster Parameter übergebene Objekt das zuvor
  // angewendete Tag hat.
  status = napi_check_object_type_tag(env,
                                      argv[0],
                                      &DatabaseHandleTypeTag,
                                      &is_db_handle);
  if (status != napi_ok) return NULL;

  // Wirft einen `TypeError`, wenn dies nicht der Fall ist.
  if (!is_db_handle) {
    // Wirft einen TypeError.
    return NULL;
  }
}

`napi_define_class`

Hinzugefügt in: v8.0.0

N-API-Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] utf8name: Name der JavaScript-Konstruktorfunktion. Der Übersichtlichkeit halber wird empfohlen, den C++-Klassennamen zu verwenden, wenn eine C++-Klasse gekapselt wird.
[in] length: Die Länge von utf8name in Bytes oder NAPI_AUTO_LENGTH, wenn es nullterminiert ist.
[in] constructor: Callback-Funktion, die das Konstruieren von Instanzen der Klasse behandelt. Beim Kapseln einer C++-Klasse muss diese Methode ein statisches Mitglied mit der Signatur napi_callback sein. Ein C++-Klassenkonstruktor kann nicht verwendet werden. napi_callback bietet weitere Details.
[in] data: Optionale Daten, die an den Konstruktor-Callback als data-Eigenschaft der Callback-Informationen übergeben werden sollen.
[in] property_count: Anzahl der Elemente im properties-Array-Argument.
[in] properties: Array von Eigenschaftsdeskriptoren, die statische und Instanz-Daten-Eigenschaften, Accessoren und Methoden der Klasse beschreiben. Siehe napi_property_descriptor.
[out] result: Ein napi_value, der die Konstruktorfunktion für die Klasse darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Definiert eine JavaScript-Klasse, einschließlich:

Einer JavaScript-Konstruktorfunktion, die den Klassennamen hat. Beim Kapseln einer entsprechenden C++-Klasse kann der über constructor übergebene Callback verwendet werden, um eine neue C++-Klasseninstanz zu erstellen, die dann mithilfe von napi_wrap in die erstellte JavaScript-Objektinstanz eingefügt werden kann.
Eigenschaften der Konstruktorfunktion, deren Implementierung entsprechende statische Daten-Eigenschaften, Accessoren und Methoden der C++-Klasse aufrufen kann (definiert durch Eigenschaftsdeskriptoren mit dem Attribut napi_static).
Eigenschaften des prototype-Objekts der Konstruktorfunktion. Beim Kapseln einer C++-Klasse können nicht-statische Daten-Eigenschaften, Accessoren und Methoden der C++-Klasse von den in den Eigenschaftsdeskriptoren angegebenen statischen Funktionen ohne das Attribut napi_static aufgerufen werden, nachdem die in der JavaScript-Objektinstanz platzierte C++-Klasseninstanz mithilfe von napi_unwrap abgerufen wurde.

Beim Kapseln einer C++-Klasse sollte der über constructor übergebene C++-Konstruktor-Callback eine statische Methode der Klasse sein, die den eigentlichen Klassenkonstruktor aufruft, die neue C++-Instanz dann in einem JavaScript-Objekt kapselt und das Wrapper-Objekt zurückgibt. Siehe napi_wrap für Details.

Die von napi_define_class zurückgegebene JavaScript-Konstruktorfunktion wird oft gespeichert und später verwendet, um neue Instanzen der Klasse aus nativem Code zu erstellen und/oder zu überprüfen, ob bereitgestellte Werte Instanzen der Klasse sind. In diesem Fall kann eine starke persistente Referenz darauf mit napi_create_reference erstellt werden, um sicherzustellen, dass der Referenzzähler >= 1 bleibt, um zu verhindern, dass der Funktionswert garbage-collected wird.

Alle nicht-NULL-Daten, die über den Parameter data oder über das Feld data der Elemente des Arrays napi_property_descriptor an diese API übergeben werden, können dem resultierenden JavaScript-Konstruktor (der im Parameter result zurückgegeben wird) zugeordnet und freigegeben werden, wenn die Klasse durch Garbage Collection entfernt wird, indem sowohl die JavaScript-Funktion als auch die Daten an napi_add_finalizer übergeben werden.

`napi_wrap`

Hinzugefügt in: v8.0.0

N-API-Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] js_object: Das JavaScript-Objekt, das als Wrapper für das native Objekt dient.
[in] native_object: Die native Instanz, die in das JavaScript-Objekt eingebunden wird.
[in] finalize_cb: Optionaler nativer Rückruf, der verwendet werden kann, um die native Instanz freizugeben, wenn das JavaScript-Objekt garbage-collected wurde. napi_finalize bietet weitere Details.
[in] finalize_hint: Optionaler kontextueller Hinweis, der an den finalize-Rückruf übergeben wird.
[out] result: Optionale Referenz auf das gewickelte Objekt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Bettet eine native Instanz in ein JavaScript-Objekt ein. Die native Instanz kann später mit napi_unwrap() abgerufen werden.

Wenn JavaScript-Code einen Konstruktor für eine Klasse aufruft, die mit napi_define_class() definiert wurde, wird der napi_callback für den Konstruktor aufgerufen. Nach dem Konstruieren einer Instanz der nativen Klasse muss der Rückruf dann napi_wrap() aufrufen, um die neu konstruierte Instanz in das bereits erstellte JavaScript-Objekt einzubetten, das das this-Argument für den Konstruktor-Rückruf ist. (Dieses this-Objekt wurde aus der prototype-Funktion des Konstruktors erstellt, daher enthält es bereits Definitionen aller Instanzeigenschaften und -methoden.)

Normalerweise sollte beim Einbetten einer Klasseninstanz ein finalize-Rückruf bereitgestellt werden, der einfach die native Instanz löscht, die als data-Argument an den finalize-Rückruf übergeben wird.

Die optionale zurückgegebene Referenz ist anfänglich eine schwache Referenz, d. h., sie hat einen Referenzzähler von 0. Normalerweise würde dieser Referenzzähler vorübergehend während asynchroner Operationen erhöht, die erfordern, dass die Instanz gültig bleibt.

Vorsicht: Die optionale zurückgegebene Referenz (falls erhalten) sollte über napi_delete_reference NUR als Antwort auf den Aufruf des finalize-Rückrufs gelöscht werden. Wenn sie vorher gelöscht wird, wird der finalize-Rückruf möglicherweise nie aufgerufen. Daher ist bei der Beschaffung einer Referenz auch ein finalize-Rückruf erforderlich, um die korrekte Beseitigung der Referenz zu ermöglichen.

Finalizer-Rückrufe können verzögert werden, wodurch ein Fenster verbleibt, in dem das Objekt garbage-collected wurde (und die schwache Referenz ungültig ist), der Finalizer aber noch nicht aufgerufen wurde. Bei der Verwendung von napi_get_reference_value() auf schwachen Referenzen, die von napi_wrap() zurückgegeben werden, sollte dennoch ein leeres Ergebnis verarbeitet werden.

Ein zweiter Aufruf von napi_wrap() für ein Objekt gibt einen Fehler zurück. Um eine andere native Instanz dem Objekt zuzuordnen, verwenden Sie zuerst napi_remove_wrap().

`napi_unwrap`

Hinzugefügt in: v8.0.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] js_object: Das Objekt, das mit der nativen Instanz verknüpft ist.
[out] result: Zeiger auf die gekapselte native Instanz.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Ruft eine native Instanz ab, die zuvor mit napi_wrap() in ein JavaScript-Objekt gekapselt wurde.

Wenn JavaScript-Code eine Methode oder einen Eigenschaftszugriff auf die Klasse aufruft, wird der entsprechende napi_callback aufgerufen. Wenn der Rückruf für eine Instanzmethode oder einen -zugriff gilt, ist das this-Argument des Rückrufs das Wrapper-Objekt; die gekapselte C++-Instanz, die das Ziel des Aufrufs ist, kann dann durch Aufrufen von napi_unwrap() auf dem Wrapper-Objekt abgerufen werden.

`napi_remove_wrap`

Hinzugefügt in: v8.5.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] js_object: Das Objekt, das mit der nativen Instanz verknüpft ist.
[out] result: Zeiger auf die gekapselte native Instanz.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Ruft eine native Instanz ab, die zuvor mit napi_wrap() in das JavaScript-Objekt js_object gekapselt wurde, und entfernt die Kapselung. Wenn ein Finalisierungscallback mit der Kapselung verknüpft war, wird er nicht mehr aufgerufen, wenn das JavaScript-Objekt garbage-collected wird.

`napi_type_tag_object`

Hinzugefügt in: v14.8.0, v12.19.0

N-API-Version: 8

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] js_object: Das JavaScript-Objekt oder extern, das markiert werden soll.
[in] type_tag: Das Tag, mit dem das Objekt markiert werden soll.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Verknüpft den Wert des type_tag-Zeigers mit dem JavaScript-Objekt oder extern. napi_check_object_type_tag() kann dann verwendet werden, um das Tag, das an das Objekt angehängt wurde, mit einem vom Addon besessenen Tag zu vergleichen, um sicherzustellen, dass das Objekt den richtigen Typ hat.

Wenn das Objekt bereits ein zugeordnetes Typtag besitzt, gibt diese API napi_invalid_arg zurück.

`napi_check_object_type_tag`

Hinzugefügt in: v14.8.0, v12.19.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] js_object: Das JavaScript-Objekt oder extern, dessen Type-Tag geprüft werden soll.
[in] type_tag: Das Tag, mit dem jedes auf dem Objekt gefundene Tag verglichen werden soll.
[out] result: Ob das angegebene Type-Tag mit dem Type-Tag des Objekts übereinstimmt. false wird auch zurückgegeben, wenn kein Type-Tag auf dem Objekt gefunden wurde.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Vergleicht den als type_tag angegebenen Zeiger mit allen, die auf js_object gefunden werden können. Wenn kein Tag auf js_object gefunden wird oder wenn ein Tag gefunden wird, das aber nicht mit type_tag übereinstimmt, wird result auf false gesetzt. Wenn ein Tag gefunden wird und es mit type_tag übereinstimmt, wird result auf true gesetzt.

`napi_add_finalizer`

Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] js_object: Das JavaScript-Objekt, an das die nativen Daten angehängt werden sollen.
[in] finalize_data: Optionale Daten, die an finalize_cb übergeben werden sollen.
[in] finalize_cb: Natives Callback, das verwendet wird, um die nativen Daten freizugeben, wenn das JavaScript-Objekt garbage-collected wurde. napi_finalize bietet weitere Details.
[in] finalize_hint: Optionaler Kontext-Hinweis, der an das finalize-Callback übergeben wird.
[out] result: Optionale Referenz auf das JavaScript-Objekt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Fügt ein napi_finalize-Callback hinzu, das aufgerufen wird, wenn das JavaScript-Objekt in js_object garbage-collected wurde.

Diese API kann mehrmals für ein einzelnes JavaScript-Objekt aufgerufen werden.

Achtung: Die optionale zurückgegebene Referenz (falls erhalten) sollte NUR als Antwort auf den Aufruf des finalize-Callbacks über napi_delete_reference gelöscht werden. Wenn sie vorher gelöscht wird, wird das finalize-Callback möglicherweise nie aufgerufen. Daher ist beim Erhalten einer Referenz auch ein finalize-Callback erforderlich, um die korrekte Bereinigung der Referenz zu ermöglichen.

`node_api_post_finalizer`

Hinzugefügt in: v21.0.0, v20.10.0, v18.19.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] finalize_cb: Native Callback-Funktion, die zum Freigeben der nativen Daten verwendet wird, wenn das JavaScript-Objekt garbage-collected wurde. napi_finalize bietet weitere Details.
[in] finalize_data: Optionale Daten, die an finalize_cb übergeben werden.
[in] finalize_hint: Optionaler kontextueller Hinweis, der an die finalize-Callback-Funktion übergeben wird.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Plant einen napi_finalize-Callback, der asynchron in der Ereignisschleife aufgerufen wird.

Normalerweise werden Finalizer aufgerufen, während der GC (Garbage Collector) Objekte sammelt. An diesem Punkt wird das Aufrufen einer beliebigen Node-API, die Änderungen im GC-Zustand verursachen könnte, deaktiviert und führt zum Absturz von Node.js.

node_api_post_finalizer hilft, diese Einschränkung zu umgehen, indem es dem Add-on ermöglicht, Aufrufe solcher Node-APIs auf einen Zeitpunkt außerhalb der GC-Finalisierung zu verschieben.

Einfache asynchrone Operationen

Addon-Module müssen oft asynchrone Hilfsprogramme von libuv als Teil ihrer Implementierung nutzen. Dies ermöglicht es ihnen, die Ausführung von Arbeiten asynchron zu planen, so dass ihre Methoden vor Abschluss der Arbeit zurückkehren können. Dadurch wird vermieden, dass die Gesamtausführung der Node.js-Anwendung blockiert wird.

Node-API bietet eine ABI-stabile Schnittstelle für diese unterstützenden Funktionen, die die häufigsten asynchronen Anwendungsfälle abdeckt.

Node-API definiert die napi_async_work-Struktur, die verwendet wird, um asynchrone Worker zu verwalten. Instanzen werden mit napi_create_async_work und napi_delete_async_work erstellt/gelöscht.

Die execute- und complete-Callbacks sind Funktionen, die aufgerufen werden, wenn der Executor zur Ausführung bereit ist und wenn er seine Aufgabe abgeschlossen hat.

Die execute-Funktion sollte vermeiden, Node-API-Aufrufe zu tätigen, die zur Ausführung von JavaScript oder zur Interaktion mit JavaScript-Objekten führen könnten. In den meisten Fällen sollte jeder Code, der Node-API-Aufrufe tätigen muss, stattdessen im complete-Callback erfolgen. Vermeiden Sie die Verwendung des napi_env-Parameters im execute-Callback, da dieser wahrscheinlich JavaScript ausführt.

Diese Funktionen implementieren die folgenden Schnittstellen:

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

Wenn diese Methoden aufgerufen werden, ist der übergebene data-Parameter die vom Addon bereitgestellten void*-Daten, die an den napi_create_async_work-Aufruf übergeben wurden.

Sobald der asynchrone Worker erstellt wurde, kann er mit der Funktion napi_queue_async_work zur Ausführung in die Warteschlange eingereiht werden:

napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

napi_cancel_async_work kann verwendet werden, wenn die Arbeit abgebrochen werden muss, bevor die Ausführung begonnen hat.

Nach dem Aufruf von napi_cancel_async_work wird der complete-Callback mit einem Statuswert von napi_cancelled aufgerufen. Die Arbeit sollte nicht vor dem Aufruf des complete-Callbacks gelöscht werden, auch wenn sie abgebrochen wurde.

`napi_create_async_work`

[Historie]

Version	Änderungen
v8.6.0	`async_resource` und `async_resource_name` Parameter hinzugefügt.
v8.0.0	Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] async_resource: Ein optionales Objekt, das der asynchronen Arbeit zugeordnet ist und an mögliche async_hooks init Hooks übergeben wird.
[in] async_resource_name: Bezeichner für die Art der Ressource, die für diagnostische Informationen bereitgestellt wird, die von der async_hooks API bereitgestellt werden.
[in] execute: Die native Funktion, die aufgerufen werden sollte, um die Logik asynchron auszuführen. Die angegebene Funktion wird von einem Worker-Pool-Thread aufgerufen und kann parallel zum Haupt-Event-Loop-Thread ausgeführt werden.
[in] complete: Die native Funktion, die aufgerufen wird, wenn die asynchrone Logik abgeschlossen oder abgebrochen wird. Die angegebene Funktion wird vom Haupt-Event-Loop-Thread aufgerufen. napi_async_complete_callback bietet weitere Details.
[in] data: Vom Benutzer bereitgestellter Datenkontext. Dieser wird an die execute und complete Funktionen zurückgegeben.
[out] result: napi_async_work*, der Handle für die neu erstellte asynchrone Arbeit ist.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API allokiert ein Arbeitsobjekt, das verwendet wird, um Logik asynchron auszuführen. Es sollte mit napi_delete_async_work freigegeben werden, sobald die Arbeit nicht mehr benötigt wird.

async_resource_name sollte eine nullterminierte, UTF-8-kodierte Zeichenkette sein.

Der Bezeichner async_resource_name wird vom Benutzer bereitgestellt und sollte die Art der durchgeführten asynchronen Arbeit repräsentieren. Es wird auch empfohlen, Namensräume auf den Bezeichner anzuwenden, z. B. durch Hinzufügen des Modulnamens. Weitere Informationen finden Sie in der async_hooks Dokumentation.

`napi_delete_async_work`

Hinzugefügt in: v8.0.0

N-API-Version: 1

napi_status napi_delete_async_work(napi_env env,
                                   napi_async_work work);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] work: Der Handle, der durch den Aufruf von napi_create_async_work zurückgegeben wurde.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt ein zuvor zugewiesenes Arbeitsobjekt frei.

Diese API kann auch dann aufgerufen werden, wenn eine ausstehende JavaScript-Ausnahme vorliegt.

`napi_queue_async_work`

Hinzugefügt in: v8.0.0

N-API-Version: 1

napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] work: Der Handle, der durch den Aufruf von napi_create_async_work zurückgegeben wurde.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API fordert an, dass die zuvor zugewiesene Arbeit zur Ausführung geplant wird. Nachdem sie erfolgreich zurückgegeben wurde, darf diese API nicht erneut mit demselben napi_async_work-Element aufgerufen werden, da das Ergebnis sonst undefiniert ist.

`napi_cancel_async_work`

Hinzugefügt in: v8.0.0

N-API-Version: 1

napi_status napi_cancel_async_work(node_api_basic_env env,
                                   napi_async_work work);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] work: Der Handle, der durch den Aufruf von napi_create_async_work zurückgegeben wurde.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API bricht die eingeordnete Arbeit ab, wenn sie noch nicht gestartet wurde. Wenn sie bereits mit der Ausführung begonnen hat, kann sie nicht abgebrochen werden und napi_generic_failure wird zurückgegeben. Bei Erfolg wird der complete-Callback mit einem Statuswert von napi_cancelled aufgerufen. Die Arbeit sollte nicht vor dem Aufruf des complete-Callbacks gelöscht werden, selbst wenn sie erfolgreich abgebrochen wurde.

Diese API kann auch dann aufgerufen werden, wenn eine ausstehende JavaScript-Ausnahme vorliegt.

Benutzerdefinierte asynchrone Operationen

Die oben genannten einfachen asynchronen Arbeits-APIs sind möglicherweise nicht für jedes Szenario geeignet. Wenn ein anderer asynchroner Mechanismus verwendet wird, sind die folgenden APIs erforderlich, um sicherzustellen, dass eine asynchrone Operation ordnungsgemäß von der Laufzeit verfolgt wird.

`napi_async_init`

Hinzugefügt in: v8.6.0

N-API-Version: 1

napi_status napi_async_init(napi_env env,
                            napi_value async_resource,
                            napi_value async_resource_name,
                            napi_async_context* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] async_resource: Objekt, das mit der asynchronen Arbeit verknüpft ist und an mögliche async_hooks init-Hooks übergeben wird und über async_hooks.executionAsyncResource() zugegriffen werden kann.
[in] async_resource_name: Bezeichner für die Art der Ressource, die für diagnostische Informationen bereitgestellt wird, die von der async_hooks-API verfügbar gemacht werden.
[out] result: Der initialisierte asynchrone Kontext.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Das async_resource-Objekt muss so lange aktiv gehalten werden, bis napi_async_destroy aufgerufen wird, damit die async_hooks-bezogenen APIs korrekt funktionieren. Um die ABI-Kompatibilität mit früheren Versionen zu erhalten, verwalten napi_async_context keine starke Referenz auf die async_resource-Objekte, um zu vermeiden, Speicherlecks zu verursachen. Wenn jedoch die async_resource von der JavaScript-Engine freigegeben wird, bevor der napi_async_context durch napi_async_destroy zerstört wurde, kann das Aufrufen von napi_async_context-bezogenen APIs wie napi_open_callback_scope und napi_make_callback zu Problemen wie dem Verlust des asynchronen Kontexts bei Verwendung der AsyncLocalStorage-API führen.

Um die ABI-Kompatibilität mit früheren Versionen zu erhalten, führt die Übergabe von NULL für async_resource nicht zu einem Fehler. Dies wird jedoch nicht empfohlen, da dies zu unerwünschtem Verhalten mit async_hooks init-Hooks und async_hooks.executionAsyncResource() führt, da die Ressource jetzt von der zugrunde liegenden async_hooks-Implementierung benötigt wird, um die Verknüpfung zwischen asynchronen Rückrufen bereitzustellen.

`napi_async_destroy`

Hinzugefügt in: v8.6.0

N-API Version: 1

napi_status napi_async_destroy(napi_env env,
                               napi_async_context async_context);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] async_context: Der zu zerstörende asynchrone Kontext.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API kann auch dann aufgerufen werden, wenn eine ausstehende JavaScript-Ausnahme vorliegt.

`napi_make_callback`

[Historie]

Version	Änderungen
v8.6.0	`async_context` Parameter hinzugefügt.
v8.0.0	Hinzugefügt in: v8.0.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] async_context: Kontext für die asynchrone Operation, die den Callback aufruft. Dies sollte normalerweise ein Wert sein, der zuvor von napi_async_init erhalten wurde. Um die ABI-Kompatibilität mit früheren Versionen zu erhalten, führt die Übergabe von NULL für async_context nicht zu einem Fehler. Dies führt jedoch zu einem falschen Verhalten von asynchronen Hooks. Mögliche Probleme sind der Verlust des asynchronen Kontexts bei Verwendung der AsyncLocalStorage-API.
[in] recv: Der this-Wert, der an die aufgerufene Funktion übergeben wird.
[in] func: napi_value, die die aufzurufende JavaScript-Funktion darstellt.
[in] argc: Die Anzahl der Elemente im argv-Array.
[in] argv: Array von JavaScript-Werten als napi_value, die die Argumente für die Funktion darstellen. Wenn argc null ist, kann dieser Parameter durch Übergabe von NULL weggelassen werden.
[out] result: napi_value, die das zurückgegebene JavaScript-Objekt darstellt.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Methode ermöglicht den Aufruf eines JavaScript-Funktionsobjekts von einem nativen Add-on. Diese API ähnelt napi_call_function. Sie wird jedoch verwendet, um von nativem Code in JavaScript zurückzurufen, nachdem von einer asynchronen Operation zurückgekehrt wurde (wenn kein anderer Script auf dem Stack ist). Es ist ein ziemlich einfacher Wrapper um node::MakeCallback.

Beachten Sie, dass es nicht notwendig ist, napi_make_callback innerhalb eines napi_async_complete_callback zu verwenden; in dieser Situation wurde der asynchrone Kontext des Callbacks bereits eingerichtet, daher ist ein direkter Aufruf von napi_call_function ausreichend und angemessen. Die Verwendung der Funktion napi_make_callback kann erforderlich sein, wenn benutzerdefiniertes asynchrones Verhalten implementiert wird, das nicht napi_create_async_work verwendet.

Alle process.nextTicks oder Promises, die von JavaScript während des Callbacks in der Microtask-Queue geplant werden, werden ausgeführt, bevor an C/C++ zurückgegeben wird.

`napi_open_callback_scope`

Hinzugefügt in: v9.6.0

N-API Version: 3

NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
                                                 napi_value resource_object,
                                                 napi_async_context context,
                                                 napi_callback_scope* result)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] resource_object: Ein Objekt, das mit der asynchronen Arbeit verknüpft ist und an mögliche async_hooks init-Hooks übergeben wird. Dieser Parameter wurde als veraltet markiert und wird zur Laufzeit ignoriert. Verwenden Sie stattdessen den Parameter async_resource in napi_async_init.
[in] context: Kontext für die asynchrone Operation, die den Callback aufruft. Dies sollte ein Wert sein, der zuvor von napi_async_init erhalten wurde.
[out] result: Der neu erstellte Scope.

Es gibt Fälle (z. B. das Auflösen von Promises), in denen es notwendig ist, das Äquivalent des Scopes, der mit einem Callback verknüpft ist, zu haben, wenn bestimmte Node-API-Aufrufe durchgeführt werden. Wenn kein anderes Skript auf dem Stack vorhanden ist, können die Funktionen napi_open_callback_scope und napi_close_callback_scope verwendet werden, um den erforderlichen Scope zu öffnen/schließen.

`napi_close_callback_scope`

Hinzugefügt in: v9.6.0

N-API Version: 3

NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
                                                  napi_callback_scope scope)

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] scope: Der zu schließende Scope.

Diese API kann aufgerufen werden, selbst wenn eine ausstehende JavaScript-Ausnahme vorliegt.

Versionsverwaltung

`napi_get_node_version`

Hinzugefügt in: v8.4.0

N-API Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[out] version: Ein Zeiger auf Versionsinformationen für Node.js selbst.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Funktion füllt die version-Struktur mit der Haupt-, Neben- und Patch-Version von Node.js, die derzeit ausgeführt wird, und das Feld release mit dem Wert von process.release.name.

Der zurückgegebene Puffer wird statisch zugeordnet und muss nicht freigegeben werden.

`napi_get_version`

Hinzugefügt in: v8.0.0

N-API-Version: 1

napi_status napi_get_version(node_api_basic_env env,
                             uint32_t* result);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: Die höchste unterstützte Node-API-Version.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API gibt die höchste vom Node.js-Laufzeitsystem unterstützte Node-API-Version zurück. Node-API soll additiv sein, so dass neuere Versionen von Node.js zusätzliche API-Funktionen unterstützen können. Um es einem Addon zu ermöglichen, eine neuere Funktion zu verwenden, wenn es mit Versionen von Node.js ausgeführt wird, die sie unterstützen, während gleichzeitig ein Fallback-Verhalten bereitgestellt wird, wenn es mit Node.js-Versionen ausgeführt wird, die sie nicht unterstützen:

Rufen Sie napi_get_version() auf, um festzustellen, ob die API verfügbar ist.
Wenn verfügbar, laden Sie dynamisch einen Zeiger auf die Funktion mit uv_dlsym() .
Verwenden Sie den dynamisch geladenen Zeiger, um die Funktion aufzurufen.
Wenn die Funktion nicht verfügbar ist, stellen Sie eine alternative Implementierung bereit, die die Funktion nicht verwendet.

Speicherverwaltung

`napi_adjust_external_memory`

Hinzugefügt in: v8.5.0

N-API-Version: 1

NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
                                                    int64_t change_in_bytes,
                                                    int64_t* result);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] change_in_bytes: Die Änderung des extern zugewiesenen Speichers, der von JavaScript-Objekten am Leben gehalten wird.
[out] result: Der angepasste Wert

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese Funktion gibt V8 einen Hinweis auf die Menge des extern zugewiesenen Speichers, der von JavaScript-Objekten am Leben gehalten wird (d. h. ein JavaScript-Objekt, das auf seinen eigenen, von einem nativen Addon zugewiesenen Speicher zeigt). Die Registrierung von extern zugewiesenem Speicher löst häufiger globale Garbage Collections aus als sonst.

Promises

Node-API bietet Funktionen zum Erstellen von Promise-Objekten, wie in Abschnitt 25.4 der ECMA-Spezifikation beschrieben. Es implementiert Promises als ein Paar von Objekten. Wenn ein Promise von napi_create_promise() erstellt wird, wird ein "Deferred"-Objekt erstellt und zusammen mit dem Promise zurückgegeben. Das Deferred-Objekt ist an das erstellte Promise gebunden und ist das einzige Mittel, um das Promise mit napi_resolve_deferred() oder napi_reject_deferred() aufzulösen oder zurückzuweisen. Das Deferred-Objekt, das von napi_create_promise() erstellt wird, wird von napi_resolve_deferred() oder napi_reject_deferred() freigegeben. Das Promise-Objekt kann an JavaScript zurückgegeben werden, wo es wie gewohnt verwendet werden kann.

Beispielsweise, um ein Promise zu erstellen und an einen asynchronen Worker zu übergeben:

napi_deferred deferred;
napi_value promise;
napi_status status;

// Erstelle das Promise.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;

// Gib das Deferred an eine Funktion weiter, die eine asynchrone Aktion ausführt.
do_something_asynchronous(deferred);

// Gib das Promise an JS zurück
return promise;

Die obige Funktion do_something_asynchronous() würde ihre asynchrone Aktion ausführen und dann das Deferred auflösen oder zurückweisen, wodurch das Promise abgeschlossen und das Deferred freigegeben wird:

napi_deferred deferred;
napi_value undefined;
napi_status status;

// Erstelle einen Wert, mit dem das Deferred abgeschlossen werden soll.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;

// Löse oder weise das Promise auf, das dem Deferred zugeordnet ist, abhängig davon,
// ob die asynchrone Aktion erfolgreich war.
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;

// An diesem Punkt wurde das Deferred freigegeben, daher sollten wir NULL zuweisen.
deferred = NULL;

`napi_create_promise`

Hinzugefügt in: v8.5.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] deferred: Ein neu erstelltes Deferred-Objekt, das später an napi_resolve_deferred() oder napi_reject_deferred() übergeben werden kann, um das zugehörige Promise zu erfüllen bzw. abzulehnen.
[out] promise: Das JavaScript-Promise, das dem Deferred-Objekt zugeordnet ist.

Gibt napi_ok zurück, wenn die API erfolgreich war.

Diese API erstellt ein Deferred-Objekt und ein JavaScript-Promise.

`napi_resolve_deferred`

Hinzugefügt in: v8.5.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] deferred: Das Deferred-Objekt, dessen zugehöriges Promise erfüllt werden soll.
[in] resolution: Der Wert, mit dem das Promise erfüllt werden soll.

Diese API erfüllt ein JavaScript-Promise über das zugehörige Deferred-Objekt. Daher kann sie nur verwendet werden, um JavaScript-Promises zu erfüllen, für die das entsprechende Deferred-Objekt verfügbar ist. Dies bedeutet effektiv, dass das Promise mit napi_create_promise() erstellt und das von diesem Aufruf zurückgegebene Deferred-Objekt beibehalten werden muss, um an diese API übergeben zu werden.

Das Deferred-Objekt wird nach erfolgreicher Ausführung freigegeben.

`napi_reject_deferred`

Hinzugefügt in: v8.5.0

N-API Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] deferred: Das Deferred-Objekt, dessen zugehöriges Promise abgelehnt werden soll.
[in] rejection: Der Wert, mit dem das Promise abgelehnt werden soll.

Diese API lehnt ein JavaScript-Promise über das zugehörige Deferred-Objekt ab. Daher kann sie nur verwendet werden, um JavaScript-Promises abzulehnen, für die das entsprechende Deferred-Objekt verfügbar ist. Dies bedeutet effektiv, dass das Promise mit napi_create_promise() erstellt und das von diesem Aufruf zurückgegebene Deferred-Objekt beibehalten werden muss, um an diese API übergeben zu werden.

Das Deferred-Objekt wird nach erfolgreicher Ausführung freigegeben.

`napi_is_promise`

Hinzugefügt in: v8.5.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] value: Der zu untersuchende Wert.
[out] is_promise: Flag, das angibt, ob promise ein natives Promise-Objekt ist (d. h. ein Promise-Objekt, das von der zugrundeliegenden Engine erstellt wurde).

Skriptausführung

Node-API bietet eine API zum Ausführen einer Zeichenkette, die JavaScript enthält, mithilfe der zugrundeliegenden JavaScript-Engine.

`napi_run_script`

Hinzugefügt in: v8.5.0

N-API-Version: 1

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] script: Eine JavaScript-Zeichenkette, die das auszuführende Skript enthält.
[out] result: Der Wert, der sich aus der Ausführung des Skripts ergibt.

Diese Funktion führt eine JavaScript-Codezeichenkette aus und gibt deren Ergebnis mit den folgenden Einschränkungen zurück:

Im Gegensatz zu eval erlaubt diese Funktion dem Skript nicht, auf den aktuellen lexikalischen Gültigkeitsbereich zuzugreifen, und erlaubt daher auch keinen Zugriff auf den Modulbereich, was bedeutet, dass Pseudo-Globale wie require nicht verfügbar sind.
Das Skript kann auf den globalen Gültigkeitsbereich zugreifen. Funktions- und var-Deklarationen im Skript werden dem global-Objekt hinzugefügt. Variablendeklarationen, die mit let und const vorgenommen werden, sind global sichtbar, werden aber nicht dem global-Objekt hinzugefügt.
Der Wert von this ist global innerhalb des Skripts.

libuv-Ereignisloop

Node-API bietet eine Funktion zum Abrufen des aktuellen Ereignisloops, der einer bestimmten napi_env zugeordnet ist.

`napi_get_uv_event_loop`

Hinzugefügt in: v9.3.0, v8.10.0

N-API-Version: 2

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

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] loop: Die aktuelle libuv-Loop-Instanz.

Hinweis: Obwohl libuv im Laufe der Zeit relativ stabil war, bietet es keine ABI-Stabilitätsgarantie. Die Verwendung dieser Funktion sollte vermieden werden. Ihre Verwendung kann zu einem Addon führen, das nicht über Node.js-Versionen hinweg funktioniert. Asynchrone threadsichere Funktionsaufrufe sind eine Alternative für viele Anwendungsfälle.

Asynchrone threadsichere Funktionsaufrufe

JavaScript-Funktionen können normalerweise nur vom Hauptthread eines nativen Addons aufgerufen werden. Wenn ein Addon zusätzliche Threads erstellt, dürfen Node-API-Funktionen, die eine napi_env, napi_value oder napi_ref benötigen, nicht von diesen Threads aufgerufen werden.

Wenn ein Addon zusätzliche Threads hat und JavaScript-Funktionen basierend auf der Verarbeitung durch diese Threads aufgerufen werden müssen, müssen diese Threads mit dem Hauptthread des Addons kommunizieren, damit der Hauptthread die JavaScript-Funktion in ihrem Namen aufrufen kann. Die threadsicheren Funktions-APIs bieten eine einfache Möglichkeit, dies zu tun.

Diese APIs stellen den Typ napi_threadsafe_function sowie APIs zum Erstellen, Zerstören und Aufrufen von Objekten dieses Typs bereit. napi_create_threadsafe_function() erstellt eine persistente Referenz auf eine napi_value, die eine JavaScript-Funktion enthält, die von mehreren Threads aufgerufen werden kann. Die Aufrufe erfolgen asynchron. Dies bedeutet, dass Werte, mit denen der JavaScript-Callback aufgerufen werden soll, in eine Warteschlange gestellt werden und für jeden Wert in der Warteschlange letztendlich ein Aufruf der JavaScript-Funktion erfolgt.

Bei der Erstellung einer napi_threadsafe_function kann ein napi_finalize-Callback bereitgestellt werden. Dieser Callback wird im Hauptthread aufgerufen, wenn die threadsichere Funktion kurz vor dem Zerstören steht. Er empfängt den Kontext und die Finalisierungsdaten, die während der Konstruktion angegeben wurden, und bietet die Möglichkeit, nach der Beendigung der Threads aufzuräumen, z. B. durch Aufrufen von uv_thread_join(). Abgesehen vom Hauptloop-Thread sollten keine Threads die threadsichere Funktion verwenden, nachdem der Finalisierungs-Callback abgeschlossen ist.

Der Kontext, der während des Aufrufs von napi_create_threadsafe_function() angegeben wird, kann von jedem Thread mit einem Aufruf von napi_get_threadsafe_function_context() abgerufen werden.

Aufrufen einer threadsicheren Funktion

napi_call_threadsafe_function() kann verwendet werden, um einen Aufruf in JavaScript zu initiieren. napi_call_threadsafe_function() akzeptiert einen Parameter, der steuert, ob sich die API blockierend verhält. Wenn er auf napi_tsfn_nonblocking gesetzt ist, verhält sich die API nicht blockierend und gibt napi_queue_full zurück, wenn die Warteschlange voll war, wodurch verhindert wird, dass Daten erfolgreich der Warteschlange hinzugefügt werden. Wenn er auf napi_tsfn_blocking gesetzt ist, blockiert die API, bis in der Warteschlange Platz verfügbar ist. napi_call_threadsafe_function() blockiert niemals, wenn die threadsichere Funktion mit einer maximalen Warteschlangengröße von 0 erstellt wurde.

napi_call_threadsafe_function() sollte nicht mit napi_tsfn_blocking von einem JavaScript-Thread aufgerufen werden, da dies, wenn die Warteschlange voll ist, zu einer Deadlock-Situation im JavaScript-Thread führen kann.

Der eigentliche Aufruf in JavaScript wird durch den Callback gesteuert, der über den Parameter call_js_cb angegeben wird. call_js_cb wird einmal im Hauptthread für jeden Wert aufgerufen, der durch einen erfolgreichen Aufruf von napi_call_threadsafe_function() in die Warteschlange gestellt wurde. Wenn ein solcher Callback nicht angegeben wird, wird ein Standard-Callback verwendet, und der resultierende JavaScript-Aufruf hat keine Argumente. Der call_js_cb-Callback empfängt die aufzurufende JavaScript-Funktion als napi_value in seinen Parametern, sowie den void*-Kontextzeiger, der beim Erstellen der napi_threadsafe_function verwendet wurde, und den nächsten Datenzeiger, der von einem der sekundären Threads erstellt wurde. Der Callback kann dann eine API wie napi_call_function() verwenden, um in JavaScript aufzurufen.

Der Callback kann auch mit env und call_js_cb beide auf NULL gesetzt aufgerufen werden, um anzuzeigen, dass Aufrufe in JavaScript nicht mehr möglich sind, während noch Elemente in der Warteschlange verbleiben, die möglicherweise freigegeben werden müssen. Dies tritt normalerweise auf, wenn der Node.js-Prozess beendet wird, während noch eine threadsichere Funktion aktiv ist.

Es ist nicht notwendig, über napi_make_callback() in JavaScript aufzurufen, da Node-API call_js_cb in einem für Callbacks geeigneten Kontext ausführt.

Null oder mehr Elemente in der Warteschlange können in jedem Tick des Ereignis-Loops aufgerufen werden. Anwendungen sollten nicht von einem bestimmten Verhalten abhängen, außer dass Fortschritte beim Aufrufen von Callbacks gemacht werden und Ereignisse mit der Zeit aufgerufen werden.

Referenzzählung threadsicherer Funktionen

Threads können während ihrer Existenz zu einem napi_threadsafe_function-Objekt hinzugefügt und daraus entfernt werden. Daher kann zusätzlich zur Angabe einer anfänglichen Anzahl von Threads bei der Erstellung napi_acquire_threadsafe_function aufgerufen werden, um anzuzeigen, dass ein neuer Thread die threadsichere Funktion nutzen wird. Ähnlich kann napi_release_threadsafe_function aufgerufen werden, um anzuzeigen, dass ein bestehender Thread die threadsichere Funktion nicht mehr nutzt.

napi_threadsafe_function-Objekte werden zerstört, wenn jeder Thread, der das Objekt verwendet, napi_release_threadsafe_function() aufgerufen hat oder als Antwort auf einen Aufruf von napi_call_threadsafe_function einen Rückgabewert von napi_closing erhalten hat. Die Warteschlange wird geleert, bevor die napi_threadsafe_function zerstört wird. napi_release_threadsafe_function() sollte der letzte API-Aufruf sein, der in Verbindung mit einer gegebenen napi_threadsafe_function durchgeführt wird, da nach Abschluss des Aufrufs nicht garantiert ist, dass die napi_threadsafe_function noch zugeordnet ist. Aus dem gleichen Grund sollte eine threadsichere Funktion nicht verwendet werden, nachdem ein Rückgabewert von napi_closing als Antwort auf einen Aufruf von napi_call_threadsafe_function erhalten wurde. Daten, die mit der napi_threadsafe_function verbunden sind, können in ihrem napi_finalize-Callback freigegeben werden, der an napi_create_threadsafe_function() übergeben wurde. Der Parameter initial_thread_count von napi_create_threadsafe_function kennzeichnet die anfängliche Anzahl von Akquisitionen der threadsicheren Funktionen, anstatt napi_acquire_threadsafe_function mehrmals bei der Erstellung aufzurufen.

Sobald die Anzahl der Threads, die eine napi_threadsafe_function verwenden, Null erreicht hat, können keine weiteren Threads durch Aufruf von napi_acquire_threadsafe_function() mehr damit beginnen, sie zu verwenden. Tatsächlich geben alle nachfolgenden damit verbundenen API-Aufrufe außer napi_release_threadsafe_function() einen Fehlerwert von napi_closing zurück.

Die threadsichere Funktion kann "abgebrochen" werden, indem der Wert napi_tsfn_abort an napi_release_threadsafe_function() übergeben wird. Dies führt dazu, dass alle nachfolgenden APIs, die mit der threadsicheren Funktion verbunden sind, außer napi_release_threadsafe_function(), napi_closing zurückgeben, noch bevor ihre Referenzzählung Null erreicht. Insbesondere gibt napi_call_threadsafe_function() napi_closing zurück und informiert so die Threads darüber, dass es nicht mehr möglich ist, asynchrone Aufrufe an die threadsichere Funktion durchzuführen. Dies kann als Kriterium für die Beendigung des Threads verwendet werden. Nach Erhalt eines Rückgabewerts von napi_closing von napi_call_threadsafe_function() darf ein Thread die threadsichere Funktion nicht mehr verwenden, da nicht mehr garantiert ist, dass sie zugeordnet ist.

Entscheidung, ob der Prozess weiterlaufen soll

Ähnlich wie bei libuv-Handles können threadsichere Funktionen "referenziert" und "aufgegeben" werden. Eine "referenzierte" threadsichere Funktion bewirkt, dass die Ereignisschleife auf dem Thread, auf dem sie erstellt wurde, so lange aktiv bleibt, bis die threadsichere Funktion zerstört wird. Im Gegensatz dazu verhindert eine "aufgegebene" threadsichere Funktion nicht das Beenden der Ereignisschleife. Die APIs napi_ref_threadsafe_function und napi_unref_threadsafe_function dienen diesem Zweck.

Weder napi_unref_threadsafe_function markiert threadsichere Funktionen als zerstörbar, noch verhindert napi_ref_threadsafe_function, dass sie zerstört werden.

`napi_create_threadsafe_function`

[Verlauf]

Version	Änderungen
v12.6.0, v10.17.0	Parameter `func` optional mit benutzerdefiniertem `call_js_cb` gemacht.
v10.6.0	Hinzugefügt in: v10.6.0

N-API-Version: 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: Die Umgebung, unter der die API aufgerufen wird.
[in] func: Eine optionale JavaScript-Funktion, die von einem anderen Thread aufgerufen werden kann. Sie muss angegeben werden, wenn NULL an call_js_cb übergeben wird.
[in] async_resource: Ein optionales Objekt, das der asynchronen Arbeit zugeordnet ist und an mögliche async_hooks init-Hooks übergeben wird.
[in] async_resource_name: Eine JavaScript-Zeichenkette, um einen Bezeichner für die Art der Ressource bereitzustellen, die für diagnostische Informationen bereitgestellt wird, die von der async_hooks-API bereitgestellt werden.
[in] max_queue_size: Maximale Größe der Warteschlange. 0 für keine Begrenzung.
[in] initial_thread_count: Die anfängliche Anzahl von Akquisitionen, d. h. die anfängliche Anzahl von Threads, einschließlich des Hauptthreads, die diese Funktion verwenden werden.
[in] thread_finalize_data: Optionale Daten, die an thread_finalize_cb übergeben werden sollen.
[in] thread_finalize_cb: Optionale Funktion, die aufgerufen wird, wenn die napi_threadsafe_function zerstört wird.
[in] context: Optionale Daten, die an die resultierende napi_threadsafe_function angehängt werden sollen.
[in] call_js_cb: Optionaler Callback, der die JavaScript-Funktion als Antwort auf einen Aufruf in einem anderen Thread aufruft. Dieser Callback wird im Hauptthread aufgerufen. Wenn nicht angegeben, wird die JavaScript-Funktion ohne Parameter und mit undefined als this-Wert aufgerufen. napi_threadsafe_function_call_js bietet weitere Details.
[out] result: Die asynchrone threadsichere JavaScript-Funktion.

Änderungsverlauf:

Experimentell (NAPI_EXPERIMENTAL ist definiert): Nicht abgefangene Ausnahmen, die in call_js_cb ausgelöst werden, werden mit dem Ereignis 'uncaughtException' behandelt, anstatt ignoriert zu werden.

`napi_get_threadsafe_function_context`

Hinzugefügt in: v10.6.0

N-API Version: 4

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

[in] func: Die threadsichere Funktion, für die der Kontext abgerufen werden soll.
[out] result: Der Speicherort, an dem der Kontext gespeichert werden soll.

Diese API kann von jedem Thread aufgerufen werden, der func verwendet.

`napi_call_threadsafe_function`

[Verlauf]

Version	Änderungen
v14.5.0	Die Unterstützung für `napi_would_deadlock` wurde rückgängig gemacht.
v14.1.0	Gibt `napi_would_deadlock` zurück, wenn mit `napi_tsfn_blocking` vom Hauptthread oder einem Worker-Thread aufgerufen wird und die Warteschlange voll ist.
v10.6.0	Hinzugefügt in: v10.6.0

N-API Version: 4

NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
                              void* data,
                              napi_threadsafe_function_call_mode is_blocking);

[in] func: Die aufzurufende asynchrone threadsichere JavaScript-Funktion.
[in] data: Daten, die über den Callback call_js_cb an JavaScript gesendet werden, der während der Erstellung der threadsicheren JavaScript-Funktion bereitgestellt wurde.
[in] is_blocking: Flag, dessen Wert entweder napi_tsfn_blocking sein kann, um anzugeben, dass der Aufruf blockieren soll, wenn die Warteschlange voll ist, oder napi_tsfn_nonblocking, um anzugeben, dass der Aufruf sofort mit dem Status napi_queue_full zurückkehren soll, wenn die Warteschlange voll ist.

Diese API sollte nicht mit napi_tsfn_blocking von einem JavaScript-Thread aufgerufen werden, da dies, wenn die Warteschlange voll ist, zu einer Deadlock-Situation im JavaScript-Thread führen kann.

Diese API gibt napi_closing zurück, wenn napi_release_threadsafe_function() mit abort auf napi_tsfn_abort von einem beliebigen Thread aufgerufen wurde. Der Wert wird nur dann der Warteschlange hinzugefügt, wenn die API napi_ok zurückgibt.

Diese API kann von jedem Thread aufgerufen werden, der func verwendet.

`napi_acquire_threadsafe_function`

Hinzugefügt in: v10.6.0

N-API Version: 4

NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);

[in] func: Die asynchrone threadsichere JavaScript-Funktion, deren Verwendung begonnen werden soll.

Ein Thread sollte diese API aufrufen, bevor er func an andere threadsichere Funktions-APIs übergibt, um anzugeben, dass er func verwenden wird. Dies verhindert, dass func zerstört wird, wenn alle anderen Threads die Verwendung beendet haben.

Diese API kann von jedem Thread aufgerufen werden, der die Verwendung von func beginnen wird.

`napi_release_threadsafe_function`

Hinzugefügt in: v10.6.0

N-API Version: 4

NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);

[in] func: Die asynchrone threadsichere JavaScript-Funktion, deren Referenzzähler dekrementiert werden soll.
[in] mode: Flag, dessen Wert entweder napi_tsfn_release sein kann, um anzugeben, dass der aktuelle Thread keine weiteren Aufrufe der threadsicheren Funktion tätigen wird, oder napi_tsfn_abort, um anzugeben, dass neben dem aktuellen Thread kein anderer Thread weitere Aufrufe der threadsicheren Funktion tätigen sollte. Wenn auf napi_tsfn_abort gesetzt, geben weitere Aufrufe von napi_call_threadsafe_function() napi_closing zurück, und es werden keine weiteren Werte in die Warteschlange gestellt.

Ein Thread sollte diese API aufrufen, wenn er die Verwendung von func beendet. Das Übergeben von func an threadsichere APIs nach dem Aufruf dieser API führt zu undefinierten Ergebnissen, da func möglicherweise zerstört wurde.

Diese API kann von jedem Thread aufgerufen werden, der die Verwendung von func beendet.

`napi_ref_threadsafe_function`

Hinzugefügt in: v10.6.0

N-API Version: 4

NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] func: Die threadsichere Funktion, auf die verwiesen werden soll.

Diese API wird verwendet, um anzugeben, dass die Ereignisschleife, die im Hauptthread läuft, nicht beendet werden sollte, bis func zerstört wurde. Ähnlich wie uv_ref ist sie auch idempotent.

Weder markiert napi_unref_threadsafe_function die threadsicheren Funktionen als zerstörbar, noch verhindert napi_ref_threadsafe_function, dass sie zerstört werden. napi_acquire_threadsafe_function und napi_release_threadsafe_function stehen zu diesem Zweck zur Verfügung.

Diese API darf nur vom Hauptthread aufgerufen werden.

`napi_unref_threadsafe_function`

Hinzugefügt in: v10.6.0

N-API Version: 4

NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[in] func: Die threadsichere Funktion, deren Referenz aufgehoben werden soll.

Diese API wird verwendet, um anzugeben, dass die Ereignisschleife, die im Hauptthread läuft, vor der Zerstörung von func beendet werden darf. Ähnlich wie uv_unref ist sie auch idempotent.

Diese API darf nur vom Hauptthread aufgerufen werden.

Verschiedene Hilfsprogramme

`node_api_get_module_file_name`

Hinzugefügt in: v15.9.0, v14.18.0, v12.22.0

N-API-Version: 9

NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);

[in] env: Die Umgebung, unter der die API aufgerufen wird.
[out] result: Eine URL, die den absoluten Pfad des Ortes enthält, von dem das Add-on geladen wurde. Für eine Datei auf dem lokalen Dateisystem beginnt sie mit file://. Die Zeichenkette ist null-terminiert und gehört zu env und darf daher nicht modifiziert oder freigegeben werden.

result kann eine leere Zeichenkette sein, wenn der Ladevorgang des Add-ons den Dateinamen des Add-ons während des Ladens nicht feststellen kann.

Node-API ​

Auswirkungen der ABI-Stabilität ​

Build ​

Build-Tools ​

node-gyp ​

CMake.js ​

Hochladen vorkompilierter Binärdateien ​

node-pre-gyp ​

prebuild ​

prebuildify ​

Verwendung ​

Node-API Versionsmatrix ​

Umgebungslebenszyklus-APIs ​

napi_set_instance_data ​

napi_get_instance_data ​

Grundlegende Node-API-Datentypen ​

napi_status ​

napi_extended_error_info ​

napi_env ​

node_api_basic_env ​

napi_value ​

napi_threadsafe_function ​

napi_threadsafe_function_release_mode ​

napi_threadsafe_function_call_mode ​

Node-API Speicherverwaltungstypen ​

napi_handle_scope ​

napi_escapable_handle_scope ​

napi_ref ​

napi_type_tag ​

napi_async_cleanup_hook_handle ​

Node-API-Rückruffunktionstypen ​

napi_callback_info ​

napi_callback ​

node_api_basic_finalize ​

napi_finalize ​

napi_async_execute_callback ​

napi_async_complete_callback ​

napi_threadsafe_function_call_js ​

napi_cleanup_hook ​

napi_async_cleanup_hook ​

Fehlerbehandlung ​

Rückgabewerte ​

napi_get_last_error_info ​

Ausnahmen ​

napi_throw ​

napi_throw_error ​

napi_throw_type_error ​

napi_throw_range_error ​

node_api_throw_syntax_error ​

napi_is_error ​

napi_create_error ​

napi_create_type_error ​

napi_create_range_error ​

node_api_create_syntax_error ​

napi_get_and_clear_last_exception ​

napi_is_exception_pending ​

napi_fatal_exception ​

Fatale Fehler ​

napi_fatal_error ​

Objekt-Lebenszyklusverwaltung ​

Verkürzung der Lebensdauer von Handles im Vergleich zur nativen Methode ​

napi_open_handle_scope ​

napi_close_handle_scope ​

napi_open_escapable_handle_scope ​

napi_close_escapable_handle_scope ​

napi_escape_handle ​

Referenzen auf Werte mit einer längeren Lebensdauer als die der nativen Methode ​

napi_create_reference ​

napi_delete_reference ​

napi_reference_ref ​

napi_reference_unref ​

napi_get_reference_value ​

Bereinigung beim Beenden der aktuellen Node.js-Umgebung ​

napi_add_env_cleanup_hook ​

napi_remove_env_cleanup_hook ​

napi_add_async_cleanup_hook ​

napi_remove_async_cleanup_hook ​

Finalisierung beim Beenden der Node.js-Umgebung ​

Modulregistrierung ​

Arbeiten mit JavaScript-Werten ​

Node-API

Auswirkungen der ABI-Stabilität

Build

Build-Tools

node-gyp

CMake.js

Hochladen vorkompilierter Binärdateien

node-pre-gyp

prebuild

prebuildify

Verwendung

Node-API Versionsmatrix

Umgebungslebenszyklus-APIs

`napi_set_instance_data`

`napi_get_instance_data`

Grundlegende Node-API-Datentypen

`napi_status`

`napi_extended_error_info`

`napi_env`

`node_api_basic_env`

`napi_value`

`napi_threadsafe_function`

`napi_threadsafe_function_release_mode`

`napi_threadsafe_function_call_mode`

Node-API Speicherverwaltungstypen

`napi_handle_scope`

`napi_escapable_handle_scope`

`napi_ref`

`napi_type_tag`

`napi_async_cleanup_hook_handle`

Node-API-Rückruffunktionstypen

`napi_callback_info`

`napi_callback`

`node_api_basic_finalize`

`napi_finalize`

`napi_async_execute_callback`

`napi_async_complete_callback`

`napi_threadsafe_function_call_js`

`napi_cleanup_hook`

`napi_async_cleanup_hook`

Fehlerbehandlung

Rückgabewerte

`napi_get_last_error_info`

Ausnahmen

`napi_throw`

`napi_throw_error`

`napi_throw_type_error`

`napi_throw_range_error`

`node_api_throw_syntax_error`

`napi_is_error`

`napi_create_error`

`napi_create_type_error`

`napi_create_range_error`

`node_api_create_syntax_error`

`napi_get_and_clear_last_exception`

`napi_is_exception_pending`

`napi_fatal_exception`

Fatale Fehler

`napi_fatal_error`

Objekt-Lebenszyklusverwaltung

Verkürzung der Lebensdauer von Handles im Vergleich zur nativen Methode

`napi_open_handle_scope`

`napi_close_handle_scope`

`napi_open_escapable_handle_scope`

`napi_close_escapable_handle_scope`

`napi_escape_handle`

Referenzen auf Werte mit einer längeren Lebensdauer als die der nativen Methode

`napi_create_reference`

`napi_delete_reference`

`napi_reference_ref`

`napi_reference_unref`

`napi_get_reference_value`

Bereinigung beim Beenden der aktuellen Node.js-Umgebung

`napi_add_env_cleanup_hook`

`napi_remove_env_cleanup_hook`

`napi_add_async_cleanup_hook`

`napi_remove_async_cleanup_hook`

Finalisierung beim Beenden der Node.js-Umgebung

Modulregistrierung

Arbeiten mit JavaScript-Werten