Skip to content

Node-API

[Stable: 2 - Stable]

Stable: 2 Stability: 2 - Stable

Node-API(이전 N-API)는 네이티브 애드온을 구축하기 위한 API입니다. 기본 JavaScript 런타임(예: V8)과 독립적이며 Node.js 자체의 일부로 유지 관리됩니다. 이 API는 Node.js 버전 간에 Application Binary Interface(ABI) 안정성을 유지합니다. 기본 JavaScript 엔진의 변경으로부터 애드온을 보호하고 하나의 주요 버전에 대해 컴파일된 모듈을 재컴파일하지 않고도 나중 주요 버전의 Node.js에서 실행할 수 있도록 하기 위한 것입니다. ABI 안정성 가이드는 더 자세한 설명을 제공합니다.

애드온은 C++ 애드온 섹션에 설명된 것과 같은 방식/도구로 빌드/패키징됩니다. 유일한 차이점은 네이티브 코드에서 사용하는 API 집합입니다. V8 또는 Node.js용 네이티브 추상화 API를 사용하는 대신 Node-API에서 사용 가능한 함수를 사용합니다.

Node-API에서 노출하는 API는 일반적으로 JavaScript 값을 생성하고 조작하는 데 사용됩니다. 개념 및 작업은 일반적으로 ECMA-262 언어 사양에 지정된 아이디어에 매핑됩니다. API는 다음과 같은 속성을 가지고 있습니다.

  • 모든 Node-API 호출은 napi_status 유형의 상태 코드를 반환합니다. 이 상태는 API 호출이 성공했는지 또는 실패했는지 나타냅니다.
  • API의 반환 값은 출력 매개 변수를 통해 전달됩니다.
  • 모든 JavaScript 값은 napi_value라는 불투명 유형 뒤에 추상화됩니다.
  • 오류 상태 코드의 경우 napi_get_last_error_info를 사용하여 추가 정보를 얻을 수 있습니다. 자세한 내용은 오류 처리 섹션 오류 처리에서 확인할 수 있습니다.

Node-API는 Node.js 버전과 다양한 컴파일러 수준에서 ABI 안정성을 보장하는 C API입니다. C++ API는 사용하기가 더 쉬울 수 있습니다. C++ 사용을 지원하기 위해 프로젝트는 node-addon-api라는 C++ 래퍼 모듈을 유지 관리합니다. 이 래퍼는 인라인 가능한 C++ API를 제공합니다. node-addon-api로 빌드된 바이너리는 Node.js에서 내보낸 Node-API C 기반 함수에 대한 심볼에 종속됩니다. node-addon-api는 Node-API를 호출하는 코드를 작성하는 더 효율적인 방법입니다. 예를 들어 다음 node-addon-api 코드를 살펴보겠습니다. 첫 번째 섹션은 node-addon-api 코드를 보여주고 두 번째 섹션은 애드온에서 실제로 사용되는 것을 보여줍니다.

C++
Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");
C++
napi_status status;
napi_value object, string;
status = napi_create_object(env, &object);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

status = napi_set_named_property(env, object, "foo", string);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

최종 결과는 애드온이 내보낸 C API만 사용한다는 것입니다. 결과적으로 C API가 제공하는 ABI 안정성의 이점을 여전히 얻을 수 있습니다.

C API 대신 node-addon-api를 사용하는 경우 node-addon-api에 대한 API docs부터 시작하십시오.

Node-API 리소스는 Node-API 및 node-addon-api를 처음 접하는 개발자에게 훌륭한 방향과 팁을 제공합니다. 추가 미디어 리소스는 Node-API 미디어 페이지에서 찾을 수 있습니다.

ABI 안정성의 의미

Node-API는 ABI 안정성을 보장하지만, Node.js의 다른 부분과 애드온에서 사용되는 외부 라이브러리는 그렇지 않습니다. 특히, 다음 API 중 어느 것도 주요 버전 간에 ABI 안정성을 보장하지 않습니다.

  • 다음을 통해 사용 가능한 Node.js C++ API
  • Node.js에도 포함되어 있으며 다음을 통해 사용 가능한 libuv API
  • 다음을 통해 사용 가능한 V8 API

따라서 애드온이 Node.js 주요 버전에서 ABI 호환성을 유지하려면,

C
#include <node_api.h>

를 사용하여 Node-API만을 독점적으로 사용하고, 사용하는 모든 외부 라이브러리에 대해 해당 외부 라이브러리가 Node-API와 유사한 ABI 안정성을 보장하는지 확인해야 합니다.

빌드

JavaScript로 작성된 모듈과 달리 Node-API를 사용하여 Node.js 네이티브 애드온을 개발하고 배포하려면 추가 도구 세트가 필요합니다. Node.js 개발에 필요한 기본 도구 외에도 네이티브 애드온 개발자는 C 및 C++ 코드를 바이너리로 컴파일할 수 있는 툴체인이 필요합니다. 또한, 네이티브 애드온의 배포 방법에 따라 네이티브 애드온의 사용자도 C/C++ 툴체인을 설치해야 합니다.

Linux 개발자의 경우 필요한 C/C++ 툴체인 패키지를 쉽게 사용할 수 있습니다. GCC는 다양한 플랫폼에서 Node.js를 빌드하고 테스트하는 데 Node.js 커뮤니티에서 널리 사용됩니다. 많은 개발자에게 LLVM 컴파일러 인프라도 좋은 선택입니다.

Mac 개발자의 경우 Xcode는 필요한 모든 컴파일러 도구를 제공합니다. 하지만 전체 Xcode IDE를 설치할 필요는 없습니다. 다음 명령어는 필요한 툴체인을 설치합니다.

bash
xcode-select --install

Windows 개발자의 경우 Visual Studio는 필요한 모든 컴파일러 도구를 제공합니다. 하지만 전체 Visual Studio IDE를 설치할 필요는 없습니다. 다음 명령어는 필요한 툴체인을 설치합니다.

bash
npm install --global windows-build-tools

다음 섹션에서는 Node.js 네이티브 애드온 개발 및 배포에 사용할 수 있는 추가 도구에 대해 설명합니다.

빌드 도구

여기에 나열된 두 도구 모두 네이티브 애드온을 성공적으로 설치하려면 네이티브 애드온의 사용자가 C/C++ 툴체인을 설치해야 합니다.

node-gyp

node-gyp는 Google의 GYP 도구의 gyp-next 포크를 기반으로 하는 빌드 시스템이며 npm에 번들로 포함되어 있습니다. GYP, 따라서 node-gyp는 Python이 설치되어 있어야 합니다.

역사적으로 node-gyp는 네이티브 애드온을 빌드하기 위한 선택 도구였습니다. 널리 채택되고 문서화되어 있습니다. 그러나 일부 개발자는 node-gyp의 한계에 직면했습니다.

CMake.js

CMake.jsCMake를 기반으로 하는 대체 빌드 시스템입니다.

CMake.js는 이미 CMake를 사용하는 프로젝트 또는 node-gyp의 한계에 영향을 받는 개발자에게 좋은 선택입니다. build_with_cmake는 CMake 기반 네이티브 애드온 프로젝트의 예입니다.

사전 컴파일된 바이너리 업로드

여기에 나열된 세 가지 도구를 통해 네이티브 애드온 개발자와 관리자는 바이너리를 공용 또는 비공개 서버에 생성하고 업로드할 수 있습니다. 이러한 도구는 일반적으로 Travis CIAppVeyor와 같은 CI/CD 빌드 시스템과 통합되어 다양한 플랫폼과 아키텍처에 대한 바이너리를 빌드하고 업로드합니다. 그러면 C/C++ 툴체인을 설치할 필요가 없는 사용자가 이러한 바이너리를 다운로드할 수 있습니다.

node-pre-gyp

node-pre-gyp는 개발자가 선택한 서버에 바이너리를 업로드하는 기능을 추가하는 node-gyp 기반 도구입니다. node-pre-gyp는 Amazon S3에 바이너리를 업로드하는 기능을 특히 잘 지원합니다.

prebuild

prebuild는 node-gyp 또는 CMake.js를 사용한 빌드를 지원하는 도구입니다. 다양한 서버를 지원하는 node-pre-gyp와 달리 prebuild는 GitHub 릴리스에만 바이너리를 업로드합니다. prebuild는 CMake.js를 사용하는 GitHub 프로젝트에 좋은 선택입니다.

prebuildify

prebuildify는 node-gyp 기반의 도구입니다. prebuildify의 장점은 빌드된 바이너리가 npm에 업로드될 때 네이티브 애드온과 함께 번들로 제공된다는 것입니다. 바이너리는 npm에서 다운로드되며, 네이티브 애드온이 설치될 때 모듈 사용자에게 즉시 사용 가능합니다.

사용법

Node-API 함수를 사용하려면 node 개발 트리의 src 디렉토리에 있는 node_api.h 파일을 포함합니다.

C
#include <node_api.h>

이렇게 하면 지정된 Node.js 릴리스에 대한 기본 NAPI_VERSION을 사용하게 됩니다. 특정 버전의 Node-API와의 호환성을 보장하려면 헤더를 포함할 때 버전을 명시적으로 지정할 수 있습니다.

C
#define NAPI_VERSION 3
#include <node_api.h>

이렇게 하면 Node-API 표면이 지정된(이전) 버전에서 사용 가능한 기능으로만 제한됩니다.

Node-API 표면의 일부는 실험적이며 명시적인 옵트인이 필요합니다.

C
#define NAPI_EXPERIMENTAL
#include <node_api.h>

이 경우 실험적 API를 포함한 전체 API 표면을 모듈 코드에서 사용할 수 있습니다.

때때로 이미 출시된 안정적인 API에 영향을 미치는 실험적 기능이 도입됩니다. 이러한 기능은 옵트아웃으로 비활성화할 수 있습니다.

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

여기서 <FEATURE_NAME>은 실험적 및 안정적인 API 모두에 영향을 미치는 실험적 기능의 이름입니다.

Node-API 버전 매트릭스

9 버전까지 Node-API 버전은 Node.js와 독립적으로 추가되고 버전이 지정되었습니다. 즉, 모든 버전은 이전 버전의 모든 API에 몇 가지 추가 기능이 있는 이전 버전에 대한 확장이었습니다. 각 Node.js 버전은 단일 Node-API 버전만 지원했습니다. 예를 들어 v18.15.0은 Node-API 버전 8만 지원합니다. 8은 이전 모든 버전의 엄격한 상위 집합이었기 때문에 ABI 안정성이 달성되었습니다.

9 버전부터 Node-API 버전은 독립적으로 버전이 지정되지만 Node-API 버전 9에서 실행된 애드온은 Node-API 버전 10에서 실행하려면 코드 업데이트가 필요할 수 있습니다. 그러나 Node.js 버전이 8보다 높은 Node-API 버전을 지원하는 경우 8과 지원하는 최고 버전 사이의 모든 버전을 지원하고 애드온이 더 높은 Node-API 버전을 선택하지 않는 한 버전 8 API를 제공하도록 기본 설정되므로 ABI 안정성이 유지됩니다. 이 방법은 기존 Node-API 함수를 더 잘 최적화하면서 ABI 안정성을 유지할 수 있는 유연성을 제공합니다. 기존 애드온은 이전 버전의 Node-API를 사용하여 재컴파일하지 않고도 계속 실행할 수 있습니다. 애드온에 최신 Node-API 버전의 기능이 필요한 경우 기존 코드를 변경하고 재컴파일하여 해당 새 기능을 사용해야 합니다.

Node-API 버전 9 이상을 지원하는 Node.js 버전에서 NAPI_VERSION=X를 정의하고 기존 애드온 초기화 매크로를 사용하면 요청된 Node-API 버전이 런타임에 애드온에 통합됩니다. NAPI_VERSION이 설정되지 않으면 8로 기본 설정됩니다.

이 표는 이전 스트림에서는 최신 정보가 아닐 수 있습니다. 최신 정보는 최신 API 설명서에 있습니다: Node-API 버전 매트릭스

Node-API 버전지원 버전
9v18.17.0+, 20.3.0+, 21.0.0 및 모든 이후 버전
8v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 및 모든 이후 버전
7v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 및 모든 이후 버전
6v10.20.0+, v12.17.0+, 14.0.0 및 모든 이후 버전
5v10.17.0+, v12.11.0+, 13.0.0 및 모든 이후 버전
4v10.16.0+, v11.8.0+, 12.0.0 및 모든 이후 버전
3v6.14.2*, 8.11.2+, v9.11.0+*, 10.0.0 및 모든 이후 버전
2v8.10.0+, v9.3.0+, 10.0.0 및 모든 이후 버전
1v8.6.0+*, v9.0.0+, 10.0.0 및 모든 이후 버전
  • Node-API는 실험적이었습니다.

** Node.js 8.0.0은 Node-API를 실험적 기능으로 포함했습니다. Node-API 버전 1로 출시되었지만 Node.js 8.6.0까지 계속 발전했습니다. Node.js 8.6.0 이전 버전의 API는 다릅니다. Node-API 버전 3 이상을 권장합니다.

Node-API에 대해 설명된 각 API에는 추가됨:, 안정적인 API에는 추가 헤더 Node-API 버전:이 있습니다. Node-API 버전:에 표시된 Node.js 버전 이상을 사용하는 경우 API를 직접 사용할 수 있습니다. Node-API 버전:에 나열된 버전을 지원하지 않는 Node.js 버전을 사용하거나 Node-API 버전:이 나열되지 않은 경우 #define NAPI_EXPERIMENTALnode_api.h 또는 js_native_api.h 포함 전에 오는 경우에만 API를 사용할 수 있습니다. 추가됨:에 표시된 버전보다 나중 버전의 Node.js에서 API를 사용할 수 없는 것으로 나타나는 경우 이것이 그 이유일 가능성이 큽니다.

네이티브 코드에서 ECMAScript 기능에 액세스하는 것과 엄격하게 관련된 Node-API는 js_native_api.hjs_native_api_types.h에서 별도로 찾을 수 있습니다. 이러한 헤더에 정의된 API는 node_api.hnode_api_types.h에 포함됩니다. 이러한 방식으로 헤더가 구성되는 것은 Node.js 외부에서 Node-API를 구현할 수 있도록 하기 위한 것입니다. 이러한 구현의 경우 Node.js 특정 API가 적용되지 않을 수 있습니다.

애드온의 Node.js 특정 부분은 실제 기능을 JavaScript 환경에 노출하는 코드와 분리할 수 있으므로 후자를 여러 Node-API 구현과 함께 사용할 수 있습니다. 아래 예에서 addon.caddon.hjs_native_api.h만 참조합니다. 이렇게 하면 addon.c를 재사용하여 Node.js 구현의 Node-API 또는 Node.js 외부의 Node-API 구현을 컴파일할 수 있습니다.

addon_node.c는 애드온에 대한 Node.js 특정 진입점을 포함하고 애드온이 Node.js 환경에 로드될 때 addon.c를 호출하여 애드온을 인스턴스화하는 별도의 파일입니다.

C
// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif  // _ADDON_H_
C
// addon.c
#include "addon.h"

#define NODE_API_CALL(env, call)                                  \
  do {                                                            \
    napi_status status = (call);                                  \
    if (status != napi_ok) {                                      \
      const napi_extended_error_info* error_info = NULL;          \
      napi_get_last_error_info((env), &error_info);               \
      const char* err_message = error_info->error_message;        \
      bool is_pending;                                            \
      napi_is_exception_pending((env), &is_pending);              \
      /* If an exception is already pending, don't rethrow it */  \
      if (!is_pending) {                                          \
        const char* message = (err_message == NULL)               \
            ? "empty error message"                               \
            : err_message;                                        \
        napi_throw_error((env), NULL, message);                   \
      }                                                           \
      return NULL;                                                \
    }                                                             \
  } while(0)

static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
  // Do something useful.
  return NULL;
}

napi_value create_addon(napi_env env) {
  napi_value result;
  NODE_API_CALL(env, napi_create_object(env, &result));

  napi_value exported_function;
  NODE_API_CALL(env, napi_create_function(env,
                                          "doSomethingUseful",
                                          NAPI_AUTO_LENGTH,
                                          DoSomethingUseful,
                                          NULL,
                                          &exported_function));

  NODE_API_CALL(env, napi_set_named_property(env,
                                             result,
                                             "doSomethingUseful",
                                             exported_function));

  return result;
}
C
// addon_node.c
#include <node_api.h>
#include "addon.h"

NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
  // This function body is expected to return a `napi_value`.
  // The variables `napi_env env` and `napi_value exports` may be used within
  // the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
  return create_addon(env);
}

환경 수명 주기 API

8.7절ECMAScript 언어 명세는 JavaScript 코드가 실행되는 자체 포함 환경인 "Agent" 개념을 정의합니다. 프로세스에 의해 여러 개의 이러한 Agent가 동시에 또는 순차적으로 시작되고 종료될 수 있습니다.

Node.js 환경은 ECMAScript Agent에 해당합니다. 메인 프로세스에서 환경은 시작 시 생성되며, 별도의 스레드에서 추가 환경을 생성하여 워커 스레드로 사용할 수 있습니다. Node.js가 다른 애플리케이션에 포함된 경우 애플리케이션의 메인 스레드는 애플리케이션 프로세스의 수명 주기 동안 여러 번 Node.js 환경을 생성하고 파괴할 수도 있습니다. 애플리케이션에 의해 생성된 각 Node.js 환경은 수명 주기 동안 워커 스레드로 추가 환경을 생성하고 파괴할 수 있습니다.

네이티브 애드온의 관점에서 보면, 이는 제공하는 바인딩이 여러 번, 여러 컨텍스트에서, 심지어 여러 스레드에서 동시에 호출될 수 있음을 의미합니다.

네이티브 애드온은 Node.js 환경의 수명 주기 동안 사용하는 전역 상태를 할당해야 할 수 있습니다. 이를 통해 상태를 애드온의 각 인스턴스에 고유하게 만들 수 있습니다.

이를 위해 Node-API는 데이터를 연결하여 해당 수명 주기가 Node.js 환경의 수명 주기에 연결되도록 하는 방법을 제공합니다.

napi_set_instance_data

추가됨: v12.8.0, v10.20.0

N-API 버전: 6

C
napi_status napi_set_instance_data(node_api_basic_env env,
                                   void* data,
                                   napi_finalize finalize_cb,
                                   void* finalize_hint);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] data: 이 인스턴스의 바인딩에서 사용할 수 있도록 할 데이터 항목입니다.
  • [in] finalize_cb: 환경이 해체될 때 호출할 함수입니다. 함수는 data를 수신하여 해제할 수 있습니다. napi_finalize에서 자세한 내용을 제공합니다.
  • [in] finalize_hint: 수집 중에 finalize 콜백에 전달할 선택적 힌트입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 data를 현재 실행 중인 Node.js 환경과 연결합니다. data는 나중에 napi_get_instance_data()를 사용하여 검색할 수 있습니다. 이전에 napi_set_instance_data() 호출을 통해 설정된 현재 실행 중인 Node.js 환경과 연결된 기존 데이터는 덮어쓰여집니다. 이전 호출에서 finalize_cb가 제공된 경우 호출되지 않습니다.

napi_get_instance_data

추가됨: v12.8.0, v10.20.0

N-API 버전: 6

C
napi_status napi_get_instance_data(node_api_basic_env env,
                                   void** data);
  • [in] env: Node-API 호출이 수행되는 환경입니다.
  • [out] data: napi_set_instance_data() 호출을 통해 현재 실행 중인 Node.js 환경에 이전에 연결된 데이터 항목입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 napi_set_instance_data()를 통해 이전에 현재 실행 중인 Node.js 환경에 연결된 데이터를 검색합니다. 데이터가 설정되지 않은 경우 호출은 성공하고 dataNULL로 설정됩니다.

기본 Node-API 데이터 형식

Node-API는 다양한 API에서 사용되는 추상화로 다음과 같은 기본 데이터 형식을 제공합니다. 이러한 API는 다른 Node-API 호출을 사용하여 내부적으로만 조사할 수 있는 불투명한 것으로 처리해야 합니다.

napi_status

추가됨: v8.0.0

N-API 버전: 1

Node-API 호출의 성공 또는 실패를 나타내는 정수 상태 코드입니다. 현재 다음 상태 코드가 지원됩니다.

C
typedef enum {
  napi_ok,
  napi_invalid_arg,
  napi_object_expected,
  napi_string_expected,
  napi_name_expected,
  napi_function_expected,
  napi_number_expected,
  napi_boolean_expected,
  napi_array_expected,
  napi_generic_failure,
  napi_pending_exception,
  napi_cancelled,
  napi_escape_called_twice,
  napi_handle_scope_mismatch,
  napi_callback_scope_mismatch,
  napi_queue_full,
  napi_closing,
  napi_bigint_expected,
  napi_date_expected,
  napi_arraybuffer_expected,
  napi_detachable_arraybuffer_expected,
  napi_would_deadlock,  /* 사용되지 않음 */
  napi_no_external_buffers_allowed,
  napi_cannot_run_js
} napi_status;

API가 실패한 상태를 반환할 때 추가 정보가 필요한 경우 napi_get_last_error_info를 호출하여 얻을 수 있습니다.

napi_extended_error_info

추가됨: v8.0.0

N-API 버전: 1

C
typedef struct {
  const char* error_message;
  void* engine_reserved;
  uint32_t engine_error_code;
  napi_status error_code;
} napi_extended_error_info;
  • error_message: 오류에 대한 VM 중립적 설명이 포함된 UTF8 인코딩 문자열입니다.
  • engine_reserved: VM별 오류 세부 정보를 위해 예약되어 있습니다. 현재 어떤 VM에도 구현되어 있지 않습니다.
  • engine_error_code: VM별 오류 코드입니다. 현재 어떤 VM에도 구현되어 있지 않습니다.
  • error_code: 마지막 오류에서 발생한 Node-API 상태 코드입니다.

추가 정보는 오류 처리 섹션을 참조하십시오.

napi_env

napi_env는 기본 Node-API 구현이 VM별 상태를 유지하는 데 사용할 수 있는 컨텍스트를 나타내는 데 사용됩니다. 이 구조체는 네이티브 함수가 호출될 때 전달되며, Node-API 호출을 수행할 때 다시 전달되어야 합니다. 구체적으로, 초기 네이티브 함수가 호출될 때 전달된 것과 동일한 napi_env를 후속 중첩 Node-API 호출에 전달해야 합니다. 일반적인 재사용을 위해 napi_env를 캐싱하고 서로 다른 Worker 스레드에서 실행되는 동일한 애드온의 인스턴스 간에 napi_env를 전달하는 것은 허용되지 않습니다. 네이티브 애드온의 인스턴스가 언로드되면 napi_env는 무효화됩니다. 이 이벤트에 대한 알림은 napi_add_env_cleanup_hooknapi_set_instance_data에 제공된 콜백을 통해 전달됩니다.

node_api_basic_env

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

napi_env의 이 변형은 동기식 finalizer(node_api_basic_finalize)에 전달됩니다. node_api_basic_env 형식의 매개변수를 첫 번째 인수로 받는 Node-API의 하위 집합이 있습니다. 이러한 API는 JavaScript 엔진의 상태에 액세스하지 않으므로 동기식 finalizer에서 호출해도 안전합니다. 이러한 API에 napi_env 형식의 매개변수를 전달하는 것은 허용되지만, JavaScript 엔진 상태에 액세스하는 API에 node_api_basic_env 형식의 매개변수를 전달하는 것은 허용되지 않습니다. 캐스팅 없이 이렇게 하려고 하면 애드온이 잘못된 포인터 유형이 함수에 전달될 때 경고 및/또는 오류를 내도록 하는 플래그로 컴파일될 때 컴파일러 경고 또는 오류가 발생합니다. 동기식 finalizer에서 이러한 API를 호출하면 최종적으로 애플리케이션이 종료됩니다.

napi_value

이는 JavaScript 값을 나타내는 데 사용되는 불투명 포인터입니다.

napi_threadsafe_function

추가됨: v10.6.0

N-API 버전: 4

napi_call_threadsafe_function()을 통해 여러 스레드에서 비동기적으로 호출할 수 있는 JavaScript 함수를 나타내는 불투명 포인터입니다.

