N-API

Устойчивость: 1 - Экспериментальная

N-API (произносится как N, как в букве, за которым следует API) — это API для создания нативных дополнений. Оно независимо от основного JavaScript-движка (например, V8) и поддерживается как часть самого Node.js. Это API будет стабильным по отношению к интерфейсу двоичных файлов (ABI) в разных версиях Node.js. Оно призвано изолировать дополнения от изменений в основном JavaScript-движке и позволить модулям, скомпилированным для одной версии, работать в более поздних версиях Node.js без перекомпиляции.

Дополнения строятся/упаковываются с тем же подходом/инструментами, что и в разделе, озаглавленном C++ Дополнения. Единственное отличие — набор API, используемый нативным кодом. Вместо использования API V8 или Нативных абстракций для Node.js, используются функции, доступные в N-API.

API, экспонированные N-API, в основном используются для создания и управления значениями JavaScript. Концепции и операции обычно соответствуют идеям, описанным в спецификации языка ECMA262. API имеют следующие свойства:

Все вызовы N-API возвращают код состояния типа napi_status. Это состояние указывает, успешно ли выполнился API-вызов или нет.
Значение возврата API передаётся через параметр-результат.
Все значения JavaScript абстрагированы за непрозрачным типом, названным napi_value.
В случае кода состояния ошибки дополнительная информация может быть получена с помощью napi_get_last_error_info. Дополнительная информация представлена в разделе обработки ошибок Обработка Ошибок.

Документация для N-API структурирована следующим образом:

Основные типы данных N-API
Обработка ошибок
Управление жизненным циклом объектов
Регистрация модулей
Работа со значениями JavaScript
Работа со значениями JavaScript — абстрактные операции
Работа со свойствами JavaScript
Работа с JavaScript-функциями
Обёртка объекта
Простые асинхронные операции
Пользовательские асинхронные операции
Обещания
Выполнение скриптов

N-API — это C API, который гарантирует стабильность ABI в разных версиях Node.js и уровнях компилятора. Однако мы также понимаем, что C++ API может быть проще в использовании во многих случаях. Для поддержки таких случаев ожидается наличие одного или нескольких модулей оберток C++, предоставляющих инлайновый C++ API. Бинарные файлы, созданные с этими модулями оберток, будут зависеть от символов функций N-API на C, экспортированных Node.js. Эти обертки не являются частью N-API и не будут поддерживаться как часть Node.js. Одним из таких примеров является: node-api.

Для использования функций N-API, включите файл node_api.h, который находится в директории src в дереве разработки node. Например:

#include <node_api.h>

Основные типы данных N-API

N-API экспонирует следующие фундаментальные типы данных как абстракции, используемые различными API. Эти API следует рассматривать как непрозрачные, инспектируемые только другими вызовами N-API.

napi_status

Целочисленный код состояния, указывающий на успешность или неудачу вызова N-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_status_last
} 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: код состояния N-API, связанный с последней ошибкой.

Дополнительную информацию см. в разделе Обработка ошибок.

napi_env

napi_env используется для представления контекста, который реализация N-API может использовать для сохранения состояния, специфичного для виртуальной машины. Эта структура передаётся в нативные функции при их вызове, и её необходимо передавать обратно при выполнении вызовов N-API. Конкретно, тот же napi_env, что и при вызове исходной нативной функции, должен передаваться любым последующим вложенным вызовам N-API. Кэширование napi_env для целей общего повторного использования запрещено.

napi_value

Это непрозрачный указатель, используемый для представления значения JavaScript.

Типы управления памятью N-API

napi_handle_scope

Это абстракция, используемая для управления и изменения жизненного цикла объектов, созданных в определённом контексте. В целом, значения N-API создаются в контексте области видимости handle. Когда нативная функция вызывается из JavaScript, существует стандартная область видимости handle. Если пользователь явно не создаёт новую область видимости handle, значения N-API будут созданы в стандартной области видимости handle. Для любых вызовов кода за пределами выполнения нативной функции (например, во время вызова обратного вызова libuv), модуль должен создать область видимости перед вызовом любых функций, которые могут привести к созданию значений JavaScript.

Области видимости handle создаются с помощью napi_open_handle_scope и уничтожаются с помощью napi_close_handle_scope. Закрытие области видимости может указать сборщику мусора, что все napi_value созданные во время существования области видимости handle, больше не ссылаются из текущей области стека.

Для получения более подробной информации см. раздел Управление жизненным циклом объектов.

napi_escapable_handle_scope

Области видимости escapable handle — это специальный тип областей видимости handle для возврата значений, созданных в определённой области видимости handle, в родительскую область видимости.

napi_ref

Это абстракция, используемая для ссылки на napi_value. Это позволяет пользователям управлять жизненным циклом значений JavaScript, включая явное определение их минимального жизненного цикла.

Для получения более подробной информации см. раздел Управление жизненным циклом объектов.

Типы обратных вызовов N-API

napi_callback_info

Непрозрачный тип данных, передаваемый функции обратного вызова. Он может использоваться для получения дополнительной информации о контексте, в котором был вызван обратный вызов.

napi_callback

Тип указателя на функцию для пользовательских нативных функций, которые должны быть экспонированы JavaScript через N-API. Функции обратного вызова должны соответствовать следующей сигнатуре:

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

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

napi_async_complete_callback

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

Обработка ошибок

N-API использует как значения возврата, так и исключения JavaScript для обработки ошибок. В следующих разделах описывается подход для каждого случая.

Значения возврата

Все функции N-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: Код состояния n-api для последней ошибки.

napi_get_last_error_info возвращает информацию для последнего выполненного вызова N-API.

Примечание: Не полагайтесь на содержимое или формат любой дополнительной информации, поскольку они не подлежат SemVer и могут изменяться в любое время. Они предназначены только для целей ведения журнала.

napi_get_last_error_info

Добавлено в: v8.0.0

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

[in] env: Среда, в которой вызывается API.
[out] result: Структура napi_extended_error_info с дополнительной информацией об ошибке.

Возвращает napi_ok если API выполнен успешно.

Этот API получает структуру napi_extended_error_info с информацией о последней возникшей ошибке.

Примечание: Содержимое napi_extended_error_info является корректным только до вызова функции n-api на том же env.

Примечание: Не полагайтесь на содержимое или формат расширенной информации, так как оно не регулируется SemVer и может измениться в любое время. Оно предназначено только для целей протоколирования.

К этому API можно обращаться даже при наличии ожидающего исключения JavaScript.

Исключения

Любой вызов функции N-API может привести к возникновению ожидающего исключения JavaScript. Это, очевидно, относится к любой функции, которая может вызвать выполнение JavaScript, но N-API указывает, что исключение может быть ожидающим при возврате из любой функции API.

Если значение napi_status возвращаемое функцией, равно napi_ok, то исключение не ожидается, и дополнительные действия не требуются. Если возвращаемое значение napi_status отличается от napi_ok или napi_pending_exception, для попытки восстановления и продолжения вместо простого немедленного возврата необходимо вызвать napi_is_exception_pending для определения наличия ожидающего исключения.

Когда ожидается исключение, можно использовать один из двух подходов.

Первый подход заключается в выполнении необходимой очистки и возврате, чтобы управление вернулось в JavaScript. В процессе возврата в JavaScript исключение будет сгенерировано в той точке кода JavaScript, где вызывался родной метод. Поведение большинства вызовов N-API не определено, пока ожидается исключение, и многие просто вернут napi_pending_exception, поэтому важно выполнить как можно меньше действий и вернуть управление в JavaScript, где исключение может быть обработано.

Второй подход заключается в попытке обработать исключение. В некоторых случаях родной код может перехватить исключение, выполнить соответствующие действия и продолжить. Это рекомендуется только в определённых случаях, когда известно, что исключение может быть безопасно обработано. В таких случаях можно использовать napi_get_and_clear_last_exception для получения и очистки исключения. При успехе результат будет содержать идентификатор последнего сгенерированного JavaScript-объекта исключения. Если после получения исключения выяснится, что оно не может быть обработано, его можно повторно сгенерировать с помощью napi_throw, где error — объект JavaScript Error, который нужно сгенерировать.

