Node-API
[Estável: 2 - Estável]
Estável: 2 Estabilidade: 2 - Estável
Node-API (anteriormente N-API) é uma API para construir Addons nativos. Ela é independente do runtime JavaScript subjacente (por exemplo, V8) e é mantida como parte do próprio Node.js. Esta API será Application Binary Interface (ABI) estável entre as versões do Node.js. Ela tem como objetivo isolar os addons de mudanças no motor JavaScript subjacente e permitir que módulos compilados para uma versão principal sejam executados em versões principais posteriores do Node.js sem recompilação. O guia Estabilidade ABI fornece uma explicação mais aprofundada.
Addons são construídos/empacotados com a mesma abordagem/ferramentas descritas na seção intitulada Addons C++. A única diferença é o conjunto de APIs que são usadas pelo código nativo. Em vez de usar as APIs do V8 ou Native Abstractions for Node.js, as funções disponíveis no Node-API são usadas.
As APIs expostas pelo Node-API são geralmente usadas para criar e manipular valores JavaScript. Conceitos e operações geralmente são mapeados para ideias especificadas na Especificação de Linguagem ECMA-262. As APIs têm as seguintes propriedades:
- Todas as chamadas Node-API retornam um código de status do tipo
napi_status. Esse status indica se a chamada da API foi bem-sucedida ou falhou. - O valor de retorno da API é passado por meio de um parâmetro de saída.
- Todos os valores JavaScript são abstraídos por trás de um tipo opaco denominado
napi_value. - Em caso de um código de status de erro, informações adicionais podem ser obtidas usando
napi_get_last_error_info. Mais informações podem ser encontradas na seção de tratamento de erros Tratamento de erros.
Node-API é uma API C que garante estabilidade ABI entre versões do Node.js e diferentes níveis de compilador. Uma API C++ pode ser mais fácil de usar. Para dar suporte ao uso de C++, o projeto mantém um módulo wrapper C++ chamado node-addon-api. Este wrapper fornece uma API C++ em linha. Os binários construídos com node-addon-api dependerão dos símbolos para as funções baseadas em C da Node-API exportadas pelo Node.js. node-addon-api é uma maneira mais eficiente de escrever código que chama Node-API. Veja, por exemplo, o seguinte código node-addon-api. A primeira seção mostra o código node-addon-api e a segunda seção mostra o que realmente é usado no 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;
}O resultado final é que o addon usa apenas as APIs C exportadas. Como resultado, ele ainda obtém os benefícios da estabilidade ABI fornecida pela API C.
Ao usar node-addon-api em vez das APIs C, comece com a API documentos para node-addon-api.
O Recurso Node-API oferece uma excelente orientação e dicas para desenvolvedores que estão começando a usar o Node-API e o node-addon-api. Recursos de mídia adicionais podem ser encontrados na página Mídia Node-API.
Implicações da estabilidade da ABI
Embora a Node-API forneça uma garantia de estabilidade da ABI, outras partes do Node.js não fornecem, e quaisquer bibliotecas externas usadas pelo addon podem não fornecer. Em particular, nenhuma das seguintes APIs fornece uma garantia de estabilidade da ABI entre as versões principais:
- as APIs C++ do Node.js disponíveis por meio de quaisquer
- as APIs libuv que também estão incluídas no Node.js e disponíveis por meio de
- a API V8 disponível por meio de
Portanto, para que um addon permaneça compatível com a ABI entre as versões principais do Node.js, ele deve usar exclusivamente a Node-API, restringindo-se ao uso de
#include <node_api.h>e verificando, para todas as bibliotecas externas que ele usa, se a biblioteca externa oferece garantias de estabilidade da ABI semelhantes à Node-API.
Construindo
Ao contrário dos módulos escritos em JavaScript, o desenvolvimento e a implantação de addons nativos do Node.js usando a Node-API exigem um conjunto adicional de ferramentas. Além das ferramentas básicas necessárias para o desenvolvimento do Node.js, o desenvolvedor de addons nativos precisa de uma cadeia de ferramentas que possa compilar código C e C++ em um binário. Além disso, dependendo de como o addon nativo é implantado, o usuário do addon nativo também precisará ter uma cadeia de ferramentas C/C++ instalada.
Para desenvolvedores Linux, os pacotes de ferramentas C/C++ necessários estão prontamente disponíveis. O GCC é amplamente utilizado na comunidade Node.js para construir e testar em uma variedade de plataformas. Para muitos desenvolvedores, a infraestrutura de compilador LLVM também é uma boa escolha.
Para desenvolvedores Mac, o Xcode oferece todas as ferramentas de compilador necessárias. No entanto, não é necessário instalar todo o IDE do Xcode. O seguinte comando instala a cadeia de ferramentas necessária:
xcode-select --installPara desenvolvedores Windows, o Visual Studio oferece todas as ferramentas de compilador necessárias. No entanto, não é necessário instalar todo o IDE do Visual Studio. O seguinte comando instala a cadeia de ferramentas necessária:
npm install --global windows-build-toolsAs seções abaixo descrevem as ferramentas adicionais disponíveis para desenvolver e implantar addons nativos do Node.js.
Ferramentas de construção
Ambas as ferramentas listadas aqui exigem que os usuários do addon nativo tenham um conjunto de ferramentas C/C++ instalado para instalar com sucesso o addon nativo.
node-gyp
node-gyp é um sistema de construção baseado no fork gyp-next da ferramenta GYP do Google e vem incluído com o npm. O GYP e, portanto, o node-gyp, exigem que o Python seja instalado.
Historicamente, o node-gyp tem sido a ferramenta de escolha para construir addons nativos. Tem ampla adoção e documentação. No entanto, alguns desenvolvedores encontraram limitações no node-gyp.
CMake.js
CMake.js é um sistema de construção alternativo baseado em CMake.
O CMake.js é uma boa escolha para projetos que já usam o CMake ou para desenvolvedores afetados por limitações no node-gyp. build_with_cmake é um exemplo de um projeto de addon nativo baseado em CMake.
Carregando binários pré-compilados
As três ferramentas listadas aqui permitem que desenvolvedores e mantenedores de addons nativos criem e carreguem binários para servidores públicos ou privados. Essas ferramentas são normalmente integradas a sistemas de construção CI/CD como Travis CI e AppVeyor para construir e carregar binários para uma variedade de plataformas e arquiteturas. Esses binários ficam então disponíveis para download por usuários que não precisam ter um conjunto de ferramentas C/C++ instalado.
node-pre-gyp
node-pre-gyp é uma ferramenta baseada em node-gyp que adiciona a capacidade de carregar binários para um servidor de escolha do desenvolvedor. O node-pre-gyp tem um suporte particularmente bom para carregar binários para o Amazon S3.
prebuild
prebuild é uma ferramenta que oferece suporte a construções usando node-gyp ou CMake.js. Ao contrário do node-pre-gyp, que oferece suporte a uma variedade de servidores, o prebuild carrega binários apenas para versões do GitHub. O prebuild é uma boa escolha para projetos do GitHub que usam CMake.js.
prebuildify
prebuildify é uma ferramenta baseada em node-gyp. A vantagem do prebuildify é que os binários construídos são agrupados com o addon nativo quando é carregado para o npm. Os binários são baixados do npm e ficam imediatamente disponíveis para o usuário do módulo quando o addon nativo é instalado.
Uso
Para usar as funções da Node-API, inclua o arquivo node_api.h que está localizado no diretório src na árvore de desenvolvimento do node:
#include <node_api.h>Isso irá optar pela NAPI_VERSION padrão para a versão específica do Node.js. Para garantir a compatibilidade com versões específicas do Node-API, a versão pode ser especificada explicitamente ao incluir o cabeçalho:
#define NAPI_VERSION 3
#include <node_api.h>Isso restringe a superfície da Node-API apenas à funcionalidade que estava disponível nas versões especificadas (e anteriores).
Parte da superfície da Node-API é experimental e requer opt-in explícito:
#define NAPI_EXPERIMENTAL
#include <node_api.h>Neste caso, toda a superfície da API, incluindo quaisquer APIs experimentais, estará disponível para o código do módulo.
Ocasionalmente, recursos experimentais são introduzidos que afetam APIs já lançadas e estáveis. Esses recursos podem ser desativados por um opt-out:
#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>onde \<FEATURE_NAME\> é o nome de um recurso experimental que afeta APIs experimentais e estáveis.
Matriz de versão da Node-API
Até a versão 9, as versões da Node-API eram aditivas e versionadas independentemente do Node.js. Isso significava que qualquer versão era uma extensão da versão anterior, pois tinha todas as APIs da versão anterior com algumas adições. Cada versão do Node.js suportava apenas uma única versão da Node-API. Por exemplo, a v18.15.0 suporta apenas a versão 8 da Node-API. A estabilidade ABI foi alcançada porque 8 era um superconjunto estrito de todas as versões anteriores.
A partir da versão 9, embora as versões da Node-API continuem a ser versionadas independentemente, um addon que foi executado com a versão 9 da Node-API pode precisar de atualizações de código para ser executado com a versão 10 da Node-API. A estabilidade ABI é mantida, no entanto, porque as versões do Node.js que suportam versões da Node-API superiores a 8 suportarão todas as versões entre 8 e a versão mais alta que suportam e usarão como padrão o fornecimento das APIs da versão 8, a menos que um addon opte por uma versão superior da Node-API. Essa abordagem oferece a flexibilidade de otimizar melhor as funções existentes da Node-API, mantendo a estabilidade da ABI. Addons existentes podem continuar a ser executados sem recompilação usando uma versão anterior da Node-API. Se um addon precisar de funcionalidade de uma versão mais recente da Node-API, serão necessárias alterações no código existente e recompilação para usar essas novas funções de qualquer maneira.
Nas versões do Node.js que suportam a versão 9 da Node-API e posteriores, definir NAPI_VERSION=X e usar as macros de inicialização de addon existentes incluirá a versão solicitada da Node-API que será usada em tempo de execução no addon. Se NAPI_VERSION não estiver definido, ele assumirá o padrão 8.
Esta tabela pode não estar atualizada em fluxos mais antigos, as informações mais atualizadas estão na documentação da API mais recente em: Matriz de versão da Node-API
| Versão da Node-API | Suportada em |
|---|---|
| 9 | v18.17.0+, 20.3.0+, 21.0.0 e todas as versões posteriores |
| 8 | v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 e todas as versões posteriores |
| 7 | v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 e todas as versões posteriores |
| 6 | v10.20.0+, v12.17.0+, 14.0.0 e todas as versões posteriores |
| 5 | v10.17.0+, v12.11.0+, 13.0.0 e todas as versões posteriores |
| 4 | v10.16.0+, v11.8.0+, 12.0.0 e todas as versões posteriores |
| 3 | v6.14.2*, 8.11.2+, v9.11.0+*, 10.0.0 e todas as versões posteriores |
| 2 | v8.10.0+, v9.3.0+, 10.0.0 e todas as versões posteriores |
| 1 | v8.6.0+*, v9.0.0+, 10.0.0 e todas as versões posteriores |
- A Node-API era experimental.
** O Node.js 8.0.0 incluiu a Node-API como experimental. Foi lançado como a versão 1 da Node-API, mas continuou a evoluir até o Node.js 8.6.0. A API é diferente em versões anteriores ao Node.js 8.6.0. Recomendamos a versão 3 ou posterior da Node-API.
Cada API documentada para a Node-API terá um cabeçalho denominado added in:, e as APIs que são estáveis terão o cabeçalho adicional Node-API version:. As APIs são diretamente utilizáveis ao usar uma versão do Node.js que suporta a versão da Node-API mostrada em Node-API version: ou superior. Ao usar uma versão do Node.js que não suporta o Node-API version: listado ou se não houver Node-API version: listado, então a API estará disponível apenas se #define NAPI_EXPERIMENTAL preceder a inclusão de node_api.h ou js_native_api.h. Se uma API parece não estar disponível em uma versão do Node.js que seja posterior à mostrada em added in:, então esta é provavelmente a razão para a aparente ausência.
As Node-APIs associadas estritamente ao acesso a recursos ECMAScript de código nativo podem ser encontradas separadamente em js_native_api.h e js_native_api_types.h. As APIs definidas nesses cabeçalhos estão incluídas em node_api.h e node_api_types.h. Os cabeçalhos são estruturados desta forma para permitir implementações da Node-API fora do Node.js. Para essas implementações, as APIs específicas do Node.js podem não ser aplicáveis.
As partes específicas do Node.js de um addon podem ser separadas do código que expõe a funcionalidade real ao ambiente JavaScript para que o último possa ser usado com várias implementações da Node-API. No exemplo abaixo, addon.c e addon.h referem-se apenas a js_native_api.h. Isso garante que addon.c possa ser reutilizado para compilar contra a implementação da Node-API do Node.js ou qualquer implementação da Node-API fora do Node.js.
addon_node.c é um arquivo separado que contém o ponto de entrada específico do Node.js para o addon e que instancia o addon chamando addon.c quando o addon é carregado em um 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); \
/* Se uma exceção já estiver pendente, não a relance */ \
if (!is_pending) { \
const char* message = (err_message == NULL) \
? "mensagem de erro vazia" \
: err_message; \
napi_throw_error((env), NULL, message); \
} \
return NULL; \
} \
} while(0)
static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
// Faça algo útil.
return NULL;
}
napi_value create_addon(napi_env env) {
napi_value result;
NODE_API_CALL(env, napi_create_object(env, &result));
napi_value exported_function;
NODE_API_CALL(env, napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function));
NODE_API_CALL(env, napi_set_named_property(env,
result,
"doSomethingUseful",
exported_function));
return result;
}// addon_node.c
#include <node_api.h>
#include "addon.h"
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
// Espera-se que o corpo desta função retorne um `napi_value`.
// As variáveis `napi_env env` e `napi_value exports` podem ser usadas dentro
// do corpo, pois são fornecidas pela definição de `NAPI_MODULE_INIT()`.
return create_addon(env);
}APIs de ciclo de vida do ambiente
A Seção 8.7 da Especificação da Linguagem ECMAScript define o conceito de um "Agente" como um ambiente autocontido no qual o código JavaScript é executado. Vários desses Agentes podem ser iniciados e encerrados simultaneamente ou em sequência pelo processo.
Um ambiente Node.js corresponde a um Agente ECMAScript. No processo principal, um ambiente é criado na inicialização, e ambientes adicionais podem ser criados em threads separados para servir como threads de worker. Quando o Node.js é incorporado em outro aplicativo, a thread principal do aplicativo também pode construir e destruir um ambiente Node.js várias vezes durante o ciclo de vida do processo do aplicativo, de modo que cada ambiente Node.js criado pelo aplicativo pode, por sua vez, durante seu ciclo de vida criar e destruir ambientes adicionais como threads de worker.
Da perspectiva de um addon nativo, isso significa que as vinculações que ele fornece podem ser chamadas várias vezes, de vários contextos e até mesmo simultaneamente de várias threads.
Addons nativos podem precisar alocar um estado global que usam durante o ciclo de vida de um ambiente Node.js, de forma que o estado possa ser exclusivo para cada instância do addon.
Para esse fim, o Node-API fornece uma maneira de associar dados de forma que seu ciclo de vida esteja vinculado ao ciclo de vida de um ambiente Node.js.
napi_set_instance_data
Adicionado em: v12.8.0, v10.20.0
Versão 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: O ambiente sob o qual a chamada Node-API é invocada.[in] data: O item de dados a ser disponibilizado para vinculações desta instância.[in] finalize_cb: A função a ser chamada quando o ambiente está sendo encerrado. A função recebedatapara que possa liberá-lo.napi_finalizefornece mais detalhes.[in] finalize_hint: Dica opcional para passar para o callback de finalização durante a coleta.
Retorna napi_ok se a API for bem-sucedida.
Esta API associa data ao ambiente Node.js em execução no momento. data pode ser recuperado posteriormente usando napi_get_instance_data(). Quaisquer dados existentes associados ao ambiente Node.js em execução no momento que foram definidos por meio de uma chamada anterior para napi_set_instance_data() serão sobrescritos. Se um finalize_cb foi fornecido pela chamada anterior, ele não será chamado.
napi_get_instance_data
Adicionado em: v12.8.0, v10.20.0
Versão N-API: 6
napi_status napi_get_instance_data(node_api_basic_env env,
void** data);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[out] data: O item de dados que foi previamente associado ao ambiente Node.js em execução através de uma chamada paranapi_set_instance_data().
Retorna napi_ok se a API for bem-sucedida.
Esta API recupera dados que foram previamente associados ao ambiente Node.js em execução através de napi_set_instance_data(). Se nenhum dado for definido, a chamada será bem-sucedida e data será definido como NULL.
Tipos de dados básicos da Node-API
A Node-API expõe os seguintes tipos de dados fundamentais como abstrações que são consumidas pelas várias APIs. Estas APIs devem ser tratadas como opacas, introspectáveis apenas com outras chamadas Node-API.
napi_status
Adicionado em: v8.0.0
Versão N-API: 1
Código de status integral que indica o sucesso ou falha de uma chamada Node-API. Atualmente, os seguintes códigos de status são suportados.
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, /* não usado */
napi_no_external_buffers_allowed,
napi_cannot_run_js
} napi_status;Se informações adicionais forem necessárias após uma API retornar um status de falha, elas podem ser obtidas chamando napi_get_last_error_info.
napi_extended_error_info
Adicionado em: v8.0.0
Versão 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: String com codificação UTF8 contendo uma descrição neutra da VM do erro.engine_reserved: Reservado para detalhes de erro específicos da VM. Atualmente, isto não está implementado para nenhuma VM.engine_error_code: Código de erro específico da VM. Atualmente, isto não está implementado para nenhuma VM.error_code: O código de status da Node-API que se originou com o último erro.
Consulte a seção Tratamento de erros para obter informações adicionais.
napi_env
napi_env é usado para representar um contexto que a implementação Node-API subjacente pode usar para persistir o estado específico da VM. Esta estrutura é passada para funções nativas quando são invocadas e deve ser passada de volta ao fazer chamadas Node-API. Especificamente, o mesmo napi_env que foi passado quando a função nativa inicial foi chamada deve ser passado para quaisquer chamadas Node-API aninhadas subsequentes. Não é permitido o armazenamento em cache do napi_env com o objetivo de reutilização geral e a passagem do napi_env entre instâncias do mesmo addon em execução em diferentes threads Worker. O napi_env torna-se inválido quando uma instância de um addon nativo é descarregada. A notificação deste evento é entregue através dos callbacks fornecidos para napi_add_env_cleanup_hook e napi_set_instance_data.
node_api_basic_env
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
Esta variante de napi_env é passada para finalizadores síncronos (node_api_basic_finalize). Há um subconjunto de Node-APIs que aceitam um parâmetro do tipo node_api_basic_env como seu primeiro argumento. Estas APIs não acessam o estado do motor JavaScript e, portanto, são seguras para serem chamadas a partir de finalizadores síncronos. É permitido passar um parâmetro do tipo napi_env para estas APIs, no entanto, não é permitido passar um parâmetro do tipo node_api_basic_env para APIs que acessam o estado do motor JavaScript. Tentar fazê-lo sem uma conversão produzirá um aviso do compilador ou um erro quando os add-ons são compilados com flags que fazem com que emitam avisos e/ou erros quando tipos de ponteiro incorretos são passados para uma função. Chamar tais APIs a partir de um finalizador síncrono resultará, em última instância, na terminação da aplicação.
napi_value
Este é um ponteiro opaco que é usado para representar um valor JavaScript.
napi_threadsafe_function
Adicionado em: v10.6.0
Versão N-API: 4
Este é um ponteiro opaco que representa uma função JavaScript que pode ser chamada de forma assíncrona a partir de várias threads por meio de napi_call_threadsafe_function().
napi_threadsafe_function_release_mode
Adicionado em: v10.6.0
Versão N-API: 4
Um valor a ser fornecido para napi_release_threadsafe_function() para indicar se a função thread-safe deve ser fechada imediatamente (napi_tsfn_abort) ou apenas liberada (napi_tsfn_release) e, portanto, disponível para uso posterior por meio de 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
Adicionado em: v10.6.0
Versão N-API: 4
Um valor a ser fornecido para napi_call_threadsafe_function() para indicar se a chamada deve bloquear sempre que a fila associada à função thread-safe estiver cheia.
typedef enum {
napi_tsfn_nonblocking,
napi_tsfn_blocking
} napi_threadsafe_function_call_mode;Tipos de gerenciamento de memória Node-API
napi_handle_scope
Esta é uma abstração usada para controlar e modificar o tempo de vida dos objetos criados dentro de um escopo específico. Em geral, os valores Node-API são criados dentro do contexto de um escopo de manipulação. Quando um método nativo é chamado a partir do JavaScript, existirá um escopo de manipulação padrão. Se o usuário não criar explicitamente um novo escopo de manipulação, os valores Node-API serão criados no escopo de manipulação padrão. Para quaisquer invocações de código fora da execução de um método nativo (por exemplo, durante uma invocação de callback libuv), o módulo é obrigado a criar um escopo antes de invocar quaisquer funções que possam resultar na criação de valores JavaScript.
Os escopos de manipulação são criados usando napi_open_handle_scope e são destruídos usando napi_close_handle_scope. Fechar o escopo pode indicar ao GC que todos os napi_values criados durante o tempo de vida do escopo de manipulação não são mais referenciados a partir do frame de pilha atual.
Para mais detalhes, revise o gerenciamento do tempo de vida do objeto.
napi_escapable_handle_scope
Adicionado em: v8.0.0
Versão N-API: 1
Escopos de manipuladores escapáveis são um tipo especial de escopo de manipulador para retornar valores criados dentro de um escopo de manipulador particular para um escopo pai.
napi_ref
Adicionado em: v8.0.0
Versão N-API: 1
Esta é a abstração a ser usada para referenciar um napi_value. Isso permite que os usuários gerenciem os tempos de vida dos valores JavaScript, incluindo a definição explícita de seus tempos de vida mínimos.
Para mais detalhes, revise Gerenciamento do tempo de vida de objetos.
napi_type_tag
Adicionado em: v14.8.0, v12.19.0
Versão N-API: 8
Um valor de 128 bits armazenado como dois inteiros não assinados de 64 bits. Ele serve como um UUID com o qual objetos JavaScript ou externals podem ser "marcados" para garantir que sejam de um certo tipo. Esta é uma verificação mais forte do que napi_instanceof, porque o último pode reportar um falso positivo se o protótipo do objeto tiver sido manipulado. A marcação de tipo é mais útil em conjunto com napi_wrap, pois garante que o ponteiro recuperado de um objeto encapsulado possa ser convertido com segurança para o tipo nativo correspondente à marca de tipo que foi aplicada anteriormente ao objeto JavaScript.
typedef struct {
uint64_t lower;
uint64_t upper;
} napi_type_tag;napi_async_cleanup_hook_handle
Adicionado em: v14.10.0, v12.19.0
Um valor opaco retornado por napi_add_async_cleanup_hook. Ele deve ser passado para napi_remove_async_cleanup_hook quando a cadeia de eventos de limpeza assíncrona for concluída.
Tipos de callback Node-API
napi_callback_info
Adicionado em: v8.0.0
Versão N-API: 1
Tipo de dados opaco que é passado para uma função de callback. Ele pode ser usado para obter informações adicionais sobre o contexto em que o callback foi invocado.
napi_callback
Adicionado em: v8.0.0
Versão N-API: 1
Tipo de ponteiro de função para funções nativas fornecidas pelo usuário que devem ser expostas ao JavaScript via Node-API. As funções de callback devem satisfazer a seguinte assinatura:
typedef napi_value (*napi_callback)(napi_env, napi_callback_info);A menos que por razões discutidas em Gerenciamento do Tempo de Vida de Objetos, criar um manipulador e/ou escopo de callback dentro de um napi_callback não é necessário.
node_api_basic_finalize
Adicionado em: v21.6.0, v20.12.0, v18.20.0
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
Tipo de ponteiro de função para funções fornecidas por add-ons que permitem que o usuário seja notificado quando dados de propriedade externa estão prontos para serem limpos porque o objeto ao qual estavam associados foi coletado pelo coletor de lixo. O usuário deve fornecer uma função que satisfaça a seguinte assinatura, que seria chamada na coleta do objeto. Atualmente, node_api_basic_finalize pode ser usado para descobrir quando objetos que possuem dados externos são coletados.
typedef void (*node_api_basic_finalize)(node_api_basic_env env,
void* finalize_data,
void* finalize_hint);A menos que por razões discutidas em Gerenciamento do Tempo de Vida do Objeto, criar um handle e/ou um escopo de callback dentro do corpo da função não é necessário.
Como essas funções podem ser chamadas enquanto o motor JavaScript está em um estado em que não pode executar código JavaScript, apenas Node-APIs que aceitam um node_api_basic_env como seu primeiro parâmetro podem ser chamadas. node_api_post_finalizer pode ser usado para agendar chamadas Node-API que exigem acesso ao estado do motor JavaScript para serem executadas após a conclusão do ciclo de coleta de lixo atual.
No caso de node_api_create_external_string_latin1 e node_api_create_external_string_utf16, o parâmetro env pode ser nulo, porque strings externas podem ser coletadas durante a última parte do desligamento do ambiente.
Histórico de Alterações:
- experimental (
NAPI_EXPERIMENTAL): Apenas chamadas Node-API que aceitam umnode_api_basic_envcomo seu primeiro parâmetro podem ser chamadas, caso contrário, o aplicativo será encerrado com uma mensagem de erro apropriada. Esse recurso pode ser desativado definindoNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.
napi_finalize
Adicionado em: v8.0.0
Versão da N-API: 1
Tipo de ponteiro de função para a função fornecida pelo complemento que permite ao usuário agendar um grupo de chamadas para as APIs do Node em resposta a um evento de coleta de lixo, após a conclusão do ciclo de coleta de lixo. Esses ponteiros de função podem ser usados com node_api_post_finalizer.
typedef void (*napi_finalize)(napi_env env,
void* finalize_data,
void* finalize_hint);Histórico de alterações:
- experimental (
NAPI_EXPERIMENTALestá definido): Uma função deste tipo pode não ser mais usada como finalizador, exceto comnode_api_post_finalizer.node_api_basic_finalizedeve ser usado em vez disso. Este recurso pode ser desativado definindoNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.
napi_async_execute_callback
Adicionado em: v8.0.0
Versão da N-API: 1
Ponteiro de função usado com funções que suportam operações assíncronas. As funções de retorno de chamada devem satisfazer a seguinte assinatura:
typedef void (*napi_async_execute_callback)(napi_env env, void* data);As implementações desta função devem evitar fazer chamadas Node-API que executam JavaScript ou interagem com objetos JavaScript. As chamadas Node-API devem estar no napi_async_complete_callback em vez disso. Não use o parâmetro napi_env, pois provavelmente resultará na execução de JavaScript.
napi_async_complete_callback
Adicionado em: v8.0.0
Versão da N-API: 1
Ponteiro de função usado com funções que suportam operações assíncronas. As funções de retorno de chamada devem satisfazer a seguinte assinatura:
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);A menos que por razões discutidas em Gerenciamento do Ciclo de Vida do Objeto, criar um identificador e/ou escopo de retorno de chamada dentro do corpo da função não é necessário.
napi_threadsafe_function_call_js
Adicionado em: v10.6.0
Versão N-API: 4
Ponteiro de função usado com chamadas assíncronas de função thread-safe. O callback será chamado no thread principal. O objetivo é usar um item de dados que chega através da fila de um dos threads secundários para construir os parâmetros necessários para uma chamada para o JavaScript, geralmente via napi_call_function, e então fazer a chamada para o JavaScript.
Os dados que chegam do thread secundário através da fila são fornecidos no parâmetro data e a função JavaScript a ser chamada é fornecida no parâmetro js_callback.
O Node-API configura o ambiente antes de chamar este callback, portanto, é suficiente chamar a função JavaScript via napi_call_function em vez de via napi_make_callback.
As funções de callback devem satisfazer a seguinte assinatura:
typedef void (*napi_threadsafe_function_call_js)(napi_env env,
napi_value js_callback,
void* context,
void* data);[in] env: O ambiente a ser usado para chamadas de API, ouNULLse a função thread-safe estiver sendo destruída edatapode precisar ser liberado.[in] js_callback: A função JavaScript a ser chamada, ouNULLse a função thread-safe estiver sendo destruída edatapode precisar ser liberado. Também pode serNULLse a função thread-safe foi criada semjs_callback.[in] context: Os dados opcionais com os quais a função thread-safe foi criada.[in] data: Dados criados pelo thread secundário. É responsabilidade do callback converter esses dados nativos em valores JavaScript (com funções Node-API) que podem ser passados como parâmetros quandojs_callbacké invocado. Este ponteiro é gerenciado inteiramente pelos threads e este callback. Assim, este callback deve liberar os dados.
A menos que por razões discutidas em Gerenciamento do Tempo de Vida do Objeto, criar um handle e/ou escopo de callback dentro do corpo da função não é necessário.
napi_cleanup_hook
Adicionado em: v19.2.0, v18.13.0
Versão N-API: 3
Ponteiro de função usado com napi_add_env_cleanup_hook. Será chamado quando o ambiente estiver sendo desmontado.
As funções de callback devem satisfazer a seguinte assinatura:
typedef void (*napi_cleanup_hook)(void* data);[in] data: Os dados que foram passados paranapi_add_env_cleanup_hook.
napi_async_cleanup_hook
Adicionado em: v14.10.0, v12.19.0
Ponteiro de função usado com napi_add_async_cleanup_hook. Será chamado quando o ambiente estiver sendo desmontado.
As funções de callback devem satisfazer a seguinte assinatura:
typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
void* data);[in] handle: O handle que deve ser passado paranapi_remove_async_cleanup_hookapós a conclusão da limpeza assíncrona.[in] data: Os dados que foram passados paranapi_add_async_cleanup_hook.
O corpo da função deve iniciar as ações de limpeza assíncrona ao final das quais handle deve ser passado em uma chamada para napi_remove_async_cleanup_hook.
Tratamento de Erros
A Node-API usa valores de retorno e exceções JavaScript para o tratamento de erros. As seções a seguir explicam a abordagem para cada caso.
Valores de Retorno
Todas as funções da Node-API compartilham o mesmo padrão de tratamento de erros. O tipo de retorno de todas as funções da API é napi_status.
O valor de retorno será napi_ok se a solicitação foi bem-sucedida e nenhuma exceção JavaScript não tratada foi lançada. Se ocorreu um erro E uma exceção foi lançada, o valor napi_status para o erro será retornado. Se uma exceção foi lançada e nenhum erro ocorreu, napi_pending_exception será retornado.
Nos casos em que um valor de retorno diferente de napi_ok ou napi_pending_exception é retornado, napi_is_exception_pending deve ser chamado para verificar se há uma exceção pendente. Veja a seção sobre exceções para mais detalhes.
O conjunto completo de possíveis valores napi_status é definido em napi_api_types.h.
O valor de retorno napi_status fornece uma representação independente da VM do erro que ocorreu. Em alguns casos, é útil obter informações mais detalhadas, incluindo uma string que representa o erro, bem como informações específicas da VM (engine).
Para recuperar essas informações, napi_get_last_error_info é fornecido, que retorna uma estrutura napi_extended_error_info. O formato da estrutura napi_extended_error_info é o seguinte:
Adicionado em: v8.0.0
Versão 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: Representação textual do erro que ocorreu.engine_reserved: Handle opaco reservado apenas para uso do engine.engine_error_code: Código de erro específico da VM.error_code: Código de status da Node-API para o último erro.
napi_get_last_error_info retorna as informações para a última chamada da Node-API que foi feita.
Não confie no conteúdo ou formato de nenhuma das informações estendidas, pois não está sujeito ao SemVer e pode mudar a qualquer momento. Destina-se apenas para fins de registro.
napi_get_last_error_info
Adicionado em: v8.0.0
Versão N-API: 1
napi_status
napi_get_last_error_info(node_api_basic_env env,
const napi_extended_error_info** result);[in] env: O ambiente sob o qual a API é invocada.[out] result: A estruturanapi_extended_error_infocom mais informações sobre o erro.
Retorna napi_ok se a API for bem-sucedida.
Esta API recupera uma estrutura napi_extended_error_info com informações sobre o último erro que ocorreu.
O conteúdo do napi_extended_error_info retornado só é válido até que uma função Node-API seja chamada no mesmo env. Isso inclui uma chamada para napi_is_exception_pending, portanto, muitas vezes pode ser necessário fazer uma cópia das informações para que elas possam ser usadas mais tarde. O ponteiro retornado em error_message aponta para uma string definida estaticamente, portanto, é seguro usar esse ponteiro se você o copiou do campo error_message (que será sobrescrito) antes que outra função Node-API fosse chamada.
Não dependa do conteúdo ou formato de nenhuma das informações estendidas, pois elas não estão sujeitas ao SemVer e podem mudar a qualquer momento. Elas são destinadas apenas para fins de registro em log.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
Exceções
Qualquer chamada de função Node-API pode resultar em uma exceção JavaScript pendente. Este é o caso de qualquer uma das funções da API, mesmo aquelas que podem não causar a execução de JavaScript.
Se o napi_status retornado por uma função for napi_ok, então nenhuma exceção está pendente e nenhuma ação adicional é necessária. Se o napi_status retornado for qualquer coisa diferente de napi_ok ou napi_pending_exception, para tentar recuperar e continuar em vez de simplesmente retornar imediatamente, napi_is_exception_pending deve ser chamado para determinar se uma exceção está pendente ou não.
Em muitos casos, quando uma função Node-API é chamada e uma exceção já está pendente, a função retornará imediatamente com um napi_status de napi_pending_exception. No entanto, este não é o caso para todas as funções. Node-API permite que um subconjunto das funções seja chamado para permitir alguma limpeza mínima antes de retornar para JavaScript. Nesse caso, napi_status refletirá o status da função. Não refletirá as exceções pendentes anteriores. Para evitar confusão, verifique o status de erro após cada chamada de função.
Quando uma exceção está pendente, uma de duas abordagens pode ser empregada.
A primeira abordagem é fazer qualquer limpeza apropriada e depois retornar para que a execução retorne ao JavaScript. Como parte da transição de volta para JavaScript, a exceção será lançada no ponto do código JavaScript onde o método nativo foi invocado. O comportamento da maioria das chamadas Node-API não é especificado enquanto uma exceção está pendente, e muitas simplesmente retornarão napi_pending_exception, então faça o mínimo possível e depois retorne para JavaScript onde a exceção pode ser tratada.
A segunda abordagem é tentar tratar a exceção. Haverá casos em que o código nativo pode capturar a exceção, tomar a ação apropriada e depois continuar. Isso só é recomendado em casos específicos onde se sabe que a exceção pode ser tratada com segurança. Nesses casos, napi_get_and_clear_last_exception pode ser usado para obter e limpar a exceção. Em caso de sucesso, o resultado conterá o manipulador para o último Object JavaScript lançado. Se for determinado, após recuperar a exceção, que a exceção não pode ser tratada, ela pode ser relançada com napi_throw onde error é o valor JavaScript a ser lançado.
As seguintes funções de utilitário também estão disponíveis caso o código nativo precise lançar uma exceção ou determinar se um napi_value é uma instância de um objeto Error JavaScript: napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error e napi_is_error.
As seguintes funções de utilitário também estão disponíveis caso o código nativo precise criar um objeto Error: napi_create_error, napi_create_type_error, napi_create_range_error e node_api_create_syntax_error, onde result é o napi_value que se refere ao objeto Error JavaScript recém-criado.
O projeto Node.js está adicionando códigos de erro a todos os erros gerados internamente. O objetivo é que as aplicações usem esses códigos de erro para toda a verificação de erros. As mensagens de erro associadas permanecerão, mas serão destinadas apenas para uso em registro em log e exibição com a expectativa de que a mensagem possa mudar sem que o SemVer se aplique. Para suportar este modelo com Node-API, tanto em funcionalidades internas quanto para funcionalidades específicas de módulo (como é uma boa prática), as funções throw_ e create_ aceitam um parâmetro de código opcional que é a string para o código a ser adicionado ao objeto de erro. Se o parâmetro opcional for NULL, nenhum código será associado ao erro. Se um código for fornecido, o nome associado ao erro também será atualizado para ser:
originalName [code]onde originalName é o nome original associado ao erro e code é o código que foi fornecido. Por exemplo, se o código for 'ERR_ERROR_1' e um TypeError estiver sendo criado, o nome será:
TypeError [ERR_ERROR_1]napi_throw
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);[in] env: O ambiente sob o qual a API é invocada.[in] error: O valor JavaScript a ser lançado.
Retorna napi_ok se a API for bem-sucedida.
Esta API lança o valor JavaScript fornecido.
napi_throw_error
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
const char* code,
const char* msg);[in] env: O ambiente sob o qual a API é invocada.[in] code: Código de erro opcional a ser definido no erro.[in] msg: String C que representa o texto a ser associado ao erro.
Retorna napi_ok se a API for bem-sucedida.
Esta API lança um Error JavaScript com o texto fornecido.
napi_throw_type_error
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
const char* code,
const char* msg);[in] env: O ambiente sob o qual a API é invocada.[in] code: Código de erro opcional a ser definido no erro.[in] msg: String C que representa o texto a ser associado ao erro.
Retorna napi_ok se a API for bem-sucedida.
Esta API lança um TypeError JavaScript com o texto fornecido.
napi_throw_range_error
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
const char* code,
const char* msg);[in] env: O ambiente sob o qual a API é invocada.[in] code: Código de erro opcional a ser definido no erro.[in] msg: String C que representa o texto a ser associado ao erro.
Retorna napi_ok se a API for bem-sucedida.
Esta API lança um RangeError JavaScript com o texto fornecido.
node_api_throw_syntax_error
Adicionado em: v17.2.0, v16.14.0
Versão N-API: 9
NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
const char* code,
const char* msg);[in] env: O ambiente sob o qual a API é invocada.[in] code: Código de erro opcional a ser definido no erro.[in] msg: String C representando o texto a ser associado ao erro.
Retorna napi_ok se a API for bem-sucedida.
Esta API lança um SyntaxError do JavaScript com o texto fornecido.
napi_is_error
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_is_error(napi_env env,
napi_value value,
bool* result);[in] env: O ambiente sob o qual a API é invocada.[in] value: Onapi_valuea ser verificado.[out] result: Valor booleano que é definido como verdadeiro senapi_valuerepresenta um erro, falso caso contrário.
Retorna napi_ok se a API for bem-sucedida.
Esta API consulta um napi_value para verificar se ele representa um objeto de erro.
napi_create_error
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_create_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[in] code:napi_valueopcional com a string para o código de erro a ser associado ao erro.[in] msg:napi_valueque referencia umastringdo JavaScript a ser usada como mensagem para oError.[out] result:napi_valuerepresentando o erro criado.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna um Error do JavaScript com o texto fornecido.
napi_create_type_error
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] code:napi_valueopcional com a string para o código de erro a ser associado ao erro.[in] msg:napi_valueque referencia umastringdo JavaScript a ser usada como mensagem para oError.[out] result:napi_valuerepresentando o erro criado.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna um TypeError do JavaScript com o texto fornecido.
napi_create_range_error
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] code:napi_valueopcional com a string para o código de erro a ser associado ao erro.[in] msg:napi_valueque referencia umastringJavaScript a ser usada como mensagem para oError.[out] result:napi_valuerepresentando o erro criado.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna um RangeError do JavaScript com o texto fornecido.
node_api_create_syntax_error
Adicionado em: v17.2.0, v16.14.0
Versão 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: O ambiente sob o qual a API é invocada.[in] code:napi_valueopcional com a string para o código de erro a ser associado ao erro.[in] msg:napi_valueque referencia umastringJavaScript a ser usada como mensagem para oError.[out] result:napi_valuerepresentando o erro criado.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna um SyntaxError do JavaScript com o texto fornecido.
napi_get_and_clear_last_exception
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_and_clear_last_exception(napi_env env,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[out] result: A exceção se houver alguma pendente,NULLcaso contrário.
Retorna napi_ok se a API for bem-sucedida.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
napi_is_exception_pending
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_is_exception_pending(napi_env env, bool* result);[in] env: O ambiente sob o qual a API é invocada.[out] result: Valor booleano que é definido como verdadeiro se uma exceção estiver pendente.
Retorna napi_ok se a API for bem-sucedida.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
napi_fatal_exception
Adicionado em: v9.10.0
Versão N-API: 3
napi_status napi_fatal_exception(napi_env env, napi_value err);[in] env: O ambiente sob o qual a API é invocada.[in] err: O erro que é passado para'uncaughtException'.
Aciona um 'uncaughtException' em JavaScript. Útil se um retorno de chamada assíncrono lançar uma exceção sem nenhuma maneira de se recuperar.
Erros fatais
Em caso de um erro irrecuperável em um complemento nativo, um erro fatal pode ser lançado para terminar o processo imediatamente.
napi_fatal_error
Adicionado em: v8.2.0
Versão 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: Localização opcional em que o erro ocorreu.[in] location_len: O comprimento da localização em bytes ouNAPI_AUTO_LENGTHse for terminado em nulo.[in] message: A mensagem associada ao erro.[in] message_len: O comprimento da mensagem em bytes ouNAPI_AUTO_LENGTHse for terminado em nulo.
A chamada de função não retorna, o processo será encerrado.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
Gerenciamento do tempo de vida do objeto
À medida que as chamadas Node-API são feitas, os manipuladores de objetos no heap para a VM subjacente podem ser retornados como napi_values. Esses manipuladores devem manter os objetos 'vivos' até que não sejam mais necessários pelo código nativo, caso contrário, os objetos podem ser coletados antes que o código nativo termine de usá-los.
À medida que os manipuladores de objetos são retornados, eles são associados a um 'escopo'. A vida útil do escopo padrão está ligada à vida útil da chamada do método nativo. O resultado é que, por padrão, os manipuladores permanecem válidos e os objetos associados a esses manipuladores serão mantidos vivos durante a vida útil da chamada do método nativo.
Em muitos casos, no entanto, é necessário que os manipuladores permaneçam válidos por uma vida útil mais curta ou mais longa do que a do método nativo. As seções a seguir descrevem as funções Node-API que podem ser usadas para alterar a vida útil do manipulador do padrão.
Reduzindo a vida útil de um identificador em comparação com a de um método nativo
É frequentemente necessário reduzir a vida útil dos identificadores em comparação com a vida útil de um método nativo. Por exemplo, considere um método nativo que tem um loop que itera através dos elementos em um 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;
}
// fazer algo com o elemento
}Isso resultaria na criação de um grande número de identificadores, consumindo recursos substanciais. Além disso, mesmo que o código nativo pudesse usar apenas o identificador mais recente, todos os objetos associados também seriam mantidos ativos, pois todos compartilham o mesmo escopo.
Para lidar com este caso, o Node-API fornece a capacidade de estabelecer um novo 'escopo' ao qual os identificadores recém-criados serão associados. Uma vez que esses identificadores não sejam mais necessários, o escopo pode ser 'fechado' e quaisquer identificadores associados ao escopo são invalidados. Os métodos disponíveis para abrir/fechar escopos são napi_open_handle_scope e napi_close_handle_scope.
O Node-API suporta apenas uma única hierarquia aninhada de escopos. Existe apenas um escopo ativo a qualquer momento, e todos os novos identificadores serão associados a esse escopo enquanto ele estiver ativo. Os escopos devem ser fechados na ordem inversa àquela em que foram abertos. Além disso, todos os escopos criados dentro de um método nativo devem ser fechados antes de retornar desse método.
Tomando o exemplo anterior, adicionar chamadas a napi_open_handle_scope e napi_close_handle_scope garantiria que no máximo um único identificador seja válido durante toda a execução do loop:
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;
}
// fazer algo com o elemento
status = napi_close_handle_scope(env, scope);
if (status != napi_ok) {
break;
}
}Ao aninhar escopos, há casos em que um identificador de um escopo interno precisa viver além da vida útil desse escopo. O Node-API suporta um 'escopo escapável' para suportar este caso. Um escopo escapável permite que um identificador seja 'promovido' para que ele 'escape' do escopo atual e a vida útil do identificador mude do escopo atual para o do escopo externo.
Os métodos disponíveis para abrir/fechar escopos escapáveis são napi_open_escapable_handle_scope e napi_close_escapable_handle_scope.
A solicitação para promover um identificador é feita através de napi_escape_handle que só pode ser chamada uma vez.
napi_open_handle_scope
Adicionado em: v8.0.0
Versão da N-API: 1
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
napi_handle_scope* result);[in] env: O ambiente sob o qual a API é invocada.[out] result:napi_valuerepresentando o novo escopo.
Retorna napi_ok se a API for bem-sucedida.
Esta API abre um novo escopo.
napi_close_handle_scope
Adicionado em: v8.0.0
Versão da N-API: 1
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
napi_handle_scope scope);[in] env: O ambiente sob o qual a API é invocada.[in] scope:napi_valuerepresentando o escopo a ser fechado.
Retorna napi_ok se a API for bem-sucedida.
Esta API fecha o escopo passado. Os escopos devem ser fechados na ordem inversa em que foram criados.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
napi_open_escapable_handle_scope
Adicionado em: v8.0.0
Versão da N-API: 1
NAPI_EXTERN napi_status
napi_open_escapable_handle_scope(napi_env env,
napi_handle_scope* result);[in] env: O ambiente sob o qual a API é invocada.[out] result:napi_valuerepresentando o novo escopo.
Retorna napi_ok se a API for bem-sucedida.
Esta API abre um novo escopo do qual um objeto pode ser promovido para o escopo externo.
napi_close_escapable_handle_scope
Adicionado em: v8.0.0
Versão da N-API: 1
NAPI_EXTERN napi_status
napi_close_escapable_handle_scope(napi_env env,
napi_handle_scope scope);[in] env: O ambiente sob o qual a API é invocada.[in] scope:napi_valuerepresentando o escopo a ser fechado.
Retorna napi_ok se a API for bem-sucedida.
Esta API fecha o escopo passado. Os escopos devem ser fechados na ordem inversa em que foram criados.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
napi_escape_handle
Adicionado em: v8.0.0
Versão da N-API: 1
napi_status napi_escape_handle(napi_env env,
napi_escapable_handle_scope scope,
napi_value escapee,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[in] scope:napi_valuerepresentando o escopo atual.[in] escapee:napi_valuerepresentando oObjectJavaScript a ser escapado.[out] result:napi_valuerepresentando o manipulador para oObjectescapado no escopo externo.
Retorna napi_ok se a API foi bem-sucedida.
Esta API promove o manipulador para o objeto JavaScript de forma que ele seja válido durante o tempo de vida do escopo externo. Ela só pode ser chamada uma vez por escopo. Se for chamada mais de uma vez, um erro será retornado.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
Referências a valores com um tempo de vida maior que o do método nativo
Em alguns casos, um addon precisará ser capaz de criar e referenciar valores com um tempo de vida maior que o de uma única invocação de método nativo. Por exemplo, para criar um construtor e posteriormente usar esse construtor em uma solicitação para criar instâncias, deve ser possível referenciar o objeto construtor em várias solicitações de criação de instância diferentes. Isso não seria possível com um manipulador normal retornado como um napi_value, conforme descrito na seção anterior. O tempo de vida de um manipulador normal é gerenciado por escopos e todos os escopos devem ser fechados antes do final de um método nativo.
A Node-API fornece métodos para criar referências persistentes a valores. Atualmente, a Node-API permite que referências sejam criadas apenas para um conjunto limitado de tipos de valor, incluindo objeto, externo, função e símbolo.
Cada referência tem uma contagem associada com um valor de 0 ou superior, que determina se a referência manterá o valor correspondente ativo. Referências com uma contagem de 0 não impedem que os valores sejam coletados. Os valores dos tipos objeto (objeto, função, externo) e símbolo estão se tornando referências 'fracas' e ainda podem ser acessados enquanto não são coletados. Qualquer contagem maior que 0 impedirá que os valores sejam coletados.
Os valores de símbolo têm diferentes sabores. O verdadeiro comportamento de referência fraca é suportado apenas por símbolos locais criados com a função napi_create_symbol ou as chamadas de construtor Symbol() do JavaScript. Símbolos registrados globalmente criados com a função node_api_symbol_for ou as chamadas de função Symbol.for() do JavaScript permanecem sempre referências fortes porque o coletor de lixo não os coleta. O mesmo acontece com símbolos bem conhecidos, como Symbol.iterator. Eles também nunca são coletados pelo coletor de lixo.
As referências podem ser criadas com uma contagem de referência inicial. A contagem pode ser modificada por meio de napi_reference_ref e napi_reference_unref. Se um objeto for coletado enquanto a contagem para uma referência for 0, todas as chamadas subsequentes para obter o objeto associado à referência napi_get_reference_value retornarão NULL para o napi_value retornado. Uma tentativa de chamar napi_reference_ref para uma referência cujo objeto foi coletado resulta em um erro.
As referências devem ser excluídas assim que não forem mais necessárias pelo addon. Quando uma referência é excluída, ela não impedirá mais que o objeto correspondente seja coletado. A falha ao excluir uma referência persistente resulta em um 'vazamento de memória', com a memória nativa para a referência persistente e o objeto correspondente no heap sendo retidos para sempre.
Pode haver várias referências persistentes criadas que se referem ao mesmo objeto, cada uma das quais manterá o objeto ativo ou não com base em sua contagem individual. Várias referências persistentes para o mesmo objeto podem resultar em manter inesperadamente a memória nativa ativa. As estruturas nativas para uma referência persistente devem ser mantidas ativas até que os finalizadores para o objeto referenciado sejam executados. Se uma nova referência persistente for criada para o mesmo objeto, os finalizadores para esse objeto não serão executados e a memória nativa apontada pela referência persistente anterior não será liberada. Isso pode ser evitado chamando napi_delete_reference além de napi_reference_unref quando possível.
Histórico de alterações:
- Experimental (
NAPI_EXPERIMENTALestá definido): Referências podem ser criadas para todos os tipos de valor. Os novos tipos de valor suportados não suportam a semântica de referência fraca e os valores desses tipos são liberados quando a contagem de referência se torna 0 e não podem mais ser acessados a partir da referência.
napi_create_reference
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] value: Onapi_valuepara o qual uma referência está sendo criada.[in] initial_refcount: Contagem de referência inicial para a nova referência.[out] result:napi_refapontando para a nova referência.
Retorna napi_ok se a API foi bem-sucedida.
Esta API cria uma nova referência com a contagem de referência especificada para o valor passado.
napi_delete_reference
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);[in] env: O ambiente sob o qual a API é invocada.[in] ref:napi_refa ser excluída.
Retorna napi_ok se a API foi bem-sucedida.
Esta API exclui a referência passada.
Esta API pode ser chamada mesmo se houver uma exceção JavaScript pendente.
napi_reference_ref
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
napi_ref ref,
uint32_t* result);[in] env: O ambiente sob o qual a API é invocada.[in] ref:napi_refpara o qual a contagem de referência será incrementada.[out] result: A nova contagem de referência.
Retorna napi_ok se a API foi bem-sucedida.
Esta API incrementa a contagem de referência para a referência passada e retorna a contagem de referência resultante.
napi_reference_unref
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
napi_ref ref,
uint32_t* result);[in] env: O ambiente sob o qual a API é invocada.[in] ref:napi_refpara o qual a contagem de referência será decrementada.[out] result: A nova contagem de referência.
Retorna napi_ok se a API foi bem-sucedida.
Esta API decrementa a contagem de referência para a referência passada e retorna a contagem de referência resultante.
napi_get_reference_value
Adicionado em: v8.0.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
napi_ref ref,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[in] ref: Onapi_refpara o qual o valor correspondente está sendo solicitado.[out] result: Onapi_valuereferenciado pelonapi_ref.
Retorna napi_ok se a API for bem-sucedida.
Se ainda for válido, esta API retorna o napi_value representando o valor JavaScript associado ao napi_ref. Caso contrário, o resultado será NULL.
Limpeza na saída do ambiente Node.js atual
Embora um processo Node.js normalmente libere todos os seus recursos ao sair, os incorporadores do Node.js ou o futuro suporte a Workers podem exigir que os addons registrem hooks de limpeza que serão executados quando o ambiente Node.js atual for encerrado.
A Node-API fornece funções para registrar e cancelar o registro de tais callbacks. Quando esses callbacks são executados, todos os recursos que estão sendo mantidos pelo addon devem ser liberados.
napi_add_env_cleanup_hook
Adicionado em: v10.2.0
Versão N-API: 3
NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
napi_cleanup_hook fun,
void* arg);Registra fun como uma função a ser executada com o parâmetro arg quando o ambiente Node.js atual for encerrado.
Uma função pode ser especificada várias vezes com valores arg diferentes. Nesse caso, ela também será chamada várias vezes. Fornecer os mesmos valores fun e arg várias vezes não é permitido e levará o processo a ser abortado.
Os hooks serão chamados em ordem inversa, ou seja, o mais recentemente adicionado será chamado primeiro.
A remoção deste hook pode ser feita usando napi_remove_env_cleanup_hook. Normalmente, isso acontece quando o recurso para o qual este hook foi adicionado já está sendo desmontado.
Para limpeza assíncrona, napi_add_async_cleanup_hook está disponível.
napi_remove_env_cleanup_hook
Adicionado em: v10.2.0
Versão N-API: 3
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
void (*fun)(void* arg),
void* arg);Cancela o registro de fun como uma função a ser executada com o parâmetro arg quando o ambiente Node.js atual for encerrado. Tanto o argumento quanto o valor da função precisam ser correspondências exatas.
A função deve ter sido originalmente registrada com napi_add_env_cleanup_hook, caso contrário, o processo será abortado.
napi_add_async_cleanup_hook
[Histórico]
| Versão | Alterações |
|---|---|
| v14.10.0, v12.19.0 | Assinatura alterada do callback hook. |
| v14.8.0, v12.19.0 | Adicionado em: v14.8.0, v12.19.0 |
Versão 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: O ambiente em que a API é invocada.[in] hook: O ponteiro de função para chamar no encerramento do ambiente.[in] arg: O ponteiro para passar parahookquando ele for chamado.[out] remove_handle: Handle opcional que se refere ao hook de limpeza assíncrona.
Registra hook, que é uma função do tipo napi_async_cleanup_hook, como uma função a ser executada com os parâmetros remove_handle e arg quando o ambiente Node.js atual for encerrado.
Ao contrário de napi_add_env_cleanup_hook, o hook pode ser assíncrono.
Caso contrário, o comportamento geralmente corresponde ao de napi_add_env_cleanup_hook.
Se remove_handle não for NULL, um valor opaco será armazenado nele que deve ser posteriormente passado para napi_remove_async_cleanup_hook, independentemente de o hook já ter sido invocado. Normalmente, isso acontece quando o recurso para o qual este hook foi adicionado está sendo encerrado de qualquer maneira.
napi_remove_async_cleanup_hook
[Histórico]
| Versão | Mudanças |
|---|---|
| v14.10.0, v12.19.0 | Removido o parâmetro env. |
| v14.8.0, v12.19.0 | Adicionado em: 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: O handle para um hook de limpeza assíncrono que foi criado comnapi_add_async_cleanup_hook.
Cancela o registro do hook de limpeza correspondente a remove_handle. Isso impedirá que o hook seja executado, a menos que já tenha começado a ser executado. Isso deve ser chamado em qualquer valor napi_async_cleanup_hook_handle obtido de napi_add_async_cleanup_hook.
Finalização na saída do ambiente Node.js
O ambiente Node.js pode ser encerrado em um momento arbitrário o mais rápido possível com a execução do JavaScript proibida, como a solicitação de worker.terminate(). Quando o ambiente está sendo encerrado, os callbacks napi_finalize registrados de objetos JavaScript, funções thread-safe e dados da instância do ambiente são invocados imediatamente e de forma independente.
A invocação de callbacks napi_finalize é agendada após os hooks de limpeza registrados manualmente. Para garantir uma ordem adequada de finalização do addon durante o desligamento do ambiente para evitar o uso após a liberação no callback napi_finalize, os addons devem registrar um hook de limpeza com napi_add_env_cleanup_hook e napi_add_async_cleanup_hook para liberar manualmente o recurso alocado em uma ordem adequada.
Registro de módulo
Os módulos Node-API são registrados de maneira semelhante a outros módulos, exceto que em vez de usar a macro NODE_MODULE, o seguinte é usado:
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)A próxima diferença é a assinatura para o método Init. Para um módulo Node-API, é o seguinte:
napi_value Init(napi_env env, napi_value exports);O valor de retorno de Init é tratado como o objeto exports para o módulo. O método Init recebe um objeto vazio através do parâmetro exports por conveniência. Se Init retornar NULL, o parâmetro passado como exports é exportado pelo módulo. Os módulos Node-API não podem modificar o objeto module, mas podem especificar qualquer coisa como a propriedade exports do módulo.
Para adicionar o método hello como uma função para que ele possa ser chamado como um método fornecido pelo 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;
}Para definir uma função a ser retornada por require() para o 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;
}Para definir uma classe para que novas instâncias possam ser criadas (frequentemente usado com Object wrap):
// OBSERVAÇÃO: exemplo parcial, nem todo o código referenciado está incluído
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;
}Você também pode usar a macro NAPI_MODULE_INIT, que atua como um atalho para NAPI_MODULE e definindo uma função 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;
}Os parâmetros env e exports são fornecidos ao corpo da macro NAPI_MODULE_INIT.
Todos os addons Node-API são context-aware, o que significa que eles podem ser carregados várias vezes. Há algumas considerações de design ao declarar tal módulo. A documentação sobre addons context-aware fornece mais detalhes.
As variáveis env e exports estarão disponíveis dentro do corpo da função após a invocação da macro.
Para obter mais detalhes sobre como definir propriedades em objetos, consulte a seção sobre Trabalhando com propriedades JavaScript.
Para obter mais detalhes sobre como construir módulos addon em geral, consulte a API existente.
Trabalhando com valores JavaScript
A Node-API expõe um conjunto de APIs para criar todos os tipos de valores JavaScript. Alguns desses tipos são documentados na Seção 6 da Especificação da Linguagem ECMAScript.
Fundamentalmente, essas APIs são usadas para fazer uma das seguintes ações:
Os valores da Node-API são representados pelo tipo napi_value. Qualquer chamada da Node-API que exija um valor JavaScript recebe um napi_value. Em alguns casos, a API verifica antecipadamente o tipo de napi_value. No entanto, para melhor desempenho, é melhor que o chamador se certifique de que o napi_value em questão seja do tipo JavaScript esperado pela API.
Tipos de enumeração
napi_key_collection_mode
Adicionado em: v13.7.0, v12.17.0, v10.20.0
Versão N-API: 6
typedef enum {
napi_key_include_prototypes,
napi_key_own_only
} napi_key_collection_mode;Descreve os enums de filtro Keys/Properties:
napi_key_collection_mode limita o intervalo de propriedades coletadas.
napi_key_own_only limita as propriedades coletadas apenas ao objeto fornecido. napi_key_include_prototypes incluirá todas as chaves da cadeia de protótipos dos objetos também.
napi_key_filter
Adicionado em: v13.7.0, v12.17.0, v10.20.0
Versão N-API: 6
typedef enum {
napi_key_all_properties = 0,
napi_key_writable = 1,
napi_key_enumerable = 1 << 1,
napi_key_configurable = 1 << 2,
napi_key_skip_strings = 1 << 3,
napi_key_skip_symbols = 1 << 4
} napi_key_filter;Bits de filtro de propriedade. Eles podem ser combinados com or para construir um filtro composto.
napi_key_conversion
Adicionado em: v13.7.0, v12.17.0, v10.20.0
Versão N-API: 6
typedef enum {
napi_key_keep_numbers,
napi_key_numbers_to_strings
} napi_key_conversion;napi_key_numbers_to_strings converterá índices inteiros em strings. napi_key_keep_numbers retornará números para índices inteiros.
napi_valuetype
typedef enum {
// Tipos ES6 (corresponde a typeof)
napi_undefined,
napi_null,
napi_boolean,
napi_number,
napi_string,
napi_symbol,
napi_object,
napi_function,
napi_external,
napi_bigint,
} napi_valuetype;Descreve o tipo de um napi_value. Isso geralmente corresponde aos tipos descritos na Seção 6.1 da Especificação da Linguagem ECMAScript. Além dos tipos nessa seção, napi_valuetype também pode representar Functions e Objects com dados externos.
Um valor JavaScript do tipo napi_external aparece em JavaScript como um objeto simples, de forma que nenhuma propriedade pode ser definida nele e nenhum protótipo.
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;Isso representa o tipo de dado escalar binário subjacente do TypedArray. Os elementos desse enum correspondem à Seção 22.2 da Especificação da Linguagem ECMAScript.
Funções de criação de objeto
napi_create_array
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_array(napi_env env, napi_value* result)[in] env: O ambiente no qual a chamada Node-API é invocada.[out] result: Umnapi_valuerepresentando umArrayJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna um valor Node-API correspondente a um tipo Array JavaScript. Os arrays JavaScript são descritos na Seção 22.1 da Especificação da Linguagem ECMAScript.
napi_create_array_with_length
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_array_with_length(napi_env env,
size_t length,
napi_value* result)[in] env: O ambiente no qual a API é invocada.[in] length: O comprimento inicial doArray.[out] result: Umnapi_valuerepresentando umArrayJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna um valor Node-API correspondente a um tipo Array JavaScript. A propriedade length do Array é definida como o parâmetro length passado. No entanto, não é garantido que o buffer subjacente seja pré-alocado pela VM quando o array é criado. Esse comportamento é deixado para a implementação da VM subjacente. Se o buffer deve ser um bloco contíguo de memória que pode ser lido e/ou gravado diretamente via C, considere usar napi_create_external_arraybuffer.
Os arrays JavaScript são descritos na Seção 22.1 da Especificação da Linguagem ECMAScript.
napi_create_arraybuffer
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_arraybuffer(napi_env env,
size_t byte_length,
void** data,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] length: O comprimento em bytes do buffer de array a ser criado.[out] data: Ponteiro para o buffer de bytes subjacente doArrayBuffer.datapode ser opcionalmente ignorado passandoNULL.[out] result: Umnapi_valuerepresentando umArrayBufferJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna um valor Node-API correspondente a um ArrayBuffer JavaScript. ArrayBuffers são usados para representar buffers de dados binários de comprimento fixo. Eles são normalmente usados como um buffer de suporte para objetos TypedArray. O ArrayBuffer alocado terá um buffer de bytes subjacente cujo tamanho é determinado pelo parâmetro length que é passado. O buffer subjacente é opcionalmente retornado ao chamador caso o chamador queira manipular diretamente o buffer. Este buffer só pode ser gravado diretamente a partir de código nativo. Para gravar neste buffer a partir de JavaScript, um array tipado ou objeto DataView precisaria ser criado.
Os objetos ArrayBuffer JavaScript são descritos na Seção 24.1 da Especificação da Linguagem ECMAScript.
napi_create_buffer
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_buffer(napi_env env,
size_t size,
void** data,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] size: Tamanho em bytes do buffer subjacente.[out] data: Ponteiro bruto para o buffer subjacente.datapode ser opcionalmente ignorado passandoNULL.[out] result: Umnapi_valuerepresentando umnode::Buffer.
Retorna napi_ok se a API for bem-sucedida.
Esta API aloca um objeto node::Buffer. Embora esta ainda seja uma estrutura de dados totalmente suportada, na maioria dos casos, usar um TypedArray será suficiente.
napi_create_buffer_copy
Adicionado em: v8.0.0
Versão 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: O ambiente no qual a API é invocada.[in] size: Tamanho em bytes do buffer de entrada (deve ser o mesmo tamanho do novo buffer).[in] data: Ponteiro bruto para o buffer subjacente do qual copiar.[out] result_data: Ponteiro para o novo buffer de dados subjacente doBuffer.result_datapode ser opcionalmente ignorado passandoNULL.[out] result: Umnapi_valuerepresentando umnode::Buffer.
Retorna napi_ok se a API for bem-sucedida.
Esta API aloca um objeto node::Buffer e o inicializa com dados copiados do buffer passado. Embora esta ainda seja uma estrutura de dados totalmente suportada, na maioria dos casos, usar um TypedArray será suficiente.
napi_create_date
Adicionado em: v11.11.0, v10.17.0
Versão N-API: 5
napi_status napi_create_date(napi_env env,
double time,
napi_value* result);[in] env: O ambiente no qual a API é invocada.[in] time: Valor de tempo ECMAScript em milissegundos desde 01 de janeiro de 1970 UTC.[out] result: Umnapi_valuerepresentando umDateJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API não observa segundos bissextos; eles são ignorados, pois o ECMAScript se alinha com a especificação de tempo POSIX.
Esta API aloca um objeto Date JavaScript.
Objetos Date JavaScript são descritos na Seção 20.3 da Especificação da Linguagem ECMAScript.
napi_create_external
Adicionado em: v8.0.0
Versão 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: O ambiente no qual a API é invocada.[in] data: Ponteiro bruto para os dados externos.[in] finalize_cb: Callback opcional para chamar quando o valor externo está sendo coletado.napi_finalizefornece mais detalhes.[in] finalize_hint: Dica opcional para passar para o callback de finalização durante a coleta.[out] result: Umnapi_valuerepresentando um valor externo.
Retorna napi_ok se a API for bem-sucedida.
Esta API aloca um valor JavaScript com dados externos anexados a ele. Isso é usado para passar dados externos através do código JavaScript, para que possam ser recuperados posteriormente pelo código nativo usando napi_get_value_external.
A API adiciona um callback napi_finalize que será chamado quando o objeto JavaScript recém-criado tiver sido coletado pelo coletor de lixo.
O valor criado não é um objeto e, portanto, não oferece suporte a propriedades adicionais. É considerado um tipo de valor distinto: chamar napi_typeof() com um valor externo produz napi_external.
napi_create_external_arraybuffer
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] external_data: Ponteiro para o buffer de bytes subjacente doArrayBuffer.[in] byte_length: O comprimento em bytes do buffer subjacente.[in] finalize_cb: Callback opcional para chamar quando oArrayBufferestá sendo coletado.napi_finalizefornece mais detalhes.[in] finalize_hint: Dica opcional para passar para o callback de finalização durante a coleta.[out] result: Umnapi_valuerepresentando umArrayBufferJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Alguns runtimes diferentes do Node.js abandonaram o suporte a buffers externos. Em runtimes diferentes do Node.js, este método pode retornar napi_no_external_buffers_allowed para indicar que buffers externos não são suportados. Um desses runtimes é o Electron, conforme descrito nesta questão electron/issues/35801.
Para manter a mais ampla compatibilidade com todos os runtimes, você pode definir NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED em seu addon antes dos includes para os headers da node-api. Isso ocultará as 2 funções que criam buffers externos. Isso garantirá que ocorra um erro de compilação se você usar acidentalmente um desses métodos.
Esta API retorna um valor Node-API correspondente a um ArrayBuffer JavaScript. O buffer de bytes subjacente do ArrayBuffer é alocado e gerenciado externamente. O chamador deve garantir que o buffer de bytes permaneça válido até que o callback de finalização seja chamado.
A API adiciona um callback napi_finalize que será chamado quando o objeto JavaScript recém-criado for coletado pelo garbage collector.
ArrayBuffers JavaScript são descritos na Seção 24.1 da Especificação da Linguagem ECMAScript.
napi_create_external_buffer
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] length: Tamanho em bytes do buffer de entrada (deve ser o mesmo tamanho do novo buffer).[in] data: Ponteiro bruto para o buffer subjacente a ser exposto ao JavaScript.[in] finalize_cb: Callback opcional a ser chamado quando oArrayBufferestiver sendo coletado.napi_finalizefornece mais detalhes.[in] finalize_hint: Dica opcional para passar para o callback de finalização durante a coleta.[out] result: Umnapi_valuerepresentando umnode::Buffer.
Retorna napi_ok se a API for bem-sucedida.
Alguns runtimes diferentes do Node.js removeram o suporte para buffers externos. Em runtimes diferentes do Node.js, este método pode retornar napi_no_external_buffers_allowed para indicar que buffers externos não são suportados. Um desses runtimes é o Electron, conforme descrito neste problema electron/issues/35801.
Para manter a mais ampla compatibilidade com todos os runtimes, você pode definir NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED em seu complemento antes dos includes para os cabeçalhos da node-api. Isso ocultará as 2 funções que criam buffers externos. Isso garantirá que ocorra um erro de compilação se você usar acidentalmente um desses métodos.
Esta API aloca um objeto node::Buffer e o inicializa com dados apoiados pelo buffer passado. Embora esta ainda seja uma estrutura de dados totalmente suportada, na maioria dos casos usar um TypedArray será suficiente.
A API adiciona um callback napi_finalize que será chamado quando o objeto JavaScript recém-criado for coletado pelo coletor de lixo.
Para Node.js >=4, Buffers são Uint8Arrays.
napi_create_object
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_object(napi_env env, napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[out] result: Umnapi_valuerepresentando umObjectJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Essa API aloca um Object JavaScript padrão. É o equivalente a fazer new Object() em JavaScript.
O tipo Object JavaScript é descrito na Seção 6.1.7 da Especificação da Linguagem ECMAScript.
napi_create_symbol
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_symbol(napi_env env,
napi_value description,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] description:napi_valueopcional que se refere a umastringJavaScript a ser definida como a descrição para o símbolo.[out] result: Umnapi_valuerepresentando umsymbolJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API cria um valor symbol JavaScript a partir de uma string C codificada em UTF8.
O tipo symbol JavaScript é descrito na Seção 19.4 da Especificação da Linguagem ECMAScript.
node_api_symbol_for
Adicionado em: v17.5.0, v16.15.0
Versão N-API: 9
napi_status node_api_symbol_for(napi_env env,
const char* utf8description,
size_t length,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] utf8description: String C UTF-8 representando o texto a ser usado como a descrição para o símbolo.[in] length: O comprimento da string de descrição em bytes ouNAPI_AUTO_LENGTHse for terminado em nulo.[out] result: Umnapi_valuerepresentando umsymbolJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API pesquisa no registro global um símbolo existente com a descrição fornecida. Se o símbolo já existir, ele será retornado, caso contrário, um novo símbolo será criado no registro.
O tipo symbol JavaScript é descrito na Seção 19.4 da Especificação da Linguagem ECMAScript.
napi_create_typedarray
Adicionado em: v8.0.0
Versão 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: O ambiente em que a API é invocada.[in] type: Tipo de dados escalar dos elementos dentro doTypedArray.[in] length: Número de elementos noTypedArray.[in] arraybuffer:ArrayBuffersubjacente ao array tipado.[in] byte_offset: O deslocamento de byte dentro doArrayBuffera partir do qual começar a projetar oTypedArray.[out] result: Umnapi_valuerepresentando umTypedArrayJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API cria um objeto TypedArray JavaScript sobre um ArrayBuffer existente. Os objetos TypedArray fornecem uma visualização semelhante a um array sobre um buffer de dados subjacente onde cada elemento tem o mesmo tipo de dados escalar binário subjacente.
É necessário que (length * size_of_element) + byte_offset seja <= o tamanho em bytes do array passado. Caso contrário, uma exceção RangeError é lançada.
Os objetos TypedArray JavaScript são descritos na Seção 22.2 da Especificação da Linguagem ECMAScript.
node_api_create_buffer_from_arraybuffer
Adicionado em: v23.0.0
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
napi_value arraybuffer,
size_t byte_offset,
size_t byte_length,
napi_value* result)[in] env: O ambiente em que a API é invocada.[in] arraybuffer: OArrayBufferdo qual o buffer será criado.[in] byte_offset: O deslocamento de byte dentro doArrayBuffera partir do qual começar a criar o buffer.[in] byte_length: O comprimento em bytes do buffer a ser criado a partir doArrayBuffer.[out] result: Umnapi_valuerepresentando o objetoBufferJavaScript criado.
Retorna napi_ok se a API for bem-sucedida.
Esta API cria um objeto Buffer JavaScript a partir de um ArrayBuffer existente. O objeto Buffer é uma classe específica do Node.js que fornece uma maneira de trabalhar com dados binários diretamente em JavaScript.
O intervalo de bytes [byte_offset, byte_offset + byte_length) deve estar dentro dos limites do ArrayBuffer. Se byte_offset + byte_length exceder o tamanho do ArrayBuffer, uma exceção RangeError é lançada.
napi_create_dataview
Adicionado em: v8.3.0
Versão da 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: O ambiente sob o qual a API é invocada.[in] length: Número de elementos noDataView.[in] arraybuffer:ArrayBuffersubjacente aoDataView.[in] byte_offset: O deslocamento de byte dentro doArrayBuffera partir do qual começar a projetar oDataView.[out] result: Umnapi_valuerepresentando umDataViewJavaScript.
Retorna napi_ok se a API foi bem-sucedida.
Esta API cria um objeto DataView JavaScript sobre um ArrayBuffer existente. Os objetos DataView fornecem uma visualização semelhante a um array sobre um buffer de dados subjacente, mas um que permite itens de tamanho e tipo diferentes no ArrayBuffer.
É necessário que byte_length + byte_offset seja menor ou igual ao tamanho em bytes do array passado. Caso contrário, uma exceção RangeError é gerada.
Os objetos DataView JavaScript são descritos na Seção 24.3 da Especificação da Linguagem ECMAScript.
Funções para converter de tipos C para Node-API
napi_create_int32
Adicionado em: v8.4.0
Versão da N-API: 1
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: Valor inteiro a ser representado em JavaScript.[out] result: Umnapi_valuerepresentando umnumberJavaScript.
Retorna napi_ok se a API foi bem-sucedida.
Esta API é usada para converter do tipo C int32_t para o tipo JavaScript number.
O tipo number JavaScript é descrito na Seção 6.1.6 da Especificação da Linguagem ECMAScript.
napi_create_uint32
Adicionado em: v8.4.0
Versão da N-API: 1
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)[in] env: O ambiente em que a API é invocada.[in] value: Valor inteiro não assinado a ser representado em JavaScript.[out] result: Umnapi_valuerepresentando umnumberem JavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API é usada para converter do tipo C uint32_t para o tipo JavaScript number.
O tipo JavaScript number é descrito na Seção 6.1.6 da Especificação da Linguagem ECMAScript.
napi_create_int64
Adicionado em: v8.4.0
Versão da N-API: 1
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)[in] env: O ambiente em que a API é invocada.[in] value: Valor inteiro a ser representado em JavaScript.[out] result: Umnapi_valuerepresentando umnumberem JavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API é usada para converter do tipo C int64_t para o tipo JavaScript number.
O tipo JavaScript number é descrito na Seção 6.1.6 da Especificação da Linguagem ECMAScript. Observe que o intervalo completo de int64_t não pode ser representado com precisão total em JavaScript. Valores inteiros fora do intervalo de Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) perderão precisão.
napi_create_double
Adicionado em: v8.4.0
Versão da N-API: 1
napi_status napi_create_double(napi_env env, double value, napi_value* result)[in] env: O ambiente em que a API é invocada.[in] value: Valor de precisão dupla a ser representado em JavaScript.[out] result: Umnapi_valuerepresentando umnumberem JavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API é usada para converter do tipo C double para o tipo JavaScript number.
O tipo JavaScript number é descrito na Seção 6.1.6 da Especificação da Linguagem ECMAScript.
napi_create_bigint_int64
Adicionado em: v10.7.0
Versão N-API: 6
napi_status napi_create_bigint_int64(napi_env env,
int64_t value,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[in] value: Valor inteiro a ser representado em JavaScript.[out] result: Umnapi_valuerepresentando umBigIntdo JavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API converte o tipo C int64_t para o tipo JavaScript BigInt.
napi_create_bigint_uint64
Adicionado em: v10.7.0
Versão N-API: 6
napi_status napi_create_bigint_uint64(napi_env env,
uint64_t value,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[in] value: Valor inteiro não assinado a ser representado em JavaScript.[out] result: Umnapi_valuerepresentando umBigIntdo JavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API converte o tipo C uint64_t para o tipo JavaScript BigInt.
napi_create_bigint_words
Adicionado em: v10.7.0
Versão 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: O ambiente sob o qual a API é invocada.[in] sign_bit: Determina se oBigIntresultante será positivo ou negativo.[in] word_count: O comprimento da arraywords.[in] words: Uma array de palavras de 64 bits little-endianuint64_t.[out] result: Umnapi_valuerepresentando umBigIntdo JavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API converte uma array de palavras não assinadas de 64 bits em um único valor BigInt.
O BigInt resultante é calculado como: (–1) (words[0] × (2) + words[1] × (2) + …)
napi_create_string_latin1
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[in] str: Buffer de caracteres representando uma string codificada em ISO-8859-1.[in] length: O comprimento da string em bytes, ouNAPI_AUTO_LENGTHse for terminada em nulo.[out] result: Umnapi_valuerepresentando umastringJavaScript.
Retorna napi_ok se a API foi bem-sucedida.
Esta API cria um valor string JavaScript a partir de uma string C codificada em ISO-8859-1. A string nativa é copiada.
O tipo string JavaScript é descrito na Seção 6.1.4 da Especificação da Linguagem ECMAScript.
node_api_create_external_string_latin1
Adicionado em: v20.4.0, v18.18.0
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
napi_status
node_api_create_external_string_latin1(napi_env env,
char* str,
size_t length,
napi_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);[in] env: O ambiente sob o qual a API é invocada.[in] str: Buffer de caracteres representando uma string codificada em ISO-8859-1.[in] length: O comprimento da string em bytes, ouNAPI_AUTO_LENGTHse for terminada em nulo.[in] finalize_callback: A função a ser chamada quando a string está sendo coletada. A função será chamada com os seguintes parâmetros:[in] env: O ambiente no qual o complemento está sendo executado. Este valor pode ser nulo se a string estiver sendo coletada como parte do encerramento do worker ou da instância principal do Node.js.[in] data: Este é o valorstrcomo um ponteirovoid*.[in] finalize_hint: Este é o valorfinalize_hintque foi dado à API.napi_finalizefornece mais detalhes. Este parâmetro é opcional. Passar um valor nulo significa que o complemento não precisa ser notificado quando a string JavaScript correspondente é coletada.
[in] finalize_hint: Dica opcional para passar para o retorno de chamada de finalização durante a coleta.[out] result: Umnapi_valuerepresentando umastringJavaScript.[out] copied: Indica se a string foi copiada. Se foi, o finalizador já terá sido invocado para destruirstr.
Retorna napi_ok se a API foi bem-sucedida.
Esta API cria um valor string JavaScript a partir de uma string C codificada em ISO-8859-1. A string nativa pode não ser copiada e, portanto, deve existir durante todo o ciclo de vida do valor JavaScript.
O tipo string JavaScript é descrito na Seção 6.1.4 da Especificação da Linguagem ECMAScript.
napi_create_string_utf16
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result)[in] env: O ambiente no qual a API é invocada.[in] str: Buffer de caracteres representando uma string codificada em UTF16-LE.[in] length: O comprimento da string em unidades de código de dois bytes, ouNAPI_AUTO_LENGTHse for terminada em nulo.[out] result: Umnapi_valuerepresentando umastringJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API cria um valor string JavaScript a partir de uma string C codificada em UTF16-LE. A string nativa é copiada.
O tipo string JavaScript é descrito na Seção 6.1.4 da Especificação da Linguagem ECMAScript.
node_api_create_external_string_utf16
Adicionado em: v20.4.0, v18.18.0
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
napi_status
node_api_create_external_string_utf16(napi_env env,
char16_t* str,
size_t length,
napi_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);[in] env: O ambiente no qual a API é invocada.[in] str: Buffer de caracteres representando uma string codificada em UTF16-LE.[in] length: O comprimento da string em unidades de código de dois bytes, ouNAPI_AUTO_LENGTHse for terminada em nulo.[in] finalize_callback: A função a ser chamada quando a string estiver sendo coletada. A função será chamada com os seguintes parâmetros:[in] env: O ambiente no qual o complemento está sendo executado. Este valor pode ser nulo se a string estiver sendo coletada como parte do término do trabalhador ou da instância principal do Node.js.[in] data: Este é o valorstrcomo um ponteirovoid*.[in] finalize_hint: Este é o valorfinalize_hintque foi fornecido à API.napi_finalizefornece mais detalhes. Este parâmetro é opcional. Passar um valor nulo significa que o complemento não precisa ser notificado quando a string JavaScript correspondente é coletada.
[in] finalize_hint: Dica opcional para passar para o callback de finalização durante a coleta.[out] result: Umnapi_valuerepresentando umastringJavaScript.[out] copied: Indica se a string foi copiada. Se foi, o finalizador já terá sido invocado para destruirstr.
Retorna napi_ok se a API for bem-sucedida.
Esta API cria um valor string JavaScript a partir de uma string C codificada em UTF16-LE. A string nativa pode não ser copiada e, portanto, deve existir durante todo o ciclo de vida do valor JavaScript.
O tipo string JavaScript é descrito na Seção 6.1.4 da Especificação da Linguagem ECMAScript.
napi_create_string_utf8
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_create_string_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] str: Buffer de caracteres representando uma string codificada em UTF8.[in] length: O comprimento da string em bytes, ouNAPI_AUTO_LENGTHse ela for terminada em nulo.[out] result: Umnapi_valuerepresentando umastringJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Essa API cria um valor string JavaScript a partir de uma string C codificada em UTF8. A string nativa é copiada.
O tipo string JavaScript é descrito na Seção 6.1.4 da Especificação da Linguagem ECMAScript.
Funções para criar chaves de propriedade otimizadas
Muitos mecanismos JavaScript, incluindo o V8, usam strings internalizadas como chaves para definir e obter valores de propriedade. Eles geralmente usam uma tabela hash para criar e procurar essas strings. Embora adicione algum custo por criação de chave, isso melhora o desempenho depois, permitindo a comparação de ponteiros de string em vez de strings inteiras.
Se uma nova string JavaScript for destinada a ser usada como chave de propriedade, então para alguns mecanismos JavaScript será mais eficiente usar as funções nesta seção. Caso contrário, use as funções napi_create_string_utf8 ou node_api_create_external_string_utf8, pois pode haver uma sobrecarga adicional na criação/armazenamento de strings com os métodos de criação de chave de propriedade.
node_api_create_property_key_latin1
Adicionado em: v22.9.0, v20.18.0
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[in] str: Buffer de caracteres representando uma string codificada em ISO-8859-1.[in] length: O comprimento da string em bytes, ouNAPI_AUTO_LENGTHse ela for terminada em nulo.[out] result: Umnapi_valuerepresentando umastringJavaScript otimizada para ser usada como chave de propriedade para objetos.
Retorna napi_ok se a API for bem-sucedida.
Essa API cria um valor string JavaScript otimizado a partir de uma string C codificada em ISO-8859-1 para ser usado como chave de propriedade para objetos. A string nativa é copiada. Em contraste com napi_create_string_latin1, chamadas subsequentes a esta função com o mesmo ponteiro str podem se beneficiar de um aumento na velocidade na criação do napi_value solicitado, dependendo do mecanismo.
O tipo string JavaScript é descrito na Seção 6.1.4 da Especificação da Linguagem ECMAScript.
node_api_create_property_key_utf16
Adicionado em: v21.7.0, v20.12.0
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result);[in] env: O ambiente no qual a API é invocada.[in] str: Buffer de caracteres representando uma string codificada em UTF16-LE.[in] length: O comprimento da string em unidades de código de dois bytes, ouNAPI_AUTO_LENGTHse for terminada em nulo.[out] result: Umnapi_valuerepresentando umastringJavaScript otimizada a ser usada como chave de propriedade para objetos.
Retorna napi_ok se a API foi bem-sucedida.
Esta API cria um valor string JavaScript otimizado a partir de uma string C codificada em UTF16-LE para ser usado como chave de propriedade para objetos. A string nativa é copiada.
O tipo string do JavaScript é descrito na Seção 6.1.4 da Especificação da Linguagem ECMAScript.
node_api_create_property_key_utf8
Adicionado em: v22.9.0, v20.18.0
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: O ambiente no qual a API é invocada.[in] str: Buffer de caracteres representando uma string codificada em UTF8.[in] length: O comprimento da string em unidades de código de dois bytes, ouNAPI_AUTO_LENGTHse for terminada em nulo.[out] result: Umnapi_valuerepresentando umastringJavaScript otimizada a ser usada como chave de propriedade para objetos.
Retorna napi_ok se a API foi bem-sucedida.
Esta API cria um valor string JavaScript otimizado a partir de uma string C codificada em UTF8 para ser usado como chave de propriedade para objetos. A string nativa é copiada.
O tipo string do JavaScript é descrito na Seção 6.1.4 da Especificação da Linguagem ECMAScript.
Funções para converter de Node-API para tipos C
napi_get_array_length
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_array_length(napi_env env,
napi_value value,
uint32_t* result)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando oArrayJavaScript cuja comprimento está sendo consultada.[out] result:uint32representando o comprimento do array.
Retorna napi_ok se a API foi bem-sucedida.
Esta API retorna o comprimento de um array.
O comprimento do Array é descrito na Seção 22.1.4.1 da Especificação da Linguagem ECMAScript.
napi_get_arraybuffer_info
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_arraybuffer_info(napi_env env,
napi_value arraybuffer,
void** data,
size_t* byte_length)[in] env: O ambiente sob o qual a API é invocada.[in] arraybuffer:napi_valuerepresentando oArrayBuffersendo consultado.[out] data: O buffer de dados subjacente doArrayBuffer. Se byte_length for0, este pode serNULLou qualquer outro valor de ponteiro.[out] byte_length: Comprimento em bytes do buffer de dados subjacente.
Retorna napi_ok se a API foi bem-sucedida.
Esta API é usada para recuperar o buffer de dados subjacente de um ArrayBuffer e seu comprimento.
AVISO: Tenha cuidado ao usar esta API. O tempo de vida do buffer de dados subjacente é gerenciado pelo ArrayBuffer mesmo depois de ser retornado. Uma possível maneira segura de usar esta API é em conjunto com napi_create_reference, que pode ser usada para garantir o controle sobre o tempo de vida do ArrayBuffer. Também é seguro usar o buffer de dados retornado dentro do mesmo callback, desde que não haja chamadas para outras APIs que possam acionar um GC.
napi_get_buffer_info
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_buffer_info(napi_env env,
napi_value value,
void** data,
size_t* length)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando onode::BufferouUint8Arrayque está sendo consultado.[out] data: O buffer de dados subjacente donode::BufferouUint8Array. Se o comprimento for0, isso pode serNULLou qualquer outro valor de ponteiro.[out] length: Comprimento em bytes do buffer de dados subjacente.
Retorna napi_ok se a API for bem-sucedida.
Este método retorna os mesmos data e byte_length que napi_get_typedarray_info. E napi_get_typedarray_info também aceita um node::Buffer (um Uint8Array) como valor.
Esta API é usada para recuperar o buffer de dados subjacente de um node::Buffer e seu comprimento.
Aviso: Use cautela ao usar esta API, pois o tempo de vida do buffer de dados subjacente não é garantido se for gerenciado pela VM.
napi_get_prototype
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_prototype(napi_env env,
napi_value object,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] object:napi_valuerepresentando oObjectJavaScript cujo protótipo deve ser retornado. Isso retorna o equivalente aObject.getPrototypeOf(que não é o mesmo que a propriedadeprototypeda função).[out] result:napi_valuerepresentando o protótipo do objeto fornecido.
Retorna napi_ok se a API for bem-sucedida.
napi_get_typedarray_info
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] typedarray:napi_valuerepresentando oTypedArraycujas propriedades devem ser consultadas.[out] type: Tipo de dados escalar dos elementos dentro doTypedArray.[out] length: O número de elementos noTypedArray.[out] data: O buffer de dados subjacente aoTypedArrayajustado pelo valorbyte_offsetpara que ele aponte para o primeiro elemento noTypedArray. Se o comprimento do array for0, isso pode serNULLou qualquer outro valor de ponteiro.[out] arraybuffer: OArrayBuffersubjacente aoTypedArray.[out] byte_offset: O deslocamento de byte dentro do array nativo subjacente no qual o primeiro elemento dos arrays está localizado. O valor para o parâmetro data já foi ajustado para que os dados apontem para o primeiro elemento no array. Portanto, o primeiro byte do array nativo estaria emdata - byte_offset.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna várias propriedades de um array tipado.
Qualquer um dos parâmetros de saída pode ser NULL se essa propriedade não for necessária.
Aviso: Use cautela ao usar esta API, pois o buffer de dados subjacente é gerenciado pela VM.
napi_get_dataview_info
Adicionado em: v8.3.0
Versão 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: O ambiente sob o qual a API é invocada.[in] dataview:napi_valuerepresentando oDataViewcujas propriedades devem ser consultadas.[out] byte_length: Número de bytes noDataView.[out] data: O buffer de dados subjacente aoDataView. Se byte_length for0, isso pode serNULLou qualquer outro valor de ponteiro.[out] arraybuffer:ArrayBuffersubjacente aoDataView.[out] byte_offset: O deslocamento de bytes dentro do buffer de dados a partir do qual começar a projetar oDataView.
Retorna napi_ok se a API for bem-sucedida.
Qualquer um dos parâmetros de saída pode ser NULL se essa propriedade não for necessária.
Esta API retorna várias propriedades de um DataView.
napi_get_date_value
Adicionado em: v11.11.0, v10.17.0
Versão N-API: 5
napi_status napi_get_date_value(napi_env env,
napi_value value,
double* result)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando umDateJavaScript.[out] result: Valor de tempo como umdoublerepresentado como milissegundos desde a meia-noite no início de 01 de janeiro de 1970 UTC.
Esta API não observa segundos bissextos; eles são ignorados, pois o ECMAScript está alinhado com a especificação de tempo POSIX.
Retorna napi_ok se a API for bem-sucedida. Se um napi_value que não seja de data for passado, ele retorna napi_date_expected.
Esta API retorna o primitivo C double do valor de tempo para o Date JavaScript fornecido.
napi_get_value_bool
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentandoBooleanJavaScript.[out] result: Primitivo booleano C equivalente aoBooleanJavaScript fornecido.
Retorna napi_ok se a API for bem-sucedida. Se um napi_value não booleano for passado, ele retorna napi_boolean_expected.
Esta API retorna o primitivo booleano C equivalente ao Boolean JavaScript fornecido.
napi_get_value_double
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_value_double(napi_env env,
napi_value value,
double* result)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando onumberdo JavaScript.[out] result: Primitivo C double equivalente aonumberdo JavaScript fornecido.
Retorna napi_ok se a API for bem-sucedida. Se um napi_value que não seja um número for passado, retorna napi_number_expected.
Esta API retorna o primitivo C double equivalente ao number do JavaScript fornecido.
napi_get_value_bigint_int64
Adicionado em: v10.7.0
Versão N-API: 6
napi_status napi_get_value_bigint_int64(napi_env env,
napi_value value,
int64_t* result,
bool* lossless);[in] env: O ambiente sob o qual a API é invocada[in] value:napi_valuerepresentando oBigIntdo JavaScript.[out] result: Primitivo Cint64_tequivalente aoBigIntdo JavaScript fornecido.[out] lossless: Indica se o valorBigIntfoi convertido sem perdas.
Retorna napi_ok se a API for bem-sucedida. Se um valor que não seja BigInt for passado, retorna napi_bigint_expected.
Esta API retorna o primitivo C int64_t equivalente ao BigInt do JavaScript fornecido. Se necessário, ele truncará o valor, definindo lossless como false.
napi_get_value_bigint_uint64
Adicionado em: v10.7.0
Versão N-API: 6
napi_status napi_get_value_bigint_uint64(napi_env env,
napi_value value,
uint64_t* result,
bool* lossless);[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando oBigIntdo JavaScript.[out] result: Primitivo Cuint64_tequivalente aoBigIntdo JavaScript fornecido.[out] lossless: Indica se o valorBigIntfoi convertido sem perdas.
Retorna napi_ok se a API for bem-sucedida. Se um valor que não seja BigInt for passado, retorna napi_bigint_expected.
Esta API retorna o primitivo C uint64_t equivalente ao BigInt do JavaScript fornecido. Se necessário, ele truncará o valor, definindo lossless como false.
napi_get_value_bigint_words
Adicionado em: v10.7.0
Versão 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: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando umBigIntJavaScript.[out] sign_bit: Inteiro representando se oBigIntJavaScript é positivo ou negativo.[in/out] word_count: Deve ser inicializado com o tamanho do arraywords. Após o retorno, ele será definido com o número real de palavras que seriam necessárias para armazenar esteBigInt.[out] words: Ponteiro para um array de palavras de 64 bits pré-alocado.
Retorna napi_ok se a API foi bem-sucedida.
Esta API converte um único valor BigInt em um bit de sinal, array little-endian de 64 bits e o número de elementos no array. sign_bit e words podem ser definidos como NULL, para obter apenas word_count.
napi_get_value_external
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_value_external(napi_env env,
napi_value value,
void** result)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando um valor externo JavaScript.[out] result: Ponteiro para os dados envolvidos pelo valor externo JavaScript.
Retorna napi_ok se a API foi bem-sucedida. Se um napi_value não externo for passado, ele retorna napi_invalid_arg.
Esta API recupera o ponteiro de dados externo que foi passado anteriormente para napi_create_external().
napi_get_value_int32
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_value_int32(napi_env env,
napi_value value,
int32_t* result)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando umnumberJavaScript.[out] result: Primitivo Cint32equivalente aonumberJavaScript fornecido.
Retorna napi_ok se a API foi bem-sucedida. Se um napi_value não número for passado, napi_number_expected.
Esta API retorna o primitivo C int32 equivalente ao number JavaScript fornecido.
Se o número exceder o intervalo do inteiro de 32 bits, o resultado será truncado para o equivalente aos 32 bits inferiores. Isso pode fazer com que um grande número positivo se torne um número negativo se o valor for > 2 - 1.
Valores numéricos não finitos (NaN, +Infinity ou -Infinity) definem o resultado como zero.
napi_get_value_int64
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_value_int64(napi_env env,
napi_value value,
int64_t* result)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando umnumberJavaScript.[out] result: Primitivo Cint64equivalente aonumberJavaScript fornecido.
Retorna napi_ok se a API for bem-sucedida. Se um napi_value que não seja um número for passado, ele retorna napi_number_expected.
Esta API retorna o primitivo C int64 equivalente ao number JavaScript fornecido.
Valores number fora do intervalo de Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) perderão precisão.
Valores numéricos não finitos (NaN, +Infinity ou -Infinity) definem o resultado como zero.
napi_get_value_string_latin1
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando uma string JavaScript.[in] buf: Buffer para escrever a string codificada em ISO-8859-1. SeNULLfor passado, o comprimento da string em bytes e excluindo o terminador nulo será retornado emresult.[in] bufsize: Tamanho do buffer de destino. Quando este valor é insuficiente, a string retornada é truncada e terminada em nulo.[out] result: Número de bytes copiados para o buffer, excluindo o terminador nulo.
Retorna napi_ok se a API for bem-sucedida. Se um napi_value que não seja string for passado, ele retorna napi_string_expected.
Esta API retorna a string codificada em ISO-8859-1 correspondente ao valor passado.
napi_get_value_string_utf8
Adicionado em: v8.0.0
Versão 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: O ambiente no qual a API é invocada.[in] value:napi_valuerepresentando uma string JavaScript.[in] buf: Buffer para escrever a string codificada em UTF8. SeNULLfor passado, o comprimento da string em bytes e excluindo o terminador nulo é retornado emresult.[in] bufsize: Tamanho do buffer de destino. Quando este valor é insuficiente, a string retornada é truncada e terminada com nulo.[out] result: Número de bytes copiados para o buffer, excluindo o terminador nulo.
Retorna napi_ok se a API for bem-sucedida. Se um napi_value não string for passado, ele retorna napi_string_expected.
Esta API retorna a string codificada em UTF8 correspondente ao valor passado.
napi_get_value_string_utf16
Adicionado em: v8.0.0
Versão 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: O ambiente no qual a API é invocada.[in] value:napi_valuerepresentando uma string JavaScript.[in] buf: Buffer para escrever a string codificada em UTF16-LE. SeNULLfor passado, o comprimento da string em unidades de código de 2 bytes e excluindo o terminador nulo é retornado.[in] bufsize: Tamanho do buffer de destino. Quando este valor é insuficiente, a string retornada é truncada e terminada com nulo.[out] result: Número de unidades de código de 2 bytes copiadas para o buffer, excluindo o terminador nulo.
Retorna napi_ok se a API for bem-sucedida. Se um napi_value não string for passado, ele retorna napi_string_expected.
Esta API retorna a string codificada em UTF16 correspondente ao valor passado.
napi_get_value_uint32
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_value_uint32(napi_env env,
napi_value value,
uint32_t* result)[in] env: O ambiente sob o qual a API é invocada.[in] value:napi_valuerepresentando umnumberJavaScript.[out] result: Primitivo C equivalente aonapi_valuefornecido como umuint32_t.
Retorna napi_ok se a API for bem-sucedida. Se um napi_value não numérico for passado, ele retornará napi_number_expected.
Esta API retorna o primitivo C equivalente ao napi_value fornecido como um uint32_t.
Funções para obter instâncias globais
napi_get_boolean
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor do booleano a ser recuperado.[out] result:napi_valuerepresentando o singletonBooleanJavaScript a ser recuperado.
Retorna napi_ok se a API for bem-sucedida.
Esta API é usada para retornar o objeto singleton JavaScript que é usado para representar o valor booleano fornecido.
napi_get_global
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_global(napi_env env, napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[out] result:napi_valuerepresentando o objetoglobalJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna o objeto global.
napi_get_null
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_null(napi_env env, napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[out] result:napi_valuerepresentando o objetonullJavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna o objeto null.
napi_get_undefined
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_undefined(napi_env env, napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[out] result:napi_valuerepresentando o valor Indefinido do JavaScript.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna o objeto Indefinido.
Trabalhando com valores JavaScript e operações abstratas
A Node-API expõe um conjunto de APIs para realizar algumas operações abstratas em valores JavaScript. Algumas dessas operações estão documentadas na Seção 7 da Especificação da Linguagem ECMAScript.
Essas APIs oferecem suporte para fazer uma das seguintes ações:
napi_coerce_to_bool
Adicionado em: v8.0.0
Versão da N-API: 1
napi_status napi_coerce_to_bool(napi_env env,
napi_value value,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser convertido.[out] result:napi_valuerepresentando oBooleanJavaScript convertido.
Retorna napi_ok se a API for bem-sucedida.
Esta API implementa a operação abstrata ToBoolean() conforme definido na Seção 7.1.2 da Especificação da Linguagem ECMAScript.
napi_coerce_to_number
Adicionado em: v8.0.0
Versão da N-API: 1
napi_status napi_coerce_to_number(napi_env env,
napi_value value,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser convertido.[out] result:napi_valuerepresentando onumberJavaScript convertido.
Retorna napi_ok se a API for bem-sucedida.
Esta API implementa a operação abstrata ToNumber() conforme definido na Seção 7.1.3 da Especificação da Linguagem ECMAScript. Essa função pode executar código JS se o valor passado for um objeto.
napi_coerce_to_object
Adicionado em: v8.0.0
Versão da N-API: 1
napi_status napi_coerce_to_object(napi_env env,
napi_value value,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser convertido.[out] result:napi_valuerepresentando oObjectJavaScript convertido.
Retorna napi_ok se a API for bem-sucedida.
Esta API implementa a operação abstrata ToObject() conforme definido na Seção 7.1.13 da Especificação da Linguagem ECMAScript.
napi_coerce_to_string
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_coerce_to_string(napi_env env,
napi_value value,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser forçado.[out] result:napi_valuerepresentando astringJavaScript forçada.
Retorna napi_ok se a API for bem-sucedida.
Esta API implementa a operação abstrata ToString() conforme definido na Seção 7.1.13 da Especificação da Linguagem ECMAScript. Esta função potencialmente executa código JS se o valor passado for um objeto.
napi_typeof
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript cujo tipo consultar.[out] result: O tipo do valor JavaScript.
Retorna napi_ok se a API for bem-sucedida.
napi_invalid_argse o tipo devaluenão for um tipo ECMAScript conhecido evaluenão for um valor External.
Esta API representa um comportamento semelhante à invocação do Operador typeof no objeto, conforme definido na Seção 12.5.5 da Especificação da Linguagem ECMAScript. No entanto, existem algumas diferenças:
Se value tiver um tipo inválido, um erro será retornado.
napi_instanceof
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_instanceof(napi_env env,
napi_value object,
napi_value constructor,
bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] object: O valor JavaScript a ser verificado.[in] constructor: O objeto de função JavaScript da função construtora a ser verificada.[out] result: Booleano que é definido como verdadeiro seobject instanceof constructorfor verdadeiro.
Retorna napi_ok se a API for bem-sucedida.
Esta API representa a invocação do Operador instanceof no objeto, conforme definido na Seção 12.10.4 da Especificação da Linguagem ECMAScript.
napi_is_array
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_is_array(napi_env env, napi_value value, bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser verificado.[out] result: Indica se o objeto fornecido é uma matriz.
Retorna napi_ok se a API for bem-sucedida.
Esta API representa a invocação da operação IsArray no objeto, conforme definido na Seção 7.2.2 da Especificação da Linguagem ECMAScript.
napi_is_arraybuffer
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser verificado.[out] result: Indica se o objeto fornecido é umArrayBuffer.
Retorna napi_ok se a API for bem-sucedida.
Esta API verifica se o Object passado é um array buffer.
napi_is_buffer
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser verificado.[out] result: Indica se onapi_valuefornecido representa um objetonode::BufferouUint8Array.
Retorna napi_ok se a API for bem-sucedida.
Esta API verifica se o Object passado é um buffer ou Uint8Array. napi_is_typedarray deve ser preferido se o chamador precisar verificar se o valor é um Uint8Array.
napi_is_date
Adicionado em: v11.11.0, v10.17.0
Versão N-API: 5
napi_status napi_is_date(napi_env env, napi_value value, bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser verificado.[out] result: Indica se onapi_valuefornecido representa um objeto JavaScriptDate.
Retorna napi_ok se a API for bem-sucedida.
Esta API verifica se o Object passado é uma data.
napi_is_error
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_is_error(napi_env env, napi_value value, bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser verificado.[out] result: Indica se onapi_valuefornecido representa um objetoError.
Retorna napi_ok se a API for bem-sucedida.
Esta API verifica se o Objeto passado é um Error.
napi_is_typedarray
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser verificado.[out] result: Indica se onapi_valuefornecido representa umTypedArray.
Retorna napi_ok se a API for bem-sucedida.
Esta API verifica se o Objeto passado é um array tipado.
napi_is_dataview
Adicionado em: v8.3.0
Versão N-API: 1
napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor JavaScript a ser verificado.[out] result: Indica se onapi_valuefornecido representa umDataView.
Retorna napi_ok se a API for bem-sucedida.
Esta API verifica se o Objeto passado é um DataView.
napi_strict_equals
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_strict_equals(napi_env env,
napi_value lhs,
napi_value rhs,
bool* result)[in] env: O ambiente sob o qual a API é invocada.[in] lhs: O valor JavaScript a ser verificado.[in] rhs: O valor JavaScript com o qual verificar.[out] result: Indica se os dois objetosnapi_valuesão iguais.
Retorna napi_ok se a API for bem-sucedida.
Esta API representa a invocação do algoritmo de Igualdade Estrita, conforme definido na Seção 7.2.14 da Especificação da Linguagem ECMAScript.
napi_detach_arraybuffer
Adicionado em: v13.0.0, v12.16.0, v10.22.0
Versão N-API: 7
napi_status napi_detach_arraybuffer(napi_env env,
napi_value arraybuffer)[in] env: O ambiente em que a API é invocada.[in] arraybuffer: OArrayBufferJavaScript a ser desanexado.
Retorna napi_ok se a API for bem-sucedida. Se um ArrayBuffer não desanexável for passado, ele retornará napi_detachable_arraybuffer_expected.
Geralmente, um ArrayBuffer não é desanexável se já foi desanexado antes. O mecanismo pode impor condições adicionais sobre se um ArrayBuffer é desanexável. Por exemplo, o V8 exige que o ArrayBuffer seja externo, ou seja, criado com napi_create_external_arraybuffer.
Esta API representa a invocação da operação de desanexação do ArrayBuffer, conforme definido na Seção 24.1.1.3 da Especificação da Linguagem ECMAScript.
napi_is_detached_arraybuffer
Adicionado em: v13.3.0, v12.16.0, v10.22.0
Versão N-API: 7
napi_status napi_is_detached_arraybuffer(napi_env env,
napi_value arraybuffer,
bool* result)[in] env: O ambiente em que a API é invocada.[in] arraybuffer: OArrayBufferJavaScript a ser verificado.[out] result: Indica se oarraybufferestá desanexado.
Retorna napi_ok se a API for bem-sucedida.
O ArrayBuffer é considerado desanexado se seus dados internos forem null.
Esta API representa a invocação da operação IsDetachedBuffer do ArrayBuffer, conforme definido na Seção 24.1.1.2 da Especificação da Linguagem ECMAScript.
Trabalhando com propriedades JavaScript
A Node-API expõe um conjunto de APIs para obter e definir propriedades em objetos JavaScript. Alguns desses tipos estão documentados na Seção 7 da Especificação da Linguagem ECMAScript.
As propriedades em JavaScript são representadas como uma tupla de uma chave e um valor. Fundamentalmente, todas as chaves de propriedade na Node-API podem ser representadas em uma das seguintes formas:
- Nomeado: uma string simples codificada em UTF8
- Indexado por Inteiro: um valor de índice representado por
uint32_t - Valor JavaScript: estes são representados na Node-API por
napi_value. Isso pode ser umnapi_valuerepresentando umastring,numberousymbol.
Os valores da Node-API são representados pelo tipo napi_value. Qualquer chamada da Node-API que exija um valor JavaScript recebe um napi_value. No entanto, é responsabilidade do chamador garantir que o napi_value em questão seja do tipo JavaScript esperado pela API.
As APIs documentadas nesta seção fornecem uma interface simples para obter e definir propriedades em objetos JavaScript arbitrários representados por napi_value.
Por exemplo, considere o seguinte trecho de código JavaScript:
const obj = {}
obj.myProp = 123O equivalente pode ser feito usando valores da Node-API com o seguinte trecho:
napi_status status = napi_generic_failure;
// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Cria um napi_value para 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;Propriedades indexadas podem ser definidas de maneira semelhante. Considere o seguinte trecho de código JavaScript:
const arr = []
arr[123] = 'hello'O equivalente pode ser feito usando valores da Node-API com o seguinte trecho:
napi_status status = napi_generic_failure;
// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// Cria um napi_value para '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;As propriedades podem ser recuperadas usando as APIs descritas nesta seção. Considere o seguinte trecho de código JavaScript:
const arr = []
const value = arr[123]A seguir está o equivalente aproximado da contraparte da Node-API:
napi_status status = napi_generic_failure;
// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status;Finalmente, várias propriedades também podem ser definidas em um objeto por motivos de desempenho. Considere o seguinte JavaScript:
const obj = {}
Object.defineProperties(obj, {
foo: { value: 123, writable: true, configurable: true, enumerable: true },
bar: { value: 456, writable: true, configurable: true, enumerable: true },
})A seguir está o equivalente aproximado da contraparte da 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;
// Cria napi_values para 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;
// Define as propriedades
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;Estruturas
napi_property_attributes
[Histórico]
| Versão | Mudanças |
|---|---|
| v14.12.0 | adicionado napi_default_method e napi_default_property. |
typedef enum {
napi_default = 0,
napi_writable = 1 << 0,
napi_enumerable = 1 << 1,
napi_configurable = 1 << 2,
// Usado com napi_define_class para distinguir propriedades estáticas
// de propriedades de instância. Ignorado por napi_define_properties.
napi_static = 1 << 10,
// Padrão para métodos de classe.
napi_default_method = napi_writable | napi_configurable,
// Padrão para propriedades de objeto, como em JS obj[prop].
napi_default_jsproperty = napi_writable |
napi_enumerable |
napi_configurable,
} napi_property_attributes;napi_property_attributes são flags usadas para controlar o comportamento de propriedades definidas em um objeto JavaScript. Além de napi_static, elas correspondem aos atributos listados na Seção 6.1.7.1 da Especificação da Linguagem ECMAScript. Elas podem ser uma ou mais das seguintes bitflags:
napi_default: Nenhum atributo explícito é definido na propriedade. Por padrão, uma propriedade é somente leitura, não enumerável e não configurável.napi_writable: A propriedade é gravável.napi_enumerable: A propriedade é enumerável.napi_configurable: A propriedade é configurável conforme definido na Seção 6.1.7.1 da Especificação da Linguagem ECMAScript.napi_static: A propriedade será definida como uma propriedade estática em uma classe, em oposição a uma propriedade de instância, que é o padrão. Isso é usado apenas pornapi_define_class. É ignorado pornapi_define_properties.napi_default_method: Como um método em uma classe JS, a propriedade é configurável e gravável, mas não enumerável.napi_default_jsproperty: Como uma propriedade definida via atribuição em JavaScript, a propriedade é gravável, enumerável e configurável.
napi_property_descriptor
typedef struct {
// Um de utf8name ou name deve ser NULL.
const char* utf8name;
napi_value name;
napi_callback method;
napi_callback getter;
napi_callback setter;
napi_value value;
napi_property_attributes attributes;
void* data;
} napi_property_descriptor;utf8name: String opcional descrevendo a chave para a propriedade, codificada como UTF8. Um deutf8nameounamedeve ser fornecido para a propriedade.name:napi_valueopcional que aponta para uma string JavaScript ou símbolo a ser usado como chave para a propriedade. Um deutf8nameounamedeve ser fornecido para a propriedade.value: O valor que é recuperado por um acesso get da propriedade se a propriedade for uma propriedade de dados. Se isso for passado, definagetter,setter,methodedatacomoNULL(já que esses membros não serão usados).getter: Uma função a ser chamada quando um acesso get da propriedade é executado. Se isso for passado, definavalueemethodcomoNULL(já que esses membros não serão usados). A função fornecida é chamada implicitamente pelo runtime quando a propriedade é acessada a partir de código JavaScript (ou se um get na propriedade for executado usando uma chamada Node-API).napi_callbackfornece mais detalhes.setter: Uma função a ser chamada quando um acesso set da propriedade é executado. Se isso for passado, definavalueemethodcomoNULL(já que esses membros não serão usados). A função fornecida é chamada implicitamente pelo runtime quando a propriedade é definida a partir de código JavaScript (ou se um set na propriedade for executado usando uma chamada Node-API).napi_callbackfornece mais detalhes.method: Defina isso para fazer com que a propriedadevaluedo objeto descritor de propriedade seja uma função JavaScript representada pormethod. Se isso for passado, definavalue,getteresettercomoNULL(já que esses membros não serão usados).napi_callbackfornece mais detalhes.attributes: Os atributos associados à propriedade específica. Vejanapi_property_attributes.data: Os dados de callback passados paramethod,getteresetterse esta função for invocada.
Funções
napi_get_property_names
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_property_names(napi_env env,
napi_value object,
napi_value* result);[in] env: O ambiente no qual a chamada Node-API é invocada.[in] object: O objeto do qual recuperar as propriedades.[out] result: Umnapi_valuerepresentando um array de valores JavaScript que representam os nomes das propriedades do objeto. A API pode ser usada para iterar sobreresultusandonapi_get_array_lengthenapi_get_element.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna os nomes das propriedades enumeráveis de object como um array de strings. As propriedades de object cuja chave é um símbolo não serão incluídas.
napi_get_all_property_names
Adicionado em: v13.7.0, v12.17.0, v10.20.0
Versão 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: O ambiente no qual a chamada Node-API é invocada.[in] object: O objeto do qual recuperar as propriedades.[in] key_mode: Se deve ou não recuperar as propriedades do protótipo também.[in] key_filter: Quais propriedades recuperar (enumeráveis/legíveis/graváveis).[in] key_conversion: Se deve ou não converter chaves de propriedades numeradas para strings.[out] result: Umnapi_valuerepresentando um array de valores JavaScript que representam os nomes das propriedades do objeto.napi_get_array_lengthenapi_get_elementpodem ser usados para iterar sobreresult.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna um array contendo os nomes das propriedades disponíveis deste objeto.
napi_set_property
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_set_property(napi_env env,
napi_value object,
napi_value key,
napi_value value);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto no qual definir a propriedade.[in] key: O nome da propriedade a ser definida.[in] value: O valor da propriedade.
Retorna napi_ok se a API for bem-sucedida.
Esta API define uma propriedade no Object passado.
napi_get_property
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_property(napi_env env,
napi_value object,
napi_value key,
napi_value* result);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto do qual recuperar a propriedade.[in] key: O nome da propriedade a ser recuperada.[out] result: O valor da propriedade.
Retorna napi_ok se a API for bem-sucedida.
Esta API obtém a propriedade solicitada do Object passado.
napi_has_property
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_has_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto a ser consultado.[in] key: O nome da propriedade cuja existência será verificada.[out] result: Se a propriedade existe ou não no objeto.
Retorna napi_ok se a API for bem-sucedida.
Esta API verifica se o Object passado possui a propriedade nomeada.
napi_delete_property
Adicionado em: v8.2.0
Versão N-API: 1
napi_status napi_delete_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto a ser consultado.[in] key: O nome da propriedade a ser excluída.[out] result: Se a exclusão da propriedade foi bem-sucedida ou não.resultpode opcionalmente ser ignorado passandoNULL.
Retorna napi_ok se a API for bem-sucedida.
Esta API tenta excluir a propriedade key do object.
napi_has_own_property
Adicionado em: v8.2.0
Versão N-API: 1
napi_status napi_has_own_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: O ambiente sob o qual a chamada da Node-API é invocada.[in] object: O objeto a ser consultado.[in] key: O nome da propriedade própria cuja existência deve ser verificada.[out] result: Indica se a propriedade própria existe no objeto ou não.
Retorna napi_ok se a API for bem-sucedida.
Esta API verifica se o Objeto passado tem a propriedade própria nomeada. key deve ser uma string ou um símbolo, ou um erro será lançado. A Node-API não realizará nenhuma conversão entre tipos de dados.
napi_set_named_property
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_set_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value value);[in] env: O ambiente sob o qual a chamada da Node-API é invocada.[in] object: O objeto no qual a propriedade deve ser definida.[in] utf8Name: O nome da propriedade a ser definida.[in] value: O valor da propriedade.
Retorna napi_ok se a API for bem-sucedida.
Este método é equivalente a chamar napi_set_property com um napi_value criado a partir da string passada como utf8Name.
napi_get_named_property
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value* result);[in] env: O ambiente sob o qual a chamada da Node-API é invocada.[in] object: O objeto do qual a propriedade deve ser recuperada.[in] utf8Name: O nome da propriedade a ser obtida.[out] result: O valor da propriedade.
Retorna napi_ok se a API for bem-sucedida.
Este método é equivalente a chamar napi_get_property com um napi_value criado a partir da string passada como utf8Name.
napi_has_named_property
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_has_named_property(napi_env env,
napi_value object,
const char* utf8Name,
bool* result);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto a ser consultado.[in] utf8Name: O nome da propriedade cuja existência deve ser verificada.[out] result: Indica se a propriedade existe no objeto ou não.
Retorna napi_ok se a API for bem-sucedida.
Este método é equivalente a chamar napi_has_property com um napi_value criado a partir da string passada como utf8Name.
napi_set_element
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_set_element(napi_env env,
napi_value object,
uint32_t index,
napi_value value);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto do qual as propriedades devem ser definidas.[in] index: O índice da propriedade a ser definida.[in] value: O valor da propriedade.
Retorna napi_ok se a API for bem-sucedida.
Esta API define um elemento no Object passado.
napi_get_element
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_element(napi_env env,
napi_value object,
uint32_t index,
napi_value* result);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto do qual a propriedade deve ser recuperada.[in] index: O índice da propriedade a ser obtida.[out] result: O valor da propriedade.
Retorna napi_ok se a API for bem-sucedida.
Esta API obtém o elemento no índice solicitado.
napi_has_element
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_has_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto a ser consultado.[in] index: O índice da propriedade cuja existência deve ser verificada.[out] result: Indica se a propriedade existe no objeto ou não.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna se o Object passado tem um elemento no índice solicitado.
napi_delete_element
Adicionado em: v8.2.0
Versão da N-API: 1
napi_status napi_delete_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto a ser consultado.[in] index: O índice da propriedade a ser excluída.[out] result: Se a exclusão do elemento foi bem-sucedida ou não.resultpode ser opcionalmente ignorado ao passarNULL.
Retorna napi_ok se a API for bem-sucedida.
Esta API tenta excluir o index especificado de object.
napi_define_properties
Adicionado em: v8.0.0
Versão da 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: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto do qual recuperar as propriedades.[in] property_count: O número de elementos no arrayproperties.[in] properties: O array de descritores de propriedade.
Retorna napi_ok se a API for bem-sucedida.
Este método permite a definição eficiente de várias propriedades em um determinado objeto. As propriedades são definidas usando descritores de propriedade (consulte napi_property_descriptor). Dado um array de tais descritores de propriedade, esta API irá definir as propriedades no objeto uma de cada vez, conforme definido por DefineOwnProperty() (descrito na Seção 9.1.6 da especificação ECMA-262).
napi_object_freeze
Adicionado em: v14.14.0, v12.20.0
Versão da N-API: 8
napi_status napi_object_freeze(napi_env env,
napi_value object);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto a ser congelado.
Retorna napi_ok se a API for bem-sucedida.
Este método congela um determinado objeto. Isso impede que novas propriedades sejam adicionadas a ele, que as propriedades existentes sejam removidas, impede a alteração da capacidade de enumeração, configurabilidade ou capacidade de gravação de propriedades existentes e impede que os valores das propriedades existentes sejam alterados. Também impede que o protótipo do objeto seja alterado. Isso é descrito na Seção 19.1.2.6 da especificação ECMA-262.
napi_object_seal
Adicionado em: v14.14.0, v12.20.0
Versão N-API: 8
napi_status napi_object_seal(napi_env env,
napi_value object);[in] env: O ambiente sob o qual a chamada Node-API é invocada.[in] object: O objeto a ser selado.
Retorna napi_ok se a API foi bem-sucedida.
Este método sela um determinado objeto. Isso impede que novas propriedades sejam adicionadas a ele, além de marcar todas as propriedades existentes como não configuráveis. Isso é descrito na Seção 19.1.2.20 da especificação ECMA-262.
Trabalhando com funções JavaScript
Node-API fornece um conjunto de APIs que permitem que o código JavaScript faça um retorno ao código nativo. As APIs Node-API que oferecem suporte ao retorno ao código nativo recebem funções de retorno de chamada representadas pelo tipo napi_callback. Quando a VM JavaScript faz um retorno ao código nativo, a função napi_callback fornecida é invocada. As APIs documentadas nesta seção permitem que a função de retorno de chamada faça o seguinte:
- Obtenha informações sobre o contexto no qual o retorno de chamada foi invocado.
- Obtenha os argumentos passados para o retorno de chamada.
- Retorne um
napi_valuedo retorno de chamada.
Além disso, Node-API fornece um conjunto de funções que permitem chamar funções JavaScript do código nativo. Pode-se chamar uma função como uma chamada de função JavaScript regular ou como uma função construtora.
Quaisquer dados não NULL que sejam passados para esta API por meio do campo data dos itens napi_property_descriptor podem ser associados ao objeto e liberados sempre que o objeto for coletado pelo coletor de lixo, passando o objeto e os dados para napi_add_finalizer.
napi_call_function
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] recv: O valorthispassado para a função chamada.[in] func:napi_valuerepresentando a função JavaScript a ser invocada.[in] argc: A contagem de elementos na matrizargv.[in] argv: Matriz denapi_valuesrepresentando valores JavaScript passados como argumentos para a função.[out] result:napi_valuerepresentando o objeto JavaScript retornado.
Retorna napi_ok se a API foi bem-sucedida.
Este método permite que um objeto de função JavaScript seja chamado de um complemento nativo. Este é o principal mecanismo para retornar do código nativo do complemento para JavaScript. Para o caso especial de chamar o JavaScript após uma operação assíncrona, consulte napi_make_callback.
Um caso de uso de amostra pode ser o seguinte. Considere o seguinte trecho de JavaScript:
function AddTwo(num) {
return num + 2
}
global.AddTwo = AddTwoEntão, a função acima pode ser invocada de um complemento nativo usando o seguinte código:
// Obtenha a função chamada "AddTwo" no objeto global
napi_value global, add_two, arg;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;
status = napi_get_named_property(env, global, "AddTwo", &add_two);
if (status != napi_ok) return;
// const arg = 1337
status = napi_create_int32(env, 1337, &arg);
if (status != napi_ok) return;
napi_value* argv = &arg;
size_t argc = 1;
// AddTwo(arg);
napi_value return_val;
status = napi_call_function(env, global, add_two, argc, argv, &return_val);
if (status != napi_ok) return;
// Converta o resultado de volta para um tipo nativo
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;napi_create_function
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] utf8Name: Nome opcional da função codificado como UTF8. Isso é visível dentro do JavaScript como a propriedadenamedo novo objeto da função.[in] length: O comprimento doutf8nameem bytes, ouNAPI_AUTO_LENGTHse for terminado em nulo.[in] cb: A função nativa que deve ser chamada quando este objeto de função for invocado.napi_callbackfornece mais detalhes.[in] data: Contexto de dados fornecido pelo usuário. Isso será passado de volta para a função quando invocado posteriormente.[out] result:napi_valuerepresentando o objeto de função JavaScript para a função recém-criada.
Retorna napi_ok se a API for bem-sucedida.
Esta API permite que um autor de add-on crie um objeto de função em código nativo. Este é o principal mecanismo para permitir chamar para o código nativo do add-on a partir do JavaScript.
A função recém-criada não é automaticamente visível a partir do script após esta chamada. Em vez disso, uma propriedade deve ser definida explicitamente em qualquer objeto que seja visível para o JavaScript, para que a função seja acessível a partir do script.
Para expor uma função como parte das exportações do módulo do add-on, defina a função recém-criada no objeto de exportações. Um módulo de exemplo pode ter a seguinte aparência:
napi_value SayHello(napi_env env, napi_callback_info info) {
printf("Olá\n");
return NULL;
}
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_value fn;
status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "sayHello", fn);
if (status != napi_ok) return NULL;
return exports;
}
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)Dado o código acima, o add-on pode ser usado a partir do JavaScript da seguinte forma:
const myaddon = require('./addon')
myaddon.sayHello()A string passada para require() é o nome do alvo em binding.gyp responsável por criar o arquivo .node.
Quaisquer dados não NULL que sejam passados para esta API através do parâmetro data podem ser associados à função JavaScript resultante (que é retornada no parâmetro result) e liberados sempre que a função for coletada pelo coletor de lixo, passando tanto a função JavaScript quanto os dados para napi_add_finalizer.
As Functions JavaScript são descritas na Seção 19.2 da Especificação da Linguagem ECMAScript.
napi_get_cb_info
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] cbinfo: As informações de retorno de chamada passadas para a função de retorno de chamada.[in-out] argc: Especifica o comprimento do arrayargvfornecido e recebe a contagem real de argumentos.argcpode ser opcionalmente ignorado ao passarNULL.[out] argv: Array C denapi_values para o qual os argumentos serão copiados. Se houver mais argumentos do que a contagem fornecida, apenas o número solicitado de argumentos será copiado. Se houver menos argumentos fornecidos do que o alegado, o resto deargvé preenchido com valoresnapi_valueque representamundefined.argvpode ser opcionalmente ignorado ao passarNULL.[out] thisArg: Recebe o argumento JavaScriptthispara a chamada.thisArgpode ser opcionalmente ignorado ao passarNULL.[out] data: Recebe o ponteiro de dados para o retorno de chamada.datapode ser opcionalmente ignorado ao passarNULL.
Retorna napi_ok se a API for bem-sucedida.
Este método é usado dentro de uma função de retorno de chamada para recuperar detalhes sobre a chamada, como os argumentos e o ponteiro this de uma determinada informação de retorno de chamada.
napi_get_new_target
Adicionado em: v8.6.0
Versão N-API: 1
napi_status napi_get_new_target(napi_env env,
napi_callback_info cbinfo,
napi_value* result)[in] env: O ambiente sob o qual a API é invocada.[in] cbinfo: As informações de retorno de chamada passadas para a função de retorno de chamada.[out] result: Onew.targetda chamada do construtor.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna o new.target da chamada do construtor. Se o retorno de chamada atual não for uma chamada de construtor, o resultado é NULL.
napi_new_instance
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] cons:napi_valuerepresentando a função JavaScript a ser invocada como um construtor.[in] argc: A contagem de elementos no arrayargv.[in] argv: Array de valores JavaScript comonapi_valuerepresentando os argumentos para o construtor. Seargcfor zero, este parâmetro pode ser omitido passandoNULL.[out] result:napi_valuerepresentando o objeto JavaScript retornado, que neste caso é o objeto construído.
Este método é usado para instanciar um novo valor JavaScript usando um dado napi_value que representa o construtor para o objeto. Por exemplo, considere o seguinte trecho:
function MyObject(param) {
this.param = param
}
const arg = 'hello'
const value = new MyObject(arg)O seguinte pode ser aproximado em Node-API usando o seguinte trecho:
// Obtenha a função construtora 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);Retorna napi_ok se a API foi bem-sucedida.
Object wrap
Node-API oferece uma maneira de "envolver" classes e instâncias C++ para que o construtor e os métodos da classe possam ser chamados a partir do JavaScript.
Para objetos envolvidos, pode ser difícil distinguir entre uma função chamada em um protótipo de classe e uma função chamada em uma instância de uma classe. Um padrão comum usado para resolver esse problema é salvar uma referência persistente ao construtor da classe para verificações posteriores de instanceof.
napi_value MyClass_constructor = NULL;
status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);
assert(napi_ok == status);
bool is_instance = false;
status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);
assert(napi_ok == status);
if (is_instance) {
// napi_unwrap() ...
} else {
// caso contrário...
}A referência deve ser liberada quando não for mais necessária.
Há ocasiões em que napi_instanceof() é insuficiente para garantir que um objeto JavaScript seja um wrapper para um certo tipo nativo. Este é o caso especialmente quando objetos JavaScript encapsulados são passados de volta para o addon através de métodos estáticos em vez de como o valor this de métodos de protótipo. Nesses casos, há uma chance de que eles possam ser desempacotados incorretamente.
const myAddon = require('./build/Release/my_addon.node')
// `openDatabase()` retorna um objeto JavaScript que envolve um banco de dados nativo
// manipulação.
const dbHandle = myAddon.openDatabase()
// `query()` retorna um objeto JavaScript que envolve uma consulta nativa
// manipulação.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')
// Há um erro acidental na linha abaixo. O primeiro parâmetro para
// `myAddon.queryHasRecords()` deve ser o identificador do banco de dados (`dbHandle`), não
// o identificador de consulta (`query`), então a condição correta para o loop while-loop
// deveria ser
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
// recuperar registros
}No exemplo acima, myAddon.queryHasRecords() é um método que aceita dois argumentos. O primeiro é um identificador de banco de dados e o segundo é um identificador de consulta. Internamente, ele desempacota o primeiro argumento e converte o ponteiro resultante em um identificador de banco de dados nativo. Em seguida, desempacota o segundo argumento e converte o ponteiro resultante em um identificador de consulta. Se os argumentos forem passados na ordem errada, as conversões funcionarão, no entanto, há uma boa chance de que a operação de banco de dados subjacente falhe, ou mesmo cause um acesso inválido à memória.
Para garantir que o ponteiro recuperado do primeiro argumento seja realmente um ponteiro para um identificador de banco de dados e, da mesma forma, que o ponteiro recuperado do segundo argumento seja realmente um ponteiro para um identificador de consulta, a implementação de queryHasRecords() tem que realizar uma validação de tipo. Reter o construtor da classe JavaScript a partir do qual o identificador do banco de dados foi instanciado e o construtor a partir do qual o identificador da consulta foi instanciado em napi_refs pode ajudar, porque napi_instanceof() pode então ser usado para garantir que as instâncias passadas para queryHashRecords() sejam de fato do tipo correto.
Infelizmente, napi_instanceof() não protege contra a manipulação de protótipos. Por exemplo, o protótipo da instância de identificador de banco de dados pode ser definido para o protótipo do construtor para instâncias de identificador de consulta. Nesse caso, a instância de identificador de banco de dados pode aparecer como uma instância de identificador de consulta, e ela passará no teste napi_instanceof() para uma instância de identificador de consulta, enquanto ainda contém um ponteiro para um identificador de banco de dados.
Para esse fim, Node-API fornece recursos de marcação de tipo.
Uma tag de tipo é um inteiro de 128 bits exclusivo para o addon. Node-API fornece a estrutura napi_type_tag para armazenar uma tag de tipo. Quando esse valor é passado junto com um objeto JavaScript ou externo armazenado em um napi_value para napi_type_tag_object(), o objeto JavaScript será "marcado" com a tag de tipo. A "marca" é invisível no lado JavaScript. Quando um objeto JavaScript chega a uma ligação nativa, napi_check_object_type_tag() pode ser usado junto com a tag de tipo original para determinar se o objeto JavaScript foi previamente "marcado" com a tag de tipo. Isso cria um recurso de verificação de tipo de uma fidelidade maior do que napi_instanceof() pode fornecer, porque essa marcação de tipo sobrevive à manipulação de protótipos e descarregamento/recarregamento de addons.
Continuando o exemplo acima, a seguinte implementação de addon de esqueleto ilustra o uso de napi_type_tag_object() e napi_check_object_type_tag().
// Este valor é a tag de tipo para um identificador de banco de dados. O comando
//
// uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// pode ser usado para obter os dois valores com os quais inicializar a estrutura.
static const napi_type_tag DatabaseHandleTypeTag = {
0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};
// Este valor é a tag de tipo para um identificador de consulta.
static const napi_type_tag QueryHandleTypeTag = {
0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};
static napi_value
openDatabase(napi_env env, napi_callback_info info) {
napi_status status;
napi_value result;
// Execute a ação subjacente que resulta em um identificador de banco de dados.
DatabaseHandle* dbHandle = open_database();
// Crie um novo objeto JS vazio.
status = napi_create_object(env, &result);
if (status != napi_ok) return NULL;
// Marque o objeto para indicar que ele contém um ponteiro para um `DatabaseHandle`.
status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
if (status != napi_ok) return NULL;
// Armazene o ponteiro para a estrutura `DatabaseHandle` dentro do objeto JS.
status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
if (status != napi_ok) return NULL;
return result;
}
// Mais tarde, quando recebermos um objeto JavaScript que alega ser um identificador de banco de dados
// podemos usar `napi_check_object_type_tag()` para garantir que seja realmente tal
// identificador.
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;
// Verifique se o objeto passado como primeiro parâmetro tem o anterior
// tag aplicada.
status = napi_check_object_type_tag(env,
argv[0],
&DatabaseHandleTypeTag,
&is_db_handle);
if (status != napi_ok) return NULL;
// Lance um `TypeError` se não tiver.
if (!is_db_handle) {
// Lance um TypeError.
return NULL;
}
}napi_define_class
Adicionado em: v8.0.0
Versão 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: O ambiente sob o qual a API é invocada.[in] utf8name: Nome da função construtora JavaScript. Para clareza, recomenda-se usar o nome da classe C++ ao encapsular uma classe C++.[in] length: O comprimento deutf8nameem bytes, ouNAPI_AUTO_LENGTHse for terminado com nulo.[in] constructor: Função de callback que manipula a construção de instâncias da classe. Ao encapsular uma classe C++, este método deve ser um membro estático com a assinaturanapi_callback. Um construtor de classe C++ não pode ser usado.napi_callbackfornece mais detalhes.[in] data: Dados opcionais a serem passados para o callback do construtor como a propriedadedatadas informações do callback.[in] property_count: Número de itens no argumento do arrayproperties.[in] properties: Array de descritores de propriedade descrevendo propriedades de dados estáticas e de instância, acessadores e métodos na classe. Vejanapi_property_descriptor.[out] result: Umnapi_valuerepresentando a função construtora para a classe.
Retorna napi_ok se a API for bem-sucedida.
Define uma classe JavaScript, incluindo:
- Uma função construtora JavaScript que tem o nome da classe. Ao encapsular uma classe C++ correspondente, o callback passado via
constructorpode ser usado para instanciar uma nova instância de classe C++, que pode então ser colocada dentro da instância de objeto JavaScript sendo construída usandonapi_wrap. - Propriedades na função construtora cuja implementação pode chamar propriedades de dados estáticas correspondentes, acessadores e métodos da classe C++ (definidos por descritores de propriedade com o atributo
napi_static). - Propriedades no objeto
prototypeda função construtora. Ao encapsular uma classe C++, propriedades de dados não estáticas, acessadores e métodos da classe C++ podem ser chamados das funções estáticas fornecidas nos descritores de propriedade sem o atributonapi_staticdepois de recuperar a instância da classe C++ colocada dentro da instância do objeto JavaScript usandonapi_unwrap.
Ao encapsular uma classe C++, o callback do construtor C++ passado via constructor deve ser um método estático na classe que chama o construtor da classe real, então encapsula a nova instância C++ em um objeto JavaScript e retorna o objeto wrapper. Veja napi_wrap para detalhes.
A função construtora JavaScript retornada de napi_define_class é frequentemente salva e usada posteriormente para construir novas instâncias da classe a partir de código nativo e/ou para verificar se os valores fornecidos são instâncias da classe. Nesse caso, para impedir que o valor da função seja coletado pelo coletor de lixo, uma referência persistente forte a ele pode ser criada usando napi_create_reference, garantindo que a contagem de referência seja mantida >= 1.
Quaisquer dados não NULL que são passados para esta API através do parâmetro data ou através do campo data dos itens do array napi_property_descriptor podem ser associados ao construtor JavaScript resultante (que é retornado no parâmetro result) e liberados sempre que a classe for coletada pelo coletor de lixo passando tanto a função JavaScript quanto os dados para napi_add_finalizer.
napi_wrap
Adicionado em: v8.0.0
Versão da 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: O ambiente sob o qual a API é invocada.[in] js_object: O objeto JavaScript que será o wrapper para o objeto nativo.[in] native_object: A instância nativa que será encapsulada no objeto JavaScript.[in] finalize_cb: Callback nativo opcional que pode ser usado para liberar a instância nativa quando o objeto JavaScript for coletado como lixo.napi_finalizefornece mais detalhes.[in] finalize_hint: Dica contextual opcional que é passada para o callback de finalização.[out] result: Referência opcional ao objeto encapsulado.
Retorna napi_ok se a API for bem-sucedida.
Encapsula uma instância nativa em um objeto JavaScript. A instância nativa pode ser recuperada posteriormente usando napi_unwrap().
Quando o código JavaScript invoca um construtor para uma classe que foi definida usando napi_define_class(), o napi_callback para o construtor é invocado. Após construir uma instância da classe nativa, o callback deve então chamar napi_wrap() para encapsular a instância recém-construída no objeto JavaScript já criado que é o argumento this para o callback do construtor. (Esse objeto this foi criado a partir do prototype da função construtora, portanto, ele já possui definições de todas as propriedades e métodos da instância.)
Normalmente, ao encapsular uma instância de classe, um callback de finalização deve ser fornecido, que simplesmente exclui a instância nativa que é recebida como o argumento data para o callback de finalização.
A referência retornada opcional é inicialmente uma referência fraca, o que significa que ela tem uma contagem de referência de 0. Normalmente, essa contagem de referência seria incrementada temporariamente durante operações assíncronas que exigem que a instância permaneça válida.
Cuidado: A referência retornada opcional (se obtida) deve ser excluída via napi_delete_reference APENAS em resposta à invocação do callback de finalização. Se for excluída antes disso, o callback de finalização pode nunca ser invocado. Portanto, ao obter uma referência, um callback de finalização também é necessário para permitir o descarte correto da referência.
Os callbacks do finalizador podem ser adiados, deixando uma janela onde o objeto foi coletado como lixo (e a referência fraca é inválida), mas o finalizador ainda não foi chamado. Ao usar napi_get_reference_value() em referências fracas retornadas por napi_wrap(), você ainda deve lidar com um resultado vazio.
Chamar napi_wrap() uma segunda vez em um objeto retornará um erro. Para associar outra instância nativa ao objeto, use napi_remove_wrap() primeiro.
napi_unwrap
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_unwrap(napi_env env,
napi_value js_object,
void** result);[in] env: O ambiente em que a API é invocada.[in] js_object: O objeto associado à instância nativa.[out] result: Ponteiro para a instância nativa envolvida.
Retorna napi_ok se a API for bem-sucedida.
Recupera uma instância nativa que foi previamente envolvida em um objeto JavaScript usando napi_wrap().
Quando o código JavaScript invoca um método ou acessador de propriedade na classe, o napi_callback correspondente é invocado. Se o callback for para um método ou acessador de instância, então o argumento this para o callback é o objeto wrapper; a instância C++ envolvida que é o alvo da chamada pode então ser obtida chamando napi_unwrap() no objeto wrapper.
napi_remove_wrap
Adicionado em: v8.5.0
Versão N-API: 1
napi_status napi_remove_wrap(napi_env env,
napi_value js_object,
void** result);[in] env: O ambiente em que a API é invocada.[in] js_object: O objeto associado à instância nativa.[out] result: Ponteiro para a instância nativa envolvida.
Retorna napi_ok se a API for bem-sucedida.
Recupera uma instância nativa que foi previamente envolvida no objeto JavaScript js_object usando napi_wrap() e remove o envolvimento. Se um callback de finalização foi associado ao envolvimento, ele não será mais chamado quando o objeto JavaScript for coletado pelo coletor de lixo.
napi_type_tag_object
Adicionado em: v14.8.0, v12.19.0
Versão N-API: 8
napi_status napi_type_tag_object(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag);[in] env: O ambiente em que a API é invocada.[in] js_object: O objeto JavaScript ou externo a ser marcado.[in] type_tag: A tag com a qual o objeto deve ser marcado.
Retorna napi_ok se a API for bem-sucedida.
Associa o valor do ponteiro type_tag ao objeto JavaScript ou externo. napi_check_object_type_tag() pode então ser usado para comparar a tag que foi anexada ao objeto com uma pertencente ao addon para garantir que o objeto tenha o tipo correto.
Se o objeto já tiver uma tag de tipo associada, esta API retornará napi_invalid_arg.
napi_check_object_type_tag
Adicionado em: v14.8.0, v12.19.0
Versão 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: O ambiente em que a API é invocada.[in] js_object: O objeto JavaScript ou externo cuja tag de tipo deve ser examinada.[in] type_tag: A tag com a qual comparar qualquer tag encontrada no objeto.[out] result: Se a tag de tipo fornecida correspondeu à tag de tipo no objeto.falsetambém é retornado se nenhuma tag de tipo foi encontrada no objeto.
Retorna napi_ok se a API for bem-sucedida.
Compara o ponteiro fornecido como type_tag com qualquer um que possa ser encontrado em js_object. Se nenhuma tag for encontrada em js_object ou, se uma tag for encontrada, mas não corresponder a type_tag, então result é definido como false. Se uma tag for encontrada e corresponder a type_tag, então result é definido como true.
napi_add_finalizer
Adicionado em: v8.0.0
Versão 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: O ambiente em que a API é invocada.[in] js_object: O objeto JavaScript ao qual os dados nativos serão anexados.[in] finalize_data: Dados opcionais a serem passados parafinalize_cb.[in] finalize_cb: Callback nativo que será usado para liberar os dados nativos quando o objeto JavaScript tiver sido coletado pelo coletor de lixo.napi_finalizefornece mais detalhes.[in] finalize_hint: Dica contextual opcional que é passada para o callback finalize.[out] result: Referência opcional para o objeto JavaScript.
Retorna napi_ok se a API for bem-sucedida.
Adiciona um callback napi_finalize que será chamado quando o objeto JavaScript em js_object tiver sido coletado pelo coletor de lixo.
Esta API pode ser chamada várias vezes em um único objeto JavaScript.
Cuidado: A referência opcional retornada (se obtida) deve ser excluída por meio de napi_delete_reference APENAS em resposta à invocação do callback finalize. Se for excluída antes disso, o callback finalize pode nunca ser invocado. Portanto, ao obter uma referência, um callback finalize também é necessário para permitir o descarte correto da referência.
node_api_post_finalizer
Adicionado em: v21.0.0, v20.10.0, v18.19.0
[Estável: 1 - Experimental]
Estável: 1 Estabilidade: 1 - Experimental
napi_status node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint);[in] env: O ambiente sob o qual a API é invocada.[in] finalize_cb: Callback nativo que será usado para liberar os dados nativos quando o objeto JavaScript for coletado pelo garbage collector.napi_finalizefornece mais detalhes.[in] finalize_data: Dados opcionais a serem passados parafinalize_cb.[in] finalize_hint: Dica contextual opcional que é passada para o callback finalize.
Retorna napi_ok se a API for bem-sucedida.
Agenda um callback napi_finalize para ser chamado de forma assíncrona no loop de eventos.
Normalmente, finalizadores são chamados enquanto o GC (garbage collector) coleta objetos. Nesse ponto, chamar qualquer Node-API que possa causar alterações no estado do GC será desabilitado e travará o Node.js.
node_api_post_finalizer ajuda a contornar essa limitação, permitindo que o addon adie chamadas para tais Node-APIs para um ponto no tempo fora da finalização do GC.
Operações assíncronas simples
Módulos addon muitas vezes precisam aproveitar helpers assíncronos do libuv como parte de sua implementação. Isso permite que eles agendem o trabalho para ser executado de forma assíncrona, para que seus métodos possam retornar antes que o trabalho seja concluído. Isso permite que eles evitem bloquear a execução geral do aplicativo Node.js.
Node-API fornece uma interface ABI-estável para essas funções de suporte que cobre os casos de uso assíncronos mais comuns.
Node-API define a estrutura napi_async_work que é usada para gerenciar workers assíncronos. Instâncias são criadas/excluídas com napi_create_async_work e napi_delete_async_work.
Os callbacks execute e complete são funções que serão invocadas quando o executor estiver pronto para executar e quando concluir sua tarefa, respectivamente.
A função execute deve evitar fazer qualquer chamada Node-API que possa resultar na execução de JavaScript ou interação com objetos JavaScript. Na maioria das vezes, qualquer código que precise fazer chamadas Node-API deve ser feito no callback complete. Evite usar o parâmetro napi_env no callback execute, pois provavelmente executará JavaScript.
Essas funções implementam as seguintes interfaces:
typedef void (*napi_async_execute_callback)(napi_env env,
void* data);
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);Quando esses métodos são invocados, o parâmetro data passado será o dado void* fornecido pelo addon que foi passado para a chamada napi_create_async_work.
Uma vez criado, o worker assíncrono pode ser enfileirado para execução usando a função napi_queue_async_work:
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);napi_cancel_async_work pode ser usado se o trabalho precisar ser cancelado antes que o trabalho tenha iniciado a execução.
Após chamar napi_cancel_async_work, o callback complete será invocado com um valor de status de napi_cancelled. O trabalho não deve ser excluído antes da invocação do callback complete, mesmo quando foi cancelado.
napi_create_async_work
[Histórico]
| Versão | Alterações |
|---|---|
| v8.6.0 | Adicionados parâmetros async_resource e async_resource_name. |
| v8.0.0 | Adicionado em: v8.0.0 |
Versão 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: O ambiente sob o qual a API é invocada.[in] async_resource: Um objeto opcional associado ao trabalho assíncrono que será passado para possíveis hooksasync_hooksinithooks.[in] async_resource_name: Identificador para o tipo de recurso que está sendo fornecido para informações de diagnóstico expostas pela APIasync_hooks.[in] execute: A função nativa que deve ser chamada para executar a lógica de forma assíncrona. A função fornecida é chamada a partir de um thread do pool de trabalhadores e pode ser executada em paralelo com o thread do loop de eventos principal.[in] complete: A função nativa que será chamada quando a lógica assíncrona for concluída ou cancelada. A função fornecida é chamada a partir do thread do loop de eventos principal.napi_async_complete_callbackfornece mais detalhes.[in] data: Contexto de dados fornecido pelo usuário. Isso será passado de volta para as funções de execução e conclusão.[out] result:napi_async_work*que é o identificador para o trabalho assíncrono recém-criado.
Retorna napi_ok se a API foi bem-sucedida.
Esta API aloca um objeto de trabalho que é usado para executar a lógica de forma assíncrona. Ele deve ser liberado usando napi_delete_async_work assim que o trabalho não for mais necessário.
async_resource_name deve ser uma string terminada em nulo e codificada em UTF-8.
O identificador async_resource_name é fornecido pelo usuário e deve ser representativo do tipo de trabalho assíncrono que está sendo realizado. Também é recomendável aplicar namespaces ao identificador, por exemplo, incluindo o nome do módulo. Consulte a documentação do async_hooks para obter mais informações.
napi_delete_async_work
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_delete_async_work(napi_env env,
napi_async_work work);[in] env: O ambiente sob o qual a API é invocada.[in] work: O manipulador retornado pela chamada paranapi_create_async_work.
Retorna napi_ok se a API foi bem-sucedida.
Esta API libera um objeto de trabalho alocado anteriormente.
Esta API pode ser chamada mesmo se houver uma exceção JavaScript pendente.
napi_queue_async_work
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);[in] env: O ambiente sob o qual a API é invocada.[in] work: O manipulador retornado pela chamada paranapi_create_async_work.
Retorna napi_ok se a API foi bem-sucedida.
Esta API solicita que o trabalho alocado anteriormente seja agendado para execução. Depois que ela retorna com sucesso, esta API não deve ser chamada novamente com o mesmo item napi_async_work, ou o resultado será indefinido.
napi_cancel_async_work
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_cancel_async_work(node_api_basic_env env,
napi_async_work work);[in] env: O ambiente sob o qual a API é invocada.[in] work: O manipulador retornado pela chamada paranapi_create_async_work.
Retorna napi_ok se a API foi bem-sucedida.
Esta API cancela o trabalho enfileirado se ele ainda não tiver sido iniciado. Se já tiver começado a ser executado, não pode ser cancelado e napi_generic_failure será retornado. Se for bem-sucedido, o retorno de chamada complete será invocado com um valor de status napi_cancelled. O trabalho não deve ser excluído antes da invocação do retorno de chamada complete, mesmo que tenha sido cancelado com sucesso.
Esta API pode ser chamada mesmo se houver uma exceção JavaScript pendente.
Operações assíncronas personalizadas
As APIs de trabalho assíncrono simples acima podem não ser apropriadas para todos os cenários. Ao usar qualquer outro mecanismo assíncrono, as seguintes APIs são necessárias para garantir que uma operação assíncrona seja devidamente rastreada pelo tempo de execução.
napi_async_init
Adicionado em: v8.6.0
Versão da 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: O ambiente sob o qual a API é invocada.[in] async_resource: Objeto associado ao trabalho assíncrono que será passado para possíveis hooksinitdoasync_hooksinithooks e que pode ser acessado porasync_hooks.executionAsyncResource().[in] async_resource_name: Identificador para o tipo de recurso que está sendo fornecido para informações de diagnóstico expostas pela APIasync_hooks.[out] result: O contexto assíncrono inicializado.
Retorna napi_ok se a API for bem-sucedida.
O objeto async_resource precisa ser mantido ativo até napi_async_destroy para que a API relacionada ao async_hooks aja corretamente. Para manter a compatibilidade ABI com as versões anteriores, os napi_async_context não estão mantendo uma referência forte aos objetos async_resource para evitar a introdução de vazamentos de memória. No entanto, se o async_resource for coletado pelo coletor de lixo do mecanismo JavaScript antes que o napi_async_context fosse destruído por napi_async_destroy, chamar APIs relacionadas ao napi_async_context, como napi_open_callback_scope e napi_make_callback, pode causar problemas como perda de contexto assíncrono ao usar a API AsyncLocalStorage.
Para manter a compatibilidade ABI com as versões anteriores, passar NULL para async_resource não resulta em um erro. No entanto, isso não é recomendado, pois resultará em um comportamento indesejável com os hooks init do async_hooks init hooks e async_hooks.executionAsyncResource(), pois o recurso agora é exigido pela implementação subjacente do async_hooks para fornecer a ligação entre os callbacks assíncronos.
napi_async_destroy
Adicionado em: v8.6.0
Versão N-API: 1
napi_status napi_async_destroy(napi_env env,
napi_async_context async_context);[in] env: O ambiente sob o qual a API é invocada.[in] async_context: O contexto assíncrono a ser destruído.
Retorna napi_ok se a API for bem-sucedida.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
napi_make_callback
[Histórico]
| Versão | Mudanças |
|---|---|
| v8.6.0 | Adicionado o parâmetro async_context. |
| v8.0.0 | Adicionado em: v8.0.0 |
Versão 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: O ambiente sob o qual a API é invocada.[in] async_context: Contexto para a operação assíncrona que está invocando o retorno de chamada. Normalmente, este deve ser um valor obtido anteriormente denapi_async_init. Para manter a compatibilidade ABI com versões anteriores, passarNULLparaasync_contextnão resulta em um erro. No entanto, isso resulta na operação incorreta dos hooks assíncronos. Problemas potenciais incluem perda de contexto assíncrono ao usar a APIAsyncLocalStorage.[in] recv: O valorthispassado para a função chamada.[in] func:napi_valuerepresentando a função JavaScript a ser invocada.[in] argc: A contagem de elementos no arrayargv.[in] argv: Array de valores JavaScript comonapi_valuerepresentando os argumentos para a função. Seargcfor zero, este parâmetro pode ser omitido passandoNULL.[out] result:napi_valuerepresentando o objeto JavaScript retornado.
Retorna napi_ok se a API for bem-sucedida.
Este método permite que um objeto de função JavaScript seja chamado de um complemento nativo. Esta API é semelhante a napi_call_function. No entanto, ela é usada para chamar de código nativo de volta para JavaScript depois de retornar de uma operação assíncrona (quando não há outro script na pilha). É um wrapper bastante simples em torno de node::MakeCallback.
Observe que não é necessário usar napi_make_callback de dentro de um napi_async_complete_callback; nessa situação, o contexto assíncrono do retorno de chamada já foi configurado, portanto, uma chamada direta para napi_call_function é suficiente e apropriada. O uso da função napi_make_callback pode ser necessário ao implementar um comportamento assíncrono personalizado que não usa napi_create_async_work.
Quaisquer process.nextTicks ou Promises agendadas na fila de microtarefas pelo JavaScript durante o retorno de chamada são executados antes de retornar para C/C++.
napi_open_callback_scope
Adicionado em: v9.6.0
Versão 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: O ambiente sob o qual a API é invocada.[in] resource_object: Um objeto associado ao trabalho assíncrono que será passado para possíveis hooksinitdoasync_hooksinithooks. Este parâmetro foi descontinuado e é ignorado em tempo de execução. Use o parâmetroasync_resourceemnapi_async_initem vez disso.[in] context: Contexto para a operação assíncrona que está invocando o callback. Este deve ser um valor obtido anteriormente denapi_async_init.[out] result: O escopo recém-criado.
Há casos (por exemplo, resolução de promessas) em que é necessário ter o equivalente ao escopo associado a um callback em vigor ao fazer certas chamadas Node-API. Se não houver nenhum outro script na pilha, as funções napi_open_callback_scope e napi_close_callback_scope podem ser usadas para abrir/fechar o escopo necessário.
napi_close_callback_scope
Adicionado em: v9.6.0
Versão N-API: 3
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
napi_callback_scope scope)[in] env: O ambiente sob o qual a API é invocada.[in] scope: O escopo a ser fechado.
Esta API pode ser chamada mesmo que haja uma exceção JavaScript pendente.
Gestão de versão
napi_get_node_version
Adicionado em: v8.4.0
Versão 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: O ambiente sob o qual a API é invocada.[out] version: Um ponteiro para as informações de versão para o próprio Node.js.
Retorna napi_ok se a API for bem-sucedida.
Esta função preenche a estrutura version com a versão major, minor e patch do Node.js que está sendo executado no momento e o campo release com o valor de process.release.name.
O buffer retornado é alocado estaticamente e não precisa ser liberado.
napi_get_version
Adicionado em: v8.0.0
Versão N-API: 1
napi_status napi_get_version(node_api_basic_env env,
uint32_t* result);[in] env: O ambiente em que a API é invocada.[out] result: A versão mais alta da Node-API suportada.
Retorna napi_ok se a API for bem-sucedida.
Esta API retorna a versão mais alta da Node-API suportada pelo tempo de execução do Node.js. A Node-API está planejada para ser aditiva, de modo que versões mais recentes do Node.js possam suportar funções de API adicionais. Para permitir que um complemento use uma função mais recente ao executar com versões do Node.js que a suportam, enquanto fornece um comportamento de fallback ao executar com versões do Node.js que não a suportam:
- Chame
napi_get_version()para determinar se a API está disponível. - Se disponível, carregue dinamicamente um ponteiro para a função usando
uv_dlsym(). - Use o ponteiro carregado dinamicamente para invocar a função.
- Se a função não estiver disponível, forneça uma implementação alternativa que não use a função.
Gerenciamento de memória
napi_adjust_external_memory
Adicionado em: v8.5.0
Versão 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: O ambiente em que a API é invocada.[in] change_in_bytes: A alteração na memória alocada externamente que é mantida ativa por objetos JavaScript.[out] result: O valor ajustado
Retorna napi_ok se a API for bem-sucedida.
Esta função dá ao V8 uma indicação da quantidade de memória alocada externamente que é mantida ativa por objetos JavaScript (ou seja, um objeto JavaScript que aponta para sua própria memória alocada por um complemento nativo). O registro de memória alocada externamente acionará coleta de lixo global com mais frequência do que ocorreria de outra forma.
Promises
A Node-API fornece recursos para criar objetos Promise, conforme descrito na Seção 25.4 da especificação ECMA. Ela implementa promises como um par de objetos. Quando uma promise é criada por napi_create_promise(), um objeto "deferred" é criado e retornado juntamente com a Promise. O objeto deferred é vinculado à Promise criada e é o único meio de resolver ou rejeitar a Promise usando napi_resolve_deferred() ou napi_reject_deferred(). O objeto deferred criado por napi_create_promise() é liberado por napi_resolve_deferred() ou napi_reject_deferred(). O objeto Promise pode ser retornado para JavaScript, onde pode ser usado da maneira usual.
Por exemplo, para criar uma promise e passá-la para um trabalhador assíncrono:
napi_deferred deferred;
napi_value promise;
napi_status status;
// Cria a promise.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;
// Passa o deferred para uma função que executa uma ação assíncrona.
do_something_asynchronous(deferred);
// Retorna a promise para JS
return promise;A função acima do_something_asynchronous() executaria sua ação assíncrona e, em seguida, resolveria ou rejeitaria o deferred, concluindo assim a promise e liberando o deferred:
napi_deferred deferred;
napi_value undefined;
napi_status status;
// Cria um valor com o qual concluir o deferred.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;
// Resolve ou rejeita a promise associada ao deferred, dependendo de
// se a ação assíncrona foi bem-sucedida.
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;
// Neste ponto, o deferred foi liberado, então devemos atribuir NULL a ele.
deferred = NULL;napi_create_promise
Adicionado em: v8.5.0
Versão N-API: 1
napi_status napi_create_promise(napi_env env,
napi_deferred* deferred,
napi_value* promise);[in] env: O ambiente sob o qual a API é invocada.[out] deferred: Um objeto deferred recém-criado que pode ser posteriormente passado paranapi_resolve_deferred()ounapi_reject_deferred()para resolver ou rejeitar a promise associada, respectivamente.[out] promise: A promise JavaScript associada ao objeto deferred.
Retorna napi_ok se a API for bem-sucedida.
Esta API cria um objeto deferred e uma promise JavaScript.
napi_resolve_deferred
Adicionado em: v8.5.0
Versão N-API: 1
napi_status napi_resolve_deferred(napi_env env,
napi_deferred deferred,
napi_value resolution);[in] env: O ambiente sob o qual a API é invocada.[in] deferred: O objeto deferred cuja promise associada deve ser resolvida.[in] resolution: O valor com o qual a promise será resolvida.
Esta API resolve uma promise JavaScript por meio do objeto deferred com o qual ela está associada. Portanto, só pode ser usada para resolver promises JavaScript para as quais o objeto deferred correspondente esteja disponível. Isso significa efetivamente que a promise deve ter sido criada usando napi_create_promise() e o objeto deferred retornado dessa chamada deve ter sido retido para ser passado para esta API.
O objeto deferred é liberado após a conclusão bem-sucedida.
napi_reject_deferred
Adicionado em: v8.5.0
Versão N-API: 1
napi_status napi_reject_deferred(napi_env env,
napi_deferred deferred,
napi_value rejection);[in] env: O ambiente sob o qual a API é invocada.[in] deferred: O objeto deferred cuja promise associada deve ser resolvida.[in] rejection: O valor com o qual a promise será rejeitada.
Esta API rejeita uma promise JavaScript por meio do objeto deferred com o qual ela está associada. Portanto, só pode ser usada para rejeitar promises JavaScript para as quais o objeto deferred correspondente esteja disponível. Isso significa efetivamente que a promise deve ter sido criada usando napi_create_promise() e o objeto deferred retornado dessa chamada deve ter sido retido para ser passado para esta API.
O objeto deferred é liberado após a conclusão bem-sucedida.
napi_is_promise
Adicionado em: v8.5.0
Versão N-API: 1
napi_status napi_is_promise(napi_env env,
napi_value value,
bool* is_promise);[in] env: O ambiente sob o qual a API é invocada.[in] value: O valor a ser examinado[out] is_promise: Sinalizador que indica sepromiseé um objeto promise nativo (ou seja, um objeto promise criado pelo mecanismo subjacente).
Execução de script
A Node-API fornece uma API para executar uma string contendo JavaScript usando o mecanismo JavaScript subjacente.
napi_run_script
Adicionado em: v8.5.0
Versão N-API: 1
NAPI_EXTERN napi_status napi_run_script(napi_env env,
napi_value script,
napi_value* result);[in] env: O ambiente sob o qual a API é invocada.[in] script: Uma string JavaScript contendo o script a ser executado.[out] result: O valor resultante da execução do script.
Esta função executa uma string de código JavaScript e retorna seu resultado com as seguintes ressalvas:
- Diferentemente de
eval, esta função não permite que o script acesse o escopo léxico atual e, portanto, também não permite o acesso ao escopo do módulo, o que significa que pseudo-globais comorequirenão estarão disponíveis. - O script pode acessar o escopo global. As declarações de função e
varno script serão adicionadas ao objetoglobal. As declarações de variáveis feitas usandoleteconstserão visíveis globalmente, mas não serão adicionadas ao objetoglobal. - O valor de
thiséglobaldentro do script.
Loop de eventos libuv
A Node-API fornece uma função para obter o loop de eventos atual associado a um napi_env específico.
napi_get_uv_event_loop
Adicionado em: v9.3.0, v8.10.0
Versão N-API: 2
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
struct uv_loop_s** loop);[in] env: O ambiente sob o qual a API é invocada.[out] loop: A instância atual do loop libuv.
Observação: Embora o libuv tenha sido relativamente estável ao longo do tempo, ele não fornece uma garantia de estabilidade ABI. O uso desta função deve ser evitado. Seu uso pode resultar em um complemento que não funciona em diferentes versões do Node.js. chamadas de função assíncronas com segurança de thread são uma alternativa para muitos casos de uso.
Chamadas de função assíncronas e thread-safe
As funções JavaScript normalmente só podem ser chamadas a partir da thread principal de um addon nativo. Se um addon criar threads adicionais, as funções da Node-API que exigem um napi_env, napi_value ou napi_ref não devem ser chamadas a partir dessas threads.
Quando um addon possui threads adicionais e as funções JavaScript precisam ser invocadas com base no processamento concluído por essas threads, essas threads devem se comunicar com a thread principal do addon para que a thread principal possa invocar a função JavaScript em seu nome. As APIs de função thread-safe fornecem uma maneira fácil de fazer isso.
Essas APIs fornecem o tipo napi_threadsafe_function, bem como APIs para criar, destruir e chamar objetos desse tipo. napi_create_threadsafe_function() cria uma referência persistente a um napi_value que contém uma função JavaScript que pode ser chamada a partir de várias threads. As chamadas ocorrem de forma assíncrona. Isso significa que os valores com os quais o callback JavaScript deve ser chamado serão colocados em uma fila e, para cada valor na fila, uma chamada será eventualmente feita para a função JavaScript.
Após a criação de um napi_threadsafe_function, um callback napi_finalize pode ser fornecido. Este callback será invocado na thread principal quando a função thread-safe estiver prestes a ser destruída. Ele recebe o contexto e os dados de finalização fornecidos durante a construção e oferece uma oportunidade para limpar as threads, por exemplo, chamando uv_thread_join(). Além da thread do loop principal, nenhuma thread deve estar usando a função thread-safe após a conclusão do callback de finalização.
O context fornecido durante a chamada para napi_create_threadsafe_function() pode ser recuperado de qualquer thread com uma chamada para napi_get_threadsafe_function_context().
Chamando uma função thread-safe
napi_call_threadsafe_function() pode ser usado para iniciar uma chamada para o JavaScript. napi_call_threadsafe_function() aceita um parâmetro que controla se a API se comporta de forma bloqueadora. Se definido como napi_tsfn_nonblocking, a API se comporta de forma não bloqueadora, retornando napi_queue_full se a fila estiver cheia, impedindo que os dados sejam adicionados com sucesso à fila. Se definido como napi_tsfn_blocking, a API bloqueia até que haja espaço disponível na fila. napi_call_threadsafe_function() nunca bloqueia se a função thread-safe foi criada com um tamanho máximo de fila de 0.
napi_call_threadsafe_function() não deve ser chamada com napi_tsfn_blocking de uma thread JavaScript, porque, se a fila estiver cheia, pode fazer com que a thread JavaScript entre em deadlock.
A chamada real para o JavaScript é controlada pelo callback fornecido através do parâmetro call_js_cb. call_js_cb é invocado na thread principal uma vez para cada valor que foi colocado na fila por uma chamada bem-sucedida para napi_call_threadsafe_function(). Se tal callback não for fornecido, um callback padrão será usado e a chamada JavaScript resultante não terá argumentos. O callback call_js_cb recebe a função JavaScript a ser chamada como um napi_value em seus parâmetros, bem como o ponteiro de contexto void* usado ao criar o napi_threadsafe_function e o próximo ponteiro de dados que foi criado por uma das threads secundárias. O callback pode então usar uma API como napi_call_function() para chamar o JavaScript.
O callback também pode ser invocado com env e call_js_cb ambos definidos como NULL para indicar que as chamadas para o JavaScript não são mais possíveis, enquanto os itens permanecem na fila que podem precisar ser liberados. Isso normalmente ocorre quando o processo Node.js sai enquanto há uma função thread-safe ainda ativa.
Não é necessário chamar o JavaScript por meio de napi_make_callback() porque a Node-API executa call_js_cb em um contexto apropriado para callbacks.
Zero ou mais itens enfileirados podem ser invocados em cada tick do loop de eventos. As aplicações não devem depender de um comportamento específico além do progresso na invocação de callbacks e os eventos serão invocados à medida que o tempo avança.
Contagem de referências de funções thread-safe
Threads podem ser adicionadas e removidas de um objeto napi_threadsafe_function durante sua existência. Assim, além de especificar um número inicial de threads na criação, napi_acquire_threadsafe_function pode ser chamado para indicar que uma nova thread começará a usar a função thread-safe. Da mesma forma, napi_release_threadsafe_function pode ser chamado para indicar que uma thread existente deixará de usar a função thread-safe.
Objetos napi_threadsafe_function são destruídos quando cada thread que usa o objeto chama napi_release_threadsafe_function() ou recebe um status de retorno de napi_closing em resposta a uma chamada para napi_call_threadsafe_function. A fila é esvaziada antes que napi_threadsafe_function seja destruída. napi_release_threadsafe_function() deve ser a última chamada de API feita em conjunto com uma determinada napi_threadsafe_function, porque após a conclusão da chamada, não há garantia de que a napi_threadsafe_function ainda esteja alocada. Pelo mesmo motivo, não use uma função thread-safe após receber um valor de retorno de napi_closing em resposta a uma chamada para napi_call_threadsafe_function. Os dados associados à napi_threadsafe_function podem ser liberados em seu callback napi_finalize que foi passado para napi_create_threadsafe_function(). O parâmetro initial_thread_count de napi_create_threadsafe_function marca o número inicial de aquisições das funções thread-safe, em vez de chamar napi_acquire_threadsafe_function várias vezes na criação.
Assim que o número de threads que usam uma napi_threadsafe_function atinge zero, nenhuma outra thread pode começar a usá-la chamando napi_acquire_threadsafe_function(). Na verdade, todas as chamadas de API subsequentes associadas a ela, exceto napi_release_threadsafe_function(), retornarão um valor de erro de napi_closing.
A função thread-safe pode ser "abortada" dando um valor de napi_tsfn_abort para napi_release_threadsafe_function(). Isso fará com que todas as APIs subsequentes associadas à função thread-safe, exceto napi_release_threadsafe_function(), retornem napi_closing mesmo antes que sua contagem de referência chegue a zero. Em particular, napi_call_threadsafe_function() retornará napi_closing, informando assim às threads que não é mais possível fazer chamadas assíncronas para a função thread-safe. Isso pode ser usado como critério para encerrar a thread. Ao receber um valor de retorno de napi_closing de napi_call_threadsafe_function(), uma thread não deve mais usar a função thread-safe, pois não há mais garantia de que ela esteja alocada.
Decidir se o processo deve continuar em execução
Semelhante aos manipuladores libuv, as funções thread-safe podem ser "referenciadas" e "não referenciadas". Uma função thread-safe "referenciada" fará com que o loop de eventos no thread em que é criada permaneça ativo até que a função thread-safe seja destruída. Em contraste, uma função thread-safe "não referenciada" não impedirá que o loop de eventos seja encerrado. As APIs napi_ref_threadsafe_function e napi_unref_threadsafe_function existem para esse propósito.
Nem napi_unref_threadsafe_function marca as funções thread-safe como capazes de serem destruídas, nem napi_ref_threadsafe_function impede que ela seja destruída.
napi_create_threadsafe_function
[Histórico]
| Versão | Mudanças |
|---|---|
| v12.6.0, v10.17.0 | Tornou o parâmetro func opcional com call_js_cb personalizado. |
| v10.6.0 | Adicionado em: v10.6.0 |
Versão 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: O ambiente sob o qual a API é invocada.[in] func: Uma função JavaScript opcional para chamar de outro thread. Deve ser fornecida seNULLfor passado paracall_js_cb.[in] async_resource: Um objeto opcional associado ao trabalho assíncrono que será passado para possíveis hooksasync_hooksinithooks.[in] async_resource_name: Uma string JavaScript para fornecer um identificador para o tipo de recurso que está sendo fornecido para informações de diagnóstico expostas pela APIasync_hooks.[in] max_queue_size: Tamanho máximo da fila.0para nenhum limite.[in] initial_thread_count: O número inicial de aquisições, ou seja, o número inicial de threads, incluindo o thread principal, que farão uso desta função.[in] thread_finalize_data: Dados opcionais a serem passados parathread_finalize_cb.[in] thread_finalize_cb: Função opcional para chamar quando onapi_threadsafe_functionestá sendo destruído.[in] context: Dados opcionais para anexar aonapi_threadsafe_functionresultante.[in] call_js_cb: Callback opcional que chama a função JavaScript em resposta a uma chamada em um thread diferente. Este callback será chamado no thread principal. Se não for fornecido, a função JavaScript será chamada sem parâmetros e comundefinedcomo seu valorthis.napi_threadsafe_function_call_jsfornece mais detalhes.[out] result: A função JavaScript assíncrona thread-safe.
Histórico de Mudanças:
- Experimental (
NAPI_EXPERIMENTALestá definido): Exceções não capturadas lançadas emcall_js_cbsão tratadas com o evento'uncaughtException', em vez de serem ignoradas.
napi_get_threadsafe_function_context
Adicionado em: v10.6.0
Versão N-API: 4
NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
void** result);[in] func: A função thread-safe para a qual recuperar o contexto.[out] result: O local onde armazenar o contexto.
Esta API pode ser chamada de qualquer thread que utilize func.
napi_call_threadsafe_function
[Histórico]
| Versão | Alterações |
|---|---|
| v14.5.0 | O suporte para napi_would_deadlock foi revertido. |
| v14.1.0 | Retorna napi_would_deadlock quando chamada com napi_tsfn_blocking da thread principal ou de uma thread de trabalho e a fila está cheia. |
| v10.6.0 | Adicionado em: v10.6.0 |
Versão 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: A função JavaScript assíncrona e thread-safe a ser invocada.[in] data: Dados a serem enviados para o JavaScript através do callbackcall_js_cbfornecido durante a criação da função JavaScript thread-safe.[in] is_blocking: Flag cujo valor pode sernapi_tsfn_blockingpara indicar que a chamada deve bloquear se a fila estiver cheia ounapi_tsfn_nonblockingpara indicar que a chamada deve retornar imediatamente com o statusnapi_queue_fullsempre que a fila estiver cheia.
Esta API não deve ser chamada com napi_tsfn_blocking de uma thread JavaScript, porque, se a fila estiver cheia, pode causar um deadlock na thread JavaScript.
Esta API retornará napi_closing se napi_release_threadsafe_function() foi chamada com abort definido como napi_tsfn_abort de qualquer thread. O valor só é adicionado à fila se a API retornar napi_ok.
Esta API pode ser chamada de qualquer thread que utilize func.
napi_acquire_threadsafe_function
Adicionado em: v10.6.0
Versão N-API: 4
NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);[in] func: A função JavaScript assíncrona e thread-safe para começar a utilizar.
Uma thread deve chamar esta API antes de passar func para qualquer outra API de função thread-safe para indicar que estará utilizando func. Isso impede que func seja destruída quando todas as outras threads pararem de utilizá-la.
Esta API pode ser chamada de qualquer thread que começará a utilizar func.
napi_release_threadsafe_function
Adicionado em: v10.6.0
Versão N-API: 4
NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
napi_threadsafe_function_release_mode mode);[in] func: A função JavaScript assíncrona thread-safe cuja contagem de referência será decrementada.[in] mode: Flag cujo valor pode sernapi_tsfn_releasepara indicar que a thread atual não fará mais chamadas à função thread-safe, ounapi_tsfn_abortpara indicar que, além da thread atual, nenhuma outra thread deve fazer mais chamadas à função thread-safe. Se definido comonapi_tsfn_abort, chamadas futuras paranapi_call_threadsafe_function()retornarãonapi_closinge nenhum valor adicional será colocado na fila.
Uma thread deve chamar esta API quando parar de usar func. Passar func para qualquer API thread-safe depois de ter chamado esta API tem resultados indefinidos, pois func pode ter sido destruído.
Esta API pode ser chamada de qualquer thread que irá parar de usar func.
napi_ref_threadsafe_function
Adicionado em: v10.6.0
Versão N-API: 4
NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);[in] env: O ambiente sob o qual a API é invocada.[in] func: A função thread-safe para referenciar.
Esta API é usada para indicar que o loop de eventos em execução na thread principal não deve sair até que func tenha sido destruído. Semelhante a uv_ref, também é idempotente.
Nem napi_unref_threadsafe_function marca as funções thread-safe como capazes de serem destruídas, nem napi_ref_threadsafe_function impede que ela seja destruída. napi_acquire_threadsafe_function e napi_release_threadsafe_function estão disponíveis para esse propósito.
Esta API só pode ser chamada a partir da thread principal.
napi_unref_threadsafe_function
Adicionado em: v10.6.0
Versão N-API: 4
NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);[in] env: O ambiente sob o qual a API é invocada.[in] func: A função thread-safe para remover a referência.
Esta API é usada para indicar que o loop de eventos em execução na thread principal pode sair antes que func seja destruído. Semelhante a uv_unref, também é idempotente.
Esta API só pode ser chamada a partir da thread principal.
Utilitários diversos
node_api_get_module_file_name
Adicionado em: v15.9.0, v14.18.0, v12.22.0
Versão N-API: 9
NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);[in] env: O ambiente em que a API é invocada.[out] result: Uma URL contendo o caminho absoluto do local de onde o complemento foi carregado. Para um arquivo no sistema de arquivos local, ele começará comfile://. A string é terminada em nulo e pertence aenve, portanto, não deve ser modificada ou liberada.
result pode ser uma string vazia se o processo de carregamento do complemento não conseguir estabelecer o nome do arquivo do complemento durante o carregamento.