napi_threadsafe_function_release_mode

추가됨: v10.6.0

N-API 버전: 4

스레드 안전 함수를 즉시 닫을지(napi_tsfn_abort) 아니면 단순히 해제할지(napi_tsfn_release) napi_release_threadsafe_function()에 제공할 값입니다. 해제된 함수는 napi_acquire_threadsafe_function()napi_call_threadsafe_function()을 통해 후속 사용이 가능합니다.

C
typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

napi_threadsafe_function_call_mode

추가됨: v10.6.0

N-API 버전: 4

스레드 안전 함수와 연결된 큐가 가득 찼을 때 호출이 차단되어야 하는지 여부를 나타내는 napi_call_threadsafe_function()에 제공할 값입니다.

C
typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

Node-API 메모리 관리 유형

napi_handle_scope

특정 범위 내에서 생성된 객체의 수명을 제어하고 수정하는 데 사용되는 추상화입니다. 일반적으로 Node-API 값은 핸들 범위의 컨텍스트 내에서 생성됩니다. 네이티브 메서드가 JavaScript에서 호출될 때 기본 핸들 범위가 존재합니다. 사용자가 명시적으로 새로운 핸들 범위를 생성하지 않으면 Node-API 값은 기본 핸들 범위에서 생성됩니다. 네이티브 메서드 실행 이외의 코드 호출(예: libuv 콜백 호출 중)에 대해 모듈은 JavaScript 값 생성으로 이어질 수 있는 함수를 호출하기 전에 범위를 생성해야 합니다.

핸들 범위는 napi_open_handle_scope를 사용하여 생성되고 napi_close_handle_scope를 사용하여 삭제됩니다. 범위를 닫으면 GC에 핸들 범위의 수명 동안 생성된 모든 napi_value가 현재 스택 프레임에서 더 이상 참조되지 않음을 나타낼 수 있습니다.

자세한 내용은 객체 수명 관리를 참조하십시오.

napi_escapable_handle_scope

추가됨: v8.0.0

N-API 버전: 1

Escapable handle scope는 특정 handle scope 내에서 생성된 값을 상위 scope로 반환하기 위한 특수한 유형의 handle scope입니다.

napi_ref

추가됨: v8.0.0

N-API 버전: 1

napi_value를 참조하는 데 사용되는 추상화입니다. 이를 통해 사용자는 JavaScript 값의 수명을 관리하고, 최소 수명을 명시적으로 정의할 수 있습니다.

자세한 내용은 객체 수명 관리를 참조하십시오.

napi_type_tag

추가됨: v14.8.0, v12.19.0

N-API 버전: 8

두 개의 부호 없는 64비트 정수로 저장되는 128비트 값입니다. JavaScript 객체 또는 외부 객체에 "태그"를 지정하여 특정 유형임을 확인하는 UUID 역할을 합니다. 객체의 프로토타입이 조작된 경우 후자가 가양성을 보고할 수 있으므로 napi_instanceof보다 더 강력한 검사입니다. 유형 태깅은 napi_wrap과 함께 사용하는 것이 가장 유용합니다. 이는 래핑된 객체에서 검색된 포인터를 이전에 JavaScript 객체에 적용된 유형 태그에 해당하는 네이티브 유형으로 안전하게 캐스팅할 수 있도록 보장하기 때문입니다.

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

napi_async_cleanup_hook_handle

추가됨: v14.10.0, v12.19.0

napi_add_async_cleanup_hook에서 반환되는 불투명 값입니다. 비동기 정리 이벤트 체인이 완료되면 napi_remove_async_cleanup_hook에 전달해야 합니다.

Node-API 콜백 유형

napi_callback_info

추가됨: v8.0.0

N-API 버전: 1

콜백 함수에 전달되는 불투명 데이터 유형입니다. 콜백이 호출된 컨텍스트에 대한 추가 정보를 얻는 데 사용할 수 있습니다.

napi_callback

추가됨: v8.0.0

N-API 버전: 1

Node-API를 통해 JavaScript에 노출될 사용자 제공 네이티브 함수에 대한 함수 포인터 유형입니다. 콜백 함수는 다음 서명을 충족해야 합니다.

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

객체 수명 관리에서 설명하는 이유가 없는 한 napi_callback 내부에서 handle 및/또는 콜백 scope를 생성할 필요가 없습니다.

node_api_basic_finalize

추가됨: v21.6.0, v20.12.0, v18.20.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

외부 소유 데이터가 연결된 객체가 가비지 수집되었으므로 정리가 준비되었음을 사용자에게 알리는 추가 기능에서 제공하는 함수 포인터 유형입니다. 사용자는 객체 수집 시 호출될 다음 서명을 충족하는 함수를 제공해야 합니다. 현재 node_api_basic_finalize는 외부 데이터가 있는 객체가 수집될 때를 확인하는 데 사용할 수 있습니다.

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

객체 수명 관리에서 논의된 이유가 아닌 한, 함수 본문 내에서 핸들 및/또는 콜백 범위를 만드는 것은 필요하지 않습니다.

이러한 함수는 JavaScript 엔진이 JavaScript 코드를 실행할 수 없는 상태에서 호출될 수 있으므로 첫 번째 매개변수로 node_api_basic_env를 허용하는 Node-API만 호출할 수 있습니다. node_api_post_finalizer는 현재 가비지 수집 주기가 완료된 후 실행하기 위해 JavaScript 엔진 상태에 대한 액세스가 필요한 Node-API 호출을 예약하는 데 사용할 수 있습니다.

node_api_create_external_string_latin1node_api_create_external_string_utf16의 경우 외부 문자열은 환경 종료 후반부에 수집될 수 있으므로 env 매개변수는 null일 수 있습니다.

변경 이력:

  • 실험적 (NAPI_EXPERIMENTAL): 첫 번째 매개변수로 node_api_basic_env를 허용하는 Node-API 호출만 호출할 수 있습니다. 그렇지 않으면 적절한 오류 메시지와 함께 애플리케이션이 종료됩니다. 이 기능은 NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT을 정의하여 끌 수 있습니다.

napi_finalize

추가된 버전: v8.0.0

N-API 버전: 1

가비지 컬렉션 이벤트에 대한 응답으로 Node-API에 대한 일련의 호출을 가비지 컬렉션 주기가 완료된 후 예약할 수 있도록 사용자에게 허용하는 애드온 제공 함수에 대한 함수 포인터 유형입니다. 이러한 함수 포인터는 node_api_post_finalizer와 함께 사용할 수 있습니다.

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

변경 이력:

  • 실험적(NAPI_EXPERIMENTAL이 정의됨): 이 유형의 함수는 node_api_post_finalizer를 제외하고는 더 이상 finalizer로 사용할 수 없습니다. 대신 node_api_basic_finalize를 사용해야 합니다. 이 기능은 NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT를 정의하여 끌 수 있습니다.

napi_async_execute_callback

추가된 버전: v8.0.0

N-API 버전: 1

비동기 작업을 지원하는 함수와 함께 사용되는 함수 포인터입니다. 콜백 함수는 다음 서명을 충족해야 합니다.

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

이 함수의 구현에서는 JavaScript를 실행하거나 JavaScript 객체와 상호 작용하는 Node-API 호출을 피해야 합니다. Node-API 호출은 대신 napi_async_complete_callback에 있어야 합니다. napi_env 매개변수를 사용하지 마십시오. JavaScript 실행으로 이어질 가능성이 높습니다.

napi_async_complete_callback

추가된 버전: v8.0.0

N-API 버전: 1

비동기 작업을 지원하는 함수와 함께 사용되는 함수 포인터입니다. 콜백 함수는 다음 서명을 충족해야 합니다.

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

객체 수명 관리에서 설명하는 이유가 없는 한 함수 본문 내부에 핸들 및/또는 콜백 범위를 생성할 필요가 없습니다.

napi_threadsafe_function_call_js

추가됨: v10.6.0

N-API 버전: 4

비동기식 쓰레드 안전 함수 호출에 사용되는 함수 포인터입니다. 콜백은 메인 쓰레드에서 호출됩니다. 그 목적은 보조 쓰레드 중 하나에서 큐를 통해 도착하는 데이터 항목을 사용하여 JavaScript로의 호출(일반적으로 napi_call_function을 통해)에 필요한 매개변수를 구성한 다음 JavaScript로 호출하는 것입니다.

큐를 통해 보조 쓰레드에서 도착하는 데이터는 data 매개변수에 제공되고 호출할 JavaScript 함수는 js_callback 매개변수에 제공됩니다.

Node-API는 이 콜백을 호출하기 전에 환경을 설정하므로 napi_make_callback을 통해서가 아니라 napi_call_function을 통해 JavaScript 함수를 호출하는 것으로 충분합니다.

콜백 함수는 다음 서명을 충족해야 합니다.

C
typedef void (*napi_threadsafe_function_call_js)(napi_env env,
                                                 napi_value js_callback,
                                                 void* context,
                                                 void* data);
  • [in] env: API 호출에 사용할 환경 또는 쓰레드 안전 함수가 해제 중이고 data를 해제해야 할 수 있는 경우 NULL입니다.
  • [in] js_callback: 호출할 JavaScript 함수 또는 쓰레드 안전 함수가 해제 중이고 data를 해제해야 할 수 있는 경우 NULL입니다. 쓰레드 안전 함수가 js_callback 없이 생성된 경우에도 NULL일 수 있습니다.
  • [in] context: 쓰레드 안전 함수가 생성된 선택적 데이터입니다.
  • [in] data: 보조 쓰레드에서 생성된 데이터입니다. 이 네이티브 데이터를 js_callback이 호출될 때 매개변수로 전달할 수 있는 JavaScript 값(Node-API 함수 사용)으로 변환하는 것은 콜백의 책임입니다. 이 포인터는 쓰레드와 이 콜백에 의해 전적으로 관리됩니다. 따라서 이 콜백은 데이터를 해제해야 합니다.

객체 수명 관리에서 논의된 이유가 아닌 한, 함수 본문 내부에 핸들 및/또는 콜백 범위를 생성할 필요가 없습니다.

napi_cleanup_hook

추가됨: v19.2.0, v18.13.0

N-API 버전: 3

napi_add_env_cleanup_hook와 함께 사용되는 함수 포인터입니다. 환경이 해체될 때 호출됩니다.

콜백 함수는 다음 시그니처를 충족해야 합니다.

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

napi_async_cleanup_hook

추가됨: v14.10.0, v12.19.0

napi_add_async_cleanup_hook와 함께 사용되는 함수 포인터입니다. 환경이 해체될 때 호출됩니다.

콜백 함수는 다음 시그니처를 충족해야 합니다.

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

함수 본문은 비동기 정리 작업을 시작해야 하며, 그 끝에서 handlenapi_remove_async_cleanup_hook 호출에 전달되어야 합니다.

오류 처리

Node-API는 오류 처리에 반환 값과 JavaScript 예외를 모두 사용합니다. 다음 섹션에서는 각 경우에 대한 접근 방식을 설명합니다.

반환 값

모든 Node-API 함수는 동일한 오류 처리 패턴을 공유합니다. 모든 API 함수의 반환 형식은 napi_status입니다.

요청이 성공하고 처리되지 않은 JavaScript 예외가 발생하지 않은 경우 반환 값은 napi_ok가 됩니다. 오류가 발생하고 예외가 발생한 경우 오류에 대한 napi_status 값이 반환됩니다. 예외가 발생하고 오류가 발생하지 않은 경우 napi_pending_exception이 반환됩니다.

napi_ok 또는 napi_pending_exception 이외의 반환 값이 반환되는 경우, 예외가 보류 중인지 확인하려면 napi_is_exception_pending을 호출해야 합니다. 자세한 내용은 예외에 대한 섹션을 참조하십시오.

가능한 napi_status 값의 전체 집합은 napi_api_types.h에 정의되어 있습니다.

napi_status 반환 값은 발생한 오류의 VM과 독립적인 표현을 제공합니다. 경우에 따라 오류를 나타내는 문자열과 VM(엔진) 관련 정보를 포함하여 더 자세한 정보를 얻는 것이 유용합니다.

이 정보를 검색하기 위해 napi_get_last_error_info가 제공되며, 이는 napi_extended_error_info 구조체를 반환합니다. napi_extended_error_info 구조체의 형식은 다음과 같습니다.

추가됨: v8.0.0

N-API 버전: 1

C
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: VM 관련 오류 코드입니다.
  • error_code: 마지막 오류에 대한 Node-API 상태 코드입니다.

napi_get_last_error_info는 마지막으로 호출된 Node-API 호출에 대한 정보를 반환합니다.

확장된 정보의 내용이나 형식에 의존하지 마십시오. SemVer의 적용 대상이 아니며 언제든지 변경될 수 있습니다. 로깅 목적으로만 사용됩니다.

napi_get_last_error_info

추가됨: v8.0.0

N-API 버전: 1

C
napi_status
napi_get_last_error_info(node_api_basic_env env,
                         const napi_extended_error_info** result);
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: 오류에 대한 자세한 정보가 포함된 napi_extended_error_info 구조체입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 발생한 마지막 오류에 대한 정보가 포함된 napi_extended_error_info 구조체를 가져옵니다.

반환된 napi_extended_error_info의 내용은 동일한 env에서 Node-API 함수가 호출될 때까지 유효합니다. 여기에는 napi_is_exception_pending 호출이 포함되므로 나중에 사용할 수 있도록 정보를 복사해야 하는 경우가 많습니다. error_message에 반환된 포인터는 정적으로 정의된 문자열을 가리키므로 다른 Node-API 함수가 호출되기 전에 error_message 필드에서 복사한 경우 해당 포인터를 안전하게 사용할 수 있습니다(덮어쓰여짐).

확장 정보의 내용이나 형식에 의존하지 마십시오. SemVer의 적용을 받지 않으며 언제든지 변경될 수 있습니다. 로깅 목적으로만 사용됩니다.

JavaScript 예외가 발생 중인 경우에도 이 API를 호출할 수 있습니다.

예외

모든 Node-API 함수 호출은 보류 중인 JavaScript 예외를 발생시킬 수 있습니다. JavaScript 실행을 유발하지 않을 수도 있는 모든 API 함수에도 해당됩니다.

함수가 반환하는 napi_statusnapi_ok이면 예외가 보류 중이 아니며 추가적인 작업이 필요하지 않습니다. 반환된 napi_statusnapi_ok 또는 napi_pending_exception이 아닌 경우, 단순히 즉시 반환하는 대신 복구하고 계속하려면, 예외가 보류 중인지 여부를 확인하기 위해 napi_is_exception_pending을 호출해야 합니다.

Node-API 함수를 호출하고 예외가 이미 보류 중인 경우 대부분의 경우 함수는 napi_pending_exceptionnapi_status를 사용하여 즉시 반환합니다. 그러나 모든 함수에 해당하는 것은 아닙니다. Node-API는 JavaScript로 돌아가기 전에 최소한의 정리를 허용하기 위해 함수의 하위 집합을 호출할 수 있도록 허용합니다. 이 경우 napi_status는 함수의 상태를 반영합니다. 이전에 보류 중인 예외는 반영하지 않습니다. 혼동을 피하려면 모든 함수 호출 후 오류 상태를 확인하십시오.

예외가 보류 중인 경우 두 가지 방법 중 하나를 사용할 수 있습니다.

첫 번째 방법은 적절한 정리를 수행한 다음 JavaScript로 실행이 반환되도록 반환하는 것입니다. JavaScript로의 전환의 일환으로, 예외는 네이티브 메서드가 호출된 JavaScript 코드의 지점에서 throw됩니다. 예외가 보류 중인 동안 대부분의 Node-API 호출의 동작은 명시되지 않았으며, 많은 호출이 단순히 napi_pending_exception을 반환하므로 최소한의 작업만 수행한 다음 예외를 처리할 수 있는 JavaScript로 돌아가십시오.

두 번째 방법은 예외를 처리하려고 시도하는 것입니다. 네이티브 코드가 예외를 catch하고 적절한 조치를 취한 다음 계속할 수 있는 경우가 있습니다. 이것은 예외를 안전하게 처리할 수 있는 것으로 알려진 특정 경우에만 권장됩니다. 이러한 경우 napi_get_and_clear_last_exception을 사용하여 예외를 가져오고 지울 수 있습니다. 성공하면 result는 throw된 마지막 JavaScript Object에 대한 핸들을 포함합니다. 예외를 가져온 후 예외를 처리할 수 없는 것으로 판단되면 napi_throw를 사용하여 다시 throw할 수 있습니다. 여기서 error는 throw될 JavaScript 값입니다.

네이티브 코드가 예외를 throw하거나 napi_value가 JavaScript Error 객체의 인스턴스인지 확인해야 하는 경우 다음 유틸리티 함수도 사용할 수 있습니다. napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_errornapi_is_error.

네이티브 코드가 Error 객체를 생성해야 하는 경우 다음 유틸리티 함수도 사용할 수 있습니다. napi_create_error, napi_create_type_error, napi_create_range_errornode_api_create_syntax_error. 여기서 result는 새로 생성된 JavaScript Error 객체를 참조하는 napi_value입니다.

Node.js 프로젝트는 내부적으로 생성된 모든 오류에 오류 코드를 추가하고 있습니다. 애플리케이션에서 모든 오류 검사에 이러한 오류 코드를 사용하는 것이 목표입니다. 관련 오류 메시지는 유지되지만, SemVer가 적용되지 않을 것이라는 예상으로 로깅 및 표시에만 사용될 것입니다. Node-API에서 내부 기능과 모듈별 기능 모두를 지원하기 위해(좋은 방법이므로) throw_create_ 함수는 오류 객체에 추가할 코드의 문자열인 선택적 코드 매개변수를 사용합니다. 선택적 매개변수가 NULL이면 오류와 연결된 코드가 없습니다. 코드가 제공되면 오류와 관련된 이름도 다음과 같이 업데이트됩니다.

text
originalName [code]

여기서 originalName은 오류와 관련된 원래 이름이고 code는 제공된 코드입니다. 예를 들어, 코드가 'ERR_ERROR_1'이고 TypeError가 생성 중이면 이름은 다음과 같습니다.

text
TypeError [ERR_ERROR_1]

napi_throw

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);
  • [in] env: API가 호출되는 환경입니다.
  • [in] error: throw할 JavaScript 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 JavaScript 값을 throw합니다.

napi_throw_error

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
                                         const char* code,
                                         const char* msg);
  • [in] env: API가 호출되는 환경입니다.
  • [in] code: 오류에 설정할 선택적 오류 코드입니다.
  • [in] msg: 오류와 연결할 텍스트를 나타내는 C 문자열입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 텍스트를 사용하여 JavaScript Error를 throw합니다.

napi_throw_type_error

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
                                              const char* code,
                                              const char* msg);
  • [in] env: API가 호출되는 환경입니다.
  • [in] code: 오류에 설정할 선택적 오류 코드입니다.
  • [in] msg: 오류와 연결할 텍스트를 나타내는 C 문자열입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 텍스트를 사용하여 JavaScript TypeError를 throw합니다.

napi_throw_range_error

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
                                               const char* code,
                                               const char* msg);
  • [in] env: API가 호출되는 환경입니다.
  • [in] code: 오류에 설정할 선택적 오류 코드입니다.
  • [in] msg: 오류와 연결할 텍스트를 나타내는 C 문자열입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 텍스트를 사용하여 JavaScript RangeError를 throw합니다.

node_api_throw_syntax_error

추가됨: v17.2.0, v16.14.0

N-API 버전: 9

C
NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
                                                    const char* code,
                                                    const char* msg);
  • [in] env: API가 호출되는 환경입니다.
  • [in] code: 오류에 설정될 선택적 오류 코드입니다.
  • [in] msg: 오류와 연결될 텍스트를 나타내는 C 문자열입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 텍스트를 사용하여 JavaScript SyntaxError를 throw합니다.

napi_is_error

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_is_error(napi_env env,
                                      napi_value value,
                                      bool* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 확인할 napi_value입니다.
  • [out] result: napi_value가 오류를 나타내는 경우 true, 그렇지 않으면 false로 설정되는 부울 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 napi_value가 오류 객체를 나타내는지 확인합니다.

napi_create_error

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_create_error(napi_env env,
                                          napi_value code,
                                          napi_value msg,
                                          napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] code: 오류와 연결될 오류 코드의 문자열이 포함된 선택적 napi_value입니다.
  • [in] msg: Error의 메시지로 사용될 JavaScript string을 참조하는 napi_value입니다.
  • [out] result: 생성된 오류를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 텍스트를 사용하여 JavaScript Error를 반환합니다.

napi_create_type_error

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
                                               napi_value code,
                                               napi_value msg,
                                               napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] code: 오류와 연결될 오류 코드의 문자열이 포함된 선택적 napi_value입니다.
  • [in] msg: Error의 메시지로 사용될 JavaScript string을 참조하는 napi_value입니다.
  • [out] result: 생성된 오류를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 텍스트를 사용하여 JavaScript TypeError를 반환합니다.

napi_create_range_error

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
                                                napi_value code,
                                                napi_value msg,
                                                napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] code: 오류와 연결될 오류 코드 문자열이 포함된 선택적 napi_value입니다.
  • [in] msg: Error의 메시지로 사용될 JavaScript string을 참조하는 napi_value입니다.
  • [out] result: 생성된 오류를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 텍스트를 사용하여 JavaScript RangeError를 반환합니다.

node_api_create_syntax_error

추가됨: v17.2.0, v16.14.0

N-API 버전: 9

C
NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
                                                     napi_value code,
                                                     napi_value msg,
                                                     napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] code: 오류와 연결될 오류 코드 문자열이 포함된 선택적 napi_value입니다.
  • [in] msg: Error의 메시지로 사용될 JavaScript string을 참조하는 napi_value입니다.
  • [out] result: 생성된 오류를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 제공된 텍스트를 사용하여 JavaScript SyntaxError를 반환합니다.

napi_get_and_clear_last_exception

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: 예외가 대기 중인 경우 예외, 그렇지 않으면 NULL입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 JavaScript 예외가 대기 중인 경우에도 호출할 수 있습니다.

napi_is_exception_pending

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_is_exception_pending(napi_env env, bool* result);
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: 예외가 대기 중인 경우 true로 설정되는 부울 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 JavaScript 예외가 대기 중인 경우에도 호출할 수 있습니다.

napi_fatal_exception

추가됨: v9.10.0

N-API 버전: 3

C
napi_status napi_fatal_exception(napi_env env, napi_value err);
  • [in] env: API가 호출되는 환경입니다.
  • [in] err: 'uncaughtException'에 전달되는 오류입니다.

JavaScript에서 'uncaughtException'을 트리거합니다. 비동기 콜백이 복구할 방법이 없는 예외를 throw하는 경우 유용합니다.

치명적인 오류

네이티브 애드온에서 복구할 수 없는 오류가 발생하는 경우, 프로세스를 즉시 종료하기 위해 치명적인 오류를 throw할 수 있습니다.

napi_fatal_error

추가됨: v8.2.0

N-API 버전: 1

C
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: 바이트 단위의 위치 길이 또는 null로 종료되는 경우 NAPI_AUTO_LENGTH입니다.
  • [in] message: 오류와 관련된 메시지입니다.
  • [in] message_len: 바이트 단위의 메시지 길이 또는 null로 종료되는 경우 NAPI_AUTO_LENGTH입니다.

함수 호출은 반환되지 않으며 프로세스가 종료됩니다.

이 API는 JavaScript 예외가 대기 중인 경우에도 호출할 수 있습니다.

객체 수명 관리

Node-API 호출이 이루어짐에 따라, 기본 VM의 힙에 있는 객체에 대한 핸들이 napi_values로 반환될 수 있습니다. 이러한 핸들은 네이티브 코드에서 더 이상 필요하지 않을 때까지 객체를 '활성' 상태로 유지해야 합니다. 그렇지 않으면 네이티브 코드가 사용을 완료하기 전에 객체가 수집될 수 있습니다.