Также доступны следующие вспомогательные функции в случае, если родной код должен сгенерировать исключение или определить, является ли 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. где result — значение napi_value, ссылающееся на только что созданный объект JavaScript Error.

Проект Node.js добавляет коды ошибок ко всем внутренне генерируемым ошибкам. Цель заключается в том, чтобы приложения использовали эти коды ошибок для всех проверок ошибок. Соответствующие сообщения об ошибках остаются, но предназначены только для протоколирования и отображения, с ожиданием, что сообщение может измениться без применения SemVer. Для поддержки этой модели в N-API, как во внутренней функциональности, так и для функциональности конкретного модуля (как это хорошая практика), функции throw_ и create_ принимают необязательный параметр code, который представляет собой строку для добавления кода в объект ошибки. Если необязательный параметр равен NULL, код не будет ассоциирован с ошибкой. Если код предоставлен, имя, ассоциированное с ошибкой, также обновляется следующим образом:

originalName [code]

где originalName — исходное имя ошибки, а code — предоставленный код. Например, если код равен 'ERR_ERROR_1' и создаётся TypeError, имя будет:

TypeError [ERR_ERROR_1]

napi_throw

Добавлена в: v8.0.0

NODE_EXTERN napi_status napi_throw(napi_env env, napi_value error);

[in] env: Окружение, в котором вызывается API.
[in] error: napi_value объекта Error, который необходимо сгенерировать.

Возвращает napi_ok, если API выполнена успешно.

Это API генерирует исключение JavaScript Error.

napi_throw_error

Добавлена в: v8.0.0

NODE_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

Добавлена в: v8.0.0

NODE_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

Добавлена в: v8.0.0

NODE_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

Добавлена в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] msg: Проверяемый napi_value.
[out] result: Булево значение, которое устанавливается в true, если napi_value представляет ошибку, в противном случае — false.

Возвращает napi_ok, если API выполнена успешно.

Это API проверяет napi_value на предмет того, является ли он объектом ошибки.

napi_create_error

Добавлена в: v8.0.0

NODE_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 со строковым кодом ошибки для
```
         be associated with the error.
```
[in] msg: napi_value, ссылающийся на JavaScript-строку, используемую в качестве сообщения для ошибки.
[out] result: napi_value созданной ошибки.

Возвращает napi_ok, если API выполнена успешно.

Это API возвращает объект JavaScript Error с предоставленным текстом.

napi_create_type_error

Добавлена в: v8.0.0

NODE_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 со строковым кодом ошибки для
```
         be associated with the error.
```
[in] msg: napi_value, ссылающийся на JavaScript-строку, используемую в качестве сообщения для ошибки.
[out] result: napi_value созданной ошибки.

Возвращает napi_ok, если API выполнена успешно.

Это API возвращает объект JavaScript TypeError с предоставленным текстом.

napi_create_range_error

Добавлена в: v8.0.0

NODE_EXTERN napi_status napi_create_range_error(napi_env env,
                                                napi_value code,
                                                const char* msg,
                                                napi_value* result);

[in] env: Окружение, в котором вызывается API.
[in] code: Необязательный napi_value со строковым кодом ошибки для
```
         be associated with the error.
```
[in] msg: napi_value, ссылающийся на JavaScript-строку, используемую в качестве сообщения для ошибки.
[out] result: napi_value созданной ошибки.

Возвращает napi_ok, если API выполнена успешно.

Это API возвращает объект JavaScript RangeError с предоставленным текстом.

napi_get_and_clear_last_exception

Добавлена в: v8.0.0

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result);

[in] env: Окружение, в котором вызывается API.
[out] result: Исключение, если оно ожидается, в противном случае NULL.

Возвращает napi_ok, если API выполнена успешно.

Это API возвращает true, если ожидается исключение.

К этому API можно обращаться даже при наличии ожидающего исключения JavaScript.

napi_is_exception_pending

Добавлена в: v8.0.0

napi_status napi_is_exception_pending(napi_env env, bool* result);

[in] env: Окружение, в котором вызывается API.
[out] result: Булево значение, которое устанавливается в true, если ожидается исключение.

Возвращает napi_ok, если API выполнена успешно.

Это API возвращает true, если ожидается исключение.

К этому API можно обращаться даже при наличии ожидающего исключения JavaScript.

napi_fatal_exception

Добавлена в: v6.14.2

napi_status napi_fatal_exception(napi_env env, napi_value err);

[in] env: Окружение, в котором вызывается API.
[in] err: Ошибка, которую нужно передать в uncaughtException.

Вызывает uncaughtException в JavaScript. Полезно, если асинхронный обработчик вызывает исключение без возможности восстановления.

Критические ошибки

В случае невосстановимой ошибки в родном модуле может быть сгенерирована критическая ошибка, чтобы немедленно завершить процесс.

napi_fatal_error

Добавлена в: v6.14.2

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.

Управление жизненным циклом объектов

При выполнении вызовов N-API могут возвращаться дескрипторы объектов в куче для базовой виртуальной машины в качестве napi_values. Эти дескрипторы должны удерживать объекты «живыми» до тех пор, пока они больше не требуются кодом нативных языков, в противном случае объекты могут быть собраны сборщиком мусора до завершения их использования кодом нативных языков.

Когда возвращаются дескрипторы объектов, они ассоциируются с «областью видимости». Жизненный цикл по умолчанию связан с жизненным циклом вызова метода нативного языка. В результате дескрипторы по умолчанию остаются валидными, а объекты, связанные с этими дескрипторами, будут удерживаться живыми на протяжении всего вызова метода нативного языка.

Однако во многих случаях необходимо, чтобы дескрипторы оставались валидными в течение более короткого или более длительного жизненного цикла, чем жизненный цикл нативного метода. В следующих разделах описаны функции N-API, которые можно использовать для изменения жизненного цикла дескрипторов от значения по умолчанию.

Сокращение жизненного цикла дескрипторов по сравнению с жизненным циклом нативного метода

Часто необходимо сократить жизненный цикл дескрипторов по сравнению с жизненным циклом нативного метода. Например, рассмотрим нативный метод, содержащий цикл, который итерирует элементы в большом массиве:

for (int i = 0; i < 1000000; i++) {
  napi_value result;
  napi_status status = napi_get_element(e, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // do something with element
}

Это приведет к созданию большого количества дескрипторов, что потребует значительных ресурсов. Кроме того, даже если код нативного языка может использовать только самый последний дескриптор, все связанные объекты также будут удерживаться живыми, поскольку они все относятся к одной и той же области видимости.

Для решения этой проблемы N-API предоставляет возможность создания новой «области видимости», к которой будут привязаны вновь созданные дескрипторы. После того, как эти дескрипторы больше не понадобятся, область видимости можно закрыть, и все дескрипторы, связанные с ней, станут невалидными. Методы открытия/закрытия областей видимости — это napi_open_handle_scope и napi_close_handle_scope.

N-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(e, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // do something with element
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
}

При вложенности областей видимости существуют случаи, когда дескриптор из внутренней области видимости должен сохранять актуальность после окончания жизненного цикла этой области. N-API поддерживает «избегаемую область видимости», чтобы справиться с этим случаем. Избегаемая область видимости позволяет одному дескриптору быть «продвинутым» таким образом, что он «выходит» из текущей области видимости, и жизненный цикл дескриптора изменяется с текущей области видимости на внешнюю область видимости.

Методы открытия/закрытия избегаемых областей видимости — это napi_open_escapable_handle_scope и napi_close_escapable_handle_scope.

Запрос на продвижение дескриптора выполняется с помощью napi_escape_handle, который может быть вызван только один раз.

napi_open_handle_scope

Добавлен в: v8.0.0

NODE_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

Добавлен в: v8.0.0

NODE_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

Добавлен в: v8.0.0

NODE_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

Добавлен в: v8.0.0

NODE_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 может быть вызван даже при наличии ожидающего JavaScript-исключения.

napi_escape_handle

Добавлен в: v8.0.0

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 представляющий JavaScript-объект, который необходимо сделать доступным во внешней области видимости.
[out] result: napi_value представляющий дескриптор объекта, доступного во внешней области видимости.

Возвращает napi_ok в случае успешного выполнения API.

Этот API продвигает дескриптор JavaScript-объекта так, что он остается валидным на протяжении всего жизненного цикла внешней области видимости. Он может быть вызван только один раз в рамках одной области видимости. Если он вызывается более одного раза, будет возвращено сообщение об ошибке.

Этот API может быть вызван даже при наличии ожидающего JavaScript-исключения.

Ссылки на объекты с жизненным циклом, превышающим жизненный цикл нативного метода

В некоторых случаях плагину необходимо создавать и ссылаться на объекты с жизненным циклом, превышающим вызов одного нативного метода. Например, чтобы создать конструктор и позже использовать этот конструктор в запросе на создание экземпляров, необходимо иметь возможность ссылаться на объект конструктора в рамках нескольких различных запросов на создание экземпляров. Это не представляется возможным с обычным дескриптором, возвращенным как napi_value, как описано в предыдущем разделе. Жизненный цикл обычного дескриптора управляется областями видимости, и все области видимости должны быть закрыты до завершения нативного метода.

N-API предоставляет методы для создания постоянных ссылок на объект. Каждая постоянная ссылка имеет связанный счетчик со значением 0 или больше. Счетчик определяет, будет ли ссылка удерживать соответствующий объект живым. Ссылки со счетчиком 0 не препятствуют сбору мусора и часто называются «слабыми» ссылками. Любой счетчик, превышающий 0, будет предотвращать сбор мусора объекта.

Ссылки могут быть созданы с начальным значением счетчика ссылок. Затем счетчик можно изменить с помощью napi_reference_ref и napi_reference_unref. Если объект собран, в то время как счетчик ссылок равен 0, все последующие вызовы получения объекта, связанного со ссылкой napi_get_reference_value, вернут NULL для возвращенного napi_value. Попытка вызвать napi_reference_ref для ссылки, объект которой был собран, приведет к ошибке.

Ссылки необходимо удалять, когда они больше не требуются плагином. После удаления ссылки она больше не будет препятствовать сбору мусора соответствующего объекта. Отсутствие удаления постоянной ссылки приведет к утечке памяти, при которой как нативные данные постоянной ссылки, так и соответствующий объект в куче будут удерживаться навсегда.

Можно создать несколько постоянных ссылок, которые ссылаются на один и тот же объект, каждая из которых либо удерживает объект живым, либо нет, в зависимости от собственного счетчика.

napi_create_reference

Добавлен в: v8.0.0

NODE_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              int initial_refcount,
                                              napi_ref* result);

[in] env: Окружение, в котором вызывается API.
[in] value: napi_value представляющий объект, для которого требуется ссылка.
[in] initial_refcount: Начальный счетчик ссылок для новой ссылки.
[out] result: napi_ref указывающий на новую ссылку.

Возвращает napi_ok в случае успешного выполнения API.

Этот API создает новую ссылку с указанным счетчиком ссылок на переданный объект.

napi_delete_reference

Добавлен в: v8.0.0

NODE_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

Добавлен в: v8.0.0

NODE_EXTERN napi_status napi_reference_ref(napi_env env,
                                           napi_ref ref,
                                           int* result);

[in] env: Окружение, в котором вызывается API.
[in] ref: napi_ref для которой необходимо увеличить счетчик ссылок.
[out] result: Новое значение счетчика ссылок.

Возвращает napi_ok в случае успешного выполнения API.

Этот API увеличивает счетчик ссылок для переданной ссылки и возвращает полученное значение.

napi_reference_unref

Добавлен в: v8.0.0

NODE_EXTERN napi_status napi_reference_unref(napi_env env,
                                             napi_ref ref,
                                             int* result);

[in] env: Окружение, в котором вызывается API.
[in] ref: napi_ref для которой необходимо уменьшить счетчик ссылок.
[out] result: Новое значение счетчика ссылок.

Возвращает napi_ok в случае успешного выполнения API.

Этот API уменьшает счетчик ссылок для переданной ссылки и возвращает полученное значение.

napi_get_reference_value

Добавлен в: v8.0.0

NODE_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, для которого запрашивается соответствующий объект.
[out] result: napi_value для объекта, на который ссылается napi_ref.

Возвращает napi_ok в случае успешного выполнения API.

Если это всё ещё допустимо, API возвращает napi_value, представляющий JavaScript-объект, связанный с napi_ref. В противном случае результат будет NULL.

Регистрация модулей

Модули N-API регистрируются аналогично другим модулям, за исключением того, что вместо макроса NODE_MODULE используется следующее:

NAPI_MODULE(addon, Init)

Следующее отличие заключается в сигнатуре метода Init. Для модуля N-API она выглядит следующим образом:

napi_value Init(napi_env env, napi_value exports);

Возвращаемое значение из Init рассматривается как объект exports для модуля. Метод Init получает пустой объект через параметр exports в качестве удобства. Если Init возвращает NULL, параметр, переданный как exports экспортируется модулем. Модули N-API не могут изменять объект module, но могут указать любое значение в качестве свойства exports модуля.

Например, чтобы добавить метод hello в качестве функции, чтобы его можно было вызывать как метод, предоставляемый дополнением:

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor desc =
    {"hello", Method, 0, 0, 0, napi_default, 0};
  if (status != napi_ok) return 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, GetValue, SetValue, 0, napi_default, 0 },
    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;
}

Для получения более подробной информации об установке свойств объектов см. раздел Работа со свойствами JavaScript.

Для получения более подробной информации о построении модулей дополнений в целом, обратитесь к существующему API

Работа со значениями JavaScript

N-API предоставляет набор API для создания всех типов значений JavaScript. Некоторые из этих типов описаны в разделе 6 спецификации языка ECMAScript .

В принципе, эти API используются для выполнения одного из следующих действий:

Создание нового JavaScript-объекта
Преобразование примитивного типа C в значение N-API
Преобразование значения N-API в примитивный тип C
Получение глобальных экземпляров, включая undefined и null

Значения N-API представляются типом napi_value. Любой вызов N-API, требующий значения JavaScript, принимает значение napi_value. В некоторых случаях API проверяет тип napi_value заранее. Однако для лучшей производительности лучше, чтобы вызывающая сторона убедилась, что napi_value имеет ожидаемый JavaScript-тип, требуемый API.

Типы перечислений

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

Описывает тип napi_value. Это, как правило, соответствует типам, описанным в разделе 6.1 спецификации языка ECMAScript. Кроме типов, указанных в этом разделе, napi_valuetype также может представлять функции и объекты с внешними данными.

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

Это представляет собой базовый бинарный скалярный тип данных TypedArray. Элементы этого перечисления соответствуют разделу 22.2 спецификации языка ECMAScript .

Функции создания объектов

napi_create_array

Добавлен в: v8.0.0

napi_status napi_create_array(napi_env env, napi_value* result)

[in] env: Окружение, в котором вызывается вызов N-API.
[out] result: napi_value, представляющий JavaScript-массив.

Возвращает napi_ok в случае успешного выполнения API.

Этот API возвращает значение N-API, соответствующее типу JavaScript-массива. JavaScript-массивы описаны в разделе 22.1 спецификации языка ECMAScript.

napi_create_array_with_length

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] length: Начальная длина массива.
[out] result: napi_value, представляющий JavaScript-массив.

Возвращает napi_ok в случае успешного выполнения API.

