Node-API¶
Стабильность: 2 - стабильная
Node-API (ранее N-API) - это API для создания собственных надстроек. Он не зависит от базовой среды выполнения JavaScript (например, V8) и поддерживается как часть самого Node.js. Этот API будет иметь двоичный интерфейс приложения (ABI), стабильный во всех версиях Node.js. Он предназначен для защиты надстроек от изменений в базовом движке JavaScript и позволяет модулям, скомпилированным для одной основной версии, работать в более поздних основных версиях Node.js без перекомпиляции. В Стабильность ABI руководство предоставляет более подробное объяснение.
Аддоны создаются / упаковываются с использованием того же подхода / инструментов, которые описаны в разделе, озаглавленном Дополнения C ++. Единственное отличие - это набор API, которые используются в машинном коде. Вместо использования V8 или Нативные абстракции для Node.js API, используются функции, доступные в Node-API.
API-интерфейсы, предоставляемые Node-API, обычно используются для создания и управления значениями JavaScript. Понятия и операции обычно соответствуют идеям, указанным в спецификации языка ECMA-262. У API есть следующие свойства:
- Все вызовы Node-API возвращают код состояния типа
napi_status
. Этот статус указывает, был ли вызов API успешным или неудачным. - Возвращаемое значение API передается через параметр out.
- Все значения JavaScript абстрагируются за непрозрачным типом с именем
napi_value
. - В случае кода состояния ошибки дополнительную информацию можно получить, используя
napi_get_last_error_info
. Более подробную информацию можно найти в разделе обработки ошибок. Обработка ошибок.
Node-API - это C API, который обеспечивает стабильность ABI в версиях Node.js и на разных уровнях компилятора. C ++ API может быть проще в использовании. Для поддержки использования C ++ в проекте поддерживается модуль-оболочка C ++, называемый node-addon-api
. Эта оболочка предоставляет встроенный C ++ API. Бинарные файлы, построенные с node-addon-api
будет зависеть от символов для функций на основе C Node-API, экспортируемых Node.js. node-addon-api
- более эффективный способ написания кода, вызывающего Node-API. Возьмем, например, следующие node-addon-api
код. Первый раздел показывает node-addon-api
код, а во втором разделе показано, что на самом деле используется в аддоне.
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;
}
Конечным результатом является то, что надстройка использует только экспортированные API-интерфейсы C. В результате он по-прежнему получает преимущества стабильности ABI, обеспечиваемой C API.
Когда используешь node-addon-api
вместо C API начните с API документы для node-addon-api
.
В Ресурс Node-APIпредлагает отличную ориентацию и советы для разработчиков, только начинающих работать с Node-API и node-addon-api
.
Последствия стабильности ABI¶
Хотя Node-API обеспечивает гарантию стабильности ABI, другие части Node.js этого не делают, а любые внешние библиотеки, используемые из надстройки, не могут. В частности, ни один из следующих API-интерфейсов не обеспечивает гарантии стабильности ABI в основных версиях:
- API-интерфейсы C ++ для Node.js, доступные через любой из
#include <node.h>
#include <node_buffer.h>
#include <node_version.h>
#include <node_object_wrap.h>
- API libuv, которые также включены в Node.js и доступны через
#include <uv.h>
- API V8 доступен через
#include <v8.h>
Таким образом, чтобы надстройка оставалась совместимой с ABI во всех основных версиях Node.js, она должна использовать исключительно Node-API, ограничивая себя использованием
#include <node_api.h>
и проверяя для всех используемых внешних библиотек, что внешняя библиотека обеспечивает гарантии стабильности ABI, аналогичные Node-API.
Строительство¶
В отличие от модулей, написанных на JavaScript, для разработки и развертывания собственных надстроек Node.js с использованием Node-API требуется дополнительный набор инструментов. Помимо основных инструментов, необходимых для разработки для Node.js, разработчику собственных аддонов требуется набор инструментов, который может компилировать код C и C ++ в двоичный файл. Кроме того, в зависимости от того, как развернут собственный аддон, Пользователь встроенного аддона также потребуется установить набор инструментов C / C ++.
Для разработчиков Linux доступны необходимые пакеты инструментальной цепочки C / C ++. GCC широко используется в сообществе Node.js для создания и тестирования на различных платформах. Для многих разработчиков LLVM Инфраструктура компилятора также является хорошим выбором.
Для разработчиков Mac: Xcode предлагает все необходимые инструменты компилятора. Однако нет необходимости устанавливать всю Xcode IDE. Следующая команда устанавливает необходимый набор инструментов:
xcode-select --install
Для разработчиков Windows: Visual Studio предлагает все необходимые инструменты компилятора. Однако нет необходимости устанавливать всю интегрированную среду разработки Visual Studio. Следующая команда устанавливает необходимый набор инструментов:
npm install --global windows-build-tools
В разделах ниже описаны дополнительные инструменты, доступные для разработки и развертывания собственных надстроек Node.js.
Инструменты сборки¶
Оба перечисленных здесь инструмента требуют, чтобы пользователи собственного надстройки имеют установленную цепочку инструментов C / C ++ для успешной установки собственного надстройки.
узел-гипс¶
узел-гипс это система сборки, основанная на gyp-next вилка Google GYP инструмент и поставляется в комплекте с npm. GYP и, следовательно, node-gyp, требуют установки Python.
Исторически сложилось так, что node-gyp был предпочтительным инструментом для создания собственных аддонов. Он получил широкое распространение и документацию. Однако некоторые разработчики столкнулись с ограничениями в node-gyp.
CMake.js¶
CMake.js альтернативная система сборки, основанная на CMake.
CMake.js - хороший выбор для проектов, которые уже используют CMake, или для разработчиков, на которых действуют ограничения в node-gyp.
Загрузка предварительно скомпилированных двоичных файлов¶
Три перечисленных здесь инструмента позволяют разработчикам и сопровождающим собственных надстроек создавать и загружать двоичные файлы на общедоступные или частные серверы. Эти инструменты обычно интегрируются с системами сборки CI / CD, такими как Трэвис Си а также AppVeyor для создания и загрузки двоичных файлов для различных платформ и архитектур. Затем эти двоичные файлы доступны для загрузки пользователям, которым не требуется установленный набор инструментов C / C ++.
узел-pre-gyp¶
узел-pre-gyp - это инструмент, основанный на node-gyp, который добавляет возможность загружать двоичные файлы на сервер по выбору разработчика. node-pre-gyp особенно хорошо поддерживает загрузку двоичных файлов в Amazon S3.
предварительная сборка¶
предварительная сборка - это инструмент, который поддерживает сборки с использованием node-gyp или CMake.js. В отличие от node-pre-gyp, который поддерживает множество серверов, prebuild загружает двоичные файлы только в Релизы GitHub. prebuild - хороший выбор для проектов GitHub, использующих CMake.js.
предварительно построить¶
предварительно построить это инструмент, основанный на node-gyp. Преимущество prebuildify заключается в том, что встроенные двоичные файлы связаны с собственным модулем при его загрузке в npm. Бинарные файлы загружаются из npm и сразу же доступны пользователю модуля после установки собственного модуля.
использование¶
Чтобы использовать функции Node-API, включите файл node_api.h
который находится в каталоге src в дереве разработки узла:
#include <node_api.h>
Это выберет значение по умолчанию NAPI_VERSION
для данного выпуска Node.js. Чтобы обеспечить совместимость с конкретными версиями Node-API, версию можно указать явно при включении заголовка:
#define NAPI_VERSION 3
#include <node_api.h>
Это ограничивает поверхность Node-API только функциональными возможностями, которые были доступны в указанных (и более ранних) версиях.
Некоторая часть поверхности Node-API является экспериментальной и требует явного согласия:
#define NAPI_EXPERIMENTAL
#include <node_api.h>
В этом случае для кода модуля будет доступна вся поверхность API, включая любые экспериментальные API.
Матрица версий Node-API¶
Версии Node-API аддитивны и контролируются независимо от Node.js. Версия 4 является расширением версии 3, поскольку в ней есть все API версии 3 с некоторыми дополнениями. Это означает, что нет необходимости перекомпилировать для новых версий Node.js, которые указаны как поддерживающие более позднюю версию.
1 | 2 | 3 | |
---|---|---|---|
v6.x | v6.14.2* | ||
v8.x | v8.6.0** | v8.10.0* | v8.11.2 |
v9.x | v9.0.0* | v9.3.0* | v9.11.0* |
≥ v10.x | all releases | all releases | all releases |
4 | 5 | 6 | 7 | 8 | |
---|---|---|---|---|---|
v10.x | v10.16.0 | v10.17.0 | v10.20.0 | v10.23.0 | |
v11.x | v11.8.0 | ||||
v12.x | v12.0.0 | v12.11.0 | v12.17.0 | v12.19.0 | v12.22.0 |
v13.x | v13.0.0 | v13.0.0 | |||
v14.x | v14.0.0 | v14.0.0 | v14.0.0 | v14.12.0 | v14.17.0 |
v15.x | v15.0.0 | v15.0.0 | v15.0.0 | v15.0.0 | v15.12.0 |
v16.x | v16.0.0 | v16.0.0 | v16.0.0 | v16.0.0 | v16.0.0 |
* Node-API был экспериментальным.
** Node.js 8.0.0 включал Node-API в качестве экспериментального. Он был выпущен как Node-API версии 1, но продолжал развиваться до Node.js 8.6.0. API отличается в версиях до Node.js 8.6.0. Мы рекомендуем Node-API версии 3 или новее.
Каждый API, документированный для Node-API, будет иметь заголовок с именем added in:
, а стабильные API будут иметь дополнительный заголовок Node-API version:
. API-интерфейсы можно использовать напрямую при использовании версии Node.js, которая поддерживает версию Node-API, показанную в Node-API version:
или выше. При использовании версии Node.js, не поддерживающей Node-API version:
в списке или если нет Node-API version:
в списке, то API будет доступен только в том случае, если #define NAPI_EXPERIMENTAL
предшествует включению node_api.h
или js_native_api.h
. Если API-интерфейс недоступен в версии Node.js, более поздней, чем та, которая показана в added in:
то это, скорее всего, причина явного отсутствия.
API-интерфейсы Node, связанные строго с доступом к функциям ECMAScript из собственного кода, можно найти отдельно в js_native_api.h
а также js_native_api_types.h
. API, определенные в этих заголовках, включены в node_api.h
а также node_api_types.h
. Заголовки структурированы таким образом, чтобы позволить реализации Node-API вне Node.js. Для этих реализаций специальные API-интерфейсы Node.js могут быть неприменимы.
Части надстройки, специфичные для Node.js, могут быть отделены от кода, который предоставляет фактическую функциональность среде JavaScript, чтобы последняя могла использоваться с несколькими реализациями Node-API. В приведенном ниже примере addon.c
а также addon.h
относятся только к js_native_api.h
. Это гарантирует, что addon.c
можно повторно использовать для компиляции либо реализации Node-API в Node.js, либо любой реализации Node-API за пределами Node.js.
addon_node.c
- это отдельный файл, содержащий конкретную точку входа Node.js в аддон и создающий экземпляр аддона путем вызова addon.c
когда аддон загружается в среду 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 NAPI_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); \
bool is_pending; \
napi_is_exception_pending((env), &is_pending); \
if (!is_pending) { \
const char* message = (error_info->error_message == NULL) \
? "empty error message" \
: error_info->error_message; \
napi_throw_error((env), NULL, message); \
return NULL; \
} \
} \
} while(0)
static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
// Do something useful.
return NULL;
}
napi_value create_addon(napi_env env) {
napi_value result;
NAPI_CALL(env, napi_create_object(env, &result));
napi_value exported_function;
NAPI_CALL(env, napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function));
NAPI_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() {
// This function body is expected to return a `napi_value`.
// The variables `napi_env env` and `napi_value exports` may be used within
// the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
return create_addon(env);
}
API жизненного цикла среды¶
Раздел 8.7 принадлежащий Спецификация языка ECMAScript определяет понятие «Агент» как автономную среду, в которой выполняется код JavaScript. Несколько таких Агентов могут быть запущены и завершены процессом одновременно или последовательно.
Среда Node.js соответствует агенту ECMAScript. В основном процессе среда создается при запуске, и дополнительные среды могут быть созданы в отдельных потоках, чтобы служить в качестве рабочие потоки. Когда Node.js встроен в другое приложение, основной поток приложения также может создавать и уничтожать среду Node.js несколько раз в течение жизненного цикла процесса приложения, так что каждая среда Node.js, созданная приложением, может в В свою очередь, в течение своего жизненного цикла создают и уничтожают дополнительные среды в качестве рабочих потоков.
С точки зрения собственного надстройки это означает, что предоставляемые им привязки могут вызываться несколько раз, из разных контекстов и даже одновременно из нескольких потоков.
Собственным аддонам может потребоваться выделить глобальное состояние, которое они используют в течение всего своего жизненного цикла, так что состояние должно быть уникальным для каждого экземпляра аддона.
С этой целью Node-API предоставляет способ распределения данных таким образом, чтобы их жизненный цикл был привязан к жизненному циклу агента.
napi_set_instance_data¶
napi_status napi_set_instance_data(napi_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] data
: Элемент данных, который нужно сделать доступным для привязок этого экземпляра.[in] finalize_cb
: Функция, вызываемая при сносе среды. Функция получаетdata
чтобы он мог освободить его.napi_finalize
предоставляет более подробную информацию.[in] finalize_hint
: Необязательная подсказка для перехода к обратному вызову finalize во время сбора.
Возврат napi_ok
если API удалось.
Этот API связывает data
с текущим работающим агентом. data
позже можно будет получить, используя napi_get_instance_data()
. Любые существующие данные, связанные с текущим работающим агентом, которые были установлены посредством предыдущего вызова napi_set_instance_data()
будет перезаписан. Если finalize_cb
был предоставлен предыдущим вызовом, он не будет вызван.
napi_get_instance_data¶
napi_status napi_get_instance_data(napi_env env,
void** data);
[in] env
: Среда, в которой вызывается вызов Node-API.[out] data
: Элемент данных, который ранее был связан с текущим работающим агентом при вызовеnapi_set_instance_data()
.
Возврат napi_ok
если API удалось.
Этот API извлекает данные, которые ранее были связаны с текущим запущенным агентом через napi_set_instance_data()
. Если данные не установлены, вызов будет успешным и data
будет установлен на NULL
.
Базовые типы данных Node-API¶
Node-API предоставляет следующие основные типы данных как абстракции, которые используются различными API. Эти API-интерфейсы следует рассматривать как непрозрачные, интроспектируемые только с другими вызовами Node-API.
napi_status¶
Интегральный код состояния, указывающий на успешность или неудачу вызова Node-API. В настоящее время поддерживаются следующие коды состояния.
typedef enum {
napi_ok,
napi_invalid_arg,
napi_object_expected,
napi_string_expected,
napi_name_expected,
napi_function_expected,
napi_number_expected,
napi_boolean_expected,
napi_array_expected,
napi_generic_failure,
napi_pending_exception,
napi_cancelled,
napi_escape_called_twice,
napi_handle_scope_mismatch,
napi_callback_scope_mismatch,
napi_queue_full,
napi_closing,
napi_bigint_expected,
napi_date_expected,
napi_arraybuffer_expected,
napi_detachable_arraybuffer_expected,
napi_would_deadlock, /* unused */
} napi_status;
Если после возврата API-интерфейсом статуса ошибки требуется дополнительная информация, ее можно получить, позвонив napi_get_last_error_info
.
napi_extended_error_info¶
typedef struct {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
} napi_extended_error_info;
error_message
: Строка в кодировке UTF8, содержащая описание ошибки, не зависящее от виртуальной машины.engine_reserved
: Зарезервировано для сведений об ошибках, связанных с виртуальной машиной. В настоящее время это не реализовано ни для одной виртуальной машины.engine_error_code
: Код ошибки, характерной для виртуальной машины. В настоящее время это не реализовано ни для одной виртуальной машины.error_code
: Код состояния Node-API, возникший при последней ошибке.
Увидеть Обработка ошибок раздел для дополнительной информации.
napi_env¶
napi_env
используется для представления контекста, который базовая реализация Node-API может использовать для сохранения состояния виртуальной машины. Эта структура передается встроенным функциям при их вызове и должна быть передана обратно при вызове Node-API. Конкретно то же самое napi_env
который был передан при вызове исходной собственной функции, должен быть передан любым последующим вложенным вызовам Node-API. Кеширование napi_env
с целью повторного использования и передачи napi_env
между экземплярами одного и того же аддона, запущенного на разных Worker
темы не допускается. В napi_env
становится недействительным, когда экземпляр собственного надстройки выгружается. Уведомление об этом событии доставляется через обратные вызовы, предоставленные napi_add_env_cleanup_hook
а также napi_set_instance_data
.
napi_value¶
Это непрозрачный указатель, который используется для представления значения JavaScript.
napi_threadsafe_function¶
Это непрозрачный указатель, представляющий функцию JavaScript, которую можно вызывать асинхронно из нескольких потоков через napi_call_threadsafe_function()
.
napi_threadsafe_function_release_mode¶
Значение, которое нужно присвоить napi_release_threadsafe_function()
чтобы указать, следует ли немедленно закрыть потокобезопасную функцию (napi_tsfn_abort
) или просто выпущен (napi_tsfn_release
) и, следовательно, доступны для последующего использования через napi_acquire_threadsafe_function()
а также napi_call_threadsafe_function()
.
typedef enum {
napi_tsfn_release,
napi_tsfn_abort
} napi_threadsafe_function_release_mode;
napi_threadsafe_function_call_mode¶
Значение, которое нужно присвоить napi_call_threadsafe_function()
чтобы указать, должен ли вызов блокироваться всякий раз, когда очередь, связанная с поточно-ориентированной функцией, заполнена.
typedef enum {
napi_tsfn_nonblocking,
napi_tsfn_blocking
} napi_threadsafe_function_call_mode;
Типы управления памятью Node-API¶
napi_handle_scope¶
Это абстракция, используемая для управления и изменения времени жизни объектов, созданных в определенной области. Как правило, значения Node-API создаются в контексте области дескриптора. Когда собственный метод вызывается из JavaScript, будет существовать область дескриптора по умолчанию. Если пользователь явно не создает новую область дескриптора, значения Node-API будут созданы в области дескриптора по умолчанию. Для любых вызовов кода вне выполнения собственного метода (например, во время вызова обратного вызова libuv) модуль должен создать область действия перед вызовом любых функций, которые могут привести к созданию значений JavaScript.
Области ручки создаются с использованием napi_open_handle_scope
и уничтожаются с использованием napi_close_handle_scope
. Закрытие области может указать для GC, что все napi_value
s, созданные во время существования области дескриптора, больше не ссылаются на текущий кадр стека.
Для получения более подробной информации просмотрите Управление жизненным циклом объекта.
napi_escapable_handle_scope¶
Экранируемые области дескриптора - это особый тип области дескриптора, который возвращает значения, созданные в определенной области дескриптора, в родительскую область.
napi_ref¶
Это абстракция для ссылки на napi_value
. Это позволяет пользователям управлять временем жизни значений JavaScript, включая явное определение минимального времени жизни.
Для получения более подробной информации просмотрите Управление жизненным циклом объекта.
napi_type_tag¶
128-битное значение, хранящееся как два 64-битных целых числа без знака. Он служит UUID, с помощью которого объекты JavaScript могут быть «помечены», чтобы гарантировать, что они относятся к определенному типу. Это более сильная проверка, чем napi_instanceof
, потому что последний может сообщить о ложном срабатывании, если прототип объекта был изменен. Тегирование типов наиболее полезно в сочетании с napi_wrap
потому что он гарантирует, что указатель, полученный из обернутого объекта, может быть безопасно приведен к собственному типу, соответствующему тегу типа, который ранее был применен к объекту JavaScript.
typedef struct {
uint64_t lower;
uint64_t upper;
} napi_type_tag;
napi_async_cleanup_hook_handle¶
Непрозрачное значение, возвращаемое napi_add_async_cleanup_hook
. Это должно быть передано napi_remove_async_cleanup_hook
когда цепочка асинхронных событий очистки завершается.
Типы обратного вызова Node-API¶
napi_callback_info¶
Непрозрачный тип данных, который передается функции обратного вызова. Его можно использовать для получения дополнительной информации о контексте, в котором был вызван обратный вызов.
napi_callback¶
Тип указателя функции для собственных функций, предоставляемых пользователем, которые должны быть представлены в JavaScript через Node-API. Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef napi_value (*napi_callback)(napi_env, napi_callback_info);
Если по причинам, указанным в Управление сроком службы объекта, создавая дескриптор и / или область обратного вызова внутри napi_callback
не обязательно.
napi_finalize¶
Тип указателя функции для дополнительных функций, которые позволяют пользователю получать уведомления, когда данные, принадлежащие извне, готовы к очистке, поскольку объект, с которым они были связаны, был собран сборщиком мусора. Пользователь должен предоставить функцию, удовлетворяющую следующей сигнатуре, которая будет вызываться для коллекции объекта. В настоящее время, napi_finalize
может использоваться для определения, когда собираются объекты с внешними данными.
typedef void (*napi_finalize)(napi_env env,
void* finalize_data,
void* finalize_hint);
Если по причинам, указанным в Управление сроком службы объектасоздание дескриптора и / или области обратного вызова внутри тела функции не требуется.
napi_async_execute_callback¶
Указатель на функцию, используемый с функциями, поддерживающими асинхронные операции. Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_async_execute_callback)(napi_env env, void* data);
Реализации этой функции должны избегать вызовов Node-API, которые выполняют JavaScript или взаимодействуют с объектами JavaScript. Вызовы Node-API должны быть в napi_async_complete_callback
вместо. Не используйте napi_env
параметр, так как это, скорее всего, приведет к выполнению JavaScript.
napi_async_complete_callback¶
Указатель на функцию, используемый с функциями, поддерживающими асинхронные операции. Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);
Если по причинам, указанным в Управление сроком службы объектасоздание дескриптора и / или области обратного вызова внутри тела функции не требуется.
napi_threadsafe_function_call_js¶
Указатель на функцию, используемый с вызовами асинхронных поточно-ориентированных функций. Обратный вызов будет вызываться в основном потоке. Его цель - использовать элемент данных, поступающий через очередь из одного из вторичных потоков, для создания параметров, необходимых для вызова в JavaScript, обычно через napi_call_function
, а затем вызовите JavaScript.
Данные, поступающие из вторичного потока через очередь, представлены в data
параметр и вызываемая функция JavaScript указаны в js_callback
параметр.
Node-API настраивает среду перед вызовом этого обратного вызова, поэтому достаточно вызвать функцию JavaScript через napi_call_function
а не через napi_make_callback
.
Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_threadsafe_function_call_js)(napi_env env,
napi_value js_callback,
void* context,
void* data);
[in] env
: Среда, используемая для вызовов API, илиNULL
если потокобезопасная функция срывается иdata
может потребоваться освободить.[in] js_callback
: Вызываемая функция JavaScript илиNULL
если потокобезопасная функция срывается иdata
может потребоваться освободить. Это также может бытьNULL
если потокобезопасная функция была создана безjs_callback
.[in] context
: Необязательные данные, с которыми была создана поточно-ориентированная функция.[in] data
: Данные, созданные вторичным потоком. Обратный вызов отвечает за преобразование этих собственных данных в значения JavaScript (с функциями Node-API), которые могут быть переданы как параметры, когдаjs_callback
вызывается. Этот указатель полностью управляется потоками и этим обратным вызовом. Таким образом, этот обратный вызов должен освободить данные.
Если по причинам, указанным в Управление сроком службы объектасоздание дескриптора и / или области обратного вызова внутри тела функции не требуется.
napi_async_cleanup_hook¶
Указатель на функцию, используемый с napi_add_async_cleanup_hook
. Он будет вызываться при сносе среды.
Функции обратного вызова должны соответствовать следующей сигнатуре:
typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
void* data);
[in] handle
: Дескриптор, который должен быть передан вnapi_remove_async_cleanup_hook
после завершения асинхронной очистки.[in] data
: Данные, переданные вnapi_add_async_cleanup_hook
.
Тело функции должно инициировать асинхронные действия по очистке, в конце которых handle
должен быть передан в вызове napi_remove_async_cleanup_hook
.
Обработка ошибок¶
Node-API использует как возвращаемые значения, так и исключения JavaScript для обработки ошибок. В следующих разделах объясняется подход для каждого случая.
Возвращаемые значения¶
Все функции Node-API используют один и тот же шаблон обработки ошибок. Тип возврата всех функций API: napi_status
.
Возвращаемое значение будет napi_ok
если запрос был успешным и не было сгенерировано неперехваченное исключение JavaScript. Если произошла ошибка И было сгенерировано исключение, napi_status
будет возвращено значение ошибки. Если было сгенерировано исключение и ошибки не было, napi_pending_exception
будет возвращен.
В случаях, когда возвращаемое значение, отличное от napi_ok
или napi_pending_exception
возвращается, napi_is_exception_pending
должен быть вызван, чтобы проверить, ожидает ли исключение. См. Более подробную информацию в разделе об исключениях.
Полный набор возможных napi_status
значения определены в napi_api_types.h
.
В napi_status
Возвращаемое значение обеспечивает независимое от виртуальной машины представление произошедшей ошибки. В некоторых случаях полезно иметь возможность получить более подробную информацию, включая строку, представляющую ошибку, а также информацию, относящуюся к виртуальной машине (движку).
Чтобы получить эту информацию napi_get_last_error_info
предоставляется, который возвращает napi_extended_error_info
состав. Формат napi_extended_error_info
структура выглядит следующим образом:
typedef struct napi_extended_error_info {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
};
error_message
: Текстовое представление возникшей ошибки.engine_reserved
: Непрозрачная ручка предназначена только для использования с двигателем.engine_error_code
: Код ошибки виртуальной машины.error_code
: Код статуса Node-API для последней ошибки.
napi_get_last_error_info
возвращает информацию о последнем сделанном вызове Node-API.
Не полагайтесь на содержание или формат какой-либо расширенной информации, поскольку она не подлежит SemVer и может измениться в любое время. Он предназначен только для ведения журнала.
napi_get_last_error_info¶
napi_status
napi_get_last_error_info(napi_env env,
const napi_extended_error_info** result);
[in] env
: Среда, в которой вызывается API.[out] result
: Thenapi_extended_error_info
структура с дополнительной информацией об ошибке.
Возврат napi_ok
если API удалось.
Этот API получает napi_extended_error_info
структура с информацией о последней произошедшей ошибке.
Содержание napi_extended_error_info
возвращенный действителен только до тех пор, пока функция Node-API не будет вызвана на том же самом env
.
Не полагайтесь на содержание или формат какой-либо расширенной информации, поскольку она не подлежит SemVer и может измениться в любое время. Он предназначен только для ведения журнала.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
Исключения¶
Любой вызов функции Node-API может привести к отложенному исключению JavaScript. Это относится к любой из функций API, даже к тем, которые не могут вызывать выполнение JavaScript.
Если napi_status
возвращается функцией napi_ok
то исключение не ожидается и никаких дополнительных действий не требуется. Если napi_status
возвращается что-либо кроме napi_ok
или napi_pending_exception
, чтобы попытаться восстановиться и продолжить, а не просто немедленно вернуться, napi_is_exception_pending
должен быть вызван, чтобы определить, ожидает ли исключение или нет.
Во многих случаях, когда вызывается функция Node-API и исключение уже ожидает обработки, функция немедленно возвращается с napi_status
из napi_pending_exception
. Однако это относится не ко всем функциям. Node-API позволяет вызывать подмножество функций для минимальной очистки перед возвратом к JavaScript. В этом случае, napi_status
будет отражать статус функции. Он не будет отражать предыдущие ожидающие исключения. Чтобы избежать путаницы, проверяйте статус ошибки после каждого вызова функции.
Когда ожидается исключение, можно использовать один из двух подходов.
Первый подход - выполнить любую соответствующую очистку, а затем вернуться, чтобы выполнение вернулось к JavaScript. В рамках перехода обратно на JavaScript исключение будет выдано в той точке кода JavaScript, где был вызван собственный метод. Поведение большинства вызовов Node-API не определено, пока ожидается исключение, и многие просто вернут napi_pending_exception
, поэтому сделайте как можно меньше, а затем вернитесь к JavaScript, где можно будет обработать исключение.
Второй подход - попытаться обработать исключение. Бывают случаи, когда собственный код может перехватить исключение, предпринять соответствующее действие и затем продолжить. Это рекомендуется только в особых случаях, когда известно, что исключение можно безопасно обработать. В этих случаях napi_get_and_clear_last_exception
может использоваться для получения и удаления исключения. В случае успеха результат будет содержать дескриптор последнего JavaScript. Object
брошен. Если он определен, после получения исключения исключение не может быть обработано, в конце концов, его можно повторно выбросить с помощью napi_throw
где error - это генерируемое значение JavaScript.
Следующие служебные функции также доступны в случае, если машинному коду необходимо вызвать исключение или определить, napi_value
является экземпляром JavaScript Error
объект: napi_throw_error
, napi_throw_type_error
, napi_throw_range_error
а также napi_is_error
.
Следующие служебные функции также доступны в случае, если собственный код должен создать Error
объект: napi_create_error
, napi_create_type_error
, а также napi_create_range_error
, где результатом является napi_value
это относится к недавно созданному JavaScript Error
объект.
Проект Node.js добавляет коды ошибок ко всем внутренним ошибкам. Цель состоит в том, чтобы приложения использовали эти коды ошибок для всех проверок ошибок. Связанные сообщения об ошибках останутся, но будут использоваться только для регистрации и отображения с ожиданием того, что сообщение может измениться без применения SemVer. Чтобы поддерживать эту модель с помощью Node-API, как во внутренней функциональности, так и для специфической функциональности модуля (в качестве хорошей практики), throw_
а также create_
функции принимают необязательный параметр кода, который представляет собой строку кода, добавляемого к объекту ошибки. Если необязательный параметр NULL
тогда никакой код не будет связан с ошибкой. Если предоставлен код, имя, связанное с ошибкой, также обновляется и будет выглядеть следующим образом:
originalName [code]
куда originalName
- исходное имя, связанное с ошибкой, и code
это код, который был предоставлен. Например, если код 'ERR_ERROR_1'
и TypeError
создается имя будет:
TypeError [ERR_ERROR_1]
napi_throw¶
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);
[in] env
: Среда, в которой вызывается API.[in] error
: Выбрасываемое значение JavaScript.
Возврат napi_ok
если API удалось.
Этот API выдает предоставленное значение JavaScript.
napi_throw_error¶
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
const char* code,
const char* msg);
[in] env
: Среда, в которой вызывается API.[in] code
: Необязательный код ошибки, который должен быть установлен для ошибки.[in] msg
: Строка C, представляющая текст, который будет связан с ошибкой.
Возврат napi_ok
если API удалось.
Этот API выдает JavaScript Error
с предоставленным текстом.
napi_throw_type_error¶
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
const char* code,
const char* msg);
[in] env
: Среда, в которой вызывается API.[in] code
: Необязательный код ошибки, который должен быть установлен для ошибки.[in] msg
: Строка C, представляющая текст, который будет связан с ошибкой.
Возврат napi_ok
если API удалось.
Этот API выдает JavaScript TypeError
с предоставленным текстом.
napi_throw_range_error¶
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
const char* code,
const char* msg);
[in] env
: Среда, в которой вызывается API.[in] code
: Необязательный код ошибки, который должен быть установлен для ошибки.[in] msg
: Строка C, представляющая текст, который будет связан с ошибкой.
Возврат napi_ok
если API удалось.
Этот API выдает JavaScript RangeError
с предоставленным текстом.
napi_is_error¶
NAPI_EXTERN napi_status napi_is_error(napi_env env,
napi_value value,
bool* result);
[in] env
: Среда, в которой вызывается API.[in] value
: Thenapi_value
быть проверенным.[out] result
: Логическое значение, равное истине, еслиnapi_value
представляет ошибку, в противном случае - false.
Возврат napi_ok
если API удалось.
Этот API запрашивает napi_value
чтобы проверить, представляет ли он объект ошибки.
napi_create_error¶
NAPI_EXTERN napi_status napi_create_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] code
: По желаниюnapi_value
со строкой кода ошибки, которая будет связана с ошибкой.[in] msg
:napi_value
который ссылается на JavaScriptstring
использоваться в качестве сообщения дляError
.[out] result
:napi_value
представляющий созданную ошибку.
Возврат napi_ok
если API удалось.
Этот API возвращает JavaScript Error
с предоставленным текстом.
napi_create_type_error¶
NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] code
: По желаниюnapi_value
со строкой кода ошибки, которая будет связана с ошибкой.[in] msg
:napi_value
который ссылается на JavaScriptstring
использоваться в качестве сообщения дляError
.[out] result
:napi_value
представляющий созданную ошибку.
Возврат napi_ok
если API удалось.
Этот API возвращает JavaScript TypeError
с предоставленным текстом.
napi_create_range_error¶
NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] code
: По желаниюnapi_value
со строкой кода ошибки, которая будет связана с ошибкой.[in] msg
:napi_value
который ссылается на JavaScriptstring
использоваться в качестве сообщения дляError
.[out] result
:napi_value
представляющий созданную ошибку.
Возврат napi_ok
если API удалось.
Этот API возвращает JavaScript RangeError
с предоставленным текстом.
napi_get_and_clear_last_exception¶
napi_status napi_get_and_clear_last_exception(napi_env env,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[out] result
: Исключение, если одно ожидает рассмотрения,NULL
иначе.
Возврат napi_ok
если API удалось.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
napi_is_exception_pending¶
napi_status napi_is_exception_pending(napi_env env, bool* result);
[in] env
: Среда, в которой вызывается API.[out] result
: Логическое значение, которое имеет значение true, если исключение ожидает обработки.
Возврат napi_ok
если API удалось.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
napi_fatal_exception¶
napi_status napi_fatal_exception(napi_env env, napi_value err);
[in] env
: Среда, в которой вызывается API.[in] err
: Ошибка, передаваемая в'uncaughtException'
.
Запустить 'uncaughtException'
в JavaScript. Полезно, если асинхронный обратный вызов вызывает исключение без возможности восстановления.
Неустранимые ошибки¶
В случае неисправимой ошибки в собственном модуле может возникнуть фатальная ошибка, которая немедленно завершит процесс.
napi_fatal_error¶
NAPI_NO_RETURN void napi_fatal_error(const char* location,
size_t location_len,
const char* message,
size_t message_len);
[in] location
: Необязательное расположение, в котором произошла ошибка.[in] location_len
: Длина местоположения в байтах, илиNAPI_AUTO_LENGTH
если он заканчивается нулем.[in] message
: Сообщение, связанное с ошибкой.[in] message_len
: Длина сообщения в байтах, илиNAPI_AUTO_LENGTH
если он заканчивается нулем.
Вызов функции не возвращается, процесс будет завершен.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
Управление жизненным циклом объекта¶
Когда выполняются вызовы Node-API, дескрипторы объектов в куче для базовой виртуальной машины могут быть возвращены как napi_values
. Эти дескрипторы должны удерживать объекты «вживую» до тех пор, пока они не перестанут быть нужны машинному коду, в противном случае объекты могут быть собраны до того, как машинный код завершит их использование.
Когда возвращаются дескрипторы объектов, они связаны с «областью действия». Продолжительность жизни для области по умолчанию привязана к продолжительности жизни вызова собственного метода. В результате по умолчанию дескрипторы остаются действительными, а объекты, связанные с этими дескрипторами, будут оставаться в рабочем состоянии в течение всего срока службы вызова собственного метода.
Однако во многих случаях необходимо, чтобы дескрипторы оставались действительными в течение более короткого или более длительного срока службы, чем у собственного метода. В следующих разделах описываются функции Node-API, которые можно использовать для изменения срока службы дескриптора по умолчанию.
Уменьшение срока службы ручки по сравнению с родным методом¶
Часто бывает необходимо сделать срок жизни дескрипторов короче, чем продолжительность жизни собственного метода. Например, рассмотрим собственный метод, который имеет цикл, который выполняет итерацию по элементам в большом массиве:
for (int i = 0; i < 1000000; i++) {
napi_value result;
napi_status status = napi_get_element(env, object, i, &result);
if (status != napi_ok) {
break;
}
// do something with element
}
Это приведет к созданию большого количества дескрипторов, потребляющих значительные ресурсы. Кроме того, даже если собственный код может использовать только самый последний дескриптор, все связанные объекты также будут оставаться активными, поскольку все они имеют одну и ту же область.
Чтобы справиться с этим случаем, Node-API предоставляет возможность установить новую «область», с которой будут связаны вновь созданные дескрипторы. Как только эти дескрипторы больше не требуются, область действия может быть «закрыта», а любые дескрипторы, связанные с областью действия, становятся недействительными. Доступные методы для открытия / закрытия областей: napi_open_handle_scope
а также napi_close_handle_scope
.
Node-API поддерживает только одну вложенную иерархию областей видимости. В любой момент времени существует только одна активная область, и все новые дескрипторы будут связаны с этой областью, пока она активна. Области должны быть закрыты в порядке, обратном их открытию. Кроме того, все области, созданные в собственном методе, должны быть закрыты перед возвратом из этого метода.
Взяв предыдущий пример, добавив вызовы к napi_open_handle_scope
а также napi_close_handle_scope
будет гарантировать, что не более одного дескриптора будет действительным во время выполнения цикла:
for (int i = 0; i < 1000000; i++) {
napi_handle_scope scope;
napi_status status = napi_open_handle_scope(env, &scope);
if (status != napi_ok) {
break;
}
napi_value result;
status = napi_get_element(env, object, i, &result);
if (status != napi_ok) {
break;
}
// do something with element
status = napi_close_handle_scope(env, scope);
if (status != napi_ok) {
break;
}
}
При вложении областей видимости бывают случаи, когда дескриптор внутренней области видимости должен существовать за пределами срока ее существования. Node-API поддерживает «экранируемую область» для поддержки этого случая. Экранируемая область позволяет «продвинуть» один дескриптор, чтобы он «ускользнул» из текущей области, и срок жизни дескриптора изменится с текущей области на внешнюю.
Методы, доступные для открытия / закрытия экранируемых областей: napi_open_escapable_handle_scope
а также napi_close_escapable_handle_scope
.
Запрос на продвижение дескриптора осуществляется через napi_escape_handle
который можно вызвать только один раз.
napi_open_handle_scope¶
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
napi_handle_scope* result);
[in] env
: Среда, в которой вызывается API.[out] result
:napi_value
представляющий новую область видимости.
Возврат napi_ok
если API удалось.
Этот API открывает новые возможности.
napi_close_handle_scope¶
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
napi_handle_scope scope);
[in] env
: Среда, в которой вызывается API.[in] scope
:napi_value
представляющий объем, который должен быть закрыт.
Возврат napi_ok
если API удалось.
Этот API закрывает переданную область. Области должны быть закрыты в порядке, обратном тому, в котором они были созданы.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
napi_open_escapable_handle_scope¶
NAPI_EXTERN napi_status
napi_open_escapable_handle_scope(napi_env env,
napi_handle_scope* result);
[in] env
: Среда, в которой вызывается API.[out] result
:napi_value
представляющий новую область видимости.
Возврат napi_ok
если API удалось.
Этот API открывает новую область видимости, из которой один объект может быть продвинут во внешнюю область.
napi_close_escapable_handle_scope¶
NAPI_EXTERN napi_status
napi_close_escapable_handle_scope(napi_env env,
napi_handle_scope scope);
[in] env
: Среда, в которой вызывается API.[in] scope
:napi_value
представляющий объем, который должен быть закрыт.
Возврат napi_ok
если API удалось.
Этот API закрывает переданную область. Области должны быть закрыты в порядке, обратном тому, в котором они были созданы.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
napi_escape_handle¶
napi_status napi_escape_handle(napi_env env,
napi_escapable_handle_scope scope,
napi_value escapee,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] scope
:napi_value
представляющий текущую область видимости.[in] escapee
:napi_value
представляющий JavaScriptObject
чтобы сбежать.[out] result
:napi_value
представляющий дескриптор сбежавшегоObject
во внешнем объеме.
Возврат napi_ok
если API удалось.
Этот API продвигает дескриптор объекта JavaScript, чтобы он действовал в течение всего времени существования внешней области. Его можно вызвать только один раз для каждой области. Если он вызывается более одного раза, будет возвращена ошибка.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
Ссылки на объекты, срок жизни которых больше, чем у собственного метода¶
В некоторых случаях надстройка должна иметь возможность создавать и ссылаться на объекты со сроком службы дольше, чем у одного вызова собственного метода. Например, чтобы создать конструктор, а затем использовать этот конструктор в запросе для создания экземпляров, должна быть возможность ссылаться на объект конструктора во многих различных запросах на создание экземпляров. Это было бы невозможно с обычным дескриптором, возвращенным как napi_value
как описано в предыдущем разделе. Срок службы обычного дескриптора управляется областями, и все области должны быть закрыты до завершения собственного метода.
Node-API предоставляет методы для создания постоянных ссылок на объект. Каждая постоянная ссылка имеет связанный счетчик со значением 0 или выше. Счетчик определяет, будет ли ссылка поддерживать соответствующий объект в рабочем состоянии. Ссылки со счетом 0 не препятствуют сбору объекта и часто называются «слабыми» ссылками. Любое значение счетчика больше 0 предотвратит сбор объекта.
Ссылки могут быть созданы с начальным счетчиком ссылок. Затем счетчик можно изменить с помощью napi_reference_ref
а также napi_reference_unref
. Если объект собирается, пока счетчик ссылки равен 0, все последующие вызовы для получения объекта, связанного со ссылкой napi_get_reference_value
вернусь NULL
для возвращенных napi_value
. Попытка позвонить napi_reference_ref
для ссылки, объект которой был собран, приводит к ошибке.
Ссылки должны быть удалены, если они больше не нужны аддону. Когда ссылка удаляется, это больше не препятствует сбору соответствующего объекта. Неспособность удалить постоянную ссылку приводит к «утечке памяти», когда как внутренняя память для постоянной ссылки, так и соответствующий объект в куче остаются навсегда.
Может быть создано несколько постоянных ссылок, которые ссылаются на один и тот же объект, каждая из которых либо будет поддерживать объект в рабочем состоянии, либо не будет зависеть от его индивидуального счетчика.
napi_create_reference¶
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
napi_value value,
uint32_t initial_refcount,
napi_ref* result);
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющийObject
на который нам нужна ссылка.[in] initial_refcount
: Начальный счетчик ссылок для новой ссылки.[out] result
:napi_ref
указывая на новую ссылку.
Возврат napi_ok
если API удалось.
Этот API создает новую ссылку с указанным счетчиком ссылок на Object
прошел внутрь.
napi_delete_reference¶
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);
[in] env
: Среда, в которой вызывается API.[in] ref
:napi_ref
быть удаленным.
Возврат napi_ok
если API удалось.
Этот API удаляет переданную ссылку.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
napi_reference_ref¶
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
napi_ref ref,
uint32_t* result);
[in] env
: Среда, в которой вызывается API.[in] ref
:napi_ref
для которого счетчик ссылок будет увеличиваться.[out] result
: Новый счетчик ссылок.
Возврат napi_ok
если API удалось.
Этот API увеличивает счетчик ссылок для переданной ссылки и возвращает результирующий счетчик ссылок.
napi_reference_unref¶
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
napi_ref ref,
uint32_t* result);
[in] env
: Среда, в которой вызывается API.[in] ref
:napi_ref
для которого счетчик ссылок будет уменьшен.[out] result
: Новый счетчик ссылок.
Возврат napi_ok
если API удалось.
Этот API уменьшает счетчик ссылок для переданной ссылки и возвращает результирующий счетчик ссылок.
napi_get_reference_value¶
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
napi_ref ref,
napi_value* result);
в napi_value passed
в этих методах или вне их - дескриптор объекта, к которому относится ссылка.
[in] env
: Среда, в которой вызывается API.[in] ref
:napi_ref
для чего мы запрашиваем соответствующиеObject
.[out] result
: Thenapi_value
дляObject
упомянутыйnapi_ref
.
Возврат napi_ok
если API удалось.
Если все еще действителен, этот API возвращает napi_value
представляющий JavaScript Object
связанный с napi_ref
. В противном случае результат будет NULL
.
Очистка при выходе из текущего экземпляра Node.js¶
В то время как процесс Node.js обычно освобождает все свои ресурсы при выходе, встраивающие устройства Node.js или будущая поддержка Worker могут потребовать надстройки для регистрации обработчиков очистки, которые будут запускаться после выхода из текущего экземпляра Node.js.
Node-API предоставляет функции для регистрации и отмены регистрации таких обратных вызовов. Когда эти обратные вызовы выполняются, все ресурсы, удерживаемые надстройкой, должны быть освобождены.
napi_add_env_cleanup_hook¶
NODE_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env,
void (*fun)(void* arg),
void* arg);
Регистры fun
как функция, запускаемая с arg
после выхода из текущей среды Node.js.
Функцию можно безопасно указывать несколько раз с разными arg
ценности. В этом случае он также будет вызываться несколько раз. Обеспечение того же fun
а также arg
значений несколько раз не допускается и приведет к прерыванию процесса.
Перехватчики будут вызываться в обратном порядке, то есть первым будет вызываться последний добавленный.
Удалить этот крючок можно с помощью napi_remove_env_cleanup_hook
. Обычно это происходит, когда ресурс, для которого был добавлен этот перехватчик, все равно удаляется.
Для асинхронной очистки napi_add_async_cleanup_hook
доступен.
napi_remove_env_cleanup_hook¶
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env,
void (*fun)(void* arg),
void* arg);
Отменить регистрацию fun
как функция, запускаемая с arg
после выхода из текущей среды Node.js. И аргумент, и значение функции должны точно совпадать.
Функция должна быть изначально зарегистрирована с napi_add_env_cleanup_hook
, иначе процесс будет прерван.
napi_add_async_cleanup_hook¶
NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
napi_env env,
napi_async_cleanup_hook hook,
void* arg,
napi_async_cleanup_hook_handle* remove_handle);
[in] env
: Среда, в которой вызывается API.[in] hook
: Указатель на функцию, вызываемую при разрыве среды.[in] arg
: Указатель для перехода кhook
когда его называют.[out] remove_handle
: Необязательный дескриптор, который относится к обработчику асинхронной очистки.
Регистры hook
, которая является функцией типа napi_async_cleanup_hook
, как функция, запускаемая с remove_handle
а также arg
параметры после выхода из текущей среды Node.js.
В отличие от napi_add_env_cleanup_hook
, ловушка может быть асинхронной.
В противном случае поведение обычно совпадает с поведением napi_add_env_cleanup_hook
.
Если remove_handle
не является NULL
, в нем будет сохранено непрозрачное значение, которое позже необходимо передать в napi_remove_async_cleanup_hook
, независимо от того, был ли уже запущен перехватчик. Обычно это происходит, когда ресурс, для которого был добавлен этот перехватчик, все равно удаляется.
napi_remove_async_cleanup_hook¶
NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
napi_async_cleanup_hook_handle remove_handle);
[in] remove_handle
: Дескриптор обработчика асинхронной очистки, созданного с помощьюnapi_add_async_cleanup_hook
.
Отменяет регистрацию обработчика очистки, соответствующего remove_handle
. Это предотвратит выполнение ловушки, если она еще не началась. Это должно быть вызвано любым napi_async_cleanup_hook_handle
значение, полученное от napi_add_async_cleanup_hook
.
Регистрация модуля¶
Модули Node-API регистрируются аналогично другим модулям, за исключением того, что вместо использования NODE_MODULE
макрос используется следующее:
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
Следующее отличие - подпись для Init
метод. Для модуля Node-API это выглядит следующим образом:
napi_value Init(napi_env env, napi_value exports);
Возвращаемое значение из Init
рассматривается как exports
объект для модуля. В Init
метод передается пустой объект через exports
параметр для удобства. Если Init
возвращается NULL
, параметр передается как exports
экспортируется модулем. Модули Node-API не могут изменять module
объект, но может указать что угодно как exports
свойство модуля.
Чтобы добавить метод hello
как функцию, чтобы ее можно было вызвать как метод, предоставляемый аддоном:
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;
}
Чтобы установить функцию, возвращаемую require()
для аддона:
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;
}
Чтобы определить класс, чтобы можно было создавать новые экземпляры (часто используется с Перенос объекта):
// NOTE: partial example, not all referenced code is included
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;
}
Вы также можете использовать NAPI_MODULE_INIT
макрос, который действует как сокращение для NAPI_MODULE
и определение Init
функция:
NAPI_MODULE_INIT() {
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;
}
Все надстройки Node-API зависят от контекста, что означает, что они могут загружаться несколько раз. При объявлении такого модуля необходимо учитывать несколько конструктивных соображений. Документация по контекстно-зависимые надстройки предоставляет более подробную информацию.
Переменные env
а также exports
будет доступен внутри тела функции после вызова макроса.
Дополнительные сведения о настройке свойств объектов см. В разделе, посвященном Работа со свойствами JavaScript.
Дополнительные сведения о создании дополнительных модулей в целом см. В существующем API.
Работа со значениями JavaScript¶
Node-API предоставляет набор API для создания всех типов значений JavaScript. Некоторые из этих типов описаны в Раздел 6 принадлежащий Спецификация языка ECMAScript.
По сути, эти API-интерфейсы используются для выполнения одного из следующих действий:
- Создайте новый объект JavaScript
- Преобразование из примитивного типа C в значение Node-API
- Преобразование из значения Node-API в примитивный тип C
- Получите глобальные экземпляры, включая
undefined
а такжеnull
Значения Node-API представлены типом napi_value
. Любой вызов Node-API, для которого требуется значение JavaScript, принимает napi_value
. В некоторых случаях API проверяет тип napi_value
аванс. Однако для повышения производительности вызывающей стороне лучше убедиться, что napi_value
речь идет о типе JavaScript, ожидаемом API.
Типы перечислений¶
napi_key_collection_mode¶
typedef enum {
napi_key_include_prototypes,
napi_key_own_only
} napi_key_collection_mode;
Описывает Keys/Properties
перечисления фильтров:
napi_key_collection_mode
ограничивает диапазон собираемых свойств.
napi_key_own_only
ограничивает собранные свойства только заданным объектом. napi_key_include_prototypes
также будет включать все ключи цепочки прототипов объектов.
napi_key_filter¶
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;
Биты фильтра свойств. Их можно использовать для создания составного фильтра.
napi_key_conversion¶
typedef enum {
napi_key_keep_numbers,
napi_key_numbers_to_strings
} napi_key_conversion;
napi_key_numbers_to_strings
преобразует целочисленные индексы в строки. napi_key_keep_numbers
вернет числа для целочисленных индексов.
napi_valuetype¶
typedef enum {
// ES6 types (corresponds to typeof)
napi_undefined,
napi_null,
napi_boolean,
napi_number,
napi_string,
napi_symbol,
napi_object,
napi_function,
napi_external,
napi_bigint,
} napi_valuetype;
Описывает тип napi_value
. Обычно это соответствует типам, описанным в Раздел 6.1 спецификации языка ECMAScript. Помимо типов в этом разделе, napi_valuetype
может также представлять Function
песок Object
s с внешними данными.
Значение типа JavaScript napi_external
отображается в JavaScript как простой объект, поэтому для него нельзя задать свойства и прототип.
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;
Это представляет собой базовый двоичный скалярный тип данных TypedArray
. Элементы этого перечисления соответствуют Раздел 22.2 принадлежащий Спецификация языка ECMAScript.
Функции создания объекта¶
napi_create_array¶
napi_status napi_create_array(napi_env env, napi_value* result)
[in] env
: Среда, в которой вызывается вызов Node-API.[out] result
: Аnapi_value
представляющий JavaScriptArray
.
Возврат napi_ok
если API удалось.
Этот API возвращает значение Node-API, соответствующее JavaScript. Array
тип. Массивы JavaScript описаны в Раздел 22.1 спецификации языка ECMAScript.
napi_create_array_with_length¶
napi_status napi_create_array_with_length(napi_env env,
size_t length,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] length
: Начальная длинаArray
.[out] result
: Аnapi_value
представляющий JavaScriptArray
.
Возврат napi_ok
если API удалось.
Этот API возвращает значение Node-API, соответствующее JavaScript. Array
тип. В Array
Свойство length установлено в переданный параметр длины. Однако не гарантируется, что базовый буфер будет предварительно выделен виртуальной машиной при создании массива. Это поведение оставлено на усмотрение базовой реализации виртуальной машины. Если буфер должен быть непрерывным блоком памяти, который может быть непосредственно прочитан и / или записан через C, рассмотрите возможность использования napi_create_external_arraybuffer
.
Массивы JavaScript описаны в Раздел 22.1 спецификации языка ECMAScript.
napi_create_arraybuffer¶
napi_status napi_create_arraybuffer(napi_env env,
size_t byte_length,
void** data,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] length
: Длина в байтах создаваемого буфера массива.[out] data
: Указатель на нижележащий байтовый буферArrayBuffer
.[out] result
: Аnapi_value
представляющий JavaScriptArrayBuffer
.
Возврат napi_ok
если API удалось.
Этот API возвращает значение Node-API, соответствующее JavaScript. ArrayBuffer
. ArrayBuffer
s используются для представления буферов двоичных данных фиксированной длины. Обычно они используются в качестве резервного буфера для TypedArray
объекты. В ArrayBuffer
распределенный будет иметь нижележащий байтовый буфер, размер которого определяется length
переданный параметр. Базовый буфер необязательно возвращается обратно вызывающей стороне в случае, если вызывающая сторона хочет напрямую манипулировать буфером. В этот буфер можно записать только непосредственно из машинного кода. Чтобы записать в этот буфер из JavaScript, типизированный массив или DataView
объект необходимо будет создать.
JavaScript ArrayBuffer
объекты описаны в Раздел 24.1 спецификации языка ECMAScript.
napi_create_buffer¶
napi_status napi_create_buffer(napi_env env,
size_t size,
void** data,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] size
: Размер нижележащего буфера в байтах.[out] data
: Необработанный указатель на базовый буфер.[out] result
: Аnapi_value
представляющийnode::Buffer
.
Возврат napi_ok
если API удалось.
Этот API выделяет node::Buffer
объект. Хотя это все еще полностью поддерживаемая структура данных, в большинстве случаев с использованием TypedArray
будет достаточно.
napi_create_buffer_copy¶
napi_status napi_create_buffer_copy(napi_env env,
size_t length,
const void* data,
void** result_data,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] size
: Размер входного буфера в байтах (должен быть таким же, как размер нового буфера).[in] data
: Необработанный указатель на базовый буфер для копирования.[out] result_data
: Указатель на новыйBuffer
базовый буфер данных.[out] result
: Аnapi_value
представляющийnode::Buffer
.
Возврат napi_ok
если API удалось.
Этот API выделяет node::Buffer
объект и инициализирует его данными, скопированными из переданного буфера. Хотя это все еще полностью поддерживаемая структура данных, в большинстве случаев с использованием TypedArray
будет достаточно.
napi_create_date¶
napi_status napi_create_date(napi_env env,
double time,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] time
: Значение времени ECMAScript в миллисекундах с 1 января 1970 года по всемирному координированному времени.[out] result
: Аnapi_value
представляющий JavaScriptDate
.
Возврат napi_ok
если API удалось.
Этот API не учитывает дополнительных секунд; они игнорируются, поскольку ECMAScript соответствует спецификации времени POSIX.
Этот API выделяет JavaScript Date
объект.
JavaScript Date
объекты описаны в Раздел 20.3 спецификации языка ECMAScript.
napi_create_external¶
napi_status napi_create_external(napi_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] data
: Необработанный указатель на внешние данные.[in] finalize_cb
: Дополнительный обратный вызов для вызова при сборе внешнего значения.napi_finalize
предоставляет более подробную информацию.[in] finalize_hint
: Необязательная подсказка для перехода к обратному вызову finalize во время сбора.[out] result
: Аnapi_value
представляющий внешнюю ценность.
Возврат napi_ok
если API удалось.
Этот API выделяет значение JavaScript с прикрепленными к нему внешними данными. Он используется для передачи внешних данных через код JavaScript, поэтому их можно получить позже с помощью собственного кода, используя napi_get_value_external
.
API добавляет napi_finalize
обратный вызов, который будет вызван, когда только что созданный объект JavaScript будет готов для сборки мусора. Это похоже на napi_wrap()
Кроме этого:
- собственные данные не могут быть получены позже с помощью
napi_unwrap()
, - и его нельзя удалить позже, используя
napi_remove_wrap()
, а также - объект, созданный API, можно использовать с
napi_wrap()
.
Созданное значение не является объектом и поэтому не поддерживает дополнительные свойства. Он считается отдельным типом значения: вызов napi_typeof()
с внешним значением дает napi_external
.
napi_create_external_arraybuffer¶
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
: Среда, в которой вызывается API.[in] external_data
: Указатель на нижележащий байтовый буферArrayBuffer
.[in] byte_length
: Длина в байтах нижележащего буфера.[in] finalize_cb
: Дополнительный обратный вызов для вызова, когдаArrayBuffer
собирается.napi_finalize
предоставляет более подробную информацию.[in] finalize_hint
: Необязательная подсказка для перехода к обратному вызову finalize во время сбора.[out] result
: Аnapi_value
представляющий JavaScriptArrayBuffer
.
Возврат napi_ok
если API удалось.
Этот API возвращает значение Node-API, соответствующее JavaScript. ArrayBuffer
. Базовый байтовый буфер ArrayBuffer
распределяется и управляется извне. Вызывающий должен гарантировать, что байтовый буфер остается действительным до тех пор, пока не будет вызван обратный вызов finalize.
API добавляет napi_finalize
обратный вызов, который будет вызван, когда только что созданный объект JavaScript будет готов для сборки мусора. Это похоже на napi_wrap()
Кроме этого:
- собственные данные не могут быть получены позже с помощью
napi_unwrap()
, - и его нельзя удалить позже, используя
napi_remove_wrap()
, а также - объект, созданный API, можно использовать с
napi_wrap()
.
JavaScript ArrayBuffer
описаны в Раздел 24.1 спецификации языка ECMAScript.
napi_create_external_buffer¶
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
: Среда, в которой вызывается API.[in] length
: Размер входного буфера в байтах (должен быть таким же, как размер нового буфера).[in] data
: Необработанный указатель на базовый буфер для доступа к JavaScript.[in] finalize_cb
: Дополнительный обратный вызов для вызова, когдаArrayBuffer
собирается.napi_finalize
предоставляет более подробную информацию.[in] finalize_hint
: Необязательная подсказка для перехода к обратному вызову finalize во время сбора.[out] result
: Аnapi_value
представляющийnode::Buffer
.
Возврат napi_ok
если API удалось.
Этот API выделяет node::Buffer
объект и инициализирует его данными, поддерживаемыми переданным в буфере. Хотя это все еще полностью поддерживаемая структура данных, в большинстве случаев с использованием TypedArray
будет достаточно.
API добавляет napi_finalize
обратный вызов, который будет вызван, когда только что созданный объект JavaScript будет готов для сборки мусора. Это похоже на napi_wrap()
Кроме этого:
- собственные данные не могут быть получены позже с помощью
napi_unwrap()
, - и его нельзя удалить позже, используя
napi_remove_wrap()
, а также - объект, созданный API, можно использовать с
napi_wrap()
.
Для Node.js> = 4 Buffers
находятся Uint8Array
с.
napi_create_object¶
napi_status napi_create_object(napi_env env, napi_value* result)
[in] env
: Среда, в которой вызывается API.[out] result
: Аnapi_value
представляющий JavaScriptObject
.
Возврат napi_ok
если API удалось.
Этот API выделяет JavaScript по умолчанию Object
. Это эквивалент выполнения new Object()
в JavaScript.
JavaScript Object
тип описан в Раздел 6.1.7 спецификации языка ECMAScript.
napi_create_symbol¶
napi_status napi_create_symbol(napi_env env,
napi_value description,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] description
: По желаниюnapi_value
который относится к JavaScriptstring
быть установленным в качестве описания символа.[out] result
: Аnapi_value
представляющий JavaScriptsymbol
.
Возврат napi_ok
если API удалось.
Этот API создает JavaScript symbol
значение из строки C в кодировке UTF8.
JavaScript symbol
тип описан в Раздел 19.4 спецификации языка ECMAScript.
napi_create_typedarray¶
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
: Среда, в которой вызывается API.[in] type
: Скалярный тип данных элементов внутриTypedArray
.[in] length
: Количество элементов вTypedArray
.[in] arraybuffer
:ArrayBuffer
лежащий в основе типизированного массива.[in] byte_offset
: Байтовое смещение внутриArrayBuffer
с которого можно начать проектированиеTypedArray
.[out] result
: Аnapi_value
представляющий JavaScriptTypedArray
.
Возврат napi_ok
если API удалось.
Этот API создает JavaScript TypedArray
объект над существующим ArrayBuffer
. TypedArray
объекты обеспечивают представление в виде массива над базовым буфером данных, где каждый элемент имеет один и тот же базовый двоичный скалярный тип данных.
Требуется, чтобы (length * size_of_element) + byte_offset
должен быть <= размер переданного массива в байтах. Если нет, RangeError
возникает исключение.
JavaScript TypedArray
объекты описаны в Раздел 22.2 спецификации языка ECMAScript.
napi_create_dataview¶
napi_status napi_create_dataview(napi_env env,
size_t byte_length,
napi_value arraybuffer,
size_t byte_offset,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] length
: Количество элементов вDataView
.[in] arraybuffer
:ArrayBuffer
лежащий в основеDataView
.[in] byte_offset
: Байтовое смещение внутриArrayBuffer
с которого можно начать проектированиеDataView
.[out] result
: Аnapi_value
представляющий JavaScriptDataView
.
Возврат napi_ok
если API удалось.
Этот API создает JavaScript DataView
объект над существующим ArrayBuffer
. DataView
объекты обеспечивают представление в виде массива над нижележащим буфером данных, но такое, которое позволяет элементам разного размера и типа в ArrayBuffer
.
Требуется, чтобы byte_length + byte_offset
меньше или равен размеру переданного массива в байтах. Если нет, RangeError
возникает исключение.
JavaScript DataView
объекты описаны в Раздел 24.3 спецификации языка ECMAScript.
Функции для преобразования из типов C в Node-API¶
napi_create_int32¶
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Целочисленное значение, которое будет представлено в JavaScript.[out] result
: Аnapi_value
представляющий JavaScriptnumber
.
Возврат napi_ok
если API удалось.
Этот API используется для преобразования из C int32_t
введите в JavaScript number
тип.
JavaScript number
тип описан в Раздел 6.1.6 спецификации языка ECMAScript.
napi_create_uint32¶
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Целочисленное значение без знака, которое будет представлено в JavaScript.[out] result
: Аnapi_value
представляющий JavaScriptnumber
.
Возврат napi_ok
если API удалось.
Этот API используется для преобразования из C uint32_t
введите в JavaScript number
тип.
JavaScript number
тип описан в Раздел 6.1.6 спецификации языка ECMAScript.
napi_create_int64¶
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Целочисленное значение, которое будет представлено в JavaScript.[out] result
: Аnapi_value
представляющий JavaScriptnumber
.
Возврат napi_ok
если API удалось.
Этот API используется для преобразования из C int64_t
введите в JavaScript number
тип.
JavaScript number
тип описан в Раздел 6.1.6 спецификации языка ECMAScript. Обратите внимание на полный спектр int64_t
не могут быть представлены с полной точностью в JavaScript. Целочисленные значения вне диапазона Number.MIN_SAFE_INTEGER
-(2**53 - 1)
- Number.MAX_SAFE_INTEGER
(2**53 - 1)
потеряет точность.
napi_create_double¶
napi_status napi_create_double(napi_env env, double value, napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение двойной точности для представления в JavaScript.[out] result
: Аnapi_value
представляющий JavaScriptnumber
.
Возврат napi_ok
если API удалось.
Этот API используется для преобразования из C double
введите в JavaScript number
тип.
JavaScript number
тип описан в Раздел 6.1.6 спецификации языка ECMAScript.
napi_create_bigint_int64¶
napi_status napi_create_bigint_int64(napi_env env,
int64_t value,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] value
: Целочисленное значение, которое будет представлено в JavaScript.[out] result
: Аnapi_value
представляющий JavaScriptBigInt
.
Возврат napi_ok
если API удалось.
Этот API преобразует C int64_t
введите в JavaScript BigInt
тип.
napi_create_bigint_uint64¶
napi_status napi_create_bigint_uint64(napi_env env,
uint64_t value,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] value
: Целочисленное значение без знака, которое будет представлено в JavaScript.[out] result
: Аnapi_value
представляющий JavaScriptBigInt
.
Возврат napi_ok
если API удалось.
Этот API преобразует C uint64_t
введите в JavaScript BigInt
тип.
napi_create_bigint_words¶
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
: Среда, в которой вызывается API.[in] sign_bit
: Определяет, есть ли в результатеBigInt
будет положительным или отрицательным.[in] word_count
: Длинаwords
множество.[in] words
: Массивuint64_t
64-битные слова с прямым порядком байтов.[out] result
: Аnapi_value
представляющий JavaScriptBigInt
.
Возврат napi_ok
если API удалось.
Этот API преобразует массив 64-битных слов без знака в один BigInt
ценить.
Результирующий BigInt
рассчитывается как: (–1)sign_bit
(words[0]
× (264)0 + words[1]
× (264)1 +…)
napi_create_string_latin1¶
napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] str
: Символьный буфер, представляющий строку в кодировке ISO-8859-1.[in] length
: Длина строки в байтах, илиNAPI_AUTO_LENGTH
если он заканчивается нулем.[out] result
: Аnapi_value
представляющий JavaScriptstring
.
Возврат napi_ok
если API удалось.
Этот API создает JavaScript string
значение из строки C в кодировке ISO-8859-1. Собственная строка копируется.
JavaScript string
тип описан в Раздел 6.1.4 спецификации языка ECMAScript.
napi_create_string_utf16¶
napi_status napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] str
: Символьный буфер, представляющий строку в кодировке UTF16-LE.[in] length
: Длина строки в двухбайтовых единицах кода, илиNAPI_AUTO_LENGTH
если он заканчивается нулем.[out] result
: Аnapi_value
представляющий JavaScriptstring
.
Возврат napi_ok
если API удалось.
Этот API создает JavaScript string
значение из строки C в кодировке UTF16-LE. Собственная строка копируется.
JavaScript string
тип описан в Раздел 6.1.4 спецификации языка ECMAScript.
napi_create_string_utf8¶
napi_status napi_create_string_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] str
: Символьный буфер, представляющий строку в кодировке UTF8.[in] length
: Длина строки в байтах, илиNAPI_AUTO_LENGTH
если он заканчивается нулем.[out] result
: Аnapi_value
представляющий JavaScriptstring
.
Возврат napi_ok
если API удалось.
Этот API создает JavaScript string
значение из строки C в кодировке UTF8. Собственная строка копируется.
JavaScript string
тип описан в Раздел 6.1.4 спецификации языка ECMAScript.
Функции для преобразования из Node-API в типы C¶
napi_get_array_length¶
napi_status napi_get_array_length(napi_env env,
napi_value value,
uint32_t* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptArray
длина которого запрашивается.[out] result
:uint32
представляющий длину массива.
Возврат napi_ok
если API удалось.
Этот API возвращает длину массива.
Array
длина описана в Раздел 22.1.4.1 спецификации языка ECMAScript.
napi_get_arraybuffer_info¶
napi_status napi_get_arraybuffer_info(napi_env env,
napi_value arraybuffer,
void** data,
size_t* byte_length)
[in] env
: Среда, в которой вызывается API.[in] arraybuffer
:napi_value
представляющийArrayBuffer
запрашивается.[out] data
: Базовый буфер данныхArrayBuffer
. Если byte_length равно0
, это может бытьNULL
или любое другое значение указателя.[out] byte_length
: Длина в байтах основного буфера данных.
Возврат napi_ok
если API удалось.
Этот API используется для получения базового буфера данных ArrayBuffer
и его длина.
ПРЕДУПРЕЖДЕНИЕ: Будьте осторожны при использовании этого API. Время жизни нижележащего буфера данных управляется ArrayBuffer
даже после того, как его вернули. Возможный безопасный способ использования этого API - в сочетании с napi_create_reference
, который можно использовать, чтобы гарантировать контроль над временем жизни ArrayBuffer
. Также безопасно использовать возвращаемый буфер данных в том же обратном вызове, пока нет вызовов других API, которые могут вызвать GC.
napi_get_buffer_info¶
napi_status napi_get_buffer_info(napi_env env,
napi_value value,
void** data,
size_t* length)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющийnode::Buffer
запрашивается.[out] data
: Базовый буфер данныхnode::Buffer
. Если длина0
, это может бытьNULL
или любое другое значение указателя.[out] length
: Длина в байтах основного буфера данных.
Возврат napi_ok
если API удалось.
Этот API используется для получения базового буфера данных node::Buffer
и его длина.
Предупреждение: Соблюдайте осторожность при использовании этого API, поскольку срок службы базового буфера данных не гарантируется, если он управляется виртуальной машиной.
napi_get_prototype¶
napi_status napi_get_prototype(napi_env env,
napi_value object,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] object
:napi_value
представляющий JavaScriptObject
чей прототип вернуть. Это возвращает эквивалентObject.getPrototypeOf
(что не то же самое, что функцияprototype
имущество).[out] result
:napi_value
представляющий прототип данного объекта.
Возврат napi_ok
если API удалось.
napi_get_typedarray_info¶
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
: Среда, в которой вызывается API.[in] typedarray
:napi_value
представляющийTypedArray
чьи свойства запрашивать.[out] type
: Скалярный тип данных элементов внутриTypedArray
.[out] length
: Количество элементов вTypedArray
.[out] data
: Буфер данных, лежащий в основеTypedArray
скорректированоbyte_offset
значение так, чтобы оно указывало на первый элемент вTypedArray
. Если длина массива равна0
, это может бытьNULL
или любое другое значение указателя.[out] arraybuffer
: TheArrayBuffer
лежащий в основеTypedArray
.[out] byte_offset
: Байтовое смещение в базовом собственном массиве, в котором расположен первый элемент массивов. Значение параметра данных уже настроено так, чтобы данные указывали на первый элемент в массиве. Следовательно, первый байт собственного массива будет вdata - byte_offset
.
Возврат napi_ok
если API удалось.
Этот API возвращает различные свойства типизированного массива.
Предупреждение: Будьте осторожны при использовании этого API, так как базовый буфер данных управляется виртуальной машиной.
napi_get_dataview_info¶
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
: Среда, в которой вызывается API.[in] dataview
:napi_value
представляющийDataView
чьи свойства запрашивать.[out] byte_length
: Количество байтов вDataView
.[out] data
: Буфер данных, лежащий в основеDataView
. Если byte_length равно0
, это может бытьNULL
или любое другое значение указателя.[out] arraybuffer
:ArrayBuffer
лежащий в основеDataView
.[out] byte_offset
: Байтовое смещение в буфере данных, с которого начинается проецированиеDataView
.
Возврат napi_ok
если API удалось.
Этот API возвращает различные свойства DataView
.
napi_get_date_value¶
napi_status napi_get_date_value(napi_env env,
napi_value value,
double* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptDate
.[out] result
: Временная стоимость какdouble
представлены в миллисекундах с полуночи в начале 1 января 1970 года по всемирному координированному времени.
Этот API не учитывает дополнительных секунд; они игнорируются, поскольку ECMAScript соответствует спецификации времени POSIX.
Возврат napi_ok
если API удалось. Если не свидание napi_value
передается в это возвращается napi_date_expected
.
Этот API возвращает примитив C double значения времени для данного JavaScript. Date
.
napi_get_value_bool¶
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptBoolean
.[out] result
: C логический примитивный эквивалент данного JavaScriptBoolean
.
Возврат napi_ok
если API удалось. Если не логическое napi_value
передается в это возвращается napi_boolean_expected
.
Этот API возвращает логический примитивный эквивалент C данного JavaScript. Boolean
.
napi_get_value_double¶
napi_status napi_get_value_double(napi_env env,
napi_value value,
double* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptnumber
.[out] result
: C двойной примитивный эквивалент данного JavaScriptnumber
.
Возврат napi_ok
если API удалось. Если не число napi_value
передается в это возвращается napi_number_expected
.
Этот API возвращает двойной примитивный эквивалент C данного JavaScript. number
.
napi_get_value_bigint_int64¶
napi_status napi_get_value_bigint_int64(napi_env env,
napi_value value,
int64_t* result,
bool* lossless);
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptBigInt
.[out] result
: Cint64_t
примитивный эквивалент данного JavaScriptBigInt
.[out] lossless
: Указывает, есть лиBigInt
стоимость была конвертирована без потерь.
Возврат napi_ok
если API удалось. Если не-BigInt
передается в это возвращается napi_bigint_expected
.
Этот API возвращает C int64_t
примитивный эквивалент данного JavaScript BigInt
. При необходимости он обрежет значение, установив lossless
к false
.
napi_get_value_bigint_uint64¶
napi_status napi_get_value_bigint_uint64(napi_env env,
napi_value value,
uint64_t* result,
bool* lossless);
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptBigInt
.[out] result
: Cuint64_t
примитивный эквивалент данного JavaScriptBigInt
.[out] lossless
: Указывает, есть лиBigInt
стоимость была конвертирована без потерь.
Возврат napi_ok
если API удалось. Если не-BigInt
передается в это возвращается napi_bigint_expected
.
Этот API возвращает C uint64_t
примитивный эквивалент данного JavaScript BigInt
. При необходимости он обрежет значение, установив lossless
к false
.
napi_get_value_bigint_words¶
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
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptBigInt
.[out] sign_bit
: Целое число, представляющее, если JavaScriptBigInt
положительный или отрицательный.[in/out] word_count
: Должен быть инициализирован длинойwords
множество. По возвращении будет установлено фактическое количество слов, которые потребуются для хранения этогоBigInt
.[out] words
: Указатель на заранее выделенный массив 64-битных слов.
Возврат napi_ok
если API удалось.
Этот API преобразует один BigInt
значение в знаковый бит, 64-битный массив с прямым порядком байтов и количество элементов в массиве. sign_bit
а также words
оба могут быть установлены на NULL
, чтобы получить только word_count
.
napi_get_value_external¶
napi_status napi_get_value_external(napi_env env,
napi_value value,
void** result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий внешнее значение JavaScript.[out] result
: Указатель на данные, заключенные во внешнее значение JavaScript.
Возврат napi_ok
если API удалось. Если невнешний napi_value
передается в это возвращается napi_invalid_arg
.
Этот API извлекает указатель внешних данных, который ранее был передан в napi_create_external()
.
napi_get_value_int32¶
napi_status napi_get_value_int32(napi_env env,
napi_value value,
int32_t* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptnumber
.[out] result
: Cint32
примитивный эквивалент данного JavaScriptnumber
.
Возврат napi_ok
если API удалось. Если не число napi_value
передается в napi_number_expected
.
Этот API возвращает C int32
примитивный эквивалент данного JavaScript number
.
Если число превышает диапазон 32-битного целого числа, результат обрезается до эквивалента нижних 32-х битов. Это может привести к тому, что большое положительное число станет отрицательным, если значение> 2.31 год - 1.
Неограниченные числовые значения (NaN
, +Infinity
, или -Infinity
) установите результат равным нулю.
napi_get_value_int64¶
napi_status napi_get_value_int64(napi_env env,
napi_value value,
int64_t* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptnumber
.[out] result
: Cint64
примитивный эквивалент данного JavaScriptnumber
.
Возврат napi_ok
если API удалось. Если не число napi_value
передается в это возвращается napi_number_expected
.
Этот API возвращает C int64
примитивный эквивалент данного JavaScript number
.
number
значения вне диапазона Number.MIN_SAFE_INTEGER
-(2**53 - 1)
- Number.MAX_SAFE_INTEGER
(2**53 - 1)
потеряет точность.
Неограниченные числовые значения (NaN
, +Infinity
, или -Infinity
) установите результат равным нулю.
napi_get_value_string_latin1¶
napi_status napi_get_value_string_latin1(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий строку JavaScript.[in] buf
: Буфер для записи строки в кодировке ISO-8859-1. ЕслиNULL
передается, длина строки в байтах и без нулевого терминатора возвращается вresult
.[in] bufsize
: Размер целевого буфера. Когда этого значения недостаточно, возвращаемая строка усекается и заканчивается нулем.[out] result
: Количество байтов, скопированных в буфер, без нулевого терминатора.
Возврат napi_ok
если API удалось. Если не-string
napi_value
передается в это возвращается napi_string_expected
.
Этот API возвращает строку в кодировке ISO-8859-1, соответствующую переданному значению.
napi_get_value_string_utf8¶
napi_status napi_get_value_string_utf8(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий строку JavaScript.[in] buf
: Буфер для записи строки в кодировке UTF8. ЕслиNULL
передается, длина строки в байтах и без нулевого терминатора возвращается вresult
.[in] bufsize
: Размер целевого буфера. Когда этого значения недостаточно, возвращаемая строка усекается и заканчивается нулем.[out] result
: Количество байтов, скопированных в буфер, без нулевого терминатора.
Возврат napi_ok
если API удалось. Если не-string
napi_value
передается в это возвращается napi_string_expected
.
Этот API возвращает строку в кодировке UTF8, соответствующую переданному значению.
napi_get_value_string_utf16¶
napi_status napi_get_value_string_utf16(napi_env env,
napi_value value,
char16_t* buf,
size_t bufsize,
size_t* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий строку JavaScript.[in] buf
: Буфер для записи строки в кодировке UTF16-LE. ЕслиNULL
передается, возвращается длина строки в 2-байтовых единицах кода, исключая нулевой терминатор.[in] bufsize
: Размер целевого буфера. Когда этого значения недостаточно, возвращаемая строка усекается и заканчивается нулем.[out] result
: Количество 2-байтовых кодовых единиц, скопированных в буфер, исключая нулевой терминатор.
Возврат napi_ok
если API удалось. Если не-string
napi_value
передается в это возвращается napi_string_expected
.
Этот API возвращает строку в кодировке UTF16, соответствующую переданному значению.
napi_get_value_uint32¶
napi_status napi_get_value_uint32(napi_env env,
napi_value value,
uint32_t* result)
[in] env
: Среда, в которой вызывается API.[in] value
:napi_value
представляющий JavaScriptnumber
.[out] result
: C примитивный эквивалент данногоnapi_value
какuint32_t
.
Возврат napi_ok
если API удалось. Если не число napi_value
передается в это возвращается napi_number_expected
.
Этот API возвращает примитивный эквивалент C заданного napi_value
как uint32_t
.
Функции для получения глобальных экземпляров¶
napi_get_boolean¶
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение получаемого логического значения.[out] result
:napi_value
представляющий JavaScriptBoolean
синглтон для получения.
Возврат napi_ok
если API удалось.
Этот API используется для возврата одноэлементного объекта JavaScript, который используется для представления заданного логического значения.
napi_get_global¶
napi_status napi_get_global(napi_env env, napi_value* result)
[in] env
: Среда, в которой вызывается API.[out] result
:napi_value
представляющий JavaScriptglobal
объект.
Возврат napi_ok
если API удалось.
Этот API возвращает global
объект.
napi_get_null¶
napi_status napi_get_null(napi_env env, napi_value* result)
[in] env
: Среда, в которой вызывается API.[out] result
:napi_value
представляющий JavaScriptnull
объект.
Возврат napi_ok
если API удалось.
Этот API возвращает null
объект.
napi_get_undefined¶
napi_status napi_get_undefined(napi_env env, napi_value* result)
[in] env
: Среда, в которой вызывается API.[out] result
:napi_value
представляет неопределенное значение JavaScript.
Возврат napi_ok
если API удалось.
Этот API возвращает неопределенный объект.
Работа со значениями JavaScript и абстрактными операциями¶
Node-API предоставляет набор API-интерфейсов для выполнения некоторых абстрактных операций со значениями JavaScript. Некоторые из этих операций задокументированы в Раздел 7 принадлежащий Спецификация языка ECMAScript.
Эти API-интерфейсы поддерживают выполнение одного из следующих действий:
- Приводить значения JavaScript к определенным типам JavaScript (например,
number
илиstring
). - Проверьте тип значения JavaScript.
- Проверьте равенство между двумя значениями JavaScript.
napi_coerce_to_bool¶
napi_status napi_coerce_to_bool(napi_env env,
napi_value value,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для принуждения.[out] result
:napi_value
представляющий принудительный JavaScriptBoolean
.
Возврат napi_ok
если API удалось.
Этот API реализует абстрактную операцию ToBoolean()
как определено в Раздел 7.1.2 спецификации языка ECMAScript.
napi_coerce_to_number¶
napi_status napi_coerce_to_number(napi_env env,
napi_value value,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для принуждения.[out] result
:napi_value
представляющий принудительный JavaScriptnumber
.
Возврат napi_ok
если API удалось.
Этот API реализует абстрактную операцию ToNumber()
как определено в Раздел 7.1.3 спецификации языка ECMAScript. Эта функция потенциально запускает JS-код, если переданное значение является объектом.
napi_coerce_to_object¶
napi_status napi_coerce_to_object(napi_env env,
napi_value value,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для принуждения.[out] result
:napi_value
представляющий принудительный JavaScriptObject
.
Возврат napi_ok
если API удалось.
Этот API реализует абстрактную операцию ToObject()
как определено в Раздел 7.1.13 спецификации языка ECMAScript.
napi_coerce_to_string¶
napi_status napi_coerce_to_string(napi_env env,
napi_value value,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для принуждения.[out] result
:napi_value
представляющий принудительный JavaScriptstring
.
Возврат napi_ok
если API удалось.
Этот API реализует абстрактную операцию ToString()
как определено в Раздел 7.1.13 спецификации языка ECMAScript. Эта функция потенциально запускает JS-код, если переданное значение является объектом.
napi_typeof¶
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript, тип которого запрашивается.[out] result
: Тип значения JavaScript.
Возврат napi_ok
если API удалось.
napi_invalid_arg
если типvalue
не является известным типом ECMAScript иvalue
не является внешним значением.
Этот API представляет поведение, аналогичное вызову typeof
Оператор объекта, как определено в Раздел 12.5.5 спецификации языка ECMAScript. Однако есть некоторые отличия:
- Он поддерживает определение внешнего значения.
- Он обнаруживает
null
как отдельный тип, а ECMAScripttypeof
обнаружитobject
.
Если value
имеет недопустимый тип, возвращается ошибка.
napi_instanceof¶
napi_status napi_instanceof(napi_env env,
napi_value object,
napi_value constructor,
bool* result)
[in] env
: Среда, в которой вызывается API.[in] object
: Значение JavaScript для проверки.[in] constructor
: Объект функции JavaScript для функции-конструктора, с которой выполняется проверка.[out] result
: Логическое значение, для которого установлено значение true, еслиobject instanceof constructor
правда.
Возврат napi_ok
если API удалось.
Этот API представляет собой вызов instanceof
Оператор объекта, как определено в Раздел 12.10.4 спецификации языка ECMAScript.
napi_is_array¶
napi_status napi_is_array(napi_env env, napi_value value, bool* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для проверки.[out] result
: Является ли данный объект массивом.
Возврат napi_ok
если API удалось.
Этот API представляет собой вызов IsArray
операция над объектом, как определено в Раздел 7.2.2 спецификации языка ECMAScript.
napi_is_arraybuffer¶
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для проверки.[out] result
: Является ли данный объектArrayBuffer
.
Возврат napi_ok
если API удалось.
Этот API проверяет, Object
передается буфер массива.
napi_is_buffer¶
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для проверки.[out] result
: Будь то данныйnapi_value
представляетnode::Buffer
объект.
Возврат napi_ok
если API удалось.
Этот API проверяет, Object
передается буфер.
napi_is_date¶
napi_status napi_is_date(napi_env env, napi_value value, bool* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для проверки.[out] result
: Будь то данныйnapi_value
представляет собой JavaScriptDate
объект.
Возврат napi_ok
если API удалось.
Этот API проверяет, Object
прошла дата.
napi_is_error¶
napi_status napi_is_error(napi_env env, napi_value value, bool* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для проверки.[out] result
: Будь то данныйnapi_value
представляет собойError
объект.
Возврат napi_ok
если API удалось.
Этот API проверяет, Object
прошел в Error
.
napi_is_typedarray¶
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для проверки.[out] result
: Будь то данныйnapi_value
представляетTypedArray
.
Возврат napi_ok
если API удалось.
Этот API проверяет, Object
передается типизированный массив.
napi_is_dataview¶
napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)
[in] env
: Среда, в которой вызывается API.[in] value
: Значение JavaScript для проверки.[out] result
: Будь то данныйnapi_value
представляетDataView
.
Возврат napi_ok
если API удалось.
Этот API проверяет, Object
прошел в DataView
.
napi_strict_equals¶
napi_status napi_strict_equals(napi_env env,
napi_value lhs,
napi_value rhs,
bool* result)
[in] env
: Среда, в которой вызывается API.[in] lhs
: Значение JavaScript для проверки.[in] rhs
: Значение JavaScript для проверки.[out] result
: Будь то дваnapi_value
объекты равны.
Возврат napi_ok
если API удалось.
Этот API представляет собой вызов алгоритма строгого равенства, как определено в Раздел 7.2.14 спецификации языка ECMAScript.
napi_detach_arraybuffer¶
napi_status napi_detach_arraybuffer(napi_env env,
napi_value arraybuffer)
[in] env
: Среда, в которой вызывается API.[in] arraybuffer
: JavaScriptArrayBuffer
быть отстраненным.
Возврат napi_ok
если API удалось. Если несъемный ArrayBuffer
передается в это возвращается napi_detachable_arraybuffer_expected
.
Как правило, ArrayBuffer
является несъемным, если он был отсоединен ранее. Двигатель может накладывать дополнительные условия на то, ArrayBuffer
съемный. Например, V8 требует, чтобы ArrayBuffer
быть внешним, то есть созданным с napi_create_external_arraybuffer
.
Этот API представляет собой вызов ArrayBuffer
операция отсоединения, как определено в Раздел 24.1.1.3 спецификации языка ECMAScript.
napi_is_detached_arraybuffer¶
napi_status napi_is_detached_arraybuffer(napi_env env,
napi_value arraybuffer,
bool* result)
[in] env
: Среда, в которой вызывается API.[in] arraybuffer
: JavaScriptArrayBuffer
быть проверенным.[out] result
: Будь тоarraybuffer
отделен.
Возврат napi_ok
если API удалось.
В ArrayBuffer
считается отсоединенным, если его внутренние данные null
.
Этот API представляет собой вызов ArrayBuffer
IsDetachedBuffer
операция, как определено в Раздел 24.1.1.2 спецификации языка ECMAScript.
Работа со свойствами JavaScript¶
Node-API предоставляет набор API для получения и установки свойств объектов JavaScript. Некоторые из этих типов описаны в Раздел 7 принадлежащий Спецификация языка ECMAScript.
Свойства в JavaScript представлены в виде кортежа, состоящего из ключа и значения. По сути, все ключи свойств в Node-API могут быть представлены в одной из следующих форм:
- Именованный: простая строка в кодировке UTF8.
- Целочисленный индекс: значение индекса, представленное
uint32_t
- Значение JavaScript: они представлены в Node-API с помощью
napi_value
. Это может бытьnapi_value
представляющийstring
,number
, илиsymbol
.
Значения Node-API представлены типом napi_value
. Любой вызов Node-API, для которого требуется значение JavaScript, принимает napi_value
. Однако вызывающий абонент обязан убедиться, что napi_value
речь идет о типе JavaScript, ожидаемом API.
API, описанные в этом разделе, предоставляют простой интерфейс для получения и установки свойств произвольных объектов JavaScript, представленных napi_value
.
Например, рассмотрим следующий фрагмент кода JavaScript:
const obj = {};
obj.myProp = 123;
Эквивалент может быть выполнен с использованием значений Node-API с помощью следующего фрагмента:
napi_status status = napi_generic_failure;
// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Create a napi_value for 123
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;
// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status;
Проиндексированные свойства можно установить аналогичным образом. Рассмотрим следующий фрагмент кода JavaScript:
const arr = [];
arr[123] = 'hello';
Эквивалент может быть выполнен с использованием значений 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;
// Create a napi_value for 'hello'
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;
// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status;
Свойства можно получить с помощью API, описанных в этом разделе. Рассмотрим следующий фрагмент кода JavaScript:
const arr = [];
const value = arr[123];
Ниже приводится приблизительный эквивалент аналога 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;
Наконец, несколько свойств также могут быть определены для объекта по соображениям производительности. Рассмотрим следующий код JavaScript:
const obj = {};
Object.defineProperties(obj, {
foo: {
value: 123,
writable: true,
configurable: true,
enumerable: true,
},
bar: {
value: 456,
writable: true,
configurable: true,
enumerable: true,
},
});
Ниже приводится приблизительный эквивалент аналога Node-API:
napi_status status = napi_status_generic_failure;
// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Create napi_values for 123 and 456
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;
// Set the properties
napi_property_descriptor descriptors[] = {
{ "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
{ "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
obj,
sizeof(descriptors) / sizeof(descriptors[0]),
descriptors);
if (status != napi_ok) return status;
Структуры¶
napi_property_attributes¶
typedef enum {
napi_default = 0,
napi_writable = 1 << 0,
napi_enumerable = 1 << 1,
napi_configurable = 1 << 2,
// Used with napi_define_class to distinguish static properties
// from instance properties. Ignored by napi_define_properties.
napi_static = 1 << 10,
// Default for class methods.
napi_default_method = napi_writable | napi_configurable,
// Default for object properties, like in JS obj[prop].
napi_default_jsproperty = napi_writable |
napi_enumerable |
napi_configurable,
} napi_property_attributes;
napi_property_attributes
- это флаги, используемые для управления поведением свойств, установленных для объекта JavaScript. Кроме как napi_static
они соответствуют атрибутам, перечисленным в Раздел 6.1.7.1 принадлежащий Спецификация языка ECMAScript. Они могут быть одним или несколькими из следующих битовых флагов:
napi_default
: Для свойства не установлены явные атрибуты. По умолчанию свойство доступно только для чтения, а не для перечисления и настройки.napi_writable
: Свойство доступно для записи.napi_enumerable
: Свойство перечислимое.napi_configurable
: Свойство настраивается, как определено в Раздел 6.1.7.1 принадлежащий Спецификация языка ECMAScript.napi_static
: Свойство будет определено как статическое свойство класса, а не свойство экземпляра, которое используется по умолчанию. Используется толькоnapi_define_class
. Это игнорируетсяnapi_define_properties
.napi_default_method
: Как и метод в классе JS, свойство можно настраивать и записывать, но нельзя перечислить.napi_default_jsproperty
: Подобно свойству, установленному посредством присвоения в JavaScript, свойство доступно для записи, перечисления и настройки.
napi_property_descriptor¶
typedef struct {
// One of utf8name or name should be 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
: Необязательная строка, описывающая ключ свойства, в кодировке UTF8. Один изutf8name
илиname
должны быть предусмотрены для собственности.name
: По желаниюnapi_value
который указывает на строку или символ JavaScript, который будет использоваться в качестве ключа для свойства. Один изutf8name
илиname
должны быть предусмотрены для собственности.value
: Значение, полученное при доступе к свойству, если свойство является свойством данных. Если это передано, установитеgetter
,setter
,method
а такжеdata
кNULL
(поскольку эти члены не будут использоваться).getter
: Функция, вызываемая при получении доступа к свойству. Если это передано, установитеvalue
а такжеmethod
кNULL
(поскольку эти члены не будут использоваться). Данная функция неявно вызывается средой выполнения, когда к свойству обращаются из кода JavaScript (или если получение свойства выполняется с помощью вызова Node-API).napi_callback
предоставляет более подробную информацию.setter
: Функция, вызываемая при выполнении заданного доступа к свойству. Если это передано, установитеvalue
а такжеmethod
кNULL
(поскольку эти члены не будут использоваться). Данная функция неявно вызывается средой выполнения, когда свойство устанавливается из кода JavaScript (или если установка свойства выполняется с помощью вызова Node-API).napi_callback
предоставляет более подробную информацию.method
: Установите это, чтобы сделать объект дескриптора свойстваvalue
свойство быть функцией JavaScript, представленнойmethod
. Если это передано, установитеvalue
,getter
а такжеsetter
кNULL
(поскольку эти члены не будут использоваться).napi_callback
предоставляет более подробную информацию.attributes
: Атрибуты, связанные с конкретным свойством. Видетьnapi_property_attributes
.data
: Данные обратного вызова, переданные вmethod
,getter
а такжеsetter
если эта функция вызвана.
Функции¶
napi_get_property_names¶
napi_status napi_get_property_names(napi_env env,
napi_value object,
napi_value* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, из которого нужно получить свойства.[out] result
: Аnapi_value
представляющий массив значений JavaScript, представляющих имена свойств объекта. API можно использовать для перебораresult
с использованиемnapi_get_array_length
а такжеnapi_get_element
.
Возврат napi_ok
если API удалось.
Этот API возвращает имена перечислимых свойств object
как массив строк. Свойства object
ключ которого является символом, не будет включен.
napi_get_all_property_names¶
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
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, из которого нужно получить свойства.[in] key_mode
: Следует ли также получать свойства прототипа.[in] key_filter
: Какие свойства извлекать (перечислимые / читаемые / записываемые).[in] key_conversion
: Преобразовывать ли ключи пронумерованных свойств в строки.[out] result
: Аnapi_value
представляющий массив значений JavaScript, представляющих имена свойств объекта.napi_get_array_length
а такжеnapi_get_element
можно использовать для перебораresult
.
Возврат napi_ok
если API удалось.
Этот API возвращает массив, содержащий имена доступных свойств этого объекта.
napi_set_property¶
napi_status napi_set_property(napi_env env,
napi_value object,
napi_value key,
napi_value value);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, для которого нужно установить свойство.[in] key
: Имя устанавливаемого свойства.[in] value
: Значение свойства.
Возврат napi_ok
если API удалось.
Этот API устанавливает свойство на Object
прошел внутрь.
napi_get_property¶
napi_status napi_get_property(napi_env env,
napi_value object,
napi_value key,
napi_value* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, из которого нужно получить свойство.[in] key
: Имя свойства, которое нужно получить.[out] result
: Стоимость собственности.
Возврат napi_ok
если API удалось.
Этот API получает запрошенное свойство из Object
прошел внутрь.
napi_has_property¶
napi_status napi_has_property(napi_env env,
napi_value object,
napi_value key,
bool* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект для запроса.[in] key
: Имя свойства, существование которого нужно проверить.[out] result
: Существует ли свойство на объекте или нет.
Возврат napi_ok
если API удалось.
Этот API проверяет, Object
переданный имеет указанное свойство.
napi_delete_property¶
napi_status napi_delete_property(napi_env env,
napi_value object,
napi_value key,
bool* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект для запроса.[in] key
: Имя удаляемого свойства.[out] result
: Успешно ли удаление свойства.result
при желании можно игнорировать, передавNULL
.
Возврат napi_ok
если API удалось.
Этот API пытается удалить key
владеть собственностью от object
.
napi_has_own_property¶
napi_status napi_has_own_property(napi_env env,
napi_value object,
napi_value key,
bool* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект для запроса.[in] key
: Имя собственного свойства, существование которого нужно проверить.[out] result
: Существует ли собственное свойство на объекте или нет.
Возврат napi_ok
если API удалось.
Этот API проверяет, Object
переданный имеет указанное собственное имущество. key
должен быть string
или symbol
, или будет выдана ошибка. Node-API не будет выполнять преобразование между типами данных.
napi_set_ named_property¶
napi_status napi_set_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value value);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, для которого нужно установить свойство.[in] utf8Name
: Имя устанавливаемого свойства.[in] value
: Значение свойства.
Возврат napi_ok
если API удалось.
Этот метод эквивалентен вызову napi_set_property
с napi_value
создан из строки, переданной как utf8Name
.
napi_get_ named_property¶
napi_status napi_get_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, из которого нужно получить свойство.[in] utf8Name
: Имя свойства, которое нужно получить.[out] result
: Стоимость собственности.
Возврат napi_ok
если API удалось.
Этот метод эквивалентен вызову napi_get_property
с napi_value
создан из строки, переданной как utf8Name
.
napi_has_ named_property¶
napi_status napi_has_named_property(napi_env env,
napi_value object,
const char* utf8Name,
bool* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект для запроса.[in] utf8Name
: Имя свойства, существование которого нужно проверить.[out] result
: Существует ли свойство на объекте или нет.
Возврат napi_ok
если API удалось.
Этот метод эквивалентен вызову napi_has_property
с napi_value
создан из строки, переданной как utf8Name
.
napi_set_element¶
napi_status napi_set_element(napi_env env,
napi_value object,
uint32_t index,
napi_value value);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, для которого нужно установить свойства.[in] index
: Индекс устанавливаемого свойства.[in] value
: Значение свойства.
Возврат napi_ok
если API удалось.
Этот API устанавливает и элемент на Object
прошел внутрь.
napi_get_element¶
napi_status napi_get_element(napi_env env,
napi_value object,
uint32_t index,
napi_value* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, из которого нужно получить свойство.[in] index
: Индекс свойства, которое нужно получить.[out] result
: Стоимость собственности.
Возврат napi_ok
если API удалось.
Этот API получает элемент по запрошенному индексу.
napi_has_element¶
napi_status napi_has_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект для запроса.[in] index
: Индекс свойства, существование которого нужно проверить.[out] result
: Существует ли свойство на объекте или нет.
Возврат napi_ok
если API удалось.
Этот API возвращается, если Object
переданный имеет элемент по запрошенному индексу.
napi_delete_element¶
napi_status napi_delete_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект для запроса.[in] index
: Индекс удаляемого свойства.[out] result
: Успешно ли удаление элемента.result
при желании можно игнорировать, передавNULL
.
Возврат napi_ok
если API удалось.
Этот API пытается удалить указанный index
из object
.
napi_define_properties¶
napi_status napi_define_properties(napi_env env,
napi_value object,
size_t property_count,
const napi_property_descriptor* properties);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, из которого нужно получить свойства.[in] property_count
: Количество элементов вproperties
множество.[in] properties
: Массив дескрипторов свойств.
Возврат napi_ok
если API удалось.
Этот метод позволяет эффективно определять несколько свойств данного объекта. Свойства определяются с помощью дескрипторов свойств (см. napi_property_descriptor
). Учитывая массив таких дескрипторов свойств, этот API будет устанавливать свойства объекта по одному, как определено DefineOwnProperty()
(описано в Раздел 9.1.6 спецификации ECMA-262).
napi_object_freeze¶
napi_status napi_object_freeze(napi_env env,
napi_value object);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, который нужно заморозить.
Возврат napi_ok
если API удалось.
Этот метод замораживает данный объект. Это предотвращает добавление к нему новых свойств, удаление существующих свойств, предотвращает изменение перечисляемости, настраиваемости или возможности записи существующих свойств и предотвращает изменение значений существующих свойств. Это также предотвращает изменение прототипа объекта. Это описано в Раздел 19.1.2.6 спецификации ECMA-262.
napi_object_seal¶
napi_status napi_object_seal(napi_env env,
napi_value object);
[in] env
: Среда, в которой вызывается вызов Node-API.[in] object
: Объект, который нужно запечатать.
Возврат napi_ok
если API удалось.
Этот метод запечатывает данный объект. Это предотвращает добавление к нему новых свойств, а также пометку всех существующих свойств как не настраиваемых. Это описано в Раздел 19.1.2.20 спецификации ECMA-262.
Работа с функциями JavaScript¶
Node-API предоставляет набор API-интерфейсов, которые позволяют коду JavaScript возвращаться в собственный код. API-интерфейсы узлов, поддерживающие обратный вызов в машинный код, принимают функции обратного вызова, представленные napi_callback
тип. Когда виртуальная машина JavaScript обращается к собственному коду, napi_callback
вызывается предоставленная функция. API, описанные в этом разделе, позволяют функции обратного вызова выполнять следующие действия:
- Получите информацию о контексте, в котором был вызван обратный вызов.
- Получите аргументы, переданные в обратный вызов.
- Вернуть
napi_value
обратно из обратного вызова.
Кроме того, Node-API предоставляет набор функций, которые позволяют вызывать функции JavaScript из собственного кода. Можно вызвать функцию как обычный вызов функции JavaScript или как функцию-конструктор.
Любые не-NULL
данные, которые передаются этому API через data
поле napi_property_descriptor
элементы могут быть связаны с object
и освобожден всякий раз, когда object
сборщиком мусора путем передачи обоих object
и данные для napi_add_finalizer
.
napi_call_function¶
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
: Среда, в которой вызывается API.[in] recv
: Thethis
значение, переданное вызываемой функции.[in] func
:napi_value
представляющий вызываемую функцию JavaScript.[in] argc
: Количество элементов вargv
множество.[in] argv
: Массивnapi_values
представляющие значения JavaScript, переданные в качестве аргументов функции.[out] result
:napi_value
представляющий возвращенный объект JavaScript.
Возврат napi_ok
если API удалось.
Этот метод позволяет вызывать объект функции JavaScript из собственного надстройки. Это основной механизм обратного звонка из собственный код надстройки в JavaScript. Для особого случая вызова JavaScript после асинхронной операции см. napi_make_callback
.
Пример использования может выглядеть следующим образом. Рассмотрим следующий фрагмент кода JavaScript:
function AddTwo(num) {
return num + 2;
}
Затем указанную выше функцию можно вызвать из собственной надстройки, используя следующий код:
// Get the function named "AddTwo" on the global object
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;
// Convert the result back to a native type
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;
napi_create_function¶
napi_status napi_create_function(napi_env env,
const char* utf8name,
size_t length,
napi_callback cb,
void* data,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] utf8Name
: Имя функции в кодировке UTF8. Это видно в JavaScript как объект новой функцииname
имущество.[in] length
: Длинаutf8name
в байтах, илиNAPI_AUTO_LENGTH
если он заканчивается нулем.[in] cb
: Собственная функция, которая должна вызываться при вызове этого функционального объекта.napi_callback
предоставляет более подробную информацию.[in] data
: Контекст данных, предоставляемых пользователем. Это будет передано обратно в функцию при вызове позже.[out] result
:napi_value
представляющий объект функции JavaScript для вновь созданной функции.
Возврат napi_ok
если API удалось.
Этот API позволяет автору надстройки создавать объект функции в собственном коде. Это основной механизм, позволяющий вызывать в собственный код надстройки из JavaScript.
Вновь созданная функция не отображается автоматически из сценария после этого вызова. Вместо этого свойство должно быть явно установлено для любого объекта, видимого для JavaScript, чтобы функция была доступна из скрипта.
Чтобы представить функцию как часть экспорта модуля надстройки, установите вновь созданную функцию для объекта экспорта. Примерный модуль может выглядеть следующим образом:
napi_value SayHello(napi_env env, napi_callback_info info) {
printf("Hello\n");
return NULL;
}
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_value fn;
status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "sayHello", fn);
if (status != napi_ok) return NULL;
return exports;
}
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
Учитывая приведенный выше код, надстройку можно использовать из JavaScript следующим образом:
const myaddon = require('./addon');
myaddon.sayHello();
Строка, переданная в require()
это имя цели в binding.gyp
отвечает за создание .node
файл.
Любые не-NULL
данные, которые передаются этому API через data
параметр может быть связан с результирующей функцией JavaScript (которая возвращается в result
параметр) и освобождается всякий раз, когда функция собирается сборщиком мусора, передавая и функцию JavaScript, и данные в napi_add_finalizer
.
JavaScript Function
описаны в Раздел 19.2 спецификации языка ECMAScript.
napi_get_cb_info¶
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
: Среда, в которой вызывается API.[in] cbinfo
: Информация обратного вызова, переданная в функцию обратного вызова.[in-out] argc
: Определяет длину предоставленногоargv
массив и получает фактическое количество аргументов.[out] argv
: Буфер, в которыйnapi_value
представляющие аргументы копируются. Если аргументов больше, чем предоставлено, копируется только запрошенное количество аргументов. Если приведено меньше аргументов, чем заявлено, остальныеargv
наполненnapi_value
ценности, которые представляютundefined
.[out] this
: Получает JavaScriptthis
аргумент для звонка.[out] data
: Получает указатель данных для обратного вызова.
Возврат napi_ok
если API удалось.
Этот метод используется в функции обратного вызова для получения сведений о вызове, таких как аргументы и this
указатель на заданную информацию обратного вызова.
napi_get_new_target¶
napi_status napi_get_new_target(napi_env env,
napi_callback_info cbinfo,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] cbinfo
: Информация обратного вызова, переданная в функцию обратного вызова.[out] result
: Thenew.target
вызова конструктора.
Возврат napi_ok
если API удалось.
Этот API возвращает new.target
вызова конструктора. Если текущий обратный вызов не является вызовом конструктора, результатом будет NULL
.
napi_new_instance¶
napi_status napi_new_instance(napi_env env,
napi_value cons,
size_t argc,
napi_value* argv,
napi_value* result)
[in] env
: Среда, в которой вызывается API.[in] cons
:napi_value
представляющий функцию JavaScript, которая должна быть вызвана как конструктор.[in] argc
: Количество элементов вargv
множество.[in] argv
: Массив значений JavaScript какnapi_value
представление аргументов конструктору.[out] result
:napi_value
представляющий возвращаемый объект JavaScript, который в данном случае является сконструированным объектом.
Этот метод используется для создания нового значения JavaScript с использованием заданного napi_value
который представляет конструктор объекта. Например, рассмотрим следующий фрагмент:
function MyObject(param) {
this.param = param;
}
const arg = 'hello';
const value = new MyObject(arg);
Следующее можно приблизительно оценить в Node-API, используя следующий фрагмент:
// Get the constructor function 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);
Возврат napi_ok
если API удалось.
Перенос объекта¶
Node-API предлагает способ «обернуть» классы и экземпляры C ++, чтобы конструктор и методы класса могли вызываться из JavaScript.
- В
napi_define_class
API определяет класс JavaScript с конструктором, статическими свойствами и методами, а также свойствами и методами экземпляра, которые соответствуют классу C ++. - Когда код JavaScript вызывает конструктор, обратный вызов конструктора использует
napi_wrap
чтобы обернуть новый экземпляр C ++ в объект JavaScript, а затем возвращает объект-оболочку. - Когда код JavaScript вызывает метод или средство доступа к свойству в классе, соответствующий
napi_callback
Вызывается функция C ++. Для обратного вызова экземпляра,napi_unwrap
получает экземпляр C ++, который является целью вызова.
Для обернутых объектов может быть трудно отличить функцию, вызываемую от прототипа класса, от функции, вызываемой от экземпляра класса. Распространенным шаблоном, используемым для решения этой проблемы, является сохранение постоянной ссылки на конструктор класса на будущее. 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 {
// otherwise...
}
Ссылка должна быть освобождена, когда она больше не нужна.
Бывают случаи, когда napi_instanceof()
недостаточно для гарантии того, что объект JavaScript является оболочкой для определенного собственного типа. Это особенно важно, когда обернутые объекты JavaScript передаются обратно в аддон через статические методы, а не как this
ценность методов прототипа. В таких случаях есть вероятность, что они могут быть неправильно развернуты.
const myAddon = require('./build/Release/my_addon.node');
// `openDatabase()` returns a JavaScript object that wraps a native database
// handle.
const dbHandle = myAddon.openDatabase();
// `query()` returns a JavaScript object that wraps a native query handle.
const queryHandle = myAddon.query(
dbHandle,
'Gimme ALL the things!'
);
// There is an accidental error in the line below. The first parameter to
// `myAddon.queryHasRecords()` should be the database handle (`dbHandle`), not
// the query handle (`query`), so the correct condition for the while-loop
// should be
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
// retrieve records
}
В приведенном выше примере myAddon.queryHasRecords()
- это метод, который принимает два аргумента. Первый - это дескриптор базы данных, а второй - дескриптор запроса. Внутри он разворачивает первый аргумент и приводит полученный указатель к собственному дескриптору базы данных. Затем он разворачивает второй аргумент и приводит полученный указатель к дескриптору запроса. Если аргументы переданы в неправильном порядке, приведение будет работать, однако есть большая вероятность, что базовая операция с базой данных завершится ошибкой или даже вызовет недопустимый доступ к памяти.
Чтобы гарантировать, что указатель, полученный из первого аргумента, действительно является указателем на дескриптор базы данных и, аналогично, что указатель, полученный из второго аргумента, действительно является указателем на дескриптор запроса, реализация queryHasRecords()
должен выполнить проверку типа. Сохранение конструктора класса JavaScript, из которого был создан дескриптор базы данных, и конструктора, из которого был создан дескриптор запроса в napi_ref
s может помочь, потому что napi_instanceof()
затем можно использовать, чтобы гарантировать, что экземпляры переданы в queryHashRecords()
действительно принадлежат к правильному типу.
К несчастью, napi_instanceof()
не защищает от манипуляций с прототипами. Например, прототип экземпляра дескриптора базы данных может быть установлен на прототип конструктора для экземпляров дескриптора запроса. В этом случае экземпляр дескриптора базы данных может отображаться как экземпляр дескриптора запроса, и он будет передавать napi_instanceof()
test для экземпляра дескриптора запроса, при этом все еще содержащего указатель на дескриптор базы данных.
С этой целью Node-API предоставляет возможности тегирования типов.
Тег типа - это 128-битное целое число, уникальное для надстройки. Node-API предоставляет napi_type_tag
структура для хранения тега типа. Когда такое значение передается вместе с объектом JavaScript, хранящимся в napi_value
к napi_type_tag_object()
, объект JavaScript будет «помечен» тегом типа. «Метка» не видна на стороне JavaScript. Когда объект JavaScript попадает в нативную привязку, napi_check_object_type_tag()
может использоваться вместе с исходным тегом типа, чтобы определить, был ли объект JavaScript ранее «помечен» тегом типа. Это создает возможность проверки типов с более высокой точностью, чем napi_instanceof()
может обеспечить, потому что такая маркировка типов переживает манипуляции с прототипами и выгрузку / перезагрузку аддонов.
Продолжая приведенный выше пример, следующая реализация скелета надстройки иллюстрирует использование napi_type_tag_object()
а также napi_check_object_type_tag()
.
// This value is the type tag for a database handle. The command
//
// uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// can be used to obtain the two values with which to initialize the structure.
static const napi_type_tag DatabaseHandleTypeTag = {
0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};
// This value is the type tag for a query handle.
static const napi_type_tag QueryHandleTypeTag = {
0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};
static napi_value
openDatabase(napi_env env, napi_callback_info info) {
napi_status status;
napi_value result;
// Perform the underlying action which results in a database handle.
DatabaseHandle* dbHandle = open_database();
// Create a new, empty JS object.
status = napi_create_object(env, &result);
if (status != napi_ok) return NULL;
// Tag the object to indicate that it holds a pointer to a `DatabaseHandle`.
status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
if (status != napi_ok) return NULL;
// Store the pointer to the `DatabaseHandle` structure inside the JS object.
status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
if (status != napi_ok) return NULL;
return result;
}
// Later when we receive a JavaScript object purporting to be a database handle
// we can use `napi_check_object_type_tag()` to ensure that it is indeed such a
// handle.
static napi_value
query(napi_env env, napi_callback_info info) {
napi_status status;
size_t argc = 2;
napi_value argv[2];
bool is_db_handle;
status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
if (status != napi_ok) return NULL;
// Check that the object passed as the first parameter has the previously
// applied tag.
status = napi_check_object_type_tag(env,
argv[0],
&DatabaseHandleTypeTag,
&is_db_handle);
if (status != napi_ok) return NULL;
// Throw a `TypeError` if it doesn't.
if (!is_db_handle) {
// Throw a TypeError.
return NULL;
}
}
napi_define_class¶
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
: Среда, в которой вызывается API.[in] utf8name
: Имя функции конструктора JavaScript; При создании оболочки для класса C ++ мы рекомендуем для ясности, чтобы это имя было таким же, как у класса C ++.[in] length
: Длинаutf8name
в байтах, илиNAPI_AUTO_LENGTH
если он заканчивается нулем.[in] constructor
: Функция обратного вызова, которая обрабатывает создание экземпляров класса. При упаковке класса C ++ этот метод должен быть статическим членом сnapi_callback
подпись. Конструктор класса C ++ использовать нельзя.napi_callback
предоставляет более подробную информацию.[in] data
: Необязательные данные, передаваемые в обратный вызов конструктора в качествеdata
свойство информации обратного вызова.[in] property_count
: Количество элементов вproperties
аргумент массива.[in] properties
: Массив дескрипторов свойств, описывающих свойства, средства доступа и методы статических данных и данных экземпляра в классе См.napi_property_descriptor
.[out] result
: Аnapi_value
представляющий функцию-конструктор для класса.
Возврат napi_ok
если API удалось.
Определяет класс JavaScript, в том числе:
- Функция-конструктор JavaScript, имеющая имя класса. При упаковке соответствующего класса C ++ обратный вызов передается через
constructor
может использоваться для создания нового экземпляра класса C ++, который затем может быть помещен внутри экземпляра объекта JavaScript, создаваемого с использованиемnapi_wrap
. - Свойства функции конструктора, реализация которой может вызывать соответствующие статический свойства данных, средства доступа и методы класса C ++ (определяемые дескрипторами свойств с
napi_static
атрибут). - Свойства конструктора функции
prototype
объект. При упаковке класса C ++ нестатический свойства данных, средства доступа и методы класса C ++ могут быть вызваны из статических функций, указанных в дескрипторах свойств, безnapi_static
атрибут после получения экземпляра класса C ++, помещенного внутри экземпляра объекта JavaScript, с помощьюnapi_unwrap
.
При упаковке класса C ++ обратный вызов конструктора C ++ передается через constructor
должен быть статическим методом в классе, который вызывает фактический конструктор класса, затем помещает новый экземпляр C ++ в объект JavaScript и возвращает объект-оболочку. Видеть napi_wrap
для подробностей.
Функция конструктора JavaScript, возвращенная из napi_define_class
часто сохраняется и используется позже для создания новых экземпляров класса из машинного кода и / или для проверки, являются ли предоставленные значения экземплярами класса. В этом случае, чтобы предотвратить сборку мусора значения функции, можно создать сильную постоянную ссылку на него с помощью napi_create_reference
, гарантируя, что счетчик ссылок поддерживается> = 1.
Любые не-NULL
данные, которые передаются этому API через data
параметр или через data
поле napi_property_descriptor
элементы массива могут быть связаны с результирующим конструктором JavaScript (который возвращается в result
параметр) и освобождается всякий раз, когда класс собирается сборщиком мусора, передавая как функцию JavaScript, так и данные в napi_add_finalizer
.
napi_wrap¶
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
: Среда, в которой вызывается API.[in] js_object
: Объект JavaScript, который будет оболочкой для собственного объекта.[in] native_object
: Собственный экземпляр, который будет заключен в объект JavaScript.[in] finalize_cb
: Необязательный собственный обратный вызов, который можно использовать для освобождения собственного экземпляра, когда объект JavaScript готов для сборки мусора.napi_finalize
предоставляет более подробную информацию.[in] finalize_hint
: Необязательная контекстная подсказка, которая передается в обратный вызов finalize.[out] result
: Необязательная ссылка на завернутый объект.
Возврат napi_ok
если API удалось.
Оборачивает собственный экземпляр в объект JavaScript. Собственный экземпляр можно получить позже, используя napi_unwrap()
.
Когда код JavaScript вызывает конструктор для класса, который был определен с помощью napi_define_class()
, то napi_callback
для конструктора вызывается. После создания экземпляра собственного класса обратный вызов должен вызвать napi_wrap()
чтобы обернуть вновь созданный экземпляр в уже созданный объект JavaScript, который является this
аргумент обратного вызова конструктора. (Что this
объект был создан из конструктора функции prototype
, поэтому в нем уже есть определения всех свойств и методов экземпляра.)
Обычно при упаковке экземпляра класса должен быть предоставлен обратный вызов finalize, который просто удаляет собственный экземпляр, полученный как data
аргумент обратного вызова finalize.
Необязательная возвращаемая ссылка изначально является слабой ссылкой, то есть она имеет счетчик ссылок 0. Обычно этот счетчик ссылок временно увеличивается во время асинхронных операций, которые требуют, чтобы экземпляр оставался действительным.
Осторожность: Необязательная возвращенная ссылка (если получена) должна быть удалена через napi_delete_reference
ТОЛЬКО в ответ на вызов обратного вызова finalize. Если он будет удален до этого, то обратный вызов finalize может никогда не быть вызван. Следовательно, при получении ссылки также требуется обратный вызов finalize, чтобы обеспечить правильное удаление ссылки.
Вызов napi_wrap()
второй раз на объекте вернет ошибку. Чтобы связать другой собственный экземпляр с объектом, используйте napi_remove_wrap()
первый.
napi_unwrap¶
napi_status napi_unwrap(napi_env env,
napi_value js_object,
void** result);
[in] env
: Среда, в которой вызывается API.[in] js_object
: Объект, связанный с собственным экземпляром.[out] result
: Указатель на обернутый собственный экземпляр.
Возврат napi_ok
если API удалось.
Извлекает собственный экземпляр, который ранее был заключен в объект JavaScript, используя napi_wrap()
.
Когда код JavaScript вызывает метод или средство доступа к свойству в классе, соответствующий napi_callback
вызывается. Если обратный вызов предназначен для метода экземпляра или средства доступа, тогда this
аргументом обратного вызова является объект-оболочка; обернутый экземпляр C ++, который является целью вызова, может быть получен затем путем вызова napi_unwrap()
на объекте-оболочке.
napi_remove_wrap¶
napi_status napi_remove_wrap(napi_env env,
napi_value js_object,
void** result);
[in] env
: Среда, в которой вызывается API.[in] js_object
: Объект, связанный с собственным экземпляром.[out] result
: Указатель на обернутый собственный экземпляр.
Возврат napi_ok
если API удалось.
Извлекает собственный экземпляр, который ранее был заключен в объект JavaScript js_object
с использованием napi_wrap()
и снимает обертку. Если обратный вызов finalize был связан с упаковкой, он больше не будет вызываться, когда объект JavaScript станет собираемым мусором.
napi_type_tag_object¶
napi_status napi_type_tag_object(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag);
[in] env
: Среда, в которой вызывается API.[in] js_object
: Объект JavaScript, который нужно отметить.[in] type_tag
: Тег, которым должен быть отмечен объект.
Возврат napi_ok
если API удалось.
Связывает ценность type_tag
указатель на объект JavaScript. napi_check_object_type_tag()
затем можно использовать для сравнения тега, прикрепленного к объекту, с тегом, принадлежащим надстройке, чтобы убедиться, что объект имеет правильный тип.
Если у объекта уже есть связанный тег типа, этот API вернет napi_invalid_arg
.
napi_check_object_type_tag¶
napi_status napi_check_object_type_tag(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag,
bool* result);
[in] env
: Среда, в которой вызывается API.[in] js_object
: Объект JavaScript, тег типа которого проверять.[in] type_tag
: Тег, с которым сравнивается любой тег, обнаруженный на объекте.[out] result
: Соответствует ли указанный тег типа тегу типа на объекте.false
также возвращается, если для объекта не было найдено ни одного тега типа.
Возврат napi_ok
если API удалось.
Сравнивает указатель, указанный как type_tag
с любым, что можно найти на js_object
. Если тег не найден на js_object
или, если тег найден, но не соответствует type_tag
, тогда result
установлен на false
. Если тег найден и соответствует type_tag
, тогда result
установлен на true
.
napi_add_finalizer¶
napi_status napi_add_finalizer(napi_env env,
napi_value js_object,
void* native_object,
napi_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);
[in] env
: Среда, в которой вызывается API.[in] js_object
: Объект JavaScript, к которому будут прикреплены собственные данные.[in] native_object
: Собственные данные, которые будут прикреплены к объекту JavaScript.[in] finalize_cb
: Собственный обратный вызов, который будет использоваться для освобождения собственных данных, когда объект JavaScript готов для сборки мусора.napi_finalize
предоставляет более подробную информацию.[in] finalize_hint
: Необязательная контекстная подсказка, которая передается в обратный вызов finalize.[out] result
: Необязательная ссылка на объект JavaScript.
Возврат napi_ok
если API удалось.
Добавляет napi_finalize
обратный вызов, который будет вызываться, когда объект JavaScript в js_object
готов к вывозу мусора. Этот API похож на napi_wrap()
Кроме этого:
- собственные данные не могут быть получены позже с помощью
napi_unwrap()
, - и его нельзя удалить позже, используя
napi_remove_wrap()
, а также - API можно вызывать несколько раз с разными элементами данных, чтобы прикрепить каждый из них к объекту JavaScript, и
- объект, которым управляет API, может использоваться с
napi_wrap()
.
Осторожность: Необязательная возвращенная ссылка (если получена) должна быть удалена через napi_delete_reference
ТОЛЬКО в ответ на вызов обратного вызова finalize. Если он будет удален до этого, то обратный вызов finalize может никогда не быть вызван. Следовательно, при получении ссылки также требуется обратный вызов finalize, чтобы обеспечить правильное удаление ссылки.
Простые асинхронные операции¶
Модули аддонов часто должны использовать асинхронные помощники из libuv как часть их реализации. Это позволяет им планировать асинхронное выполнение работы, чтобы их методы могли возвращаться до завершения работы. Это позволяет им избежать блокировки общего выполнения приложения Node.js.
Node-API предоставляет ABI-стабильный интерфейс для этих вспомогательных функций, который охватывает наиболее распространенные случаи асинхронного использования.
Node-API определяет napi_async_work
структура, которая используется для управления асинхронными работниками. Экземпляры создаются / удаляются с помощью napi_create_async_work
а также napi_delete_async_work
.
В execute
а также complete
Обратные вызовы - это функции, которые будут вызываться, когда исполнитель будет готов к выполнению и когда он завершит свою задачу соответственно.
В execute
функция должна избегать любых вызовов Node-API, которые могут привести к выполнению JavaScript или взаимодействию с объектами JavaScript. Чаще всего любой код, который должен выполнять вызовы Node-API, должен выполняться в complete
обратный вызов вместо этого. Избегайте использования napi_env
в обратном вызове execute, поскольку он, скорее всего, выполнит JavaScript.
Эти функции реализуют следующие интерфейсы:
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);
Когда эти методы вызываются, data
переданный параметр будет предоставлен аддоном void*
данные, которые были переданы в napi_create_async_work
вызов.
После создания асинхронный рабочий процесс может быть поставлен в очередь для выполнения с помощью napi_queue_async_work
функция:
napi_status napi_queue_async_work(napi_env env,
napi_async_work work);
napi_cancel_async_work
может использоваться, если работа должна быть отменена до того, как работа начала выполняться.
После звонка napi_cancel_async_work
, то complete
обратный вызов будет вызван со значением статуса napi_cancelled
. Работа не должна быть удалена до complete
вызов обратного вызова, даже если он был отменен.
napi_create_async_work¶
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
: Среда, в которой вызывается API.[in] async_resource
: Необязательный объект, связанный с асинхронной работой, который будет передан возможномуasync_hooks
init
крючки.[in] async_resource_name
: Идентификатор типа ресурса, который предоставляется для диагностической информации, предоставляемойasync_hooks
API.[in] execute
: Собственная функция, которая должна быть вызвана для асинхронного выполнения логики. Данная функция вызывается из потока рабочего пула и может выполняться параллельно с основным потоком цикла событий.[in] complete
: Собственная функция, которая будет вызываться при завершении или отмене асинхронной логики. Данная функция вызывается из основного потока цикла событий.napi_async_complete_callback
предоставляет более подробную информацию.[in] data
: Контекст данных, предоставляемых пользователем. Это будет передано обратно в функции execute и complete.[out] result
:napi_async_work*
который является дескриптором вновь созданной асинхронной работы.
Возврат napi_ok
если API удалось.
Этот API выделяет рабочий объект, который используется для асинхронного выполнения логики. Его следует освободить с помощью napi_delete_async_work
как только работа больше не требуется.
async_resource_name
должна быть строкой в кодировке UTF-8 с завершающим нулем.
В async_resource_name
идентификатор предоставляется пользователем и должен представлять тип выполняемой асинхронной работы. Также рекомендуется применять к идентификатору пространство имен, например включив имя модуля. Увидеть async_hooks
документация для дополнительной информации.
napi_delete_async_work¶
napi_status napi_delete_async_work(napi_env env,
napi_async_work work);
[in] env
: Среда, в которой вызывается API.[in] work
: Дескриптор, возвращаемый вызовомnapi_create_async_work
.
Возврат napi_ok
если API удалось.
Этот API освобождает ранее выделенный рабочий объект.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
napi_queue_async_work¶
napi_status napi_queue_async_work(napi_env env,
napi_async_work work);
[in] env
: Среда, в которой вызывается API.[in] work
: Дескриптор, возвращаемый вызовомnapi_create_async_work
.
Возврат napi_ok
если API удалось.
Этот API запрашивает, чтобы запланированная ранее работа была запланирована для выполнения. После успешного возврата этот API нельзя вызывать снова с тем же napi_async_work
item, иначе результат будет неопределенным.
napi_cancel_async_work¶
napi_status napi_cancel_async_work(napi_env env,
napi_async_work work);
[in] env
: Среда, в которой вызывается API.[in] work
: Дескриптор, возвращаемый вызовомnapi_create_async_work
.
Возврат napi_ok
если API удалось.
Этот API отменяет работу в очереди, если она еще не запущена. Если он уже начал выполняться, его нельзя отменить и napi_generic_failure
будет возвращен. В случае успеха complete
обратный вызов будет вызван со значением статуса napi_cancelled
. Работа не должна быть удалена до complete
вызов обратного вызова, даже если он был успешно отменен.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
Пользовательские асинхронные операции¶
Упомянутые выше простые API асинхронной работы могут не подходить для каждого сценария. При использовании любого другого асинхронного механизма необходимы следующие API-интерфейсы, чтобы гарантировать, что асинхронная операция должным образом отслеживается средой выполнения.
napi_async_init¶
napi_status napi_async_init(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_context* result)
[in] env
: Среда, в которой вызывается API.[in] async_resource
: Объект, связанный с асинхронной работой, который будет передан возможномуasync_hooks
init
крючки и к нему можно получить доступasync_hooks.executionAsyncResource()
.[in] async_resource_name
: Идентификатор типа ресурса, который предоставляется для диагностической информации, предоставляемойasync_hooks
API.[out] result
: Инициализированный асинхронный контекст.
Возврат napi_ok
если API удалось.
В async_resource
объект необходимо поддерживать до тех пор, пока napi_async_destroy
хранить async_hooks
связанный API работает правильно. Чтобы сохранить совместимость ABI с предыдущими версиями, napi_async_context
s не настойчиво ссылаются на async_resource
объекты, чтобы избежать утечки памяти. Однако если async_resource
сборщик мусора движком JavaScript перед napi_async_context
был уничтожен napi_async_destroy
, звоню napi_async_context
связанные API, такие как napi_open_callback_scope
а также napi_make_callback
может вызвать проблемы, такие как потеря асинхронного контекста при использовании AsyncLocalStorage
API.
Чтобы сохранить совместимость ABI с предыдущими версиями, передавая NULL
для async_resource
не приводит к ошибке. Однако это не рекомендуется, так как это приведет к плохим результатам с async_hooks
init
крючки а также async_hooks.executionAsyncResource()
поскольку ресурс теперь требуется базовому async_hooks
реализация для обеспечения связи между асинхронными обратными вызовами.
napi_async_destroy¶
napi_status napi_async_destroy(napi_env env,
napi_async_context async_context);
[in] env
: Среда, в которой вызывается API.[in] async_context
: Асинхронный контекст, который нужно уничтожить.
Возврат napi_ok
если API удалось.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
napi_make_callback¶
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
: Среда, в которой вызывается API.[in] async_context
: Контекст для асинхронной операции, вызывающей обратный вызов. Обычно это значение, полученное ранее изnapi_async_init
. Чтобы сохранить совместимость ABI с предыдущими версиями, передаваяNULL
дляasync_context
не приводит к ошибке. Однако это приводит к некорректной работе асинхронных хуков. Возможные проблемы включают потерю асинхронного контекста при использованииAsyncLocalStorage
API.[in] recv
: Thethis
значение, переданное вызываемой функции.[in] func
:napi_value
представляющий вызываемую функцию JavaScript.[in] argc
: Количество элементов вargv
множество.[in] argv
: Массив значений JavaScript какnapi_value
представляющие аргументы функции.[out] result
:napi_value
представляющий возвращенный объект JavaScript.
Возврат napi_ok
если API удалось.
Этот метод позволяет вызывать объект функции JavaScript из собственного надстройки. Этот API похож на napi_call_function
. Однако он используется для вызова из собственный код назад в JavaScript после возврат из асинхронной операции (когда в стеке нет другого скрипта). Это довольно простая обертка вокруг node::MakeCallback
.
Обратите внимание, это нет необходимо использовать napi_make_callback
изнутри napi_async_complete_callback
; в этой ситуации асинхронный контекст обратного вызова уже настроен, поэтому прямой вызов napi_call_function
достаточно и уместно. Использование napi_make_callback
функция может потребоваться при реализации пользовательского асинхронного поведения, которое не использует napi_create_async_work
.
Любой process.nextTick
s или обещания, запланированные в очереди микрозадач JavaScript во время обратного вызова, выполняются перед возвратом в C / C ++.
napi_open_callback_scope¶
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
: Среда, в которой вызывается API.[in] resource_object
: Объект, связанный с асинхронной работой, который будет передан возможномуasync_hooks
init
крючки. Этот параметр устарел и игнорируется во время выполнения. Использоватьasync_resource
параметр вnapi_async_init
вместо.[in] context
: Контекст для асинхронной операции, вызывающей обратный вызов. Это должно быть значение, ранее полученное изnapi_async_init
.[out] result
: Вновь созданная область.
Есть случаи (например, выполнение обещаний), когда необходимо иметь эквивалент области, связанной с обратным вызовом, при выполнении определенных вызовов Node-API. Если в стеке нет другого скрипта, napi_open_callback_scope
а также napi_close_callback_scope
функции могут использоваться для открытия / закрытия требуемой области.
napi_close_callback_scope¶
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
napi_callback_scope scope)
[in] env
: Среда, в которой вызывается API.[in] scope
: Область, которую необходимо закрыть.
Этот API можно вызвать, даже если есть ожидающее исключение JavaScript.
Управление версиями¶
napi_get_node_version¶
typedef struct {
uint32_t major;
uint32_t minor;
uint32_t patch;
const char* release;
} napi_node_version;
napi_status napi_get_node_version(napi_env env,
const napi_node_version** version);
[in] env
: Среда, в которой вызывается API.[out] version
: Указатель на информацию о версии самого Node.js.
Возврат napi_ok
если API удалось.
Эта функция заполняет version
struct с основной, второстепенной версией и версией исправления Node.js, которая выполняется в данный момент, и release
поле со значением process.release.name
.
Возвращаемый буфер выделяется статически, и его не нужно освобождать.
napi_get_version¶
napi_status napi_get_version(napi_env env,
uint32_t* result);
[in] env
: Среда, в которой вызывается API.[out] result
: Самая высокая версия поддерживаемого Node-API.
Возврат napi_ok
если API удалось.
Этот API возвращает самую высокую версию Node-API, поддерживаемую средой выполнения Node.js. Планируется, что Node-API будет дополнительным, чтобы новые версии Node.js могли поддерживать дополнительные функции API. Чтобы аддон мог использовать более новую функцию при работе с поддерживающими его версиями Node.js, обеспечивая при этом резервное поведение при работе с версиями Node.js, которые его не поддерживают:
- Вызов
napi_get_version()
чтобы определить, доступен ли API. - Если доступно, динамически загрузить указатель на функцию, используя
uv_dlsym()
. - Используйте динамически загружаемый указатель для вызова функции.
- Если функция недоступна, предоставьте альтернативную реализацию, которая не использует эту функцию.
Управление памятью¶
napi_adjust_external_memory¶
NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env,
int64_t change_in_bytes,
int64_t* result);
[in] env
: Среда, в которой вызывается API.[in] change_in_bytes
: Изменение выделенной извне памяти, которая поддерживается объектами JavaScript.[out] result
: Скорректированное значение
Возврат napi_ok
если API удалось.
Эта функция дает V8 индикацию объема выделенной извне памяти, которая поддерживается объектами JavaScript (то есть объектом JavaScript, который указывает на его собственную память, выделенную собственным модулем). Регистрация выделенной извне памяти будет запускать глобальную сборку мусора чаще, чем в противном случае.
Обещания¶
Node-API предоставляет возможности для создания Promise
объекты, как описано в Раздел 25.4 спецификации ECMA. Он реализует обещания как пару объектов. Когда обещание создается napi_create_promise()
, создается "отложенный" объект, который возвращается вместе с Promise
. Отложенный объект привязан к созданному Promise
и это единственный способ решить или отклонить Promise
с использованием napi_resolve_deferred()
или napi_reject_deferred()
. Отложенный объект, созданный napi_create_promise()
освобожден napi_resolve_deferred()
или napi_reject_deferred()
. В Promise
объект может быть возвращен в JavaScript, где его можно использовать обычным образом.
Например, чтобы создать обещание и передать его асинхронному исполнителю:
napi_deferred deferred;
napi_value promise;
napi_status status;
// Create the promise.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;
// Pass the deferred to a function that performs an asynchronous action.
do_something_asynchronous(deferred);
// Return the promise to JS
return promise;
Вышеупомянутая функция do_something_asynchronous()
выполнит свое асинхронное действие, а затем разрешит или отклонит отложенное, тем самым завершив обещание и освободив отложенное:
napi_deferred deferred;
napi_value undefined;
napi_status status;
// Create a value with which to conclude the deferred.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;
// Resolve or reject the promise associated with the deferred depending on
// whether the asynchronous action succeeded.
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;
// At this point the deferred has been freed, so we should assign NULL to it.
deferred = NULL;
napi_create_promise¶
napi_status napi_create_promise(napi_env env,
napi_deferred* deferred,
napi_value* promise);
[in] env
: Среда, в которой вызывается API.[out] deferred
: Вновь созданный отложенный объект, который позже может быть передан вnapi_resolve_deferred()
илиnapi_reject_deferred()
решить соотв. отклонить связанное обещание.[out] promise
: Обещание JavaScript, связанное с отложенным объектом.
Возврат napi_ok
если API удалось.
Этот API создает отложенный объект и обещание JavaScript.
napi_resolve_deferred¶
napi_status napi_resolve_deferred(napi_env env,
napi_deferred deferred,
napi_value resolution);
[in] env
: Среда, в которой вызывается API.[in] deferred
: Отложенный объект, связанный с которым обещание разрешить.[in] resolution
: Значение, с которым разрешается обещание.
Этот API разрешает обещание JavaScript посредством отложенного объекта, с которым оно связано. Таким образом, его можно использовать только для разрешения обещаний JavaScript, для которых доступен соответствующий отложенный объект. Это фактически означает, что обещание должно быть создано с использованием napi_create_promise()
и отложенный объект, возвращенный из этого вызова, должен быть сохранен, чтобы быть переданным в этот API.
Отложенный объект освобождается после успешного завершения.
napi_reject_deferred¶
napi_status napi_reject_deferred(napi_env env,
napi_deferred deferred,
napi_value rejection);
[in] env
: Среда, в которой вызывается API.[in] deferred
: Отложенный объект, связанный с которым обещание разрешить.[in] rejection
: Значение, с которым следует отклонить обещание.
Этот API отклоняет обещание JavaScript посредством отложенного объекта, с которым он связан. Таким образом, его можно использовать только для отклонения обещаний JavaScript, для которых доступен соответствующий отложенный объект. Это фактически означает, что обещание должно быть создано с использованием napi_create_promise()
и отложенный объект, возвращенный из этого вызова, должен быть сохранен, чтобы быть переданным в этот API.
Отложенный объект освобождается после успешного завершения.
napi_is_promise¶
napi_status napi_is_promise(napi_env env,
napi_value value,
bool* is_promise);
[in] env
: Среда, в которой вызывается API.[in] value
: Значение для изучения[out] is_promise
: Флаг, указывающий,promise
- это собственный объект обещания (то есть объект обещания, созданный базовым механизмом).
Выполнение скрипта¶
Node-API предоставляет API для выполнения строки, содержащей JavaScript, с использованием базового механизма JavaScript.
napi_run_script¶
NAPI_EXTERN napi_status napi_run_script(napi_env env,
napi_value script,
napi_value* result);
[in] env
: Среда, в которой вызывается API.[in] script
: Строка JavaScript, содержащая сценарий для выполнения.[out] result
: Значение, полученное в результате выполнения сценария.
Эта функция выполняет строку кода JavaScript и возвращает результат со следующими оговорками:
- В отличие от
eval
, эта функция не позволяет скрипту получить доступ к текущей лексической области видимости и, следовательно, также не позволяет получить доступ к область применения модуля, что означает, что псевдоглобальные объекты, такие какrequire
не будет доступен. - Скрипт может получить доступ к глобальный масштаб. Функция и
var
объявления в скрипте будут добавлены вglobal
объект. Объявления переменных, сделанные с использованиемlet
а такжеconst
будут видны глобально, но не будут добавлены вglobal
объект. - Значение
this
являетсяglobal
внутри сценария.
цикл событий libuv¶
Node-API предоставляет функцию для получения текущего цикла событий, связанного с конкретным napi_env
.
napi_get_uv_event_loop¶
NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env,
struct uv_loop_s** loop);
[in] env
: Среда, в которой вызывается API.[out] loop
: Текущий экземпляр цикла libuv.
Асинхронные вызовы поточно-ориентированных функций¶
Функции JavaScript обычно могут быть вызваны только из основного потока собственного надстройки. Если надстройка создает дополнительные потоки, то функции Node-API, требующие napi_env
, napi_value
, или napi_ref
не должны вызываться из этих потоков.
Когда надстройка имеет дополнительные потоки и функции JavaScript необходимо вызывать на основе обработки, выполненной этими потоками, эти потоки должны взаимодействовать с основным потоком надстройки, чтобы основной поток мог вызывать функцию JavaScript от их имени. API-интерфейсы поточно-ориентированных функций предоставляют простой способ сделать это.
Эти API предоставляют тип napi_threadsafe_function
а также API для создания, уничтожения и вызова объектов этого типа. napi_create_threadsafe_function()
создает постоянную ссылку на napi_value
который содержит функцию JavaScript, которую можно вызывать из нескольких потоков. Вызовы происходят асинхронно. Это означает, что значения, с которыми должен быть вызван обратный вызов JavaScript, будут помещены в очередь, и для каждого значения в очереди в конечном итоге будет выполнен вызов функции JavaScript.
При создании napi_threadsafe_function
а napi_finalize
обратный звонок может быть предоставлен. Этот обратный вызов будет вызываться в основном потоке, когда потокобезопасная функция вот-вот будет уничтожена. Он получает контекст и данные финализации, предоставленные во время построения, и предоставляет возможность для очистки после потоков, например. позвонив uv_thread_join()
. За исключением потока основного цикла, потоки не должны использовать потокобезопасную функцию после завершения обратного вызова finalize.
В context
данный во время звонка napi_create_threadsafe_function()
может быть получен из любого потока с помощью вызова napi_get_threadsafe_function_context()
.
Вызов поточно-ориентированной функции¶
napi_call_threadsafe_function()
может использоваться для инициирования вызова в JavaScript. napi_call_threadsafe_function()
принимает параметр, который определяет, будет ли API вести себя блокирующим образом. Если установлено на napi_tsfn_nonblocking
, API ведет себя неблокирующе, возвращая napi_queue_full
если очередь была заполнена, что препятствует успешному добавлению данных в очередь. Если установлено на napi_tsfn_blocking
, API блокируется до тех пор, пока в очереди не станет доступным место. napi_call_threadsafe_function()
никогда не блокируется, если потокобезопасная функция была создана с максимальным размером очереди 0.
napi_call_threadsafe_function()
не следует называть napi_tsfn_blocking
из потока JavaScript, потому что, если очередь заполнена, это может вызвать взаимоблокировку потока JavaScript.
Фактический вызов в JavaScript контролируется обратным вызовом, заданным через call_js_cb
параметр. call_js_cb
вызывается в основном потоке один раз для каждого значения, которое было помещено в очередь в результате успешного вызова napi_call_threadsafe_function()
. Если такой обратный вызов не задан, будет использоваться обратный вызов по умолчанию, и результирующий вызов JavaScript не будет иметь аргументов. В call_js_cb
обратный вызов получает функцию JavaScript для вызова как napi_value
по своим параметрам, а также void*
указатель контекста, используемый при создании napi_threadsafe_function
и следующий указатель данных, созданный одним из вторичных потоков. Затем обратный вызов может использовать API, например napi_call_function()
для вызова JavaScript.
Обратный вызов также может быть вызван с помощью env
а также call_js_cb
оба установлены на NULL
чтобы указать, что вызовы JavaScript больше невозможны, а в очереди остаются элементы, которые, возможно, необходимо освободить. Обычно это происходит, когда процесс Node.js завершается, в то время как потокобезопасная функция все еще активна.
Нет необходимости вызывать JavaScript через napi_make_callback()
потому что Node-API работает call_js_cb
в контексте, подходящем для обратных вызовов.
Подсчет ссылок поточно-ориентированных функций¶
Темы можно добавлять и удалять из napi_threadsafe_function
объект за время его существования. Таким образом, помимо указания начального количества потоков при создании, napi_acquire_threadsafe_function
может быть вызван, чтобы указать, что новый поток начнет использовать потокобезопасную функцию. Сходным образом, napi_release_threadsafe_function
может быть вызван, чтобы указать, что существующий поток перестанет использовать потокобезопасную функцию.
napi_threadsafe_function
объекты уничтожаются, когда каждый поток, использующий объект, вызвал napi_release_threadsafe_function()
или получил статус возврата napi_closing
в ответ на звонок napi_call_threadsafe_function
. Очередь очищается до napi_threadsafe_function
уничтожен. napi_release_threadsafe_function()
должен быть последним вызовом API, выполненным вместе с заданным napi_threadsafe_function
, потому что после завершения вызова нет гарантии, что napi_threadsafe_function
по-прежнему выделяется. По той же причине не используйте потокобезопасные функции после получения возвращаемого значения napi_closing
в ответ на звонок napi_call_threadsafe_function
. Данные, связанные с napi_threadsafe_function
может быть освобожден в его napi_finalize
обратный вызов, который был передан napi_create_threadsafe_function()
. Параметр initial_thread_count
из napi_create_threadsafe_function
отмечает начальное количество получений потоковобезопасных функций вместо вызова napi_acquire_threadsafe_function
несколько раз при создании.
Как только количество потоков, использующих napi_threadsafe_function
достигает нуля, никакие другие потоки не могут начать использовать его, вызывая napi_acquire_threadsafe_function()
. Фактически, все последующие вызовы API, связанные с ним, кроме napi_release_threadsafe_function()
, вернет значение ошибки napi_closing
.
Поточно-ориентированную функцию можно «прервать», задав значение napi_tsfn_abort
к napi_release_threadsafe_function()
. Это приведет к тому, что все последующие API, связанные с поточно-ориентированной функцией, кроме napi_release_threadsafe_function()
возвращать napi_closing
даже до того, как его счетчик ссылок достигнет нуля. Особенно, napi_call_threadsafe_function()
вернусь napi_closing
, тем самым сообщая потокам, что больше невозможно выполнять асинхронные вызовы поточно-ориентированной функции. Это можно использовать как критерий для завершения потока. При получении возвращаемого значения napi_closing
из napi_call_threadsafe_function()
поток не должен больше использовать потокобезопасную функцию, потому что больше не гарантируется его выделение.
Принятие решения о том, следует ли продолжать процесс¶
Подобно дескрипторам libuv, потокобезопасные функции могут иметь «ссылки» и «ссылки без ссылок». «Ссылочная» потокобезопасная функция заставит цикл событий в потоке, в котором он создан, оставаться активным до тех пор, пока потокобезопасная функция не будет уничтожена. Напротив, поточно-ориентированная функция "без ссылки" не предотвратит выход из цикла обработки событий. API napi_ref_threadsafe_function
а также napi_unref_threadsafe_function
существуют для этой цели.
Также не делает napi_unref_threadsafe_function
пометить потокобезопасные функции как подлежащие уничтожению и не napi_ref_threadsafe_function
предотвратить его разрушение.
napi_create_threadsafe_function¶
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
: Среда, в которой вызывается API.[in] func
: Необязательная функция JavaScript для вызова из другого потока. Он должен быть предоставлен, еслиNULL
передаетсяcall_js_cb
.[in] async_resource
: Необязательный объект, связанный с асинхронной работой, который будет передан возможномуasync_hooks
init
крючки.[in] async_resource_name
: Строка JavaScript для предоставления идентификатора типа ресурса, предоставляемого для диагностической информации, предоставляемойasync_hooks
API.[in] max_queue_size
: Максимальный размер очереди.0
без ограничений.[in] initial_thread_count
: Начальное количество захватов, то есть начальное количество потоков, включая основной поток, которые будут использовать эту функцию.[in] thread_finalize_data
: Необязательные данные для передачи вthread_finalize_cb
.[in] thread_finalize_cb
: Дополнительная функция для вызова, когдаnapi_threadsafe_function
разрушается.[in] context
: Необязательные данные для присоединения к результирующемуnapi_threadsafe_function
.[in] call_js_cb
: Необязательный обратный вызов, который вызывает функцию JavaScript в ответ на вызов в другом потоке. Этот обратный вызов будет вызываться в основном потоке. Если не указан, функция JavaScript будет вызываться без параметров и сundefined
как егоthis
ценить.napi_threadsafe_function_call_js
предоставляет более подробную информацию.[out] result
: Асинхронная поточно-ориентированная функция JavaScript.
napi_get_threadsafe_function_context¶
NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
void** result);
[in] func
: Поточно-ориентированная функция, для которой нужно получить контекст.[out] result
: Место для хранения контекста.
Этот API может быть вызван из любого потока, который использует func
.
napi_call_threadsafe_function¶
NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
void* data,
napi_threadsafe_function_call_mode is_blocking);
[in] func
: Вызываемая асинхронная поточно-ориентированная функция JavaScript.[in] data
: Данные для отправки в JavaScript через обратный вызовcall_js_cb
предоставляется при создании потокобезопасной функции JavaScript.[in] is_blocking
: Флаг, значение которого может быть либоnapi_tsfn_blocking
чтобы указать, что вызов должен блокироваться, если очередь заполнена, илиnapi_tsfn_nonblocking
чтобы указать, что вызов должен немедленно вернуться со статусомnapi_queue_full
всякий раз, когда очередь заполнена.
Этот API не следует вызывать с napi_tsfn_blocking
из потока JavaScript, потому что, если очередь заполнена, это может вызвать взаимоблокировку потока JavaScript.
Этот API вернет napi_closing
если napi_release_threadsafe_function()
был вызван с abort
установлен в napi_tsfn_abort
из любого потока. Значение добавляется в очередь только в том случае, если API возвращает napi_ok
.
Этот API может быть вызван из любого потока, который использует func
.
napi_acquire_threadsafe_function¶
NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);
[in] func
: Асинхронная поточно-ориентированная функция JavaScript, которую нужно начать использовать.
Поток должен вызвать этот API перед передачей func
к любым другим API-интерфейсам поточно-ориентированных функций, чтобы указать, что он будет использовать func
. Это предотвращает func
от уничтожения, когда все другие потоки перестали его использовать.
Этот API может быть вызван из любого потока, который начнет использовать func
.
napi_release_threadsafe_function¶
NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
napi_threadsafe_function_release_mode mode);
[in] func
: Асинхронная поточно-ориентированная функция JavaScript, счетчик ссылок которой подлежит уменьшению.[in] mode
: Флаг, значение которого может быть либоnapi_tsfn_release
чтобы указать, что текущий поток больше не будет вызывать поточно-ориентированную функцию, илиnapi_tsfn_abort
чтобы указать, что в дополнение к текущему потоку никакой другой поток не должен делать никаких дальнейших вызовов поточно-ориентированной функции. Если установлено наnapi_tsfn_abort
, дальнейшие звонки вnapi_call_threadsafe_function()
вернусьnapi_closing
, и никакие другие значения не будут помещены в очередь.
Поток должен вызывать этот API, когда он перестает использовать func
. Проходящий func
к любым потокобезопасным API-интерфейсам после вызова этого API-интерфейса есть неопределенные результаты, так как func
возможно, были уничтожены.
Этот API может быть вызван из любого потока, который перестанет использовать func
.
napi_ref_threadsafe_function¶
NAPI_EXTERN napi_status
napi_ref_threadsafe_function(napi_env env, napi_threadsafe_function func);
[in] env
: Среда, в которой вызывается API.[in] func
: Потокобезопасная функция для ссылки.
Этот API используется, чтобы указать, что цикл событий, запущенный в основном потоке, не должен завершаться до тех пор, пока func
был разрушен. Похожий на uv_ref
он также идемпотентен.
Также не делает napi_unref_threadsafe_function
пометить потокобезопасные функции как подлежащие уничтожению и не napi_ref_threadsafe_function
предотвратить его разрушение. napi_acquire_threadsafe_function
а также napi_release_threadsafe_function
доступны для этой цели.
Этот API можно вызывать только из основного потока.
napi_unref_threadsafe_function¶
NAPI_EXTERN napi_status
napi_unref_threadsafe_function(napi_env env, napi_threadsafe_function func);
[in] env
: Среда, в которой вызывается API.[in] func
: Поточно-ориентированная функция без ссылки.
Этот API используется, чтобы указать, что цикл событий, запущенный в основном потоке, может завершиться до того, как func
уничтожен. Похожий на uv_unref
он также идемпотентен.
Этот API можно вызывать только из основного потока.
Разные утилиты¶
node_api_get_module_file_name¶
Стабильность: 1 - экспериментальная
NAPI_EXTERN napi_status
node_api_get_module_file_name(napi_env env, const char** result);
[in] env
: Среда, в которой вызывается API.[out] result
: URL-адрес, содержащий абсолютный путь к месту, из которого была загружена надстройка. Для файла в локальной файловой системе он будет начинаться сfile://
. Строка заканчивается нулем и принадлежитenv
и поэтому не должны быть изменены или освобождены.
result
может быть пустой строкой, если в процессе загрузки надстройки не удается установить имя файла надстройки во время загрузки.