객체 핸들이 반환됨에 따라 '범위'와 연결됩니다. 기본 범위의 수명은 네이티브 메서드 호출의 수명과 연결됩니다. 결과적으로 기본적으로 핸들은 유효한 상태를 유지하고 이러한 핸들과 연결된 객체는 네이티브 메서드 호출의 수명 동안 활성 상태로 유지됩니다.

그러나 많은 경우 핸들이 네이티브 메서드보다 짧거나 긴 수명 동안 유효해야 합니다. 다음 섹션에서는 핸들 수명을 기본값에서 변경하는 데 사용할 수 있는 Node-API 함수에 대해 설명합니다.

네이티브 메서드보다 짧은 핸들 수명주기 만들기

네이티브 메서드의 수명주기보다 짧은 핸들 수명주기를 만드는 것이 종종 필요합니다. 예를 들어, 큰 배열의 요소를 반복하는 루프가 있는 네이티브 메서드를 고려해 보세요.

C
for (int i = 0; i < 1000000; i++) {
  napi_value result;
  napi_status status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // 요소를 사용하여 작업 수행
}

이렇게 하면 많은 수의 핸들이 생성되어 상당한 리소스를 소모하게 됩니다. 또한 네이티브 코드는 가장 최근의 핸들만 사용할 수 있지만, 모든 연관된 객체는 동일한 범위를 공유하기 때문에 계속해서 살아 있게 됩니다.

이러한 경우를 처리하기 위해 Node-API는 새로 생성된 핸들이 연결될 새로운 '범위'를 설정하는 기능을 제공합니다. 해당 핸들이 더 이상 필요하지 않으면 범위를 '닫을' 수 있으며, 범위와 연결된 모든 핸들은 무효화됩니다. 범위를 열고 닫는 데 사용할 수 있는 메서드는 napi_open_handle_scopenapi_close_handle_scope입니다.

Node-API는 중첩된 단일 범위 계층 구조만 지원합니다. 어느 시점에도 활성 범위는 하나뿐이며, 모든 새 핸들은 활성화된 동안 해당 범위와 연결됩니다. 범위는 열린 순서의 역순으로 닫아야 합니다. 또한 네이티브 메서드 내에서 생성된 모든 범위는 해당 메서드에서 반환하기 전에 닫아야 합니다.

앞의 예제에서 napi_open_handle_scopenapi_close_handle_scope 호출을 추가하면 루프 실행 전체에서 최대 하나의 핸들만 유효하게 유지됩니다.

C
for (int i = 0; i < 1000000; i++) {
  napi_handle_scope scope;
  napi_status status = napi_open_handle_scope(env, &scope);
  if (status != napi_ok) {
    break;
  }
  napi_value result;
  status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // 요소를 사용하여 작업 수행
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
}

범위를 중첩할 때 내부 범위의 핸들이 해당 범위의 수명주기보다 오래 지속되어야 하는 경우가 있습니다. Node-API는 이러한 경우를 지원하기 위해 '탈출 가능한 범위'를 지원합니다. 탈출 가능한 범위를 사용하면 하나의 핸들을 '승격'하여 현재 범위를 '탈출'할 수 있으며, 핸들의 수명주기는 현재 범위에서 외부 범위로 변경됩니다.

탈출 가능한 범위를 열고 닫는 데 사용할 수 있는 메서드는 napi_open_escapable_handle_scopenapi_close_escapable_handle_scope입니다.

핸들을 승격하려는 요청은 napi_escape_handle을 통해 이루어지며, 이 메서드는 한 번만 호출할 수 있습니다.

napi_open_handle_scope

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
                                               napi_handle_scope* result);
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: 새 스코프를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 새로운 스코프를 엽니다.

napi_close_handle_scope

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope);
  • [in] env: API가 호출되는 환경입니다.
  • [in] scope: 닫을 스코프를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 스코프를 닫습니다. 스코프는 생성된 역순으로 닫아야 합니다.

이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.

napi_open_escapable_handle_scope

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status
    napi_open_escapable_handle_scope(napi_env env,
                                     napi_handle_scope* result);
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: 새 스코프를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 외부 스코프로 하나의 객체를 승격시킬 수 있는 새로운 스코프를 엽니다.

napi_close_escapable_handle_scope

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope);
  • [in] env: API가 호출되는 환경입니다.
  • [in] scope: 닫을 스코프를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 스코프를 닫습니다. 스코프는 생성된 역순으로 닫아야 합니다.

이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.

napi_escape_handle

추가됨: v8.0.0

N-API 버전: 1

C
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: escaping될 JavaScript Object를 나타내는 napi_value입니다.
  • [out] result: 외부 범위에서 escaping된 Object에 대한 핸들을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 JavaScript 객체에 대한 핸들을 승격시켜 외부 범위의 수명 동안 유효하게 만듭니다. 범위당 한 번만 호출할 수 있습니다. 한 번 이상 호출하면 오류가 반환됩니다.

이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.

네이티브 메서드보다 수명이 긴 값에 대한 참조

어떤 경우에는 애드온이 단일 네이티브 메서드 호출보다 수명이 긴 값을 생성하고 참조해야 할 수 있습니다. 예를 들어, 생성자를 만들고 나중에 인스턴스를 생성하기 위한 요청에서 해당 생성자를 사용하려면 여러 다른 인스턴스 생성 요청에서 생성자 객체를 참조할 수 있어야 합니다. 이전 섹션에서 설명한 것처럼 napi_value로 반환된 일반 핸들로는 이것이 불가능합니다. 일반 핸들의 수명은 범위에 의해 관리되며 모든 범위는 네이티브 메서드가 끝나기 전에 닫혀야 합니다.

Node-API는 값에 대한 영속 참조를 생성하는 메서드를 제공합니다. 현재 Node-API는 객체, 외부, 함수 및 심볼을 포함한 제한된 값 유형 집합에 대해서만 참조를 생성할 수 있습니다.

각 참조에는 0 이상의 값을 갖는 연관된 카운트가 있으며, 이는 참조가 해당 값을 계속 유지할지 여부를 결정합니다. 카운트가 0인 참조는 값이 수집되는 것을 방지하지 않습니다. 객체(객체, 함수, 외부) 및 심볼 유형의 값은 '약한' 참조가 되며 수집되지 않는 동안에도 계속 액세스할 수 있습니다. 0보다 큰 카운트는 값이 수집되는 것을 방지합니다.

심볼 값에는 여러 가지 종류가 있습니다. 진정한 약한 참조 동작은 napi_create_symbol 함수 또는 JavaScript Symbol() 생성자 호출을 사용하여 생성된 로컬 심볼에 의해서만 지원됩니다. node_api_symbol_for 함수 또는 JavaScript Symbol.for() 함수 호출을 사용하여 생성된 전역적으로 등록된 심볼은 가비지 수집기가 수집하지 않기 때문에 항상 강한 참조로 유지됩니다. Symbol.iterator와 같은 잘 알려진 심볼도 마찬가지입니다. 이것들은 가비지 수집기에서 수집되지 않습니다.

참조는 초기 참조 카운트로 생성할 수 있습니다. 그런 다음 카운트는 napi_reference_refnapi_reference_unref를 통해 수정할 수 있습니다. 카운트가 0인 참조에 대해 객체가 수집되면 참조와 연결된 객체를 가져오는 후속 호출 napi_get_reference_value은 반환된 napi_value에 대해 NULL을 반환합니다. 객체가 수집된 참조에 대해 napi_reference_ref를 호출하려고 하면 오류가 발생합니다.

애드온에서 더 이상 필요하지 않으면 참조를 삭제해야 합니다. 참조가 삭제되면 해당 객체가 수집되는 것을 더 이상 방지하지 않습니다. 영속 참조를 삭제하지 않으면 영속 참조에 대한 네이티브 메모리와 힙에 있는 해당 객체가 영구히 유지되어 '메모리 누수'가 발생합니다.

동일한 객체를 참조하는 여러 영속 참조를 생성할 수 있으며, 각 참조는 개별 카운트를 기반으로 객체를 계속 유지하거나 유지하지 않습니다. 동일한 객체에 대한 여러 영속 참조는 예기치 않게 네이티브 메모리를 계속 유지할 수 있습니다. 영속 참조에 대한 네이티브 구조는 참조된 객체에 대한 finalizer가 실행될 때까지 계속 유지되어야 합니다. 동일한 객체에 대해 새로운 영속 참조가 생성되면 해당 객체에 대한 finalizer가 실행되지 않고 이전 영속 참조가 가리키는 네이티브 메모리가 해제되지 않습니다. 가능한 경우 napi_reference_unref와 함께 napi_delete_reference를 호출하면 이를 방지할 수 있습니다.

변경 내역:

  • 실험적(NAPI_EXPERIMENTAL이 정의됨): 모든 값 유형에 대해 참조를 생성할 수 있습니다. 새로 지원되는 값 유형은 약한 참조 의미 체계를 지원하지 않으며 이러한 유형의 값은 참조 카운트가 0이 되면 해제되고 더 이상 참조에서 액세스할 수 없습니다.

napi_create_reference

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              uint32_t initial_refcount,
                                              napi_ref* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 참조가 생성될 napi_value입니다.
  • [in] initial_refcount: 새 참조의 초기 참조 카운트입니다.
  • [out] result: 새 참조를 가리키는 napi_ref입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 값에 대해 지정된 참조 카운트를 가진 새 참조를 생성합니다.

napi_delete_reference

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);
  • [in] env: API가 호출되는 환경입니다.
  • [in] ref: 삭제할 napi_ref입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 참조를 삭제합니다.

이 API는 보류 중인 JavaScript 예외가 있어도 호출할 수 있습니다.

napi_reference_ref

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
                                           napi_ref ref,
                                           uint32_t* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] ref: 참조 카운트가 증가될 napi_ref입니다.
  • [out] result: 새로운 참조 카운트입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 참조의 참조 카운트를 증가시키고 결과 참조 카운트를 반환합니다.

napi_reference_unref

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
                                             napi_ref ref,
                                             uint32_t* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] ref: 참조 카운트가 감소될 napi_ref입니다.
  • [out] result: 새로운 참조 카운트입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 참조의 참조 카운트를 감소시키고 결과 참조 카운트를 반환합니다.

napi_get_reference_value

추가됨: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
                                                 napi_ref ref,
                                                 napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] ref: 해당 값이 요청되는 napi_ref입니다.
  • [out] result: napi_ref가 참조하는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

유효한 경우, 이 API는 napi_ref와 연결된 JavaScript 값을 나타내는 napi_value를 반환합니다. 그렇지 않으면, result는 NULL이 됩니다.

현재 Node.js 환경 종료 시 정리

Node.js 프로세스는 일반적으로 종료 시 모든 리소스를 해제하지만, Node.js의 임베더 또는 향후 Worker 지원에서는 현재 Node.js 환경이 종료될 때 실행될 정리 후크를 애드온이 등록해야 할 수 있습니다.

Node-API는 이러한 콜백을 등록하고 등록 해제하는 함수를 제공합니다. 해당 콜백이 실행될 때 애드온이 보유하고 있는 모든 리소스는 해제되어야 합니다.

napi_add_env_cleanup_hook

추가됨: v10.2.0

N-API 버전: 3

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

현재 Node.js 환경이 종료될 때 arg 매개변수와 함께 실행될 함수로 fun을 등록합니다.

다른 arg 값을 사용하여 함수를 여러 번 안전하게 지정할 수 있습니다. 이 경우에도 여러 번 호출됩니다. 동일한 funarg 값을 여러 번 제공하는 것은 허용되지 않으며 프로세스가 중단됩니다.

후크는 역순으로 호출됩니다. 즉, 가장 최근에 추가된 후크가 먼저 호출됩니다.

이 후크는 napi_remove_env_cleanup_hook을 사용하여 제거할 수 있습니다. 일반적으로 이 후크가 추가된 리소스가 어쨌든 해체될 때 발생합니다.

비동기 정리의 경우 napi_add_async_cleanup_hook을 사용할 수 있습니다.

napi_remove_env_cleanup_hook

추가됨: v10.2.0

N-API 버전: 3

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

현재 Node.js 환경이 종료될 때 arg 매개변수와 함께 실행될 함수로 fun을 등록 해제합니다. 인수와 함수 값은 정확하게 일치해야 합니다.

이 함수는 원래 napi_add_env_cleanup_hook을 사용하여 등록되어야 하며, 그렇지 않으면 프로세스가 중단됩니다.

napi_add_async_cleanup_hook

[히스토리]

버전변경 사항
v14.10.0, v12.19.0hook 콜백의 시그니처 변경
v14.8.0, v12.19.0추가됨: v14.8.0, v12.19.0

N-API 버전: 8

C
NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
    node_api_basic_env env,
    napi_async_cleanup_hook hook,
    void* arg,
    napi_async_cleanup_hook_handle* remove_handle);
  • [in] env: API가 호출되는 환경입니다.
  • [in] hook: 환경 해체 시 호출할 함수 포인터입니다.
  • [in] arg: 호출될 때 hook에 전달할 포인터입니다.
  • [out] remove_handle: 비동기 정리 후크를 참조하는 선택적 핸들입니다.

현재 Node.js 환경이 종료될 때 remove_handlearg 매개변수와 함께 실행될 함수로 napi_async_cleanup_hook 유형의 함수인 hook을 등록합니다.

napi_add_env_cleanup_hook과 달리 후크는 비동기적일 수 있습니다.

그 외에는 일반적으로 napi_add_env_cleanup_hook의 동작과 일치합니다.

remove_handleNULL이 아니면, 후크가 이미 호출되었는지 여부에 관계없이 나중에 napi_remove_async_cleanup_hook에 전달해야 하는 불투명 값이 저장됩니다. 일반적으로 이 후크가 추가된 리소스가 어쨌든 해체될 때 발생합니다.

napi_remove_async_cleanup_hook

[히스토리]

버전변경 사항
v14.10.0, v12.19.0env 매개변수 제거
v14.8.0, v12.19.0추가됨: v14.8.0, v12.19.0
C
NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
    napi_async_cleanup_hook_handle remove_handle);

remove_handle에 해당하는 정리 후크의 등록을 취소합니다. 이미 실행이 시작되지 않은 경우 후크가 실행되지 않습니다. napi_add_async_cleanup_hook에서 얻은 모든 napi_async_cleanup_hook_handle 값에 대해 호출해야 합니다.

Node.js 환경 종료 시 최종화

Node.js 환경은 worker.terminate() 요청과 같이 JavaScript 실행이 허용되지 않는 즉시 임의의 시점에 해체될 수 있습니다. 환경이 해체될 때, JavaScript 객체, 스레드 안전 함수 및 환경 인스턴스 데이터의 등록된 napi_finalize 콜백이 즉시 독립적으로 호출됩니다.

napi_finalize 콜백의 호출은 수동으로 등록된 정리 후크 이후에 예약됩니다. napi_finalize 콜백에서 use-after-free를 방지하기 위해 환경 종료 중 애드온 최종화의 적절한 순서를 보장하기 위해 애드온은 napi_add_env_cleanup_hooknapi_add_async_cleanup_hook을 사용하여 정리 후크를 등록하여 할당된 리소스를 적절한 순서로 수동으로 해제해야 합니다.

모듈 등록

Node-API 모듈은 NODE_MODULE 매크로 대신 다음을 사용하는 것을 제외하고 다른 모듈과 유사한 방식으로 등록됩니다.

C
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

다음 차이점은 Init 메서드의 시그니처입니다. Node-API 모듈의 경우 다음과 같습니다.

C
napi_value Init(napi_env env, napi_value exports);

Init의 반환 값은 모듈의 exports 객체로 처리됩니다. 편의를 위해 Init 메서드에는 exports 매개변수를 통해 빈 객체가 전달됩니다. InitNULL을 반환하면 exports로 전달된 매개변수가 모듈에 의해 내보내집니다. Node-API 모듈은 module 객체를 수정할 수 없지만 모듈의 exports 속성으로 아무거나 지정할 수 있습니다.

hello 메서드를 함수로 추가하여 애드온에서 제공하는 메서드로 호출할 수 있도록 합니다.

C
napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor desc = {
    "hello",
    NULL,
    Method,
    NULL,
    NULL,
    NULL,
    napi_writable | napi_enumerable | napi_configurable,
    NULL
  };
  status = napi_define_properties(env, exports, 1, &desc);
  if (status != napi_ok) return NULL;
  return exports;
}

애드온에 대한 require()가 반환할 함수를 설정합니다.

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

새 인스턴스를 생성할 수 있도록 클래스를 정의합니다(객체 래핑과 함께 자주 사용됨).

C
// NOTE: 부분 예제, 참조된 모든 코드가 포함된 것은 아닙니다.
napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor properties[] = {
    { "value", NULL, NULL, GetValue, SetValue, NULL, napi_writable | napi_configurable, NULL },
    DECLARE_NAPI_METHOD("plusOne", PlusOne),
    DECLARE_NAPI_METHOD("multiply", Multiply),
  };

  napi_value cons;
  status =
      napi_define_class(env, "MyObject", New, NULL, 3, properties, &cons);
  if (status != napi_ok) return NULL;

  status = napi_create_reference(env, cons, 1, &constructor);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "MyObject", cons);
  if (status != napi_ok) return NULL;

  return exports;
}

NAPI_MODULEInit 함수를 정의하는 축약형으로 작동하는 NAPI_MODULE_INIT 매크로를 사용할 수도 있습니다.

C
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
  napi_value answer;
  napi_status result;

  status = napi_create_int64(env, 42, &answer);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "answer", answer);
  if (status != napi_ok) return NULL;

  return exports;
}

envexports 매개변수는 매크로 호출 후 함수 본문에 제공됩니다.

모든 Node-API 애드온은 컨텍스트 인식이므로 여러 번 로드될 수 있습니다. 이러한 모듈을 선언할 때 몇 가지 설계 고려 사항이 있습니다. 컨텍스트 인식 애드온에 대한 설명서에서 자세한 내용을 확인하십시오.

envexports 변수는 매크로 호출 후 함수 본문 내에서 사용할 수 있습니다.

객체에 속성을 설정하는 방법에 대한 자세한 내용은 JavaScript 속성 사용 섹션을 참조하십시오.

일반적으로 애드온 모듈을 빌드하는 방법에 대한 자세한 내용은 기존 API를 참조하십시오.

JavaScript 값 사용하기

Node-API는 모든 유형의 JavaScript 값을 생성하기 위한 API 집합을 제공합니다. 이러한 유형 중 일부는 ECMAScript 언어 사양6절에서 설명되어 있습니다.

기본적으로 이러한 API는 다음 중 하나를 수행하는 데 사용됩니다.

Node-API 값은 napi_value 유형으로 표현됩니다. JavaScript 값이 필요한 Node-API 호출은 napi_value를 사용합니다. 어떤 경우에는 API가 사전에 napi_value의 유형을 확인합니다. 그러나 성능 향상을 위해 호출자는 해당 napi_value가 API에서 예상하는 JavaScript 유형인지 확인하는 것이 좋습니다.

열거형 유형

napi_key_collection_mode

추가됨: v13.7.0, v12.17.0, v10.20.0

N-API 버전: 6

C
typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode;

Keys/Properties 필터 열거형을 설명합니다.

napi_key_collection_mode는 수집된 속성의 범위를 제한합니다.

napi_key_own_only는 수집된 속성을 지정된 객체로만 제한합니다. napi_key_include_prototypes는 객체의 프로토타입 체인의 모든 키도 포함합니다.

napi_key_filter

추가됨: v13.7.0, v12.17.0, v10.20.0

N-API 버전: 6

C
typedef enum {
  napi_key_all_properties = 0,
  napi_key_writable = 1,
  napi_key_enumerable = 1 << 1,
  napi_key_configurable = 1 << 2,
  napi_key_skip_strings = 1 << 3,
  napi_key_skip_symbols = 1 << 4
} napi_key_filter;

속성 필터 비트입니다. 이들은 OR 연산을 사용하여 복합 필터를 구성할 수 있습니다.

napi_key_conversion

추가됨: v13.7.0, v12.17.0, v10.20.0

N-API 버전: 6

C
typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion;

napi_key_numbers_to_strings는 정수 인덱스를 문자열로 변환합니다. napi_key_keep_numbers는 정수 인덱스에 대해 숫자를 반환합니다.

napi_valuetype

C
typedef enum {
  // ES6 유형 (typeof에 해당)
  napi_undefined,
  napi_null,
  napi_boolean,
  napi_number,
  napi_string,
  napi_symbol,
  napi_object,
  napi_function,
  napi_external,
  napi_bigint,
} napi_valuetype;

napi_value의 유형을 설명합니다. 이는 일반적으로 ECMAScript 언어 사양의 6.1절에 설명된 유형에 해당합니다. 해당 절의 유형 외에도 napi_valuetype는 외부 데이터가 있는 FunctionObject를 나타낼 수도 있습니다.

napi_external 유형의 JavaScript 값은 JavaScript에서 속성을 설정할 수 없고 프로토타입이 없는 일반 객체로 나타납니다.

napi_typedarray_type

C
typedef enum {
  napi_int8_array,
  napi_uint8_array,
  napi_uint8_clamped_array,
  napi_int16_array,
  napi_uint16_array,
  napi_int32_array,
  napi_uint32_array,
  napi_float32_array,
  napi_float64_array,
  napi_bigint64_array,
  napi_biguint64_array,
} napi_typedarray_type;

이는 TypedArray의 기본 이진 스칼라 데이터 유형을 나타냅니다. 이 열거형의 요소는 ECMAScript 언어 사양22.2절에 해당합니다.

객체 생성 함수

napi_create_array

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_array(napi_env env, napi_value* result)
  • [in] env: Node-API 호출이 수행되는 환경입니다.
  • [out] result: JavaScript Array를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 JavaScript Array 유형에 해당하는 Node-API 값을 반환합니다. JavaScript 배열은 ECMAScript 언어 사양의 22.1절에 설명되어 있습니다.

napi_create_array_with_length

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_array_with_length(napi_env env,
                                          size_t length,
                                          napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] length: Array의 초기 길이입니다.
  • [out] result: JavaScript Array를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 JavaScript Array 유형에 해당하는 Node-API 값을 반환합니다. Array의 length 속성은 전달된 length 매개변수로 설정됩니다. 그러나 배열이 생성될 때 기본 버퍼가 VM에 의해 미리 할당될 것이라고 보장되지는 않습니다. 해당 동작은 기본 VM 구현에 따라 달라집니다. 버퍼가 C를 통해 직접 읽고 쓰기 가능한 연속적인 메모리 블록이어야 하는 경우 napi_create_external_arraybuffer를 사용하는 것을 고려하십시오.

JavaScript 배열은 ECMAScript 언어 사양의 22.1절에 설명되어 있습니다.

napi_create_arraybuffer

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_arraybuffer(napi_env env,
                                    size_t byte_length,
                                    void** data,
                                    napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] length: 생성할 ArrayBuffer의 바이트 길이입니다.
  • [out] data: ArrayBuffer의 기본 바이트 버퍼에 대한 포인터입니다. dataNULL을 전달하여 선택적으로 무시할 수 있습니다.
  • [out] result: JavaScript ArrayBuffer를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 JavaScript ArrayBuffer에 해당하는 Node-API 값을 반환합니다. ArrayBuffer는 고정 길이 바이너리 데이터 버퍼를 나타내는 데 사용됩니다. 일반적으로 TypedArray 객체의 백업 버퍼로 사용됩니다. 할당된 ArrayBuffer는 전달된 length 매개변수에 의해 크기가 결정되는 기본 바이트 버퍼를 갖습니다. 호출자가 버퍼를 직접 조작하려는 경우 기본 버퍼가 선택적으로 호출자에게 반환됩니다. 이 버퍼는 네이티브 코드에서만 직접 작성할 수 있습니다. JavaScript에서 이 버퍼에 쓰려면 형식화된 배열 또는 DataView 객체를 생성해야 합니다.

JavaScript ArrayBuffer 객체는 ECMAScript 언어 사양의 24.1절에 설명되어 있습니다.

napi_create_buffer

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_buffer(napi_env env,
                               size_t size,
                               void** data,
                               napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] size: 기본 버퍼의 바이트 크기입니다.
  • [out] data: 기본 버퍼에 대한 원시 포인터입니다. dataNULL을 전달하여 선택적으로 무시할 수 있습니다.
  • [out] result: node::Buffer를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 node::Buffer 객체를 할당합니다. 이것은 여전히 완벽하게 지원되는 데이터 구조이지만, 대부분의 경우 TypedArray를 사용해도 충분합니다.