Этот API возвращает значение N-API, соответствующее типу JavaScript-массива. Свойство length массива устанавливается в переданный параметр длины. Однако гарантии предварительной выделения буфера в памяти не гарантируется при создании массива в виртуальной машине (VM) – это поведение зависит от реализации VM. Если буфер должен быть непрерывным блоком памяти, который можно непосредственно читать и/или записывать через C, рассмотрите использование napi_create_external_arraybuffer.

JavaScript-массивы описаны в разделе 22.1 спецификации языка ECMAScript.

napi_create_arraybuffer

Добавлен в: v8.0.0

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, представляющий JavaScript-ArrayBuffer.

Возвращает napi_ok в случае успешного выполнения API.

Этот API возвращает значение N-API, соответствующее JavaScript-ArrayBuffer. ArrayBuffer используется для представления буферов бинарных данных фиксированной длины. Обычно они используются в качестве буфера подложки для объектов TypedArray. Выделенный ArrayBuffer будет иметь базовый байтовый буфер, размер которого определяется параметром length.

Базовый буфер, по желанию, возвращается вызывающей стороне, если вызывающая сторона хочет напрямую манипулировать им. Этот буфер может быть записан только напрямую из кода на языке C. Чтобы записать в этот буфер из JavaScript, необходимо создать объект TypedArray или DataView.

Объекты JavaScript ArrayBuffer описаны в разделе 24.1 спецификации языка ECMAScript.

napi_create_buffer

Добавлен в: v8.0.0

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.

napi_create_buffer_copy

Добавлен в: v8.0.0

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: Указатель на базовый буфер данных нового буфера.
[out] result: napi_value, представляющий node::Buffer.

Возвращает napi_ok в случае успешного выполнения API.

Этот API выделяет объект node::Buffer и инициализирует его данными, скопированными из переданного буфера. Хотя эта структура по-прежнему полностью поддерживается, в большинстве случаев будет достаточно использования TypedArray.

napi_create_external

Добавлен в: v8.0.0

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: Необязательный обработчик, вызываемый при сборе внешнего значения.
[in] finalize_hint: Необязательный маркер для передачи в обработчик finalize при сборе.
[out] result: napi_value, представляющий внешнее значение.

Возвращает napi_ok в случае успешного выполнения API.

Этот API выделяет значение JavaScript с прикреплёнными к нему внешними данными. Это используется для передачи внешних данных через код JavaScript, чтобы их можно было получить позже кодом на языке C. API позволяет вызывающей стороне передавать обработчик finalize, на случай, если необходимо очистить базовые нативные ресурсы при сборе внешнего JavaScript-значения.

Примечание: Созданное значение не является объектом и поэтому не поддерживает дополнительные свойства. Оно считается отдельным типом значения: вызов napi_typeof() с внешним значением возвращает napi_external.

napi_create_external_arraybuffer

Добавлен в: v8.0.0

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.
[in] finalize_hint: Необязательный маркер для передачи в обработчик finalize при сборе.
[out] result: napi_value, представляющий JavaScript-ArrayBuffer.

Возвращает napi_ok в случае успешного выполнения API.

Этот API возвращает значение N-API, соответствующее JavaScript-ArrayBuffer. Базовый байтовый буфер ArrayBuffer выделяется и управляется внешним образом. Вызывающая сторона должна гарантировать, что байтовый буфер остаётся допустимым до вызова обработчика finalize.

Объекты JavaScript ArrayBuffer описаны в разделе 24.1 спецификации языка ECMAScript.

napi_create_external_buffer

Добавлен в: v8.0.0

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: Необработанный указатель на базовый буфер, из которого нужно копировать.
[in] finalize_cb: Необязательный обратный вызов, вызываемый при сборе ArrayBuffer.
[in] finalize_hint: Необязательный параметр, передаваемый в обратный вызов finalize при сборе.
[out] result: A napi_value представляющий node::Buffer.

Возвращает napi_ok в случае успешного выполнения API.

Этот API выделяет объект node::Buffer и инициализирует его данными, опираясь на переданный буфер. Хотя это все еще полностью поддерживаемая структура данных, в большинстве случаев достаточно использовать TypedArray.

Примечание: Для Node.js >=4 Buffers являются Uint8Arrays.

napi_create_function

Добавлено в: v8.0.0

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.
[in] length: Длина utf8name в байтах или NAPI_AUTO_LENGTH если она имеет нулевое завершение.
[in] cb: Указатель на функцию, которая будет вызываться, когда созданная функция вызывается из JavaScript.
[in] data: Необязательные произвольные данные контекста, которые будут переданы в нативную функцию при ее вызове.
[out] result: A napi_value представляющий JavaScript функцию.

Возвращает napi_ok в случае успешного выполнения API.

Этот API возвращает значение N-API, соответствующее объекту JavaScript Function. Он используется для обертывания нативных функций, чтобы их можно было вызывать из JavaScript.

JavaScript функции описаны в разделе 19.2 спецификации языка ECMAScript.

napi_create_object

Добавлено в: v8.0.0

napi_status napi_create_object(napi_env env, napi_value* result)

[in] env: Окружающая среда, в которой вызывается API.
[out] result: A napi_value представляющий JavaScript объект.

Возвращает napi_ok в случае успешного выполнения API.

Этот API выделяет стандартный объект JavaScript. Это эквивалентно выполнению new Object() в JavaScript.

Тип JavaScript объекта описан в разделе 6.1.7 спецификации языка ECMAScript.

napi_create_symbol

Добавлено в: v8.0.0

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

[in] env: Окружающая среда, в которой вызывается API.
[in] description: Необязательное значение napi_value, ссылающееся на JavaScript строку, которая будет установлена в качестве описания символа.
[out] result: A napi_value представляющий JavaScript символ.

Возвращает napi_ok в случае успешного выполнения API.

Этот API создает объект JavaScript Symbol из UTF8-закодированной C строки.

Тип JavaScript Symbol описан в разделе 19.4 спецификации языка ECMAScript.

napi_create_typedarray

Добавлено в: v8.0.0

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: A napi_value представляющий JavaScript TypedArray.

Возвращает napi_ok в случае успешного выполнения API.

Этот API создает объект JavaScript TypedArray над существующим ArrayBuffer. Объекты TypedArray предоставляют массивный вид на базовом буфере данных, где каждый элемент имеет одинаковый базовый двоичный скалярный тип данных.

Требуется, чтобы (length * size_of_element) + byte_offset было меньше или равно размеру переданного массива в байтах. В противном случае возникает исключение RangeError.

Объекты JavaScript TypedArray описаны в разделе 22.2 спецификации языка ECMAScript.

napi_create_dataview

Добавлено в: v6.14.2

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: A napi_value представляющий JavaScript DataView.

Возвращает napi_ok в случае успешного выполнения API.

Этот API создает объект JavaScript DataView над существующим ArrayBuffer. Объекты DataView предоставляют массивный вид на базовом буфере данных, но позволяющие использовать элементы разного размера и типа в ArrayBuffer.

Требуется, чтобы byte_length + byte_offset было меньше или равно размеру переданного массива в байтах. В противном случае возникает исключение RangeError.

Объекты JavaScript DataView описаны в разделе 24.3 спецификации языка ECMAScript.

Функции для преобразования из C типов в N-API

napi_create_int32

Добавлено в: v6.14.2

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

[in] env: Окружающая среда, в которой вызывается API.
[in] value: Целочисленное значение, которое должно быть представлено в JavaScript.
[out] result: A napi_value представляющий JavaScript число.

Возвращает napi_ok в случае успешного выполнения API.

Этот API используется для преобразования из C типа int32_t в тип JavaScript Number.

Тип JavaScript Number описан в разделе 6.1.6 спецификации языка ECMAScript.

napi_create_uint32

Добавлено в: v6.14.2

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

[in] env: Окружающая среда, в которой вызывается API.
[in] value: Беззнаковое целое значение, которое должно быть представлено в JavaScript.
[out] result: A napi_value представляющий JavaScript число.

Возвращает napi_ok в случае успешного выполнения API.

