Node-API
[Stable: 2 - Stable]
Stable: 2 Stabilità: 2 - Stabile
Node-API (precedentemente N-API) è un'API per la creazione di Addon nativi. È indipendente dal runtime JavaScript sottostante (ad esempio, V8) e viene mantenuta come parte di Node.js stesso. Questa API sarà Application Binary Interface (ABI) stabile tra le versioni di Node.js. Lo scopo è di isolare gli addon dalle modifiche nel motore JavaScript sottostante e consentire ai moduli compilati per una versione principale di funzionare su versioni principali successive di Node.js senza ricompilazione. La guida Stabilità ABI fornisce una spiegazione più approfondita.
Gli addon vengono creati/impacchettati con lo stesso approccio/strumenti descritti nella sezione intitolata Addon C++. L'unica differenza è l'insieme di API utilizzate dal codice nativo. Invece di utilizzare le API V8 o Native Abstractions for Node.js, vengono utilizzate le funzioni disponibili in Node-API.
Le API esposte da Node-API vengono generalmente utilizzate per creare e manipolare valori JavaScript. I concetti e le operazioni generalmente corrispondono alle idee specificate nella specifica del linguaggio ECMA-262. Le API hanno le seguenti proprietà:
- Tutte le chiamate Node-API restituiscono un codice di stato di tipo
napi_status. Questo stato indica se la chiamata API ha avuto successo o meno. - Il valore di ritorno dell'API viene passato tramite un parametro di output.
- Tutti i valori JavaScript sono astratti dietro un tipo opaco chiamato
napi_value. - In caso di codice di stato di errore, è possibile ottenere informazioni aggiuntive utilizzando
napi_get_last_error_info. Maggiori informazioni sono disponibili nella sezione sulla gestione degli errori Gestione degli errori.
Node-API è un'API C che garantisce la stabilità ABI tra le versioni di Node.js e diversi livelli di compilatore. Un'API C++ può essere più facile da usare. Per supportare l'utilizzo di C++, il progetto mantiene un modulo wrapper C++ chiamato node-addon-api. Questo wrapper fornisce un'API C++ inlineable. I binari costruiti con node-addon-api dipenderanno dai simboli per le funzioni Node-API basate su C esportate da Node.js. node-addon-api è un modo più efficiente per scrivere codice che chiama Node-API. Considera, ad esempio, il seguente codice node-addon-api. La prima sezione mostra il codice node-addon-api e la seconda sezione mostra cosa viene effettivamente utilizzato nell'addon.
Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");napi_status status;
napi_value object, string;
status = napi_create_object(env, &object);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
status = napi_set_named_property(env, object, "foo", string);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}Il risultato finale è che l'addon utilizza solo le API C esportate. Di conseguenza, ottiene comunque i vantaggi della stabilità ABI fornita dall'API C.
Quando si utilizza node-addon-api invece delle API C, inizia con la documentazione dell'API per node-addon-api.
La Risorsa Node-API offre un ottimo orientamento e suggerimenti per gli sviluppatori che iniziano a utilizzare Node-API e node-addon-api. Ulteriori risorse multimediali sono disponibili nella pagina Media Node-API.
Implicazioni della stabilità dell'ABI
Sebbene Node-API fornisca una garanzia di stabilità dell'ABI, altre parti di Node.js non lo fanno, e nessuna delle librerie esterne utilizzate dall'addon potrebbe farlo. In particolare, nessuna delle seguenti API fornisce una garanzia di stabilità dell'ABI tra le versioni principali:
- le API C++ di Node.js disponibili tramite qualsiasi
- le API libuv incluse anche in Node.js e disponibili tramite
- l'API V8 disponibile tramite
Pertanto, affinché un addon rimanga compatibile con l'ABI tra le versioni principali di Node.js, deve utilizzare esclusivamente Node-API limitandosi a usare
#include <node_api.h>e verificando, per tutte le librerie esterne utilizzate, che la libreria esterna fornisca garanzie di stabilità dell'ABI simili a Node-API.
Compilazione
A differenza dei moduli scritti in JavaScript, lo sviluppo e la distribuzione di addon nativi Node.js utilizzando Node-API richiedono un set aggiuntivo di strumenti. Oltre agli strumenti di base necessari per lo sviluppo di Node.js, lo sviluppatore di addon nativi richiede una toolchain in grado di compilare codice C e C++ in un binario. Inoltre, a seconda di come viene distribuito l'addon nativo, anche l'utente dell'addon nativo dovrà avere installata una toolchain C/C++.
Per gli sviluppatori Linux, i pacchetti della toolchain C/C++ necessari sono facilmente disponibili. GCC è ampiamente utilizzato nella community di Node.js per compilare e testare su una varietà di piattaforme. Per molti sviluppatori, anche l'infrastruttura del compilatore LLVM è una buona scelta.
Per gli sviluppatori Mac, Xcode offre tutti gli strumenti di compilazione necessari. Tuttavia, non è necessario installare l'intero IDE Xcode. Il seguente comando installa la toolchain necessaria:
xcode-select --installPer gli sviluppatori Windows, Visual Studio offre tutti gli strumenti di compilazione necessari. Tuttavia, non è necessario installare l'intero IDE di Visual Studio. Il seguente comando installa la toolchain necessaria:
npm install --global windows-build-toolsLe sezioni seguenti descrivono gli strumenti aggiuntivi disponibili per lo sviluppo e la distribuzione di addon nativi Node.js.
Strumenti di compilazione
Entrambi gli strumenti elencati qui richiedono che gli utenti dell'addon nativo abbiano una toolchain C/C++ installata per poter installare correttamente l'addon nativo.
node-gyp
node-gyp è un sistema di compilazione basato sul fork gyp-next dello strumento GYP di Google e viene fornito in bundle con npm. GYP, e quindi node-gyp, richiede che Python sia installato.
Storicamente, node-gyp è stato lo strumento preferito per la compilazione di addon nativi. Ha un'ampia diffusione e documentazione. Tuttavia, alcuni sviluppatori si sono imbattuti in limitazioni in node-gyp.
CMake.js
CMake.js è un sistema di compilazione alternativo basato su CMake.
CMake.js è una buona scelta per i progetti che utilizzano già CMake o per gli sviluppatori che risentono delle limitazioni di node-gyp. build_with_cmake è un esempio di progetto di addon nativo basato su CMake.
Caricamento di binari precompilati
I tre strumenti elencati qui consentono agli sviluppatori e ai manutentori di addon nativi di creare e caricare binari su server pubblici o privati. Questi strumenti sono in genere integrati con sistemi di compilazione CI/CD come Travis CI e AppVeyor per compilare e caricare binari per una varietà di piattaforme e architetture. Questi binari sono quindi disponibili per il download da parte degli utenti che non hanno bisogno di avere una toolchain C/C++ installata.
node-pre-gyp
node-pre-gyp è uno strumento basato su node-gyp che aggiunge la possibilità di caricare binari su un server a scelta dello sviluppatore. node-pre-gyp ha un supporto particolarmente buono per il caricamento di binari su Amazon S3.
prebuild
prebuild è uno strumento che supporta le compilazioni utilizzando node-gyp o CMake.js. A differenza di node-pre-gyp che supporta una varietà di server, prebuild carica binari solo sui rilasci di GitHub. prebuild è una buona scelta per i progetti GitHub che utilizzano CMake.js.
prebuildify
prebuildify è uno strumento basato su node-gyp. Il vantaggio di prebuildify è che i binari compilati vengono inclusi con l'addon nativo quando viene caricato su npm. I binari vengono scaricati da npm e sono immediatamente disponibili per l'utente del modulo quando l'addon nativo viene installato.
Utilizzo
Per utilizzare le funzioni Node-API, includi il file node_api.h che si trova nella directory src nell'albero di sviluppo di Node:
#include <node_api.h>Questo opterà per la NAPI_VERSION predefinita per la release specifica di Node.js. Per garantire la compatibilità con versioni specifiche di Node-API, la versione può essere specificata esplicitamente quando si include l'header:
#define NAPI_VERSION 3
#include <node_api.h>Ciò limita la superficie Node-API alla sola funzionalità che era disponibile nelle versioni specificate (e precedenti).
Alcune parti della superficie Node-API sono sperimentali e richiedono l'esplicito opt-in:
#define NAPI_EXPERIMENTAL
#include <node_api.h>In questo caso, l'intera superficie API, comprese le API sperimentali, sarà disponibile per il codice del modulo.
Occasionalmente, vengono introdotte funzionalità sperimentali che influenzano API già rilasciate e stabili. Queste funzionalità possono essere disabilitate tramite un opt-out:
#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>dove \<FEATURE_NAME\> è il nome di una funzionalità sperimentale che influisce sia sulle API sperimentali che su quelle stabili.
Matrice delle versioni di Node-API
Fino alla versione 9, le versioni di Node-API erano additive e con versione indipendente da Node.js. Ciò significava che ogni versione era un'estensione della versione precedente in quanto aveva tutte le API della versione precedente con alcune aggiunte. Ogni versione di Node.js supportava una sola versione di Node-API. Ad esempio, v18.15.0 supporta solo la versione 8 di Node-API. La stabilità ABI è stata ottenuta perché 8 era un superset stretto di tutte le versioni precedenti.
A partire dalla versione 9, mentre le versioni di Node-API continuano ad essere versionate in modo indipendente, un add-on che girava con la versione 9 di Node-API potrebbe aver bisogno di aggiornamenti del codice per girare con la versione 10 di Node-API. La stabilità ABI viene mantenuta, tuttavia, perché le versioni di Node.js che supportano versioni di Node-API superiori alla 8 supporteranno tutte le versioni tra la 8 e la versione più alta che supportano e per impostazione predefinita forniranno le API della versione 8 a meno che un add-on non opti per una versione Node-API superiore. Questo approccio offre la flessibilità di ottimizzare meglio le funzioni Node-API esistenti mantenendo la stabilità ABI. Gli add-on esistenti possono continuare a funzionare senza ricompilazione utilizzando una versione precedente di Node-API. Se un add-on ha bisogno di funzionalità da una versione Node-API più recente, saranno comunque necessari modifiche al codice esistente e ricompilazione per utilizzare quelle nuove funzioni.
Nelle versioni di Node.js che supportano la versione 9 di Node-API e successive, la definizione di NAPI_VERSION=X e l'utilizzo delle macro di inizializzazione dell'add-on esistenti integreranno nell'add-on la versione di Node-API richiesta che verrà utilizzata in fase di esecuzione. Se NAPI_VERSION non è impostata, per impostazione predefinita sarà 8.
Questa tabella potrebbe non essere aggiornata in stream più vecchi, le informazioni più aggiornate si trovano nella documentazione API più recente in: Matrice delle versioni di Node-API
| Versione Node-API | Supportata in |
|---|---|
| 9 | v18.17.0+, 20.3.0+, 21.0.0 e tutte le versioni successive |
| 8 | v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 e tutte le versioni successive |
| 7 | v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 e tutte le versioni successive |
| 6 | v10.20.0+, v12.17.0+, 14.0.0 e tutte le versioni successive |
| 5 | v10.17.0+, v12.11.0+, 13.0.0 e tutte le versioni successive |
| 4 | v10.16.0+, v11.8.0+, 12.0.0 e tutte le versioni successive |
| 3 | v6.14.2*, 8.11.2+, v9.11.0+*, 10.0.0 e tutte le versioni successive |
| 2 | v8.10.0+, v9.3.0+, 10.0.0 e tutte le versioni successive |
| 1 | v8.6.0+*, v9.0.0+, 10.0.0 e tutte le versioni successive |
- Node-API era sperimentale.
** Node.js 8.0.0 includeva Node-API come sperimentale. È stata rilasciata come versione 1 di Node-API, ma ha continuato a evolvere fino a Node.js 8.6.0. L'API è diversa nelle versioni precedenti a Node.js 8.6.0. Si consiglia la versione 3 o successiva di Node-API.
Ogni API documentata per Node-API avrà un header denominato aggiunta in:, e le API che sono stabili avranno l'header aggiuntivo Versione Node-API:. Le API sono direttamente utilizzabili quando si utilizza una versione di Node.js che supporta la versione di Node-API mostrata in Versione Node-API: o superiore. Quando si utilizza una versione di Node.js che non supporta la Versione Node-API: elencata o se non è elencata alcuna Versione Node-API:, l'API sarà disponibile solo se #define NAPI_EXPERIMENTAL precede l'inclusione di node_api.h o js_native_api.h. Se un'API sembra non essere disponibile su una versione di Node.js che è successiva a quella mostrata in aggiunta in:, allora questo è molto probabilmente il motivo dell'apparente assenza.
Le Node-API associate strettamente all'accesso alle funzionalità di ECMAScript dal codice nativo si possono trovare separatamente in js_native_api.h e js_native_api_types.h. Le API definite in questi header sono incluse in node_api.h e node_api_types.h. Gli header sono strutturati in questo modo per consentire implementazioni di Node-API al di fuori di Node.js. Per queste implementazioni le API specifiche di Node.js potrebbero non essere applicabili.
Le parti specifiche di Node.js di un add-on possono essere separate dal codice che espone l'effettiva funzionalità all'ambiente JavaScript in modo che quest'ultimo possa essere utilizzato con più implementazioni di Node-API. Nell'esempio seguente, addon.c e addon.h si riferiscono solo a js_native_api.h. Ciò garantisce che addon.c possa essere riutilizzato per la compilazione con l'implementazione di Node-API di Node.js o con qualsiasi implementazione di Node-API al di fuori di Node.js.
addon_node.c è un file separato che contiene il punto di ingresso specifico di Node.js per l'add-on e che istanzia l'add-on chiamando addon.c quando l'add-on viene caricato in un ambiente Node.js.
// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif // _ADDON_H_// addon.c
#include "addon.h"
#define NODE_API_CALL(env, call) \
do { \
napi_status status = (call); \
if (status != napi_ok) { \
const napi_extended_error_info* error_info = NULL; \
napi_get_last_error_info((env), &error_info); \
const char* err_message = error_info->error_message; \
bool is_pending; \
napi_is_exception_pending((env), &is_pending); \
/* If an exception is already pending, don't rethrow it */ \
if (!is_pending) { \
const char* message = (err_message == NULL) \
? "empty error message" \
: err_message; \
napi_throw_error((env), NULL, message); \
} \
return NULL; \
} \
} while(0)
static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
// Do something useful.
return NULL;
}
napi_value create_addon(napi_env env) {
napi_value result;
NODE_API_CALL(env, napi_create_object(env, &result));
napi_value exported_function;
NODE_API_CALL(env, napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function));
NODE_API_CALL(env, napi_set_named_property(env,
result,
"doSomethingUseful",
exported_function));
return result;
}// addon_node.c
#include <node_api.h>
#include "addon.h"
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
// This function body is expected to return a `napi_value`.
// The variables `napi_env env` and `napi_value exports` may be used within
// the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
return create_addon(env);
}API del ciclo di vita dell'ambiente
La Sezione 8.7 della Specifica del linguaggio ECMAScript definisce il concetto di "Agent" come un ambiente autonomo in cui viene eseguito il codice JavaScript. Molti di questi Agent possono essere avviati e terminati in modo concorrente o in sequenza dal processo.
Un ambiente Node.js corrisponde a un Agent ECMAScript. Nel processo principale, un ambiente viene creato all'avvio e ambienti aggiuntivi possono essere creati su thread separati per fungere da thread di lavoro. Quando Node.js è incorporato in un'altra applicazione, il thread principale dell'applicazione può anche costruire e distruggere un ambiente Node.js più volte durante il ciclo di vita del processo dell'applicazione, in modo che ciascun ambiente Node.js creato dall'applicazione possa, a sua volta, durante il suo ciclo di vita, creare e distruggere ambienti aggiuntivi come thread di lavoro.
Dal punto di vista di un addon nativo, ciò significa che i binding che fornisce possono essere chiamati più volte, da più contesti e persino in modo concorrente da più thread.
Gli addon nativi potrebbero dover allocare uno stato globale che utilizzano durante il ciclo di vita di un ambiente Node.js in modo che lo stato possa essere univoco per ciascuna istanza dell'addon.
A tal fine, Node-API fornisce un modo per associare i dati in modo che il loro ciclo di vita sia legato al ciclo di vita di un ambiente Node.js.
napi_set_instance_data
Aggiunto in: v12.8.0, v10.20.0
Versione N-API: 6
napi_status napi_set_instance_data(node_api_basic_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] data: L'elemento dati da rendere disponibile ai binding di questa istanza.[in] finalize_cb: La funzione da chiamare quando l'ambiente viene smantellato. La funzione ricevedatain modo che possa liberarlo.napi_finalizefornisce maggiori dettagli.[in] finalize_hint: Suggerimento opzionale da passare alla callback di finalizzazione durante la raccolta.
Restituisce napi_ok se l'API ha avuto successo.
Questa API associa data all'ambiente Node.js attualmente in esecuzione. data può essere recuperato successivamente utilizzando napi_get_instance_data(). Tutti i dati esistenti associati all'ambiente Node.js attualmente in esecuzione che sono stati impostati tramite una precedente chiamata a napi_set_instance_data() verranno sovrascritti. Se è stato fornito un finalize_cb dalla chiamata precedente, non verrà chiamato.
napi_get_instance_data
Aggiunto in: v12.8.0, v10.20.0
Versione N-API: 6
napi_status napi_get_instance_data(node_api_basic_env env,
void** data);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[out] data: L'elemento dati precedentemente associato all'ambiente Node.js attualmente in esecuzione tramite una chiamata anapi_set_instance_data().
Restituisce napi_ok se l'API ha avuto successo.
Questa API recupera i dati precedentemente associati all'ambiente Node.js attualmente in esecuzione tramite napi_set_instance_data(). Se non sono impostati dati, la chiamata avrà successo e data verrà impostato su NULL.
Tipi di dati Node-API di base
Node-API espone i seguenti tipi di dati fondamentali come astrazioni che vengono utilizzate dalle varie API. Queste API devono essere trattate come opache, ispezionabili solo con altre chiamate Node-API.
napi_status
Aggiunto in: v8.0.0
Versione N-API: 1
Codice di stato integrale che indica il successo o il fallimento di una chiamata Node-API. Attualmente, sono supportati i seguenti codici di stato.
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, /* inutilizzato */
napi_no_external_buffers_allowed,
napi_cannot_run_js
} napi_status;Se sono necessarie informazioni aggiuntive quando un'API restituisce uno stato non riuscito, è possibile ottenerle chiamando napi_get_last_error_info.
napi_extended_error_info
Aggiunto in: v8.0.0
Versione N-API: 1
typedef struct {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
} napi_extended_error_info;error_message: Stringa con codifica UTF8 contenente una descrizione dell'errore neutrale rispetto alla VM.engine_reserved: Riservato per i dettagli dell'errore specifici della VM. Attualmente non è implementato per nessuna VM.engine_error_code: Codice di errore specifico della VM. Attualmente non è implementato per nessuna VM.error_code: Il codice di stato Node-API che ha avuto origine con l'ultimo errore.
Vedere la sezione Gestione degli errori per ulteriori informazioni.
napi_env
napi_env viene utilizzato per rappresentare un contesto che l'implementazione sottostante di Node-API può utilizzare per rendere persistente lo stato specifico della VM. Questa struttura viene passata alle funzioni native quando vengono richiamate e deve essere ripassata quando si effettuano chiamate Node-API. In particolare, lo stesso napi_env che è stato passato quando è stata chiamata la funzione nativa iniziale deve essere passato a qualsiasi successiva chiamata nidificata di Node-API. Non è consentito memorizzare nella cache napi_env allo scopo di un riutilizzo generale e passare napi_env tra le istanze dello stesso addon in esecuzione su diversi thread Worker. napi_env diventa non valido quando viene scaricata un'istanza di un addon nativo. La notifica di questo evento viene recapitata tramite i callback forniti a napi_add_env_cleanup_hook e napi_set_instance_data.
node_api_basic_env
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
Questa variante di napi_env viene passata ai finalizzatori sincroni (node_api_basic_finalize). Esiste un sottoinsieme di Node-API che accettano un parametro di tipo node_api_basic_env come primo argomento. Queste API non accedono allo stato del motore JavaScript e quindi possono essere chiamate in sicurezza dai finalizzatori sincroni. È consentito passare un parametro di tipo napi_env a queste API, tuttavia, non è consentito passare un parametro di tipo node_api_basic_env alle API che accedono allo stato del motore JavaScript. Il tentativo di farlo senza un cast produrrà un avviso del compilatore o un errore quando gli add-on vengono compilati con flag che li inducono a emettere avvisi e/o errori quando vengono passati tipi di puntatore non corretti a una funzione. La chiamata di tali API da un finalizzatore sincrono comporterà in definitiva la terminazione dell'applicazione.
napi_value
Questo è un puntatore opaco che viene utilizzato per rappresentare un valore JavaScript.
napi_threadsafe_function
Aggiunto in: v10.6.0
Versione N-API: 4
Questo è un puntatore opaco che rappresenta una funzione JavaScript che può essere chiamata in modo asincrono da più thread tramite napi_call_threadsafe_function().
napi_threadsafe_function_release_mode
Aggiunto in: v10.6.0
Versione N-API: 4
Un valore da fornire a napi_release_threadsafe_function() per indicare se la funzione thread-safe deve essere chiusa immediatamente (napi_tsfn_abort) o semplicemente rilasciata (napi_tsfn_release) e quindi disponibile per un uso successivo tramite napi_acquire_threadsafe_function() e napi_call_threadsafe_function().
typedef enum {
napi_tsfn_release,
napi_tsfn_abort
} napi_threadsafe_function_release_mode;napi_threadsafe_function_call_mode
Aggiunto in: v10.6.0
Versione N-API: 4
Un valore da fornire a napi_call_threadsafe_function() per indicare se la chiamata deve bloccarsi quando la coda associata alla funzione thread-safe è piena.
typedef enum {
napi_tsfn_nonblocking,
napi_tsfn_blocking
} napi_threadsafe_function_call_mode;Tipi di gestione della memoria Node-API
napi_handle_scope
Questa è un'astrazione utilizzata per controllare e modificare la durata degli oggetti creati all'interno di un particolare scope. In generale, i valori Node-API vengono creati nel contesto di un handle scope. Quando un metodo nativo viene chiamato da JavaScript, esisterà un handle scope predefinito. Se l'utente non crea esplicitamente un nuovo handle scope, i valori Node-API verranno creati nell'handle scope predefinito. Per qualsiasi invocazione di codice al di fuori dell'esecuzione di un metodo nativo (ad esempio, durante un'invocazione di callback libuv), il modulo è tenuto a creare uno scope prima di invocare qualsiasi funzione che possa comportare la creazione di valori JavaScript.
Gli handle scope vengono creati utilizzando napi_open_handle_scope e vengono distrutti utilizzando napi_close_handle_scope. La chiusura dello scope può indicare al GC che tutti i napi_value creati durante la durata dell'handle scope non sono più referenziati dal frame di stack corrente.
Per maggiori dettagli, rivedere la Gestione della durata degli oggetti.
napi_escapable_handle_scope
Aggiunto in: v8.0.0
Versione N-API: 1
Gli scope di handle "escapable" sono un tipo speciale di scope di handle per restituire valori creati all'interno di un particolare scope di handle a uno scope padre.
napi_ref
Aggiunto in: v8.0.0
Versione N-API: 1
Questa è l'astrazione da usare per fare riferimento a un napi_value. Ciò consente agli utenti di gestire la durata dei valori JavaScript, inclusa la definizione esplicita della loro durata minima.
Per maggiori dettagli, rivedi la Gestione della durata degli oggetti.
napi_type_tag
Aggiunto in: v14.8.0, v12.19.0
Versione N-API: 8
Un valore a 128 bit memorizzato come due interi senza segno a 64 bit. Serve come UUID con cui gli oggetti JavaScript o gli external possono essere "taggati" per garantire che siano di un certo tipo. Questo è un controllo più forte di napi_instanceof, perché quest'ultimo può segnalare un falso positivo se il prototipo dell'oggetto è stato manipolato. Il type-tagging è più utile in combinazione con napi_wrap perché garantisce che il puntatore recuperato da un oggetto avvolto possa essere convertito in modo sicuro nel tipo nativo corrispondente al tag di tipo che era stato precedentemente applicato all'oggetto JavaScript.
typedef struct {
uint64_t lower;
uint64_t upper;
} napi_type_tag;napi_async_cleanup_hook_handle
Aggiunto in: v14.10.0, v12.19.0
Un valore opaco restituito da napi_add_async_cleanup_hook. Deve essere passato a napi_remove_async_cleanup_hook quando la catena di eventi di pulizia asincrona è completata.
Tipi di callback Node-API
napi_callback_info
Aggiunto in: v8.0.0
Versione N-API: 1
Tipo di dati opaco che viene passato a una funzione di callback. Può essere utilizzato per ottenere ulteriori informazioni sul contesto in cui è stata invocata la callback.
napi_callback
Aggiunto in: v8.0.0
Versione N-API: 1
Tipo di puntatore a funzione per le funzioni native fornite dall'utente che devono essere esposte a JavaScript tramite Node-API. Le funzioni di callback devono soddisfare la seguente firma:
typedef napi_value (*napi_callback)(napi_env, napi_callback_info);A meno che per ragioni discusse in Gestione della durata degli oggetti, non è necessario creare un handle e/o uno scope di callback all'interno di una napi_callback.
node_api_basic_finalize
Aggiunto in: v21.6.0, v20.12.0, v18.20.0
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
Tipo di puntatore a funzione per funzioni fornite da add-on che consentono all'utente di essere notificato quando i dati di proprietà esterna sono pronti per essere puliti perché l'oggetto a cui erano associati è stato sottoposto a garbage collection. L'utente deve fornire una funzione che soddisfi la seguente firma, che verrebbe chiamata al momento della raccolta dell'oggetto. Attualmente, node_api_basic_finalize può essere utilizzato per scoprire quando vengono raccolti gli oggetti che hanno dati esterni.
typedef void (*node_api_basic_finalize)(node_api_basic_env env,
void* finalize_data,
void* finalize_hint);A meno che per ragioni discusse in Gestione della durata degli oggetti, non è necessario creare un handle e/o uno scope di callback all'interno del corpo della funzione.
Poiché queste funzioni possono essere chiamate mentre il motore JavaScript si trova in uno stato in cui non può eseguire codice JavaScript, è possibile chiamare solo le Node-API che accettano un node_api_basic_env come primo parametro. node_api_post_finalizer può essere utilizzato per programmare chiamate Node-API che richiedono l'accesso allo stato del motore JavaScript da eseguire dopo che il ciclo di garbage collection corrente è stato completato.
Nel caso di node_api_create_external_string_latin1 e node_api_create_external_string_utf16 il parametro env può essere null, perché le stringhe esterne possono essere raccolte durante l'ultima parte dell'arresto dell'ambiente.
Cronologia delle modifiche:
- sperimentale (
NAPI_EXPERIMENTAL): È possibile chiamare solo le Node-API che accettano unnode_api_basic_envcome primo parametro, altrimenti l'applicazione verrà terminata con un messaggio di errore appropriato. Questa funzionalità può essere disattivata definendoNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.
napi_finalize
Aggiunto in: v8.0.0
Versione N-API: 1
Tipo puntatore a funzione per la funzione fornita dall'addon che consente all'utente di pianificare un gruppo di chiamate alle Node-API in risposta a un evento di garbage collection, dopo che il ciclo di garbage collection è stato completato. Questi puntatori a funzione possono essere utilizzati con node_api_post_finalizer.
typedef void (*napi_finalize)(napi_env env,
void* finalize_data,
void* finalize_hint);Cronologia delle modifiche:
- Sperimentale (
NAPI_EXPERIMENTALè definito): una funzione di questo tipo non può più essere utilizzata come finalizzatore, tranne che connode_api_post_finalizer. Deve invece essere utilizzatonode_api_basic_finalize. Questa funzionalità può essere disattivata definendoNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.
napi_async_execute_callback
Aggiunto in: v8.0.0
Versione N-API: 1
Puntatore a funzione utilizzato con funzioni che supportano operazioni asincrone. Le funzioni di callback devono soddisfare la seguente firma:
typedef void (*napi_async_execute_callback)(napi_env env, void* data);Le implementazioni di questa funzione devono evitare di effettuare chiamate Node-API che eseguono JavaScript o interagiscono con oggetti JavaScript. Le chiamate Node-API dovrebbero essere invece in napi_async_complete_callback. Non utilizzare il parametro napi_env in quanto ciò potrebbe comportare l'esecuzione di JavaScript.
napi_async_complete_callback
Aggiunto in: v8.0.0
Versione N-API: 1
Puntatore a funzione utilizzato con funzioni che supportano operazioni asincrone. Le funzioni di callback devono soddisfare la seguente firma:
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);A meno che per i motivi discussi in Gestione del ciclo di vita degli oggetti, non è necessario creare un handle e/o uno scope di callback all'interno del corpo della funzione.
napi_threadsafe_function_call_js
Aggiunto in: v10.6.0
Versione N-API: 4
Puntatore a funzione utilizzato con chiamate di funzioni thread-safe asincrone. La callback sarà chiamata sul thread principale. Il suo scopo è utilizzare un elemento di dati in arrivo tramite la coda da uno dei thread secondari per costruire i parametri necessari per una chiamata in JavaScript, di solito tramite napi_call_function, e quindi effettuare la chiamata in JavaScript.
I dati in arrivo dal thread secondario tramite la coda sono forniti nel parametro data e la funzione JavaScript da chiamare è fornita nel parametro js_callback.
Node-API imposta l'ambiente prima di chiamare questa callback, quindi è sufficiente chiamare la funzione JavaScript tramite napi_call_function piuttosto che tramite napi_make_callback.
Le funzioni di callback devono soddisfare la seguente firma:
typedef void (*napi_threadsafe_function_call_js)(napi_env env,
napi_value js_callback,
void* context,
void* data);[in] env: L'ambiente da utilizzare per le chiamate API, oNULLse la funzione thread-safe è in fase di chiusura edatapotrebbe dover essere liberato.[in] js_callback: La funzione JavaScript da chiamare, oNULLse la funzione thread-safe è in fase di chiusura edatapotrebbe dover essere liberato. Può anche essereNULLse la funzione thread-safe è stata creata senzajs_callback.[in] context: I dati opzionali con cui è stata creata la funzione thread-safe.[in] data: Dati creati dal thread secondario. È responsabilità della callback convertire questi dati nativi in valori JavaScript (con funzioni Node-API) che possono essere passati come parametri quando viene invocatajs_callback. Questo puntatore è gestito interamente dai thread e da questa callback. Pertanto, questa callback dovrebbe liberare i dati.
A meno che non per ragioni discusse in Gestione della durata dell'oggetto, non è necessario creare un handle e/o un ambito di callback all'interno del corpo della funzione.
napi_cleanup_hook
Aggiunto in: v19.2.0, v18.13.0
Versione N-API: 3
Puntatore a funzione utilizzato con napi_add_env_cleanup_hook. Verrà chiamato quando l'ambiente viene smantellato.
Le funzioni di callback devono soddisfare la seguente firma:
typedef void (*napi_cleanup_hook)(void* data);[in] data: I dati che sono stati passati anapi_add_env_cleanup_hook.
napi_async_cleanup_hook
Aggiunto in: v14.10.0, v12.19.0
Puntatore a funzione utilizzato con napi_add_async_cleanup_hook. Verrà chiamato quando l'ambiente viene smantellato.
Le funzioni di callback devono soddisfare la seguente firma:
typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
void* data);[in] handle: L'handle che deve essere passato anapi_remove_async_cleanup_hookdopo il completamento della pulizia asincrona.[in] data: I dati che sono stati passati anapi_add_async_cleanup_hook.
Il corpo della funzione deve avviare le azioni di pulizia asincrona al termine delle quali handle deve essere passato in una chiamata a napi_remove_async_cleanup_hook.
Gestione degli errori
Node-API utilizza sia valori di ritorno che eccezioni JavaScript per la gestione degli errori. Le sezioni seguenti spiegano l'approccio per ciascun caso.
Valori di ritorno
Tutte le funzioni Node-API condividono lo stesso schema di gestione degli errori. Il tipo di ritorno di tutte le funzioni API è napi_status.
Il valore di ritorno sarà napi_ok se la richiesta è andata a buon fine e non è stata generata alcuna eccezione JavaScript non intercettata. Se si è verificato un errore E un'eccezione è stata generata, verrà restituito il valore napi_status per l'errore. Se è stata generata un'eccezione e non si è verificato alcun errore, verrà restituito napi_pending_exception.
Nei casi in cui viene restituito un valore di ritorno diverso da napi_ok o napi_pending_exception, è necessario chiamare napi_is_exception_pending per verificare se è in sospeso un'eccezione. Vedere la sezione sulle eccezioni per maggiori dettagli.
L'insieme completo dei possibili valori napi_status è definito in napi_api_types.h.
Il valore di ritorno napi_status fornisce una rappresentazione indipendente dalla VM dell'errore che si è verificato. In alcuni casi è utile essere in grado di ottenere informazioni più dettagliate, inclusa una stringa che rappresenta l'errore e informazioni specifiche della VM (motore).
Per recuperare queste informazioni, viene fornito napi_get_last_error_info che restituisce una struttura napi_extended_error_info. Il formato della struttura napi_extended_error_info è il seguente:
Aggiunto in: v8.0.0
Versione N-API: 1
typedef struct napi_extended_error_info {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
};error_message: Rappresentazione testuale dell'errore che si è verificato.engine_reserved: Handle opaco riservato esclusivamente per l'uso del motore.engine_error_code: Codice di errore specifico della VM.error_code: Codice di stato Node-API per l'ultimo errore.
napi_get_last_error_info restituisce le informazioni per l'ultima chiamata Node-API effettuata.
Non fare affidamento sul contenuto o sul formato di nessuna delle informazioni estese in quanto non sono soggette a SemVer e possono cambiare in qualsiasi momento. Sono destinate esclusivamente a scopi di registrazione.
napi_get_last_error_info
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status
napi_get_last_error_info(node_api_basic_env env,
const napi_extended_error_info** result);[in] env: L'ambiente in cui viene richiamata l'API.[out] result: La strutturanapi_extended_error_infocon maggiori informazioni sull'errore.
Restituisce napi_ok se l'API ha avuto successo.
Questa API recupera una struttura napi_extended_error_info con informazioni sull'ultimo errore verificatosi.
Il contenuto di napi_extended_error_info restituito è valido solo fino a quando una funzione Node-API non viene chiamata sullo stesso env. Ciò include una chiamata a napi_is_exception_pending, quindi potrebbe essere spesso necessario fare una copia delle informazioni in modo che possano essere utilizzate in seguito. Il puntatore restituito in error_message punta a una stringa definita staticamente, quindi è sicuro usare quel puntatore se lo hai copiato dal campo error_message (che verrà sovrascritto) prima che venisse chiamata un'altra funzione Node-API.
Non fare affidamento sul contenuto o sul formato di nessuna delle informazioni estese in quanto non è soggetto a SemVer e può cambiare in qualsiasi momento. È destinato solo a scopi di registrazione.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
Eccezioni
Qualsiasi chiamata di funzione Node-API può comportare un'eccezione JavaScript in sospeso. Questo è il caso di tutte le funzioni API, anche quelle che potrebbero non causare l'esecuzione di JavaScript.
Se napi_status restituito da una funzione è napi_ok, allora non ci sono eccezioni in sospeso e non è richiesta alcuna azione aggiuntiva. Se napi_status restituito è diverso da napi_ok o napi_pending_exception, per cercare di recuperare e continuare invece di tornare immediatamente, napi_is_exception_pending deve essere chiamato per determinare se un'eccezione è in sospeso o meno.
In molti casi, quando viene chiamata una funzione Node-API e un'eccezione è già in sospeso, la funzione tornerà immediatamente con un napi_status di napi_pending_exception. Tuttavia, questo non è il caso di tutte le funzioni. Node-API consente di chiamare un sottoinsieme di funzioni per consentire una pulizia minima prima di tornare a JavaScript. In tal caso, napi_status rifletterà lo stato della funzione. Non rifletterà le precedenti eccezioni in sospeso. Per evitare confusione, controlla lo stato di errore dopo ogni chiamata di funzione.
Quando un'eccezione è in sospeso, è possibile utilizzare uno dei due approcci.
Il primo approccio consiste nell'eseguire qualsiasi pulizia appropriata e quindi tornare indietro in modo che l'esecuzione torni a JavaScript. Come parte della transizione di ritorno a JavaScript, l'eccezione verrà generata nel punto del codice JavaScript in cui è stato richiamato il metodo nativo. Il comportamento della maggior parte delle chiamate Node-API non è specificato mentre un'eccezione è in sospeso e molte restituiranno semplicemente napi_pending_exception, quindi fai il meno possibile e poi torna a JavaScript dove l'eccezione può essere gestita.
Il secondo approccio consiste nel provare a gestire l'eccezione. Ci saranno casi in cui il codice nativo può intercettare l'eccezione, intraprendere l'azione appropriata e quindi continuare. Questo è raccomandato solo in casi specifici in cui è noto che l'eccezione può essere gestita in modo sicuro. In questi casi, napi_get_and_clear_last_exception può essere utilizzato per ottenere e cancellare l'eccezione. In caso di successo, il risultato conterrà l'handle dell'ultimo Object JavaScript lanciato. Se si determina, dopo aver recuperato l'eccezione, che l'eccezione non può essere gestita dopo tutto, può essere ri-lanciata con napi_throw dove error è il valore JavaScript da lanciare.
Le seguenti funzioni di utilità sono disponibili anche nel caso in cui il codice nativo debba lanciare un'eccezione o determinare se un napi_value è un'istanza di un oggetto Error JavaScript: napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error e napi_is_error.
Le seguenti funzioni di utilità sono disponibili anche nel caso in cui il codice nativo debba creare un oggetto Error: napi_create_error, napi_create_type_error, napi_create_range_error e node_api_create_syntax_error, dove result è napi_value che si riferisce all'oggetto Error JavaScript appena creato.
Il progetto Node.js sta aggiungendo codici di errore a tutti gli errori generati internamente. L'obiettivo è che le applicazioni utilizzino questi codici di errore per tutti i controlli degli errori. I messaggi di errore associati rimarranno, ma saranno intesi solo per essere utilizzati per la registrazione e la visualizzazione con l'aspettativa che il messaggio possa cambiare senza che SemVer venga applicato. Per supportare questo modello con Node-API, sia nella funzionalità interna che per la funzionalità specifica del modulo (in quanto è una buona pratica), le funzioni throw_ e create_ accettano un parametro di codice opzionale che è la stringa per il codice da aggiungere all'oggetto di errore. Se il parametro opzionale è NULL, non verrà associato alcun codice all'errore. Se viene fornito un codice, viene aggiornato anche il nome associato all'errore:
originalName [code]dove originalName è il nome originale associato all'errore e code è il codice che è stato fornito. Ad esempio, se il codice è 'ERR_ERROR_1' e viene creato un TypeError, il nome sarà:
TypeError [ERR_ERROR_1]napi_throw
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);[in] env: L'ambiente in cui viene invocata l'API.[in] error: Il valore JavaScript da generare.
Restituisce napi_ok se l'API ha avuto successo.
Questa API genera il valore JavaScript fornito.
napi_throw_error
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
const char* code,
const char* msg);[in] env: L'ambiente in cui viene invocata l'API.[in] code: Codice di errore facoltativo da impostare sull'errore.[in] msg: Stringa C che rappresenta il testo da associare all'errore.
Restituisce napi_ok se l'API ha avuto successo.
Questa API genera un Error JavaScript con il testo fornito.
napi_throw_type_error
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
const char* code,
const char* msg);[in] env: L'ambiente in cui viene invocata l'API.[in] code: Codice di errore facoltativo da impostare sull'errore.[in] msg: Stringa C che rappresenta il testo da associare all'errore.
Restituisce napi_ok se l'API ha avuto successo.
Questa API genera un TypeError JavaScript con il testo fornito.
napi_throw_range_error
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
const char* code,
const char* msg);[in] env: L'ambiente in cui viene invocata l'API.[in] code: Codice di errore facoltativo da impostare sull'errore.[in] msg: Stringa C che rappresenta il testo da associare all'errore.
Restituisce napi_ok se l'API ha avuto successo.
Questa API genera un RangeError JavaScript con il testo fornito.
node_api_throw_syntax_error
Aggiunto in: v17.2.0, v16.14.0
Versione N-API: 9
NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
const char* code,
const char* msg);[in] env: L'ambiente in cui viene richiamata l'API.[in] code: Codice di errore opzionale da impostare sull'errore.[in] msg: Stringa C che rappresenta il testo da associare all'errore.
Restituisce napi_ok se l'API ha avuto successo.
Questa API genera un SyntaxError JavaScript con il testo fornito.
napi_is_error
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_is_error(napi_env env,
napi_value value,
bool* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Ilnapi_valueda controllare.[out] result: Valore booleano impostato su true senapi_valuerappresenta un errore, false altrimenti.
Restituisce napi_ok se l'API ha avuto successo.
Questa API interroga un napi_value per verificare se rappresenta un oggetto errore.
napi_create_error
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_create_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] code:napi_valueopzionale con la stringa per il codice di errore da associare all'errore.[in] msg:napi_valueche fa riferimento a unastringJavaScript da utilizzare come messaggio per l'Error.[out] result:napi_valueche rappresenta l'errore creato.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce un Error JavaScript con il testo fornito.
napi_create_type_error
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] code:napi_valueopzionale con la stringa per il codice di errore da associare all'errore.[in] msg:napi_valueche fa riferimento a unastringJavaScript da utilizzare come messaggio per l'Error.[out] result:napi_valueche rappresenta l'errore creato.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce un TypeError JavaScript con il testo fornito.
napi_create_range_error
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] code:napi_valueopzionale con la stringa per il codice di errore da associare all'errore.[in] msg:napi_valueche fa riferimento a unastringJavaScript da utilizzare come messaggio per l'Error.[out] result:napi_valueche rappresenta l'errore creato.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce un RangeError JavaScript con il testo fornito.
node_api_create_syntax_error
Aggiunto in: v17.2.0, v16.14.0
Versione N-API: 9
NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] code:napi_valueopzionale con la stringa per il codice di errore da associare all'errore.[in] msg:napi_valueche fa riferimento a unastringJavaScript da utilizzare come messaggio per l'Error.[out] result:napi_valueche rappresenta l'errore creato.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce un SyntaxError JavaScript con il testo fornito.
napi_get_and_clear_last_exception
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_and_clear_last_exception(napi_env env,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[out] result: L'eccezione se è in sospeso,NULLaltrimenti.
Restituisce napi_ok se l'API ha avuto successo.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
napi_is_exception_pending
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_is_exception_pending(napi_env env, bool* result);[in] env: L'ambiente in cui viene richiamata l'API.[out] result: Valore booleano impostato su true se è in sospeso un'eccezione.
Restituisce napi_ok se l'API ha avuto successo.
Questa API può essere chiamata anche se è in sospeso un'eccezione JavaScript.
napi_fatal_exception
Aggiunto in: v9.10.0
Versione N-API: 3
napi_status napi_fatal_exception(napi_env env, napi_value err);[in] env: L'ambiente in cui viene richiamata l'API.[in] err: L'errore che viene passato a'uncaughtException'.
Attiva un 'uncaughtException' in JavaScript. Utile se un callback asincrono genera un'eccezione senza possibilità di ripristino.
Errori fatali
In caso di errore non recuperabile in un componente aggiuntivo nativo, è possibile generare un errore fatale per terminare immediatamente il processo.
napi_fatal_error
Aggiunto in: v8.2.0
Versione N-API: 1
NAPI_NO_RETURN void napi_fatal_error(const char* location,
size_t location_len,
const char* message,
size_t message_len);[in] location: Posizione opzionale in cui si è verificato l'errore.[in] location_len: La lunghezza della posizione in byte, oNAPI_AUTO_LENGTHse è terminata con null.[in] message: Il messaggio associato all'errore.[in] message_len: La lunghezza del messaggio in byte, oNAPI_AUTO_LENGTHse è terminata con null.
La chiamata di funzione non restituisce valori, il processo verrà terminato.
Questa API può essere chiamata anche se è in sospeso un'eccezione JavaScript.
Gestione della durata degli oggetti
Quando vengono effettuate chiamate Node-API, gli handle agli oggetti nell'heap per la VM sottostante possono essere restituiti come napi_values. Questi handle devono mantenere gli oggetti "attivi" finché non sono più necessari per il codice nativo, altrimenti gli oggetti potrebbero essere raccolti prima che il codice nativo abbia terminato di utilizzarli.
Quando vengono restituiti gli handle degli oggetti, questi sono associati a uno "scope". La durata dello scope predefinito è legata alla durata della chiamata al metodo nativo. Il risultato è che, per impostazione predefinita, gli handle rimangono validi e gli oggetti associati a questi handle saranno mantenuti attivi per tutta la durata della chiamata al metodo nativo.
In molti casi, tuttavia, è necessario che gli handle rimangano validi per una durata più breve o più lunga rispetto a quella del metodo nativo. Le sezioni che seguono descrivono le funzioni Node-API che possono essere utilizzate per modificare la durata dell'handle rispetto a quella predefinita.
Ridurre la durata di vita degli handle rispetto a quella del metodo nativo
Spesso è necessario che la durata degli handle sia inferiore a quella di un metodo nativo. Ad esempio, si consideri un metodo nativo con un ciclo che scorre gli elementi di un grande array:
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;
}
// fare qualcosa con l'elemento
}Ciò comporterebbe la creazione di un gran numero di handle, con un notevole consumo di risorse. Inoltre, anche se il codice nativo potrebbe utilizzare solo l'handle più recente, tutti gli oggetti associati verrebbero mantenuti attivi poiché condividono tutti lo stesso scope.
Per gestire questo caso, Node-API offre la possibilità di stabilire un nuovo "scope" a cui saranno associati gli handle appena creati. Una volta che tali handle non sono più necessari, lo scope può essere "chiuso" e tutti gli handle associati allo scope vengono invalidati. I metodi disponibili per aprire/chiudere gli scope sono napi_open_handle_scope e napi_close_handle_scope.
Node-API supporta solo una singola gerarchia nidificata di scope. In qualsiasi momento è presente un solo scope attivo e tutti i nuovi handle saranno associati a tale scope mentre è attivo. Gli scope devono essere chiusi nell'ordine inverso rispetto a quello in cui sono stati aperti. Inoltre, tutti gli scope creati all'interno di un metodo nativo devono essere chiusi prima di restituire il controllo da tale metodo.
Riprendendo l'esempio precedente, l'aggiunta di chiamate a napi_open_handle_scope e napi_close_handle_scope garantirebbe che al massimo un singolo handle sia valido durante l'esecuzione del ciclo:
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;
}
// fare qualcosa con l'elemento
status = napi_close_handle_scope(env, scope);
if (status != napi_ok) {
break;
}
}Quando si annidano gli scope, ci sono casi in cui un handle di uno scope interno deve sopravvivere alla durata di vita di tale scope. Node-API supporta uno "scope escapabile" per supportare questo caso. Uno scope escapabile consente di "promuovere" un handle in modo che "sfugga" allo scope corrente e la durata di vita dell'handle cambi dallo scope corrente a quello dello scope esterno.
I metodi disponibili per aprire/chiudere gli scope escapabili sono napi_open_escapable_handle_scope e napi_close_escapable_handle_scope.
La richiesta di promuovere un handle viene effettuata tramite napi_escape_handle, che può essere chiamata una sola volta.
napi_open_handle_scope
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
napi_handle_scope* result);[in] env: L'ambiente in cui viene richiamata l'API.[out] result:napi_valueche rappresenta il nuovo scope.
Restituisce napi_ok se l'API ha avuto successo.
Questa API apre un nuovo scope.
napi_close_handle_scope
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
napi_handle_scope scope);[in] env: L'ambiente in cui viene richiamata l'API.[in] scope:napi_valueche rappresenta lo scope da chiudere.
Restituisce napi_ok se l'API ha avuto successo.
Questa API chiude lo scope passato. Gli scope devono essere chiusi nell'ordine inverso rispetto a quello in cui sono stati creati.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
napi_open_escapable_handle_scope
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status
napi_open_escapable_handle_scope(napi_env env,
napi_handle_scope* result);[in] env: L'ambiente in cui viene richiamata l'API.[out] result:napi_valueche rappresenta il nuovo scope.
Restituisce napi_ok se l'API ha avuto successo.
Questa API apre un nuovo scope da cui un oggetto può essere promosso allo scope esterno.
napi_close_escapable_handle_scope
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status
napi_close_escapable_handle_scope(napi_env env,
napi_handle_scope scope);[in] env: L'ambiente in cui viene richiamata l'API.[in] scope:napi_valueche rappresenta lo scope da chiudere.
Restituisce napi_ok se l'API ha avuto successo.
Questa API chiude lo scope passato. Gli scope devono essere chiusi nell'ordine inverso rispetto a quello in cui sono stati creati.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
napi_escape_handle
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_escape_handle(napi_env env,
napi_escapable_handle_scope scope,
napi_value escapee,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] scope:napi_valueche rappresenta l'ambito corrente.[in] escapee:napi_valueche rappresenta l'ObjectJavaScript da "escapare".[out] result:napi_valueche rappresenta l'handle all'Object"escapato" nell'ambito esterno.
Restituisce napi_ok se l'API ha avuto successo.
Questa API promuove l'handle all'oggetto JavaScript in modo che sia valido per tutta la durata dell'ambito esterno. Può essere chiamata solo una volta per ambito. Se viene chiamata più di una volta, verrà restituito un errore.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
Riferimenti a valori con una durata maggiore di quella del metodo nativo
In alcuni casi, un addon dovrà essere in grado di creare e fare riferimento a valori con una durata maggiore di quella di una singola invocazione di metodo nativo. Ad esempio, per creare un costruttore e successivamente utilizzare tale costruttore in una richiesta per creare istanze, deve essere possibile fare riferimento all'oggetto costruttore attraverso molte richieste di creazione di istanze diverse. Ciò non sarebbe possibile con un normale handle restituito come napi_value come descritto nella sezione precedente. La durata di un normale handle è gestita da scope e tutti gli scope devono essere chiusi prima della fine di un metodo nativo.
Node-API fornisce metodi per la creazione di riferimenti persistenti ai valori. Attualmente Node-API consente la creazione di riferimenti solo per un insieme limitato di tipi di valori, inclusi object, external, function e symbol.
Ogni riferimento ha un conteggio associato con un valore pari o superiore a 0, che determina se il riferimento manterrà vivo il valore corrispondente. I riferimenti con un conteggio pari a 0 non impediscono la raccolta dei valori. I valori di tipo object (object, function, external) e symbol stanno diventando riferimenti "deboli" e possono comunque essere accessibili finché non vengono raccolti. Qualsiasi conteggio maggiore di 0 impedirà la raccolta dei valori.
I valori Symbol hanno diverse versioni. Il vero comportamento di riferimento debole è supportato solo dai simboli locali creati con la funzione napi_create_symbol o le chiamate al costruttore JavaScript Symbol(). I simboli registrati globalmente creati con la funzione node_api_symbol_for o le chiamate JavaScript Symbol.for() rimangono sempre riferimenti forti perché il garbage collector non li raccoglie. Lo stesso vale per i simboli noti come Symbol.iterator. Anche questi non vengono mai raccolti dal garbage collector.
I riferimenti possono essere creati con un conteggio di riferimenti iniziale. Il conteggio può quindi essere modificato tramite napi_reference_ref e napi_reference_unref. Se un oggetto viene raccolto mentre il conteggio di un riferimento è 0, tutte le chiamate successive per ottenere l'oggetto associato al riferimento napi_get_reference_value restituiranno NULL per il napi_value restituito. Un tentativo di chiamare napi_reference_ref per un riferimento il cui oggetto è stato raccolto si traduce in un errore.
I riferimenti devono essere eliminati una volta che non sono più richiesti dall'addon. Quando un riferimento viene eliminato, non impedirà più la raccolta dell'oggetto corrispondente. La mancata eliminazione di un riferimento persistente comporta una "perdita di memoria" con sia la memoria nativa per il riferimento persistente che l'oggetto corrispondente nell'heap che vengono conservati per sempre.
Possono essere creati più riferimenti persistenti che fanno riferimento allo stesso oggetto, ciascuno dei quali manterrà l'oggetto attivo o meno in base al suo conteggio individuale. Più riferimenti persistenti allo stesso oggetto possono comportare la conservazione in modo inaspettato della memoria nativa. Le strutture native per un riferimento persistente devono essere mantenute attive fino all'esecuzione dei finalizzatori per l'oggetto a cui si fa riferimento. Se viene creato un nuovo riferimento persistente per lo stesso oggetto, i finalizzatori per tale oggetto non verranno eseguiti e la memoria nativa puntata dal precedente riferimento persistente non verrà liberata. Ciò può essere evitato chiamando napi_delete_reference oltre a napi_reference_unref quando possibile.
Cronologia delle modifiche:
- Sperimentale (
NAPI_EXPERIMENTALè definito): è possibile creare riferimenti per tutti i tipi di valori. I nuovi tipi di valori supportati non supportano la semantica di riferimento debole e i valori di questi tipi vengono rilasciati quando il conteggio dei riferimenti diventa 0 e non è più possibile accedervi dal riferimento.
napi_create_reference
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
napi_value value,
uint32_t initial_refcount,
napi_ref* result);[in] env: L'ambiente in cui viene invocata l'API.[in] value: Ilnapi_valueper il quale viene creato un riferimento.[in] initial_refcount: Conteggio iniziale dei riferimenti per il nuovo riferimento.[out] result:napi_refche punta al nuovo riferimento.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un nuovo riferimento con il conteggio di riferimenti specificato al valore passato.
napi_delete_reference
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);[in] env: L'ambiente in cui viene invocata l'API.[in] ref:napi_refda eliminare.
Restituisce napi_ok se l'API ha avuto successo.
Questa API elimina il riferimento passato.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
napi_reference_ref
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
napi_ref ref,
uint32_t* result);[in] env: L'ambiente in cui viene invocata l'API.[in] ref:napi_refper il quale verrà incrementato il conteggio dei riferimenti.[out] result: Il nuovo conteggio dei riferimenti.
Restituisce napi_ok se l'API ha avuto successo.
Questa API incrementa il conteggio dei riferimenti per il riferimento passato e restituisce il conteggio dei riferimenti risultante.
napi_reference_unref
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
napi_ref ref,
uint32_t* result);[in] env: L'ambiente in cui viene invocata l'API.[in] ref:napi_refper il quale verrà decrementato il conteggio dei riferimenti.[out] result: Il nuovo conteggio dei riferimenti.
Restituisce napi_ok se l'API ha avuto successo.
Questa API decrementa il conteggio dei riferimenti per il riferimento passato e restituisce il conteggio dei riferimenti risultante.
napi_get_reference_value
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
napi_ref ref,
napi_value* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] ref: Ilnapi_refper cui viene richiesto il valore corrispondente.[out] result: Ilnapi_valuea cui fa riferimentonapi_ref.
Restituisce napi_ok se l'API ha avuto successo.
Se è ancora valido, questa API restituisce il napi_value che rappresenta il valore JavaScript associato al napi_ref. Altrimenti, il risultato sarà NULL.
Pulizia all'uscita dell'ambiente Node.js corrente
Mentre un processo Node.js in genere rilascia tutte le sue risorse all'uscita, gli embedder di Node.js o il futuro supporto di Worker possono richiedere che gli addon registrino hook di pulizia che verranno eseguiti una volta che l'ambiente Node.js corrente esce.
Node-API fornisce funzioni per la registrazione e l'annullamento della registrazione di tali callback. Quando tali callback vengono eseguiti, tutte le risorse detenute dall'addon devono essere liberate.
napi_add_env_cleanup_hook
Aggiunto in: v10.2.0
Versione N-API: 3
NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
napi_cleanup_hook fun,
void* arg);Registra fun come una funzione da eseguire con il parametro arg una volta che l'ambiente Node.js corrente esce.
Una funzione può essere specificata in modo sicuro più volte con valori arg diversi. In tal caso, verrà chiamata più volte. Fornire gli stessi valori fun e arg più volte non è consentito e porterà il processo ad abortire.
Gli hook verranno chiamati in ordine inverso, ovvero il più recente aggiunto verrà chiamato per primo.
La rimozione di questo hook può essere eseguita usando napi_remove_env_cleanup_hook. In genere, ciò accade quando la risorsa per la quale è stato aggiunto questo hook viene comunque smantellata.
Per la pulizia asincrona, è disponibile napi_add_async_cleanup_hook.
napi_remove_env_cleanup_hook
Aggiunto in: v10.2.0
Versione N-API: 3
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
void (*fun)(void* arg),
void* arg);Annulla la registrazione di fun come funzione da eseguire con il parametro arg una volta che l'ambiente Node.js corrente termina. Sia l'argomento che il valore della funzione devono corrispondere esattamente.
La funzione deve essere stata originariamente registrata con napi_add_env_cleanup_hook, altrimenti il processo verrà interrotto.
napi_add_async_cleanup_hook
[Cronologia]
| Versione | Modifiche |
|---|---|
| v14.10.0, v12.19.0 | Modificata la firma del callback hook. |
| v14.8.0, v12.19.0 | Aggiunto in: v14.8.0, v12.19.0 |
Versione N-API: 8
NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
node_api_basic_env env,
napi_async_cleanup_hook hook,
void* arg,
napi_async_cleanup_hook_handle* remove_handle);[in] env: L'ambiente in cui viene richiamata l'API.[in] hook: Il puntatore alla funzione da chiamare all'interruzione dell'ambiente.[in] arg: Il puntatore da passare ahookquando viene chiamato.[out] remove_handle: Handle opzionale che fa riferimento all'hook di pulizia asincrono.
Registra hook, che è una funzione di tipo napi_async_cleanup_hook, come funzione da eseguire con i parametri remove_handle e arg una volta che l'ambiente Node.js corrente termina.
A differenza di napi_add_env_cleanup_hook, l'hook può essere asincrono.
In caso contrario, il comportamento corrisponde generalmente a quello di napi_add_env_cleanup_hook.
Se remove_handle non è NULL, verrà memorizzato un valore opaco che dovrà essere successivamente passato a napi_remove_async_cleanup_hook, indipendentemente dal fatto che l'hook sia già stato richiamato. In genere, ciò accade quando la risorsa per cui è stato aggiunto questo hook viene comunque interrotta.
napi_remove_async_cleanup_hook
[Cronologia]
| Versione | Modifiche |
|---|---|
| v14.10.0, v12.19.0 | Rimosso il parametro env. |
| v14.8.0, v12.19.0 | Aggiunto 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: L'handle di un hook di pulizia asincrono creato connapi_add_async_cleanup_hook.
Annulla la registrazione dell'hook di pulizia corrispondente a remove_handle. Ciò impedirà l'esecuzione dell'hook, a meno che non abbia già iniziato l'esecuzione. Questo deve essere chiamato su qualsiasi valore napi_async_cleanup_hook_handle ottenuto da napi_add_async_cleanup_hook.
Finalizzazione all'uscita dall'ambiente Node.js
L'ambiente Node.js può essere eliminato in modo arbitrario non appena possibile con l'esecuzione di JavaScript non consentita, come su richiesta di worker.terminate(). Quando l'ambiente viene eliminato, i callback napi_finalize registrati di oggetti JavaScript, funzioni thread-safe e dati dell'istanza dell'ambiente vengono richiamati immediatamente e in modo indipendente.
L'invocazione dei callback napi_finalize è pianificata dopo gli hook di pulizia registrati manualmente. Per garantire un ordine corretto della finalizzazione degli addon durante lo spegnimento dell'ambiente al fine di evitare l'uso after-free nel callback napi_finalize, gli addon dovrebbero registrare un hook di pulizia con napi_add_env_cleanup_hook e napi_add_async_cleanup_hook per rilasciare manualmente la risorsa allocata in un ordine corretto.
Registrazione del modulo
I moduli Node-API vengono registrati in modo simile agli altri moduli, tranne per il fatto che invece di utilizzare la macro NODE_MODULE viene utilizzato quanto segue:
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)La successiva differenza è la firma per il metodo Init. Per un modulo Node-API è la seguente:
napi_value Init(napi_env env, napi_value exports);Il valore restituito da Init viene trattato come l'oggetto exports per il modulo. Il metodo Init riceve un oggetto vuoto tramite il parametro exports per comodità. Se Init restituisce NULL, il parametro passato come exports viene esportato dal modulo. I moduli Node-API non possono modificare l'oggetto module, ma possono specificare qualsiasi cosa come proprietà exports del modulo.
Per aggiungere il metodo hello come funzione in modo che possa essere chiamato come metodo fornito dall'addon:
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_property_descriptor desc = {
"hello",
NULL,
Method,
NULL,
NULL,
NULL,
napi_writable | napi_enumerable | napi_configurable,
NULL
};
status = napi_define_properties(env, exports, 1, &desc);
if (status != napi_ok) return NULL;
return exports;
}Per impostare una funzione da restituire da require() per l'addon:
napi_value Init(napi_env env, napi_value exports) {
napi_value method;
napi_status status;
status = napi_create_function(env, "exports", NAPI_AUTO_LENGTH, Method, NULL, &method);
if (status != napi_ok) return NULL;
return method;
}Per definire una classe in modo che possano essere create nuove istanze (spesso utilizzata con Object wrap):
// NOTA: esempio parziale, non tutto il codice a cui si fa riferimento è incluso
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;
}È anche possibile utilizzare la macro NAPI_MODULE_INIT, che funge da scorciatoia per NAPI_MODULE e definisce una funzione Init:
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
napi_value answer;
napi_status result;
status = napi_create_int64(env, 42, &answer);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "answer", answer);
if (status != napi_ok) return NULL;
return exports;
}I parametri env e exports vengono forniti al corpo della macro NAPI_MODULE_INIT.
Tutti gli addon Node-API sono context-aware, il che significa che possono essere caricati più volte. Ci sono alcune considerazioni di progettazione quando si dichiara un tale modulo. La documentazione sugli addon context-aware fornisce maggiori dettagli.
Le variabili env e exports saranno disponibili all'interno del corpo della funzione dopo l'invocazione della macro.
Per maggiori dettagli sull'impostazione delle proprietà sugli oggetti, vedere la sezione Utilizzo delle proprietà JavaScript.
Per maggiori dettagli sulla creazione di moduli addon in generale, fare riferimento all'API esistente.
Lavorare con i valori JavaScript
Node-API espone un set di API per creare tutti i tipi di valori JavaScript. Alcuni di questi tipi sono documentati nella Sezione 6 della Specificazione del linguaggio ECMAScript.
Fondamentalmente, queste API vengono utilizzate per fare una delle seguenti cose:
I valori Node-API sono rappresentati dal tipo napi_value. Qualsiasi chiamata Node-API che richiede un valore JavaScript accetta un napi_value. In alcuni casi, l'API controlla preventivamente il tipo di napi_value. Tuttavia, per migliori prestazioni, è meglio che il chiamante si assicuri che il napi_value in questione sia del tipo JavaScript previsto dall'API.
Tipi enum
napi_key_collection_mode
Aggiunto in: v13.7.0, v12.17.0, v10.20.0
Versione N-API: 6
typedef enum {
napi_key_include_prototypes,
napi_key_own_only
} napi_key_collection_mode;Descrive gli enum dei filtri Chiavi/Proprietà:
napi_key_collection_mode limita l'intervallo delle proprietà raccolte.
napi_key_own_only limita le proprietà raccolte al solo oggetto dato. napi_key_include_prototypes includerà anche tutte le chiavi della catena di prototipi dell'oggetto.
napi_key_filter
Aggiunto in: v13.7.0, v12.17.0, v10.20.0
Versione N-API: 6
typedef enum {
napi_key_all_properties = 0,
napi_key_writable = 1,
napi_key_enumerable = 1 << 1,
napi_key_configurable = 1 << 2,
napi_key_skip_strings = 1 << 3,
napi_key_skip_symbols = 1 << 4
} napi_key_filter;Bit di filtro proprietà. Possono essere combinati con l'operatore or per costruire un filtro composito.
napi_key_conversion
Aggiunto in: v13.7.0, v12.17.0, v10.20.0
Versione N-API: 6
typedef enum {
napi_key_keep_numbers,
napi_key_numbers_to_strings
} napi_key_conversion;napi_key_numbers_to_strings convertirà gli indici interi in stringhe. napi_key_keep_numbers restituirà numeri per gli indici interi.
napi_valuetype
typedef enum {
// tipi ES6 (corrisponde a typeof)
napi_undefined,
napi_null,
napi_boolean,
napi_number,
napi_string,
napi_symbol,
napi_object,
napi_function,
napi_external,
napi_bigint,
} napi_valuetype;Descrive il tipo di un napi_value. Questo in genere corrisponde ai tipi descritti nella Sezione 6.1 della Specificazione del linguaggio ECMAScript. Oltre ai tipi in quella sezione, napi_valuetype può anche rappresentare Function e Object con dati esterni.
Un valore JavaScript di tipo napi_external appare in JavaScript come un oggetto semplice tale che non è possibile impostare proprietà su di esso e nessun prototipo.
napi_typedarray_type
typedef enum {
napi_int8_array,
napi_uint8_array,
napi_uint8_clamped_array,
napi_int16_array,
napi_uint16_array,
napi_int32_array,
napi_uint32_array,
napi_float32_array,
napi_float64_array,
napi_bigint64_array,
napi_biguint64_array,
} napi_typedarray_type;Questo rappresenta il tipo di dati scalare binario sottostante di TypedArray. Gli elementi di questo enum corrispondono alla Sezione 22.2 della Specificazione del linguaggio ECMAScript.
Funzioni di creazione di oggetti
napi_create_array
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_array(napi_env env, napi_value* result)[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[out] result: Unnapi_valueche rappresenta unArrayJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce un valore Node-API corrispondente a un tipo Array JavaScript. Gli array JavaScript sono descritti nella Sezione 22.1 della Specificazione del linguaggio ECMAScript.
napi_create_array_with_length
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_array_with_length(napi_env env,
size_t length,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] length: La lunghezza iniziale dell'Array.[out] result: Unnapi_valueche rappresenta unArrayJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce un valore Node-API corrispondente a un tipo Array JavaScript. La proprietà length dell' Array è impostata sul parametro length passato. Tuttavia, non è garantito che il buffer sottostante venga pre-allocato dalla VM quando l'array viene creato. Tale comportamento viene lasciato all'implementazione della VM sottostante. Se il buffer deve essere un blocco di memoria contiguo che può essere letto e/o scritto direttamente tramite C, si consideri l'utilizzo di napi_create_external_arraybuffer.
Gli array JavaScript sono descritti nella Sezione 22.1 della Specificazione del linguaggio ECMAScript.
napi_create_arraybuffer
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_arraybuffer(napi_env env,
size_t byte_length,
void** data,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] length: La lunghezza in byte dell'array buffer da creare.[out] data: Puntatore al buffer di byte sottostante dell'ArrayBuffer.datapuò essere facoltativamente ignorato passandoNULL.[out] result: Unnapi_valueche rappresenta unArrayBufferJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce un valore Node-API corrispondente a un ArrayBuffer JavaScript. Gli ArrayBuffer sono usati per rappresentare buffer di dati binari di lunghezza fissa. Normalmente vengono usati come buffer di supporto per gli oggetti TypedArray. L'ArrayBuffer allocato avrà un buffer di byte sottostante la cui dimensione è determinata dal parametro length passato. Il buffer sottostante viene facoltativamente restituito al chiamante nel caso in cui il chiamante voglia manipolare direttamente il buffer. Questo buffer può essere scritto direttamente solo dal codice nativo. Per scrivere in questo buffer da JavaScript, sarebbe necessario creare un array tipizzato o un oggetto DataView.
Gli oggetti ArrayBuffer JavaScript sono descritti nella Sezione 24.1 della Specificazione del linguaggio ECMAScript.
napi_create_buffer
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_buffer(napi_env env,
size_t size,
void** data,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] size: Dimensione in byte del buffer sottostante.[out] data: Puntatore grezzo al buffer sottostante.datapuò essere facoltativamente ignorato passandoNULL.[out] result: Unnapi_valueche rappresenta unnode::Buffer.
Restituisce napi_ok se l'API ha avuto successo.
Questa API alloca un oggetto node::Buffer. Sebbene questa sia ancora una struttura dati pienamente supportata, nella maggior parte dei casi l'uso di un TypedArray sarà sufficiente.
napi_create_buffer_copy
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_buffer_copy(napi_env env,
size_t length,
const void* data,
void** result_data,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] size: Dimensione in byte del buffer di input (dovrebbe essere la stessa dimensione del nuovo buffer).[in] data: Puntatore grezzo al buffer sottostante da cui copiare.[out] result_data: Puntatore al nuovo buffer di dati sottostante delBuffer.result_datapuò essere facoltativamente ignorato passandoNULL.[out] result: Unnapi_valueche rappresenta unnode::Buffer.
Restituisce napi_ok se l'API ha avuto successo.
Questa API alloca un oggetto node::Buffer e lo inizializza con i dati copiati dal buffer passato. Sebbene questa sia ancora una struttura dati pienamente supportata, nella maggior parte dei casi l'utilizzo di un TypedArray sarà sufficiente.
napi_create_date
Aggiunto in: v11.11.0, v10.17.0
Versione N-API: 5
napi_status napi_create_date(napi_env env,
double time,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] time: Valore di tempo ECMAScript in millisecondi dal 1° gennaio 1970 UTC.[out] result: Unnapi_valueche rappresenta unaDateJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API non osserva i secondi intercalari; vengono ignorati, poiché ECMAScript si allinea alla specifica temporale POSIX.
Questa API alloca un oggetto JavaScript Date.
Gli oggetti JavaScript Date sono descritti nella Sezione 20.3 della specifica del linguaggio ECMAScript.
napi_create_external
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_external(napi_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] data: Puntatore grezzo ai dati esterni.[in] finalize_cb: Callback opzionale da chiamare quando il valore esterno viene raccolto.napi_finalizefornisce maggiori dettagli.[in] finalize_hint: Suggerimento opzionale da passare alla callback di finalizzazione durante la raccolta.[out] result: Unnapi_valueche rappresenta un valore esterno.
Restituisce napi_ok se l'API ha avuto successo.
Questa API alloca un valore JavaScript con dati esterni ad esso allegati. Viene utilizzato per passare dati esterni attraverso il codice JavaScript, in modo che possano essere recuperati in seguito dal codice nativo utilizzando napi_get_value_external.
L'API aggiunge una callback napi_finalize che verrà chiamata quando l'oggetto JavaScript appena creato è stato sottoposto a garbage collection.
Il valore creato non è un oggetto e quindi non supporta proprietà aggiuntive. È considerato un tipo di valore distinto: chiamando napi_typeof() con un valore esterno si ottiene napi_external.
napi_create_external_arraybuffer
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status
napi_create_external_arraybuffer(napi_env env,
void* external_data,
size_t byte_length,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] external_data: Puntatore al buffer di byte sottostante dell'ArrayBuffer.[in] byte_length: La lunghezza in byte del buffer sottostante.[in] finalize_cb: Callback opzionale da chiamare quando l'ArrayBufferviene raccolto.napi_finalizefornisce maggiori dettagli.[in] finalize_hint: Suggerimento opzionale da passare alla callback di finalizzazione durante la raccolta.[out] result: Unnapi_valueche rappresenta unArrayBufferJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Alcuni runtime diversi da Node.js hanno abbandonato il supporto per i buffer esterni. Su runtime diversi da Node.js questo metodo potrebbe restituire napi_no_external_buffers_allowed per indicare che i buffer esterni non sono supportati. Un tale runtime è Electron come descritto in questo problema electron/issues/35801.
Per mantenere la più ampia compatibilità con tutti i runtime, è possibile definire NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED nel proprio addon prima degli include per gli header node-api. Ciò nasconderà le 2 funzioni che creano buffer esterni. Ciò assicurerà che si verifichi un errore di compilazione se si utilizza accidentalmente uno di questi metodi.
Questa API restituisce un valore Node-API corrispondente a un ArrayBuffer JavaScript. Il buffer di byte sottostante dell'ArrayBuffer è allocato e gestito esternamente. Il chiamante deve garantire che il buffer di byte rimanga valido fino a quando non viene chiamata la callback di finalizzazione.
L'API aggiunge una callback napi_finalize che verrà chiamata quando l'oggetto JavaScript appena creato è stato sottoposto a garbage collection.
Gli ArrayBuffer JavaScript sono descritti nella Sezione 24.1 della Specifiche del Linguaggio ECMAScript.
napi_create_external_buffer
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_external_buffer(napi_env env,
size_t length,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] length: Dimensione in byte del buffer di input (dovrebbe essere uguale alla dimensione del nuovo buffer).[in] data: Puntatore grezzo al buffer sottostante da esporre a JavaScript.[in] finalize_cb: Callback opzionale da chiamare quando l'ArrayBufferviene raccolto.napi_finalizefornisce maggiori dettagli.[in] finalize_hint: Suggerimento opzionale da passare alla callback di finalizzazione durante la raccolta.[out] result: Unnapi_valueche rappresenta unnode::Buffer.
Restituisce napi_ok se l'API ha avuto successo.
Alcuni runtime diversi da Node.js hanno abbandonato il supporto per i buffer esterni. Sui runtime diversi da Node.js, questo metodo può restituire napi_no_external_buffers_allowed per indicare che i buffer esterni non sono supportati. Un runtime di questo tipo è Electron, come descritto in questo problema electron/issues/35801.
Per mantenere la massima compatibilità con tutti i runtime, è possibile definire NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED nel proprio addon prima degli include per le intestazioni node-api. In questo modo si nasconderanno le 2 funzioni che creano buffer esterni. Ciò garantirà che si verifichi un errore di compilazione se si utilizza accidentalmente uno di questi metodi.
Questa API alloca un oggetto node::Buffer e lo inizializza con dati supportati dal buffer passato. Sebbene questa sia ancora una struttura dati completamente supportata, nella maggior parte dei casi l'utilizzo di un TypedArray sarà sufficiente.
L'API aggiunge una callback napi_finalize che verrà chiamata quando l'oggetto JavaScript appena creato è stato sottoposto a garbage collection.
Per Node.js >=4 i Buffer sono Uint8Array.
napi_create_object
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_object(napi_env env, napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[out] result: Unnapi_valueche rappresenta unObjectJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API alloca un Object JavaScript predefinito. È l'equivalente di fare new Object() in JavaScript.
Il tipo Object di JavaScript è descritto nella Sezione 6.1.7 della Specifica del linguaggio ECMAScript.
napi_create_symbol
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_symbol(napi_env env,
napi_value description,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] description:napi_valueopzionale che fa riferimento a unastringJavaScript da impostare come descrizione per il simbolo.[out] result: Unnapi_valueche rappresenta unsymbolJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore symbol JavaScript da una stringa C codificata in UTF8.
Il tipo symbol di JavaScript è descritto nella Sezione 19.4 della Specifica del linguaggio ECMAScript.
node_api_symbol_for
Aggiunto in: v17.5.0, v16.15.0
Versione N-API: 9
napi_status node_api_symbol_for(napi_env env,
const char* utf8description,
size_t length,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] utf8description: Stringa C UTF-8 che rappresenta il testo da utilizzare come descrizione per il simbolo.[in] length: La lunghezza della stringa di descrizione in byte, oNAPI_AUTO_LENGTHse è terminata con null.[out] result: Unnapi_valueche rappresenta unsymbolJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API cerca nel registro globale un simbolo esistente con la descrizione fornita. Se il simbolo esiste già, verrà restituito, altrimenti verrà creato un nuovo simbolo nel registro.
Il tipo symbol di JavaScript è descritto nella Sezione 19.4 della Specifica del linguaggio ECMAScript.
napi_create_typedarray
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_typedarray(napi_env env,
napi_typedarray_type type,
size_t length,
napi_value arraybuffer,
size_t byte_offset,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] type: Tipo di dati scalare degli elementi all'interno diTypedArray.[in] length: Numero di elementi inTypedArray.[in] arraybuffer:ArrayBuffersottostante l'array tipizzato.[in] byte_offset: L'offset di byte all'interno diArrayBufferda cui iniziare a proiettareTypedArray.[out] result: Unnapi_valueche rappresenta unTypedArrayJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un oggetto TypedArray JavaScript su un ArrayBuffer esistente. Gli oggetti TypedArray forniscono una visualizzazione simile a un array su un buffer di dati sottostante in cui ogni elemento ha lo stesso tipo di dati scalare binario sottostante.
È necessario che (length * dimensione_dell'elemento) + byte_offset sia <= alla dimensione in byte dell'array passato. In caso contrario, viene generata un'eccezione RangeError.
Gli oggetti TypedArray JavaScript sono descritti nella Sezione 22.2 della Specifica del Linguaggio ECMAScript.
node_api_create_buffer_from_arraybuffer
Aggiunto in: v23.0.0
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
napi_value arraybuffer,
size_t byte_offset,
size_t byte_length,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] arraybuffer: L'ArrayBufferda cui verrà creato il buffer.[in] byte_offset: L'offset di byte all'interno diArrayBufferda cui iniziare a creare il buffer.[in] byte_length: La lunghezza in byte del buffer da creare daArrayBuffer.[out] result: Unnapi_valueche rappresenta l'oggettoBufferJavaScript creato.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un oggetto Buffer JavaScript da un ArrayBuffer esistente. L'oggetto Buffer è una classe specifica di Node.js che fornisce un modo per lavorare direttamente con dati binari in JavaScript.
L'intervallo di byte [byte_offset, byte_offset + byte_length) deve essere entro i limiti di ArrayBuffer. Se byte_offset + byte_length supera la dimensione di ArrayBuffer, viene generata un'eccezione RangeError.
napi_create_dataview
Aggiunto in: v8.3.0
Versione N-API: 1
napi_status napi_create_dataview(napi_env env,
size_t byte_length,
napi_value arraybuffer,
size_t byte_offset,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] length: Numero di elementi nellaDataView.[in] arraybuffer:ArrayBuffersottostante allaDataView.[in] byte_offset: L'offset di byte all'interno dell'ArrayBufferda cui iniziare a proiettare laDataView.[out] result: Unnapi_valueche rappresenta unDataViewJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un oggetto JavaScript DataView su un ArrayBuffer esistente. Gli oggetti DataView forniscono una visualizzazione simile a un array su un buffer di dati sottostante, ma che consente elementi di dimensioni e tipo diversi nell'ArrayBuffer.
È necessario che byte_length + byte_offset sia minore o uguale alla dimensione in byte dell'array passato. In caso contrario, viene generata un'eccezione RangeError.
Gli oggetti DataView JavaScript sono descritti nella Sezione 24.3 della specifica del linguaggio ECMAScript.
Funzioni per convertire dai tipi C a Node-API
napi_create_int32
Aggiunto in: v8.4.0
Versione N-API: 1
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Valore intero da rappresentare in JavaScript.[out] result: Unnapi_valueche rappresenta unnumberJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API viene utilizzata per convertire dal tipo C int32_t al tipo JavaScript number.
Il tipo JavaScript number è descritto nella Sezione 6.1.6 della specifica del linguaggio ECMAScript.
napi_create_uint32
Aggiunto in: v8.4.0
Versione N-API: 1
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Valore intero senza segno da rappresentare in JavaScript.[out] result: Unnapi_valueche rappresenta unnumberJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API viene utilizzata per convertire il tipo uint32_t C nel tipo number JavaScript.
Il tipo number JavaScript è descritto nella Sezione 6.1.6 della specifica del linguaggio ECMAScript.
napi_create_int64
Aggiunto in: v8.4.0
Versione N-API: 1
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Valore intero da rappresentare in JavaScript.[out] result: Unnapi_valueche rappresenta unnumberJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API viene utilizzata per convertire il tipo int64_t C nel tipo number JavaScript.
Il tipo number JavaScript è descritto nella Sezione 6.1.6 della specifica del linguaggio ECMAScript. Si noti che l'intervallo completo di int64_t non può essere rappresentato con la massima precisione in JavaScript. I valori interi al di fuori dell'intervallo di Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) perderanno precisione.
napi_create_double
Aggiunto in: v8.4.0
Versione N-API: 1
napi_status napi_create_double(napi_env env, double value, napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Valore a doppia precisione da rappresentare in JavaScript.[out] result: Unnapi_valueche rappresenta unnumberJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API viene utilizzata per convertire il tipo double C nel tipo number JavaScript.
Il tipo number JavaScript è descritto nella Sezione 6.1.6 della specifica del linguaggio ECMAScript.
napi_create_bigint_int64
Aggiunto in: v10.7.0
Versione N-API: 6
napi_status napi_create_bigint_int64(napi_env env,
int64_t value,
napi_value* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Valore intero da rappresentare in JavaScript.[out] result: Unnapi_valueche rappresenta unBigIntJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API converte il tipo C int64_t nel tipo BigInt JavaScript.
napi_create_bigint_uint64
Aggiunto in: v10.7.0
Versione N-API: 6
napi_status napi_create_bigint_uint64(napi_env env,
uint64_t value,
napi_value* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Valore intero senza segno da rappresentare in JavaScript.[out] result: Unnapi_valueche rappresenta unBigIntJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API converte il tipo C uint64_t nel tipo BigInt JavaScript.
napi_create_bigint_words
Aggiunto in: v10.7.0
Versione N-API: 6
napi_status napi_create_bigint_words(napi_env env,
int sign_bit,
size_t word_count,
const uint64_t* words,
napi_value* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] sign_bit: Determina se ilBigIntrisultante sarà positivo o negativo.[in] word_count: La lunghezza dell'arraywords.[in] words: Un array di parole a 64 bit little-endianuint64_t.[out] result: Unnapi_valueche rappresenta unBigIntJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API converte un array di parole a 64 bit senza segno in un singolo valore BigInt.
Il BigInt risultante viene calcolato come: (–1) (words[0] × (2) + words[1] × (2) + …)
napi_create_string_latin1
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] str: Buffer di caratteri che rappresenta una stringa con codifica ISO-8859-1.[in] length: La lunghezza della stringa in byte, oNAPI_AUTO_LENGTHse è terminata con null.[out] result: Unnapi_valueche rappresenta unastringdi JavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore string di JavaScript da una stringa C con codifica ISO-8859-1. La stringa nativa viene copiata.
Il tipo string di JavaScript è descritto nella Sezione 6.1.4 della specifica del linguaggio ECMAScript.
node_api_create_external_string_latin1
Aggiunto in: v20.4.0, v18.18.0
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
napi_status
node_api_create_external_string_latin1(napi_env env,
char* str,
size_t length,
napi_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);[in] env: L'ambiente in cui viene invocata l'API.[in] str: Buffer di caratteri che rappresenta una stringa con codifica ISO-8859-1.[in] length: La lunghezza della stringa in byte, oNAPI_AUTO_LENGTHse è terminata con null.[in] finalize_callback: La funzione da chiamare quando la stringa viene raccolta. La funzione verrà chiamata con i seguenti parametri:[in] env: L'ambiente in cui è in esecuzione l'addon. Questo valore potrebbe essere null se la stringa viene raccolta come parte della terminazione del worker o dell'istanza principale di Node.js.[in] data: Questo è il valorestrcome puntatorevoid*.[in] finalize_hint: Questo è il valorefinalize_hintche è stato fornito all'API.napi_finalizefornisce maggiori dettagli. Questo parametro è opzionale. Passare un valore null significa che l'addon non ha bisogno di essere notificato quando la corrispondente stringa JavaScript viene raccolta.
[in] finalize_hint: Suggerimento opzionale da passare al callback di finalizzazione durante la raccolta.[out] result: Unnapi_valueche rappresenta unastringdi JavaScript.[out] copied: Indica se la stringa è stata copiata. Se lo è stata, il finalizzatore sarà già stato invocato per distruggerestr.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore string di JavaScript da una stringa C con codifica ISO-8859-1. La stringa nativa potrebbe non essere copiata e quindi deve esistere per l'intero ciclo di vita del valore JavaScript.
Il tipo string di JavaScript è descritto nella Sezione 6.1.4 della specifica del linguaggio ECMAScript.
napi_create_string_utf16
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] str: Buffer di caratteri che rappresenta una stringa con codifica UTF16-LE.[in] length: La lunghezza della stringa in unità di codice a due byte, oNAPI_AUTO_LENGTHse è terminata con null.[out] result: Unnapi_valueche rappresenta unastringJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore string JavaScript da una stringa C con codifica UTF16-LE. La stringa nativa viene copiata.
Il tipo string JavaScript è descritto nella Sezione 6.1.4 della Specificazione del linguaggio ECMAScript.
node_api_create_external_string_utf16
Aggiunto in: v20.4.0, v18.18.0
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
napi_status
node_api_create_external_string_utf16(napi_env env,
char16_t* str,
size_t length,
napi_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);[in] env: L'ambiente in cui viene richiamata l'API.[in] str: Buffer di caratteri che rappresenta una stringa con codifica UTF16-LE.[in] length: La lunghezza della stringa in unità di codice a due byte, oNAPI_AUTO_LENGTHse è terminata con null.[in] finalize_callback: La funzione da chiamare quando la stringa viene raccolta. La funzione verrà chiamata con i seguenti parametri:[in] env: L'ambiente in cui è in esecuzione l'addon. Questo valore può essere nullo se la stringa viene raccolta come parte della terminazione del worker o dell'istanza principale di Node.js.[in] data: Questo è il valorestrcome puntatorevoid*.[in] finalize_hint: Questo è il valorefinalize_hintche è stato fornito all'API.napi_finalizefornisce maggiori dettagli. Questo parametro è opzionale. Passare un valore nullo significa che l'addon non ha bisogno di essere notificato quando la stringa JavaScript corrispondente viene raccolta.
[in] finalize_hint: Suggerimento opzionale da passare al callback di finalizzazione durante la raccolta.[out] result: Unnapi_valueche rappresenta unastringJavaScript.[out] copied: Indica se la stringa è stata copiata. Se lo è stata, il finalizzatore sarà già stato invocato per distruggerestr.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore string JavaScript da una stringa C con codifica UTF16-LE. La stringa nativa potrebbe non essere copiata e deve quindi esistere per l'intero ciclo di vita del valore JavaScript.
Il tipo string JavaScript è descritto nella Sezione 6.1.4 della Specificazione del linguaggio ECMAScript.
napi_create_string_utf8
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_string_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] str: Buffer di caratteri che rappresenta una stringa con codifica UTF8.[in] length: La lunghezza della stringa in byte, oNAPI_AUTO_LENGTHse è terminata con null.[out] result: Unnapi_valueche rappresenta unastringJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore string JavaScript da una stringa C con codifica UTF8. La stringa nativa viene copiata.
Il tipo string JavaScript è descritto nella Sezione 6.1.4 della specifica del linguaggio ECMAScript.
Funzioni per creare chiavi di proprietà ottimizzate
Molti motori JavaScript, incluso V8, utilizzano stringhe internalizzate come chiavi per impostare e ottenere valori di proprietà. Solitamente utilizzano una tabella hash per creare e cercare tali stringhe. Sebbene aggiunga un certo costo per la creazione di ogni chiave, migliora le prestazioni in seguito consentendo il confronto di puntatori di stringhe anziché dell'intera stringa.
Se una nuova stringa JavaScript deve essere utilizzata come chiave di proprietà, allora per alcuni motori JavaScript sarà più efficiente utilizzare le funzioni in questa sezione. Altrimenti, utilizzare le funzioni della serie napi_create_string_utf8 o node_api_create_external_string_utf8 poiché potrebbero esserci costi aggiuntivi nella creazione/memorizzazione di stringhe con i metodi di creazione di chiavi di proprietà.
node_api_create_property_key_latin1
Aggiunto in: v22.9.0, v20.18.0
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] str: Buffer di caratteri che rappresenta una stringa con codifica ISO-8859-1.[in] length: La lunghezza della stringa in byte, oNAPI_AUTO_LENGTHse è terminata con null.[out] result: Unnapi_valueche rappresenta unastringJavaScript ottimizzata da utilizzare come chiave di proprietà per gli oggetti.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore string JavaScript ottimizzato da una stringa C con codifica ISO-8859-1 da utilizzare come chiave di proprietà per gli oggetti. La stringa nativa viene copiata. A differenza di napi_create_string_latin1, successive chiamate a questa funzione con lo stesso puntatore str possono beneficiare di un aumento di velocità nella creazione del napi_value richiesto, a seconda del motore.
Il tipo string JavaScript è descritto nella Sezione 6.1.4 della specifica del linguaggio ECMAScript.
node_api_create_property_key_utf16
Aggiunto in: v21.7.0, v20.12.0
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] str: Buffer di caratteri che rappresenta una stringa con codifica UTF16-LE.[in] length: La lunghezza della stringa in unità di codice a due byte, oppureNAPI_AUTO_LENGTHse è terminata con null.[out] result: Unnapi_valueche rappresenta unastringJavaScript ottimizzata da utilizzare come chiave di proprietà per gli oggetti.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore string JavaScript ottimizzato da una stringa C con codifica UTF16-LE da utilizzare come chiave di proprietà per gli oggetti. La stringa nativa viene copiata.
Il tipo string JavaScript è descritto nella Sezione 6.1.4 della Specifica del linguaggio ECMAScript.
node_api_create_property_key_utf8
Aggiunto in: v22.9.0, v20.18.0
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] str: Buffer di caratteri che rappresenta una stringa con codifica UTF8.[in] length: La lunghezza della stringa in unità di codice a due byte, oppureNAPI_AUTO_LENGTHse è terminata con null.[out] result: Unnapi_valueche rappresenta unastringJavaScript ottimizzata da utilizzare come chiave di proprietà per gli oggetti.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un valore string JavaScript ottimizzato da una stringa C con codifica UTF8 da utilizzare come chiave di proprietà per gli oggetti. La stringa nativa viene copiata.
Il tipo string JavaScript è descritto nella Sezione 6.1.4 della Specifica del linguaggio ECMAScript.
Funzioni per convertire da Node-API a tipi C
napi_get_array_length
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_array_length(napi_env env,
napi_value value,
uint32_t* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value:napi_valueche rappresenta l'ArrayJavaScript di cui si sta interrogando la lunghezza.[out] result:uint32che rappresenta la lunghezza dell'array.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce la lunghezza di un array.
La lunghezza dell'Array è descritta nella Sezione 22.1.4.1 della specifica del linguaggio ECMAScript.
napi_get_arraybuffer_info
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_arraybuffer_info(napi_env env,
napi_value arraybuffer,
void** data,
size_t* byte_length)[in] env: L'ambiente in cui viene invocata l'API.[in] arraybuffer:napi_valueche rappresenta l'ArrayBufferdi cui si sta effettuando la query.[out] data: Il buffer di dati sottostante dell'ArrayBuffer. Se byte_length è0, questo può essereNULLo qualsiasi altro valore puntatore.[out] byte_length: Lunghezza in byte del buffer di dati sottostante.
Restituisce napi_ok se l'API ha avuto successo.
Questa API viene utilizzata per recuperare il buffer di dati sottostante di un ArrayBuffer e la sua lunghezza.
ATTENZIONE: Usare cautela durante l'utilizzo di questa API. La durata del buffer di dati sottostante è gestita dall'ArrayBuffer anche dopo che è stata restituita. Un modo sicuro possibile per utilizzare questa API è in combinazione con napi_create_reference, che può essere utilizzato per garantire il controllo sulla durata dell'ArrayBuffer. È anche sicuro utilizzare il buffer di dati restituito all'interno della stessa callback fintanto che non ci sono chiamate ad altre API che potrebbero innescare un GC.
napi_get_buffer_info
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_buffer_info(napi_env env,
napi_value value,
void** data,
size_t* length)[in] env: L'ambiente in cui viene richiamata l'API.[in] value:napi_valueche rappresenta ilnode::BufferoUint8Arraysu cui si sta eseguendo la query.[out] data: Il buffer dati sottostante delnode::BufferoUint8Array. Se la lunghezza è0, questo può essereNULLo qualsiasi altro valore puntatore.[out] length: La lunghezza in byte del buffer dati sottostante.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo restituisce data e byte_length identici a napi_get_typedarray_info. E napi_get_typedarray_info accetta anche un node::Buffer (un Uint8Array) come valore.
Questa API viene utilizzata per recuperare il buffer dati sottostante di un node::Buffer e la sua lunghezza.
Avviso: Prestare attenzione quando si utilizza questa API poiché la durata del buffer dati sottostante non è garantita se è gestita dalla VM.
napi_get_prototype
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_prototype(napi_env env,
napi_value object,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] object:napi_valueche rappresenta l'ObjectJavaScript di cui restituire il prototipo. Questo restituisce l'equivalente diObject.getPrototypeOf(che non è lo stesso della proprietàprototypedella funzione).[out] result:napi_valueche rappresenta il prototipo dell'oggetto fornito.
Restituisce napi_ok se l'API ha avuto successo.
napi_get_typedarray_info
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_typedarray_info(napi_env env,
napi_value typedarray,
napi_typedarray_type* type,
size_t* length,
void** data,
napi_value* arraybuffer,
size_t* byte_offset)[in] env: L'ambiente in cui viene richiamata l'API.[in] typedarray:napi_valueche rappresenta ilTypedArraydi cui eseguire la query sulle proprietà.[out] type: Tipo di dati scalare degli elementi all'interno delTypedArray.[out] length: Il numero di elementi nelTypedArray.[out] data: Il buffer di dati sottostante ilTypedArrayadattato dal valorebyte_offsetin modo che punti al primo elemento nelTypedArray. Se la lunghezza dell'array è0, questo può essereNULLo qualsiasi altro valore puntatore.[out] arraybuffer: L'ArrayBuffersottostante ilTypedArray.[out] byte_offset: L'offset in byte all'interno dell'array nativo sottostante in cui si trova il primo elemento degli array. Il valore per il parametro data è già stato modificato in modo che data punti al primo elemento dell'array. Pertanto, il primo byte dell'array nativo sarebbe indata - byte_offset.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce varie proprietà di un array tipizzato.
Qualsiasi dei parametri out può essere NULL se quella proprietà non è necessaria.
Avviso: Prestare attenzione quando si utilizza questa API poiché il buffer di dati sottostante è gestito dalla VM.
napi_get_dataview_info
Aggiunto in: v8.3.0
Versione N-API: 1
napi_status napi_get_dataview_info(napi_env env,
napi_value dataview,
size_t* byte_length,
void** data,
napi_value* arraybuffer,
size_t* byte_offset)[in] env: L'ambiente in cui viene richiamata l'API.[in] dataview:napi_valueche rappresenta laDataViewdi cui interrogare le proprietà.[out] byte_length: Numero di byte nellaDataView.[out] data: Il buffer di dati sottostante allaDataView. Se byte_length è0, questo può essereNULLo qualsiasi altro valore puntatore.[out] arraybuffer:ArrayBuffersottostante allaDataView.[out] byte_offset: L'offset in byte all'interno del buffer di dati da cui iniziare a proiettare laDataView.
Restituisce napi_ok se l'API ha avuto successo.
Qualsiasi dei parametri out può essere NULL se quella proprietà non è necessaria.
Questa API restituisce varie proprietà di una DataView.
napi_get_date_value
Aggiunto in: v11.11.0, v10.17.0
Versione N-API: 5
napi_status napi_get_date_value(napi_env env,
napi_value value,
double* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value:napi_valueche rappresenta unDateJavaScript.[out] result: Valore temporale comedoublerappresentato in millisecondi a partire dalla mezzanotte all'inizio del 01 gennaio 1970 UTC.
Questa API non tiene conto dei secondi intercalari; vengono ignorati, poiché ECMAScript si allinea alla specifica temporale POSIX.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non di tipo data, restituisce napi_date_expected.
Questa API restituisce il valore primitivo C double del valore temporale per il Date JavaScript specificato.
napi_get_value_bool
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value:napi_valueche rappresenta unBooleanJavaScript.[out] result: Primitiva booleana C equivalente alBooleanJavaScript specificato.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non booleano, restituisce napi_boolean_expected.
Questa API restituisce la primitiva booleana C equivalente al Boolean JavaScript specificato.
napi_get_value_double
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_double(napi_env env,
napi_value value,
double* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value:napi_valueche rappresenta unnumberJavaScript.[out] result: Il valore primitivo C double equivalente alnumberJavaScript dato.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value che non è un numero, restituisce napi_number_expected.
Questa API restituisce il valore primitivo C double equivalente al number JavaScript dato.
napi_get_value_bigint_int64
Aggiunto in: v10.7.0
Versione N-API: 6
napi_status napi_get_value_bigint_int64(napi_env env,
napi_value value,
int64_t* result,
bool* lossless);[in] env: L'ambiente in cui viene richiamata l'API[in] value:napi_valueche rappresenta unBigIntJavaScript.[out] result: Il valore primitivo Cint64_tequivalente alBigIntJavaScript dato.[out] lossless: Indica se il valoreBigIntè stato convertito senza perdita di dati.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un valore che non è BigInt, restituisce napi_bigint_expected.
Questa API restituisce il valore primitivo C int64_t equivalente al BigInt JavaScript dato. Se necessario, troncherà il valore, impostando lossless a false.
napi_get_value_bigint_uint64
Aggiunto in: v10.7.0
Versione N-API: 6
napi_status napi_get_value_bigint_uint64(napi_env env,
napi_value value,
uint64_t* result,
bool* lossless);[in] env: L'ambiente in cui viene richiamata l'API.[in] value:napi_valueche rappresenta unBigIntJavaScript.[out] result: Il valore primitivo Cuint64_tequivalente alBigIntJavaScript dato.[out] lossless: Indica se il valoreBigIntè stato convertito senza perdita di dati.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un valore che non è BigInt, restituisce napi_bigint_expected.
Questa API restituisce il valore primitivo C uint64_t equivalente al BigInt JavaScript dato. Se necessario, troncherà il valore, impostando lossless a false.
napi_get_value_bigint_words
Aggiunto in: v10.7.0
Versione N-API: 6
napi_status napi_get_value_bigint_words(napi_env env,
napi_value value,
int* sign_bit,
size_t* word_count,
uint64_t* words);[in] env: L'ambiente in cui viene invocata l'API.[in] value:napi_valueche rappresenta unBigIntJavaScript.[out] sign_bit: Numero intero che rappresenta se ilBigIntJavaScript è positivo o negativo.[in/out] word_count: Deve essere inizializzato con la lunghezza dell'arraywords. Al ritorno, verrà impostato con il numero effettivo di word necessari per memorizzare questoBigInt.[out] words: Puntatore a un array di word a 64 bit pre-allocato.
Restituisce napi_ok se l'API ha avuto successo.
Questa API converte un singolo valore BigInt in un bit di segno, un array little-endian a 64 bit e il numero di elementi nell'array. sign_bit e words possono essere entrambi impostati su NULL, al fine di ottenere solo word_count.
napi_get_value_external
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_external(napi_env env,
napi_value value,
void** result)[in] env: L'ambiente in cui viene invocata l'API.[in] value:napi_valueche rappresenta un valore esterno JavaScript.[out] result: Puntatore ai dati incapsulati dal valore esterno JavaScript.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non esterno, restituisce napi_invalid_arg.
Questa API recupera il puntatore ai dati esterni che era stato precedentemente passato a napi_create_external().
napi_get_value_int32
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_int32(napi_env env,
napi_value value,
int32_t* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value:napi_valueche rappresenta unnumberJavaScript.[out] result: Primitiva Cint32equivalente alnumberJavaScript fornito.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non-number viene restituito napi_number_expected.
Questa API restituisce la primitiva C int32 equivalente al number JavaScript fornito.
Se il numero supera l'intervallo dell'intero a 32 bit, il risultato viene troncato all'equivalente dei 32 bit inferiori. Ciò può comportare che un grande numero positivo diventi un numero negativo se il valore è > 2 - 1.
I valori numerici non finiti (NaN, +Infinity o -Infinity) impostano il risultato su zero.
napi_get_value_int64
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_int64(napi_env env,
napi_value value,
int64_t* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value:napi_valueche rappresenta unnumberJavaScript.[out] result: Primitiva Cint64equivalente alnumberJavaScript specificato.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non di tipo numero, restituisce napi_number_expected.
Questa API restituisce la primitiva C int64 equivalente al number JavaScript specificato.
I valori number al di fuori dell'intervallo di Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) perderanno precisione.
I valori numerici non finiti (NaN, +Infinity o -Infinity) impostano il risultato a zero.
napi_get_value_string_latin1
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_string_latin1(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value:napi_valueche rappresenta una stringa JavaScript.[in] buf: Buffer in cui scrivere la stringa codificata ISO-8859-1. Se viene passatoNULL, la lunghezza della stringa in byte, escluso il terminatore nullo, viene restituita inresult.[in] bufsize: Dimensione del buffer di destinazione. Quando questo valore è insufficiente, la stringa restituita viene troncata e terminata con null.[out] result: Numero di byte copiati nel buffer, escluso il terminatore nullo.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non di tipo string, restituisce napi_string_expected.
Questa API restituisce la stringa codificata ISO-8859-1 corrispondente al valore passato.
napi_get_value_string_utf8
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_string_utf8(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value:napi_valueche rappresenta una stringa JavaScript.[in] buf: Buffer in cui scrivere la stringa codificata UTF8. Se viene passatoNULL, la lunghezza della stringa in byte, escluso il terminatore null, viene restituita inresult.[in] bufsize: Dimensione del buffer di destinazione. Se questo valore è insufficiente, la stringa restituita viene troncata e terminata con null.[out] result: Numero di byte copiati nel buffer, escluso il terminatore null.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non di tipo string, restituisce napi_string_expected.
Questa API restituisce la stringa codificata UTF8 corrispondente al valore passato.
napi_get_value_string_utf16
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_string_utf16(napi_env env,
napi_value value,
char16_t* buf,
size_t bufsize,
size_t* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value:napi_valueche rappresenta una stringa JavaScript.[in] buf: Buffer in cui scrivere la stringa codificata UTF16-LE. Se viene passatoNULL, viene restituita la lunghezza della stringa in unità di codice di 2 byte, escluso il terminatore null.[in] bufsize: Dimensione del buffer di destinazione. Se questo valore è insufficiente, la stringa restituita viene troncata e terminata con null.[out] result: Numero di unità di codice di 2 byte copiate nel buffer, escluso il terminatore null.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non di tipo string, restituisce napi_string_expected.
Questa API restituisce la stringa codificata UTF16 corrispondente al valore passato.
napi_get_value_uint32
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_value_uint32(napi_env env,
napi_value value,
uint32_t* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value:napi_valueche rappresenta unnumberJavaScript.[out] result: Primitiva C equivalente alnapi_valuedato comeuint32_t.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un napi_value non numerico, restituisce napi_number_expected.
Questa API restituisce la primitiva C equivalente del napi_value dato come uint32_t.
Funzioni per ottenere istanze globali
napi_get_boolean
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Il valore del booleano da recuperare.[out] result:napi_valueche rappresenta il singletonBooleandi JavaScript da recuperare.
Restituisce napi_ok se l'API ha avuto successo.
Questa API viene utilizzata per restituire l'oggetto singleton JavaScript che viene utilizzato per rappresentare il valore booleano dato.
napi_get_global
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_global(napi_env env, napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[out] result:napi_valueche rappresenta l'oggettoglobalJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce l'oggetto global.
napi_get_null
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_null(napi_env env, napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[out] result:napi_valueche rappresenta l'oggettonullJavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce l'oggetto null.
napi_get_undefined
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_undefined(napi_env env, napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[out] result:napi_valueche rappresenta il valore Undefined JavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce l'oggetto Undefined.
Lavorare con i valori JavaScript e le operazioni astratte
Node-API espone un insieme di API per eseguire alcune operazioni astratte sui valori JavaScript. Alcune di queste operazioni sono documentate nella Sezione 7 della Specifica del Linguaggio ECMAScript.
Queste API supportano l'esecuzione di una delle seguenti operazioni:
napi_coerce_to_bool
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_coerce_to_bool(napi_env env,
napi_value value,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Il valore JavaScript da coercire.[out] result:napi_valueche rappresenta ilBooleanJavaScript coercito.
Restituisce napi_ok se l'API ha avuto successo.
Questa API implementa l'operazione astratta ToBoolean() come definito nella Sezione 7.1.2 della Specifica del Linguaggio ECMAScript.
napi_coerce_to_number
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_coerce_to_number(napi_env env,
napi_value value,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Il valore JavaScript da coercire.[out] result:napi_valueche rappresenta ilnumberJavaScript coercito.
Restituisce napi_ok se l'API ha avuto successo.
Questa API implementa l'operazione astratta ToNumber() come definito nella Sezione 7.1.3 della Specifica del Linguaggio ECMAScript. Questa funzione potenzialmente esegue codice JS se il valore passato è un oggetto.
napi_coerce_to_object
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_coerce_to_object(napi_env env,
napi_value value,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Il valore JavaScript da coercire.[out] result:napi_valueche rappresenta l'ObjectJavaScript coercito.
Restituisce napi_ok se l'API ha avuto successo.
Questa API implementa l'operazione astratta ToObject() come definito nella Sezione 7.1.13 della Specifica del Linguaggio ECMAScript.
napi_coerce_to_string
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_coerce_to_string(napi_env env,
napi_value value,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Il valore JavaScript da convertire.[out] result:napi_valueche rappresenta lastringJavaScript convertita.
Restituisce napi_ok se l'API ha avuto successo.
Questa API implementa l'operazione astratta ToString() come definito nella Sezione 7.1.13 delle Specifiche del linguaggio ECMAScript. Questa funzione potenzialmente esegue codice JS se il valore passato è un oggetto.
napi_typeof
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)[in] env: L'ambiente in cui viene invocata l'API.[in] value: Il valore JavaScript di cui si vuole interrogare il tipo.[out] result: Il tipo del valore JavaScript.
Restituisce napi_ok se l'API ha avuto successo.
napi_invalid_argse il tipo divaluenon è un tipo ECMAScript noto evaluenon è un valore Esterno.
Questa API rappresenta un comportamento simile all'invocazione dell'operatore typeof sull'oggetto come definito nella Sezione 12.5.5 delle Specifiche del linguaggio ECMAScript. Tuttavia, ci sono alcune differenze:
Se value ha un tipo non valido, viene restituito un errore.
napi_instanceof
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_instanceof(napi_env env,
napi_value object,
napi_value constructor,
bool* result)[in] env: L'ambiente in cui viene invocata l'API.[in] object: Il valore JavaScript da controllare.[in] constructor: L'oggetto funzione JavaScript della funzione costruttore rispetto alla quale effettuare il controllo.[out] result: Booleano impostato a true seobject instanceof constructorè true.
Restituisce napi_ok se l'API ha avuto successo.
Questa API rappresenta l'invocazione dell'operatore instanceof sull'oggetto come definito nella Sezione 12.10.4 delle Specifiche del linguaggio ECMAScript.
napi_is_array
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_is_array(napi_env env, napi_value value, bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Il valore JavaScript da controllare.[out] result: Indica se l'oggetto specificato è un array.
Restituisce napi_ok se l'API ha avuto successo.
Questa API rappresenta l'invocazione dell'operazione IsArray sull'oggetto come definito nella Sezione 7.2.2 della specifica del linguaggio ECMAScript.
napi_is_arraybuffer
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Il valore JavaScript da controllare.[out] result: Indica se l'oggetto specificato è unArrayBuffer.
Restituisce napi_ok se l'API ha avuto successo.
Questa API verifica se l'Object passato è un array buffer.
napi_is_buffer
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Il valore JavaScript da controllare.[out] result: Indica se ilnapi_valuespecificato rappresenta un oggettonode::BufferoUint8Array.
Restituisce napi_ok se l'API ha avuto successo.
Questa API verifica se l'Object passato è un buffer o Uint8Array. napi_is_typedarray dovrebbe essere preferito se il chiamante deve verificare se il valore è un Uint8Array.
napi_is_date
Aggiunto in: v11.11.0, v10.17.0
Versione N-API: 5
napi_status napi_is_date(napi_env env, napi_value value, bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Il valore JavaScript da controllare.[out] result: Indica se ilnapi_valuespecificato rappresenta un oggetto JavaScriptDate.
Restituisce napi_ok se l'API ha avuto successo.
Questa API verifica se l'Object passato è una data.
napi_is_error
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_is_error(napi_env env, napi_value value, bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Il valore JavaScript da controllare.[out] result: Indica se ilnapi_valuefornito rappresenta un oggettoError.
Restituisce napi_ok se l'API ha avuto successo.
Questa API verifica se l'Object passato è un Error.
napi_is_typedarray
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Il valore JavaScript da controllare.[out] result: Indica se ilnapi_valuefornito rappresenta unTypedArray.
Restituisce napi_ok se l'API ha avuto successo.
Questa API verifica se l'Object passato è un array tipizzato.
napi_is_dataview
Aggiunto in: v8.3.0
Versione N-API: 1
napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] value: Il valore JavaScript da controllare.[out] result: Indica se ilnapi_valuefornito rappresenta unDataView.
Restituisce napi_ok se l'API ha avuto successo.
Questa API verifica se l'Object passato è un DataView.
napi_strict_equals
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_strict_equals(napi_env env,
napi_value lhs,
napi_value rhs,
bool* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] lhs: Il valore JavaScript da controllare.[in] rhs: Il valore JavaScript con cui confrontare.[out] result: Indica se i due oggettinapi_valuesono uguali.
Restituisce napi_ok se l'API ha avuto successo.
Questa API rappresenta l'invocazione dell'algoritmo di uguaglianza stretta come definito nella Sezione 7.2.14 della specifica del linguaggio ECMAScript.
napi_detach_arraybuffer
Aggiunto in: v13.0.0, v12.16.0, v10.22.0
Versione N-API: 7
napi_status napi_detach_arraybuffer(napi_env env,
napi_value arraybuffer)[in] env: L'ambiente in cui viene invocata l'API.[in] arraybuffer: IlArrayBufferJavaScript da scollegare.
Restituisce napi_ok se l'API ha avuto successo. Se viene passato un ArrayBuffer non scollegabile, restituisce napi_detachable_arraybuffer_expected.
Generalmente, un ArrayBuffer non è scollegabile se è stato scollegato in precedenza. Il motore può imporre ulteriori condizioni sulla scollegabilità di un ArrayBuffer. Ad esempio, V8 richiede che ArrayBuffer sia esterno, ovvero creato con napi_create_external_arraybuffer.
Questa API rappresenta l'invocazione dell'operazione di scollegamento di ArrayBuffer come definito nella Sezione 24.1.1.3 della Specificazione del Linguaggio ECMAScript.
napi_is_detached_arraybuffer
Aggiunto in: v13.3.0, v12.16.0, v10.22.0
Versione N-API: 7
napi_status napi_is_detached_arraybuffer(napi_env env,
napi_value arraybuffer,
bool* result)[in] env: L'ambiente in cui viene invocata l'API.[in] arraybuffer: IlArrayBufferJavaScript da controllare.[out] result: Indica se l'arraybufferè scollegato.
Restituisce napi_ok se l'API ha avuto successo.
L'ArrayBuffer è considerato scollegato se i suoi dati interni sono null.
Questa API rappresenta l'invocazione dell'operazione IsDetachedBuffer di ArrayBuffer come definito nella Sezione 24.1.1.2 della Specificazione del Linguaggio ECMAScript.
Lavorare con le proprietà JavaScript
Node-API espone una serie di API per ottenere e impostare proprietà su oggetti JavaScript. Alcuni di questi tipi sono documentati nella Sezione 7 della Specificazione del Linguaggio ECMAScript.
Le proprietà in JavaScript sono rappresentate come una tupla di una chiave e un valore. Fondamentalmente, tutte le chiavi di proprietà in Node-API possono essere rappresentate in una delle seguenti forme:
- Nome: una semplice stringa codificata UTF8
- Indicizzata per intero: un valore di indice rappresentato da
uint32_t - Valore JavaScript: questi sono rappresentati in Node-API da
napi_value. Questo può essere unnapi_valueche rappresenta unastring, unnumbero unsymbol.
I valori Node-API sono rappresentati dal tipo napi_value. Qualsiasi chiamata Node-API che richiede un valore JavaScript accetta un napi_value. Tuttavia, è responsabilità del chiamante assicurarsi che il napi_value in questione sia del tipo JavaScript previsto dall'API.
Le API documentate in questa sezione forniscono una semplice interfaccia per ottenere e impostare proprietà su oggetti JavaScript arbitrari rappresentati da napi_value.
Ad esempio, considera il seguente frammento di codice JavaScript:
const obj = {}
obj.myProp = 123L'equivalente può essere fatto usando i valori Node-API con il seguente frammento:
napi_status status = napi_generic_failure;
// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Crea un napi_value per 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;Le proprietà indicizzate possono essere impostate in modo simile. Considera il seguente frammento di codice JavaScript:
const arr = []
arr[123] = 'hello'L'equivalente può essere fatto usando i valori Node-API con il seguente frammento:
napi_status status = napi_generic_failure;
// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// Crea un napi_value per '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;Le proprietà possono essere recuperate utilizzando le API descritte in questa sezione. Considera il seguente frammento di codice JavaScript:
const arr = []
const value = arr[123]Il seguente è l'equivalente approssimativo della controparte Node-API:
napi_status status = napi_generic_failure;
// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status;Infine, più proprietà possono anche essere definite su un oggetto per motivi di prestazioni. Considera il seguente JavaScript:
const obj = {}
Object.defineProperties(obj, {
foo: { value: 123, writable: true, configurable: true, enumerable: true },
bar: { value: 456, writable: true, configurable: true, enumerable: true },
})Il seguente è l'equivalente approssimativo della controparte Node-API:
napi_status status = napi_status_generic_failure;
// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Crea napi_values per 123 e 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;
// Imposta le proprietà
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;Strutture
napi_property_attributes
[Cronologia]
| Versione | Cambiamenti |
|---|---|
| v14.12.0 | aggiunti napi_default_method e napi_default_property. |
typedef enum {
napi_default = 0,
napi_writable = 1 << 0,
napi_enumerable = 1 << 1,
napi_configurable = 1 << 2,
// Usato con napi_define_class per distinguere le proprietà statiche
// dalle proprietà di istanza. Ignorato da napi_define_properties.
napi_static = 1 << 10,
// Predefinito per i metodi delle classi.
napi_default_method = napi_writable | napi_configurable,
// Predefinito per le proprietà degli oggetti, come in JS obj[prop].
napi_default_jsproperty = napi_writable |
napi_enumerable |
napi_configurable,
} napi_property_attributes;napi_property_attributes sono flag utilizzati per controllare il comportamento delle proprietà impostate su un oggetto JavaScript. Ad eccezione di napi_static corrispondono agli attributi elencati nella Sezione 6.1.7.1 della Specificazione del linguaggio ECMAScript. Possono essere uno o più dei seguenti bitflag:
napi_default: Nessun attributo esplicito è impostato sulla proprietà. Per impostazione predefinita, una proprietà è di sola lettura, non enumerabile e non configurabile.napi_writable: La proprietà è scrivibile.napi_enumerable: La proprietà è enumerabile.napi_configurable: La proprietà è configurabile come definito nella Sezione 6.1.7.1 della Specificazione del linguaggio ECMAScript.napi_static: La proprietà sarà definita come proprietà statica su una classe anziché come proprietà di istanza, che è l'impostazione predefinita. Questo è usato solo danapi_define_class. È ignorato danapi_define_properties.napi_default_method: Come un metodo in una classe JS, la proprietà è configurabile e scrivibile, ma non enumerabile.napi_default_jsproperty: Come una proprietà impostata tramite assegnazione in JavaScript, la proprietà è scrivibile, enumerabile e configurabile.
napi_property_descriptor
typedef struct {
// Uno tra utf8name o name deve essere NULL.
const char* utf8name;
napi_value name;
napi_callback method;
napi_callback getter;
napi_callback setter;
napi_value value;
napi_property_attributes attributes;
void* data;
} napi_property_descriptor;utf8name: Stringa opzionale che descrive la chiave per la proprietà, codificata come UTF8. Uno trautf8nameonamedeve essere fornito per la proprietà.name:napi_valueopzionale che punta a una stringa JavaScript o a un simbolo da utilizzare come chiave per la proprietà. Uno trautf8nameonamedeve essere fornito per la proprietà.value: Il valore che viene recuperato da un accesso get della proprietà se la proprietà è una proprietà dati. Se questo viene passato, impostagetter,setter,methodedataaNULL(poiché questi membri non saranno utilizzati).getter: Una funzione da chiamare quando viene eseguito un accesso get della proprietà. Se questo viene passato, impostavalueemethodaNULL(poiché questi membri non saranno utilizzati). La funzione fornita viene chiamata implicitamente dal runtime quando si accede alla proprietà dal codice JavaScript (o se viene eseguito un get sulla proprietà utilizzando una chiamata Node-API).napi_callbackfornisce maggiori dettagli.setter: Una funzione da chiamare quando viene eseguito un accesso set della proprietà. Se questo viene passato, impostavalueemethodaNULL(poiché questi membri non saranno utilizzati). La funzione fornita viene chiamata implicitamente dal runtime quando la proprietà viene impostata dal codice JavaScript (o se viene eseguito un set sulla proprietà utilizzando una chiamata Node-API).napi_callbackfornisce maggiori dettagli.method: Imposta questo per fare in modo che la proprietàvaluedell'oggetto descrittore di proprietà sia una funzione JavaScript rappresentata damethod. Se questo viene passato, impostavalue,getteresetteraNULL(poiché questi membri non saranno utilizzati).napi_callbackfornisce maggiori dettagli.attributes: Gli attributi associati alla particolare proprietà. Vederenapi_property_attributes.data: I dati di callback passati amethod,getteresetterse questa funzione viene invocata.
Funzioni
napi_get_property_names
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_property_names(napi_env env,
napi_value object,
napi_value* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da cui recuperare le proprietà.[out] result: Unnapi_valueche rappresenta un array di valori JavaScript che rappresentano i nomi delle proprietà dell'oggetto. L'API può essere utilizzata per iterare suresultusandonapi_get_array_lengthenapi_get_element.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce i nomi delle proprietà enumerabili di object come un array di stringhe. Le proprietà di object la cui chiave è un simbolo non saranno incluse.
napi_get_all_property_names
Aggiunto in: v13.7.0, v12.17.0, v10.20.0
Versione N-API: 6
napi_get_all_property_names(napi_env env,
napi_value object,
napi_key_collection_mode key_mode,
napi_key_filter key_filter,
napi_key_conversion key_conversion,
napi_value* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da cui recuperare le proprietà.[in] key_mode: Indica se recuperare anche le proprietà del prototipo.[in] key_filter: Indica quali proprietà recuperare (enumerabili/leggibili/scrivibili).[in] key_conversion: Indica se convertire le chiavi di proprietà numerate in stringhe.[out] result: Unnapi_valueche rappresenta un array di valori JavaScript che rappresentano i nomi delle proprietà dell'oggetto.napi_get_array_lengthenapi_get_elementpossono essere utilizzati per iterare suresult.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce un array contenente i nomi delle proprietà disponibili di questo oggetto.
napi_set_property
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_set_property(napi_env env,
napi_value object,
napi_value key,
napi_value value);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto su cui impostare la proprietà.[in] key: Il nome della proprietà da impostare.[in] value: Il valore della proprietà.
Restituisce napi_ok se l'API ha avuto successo.
Questa API imposta una proprietà sull'Oggetto passato.
napi_get_property
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_property(napi_env env,
napi_value object,
napi_value key,
napi_value* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da cui recuperare la proprietà.[in] key: Il nome della proprietà da recuperare.[out] result: Il valore della proprietà.
Restituisce napi_ok se l'API ha avuto successo.
Questa API ottiene la proprietà richiesta dall'Oggetto passato.
napi_has_property
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_has_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da interrogare.[in] key: Il nome della proprietà di cui verificare l'esistenza.[out] result: Indica se la proprietà esiste o meno sull'oggetto.
Restituisce napi_ok se l'API ha avuto successo.
Questa API controlla se l'Oggetto passato ha la proprietà con il nome specificato.
napi_delete_property
Aggiunto in: v8.2.0
Versione N-API: 1
napi_status napi_delete_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da interrogare.[in] key: Il nome della proprietà da eliminare.[out] result: Indica se l'eliminazione della proprietà ha avuto successo o meno.resultpuò essere facoltativamente ignorato passandoNULL.
Restituisce napi_ok se l'API ha avuto successo.
Questa API tenta di eliminare la proprietà propria key dall'oggetto.
napi_has_own_property
Aggiunto in: v8.2.0
Versione N-API: 1
napi_status napi_has_own_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da interrogare.[in] key: Il nome della proprietà propria di cui verificare l'esistenza.[out] result: Indica se la proprietà propria esiste o meno sull'oggetto.
Restituisce napi_ok se l'API ha avuto successo.
Questa API verifica se l'Object passato ha la proprietà propria con il nome specificato. key deve essere una stringa o un simbolo, altrimenti verrà generato un errore. Node-API non eseguirà alcuna conversione tra tipi di dati.
napi_set_named_property
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_set_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value value);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto su cui impostare la proprietà.[in] utf8Name: Il nome della proprietà da impostare.[in] value: Il valore della proprietà.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo è equivalente a chiamare napi_set_property con un napi_value creato dalla stringa passata come utf8Name.
napi_get_named_property
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da cui recuperare la proprietà.[in] utf8Name: Il nome della proprietà da ottenere.[out] result: Il valore della proprietà.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo è equivalente a chiamare napi_get_property con un napi_value creato dalla stringa passata come utf8Name.
napi_has_named_property
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_has_named_property(napi_env env,
napi_value object,
const char* utf8Name,
bool* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da interrogare.[in] utf8Name: Il nome della proprietà di cui verificare l'esistenza.[out] result: Indica se la proprietà esiste o meno sull'oggetto.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo è equivalente a chiamare napi_has_property con un napi_value creato dalla stringa passata come utf8Name.
napi_set_element
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_set_element(napi_env env,
napi_value object,
uint32_t index,
napi_value value);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da cui impostare le proprietà.[in] index: L'indice della proprietà da impostare.[in] value: Il valore della proprietà.
Restituisce napi_ok se l'API ha avuto successo.
Questa API imposta un elemento sull'Oggetto passato.
napi_get_element
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_element(napi_env env,
napi_value object,
uint32_t index,
napi_value* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da cui recuperare la proprietà.[in] index: L'indice della proprietà da ottenere.[out] result: Il valore della proprietà.
Restituisce napi_ok se l'API ha avuto successo.
Questa API ottiene l'elemento all'indice richiesto.
napi_has_element
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_has_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da interrogare.[in] index: L'indice della proprietà di cui verificare l'esistenza.[out] result: Indica se la proprietà esiste o meno sull'oggetto.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce se l'Oggetto passato ha un elemento all'indice richiesto.
napi_delete_element
Aggiunto in: v8.2.0
Versione N-API: 1
napi_status napi_delete_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da interrogare.[in] index: L'indice della proprietà da eliminare.[out] result: Indica se l'eliminazione dell'elemento è andata a buon fine o meno.resultpuò essere facoltativamente ignorato passandoNULL.
Restituisce napi_ok se l'API ha avuto successo.
Questa API tenta di eliminare l'index specificato da object.
napi_define_properties
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_define_properties(napi_env env,
napi_value object,
size_t property_count,
const napi_property_descriptor* properties);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da cui recuperare le proprietà.[in] property_count: Il numero di elementi nell'arrayproperties.[in] properties: L'array di descrittori di proprietà.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo consente la definizione efficiente di più proprietà su un determinato oggetto. Le proprietà sono definite usando i descrittori di proprietà (vedi napi_property_descriptor). Dato un array di tali descrittori di proprietà, questa API imposterà le proprietà sull'oggetto una alla volta, come definito da DefineOwnProperty() (descritto nella Sezione 9.1.6 della specifica ECMA-262).
napi_object_freeze
Aggiunto in: v14.14.0, v12.20.0
Versione N-API: 8
napi_status napi_object_freeze(napi_env env,
napi_value object);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da bloccare.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo blocca un determinato oggetto. Ciò impedisce l'aggiunta di nuove proprietà, la rimozione di proprietà esistenti, impedisce la modifica dell'enumerabilità, della configurabilità o della scrivibilità delle proprietà esistenti e impedisce la modifica dei valori delle proprietà esistenti. Impedisce inoltre la modifica del prototipo dell'oggetto. Questo è descritto nella Sezione 19.1.2.6 della specifica ECMA-262.
napi_object_seal
Aggiunto in: v14.14.0, v12.20.0
Versione N-API: 8
napi_status napi_object_seal(napi_env env,
napi_value object);[in] env: L'ambiente in cui viene invocata la chiamata Node-API.[in] object: L'oggetto da sigillare.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo sigilla un dato oggetto. Ciò impedisce che nuove proprietà vengano aggiunte ad esso, oltre a contrassegnare tutte le proprietà esistenti come non configurabili. Ciò è descritto nella Sezione 19.1.2.20 della specifica ECMA-262.
Lavorare con le funzioni JavaScript
Node-API fornisce una serie di API che consentono al codice JavaScript di richiamare il codice nativo. Le API Node che supportano il richiamo al codice nativo accettano funzioni di callback rappresentate dal tipo napi_callback. Quando la VM JavaScript richiama il codice nativo, viene invocata la funzione napi_callback fornita. Le API documentate in questa sezione consentono alla funzione di callback di fare quanto segue:
- Ottenere informazioni sul contesto in cui è stato invocato il callback.
- Ottenere gli argomenti passati al callback.
- Restituire un
napi_valuedal callback.
Inoltre, Node-API fornisce una serie di funzioni che consentono di chiamare funzioni JavaScript dal codice nativo. Si può chiamare una funzione come una normale chiamata di funzione JavaScript, o come una funzione costruttore.
Qualsiasi dato non NULL passato a questa API tramite il campo data degli elementi napi_property_descriptor può essere associato a object e liberato ogni volta che object viene raccolto come spazzatura passando sia object che i dati a napi_add_finalizer.
napi_call_function
Aggiunto in: v8.0.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_call_function(napi_env env,
napi_value recv,
napi_value func,
size_t argc,
const napi_value* argv,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] recv: Il valorethispassato alla funzione chiamata.[in] func:napi_valueche rappresenta la funzione JavaScript da invocare.[in] argc: Il conteggio degli elementi nell'arrayargv.[in] argv: Array dinapi_valuesche rappresentano valori JavaScript passati come argomenti alla funzione.[out] result:napi_valueche rappresenta l'oggetto JavaScript restituito.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo consente di chiamare un oggetto funzione JavaScript da un componente aggiuntivo nativo. Questo è il meccanismo principale per richiamare dal codice nativo del componente aggiuntivo in JavaScript. Per il caso speciale di richiamare JavaScript dopo un'operazione asincrona, vedere napi_make_callback.
Un caso d'uso di esempio potrebbe essere il seguente. Considera il seguente frammento JavaScript:
function AddTwo(num) {
return num + 2
}
global.AddTwo = AddTwoQuindi, la funzione sopra può essere invocata da un componente aggiuntivo nativo usando il seguente codice:
// Ottieni la funzione chiamata "AddTwo" sull'oggetto globale
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;
// Converti il risultato di nuovo in un tipo nativo
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;napi_create_function
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_create_function(napi_env env,
const char* utf8name,
size_t length,
napi_callback cb,
void* data,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] utf8Name: Nome opzionale della funzione codificato come UTF8. Questo è visibile all'interno di JavaScript come proprietànamedel nuovo oggetto funzione.[in] length: La lunghezza diutf8namein byte, oNAPI_AUTO_LENGTHse è terminato con null.[in] cb: La funzione nativa che deve essere chiamata quando viene invocato questo oggetto funzione.napi_callbackfornisce maggiori dettagli.[in] data: Contesto di dati fornito dall'utente. Questo verrà ripassato alla funzione quando verrà invocata in seguito.[out] result:napi_valueche rappresenta l'oggetto funzione JavaScript per la funzione appena creata.
Restituisce napi_ok se l'API ha avuto successo.
Questa API consente a un autore di add-on di creare un oggetto funzione nel codice nativo. Questo è il meccanismo principale per consentire la chiamata nel codice nativo dell'add-on da JavaScript.
La funzione appena creata non è automaticamente visibile dallo script dopo questa chiamata. Invece, una proprietà deve essere esplicitamente impostata su qualsiasi oggetto visibile a JavaScript, affinché la funzione sia accessibile dallo script.
Per esporre una funzione come parte delle esportazioni del modulo dell'add-on, impostare la funzione appena creata sull'oggetto exports. Un modulo di esempio potrebbe apparire come segue:
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)Dato il codice di cui sopra, l'add-on può essere utilizzato da JavaScript come segue:
const myaddon = require('./addon')
myaddon.sayHello()La stringa passata a require() è il nome del target in binding.gyp responsabile della creazione del file .node.
Qualsiasi dato non-NULL che viene passato a questa API tramite il parametro data può essere associato alla funzione JavaScript risultante (che viene restituita nel parametro result) e liberato ogni volta che la funzione viene raccolta come spazzatura passando sia la funzione JavaScript che i dati a napi_add_finalizer.
Le Function di JavaScript sono descritte nella Sezione 19.2 della Specifica del linguaggio ECMAScript.
napi_get_cb_info
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_cb_info(napi_env env,
napi_callback_info cbinfo,
size_t* argc,
napi_value* argv,
napi_value* thisArg,
void** data)[in] env: L'ambiente in cui viene invocata l'API.[in] cbinfo: Le informazioni di callback passate alla funzione di callback.[in-out] argc: Specifica la lunghezza dell'arrayargvfornito e riceve il conteggio effettivo degli argomenti.argcpuò essere opzionalmente ignorato passandoNULL.[out] argv: Array C dinapi_valuein cui verranno copiati gli argomenti. Se ci sono più argomenti rispetto al conteggio fornito, viene copiato solo il numero richiesto di argomenti. Se ci sono meno argomenti forniti di quelli dichiarati, il resto diargvviene riempito con valorinapi_valueche rappresentanoundefined.argvpuò essere opzionalmente ignorato passandoNULL.[out] thisArg: Riceve l'argomento JavaScriptthisper la chiamata.thisArgpuò essere opzionalmente ignorato passandoNULL.[out] data: Riceve il puntatore ai dati per il callback.datapuò essere opzionalmente ignorato passandoNULL.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo viene utilizzato all'interno di una funzione di callback per recuperare i dettagli sulla chiamata come gli argomenti e il puntatore this da una determinata informazione di callback.
napi_get_new_target
Aggiunto in: v8.6.0
Versione N-API: 1
napi_status napi_get_new_target(napi_env env,
napi_callback_info cbinfo,
napi_value* result)[in] env: L'ambiente in cui viene invocata l'API.[in] cbinfo: Le informazioni di callback passate alla funzione di callback.[out] result: Ilnew.targetdella chiamata al costruttore.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce il new.target della chiamata al costruttore. Se il callback corrente non è una chiamata al costruttore, il risultato è NULL.
napi_new_instance
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_new_instance(napi_env env,
napi_value cons,
size_t argc,
napi_value* argv,
napi_value* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] cons:napi_valueche rappresenta la funzione JavaScript da richiamare come costruttore.[in] argc: Il numero di elementi nell'arrayargv.[in] argv: Array di valori JavaScript comenapi_valueche rappresentano gli argomenti del costruttore. Seargcè zero, questo parametro può essere omesso passandoNULL.[out] result:napi_valueche rappresenta l'oggetto JavaScript restituito, che in questo caso è l'oggetto costruito.
Questo metodo viene utilizzato per istanziare un nuovo valore JavaScript utilizzando un dato napi_value che rappresenta il costruttore per l'oggetto. Ad esempio, considera il seguente snippet:
function MyObject(param) {
this.param = param
}
const arg = 'hello'
const value = new MyObject(arg)Quanto segue può essere approssimato in Node-API utilizzando il seguente snippet:
// Ottieni la funzione costruttore MyObject
napi_value global, constructor, arg, value;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;
status = napi_get_named_property(env, global, "MyObject", &constructor);
if (status != napi_ok) return;
// const arg = "hello"
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg);
if (status != napi_ok) return;
napi_value* argv = &arg;
size_t argc = 1;
// const value = new MyObject(arg)
status = napi_new_instance(env, constructor, argc, argv, &value);Restituisce napi_ok se l'API ha avuto successo.
Object wrap
Node-API offre un modo per "avvolgere" le classi e le istanze C++ in modo che il costruttore e i metodi della classe possano essere chiamati da JavaScript.
Per gli oggetti avvolti, potrebbe essere difficile distinguere tra una funzione chiamata sul prototipo di una classe e una funzione chiamata su un'istanza di una classe. Un modello comune utilizzato per affrontare questo problema è quello di salvare un riferimento persistente al costruttore della classe per successivi controlli instanceof.
napi_value MyClass_constructor = NULL;
status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);
assert(napi_ok == status);
bool is_instance = false;
status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);
assert(napi_ok == status);
if (is_instance) {
// napi_unwrap() ...
} else {
// altrimenti...
}Il riferimento deve essere liberato una volta che non è più necessario.
Ci sono occasioni in cui napi_instanceof() è insufficiente per garantire che un oggetto JavaScript sia un wrapper per un certo tipo nativo. Questo è il caso specialmente quando gli oggetti JavaScript avvolti vengono ripassati all'addon tramite metodi statici piuttosto che come valore this dei metodi del prototipo. In tali casi, c'è la possibilità che possano essere srotolati in modo errato.
const myAddon = require('./build/Release/my_addon.node')
// `openDatabase()` restituisce un oggetto JavaScript che avvolge un handle di database nativo.
const dbHandle = myAddon.openDatabase()
// `query()` restituisce un oggetto JavaScript che avvolge un handle di query nativo.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')
// C'è un errore accidentale nella riga seguente. Il primo parametro di
// `myAddon.queryHasRecords()` dovrebbe essere l'handle del database (`dbHandle`), non
// l'handle della query (`query`), quindi la condizione corretta per il ciclo while
// dovrebbe essere
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
// recupera i record
}Nell'esempio sopra, myAddon.queryHasRecords() è un metodo che accetta due argomenti. Il primo è un handle del database e il secondo è un handle di query. Internamente, srotola il primo argomento e converte il puntatore risultante in un handle di database nativo. Quindi srotola il secondo argomento e converte il puntatore risultante in un handle di query. Se gli argomenti vengono passati nell'ordine sbagliato, le conversioni funzioneranno, tuttavia, c'è una buona possibilità che l'operazione di database sottostante fallisca o causi persino un accesso alla memoria non valido.
Per garantire che il puntatore recuperato dal primo argomento sia effettivamente un puntatore a un handle di database e, allo stesso modo, che il puntatore recuperato dal secondo argomento sia effettivamente un puntatore a un handle di query, l'implementazione di queryHasRecords() deve eseguire una convalida del tipo. Conservare il costruttore della classe JavaScript da cui è stato istanziato l'handle del database e il costruttore da cui è stato istanziato l'handle della query in napi_ref può essere d'aiuto, perché napi_instanceof() può quindi essere utilizzato per garantire che le istanze passate in queryHashRecords() siano effettivamente del tipo corretto.
Sfortunatamente, napi_instanceof() non protegge dalla manipolazione del prototipo. Ad esempio, il prototipo dell'istanza dell'handle del database può essere impostato sul prototipo del costruttore per le istanze dell'handle della query. In questo caso, l'istanza dell'handle del database può apparire come un'istanza dell'handle della query e supererà il test napi_instanceof() per un'istanza dell'handle della query, pur contenendo un puntatore a un handle del database.
A tal fine, Node-API fornisce funzionalità di etichettatura del tipo.
Un'etichetta di tipo è un intero a 128 bit univoco per l'addon. Node-API fornisce la struttura napi_type_tag per memorizzare un'etichetta di tipo. Quando tale valore viene passato insieme a un oggetto JavaScript o esterno memorizzato in un napi_value a napi_type_tag_object(), l'oggetto JavaScript verrà "contrassegnato" con l'etichetta di tipo. Il "contrassegno" è invisibile sul lato JavaScript. Quando un oggetto JavaScript arriva in un binding nativo, napi_check_object_type_tag() può essere utilizzato insieme all'etichetta di tipo originale per determinare se l'oggetto JavaScript era stato precedentemente "contrassegnato" con l'etichetta di tipo. Ciò crea una funzionalità di controllo del tipo di una fedeltà superiore a quella che napi_instanceof() può fornire, perché tale etichettatura di tipo sopravvive alla manipolazione del prototipo e al caricamento/ricaricamento dell'addon.
Continuando l'esempio sopra, la seguente implementazione scheletrica dell'addon illustra l'uso di napi_type_tag_object() e napi_check_object_type_tag().
// Questo valore è l'etichetta di tipo per un handle di database. Il comando
//
// uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// può essere utilizzato per ottenere i due valori con cui inizializzare la struttura.
static const napi_type_tag DatabaseHandleTypeTag = {
0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};
// Questo valore è l'etichetta di tipo per un handle di query.
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;
// Esegui l'azione sottostante che si traduce in un handle di database.
DatabaseHandle* dbHandle = open_database();
// Crea un nuovo oggetto JS vuoto.
status = napi_create_object(env, &result);
if (status != napi_ok) return NULL;
// Etichetta l'oggetto per indicare che contiene un puntatore a un `DatabaseHandle`.
status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
if (status != napi_ok) return NULL;
// Memorizza il puntatore alla struttura `DatabaseHandle` all'interno dell'oggetto JS.
status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
if (status != napi_ok) return NULL;
return result;
}
// Più tardi, quando riceviamo un oggetto JavaScript che pretende di essere un handle di database
// possiamo usare `napi_check_object_type_tag()` per garantire che sia effettivamente tale un
// handle.
static napi_value
query(napi_env env, napi_callback_info info) {
napi_status status;
size_t argc = 2;
napi_value argv[2];
bool is_db_handle;
status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
if (status != napi_ok) return NULL;
// Verifica che l'oggetto passato come primo parametro abbia l'etichetta
// applicata precedentemente.
status = napi_check_object_type_tag(env,
argv[0],
&DatabaseHandleTypeTag,
&is_db_handle);
if (status != napi_ok) return NULL;
// Lancia un `TypeError` se non lo è.
if (!is_db_handle) {
// Lancia un TypeError.
return NULL;
}
}napi_define_class
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_define_class(napi_env env,
const char* utf8name,
size_t length,
napi_callback constructor,
void* data,
size_t property_count,
const napi_property_descriptor* properties,
napi_value* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] utf8name: Nome della funzione costruttore JavaScript. Per chiarezza, si consiglia di utilizzare il nome della classe C++ quando si esegue il wrapping di una classe C++.[in] length: La lunghezza diutf8namein byte, oNAPI_AUTO_LENGTHse è terminato da null.[in] constructor: Funzione di callback che gestisce la costruzione delle istanze della classe. Quando si esegue il wrapping di una classe C++, questo metodo deve essere un membro statico con la firmanapi_callback. Un costruttore di classe C++ non può essere utilizzato.napi_callbackfornisce maggiori dettagli.[in] data: Dati opzionali da passare alla callback del costruttore come proprietàdatadell'info della callback.[in] property_count: Numero di elementi nell'argomento arrayproperties.[in] properties: Array di descrittori di proprietà che descrivono le proprietà di dati statiche e di istanza, gli accessori e i metodi sulla classe. Vederenapi_property_descriptor.[out] result: Unnapi_valueche rappresenta la funzione costruttore per la classe.
Restituisce napi_ok se l'API ha avuto successo.
Definisce una classe JavaScript, inclusi:
- Una funzione costruttore JavaScript che ha il nome della classe. Quando si esegue il wrapping di una corrispondente classe C++, la callback passata tramite
constructorpuò essere utilizzata per istanziare una nuova istanza di classe C++, che può quindi essere inserita all'interno dell'istanza dell'oggetto JavaScript in fase di costruzione utilizzandonapi_wrap. - Proprietà sulla funzione costruttore la cui implementazione può richiamare le corrispondenti proprietà di dati statiche, gli accessori e i metodi della classe C++ (definiti da descrittori di proprietà con l'attributo
napi_static). - Proprietà sull'oggetto
prototypedella funzione costruttore. Quando si esegue il wrapping di una classe C++, le proprietà di dati non statiche, gli accessori e i metodi della classe C++ possono essere richiamati dalle funzioni statiche fornite nei descrittori di proprietà senza l'attributonapi_staticdopo aver recuperato l'istanza della classe C++ inserita all'interno dell'istanza dell'oggetto JavaScript utilizzandonapi_unwrap.
Quando si esegue il wrapping di una classe C++, la callback del costruttore C++ passata tramite constructor dovrebbe essere un metodo statico sulla classe che richiama l'effettivo costruttore della classe, quindi esegue il wrapping della nuova istanza C++ in un oggetto JavaScript e restituisce l'oggetto wrapper. Vedere napi_wrap per i dettagli.
La funzione costruttore JavaScript restituita da napi_define_class viene spesso salvata e utilizzata in seguito per costruire nuove istanze della classe dal codice nativo e/o per verificare se i valori forniti sono istanze della classe. In tal caso, per evitare che il valore della funzione venga raccolto dal garbage collector, è possibile creare un forte riferimento persistente ad esso utilizzando napi_create_reference, assicurandosi che il conteggio dei riferimenti sia mantenuto >= 1.
Qualsiasi dato non NULL passato a questa API tramite il parametro data o tramite il campo data degli elementi dell'array napi_property_descriptor può essere associato al costruttore JavaScript risultante (che viene restituito nel parametro result) e liberato ogni volta che la classe viene raccolta dal garbage collector passando sia la funzione JavaScript sia i dati a napi_add_finalizer.
napi_wrap
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
napi_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);[in] env: L'ambiente in cui viene invocata l'API.[in] js_object: L'oggetto JavaScript che sarà il wrapper per l'oggetto nativo.[in] native_object: L'istanza nativa che sarà racchiusa nell'oggetto JavaScript.[in] finalize_cb: Callback nativa opzionale che può essere utilizzata per liberare l'istanza nativa quando l'oggetto JavaScript è stato sottoposto a garbage collection.napi_finalizefornisce maggiori dettagli.[in] finalize_hint: Suggerimento contestuale opzionale che viene passato alla callback finalize.[out] result: Riferimento opzionale all'oggetto wrappato.
Restituisce napi_ok se l'API ha avuto successo.
Avvolge un'istanza nativa in un oggetto JavaScript. L'istanza nativa può essere recuperata in seguito utilizzando napi_unwrap().
Quando il codice JavaScript richiama un costruttore per una classe definita utilizzando napi_define_class(), viene richiamata la napi_callback per il costruttore. Dopo aver costruito un'istanza della classe nativa, la callback deve quindi chiamare napi_wrap() per avvolgere l'istanza appena costruita nell'oggetto JavaScript già creato che è l'argomento this della callback del costruttore. (Quell'oggetto this è stato creato dal prototype della funzione costruttore, quindi ha già le definizioni di tutte le proprietà e i metodi dell'istanza.)
In genere, quando si avvolge un'istanza di classe, è necessario fornire una callback finalize che elimini semplicemente l'istanza nativa che viene ricevuta come argomento data per la callback finalize.
Il riferimento opzionale restituito è inizialmente un riferimento debole, il che significa che ha un conteggio di riferimento di 0. In genere questo conteggio di riferimento verrebbe incrementato temporaneamente durante le operazioni asincrone che richiedono che l'istanza rimanga valida.
Attenzione: Il riferimento opzionale restituito (se ottenuto) deve essere eliminato tramite napi_delete_reference SOLO in risposta all'invocazione della callback finalize. Se viene eliminato prima di allora, la callback finalize potrebbe non essere mai invocata. Pertanto, quando si ottiene un riferimento è necessaria anche una callback finalize per consentire la corretta eliminazione del riferimento.
Le callback Finalizer possono essere differite, lasciando una finestra in cui l'oggetto è stato sottoposto a garbage collection (e il riferimento debole non è valido) ma il finalizer non è stato ancora chiamato. Quando si utilizza napi_get_reference_value() su riferimenti deboli restituiti da napi_wrap(), è comunque necessario gestire un risultato vuoto.
Chiamare napi_wrap() una seconda volta su un oggetto restituirà un errore. Per associare un'altra istanza nativa all'oggetto, utilizzare prima napi_remove_wrap().
napi_unwrap
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_unwrap(napi_env env,
napi_value js_object,
void** result);[in] env: L'ambiente in cui viene invocata l'API.[in] js_object: L'oggetto associato all'istanza nativa.[out] result: Puntatore all'istanza nativa wrappata.
Restituisce napi_ok se l'API ha avuto successo.
Recupera un'istanza nativa precedentemente wrappata in un oggetto JavaScript usando napi_wrap().
Quando il codice JavaScript invoca un metodo o un'accesso alla proprietà sulla classe, viene invocato il corrispondente napi_callback. Se il callback è per un metodo di istanza o un accesso, allora l'argomento this del callback è l'oggetto wrapper; l'istanza C++ wrappata che è il target della chiamata può essere ottenuta chiamando napi_unwrap() sull'oggetto wrapper.
napi_remove_wrap
Aggiunto in: v8.5.0
Versione N-API: 1
napi_status napi_remove_wrap(napi_env env,
napi_value js_object,
void** result);[in] env: L'ambiente in cui viene invocata l'API.[in] js_object: L'oggetto associato all'istanza nativa.[out] result: Puntatore all'istanza nativa wrappata.
Restituisce napi_ok se l'API ha avuto successo.
Recupera un'istanza nativa che era precedentemente wrappata nell'oggetto JavaScript js_object usando napi_wrap() e rimuove il wrapping. Se un callback di finalizzazione era associato al wrapping, non verrà più chiamato quando l'oggetto JavaScript diventa spazzatura.
napi_type_tag_object
Aggiunto in: v14.8.0, v12.19.0
Versione N-API: 8
napi_status napi_type_tag_object(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag);[in] env: L'ambiente in cui viene invocata l'API.[in] js_object: L'oggetto JavaScript o esterno da contrassegnare.[in] type_tag: Il tag con cui l'oggetto deve essere contrassegnato.
Restituisce napi_ok se l'API ha avuto successo.
Associa il valore del puntatore type_tag con l'oggetto JavaScript o esterno. napi_check_object_type_tag() può quindi essere usato per confrontare il tag che è stato allegato all'oggetto con uno di proprietà dell'addon per assicurarsi che l'oggetto abbia il tipo corretto.
Se l'oggetto ha già un tag di tipo associato, questa API restituirà napi_invalid_arg.
napi_check_object_type_tag
Aggiunto in: v14.8.0, v12.19.0
Versione N-API: 8
napi_status napi_check_object_type_tag(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag,
bool* result);[in] env: L'ambiente in cui viene invocata l'API.[in] js_object: L'oggetto JavaScript o esterno di cui esaminare il tag del tipo.[in] type_tag: Il tag con cui confrontare qualsiasi tag trovato sull'oggetto.[out] result: Indica se il tag del tipo fornito corrisponde al tag del tipo sull'oggetto. Viene restituito anchefalsese non è stato trovato alcun tag del tipo sull'oggetto.
Restituisce napi_ok se l'API ha avuto successo.
Confronta il puntatore fornito come type_tag con qualsiasi puntatore che può essere trovato su js_object. Se non viene trovato alcun tag su js_object o se viene trovato un tag ma non corrisponde a type_tag, allora result viene impostato su false. Se viene trovato un tag e corrisponde a type_tag, allora result viene impostato su true.
napi_add_finalizer
Aggiunto in: v8.0.0
Versione N-API: 5
napi_status napi_add_finalizer(napi_env env,
napi_value js_object,
void* finalize_data,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);[in] env: L'ambiente in cui viene invocata l'API.[in] js_object: L'oggetto JavaScript a cui verranno allegati i dati nativi.[in] finalize_data: Dati opzionali da passare afinalize_cb.[in] finalize_cb: Callback nativo che verrà utilizzato per liberare i dati nativi quando l'oggetto JavaScript è stato sottoposto a garbage collection.napi_finalizefornisce maggiori dettagli.[in] finalize_hint: Suggerimento contestuale opzionale che viene passato alla callback di finalizzazione.[out] result: Riferimento opzionale all'oggetto JavaScript.
Restituisce napi_ok se l'API ha avuto successo.
Aggiunge una callback napi_finalize che verrà chiamata quando l'oggetto JavaScript in js_object è stato sottoposto a garbage collection.
Questa API può essere chiamata più volte su un singolo oggetto JavaScript.
Attenzione: Il riferimento opzionale restituito (se ottenuto) deve essere eliminato tramite napi_delete_reference SOLO in risposta all'invocazione della callback di finalizzazione. Se viene eliminato prima, la callback di finalizzazione potrebbe non essere mai invocata. Pertanto, quando si ottiene un riferimento, è necessaria anche una callback di finalizzazione per consentire lo smaltimento corretto del riferimento.
node_api_post_finalizer
Aggiunto in: v21.0.0, v20.10.0, v18.19.0
[Stabile: 1 - Sperimentale]
Stabile: 1 Stabilità: 1 - Sperimentale
napi_status node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint);[in] env: L'ambiente in cui viene invocata l'API.[in] finalize_cb: Callback nativa che verrà utilizzata per liberare i dati nativi quando l'oggetto JavaScript è stato raccolto dal garbage collector.napi_finalizefornisce maggiori dettagli.[in] finalize_data: Dati opzionali da passare afinalize_cb.[in] finalize_hint: Suggerimento contestuale opzionale che viene passato alla callback di finalizzazione.
Restituisce napi_ok se l'API ha avuto successo.
Pianifica una callback napi_finalize da chiamare in modo asincrono nell'event loop.
Normalmente, i finalizzatori vengono chiamati mentre il GC (garbage collector) raccoglie gli oggetti. A quel punto, chiamare qualsiasi Node-API che potrebbe causare modifiche nello stato del GC verrà disabilitato e Node.js andrà in crash.
node_api_post_finalizer aiuta a risolvere questa limitazione consentendo all'addon di posticipare le chiamate a tali Node-API a un momento al di fuori della finalizzazione del GC.
Operazioni asincrone semplici
I moduli addon hanno spesso bisogno di sfruttare gli helper asincroni di libuv come parte della loro implementazione. Ciò consente loro di pianificare il lavoro da eseguire in modo asincrono in modo che i loro metodi possano restituire prima che il lavoro sia completato. Ciò consente loro di evitare di bloccare l'esecuzione complessiva dell'applicazione Node.js.
Node-API fornisce un'interfaccia ABI-stabile per queste funzioni di supporto che copre i casi d'uso asincroni più comuni.
Node-API definisce la struttura napi_async_work che viene utilizzata per gestire i worker asincroni. Le istanze vengono create/eliminate con napi_create_async_work e napi_delete_async_work.
Le callback execute e complete sono funzioni che verranno invocate quando l'executor è pronto per l'esecuzione e quando completa rispettivamente il suo compito.
La funzione execute dovrebbe evitare di effettuare chiamate Node-API che potrebbero comportare l'esecuzione di JavaScript o l'interazione con oggetti JavaScript. Molto spesso, qualsiasi codice che deve effettuare chiamate Node-API dovrebbe essere fatto invece nella callback complete. Evitare di utilizzare il parametro napi_env nella callback di esecuzione poiché probabilmente eseguirà JavaScript.
Queste funzioni implementano le seguenti interfacce:
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);Quando questi metodi vengono invocati, il parametro data passato sarà il dato void* fornito dall'addon che è stato passato alla chiamata napi_create_async_work.
Una volta creato, il worker asincrono può essere messo in coda per l'esecuzione utilizzando la funzione napi_queue_async_work:
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);napi_cancel_async_work può essere utilizzato se il lavoro deve essere annullato prima che il lavoro abbia iniziato l'esecuzione.
Dopo aver chiamato napi_cancel_async_work, la callback complete verrà invocata con un valore di stato di napi_cancelled. Il lavoro non deve essere eliminato prima dell'invocazione della callback complete, anche quando è stato annullato.
napi_create_async_work
[Cronologia]
| Versione | Modifiche |
|---|---|
| v8.6.0 | Aggiunti i parametri async_resource e async_resource_name. |
| v8.0.0 | Aggiunto in: v8.0.0 |
Versione N-API: 1
napi_status napi_create_async_work(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_execute_callback execute,
napi_async_complete_callback complete,
void* data,
napi_async_work* result);[in] env: L'ambiente in cui viene invocata l'API.[in] async_resource: Un oggetto opzionale associato al lavoro asincrono che verrà passato ai possibili hookinitdiasync_hooksinithook.[in] async_resource_name: Identificatore per il tipo di risorsa che viene fornito per le informazioni diagnostiche esposte dall'APIasync_hooks.[in] execute: La funzione nativa che dovrebbe essere chiamata per eseguire la logica in modo asincrono. La funzione fornita viene chiamata da un thread del pool di worker e può essere eseguita in parallelo con il thread principale del ciclo di eventi.[in] complete: La funzione nativa che verrà chiamata quando la logica asincrona è completata o annullata. La funzione fornita viene chiamata dal thread principale del ciclo di eventi.napi_async_complete_callbackfornisce maggiori dettagli.[in] data: Contesto di dati fornito dall'utente. Questo verrà ripassato alle funzioni execute e complete.[out] result:napi_async_work*che è l'handle per il lavoro asincrono appena creato.
Restituisce napi_ok se l'API ha avuto successo.
Questa API alloca un oggetto di lavoro che viene utilizzato per eseguire la logica in modo asincrono. Dovrebbe essere liberato usando napi_delete_async_work una volta che il lavoro non è più necessario.
async_resource_name dovrebbe essere una stringa con terminazione null, codificata in UTF-8.
L'identificatore async_resource_name è fornito dall'utente e dovrebbe essere rappresentativo del tipo di lavoro asincrono in esecuzione. Si consiglia anche di applicare un namespacing all'identificatore, ad esempio includendo il nome del modulo. Consulta la documentazione di async_hooks per maggiori informazioni.
napi_delete_async_work
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_delete_async_work(napi_env env,
napi_async_work work);[in] env: L'ambiente in cui viene invocata l'API.[in] work: L'handle restituito dalla chiamata anapi_create_async_work.
Restituisce napi_ok se l'API ha avuto successo.
Questa API libera un oggetto di lavoro precedentemente allocato.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
napi_queue_async_work
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);[in] env: L'ambiente in cui viene invocata l'API.[in] work: L'handle restituito dalla chiamata anapi_create_async_work.
Restituisce napi_ok se l'API ha avuto successo.
Questa API richiede che il lavoro precedentemente allocato venga programmato per l'esecuzione. Una volta che restituisce un valore positivo, questa API non deve essere chiamata nuovamente con lo stesso elemento napi_async_work o il risultato sarà indefinito.
napi_cancel_async_work
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_cancel_async_work(node_api_basic_env env,
napi_async_work work);[in] env: L'ambiente in cui viene invocata l'API.[in] work: L'handle restituito dalla chiamata anapi_create_async_work.
Restituisce napi_ok se l'API ha avuto successo.
Questa API annulla il lavoro in coda se non è ancora stato avviato. Se è già iniziato l'esecuzione, non può essere annullato e verrà restituito napi_generic_failure. In caso di successo, il callback complete verrà invocato con un valore di stato di napi_cancelled. Il lavoro non deve essere eliminato prima dell'invocazione del callback complete, anche se è stato annullato con successo.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
Operazioni asincrone personalizzate
Le semplici API di lavoro asincrono sopra descritte potrebbero non essere appropriate per ogni scenario. Quando si utilizza qualsiasi altro meccanismo asincrono, sono necessarie le seguenti API per garantire che un'operazione asincrona venga tracciata correttamente dal runtime.
napi_async_init
Aggiunto in: v8.6.0
Versione N-API: 1
napi_status napi_async_init(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_context* result)[in] env: L'ambiente in cui viene invocata l'API.[in] async_resource: Oggetto associato al lavoro asincrono che verrà passato ai possibili hookinitdiasync_hooks[/api/async_hooks#initasyncid-type-triggerasyncid-resource] e a cui si può accedere tramiteasync_hooks.executionAsyncResource().[in] async_resource_name: Identificatore per il tipo di risorsa fornita per le informazioni diagnostiche esposte dall'APIasync_hooks.[out] result: Il contesto asincrono inizializzato.
Restituisce napi_ok se l'API ha avuto successo.
L'oggetto async_resource deve essere mantenuto attivo fino a napi_async_destroy per fare in modo che l'API correlata a async_hooks agisca correttamente. Al fine di mantenere la compatibilità ABI con le versioni precedenti, napi_async_context non mantiene un riferimento forte agli oggetti async_resource per evitare di introdurre perdite di memoria. Tuttavia, se async_resource viene raccolto dal garbage collector del motore JavaScript prima che napi_async_context venga distrutto da napi_async_destroy, la chiamata di API correlate a napi_async_context come napi_open_callback_scope e napi_make_callback può causare problemi come la perdita del contesto asincrono quando si utilizza l'API AsyncLocalStorage.
Al fine di mantenere la compatibilità ABI con le versioni precedenti, passare NULL per async_resource non comporta un errore. Tuttavia, questo non è consigliato in quanto ciò comporterà un comportamento indesiderabile con gli hook init di async_hooks [/api/async_hooks#initasyncid-type-triggerasyncid-resource] e async_hooks.executionAsyncResource() poiché la risorsa è ora richiesta dall'implementazione sottostante di async_hooks per fornire il collegamento tra i callback asincroni.
napi_async_destroy
Aggiunto in: v8.6.0
Versione N-API: 1
napi_status napi_async_destroy(napi_env env,
napi_async_context async_context);[in] env: L'ambiente in cui viene invocata l'API.[in] async_context: Il contesto asincrono da eliminare.
Restituisce napi_ok se l'API ha avuto successo.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
napi_make_callback
[Cronologia]
| Versione | Modifiche |
|---|---|
| v8.6.0 | Aggiunto il parametro async_context. |
| v8.0.0 | Aggiunto in: v8.0.0 |
Versione N-API: 1
NAPI_EXTERN napi_status napi_make_callback(napi_env env,
napi_async_context async_context,
napi_value recv,
napi_value func,
size_t argc,
const napi_value* argv,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] async_context: Contesto per l'operazione asincrona che sta invocando la callback. Questo dovrebbe normalmente essere un valore precedentemente ottenuto danapi_async_init. Per mantenere la compatibilità ABI con le versioni precedenti, passareNULLperasync_contextnon comporta un errore. Tuttavia, ciò comporta un funzionamento non corretto degli hook asincroni. I possibili problemi includono la perdita del contesto asincrono quando si utilizza l'APIAsyncLocalStorage.[in] recv: Il valorethispassato alla funzione chiamata.[in] func:napi_valueche rappresenta la funzione JavaScript da invocare.[in] argc: Il conteggio degli elementi nell'arrayargv.[in] argv: Array di valori JavaScript comenapi_valueche rappresentano gli argomenti della funzione. Seargcè zero, questo parametro può essere omesso passandoNULL.[out] result:napi_valueche rappresenta l'oggetto JavaScript restituito.
Restituisce napi_ok se l'API ha avuto successo.
Questo metodo consente di chiamare un oggetto funzione JavaScript da un add-on nativo. Questa API è simile a napi_call_function. Tuttavia, viene utilizzata per richiamare dal codice nativo nel JavaScript dopo essere tornati da un'operazione asincrona (quando non ci sono altri script nello stack). È un wrapper abbastanza semplice intorno a node::MakeCallback.
Si noti che non è necessario utilizzare napi_make_callback dall'interno di una napi_async_complete_callback; in tale situazione, il contesto asincrono della callback è già stato impostato, quindi una chiamata diretta a napi_call_function è sufficiente e appropriata. L'uso della funzione napi_make_callback può essere richiesto quando si implementa un comportamento asincrono personalizzato che non utilizza napi_create_async_work.
Eventuali process.nextTick o Promise pianificate nella coda di microtask da JavaScript durante la callback vengono eseguite prima di tornare a C/C++.
napi_open_callback_scope
Aggiunto in: v9.6.0
Versione N-API: 3
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
napi_value resource_object,
napi_async_context context,
napi_callback_scope* result)[in] env: L'ambiente in cui viene richiamata l'API.[in] resource_object: Un oggetto associato all'attività asincrona che verrà passato ai possibili hookasync_hooksinit. Questo parametro è stato deprecato e viene ignorato in fase di runtime. Utilizzare invece il parametroasync_resourceinnapi_async_init.[in] context: Contesto per l'operazione asincrona che sta richiamando la callback. Questo dovrebbe essere un valore precedentemente ottenuto danapi_async_init.[out] result: Il nuovo scope creato.
Ci sono casi (ad esempio, la risoluzione di promises) in cui è necessario avere l'equivalente dello scope associato a una callback quando si effettuano determinate chiamate Node-API. Se non c'è altro script nello stack, le funzioni napi_open_callback_scope e napi_close_callback_scope possono essere utilizzate per aprire/chiudere lo scope richiesto.
napi_close_callback_scope
Aggiunto in: v9.6.0
Versione N-API: 3
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
napi_callback_scope scope)[in] env: L'ambiente in cui viene richiamata l'API.[in] scope: Lo scope da chiudere.
Questa API può essere chiamata anche se è presente un'eccezione JavaScript in sospeso.
Gestione delle versioni
napi_get_node_version
Aggiunto in: v8.4.0
Versione N-API: 1
typedef struct {
uint32_t major;
uint32_t minor;
uint32_t patch;
const char* release;
} napi_node_version;
napi_status napi_get_node_version(node_api_basic_env env,
const napi_node_version** version);[in] env: L'ambiente in cui viene richiamata l'API.[out] version: Un puntatore alle informazioni sulla versione per Node.js stesso.
Restituisce napi_ok se l'API ha avuto successo.
Questa funzione riempie la struct version con la versione major, minor e patch di Node.js in esecuzione e il campo release con il valore di process.release.name.
Il buffer restituito è allocato staticamente e non necessita di essere liberato.
napi_get_version
Aggiunto in: v8.0.0
Versione N-API: 1
napi_status napi_get_version(node_api_basic_env env,
uint32_t* result);[in] env: L'ambiente in cui viene richiamata l'API.[out] result: La versione più alta di Node-API supportata.
Restituisce napi_ok se l'API ha avuto successo.
Questa API restituisce la versione di Node-API più alta supportata dal runtime di Node.js. Node-API è progettato per essere additivo, in modo che le versioni più recenti di Node.js possano supportare funzioni API aggiuntive. Per consentire a un addon di utilizzare una funzione più recente quando viene eseguito con versioni di Node.js che la supportano, fornendo al contempo un comportamento di fallback quando viene eseguito con versioni di Node.js che non la supportano:
- Chiama
napi_get_version()per determinare se l'API è disponibile. - Se disponibile, carica dinamicamente un puntatore alla funzione utilizzando
uv_dlsym(). - Utilizza il puntatore caricato dinamicamente per richiamare la funzione.
- Se la funzione non è disponibile, fornisci un'implementazione alternativa che non la utilizzi.
Gestione della memoria
napi_adjust_external_memory
Aggiunto in: v8.5.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
int64_t change_in_bytes,
int64_t* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] change_in_bytes: La modifica nella memoria allocata esternamente che viene mantenuta in vita dagli oggetti JavaScript.[out] result: Il valore modificato
Restituisce napi_ok se l'API ha avuto successo.
Questa funzione fornisce a V8 un'indicazione della quantità di memoria allocata esternamente che viene mantenuta in vita dagli oggetti JavaScript (ovvero, un oggetto JavaScript che punta alla propria memoria allocata da un addon nativo). La registrazione della memoria allocata esternamente attiverà le garbage collection globali più spesso di quanto farebbe altrimenti.
Promise
Node-API fornisce strumenti per la creazione di oggetti Promise come descritto nella Sezione 25.4 della specifica ECMA. Implementa le promise come una coppia di oggetti. Quando una promise viene creata da napi_create_promise(), viene creato e restituito insieme alla Promise un oggetto "deferred". L'oggetto deferred è vincolato alla Promise creata ed è l'unico modo per risolvere o rifiutare la Promise utilizzando napi_resolve_deferred() o napi_reject_deferred(). L'oggetto deferred creato da napi_create_promise() viene liberato da napi_resolve_deferred() o napi_reject_deferred(). L'oggetto Promise può essere restituito a JavaScript dove può essere utilizzato nel solito modo.
Ad esempio, per creare una promise e passarla a un worker asincrono:
napi_deferred deferred;
napi_value promise;
napi_status status;
// Crea la promise.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;
// Passa il deferred a una funzione che esegue un'azione asincrona.
do_something_asynchronous(deferred);
// Restituisce la promise a JS
return promise;La funzione precedente do_something_asynchronous() eseguirà la sua azione asincrona e quindi risolverà o rifiuterà il deferred, concludendo così la promise e liberando il deferred:
napi_deferred deferred;
napi_value undefined;
napi_status status;
// Crea un valore con cui concludere il deferred.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;
// Risolve o rifiuta la promise associata al deferred a seconda
// se l'azione asincrona ha avuto successo.
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;
// A questo punto il deferred è stato liberato, quindi dovremmo assegnare NULL ad esso.
deferred = NULL;napi_create_promise
Aggiunto in: v8.5.0
Versione N-API: 1
napi_status napi_create_promise(napi_env env,
napi_deferred* deferred,
napi_value* promise);[in] env: L'ambiente in cui viene richiamata l'API.[out] deferred: Un oggetto deferred appena creato che può essere passato successivamente anapi_resolve_deferred()onapi_reject_deferred()per risolvere o rifiutare la promise associata.[out] promise: La promise JavaScript associata all'oggetto deferred.
Restituisce napi_ok se l'API ha avuto successo.
Questa API crea un oggetto deferred e una promise JavaScript.
napi_resolve_deferred
Aggiunto in: v8.5.0
Versione N-API: 1
napi_status napi_resolve_deferred(napi_env env,
napi_deferred deferred,
napi_value resolution);[in] env: L'ambiente in cui viene richiamata l'API.[in] deferred: L'oggetto deferred la cui promise associata deve essere risolta.[in] resolution: Il valore con cui risolvere la promise.
Questa API risolve una promise JavaScript tramite l'oggetto deferred a cui è associata. Pertanto, può essere utilizzata solo per risolvere le promise JavaScript per le quali è disponibile l'oggetto deferred corrispondente. Ciò significa che la promise deve essere stata creata usando napi_create_promise() e l'oggetto deferred restituito da tale chiamata deve essere stato conservato per poter essere passato a questa API.
L'oggetto deferred viene liberato al completamento con successo.
napi_reject_deferred
Aggiunto in: v8.5.0
Versione N-API: 1
napi_status napi_reject_deferred(napi_env env,
napi_deferred deferred,
napi_value rejection);[in] env: L'ambiente in cui viene richiamata l'API.[in] deferred: L'oggetto deferred la cui promise associata deve essere rifiutata.[in] rejection: Il valore con cui rifiutare la promise.
Questa API rifiuta una promise JavaScript tramite l'oggetto deferred a cui è associata. Pertanto, può essere utilizzata solo per rifiutare le promise JavaScript per le quali è disponibile l'oggetto deferred corrispondente. Ciò significa che la promise deve essere stata creata usando napi_create_promise() e l'oggetto deferred restituito da tale chiamata deve essere stato conservato per poter essere passato a questa API.
L'oggetto deferred viene liberato al completamento con successo.
napi_is_promise
Aggiunto in: v8.5.0
Versione N-API: 1
napi_status napi_is_promise(napi_env env,
napi_value value,
bool* is_promise);[in] env: L'ambiente in cui viene invocata l'API.[in] value: Il valore da esaminare.[out] is_promise: Flag che indica sepromiseè un oggetto promise nativo (ovvero, un oggetto promise creato dal motore sottostante).
Esecuzione di script
Node-API fornisce un'API per l'esecuzione di una stringa contenente JavaScript utilizzando il motore JavaScript sottostante.
napi_run_script
Aggiunto in: v8.5.0
Versione N-API: 1
NAPI_EXTERN napi_status napi_run_script(napi_env env,
napi_value script,
napi_value* result);[in] env: L'ambiente in cui viene invocata l'API.[in] script: Una stringa JavaScript contenente lo script da eseguire.[out] result: Il valore risultante dall'esecuzione dello script.
Questa funzione esegue una stringa di codice JavaScript e ne restituisce il risultato con le seguenti avvertenze:
- A differenza di
eval, questa funzione non consente allo script di accedere all'ambito lessicale corrente e, pertanto, non consente nemmeno di accedere all'ambito del modulo, il che significa che pseudo-globali comerequirenon saranno disponibili. - Lo script può accedere all'ambito globale. Le dichiarazioni di funzioni e
varnello script verranno aggiunte all'oggettoglobal. Le dichiarazioni di variabili effettuate usandoleteconstsaranno visibili globalmente, ma non verranno aggiunte all'oggettoglobal. - Il valore di
thisèglobalall'interno dello script.
Ciclo di eventi libuv
Node-API fornisce una funzione per ottenere il ciclo di eventi corrente associato a un napi_env specifico.
napi_get_uv_event_loop
Aggiunto in: v9.3.0, v8.10.0
Versione N-API: 2
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
struct uv_loop_s** loop);[in] env: L'ambiente in cui viene invocata l'API.[out] loop: L'istanza corrente del ciclo libuv.
Nota: Sebbene libuv sia stato relativamente stabile nel tempo, non fornisce una garanzia di stabilità ABI. L'uso di questa funzione dovrebbe essere evitato. Il suo utilizzo può comportare un addon che non funziona con le diverse versioni di Node.js. Le chiamate di funzioni asincrone thread-safe sono un'alternativa per molti casi d'uso.
Chiamate di funzione asincrone thread-safe
Le funzioni JavaScript normalmente possono essere chiamate solo dal thread principale di un addon nativo. Se un addon crea thread aggiuntivi, le funzioni Node-API che richiedono un napi_env, napi_value o napi_ref non devono essere chiamate da tali thread.
Quando un addon ha thread aggiuntivi e le funzioni JavaScript devono essere invocate in base all'elaborazione completata da tali thread, questi thread devono comunicare con il thread principale dell'addon in modo che il thread principale possa invocare la funzione JavaScript per loro conto. Le API delle funzioni thread-safe forniscono un modo semplice per farlo.
Queste API forniscono il tipo napi_threadsafe_function così come le API per creare, distruggere e chiamare oggetti di questo tipo. napi_create_threadsafe_function() crea un riferimento persistente a un napi_value che contiene una funzione JavaScript che può essere chiamata da più thread. Le chiamate avvengono in modo asincrono. Ciò significa che i valori con cui deve essere chiamata la callback JavaScript verranno inseriti in una coda e, per ogni valore nella coda, verrà effettuata una chiamata alla funzione JavaScript.
Al momento della creazione di un napi_threadsafe_function è possibile fornire una callback napi_finalize. Questa callback verrà invocata sul thread principale quando la funzione thread-safe sta per essere distrutta. Riceve il contesto e i dati di finalizzazione forniti durante la costruzione e offre un'opportunità per la pulizia dopo i thread, ad es. chiamando uv_thread_join(). A parte il thread del ciclo principale, nessun thread deve utilizzare la funzione thread-safe dopo che la callback di finalizzazione è completata.
Il context fornito durante la chiamata a napi_create_threadsafe_function() può essere recuperato da qualsiasi thread con una chiamata a napi_get_threadsafe_function_context().
Chiamata di una funzione thread-safe
napi_call_threadsafe_function() può essere utilizzato per avviare una chiamata in JavaScript. napi_call_threadsafe_function() accetta un parametro che controlla se l'API si comporta in modo bloccante. Se impostato su napi_tsfn_nonblocking, l'API si comporta in modo non bloccante, restituendo napi_queue_full se la coda era piena, impedendo l'aggiunta corretta di dati alla coda. Se impostato su napi_tsfn_blocking, l'API si blocca finché non si rende disponibile spazio nella coda. napi_call_threadsafe_function() non si blocca mai se la funzione thread-safe è stata creata con una dimensione massima della coda pari a 0.
napi_call_threadsafe_function() non deve essere chiamata con napi_tsfn_blocking da un thread JavaScript perché, se la coda è piena, potrebbe causare un deadlock del thread JavaScript.
La chiamata effettiva in JavaScript è controllata dalla callback fornita tramite il parametro call_js_cb. call_js_cb viene invocata sul thread principale una volta per ogni valore inserito nella coda da una chiamata riuscita a napi_call_threadsafe_function(). Se tale callback non viene fornita, verrà utilizzata una callback predefinita e la chiamata JavaScript risultante non avrà argomenti. La callback call_js_cb riceve la funzione JavaScript da chiamare come napi_value nei suoi parametri, così come il puntatore di contesto void* utilizzato durante la creazione di napi_threadsafe_function e il successivo puntatore ai dati creato da uno dei thread secondari. La callback può quindi utilizzare un'API come napi_call_function() per chiamare in JavaScript.
La callback può anche essere invocata con env e call_js_cb entrambi impostati su NULL per indicare che le chiamate in JavaScript non sono più possibili, mentre rimangono elementi nella coda che potrebbero dover essere liberati. Ciò si verifica normalmente quando il processo Node.js si chiude mentre è ancora attiva una funzione thread-safe.
Non è necessario chiamare in JavaScript tramite napi_make_callback() perché Node-API esegue call_js_cb in un contesto appropriato per le callback.
Zero o più elementi in coda possono essere invocati in ogni tick del ciclo di eventi. Le applicazioni non devono dipendere da un comportamento specifico diverso dal progresso nell'invocazione delle callback e gli eventi verranno invocati man mano che il tempo avanza.
Conteggio dei riferimenti delle funzioni thread-safe
I thread possono essere aggiunti e rimossi da un oggetto napi_threadsafe_function durante la sua esistenza. Pertanto, oltre a specificare un numero iniziale di thread al momento della creazione, è possibile chiamare napi_acquire_threadsafe_function per indicare che un nuovo thread inizierà a utilizzare la funzione thread-safe. Allo stesso modo, è possibile chiamare napi_release_threadsafe_function per indicare che un thread esistente smetterà di utilizzare la funzione thread-safe.
Gli oggetti napi_threadsafe_function vengono distrutti quando ogni thread che utilizza l'oggetto ha chiamato napi_release_threadsafe_function() o ha ricevuto uno stato di ritorno napi_closing in risposta a una chiamata a napi_call_threadsafe_function. La coda viene svuotata prima che napi_threadsafe_function venga distrutta. napi_release_threadsafe_function() dovrebbe essere l'ultima chiamata API effettuata in combinazione con una determinata napi_threadsafe_function, poiché dopo il completamento della chiamata, non vi è alcuna garanzia che napi_threadsafe_function sia ancora allocata. Per lo stesso motivo, non utilizzare una funzione thread-safe dopo aver ricevuto un valore di ritorno di napi_closing in risposta a una chiamata a napi_call_threadsafe_function. I dati associati a napi_threadsafe_function possono essere liberati nel suo callback napi_finalize passato a napi_create_threadsafe_function(). Il parametro initial_thread_count di napi_create_threadsafe_function contrassegna il numero iniziale di acquisizioni delle funzioni thread-safe, invece di chiamare napi_acquire_threadsafe_function più volte al momento della creazione.
Una volta che il numero di thread che utilizzano una napi_threadsafe_function raggiunge lo zero, nessun altro thread può iniziare a utilizzarla chiamando napi_acquire_threadsafe_function(). Infatti, tutte le successive chiamate API ad essa associate, ad eccezione di napi_release_threadsafe_function(), restituiranno un valore di errore napi_closing.
La funzione thread-safe può essere "interrotta" fornendo un valore di napi_tsfn_abort a napi_release_threadsafe_function(). Ciò farà sì che tutte le successive API associate alla funzione thread-safe, ad eccezione di napi_release_threadsafe_function(), restituiscano napi_closing anche prima che il suo conteggio dei riferimenti raggiunga lo zero. In particolare, napi_call_threadsafe_function() restituirà napi_closing, informando così i thread che non è più possibile effettuare chiamate asincrone alla funzione thread-safe. Questo può essere utilizzato come criterio per terminare il thread. Dopo aver ricevuto un valore di ritorno di napi_closing da napi_call_threadsafe_function(), un thread non deve più utilizzare la funzione thread-safe poiché non è più garantito che sia allocata.
Decidere se mantenere il processo in esecuzione
Analogamente agli handle libuv, le funzioni thread-safe possono essere "referenziate" e "dereferenziate". Una funzione thread-safe "referenziata" farà sì che il ciclo di eventi sul thread su cui viene creata rimanga attivo fino a quando la funzione thread-safe non viene distrutta. Al contrario, una funzione thread-safe "dereferenziata" non impedirà l'uscita dal ciclo di eventi. Le API napi_ref_threadsafe_function e napi_unref_threadsafe_function esistono per questo scopo.
Né napi_unref_threadsafe_function contrassegna le funzioni thread-safe come distruttibili, né napi_ref_threadsafe_function ne impedisce la distruzione.
napi_create_threadsafe_function
[Cronologia]
| Versione | Modifiche |
|---|---|
| v12.6.0, v10.17.0 | Il parametro func è reso facoltativo con call_js_cb personalizzato. |
| v10.6.0 | Aggiunto in: v10.6.0 |
Versione N-API: 4
NAPI_EXTERN napi_status
napi_create_threadsafe_function(napi_env env,
napi_value func,
napi_value async_resource,
napi_value async_resource_name,
size_t max_queue_size,
size_t initial_thread_count,
void* thread_finalize_data,
napi_finalize thread_finalize_cb,
void* context,
napi_threadsafe_function_call_js call_js_cb,
napi_threadsafe_function* result);[in] env: L'ambiente in cui viene richiamata l'API.[in] func: Una funzione JavaScript opzionale da chiamare da un altro thread. Deve essere fornita se viene passatoNULLacall_js_cb.[in] async_resource: Un oggetto opzionale associato al lavoro asincrono che verrà passato ai possibili hookinitdiasync_hooks[/api/async_hooks#initasyncid-type-triggerasyncid-resource].[in] async_resource_name: Una stringa JavaScript per fornire un identificatore per il tipo di risorsa fornita per le informazioni diagnostiche esposte dall'APIasync_hooks.[in] max_queue_size: Dimensione massima della coda.0per nessun limite.[in] initial_thread_count: Il numero iniziale di acquisizioni, ovvero il numero iniziale di thread, incluso il thread principale, che utilizzeranno questa funzione.[in] thread_finalize_data: Dati opzionali da passare athread_finalize_cb.[in] thread_finalize_cb: Funzione opzionale da chiamare quando lanapi_threadsafe_functionviene distrutta.[in] context: Dati opzionali da collegare allanapi_threadsafe_functionrisultante.[in] call_js_cb: Callback opzionale che chiama la funzione JavaScript in risposta a una chiamata su un thread diverso. Questa callback verrà chiamata sul thread principale. Se non fornita, la funzione JavaScript verrà chiamata senza parametri e conundefinedcome valorethis.napi_threadsafe_function_call_jsfornisce maggiori dettagli.[out] result: La funzione JavaScript asincrona thread-safe.
Cronologia delle modifiche:
- Sperimentale (
NAPI_EXPERIMENTALè definito): Le eccezioni non intercettate generate incall_js_cbvengono gestite con l'evento'uncaughtException', invece di essere ignorate.
napi_get_threadsafe_function_context
Aggiunto in: v10.6.0
Versione N-API: 4
NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
void** result);[in] func: La funzione thread-safe per la quale recuperare il contesto.[out] result: La posizione in cui memorizzare il contesto.
Questa API può essere chiamata da qualsiasi thread che utilizzi func.
napi_call_threadsafe_function
[Cronologia]
| Versione | Modifiche |
|---|---|
| v14.5.0 | Il supporto per napi_would_deadlock è stato ripristinato. |
| v14.1.0 | Restituisce napi_would_deadlock quando viene chiamato con napi_tsfn_blocking dal thread principale o da un thread di lavoro e la coda è piena. |
| v10.6.0 | Aggiunto in: v10.6.0 |
Versione N-API: 4
NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
void* data,
napi_threadsafe_function_call_mode is_blocking);[in] func: La funzione JavaScript asincrona thread-safe da invocare.[in] data: Dati da inviare a JavaScript tramite il callbackcall_js_cbfornito durante la creazione della funzione JavaScript thread-safe.[in] is_blocking: Flag il cui valore può esserenapi_tsfn_blockingper indicare che la chiamata dovrebbe bloccarsi se la coda è piena onapi_tsfn_nonblockingper indicare che la chiamata dovrebbe tornare immediatamente con uno stato dinapi_queue_fullogni volta che la coda è piena.
Questa API non deve essere chiamata con napi_tsfn_blocking da un thread JavaScript, perché, se la coda è piena, potrebbe causare un deadlock del thread JavaScript.
Questa API restituirà napi_closing se napi_release_threadsafe_function() è stato chiamato con abort impostato su napi_tsfn_abort da qualsiasi thread. Il valore viene aggiunto alla coda solo se l'API restituisce napi_ok.
Questa API può essere chiamata da qualsiasi thread che utilizzi func.
napi_acquire_threadsafe_function
Aggiunto in: v10.6.0
Versione N-API: 4
NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);[in] func: La funzione JavaScript asincrona thread-safe da iniziare a utilizzare.
Un thread deve chiamare questa API prima di passare func a qualsiasi altra API di funzione thread-safe per indicare che utilizzerà func. Ciò impedisce che func venga distrutta quando tutti gli altri thread hanno smesso di utilizzarla.
Questa API può essere chiamata da qualsiasi thread che inizierà a utilizzare func.
napi_release_threadsafe_function
Aggiunto in: v10.6.0
Versione N-API: 4
NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
napi_threadsafe_function_release_mode mode);[in] func: La funzione JavaScript asincrona thread-safe il cui conteggio dei riferimenti deve essere decrementato.[in] mode: Flag il cui valore può esserenapi_tsfn_releaseper indicare che il thread corrente non effettuerà ulteriori chiamate alla funzione thread-safe, onapi_tsfn_abortper indicare che, oltre al thread corrente, nessun altro thread dovrebbe effettuare ulteriori chiamate alla funzione thread-safe. Se impostato sunapi_tsfn_abort, ulteriori chiamate anapi_call_threadsafe_function()restituirannonapi_closinge non verranno inseriti ulteriori valori nella coda.
Un thread dovrebbe chiamare questa API quando smette di utilizzare func. Passare func a qualsiasi API thread-safe dopo aver chiamato questa API ha risultati indefiniti, poiché func potrebbe essere stata distrutta.
Questa API può essere chiamata da qualsiasi thread che smetterà di utilizzare func.
napi_ref_threadsafe_function
Aggiunto in: v10.6.0
Versione N-API: 4
NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);[in] env: L'ambiente in cui viene invocata l'API.[in] func: La funzione thread-safe a cui fare riferimento.
Questa API viene utilizzata per indicare che il loop di eventi in esecuzione sul thread principale non dovrebbe uscire fino a quando func non è stata distrutta. Simile a uv_ref è anche idempotente.
Né napi_unref_threadsafe_function contrassegna le funzioni thread-safe come in grado di essere distrutte, né napi_ref_threadsafe_function impedisce che vengano distrutte. napi_acquire_threadsafe_function e napi_release_threadsafe_function sono disponibili a tale scopo.
Questa API può essere chiamata solo dal thread principale.
napi_unref_threadsafe_function
Aggiunto in: v10.6.0
Versione N-API: 4
NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);[in] env: L'ambiente in cui viene invocata l'API.[in] func: La funzione thread-safe di cui rimuovere il riferimento.
Questa API viene utilizzata per indicare che il loop di eventi in esecuzione sul thread principale può uscire prima che func venga distrutta. Simile a uv_unref è anche idempotente.
Questa API può essere chiamata solo dal thread principale.
Utilità varie
node_api_get_module_file_name
Aggiunto in: v15.9.0, v14.18.0, v12.22.0
Versione N-API: 9
NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);[in] env: L'ambiente in cui viene invocata l'API.[out] result: Un URL contenente il percorso assoluto della posizione da cui è stato caricato l'add-on. Per un file sul file system locale, inizierà confile://. La stringa è terminata da null ed è di proprietà dienve quindi non deve essere modificata o liberata.
result potrebbe essere una stringa vuota se il processo di caricamento dell'add-on non riesce a stabilire il nome del file dell'add-on durante il caricamento.