napi_create_buffer_copy

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_buffer_copy(napi_env env,
                                    size_t length,
                                    const void* data,
                                    void** result_data,
                                    napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] size: 입력 버퍼의 크기(바이트)(새 버퍼의 크기와 같아야 함).
  • [in] data: 복사할 기본 버퍼에 대한 원시 포인터.
  • [out] result_data: 새 Buffer의 기본 데이터 버퍼에 대한 포인터. result_dataNULL을 전달하여 선택적으로 무시할 수 있습니다.
  • [out] result: node::Buffer를 나타내는 napi_value.

API가 성공하면 napi_ok를 반환합니다.

이 API는 node::Buffer 객체를 할당하고 전달된 버퍼에서 복사된 데이터로 초기화합니다. 이것은 여전히 완벽하게 지원되는 데이터 구조이지만, 대부분의 경우 TypedArray를 사용해도 충분합니다.

napi_create_date

추가됨: v11.11.0, v10.17.0

N-API 버전: 5

C
napi_status napi_create_date(napi_env env,
                             double time,
                             napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] time: 1970년 1월 1일 UTC 이후 밀리초 단위의 ECMAScript 시간 값.
  • [out] result: JavaScript Date를 나타내는 napi_value.

API가 성공하면 napi_ok를 반환합니다.

이 API는 윤초를 관찰하지 않습니다. ECMAScript가 POSIX 시간 사양과 일치하므로 무시됩니다.

이 API는 JavaScript Date 객체를 할당합니다.

JavaScript Date 객체는 ECMAScript 언어 사양의 20.3절에 설명되어 있습니다.

napi_create_external

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_external(napi_env env,
                                 void* data,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] data: 외부 데이터에 대한 원시 포인터.
  • [in] finalize_cb: 외부 값이 수집될 때 호출할 선택적 콜백입니다. napi_finalize에서 자세한 내용을 제공합니다.
  • [in] finalize_hint: 수집 중에 마무리 콜백에 전달할 선택적 힌트.
  • [out] result: 외부 값을 나타내는 napi_value.

API가 성공하면 napi_ok를 반환합니다.

이 API는 외부 데이터가 연결된 JavaScript 값을 할당합니다. 이것은 JavaScript 코드를 통해 외부 데이터를 전달하는 데 사용되므로 나중에 napi_get_value_external을 사용하여 네이티브 코드에서 검색할 수 있습니다.

API는 생성된 JavaScript 객체가 가비지 수집될 때 호출되는 napi_finalize 콜백을 추가합니다.

생성된 값은 객체가 아니므로 추가 속성을 지원하지 않습니다. 별개의 값 유형으로 간주됩니다. 외부 값을 사용하여 napi_typeof()를 호출하면 napi_external이 생성됩니다.

napi_create_external_arraybuffer

추가됨: v8.0.0

N-API 버전: 1

C
napi_status
napi_create_external_arraybuffer(napi_env env,
                                 void* external_data,
                                 size_t byte_length,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] external_data: ArrayBuffer의 기본 바이트 버퍼에 대한 포인터입니다.
  • [in] byte_length: 기본 버퍼의 바이트 길이입니다.
  • [in] finalize_cb: ArrayBuffer가 수거될 때 호출할 선택적 콜백입니다. napi_finalize에서 자세한 내용을 확인할 수 있습니다.
  • [in] finalize_hint: 수거 중 finalize 콜백에 전달할 선택적 힌트입니다.
  • [out] result: JavaScript ArrayBuffer를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

Node.js 이외의 일부 런타임에서는 외부 버퍼 지원이 중단되었습니다. Node.js 이외의 런타임에서는 이 메서드가 외부 버퍼가 지원되지 않음을 나타내는 napi_no_external_buffers_allowed를 반환할 수 있습니다. 이러한 런타임 중 하나는 이 문제 electron/issues/35801에서 설명된 것처럼 Electron입니다.

모든 런타임과의 가장 광범위한 호환성을 유지하려면 노드-API 헤더를 포함하기 전에 애드온에서 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED를 정의할 수 있습니다. 이렇게 하면 외부 버퍼를 생성하는 2개의 함수가 숨겨집니다. 이렇게 하면 실수로 이러한 메서드 중 하나를 사용하는 경우 컴파일 오류가 발생합니다.

이 API는 JavaScript ArrayBuffer에 해당하는 Node-API 값을 반환합니다. ArrayBuffer의 기본 바이트 버퍼는 외부에서 할당되고 관리됩니다. 호출자는 finalize 콜백이 호출될 때까지 바이트 버퍼가 유효하게 유지되도록 해야 합니다.

API는 방금 생성된 JavaScript 객체가 가비지 수집될 때 호출될 napi_finalize 콜백을 추가합니다.

JavaScript ArrayBuffer는 ECMAScript 언어 사양의 24.1절에 설명되어 있습니다.

napi_create_external_buffer

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_external_buffer(napi_env env,
                                        size_t length,
                                        void* data,
                                        napi_finalize finalize_cb,
                                        void* finalize_hint,
                                        napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] length: 입력 버퍼의 크기(바이트)(새 버퍼의 크기와 같아야 함).
  • [in] data: JavaScript에 노출할 기본 버퍼에 대한 원시 포인터.
  • [in] finalize_cb: ArrayBuffer가 수집될 때 호출할 선택적 콜백입니다. napi_finalize에서 자세한 내용을 확인할 수 있습니다.
  • [in] finalize_hint: 수집 중 finalize 콜백에 전달할 선택적 힌트.
  • [out] result: node::Buffer를 나타내는 napi_value.

API가 성공하면 napi_ok를 반환합니다.

Node.js 이외의 일부 런타임은 외부 버퍼 지원을 중단했습니다. Node.js 이외의 런타임에서 이 메서드는 외부 버퍼가 지원되지 않음을 나타내는 napi_no_external_buffers_allowed를 반환할 수 있습니다. 이러한 런타임 중 하나는 이 문제 electron/issues/35801에 설명된 대로 Electron입니다.

모든 런타임과의 최대한의 호환성을 유지하려면 node-api 헤더를 포함하기 전에 애드온에서 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED를 정의할 수 있습니다. 그렇게 하면 외부 버퍼를 생성하는 2개의 함수가 숨겨집니다. 이렇게 하면 실수로 이러한 메서드 중 하나를 사용하는 경우 컴파일 오류가 발생합니다.

이 API는 node::Buffer 객체를 할당하고 전달된 버퍼를 백업으로 하는 데이터로 초기화합니다. 이것은 여전히 완전히 지원되는 데이터 구조이지만, 대부분의 경우 TypedArray를 사용해도 충분합니다.

이 API는 방금 생성된 JavaScript 객체가 가비지 수집된 후 호출되는 napi_finalize 콜백을 추가합니다.

Node.js >=4의 경우 BuffersUint8Array입니다.

napi_create_object

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_object(napi_env env, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: JavaScript Object를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 기본 JavaScript Object를 할당합니다. JavaScript에서 new Object()를 하는 것과 같습니다.

JavaScript Object 형식은 ECMAScript 언어 사양의 6.1.7절에 설명되어 있습니다.

napi_create_symbol

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_symbol(napi_env env,
                               napi_value description,
                               napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] description: 심볼의 설명으로 설정될 JavaScript string을 참조하는 선택적 napi_value입니다.
  • [out] result: JavaScript symbol을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 UTF8로 인코딩된 C 문자열에서 JavaScript symbol 값을 만듭니다.

JavaScript symbol 형식은 ECMAScript 언어 사양의 19.4절에 설명되어 있습니다.

node_api_symbol_for

추가됨: v17.5.0, v16.15.0

N-API 버전: 9

C
napi_status node_api_symbol_for(napi_env env,
                                const char* utf8description,
                                size_t length,
                                napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] utf8description: 심볼의 설명으로 사용될 텍스트를 나타내는 UTF-8 C 문자열입니다.
  • [in] length: 설명 문자열의 길이(바이트)입니다. null로 끝나는 경우 NAPI_AUTO_LENGTH입니다.
  • [out] result: JavaScript symbol을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 지정된 설명을 가진 기존 심볼을 전역 레지스트리에서 검색합니다. 심볼이 이미 존재하면 반환되고, 그렇지 않으면 레지스트리에 새 심볼이 생성됩니다.

JavaScript symbol 형식은 ECMAScript 언어 사양의 19.4절에 설명되어 있습니다.

napi_create_typedarray

추가됨: v8.0.0

N-API 버전: 1

C
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: TypedArray를 투영할 시작 위치의 ArrayBuffer 내 바이트 오프셋입니다.
  • [out] result: JavaScript TypedArray를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 기존 ArrayBuffer를 기반으로 JavaScript TypedArray 객체를 생성합니다. TypedArray 객체는 각 요소가 동일한 기본 이진 스칼라 데이터 유형을 갖는 기본 데이터 버퍼에 대한 배열과 같은 뷰를 제공합니다.

(length * size_of_element) + byte_offset은 전달된 배열의 바이트 크기보다 작거나 같아야 합니다. 그렇지 않으면 RangeError 예외가 발생합니다.

JavaScript TypedArray 객체는 ECMAScript 언어 사양의 22.2절에 설명되어 있습니다.

node_api_create_buffer_from_arraybuffer

추가됨: v23.0.0

[안정적: 1 - 실험적]

안정적: 1 안정성: 1 - 실험적

C
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
                                                              napi_value arraybuffer,
                                                              size_t byte_offset,
                                                              size_t byte_length,
                                                              napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] arraybuffer: 버퍼가 생성될 ArrayBuffer입니다.
  • [in] byte_offset: 버퍼 생성을 시작할 ArrayBuffer 내 바이트 오프셋입니다.
  • [in] byte_length: ArrayBuffer에서 생성할 버퍼의 바이트 길이입니다.
  • [out] result: 생성된 JavaScript Buffer 객체를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 기존 ArrayBuffer에서 JavaScript Buffer 객체를 생성합니다. Buffer 객체는 Node.js 전용 클래스로 JavaScript에서 이진 데이터를 직접 처리하는 방법을 제공합니다.

바이트 범위 [byte_offset, byte_offset + byte_length)ArrayBuffer의 경계 내에 있어야 합니다. byte_offset + byte_lengthArrayBuffer의 크기를 초과하면 RangeError 예외가 발생합니다.

napi_create_dataview

추가됨: v8.3.0

N-API 버전: 1

C
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: DataView의 기반이 되는 ArrayBuffer입니다.
  • [in] byte_offset: ArrayBuffer 내에서 DataView를 투영할 시작 바이트 오프셋입니다.
  • [out] result: JavaScript DataView를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 기존 ArrayBuffer를 기반으로 JavaScript DataView 객체를 생성합니다. DataView 객체는 기본 데이터 버퍼에 대한 배열과 같은 뷰를 제공하지만, ArrayBuffer에 크기와 유형이 다른 항목을 허용합니다.

byte_length + byte_offset이 전달된 배열의 바이트 크기 이하여야 합니다. 그렇지 않으면 RangeError 예외가 발생합니다.

JavaScript DataView 객체는 ECMAScript 언어 사양의 24.3절에 설명되어 있습니다.

C 유형에서 Node-API로 변환하는 함수

napi_create_int32

추가됨: v8.4.0

N-API 버전: 1

C
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript에서 표현될 정수 값입니다.
  • [out] result: JavaScript number를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 C int32_t 유형을 JavaScript number 유형으로 변환하는 데 사용됩니다.

JavaScript number 유형은 ECMAScript 언어 사양의 6.1.6절에 설명되어 있습니다.

napi_create_uint32

추가된 버전: v8.4.0

N-API 버전: 1

C
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript에 표현될 부호 없는 정수 값입니다.
  • [out] result: JavaScript number를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 C uint32_t 형식에서 JavaScript number 형식으로 변환하는 데 사용됩니다.

JavaScript number 형식은 ECMAScript 언어 사양의 섹션 6.1.6에 설명되어 있습니다.

napi_create_int64

추가된 버전: v8.4.0

N-API 버전: 1

C
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript에 표현될 정수 값입니다.
  • [out] result: JavaScript number를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 C int64_t 형식에서 JavaScript number 형식으로 변환하는 데 사용됩니다.

JavaScript number 형식은 ECMAScript 언어 사양의 섹션 6.1.6에 설명되어 있습니다. int64_t의 전체 범위는 JavaScript에서 완전한 정밀도로 표현할 수 없습니다. Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) 범위를 벗어나는 정수 값은 정밀도를 잃게 됩니다.

napi_create_double

추가된 버전: v8.4.0

N-API 버전: 1

C
napi_status napi_create_double(napi_env env, double value, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript에 표현될 배정밀도 값입니다.
  • [out] result: JavaScript number를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 C double 형식에서 JavaScript number 형식으로 변환하는 데 사용됩니다.

JavaScript number 형식은 ECMAScript 언어 사양의 섹션 6.1.6에 설명되어 있습니다.

napi_create_bigint_int64

추가 버전: v10.7.0

N-API 버전: 6

C
napi_status napi_create_bigint_int64(napi_env env,
                                     int64_t value,
                                     napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript에 표시될 정수 값입니다.
  • [out] result: JavaScript BigInt를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 C int64_t 형식을 JavaScript BigInt 형식으로 변환합니다.

napi_create_bigint_uint64

추가 버전: v10.7.0

N-API 버전: 6

C
napi_status napi_create_bigint_uint64(napi_env env,
                                      uint64_t value,
                                      napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript에 표시될 부호 없는 정수 값입니다.
  • [out] result: JavaScript BigInt를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 C uint64_t 형식을 JavaScript BigInt 형식으로 변환합니다.

napi_create_bigint_words

추가 버전: v10.7.0

N-API 버전: 6

C
napi_status napi_create_bigint_words(napi_env env,
                                     int sign_bit,
                                     size_t word_count,
                                     const uint64_t* words,
                                     napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] sign_bit: 결과 BigInt가 양수인지 음수인지 결정합니다.
  • [in] word_count: words 배열의 길이입니다.
  • [in] words: little-endian 64비트 단어의 uint64_t 배열입니다.
  • [out] result: JavaScript BigInt를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 부호 없는 64비트 단어 배열을 단일 BigInt 값으로 변환합니다.

결과 BigInt는 다음과 같이 계산됩니다: (–1) (words[0] × (2) + words[1] × (2) + …)

napi_create_string_latin1

추가된 버전: v8.0.0

N-API 버전: 1

C
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: 바이트 단위의 문자열 길이입니다. null로 끝나는 경우 NAPI_AUTO_LENGTH입니다.
  • [out] result: JavaScript string을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ISO-8859-1 인코딩된 C 문자열에서 JavaScript string 값을 생성합니다. 네이티브 문자열은 복사됩니다.

JavaScript string 타입은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.

node_api_create_external_string_latin1

추가된 버전: v20.4.0, v18.18.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

C
napi_status
node_api_create_external_string_latin1(napi_env env,
                                       char* str,
                                       size_t length,
                                       napi_finalize finalize_callback,
                                       void* finalize_hint,
                                       napi_value* result,
                                       bool* copied);
  • [in] env: API가 호출된 환경입니다.
  • [in] str: ISO-8859-1 인코딩된 문자열을 나타내는 문자 버퍼입니다.
  • [in] length: 바이트 단위의 문자열 길이입니다. null로 끝나는 경우 NAPI_AUTO_LENGTH입니다.
  • [in] finalize_callback: 문자열이 수집될 때 호출되는 함수입니다. 이 함수는 다음 매개변수를 사용하여 호출됩니다.
    • [in] env: 애드온이 실행 중인 환경입니다. 이 값은 문자열이 워커 또는 메인 Node.js 인스턴스 종료의 일부로 수집되는 경우 null일 수 있습니다.
    • [in] data: void* 포인터인 값 str입니다.
    • [in] finalize_hint: API에 제공된 값 finalize_hint입니다. napi_finalize에서 자세한 정보를 제공합니다. 이 매개변수는 선택 사항입니다. null 값을 전달하면 해당 JavaScript 문자열이 수집될 때 애드온에 알릴 필요가 없음을 의미합니다.
  • [in] finalize_hint: 수집 중 최종화 콜백에 전달할 선택적 힌트입니다.
  • [out] result: JavaScript string을 나타내는 napi_value입니다.
  • [out] copied: 문자열이 복사되었는지 여부입니다. 복사된 경우, finalizer가 이미 호출되어 str을 파괴했을 것입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ISO-8859-1 인코딩된 C 문자열에서 JavaScript string 값을 생성합니다. 네이티브 문자열은 복사되지 않을 수 있으며 따라서 JavaScript 값의 전체 수명 동안 존재해야 합니다.

JavaScript string 타입은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.

napi_create_string_utf16

추가된 버전: v8.0.0

N-API 버전: 1

C
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: 두 바이트 코드 단위로 된 문자열의 길이입니다. null로 종료되는 경우 NAPI_AUTO_LENGTH를 사용합니다.
  • [out] result: JavaScript string을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 UTF16-LE 인코딩된 C 문자열에서 JavaScript string 값을 생성합니다. 네이티브 문자열이 복사됩니다.

JavaScript string 유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.

node_api_create_external_string_utf16

추가된 버전: v20.4.0, v18.18.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

C
napi_status
node_api_create_external_string_utf16(napi_env env,
                                      char16_t* str,
                                      size_t length,
                                      napi_finalize finalize_callback,
                                      void* finalize_hint,
                                      napi_value* result,
                                      bool* copied);
  • [in] env: API가 호출되는 환경입니다.

  • [in] str: UTF16-LE 인코딩된 문자열을 나타내는 문자 버퍼입니다.

  • [in] length: 두 바이트 코드 단위로 된 문자열의 길이입니다. null로 종료되는 경우 NAPI_AUTO_LENGTH를 사용합니다.

  • [in] finalize_callback: 문자열이 수집될 때 호출할 함수입니다. 이 함수는 다음 매개변수로 호출됩니다.

    • [in] env: 애드온이 실행 중인 환경입니다. 이 값은 문자열이 워커 또는 기본 Node.js 인스턴스의 종료의 일부로 수집되는 경우 null일 수 있습니다.
    • [in] data: void* 포인터인 str 값입니다.
    • [in] finalize_hint: API에 제공된 finalize_hint 값입니다. napi_finalize에서 더 자세한 내용을 제공합니다. 이 매개변수는 선택 사항입니다. null 값을 전달하면 해당 JavaScript 문자열이 수집될 때 애드온에 알릴 필요가 없음을 의미합니다.
  • [in] finalize_hint: 수집 중에 finalize 콜백에 전달할 선택적 힌트입니다.

  • [out] result: JavaScript string을 나타내는 napi_value입니다.

  • [out] copied: 문자열이 복사되었는지 여부입니다. 복사된 경우 finalizer가 이미 str을 삭제하기 위해 호출되었습니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 UTF16-LE 인코딩된 C 문자열에서 JavaScript string 값을 생성합니다. 네이티브 문자열은 복사되지 않을 수 있으므로 JavaScript 값의 전체 수명 주기 동안 존재해야 합니다.

JavaScript string 유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.

napi_create_string_utf8

추가된 버전: v8.0.0

N-API 버전: 1

C
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: 바이트 단위의 문자열 길이이거나, null로 종료된 경우 NAPI_AUTO_LENGTH입니다.
  • [out] result: JavaScript string을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 UTF8로 인코딩된 C 문자열에서 JavaScript string 값을 생성합니다. 네이티브 문자열은 복사됩니다.

JavaScript string 유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.

최적화된 속성 키를 생성하는 함수

V8을 포함한 많은 JavaScript 엔진은 내부화된 문자열을 속성 값을 설정하고 가져오는 키로 사용합니다. 일반적으로 해시 테이블을 사용하여 이러한 문자열을 생성하고 조회합니다. 키 생성당 약간의 비용이 추가되지만 전체 문자열 대신 문자열 포인터 비교를 가능하게 하여 이후 성능을 향상시킵니다.

새 JavaScript 문자열을 속성 키로 사용하려는 경우 일부 JavaScript 엔진의 경우 이 섹션의 함수를 사용하는 것이 더 효율적입니다. 그렇지 않으면 속성 키 생성 방법으로 문자열을 만들고 저장하는 데 추가 오버헤드가 있을 수 있으므로 napi_create_string_utf8 또는 node_api_create_external_string_utf8 시리즈 함수를 사용하세요.

node_api_create_property_key_latin1

추가된 버전: v22.9.0, v20.18.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

C
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
                                                           const char* str,
                                                           size_t length,
                                                           napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] str: ISO-8859-1로 인코딩된 문자열을 나타내는 문자 버퍼입니다.
  • [in] length: 바이트 단위의 문자열 길이이거나, null로 종료된 경우 NAPI_AUTO_LENGTH입니다.
  • [out] result: 객체의 속성 키로 사용될 최적화된 JavaScript string을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 객체의 속성 키로 사용될 ISO-8859-1로 인코딩된 C 문자열에서 최적화된 JavaScript string 값을 생성합니다. 네이티브 문자열은 복사됩니다. napi_create_string_latin1과 달리 동일한 str 포인터로 이 함수를 후속 호출하면 엔진에 따라 요청된 napi_value 생성 속도가 빨라질 수 있습니다.

JavaScript string 유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.

node_api_create_property_key_utf16

추가 버전: v21.7.0, v20.12.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

C
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
                                                          const char16_t* str,
                                                          size_t length,
                                                          napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] str: UTF16-LE로 인코딩된 문자열을 나타내는 문자 버퍼입니다.
  • [in] length: 문자열의 길이를 2바이트 코드 단위로 나타냅니다. null로 끝나는 문자열의 경우 NAPI_AUTO_LENGTH입니다.
  • [out] result: 객체의 속성 키로 사용될 최적화된 JavaScript string을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 객체의 속성 키로 사용될 UTF16-LE로 인코딩된 C 문자열에서 최적화된 JavaScript string 값을 만듭니다. 네이티브 문자열은 복사됩니다.

JavaScript string 유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.

node_api_create_property_key_utf8

추가 버전: v22.9.0, v20.18.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

C
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
                                                         const char* str,
                                                         size_t length,
                                                         napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] str: UTF8로 인코딩된 문자열을 나타내는 문자 버퍼입니다.
  • [in] length: 문자열의 길이를 2바이트 코드 단위로 나타냅니다. null로 끝나는 문자열의 경우 NAPI_AUTO_LENGTH입니다.
  • [out] result: 객체의 속성 키로 사용될 최적화된 JavaScript string을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 객체의 속성 키로 사용될 UTF8로 인코딩된 C 문자열에서 최적화된 JavaScript string 값을 만듭니다. 네이티브 문자열은 복사됩니다.

JavaScript string 유형은 ECMAScript 언어 사양의 섹션 6.1.4에 설명되어 있습니다.

Node-API에서 C 타입으로 변환하는 함수

napi_get_array_length