Этот API используется для преобразования из C типа uint32_t в тип JavaScript Number.

Тип JavaScript Number описан в разделе 6.1.6 спецификации языка ECMAScript.

napi_create_int64

Добавлено в: v6.14.2

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

[in] env: Окружающая среда, в которой вызывается API.
[in] value: Целочисленное значение, которое должно быть представлено в JavaScript.
[out] result: A napi_value представляющий JavaScript число.

Возвращает 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

Добавлено в: v6.14.2

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

[in] env: Окружающая среда, в которой вызывается API.
[in] value: Двойное значение, которое должно быть представлено в JavaScript.
[out] result: A napi_value представляющий JavaScript число.

Возвращает napi_ok в случае успешного выполнения API.

Этот API используется для преобразования из C типа double в тип JavaScript Number.

Тип JavaScript Number описан в разделе 6.1.6 спецификации языка ECMAScript.

napi_create_string_latin1

Добавлено в: v8.0.0

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: A napi_value представляющий JavaScript строку.

Возвращает napi_ok в случае успешного выполнения API.

Этот API создает объект JavaScript String из C строки, закодированной в ISO-8859-1.

Тип JavaScript String описан в разделе 6.1.4 спецификации языка ECMAScript.

napi_create_string_utf16

Добавлено в: v8.0.0

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: A napi_value представляющий JavaScript строку.

Возвращает napi_ok в случае успешного выполнения API.

Этот API создает объект JavaScript String из C строки, закодированной в UTF16-LE.

Тип JavaScript String описан в разделе 6.1.4 спецификации языка ECMAScript.

napi_create_string_utf8

Добавлен в: v8.0.0

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, представляющий строку JavaScript.

Возвращает napi_ok если API успешно выполнилась.

Этот API создаёт объект JavaScript String из UTF8-строки C.

Тип JavaScript String описан в Разделе 6.1.4 спецификации языка ECMAScript.

Функции преобразования из N-API в типы C

napi_get_array_length

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] value: Объект napi_value, представляющий массив JavaScript, длина которого запрашивается.
[out] result: Значение uint32, представляющее длину массива.

Возвращает napi_ok если API успешно выполнилась.

Этот API возвращает длину массива.

Длина массива описана в Разделе 22.1.4.1 спецификации языка ECMAScript.

napi_get_arraybuffer_info

Добавлен в: v8.0.0

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.
[out] byte_length: Длина базового буфера данных в байтах.

Возвращает napi_ok если API успешно выполнилась.

Этот API используется для получения базового буфера данных ArrayBuffer и его длины.

ВНИМАНИЕ: Будьте осторожны при использовании этого API. Жизненный цикл базового буфера данных управляется ArrayBuffer даже после его возврата. Безопасный способ использования этого API — в сочетании с napi_create_reference, который может использоваться для гарантии контроля над жизненным циклом ArrayBuffer. Также безопасно использовать возвращённый буфер данных в том же обратном вызове, пока не будет вызвано других API, которые могут инициировать сборку мусора.

napi_get_buffer_info

Добавлен в: v8.0.0

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.
[out] length: Длина базового буфера данных в байтах.

Возвращает napi_ok если API успешно выполнилась.

Этот API используется для получения базового буфера данных node::Buffer и его длины.

Предупреждение: Будьте осторожны при использовании этого API, так как жизненный цикл базового буфера данных не гарантируется, если он управляется виртуальной машиной.

napi_get_prototype

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] object: Объект napi_value, представляющий объект JavaScript, прототип которого нужно вернуть. Это возвращает эквивалент Object.getPrototypeOf (что не то же самое, что свойство prototype функции).
[out] result: Объект napi_value, представляющий прототип данного объекта.

Возвращает napi_ok если API успешно выполнилась.

napi_get_typedarray_info

Добавлен в: v8.0.0

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: Буфер данных, лежащий в основе массива с типом данных.
[out] byte_offset: Смещение в байтах в буфере данных, с которого начинать проецирование TypedArray.

Возвращает napi_ok если API успешно выполнилась.

Этот API возвращает различные свойства массива с типом данных.

Предупреждение: Будьте осторожны при использовании этого API, так как базовый буфер данных управляется виртуальной машиной.

napi_get_dataview_info

Добавлен в: v6.14.2

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.
[out] arraybuffer: ArrayBuffer, лежащий в основе DataView.
[out] byte_offset: Смещение в байтах в буфере данных, с которого начинать проецирование DataView.

Возвращает napi_ok если API успешно выполнилась.

Этот API возвращает различные свойства DataView.

napi_get_value_bool

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] value: Объект napi_value, представляющий булево значение JavaScript.
[out] result: Эквивалент булевого значения C, соответствующий данному булевому значению JavaScript.

Возвращает napi_ok если API успешно выполнилась. Если в качестве аргумента передан не булев napi_value, возвращается napi_boolean_expected.

Этот API возвращает эквивалент булевого значения C, соответствующий данному булевому значению JavaScript.

napi_get_value_double

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] value: Объект napi_value, представляющий число JavaScript.
[out] result: Эквивалент числа с плавающей запятой C, соответствующий данному числу JavaScript.

Возвращает napi_ok если API успешно выполнилась. Если в качестве аргумента передан не числовой napi_value, возвращается napi_number_expected.

Этот API возвращает эквивалент числа с плавающей запятой C, соответствующий данному числу JavaScript.

napi_get_value_external

Добавлен в: v8.0.0

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

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] value: Объект napi_value, представляющий число JavaScript.
[out] result: Эквивалент int32 C, соответствующий данному числу JavaScript.

Возвращает napi_ok если API успешно выполнилась. Если в качестве аргумента передан не числовой napi_value, то napi_number_expected.

Этот API возвращает эквивалент int32 C, соответствующий данному числу JavaScript.

Если число выходит за пределы диапазона 32-битного целого числа, результат усекается до эквивалента нижних 32 бит. Это может привести к тому, что большое положительное число станет отрицательным, если значение больше, чем 2^31 -1.

Неконечные числовые значения (NaN, положительная и отрицательная бесконечности) устанавливают результат в ноль.

napi_get_value_int64

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] value: Объект napi_value, представляющий число JavaScript.
[out] result: Эквивалент int64 C, соответствующий данному числу JavaScript.

Этот API возвращает эквивалент int64 C, соответствующий данному числу JavaScript.

Числовые значения, выходящие за пределы диапазона Number.MIN_SAFE_INTEGER -(2^53 - 1) - Number.MAX_SAFE_INTEGER (2^53 - 1) потеряют точность.

napi_get_value_string_latin1

Добавлен в: v8.0.0

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, возвращается длина строки (в байтах).
[in] bufsize: Размер буфера назначения. Если этот размер недостаточен, возвращаемая строка будет усечена.
[out] result: Количество скопированных байтов в буфер, без учёта терминатора null.

Возвращает napi_ok если API выполнилась успешно. Если в качестве аргумента передан не строковый napi_value, возвращается napi_string_expected.

Этот API возвращает строку ISO-8859-1, соответствующую переданному значению.

napi_get_value_string_utf8

Добавлен в: v8.0.0

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, возвращается длина строки (в байтах).
[in] bufsize: Размер буфера назначения. Если этот размер недостаточен, возвращаемая строка будет усечена.
[out] result: Количество байтов, скопированных в буфер, без учёта нулевого терминатора.

Возвращает napi_ok при успешном выполнении API. Если передан нестроковый napi_value, возвращает napi_string_expected.

Этот API возвращает закодированную в UTF8 строку, соответствующую переданному значению.

napi_get_value_string_utf16

Добавлен в: v8.0.0

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. Если передан нестроковый napi_value, возвращает napi_string_expected.

Этот API возвращает строку, закодированную в UTF16, соответствующую переданному значению.

napi_get_value_uint32

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] value: napi_value, представляющий число JavaScript.
[out] result: C-эквивалент данного napi_value как uint32_t.

Возвращает napi_ok при успешном выполнении API. Если передан нечисловой napi_value, возвращает napi_number_expected.

Этот API возвращает C-эквивалент данного napi_value как uint32_t.

Функции для получения глобальных экземпляров

napi_get_boolean

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается API.
[in] value: Значение булевого значения для извлечения.
[out] result: napi_value, представляющий JavaScript-объект Boolean для извлечения.

Возвращает napi_ok при успешном выполнении API.

Этот API используется для возвращения JavaScript-объекта, представляющего данное булевое значение.

napi_get_global

Добавлен в: v8.0.0

napi_status napi_get_global(napi_env env, napi_value* result)

[in] env: Окружение, в котором вызывается API.
[out] result: napi_value, представляющий JavaScript-объект Global.

Возвращает napi_ok при успешном выполнении API.

Этот API возвращает глобальный объект.

napi_get_null

Добавлен в: v8.0.0

napi_status napi_get_null(napi_env env, napi_value* result)

[in] env: Окружение, в котором вызывается API.
[out] result: napi_value, представляющий JavaScript-объект Null.

Возвращает napi_ok при успешном выполнении API.

Этот API возвращает объект null.

napi_get_undefined

Добавлен в: v8.0.0

napi_status napi_get_undefined(napi_env env, napi_value* result)

[in] env: Окружение, в котором вызывается API.
[out] result: napi_value, представляющий значение JavaScript Undefined.

Возвращает napi_ok при успешном выполнении API.

Этот API возвращает объект Undefined.

Работа с JavaScript-значениями - Абстрактные операции

N-API предоставляет набор API для выполнения некоторых абстрактных операций над JavaScript-значениями. Некоторые из этих операций описаны в разделе 7 Спецификации языка ECMAScript.

Эти API поддерживают выполнение одного из следующих действий:

Преобразование JavaScript-значений к определённым типам JavaScript (например, Number или String)
Проверка типа JavaScript-значения
Проверка равенства двух JavaScript-значений

napi_coerce_to_bool

Добавлен в: v8.0.0

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, представляющий преобразованное JavaScript-булевое значение.

Возвращает napi_ok при успешном выполнении API.

Этот API реализует абстрактную операцию ToBoolean, как определено в разделе 7.1.2 Спецификации языка ECMAScript. Этот API может быть многопоточным, если для переданного объекта определены геттеры.

napi_coerce_to_number

Добавлен в: v8.0.0

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, представляющий преобразованное JavaScript-число.

Возвращает napi_ok при успешном выполнении API.

Этот API реализует абстрактную операцию ToNumber, как определено в разделе 7.1.3 Спецификации языка ECMAScript. Этот API может быть многопоточным, если для переданного объекта определены геттеры.

napi_coerce_to_object

Добавлен в: v8.0.0

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, представляющий преобразованный JavaScript-объект.

Возвращает napi_ok при успешном выполнении API.

Этот API реализует абстрактную операцию ToObject, как определено в разделе 7.1.13 Спецификации языка ECMAScript. Этот API может быть многопоточным, если для переданного объекта определены геттеры.

napi_coerce_to_string

Добавлен в: v8.0.0

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, представляющий преобразованную JavaScript-строку.

Возвращает napi_ok при успешном выполнении API.

Этот API реализует абстрактную операцию ToString, как определено в разделе 7.1.13 Спецификации языка ECMAScript. Этот API может быть многопоточным, если для переданного объекта определены геттеры.

napi_typeof

Добавлен в: v8.0.0

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 не является значением External.

Этот API имитирует поведение оператора typeof, применяемого к объекту, как определено в разделе 12.5.5 Спецификации языка ECMAScript. Однако он поддерживает определение значения External. Если у value неверный тип, возвращается ошибка.

napi_instanceof

Добавлен в: v8.0.0

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 равно true.

Возвращает napi_ok при успешном выполнении API.

Этот API представляет вызов оператора instanceof, как определено в разделе 12.10.4 Спецификации языка ECMAScript.

napi_is_array

Добавлен в: v8.0.0

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

Добавлен в: v8.0.0

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 проверяет, является ли переданный объект буфером массива.

napi_is_buffer

Добавлен в: v8.0.0

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 проверяет, является ли переданный объект буфером.

napi_is_error

Добавлен в: v8.0.0

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 проверяет, является ли переданный объект объектом Error.

napi_is_typedarray

Добавлен в: v8.0.0

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 проверяет, является ли переданный объект массивом с типом.

napi_is_dataview

Добавлен в: v6.14.2

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 проверяет, является ли переданный объект объектом DataView.

napi_strict_equals

Добавлен в: v8.0.0

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.

Работа с свойствами JavaScript

N-API предоставляет набор API для получения и установки свойств объектов JavaScript. Некоторые из этих типов задокументированы в разделе 7 спецификации языка ECMAScript.

Свойства в JavaScript представлены в виде пары ключ-значение. В N-API все ключи свойств могут быть представлены в следующих формах:

Именованные: простая строка UTF8
Индексированные: значение индекса, представленное uint32_t
Значение JavaScript: в N-API они представлены как napi_value. Это может быть napi_value , представляющее строку, число или символ.

Значения N-API представлены типом napi_value. Любой вызов N-API, требующий значения JavaScript, принимает napi_value. Однако ответственность за проверку типа napi_value на соответствие ожидаемому типом JavaScript лежит на вызывающей стороне.

API, описанные в этом разделе, предоставляют простой интерфейс для получения и установки свойств произвольных объектов JavaScript, представленных napi_value.

Например, рассмотрим следующий фрагмент кода JavaScript:

const obj = {};
obj.myProp = 123;

Эквивалент можно реализовать с использованием значений N-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';

Эквивалент можно реализовать с использованием значений N-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];

Следующее приблизительно соответствует N-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 }
});

Следующее приблизительно соответствует N-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, 0, 0, 0, fooValue, napi_default, 0 },
  { "bar", NULL, 0, 0, 0, barValue, napi_default, 0 }
}
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,
} 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_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 (или если чтение свойства выполняется с помощью вызова N-API).
setter: Функция, вызываемая при записи в свойство. Если это значение передано, установите value и method в NULL (так как эти члены не будут использоваться). Эта функция неявно вызывается исполнителем при записи в свойство из кода JavaScript (или если запись в свойство выполняется с помощью вызова N-API).
method: Установите это значение, чтобы свойство описателя свойства value было функцией JavaScript, представленной method. Если это значение передано, установите value, getter и setter в NULL (так как эти члены не будут использоваться).
data: Данные обратного вызова, передаваемые в method, getter и setter при вызове этой функции.
attributes: Атрибуты, связанные с данным свойством. См. napi_property_attributes.

Функции

napi_get_property_names

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект, из которого нужно получить свойства.
[out] result: napi_value , представляющий массив значений JavaScript, представляющих имена свойств объекта. API можно использовать для итерирования по result с помощью napi_get_array_length и napi_get_element.

Возвращает napi_ok в случае успешного выполнения API.

Этот API возвращает массив свойств для переданного объекта.

napi_set_property

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект, на котором нужно установить свойство.
[in] key: Имя свойства, которое нужно установить.
[in] value: Значение свойства.

Возвращает napi_ok в случае успешного выполнения API.

Этот API устанавливает свойство на переданный объект.

napi_get_property

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект, из которого нужно получить свойство.
[in] key: Имя свойства, которое нужно получить.
[out] result: Значение свойства.

Возвращает napi_ok в случае успешного выполнения API.

Этот API получает запрошенное свойство из переданного объекта.

napi_has_property

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект для запроса.
[in] key: Имя свойства, существование которого нужно проверить.
[out] result: Существует ли свойство в объекте или нет.

Возвращает napi_ok в случае успешного выполнения API.

Этот API проверяет, содержит ли переданный объект свойство с указанным именем.

napi_delete_property

Добавлен в: v6.14.2

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект для запроса.
[in] key: Имя свойства, которое нужно удалить.
[out] result: Успешно ли удаление свойства. result можно необязательно игнорировать, передав NULL.