추가 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_array_length(napi_env env,
                                  napi_value value,
                                  uint32_t* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 길이를 조회할 JavaScript Array를 나타내는 napi_value입니다.
  • [out] result: 배열의 길이를 나타내는 uint32입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 배열의 길이를 반환합니다.

Array 길이는 ECMAScript 언어 사양의 섹션 22.1.4.1에 설명되어 있습니다.

napi_get_arraybuffer_info

추가 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_arraybuffer_info(napi_env env,
                                      napi_value arraybuffer,
                                      void** data,
                                      size_t* byte_length)
  • [in] env: API가 호출되는 환경입니다.
  • [in] arraybuffer: 조회할 ArrayBuffer를 나타내는 napi_value입니다.
  • [out] data: ArrayBuffer의 기본 데이터 버퍼입니다. byte_length가 0이면 NULL 또는 다른 포인터 값일 수 있습니다.
  • [out] byte_length: 기본 데이터 버퍼의 바이트 단위 길이입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ArrayBuffer의 기본 데이터 버퍼와 길이를 검색하는 데 사용됩니다.

경고: 이 API를 사용하는 동안 주의하십시오. 기본 데이터 버퍼의 수명은 반환된 후에도 ArrayBuffer에 의해 관리됩니다. 이 API를 안전하게 사용할 수 있는 한 가지 방법은 ArrayBuffer의 수명에 대한 제어를 보장하는 데 사용할 수 있는 napi_create_reference와 함께 사용하는 것입니다. GC를 트리거할 수 있는 다른 API 호출이 없는 한 동일한 콜백 내에서 반환된 데이터 버퍼를 사용하는 것도 안전합니다.

napi_get_buffer_info

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_buffer_info(napi_env env,
                                 napi_value value,
                                 void** data,
                                 size_t* length)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 쿼리할 node::Buffer 또는 Uint8Array를 나타내는 napi_value입니다.
  • [out] data: node::Buffer 또는 Uint8Array의 기본 데이터 버퍼입니다. 길이가 0이면 NULL이거나 다른 포인터 값일 수 있습니다.
  • [out] length: 기본 데이터 버퍼의 바이트 단위 길이입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드는 napi_get_typedarray_info와 동일한 databyte_length를 반환합니다. 또한 napi_get_typedarray_infonode::Buffer(Uint8Array)를 값으로 허용합니다.

이 API는 node::Buffer의 기본 데이터 버퍼와 길이를 검색하는 데 사용됩니다.

경고: 이 API를 사용할 때 기본 데이터 버퍼의 수명이 VM에 의해 관리되는 경우 보장되지 않으므로 주의하십시오.

napi_get_prototype

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_prototype(napi_env env,
                               napi_value object,
                               napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] object: 반환할 프로토타입을 가진 JavaScript Object를 나타내는 napi_value입니다. 이는 Object.getPrototypeOf와 동일한 값을 반환합니다(함수의 prototype 속성과는 다름).
  • [out] result: 지정된 객체의 프로토타입을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

napi_get_typedarray_info

추가된 버전: v8.0.0

N-API 버전: 1

C
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: 쿼리할 속성을 가진 TypedArray를 나타내는 napi_value입니다.
  • [out] type: TypedArray 내의 요소의 스칼라 데이터 유형입니다.
  • [out] length: TypedArray 내의 요소 수입니다.
  • [out] data: TypedArray의 첫 번째 요소를 가리키도록 byte_offset 값으로 조정된 TypedArray의 기본 데이터 버퍼입니다. 배열의 길이가 0이면 NULL이거나 다른 포인터 값일 수 있습니다.
  • [out] arraybuffer: TypedArray의 기본 ArrayBuffer입니다.
  • [out] byte_offset: 배열의 첫 번째 요소가 있는 기본 네이티브 배열 내의 바이트 오프셋입니다. 데이터 매개변수 값은 이미 조정되어 데이터가 배열의 첫 번째 요소를 가리키고 있습니다. 따라서 네이티브 배열의 첫 번째 바이트는 data - byte_offset에 있습니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 typed array의 다양한 속성을 반환합니다.

해당 속성이 필요하지 않으면 출력 매개변수 중 아무거나 NULL이 될 수 있습니다.

경고: 기본 데이터 버퍼는 VM에 의해 관리되므로 이 API를 사용할 때 주의하십시오.

napi_get_dataview_info

추가 버전: v8.3.0

N-API 버전: 1

C
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: 속성을 조회할 DataView를 나타내는 napi_value입니다.
  • [out] byte_length: DataView의 바이트 수입니다.
  • [out] data: DataView의 기본 데이터 버퍼입니다. byte_length가 0인 경우, NULL 또는 다른 포인터 값일 수 있습니다.
  • [out] arraybuffer: DataView의 기본 ArrayBuffer입니다.
  • [out] byte_offset: DataView 프로젝션을 시작할 데이터 버퍼 내 바이트 오프셋입니다.

API가 성공하면 napi_ok를 반환합니다.

해당 속성이 필요하지 않으면 출력 매개변수 중 어느 것이든 NULL이 될 수 있습니다.

이 API는 DataView의 다양한 속성을 반환합니다.

napi_get_date_value

추가 버전: v11.11.0, v10.17.0

N-API 버전: 5

C
napi_status napi_get_date_value(napi_env env,
                                napi_value value,
                                double* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript Date를 나타내는 napi_value입니다.
  • [out] result: 1970년 1월 1일 0시 UTC를 기준으로 한 밀리초 단위의 시간 값(double)입니다.

이 API는 윤초를 고려하지 않습니다. ECMAScript는 POSIX 시간 사양에 맞춰 윤초를 무시합니다.

API가 성공하면 napi_ok를 반환합니다. 날짜가 아닌 napi_value가 전달되면 napi_date_expected를 반환합니다.

이 API는 주어진 JavaScript Date의 시간 값에 대한 C double 기본형을 반환합니다.

napi_get_value_bool

추가 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript Boolean을 나타내는 napi_value입니다.
  • [out] result: 주어진 JavaScript Boolean과 동일한 C 부울 기본형입니다.

API가 성공하면 napi_ok를 반환합니다. 부울이 아닌 napi_value가 전달되면 napi_boolean_expected를 반환합니다.

이 API는 주어진 JavaScript Boolean과 동일한 C 부울 기본형을 반환합니다.

napi_get_value_double

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_get_value_double(napi_env env,
                                  napi_value value,
                                  double* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript number를 나타내는 napi_value입니다.
  • [out] result: 주어진 JavaScript number와 동등한 C double 기본형입니다.

API가 성공하면 napi_ok를 반환합니다. 숫자가 아닌 napi_value가 전달되면 napi_number_expected를 반환합니다.

이 API는 주어진 JavaScript number와 동등한 C double 기본형을 반환합니다.

napi_get_value_bigint_int64

추가됨: v10.7.0

N-API 버전: 6

C
napi_status napi_get_value_bigint_int64(napi_env env,
                                        napi_value value,
                                        int64_t* result,
                                        bool* lossless);
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript BigInt를 나타내는 napi_value입니다.
  • [out] result: 주어진 JavaScript BigInt와 동등한 C int64_t 기본형입니다.
  • [out] lossless: BigInt 값이 손실 없이 변환되었는지 여부를 나타냅니다.

API가 성공하면 napi_ok를 반환합니다. BigInt가 아닌 값이 전달되면 napi_bigint_expected를 반환합니다.

이 API는 주어진 JavaScript BigInt와 동등한 C int64_t 기본형을 반환합니다. 필요한 경우 값을 자르고 losslessfalse로 설정합니다.

napi_get_value_bigint_uint64

추가됨: v10.7.0

N-API 버전: 6

C
napi_status napi_get_value_bigint_uint64(napi_env env,
                                        napi_value value,
                                        uint64_t* result,
                                        bool* lossless);
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript BigInt를 나타내는 napi_value입니다.
  • [out] result: 주어진 JavaScript BigInt와 동등한 C uint64_t 기본형입니다.
  • [out] lossless: BigInt 값이 손실 없이 변환되었는지 여부를 나타냅니다.

API가 성공하면 napi_ok를 반환합니다. BigInt가 아닌 값이 전달되면 napi_bigint_expected를 반환합니다.

이 API는 주어진 JavaScript BigInt와 동등한 C uint64_t 기본형을 반환합니다. 필요한 경우 값을 자르고 losslessfalse로 설정합니다.

napi_get_value_bigint_words

추가된 버전: v10.7.0

N-API 버전: 6

C
napi_status napi_get_value_bigint_words(napi_env env,
                                        napi_value value,
                                        int* sign_bit,
                                        size_t* word_count,
                                        uint64_t* words);
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript BigInt를 나타내는 napi_value입니다.
  • [out] sign_bit: JavaScript BigInt가 양수인지 음수인지 나타내는 정수입니다.
  • [in/out] word_count: words 배열의 길이로 초기화해야 합니다. 반환 시 이 BigInt를 저장하는 데 필요한 실제 단어 수로 설정됩니다.
  • [out] words: 미리 할당된 64비트 단어 배열에 대한 포인터입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 단일 BigInt 값을 부호 비트, 64비트 리틀 엔디안 배열 및 배열의 요소 수로 변환합니다. word_count만 얻기 위해 sign_bitwords를 모두 NULL로 설정할 수 있습니다.

napi_get_value_external

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_value_external(napi_env env,
                                    napi_value value,
                                    void** result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript 외부 값을 나타내는 napi_value입니다.
  • [out] result: JavaScript 외부 값으로 래핑된 데이터에 대한 포인터입니다.

API가 성공하면 napi_ok를 반환합니다. 외부가 아닌 napi_value가 전달되면 napi_invalid_arg를 반환합니다.

이 API는 이전에 napi_create_external()에 전달된 외부 데이터 포인터를 검색합니다.

napi_get_value_int32

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_value_int32(napi_env env,
                                 napi_value value,
                                 int32_t* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript number를 나타내는 napi_value입니다.
  • [out] result: 주어진 JavaScript number에 해당하는 C int32 기본형입니다.

API가 성공하면 napi_ok를 반환합니다. 숫자가 아닌 napi_value가 전달되면 napi_number_expected가 반환됩니다.

이 API는 주어진 JavaScript number에 해당하는 C int32 기본형을 반환합니다.

숫자가 32비트 정수 범위를 초과하면 결과는 하위 32비트에 해당하는 값으로 잘립니다. 이로 인해 값이 > 2 - 1인 경우 큰 양수가 음수가 될 수 있습니다.

비유한 숫자 값(NaN, +Infinity 또는 -Infinity)은 결과를 0으로 설정합니다.

napi_get_value_int64

추가 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_value_int64(napi_env env,
                                 napi_value value,
                                 int64_t* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript number를 나타내는 napi_value입니다.
  • [out] result: 주어진 JavaScript number에 해당하는 C int64 기본형입니다.

API가 성공하면 napi_ok를 반환합니다. 숫자가 아닌 napi_value가 전달되면 napi_number_expected를 반환합니다.

이 API는 주어진 JavaScript number에 해당하는 C int64 기본형을 반환합니다.

Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) 범위 밖의 number 값은 정밀도가 손실됩니다.

유한하지 않은 숫자 값(NaN, +Infinity 또는 -Infinity)은 결과를 0으로 설정합니다.

napi_get_value_string_latin1

추가 버전: v8.0.0

N-API 버전: 1

C
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: JavaScript 문자열을 나타내는 napi_value입니다.
  • [in] buf: ISO-8859-1로 인코딩된 문자열을 쓸 버퍼입니다. NULL이 전달되면 null 종결자를 제외한 바이트 단위 문자열의 길이가 result에 반환됩니다.
  • [in] bufsize: 대상 버퍼의 크기입니다. 이 값이 부족하면 반환된 문자열이 잘리고 null로 종료됩니다.
  • [out] result: null 종결자를 제외하고 버퍼에 복사된 바이트 수입니다.

API가 성공하면 napi_ok를 반환합니다. string이 아닌 napi_value가 전달되면 napi_string_expected를 반환합니다.

이 API는 전달된 값에 해당하는 ISO-8859-1로 인코딩된 문자열을 반환합니다.

napi_get_value_string_utf8

추가됨: v8.0.0

N-API 버전: 1

C
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: JavaScript 문자열을 나타내는 napi_value입니다.
  • [in] buf: UTF8로 인코딩된 문자열을 쓸 버퍼입니다. NULL이 전달되면, 널 종결자를 제외한 문자열의 바이트 길이가 result에 반환됩니다.
  • [in] bufsize: 대상 버퍼의 크기입니다. 이 값이 충분하지 않으면, 반환된 문자열은 잘리고 널로 끝납니다.
  • [out] result: 널 종결자를 제외하고 버퍼에 복사된 바이트 수입니다.

API가 성공하면 napi_ok를 반환합니다. string이 아닌 napi_value가 전달되면 napi_string_expected를 반환합니다.

이 API는 전달된 값에 해당하는 UTF8로 인코딩된 문자열을 반환합니다.

napi_get_value_string_utf16

추가됨: v8.0.0

N-API 버전: 1

C
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: JavaScript 문자열을 나타내는 napi_value입니다.
  • [in] buf: UTF16-LE로 인코딩된 문자열을 쓸 버퍼입니다. NULL이 전달되면, 널 종결자를 제외한 문자열의 2바이트 코드 단위 길이가 반환됩니다.
  • [in] bufsize: 대상 버퍼의 크기입니다. 이 값이 충분하지 않으면, 반환된 문자열은 잘리고 널로 끝납니다.
  • [out] result: 널 종결자를 제외하고 버퍼에 복사된 2바이트 코드 단위 수입니다.

API가 성공하면 napi_ok를 반환합니다. string이 아닌 napi_value가 전달되면 napi_string_expected를 반환합니다.

이 API는 전달된 값에 해당하는 UTF16으로 인코딩된 문자열을 반환합니다.

napi_get_value_uint32

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_get_value_uint32(napi_env env,
                                  napi_value value,
                                  uint32_t* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: JavaScript number를 나타내는 napi_value입니다.
  • [out] result: 주어진 napi_value의 C 기본형과 동일한 uint32_t입니다.

API가 성공하면 napi_ok를 반환합니다. 숫자가 아닌 napi_value가 전달되면 napi_number_expected를 반환합니다.

이 API는 주어진 napi_value의 C 기본형과 동일한 값을 uint32_t로 반환합니다.

전역 인스턴스를 가져오는 함수

napi_get_boolean

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 가져올 부울 값입니다.
  • [out] result: 가져올 JavaScript Boolean 싱글톤을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 주어진 부울 값을 나타내는 데 사용되는 JavaScript 싱글톤 객체를 반환하는 데 사용됩니다.

napi_get_global

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_get_global(napi_env env, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: JavaScript global 객체를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 global 객체를 반환합니다.

napi_get_null

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_get_null(napi_env env, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: JavaScript null 객체를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 null 객체를 반환합니다.

napi_get_undefined

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_get_undefined(napi_env env, napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: JavaScript Undefined 값을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 Undefined 객체를 반환합니다.

JavaScript 값 및 추상 연산 작업

Node-API는 JavaScript 값에 대한 일부 추상 연산을 수행하는 API 세트를 노출합니다. 이러한 연산 중 일부는 ECMAScript 언어 사양섹션 7에 문서화되어 있습니다.

이러한 API는 다음 중 하나를 수행하는 것을 지원합니다.

napi_coerce_to_bool

추가 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_coerce_to_bool(napi_env env,
                                napi_value value,
                                napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 강제 변환할 JavaScript 값입니다.
  • [out] result: 강제 변환된 JavaScript Boolean을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ECMAScript 언어 사양의 섹션 7.1.2에 정의된 추상 연산 ToBoolean()을 구현합니다.

napi_coerce_to_number

추가 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_coerce_to_number(napi_env env,
                                  napi_value value,
                                  napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 강제 변환할 JavaScript 값입니다.
  • [out] result: 강제 변환된 JavaScript number를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ECMAScript 언어 사양의 섹션 7.1.3에 정의된 추상 연산 ToNumber()를 구현합니다. 이 함수는 전달된 값이 객체인 경우 잠재적으로 JS 코드를 실행합니다.

napi_coerce_to_object

추가 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_coerce_to_object(napi_env env,
                                  napi_value value,
                                  napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 강제 변환할 JavaScript 값입니다.
  • [out] result: 강제 변환된 JavaScript Object를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ECMAScript 언어 사양의 섹션 7.1.13에 정의된 추상 연산 ToObject()를 구현합니다.

napi_coerce_to_string

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_coerce_to_string(napi_env env,
                                  napi_value value,
                                  napi_value* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 강제 변환할 JavaScript 값입니다.
  • [out] result: 강제 변환된 JavaScript string을 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ECMAScript 언어 사양의 섹션 7.1.13에 정의된 추상 연산 ToString()을 구현합니다. 이 함수는 전달된 값이 객체인 경우 JS 코드를 실행할 가능성이 있습니다.

napi_typeof

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 형식을 쿼리할 JavaScript 값입니다.
  • [out] result: JavaScript 값의 형식입니다.

API가 성공하면 napi_ok를 반환합니다.

  • value의 형식이 알려진 ECMAScript 형식이 아니고 value가 외부 값이 아니면 napi_invalid_arg입니다.

이 API는 ECMAScript 언어 사양의 섹션 12.5.5에 정의된 객체에서 typeof 연산자를 호출하는 것과 유사한 동작을 나타냅니다. 그러나 몇 가지 차이점이 있습니다.

value에 유효하지 않은 형식이 있으면 오류가 반환됩니다.

napi_instanceof

추가됨: v8.0.0

N-API 버전: 1

C
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: object instanceof constructor가 참이면 true로 설정되는 부울 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ECMAScript 언어 사양의 섹션 12.10.4에 정의된 객체에서 instanceof 연산자를 호출하는 것을 나타냅니다.

napi_is_array

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_is_array(napi_env env, napi_value value, bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 확인할 JavaScript 값입니다.
  • [out] result: 주어진 객체가 배열인지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ECMAScript 언어 사양의 섹션 7.2.2에 정의된 대로 객체에서 IsArray 작업을 호출하는 것을 나타냅니다.

napi_is_arraybuffer

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 확인할 JavaScript 값입니다.
  • [out] result: 주어진 객체가 ArrayBuffer인지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object가 ArrayBuffer인지 확인합니다.

napi_is_buffer

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 확인할 JavaScript 값입니다.
  • [out] result: 주어진 napi_valuenode::Buffer 또는 Uint8Array 객체를 나타내는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object가 버퍼 또는 Uint8Array인지 확인합니다. 호출자가 값이 Uint8Array인지 확인해야 하는 경우 napi_is_typedarray를 사용하는 것이 좋습니다.

napi_is_date

추가된 버전: v11.11.0, v10.17.0

N-API 버전: 5

C
napi_status napi_is_date(napi_env env, napi_value value, bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 확인할 JavaScript 값입니다.
  • [out] result: 주어진 napi_value가 JavaScript Date 객체를 나타내는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object가 날짜인지 확인합니다.

napi_is_error

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_is_error(napi_env env, napi_value value, bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 확인할 JavaScript 값입니다.
  • [out] result: 주어진 napi_valueError 객체를 나타내는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 ObjectError인지 확인합니다.

napi_is_typedarray

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 확인할 JavaScript 값입니다.
  • [out] result: 주어진 napi_valueTypedArray를 나타내는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object가 타입 배열인지 확인합니다.

napi_is_dataview

추가된 버전: v8.3.0

N-API 버전: 1

C
napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 확인할 JavaScript 값입니다.
  • [out] result: 주어진 napi_valueDataView를 나타내는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 ObjectDataView인지 확인합니다.

napi_strict_equals

추가된 버전: v8.0.0

N-API 버전: 1

C
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 객체가 같은지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 ECMAScript 언어 사양의 섹션 7.2.14에 정의된 엄격한 동등성 알고리즘의 호출을 나타냅니다.

napi_detach_arraybuffer

추가된 버전: v13.0.0, v12.16.0, v10.22.0

N-API 버전: 7

C
napi_status napi_detach_arraybuffer(napi_env env,
                                    napi_value arraybuffer)
  • [in] env: API가 호출되는 환경입니다.
  • [in] arraybuffer: 분리할 JavaScript ArrayBuffer입니다.

API가 성공하면 napi_ok를 반환합니다. 분리할 수 없는 ArrayBuffer가 전달되면 napi_detachable_arraybuffer_expected를 반환합니다.

일반적으로 ArrayBuffer는 이전에 분리된 경우 분리할 수 없습니다. 엔진은 ArrayBuffer를 분리할 수 있는지 여부에 추가 조건을 적용할 수 있습니다. 예를 들어, V8은 ArrayBuffer가 외부여야 합니다. 즉, napi_create_external_arraybuffer로 생성해야 합니다.

이 API는 ECMAScript 언어 사양의 섹션 24.1.1.3에 정의된 ArrayBuffer 분리 작업의 호출을 나타냅니다.

napi_is_detached_arraybuffer

추가된 버전: v13.3.0, v12.16.0, v10.22.0

N-API 버전: 7

C
napi_status napi_is_detached_arraybuffer(napi_env env,
                                         napi_value arraybuffer,
                                         bool* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] arraybuffer: 확인할 JavaScript ArrayBuffer입니다.
  • [out] result: arraybuffer가 분리되었는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

ArrayBuffer의 내부 데이터가 null이면 분리된 것으로 간주됩니다.

이 API는 ECMAScript 언어 사양의 섹션 24.1.1.2에 정의된 ArrayBuffer IsDetachedBuffer 작업의 호출을 나타냅니다.

JavaScript 속성 작업

Node-API는 JavaScript 객체에서 속성을 가져오고 설정하는 API 세트를 제공합니다. 이러한 유형 중 일부는 ECMAScript 언어 사양섹션 7에 문서화되어 있습니다.

JavaScript의 속성은 키와 값의 튜플로 표현됩니다. 근본적으로 Node-API의 모든 속성 키는 다음 형식 중 하나로 표현할 수 있습니다.

  • 이름 지정됨: 간단한 UTF8 인코딩 문자열
  • 정수 인덱스: uint32_t로 표현되는 인덱스 값
  • JavaScript 값: Node-API에서 napi_value로 표현됩니다. 이는 string, number 또는 symbol을 나타내는 napi_value일 수 있습니다.

Node-API 값은 napi_value 유형으로 표현됩니다. JavaScript 값이 필요한 모든 Node-API 호출은 napi_value를 사용합니다. 그러나 해당 napi_value가 API에서 예상하는 JavaScript 유형인지 확인하는 것은 호출자의 책임입니다.

이 섹션에 문서화된 API는 napi_value로 표현되는 임의의 JavaScript 객체에서 속성을 가져오고 설정하는 간단한 인터페이스를 제공합니다.

예를 들어 다음 JavaScript 코드 조각을 고려해 보세요.

js
const obj = {}
obj.myProp = 123

다음 코드 조각을 사용하여 Node-API 값으로 이와 동등한 작업을 수행할 수 있습니다.

C
napi_status status = napi_generic_failure;

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

// 123에 대한 napi_value 생성
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 코드 조각을 고려해 보세요.

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

다음 코드 조각을 사용하여 Node-API 값으로 이와 동등한 작업을 수행할 수 있습니다.

C
napi_status status = napi_generic_failure;

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

// 'hello'에 대한 napi_value 생성
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 코드 조각을 고려해 보세요.

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

다음은 Node-API 대응 항목과 대략적으로 동일합니다.

C
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를 고려해 보세요.

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

다음은 Node-API 대응 항목과 대략적으로 동일합니다.

C
napi_status status = napi_status_generic_failure;

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

// 123 및 456에 대한 napi_value 생성
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;

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

구조체

napi_property_attributes

[연혁]

버전변경 사항
v14.12.0napi_default_methodnapi_default_property 추가
C
typedef enum {
  napi_default = 0,
  napi_writable = 1 << 0,
  napi_enumerable = 1 << 1,
  napi_configurable = 1 << 2,

  // napi_define_class에서 정적 속성과
  // 인스턴스 속성을 구별하는 데 사용됩니다. napi_define_properties에서는 무시됩니다.
  napi_static = 1 << 10,

  // 클래스 메서드의 기본값입니다.
  napi_default_method = napi_writable | napi_configurable,

  // JS obj[prop]과 같은 객체 속성의 기본값입니다.
  napi_default_jsproperty = napi_writable |
                          napi_enumerable |
                          napi_configurable,
} napi_property_attributes;

napi_property_attributes는 JavaScript 객체에 설정된 속성의 동작을 제어하는 데 사용되는 플래그입니다. napi_static을 제외하고는 ECMAScript 언어 사양섹션 6.1.7.1에 나열된 속성에 해당합니다. 다음 비트 플래그 중 하나 이상일 수 있습니다.

  • napi_default: 속성에 명시적 속성이 설정되지 않았습니다. 기본적으로 속성은 읽기 전용이고 열거할 수 없으며 구성할 수 없습니다.
  • napi_writable: 속성을 쓸 수 있습니다.
  • napi_enumerable: 속성을 열거할 수 있습니다.
  • napi_configurable: 속성은 ECMAScript 언어 사양섹션 6.1.7.1에 정의된 대로 구성할 수 있습니다.
  • napi_static: 속성은 기본값인 인스턴스 속성과 반대로 클래스에서 정적 속성으로 정의됩니다. 이는 napi_define_class에서만 사용됩니다. napi_define_properties에서는 무시됩니다.
  • napi_default_method: JS 클래스의 메서드와 마찬가지로 속성을 구성하고 쓸 수 있지만 열거할 수는 없습니다.
  • napi_default_jsproperty: JavaScript에서 할당을 통해 설정된 속성과 마찬가지로 속성을 쓰고, 열거하고, 구성할 수 있습니다.

napi_property_descriptor

C
typedef struct {
  // utf8name 또는 name 중 하나는 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: 속성의 키로 사용할 JavaScript 문자열 또는 심볼을 가리키는 선택적 napi_value입니다. 속성에 대해 utf8name 또는 name 중 하나를 제공해야 합니다.
  • value: 속성이 데이터 속성인 경우 속성의 get 액세스에 의해 검색되는 값입니다. 이것이 전달되면 getter, setter, methoddataNULL로 설정합니다(이러한 멤버는 사용되지 않으므로).
  • getter: 속성에 대한 get 액세스가 수행될 때 호출할 함수입니다. 이것이 전달되면 valuemethodNULL로 설정합니다(이러한 멤버는 사용되지 않으므로). 주어진 함수는 JavaScript 코드에서 속성에 액세스하거나 Node-API 호출을 사용하여 속성에 대한 get이 수행될 때 런타임에 의해 암시적으로 호출됩니다. napi_callback에서 자세한 내용을 제공합니다.
  • setter: 속성에 대한 set 액세스가 수행될 때 호출할 함수입니다. 이것이 전달되면 valuemethodNULL로 설정합니다(이러한 멤버는 사용되지 않으므로). 주어진 함수는 JavaScript 코드에서 속성이 설정되거나 Node-API 호출을 사용하여 속성에 대한 set이 수행될 때 런타임에 의해 암시적으로 호출됩니다. napi_callback에서 자세한 내용을 제공합니다.
  • method: 속성 설명자 객체의 value 속성을 method로 표현되는 JavaScript 함수로 만들려면 이것을 설정합니다. 이것이 전달되면 value, gettersetterNULL로 설정합니다(이러한 멤버는 사용되지 않으므로). napi_callback에서 자세한 내용을 제공합니다.
  • attributes: 특정 속성과 관련된 속성입니다. napi_property_attributes를 참조하십시오.
  • data: 이 함수가 호출될 경우 method, gettersetter에 전달되는 콜백 데이터입니다.

함수

napi_get_property_names

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_property_names(napi_env env,
                                    napi_value object,
                                    napi_value* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 속성을 검색할 객체입니다.
  • [out] result: 객체의 속성 이름을 나타내는 JavaScript 값의 배열을 나타내는 napi_value입니다. API는 napi_get_array_lengthnapi_get_element를 사용하여 result를 반복하는 데 사용할 수 있습니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 object의 열거 가능한 속성의 이름을 문자열 배열로 반환합니다. 키가 심볼인 object의 속성은 포함되지 않습니다.

napi_get_all_property_names

추가된 버전: v13.7.0, v12.17.0, v10.20.0

N-API 버전: 6

C
napi_get_all_property_names(napi_env env,
                            napi_value object,
                            napi_key_collection_mode key_mode,
                            napi_key_filter key_filter,
                            napi_key_conversion key_conversion,
                            napi_value* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 속성을 검색할 객체입니다.
  • [in] key_mode: 프로토타입 속성도 검색할지 여부입니다.
  • [in] key_filter: 검색할 속성(열거 가능/읽기 가능/쓰기 가능)입니다.
  • [in] key_conversion: 번호가 매겨진 속성 키를 문자열로 변환할지 여부입니다.
  • [out] result: 객체의 속성 이름을 나타내는 JavaScript 값의 배열을 나타내는 napi_value입니다. napi_get_array_lengthnapi_get_element를 사용하여 result를 반복할 수 있습니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 이 객체에서 사용 가능한 속성의 이름을 포함하는 배열을 반환합니다.

napi_set_property

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_set_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value value);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 속성을 설정할 객체입니다.
  • [in] key: 설정할 속성의 이름입니다.
  • [in] value: 속성 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object에 속성을 설정합니다.

napi_get_property

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 속성을 가져올 객체입니다.
  • [in] key: 가져올 속성의 이름입니다.
  • [out] result: 속성의 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object에서 요청된 속성을 가져옵니다.

napi_has_property

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_has_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              bool* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 쿼리할 객체입니다.
  • [in] key: 존재 여부를 확인할 속성의 이름입니다.
  • [out] result: 객체에 속성이 존재하는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object에 명명된 속성이 있는지 확인합니다.

napi_delete_property

추가된 버전: v8.2.0

N-API 버전: 1

C
napi_status napi_delete_property(napi_env env,
                                 napi_value object,
                                 napi_value key,
                                 bool* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 쿼리할 객체입니다.
  • [in] key: 삭제할 속성의 이름입니다.
  • [out] result: 속성 삭제가 성공했는지 여부입니다. resultNULL을 전달하여 선택적으로 무시할 수 있습니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 object에서 key 자체 속성을 삭제하려고 시도합니다.

napi_has_own_property

추가된 버전: v8.2.0

N-API 버전: 1

C
napi_status napi_has_own_property(napi_env env,
                                  napi_value object,
                                  napi_value key,
                                  bool* result);
  • [in] env: Node-API 호출이 호출된 환경입니다.
  • [in] object: 쿼리할 객체입니다.
  • [in] key: 존재하는지 확인할 고유 속성의 이름입니다.
  • [out] result: 객체에 고유 속성이 존재하는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object에 명명된 고유 속성이 있는지 확인합니다. keystring 또는 symbol이어야 하며 그렇지 않으면 오류가 발생합니다. Node-API는 데이터 유형 간에 변환을 수행하지 않습니다.

napi_set_named_property

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value);
  • [in] env: Node-API 호출이 호출된 환경입니다.
  • [in] object: 속성을 설정할 객체입니다.
  • [in] utf8Name: 설정할 속성의 이름입니다.
  • [in] value: 속성 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드는 utf8Name으로 전달된 문자열에서 생성된 napi_value를 사용하여 napi_set_property를 호출하는 것과 같습니다.

napi_get_named_property

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value* result);
  • [in] env: Node-API 호출이 호출된 환경입니다.
  • [in] object: 속성을 검색할 객체입니다.
  • [in] utf8Name: 가져올 속성의 이름입니다.
  • [out] result: 속성의 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드는 utf8Name으로 전달된 문자열에서 생성된 napi_value를 사용하여 napi_get_property를 호출하는 것과 같습니다.

napi_has_named_property

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_has_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    bool* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 쿼리할 객체입니다.
  • [in] utf8Name: 확인하려는 속성의 이름입니다.
  • [out] result: 객체에 속성이 존재하는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드는 utf8Name으로 전달된 문자열에서 생성된 napi_valuenapi_has_property를 호출하는 것과 같습니다.

napi_set_element

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_set_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value value);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 속성을 설정할 객체입니다.
  • [in] index: 설정할 속성의 인덱스입니다.
  • [in] value: 속성 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object에 요소를 설정합니다.

napi_get_element

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 속성을 검색할 객체입니다.
  • [in] index: 가져올 속성의 인덱스입니다.
  • [out] result: 속성 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 요청된 인덱스에서 요소를 가져옵니다.

napi_has_element

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_has_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             bool* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 쿼리할 객체입니다.
  • [in] index: 확인하려는 속성의 인덱스입니다.
  • [out] result: 객체에 속성이 존재하는지 여부입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 전달된 Object에 요청된 인덱스에 요소가 있는지 여부를 반환합니다.

napi_delete_element

추가된 버전: v8.2.0

N-API 버전: 1

C
napi_status napi_delete_element(napi_env env,
                                napi_value object,
                                uint32_t index,
                                bool* result);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 쿼리할 객체입니다.
  • [in] index: 삭제할 속성의 인덱스입니다.
  • [out] result: 요소 삭제 성공 여부입니다. result는 선택적으로 NULL을 전달하여 무시할 수 있습니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 object에서 지정된 index를 삭제하려고 시도합니다.

napi_define_properties

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_define_properties(napi_env env,
                                   napi_value object,
                                   size_t property_count,
                                   const napi_property_descriptor* properties);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 속성을 검색할 객체입니다.
  • [in] property_count: properties 배열의 요소 수입니다.
  • [in] properties: 속성 설명자 배열입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드를 사용하면 지정된 객체에 여러 속성을 효율적으로 정의할 수 있습니다. 속성은 속성 설명자를 사용하여 정의됩니다(napi_property_descriptor 참조). 이러한 속성 설명자의 배열이 주어지면 이 API는 DefineOwnProperty()(ECMA-262 사양의 섹션 9.1.6에 설명됨)에 정의된 대로 한 번에 하나씩 객체에 속성을 설정합니다.

napi_object_freeze

추가된 버전: v14.14.0, v12.20.0

N-API 버전: 8

C
napi_status napi_object_freeze(napi_env env,
                               napi_value object);
  • [in] env: Node-API 호출이 실행되는 환경입니다.
  • [in] object: 고정할 객체입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드는 지정된 객체를 고정합니다. 이렇게 하면 새 속성이 추가되지 않고, 기존 속성이 제거되지 않으며, 기존 속성의 열거 가능성, 구성 가능성 또는 쓰기 가능성이 변경되지 않고, 기존 속성의 값이 변경되지 않습니다. 또한 객체의 프로토타입이 변경되는 것을 방지합니다. 이는 ECMA-262 사양의 섹션 19.1.2.6에 설명되어 있습니다.

napi_object_seal

추가된 버전: v14.14.0, v12.20.0

N-API 버전: 8

C
napi_status napi_object_seal(napi_env env,
                             napi_value object);
  • [in] env: Node-API 호출이 호출되는 환경입니다.
  • [in] object: 봉인할 객체입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드는 주어진 객체를 봉인합니다. 이렇게 하면 새 속성이 추가되는 것을 막고 모든 기존 속성을 구성 불가능으로 표시합니다. 이는 ECMA-262 사양의 섹션 19.1.2.20에 설명되어 있습니다.

JavaScript 함수 작업

Node-API는 JavaScript 코드가 네이티브 코드로 다시 호출될 수 있도록 하는 API 세트를 제공합니다. 네이티브 코드로 다시 호출하는 기능을 지원하는 Node-API는 napi_callback 유형으로 표현되는 콜백 함수를 사용합니다. JavaScript VM이 네이티브 코드로 다시 호출하면 제공된 napi_callback 함수가 호출됩니다. 이 섹션에 설명된 API를 통해 콜백 함수는 다음을 수행할 수 있습니다.

  • 콜백이 호출된 컨텍스트에 대한 정보를 가져옵니다.
  • 콜백에 전달된 인수를 가져옵니다.
  • 콜백에서 napi_value를 반환합니다.

또한 Node-API는 네이티브 코드에서 JavaScript 함수를 호출할 수 있도록 하는 함수 세트를 제공합니다. 함수를 일반 JavaScript 함수 호출처럼 호출하거나 생성자 함수처럼 호출할 수 있습니다.

napi_property_descriptor 항목의 data 필드를 통해 이 API에 전달되는 NULL이 아닌 데이터는 object와 연결될 수 있으며 object와 데이터를 napi_add_finalizer에 전달하여 object가 가비지 수집될 때마다 해제할 수 있습니다.

napi_call_function

추가된 버전: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_call_function(napi_env env,
                                           napi_value recv,
                                           napi_value func,
                                           size_t argc,
                                           const napi_value* argv,
                                           napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] recv: 호출된 함수에 전달된 this 값입니다.
  • [in] func: 호출할 JavaScript 함수를 나타내는 napi_value입니다.
  • [in] argc: argv 배열의 요소 수입니다.
  • [in] argv: 함수에 인수로 전달된 JavaScript 값을 나타내는 napi_values 배열입니다.
  • [out] result: 반환된 JavaScript 객체를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드를 사용하면 네이티브 추가 기능에서 JavaScript 함수 객체를 호출할 수 있습니다. 이것은 추가 기능의 네이티브 코드 에서 JavaScript 다시 호출하는 기본 메커니즘입니다. 비동기 작업 후 JavaScript로 호출하는 특수한 경우에는 napi_make_callback을 참조하십시오.

샘플 사용 사례는 다음과 같습니다. 다음 JavaScript 스니펫을 고려하십시오.

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

그런 다음 위의 함수는 다음 코드를 사용하여 네이티브 추가 기능에서 호출할 수 있습니다.

C
// 전역 객체에서 "AddTwo"라는 함수를 가져옵니다.
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;

// 결과를 네이티브 유형으로 다시 변환합니다.
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;

napi_create_function

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_create_function(napi_env env,
                                 const char* utf8name,
                                 size_t length,
                                 napi_callback cb,
                                 void* data,
                                 napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] utf8Name: UTF8로 인코딩된 함수의 선택적 이름입니다. JavaScript 내에서 새 함수 객체의 name 속성으로 표시됩니다.
  • [in] length: utf8name의 바이트 길이이거나 null로 끝나는 경우 NAPI_AUTO_LENGTH입니다.
  • [in] cb: 이 함수 객체가 호출될 때 호출되어야 하는 네이티브 함수입니다. napi_callback에서 자세한 내용을 제공합니다.
  • [in] data: 사용자 제공 데이터 컨텍스트입니다. 나중에 호출될 때 함수로 다시 전달됩니다.
  • [out] result: 새로 생성된 함수에 대한 JavaScript 함수 객체를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API를 사용하면 애드온 작성자가 네이티브 코드에서 함수 객체를 만들 수 있습니다. 이것은 JavaScript 에서 애드온의 네이티브 코드로 호출을 허용하는 주요 메커니즘입니다.

새로 생성된 함수는 이 호출 후 스크립트에서 자동으로 표시되지 않습니다. 대신, 스크립트에서 함수에 접근할 수 있도록 JavaScript에 표시되는 모든 객체에 속성을 명시적으로 설정해야 합니다.

애드온의 모듈 내보내기의 일부로 함수를 노출하려면 내보내기 객체에 새로 생성된 함수를 설정합니다. 샘플 모듈은 다음과 같습니다.

C
napi_value SayHello(napi_env env, napi_callback_info info) {
  printf("Hello\n");
  return NULL;
}

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;

  napi_value fn;
  status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "sayHello", fn);
  if (status != napi_ok) return NULL;

  return exports;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

위의 코드를 감안할 때, JavaScript에서 다음과 같이 애드온을 사용할 수 있습니다.

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

require()에 전달된 문자열은 .node 파일을 만드는 데 사용되는 binding.gyp의 대상 이름입니다.

data 매개변수를 통해 이 API에 전달되는 NULL이 아닌 모든 데이터는 결과 JavaScript 함수( result 매개변수에서 반환됨)와 연결될 수 있으며, JavaScript 함수와 데이터를 napi_add_finalizer에 전달하여 함수가 가비지 수집될 때마다 해제할 수 있습니다.

JavaScript Function은 ECMAScript 언어 사양의 섹션 19.2에 설명되어 있습니다.

napi_get_cb_info

추가 버전: v8.0.0

N-API 버전: 1

C
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 배열의 길이를 지정하고 실제 인수의 개수를 받습니다. NULL을 전달하여 argc를 선택적으로 무시할 수 있습니다.
  • [out] argv: 인수가 복사될 napi_value의 C 배열입니다. 제공된 개수보다 많은 인수가 있는 경우 요청된 수의 인수만 복사됩니다. 주장된 것보다 적은 인수가 제공된 경우, argv의 나머지는 undefined를 나타내는 napi_value 값으로 채워집니다. NULL을 전달하여 argv를 선택적으로 무시할 수 있습니다.
  • [out] thisArg: 호출에 대한 JavaScript this 인수를 받습니다. NULL을 전달하여 thisArg를 선택적으로 무시할 수 있습니다.
  • [out] data: 콜백에 대한 데이터 포인터를 받습니다. NULL을 전달하여 data를 선택적으로 무시할 수 있습니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드는 콜백 함수 내에서 주어진 콜백 정보에서 인수 및 this 포인터와 같은 호출에 대한 세부 정보를 검색하는 데 사용됩니다.

napi_get_new_target

추가 버전: v8.6.0

N-API 버전: 1

C
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입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 생성자 호출의 new.target을 반환합니다. 현재 콜백이 생성자 호출이 아니면 결과는 NULL입니다.

napi_new_instance

추가됨: v8.0.0

N-API 버전: 1

C
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: 생성자로 호출될 JavaScript 함수를 나타내는 napi_value입니다.
  • [in] argc: argv 배열의 요소 개수입니다.
  • [in] argv: 생성자에 대한 인수를 나타내는 napi_value 형식의 JavaScript 값 배열입니다. argc가 0인 경우 이 매개변수는 NULL을 전달하여 생략할 수 있습니다.
  • [out] result: 반환된 JavaScript 객체를 나타내는 napi_value입니다. 이 경우 생성된 객체입니다.

이 메서드는 객체의 생성자를 나타내는 주어진 napi_value를 사용하여 새 JavaScript 값을 인스턴스화하는 데 사용됩니다. 예를 들어 다음 스니펫을 살펴보겠습니다.

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

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

다음 스니펫을 사용하여 Node-API에서 근사화할 수 있습니다.

C
// 생성자 함수 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);

API가 성공하면 napi_ok를 반환합니다.

객체 래핑

Node-API는 C++ 클래스 및 인스턴스를 "래핑"하여 JavaScript에서 클래스 생성자 및 메서드를 호출할 수 있도록 하는 방법을 제공합니다.

래핑된 객체의 경우 클래스 프로토타입에서 호출되는 함수와 클래스 인스턴스에서 호출되는 함수를 구별하기 어려울 수 있습니다. 이 문제를 해결하는 데 사용되는 일반적인 패턴은 나중에 instanceof 검사를 위해 클래스 생성자에 대한 영구 참조를 저장하는 것입니다.

C
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 {
  // 그렇지 않으면...
}

더 이상 필요하지 않으면 참조를 해제해야 합니다.

JavaScript 객체가 특정 네이티브 유형에 대한 래퍼인지 확인하기에 napi_instanceof()가 충분하지 않은 경우가 있습니다. 이는 특히 래핑된 JavaScript 객체가 프로토타입 메서드의 this 값으로가 아니라 정적 메서드를 통해 애드온으로 다시 전달될 때 그렇습니다. 이러한 경우 잘못 래핑 해제될 가능성이 있습니다.

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

// `openDatabase()`는 네이티브 데이터베이스를 래핑하는 JavaScript 객체를 반환합니다.
// 처리합니다.
const dbHandle = myAddon.openDatabase()

// `query()`는 네이티브 쿼리를 래핑하는 JavaScript 객체를 반환합니다.
// 처리합니다.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')

// 아래 줄에 의도하지 않은 오류가 있습니다. `myAddon.queryHasRecords()`의 첫 번째 매개변수는
// 쿼리 처리(`query`)가 아닌 데이터베이스 처리(`dbHandle`)여야 하므로 while 루프의 올바른 조건은
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
  // 레코드 검색
}

위의 예에서 myAddon.queryHasRecords()는 두 개의 인수를 허용하는 메서드입니다. 첫 번째는 데이터베이스 처리이고 두 번째는 쿼리 처리입니다. 내부적으로는 첫 번째 인수를 래핑 해제하고 결과 포인터를 네이티브 데이터베이스 처리로 캐스팅합니다. 그런 다음 두 번째 인수를 래핑 해제하고 결과 포인터를 쿼리 처리로 캐스팅합니다. 인수가 잘못된 순서로 전달되면 캐스트가 작동하지만, 기본 데이터베이스 작업이 실패하거나 유효하지 않은 메모리 액세스를 유발할 가능성이 큽니다.

첫 번째 인수에서 검색된 포인터가 실제로 데이터베이스 처리에 대한 포인터이고 유사하게 두 번째 인수에서 검색된 포인터가 실제로 쿼리 처리에 대한 포인터인지 확인하려면 queryHasRecords()의 구현이 유형 유효성 검사를 수행해야 합니다. 데이터베이스 처리가 인스턴스화된 JavaScript 클래스 생성자와 napi_ref에 인스턴스화된 쿼리 처리의 생성자를 유지하면 napi_instanceof()를 사용하여 queryHashRecords()에 전달된 인스턴스가 실제로 올바른 유형인지 확인할 수 있으므로 도움이 됩니다.

불행히도 napi_instanceof()는 프로토타입 조작에 대한 보호를 제공하지 않습니다. 예를 들어 데이터베이스 처리 인스턴스의 프로토타입을 쿼리 처리 인스턴스에 대한 생성자의 프로토타입으로 설정할 수 있습니다. 이 경우 데이터베이스 처리 인스턴스는 쿼리 처리 인스턴스로 나타날 수 있으며 쿼리 처리 인스턴스에 대한 napi_instanceof() 테스트를 통과하면서도 데이터베이스 처리 포인터를 포함합니다.

이를 위해 Node-API는 유형 태깅 기능을 제공합니다.

유형 태그는 애드온에 고유한 128비트 정수입니다. Node-API는 유형 태그를 저장하기 위한 napi_type_tag 구조를 제공합니다. 이러한 값이 JavaScript 객체 또는 napi_value에 저장된 외부 값과 함께 napi_type_tag_object()에 전달되면 JavaScript 객체는 유형 태그로 "표시"됩니다. "표시"는 JavaScript 측에서 보이지 않습니다. JavaScript 객체가 네이티브 바인딩에 도착하면 napi_check_object_type_tag()를 원래 유형 태그와 함께 사용하여 JavaScript 객체가 이전에 유형 태그로 "표시"되었는지 확인할 수 있습니다. 이렇게 하면 프로토타입 조작 및 애드온 언로드/재로딩을 견딜 수 있으므로 napi_instanceof()에서 제공할 수 있는 것보다 충실도가 높은 유형 검사 기능이 생성됩니다.

위의 예시를 계속해서, 다음 골격 애드온 구현은 napi_type_tag_object()napi_check_object_type_tag()의 사용법을 보여줍니다.

C
// 이 값은 데이터베이스 처리의 유형 태그입니다. 명령
//
//   uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// 구조체를 초기화하는 데 사용할 두 개의 값을 얻는 데 사용할 수 있습니다.
static const napi_type_tag DatabaseHandleTypeTag = {
  0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};

// 이 값은 쿼리 처리의 유형 태그입니다.
static const napi_type_tag QueryHandleTypeTag = {
  0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};

static napi_value
openDatabase(napi_env env, napi_callback_info info) {
  napi_status status;
  napi_value result;

  // 데이터베이스 처리로 이어지는 기본 작업을 수행합니다.
  DatabaseHandle* dbHandle = open_database();

  // 비어 있는 새 JS 객체를 만듭니다.
  status = napi_create_object(env, &result);
  if (status != napi_ok) return NULL;

  // 객체에 `DatabaseHandle`에 대한 포인터가 있음을 나타내도록 객체를 태그합니다.
  status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
  if (status != napi_ok) return NULL;

  // JS 객체 내부에 `DatabaseHandle` 구조체에 대한 포인터를 저장합니다.
  status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
  if (status != napi_ok) return NULL;

  return result;
}

// 나중에 데이터베이스 처리인 JavaScript 객체를 수신하면
// `napi_check_object_type_tag()`를 사용하여 실제로 그러한 처리인지 확인할 수 있습니다.

static napi_value
query(napi_env env, napi_callback_info info) {
  napi_status status;
  size_t argc = 2;
  napi_value argv[2];
  bool is_db_handle;

  status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
  if (status != napi_ok) return NULL;

  // 첫 번째 매개변수로 전달된 객체에 이전에 적용된 태그가 있는지 확인합니다.
  status = napi_check_object_type_tag(env,
                                      argv[0],
                                      &DatabaseHandleTypeTag,
                                      &is_db_handle);
  if (status != napi_ok) return NULL;

  // 그렇지 않은 경우 `TypeError`를 발생시킵니다.
  if (!is_db_handle) {
    // TypeError를 발생시킵니다.
    return NULL;
  }
}

napi_define_class

추가 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_define_class(napi_env env,
                              const char* utf8name,
                              size_t length,
                              napi_callback constructor,
                              void* data,
                              size_t property_count,
                              const napi_property_descriptor* properties,
                              napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] utf8name: JavaScript 생성자 함수의 이름입니다. 명확성을 위해 C++ 클래스를 래핑할 때 C++ 클래스 이름을 사용하는 것이 좋습니다.
  • [in] length: utf8name의 바이트 단위 길이입니다. null로 종료되는 경우 NAPI_AUTO_LENGTH입니다.
  • [in] constructor: 클래스 인스턴스 생성을 처리하는 콜백 함수입니다. C++ 클래스를 래핑할 때 이 메서드는 napi_callback 서명이 있는 정적 멤버여야 합니다. C++ 클래스 생성자는 사용할 수 없습니다. napi_callback에서 자세한 내용을 제공합니다.
  • [in] data: 콜백 정보의 data 속성으로 생성자 콜백에 전달될 선택적 데이터입니다.
  • [in] property_count: properties 배열 인수의 항목 수입니다.
  • [in] properties: 클래스에 대한 정적 및 인스턴스 데이터 속성, 접근자 및 메서드를 설명하는 속성 설명자의 배열입니다. napi_property_descriptor를 참조하십시오.
  • [out] result: 클래스에 대한 생성자 함수를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

다음을 포함하는 JavaScript 클래스를 정의합니다.

  • 클래스 이름이 있는 JavaScript 생성자 함수입니다. 해당 C++ 클래스를 래핑할 때 constructor를 통해 전달된 콜백을 사용하여 새로운 C++ 클래스 인스턴스를 인스턴스화할 수 있습니다. 그런 다음 napi_wrap을 사용하여 생성되는 JavaScript 객체 인스턴스 내부에 배치할 수 있습니다.
  • 구현에서 해당 C++ 클래스의 정적 데이터 속성, 접근자 및 메서드를 호출할 수 있는 생성자 함수의 속성입니다( napi_static 특성이 있는 속성 설명자로 정의됨).
  • 생성자 함수의 prototype 객체 속성입니다. C++ 클래스를 래핑할 때 C++ 클래스의 비정적 데이터 속성, 접근자 및 메서드는 napi_unwrap을 사용하여 JavaScript 객체 인스턴스 내부에 배치된 C++ 클래스 인스턴스를 검색한 후 napi_static 특성 없이 속성 설명자에 제공된 정적 함수에서 호출할 수 있습니다.

C++ 클래스를 래핑할 때 constructor를 통해 전달된 C++ 생성자 콜백은 실제 클래스 생성자를 호출한 다음 새로운 C++ 인스턴스를 JavaScript 객체로 래핑하고 래퍼 객체를 반환하는 클래스의 정적 메서드여야 합니다. 자세한 내용은 napi_wrap을 참조하십시오.

napi_define_class에서 반환된 JavaScript 생성자 함수는 종종 저장되고 나중에 네이티브 코드에서 클래스의 새 인스턴스를 생성하거나 제공된 값이 클래스의 인스턴스인지 확인하는 데 사용됩니다. 이 경우 함수 값이 가비지 수집되지 않도록 하려면 napi_create_reference를 사용하여 강력한 영구 참조를 만들어 참조 수가 >= 1로 유지되도록 할 수 있습니다.

data 매개변수 또는 napi_property_descriptor 배열 항목의 data 필드를 통해 이 API에 전달되는 NULL이 아닌 모든 데이터는 결과 JavaScript 생성자( result 매개변수로 반환됨)와 연결될 수 있으며 JavaScript 함수와 데이터를 모두 napi_add_finalizer에 전달하여 클래스가 가비지 수집될 때마다 해제될 수 있습니다.

napi_wrap

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_wrap(napi_env env,
                      napi_value js_object,
                      void* native_object,
                      napi_finalize finalize_cb,
                      void* finalize_hint,
                      napi_ref* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] js_object: 네이티브 객체를 감쌀 JavaScript 객체입니다.
  • [in] native_object: JavaScript 객체로 감쌀 네이티브 인스턴스입니다.
  • [in] finalize_cb: JavaScript 객체가 가비지 수집될 때 네이티브 인스턴스를 해제하는 데 사용할 수 있는 선택적 네이티브 콜백입니다. napi_finalize에서 더 자세한 내용을 제공합니다.
  • [in] finalize_hint: 최종화 콜백으로 전달되는 선택적 컨텍스트 힌트입니다.
  • [out] result: 래핑된 객체에 대한 선택적 참조입니다.

API가 성공하면 napi_ok를 반환합니다.

JavaScript 객체에 네이티브 인스턴스를 래핑합니다. 네이티브 인스턴스는 나중에 napi_unwrap()을 사용하여 검색할 수 있습니다.

JavaScript 코드가 napi_define_class()를 사용하여 정의된 클래스의 생성자를 호출하면 생성자에 대한 napi_callback이 호출됩니다. 네이티브 클래스의 인스턴스를 생성한 후 콜백은 생성자 콜백에 대한 this 인수 인 이미 생성된 JavaScript 객체에 새로 생성된 인스턴스를 래핑하기 위해 napi_wrap()을 호출해야 합니다. (해당 this 객체는 생성자 함수의 prototype에서 생성되었으므로 이미 모든 인스턴스 속성 및 메서드 정의를 가지고 있습니다.)

일반적으로 클래스 인스턴스를 래핑할 때 최종화 콜백은 최종화 콜백에 대한 data 인수로 수신되는 네이티브 인스턴스를 단순히 삭제하는 콜백을 제공해야 합니다.

선택적으로 반환되는 참조는 처음에 0의 참조 횟수를 갖는 약한 참조입니다. 일반적으로 이 참조 횟수는 인스턴스가 유효하게 유지되어야 하는 비동기 작업 중에 일시적으로 증가합니다.

주의: 선택적으로 반환되는 참조(획득된 경우)는 최종화 콜백 호출에 대한 응답으로만 napi_delete_reference를 통해 삭제해야 합니다. 그 전에 삭제하면 최종화 콜백이 호출되지 않을 수 있습니다. 따라서 참조를 얻을 때 참조의 올바른 폐기를 활성화하려면 최종화 콜백도 필요합니다.

최종자 콜백은 지연될 수 있으며, 이로 인해 객체가 가비지 수집되었고(약한 참조가 유효하지 않음) 최종자가 아직 호출되지 않은 창이 남습니다. napi_wrap()에서 반환된 약한 참조에 대해 napi_get_reference_value()를 사용하는 경우에도 빈 결과를 처리해야 합니다.

객체에서 napi_wrap()을 두 번째로 호출하면 오류가 반환됩니다. 객체와 다른 네이티브 인스턴스를 연결하려면 먼저 napi_remove_wrap()을 사용하십시오.

napi_unwrap

추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_unwrap(napi_env env,
                        napi_value js_object,
                        void** result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] js_object: 네이티브 인스턴스와 연결된 객체입니다.
  • [out] result: 래핑된 네이티브 인스턴스에 대한 포인터입니다.

API가 성공하면 napi_ok를 반환합니다.

napi_wrap()을 사용하여 이전에 JavaScript 객체로 래핑된 네이티브 인스턴스를 검색합니다.

JavaScript 코드가 클래스에서 메서드 또는 속성 접근자를 호출하면 해당 napi_callback이 호출됩니다. 콜백이 인스턴스 메서드 또는 접근자에 대한 것이면 콜백에 대한 this 인수는 래퍼 객체입니다. 호출 대상인 래핑된 C++ 인스턴스는 래퍼 객체에서 napi_unwrap()을 호출하여 얻을 수 있습니다.

napi_remove_wrap

추가됨: v8.5.0

N-API 버전: 1

C
napi_status napi_remove_wrap(napi_env env,
                             napi_value js_object,
                             void** result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] js_object: 네이티브 인스턴스와 연결된 객체입니다.
  • [out] result: 래핑된 네이티브 인스턴스에 대한 포인터입니다.

API가 성공하면 napi_ok를 반환합니다.

napi_wrap()을 사용하여 이전에 JavaScript 객체 js_object로 래핑된 네이티브 인스턴스를 검색하고 래핑을 제거합니다. finalize 콜백이 래핑과 연결된 경우 JavaScript 객체가 가비지 수집될 때 더 이상 호출되지 않습니다.

napi_type_tag_object

추가됨: v14.8.0, v12.19.0

N-API 버전: 8

C
napi_status napi_type_tag_object(napi_env env,
                                 napi_value js_object,
                                 const napi_type_tag* type_tag);
  • [in] env: API가 호출되는 환경입니다.
  • [in] js_object: 표시할 JavaScript 객체 또는 외부입니다.
  • [in] type_tag: 객체가 표시될 태그입니다.

API가 성공하면 napi_ok를 반환합니다.

type_tag 포인터의 값을 JavaScript 객체 또는 외부와 연결합니다. 그런 다음 napi_check_object_type_tag()를 사용하여 객체에 첨부된 태그를 애드온이 소유한 태그와 비교하여 객체의 유형이 올바른지 확인할 수 있습니다.

객체에 이미 연결된 유형 태그가 있는 경우 이 API는 napi_invalid_arg를 반환합니다.

napi_check_object_type_tag

추가된 버전: v14.8.0, v12.19.0

N-API 버전: 8

C
napi_status napi_check_object_type_tag(napi_env env,
                                       napi_value js_object,
                                       const napi_type_tag* type_tag,
                                       bool* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] js_object: 검사할 타입 태그가 있는 JavaScript 객체 또는 외부 객체입니다.
  • [in] type_tag: 객체에서 찾은 태그와 비교할 태그입니다.
  • [out] result: 주어진 타입 태그가 객체의 타입 태그와 일치하는지 여부입니다. 객체에서 타입 태그를 찾지 못한 경우에도 false가 반환됩니다.

API가 성공하면 napi_ok를 반환합니다.

type_tag로 주어진 포인터를 js_object에서 찾을 수 있는 포인터와 비교합니다. js_object에서 태그를 찾지 못하거나 태그가 발견되었지만 type_tag와 일치하지 않으면 resultfalse로 설정됩니다. 태그가 발견되고 type_tag와 일치하면 resulttrue로 설정됩니다.

napi_add_finalizer

추가된 버전: v8.0.0

N-API 버전: 5

C
napi_status napi_add_finalizer(napi_env env,
                               napi_value js_object,
                               void* finalize_data,
                               node_api_basic_finalize finalize_cb,
                               void* finalize_hint,
                               napi_ref* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] js_object: 네이티브 데이터가 연결될 JavaScript 객체입니다.
  • [in] finalize_data: finalize_cb에 전달할 선택적 데이터입니다.
  • [in] finalize_cb: JavaScript 객체가 가비지 수집될 때 네이티브 데이터를 해제하는 데 사용될 네이티브 콜백입니다. napi_finalize에서 자세한 내용을 제공합니다.
  • [in] finalize_hint: finalize 콜백에 전달되는 선택적 컨텍스트 힌트입니다.
  • [out] result: JavaScript 객체에 대한 선택적 참조입니다.

API가 성공하면 napi_ok를 반환합니다.

js_object의 JavaScript 객체가 가비지 수집될 때 호출되는 napi_finalize 콜백을 추가합니다.

이 API는 단일 JavaScript 객체에서 여러 번 호출할 수 있습니다.

주의: 선택적으로 반환된 참조(얻은 경우)는 finalize 콜백 호출에 대한 응답으로만 napi_delete_reference를 통해 삭제해야 합니다. 그 전에 삭제하면 finalize 콜백이 호출되지 않을 수 있습니다. 따라서 참조를 얻을 때 참조를 올바르게 처리하려면 finalize 콜백도 필요합니다.

node_api_post_finalizer

추가된 버전: v21.0.0, v20.10.0, v18.19.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

C
napi_status node_api_post_finalizer(node_api_basic_env env,
                                    napi_finalize finalize_cb,
                                    void* finalize_data,
                                    void* finalize_hint);
  • [in] env: API가 호출되는 환경입니다.
  • [in] finalize_cb: JavaScript 객체가 가비지 수집될 때 네이티브 데이터를 해제하는 데 사용될 네이티브 콜백입니다. napi_finalize에서 자세한 내용을 확인할 수 있습니다.
  • [in] finalize_data: finalize_cb에 전달될 선택적 데이터입니다.
  • [in] finalize_hint: finalize 콜백에 전달되는 선택적 컨텍스트 힌트입니다.

API가 성공하면 napi_ok를 반환합니다.

이벤트 루프에서 비동기적으로 호출될 napi_finalize 콜백을 예약합니다.

일반적으로 finalizer는 GC(가비지 수집기)가 객체를 수집하는 동안 호출됩니다. 이 시점에서 GC 상태의 변경을 일으킬 수 있는 Node-API 호출은 비활성화되며 Node.js가 충돌합니다.

node_api_post_finalizer는 애드온이 GC finalization 외부의 시점으로 이러한 Node-API 호출을 연기하도록 허용함으로써 이러한 제한을 해결하는 데 도움이 됩니다.

간단한 비동기 작업

애드온 모듈은 구현의 일부로 libuv에서 비동기 도우미를 활용해야 하는 경우가 많습니다. 이렇게 하면 작업을 비동기적으로 실행하도록 예약하여 메서드가 작업 완료 전에 반환될 수 있습니다. 이를 통해 Node.js 애플리케이션의 전체 실행을 차단하지 않도록 할 수 있습니다.

Node-API는 가장 일반적인 비동기 사용 사례를 다루는 이러한 지원 기능에 대한 ABI 안정적인 인터페이스를 제공합니다.

Node-API는 비동기 워커를 관리하는 데 사용되는 napi_async_work 구조를 정의합니다. 인스턴스는 napi_create_async_worknapi_delete_async_work를 사용하여 생성/삭제됩니다.

executecomplete 콜백은 실행기가 실행할 준비가 되었을 때와 작업을 완료했을 때 각각 호출되는 함수입니다.

execute 함수는 JavaScript 실행 또는 JavaScript 객체와의 상호 작용을 초래할 수 있는 Node-API 호출을 피해야 합니다. 대부분의 경우 Node-API 호출을 해야 하는 코드는 complete 콜백에서 수행해야 합니다. JavaScript를 실행할 가능성이 높으므로 실행 콜백에서 napi_env 매개변수를 사용하지 마십시오.

이러한 함수는 다음 인터페이스를 구현합니다.

C
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 매개변수는 napi_create_async_work 호출에 전달된 애드온 제공 void* 데이터입니다.

생성된 비동기 워커는 napi_queue_async_work 함수를 사용하여 실행을 위해 대기열에 넣을 수 있습니다.

C
napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

작업이 실행을 시작하기 전에 취소해야 하는 경우 napi_cancel_async_work를 사용할 수 있습니다.

napi_cancel_async_work를 호출한 후에는 complete 콜백이 napi_cancelled 상태 값으로 호출됩니다. 취소된 경우에도 complete 콜백 호출 전에 작업을 삭제해서는 안 됩니다.

napi_create_async_work

[기록]

버전변경 사항
v8.6.0async_resourceasync_resource_name 매개변수 추가.
v8.0.0추가됨: v8.0.0

N-API 버전: 1

C
napi_status napi_create_async_work(napi_env env,
                                   napi_value async_resource,
                                   napi_value async_resource_name,
                                   napi_async_execute_callback execute,
                                   napi_async_complete_callback complete,
                                   void* data,
                                   napi_async_work* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] async_resource: async_hooks init 후크에 전달될 비동기 작업과 관련된 선택적 객체입니다.
  • [in] async_resource_name: async_hooks API에서 노출되는 진단 정보에 제공되는 리소스 종류에 대한 식별자입니다.
  • [in] execute: 비동기적으로 로직을 실행하기 위해 호출해야 하는 네이티브 함수입니다. 주어진 함수는 워커 풀 스레드에서 호출되며 메인 이벤트 루프 스레드와 병렬로 실행할 수 있습니다.
  • [in] complete: 비동기 로직이 완료되거나 취소될 때 호출될 네이티브 함수입니다. 주어진 함수는 메인 이벤트 루프 스레드에서 호출됩니다. napi_async_complete_callback에서 더 자세한 내용을 제공합니다.
  • [in] data: 사용자 제공 데이터 컨텍스트입니다. 이는 execute 및 complete 함수에 다시 전달됩니다.
  • [out] result: 새로 생성된 비동기 작업에 대한 핸들인 napi_async_work*입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 비동기적으로 로직을 실행하는 데 사용되는 작업 객체를 할당합니다. 작업이 더 이상 필요하지 않으면 napi_delete_async_work를 사용하여 해제해야 합니다.

async_resource_name은 null로 끝나는 UTF-8 인코딩 문자열이어야 합니다.

async_resource_name 식별자는 사용자가 제공하며 수행 중인 비동기 작업 유형을 나타내야 합니다. 모듈 이름을 포함하는 등 식별자에 네임스페이스를 적용하는 것이 좋습니다. 자세한 내용은 async_hooks 문서를 참조하십시오.

napi_delete_async_work

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_delete_async_work(napi_env env,
                                   napi_async_work work);
  • [in] env: API가 호출된 환경입니다.
  • [in] work: napi_create_async_work 호출에서 반환된 핸들입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 이전에 할당된 작업 객체를 해제합니다.

보류 중인 JavaScript 예외가 있는 경우에도 이 API를 호출할 수 있습니다.

napi_queue_async_work

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);
  • [in] env: API가 호출된 환경입니다.
  • [in] work: napi_create_async_work 호출에서 반환된 핸들입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 이전에 할당된 작업을 실행되도록 스케줄링할 것을 요청합니다. 성공적으로 반환되면 동일한 napi_async_work 항목으로 이 API를 다시 호출해서는 안 되며, 그렇지 않으면 결과가 정의되지 않습니다.

napi_cancel_async_work

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_cancel_async_work(node_api_basic_env env,
                                   napi_async_work work);
  • [in] env: API가 호출된 환경입니다.
  • [in] work: napi_create_async_work 호출에서 반환된 핸들입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 아직 시작되지 않은 경우 대기 중인 작업을 취소합니다. 이미 실행이 시작된 경우에는 취소할 수 없으며 napi_generic_failure가 반환됩니다. 성공하면 complete 콜백이 napi_cancelled 상태 값으로 호출됩니다. 작업이 성공적으로 취소된 경우에도 complete 콜백 호출 전에 삭제해서는 안 됩니다.

보류 중인 JavaScript 예외가 있는 경우에도 이 API를 호출할 수 있습니다.

사용자 지정 비동기 작업

위의 간단한 비동기 작업 API는 모든 시나리오에 적합하지 않을 수 있습니다. 다른 비동기 메커니즘을 사용하는 경우 비동기 작업이 런타임에서 적절하게 추적되도록 하기 위해 다음 API가 필요합니다.

napi_async_init

추가된 버전: v8.6.0

N-API 버전: 1

C
napi_status napi_async_init(napi_env env,
                            napi_value async_resource,
                            napi_value async_resource_name,
                            napi_async_context* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] async_resource: 가능한 async_hooks init에 전달되고 async_hooks.executionAsyncResource()로 접근할 수 있는 비동기 작업과 관련된 객체입니다.
  • [in] async_resource_name: async_hooks API에서 노출되는 진단 정보에 제공되는 리소스 종류의 식별자입니다.
  • [out] result: 초기화된 비동기 컨텍스트입니다.

API가 성공하면 napi_ok를 반환합니다.

async_hooks 관련 API가 올바르게 작동하도록 하려면 async_resource 객체를 napi_async_destroy까지 유지해야 합니다. 이전 버전과의 ABI 호환성을 유지하기 위해 napi_async_context는 메모리 누수를 방지하기 위해 async_resource 객체에 대한 강력한 참조를 유지하지 않습니다. 그러나 napi_async_contextnapi_async_destroy에 의해 파괴되기 전에 JavaScript 엔진에 의해 async_resource가 가비지 컬렉션되는 경우, napi_open_callback_scopenapi_make_callback과 같은 napi_async_context 관련 API를 호출하면 AsyncLocalStorage API를 사용할 때 비동기 컨텍스트 손실과 같은 문제가 발생할 수 있습니다.

이전 버전과의 ABI 호환성을 유지하기 위해 async_resourceNULL을 전달해도 오류가 발생하지 않습니다. 그러나 이는 async_hooks initasync_hooks.executionAsyncResource()에서 바람직하지 않은 동작을 초래할 수 있으므로 권장되지 않습니다. 이제 리소스는 비동기 콜백 간의 연결을 제공하기 위해 기본 async_hooks 구현에 필요하기 때문입니다.

napi_async_destroy

추가된 버전: v8.6.0

N-API 버전: 1

C
napi_status napi_async_destroy(napi_env env,
                               napi_async_context async_context);
  • [in] env: API가 호출되는 환경입니다.
  • [in] async_context: 제거할 비동기 컨텍스트입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 보류 중인 JavaScript 예외가 있는 경우에도 호출할 수 있습니다.

napi_make_callback

[기록]

버전변경 사항
v8.6.0async_context 매개변수가 추가되었습니다.
v8.0.0추가된 버전: v8.0.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_make_callback(napi_env env,
                                           napi_async_context async_context,
                                           napi_value recv,
                                           napi_value func,
                                           size_t argc,
                                           const napi_value* argv,
                                           napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] async_context: 콜백을 호출하는 비동기 작업의 컨텍스트입니다. 일반적으로 napi_async_init에서 이전에 얻은 값이어야 합니다. 이전 버전과의 ABI 호환성을 유지하기 위해 async_context에 대해 NULL을 전달해도 오류가 발생하지 않습니다. 그러나 이렇게 하면 비동기 후크가 잘못 작동합니다. 잠재적인 문제로는 AsyncLocalStorage API를 사용할 때 비동기 컨텍스트 손실이 있습니다.
  • [in] recv: 호출된 함수에 전달되는 this 값입니다.
  • [in] func: 호출할 JavaScript 함수를 나타내는 napi_value입니다.
  • [in] argc: argv 배열의 요소 수입니다.
  • [in] argv: 함수의 인수를 나타내는 napi_value 형식의 JavaScript 값 배열입니다. argc가 0이면 이 매개변수는 NULL을 전달하여 생략할 수 있습니다.
  • [out] result: 반환된 JavaScript 객체를 나타내는 napi_value입니다.

API가 성공하면 napi_ok를 반환합니다.

이 메서드를 사용하면 네이티브 애드온에서 JavaScript 함수 객체를 호출할 수 있습니다. 이 API는 napi_call_function과 유사합니다. 그러나 비동기 작업에서 반환된 (스택에 다른 스크립트가 없는 경우) 네이티브 코드 에서 다시 JavaScript 호출하는 데 사용됩니다. 이는 node::MakeCallback에 대한 매우 간단한 래퍼입니다.

napi_async_complete_callback 내에서 napi_make_callback을 사용할 필요는 없습니다. 해당 상황에서는 콜백의 비동기 컨텍스트가 이미 설정되어 있으므로 napi_call_function을 직접 호출하는 것으로 충분합니다. napi_make_callback 함수는 napi_create_async_work를 사용하지 않는 사용자 정의 비동기 동작을 구현할 때 필요할 수 있습니다.

콜백 중에 JavaScript에서 마이크로태스크 큐에 예약된 모든 process.nextTick 또는 Promises는 C/C++로 다시 반환되기 전에 실행됩니다.

napi_open_callback_scope

Added in: v9.6.0

N-API version: 3

C
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
                                                 napi_value resource_object,
                                                 napi_async_context context,
                                                 napi_callback_scope* result)
  • [in] env: API가 호출되는 환경입니다.
  • [in] resource_object: 가능한 async_hooks init hooks에 전달될 비동기 작업과 관련된 객체입니다. 이 매개변수는 더 이상 사용되지 않으며 런타임에 무시됩니다. 대신 napi_async_initasync_resource 매개변수를 사용하십시오.
  • [in] context: 콜백을 호출하는 비동기 작업의 컨텍스트입니다. 이 값은 이전에 napi_async_init에서 얻어야 합니다.
  • [out] result: 새로 생성된 범위입니다.

특정 Node-API 호출을 할 때 콜백과 관련된 범위와 동등한 범위가 필요한 경우(예: 프로미스 해결)가 있습니다. 스택에 다른 스크립트가 없는 경우 napi_open_callback_scopenapi_close_callback_scope 함수를 사용하여 필요한 범위를 열고 닫을 수 있습니다.

napi_close_callback_scope

Added in: v9.6.0

N-API version: 3

C
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: v8.4.0

N-API version: 1

C
typedef struct {
  uint32_t major;
  uint32_t minor;
  uint32_t patch;
  const char* release;
} napi_node_version;

napi_status napi_get_node_version(node_api_basic_env env,
                                  const napi_node_version** version);
  • [in] env: API가 호출되는 환경입니다.
  • [out] version: 현재 실행 중인 Node.js 자체의 버전 정보를 가리키는 포인터입니다.

API가 성공하면 napi_ok를 반환합니다.

이 함수는 현재 실행 중인 Node.js의 메이저, 마이너 및 패치 버전으로 version 구조체를 채우고 process.release.name 값으로 release 필드를 채웁니다.

반환된 버퍼는 정적으로 할당되며 해제할 필요가 없습니다.

napi_get_version

추가된 버전: v8.0.0

N-API 버전: 1

C
napi_status napi_get_version(node_api_basic_env env,
                             uint32_t* result);
  • [in] env: API가 호출되는 환경입니다.
  • [out] result: 지원되는 Node-API의 최고 버전입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 Node.js 런타임에서 지원하는 최고 Node-API 버전을 반환합니다. Node-API는 새로운 Node.js 릴리스에서 추가적인 API 기능을 지원할 수 있도록 추가 방식으로 계획됩니다. 애드온이 Node.js에서 지원하는 버전으로 실행될 때 새로운 기능을 사용할 수 있도록 하면서도 지원하지 않는 Node.js 버전으로 실행할 때 대체 동작을 제공하기 위해 다음을 수행합니다.

  • napi_get_version()을 호출하여 API가 사용 가능한지 확인합니다.
  • 사용 가능한 경우 uv_dlsym()을 사용하여 함수의 포인터를 동적으로 로드합니다.
  • 동적으로 로드된 포인터를 사용하여 함수를 호출합니다.
  • 함수를 사용할 수 없는 경우 함수를 사용하지 않는 대체 구현을 제공합니다.

메모리 관리

napi_adjust_external_memory

추가된 버전: v8.5.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
                                                    int64_t change_in_bytes,
                                                    int64_t* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] change_in_bytes: JavaScript 객체에 의해 유지되는 외부 할당 메모리의 변경 사항입니다.
  • [out] result: 조정된 값입니다.

API가 성공하면 napi_ok를 반환합니다.

이 함수는 V8에 JavaScript 객체에 의해 유지되는 외부 할당 메모리 양에 대한 정보를 제공합니다(예: 네이티브 애드온에서 할당한 자체 메모리를 가리키는 JavaScript 객체). 외부 할당 메모리를 등록하면 평소보다 더 자주 글로벌 가비지 컬렉션이 트리거됩니다.

프로미스

Node-API는 ECMA 사양의 섹션 25.4에 설명된 대로 Promise 객체를 생성하는 기능을 제공합니다. 프로미스를 한 쌍의 객체로 구현합니다. napi_create_promise()에 의해 프로미스가 생성되면 "deferred" 객체가 생성되어 Promise와 함께 반환됩니다. deferred 객체는 생성된 Promise에 바인딩되며 napi_resolve_deferred() 또는 napi_reject_deferred()를 사용하여 Promise를 해결하거나 거부하는 유일한 수단입니다. napi_create_promise()에서 생성된 deferred 객체는 napi_resolve_deferred() 또는 napi_reject_deferred()에 의해 해제됩니다. Promise 객체는 일반적인 방식으로 사용할 수 있는 JavaScript로 반환될 수 있습니다.

예를 들어, 프로미스를 생성하여 비동기 작업자에 전달하려면:

C
napi_deferred deferred;
napi_value promise;
napi_status status;

// 프로미스를 생성합니다.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;

// 비동기 작업을 수행하는 함수에 deferred를 전달합니다.
do_something_asynchronous(deferred);

// JS에 프로미스를 반환합니다.
return promise;

위의 함수 do_something_asynchronous()는 비동기 작업을 수행한 다음 deferred를 해결하거나 거부하여 프로미스를 완료하고 deferred를 해제합니다.

C
napi_deferred deferred;
napi_value undefined;
napi_status status;

// deferred를 완료할 값을 생성합니다.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;

// 비동기 작업이 성공했는지 여부에 따라 deferred와 연결된 프로미스를 해결하거나 거부합니다.
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;

// 이 시점에서 deferred가 해제되었으므로 NULL을 할당해야 합니다.
deferred = NULL;

napi_create_promise

추가된 버전: v8.5.0

N-API 버전: 1

C
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 프로미스입니다.

API가 성공하면 napi_ok를 반환합니다.

이 API는 지연 객체와 JavaScript 프로미스를 생성합니다.

napi_resolve_deferred

추가된 버전: v8.5.0

N-API 버전: 1

C
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

추가된 버전: v8.5.0

N-API 버전: 1

C
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

추가된 버전: v8.5.0

N-API 버전: 1

C
napi_status napi_is_promise(napi_env env,
                            napi_value value,
                            bool* is_promise);
  • [in] env: API가 호출되는 환경입니다.
  • [in] value: 검사할 값입니다.
  • [out] is_promise: promise가 네이티브 Promise 객체(즉, 기본 엔진에 의해 생성된 Promise 객체)인지 여부를 나타내는 플래그입니다.

스크립트 실행

Node-API는 기본 JavaScript 엔진을 사용하여 JavaScript가 포함된 문자열을 실행하기 위한 API를 제공합니다.

napi_run_script

추가된 버전: v8.5.0

N-API 버전: 1

C
NAPI_EXTERN napi_status napi_run_script(napi_env env,
                                        napi_value script,
                                        napi_value* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] script: 실행할 스크립트를 포함하는 JavaScript 문자열입니다.
  • [out] result: 스크립트 실행 결과로 생성된 값입니다.

이 함수는 다음과 같은 주의 사항과 함께 JavaScript 코드 문자열을 실행하고 그 결과를 반환합니다.

  • eval과 달리 이 함수는 스크립트가 현재 어휘 범위에 액세스하는 것을 허용하지 않으므로 모듈 범위에 액세스하는 것도 허용하지 않습니다. 즉, require와 같은 의사 전역 변수를 사용할 수 없습니다.
  • 스크립트는 전역 범위에 액세스할 수 있습니다. 스크립트의 함수 및 var 선언은 global 객체에 추가됩니다. letconst를 사용하여 만든 변수 선언은 전역적으로 표시되지만 global 객체에 추가되지는 않습니다.
  • this 값은 스크립트 내에서 global입니다.

libuv 이벤트 루프

Node-API는 특정 napi_env와 연결된 현재 이벤트 루프를 가져오기 위한 함수를 제공합니다.

napi_get_uv_event_loop

추가된 버전: v9.3.0, v8.10.0

N-API 버전: 2

C
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
                                               struct uv_loop_s** loop);
  • [in] env: API가 호출되는 환경입니다.
  • [out] loop: 현재 libuv 루프 인스턴스입니다.

참고: libuv는 시간이 지남에 따라 비교적 안정적이지만 ABI 안정성을 보장하지 않습니다. 이 함수의 사용은 피해야 합니다. 이 함수를 사용하면 Node.js 버전에서 작동하지 않는 애드온이 생길 수 있습니다. 많은 사용 사례에서 비동기식 스레드 안전 함수 호출이 대안입니다.

비동기 스레드 안전 함수 호출

JavaScript 함수는 일반적으로 네이티브 애드온의 메인 스레드에서만 호출할 수 있습니다. 애드온이 추가 스레드를 생성하는 경우 napi_env, napi_value 또는 napi_ref가 필요한 Node-API 함수는 해당 스레드에서 호출해서는 안 됩니다.

애드온에 추가 스레드가 있고 해당 스레드에서 완료한 처리를 기반으로 JavaScript 함수를 호출해야 하는 경우 해당 스레드는 애드온의 메인 스레드와 통신하여 메인 스레드가 대신 JavaScript 함수를 호출할 수 있도록 해야 합니다. 스레드 안전 함수 API는 이를 쉽게 수행할 수 있는 방법을 제공합니다.

이러한 API는 napi_threadsafe_function 유형과 이 유형의 객체를 만들고 파괴하고 호출하는 API를 제공합니다. napi_create_threadsafe_function()은 여러 스레드에서 호출할 수 있는 JavaScript 함수를 보유하는 napi_value에 대한 영구 참조를 만듭니다. 호출은 비동기적으로 발생합니다. 즉, JavaScript 콜백을 호출하는 값은 큐에 배치되고 큐의 각 값에 대해 결국 JavaScript 함수가 호출됩니다.

napi_threadsafe_function을 생성할 때 napi_finalize 콜백을 제공할 수 있습니다. 이 콜백은 스레드 안전 함수가 파괴되려고 할 때 메인 스레드에서 호출됩니다. 생성하는 동안 제공된 컨텍스트와 마무리 데이터를 수신하고 uv_thread_join()을 호출하여 스레드 이후에 정리할 기회를 제공합니다. 메인 루프 스레드 외에 마무리 콜백이 완료된 후에는 어떤 스레드도 스레드 안전 함수를 사용해서는 안 됩니다.

napi_create_threadsafe_function() 호출 중에 주어진 contextnapi_get_threadsafe_function_context()를 호출하여 모든 스레드에서 검색할 수 있습니다.

스레드 안전 함수 호출

napi_call_threadsafe_function()은 JavaScript로 호출을 시작하는 데 사용할 수 있습니다. napi_call_threadsafe_function()은 API가 블로킹 방식으로 동작할지 여부를 제어하는 매개변수를 허용합니다. napi_tsfn_nonblocking으로 설정되면 API는 비 블로킹 방식으로 동작하며 큐가 가득 차서 데이터를 큐에 성공적으로 추가할 수 없으면 napi_queue_full을 반환합니다. napi_tsfn_blocking으로 설정되면 API는 큐에 공간이 생길 때까지 차단됩니다. 스레드 안전 함수가 최대 큐 크기가 0으로 생성된 경우 napi_call_threadsafe_function()은 차단되지 않습니다.

큐가 가득 찬 경우 JavaScript 스레드가 교착 상태에 빠질 수 있으므로 JavaScript 스레드에서 napi_tsfn_blocking으로 napi_call_threadsafe_function()을 호출해서는 안 됩니다.

JavaScript로의 실제 호출은 call_js_cb 매개변수를 통해 제공된 콜백에 의해 제어됩니다. call_js_cbnapi_call_threadsafe_function()에 대한 성공적인 호출로 큐에 배치된 각 값에 대해 한 번씩 메인 스레드에서 호출됩니다. 이러한 콜백이 제공되지 않으면 기본 콜백이 사용되고 결과 JavaScript 호출에는 인수가 없습니다. call_js_cb 콜백은 해당 매개변수에서 호출할 JavaScript 함수를 napi_value로 받습니다. 또한 napi_threadsafe_function을 만들 때 사용한 void* 컨텍스트 포인터와 보조 스레드 중 하나에서 만든 다음 데이터 포인터를 받습니다. 그런 다음 콜백은 napi_call_function()과 같은 API를 사용하여 JavaScript를 호출할 수 있습니다.

또한 콜백은 JavaScript 호출이 더 이상 가능하지 않다는 것을 나타내기 위해 envcall_js_cb가 모두 NULL로 설정되어 호출될 수 있으며, 이 경우 큐에 해제해야 할 항목이 남아 있을 수 있습니다. 일반적으로 Node.js 프로세스가 활성 상태인 스레드 안전 함수가 있는 동안 종료될 때 발생합니다.

Node-API가 콜백에 적합한 컨텍스트에서 call_js_cb를 실행하므로 napi_make_callback()을 통해 JavaScript를 호출할 필요는 없습니다.

이벤트 루프의 각 틱에서 0개 이상의 큐에 대기 중인 항목을 호출할 수 있습니다. 응용 프로그램은 콜백 호출 진행이 이루어지고 시간이 지남에 따라 이벤트가 호출된다는 것 외에 특정 동작에 의존해서는 안 됩니다.

스레드 안전 함수의 참조 카운팅

스레드는 존재하는 동안 napi_threadsafe_function 객체에 추가 및 제거될 수 있습니다. 따라서 생성 시 초기 스레드 수를 지정하는 것 외에도 napi_acquire_threadsafe_function을 호출하여 새 스레드가 스레드 안전 함수를 사용하기 시작함을 나타낼 수 있습니다. 마찬가지로 napi_release_threadsafe_function을 호출하여 기존 스레드가 스레드 안전 함수 사용을 중단함을 나타낼 수 있습니다.

napi_threadsafe_function 객체는 객체를 사용하는 모든 스레드가 napi_release_threadsafe_function()을 호출하거나 napi_call_threadsafe_function 호출에 대한 응답으로 napi_closing 반환 상태를 받은 경우 소멸됩니다. napi_threadsafe_function이 소멸되기 전에 큐가 비워집니다. napi_release_threadsafe_function()은 주어진 napi_threadsafe_function과 관련하여 수행되는 마지막 API 호출이어야 합니다. 호출이 완료된 후에는 napi_threadsafe_function이 여전히 할당되어 있다고 보장할 수 없기 때문입니다. 같은 이유로 napi_call_threadsafe_function 호출에 대한 응답으로 napi_closing 반환 값을 받은 후에는 스레드 안전 함수를 사용하지 마십시오. napi_threadsafe_function과 관련된 데이터는 napi_create_threadsafe_function()에 전달된 napi_finalize 콜백에서 해제할 수 있습니다. napi_create_threadsafe_function의 파라미터 initial_thread_count는 생성 시 napi_acquire_threadsafe_function을 여러 번 호출하는 대신 스레드 안전 함수의 초기 획득 횟수를 표시합니다.

napi_threadsafe_function을 사용하는 스레드 수가 0에 도달하면 napi_acquire_threadsafe_function()을 호출하여 더 이상 스레드를 사용할 수 없습니다. 실제로 napi_release_threadsafe_function()을 제외한 모든 후속 API 호출은 napi_closing 오류 값을 반환합니다.

napi_release_threadsafe_function()napi_tsfn_abort 값을 제공하여 스레드 안전 함수를 "중단"할 수 있습니다. 이렇게 하면 참조 카운트가 0에 도달하기 전에도 napi_release_threadsafe_function()을 제외한 스레드 안전 함수와 관련된 모든 후속 API가 napi_closing을 반환합니다. 특히 napi_call_threadsafe_function()napi_closing을 반환하므로 스레드 안전 함수에 대한 비동기 호출을 더 이상 할 수 없음을 스레드에 알립니다. 이는 스레드를 종료하기 위한 기준으로 사용할 수 있습니다. napi_call_threadsafe_function()에서 napi_closing 반환 값을 받으면 스레드는 더 이상 스레드 안전 함수를 사용해서는 안됩니다. 스레드 안전 함수가 더 이상 할당되어 있다고 보장할 수 없기 때문입니다.

프로세스를 계속 실행할지 여부 결정

libuv 핸들과 유사하게, 스레드로부터 안전한 함수는 "참조"되고 "참조 해제"될 수 있습니다. "참조된" 스레드로부터 안전한 함수는 해당 함수가 생성된 스레드의 이벤트 루프가 스레드로부터 안전한 함수가 소멸될 때까지 살아있게 합니다. 반대로, "참조 해제된" 스레드로부터 안전한 함수는 이벤트 루프가 종료되는 것을 방지하지 않습니다. napi_ref_threadsafe_functionnapi_unref_threadsafe_function API는 이러한 목적을 위해 존재합니다.

napi_unref_threadsafe_function은 스레드로부터 안전한 함수를 소멸될 수 있는 것으로 표시하지 않으며, napi_ref_threadsafe_function은 소멸되는 것을 방지하지도 않습니다.

napi_create_threadsafe_function

[기록]

버전변경 사항
v12.6.0, v10.17.0사용자 정의 call_js_cbfunc 매개변수를 선택 사항으로 만듦.
v10.6.0v10.6.0에 추가됨

N-API 버전: 4

C
NAPI_EXTERN napi_status
napi_create_threadsafe_function(napi_env env,
                                napi_value func,
                                napi_value async_resource,
                                napi_value async_resource_name,
                                size_t max_queue_size,
                                size_t initial_thread_count,
                                void* thread_finalize_data,
                                napi_finalize thread_finalize_cb,
                                void* context,
                                napi_threadsafe_function_call_js call_js_cb,
                                napi_threadsafe_function* result);
  • [in] env: API가 호출되는 환경입니다.
  • [in] func: 다른 스레드에서 호출할 선택적 JavaScript 함수입니다. NULLcall_js_cb에 전달된 경우 반드시 제공해야 합니다.
  • [in] async_resource: 가능한 async_hooks init 후크에 전달될 비동기 작업과 관련된 선택적 객체입니다.
  • [in] async_resource_name: async_hooks API에서 노출된 진단 정보를 위해 제공되는 리소스 종류에 대한 식별자를 제공하는 JavaScript 문자열입니다.
  • [in] max_queue_size: 큐의 최대 크기입니다. 제한이 없으면 0입니다.
  • [in] initial_thread_count: 초기 획득 수, 즉 이 함수를 사용하는 메인 스레드를 포함한 초기 스레드 수입니다.
  • [in] thread_finalize_data: thread_finalize_cb에 전달할 선택적 데이터입니다.
  • [in] thread_finalize_cb: napi_threadsafe_function이 소멸될 때 호출할 선택적 함수입니다.
  • [in] context: 결과 napi_threadsafe_function에 첨부할 선택적 데이터입니다.
  • [in] call_js_cb: 다른 스레드에서의 호출에 대한 응답으로 JavaScript 함수를 호출하는 선택적 콜백입니다. 이 콜백은 메인 스레드에서 호출됩니다. 제공되지 않으면 JavaScript 함수는 매개변수 없이, undefinedthis 값으로 사용하여 호출됩니다. napi_threadsafe_function_call_js는 더 자세한 정보를 제공합니다.
  • [out] result: 비동기 스레드로부터 안전한 JavaScript 함수입니다.

변경 내역:

  • 실험적 (NAPI_EXPERIMENTAL 정의됨): call_js_cb에서 던져진 포착되지 않은 예외는 무시되는 대신 'uncaughtException' 이벤트로 처리됩니다.

napi_get_threadsafe_function_context

추가된 버전: v10.6.0

N-API 버전: 4

C
NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
                                     void** result);
  • [in] func: 컨텍스트를 검색할 스레드 안전 함수입니다.
  • [out] result: 컨텍스트를 저장할 위치입니다.

이 API는 func를 사용하는 모든 스레드에서 호출할 수 있습니다.

napi_call_threadsafe_function

[기록]

버전변경 사항
v14.5.0napi_would_deadlock에 대한 지원이 되돌려졌습니다.
v14.1.0메인 스레드 또는 워커 스레드에서 napi_tsfn_blocking으로 호출하고 큐가 가득 찬 경우 napi_would_deadlock을 반환합니다.
v10.6.0추가된 버전: v10.6.0

N-API 버전: 4

C
NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
                              void* data,
                              napi_threadsafe_function_call_mode is_blocking);
  • [in] func: 호출할 비동기 스레드 안전 JavaScript 함수입니다.
  • [in] data: 스레드 안전 JavaScript 함수 생성 중에 제공된 콜백 call_js_cb를 통해 JavaScript로 보낼 데이터입니다.
  • [in] is_blocking: 큐가 가득 찬 경우 호출이 차단되어야 함을 나타내는 napi_tsfn_blocking 또는 큐가 가득 찰 때마다 napi_queue_full 상태로 즉시 반환해야 함을 나타내는 napi_tsfn_nonblocking 중 하나의 값을 가질 수 있는 플래그입니다.

이 API는 큐가 가득 찬 경우 JavaScript 스레드가 교착 상태에 빠질 수 있으므로 JavaScript 스레드에서 napi_tsfn_blocking으로 호출해서는 안 됩니다.

이 API는 napi_release_threadsafe_function()이 모든 스레드에서 abortnapi_tsfn_abort로 설정하여 호출된 경우 napi_closing을 반환합니다. 이 값은 API가 napi_ok를 반환하는 경우에만 큐에 추가됩니다.

이 API는 func를 사용하는 모든 스레드에서 호출할 수 있습니다.

napi_acquire_threadsafe_function

추가된 버전: v10.6.0

N-API 버전: 4

C
NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);
  • [in] func: 사용을 시작할 비동기 스레드 안전 JavaScript 함수입니다.

스레드는 func를 사용할 것임을 나타내기 위해 다른 스레드 안전 함수 API에 전달하기 전에 이 API를 호출해야 합니다. 이렇게 하면 다른 모든 스레드가 사용을 중지했을 때 func가 소멸되는 것을 방지합니다.

이 API는 func를 사용하기 시작할 모든 스레드에서 호출할 수 있습니다.

napi_release_threadsafe_function

추가됨: v10.6.0

N-API 버전: 4

C
NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);
  • [in] func: 참조 횟수를 줄일 비동기 스레드 안전 JavaScript 함수입니다.
  • [in] mode: 현재 스레드가 스레드 안전 함수를 더 이상 호출하지 않음을 나타내기 위해 napi_tsfn_release로 설정하거나, 현재 스레드뿐만 아니라 다른 스레드도 스레드 안전 함수를 더 이상 호출하지 않아야 함을 나타내기 위해 napi_tsfn_abort로 설정할 수 있는 플래그입니다. napi_tsfn_abort로 설정된 경우, napi_call_threadsafe_function()을 추가로 호출하면 napi_closing이 반환되고 큐에 추가 값이 배치되지 않습니다.

스레드는 func 사용을 중지할 때 이 API를 호출해야 합니다. 이 API를 호출한 후 func를 스레드 안전 API에 전달하면 func가 삭제되었을 수 있으므로 정의되지 않은 결과가 발생합니다.

이 API는 func 사용을 중지하는 모든 스레드에서 호출할 수 있습니다.

napi_ref_threadsafe_function

추가됨: v10.6.0

N-API 버전: 4

C
NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);
  • [in] env: API가 호출되는 환경입니다.
  • [in] func: 참조할 스레드 안전 함수입니다.

이 API는 func가 삭제될 때까지 메인 스레드에서 실행 중인 이벤트 루프가 종료되지 않아야 함을 나타내는 데 사용됩니다. uv_ref와 유사하게 멱등성입니다.

napi_unref_threadsafe_function은 스레드 안전 함수를 삭제할 수 있는 것으로 표시하지 않으며 napi_ref_threadsafe_function은 삭제되는 것을 방지하지 않습니다. napi_acquire_threadsafe_functionnapi_release_threadsafe_function을 해당 용도로 사용할 수 있습니다.

이 API는 메인 스레드에서만 호출할 수 있습니다.

napi_unref_threadsafe_function

추가됨: v10.6.0

N-API 버전: 4

C
NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);
  • [in] env: API가 호출되는 환경입니다.
  • [in] func: 참조를 해제할 스레드 안전 함수입니다.

이 API는 func가 삭제되기 전에 메인 스레드에서 실행 중인 이벤트 루프가 종료될 수 있음을 나타내는 데 사용됩니다. uv_unref와 유사하게 멱등성입니다.

이 API는 메인 스레드에서만 호출할 수 있습니다.

기타 유틸리티

node_api_get_module_file_name

추가된 버전: v15.9.0, v14.18.0, v12.22.0

N-API 버전: 9

C
NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);
  • [in] env: API가 호출된 환경입니다.
  • [out] result: 애드온이 로드된 위치의 절대 경로를 포함하는 URL입니다. 로컬 파일 시스템의 파일의 경우 file://로 시작합니다. 문자열은 null로 종료되고 env가 소유하므로 수정하거나 해제해서는 안 됩니다.

애드온 로드 프로세스 중에 애드온의 파일 이름을 설정하는 데 실패한 경우 result는 빈 문자열일 수 있습니다.