Возвращает napi_ok в случае успешного выполнения API.

Этот API пытается удалить собственную (own) собственность key из object.

napi_has_own_property

Добавлен в: v6.14.2

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект для запроса.
[in] key: Название собственной (own) свойства, существование которого нужно проверить.
[out] result: Существует ли данная собственная (own) собственность в объекте или нет.

Возвращает napi_ok если API выполнился успешно.

Этот API проверяет, содержит ли переданный объект указанное собственное (own) свойство. key должно быть строкой или символом, в противном случае будет выброшено исключение. N-API не будет выполнять никаких преобразований типов данных.

napi_set_named_property

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект, на котором нужно установить свойство.
[in] utf8Name: Название свойства, которое нужно установить.
[in] value: Значение свойства.

Возвращает napi_ok если API выполнился успешно.

Этот метод эквивалентен вызову napi_set_property со строкой, преобразованной в napi_value из utf8Name.

napi_get_named_property

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект, из которого нужно получить свойство.
[in] utf8Name: Название свойства, которое нужно получить.
[out] result: Значение свойства.

Возвращает napi_ok если API выполнился успешно.

Этот метод эквивалентен вызову napi_get_property со строкой, преобразованной в napi_value из utf8Name.

napi_has_named_property

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект для запроса.
[in] utf8Name: Название свойства, существование которого нужно проверить.
[out] result: Существует ли свойство в объекте или нет.

Возвращает napi_ok если API выполнился успешно.

Этот метод эквивалентен вызову napi_has_property со строкой, преобразованной в napi_value из utf8Name.

napi_set_element

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект, для установки свойств.
[in] index: Индекс свойства, которое нужно установить.
[in] value: Значение свойства.

Возвращает napi_ok если API выполнился успешно.

Этот API устанавливает элемент в переданный объект.

napi_get_element

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект, из которого нужно получить свойство.
[in] index: Индекс свойства, которое нужно получить.
[out] result: Значение свойства.

Возвращает napi_ok если API выполнился успешно.

Этот API получает элемент по запрошенному индексу.

napi_has_element

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект для запроса.
[in] index: Индекс свойства, существование которого нужно проверить.
[out] result: Существует ли свойство в объекте или нет.

Возвращает napi_ok если API выполнился успешно.

Этот API возвращает, содержит ли переданный объект элемент по запрошенному индексу.

napi_delete_element

Добавлен в: v6.14.2

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект для запроса.
[in] index: Индекс свойства, которое нужно удалить.
[out] result: Удалось ли удалить элемент или нет. result можно выборочно пропустить, передав NULL.

Возвращает napi_ok если API выполнился успешно.

Этот API пытается удалить указанный index из object.

napi_define_properties

Добавлен в: v8.0.0

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

[in] env: Окружение, в котором вызывается вызов N-API.
[in] object: Объект, из которого нужно получить свойства.
[in] property_count: Количество элементов в массиве properties.
[in] properties: Массив описателей свойств.

Возвращает napi_ok если API выполнился успешно.

Этот метод позволяет эффективно определить несколько свойств в заданном объекте. Свойства определяются с помощью описателей свойств (см. napi_property_descriptor). Используя массив таких описателей свойств, этот API устанавливает свойства в объекте по одному, как определено в DefineOwnProperty (описано в Разделе 9.1.6 спецификации ECMA262).

Работа с функциями JavaScript

N-API предоставляет набор API, которые позволяют коду JavaScript вызывать обратные вызовы в код нативном коде. API N-API, которые поддерживают обратные вызовы в нативный код, принимают функции обратного вызова, представленные типом napi_callback. Когда JavaScript VM вызывает обратный вызов в код нативном коде, вызывается функция napi_callback.

Документированные в этом разделе API позволяют функции обратного вызова выполнять следующие действия:

Получить информацию о контексте, в котором был вызван обратный вызов.
Получить аргументы, переданные в обратный вызов.
Возвратить napi_value из обратного вызова.

Кроме того, N-API предоставляет набор функций, которые позволяют вызывать функции JavaScript из нативного кода. Можно либо вызвать функцию как обычный вызов JavaScript-функции, либо как конструктор функции.

napi_call_function

Добавлен в: v8.0.0

napi_status napi_call_function(napi_env env,
                               napi_value recv,
                               napi_value func,
                               int argc,
                               const napi_value* argv,
                               napi_value* result)

[in] env: Окружение, в котором вызывается API.
[in] recv: Объект this переданный вызываемой функции.
[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

Добавлен в: v8.0.0

napi_status napi_create_function(napi_env env,
                                 const char* utf8name,
                                 napi_callback cb,
                                 void* data,
                                 napi_value* result);

[in] env: Окружение, в котором вызывается API.
[in] utf8Name: Имя функции, закодированное в UTF8. Это отображается в JavaScript как свойство name нового объекта функции.
[in] cb: Нативная функция, которая должна вызываться при вызове этого объекта функции.
[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(addon, Init)

Учитывая вышеприведенный код, дополнение можно использовать из JavaScript следующим образом:

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

Примечание: Строка, переданная require, не обязательно совпадает с именем, переданным в NAPI_MODULE в предыдущем фрагменте, но является именем целевого объекта в binding.gyp отвечающего за создание файла .node.

napi_get_cb_info

Добавлен в: v8.0.0

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: Получает аргумент JavaScript this для вызова.
[out] data: Получает указатель на данные для коллбека.

Возвращает napi_ok в случае успешного выполнения API.

Этот метод используется внутри функции обратного вызова для получения подробностей о вызове, таких как аргументы и указатель this из заданной информации о коллбеке.

napi_get_new_target

Добавлена в: v6.14.2

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

[in] env: Окружение, в котором вызывается API.
[in] cbinfo: Информация о коллбеке, переданная в функцию коллбека.
[out] result: new.target вызова конструктора.

Возвращает napi_ok в случае успешного выполнения API.

Этот API возвращает new.target вызова конструктора. Если текущий коллбек не является вызовом конструктора, результат — NULL.

napi_new_instance

Добавлена в: v8.0.0

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

Следующее можно приблизительно воспроизвести в N-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.

Оборачивание объекта

N-API предлагает способ «оборачивания» C++-классов и экземпляров, чтобы конструктор класса и методы можно было вызывать из JavaScript.

API napi_define_class определяет JavaScript-класс с конструктором, статическими свойствами и методами, а также свойствами и методами экземпляров, соответствующими C++-классу.
Когда JavaScript-код вызывает конструктор, функция обратного вызова конструктора использует napi_wrap для оборачивания нового экземпляра C++ в JavaScript-объект, а затем возвращает обернутый объект.
Когда JavaScript-код вызывает метод или свойство-аксессор класса, вызывается соответствующая функция C++ napi_callback. Для обратного вызова экземпляра 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_define_class

Добавлена в: v8.0.0

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++-класса, хотя для ясности это рекомендуется.
[in] length: Длина utf8name в байтах или NAPI_AUTO_LENGTH, если она завершается нулём.
[in] constructor: Функция обратного вызова, обрабатывающая создание экземпляров класса. (Это должна быть статический метод класса, а не собственно функция C++-конструктора.)
[in] data: Дополнительные данные, передаваемые функции обратного вызова конструктора как свойство data информации о коллбеке.
[in] property_count: Количество элементов в массиве аргументов properties.
[in] properties: Массив описателей свойств, описывающих статические и экземплярные свойства данных, аксессоры и методы класса. См. napi_property_descriptor.
[out] result: napi_value , представляющий функцию-конструктор класса.

Возвращает napi_ok в случае успешного выполнения API.

Определяет JavaScript-класс, соответствующий C++-классу, включая:

JavaScript-функцию-конструктор с именем класса, которая вызывает предоставленную функцию обратного вызова C++ конструктора.
Свойства функции-конструктора, соответствующие статическим свойствам данных, аксессорам и методам C++-класса (определяются описателями свойств с атрибутом napi_static).
Свойства объекта прототипа функции-конструктора, соответствующие нестатическим свойствам данных, аксессорам и методам C++-класса (определяются описателями свойств без атрибута napi_static).

Функция обратного вызова C++-конструктора должна быть статическим методом класса, который вызывает фактический конструктор класса, затем оборачивает новый экземпляр C++ в JavaScript-объект и возвращает обернутый объект. См. napi_wrap() для получения подробностей.

JavaScript-функция-конструктор, возвращаемая из napi_define_class, часто сохраняется и используется позже для создания новых экземпляров класса из кода нативных языков и/или проверки, являются ли предоставленные значения экземплярами класса. В этом случае, чтобы предотвратить сборку мусора функции, создайте постоянную ссылку на нее с помощью napi_create_reference и убедитесь, что счётчик ссылок остается >= 1.

napi_wrap

Добавлена в: v8.0.0

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-объект, который будет обернутым для нативного объекта. Этот объект должен быть создан из prototype конструктора, который был создан с помощью napi_define_class().
[in] native_object: Нативный экземпляр, который будет обернут в JavaScript-объект.
[in] finalize_cb: Необязательный нативный коллбек, который может быть использован для освобождения нативного экземпляра, когда JavaScript-объект готов к сбору мусора.
[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 для правильной обработки ссылки.

Примечание: Этот API может изменять цепочку прототипов обернутого объекта. Последующие манипуляции цепочкой прототипов обернутого объекта могут привести к тому, что napi_unwrap() завершится неудачей.

Повторный вызов napi_wrap() для объекта вернёт ошибку. Чтобы связать с объектом другой нативный экземпляр, сначала используйте napi_remove_wrap().

napi_unwrap

Добавлена в: v8.0.0

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

Добавлена в: v6.14.2

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() и удаляет обёртку, тем самым восстанавливая цепочку прототипов JavaScript-объекта. Если с обёрткой был связан обратный вызов finalize, он больше не будет вызываться при сборе мусора JavaScript-объекта.

Простые асинхронные операции

Модули плагинов часто нуждаются в использовании асинхронных помощников из libuv в своей реализации. Это позволяет им планировать выполнение задач асинхронно, чтобы их методы могли возвращаться до завершения задач. Это важно, чтобы избежать блокировки выполнения приложения Node.js в целом.

N-API предоставляет ABI-стабильный интерфейс для этих вспомогательных функций, охватывающий наиболее распространённые случаи использования асинхронных операций.

N-API определяет структуру napi_work, которая используется для управления асинхронными рабочими потоками. Экземпляры создаются/удаляются с помощью napi_create_async_work и napi_delete_async_work.

Обратные вызовы execute и complete — это функции, которые будут вызваны, когда исполняющий механизм готов к выполнению и при завершении задачи соответственно. Эти функции реализуют следующие интерфейсы:

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

Added in: v8.0.0

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: Необязательный объект, связанный с асинхронной задачей, который будет передан в возможные асинхронные init хуки.
[in] async_resource_name: Идентификатор типа ресурса, предоставляемого для диагностических целей, представленных API async_hooks.
[in] execute: Нативная функция, которая должна вызываться для асинхронного выполнения логики. Данная функция вызывается из потока пула рабочих потоков и может выполняться параллельно с основным потоком событий.
[in] complete: Нативная функция, которая будет вызываться при завершении или отмене асинхронной логики. Данная функция вызывается из основного потока событий.
[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

Added in: v8.0.0

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

Added in: v8.0.0

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 запрашивает планирование ранее выделенной задачи для выполнения.

napi_cancel_async_work

Added in: v8.0.0

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

Added in: v6.14.2

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 хуки.
[in] async_resource_name: Идентификатор типа ресурса, предоставляемого для диагностических целей, представленных API async_hooks.
[out] result: Инициализированный контекст асинхронной операции.

Возвращает napi_ok в случае успешного выполнения API.

napi_async_destroy

Added in: v6.14.2

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

Added in: v8.0.0

napi_status napi_make_callback(napi_env env,
                               napi_async_context async_context,
                               napi_value recv,
                               napi_value func,
                               int argc,
                               const napi_value* argv,
                               napi_value* result)

[in] env: Среда, в которой вызывается API.
[in] async_context: Контекст асинхронной операции, вызывающей обратный вызов. Обычно это значение, полученное ранее из napi_async_init. Однако также разрешено значение NULL, что указывает на использование текущего контекста асинхронной операции (если он есть) для обратного вызова.
[in] recv: Объект this, переданный вызываемой функции.
[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.

napi_open_callback_scope

Added in: v6.14.2

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: Необязательный объект, связанный с асинхронной задачей, который будет передан в возможные асинхронные init хуки.
[in] context: Контекст асинхронной операции, вызывающей обратный вызов. Это должно быть значение, полученное ранее из napi_async_init.
[out] result: Созданный контекст.

В некоторых случаях (например, при разрешении обещаний) необходимо иметь эквивалент контекста, связанного с обратным вызовом, когда выполняются определенные вызовы N-API. Если на стеке нет другого скрипта, функции napi_open_callback_scope и napi_close_callback_scope могут быть использованы для открытия/закрытия необходимого контекста.

napi_close_callback_scope

Added in: v6.14.2

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

Added in: v6.14.2

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.

Возвращает napi_ok в случае успешного выполнения API.

Эта функция заполняет структуру version значениями основной, дополнительной и исправленной версий текущей версии Node, а также поле release значением process.release.name.

Возвращаемый буфер статически выделен и не требует освобождения.

napi_get_version

Добавлена в: v6.14.2

napi_status napi_get_version(napi_env env,
                             uint32_t* result);

[in] env: Окружение, в котором вызывается API.
[out] result: Наивысшая поддерживаемая версия N-API.

Возвращает napi_ok в случае успешного выполнения API.

Этот API возвращает наивысшую версию N-API, поддерживаемую исполняемой средой Node.js. N-API, как ожидается, будет развиваться, поэтому более новые версии Node.js могут поддерживать дополнительные функции API. Для возможности использования новой функции дополнением при работе с версиями Node.js, которые её поддерживают, с обеспечением запасного поведения при работе с версиями Node.js, которые её не поддерживают:

Вызовите napi_get_version() для определения доступности API.
Если API доступен, динамически загрузите указатель на функцию, используя uv_dlsym().
Используйте динамически загруженный указатель для вызова функции.
Если функция недоступна, обеспечьте альтернативную реализацию, не использующую данную функцию.

Управление памятью

napi_adjust_external_memory

Добавлена в: v6.14.2

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, указывающий на собственную память, выделенную родным модулем). Регистрация внешней выделенной памяти вызовет глобальные сборки мусора чаще, чем в противном случае.

Обещания

N-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

Добавлена в: v6.14.2

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

Добавлена в: v6.14.2

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

Добавлена в: v6.14.2

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

Добавлена в: v6.14.2

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

[in] env: Окружение, в котором вызывается API.
[in] promise: Обещание для проверки
[out] is_promise: Флаг, указывающий, является ли promise родным объектом обещания — то есть, объектом обещания, созданным базовым движком.

Исполнение скрипта

N-API предоставляет API для выполнения строки JavaScript с помощью базового движка JavaScript.

napi_run_script

Добавлена в: v6.14.2

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

[in] env: Окружение, в котором вызывается API.
[in] script: Строка JavaScript, содержащая скрипт для выполнения.
[out] result: Значение, полученное в результате выполнения скрипта.

Цикл событий libuv

N-API предоставляет функцию для получения текущего цикла событий, связанного с определённым napi_env.

napi_get_uv_event_loop

Добавлена в: v6.14.2

NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env,
                                               uv_loop_t** loop);

[in] env: Окружение, в котором вызывается API.
[out] loop: Текущая инстанция цикла libuv.

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v6.x/docs/api/n-api.html