11cb0ef41Sopenharmony_ci<!DOCTYPE html> 21cb0ef41Sopenharmony_ci<html lang="en"> 31cb0ef41Sopenharmony_ci<head> 41cb0ef41Sopenharmony_ci <meta charset="utf-8"> 51cb0ef41Sopenharmony_ci <meta name="viewport" content="width=device-width"> 61cb0ef41Sopenharmony_ci <meta name="nodejs.org:node-version" content="v18.20.1"> 71cb0ef41Sopenharmony_ci <title>Node-API | Node.js v18.20.1 Documentation</title> 81cb0ef41Sopenharmony_ci <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 91cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/style.css"> 101cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/hljs.css"> 111cb0ef41Sopenharmony_ci <link rel="canonical" href="https://nodejs.org/api/n-api.html"> 121cb0ef41Sopenharmony_ci <script async defer src="assets/api.js" type="text/javascript"></script> 131cb0ef41Sopenharmony_ci 141cb0ef41Sopenharmony_ci</head> 151cb0ef41Sopenharmony_ci<body class="alt apidoc" id="api-section-n-api"> 161cb0ef41Sopenharmony_ci <div id="content" class="clearfix"> 171cb0ef41Sopenharmony_ci <div id="column2" class="interior"> 181cb0ef41Sopenharmony_ci <div id="intro" class="interior"> 191cb0ef41Sopenharmony_ci <a href="/" title="Go back to the home page"> 201cb0ef41Sopenharmony_ci Node.js 211cb0ef41Sopenharmony_ci </a> 221cb0ef41Sopenharmony_ci </div> 231cb0ef41Sopenharmony_ci <ul> 241cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 251cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 261cb0ef41Sopenharmony_ci</ul> 271cb0ef41Sopenharmony_ci<hr class="line"> 281cb0ef41Sopenharmony_ci<ul> 291cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 301cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 311cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 321cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 331cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 341cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api active">C/C++ addons with Node-API</a></li> 351cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 361cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 371cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 381cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 391cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 401cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 411cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 421cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 431cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 441cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 451cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 461cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 471cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 481cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 491cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 501cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 511cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 521cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 531cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 541cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 551cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 561cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 571cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 581cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 591cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 601cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 611cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 621cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 631cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 641cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 651cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 661cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 671cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 681cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 691cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 701cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 711cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 721cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 731cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 741cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 751cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 761cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 771cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 781cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 791cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 801cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 811cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 821cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 831cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 841cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 851cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 861cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 871cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 881cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 891cb0ef41Sopenharmony_ci</ul> 901cb0ef41Sopenharmony_ci<hr class="line"> 911cb0ef41Sopenharmony_ci<ul> 921cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 931cb0ef41Sopenharmony_ci</ul> 941cb0ef41Sopenharmony_ci </div> 951cb0ef41Sopenharmony_ci 961cb0ef41Sopenharmony_ci <div id="column1" data-id="n-api" class="interior"> 971cb0ef41Sopenharmony_ci <header class="header"> 981cb0ef41Sopenharmony_ci <div class="header-container"> 991cb0ef41Sopenharmony_ci <h1>Node.js v18.20.1 documentation</h1> 1001cb0ef41Sopenharmony_ci <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 1011cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 1021cb0ef41Sopenharmony_ci <path fill="none" d="M0 0h24v24H0z" /> 1031cb0ef41Sopenharmony_ci <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 1041cb0ef41Sopenharmony_ci <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 1051cb0ef41Sopenharmony_ci </svg> 1061cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 1071cb0ef41Sopenharmony_ci <path d="M0 0h24v24H0z" fill="none" /> 1081cb0ef41Sopenharmony_ci <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 1091cb0ef41Sopenharmony_ci </svg> 1101cb0ef41Sopenharmony_ci </button> 1111cb0ef41Sopenharmony_ci </div> 1121cb0ef41Sopenharmony_ci <div id="gtoc"> 1131cb0ef41Sopenharmony_ci <ul> 1141cb0ef41Sopenharmony_ci <li class="pinned-header">Node.js v18.20.1</li> 1151cb0ef41Sopenharmony_ci 1161cb0ef41Sopenharmony_ci <li class="picker-header"> 1171cb0ef41Sopenharmony_ci <a href="#"> 1181cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1191cb0ef41Sopenharmony_ci Table of contents 1201cb0ef41Sopenharmony_ci </a> 1211cb0ef41Sopenharmony_ci 1221cb0ef41Sopenharmony_ci <div class="picker"><div class="toc"><ul> 1231cb0ef41Sopenharmony_ci<li><span class="stability_2"><a href="#node-api">Node-API</a></span> 1241cb0ef41Sopenharmony_ci<ul> 1251cb0ef41Sopenharmony_ci<li><a href="#implications-of-abi-stability">Implications of ABI stability</a></li> 1261cb0ef41Sopenharmony_ci<li><a href="#building">Building</a> 1271cb0ef41Sopenharmony_ci<ul> 1281cb0ef41Sopenharmony_ci<li><a href="#build-tools">Build tools</a> 1291cb0ef41Sopenharmony_ci<ul> 1301cb0ef41Sopenharmony_ci<li><a href="#node-gyp">node-gyp</a></li> 1311cb0ef41Sopenharmony_ci<li><a href="#cmakejs">CMake.js</a></li> 1321cb0ef41Sopenharmony_ci</ul> 1331cb0ef41Sopenharmony_ci</li> 1341cb0ef41Sopenharmony_ci<li><a href="#uploading-precompiled-binaries">Uploading precompiled binaries</a> 1351cb0ef41Sopenharmony_ci<ul> 1361cb0ef41Sopenharmony_ci<li><a href="#node-pre-gyp">node-pre-gyp</a></li> 1371cb0ef41Sopenharmony_ci<li><a href="#prebuild">prebuild</a></li> 1381cb0ef41Sopenharmony_ci<li><a href="#prebuildify">prebuildify</a></li> 1391cb0ef41Sopenharmony_ci</ul> 1401cb0ef41Sopenharmony_ci</li> 1411cb0ef41Sopenharmony_ci</ul> 1421cb0ef41Sopenharmony_ci</li> 1431cb0ef41Sopenharmony_ci<li><a href="#usage">Usage</a></li> 1441cb0ef41Sopenharmony_ci<li><a href="#node-api-version-matrix">Node-API version matrix</a></li> 1451cb0ef41Sopenharmony_ci<li><a href="#environment-life-cycle-apis">Environment life cycle APIs</a> 1461cb0ef41Sopenharmony_ci<ul> 1471cb0ef41Sopenharmony_ci<li><a href="#napi_set_instance_data"><code>napi_set_instance_data</code></a></li> 1481cb0ef41Sopenharmony_ci<li><a href="#napi_get_instance_data"><code>napi_get_instance_data</code></a></li> 1491cb0ef41Sopenharmony_ci</ul> 1501cb0ef41Sopenharmony_ci</li> 1511cb0ef41Sopenharmony_ci<li><a href="#basic-node-api-data-types">Basic Node-API data types</a> 1521cb0ef41Sopenharmony_ci<ul> 1531cb0ef41Sopenharmony_ci<li><a href="#napi_status"><code>napi_status</code></a></li> 1541cb0ef41Sopenharmony_ci<li><a href="#napi_extended_error_info"><code>napi_extended_error_info</code></a></li> 1551cb0ef41Sopenharmony_ci<li><a href="#napi_env"><code>napi_env</code></a></li> 1561cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_nogc_env"><code>node_api_nogc_env</code></a></span></li> 1571cb0ef41Sopenharmony_ci<li><a href="#napi_value"><code>napi_value</code></a></li> 1581cb0ef41Sopenharmony_ci<li><a href="#napi_threadsafe_function"><code>napi_threadsafe_function</code></a></li> 1591cb0ef41Sopenharmony_ci<li><a href="#napi_threadsafe_function_release_mode"><code>napi_threadsafe_function_release_mode</code></a></li> 1601cb0ef41Sopenharmony_ci<li><a href="#napi_threadsafe_function_call_mode"><code>napi_threadsafe_function_call_mode</code></a></li> 1611cb0ef41Sopenharmony_ci<li><a href="#node-api-memory-management-types">Node-API memory management types</a> 1621cb0ef41Sopenharmony_ci<ul> 1631cb0ef41Sopenharmony_ci<li><a href="#napi_handle_scope"><code>napi_handle_scope</code></a></li> 1641cb0ef41Sopenharmony_ci<li><a href="#napi_escapable_handle_scope"><code>napi_escapable_handle_scope</code></a></li> 1651cb0ef41Sopenharmony_ci<li><a href="#napi_ref"><code>napi_ref</code></a></li> 1661cb0ef41Sopenharmony_ci<li><a href="#napi_type_tag"><code>napi_type_tag</code></a></li> 1671cb0ef41Sopenharmony_ci<li><a href="#napi_async_cleanup_hook_handle"><code>napi_async_cleanup_hook_handle</code></a></li> 1681cb0ef41Sopenharmony_ci</ul> 1691cb0ef41Sopenharmony_ci</li> 1701cb0ef41Sopenharmony_ci<li><a href="#node-api-callback-types">Node-API callback types</a> 1711cb0ef41Sopenharmony_ci<ul> 1721cb0ef41Sopenharmony_ci<li><a href="#napi_callback_info"><code>napi_callback_info</code></a></li> 1731cb0ef41Sopenharmony_ci<li><a href="#napi_callback"><code>napi_callback</code></a></li> 1741cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_nogc_finalize"><code>node_api_nogc_finalize</code></a></span></li> 1751cb0ef41Sopenharmony_ci<li><a href="#napi_finalize"><code>napi_finalize</code></a></li> 1761cb0ef41Sopenharmony_ci<li><a href="#napi_async_execute_callback"><code>napi_async_execute_callback</code></a></li> 1771cb0ef41Sopenharmony_ci<li><a href="#napi_async_complete_callback"><code>napi_async_complete_callback</code></a></li> 1781cb0ef41Sopenharmony_ci<li><a href="#napi_threadsafe_function_call_js"><code>napi_threadsafe_function_call_js</code></a></li> 1791cb0ef41Sopenharmony_ci<li><a href="#napi_cleanup_hook"><code>napi_cleanup_hook</code></a></li> 1801cb0ef41Sopenharmony_ci<li><a href="#napi_async_cleanup_hook"><code>napi_async_cleanup_hook</code></a></li> 1811cb0ef41Sopenharmony_ci</ul> 1821cb0ef41Sopenharmony_ci</li> 1831cb0ef41Sopenharmony_ci</ul> 1841cb0ef41Sopenharmony_ci</li> 1851cb0ef41Sopenharmony_ci<li><a href="#error-handling">Error handling</a> 1861cb0ef41Sopenharmony_ci<ul> 1871cb0ef41Sopenharmony_ci<li><a href="#return-values">Return values</a> 1881cb0ef41Sopenharmony_ci<ul> 1891cb0ef41Sopenharmony_ci<li><a href="#napi_get_last_error_info"><code>napi_get_last_error_info</code></a></li> 1901cb0ef41Sopenharmony_ci</ul> 1911cb0ef41Sopenharmony_ci</li> 1921cb0ef41Sopenharmony_ci<li><a href="#exceptions">Exceptions</a> 1931cb0ef41Sopenharmony_ci<ul> 1941cb0ef41Sopenharmony_ci<li><a href="#napi_throw"><code>napi_throw</code></a></li> 1951cb0ef41Sopenharmony_ci<li><a href="#napi_throw_error"><code>napi_throw_error</code></a></li> 1961cb0ef41Sopenharmony_ci<li><a href="#napi_throw_type_error"><code>napi_throw_type_error</code></a></li> 1971cb0ef41Sopenharmony_ci<li><a href="#napi_throw_range_error"><code>napi_throw_range_error</code></a></li> 1981cb0ef41Sopenharmony_ci<li><a href="#node_api_throw_syntax_error"><code>node_api_throw_syntax_error</code></a></li> 1991cb0ef41Sopenharmony_ci<li><a href="#napi_is_error"><code>napi_is_error</code></a></li> 2001cb0ef41Sopenharmony_ci<li><a href="#napi_create_error"><code>napi_create_error</code></a></li> 2011cb0ef41Sopenharmony_ci<li><a href="#napi_create_type_error"><code>napi_create_type_error</code></a></li> 2021cb0ef41Sopenharmony_ci<li><a href="#napi_create_range_error"><code>napi_create_range_error</code></a></li> 2031cb0ef41Sopenharmony_ci<li><a href="#node_api_create_syntax_error"><code>node_api_create_syntax_error</code></a></li> 2041cb0ef41Sopenharmony_ci<li><a href="#napi_get_and_clear_last_exception"><code>napi_get_and_clear_last_exception</code></a></li> 2051cb0ef41Sopenharmony_ci<li><a href="#napi_is_exception_pending"><code>napi_is_exception_pending</code></a></li> 2061cb0ef41Sopenharmony_ci<li><a href="#napi_fatal_exception"><code>napi_fatal_exception</code></a></li> 2071cb0ef41Sopenharmony_ci</ul> 2081cb0ef41Sopenharmony_ci</li> 2091cb0ef41Sopenharmony_ci<li><a href="#fatal-errors">Fatal errors</a> 2101cb0ef41Sopenharmony_ci<ul> 2111cb0ef41Sopenharmony_ci<li><a href="#napi_fatal_error"><code>napi_fatal_error</code></a></li> 2121cb0ef41Sopenharmony_ci</ul> 2131cb0ef41Sopenharmony_ci</li> 2141cb0ef41Sopenharmony_ci</ul> 2151cb0ef41Sopenharmony_ci</li> 2161cb0ef41Sopenharmony_ci<li><a href="#object-lifetime-management">Object lifetime management</a> 2171cb0ef41Sopenharmony_ci<ul> 2181cb0ef41Sopenharmony_ci<li><a href="#making-handle-lifespan-shorter-than-that-of-the-native-method">Making handle lifespan shorter than that of the native method</a> 2191cb0ef41Sopenharmony_ci<ul> 2201cb0ef41Sopenharmony_ci<li><a href="#napi_open_handle_scope"><code>napi_open_handle_scope</code></a></li> 2211cb0ef41Sopenharmony_ci<li><a href="#napi_close_handle_scope"><code>napi_close_handle_scope</code></a></li> 2221cb0ef41Sopenharmony_ci<li><a href="#napi_open_escapable_handle_scope"><code>napi_open_escapable_handle_scope</code></a></li> 2231cb0ef41Sopenharmony_ci<li><a href="#napi_close_escapable_handle_scope"><code>napi_close_escapable_handle_scope</code></a></li> 2241cb0ef41Sopenharmony_ci<li><a href="#napi_escape_handle"><code>napi_escape_handle</code></a></li> 2251cb0ef41Sopenharmony_ci</ul> 2261cb0ef41Sopenharmony_ci</li> 2271cb0ef41Sopenharmony_ci<li><a href="#references-to-values-with-a-lifespan-longer-than-that-of-the-native-method">References to values with a lifespan longer than that of the native method</a> 2281cb0ef41Sopenharmony_ci<ul> 2291cb0ef41Sopenharmony_ci<li><a href="#napi_create_reference"><code>napi_create_reference</code></a></li> 2301cb0ef41Sopenharmony_ci<li><a href="#napi_delete_reference"><code>napi_delete_reference</code></a></li> 2311cb0ef41Sopenharmony_ci<li><a href="#napi_reference_ref"><code>napi_reference_ref</code></a></li> 2321cb0ef41Sopenharmony_ci<li><a href="#napi_reference_unref"><code>napi_reference_unref</code></a></li> 2331cb0ef41Sopenharmony_ci<li><a href="#napi_get_reference_value"><code>napi_get_reference_value</code></a></li> 2341cb0ef41Sopenharmony_ci</ul> 2351cb0ef41Sopenharmony_ci</li> 2361cb0ef41Sopenharmony_ci<li><a href="#cleanup-on-exit-of-the-current-nodejs-environment">Cleanup on exit of the current Node.js environment</a> 2371cb0ef41Sopenharmony_ci<ul> 2381cb0ef41Sopenharmony_ci<li><a href="#napi_add_env_cleanup_hook"><code>napi_add_env_cleanup_hook</code></a></li> 2391cb0ef41Sopenharmony_ci<li><a href="#napi_remove_env_cleanup_hook"><code>napi_remove_env_cleanup_hook</code></a></li> 2401cb0ef41Sopenharmony_ci<li><a href="#napi_add_async_cleanup_hook"><code>napi_add_async_cleanup_hook</code></a></li> 2411cb0ef41Sopenharmony_ci<li><a href="#napi_remove_async_cleanup_hook"><code>napi_remove_async_cleanup_hook</code></a></li> 2421cb0ef41Sopenharmony_ci</ul> 2431cb0ef41Sopenharmony_ci</li> 2441cb0ef41Sopenharmony_ci<li><a href="#finalization-on-the-exit-of-the-nodejs-environment">Finalization on the exit of the Node.js environment</a></li> 2451cb0ef41Sopenharmony_ci</ul> 2461cb0ef41Sopenharmony_ci</li> 2471cb0ef41Sopenharmony_ci<li><a href="#module-registration">Module registration</a></li> 2481cb0ef41Sopenharmony_ci<li><a href="#working-with-javascript-values">Working with JavaScript values</a> 2491cb0ef41Sopenharmony_ci<ul> 2501cb0ef41Sopenharmony_ci<li><a href="#enum-types">Enum types</a> 2511cb0ef41Sopenharmony_ci<ul> 2521cb0ef41Sopenharmony_ci<li><a href="#napi_key_collection_mode"><code>napi_key_collection_mode</code></a></li> 2531cb0ef41Sopenharmony_ci<li><a href="#napi_key_filter"><code>napi_key_filter</code></a></li> 2541cb0ef41Sopenharmony_ci<li><a href="#napi_key_conversion"><code>napi_key_conversion</code></a></li> 2551cb0ef41Sopenharmony_ci<li><a href="#napi_valuetype"><code>napi_valuetype</code></a></li> 2561cb0ef41Sopenharmony_ci<li><a href="#napi_typedarray_type"><code>napi_typedarray_type</code></a></li> 2571cb0ef41Sopenharmony_ci</ul> 2581cb0ef41Sopenharmony_ci</li> 2591cb0ef41Sopenharmony_ci<li><a href="#object-creation-functions">Object creation functions</a> 2601cb0ef41Sopenharmony_ci<ul> 2611cb0ef41Sopenharmony_ci<li><a href="#napi_create_array"><code>napi_create_array</code></a></li> 2621cb0ef41Sopenharmony_ci<li><a href="#napi_create_array_with_length"><code>napi_create_array_with_length</code></a></li> 2631cb0ef41Sopenharmony_ci<li><a href="#napi_create_arraybuffer"><code>napi_create_arraybuffer</code></a></li> 2641cb0ef41Sopenharmony_ci<li><a href="#napi_create_buffer"><code>napi_create_buffer</code></a></li> 2651cb0ef41Sopenharmony_ci<li><a href="#napi_create_buffer_copy"><code>napi_create_buffer_copy</code></a></li> 2661cb0ef41Sopenharmony_ci<li><a href="#napi_create_date"><code>napi_create_date</code></a></li> 2671cb0ef41Sopenharmony_ci<li><a href="#napi_create_external"><code>napi_create_external</code></a></li> 2681cb0ef41Sopenharmony_ci<li><a href="#napi_create_external_arraybuffer"><code>napi_create_external_arraybuffer</code></a></li> 2691cb0ef41Sopenharmony_ci<li><a href="#napi_create_external_buffer"><code>napi_create_external_buffer</code></a></li> 2701cb0ef41Sopenharmony_ci<li><a href="#napi_create_object"><code>napi_create_object</code></a></li> 2711cb0ef41Sopenharmony_ci<li><a href="#napi_create_symbol"><code>napi_create_symbol</code></a></li> 2721cb0ef41Sopenharmony_ci<li><a href="#node_api_symbol_for"><code>node_api_symbol_for</code></a></li> 2731cb0ef41Sopenharmony_ci<li><a href="#napi_create_typedarray"><code>napi_create_typedarray</code></a></li> 2741cb0ef41Sopenharmony_ci<li><a href="#napi_create_dataview"><code>napi_create_dataview</code></a></li> 2751cb0ef41Sopenharmony_ci</ul> 2761cb0ef41Sopenharmony_ci</li> 2771cb0ef41Sopenharmony_ci<li><a href="#functions-to-convert-from-c-types-to-node-api">Functions to convert from C types to Node-API</a> 2781cb0ef41Sopenharmony_ci<ul> 2791cb0ef41Sopenharmony_ci<li><a href="#napi_create_int32"><code>napi_create_int32</code></a></li> 2801cb0ef41Sopenharmony_ci<li><a href="#napi_create_uint32"><code>napi_create_uint32</code></a></li> 2811cb0ef41Sopenharmony_ci<li><a href="#napi_create_int64"><code>napi_create_int64</code></a></li> 2821cb0ef41Sopenharmony_ci<li><a href="#napi_create_double"><code>napi_create_double</code></a></li> 2831cb0ef41Sopenharmony_ci<li><a href="#napi_create_bigint_int64"><code>napi_create_bigint_int64</code></a></li> 2841cb0ef41Sopenharmony_ci<li><a href="#napi_create_bigint_uint64"><code>napi_create_bigint_uint64</code></a></li> 2851cb0ef41Sopenharmony_ci<li><a href="#napi_create_bigint_words"><code>napi_create_bigint_words</code></a></li> 2861cb0ef41Sopenharmony_ci<li><a href="#napi_create_string_latin1"><code>napi_create_string_latin1</code></a></li> 2871cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_create_external_string_latin1"><code>node_api_create_external_string_latin1</code></a></span></li> 2881cb0ef41Sopenharmony_ci<li><a href="#napi_create_string_utf16"><code>napi_create_string_utf16</code></a></li> 2891cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_create_external_string_utf16"><code>node_api_create_external_string_utf16</code></a></span></li> 2901cb0ef41Sopenharmony_ci<li><a href="#napi_create_string_utf8"><code>napi_create_string_utf8</code></a></li> 2911cb0ef41Sopenharmony_ci</ul> 2921cb0ef41Sopenharmony_ci</li> 2931cb0ef41Sopenharmony_ci<li><a href="#functions-to-convert-from-node-api-to-c-types">Functions to convert from Node-API to C types</a> 2941cb0ef41Sopenharmony_ci<ul> 2951cb0ef41Sopenharmony_ci<li><a href="#napi_get_array_length"><code>napi_get_array_length</code></a></li> 2961cb0ef41Sopenharmony_ci<li><a href="#napi_get_arraybuffer_info"><code>napi_get_arraybuffer_info</code></a></li> 2971cb0ef41Sopenharmony_ci<li><a href="#napi_get_buffer_info"><code>napi_get_buffer_info</code></a></li> 2981cb0ef41Sopenharmony_ci<li><a href="#napi_get_prototype"><code>napi_get_prototype</code></a></li> 2991cb0ef41Sopenharmony_ci<li><a href="#napi_get_typedarray_info"><code>napi_get_typedarray_info</code></a></li> 3001cb0ef41Sopenharmony_ci<li><a href="#napi_get_dataview_info"><code>napi_get_dataview_info</code></a></li> 3011cb0ef41Sopenharmony_ci<li><a href="#napi_get_date_value"><code>napi_get_date_value</code></a></li> 3021cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_bool"><code>napi_get_value_bool</code></a></li> 3031cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_double"><code>napi_get_value_double</code></a></li> 3041cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_bigint_int64"><code>napi_get_value_bigint_int64</code></a></li> 3051cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_bigint_uint64"><code>napi_get_value_bigint_uint64</code></a></li> 3061cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_bigint_words"><code>napi_get_value_bigint_words</code></a></li> 3071cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_external"><code>napi_get_value_external</code></a></li> 3081cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_int32"><code>napi_get_value_int32</code></a></li> 3091cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_int64"><code>napi_get_value_int64</code></a></li> 3101cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_string_latin1"><code>napi_get_value_string_latin1</code></a></li> 3111cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_string_utf8"><code>napi_get_value_string_utf8</code></a></li> 3121cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_string_utf16"><code>napi_get_value_string_utf16</code></a></li> 3131cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_uint32"><code>napi_get_value_uint32</code></a></li> 3141cb0ef41Sopenharmony_ci</ul> 3151cb0ef41Sopenharmony_ci</li> 3161cb0ef41Sopenharmony_ci<li><a href="#functions-to-get-global-instances">Functions to get global instances</a> 3171cb0ef41Sopenharmony_ci<ul> 3181cb0ef41Sopenharmony_ci<li><a href="#napi_get_boolean"><code>napi_get_boolean</code></a></li> 3191cb0ef41Sopenharmony_ci<li><a href="#napi_get_global"><code>napi_get_global</code></a></li> 3201cb0ef41Sopenharmony_ci<li><a href="#napi_get_null"><code>napi_get_null</code></a></li> 3211cb0ef41Sopenharmony_ci<li><a href="#napi_get_undefined"><code>napi_get_undefined</code></a></li> 3221cb0ef41Sopenharmony_ci</ul> 3231cb0ef41Sopenharmony_ci</li> 3241cb0ef41Sopenharmony_ci</ul> 3251cb0ef41Sopenharmony_ci</li> 3261cb0ef41Sopenharmony_ci<li><a href="#working-with-javascript-values-and-abstract-operations">Working with JavaScript values and abstract operations</a> 3271cb0ef41Sopenharmony_ci<ul> 3281cb0ef41Sopenharmony_ci<li><a href="#napi_coerce_to_bool"><code>napi_coerce_to_bool</code></a></li> 3291cb0ef41Sopenharmony_ci<li><a href="#napi_coerce_to_number"><code>napi_coerce_to_number</code></a></li> 3301cb0ef41Sopenharmony_ci<li><a href="#napi_coerce_to_object"><code>napi_coerce_to_object</code></a></li> 3311cb0ef41Sopenharmony_ci<li><a href="#napi_coerce_to_string"><code>napi_coerce_to_string</code></a></li> 3321cb0ef41Sopenharmony_ci<li><a href="#napi_typeof"><code>napi_typeof</code></a></li> 3331cb0ef41Sopenharmony_ci<li><a href="#napi_instanceof"><code>napi_instanceof</code></a></li> 3341cb0ef41Sopenharmony_ci<li><a href="#napi_is_array"><code>napi_is_array</code></a></li> 3351cb0ef41Sopenharmony_ci<li><a href="#napi_is_arraybuffer"><code>napi_is_arraybuffer</code></a></li> 3361cb0ef41Sopenharmony_ci<li><a href="#napi_is_buffer"><code>napi_is_buffer</code></a></li> 3371cb0ef41Sopenharmony_ci<li><a href="#napi_is_date"><code>napi_is_date</code></a></li> 3381cb0ef41Sopenharmony_ci<li><a href="#napi_is_error_1"><code>napi_is_error</code></a></li> 3391cb0ef41Sopenharmony_ci<li><a href="#napi_is_typedarray"><code>napi_is_typedarray</code></a></li> 3401cb0ef41Sopenharmony_ci<li><a href="#napi_is_dataview"><code>napi_is_dataview</code></a></li> 3411cb0ef41Sopenharmony_ci<li><a href="#napi_strict_equals"><code>napi_strict_equals</code></a></li> 3421cb0ef41Sopenharmony_ci<li><a href="#napi_detach_arraybuffer"><code>napi_detach_arraybuffer</code></a></li> 3431cb0ef41Sopenharmony_ci<li><a href="#napi_is_detached_arraybuffer"><code>napi_is_detached_arraybuffer</code></a></li> 3441cb0ef41Sopenharmony_ci</ul> 3451cb0ef41Sopenharmony_ci</li> 3461cb0ef41Sopenharmony_ci<li><a href="#working-with-javascript-properties">Working with JavaScript properties</a> 3471cb0ef41Sopenharmony_ci<ul> 3481cb0ef41Sopenharmony_ci<li><a href="#structures">Structures</a> 3491cb0ef41Sopenharmony_ci<ul> 3501cb0ef41Sopenharmony_ci<li><a href="#napi_property_attributes"><code>napi_property_attributes</code></a></li> 3511cb0ef41Sopenharmony_ci<li><a href="#napi_property_descriptor"><code>napi_property_descriptor</code></a></li> 3521cb0ef41Sopenharmony_ci</ul> 3531cb0ef41Sopenharmony_ci</li> 3541cb0ef41Sopenharmony_ci<li><a href="#functions">Functions</a> 3551cb0ef41Sopenharmony_ci<ul> 3561cb0ef41Sopenharmony_ci<li><a href="#napi_get_property_names"><code>napi_get_property_names</code></a></li> 3571cb0ef41Sopenharmony_ci<li><a href="#napi_get_all_property_names"><code>napi_get_all_property_names</code></a></li> 3581cb0ef41Sopenharmony_ci<li><a href="#napi_set_property"><code>napi_set_property</code></a></li> 3591cb0ef41Sopenharmony_ci<li><a href="#napi_get_property"><code>napi_get_property</code></a></li> 3601cb0ef41Sopenharmony_ci<li><a href="#napi_has_property"><code>napi_has_property</code></a></li> 3611cb0ef41Sopenharmony_ci<li><a href="#napi_delete_property"><code>napi_delete_property</code></a></li> 3621cb0ef41Sopenharmony_ci<li><a href="#napi_has_own_property"><code>napi_has_own_property</code></a></li> 3631cb0ef41Sopenharmony_ci<li><a href="#napi_set_named_property"><code>napi_set_named_property</code></a></li> 3641cb0ef41Sopenharmony_ci<li><a href="#napi_get_named_property"><code>napi_get_named_property</code></a></li> 3651cb0ef41Sopenharmony_ci<li><a href="#napi_has_named_property"><code>napi_has_named_property</code></a></li> 3661cb0ef41Sopenharmony_ci<li><a href="#napi_set_element"><code>napi_set_element</code></a></li> 3671cb0ef41Sopenharmony_ci<li><a href="#napi_get_element"><code>napi_get_element</code></a></li> 3681cb0ef41Sopenharmony_ci<li><a href="#napi_has_element"><code>napi_has_element</code></a></li> 3691cb0ef41Sopenharmony_ci<li><a href="#napi_delete_element"><code>napi_delete_element</code></a></li> 3701cb0ef41Sopenharmony_ci<li><a href="#napi_define_properties"><code>napi_define_properties</code></a></li> 3711cb0ef41Sopenharmony_ci<li><a href="#napi_object_freeze"><code>napi_object_freeze</code></a></li> 3721cb0ef41Sopenharmony_ci<li><a href="#napi_object_seal"><code>napi_object_seal</code></a></li> 3731cb0ef41Sopenharmony_ci</ul> 3741cb0ef41Sopenharmony_ci</li> 3751cb0ef41Sopenharmony_ci</ul> 3761cb0ef41Sopenharmony_ci</li> 3771cb0ef41Sopenharmony_ci<li><a href="#working-with-javascript-functions">Working with JavaScript functions</a> 3781cb0ef41Sopenharmony_ci<ul> 3791cb0ef41Sopenharmony_ci<li><a href="#napi_call_function"><code>napi_call_function</code></a></li> 3801cb0ef41Sopenharmony_ci<li><a href="#napi_create_function"><code>napi_create_function</code></a></li> 3811cb0ef41Sopenharmony_ci<li><a href="#napi_get_cb_info"><code>napi_get_cb_info</code></a></li> 3821cb0ef41Sopenharmony_ci<li><a href="#napi_get_new_target"><code>napi_get_new_target</code></a></li> 3831cb0ef41Sopenharmony_ci<li><a href="#napi_new_instance"><code>napi_new_instance</code></a></li> 3841cb0ef41Sopenharmony_ci</ul> 3851cb0ef41Sopenharmony_ci</li> 3861cb0ef41Sopenharmony_ci<li><a href="#object-wrap">Object wrap</a> 3871cb0ef41Sopenharmony_ci<ul> 3881cb0ef41Sopenharmony_ci<li><a href="#napi_define_class"><code>napi_define_class</code></a></li> 3891cb0ef41Sopenharmony_ci<li><a href="#napi_wrap"><code>napi_wrap</code></a></li> 3901cb0ef41Sopenharmony_ci<li><a href="#napi_unwrap"><code>napi_unwrap</code></a></li> 3911cb0ef41Sopenharmony_ci<li><a href="#napi_remove_wrap"><code>napi_remove_wrap</code></a></li> 3921cb0ef41Sopenharmony_ci<li><a href="#napi_type_tag_object"><code>napi_type_tag_object</code></a></li> 3931cb0ef41Sopenharmony_ci<li><a href="#napi_check_object_type_tag"><code>napi_check_object_type_tag</code></a></li> 3941cb0ef41Sopenharmony_ci<li><a href="#napi_add_finalizer"><code>napi_add_finalizer</code></a> 3951cb0ef41Sopenharmony_ci<ul> 3961cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_post_finalizer"><code>node_api_post_finalizer</code></a></span></li> 3971cb0ef41Sopenharmony_ci</ul> 3981cb0ef41Sopenharmony_ci</li> 3991cb0ef41Sopenharmony_ci</ul> 4001cb0ef41Sopenharmony_ci</li> 4011cb0ef41Sopenharmony_ci<li><a href="#simple-asynchronous-operations">Simple asynchronous operations</a> 4021cb0ef41Sopenharmony_ci<ul> 4031cb0ef41Sopenharmony_ci<li><a href="#napi_create_async_work"><code>napi_create_async_work</code></a></li> 4041cb0ef41Sopenharmony_ci<li><a href="#napi_delete_async_work"><code>napi_delete_async_work</code></a></li> 4051cb0ef41Sopenharmony_ci<li><a href="#napi_queue_async_work"><code>napi_queue_async_work</code></a></li> 4061cb0ef41Sopenharmony_ci<li><a href="#napi_cancel_async_work"><code>napi_cancel_async_work</code></a></li> 4071cb0ef41Sopenharmony_ci</ul> 4081cb0ef41Sopenharmony_ci</li> 4091cb0ef41Sopenharmony_ci<li><a href="#custom-asynchronous-operations">Custom asynchronous operations</a> 4101cb0ef41Sopenharmony_ci<ul> 4111cb0ef41Sopenharmony_ci<li><a href="#napi_async_init"><code>napi_async_init</code></a></li> 4121cb0ef41Sopenharmony_ci<li><a href="#napi_async_destroy"><code>napi_async_destroy</code></a></li> 4131cb0ef41Sopenharmony_ci<li><a href="#napi_make_callback"><code>napi_make_callback</code></a></li> 4141cb0ef41Sopenharmony_ci<li><a href="#napi_open_callback_scope"><code>napi_open_callback_scope</code></a></li> 4151cb0ef41Sopenharmony_ci<li><a href="#napi_close_callback_scope"><code>napi_close_callback_scope</code></a></li> 4161cb0ef41Sopenharmony_ci</ul> 4171cb0ef41Sopenharmony_ci</li> 4181cb0ef41Sopenharmony_ci<li><a href="#version-management">Version management</a> 4191cb0ef41Sopenharmony_ci<ul> 4201cb0ef41Sopenharmony_ci<li><a href="#napi_get_node_version"><code>napi_get_node_version</code></a></li> 4211cb0ef41Sopenharmony_ci<li><a href="#napi_get_version"><code>napi_get_version</code></a></li> 4221cb0ef41Sopenharmony_ci</ul> 4231cb0ef41Sopenharmony_ci</li> 4241cb0ef41Sopenharmony_ci<li><a href="#memory-management">Memory management</a> 4251cb0ef41Sopenharmony_ci<ul> 4261cb0ef41Sopenharmony_ci<li><a href="#napi_adjust_external_memory"><code>napi_adjust_external_memory</code></a></li> 4271cb0ef41Sopenharmony_ci</ul> 4281cb0ef41Sopenharmony_ci</li> 4291cb0ef41Sopenharmony_ci<li><a href="#promises">Promises</a> 4301cb0ef41Sopenharmony_ci<ul> 4311cb0ef41Sopenharmony_ci<li><a href="#napi_create_promise"><code>napi_create_promise</code></a></li> 4321cb0ef41Sopenharmony_ci<li><a href="#napi_resolve_deferred"><code>napi_resolve_deferred</code></a></li> 4331cb0ef41Sopenharmony_ci<li><a href="#napi_reject_deferred"><code>napi_reject_deferred</code></a></li> 4341cb0ef41Sopenharmony_ci<li><a href="#napi_is_promise"><code>napi_is_promise</code></a></li> 4351cb0ef41Sopenharmony_ci</ul> 4361cb0ef41Sopenharmony_ci</li> 4371cb0ef41Sopenharmony_ci<li><a href="#script-execution">Script execution</a> 4381cb0ef41Sopenharmony_ci<ul> 4391cb0ef41Sopenharmony_ci<li><a href="#napi_run_script"><code>napi_run_script</code></a></li> 4401cb0ef41Sopenharmony_ci</ul> 4411cb0ef41Sopenharmony_ci</li> 4421cb0ef41Sopenharmony_ci<li><a href="#libuv-event-loop">libuv event loop</a> 4431cb0ef41Sopenharmony_ci<ul> 4441cb0ef41Sopenharmony_ci<li><a href="#napi_get_uv_event_loop"><code>napi_get_uv_event_loop</code></a></li> 4451cb0ef41Sopenharmony_ci</ul> 4461cb0ef41Sopenharmony_ci</li> 4471cb0ef41Sopenharmony_ci<li><a href="#asynchronous-thread-safe-function-calls">Asynchronous thread-safe function calls</a> 4481cb0ef41Sopenharmony_ci<ul> 4491cb0ef41Sopenharmony_ci<li><a href="#calling-a-thread-safe-function">Calling a thread-safe function</a></li> 4501cb0ef41Sopenharmony_ci<li><a href="#reference-counting-of-thread-safe-functions">Reference counting of thread-safe functions</a></li> 4511cb0ef41Sopenharmony_ci<li><a href="#deciding-whether-to-keep-the-process-running">Deciding whether to keep the process running</a></li> 4521cb0ef41Sopenharmony_ci<li><a href="#napi_create_threadsafe_function"><code>napi_create_threadsafe_function</code></a></li> 4531cb0ef41Sopenharmony_ci<li><a href="#napi_get_threadsafe_function_context"><code>napi_get_threadsafe_function_context</code></a></li> 4541cb0ef41Sopenharmony_ci<li><a href="#napi_call_threadsafe_function"><code>napi_call_threadsafe_function</code></a></li> 4551cb0ef41Sopenharmony_ci<li><a href="#napi_acquire_threadsafe_function"><code>napi_acquire_threadsafe_function</code></a></li> 4561cb0ef41Sopenharmony_ci<li><a href="#napi_release_threadsafe_function"><code>napi_release_threadsafe_function</code></a></li> 4571cb0ef41Sopenharmony_ci<li><a href="#napi_ref_threadsafe_function"><code>napi_ref_threadsafe_function</code></a></li> 4581cb0ef41Sopenharmony_ci<li><a href="#napi_unref_threadsafe_function"><code>napi_unref_threadsafe_function</code></a></li> 4591cb0ef41Sopenharmony_ci</ul> 4601cb0ef41Sopenharmony_ci</li> 4611cb0ef41Sopenharmony_ci<li><a href="#miscellaneous-utilities">Miscellaneous utilities</a> 4621cb0ef41Sopenharmony_ci<ul> 4631cb0ef41Sopenharmony_ci<li><a href="#node_api_get_module_file_name"><code>node_api_get_module_file_name</code></a></li> 4641cb0ef41Sopenharmony_ci</ul> 4651cb0ef41Sopenharmony_ci</li> 4661cb0ef41Sopenharmony_ci</ul> 4671cb0ef41Sopenharmony_ci</li> 4681cb0ef41Sopenharmony_ci</ul></div></div> 4691cb0ef41Sopenharmony_ci </li> 4701cb0ef41Sopenharmony_ci 4711cb0ef41Sopenharmony_ci 4721cb0ef41Sopenharmony_ci <li class="picker-header"> 4731cb0ef41Sopenharmony_ci <a href="#"> 4741cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 4751cb0ef41Sopenharmony_ci Index 4761cb0ef41Sopenharmony_ci </a> 4771cb0ef41Sopenharmony_ci 4781cb0ef41Sopenharmony_ci <div class="picker"><ul> 4791cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 4801cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 4811cb0ef41Sopenharmony_ci 4821cb0ef41Sopenharmony_ci <li> 4831cb0ef41Sopenharmony_ci <a href="index.html">Index</a> 4841cb0ef41Sopenharmony_ci </li> 4851cb0ef41Sopenharmony_ci </ul> 4861cb0ef41Sopenharmony_ci 4871cb0ef41Sopenharmony_ci<hr class="line"> 4881cb0ef41Sopenharmony_ci<ul> 4891cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 4901cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 4911cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 4921cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 4931cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 4941cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api active">C/C++ addons with Node-API</a></li> 4951cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 4961cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 4971cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 4981cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 4991cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 5001cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 5011cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 5021cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 5031cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 5041cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 5051cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 5061cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 5071cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 5081cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 5091cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 5101cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 5111cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 5121cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 5131cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 5141cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 5151cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 5161cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 5171cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 5181cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 5191cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 5201cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 5211cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 5221cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 5231cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 5241cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 5251cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 5261cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 5271cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 5281cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 5291cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 5301cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 5311cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 5321cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 5331cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 5341cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 5351cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 5361cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 5371cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 5381cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 5391cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 5401cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 5411cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 5421cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 5431cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 5441cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 5451cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 5461cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 5471cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 5481cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 5491cb0ef41Sopenharmony_ci</ul> 5501cb0ef41Sopenharmony_ci<hr class="line"> 5511cb0ef41Sopenharmony_ci<ul> 5521cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 5531cb0ef41Sopenharmony_ci</ul></div> 5541cb0ef41Sopenharmony_ci </li> 5551cb0ef41Sopenharmony_ci 5561cb0ef41Sopenharmony_ci 5571cb0ef41Sopenharmony_ci <li class="picker-header"> 5581cb0ef41Sopenharmony_ci <a href="#"> 5591cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 5601cb0ef41Sopenharmony_ci Other versions 5611cb0ef41Sopenharmony_ci </a> 5621cb0ef41Sopenharmony_ci <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v21.x/api/n-api.html">21.x</a></li> 5631cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v20.x/api/n-api.html">20.x <b>LTS</b></a></li> 5641cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v19.x/api/n-api.html">19.x</a></li> 5651cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v18.x/api/n-api.html">18.x <b>LTS</b></a></li> 5661cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v17.x/api/n-api.html">17.x</a></li> 5671cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v16.x/api/n-api.html">16.x</a></li> 5681cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v15.x/api/n-api.html">15.x</a></li> 5691cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v14.x/api/n-api.html">14.x</a></li> 5701cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v13.x/api/n-api.html">13.x</a></li> 5711cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v12.x/api/n-api.html">12.x</a></li> 5721cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v11.x/api/n-api.html">11.x</a></li> 5731cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v10.x/api/n-api.html">10.x</a></li> 5741cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v9.x/api/n-api.html">9.x</a></li> 5751cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v8.x/api/n-api.html">8.x</a></li></ol></div> 5761cb0ef41Sopenharmony_ci </li> 5771cb0ef41Sopenharmony_ci 5781cb0ef41Sopenharmony_ci <li class="picker-header"> 5791cb0ef41Sopenharmony_ci <a href="#"> 5801cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 5811cb0ef41Sopenharmony_ci Options 5821cb0ef41Sopenharmony_ci </a> 5831cb0ef41Sopenharmony_ci 5841cb0ef41Sopenharmony_ci <div class="picker"> 5851cb0ef41Sopenharmony_ci <ul> 5861cb0ef41Sopenharmony_ci <li> 5871cb0ef41Sopenharmony_ci <a href="all.html">View on single page</a> 5881cb0ef41Sopenharmony_ci </li> 5891cb0ef41Sopenharmony_ci <li> 5901cb0ef41Sopenharmony_ci <a href="n-api.json">View as JSON</a> 5911cb0ef41Sopenharmony_ci </li> 5921cb0ef41Sopenharmony_ci <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/n-api.md">Edit on GitHub</a></li> 5931cb0ef41Sopenharmony_ci </ul> 5941cb0ef41Sopenharmony_ci </div> 5951cb0ef41Sopenharmony_ci </li> 5961cb0ef41Sopenharmony_ci </ul> 5971cb0ef41Sopenharmony_ci </div> 5981cb0ef41Sopenharmony_ci <hr> 5991cb0ef41Sopenharmony_ci </header> 6001cb0ef41Sopenharmony_ci 6011cb0ef41Sopenharmony_ci <details id="toc" open><summary>Table of contents</summary><ul> 6021cb0ef41Sopenharmony_ci<li><span class="stability_2"><a href="#node-api">Node-API</a></span> 6031cb0ef41Sopenharmony_ci<ul> 6041cb0ef41Sopenharmony_ci<li><a href="#implications-of-abi-stability">Implications of ABI stability</a></li> 6051cb0ef41Sopenharmony_ci<li><a href="#building">Building</a> 6061cb0ef41Sopenharmony_ci<ul> 6071cb0ef41Sopenharmony_ci<li><a href="#build-tools">Build tools</a> 6081cb0ef41Sopenharmony_ci<ul> 6091cb0ef41Sopenharmony_ci<li><a href="#node-gyp">node-gyp</a></li> 6101cb0ef41Sopenharmony_ci<li><a href="#cmakejs">CMake.js</a></li> 6111cb0ef41Sopenharmony_ci</ul> 6121cb0ef41Sopenharmony_ci</li> 6131cb0ef41Sopenharmony_ci<li><a href="#uploading-precompiled-binaries">Uploading precompiled binaries</a> 6141cb0ef41Sopenharmony_ci<ul> 6151cb0ef41Sopenharmony_ci<li><a href="#node-pre-gyp">node-pre-gyp</a></li> 6161cb0ef41Sopenharmony_ci<li><a href="#prebuild">prebuild</a></li> 6171cb0ef41Sopenharmony_ci<li><a href="#prebuildify">prebuildify</a></li> 6181cb0ef41Sopenharmony_ci</ul> 6191cb0ef41Sopenharmony_ci</li> 6201cb0ef41Sopenharmony_ci</ul> 6211cb0ef41Sopenharmony_ci</li> 6221cb0ef41Sopenharmony_ci<li><a href="#usage">Usage</a></li> 6231cb0ef41Sopenharmony_ci<li><a href="#node-api-version-matrix">Node-API version matrix</a></li> 6241cb0ef41Sopenharmony_ci<li><a href="#environment-life-cycle-apis">Environment life cycle APIs</a> 6251cb0ef41Sopenharmony_ci<ul> 6261cb0ef41Sopenharmony_ci<li><a href="#napi_set_instance_data"><code>napi_set_instance_data</code></a></li> 6271cb0ef41Sopenharmony_ci<li><a href="#napi_get_instance_data"><code>napi_get_instance_data</code></a></li> 6281cb0ef41Sopenharmony_ci</ul> 6291cb0ef41Sopenharmony_ci</li> 6301cb0ef41Sopenharmony_ci<li><a href="#basic-node-api-data-types">Basic Node-API data types</a> 6311cb0ef41Sopenharmony_ci<ul> 6321cb0ef41Sopenharmony_ci<li><a href="#napi_status"><code>napi_status</code></a></li> 6331cb0ef41Sopenharmony_ci<li><a href="#napi_extended_error_info"><code>napi_extended_error_info</code></a></li> 6341cb0ef41Sopenharmony_ci<li><a href="#napi_env"><code>napi_env</code></a></li> 6351cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_nogc_env"><code>node_api_nogc_env</code></a></span></li> 6361cb0ef41Sopenharmony_ci<li><a href="#napi_value"><code>napi_value</code></a></li> 6371cb0ef41Sopenharmony_ci<li><a href="#napi_threadsafe_function"><code>napi_threadsafe_function</code></a></li> 6381cb0ef41Sopenharmony_ci<li><a href="#napi_threadsafe_function_release_mode"><code>napi_threadsafe_function_release_mode</code></a></li> 6391cb0ef41Sopenharmony_ci<li><a href="#napi_threadsafe_function_call_mode"><code>napi_threadsafe_function_call_mode</code></a></li> 6401cb0ef41Sopenharmony_ci<li><a href="#node-api-memory-management-types">Node-API memory management types</a> 6411cb0ef41Sopenharmony_ci<ul> 6421cb0ef41Sopenharmony_ci<li><a href="#napi_handle_scope"><code>napi_handle_scope</code></a></li> 6431cb0ef41Sopenharmony_ci<li><a href="#napi_escapable_handle_scope"><code>napi_escapable_handle_scope</code></a></li> 6441cb0ef41Sopenharmony_ci<li><a href="#napi_ref"><code>napi_ref</code></a></li> 6451cb0ef41Sopenharmony_ci<li><a href="#napi_type_tag"><code>napi_type_tag</code></a></li> 6461cb0ef41Sopenharmony_ci<li><a href="#napi_async_cleanup_hook_handle"><code>napi_async_cleanup_hook_handle</code></a></li> 6471cb0ef41Sopenharmony_ci</ul> 6481cb0ef41Sopenharmony_ci</li> 6491cb0ef41Sopenharmony_ci<li><a href="#node-api-callback-types">Node-API callback types</a> 6501cb0ef41Sopenharmony_ci<ul> 6511cb0ef41Sopenharmony_ci<li><a href="#napi_callback_info"><code>napi_callback_info</code></a></li> 6521cb0ef41Sopenharmony_ci<li><a href="#napi_callback"><code>napi_callback</code></a></li> 6531cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_nogc_finalize"><code>node_api_nogc_finalize</code></a></span></li> 6541cb0ef41Sopenharmony_ci<li><a href="#napi_finalize"><code>napi_finalize</code></a></li> 6551cb0ef41Sopenharmony_ci<li><a href="#napi_async_execute_callback"><code>napi_async_execute_callback</code></a></li> 6561cb0ef41Sopenharmony_ci<li><a href="#napi_async_complete_callback"><code>napi_async_complete_callback</code></a></li> 6571cb0ef41Sopenharmony_ci<li><a href="#napi_threadsafe_function_call_js"><code>napi_threadsafe_function_call_js</code></a></li> 6581cb0ef41Sopenharmony_ci<li><a href="#napi_cleanup_hook"><code>napi_cleanup_hook</code></a></li> 6591cb0ef41Sopenharmony_ci<li><a href="#napi_async_cleanup_hook"><code>napi_async_cleanup_hook</code></a></li> 6601cb0ef41Sopenharmony_ci</ul> 6611cb0ef41Sopenharmony_ci</li> 6621cb0ef41Sopenharmony_ci</ul> 6631cb0ef41Sopenharmony_ci</li> 6641cb0ef41Sopenharmony_ci<li><a href="#error-handling">Error handling</a> 6651cb0ef41Sopenharmony_ci<ul> 6661cb0ef41Sopenharmony_ci<li><a href="#return-values">Return values</a> 6671cb0ef41Sopenharmony_ci<ul> 6681cb0ef41Sopenharmony_ci<li><a href="#napi_get_last_error_info"><code>napi_get_last_error_info</code></a></li> 6691cb0ef41Sopenharmony_ci</ul> 6701cb0ef41Sopenharmony_ci</li> 6711cb0ef41Sopenharmony_ci<li><a href="#exceptions">Exceptions</a> 6721cb0ef41Sopenharmony_ci<ul> 6731cb0ef41Sopenharmony_ci<li><a href="#napi_throw"><code>napi_throw</code></a></li> 6741cb0ef41Sopenharmony_ci<li><a href="#napi_throw_error"><code>napi_throw_error</code></a></li> 6751cb0ef41Sopenharmony_ci<li><a href="#napi_throw_type_error"><code>napi_throw_type_error</code></a></li> 6761cb0ef41Sopenharmony_ci<li><a href="#napi_throw_range_error"><code>napi_throw_range_error</code></a></li> 6771cb0ef41Sopenharmony_ci<li><a href="#node_api_throw_syntax_error"><code>node_api_throw_syntax_error</code></a></li> 6781cb0ef41Sopenharmony_ci<li><a href="#napi_is_error"><code>napi_is_error</code></a></li> 6791cb0ef41Sopenharmony_ci<li><a href="#napi_create_error"><code>napi_create_error</code></a></li> 6801cb0ef41Sopenharmony_ci<li><a href="#napi_create_type_error"><code>napi_create_type_error</code></a></li> 6811cb0ef41Sopenharmony_ci<li><a href="#napi_create_range_error"><code>napi_create_range_error</code></a></li> 6821cb0ef41Sopenharmony_ci<li><a href="#node_api_create_syntax_error"><code>node_api_create_syntax_error</code></a></li> 6831cb0ef41Sopenharmony_ci<li><a href="#napi_get_and_clear_last_exception"><code>napi_get_and_clear_last_exception</code></a></li> 6841cb0ef41Sopenharmony_ci<li><a href="#napi_is_exception_pending"><code>napi_is_exception_pending</code></a></li> 6851cb0ef41Sopenharmony_ci<li><a href="#napi_fatal_exception"><code>napi_fatal_exception</code></a></li> 6861cb0ef41Sopenharmony_ci</ul> 6871cb0ef41Sopenharmony_ci</li> 6881cb0ef41Sopenharmony_ci<li><a href="#fatal-errors">Fatal errors</a> 6891cb0ef41Sopenharmony_ci<ul> 6901cb0ef41Sopenharmony_ci<li><a href="#napi_fatal_error"><code>napi_fatal_error</code></a></li> 6911cb0ef41Sopenharmony_ci</ul> 6921cb0ef41Sopenharmony_ci</li> 6931cb0ef41Sopenharmony_ci</ul> 6941cb0ef41Sopenharmony_ci</li> 6951cb0ef41Sopenharmony_ci<li><a href="#object-lifetime-management">Object lifetime management</a> 6961cb0ef41Sopenharmony_ci<ul> 6971cb0ef41Sopenharmony_ci<li><a href="#making-handle-lifespan-shorter-than-that-of-the-native-method">Making handle lifespan shorter than that of the native method</a> 6981cb0ef41Sopenharmony_ci<ul> 6991cb0ef41Sopenharmony_ci<li><a href="#napi_open_handle_scope"><code>napi_open_handle_scope</code></a></li> 7001cb0ef41Sopenharmony_ci<li><a href="#napi_close_handle_scope"><code>napi_close_handle_scope</code></a></li> 7011cb0ef41Sopenharmony_ci<li><a href="#napi_open_escapable_handle_scope"><code>napi_open_escapable_handle_scope</code></a></li> 7021cb0ef41Sopenharmony_ci<li><a href="#napi_close_escapable_handle_scope"><code>napi_close_escapable_handle_scope</code></a></li> 7031cb0ef41Sopenharmony_ci<li><a href="#napi_escape_handle"><code>napi_escape_handle</code></a></li> 7041cb0ef41Sopenharmony_ci</ul> 7051cb0ef41Sopenharmony_ci</li> 7061cb0ef41Sopenharmony_ci<li><a href="#references-to-values-with-a-lifespan-longer-than-that-of-the-native-method">References to values with a lifespan longer than that of the native method</a> 7071cb0ef41Sopenharmony_ci<ul> 7081cb0ef41Sopenharmony_ci<li><a href="#napi_create_reference"><code>napi_create_reference</code></a></li> 7091cb0ef41Sopenharmony_ci<li><a href="#napi_delete_reference"><code>napi_delete_reference</code></a></li> 7101cb0ef41Sopenharmony_ci<li><a href="#napi_reference_ref"><code>napi_reference_ref</code></a></li> 7111cb0ef41Sopenharmony_ci<li><a href="#napi_reference_unref"><code>napi_reference_unref</code></a></li> 7121cb0ef41Sopenharmony_ci<li><a href="#napi_get_reference_value"><code>napi_get_reference_value</code></a></li> 7131cb0ef41Sopenharmony_ci</ul> 7141cb0ef41Sopenharmony_ci</li> 7151cb0ef41Sopenharmony_ci<li><a href="#cleanup-on-exit-of-the-current-nodejs-environment">Cleanup on exit of the current Node.js environment</a> 7161cb0ef41Sopenharmony_ci<ul> 7171cb0ef41Sopenharmony_ci<li><a href="#napi_add_env_cleanup_hook"><code>napi_add_env_cleanup_hook</code></a></li> 7181cb0ef41Sopenharmony_ci<li><a href="#napi_remove_env_cleanup_hook"><code>napi_remove_env_cleanup_hook</code></a></li> 7191cb0ef41Sopenharmony_ci<li><a href="#napi_add_async_cleanup_hook"><code>napi_add_async_cleanup_hook</code></a></li> 7201cb0ef41Sopenharmony_ci<li><a href="#napi_remove_async_cleanup_hook"><code>napi_remove_async_cleanup_hook</code></a></li> 7211cb0ef41Sopenharmony_ci</ul> 7221cb0ef41Sopenharmony_ci</li> 7231cb0ef41Sopenharmony_ci<li><a href="#finalization-on-the-exit-of-the-nodejs-environment">Finalization on the exit of the Node.js environment</a></li> 7241cb0ef41Sopenharmony_ci</ul> 7251cb0ef41Sopenharmony_ci</li> 7261cb0ef41Sopenharmony_ci<li><a href="#module-registration">Module registration</a></li> 7271cb0ef41Sopenharmony_ci<li><a href="#working-with-javascript-values">Working with JavaScript values</a> 7281cb0ef41Sopenharmony_ci<ul> 7291cb0ef41Sopenharmony_ci<li><a href="#enum-types">Enum types</a> 7301cb0ef41Sopenharmony_ci<ul> 7311cb0ef41Sopenharmony_ci<li><a href="#napi_key_collection_mode"><code>napi_key_collection_mode</code></a></li> 7321cb0ef41Sopenharmony_ci<li><a href="#napi_key_filter"><code>napi_key_filter</code></a></li> 7331cb0ef41Sopenharmony_ci<li><a href="#napi_key_conversion"><code>napi_key_conversion</code></a></li> 7341cb0ef41Sopenharmony_ci<li><a href="#napi_valuetype"><code>napi_valuetype</code></a></li> 7351cb0ef41Sopenharmony_ci<li><a href="#napi_typedarray_type"><code>napi_typedarray_type</code></a></li> 7361cb0ef41Sopenharmony_ci</ul> 7371cb0ef41Sopenharmony_ci</li> 7381cb0ef41Sopenharmony_ci<li><a href="#object-creation-functions">Object creation functions</a> 7391cb0ef41Sopenharmony_ci<ul> 7401cb0ef41Sopenharmony_ci<li><a href="#napi_create_array"><code>napi_create_array</code></a></li> 7411cb0ef41Sopenharmony_ci<li><a href="#napi_create_array_with_length"><code>napi_create_array_with_length</code></a></li> 7421cb0ef41Sopenharmony_ci<li><a href="#napi_create_arraybuffer"><code>napi_create_arraybuffer</code></a></li> 7431cb0ef41Sopenharmony_ci<li><a href="#napi_create_buffer"><code>napi_create_buffer</code></a></li> 7441cb0ef41Sopenharmony_ci<li><a href="#napi_create_buffer_copy"><code>napi_create_buffer_copy</code></a></li> 7451cb0ef41Sopenharmony_ci<li><a href="#napi_create_date"><code>napi_create_date</code></a></li> 7461cb0ef41Sopenharmony_ci<li><a href="#napi_create_external"><code>napi_create_external</code></a></li> 7471cb0ef41Sopenharmony_ci<li><a href="#napi_create_external_arraybuffer"><code>napi_create_external_arraybuffer</code></a></li> 7481cb0ef41Sopenharmony_ci<li><a href="#napi_create_external_buffer"><code>napi_create_external_buffer</code></a></li> 7491cb0ef41Sopenharmony_ci<li><a href="#napi_create_object"><code>napi_create_object</code></a></li> 7501cb0ef41Sopenharmony_ci<li><a href="#napi_create_symbol"><code>napi_create_symbol</code></a></li> 7511cb0ef41Sopenharmony_ci<li><a href="#node_api_symbol_for"><code>node_api_symbol_for</code></a></li> 7521cb0ef41Sopenharmony_ci<li><a href="#napi_create_typedarray"><code>napi_create_typedarray</code></a></li> 7531cb0ef41Sopenharmony_ci<li><a href="#napi_create_dataview"><code>napi_create_dataview</code></a></li> 7541cb0ef41Sopenharmony_ci</ul> 7551cb0ef41Sopenharmony_ci</li> 7561cb0ef41Sopenharmony_ci<li><a href="#functions-to-convert-from-c-types-to-node-api">Functions to convert from C types to Node-API</a> 7571cb0ef41Sopenharmony_ci<ul> 7581cb0ef41Sopenharmony_ci<li><a href="#napi_create_int32"><code>napi_create_int32</code></a></li> 7591cb0ef41Sopenharmony_ci<li><a href="#napi_create_uint32"><code>napi_create_uint32</code></a></li> 7601cb0ef41Sopenharmony_ci<li><a href="#napi_create_int64"><code>napi_create_int64</code></a></li> 7611cb0ef41Sopenharmony_ci<li><a href="#napi_create_double"><code>napi_create_double</code></a></li> 7621cb0ef41Sopenharmony_ci<li><a href="#napi_create_bigint_int64"><code>napi_create_bigint_int64</code></a></li> 7631cb0ef41Sopenharmony_ci<li><a href="#napi_create_bigint_uint64"><code>napi_create_bigint_uint64</code></a></li> 7641cb0ef41Sopenharmony_ci<li><a href="#napi_create_bigint_words"><code>napi_create_bigint_words</code></a></li> 7651cb0ef41Sopenharmony_ci<li><a href="#napi_create_string_latin1"><code>napi_create_string_latin1</code></a></li> 7661cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_create_external_string_latin1"><code>node_api_create_external_string_latin1</code></a></span></li> 7671cb0ef41Sopenharmony_ci<li><a href="#napi_create_string_utf16"><code>napi_create_string_utf16</code></a></li> 7681cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_create_external_string_utf16"><code>node_api_create_external_string_utf16</code></a></span></li> 7691cb0ef41Sopenharmony_ci<li><a href="#napi_create_string_utf8"><code>napi_create_string_utf8</code></a></li> 7701cb0ef41Sopenharmony_ci</ul> 7711cb0ef41Sopenharmony_ci</li> 7721cb0ef41Sopenharmony_ci<li><a href="#functions-to-convert-from-node-api-to-c-types">Functions to convert from Node-API to C types</a> 7731cb0ef41Sopenharmony_ci<ul> 7741cb0ef41Sopenharmony_ci<li><a href="#napi_get_array_length"><code>napi_get_array_length</code></a></li> 7751cb0ef41Sopenharmony_ci<li><a href="#napi_get_arraybuffer_info"><code>napi_get_arraybuffer_info</code></a></li> 7761cb0ef41Sopenharmony_ci<li><a href="#napi_get_buffer_info"><code>napi_get_buffer_info</code></a></li> 7771cb0ef41Sopenharmony_ci<li><a href="#napi_get_prototype"><code>napi_get_prototype</code></a></li> 7781cb0ef41Sopenharmony_ci<li><a href="#napi_get_typedarray_info"><code>napi_get_typedarray_info</code></a></li> 7791cb0ef41Sopenharmony_ci<li><a href="#napi_get_dataview_info"><code>napi_get_dataview_info</code></a></li> 7801cb0ef41Sopenharmony_ci<li><a href="#napi_get_date_value"><code>napi_get_date_value</code></a></li> 7811cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_bool"><code>napi_get_value_bool</code></a></li> 7821cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_double"><code>napi_get_value_double</code></a></li> 7831cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_bigint_int64"><code>napi_get_value_bigint_int64</code></a></li> 7841cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_bigint_uint64"><code>napi_get_value_bigint_uint64</code></a></li> 7851cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_bigint_words"><code>napi_get_value_bigint_words</code></a></li> 7861cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_external"><code>napi_get_value_external</code></a></li> 7871cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_int32"><code>napi_get_value_int32</code></a></li> 7881cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_int64"><code>napi_get_value_int64</code></a></li> 7891cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_string_latin1"><code>napi_get_value_string_latin1</code></a></li> 7901cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_string_utf8"><code>napi_get_value_string_utf8</code></a></li> 7911cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_string_utf16"><code>napi_get_value_string_utf16</code></a></li> 7921cb0ef41Sopenharmony_ci<li><a href="#napi_get_value_uint32"><code>napi_get_value_uint32</code></a></li> 7931cb0ef41Sopenharmony_ci</ul> 7941cb0ef41Sopenharmony_ci</li> 7951cb0ef41Sopenharmony_ci<li><a href="#functions-to-get-global-instances">Functions to get global instances</a> 7961cb0ef41Sopenharmony_ci<ul> 7971cb0ef41Sopenharmony_ci<li><a href="#napi_get_boolean"><code>napi_get_boolean</code></a></li> 7981cb0ef41Sopenharmony_ci<li><a href="#napi_get_global"><code>napi_get_global</code></a></li> 7991cb0ef41Sopenharmony_ci<li><a href="#napi_get_null"><code>napi_get_null</code></a></li> 8001cb0ef41Sopenharmony_ci<li><a href="#napi_get_undefined"><code>napi_get_undefined</code></a></li> 8011cb0ef41Sopenharmony_ci</ul> 8021cb0ef41Sopenharmony_ci</li> 8031cb0ef41Sopenharmony_ci</ul> 8041cb0ef41Sopenharmony_ci</li> 8051cb0ef41Sopenharmony_ci<li><a href="#working-with-javascript-values-and-abstract-operations">Working with JavaScript values and abstract operations</a> 8061cb0ef41Sopenharmony_ci<ul> 8071cb0ef41Sopenharmony_ci<li><a href="#napi_coerce_to_bool"><code>napi_coerce_to_bool</code></a></li> 8081cb0ef41Sopenharmony_ci<li><a href="#napi_coerce_to_number"><code>napi_coerce_to_number</code></a></li> 8091cb0ef41Sopenharmony_ci<li><a href="#napi_coerce_to_object"><code>napi_coerce_to_object</code></a></li> 8101cb0ef41Sopenharmony_ci<li><a href="#napi_coerce_to_string"><code>napi_coerce_to_string</code></a></li> 8111cb0ef41Sopenharmony_ci<li><a href="#napi_typeof"><code>napi_typeof</code></a></li> 8121cb0ef41Sopenharmony_ci<li><a href="#napi_instanceof"><code>napi_instanceof</code></a></li> 8131cb0ef41Sopenharmony_ci<li><a href="#napi_is_array"><code>napi_is_array</code></a></li> 8141cb0ef41Sopenharmony_ci<li><a href="#napi_is_arraybuffer"><code>napi_is_arraybuffer</code></a></li> 8151cb0ef41Sopenharmony_ci<li><a href="#napi_is_buffer"><code>napi_is_buffer</code></a></li> 8161cb0ef41Sopenharmony_ci<li><a href="#napi_is_date"><code>napi_is_date</code></a></li> 8171cb0ef41Sopenharmony_ci<li><a href="#napi_is_error_1"><code>napi_is_error</code></a></li> 8181cb0ef41Sopenharmony_ci<li><a href="#napi_is_typedarray"><code>napi_is_typedarray</code></a></li> 8191cb0ef41Sopenharmony_ci<li><a href="#napi_is_dataview"><code>napi_is_dataview</code></a></li> 8201cb0ef41Sopenharmony_ci<li><a href="#napi_strict_equals"><code>napi_strict_equals</code></a></li> 8211cb0ef41Sopenharmony_ci<li><a href="#napi_detach_arraybuffer"><code>napi_detach_arraybuffer</code></a></li> 8221cb0ef41Sopenharmony_ci<li><a href="#napi_is_detached_arraybuffer"><code>napi_is_detached_arraybuffer</code></a></li> 8231cb0ef41Sopenharmony_ci</ul> 8241cb0ef41Sopenharmony_ci</li> 8251cb0ef41Sopenharmony_ci<li><a href="#working-with-javascript-properties">Working with JavaScript properties</a> 8261cb0ef41Sopenharmony_ci<ul> 8271cb0ef41Sopenharmony_ci<li><a href="#structures">Structures</a> 8281cb0ef41Sopenharmony_ci<ul> 8291cb0ef41Sopenharmony_ci<li><a href="#napi_property_attributes"><code>napi_property_attributes</code></a></li> 8301cb0ef41Sopenharmony_ci<li><a href="#napi_property_descriptor"><code>napi_property_descriptor</code></a></li> 8311cb0ef41Sopenharmony_ci</ul> 8321cb0ef41Sopenharmony_ci</li> 8331cb0ef41Sopenharmony_ci<li><a href="#functions">Functions</a> 8341cb0ef41Sopenharmony_ci<ul> 8351cb0ef41Sopenharmony_ci<li><a href="#napi_get_property_names"><code>napi_get_property_names</code></a></li> 8361cb0ef41Sopenharmony_ci<li><a href="#napi_get_all_property_names"><code>napi_get_all_property_names</code></a></li> 8371cb0ef41Sopenharmony_ci<li><a href="#napi_set_property"><code>napi_set_property</code></a></li> 8381cb0ef41Sopenharmony_ci<li><a href="#napi_get_property"><code>napi_get_property</code></a></li> 8391cb0ef41Sopenharmony_ci<li><a href="#napi_has_property"><code>napi_has_property</code></a></li> 8401cb0ef41Sopenharmony_ci<li><a href="#napi_delete_property"><code>napi_delete_property</code></a></li> 8411cb0ef41Sopenharmony_ci<li><a href="#napi_has_own_property"><code>napi_has_own_property</code></a></li> 8421cb0ef41Sopenharmony_ci<li><a href="#napi_set_named_property"><code>napi_set_named_property</code></a></li> 8431cb0ef41Sopenharmony_ci<li><a href="#napi_get_named_property"><code>napi_get_named_property</code></a></li> 8441cb0ef41Sopenharmony_ci<li><a href="#napi_has_named_property"><code>napi_has_named_property</code></a></li> 8451cb0ef41Sopenharmony_ci<li><a href="#napi_set_element"><code>napi_set_element</code></a></li> 8461cb0ef41Sopenharmony_ci<li><a href="#napi_get_element"><code>napi_get_element</code></a></li> 8471cb0ef41Sopenharmony_ci<li><a href="#napi_has_element"><code>napi_has_element</code></a></li> 8481cb0ef41Sopenharmony_ci<li><a href="#napi_delete_element"><code>napi_delete_element</code></a></li> 8491cb0ef41Sopenharmony_ci<li><a href="#napi_define_properties"><code>napi_define_properties</code></a></li> 8501cb0ef41Sopenharmony_ci<li><a href="#napi_object_freeze"><code>napi_object_freeze</code></a></li> 8511cb0ef41Sopenharmony_ci<li><a href="#napi_object_seal"><code>napi_object_seal</code></a></li> 8521cb0ef41Sopenharmony_ci</ul> 8531cb0ef41Sopenharmony_ci</li> 8541cb0ef41Sopenharmony_ci</ul> 8551cb0ef41Sopenharmony_ci</li> 8561cb0ef41Sopenharmony_ci<li><a href="#working-with-javascript-functions">Working with JavaScript functions</a> 8571cb0ef41Sopenharmony_ci<ul> 8581cb0ef41Sopenharmony_ci<li><a href="#napi_call_function"><code>napi_call_function</code></a></li> 8591cb0ef41Sopenharmony_ci<li><a href="#napi_create_function"><code>napi_create_function</code></a></li> 8601cb0ef41Sopenharmony_ci<li><a href="#napi_get_cb_info"><code>napi_get_cb_info</code></a></li> 8611cb0ef41Sopenharmony_ci<li><a href="#napi_get_new_target"><code>napi_get_new_target</code></a></li> 8621cb0ef41Sopenharmony_ci<li><a href="#napi_new_instance"><code>napi_new_instance</code></a></li> 8631cb0ef41Sopenharmony_ci</ul> 8641cb0ef41Sopenharmony_ci</li> 8651cb0ef41Sopenharmony_ci<li><a href="#object-wrap">Object wrap</a> 8661cb0ef41Sopenharmony_ci<ul> 8671cb0ef41Sopenharmony_ci<li><a href="#napi_define_class"><code>napi_define_class</code></a></li> 8681cb0ef41Sopenharmony_ci<li><a href="#napi_wrap"><code>napi_wrap</code></a></li> 8691cb0ef41Sopenharmony_ci<li><a href="#napi_unwrap"><code>napi_unwrap</code></a></li> 8701cb0ef41Sopenharmony_ci<li><a href="#napi_remove_wrap"><code>napi_remove_wrap</code></a></li> 8711cb0ef41Sopenharmony_ci<li><a href="#napi_type_tag_object"><code>napi_type_tag_object</code></a></li> 8721cb0ef41Sopenharmony_ci<li><a href="#napi_check_object_type_tag"><code>napi_check_object_type_tag</code></a></li> 8731cb0ef41Sopenharmony_ci<li><a href="#napi_add_finalizer"><code>napi_add_finalizer</code></a> 8741cb0ef41Sopenharmony_ci<ul> 8751cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#node_api_post_finalizer"><code>node_api_post_finalizer</code></a></span></li> 8761cb0ef41Sopenharmony_ci</ul> 8771cb0ef41Sopenharmony_ci</li> 8781cb0ef41Sopenharmony_ci</ul> 8791cb0ef41Sopenharmony_ci</li> 8801cb0ef41Sopenharmony_ci<li><a href="#simple-asynchronous-operations">Simple asynchronous operations</a> 8811cb0ef41Sopenharmony_ci<ul> 8821cb0ef41Sopenharmony_ci<li><a href="#napi_create_async_work"><code>napi_create_async_work</code></a></li> 8831cb0ef41Sopenharmony_ci<li><a href="#napi_delete_async_work"><code>napi_delete_async_work</code></a></li> 8841cb0ef41Sopenharmony_ci<li><a href="#napi_queue_async_work"><code>napi_queue_async_work</code></a></li> 8851cb0ef41Sopenharmony_ci<li><a href="#napi_cancel_async_work"><code>napi_cancel_async_work</code></a></li> 8861cb0ef41Sopenharmony_ci</ul> 8871cb0ef41Sopenharmony_ci</li> 8881cb0ef41Sopenharmony_ci<li><a href="#custom-asynchronous-operations">Custom asynchronous operations</a> 8891cb0ef41Sopenharmony_ci<ul> 8901cb0ef41Sopenharmony_ci<li><a href="#napi_async_init"><code>napi_async_init</code></a></li> 8911cb0ef41Sopenharmony_ci<li><a href="#napi_async_destroy"><code>napi_async_destroy</code></a></li> 8921cb0ef41Sopenharmony_ci<li><a href="#napi_make_callback"><code>napi_make_callback</code></a></li> 8931cb0ef41Sopenharmony_ci<li><a href="#napi_open_callback_scope"><code>napi_open_callback_scope</code></a></li> 8941cb0ef41Sopenharmony_ci<li><a href="#napi_close_callback_scope"><code>napi_close_callback_scope</code></a></li> 8951cb0ef41Sopenharmony_ci</ul> 8961cb0ef41Sopenharmony_ci</li> 8971cb0ef41Sopenharmony_ci<li><a href="#version-management">Version management</a> 8981cb0ef41Sopenharmony_ci<ul> 8991cb0ef41Sopenharmony_ci<li><a href="#napi_get_node_version"><code>napi_get_node_version</code></a></li> 9001cb0ef41Sopenharmony_ci<li><a href="#napi_get_version"><code>napi_get_version</code></a></li> 9011cb0ef41Sopenharmony_ci</ul> 9021cb0ef41Sopenharmony_ci</li> 9031cb0ef41Sopenharmony_ci<li><a href="#memory-management">Memory management</a> 9041cb0ef41Sopenharmony_ci<ul> 9051cb0ef41Sopenharmony_ci<li><a href="#napi_adjust_external_memory"><code>napi_adjust_external_memory</code></a></li> 9061cb0ef41Sopenharmony_ci</ul> 9071cb0ef41Sopenharmony_ci</li> 9081cb0ef41Sopenharmony_ci<li><a href="#promises">Promises</a> 9091cb0ef41Sopenharmony_ci<ul> 9101cb0ef41Sopenharmony_ci<li><a href="#napi_create_promise"><code>napi_create_promise</code></a></li> 9111cb0ef41Sopenharmony_ci<li><a href="#napi_resolve_deferred"><code>napi_resolve_deferred</code></a></li> 9121cb0ef41Sopenharmony_ci<li><a href="#napi_reject_deferred"><code>napi_reject_deferred</code></a></li> 9131cb0ef41Sopenharmony_ci<li><a href="#napi_is_promise"><code>napi_is_promise</code></a></li> 9141cb0ef41Sopenharmony_ci</ul> 9151cb0ef41Sopenharmony_ci</li> 9161cb0ef41Sopenharmony_ci<li><a href="#script-execution">Script execution</a> 9171cb0ef41Sopenharmony_ci<ul> 9181cb0ef41Sopenharmony_ci<li><a href="#napi_run_script"><code>napi_run_script</code></a></li> 9191cb0ef41Sopenharmony_ci</ul> 9201cb0ef41Sopenharmony_ci</li> 9211cb0ef41Sopenharmony_ci<li><a href="#libuv-event-loop">libuv event loop</a> 9221cb0ef41Sopenharmony_ci<ul> 9231cb0ef41Sopenharmony_ci<li><a href="#napi_get_uv_event_loop"><code>napi_get_uv_event_loop</code></a></li> 9241cb0ef41Sopenharmony_ci</ul> 9251cb0ef41Sopenharmony_ci</li> 9261cb0ef41Sopenharmony_ci<li><a href="#asynchronous-thread-safe-function-calls">Asynchronous thread-safe function calls</a> 9271cb0ef41Sopenharmony_ci<ul> 9281cb0ef41Sopenharmony_ci<li><a href="#calling-a-thread-safe-function">Calling a thread-safe function</a></li> 9291cb0ef41Sopenharmony_ci<li><a href="#reference-counting-of-thread-safe-functions">Reference counting of thread-safe functions</a></li> 9301cb0ef41Sopenharmony_ci<li><a href="#deciding-whether-to-keep-the-process-running">Deciding whether to keep the process running</a></li> 9311cb0ef41Sopenharmony_ci<li><a href="#napi_create_threadsafe_function"><code>napi_create_threadsafe_function</code></a></li> 9321cb0ef41Sopenharmony_ci<li><a href="#napi_get_threadsafe_function_context"><code>napi_get_threadsafe_function_context</code></a></li> 9331cb0ef41Sopenharmony_ci<li><a href="#napi_call_threadsafe_function"><code>napi_call_threadsafe_function</code></a></li> 9341cb0ef41Sopenharmony_ci<li><a href="#napi_acquire_threadsafe_function"><code>napi_acquire_threadsafe_function</code></a></li> 9351cb0ef41Sopenharmony_ci<li><a href="#napi_release_threadsafe_function"><code>napi_release_threadsafe_function</code></a></li> 9361cb0ef41Sopenharmony_ci<li><a href="#napi_ref_threadsafe_function"><code>napi_ref_threadsafe_function</code></a></li> 9371cb0ef41Sopenharmony_ci<li><a href="#napi_unref_threadsafe_function"><code>napi_unref_threadsafe_function</code></a></li> 9381cb0ef41Sopenharmony_ci</ul> 9391cb0ef41Sopenharmony_ci</li> 9401cb0ef41Sopenharmony_ci<li><a href="#miscellaneous-utilities">Miscellaneous utilities</a> 9411cb0ef41Sopenharmony_ci<ul> 9421cb0ef41Sopenharmony_ci<li><a href="#node_api_get_module_file_name"><code>node_api_get_module_file_name</code></a></li> 9431cb0ef41Sopenharmony_ci</ul> 9441cb0ef41Sopenharmony_ci</li> 9451cb0ef41Sopenharmony_ci</ul> 9461cb0ef41Sopenharmony_ci</li> 9471cb0ef41Sopenharmony_ci</ul></details> 9481cb0ef41Sopenharmony_ci 9491cb0ef41Sopenharmony_ci <div id="apicontent"> 9501cb0ef41Sopenharmony_ci <h2>Node-API<span><a class="mark" href="#node-api" id="node-api">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api"></a></h2> 9511cb0ef41Sopenharmony_ci 9521cb0ef41Sopenharmony_ci 9531cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_2"><a href="documentation.html#stability-index">Stability: 2</a> - Stable</div><p></p> 9541cb0ef41Sopenharmony_ci<p>Node-API (formerly N-API) is an API for building native Addons. It is 9551cb0ef41Sopenharmony_ciindependent from the underlying JavaScript runtime (for example, V8) and is 9561cb0ef41Sopenharmony_cimaintained as part of Node.js itself. This API will be Application Binary 9571cb0ef41Sopenharmony_ciInterface (ABI) stable across versions of Node.js. It is intended to insulate 9581cb0ef41Sopenharmony_ciaddons from changes in the underlying JavaScript engine and allow modules 9591cb0ef41Sopenharmony_cicompiled for one major version to run on later major versions of Node.js without 9601cb0ef41Sopenharmony_cirecompilation. The <a href="https://nodejs.org/en/docs/guides/abi-stability/">ABI Stability</a> guide provides a more in-depth explanation.</p> 9611cb0ef41Sopenharmony_ci<p>Addons are built/packaged with the same approach/tools outlined in the section 9621cb0ef41Sopenharmony_cititled <a href="addons.html">C++ Addons</a>. The only difference is the set of APIs that are used by 9631cb0ef41Sopenharmony_cithe native code. Instead of using the V8 or <a href="https://github.com/nodejs/nan">Native Abstractions for Node.js</a> 9641cb0ef41Sopenharmony_ciAPIs, the functions available in Node-API are used.</p> 9651cb0ef41Sopenharmony_ci<p>APIs exposed by Node-API are generally used to create and manipulate 9661cb0ef41Sopenharmony_ciJavaScript values. Concepts and operations generally map to ideas specified 9671cb0ef41Sopenharmony_ciin the ECMA-262 Language Specification. The APIs have the following 9681cb0ef41Sopenharmony_ciproperties:</p> 9691cb0ef41Sopenharmony_ci<ul> 9701cb0ef41Sopenharmony_ci<li>All Node-API calls return a status code of type <code>napi_status</code>. This 9711cb0ef41Sopenharmony_cistatus indicates whether the API call succeeded or failed.</li> 9721cb0ef41Sopenharmony_ci<li>The API's return value is passed via an out parameter.</li> 9731cb0ef41Sopenharmony_ci<li>All JavaScript values are abstracted behind an opaque type named 9741cb0ef41Sopenharmony_ci<code>napi_value</code>.</li> 9751cb0ef41Sopenharmony_ci<li>In case of an error status code, additional information can be obtained 9761cb0ef41Sopenharmony_ciusing <code>napi_get_last_error_info</code>. More information can be found in the error 9771cb0ef41Sopenharmony_cihandling section <a href="#error-handling">Error handling</a>.</li> 9781cb0ef41Sopenharmony_ci</ul> 9791cb0ef41Sopenharmony_ci<p>Node-API is a C API that ensures ABI stability across Node.js versions 9801cb0ef41Sopenharmony_ciand different compiler levels. A C++ API can be easier to use. 9811cb0ef41Sopenharmony_ciTo support using C++, the project maintains a 9821cb0ef41Sopenharmony_ciC++ wrapper module called <a href="https://github.com/nodejs/node-addon-api"><code>node-addon-api</code></a>. 9831cb0ef41Sopenharmony_ciThis wrapper provides an inlinable C++ API. Binaries built 9841cb0ef41Sopenharmony_ciwith <code>node-addon-api</code> will depend on the symbols for the Node-API C-based 9851cb0ef41Sopenharmony_cifunctions exported by Node.js. <code>node-addon-api</code> is a more 9861cb0ef41Sopenharmony_ciefficient way to write code that calls Node-API. Take, for example, the 9871cb0ef41Sopenharmony_cifollowing <code>node-addon-api</code> code. The first section shows the 9881cb0ef41Sopenharmony_ci<code>node-addon-api</code> code and the second section shows what actually gets 9891cb0ef41Sopenharmony_ciused in the addon.</p> 9901cb0ef41Sopenharmony_ci<pre><code class="language-cpp">Object obj = Object::<span class="hljs-built_in">New</span>(env); 9911cb0ef41Sopenharmony_ciobj[<span class="hljs-string">"foo"</span>] = String::<span class="hljs-built_in">New</span>(env, <span class="hljs-string">"bar"</span>);</code> <button class="copy-button">copy</button></pre> 9921cb0ef41Sopenharmony_ci<pre><code class="language-cpp">napi_status status; 9931cb0ef41Sopenharmony_cinapi_value object, string; 9941cb0ef41Sopenharmony_cistatus = <span class="hljs-built_in">napi_create_object</span>(env, &object); 9951cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) { 9961cb0ef41Sopenharmony_ci <span class="hljs-built_in">napi_throw_error</span>(env, ...); 9971cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span>; 9981cb0ef41Sopenharmony_ci} 9991cb0ef41Sopenharmony_ci 10001cb0ef41Sopenharmony_cistatus = <span class="hljs-built_in">napi_create_string_utf8</span>(env, <span class="hljs-string">"bar"</span>, NAPI_AUTO_LENGTH, &string); 10011cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) { 10021cb0ef41Sopenharmony_ci <span class="hljs-built_in">napi_throw_error</span>(env, ...); 10031cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span>; 10041cb0ef41Sopenharmony_ci} 10051cb0ef41Sopenharmony_ci 10061cb0ef41Sopenharmony_cistatus = <span class="hljs-built_in">napi_set_named_property</span>(env, object, <span class="hljs-string">"foo"</span>, string); 10071cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) { 10081cb0ef41Sopenharmony_ci <span class="hljs-built_in">napi_throw_error</span>(env, ...); 10091cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span>; 10101cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 10111cb0ef41Sopenharmony_ci<p>The end result is that the addon only uses the exported C APIs. As a result, 10121cb0ef41Sopenharmony_ciit still gets the benefits of the ABI stability provided by the C API.</p> 10131cb0ef41Sopenharmony_ci<p>When using <code>node-addon-api</code> instead of the C APIs, start with the API <a href="https://github.com/nodejs/node-addon-api#api-documentation">docs</a> 10141cb0ef41Sopenharmony_cifor <code>node-addon-api</code>.</p> 10151cb0ef41Sopenharmony_ci<p>The <a href="https://nodejs.github.io/node-addon-examples/">Node-API Resource</a> offers 10161cb0ef41Sopenharmony_cian excellent orientation and tips for developers just getting started with 10171cb0ef41Sopenharmony_ciNode-API and <code>node-addon-api</code>. Additional media resources can be found on the 10181cb0ef41Sopenharmony_ci<a href="https://github.com/nodejs/abi-stable-node/blob/HEAD/node-api-media.md">Node-API Media</a> page.</p> 10191cb0ef41Sopenharmony_ci<section><h3>Implications of ABI stability<span><a class="mark" href="#implications-of-abi-stability" id="implications-of-abi-stability">#</a></span><a aria-hidden="true" class="legacy" id="n_api_implications_of_abi_stability"></a></h3> 10201cb0ef41Sopenharmony_ci<p>Although Node-API provides an ABI stability guarantee, other parts of Node.js do 10211cb0ef41Sopenharmony_cinot, and any external libraries used from the addon may not. In particular, 10221cb0ef41Sopenharmony_cinone of the following APIs provide an ABI stability guarantee across major 10231cb0ef41Sopenharmony_civersions:</p> 10241cb0ef41Sopenharmony_ci<ul> 10251cb0ef41Sopenharmony_ci<li> 10261cb0ef41Sopenharmony_ci<p>the Node.js C++ APIs available via any of</p> 10271cb0ef41Sopenharmony_ci<pre><code class="language-cpp"><span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node.h></span></span> 10281cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_buffer.h></span></span> 10291cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_version.h></span></span> 10301cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_object_wrap.h></span></span></code> <button class="copy-button">copy</button></pre> 10311cb0ef41Sopenharmony_ci</li> 10321cb0ef41Sopenharmony_ci<li> 10331cb0ef41Sopenharmony_ci<p>the libuv APIs which are also included with Node.js and available via</p> 10341cb0ef41Sopenharmony_ci<pre><code class="language-cpp"><span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><uv.h></span></span></code> <button class="copy-button">copy</button></pre> 10351cb0ef41Sopenharmony_ci</li> 10361cb0ef41Sopenharmony_ci<li> 10371cb0ef41Sopenharmony_ci<p>the V8 API available via</p> 10381cb0ef41Sopenharmony_ci<pre><code class="language-cpp"><span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><v8.h></span></span></code> <button class="copy-button">copy</button></pre> 10391cb0ef41Sopenharmony_ci</li> 10401cb0ef41Sopenharmony_ci</ul> 10411cb0ef41Sopenharmony_ci<p>Thus, for an addon to remain ABI-compatible across Node.js major versions, it 10421cb0ef41Sopenharmony_cimust use Node-API exclusively by restricting itself to using</p> 10431cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_api.h></span></span></code> <button class="copy-button">copy</button></pre> 10441cb0ef41Sopenharmony_ci<p>and by checking, for all external libraries that it uses, that the external 10451cb0ef41Sopenharmony_cilibrary makes ABI stability guarantees similar to Node-API.</p> 10461cb0ef41Sopenharmony_ci</section><section><h3>Building<span><a class="mark" href="#building" id="building">#</a></span><a aria-hidden="true" class="legacy" id="n_api_building"></a></h3> 10471cb0ef41Sopenharmony_ci<p>Unlike modules written in JavaScript, developing and deploying Node.js 10481cb0ef41Sopenharmony_cinative addons using Node-API requires an additional set of tools. Besides the 10491cb0ef41Sopenharmony_cibasic tools required to develop for Node.js, the native addon developer 10501cb0ef41Sopenharmony_cirequires a toolchain that can compile C and C++ code into a binary. In 10511cb0ef41Sopenharmony_ciaddition, depending upon how the native addon is deployed, the <em>user</em> of 10521cb0ef41Sopenharmony_cithe native addon will also need to have a C/C++ toolchain installed.</p> 10531cb0ef41Sopenharmony_ci<p>For Linux developers, the necessary C/C++ toolchain packages are readily 10541cb0ef41Sopenharmony_ciavailable. <a href="https://gcc.gnu.org">GCC</a> is widely used in the Node.js community to build and 10551cb0ef41Sopenharmony_citest across a variety of platforms. For many developers, the <a href="https://llvm.org">LLVM</a> 10561cb0ef41Sopenharmony_cicompiler infrastructure is also a good choice.</p> 10571cb0ef41Sopenharmony_ci<p>For Mac developers, <a href="https://developer.apple.com/xcode/">Xcode</a> offers all the required compiler tools. 10581cb0ef41Sopenharmony_ciHowever, it is not necessary to install the entire Xcode IDE. The following 10591cb0ef41Sopenharmony_cicommand installs the necessary toolchain:</p> 10601cb0ef41Sopenharmony_ci<pre><code class="language-bash">xcode-select --install</code> <button class="copy-button">copy</button></pre> 10611cb0ef41Sopenharmony_ci<p>For Windows developers, <a href="https://visualstudio.microsoft.com">Visual Studio</a> offers all the required compiler 10621cb0ef41Sopenharmony_citools. However, it is not necessary to install the entire Visual Studio 10631cb0ef41Sopenharmony_ciIDE. The following command installs the necessary toolchain:</p> 10641cb0ef41Sopenharmony_ci<pre><code class="language-bash">npm install --global windows-build-tools</code> <button class="copy-button">copy</button></pre> 10651cb0ef41Sopenharmony_ci<p>The sections below describe the additional tools available for developing 10661cb0ef41Sopenharmony_ciand deploying Node.js native addons.</p> 10671cb0ef41Sopenharmony_ci<h4>Build tools<span><a class="mark" href="#build-tools" id="build-tools">#</a></span><a aria-hidden="true" class="legacy" id="n_api_build_tools"></a></h4> 10681cb0ef41Sopenharmony_ci<p>Both the tools listed here require that <em>users</em> of the native 10691cb0ef41Sopenharmony_ciaddon have a C/C++ toolchain installed in order to successfully install 10701cb0ef41Sopenharmony_cithe native addon.</p> 10711cb0ef41Sopenharmony_ci<h5>node-gyp<span><a class="mark" href="#node-gyp" id="node-gyp">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_gyp"></a></h5> 10721cb0ef41Sopenharmony_ci<p><a href="https://github.com/nodejs/node-gyp">node-gyp</a> is a build system based on the <a href="https://github.com/nodejs/gyp-next">gyp-next</a> fork of 10731cb0ef41Sopenharmony_ciGoogle's <a href="https://gyp.gsrc.io">GYP</a> tool and comes bundled with npm. GYP, and therefore node-gyp, 10741cb0ef41Sopenharmony_cirequires that Python be installed.</p> 10751cb0ef41Sopenharmony_ci<p>Historically, node-gyp has been the tool of choice for building native 10761cb0ef41Sopenharmony_ciaddons. It has widespread adoption and documentation. However, some 10771cb0ef41Sopenharmony_cidevelopers have run into limitations in node-gyp.</p> 10781cb0ef41Sopenharmony_ci<h5>CMake.js<span><a class="mark" href="#cmakejs" id="cmakejs">#</a></span><a aria-hidden="true" class="legacy" id="n_api_cmake_js"></a></h5> 10791cb0ef41Sopenharmony_ci<p><a href="https://github.com/cmake-js/cmake-js">CMake.js</a> is an alternative build system based on <a href="https://cmake.org">CMake</a>.</p> 10801cb0ef41Sopenharmony_ci<p>CMake.js is a good choice for projects that already use CMake or for 10811cb0ef41Sopenharmony_cidevelopers affected by limitations in node-gyp. <a href="https://github.com/nodejs/node-addon-examples/tree/main/build_with_cmake"><code>build_with_cmake</code></a> is an 10821cb0ef41Sopenharmony_ciexample of a CMake-based native addon project.</p> 10831cb0ef41Sopenharmony_ci<h4>Uploading precompiled binaries<span><a class="mark" href="#uploading-precompiled-binaries" id="uploading-precompiled-binaries">#</a></span><a aria-hidden="true" class="legacy" id="n_api_uploading_precompiled_binaries"></a></h4> 10841cb0ef41Sopenharmony_ci<p>The three tools listed here permit native addon developers and maintainers 10851cb0ef41Sopenharmony_cito create and upload binaries to public or private servers. These tools are 10861cb0ef41Sopenharmony_citypically integrated with CI/CD build systems like <a href="https://travis-ci.org">Travis CI</a> and 10871cb0ef41Sopenharmony_ci<a href="https://www.appveyor.com">AppVeyor</a> to build and upload binaries for a variety of platforms and 10881cb0ef41Sopenharmony_ciarchitectures. These binaries are then available for download by users who 10891cb0ef41Sopenharmony_cido not need to have a C/C++ toolchain installed.</p> 10901cb0ef41Sopenharmony_ci<h5>node-pre-gyp<span><a class="mark" href="#node-pre-gyp" id="node-pre-gyp">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_pre_gyp"></a></h5> 10911cb0ef41Sopenharmony_ci<p><a href="https://github.com/mapbox/node-pre-gyp">node-pre-gyp</a> is a tool based on node-gyp that adds the ability to 10921cb0ef41Sopenharmony_ciupload binaries to a server of the developer's choice. node-pre-gyp has 10931cb0ef41Sopenharmony_ciparticularly good support for uploading binaries to Amazon S3.</p> 10941cb0ef41Sopenharmony_ci<h5>prebuild<span><a class="mark" href="#prebuild" id="prebuild">#</a></span><a aria-hidden="true" class="legacy" id="n_api_prebuild"></a></h5> 10951cb0ef41Sopenharmony_ci<p><a href="https://github.com/prebuild/prebuild">prebuild</a> is a tool that supports builds using either node-gyp or 10961cb0ef41Sopenharmony_ciCMake.js. Unlike node-pre-gyp which supports a variety of servers, prebuild 10971cb0ef41Sopenharmony_ciuploads binaries only to <a href="https://help.github.com/en/github/administering-a-repository/about-releases">GitHub releases</a>. prebuild is a good choice for 10981cb0ef41Sopenharmony_ciGitHub projects using CMake.js.</p> 10991cb0ef41Sopenharmony_ci<h5>prebuildify<span><a class="mark" href="#prebuildify" id="prebuildify">#</a></span><a aria-hidden="true" class="legacy" id="n_api_prebuildify"></a></h5> 11001cb0ef41Sopenharmony_ci<p><a href="https://github.com/prebuild/prebuildify">prebuildify</a> is a tool based on node-gyp. The advantage of prebuildify is 11011cb0ef41Sopenharmony_cithat the built binaries are bundled with the native addon when it's 11021cb0ef41Sopenharmony_ciuploaded to npm. The binaries are downloaded from npm and are immediately 11031cb0ef41Sopenharmony_ciavailable to the module user when the native addon is installed.</p> 11041cb0ef41Sopenharmony_ci</section><section><h3>Usage<span><a class="mark" href="#usage" id="usage">#</a></span><a aria-hidden="true" class="legacy" id="n_api_usage"></a></h3> 11051cb0ef41Sopenharmony_ci<p>In order to use the Node-API functions, include the file <a href="https://github.com/nodejs/node/blob/HEAD/src/node_api.h"><code>node_api.h</code></a> which 11061cb0ef41Sopenharmony_ciis located in the src directory in the node development tree:</p> 11071cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_api.h></span></span></code> <button class="copy-button">copy</button></pre> 11081cb0ef41Sopenharmony_ci<p>This will opt into the default <code>NAPI_VERSION</code> for the given release of Node.js. 11091cb0ef41Sopenharmony_ciIn order to ensure compatibility with specific versions of Node-API, the version 11101cb0ef41Sopenharmony_cican be specified explicitly when including the header:</p> 11111cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-meta">#<span class="hljs-keyword">define</span> NAPI_VERSION 3</span> 11121cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_api.h></span></span></code> <button class="copy-button">copy</button></pre> 11131cb0ef41Sopenharmony_ci<p>This restricts the Node-API surface to just the functionality that was available 11141cb0ef41Sopenharmony_ciin the specified (and earlier) versions.</p> 11151cb0ef41Sopenharmony_ci<p>Some of the Node-API surface is experimental and requires explicit opt-in:</p> 11161cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-meta">#<span class="hljs-keyword">define</span> NAPI_EXPERIMENTAL</span> 11171cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_api.h></span></span></code> <button class="copy-button">copy</button></pre> 11181cb0ef41Sopenharmony_ci<p>In this case the entire API surface, including any experimental APIs, will be 11191cb0ef41Sopenharmony_ciavailable to the module code.</p> 11201cb0ef41Sopenharmony_ci<p>Occasionally, experimental features are introduced that affect already-released 11211cb0ef41Sopenharmony_ciand stable APIs. These features can be disabled by an opt-out:</p> 11221cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-meta">#<span class="hljs-keyword">define</span> NAPI_EXPERIMENTAL</span> 11231cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">define</span> NODE_API_EXPERIMENTAL_<span class="hljs-string"><FEATURE_NAME></span>_OPT_OUT</span> 11241cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_api.h></span></span></code> <button class="copy-button">copy</button></pre> 11251cb0ef41Sopenharmony_ci<p>where <code><FEATURE_NAME></code> is the name of an experimental feature that affects both 11261cb0ef41Sopenharmony_ciexperimental and stable APIs.</p> 11271cb0ef41Sopenharmony_ci</section><section><h3>Node-API version matrix<span><a class="mark" href="#node-api-version-matrix" id="node-api-version-matrix">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_version_matrix"></a></h3> 11281cb0ef41Sopenharmony_ci<p>Node-API versions are additive and versioned independently from Node.js. 11291cb0ef41Sopenharmony_ciVersion 4 is an extension to version 3 in that it has all of the APIs 11301cb0ef41Sopenharmony_cifrom version 3 with some additions. This means that it is not necessary 11311cb0ef41Sopenharmony_cito recompile for new versions of Node.js which are 11321cb0ef41Sopenharmony_cilisted as supporting a later version.</p> 11331cb0ef41Sopenharmony_ci<p>This table may not be up to date in older streams, the most up to date 11341cb0ef41Sopenharmony_ciinformation is in the latest API documentation in: 11351cb0ef41Sopenharmony_ci<a href="https://nodejs.org/docs/latest/api/n-api.html#node-api-version-matrix">Node-API version matrix</a></p> 11361cb0ef41Sopenharmony_ci<!-- For accessibility purposes, this table needs row headers. That means we 11371cb0ef41Sopenharmony_ci can't do it in markdown. Hence, the raw HTML. --> 11381cb0ef41Sopenharmony_ci<table> 11391cb0ef41Sopenharmony_ci <tbody><tr> 11401cb0ef41Sopenharmony_ci <th>Node-API version</th> 11411cb0ef41Sopenharmony_ci <th scope="col">Supported In</th> 11421cb0ef41Sopenharmony_ci </tr> 11431cb0ef41Sopenharmony_ci <tr> 11441cb0ef41Sopenharmony_ci <th scope="row">9</th> 11451cb0ef41Sopenharmony_ci <td>v18.17.0+, 20.3.0+, 21.0.0 and all later versions</td> 11461cb0ef41Sopenharmony_ci </tr> 11471cb0ef41Sopenharmony_ci <tr> 11481cb0ef41Sopenharmony_ci <th scope="row">8</th> 11491cb0ef41Sopenharmony_ci <td>v12.22.0+, v14.17.0+, v15.12.0+, 16.0.0 and all later versions</td> 11501cb0ef41Sopenharmony_ci </tr> 11511cb0ef41Sopenharmony_ci <tr> 11521cb0ef41Sopenharmony_ci <th scope="row">7</th> 11531cb0ef41Sopenharmony_ci <td>v10.23.0+, v12.19.0+, v14.12.0+, 15.0.0 and all later versions</td> 11541cb0ef41Sopenharmony_ci </tr> 11551cb0ef41Sopenharmony_ci <tr> 11561cb0ef41Sopenharmony_ci <th scope="row">6</th> 11571cb0ef41Sopenharmony_ci <td>v10.20.0+, v12.17.0+, 14.0.0 and all later versions</td> 11581cb0ef41Sopenharmony_ci </tr> 11591cb0ef41Sopenharmony_ci <tr> 11601cb0ef41Sopenharmony_ci <th scope="row">5</th> 11611cb0ef41Sopenharmony_ci <td>v10.17.0+, v12.11.0+, 13.0.0 and all later versions</td> 11621cb0ef41Sopenharmony_ci </tr> 11631cb0ef41Sopenharmony_ci <tr> 11641cb0ef41Sopenharmony_ci <th scope="row">4</th> 11651cb0ef41Sopenharmony_ci <td>v10.16.0+, v11.8.0+, 12.0.0 and all later versions</td> 11661cb0ef41Sopenharmony_ci </tr> 11671cb0ef41Sopenharmony_ci 11681cb0ef41Sopenharmony_ci <tr> 11691cb0ef41Sopenharmony_ci <th scope="row">3</th> 11701cb0ef41Sopenharmony_ci <td>v6.14.2*, 8.11.2+, v9.11.0+*, 10.0.0 and all later versions</td> 11711cb0ef41Sopenharmony_ci </tr> 11721cb0ef41Sopenharmony_ci <tr> 11731cb0ef41Sopenharmony_ci <th scope="row">2</th> 11741cb0ef41Sopenharmony_ci <td>v8.10.0+*, v9.3.0+*, 10.0.0 and all later versions</td> 11751cb0ef41Sopenharmony_ci </tr> 11761cb0ef41Sopenharmony_ci <tr> 11771cb0ef41Sopenharmony_ci <th scope="row">1</th> 11781cb0ef41Sopenharmony_ci <td>v8.6.0+**, v9.0.0+*, 10.0.0 and all later versions</td> 11791cb0ef41Sopenharmony_ci </tr> 11801cb0ef41Sopenharmony_ci</tbody></table> 11811cb0ef41Sopenharmony_ci<p>* Node-API was experimental.</p> 11821cb0ef41Sopenharmony_ci<p>** Node.js 8.0.0 included Node-API as experimental. It was released as 11831cb0ef41Sopenharmony_ciNode-API version 1 but continued to evolve until Node.js 8.6.0. The API is 11841cb0ef41Sopenharmony_cidifferent in versions prior to Node.js 8.6.0. We recommend Node-API version 3 or 11851cb0ef41Sopenharmony_cilater.</p> 11861cb0ef41Sopenharmony_ci<p>Each API documented for Node-API will have a header named <code>added in:</code>, and APIs 11871cb0ef41Sopenharmony_ciwhich are stable will have the additional header <code>Node-API version:</code>. 11881cb0ef41Sopenharmony_ciAPIs are directly usable when using a Node.js version which supports 11891cb0ef41Sopenharmony_cithe Node-API version shown in <code>Node-API version:</code> or higher. 11901cb0ef41Sopenharmony_ciWhen using a Node.js version that does not support the 11911cb0ef41Sopenharmony_ci<code>Node-API version:</code> listed or if there is no <code>Node-API version:</code> listed, 11921cb0ef41Sopenharmony_cithen the API will only be available if 11931cb0ef41Sopenharmony_ci<code>#define NAPI_EXPERIMENTAL</code> precedes the inclusion of <code>node_api.h</code> 11941cb0ef41Sopenharmony_cior <code>js_native_api.h</code>. If an API appears not to be available on 11951cb0ef41Sopenharmony_cia version of Node.js which is later than the one shown in <code>added in:</code> then 11961cb0ef41Sopenharmony_cithis is most likely the reason for the apparent absence.</p> 11971cb0ef41Sopenharmony_ci<p>The Node-APIs associated strictly with accessing ECMAScript features from native 11981cb0ef41Sopenharmony_cicode can be found separately in <code>js_native_api.h</code> and <code>js_native_api_types.h</code>. 11991cb0ef41Sopenharmony_ciThe APIs defined in these headers are included in <code>node_api.h</code> and 12001cb0ef41Sopenharmony_ci<code>node_api_types.h</code>. The headers are structured in this way in order to allow 12011cb0ef41Sopenharmony_ciimplementations of Node-API outside of Node.js. For those implementations the 12021cb0ef41Sopenharmony_ciNode.js specific APIs may not be applicable.</p> 12031cb0ef41Sopenharmony_ci<p>The Node.js-specific parts of an addon can be separated from the code that 12041cb0ef41Sopenharmony_ciexposes the actual functionality to the JavaScript environment so that the 12051cb0ef41Sopenharmony_cilatter may be used with multiple implementations of Node-API. In the example 12061cb0ef41Sopenharmony_cibelow, <code>addon.c</code> and <code>addon.h</code> refer only to <code>js_native_api.h</code>. This ensures 12071cb0ef41Sopenharmony_cithat <code>addon.c</code> can be reused to compile against either the Node.js 12081cb0ef41Sopenharmony_ciimplementation of Node-API or any implementation of Node-API outside of Node.js.</p> 12091cb0ef41Sopenharmony_ci<p><code>addon_node.c</code> is a separate file that contains the Node.js specific entry point 12101cb0ef41Sopenharmony_cito the addon and which instantiates the addon by calling into <code>addon.c</code> when the 12111cb0ef41Sopenharmony_ciaddon is loaded into a Node.js environment.</p> 12121cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-comment">// addon.h</span> 12131cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">ifndef</span> _ADDON_H_</span> 12141cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">define</span> _ADDON_H_</span> 12151cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><js_native_api.h></span></span> 12161cb0ef41Sopenharmony_cinapi_value <span class="hljs-title function_">create_addon</span><span class="hljs-params">(napi_env env)</span>; 12171cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">endif</span> <span class="hljs-comment">// _ADDON_H_</span></span></code> <button class="copy-button">copy</button></pre> 12181cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-comment">// addon.c</span> 12191cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string">"addon.h"</span></span> 12201cb0ef41Sopenharmony_ci 12211cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">define</span> NODE_API_CALL(env, call) \ 12221cb0ef41Sopenharmony_ci do { \ 12231cb0ef41Sopenharmony_ci napi_status status = (call); \ 12241cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) { \ 12251cb0ef41Sopenharmony_ci const napi_extended_error_info* error_info = NULL; \ 12261cb0ef41Sopenharmony_ci napi_get_last_error_info((env), &error_info); \ 12271cb0ef41Sopenharmony_ci const char* err_message = error_info->error_message; \ 12281cb0ef41Sopenharmony_ci bool is_pending; \ 12291cb0ef41Sopenharmony_ci napi_is_exception_pending((env), &is_pending); \ 12301cb0ef41Sopenharmony_ci <span class="hljs-comment">/* If an exception is already pending, don't rethrow it */</span> \ 12311cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (!is_pending) { \ 12321cb0ef41Sopenharmony_ci const char* message = (err_message == NULL) \ 12331cb0ef41Sopenharmony_ci ? <span class="hljs-string">"empty error message"</span> \ 12341cb0ef41Sopenharmony_ci : err_message; \ 12351cb0ef41Sopenharmony_ci napi_throw_error((env), NULL, message); \ 12361cb0ef41Sopenharmony_ci } \ 12371cb0ef41Sopenharmony_ci return NULL; \ 12381cb0ef41Sopenharmony_ci } \ 12391cb0ef41Sopenharmony_ci } while(0)</span> 12401cb0ef41Sopenharmony_ci 12411cb0ef41Sopenharmony_ci<span class="hljs-type">static</span> napi_value 12421cb0ef41Sopenharmony_ci<span class="hljs-title function_">DoSomethingUseful</span><span class="hljs-params">(napi_env env, napi_callback_info info)</span> { 12431cb0ef41Sopenharmony_ci <span class="hljs-comment">// Do something useful.</span> 12441cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 12451cb0ef41Sopenharmony_ci} 12461cb0ef41Sopenharmony_ci 12471cb0ef41Sopenharmony_cinapi_value <span class="hljs-title function_">create_addon</span><span class="hljs-params">(napi_env env)</span> { 12481cb0ef41Sopenharmony_ci napi_value result; 12491cb0ef41Sopenharmony_ci NODE_API_CALL(env, napi_create_object(env, &result)); 12501cb0ef41Sopenharmony_ci 12511cb0ef41Sopenharmony_ci napi_value exported_function; 12521cb0ef41Sopenharmony_ci NODE_API_CALL(env, napi_create_function(env, 12531cb0ef41Sopenharmony_ci <span class="hljs-string">"doSomethingUseful"</span>, 12541cb0ef41Sopenharmony_ci NAPI_AUTO_LENGTH, 12551cb0ef41Sopenharmony_ci DoSomethingUseful, 12561cb0ef41Sopenharmony_ci <span class="hljs-literal">NULL</span>, 12571cb0ef41Sopenharmony_ci &exported_function)); 12581cb0ef41Sopenharmony_ci 12591cb0ef41Sopenharmony_ci NODE_API_CALL(env, napi_set_named_property(env, 12601cb0ef41Sopenharmony_ci result, 12611cb0ef41Sopenharmony_ci <span class="hljs-string">"doSomethingUseful"</span>, 12621cb0ef41Sopenharmony_ci exported_function)); 12631cb0ef41Sopenharmony_ci 12641cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> result; 12651cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 12661cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-comment">// addon_node.c</span> 12671cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string"><node_api.h></span></span> 12681cb0ef41Sopenharmony_ci<span class="hljs-meta">#<span class="hljs-keyword">include</span> <span class="hljs-string">"addon.h"</span></span> 12691cb0ef41Sopenharmony_ci 12701cb0ef41Sopenharmony_ciNAPI_MODULE_INIT(<span class="hljs-comment">/* napi_env env, napi_value exports */</span>) { 12711cb0ef41Sopenharmony_ci <span class="hljs-comment">// This function body is expected to return a `napi_value`.</span> 12721cb0ef41Sopenharmony_ci <span class="hljs-comment">// The variables `napi_env env` and `napi_value exports` may be used within</span> 12731cb0ef41Sopenharmony_ci <span class="hljs-comment">// the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.</span> 12741cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> create_addon(env); 12751cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 12761cb0ef41Sopenharmony_ci</section><section><h3>Environment life cycle APIs<span><a class="mark" href="#environment-life-cycle-apis" id="environment-life-cycle-apis">#</a></span><a aria-hidden="true" class="legacy" id="n_api_environment_life_cycle_apis"></a></h3> 12771cb0ef41Sopenharmony_ci<p><a href="https://tc39.es/ecma262/#sec-agents">Section 8.7</a> of the <a href="https://tc39.github.io/ecma262/">ECMAScript Language Specification</a> defines the concept 12781cb0ef41Sopenharmony_ciof an "Agent" as a self-contained environment in which JavaScript code runs. 12791cb0ef41Sopenharmony_ciMultiple such Agents may be started and terminated either concurrently or in 12801cb0ef41Sopenharmony_cisequence by the process.</p> 12811cb0ef41Sopenharmony_ci<p>A Node.js environment corresponds to an ECMAScript Agent. In the main process, 12821cb0ef41Sopenharmony_cian environment is created at startup, and additional environments can be created 12831cb0ef41Sopenharmony_cion separate threads to serve as <a href="https://nodejs.org/api/worker_threads.html">worker threads</a>. When Node.js is embedded in 12841cb0ef41Sopenharmony_cianother application, the main thread of the application may also construct and 12851cb0ef41Sopenharmony_cidestroy a Node.js environment multiple times during the life cycle of the 12861cb0ef41Sopenharmony_ciapplication process such that each Node.js environment created by the 12871cb0ef41Sopenharmony_ciapplication may, in turn, during its life cycle create and destroy additional 12881cb0ef41Sopenharmony_cienvironments as worker threads.</p> 12891cb0ef41Sopenharmony_ci<p>From the perspective of a native addon this means that the bindings it provides 12901cb0ef41Sopenharmony_cimay be called multiple times, from multiple contexts, and even concurrently from 12911cb0ef41Sopenharmony_cimultiple threads.</p> 12921cb0ef41Sopenharmony_ci<p>Native addons may need to allocate global state which they use during 12931cb0ef41Sopenharmony_citheir life cycle of an Node.js environment such that the state can be 12941cb0ef41Sopenharmony_ciunique to each instance of the addon.</p> 12951cb0ef41Sopenharmony_ci<p>To this end, Node-API provides a way to associate data such that its life cycle 12961cb0ef41Sopenharmony_ciis tied to the life cycle of a Node.js environment.</p> 12971cb0ef41Sopenharmony_ci<h4><code>napi_set_instance_data</code><span><a class="mark" href="#napi_set_instance_data" id="napi_set_instance_data">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_set_instance_data"></a></h4> 12981cb0ef41Sopenharmony_ci<div class="api_metadata"> 12991cb0ef41Sopenharmony_ci<span>Added in: v12.8.0, v10.20.0</span> 13001cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 13011cb0ef41Sopenharmony_ci</div> 13021cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_set_instance_data</span><span class="hljs-params">(node_api_nogc_env env, 13031cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data, 13041cb0ef41Sopenharmony_ci napi_finalize finalize_cb, 13051cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint)</span>;</code> <button class="copy-button">copy</button></pre> 13061cb0ef41Sopenharmony_ci<ul> 13071cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 13081cb0ef41Sopenharmony_ci<li><code>[in] data</code>: The data item to make available to bindings of this instance.</li> 13091cb0ef41Sopenharmony_ci<li><code>[in] finalize_cb</code>: The function to call when the environment is being torn 13101cb0ef41Sopenharmony_cidown. The function receives <code>data</code> so that it might free it. 13111cb0ef41Sopenharmony_ci<a href="#napi_finalize"><code>napi_finalize</code></a> provides more details.</li> 13121cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional hint to pass to the finalize callback during 13131cb0ef41Sopenharmony_cicollection.</li> 13141cb0ef41Sopenharmony_ci</ul> 13151cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 13161cb0ef41Sopenharmony_ci<p>This API associates <code>data</code> with the currently running Node.js environment. <code>data</code> 13171cb0ef41Sopenharmony_cican later be retrieved using <code>napi_get_instance_data()</code>. Any existing data 13181cb0ef41Sopenharmony_ciassociated with the currently running Node.js environment which was set by means 13191cb0ef41Sopenharmony_ciof a previous call to <code>napi_set_instance_data()</code> will be overwritten. If a 13201cb0ef41Sopenharmony_ci<code>finalize_cb</code> was provided by the previous call, it will not be called.</p> 13211cb0ef41Sopenharmony_ci<h4><code>napi_get_instance_data</code><span><a class="mark" href="#napi_get_instance_data" id="napi_get_instance_data">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_instance_data"></a></h4> 13221cb0ef41Sopenharmony_ci<div class="api_metadata"> 13231cb0ef41Sopenharmony_ci<span>Added in: v12.8.0, v10.20.0</span> 13241cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 13251cb0ef41Sopenharmony_ci</div> 13261cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_instance_data</span><span class="hljs-params">(node_api_nogc_env env, 13271cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** data)</span>;</code> <button class="copy-button">copy</button></pre> 13281cb0ef41Sopenharmony_ci<ul> 13291cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 13301cb0ef41Sopenharmony_ci<li><code>[out] data</code>: The data item that was previously associated with the currently 13311cb0ef41Sopenharmony_cirunning Node.js environment by a call to <code>napi_set_instance_data()</code>.</li> 13321cb0ef41Sopenharmony_ci</ul> 13331cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 13341cb0ef41Sopenharmony_ci<p>This API retrieves data that was previously associated with the currently 13351cb0ef41Sopenharmony_cirunning Node.js environment via <code>napi_set_instance_data()</code>. If no data is set, 13361cb0ef41Sopenharmony_cithe call will succeed and <code>data</code> will be set to <code>NULL</code>.</p> 13371cb0ef41Sopenharmony_ci</section><section><h3>Basic Node-API data types<span><a class="mark" href="#basic-node-api-data-types" id="basic-node-api-data-types">#</a></span><a aria-hidden="true" class="legacy" id="n_api_basic_node_api_data_types"></a></h3> 13381cb0ef41Sopenharmony_ci<p>Node-API exposes the following fundamental data types as abstractions that are 13391cb0ef41Sopenharmony_ciconsumed by the various APIs. These APIs should be treated as opaque, 13401cb0ef41Sopenharmony_ciintrospectable only with other Node-API calls.</p> 13411cb0ef41Sopenharmony_ci<h4><code>napi_status</code><span><a class="mark" href="#napi_status" id="napi_status">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_status"></a></h4> 13421cb0ef41Sopenharmony_ci<div class="api_metadata"> 13431cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 13441cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 13451cb0ef41Sopenharmony_ci</div> 13461cb0ef41Sopenharmony_ci<p>Integral status code indicating the success or failure of a Node-API call. 13471cb0ef41Sopenharmony_ciCurrently, the following status codes are supported.</p> 13481cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 13491cb0ef41Sopenharmony_ci napi_ok, 13501cb0ef41Sopenharmony_ci napi_invalid_arg, 13511cb0ef41Sopenharmony_ci napi_object_expected, 13521cb0ef41Sopenharmony_ci napi_string_expected, 13531cb0ef41Sopenharmony_ci napi_name_expected, 13541cb0ef41Sopenharmony_ci napi_function_expected, 13551cb0ef41Sopenharmony_ci napi_number_expected, 13561cb0ef41Sopenharmony_ci napi_boolean_expected, 13571cb0ef41Sopenharmony_ci napi_array_expected, 13581cb0ef41Sopenharmony_ci napi_generic_failure, 13591cb0ef41Sopenharmony_ci napi_pending_exception, 13601cb0ef41Sopenharmony_ci napi_cancelled, 13611cb0ef41Sopenharmony_ci napi_escape_called_twice, 13621cb0ef41Sopenharmony_ci napi_handle_scope_mismatch, 13631cb0ef41Sopenharmony_ci napi_callback_scope_mismatch, 13641cb0ef41Sopenharmony_ci napi_queue_full, 13651cb0ef41Sopenharmony_ci napi_closing, 13661cb0ef41Sopenharmony_ci napi_bigint_expected, 13671cb0ef41Sopenharmony_ci napi_date_expected, 13681cb0ef41Sopenharmony_ci napi_arraybuffer_expected, 13691cb0ef41Sopenharmony_ci napi_detachable_arraybuffer_expected, 13701cb0ef41Sopenharmony_ci napi_would_deadlock, <span class="hljs-comment">/* unused */</span> 13711cb0ef41Sopenharmony_ci napi_no_external_buffers_allowed, 13721cb0ef41Sopenharmony_ci napi_cannot_run_js 13731cb0ef41Sopenharmony_ci} napi_status;</code> <button class="copy-button">copy</button></pre> 13741cb0ef41Sopenharmony_ci<p>If additional information is required upon an API returning a failed status, 13751cb0ef41Sopenharmony_ciit can be obtained by calling <code>napi_get_last_error_info</code>.</p> 13761cb0ef41Sopenharmony_ci<h4><code>napi_extended_error_info</code><span><a class="mark" href="#napi_extended_error_info" id="napi_extended_error_info">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_extended_error_info"></a></h4> 13771cb0ef41Sopenharmony_ci<div class="api_metadata"> 13781cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 13791cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 13801cb0ef41Sopenharmony_ci</div> 13811cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">struct</span> {</span> 13821cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* error_message; 13831cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* engine_reserved; 13841cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> engine_error_code; 13851cb0ef41Sopenharmony_ci napi_status error_code; 13861cb0ef41Sopenharmony_ci} napi_extended_error_info;</code> <button class="copy-button">copy</button></pre> 13871cb0ef41Sopenharmony_ci<ul> 13881cb0ef41Sopenharmony_ci<li><code>error_message</code>: UTF8-encoded string containing a VM-neutral description of 13891cb0ef41Sopenharmony_cithe error.</li> 13901cb0ef41Sopenharmony_ci<li><code>engine_reserved</code>: Reserved for VM-specific error details. This is currently 13911cb0ef41Sopenharmony_cinot implemented for any VM.</li> 13921cb0ef41Sopenharmony_ci<li><code>engine_error_code</code>: VM-specific error code. This is currently 13931cb0ef41Sopenharmony_cinot implemented for any VM.</li> 13941cb0ef41Sopenharmony_ci<li><code>error_code</code>: The Node-API status code that originated with the last error.</li> 13951cb0ef41Sopenharmony_ci</ul> 13961cb0ef41Sopenharmony_ci<p>See the <a href="#error-handling">Error handling</a> section for additional information.</p> 13971cb0ef41Sopenharmony_ci<h4><code>napi_env</code><span><a class="mark" href="#napi_env" id="napi_env">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_env"></a></h4> 13981cb0ef41Sopenharmony_ci<p><code>napi_env</code> is used to represent a context that the underlying Node-API 13991cb0ef41Sopenharmony_ciimplementation can use to persist VM-specific state. This structure is passed 14001cb0ef41Sopenharmony_cito native functions when they're invoked, and it must be passed back when 14011cb0ef41Sopenharmony_cimaking Node-API calls. Specifically, the same <code>napi_env</code> that was passed in when 14021cb0ef41Sopenharmony_cithe initial native function was called must be passed to any subsequent 14031cb0ef41Sopenharmony_cinested Node-API calls. Caching the <code>napi_env</code> for the purpose of general reuse, 14041cb0ef41Sopenharmony_ciand passing the <code>napi_env</code> between instances of the same addon running on 14051cb0ef41Sopenharmony_cidifferent <a href="worker_threads.html#class-worker"><code>Worker</code></a> threads is not allowed. The <code>napi_env</code> becomes invalid 14061cb0ef41Sopenharmony_ciwhen an instance of a native addon is unloaded. Notification of this event is 14071cb0ef41Sopenharmony_cidelivered through the callbacks given to <a href="#napi_add_env_cleanup_hook"><code>napi_add_env_cleanup_hook</code></a> and 14081cb0ef41Sopenharmony_ci<a href="#napi_set_instance_data"><code>napi_set_instance_data</code></a>.</p> 14091cb0ef41Sopenharmony_ci<h4><code>node_api_nogc_env</code><span><a class="mark" href="#node_api_nogc_env" id="node_api_nogc_env">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_nogc_env"></a></h4> 14101cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 14111cb0ef41Sopenharmony_ci<p>This variant of <code>napi_env</code> is passed to synchronous finalizers 14121cb0ef41Sopenharmony_ci(<a href="#node_api_nogc_finalize"><code>node_api_nogc_finalize</code></a>). There is a subset of Node-APIs which accept 14131cb0ef41Sopenharmony_cia parameter of type <code>node_api_nogc_env</code> as their first argument. These APIs do 14141cb0ef41Sopenharmony_cinot access the state of the JavaScript engine and are thus safe to call from 14151cb0ef41Sopenharmony_cisynchronous finalizers. Passing a parameter of type <code>napi_env</code> to these APIs is 14161cb0ef41Sopenharmony_ciallowed, however, passing a parameter of type <code>node_api_nogc_env</code> to APIs that 14171cb0ef41Sopenharmony_ciaccess the JavaScript engine state is not allowed. Attempting to do so without 14181cb0ef41Sopenharmony_cia cast will produce a compiler warning or an error when add-ons are compiled 14191cb0ef41Sopenharmony_ciwith flags which cause them to emit warnings and/or errors when incorrect 14201cb0ef41Sopenharmony_cipointer types are passed into a function. Calling such APIs from a synchronous 14211cb0ef41Sopenharmony_cifinalizer will ultimately result in the termination of the application.</p> 14221cb0ef41Sopenharmony_ci<h4><code>napi_value</code><span><a class="mark" href="#napi_value" id="napi_value">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_value"></a></h4> 14231cb0ef41Sopenharmony_ci<p>This is an opaque pointer that is used to represent a JavaScript value.</p> 14241cb0ef41Sopenharmony_ci<h4><code>napi_threadsafe_function</code><span><a class="mark" href="#napi_threadsafe_function" id="napi_threadsafe_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_threadsafe_function"></a></h4> 14251cb0ef41Sopenharmony_ci<div class="api_metadata"> 14261cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 14271cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 14281cb0ef41Sopenharmony_ci</div> 14291cb0ef41Sopenharmony_ci<p>This is an opaque pointer that represents a JavaScript function which can be 14301cb0ef41Sopenharmony_cicalled asynchronously from multiple threads via 14311cb0ef41Sopenharmony_ci<code>napi_call_threadsafe_function()</code>.</p> 14321cb0ef41Sopenharmony_ci<h4><code>napi_threadsafe_function_release_mode</code><span><a class="mark" href="#napi_threadsafe_function_release_mode" id="napi_threadsafe_function_release_mode">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_threadsafe_function_release_mode"></a></h4> 14331cb0ef41Sopenharmony_ci<div class="api_metadata"> 14341cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 14351cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 14361cb0ef41Sopenharmony_ci</div> 14371cb0ef41Sopenharmony_ci<p>A value to be given to <code>napi_release_threadsafe_function()</code> to indicate whether 14381cb0ef41Sopenharmony_cithe thread-safe function is to be closed immediately (<code>napi_tsfn_abort</code>) or 14391cb0ef41Sopenharmony_cimerely released (<code>napi_tsfn_release</code>) and thus available for subsequent use via 14401cb0ef41Sopenharmony_ci<code>napi_acquire_threadsafe_function()</code> and <code>napi_call_threadsafe_function()</code>.</p> 14411cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 14421cb0ef41Sopenharmony_ci napi_tsfn_release, 14431cb0ef41Sopenharmony_ci napi_tsfn_abort 14441cb0ef41Sopenharmony_ci} napi_threadsafe_function_release_mode;</code> <button class="copy-button">copy</button></pre> 14451cb0ef41Sopenharmony_ci<h4><code>napi_threadsafe_function_call_mode</code><span><a class="mark" href="#napi_threadsafe_function_call_mode" id="napi_threadsafe_function_call_mode">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_threadsafe_function_call_mode"></a></h4> 14461cb0ef41Sopenharmony_ci<div class="api_metadata"> 14471cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 14481cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 14491cb0ef41Sopenharmony_ci</div> 14501cb0ef41Sopenharmony_ci<p>A value to be given to <code>napi_call_threadsafe_function()</code> to indicate whether 14511cb0ef41Sopenharmony_cithe call should block whenever the queue associated with the thread-safe 14521cb0ef41Sopenharmony_cifunction is full.</p> 14531cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 14541cb0ef41Sopenharmony_ci napi_tsfn_nonblocking, 14551cb0ef41Sopenharmony_ci napi_tsfn_blocking 14561cb0ef41Sopenharmony_ci} napi_threadsafe_function_call_mode;</code> <button class="copy-button">copy</button></pre> 14571cb0ef41Sopenharmony_ci<h4>Node-API memory management types<span><a class="mark" href="#node-api-memory-management-types" id="node-api-memory-management-types">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_memory_management_types"></a></h4> 14581cb0ef41Sopenharmony_ci<h5><code>napi_handle_scope</code><span><a class="mark" href="#napi_handle_scope" id="napi_handle_scope">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_handle_scope"></a></h5> 14591cb0ef41Sopenharmony_ci<p>This is an abstraction used to control and modify the lifetime of objects 14601cb0ef41Sopenharmony_cicreated within a particular scope. In general, Node-API values are created 14611cb0ef41Sopenharmony_ciwithin the context of a handle scope. When a native method is called from 14621cb0ef41Sopenharmony_ciJavaScript, a default handle scope will exist. If the user does not explicitly 14631cb0ef41Sopenharmony_cicreate a new handle scope, Node-API values will be created in the default handle 14641cb0ef41Sopenharmony_ciscope. For any invocations of code outside the execution of a native method 14651cb0ef41Sopenharmony_ci(for instance, during a libuv callback invocation), the module is required to 14661cb0ef41Sopenharmony_cicreate a scope before invoking any functions that can result in the creation 14671cb0ef41Sopenharmony_ciof JavaScript values.</p> 14681cb0ef41Sopenharmony_ci<p>Handle scopes are created using <a href="#napi_open_handle_scope"><code>napi_open_handle_scope</code></a> and are destroyed 14691cb0ef41Sopenharmony_ciusing <a href="#napi_close_handle_scope"><code>napi_close_handle_scope</code></a>. Closing the scope can indicate to the GC 14701cb0ef41Sopenharmony_cithat all <code>napi_value</code>s created during the lifetime of the handle scope are no 14711cb0ef41Sopenharmony_cilonger referenced from the current stack frame.</p> 14721cb0ef41Sopenharmony_ci<p>For more details, review the <a href="#object-lifetime-management">Object lifetime management</a>.</p> 14731cb0ef41Sopenharmony_ci<h5><code>napi_escapable_handle_scope</code><span><a class="mark" href="#napi_escapable_handle_scope" id="napi_escapable_handle_scope">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_escapable_handle_scope"></a></h5> 14741cb0ef41Sopenharmony_ci<div class="api_metadata"> 14751cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 14761cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 14771cb0ef41Sopenharmony_ci</div> 14781cb0ef41Sopenharmony_ci<p>Escapable handle scopes are a special type of handle scope to return values 14791cb0ef41Sopenharmony_cicreated within a particular handle scope to a parent scope.</p> 14801cb0ef41Sopenharmony_ci<h5><code>napi_ref</code><span><a class="mark" href="#napi_ref" id="napi_ref">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_ref"></a></h5> 14811cb0ef41Sopenharmony_ci<div class="api_metadata"> 14821cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 14831cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 14841cb0ef41Sopenharmony_ci</div> 14851cb0ef41Sopenharmony_ci<p>This is the abstraction to use to reference a <code>napi_value</code>. This allows for 14861cb0ef41Sopenharmony_ciusers to manage the lifetimes of JavaScript values, including defining their 14871cb0ef41Sopenharmony_ciminimum lifetimes explicitly.</p> 14881cb0ef41Sopenharmony_ci<p>For more details, review the <a href="#object-lifetime-management">Object lifetime management</a>.</p> 14891cb0ef41Sopenharmony_ci<h5><code>napi_type_tag</code><span><a class="mark" href="#napi_type_tag" id="napi_type_tag">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_type_tag"></a></h5> 14901cb0ef41Sopenharmony_ci<div class="api_metadata"> 14911cb0ef41Sopenharmony_ci<span>Added in: v14.8.0, v12.19.0</span> 14921cb0ef41Sopenharmony_ci<span>N-API version: 8</span> 14931cb0ef41Sopenharmony_ci</div> 14941cb0ef41Sopenharmony_ci<p>A 128-bit value stored as two unsigned 64-bit integers. It serves as a UUID 14951cb0ef41Sopenharmony_ciwith which JavaScript objects or <a href="#napi_create_external">externals</a> can be "tagged" in order to 14961cb0ef41Sopenharmony_ciensure that they are of a certain type. This is a stronger check than 14971cb0ef41Sopenharmony_ci<a href="#napi_instanceof"><code>napi_instanceof</code></a>, because the latter can report a false positive if the 14981cb0ef41Sopenharmony_ciobject's prototype has been manipulated. Type-tagging is most useful in 14991cb0ef41Sopenharmony_ciconjunction with <a href="#napi_wrap"><code>napi_wrap</code></a> because it ensures that the pointer retrieved 15001cb0ef41Sopenharmony_cifrom a wrapped object can be safely cast to the native type corresponding to the 15011cb0ef41Sopenharmony_citype tag that had been previously applied to the JavaScript object.</p> 15021cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">struct</span> {</span> 15031cb0ef41Sopenharmony_ci <span class="hljs-type">uint64_t</span> lower; 15041cb0ef41Sopenharmony_ci <span class="hljs-type">uint64_t</span> upper; 15051cb0ef41Sopenharmony_ci} napi_type_tag;</code> <button class="copy-button">copy</button></pre> 15061cb0ef41Sopenharmony_ci<h5><code>napi_async_cleanup_hook_handle</code><span><a class="mark" href="#napi_async_cleanup_hook_handle" id="napi_async_cleanup_hook_handle">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_async_cleanup_hook_handle"></a></h5> 15071cb0ef41Sopenharmony_ci<div class="api_metadata"> 15081cb0ef41Sopenharmony_ci<span>Added in: v14.10.0, v12.19.0</span> 15091cb0ef41Sopenharmony_ci</div> 15101cb0ef41Sopenharmony_ci<p>An opaque value returned by <a href="#napi_add_async_cleanup_hook"><code>napi_add_async_cleanup_hook</code></a>. It must be passed 15111cb0ef41Sopenharmony_cito <a href="#napi_remove_async_cleanup_hook"><code>napi_remove_async_cleanup_hook</code></a> when the chain of asynchronous cleanup 15121cb0ef41Sopenharmony_cievents completes.</p> 15131cb0ef41Sopenharmony_ci<h4>Node-API callback types<span><a class="mark" href="#node-api-callback-types" id="node-api-callback-types">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_callback_types"></a></h4> 15141cb0ef41Sopenharmony_ci<h5><code>napi_callback_info</code><span><a class="mark" href="#napi_callback_info" id="napi_callback_info">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_callback_info"></a></h5> 15151cb0ef41Sopenharmony_ci<div class="api_metadata"> 15161cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 15171cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 15181cb0ef41Sopenharmony_ci</div> 15191cb0ef41Sopenharmony_ci<p>Opaque datatype that is passed to a callback function. It can be used for 15201cb0ef41Sopenharmony_cigetting additional information about the context in which the callback was 15211cb0ef41Sopenharmony_ciinvoked.</p> 15221cb0ef41Sopenharmony_ci<h5><code>napi_callback</code><span><a class="mark" href="#napi_callback" id="napi_callback">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_callback"></a></h5> 15231cb0ef41Sopenharmony_ci<div class="api_metadata"> 15241cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 15251cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 15261cb0ef41Sopenharmony_ci</div> 15271cb0ef41Sopenharmony_ci<p>Function pointer type for user-provided native functions which are to be 15281cb0ef41Sopenharmony_ciexposed to JavaScript via Node-API. Callback functions should satisfy the 15291cb0ef41Sopenharmony_cifollowing signature:</p> 15301cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">napi_value</span> <span class="hljs-params">(*napi_callback)</span><span class="hljs-params">(napi_env, napi_callback_info)</span>;</code> <button class="copy-button">copy</button></pre> 15311cb0ef41Sopenharmony_ci<p>Unless for reasons discussed in <a href="#object-lifetime-management">Object Lifetime Management</a>, creating a 15321cb0ef41Sopenharmony_cihandle and/or callback scope inside a <code>napi_callback</code> is not necessary.</p> 15331cb0ef41Sopenharmony_ci<h5><code>node_api_nogc_finalize</code><span><a class="mark" href="#node_api_nogc_finalize" id="node_api_nogc_finalize">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_nogc_finalize"></a></h5> 15341cb0ef41Sopenharmony_ci<div class="api_metadata"> 15351cb0ef41Sopenharmony_ci<span>Added in: v18.20.0</span> 15361cb0ef41Sopenharmony_ci</div> 15371cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 15381cb0ef41Sopenharmony_ci<p>Function pointer type for add-on provided functions that allow the user to be 15391cb0ef41Sopenharmony_cinotified when externally-owned data is ready to be cleaned up because the 15401cb0ef41Sopenharmony_ciobject it was associated with has been garbage-collected. The user must provide 15411cb0ef41Sopenharmony_cia function satisfying the following signature which would get called upon the 15421cb0ef41Sopenharmony_ciobject's collection. Currently, <code>node_api_nogc_finalize</code> can be used for 15431cb0ef41Sopenharmony_cifinding out when objects that have external data are collected.</p> 15441cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*node_api_nogc_finalize)</span><span class="hljs-params">(node_api_nogc_env env, 15451cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_data, 15461cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint)</span>;</code> <button class="copy-button">copy</button></pre> 15471cb0ef41Sopenharmony_ci<p>Unless for reasons discussed in <a href="#object-lifetime-management">Object Lifetime Management</a>, creating a 15481cb0ef41Sopenharmony_cihandle and/or callback scope inside the function body is not necessary.</p> 15491cb0ef41Sopenharmony_ci<p>Since these functions may be called while the JavaScript engine is in a state 15501cb0ef41Sopenharmony_ciwhere it cannot execute JavaScript code, only Node-APIs which accept a 15511cb0ef41Sopenharmony_ci<code>node_api_nogc_env</code> as their first parameter may be called. 15521cb0ef41Sopenharmony_ci<a href="#node_api_post_finalizer"><code>node_api_post_finalizer</code></a> can be used to schedule Node-API calls that 15531cb0ef41Sopenharmony_cirequire access to the JavaScript engine's state to run after the current 15541cb0ef41Sopenharmony_cigarbage collection cycle has completed.</p> 15551cb0ef41Sopenharmony_ci<p>In the case of <a href="#node_api_create_external_string_latin1"><code>node_api_create_external_string_latin1</code></a> and 15561cb0ef41Sopenharmony_ci<a href="#node_api_create_external_string_utf16"><code>node_api_create_external_string_utf16</code></a> the <code>env</code> parameter may be null, 15571cb0ef41Sopenharmony_cibecause external strings can be collected during the latter part of environment 15581cb0ef41Sopenharmony_cishutdown.</p> 15591cb0ef41Sopenharmony_ci<p>Change History:</p> 15601cb0ef41Sopenharmony_ci<ul> 15611cb0ef41Sopenharmony_ci<li> 15621cb0ef41Sopenharmony_ci<p>experimental (<code>NAPI_EXPERIMENTAL</code>):</p> 15631cb0ef41Sopenharmony_ci<p>Only Node-API calls that accept a <code>node_api_nogc_env</code> as their first 15641cb0ef41Sopenharmony_ciparameter may be called, otherwise the application will be terminated with an 15651cb0ef41Sopenharmony_ciappropriate error message. This feature can be turned off by defining 15661cb0ef41Sopenharmony_ci<code>NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT</code>.</p> 15671cb0ef41Sopenharmony_ci</li> 15681cb0ef41Sopenharmony_ci</ul> 15691cb0ef41Sopenharmony_ci<h5><code>napi_finalize</code><span><a class="mark" href="#napi_finalize" id="napi_finalize">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_finalize"></a></h5> 15701cb0ef41Sopenharmony_ci<div class="api_metadata"> 15711cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 15721cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 15731cb0ef41Sopenharmony_ci</div> 15741cb0ef41Sopenharmony_ci<p>Function pointer type for add-on provided function that allow the user to 15751cb0ef41Sopenharmony_cischedule a group of calls to Node-APIs in response to a garbage collection 15761cb0ef41Sopenharmony_cievent, after the garbage collection cycle has completed. These function 15771cb0ef41Sopenharmony_cipointers can be used with <a href="#node_api_post_finalizer"><code>node_api_post_finalizer</code></a>.</p> 15781cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*napi_finalize)</span><span class="hljs-params">(napi_env env, 15791cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_data, 15801cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint)</span>;</code> <button class="copy-button">copy</button></pre> 15811cb0ef41Sopenharmony_ci<p>Change History:</p> 15821cb0ef41Sopenharmony_ci<ul> 15831cb0ef41Sopenharmony_ci<li> 15841cb0ef41Sopenharmony_ci<p>experimental (<code>NAPI_EXPERIMENTAL</code> is defined):</p> 15851cb0ef41Sopenharmony_ci<p>A function of this type may no longer be used as a finalizer, except with 15861cb0ef41Sopenharmony_ci<a href="#node_api_post_finalizer"><code>node_api_post_finalizer</code></a>. <a href="#node_api_nogc_finalize"><code>node_api_nogc_finalize</code></a> must be used 15871cb0ef41Sopenharmony_ciinstead. This feature can be turned off by defining 15881cb0ef41Sopenharmony_ci<code>NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT</code>.</p> 15891cb0ef41Sopenharmony_ci</li> 15901cb0ef41Sopenharmony_ci</ul> 15911cb0ef41Sopenharmony_ci<h5><code>napi_async_execute_callback</code><span><a class="mark" href="#napi_async_execute_callback" id="napi_async_execute_callback">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_async_execute_callback"></a></h5> 15921cb0ef41Sopenharmony_ci<div class="api_metadata"> 15931cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 15941cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 15951cb0ef41Sopenharmony_ci</div> 15961cb0ef41Sopenharmony_ci<p>Function pointer used with functions that support asynchronous 15971cb0ef41Sopenharmony_cioperations. Callback functions must satisfy the following signature:</p> 15981cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*napi_async_execute_callback)</span><span class="hljs-params">(napi_env env, <span class="hljs-type">void</span>* data)</span>;</code> <button class="copy-button">copy</button></pre> 15991cb0ef41Sopenharmony_ci<p>Implementations of this function must avoid making Node-API calls that execute 16001cb0ef41Sopenharmony_ciJavaScript or interact with JavaScript objects. Node-API calls should be in the 16011cb0ef41Sopenharmony_ci<code>napi_async_complete_callback</code> instead. Do not use the <code>napi_env</code> parameter as 16021cb0ef41Sopenharmony_ciit will likely result in execution of JavaScript.</p> 16031cb0ef41Sopenharmony_ci<h5><code>napi_async_complete_callback</code><span><a class="mark" href="#napi_async_complete_callback" id="napi_async_complete_callback">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_async_complete_callback"></a></h5> 16041cb0ef41Sopenharmony_ci<div class="api_metadata"> 16051cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 16061cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 16071cb0ef41Sopenharmony_ci</div> 16081cb0ef41Sopenharmony_ci<p>Function pointer used with functions that support asynchronous 16091cb0ef41Sopenharmony_cioperations. Callback functions must satisfy the following signature:</p> 16101cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*napi_async_complete_callback)</span><span class="hljs-params">(napi_env env, 16111cb0ef41Sopenharmony_ci napi_status status, 16121cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data)</span>;</code> <button class="copy-button">copy</button></pre> 16131cb0ef41Sopenharmony_ci<p>Unless for reasons discussed in <a href="#object-lifetime-management">Object Lifetime Management</a>, creating a 16141cb0ef41Sopenharmony_cihandle and/or callback scope inside the function body is not necessary.</p> 16151cb0ef41Sopenharmony_ci<h5><code>napi_threadsafe_function_call_js</code><span><a class="mark" href="#napi_threadsafe_function_call_js" id="napi_threadsafe_function_call_js">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_threadsafe_function_call_js"></a></h5> 16161cb0ef41Sopenharmony_ci<div class="api_metadata"> 16171cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 16181cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 16191cb0ef41Sopenharmony_ci</div> 16201cb0ef41Sopenharmony_ci<p>Function pointer used with asynchronous thread-safe function calls. The callback 16211cb0ef41Sopenharmony_ciwill be called on the main thread. Its purpose is to use a data item arriving 16221cb0ef41Sopenharmony_civia the queue from one of the secondary threads to construct the parameters 16231cb0ef41Sopenharmony_cinecessary for a call into JavaScript, usually via <code>napi_call_function</code>, and then 16241cb0ef41Sopenharmony_cimake the call into JavaScript.</p> 16251cb0ef41Sopenharmony_ci<p>The data arriving from the secondary thread via the queue is given in the <code>data</code> 16261cb0ef41Sopenharmony_ciparameter and the JavaScript function to call is given in the <code>js_callback</code> 16271cb0ef41Sopenharmony_ciparameter.</p> 16281cb0ef41Sopenharmony_ci<p>Node-API sets up the environment prior to calling this callback, so it is 16291cb0ef41Sopenharmony_cisufficient to call the JavaScript function via <code>napi_call_function</code> rather than 16301cb0ef41Sopenharmony_civia <code>napi_make_callback</code>.</p> 16311cb0ef41Sopenharmony_ci<p>Callback functions must satisfy the following signature:</p> 16321cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*napi_threadsafe_function_call_js)</span><span class="hljs-params">(napi_env env, 16331cb0ef41Sopenharmony_ci napi_value js_callback, 16341cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* context, 16351cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data)</span>;</code> <button class="copy-button">copy</button></pre> 16361cb0ef41Sopenharmony_ci<ul> 16371cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment to use for API calls, or <code>NULL</code> if the thread-safe 16381cb0ef41Sopenharmony_cifunction is being torn down and <code>data</code> may need to be freed.</li> 16391cb0ef41Sopenharmony_ci<li><code>[in] js_callback</code>: The JavaScript function to call, or <code>NULL</code> if the 16401cb0ef41Sopenharmony_cithread-safe function is being torn down and <code>data</code> may need to be freed. It 16411cb0ef41Sopenharmony_cimay also be <code>NULL</code> if the thread-safe function was created without 16421cb0ef41Sopenharmony_ci<code>js_callback</code>.</li> 16431cb0ef41Sopenharmony_ci<li><code>[in] context</code>: The optional data with which the thread-safe function was 16441cb0ef41Sopenharmony_cicreated.</li> 16451cb0ef41Sopenharmony_ci<li><code>[in] data</code>: Data created by the secondary thread. It is the responsibility of 16461cb0ef41Sopenharmony_cithe callback to convert this native data to JavaScript values (with Node-API 16471cb0ef41Sopenharmony_cifunctions) that can be passed as parameters when <code>js_callback</code> is invoked. 16481cb0ef41Sopenharmony_ciThis pointer is managed entirely by the threads and this callback. Thus this 16491cb0ef41Sopenharmony_cicallback should free the data.</li> 16501cb0ef41Sopenharmony_ci</ul> 16511cb0ef41Sopenharmony_ci<p>Unless for reasons discussed in <a href="#object-lifetime-management">Object Lifetime Management</a>, creating a 16521cb0ef41Sopenharmony_cihandle and/or callback scope inside the function body is not necessary.</p> 16531cb0ef41Sopenharmony_ci<h5><code>napi_cleanup_hook</code><span><a class="mark" href="#napi_cleanup_hook" id="napi_cleanup_hook">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_cleanup_hook"></a></h5> 16541cb0ef41Sopenharmony_ci<div class="api_metadata"> 16551cb0ef41Sopenharmony_ci<span>Added in: v18.13.0</span> 16561cb0ef41Sopenharmony_ci<span>N-API version: 3</span> 16571cb0ef41Sopenharmony_ci</div> 16581cb0ef41Sopenharmony_ci<p>Function pointer used with <a href="#napi_add_env_cleanup_hook"><code>napi_add_env_cleanup_hook</code></a>. It will be called 16591cb0ef41Sopenharmony_ciwhen the environment is being torn down.</p> 16601cb0ef41Sopenharmony_ci<p>Callback functions must satisfy the following signature:</p> 16611cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*napi_cleanup_hook)</span><span class="hljs-params">(<span class="hljs-type">void</span>* data)</span>;</code> <button class="copy-button">copy</button></pre> 16621cb0ef41Sopenharmony_ci<ul> 16631cb0ef41Sopenharmony_ci<li><code>[in] data</code>: The data that was passed to <a href="#napi_add_env_cleanup_hook"><code>napi_add_env_cleanup_hook</code></a>.</li> 16641cb0ef41Sopenharmony_ci</ul> 16651cb0ef41Sopenharmony_ci<h5><code>napi_async_cleanup_hook</code><span><a class="mark" href="#napi_async_cleanup_hook" id="napi_async_cleanup_hook">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_async_cleanup_hook"></a></h5> 16661cb0ef41Sopenharmony_ci<div class="api_metadata"> 16671cb0ef41Sopenharmony_ci<span>Added in: v14.10.0, v12.19.0</span> 16681cb0ef41Sopenharmony_ci</div> 16691cb0ef41Sopenharmony_ci<p>Function pointer used with <a href="#napi_add_async_cleanup_hook"><code>napi_add_async_cleanup_hook</code></a>. It will be called 16701cb0ef41Sopenharmony_ciwhen the environment is being torn down.</p> 16711cb0ef41Sopenharmony_ci<p>Callback functions must satisfy the following signature:</p> 16721cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*napi_async_cleanup_hook)</span><span class="hljs-params">(napi_async_cleanup_hook_handle handle, 16731cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data)</span>;</code> <button class="copy-button">copy</button></pre> 16741cb0ef41Sopenharmony_ci<ul> 16751cb0ef41Sopenharmony_ci<li><code>[in] handle</code>: The handle that must be passed to 16761cb0ef41Sopenharmony_ci<a href="#napi_remove_async_cleanup_hook"><code>napi_remove_async_cleanup_hook</code></a> after completion of the asynchronous 16771cb0ef41Sopenharmony_cicleanup.</li> 16781cb0ef41Sopenharmony_ci<li><code>[in] data</code>: The data that was passed to <a href="#napi_add_async_cleanup_hook"><code>napi_add_async_cleanup_hook</code></a>.</li> 16791cb0ef41Sopenharmony_ci</ul> 16801cb0ef41Sopenharmony_ci<p>The body of the function should initiate the asynchronous cleanup actions at the 16811cb0ef41Sopenharmony_ciend of which <code>handle</code> must be passed in a call to 16821cb0ef41Sopenharmony_ci<a href="#napi_remove_async_cleanup_hook"><code>napi_remove_async_cleanup_hook</code></a>.</p> 16831cb0ef41Sopenharmony_ci</section><section><h3>Error handling<span><a class="mark" href="#error-handling" id="error-handling">#</a></span><a aria-hidden="true" class="legacy" id="n_api_error_handling"></a></h3> 16841cb0ef41Sopenharmony_ci<p>Node-API uses both return values and JavaScript exceptions for error handling. 16851cb0ef41Sopenharmony_ciThe following sections explain the approach for each case.</p> 16861cb0ef41Sopenharmony_ci<h4>Return values<span><a class="mark" href="#return-values" id="return-values">#</a></span><a aria-hidden="true" class="legacy" id="n_api_return_values"></a></h4> 16871cb0ef41Sopenharmony_ci<p>All of the Node-API functions share the same error handling pattern. The 16881cb0ef41Sopenharmony_cireturn type of all API functions is <code>napi_status</code>.</p> 16891cb0ef41Sopenharmony_ci<p>The return value will be <code>napi_ok</code> if the request was successful and 16901cb0ef41Sopenharmony_cino uncaught JavaScript exception was thrown. If an error occurred AND 16911cb0ef41Sopenharmony_cian exception was thrown, the <code>napi_status</code> value for the error 16921cb0ef41Sopenharmony_ciwill be returned. If an exception was thrown, and no error occurred, 16931cb0ef41Sopenharmony_ci<code>napi_pending_exception</code> will be returned.</p> 16941cb0ef41Sopenharmony_ci<p>In cases where a return value other than <code>napi_ok</code> or 16951cb0ef41Sopenharmony_ci<code>napi_pending_exception</code> is returned, <a href="#napi_is_exception_pending"><code>napi_is_exception_pending</code></a> 16961cb0ef41Sopenharmony_cimust be called to check if an exception is pending. 16971cb0ef41Sopenharmony_ciSee the section on exceptions for more details.</p> 16981cb0ef41Sopenharmony_ci<p>The full set of possible <code>napi_status</code> values is defined 16991cb0ef41Sopenharmony_ciin <code>napi_api_types.h</code>.</p> 17001cb0ef41Sopenharmony_ci<p>The <code>napi_status</code> return value provides a VM-independent representation of 17011cb0ef41Sopenharmony_cithe error which occurred. In some cases it is useful to be able to get 17021cb0ef41Sopenharmony_cimore detailed information, including a string representing the error as well as 17031cb0ef41Sopenharmony_ciVM (engine)-specific information.</p> 17041cb0ef41Sopenharmony_ci<p>In order to retrieve this information <a href="#napi_get_last_error_info"><code>napi_get_last_error_info</code></a> 17051cb0ef41Sopenharmony_ciis provided which returns a <code>napi_extended_error_info</code> structure. 17061cb0ef41Sopenharmony_ciThe format of the <code>napi_extended_error_info</code> structure is as follows:</p> 17071cb0ef41Sopenharmony_ci<div class="api_metadata"> 17081cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 17091cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 17101cb0ef41Sopenharmony_ci</div> 17111cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">struct</span> <span class="hljs-title">napi_extended_error_info</span> {</span> 17121cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* error_message; 17131cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* engine_reserved; 17141cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> engine_error_code; 17151cb0ef41Sopenharmony_ci napi_status error_code; 17161cb0ef41Sopenharmony_ci};</code> <button class="copy-button">copy</button></pre> 17171cb0ef41Sopenharmony_ci<ul> 17181cb0ef41Sopenharmony_ci<li><code>error_message</code>: Textual representation of the error that occurred.</li> 17191cb0ef41Sopenharmony_ci<li><code>engine_reserved</code>: Opaque handle reserved for engine use only.</li> 17201cb0ef41Sopenharmony_ci<li><code>engine_error_code</code>: VM specific error code.</li> 17211cb0ef41Sopenharmony_ci<li><code>error_code</code>: Node-API status code for the last error.</li> 17221cb0ef41Sopenharmony_ci</ul> 17231cb0ef41Sopenharmony_ci<p><a href="#napi_get_last_error_info"><code>napi_get_last_error_info</code></a> returns the information for the last 17241cb0ef41Sopenharmony_ciNode-API call that was made.</p> 17251cb0ef41Sopenharmony_ci<p>Do not rely on the content or format of any of the extended information as it 17261cb0ef41Sopenharmony_ciis not subject to SemVer and may change at any time. It is intended only for 17271cb0ef41Sopenharmony_cilogging purposes.</p> 17281cb0ef41Sopenharmony_ci<h5><code>napi_get_last_error_info</code><span><a class="mark" href="#napi_get_last_error_info" id="napi_get_last_error_info">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_last_error_info"></a></h5> 17291cb0ef41Sopenharmony_ci<div class="api_metadata"> 17301cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 17311cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 17321cb0ef41Sopenharmony_ci</div> 17331cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status 17341cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_get_last_error_info</span><span class="hljs-params">(node_api_nogc_env env, 17351cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> napi_extended_error_info** result)</span>;</code> <button class="copy-button">copy</button></pre> 17361cb0ef41Sopenharmony_ci<ul> 17371cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 17381cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The <code>napi_extended_error_info</code> structure with more 17391cb0ef41Sopenharmony_ciinformation about the error.</li> 17401cb0ef41Sopenharmony_ci</ul> 17411cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 17421cb0ef41Sopenharmony_ci<p>This API retrieves a <code>napi_extended_error_info</code> structure with information 17431cb0ef41Sopenharmony_ciabout the last error that occurred.</p> 17441cb0ef41Sopenharmony_ci<p>The content of the <code>napi_extended_error_info</code> returned is only valid up until 17451cb0ef41Sopenharmony_cia Node-API function is called on the same <code>env</code>. This includes a call to 17461cb0ef41Sopenharmony_ci<code>napi_is_exception_pending</code> so it may often be necessary to make a copy 17471cb0ef41Sopenharmony_ciof the information so that it can be used later. The pointer returned 17481cb0ef41Sopenharmony_ciin <code>error_message</code> points to a statically-defined string so it is safe to use 17491cb0ef41Sopenharmony_cithat pointer if you have copied it out of the <code>error_message</code> field (which will 17501cb0ef41Sopenharmony_cibe overwritten) before another Node-API function was called.</p> 17511cb0ef41Sopenharmony_ci<p>Do not rely on the content or format of any of the extended information as it 17521cb0ef41Sopenharmony_ciis not subject to SemVer and may change at any time. It is intended only for 17531cb0ef41Sopenharmony_cilogging purposes.</p> 17541cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 17551cb0ef41Sopenharmony_ci<h4>Exceptions<span><a class="mark" href="#exceptions" id="exceptions">#</a></span><a aria-hidden="true" class="legacy" id="n_api_exceptions"></a></h4> 17561cb0ef41Sopenharmony_ci<p>Any Node-API function call may result in a pending JavaScript exception. This is 17571cb0ef41Sopenharmony_cithe case for any of the API functions, even those that may not cause the 17581cb0ef41Sopenharmony_ciexecution of JavaScript.</p> 17591cb0ef41Sopenharmony_ci<p>If the <code>napi_status</code> returned by a function is <code>napi_ok</code> then no 17601cb0ef41Sopenharmony_ciexception is pending and no additional action is required. If the 17611cb0ef41Sopenharmony_ci<code>napi_status</code> returned is anything other than <code>napi_ok</code> or 17621cb0ef41Sopenharmony_ci<code>napi_pending_exception</code>, in order to try to recover and continue 17631cb0ef41Sopenharmony_ciinstead of simply returning immediately, <a href="#napi_is_exception_pending"><code>napi_is_exception_pending</code></a> 17641cb0ef41Sopenharmony_cimust be called in order to determine if an exception is pending or not.</p> 17651cb0ef41Sopenharmony_ci<p>In many cases when a Node-API function is called and an exception is 17661cb0ef41Sopenharmony_cialready pending, the function will return immediately with a 17671cb0ef41Sopenharmony_ci<code>napi_status</code> of <code>napi_pending_exception</code>. However, this is not the case 17681cb0ef41Sopenharmony_cifor all functions. Node-API allows a subset of the functions to be 17691cb0ef41Sopenharmony_cicalled to allow for some minimal cleanup before returning to JavaScript. 17701cb0ef41Sopenharmony_ciIn that case, <code>napi_status</code> will reflect the status for the function. It 17711cb0ef41Sopenharmony_ciwill not reflect previous pending exceptions. To avoid confusion, check 17721cb0ef41Sopenharmony_cithe error status after every function call.</p> 17731cb0ef41Sopenharmony_ci<p>When an exception is pending one of two approaches can be employed.</p> 17741cb0ef41Sopenharmony_ci<p>The first approach is to do any appropriate cleanup and then return so that 17751cb0ef41Sopenharmony_ciexecution will return to JavaScript. As part of the transition back to 17761cb0ef41Sopenharmony_ciJavaScript, the exception will be thrown at the point in the JavaScript 17771cb0ef41Sopenharmony_cicode where the native method was invoked. The behavior of most Node-API calls 17781cb0ef41Sopenharmony_ciis unspecified while an exception is pending, and many will simply return 17791cb0ef41Sopenharmony_ci<code>napi_pending_exception</code>, so do as little as possible and then return to 17801cb0ef41Sopenharmony_ciJavaScript where the exception can be handled.</p> 17811cb0ef41Sopenharmony_ci<p>The second approach is to try to handle the exception. There will be cases 17821cb0ef41Sopenharmony_ciwhere the native code can catch the exception, take the appropriate action, 17831cb0ef41Sopenharmony_ciand then continue. This is only recommended in specific cases 17841cb0ef41Sopenharmony_ciwhere it is known that the exception can be safely handled. In these 17851cb0ef41Sopenharmony_cicases <a href="#napi_get_and_clear_last_exception"><code>napi_get_and_clear_last_exception</code></a> can be used to get and 17861cb0ef41Sopenharmony_ciclear the exception. On success, result will contain the handle to 17871cb0ef41Sopenharmony_cithe last JavaScript <code>Object</code> thrown. If it is determined, after 17881cb0ef41Sopenharmony_ciretrieving the exception, the exception cannot be handled after all 17891cb0ef41Sopenharmony_ciit can be re-thrown it with <a href="#napi_throw"><code>napi_throw</code></a> where error is the 17901cb0ef41Sopenharmony_ciJavaScript value to be thrown.</p> 17911cb0ef41Sopenharmony_ci<p>The following utility functions are also available in case native code 17921cb0ef41Sopenharmony_cineeds to throw an exception or determine if a <code>napi_value</code> is an instance 17931cb0ef41Sopenharmony_ciof a JavaScript <code>Error</code> object: <a href="#napi_throw_error"><code>napi_throw_error</code></a>, 17941cb0ef41Sopenharmony_ci<a href="#napi_throw_type_error"><code>napi_throw_type_error</code></a>, <a href="#napi_throw_range_error"><code>napi_throw_range_error</code></a>, <a href="#node_api_throw_syntax_error"><code>node_api_throw_syntax_error</code></a> and <a href="#napi_is_error"><code>napi_is_error</code></a>.</p> 17951cb0ef41Sopenharmony_ci<p>The following utility functions are also available in case native 17961cb0ef41Sopenharmony_cicode needs to create an <code>Error</code> object: <a href="#napi_create_error"><code>napi_create_error</code></a>, 17971cb0ef41Sopenharmony_ci<a href="#napi_create_type_error"><code>napi_create_type_error</code></a>, <a href="#napi_create_range_error"><code>napi_create_range_error</code></a> and <a href="#node_api_create_syntax_error"><code>node_api_create_syntax_error</code></a>, 17981cb0ef41Sopenharmony_ciwhere result is the <code>napi_value</code> that refers to the newly created 17991cb0ef41Sopenharmony_ciJavaScript <code>Error</code> object.</p> 18001cb0ef41Sopenharmony_ci<p>The Node.js project is adding error codes to all of the errors 18011cb0ef41Sopenharmony_cigenerated internally. The goal is for applications to use these 18021cb0ef41Sopenharmony_cierror codes for all error checking. The associated error messages 18031cb0ef41Sopenharmony_ciwill remain, but will only be meant to be used for logging and 18041cb0ef41Sopenharmony_cidisplay with the expectation that the message can change without 18051cb0ef41Sopenharmony_ciSemVer applying. In order to support this model with Node-API, both 18061cb0ef41Sopenharmony_ciin internal functionality and for module specific functionality 18071cb0ef41Sopenharmony_ci(as its good practice), the <code>throw_</code> and <code>create_</code> functions 18081cb0ef41Sopenharmony_citake an optional code parameter which is the string for the code 18091cb0ef41Sopenharmony_cito be added to the error object. If the optional parameter is <code>NULL</code> 18101cb0ef41Sopenharmony_cithen no code will be associated with the error. If a code is provided, 18111cb0ef41Sopenharmony_cithe name associated with the error is also updated to be:</p> 18121cb0ef41Sopenharmony_ci<pre><code class="language-text">originalName [code]</code> <button class="copy-button">copy</button></pre> 18131cb0ef41Sopenharmony_ci<p>where <code>originalName</code> is the original name associated with the error 18141cb0ef41Sopenharmony_ciand <code>code</code> is the code that was provided. For example, if the code 18151cb0ef41Sopenharmony_ciis <code>'ERR_ERROR_1'</code> and a <code>TypeError</code> is being created the name will be:</p> 18161cb0ef41Sopenharmony_ci<pre><code class="language-text">TypeError [ERR_ERROR_1]</code> <button class="copy-button">copy</button></pre> 18171cb0ef41Sopenharmony_ci<h5><code>napi_throw</code><span><a class="mark" href="#napi_throw" id="napi_throw">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_throw"></a></h5> 18181cb0ef41Sopenharmony_ci<div class="api_metadata"> 18191cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 18201cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 18211cb0ef41Sopenharmony_ci</div> 18221cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_throw</span><span class="hljs-params">(napi_env env, napi_value error)</span>;</code> <button class="copy-button">copy</button></pre> 18231cb0ef41Sopenharmony_ci<ul> 18241cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 18251cb0ef41Sopenharmony_ci<li><code>[in] error</code>: The JavaScript value to be thrown.</li> 18261cb0ef41Sopenharmony_ci</ul> 18271cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 18281cb0ef41Sopenharmony_ci<p>This API throws the JavaScript value provided.</p> 18291cb0ef41Sopenharmony_ci<h5><code>napi_throw_error</code><span><a class="mark" href="#napi_throw_error" id="napi_throw_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_throw_error"></a></h5> 18301cb0ef41Sopenharmony_ci<div class="api_metadata"> 18311cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 18321cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 18331cb0ef41Sopenharmony_ci</div> 18341cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_throw_error</span><span class="hljs-params">(napi_env env, 18351cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* code, 18361cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* msg)</span>;</code> <button class="copy-button">copy</button></pre> 18371cb0ef41Sopenharmony_ci<ul> 18381cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 18391cb0ef41Sopenharmony_ci<li><code>[in] code</code>: Optional error code to be set on the error.</li> 18401cb0ef41Sopenharmony_ci<li><code>[in] msg</code>: C string representing the text to be associated with the error.</li> 18411cb0ef41Sopenharmony_ci</ul> 18421cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 18431cb0ef41Sopenharmony_ci<p>This API throws a JavaScript <code>Error</code> with the text provided.</p> 18441cb0ef41Sopenharmony_ci<h5><code>napi_throw_type_error</code><span><a class="mark" href="#napi_throw_type_error" id="napi_throw_type_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_throw_type_error"></a></h5> 18451cb0ef41Sopenharmony_ci<div class="api_metadata"> 18461cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 18471cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 18481cb0ef41Sopenharmony_ci</div> 18491cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_throw_type_error</span><span class="hljs-params">(napi_env env, 18501cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* code, 18511cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* msg)</span>;</code> <button class="copy-button">copy</button></pre> 18521cb0ef41Sopenharmony_ci<ul> 18531cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 18541cb0ef41Sopenharmony_ci<li><code>[in] code</code>: Optional error code to be set on the error.</li> 18551cb0ef41Sopenharmony_ci<li><code>[in] msg</code>: C string representing the text to be associated with the error.</li> 18561cb0ef41Sopenharmony_ci</ul> 18571cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 18581cb0ef41Sopenharmony_ci<p>This API throws a JavaScript <code>TypeError</code> with the text provided.</p> 18591cb0ef41Sopenharmony_ci<h5><code>napi_throw_range_error</code><span><a class="mark" href="#napi_throw_range_error" id="napi_throw_range_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_throw_range_error"></a></h5> 18601cb0ef41Sopenharmony_ci<div class="api_metadata"> 18611cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 18621cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 18631cb0ef41Sopenharmony_ci</div> 18641cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_throw_range_error</span><span class="hljs-params">(napi_env env, 18651cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* code, 18661cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* msg)</span>;</code> <button class="copy-button">copy</button></pre> 18671cb0ef41Sopenharmony_ci<ul> 18681cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 18691cb0ef41Sopenharmony_ci<li><code>[in] code</code>: Optional error code to be set on the error.</li> 18701cb0ef41Sopenharmony_ci<li><code>[in] msg</code>: C string representing the text to be associated with the error.</li> 18711cb0ef41Sopenharmony_ci</ul> 18721cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 18731cb0ef41Sopenharmony_ci<p>This API throws a JavaScript <code>RangeError</code> with the text provided.</p> 18741cb0ef41Sopenharmony_ci<h5><code>node_api_throw_syntax_error</code><span><a class="mark" href="#node_api_throw_syntax_error" id="node_api_throw_syntax_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_throw_syntax_error"></a></h5> 18751cb0ef41Sopenharmony_ci<div class="api_metadata"> 18761cb0ef41Sopenharmony_ci<span>Added in: v17.2.0, v16.14.0</span> 18771cb0ef41Sopenharmony_ci<span>N-API version: 9</span> 18781cb0ef41Sopenharmony_ci</div> 18791cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">node_api_throw_syntax_error</span><span class="hljs-params">(napi_env env, 18801cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* code, 18811cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* msg)</span>;</code> <button class="copy-button">copy</button></pre> 18821cb0ef41Sopenharmony_ci<ul> 18831cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 18841cb0ef41Sopenharmony_ci<li><code>[in] code</code>: Optional error code to be set on the error.</li> 18851cb0ef41Sopenharmony_ci<li><code>[in] msg</code>: C string representing the text to be associated with the error.</li> 18861cb0ef41Sopenharmony_ci</ul> 18871cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 18881cb0ef41Sopenharmony_ci<p>This API throws a JavaScript <code>SyntaxError</code> with the text provided.</p> 18891cb0ef41Sopenharmony_ci<h5><code>napi_is_error</code><span><a class="mark" href="#napi_is_error" id="napi_is_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_error"></a></h5> 18901cb0ef41Sopenharmony_ci<div class="api_metadata"> 18911cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 18921cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 18931cb0ef41Sopenharmony_ci</div> 18941cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_is_error</span><span class="hljs-params">(napi_env env, 18951cb0ef41Sopenharmony_ci napi_value value, 18961cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 18971cb0ef41Sopenharmony_ci<ul> 18981cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 18991cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The <code>napi_value</code> to be checked.</li> 19001cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Boolean value that is set to true if <code>napi_value</code> represents 19011cb0ef41Sopenharmony_cian error, false otherwise.</li> 19021cb0ef41Sopenharmony_ci</ul> 19031cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 19041cb0ef41Sopenharmony_ci<p>This API queries a <code>napi_value</code> to check if it represents an error object.</p> 19051cb0ef41Sopenharmony_ci<h5><code>napi_create_error</code><span><a class="mark" href="#napi_create_error" id="napi_create_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_error"></a></h5> 19061cb0ef41Sopenharmony_ci<div class="api_metadata"> 19071cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 19081cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 19091cb0ef41Sopenharmony_ci</div> 19101cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_create_error</span><span class="hljs-params">(napi_env env, 19111cb0ef41Sopenharmony_ci napi_value code, 19121cb0ef41Sopenharmony_ci napi_value msg, 19131cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 19141cb0ef41Sopenharmony_ci<ul> 19151cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 19161cb0ef41Sopenharmony_ci<li><code>[in] code</code>: Optional <code>napi_value</code> with the string for the error code to be 19171cb0ef41Sopenharmony_ciassociated with the error.</li> 19181cb0ef41Sopenharmony_ci<li><code>[in] msg</code>: <code>napi_value</code> that references a JavaScript <code>string</code> to be used as 19191cb0ef41Sopenharmony_cithe message for the <code>Error</code>.</li> 19201cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the error created.</li> 19211cb0ef41Sopenharmony_ci</ul> 19221cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 19231cb0ef41Sopenharmony_ci<p>This API returns a JavaScript <code>Error</code> with the text provided.</p> 19241cb0ef41Sopenharmony_ci<h5><code>napi_create_type_error</code><span><a class="mark" href="#napi_create_type_error" id="napi_create_type_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_type_error"></a></h5> 19251cb0ef41Sopenharmony_ci<div class="api_metadata"> 19261cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 19271cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 19281cb0ef41Sopenharmony_ci</div> 19291cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_create_type_error</span><span class="hljs-params">(napi_env env, 19301cb0ef41Sopenharmony_ci napi_value code, 19311cb0ef41Sopenharmony_ci napi_value msg, 19321cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 19331cb0ef41Sopenharmony_ci<ul> 19341cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 19351cb0ef41Sopenharmony_ci<li><code>[in] code</code>: Optional <code>napi_value</code> with the string for the error code to be 19361cb0ef41Sopenharmony_ciassociated with the error.</li> 19371cb0ef41Sopenharmony_ci<li><code>[in] msg</code>: <code>napi_value</code> that references a JavaScript <code>string</code> to be used as 19381cb0ef41Sopenharmony_cithe message for the <code>Error</code>.</li> 19391cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the error created.</li> 19401cb0ef41Sopenharmony_ci</ul> 19411cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 19421cb0ef41Sopenharmony_ci<p>This API returns a JavaScript <code>TypeError</code> with the text provided.</p> 19431cb0ef41Sopenharmony_ci<h5><code>napi_create_range_error</code><span><a class="mark" href="#napi_create_range_error" id="napi_create_range_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_range_error"></a></h5> 19441cb0ef41Sopenharmony_ci<div class="api_metadata"> 19451cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 19461cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 19471cb0ef41Sopenharmony_ci</div> 19481cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_create_range_error</span><span class="hljs-params">(napi_env env, 19491cb0ef41Sopenharmony_ci napi_value code, 19501cb0ef41Sopenharmony_ci napi_value msg, 19511cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 19521cb0ef41Sopenharmony_ci<ul> 19531cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 19541cb0ef41Sopenharmony_ci<li><code>[in] code</code>: Optional <code>napi_value</code> with the string for the error code to be 19551cb0ef41Sopenharmony_ciassociated with the error.</li> 19561cb0ef41Sopenharmony_ci<li><code>[in] msg</code>: <code>napi_value</code> that references a JavaScript <code>string</code> to be used as 19571cb0ef41Sopenharmony_cithe message for the <code>Error</code>.</li> 19581cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the error created.</li> 19591cb0ef41Sopenharmony_ci</ul> 19601cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 19611cb0ef41Sopenharmony_ci<p>This API returns a JavaScript <code>RangeError</code> with the text provided.</p> 19621cb0ef41Sopenharmony_ci<h5><code>node_api_create_syntax_error</code><span><a class="mark" href="#node_api_create_syntax_error" id="node_api_create_syntax_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_create_syntax_error"></a></h5> 19631cb0ef41Sopenharmony_ci<div class="api_metadata"> 19641cb0ef41Sopenharmony_ci<span>Added in: v17.2.0, v16.14.0</span> 19651cb0ef41Sopenharmony_ci<span>N-API version: 9</span> 19661cb0ef41Sopenharmony_ci</div> 19671cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">node_api_create_syntax_error</span><span class="hljs-params">(napi_env env, 19681cb0ef41Sopenharmony_ci napi_value code, 19691cb0ef41Sopenharmony_ci napi_value msg, 19701cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 19711cb0ef41Sopenharmony_ci<ul> 19721cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 19731cb0ef41Sopenharmony_ci<li><code>[in] code</code>: Optional <code>napi_value</code> with the string for the error code to be 19741cb0ef41Sopenharmony_ciassociated with the error.</li> 19751cb0ef41Sopenharmony_ci<li><code>[in] msg</code>: <code>napi_value</code> that references a JavaScript <code>string</code> to be used as 19761cb0ef41Sopenharmony_cithe message for the <code>Error</code>.</li> 19771cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the error created.</li> 19781cb0ef41Sopenharmony_ci</ul> 19791cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 19801cb0ef41Sopenharmony_ci<p>This API returns a JavaScript <code>SyntaxError</code> with the text provided.</p> 19811cb0ef41Sopenharmony_ci<h5><code>napi_get_and_clear_last_exception</code><span><a class="mark" href="#napi_get_and_clear_last_exception" id="napi_get_and_clear_last_exception">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_and_clear_last_exception"></a></h5> 19821cb0ef41Sopenharmony_ci<div class="api_metadata"> 19831cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 19841cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 19851cb0ef41Sopenharmony_ci</div> 19861cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_and_clear_last_exception</span><span class="hljs-params">(napi_env env, 19871cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 19881cb0ef41Sopenharmony_ci<ul> 19891cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 19901cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The exception if one is pending, <code>NULL</code> otherwise.</li> 19911cb0ef41Sopenharmony_ci</ul> 19921cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 19931cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 19941cb0ef41Sopenharmony_ci<h5><code>napi_is_exception_pending</code><span><a class="mark" href="#napi_is_exception_pending" id="napi_is_exception_pending">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_exception_pending"></a></h5> 19951cb0ef41Sopenharmony_ci<div class="api_metadata"> 19961cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 19971cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 19981cb0ef41Sopenharmony_ci</div> 19991cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_exception_pending</span><span class="hljs-params">(napi_env env, <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 20001cb0ef41Sopenharmony_ci<ul> 20011cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 20021cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Boolean value that is set to true if an exception is pending.</li> 20031cb0ef41Sopenharmony_ci</ul> 20041cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 20051cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 20061cb0ef41Sopenharmony_ci<h5><code>napi_fatal_exception</code><span><a class="mark" href="#napi_fatal_exception" id="napi_fatal_exception">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_fatal_exception"></a></h5> 20071cb0ef41Sopenharmony_ci<div class="api_metadata"> 20081cb0ef41Sopenharmony_ci<span>Added in: v9.10.0</span> 20091cb0ef41Sopenharmony_ci<span>N-API version: 3</span> 20101cb0ef41Sopenharmony_ci</div> 20111cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_fatal_exception</span><span class="hljs-params">(napi_env env, napi_value err)</span>;</code> <button class="copy-button">copy</button></pre> 20121cb0ef41Sopenharmony_ci<ul> 20131cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 20141cb0ef41Sopenharmony_ci<li><code>[in] err</code>: The error that is passed to <code>'uncaughtException'</code>.</li> 20151cb0ef41Sopenharmony_ci</ul> 20161cb0ef41Sopenharmony_ci<p>Trigger an <code>'uncaughtException'</code> in JavaScript. Useful if an async 20171cb0ef41Sopenharmony_cicallback throws an exception with no way to recover.</p> 20181cb0ef41Sopenharmony_ci<h4>Fatal errors<span><a class="mark" href="#fatal-errors" id="fatal-errors">#</a></span><a aria-hidden="true" class="legacy" id="n_api_fatal_errors"></a></h4> 20191cb0ef41Sopenharmony_ci<p>In the event of an unrecoverable error in a native addon, a fatal error can be 20201cb0ef41Sopenharmony_cithrown to immediately terminate the process.</p> 20211cb0ef41Sopenharmony_ci<h5><code>napi_fatal_error</code><span><a class="mark" href="#napi_fatal_error" id="napi_fatal_error">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_fatal_error"></a></h5> 20221cb0ef41Sopenharmony_ci<div class="api_metadata"> 20231cb0ef41Sopenharmony_ci<span>Added in: v8.2.0</span> 20241cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 20251cb0ef41Sopenharmony_ci</div> 20261cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_NO_RETURN <span class="hljs-type">void</span> <span class="hljs-title function_">napi_fatal_error</span><span class="hljs-params">(<span class="hljs-type">const</span> <span class="hljs-type">char</span>* location, 20271cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> location_len, 20281cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* message, 20291cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> message_len)</span>;</code> <button class="copy-button">copy</button></pre> 20301cb0ef41Sopenharmony_ci<ul> 20311cb0ef41Sopenharmony_ci<li><code>[in] location</code>: Optional location at which the error occurred.</li> 20321cb0ef41Sopenharmony_ci<li><code>[in] location_len</code>: The length of the location in bytes, or 20331cb0ef41Sopenharmony_ci<code>NAPI_AUTO_LENGTH</code> if it is null-terminated.</li> 20341cb0ef41Sopenharmony_ci<li><code>[in] message</code>: The message associated with the error.</li> 20351cb0ef41Sopenharmony_ci<li><code>[in] message_len</code>: The length of the message in bytes, or <code>NAPI_AUTO_LENGTH</code> 20361cb0ef41Sopenharmony_ciif it is null-terminated.</li> 20371cb0ef41Sopenharmony_ci</ul> 20381cb0ef41Sopenharmony_ci<p>The function call does not return, the process will be terminated.</p> 20391cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 20401cb0ef41Sopenharmony_ci</section><section><h3>Object lifetime management<span><a class="mark" href="#object-lifetime-management" id="object-lifetime-management">#</a></span><a aria-hidden="true" class="legacy" id="n_api_object_lifetime_management"></a></h3> 20411cb0ef41Sopenharmony_ci<p>As Node-API calls are made, handles to objects in the heap for the underlying 20421cb0ef41Sopenharmony_ciVM may be returned as <code>napi_values</code>. These handles must hold the 20431cb0ef41Sopenharmony_ciobjects 'live' until they are no longer required by the native code, 20441cb0ef41Sopenharmony_ciotherwise the objects could be collected before the native code was 20451cb0ef41Sopenharmony_cifinished using them.</p> 20461cb0ef41Sopenharmony_ci<p>As object handles are returned they are associated with a 20471cb0ef41Sopenharmony_ci'scope'. The lifespan for the default scope is tied to the lifespan 20481cb0ef41Sopenharmony_ciof the native method call. The result is that, by default, handles 20491cb0ef41Sopenharmony_ciremain valid and the objects associated with these handles will be 20501cb0ef41Sopenharmony_ciheld live for the lifespan of the native method call.</p> 20511cb0ef41Sopenharmony_ci<p>In many cases, however, it is necessary that the handles remain valid for 20521cb0ef41Sopenharmony_cieither a shorter or longer lifespan than that of the native method. 20531cb0ef41Sopenharmony_ciThe sections which follow describe the Node-API functions that can be used 20541cb0ef41Sopenharmony_cito change the handle lifespan from the default.</p> 20551cb0ef41Sopenharmony_ci<h4>Making handle lifespan shorter than that of the native method<span><a class="mark" href="#making-handle-lifespan-shorter-than-that-of-the-native-method" id="making-handle-lifespan-shorter-than-that-of-the-native-method">#</a></span><a aria-hidden="true" class="legacy" id="n_api_making_handle_lifespan_shorter_than_that_of_the_native_method"></a></h4> 20561cb0ef41Sopenharmony_ci<p>It is often necessary to make the lifespan of handles shorter than 20571cb0ef41Sopenharmony_cithe lifespan of a native method. For example, consider a native method 20581cb0ef41Sopenharmony_cithat has a loop which iterates through the elements in a large array:</p> 20591cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">for</span> (<span class="hljs-type">int</span> i = <span class="hljs-number">0</span>; i < <span class="hljs-number">1000000</span>; i++) { 20601cb0ef41Sopenharmony_ci napi_value result; 20611cb0ef41Sopenharmony_ci napi_status status = napi_get_element(env, object, i, &result); 20621cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) { 20631cb0ef41Sopenharmony_ci <span class="hljs-keyword">break</span>; 20641cb0ef41Sopenharmony_ci } 20651cb0ef41Sopenharmony_ci <span class="hljs-comment">// do something with element</span> 20661cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 20671cb0ef41Sopenharmony_ci<p>This would result in a large number of handles being created, consuming 20681cb0ef41Sopenharmony_cisubstantial resources. In addition, even though the native code could only 20691cb0ef41Sopenharmony_ciuse the most recent handle, all of the associated objects would also be 20701cb0ef41Sopenharmony_cikept alive since they all share the same scope.</p> 20711cb0ef41Sopenharmony_ci<p>To handle this case, Node-API provides the ability to establish a new 'scope' to 20721cb0ef41Sopenharmony_ciwhich newly created handles will be associated. Once those handles 20731cb0ef41Sopenharmony_ciare no longer required, the scope can be 'closed' and any handles associated 20741cb0ef41Sopenharmony_ciwith the scope are invalidated. The methods available to open/close scopes are 20751cb0ef41Sopenharmony_ci<a href="#napi_open_handle_scope"><code>napi_open_handle_scope</code></a> and <a href="#napi_close_handle_scope"><code>napi_close_handle_scope</code></a>.</p> 20761cb0ef41Sopenharmony_ci<p>Node-API only supports a single nested hierarchy of scopes. There is only one 20771cb0ef41Sopenharmony_ciactive scope at any time, and all new handles will be associated with that 20781cb0ef41Sopenharmony_ciscope while it is active. Scopes must be closed in the reverse order from 20791cb0ef41Sopenharmony_ciwhich they are opened. In addition, all scopes created within a native method 20801cb0ef41Sopenharmony_cimust be closed before returning from that method.</p> 20811cb0ef41Sopenharmony_ci<p>Taking the earlier example, adding calls to <a href="#napi_open_handle_scope"><code>napi_open_handle_scope</code></a> and 20821cb0ef41Sopenharmony_ci<a href="#napi_close_handle_scope"><code>napi_close_handle_scope</code></a> would ensure that at most a single handle 20831cb0ef41Sopenharmony_ciis valid throughout the execution of the loop:</p> 20841cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">for</span> (<span class="hljs-type">int</span> i = <span class="hljs-number">0</span>; i < <span class="hljs-number">1000000</span>; i++) { 20851cb0ef41Sopenharmony_ci napi_handle_scope scope; 20861cb0ef41Sopenharmony_ci napi_status status = napi_open_handle_scope(env, &scope); 20871cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) { 20881cb0ef41Sopenharmony_ci <span class="hljs-keyword">break</span>; 20891cb0ef41Sopenharmony_ci } 20901cb0ef41Sopenharmony_ci napi_value result; 20911cb0ef41Sopenharmony_ci status = napi_get_element(env, object, i, &result); 20921cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) { 20931cb0ef41Sopenharmony_ci <span class="hljs-keyword">break</span>; 20941cb0ef41Sopenharmony_ci } 20951cb0ef41Sopenharmony_ci <span class="hljs-comment">// do something with element</span> 20961cb0ef41Sopenharmony_ci status = napi_close_handle_scope(env, scope); 20971cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) { 20981cb0ef41Sopenharmony_ci <span class="hljs-keyword">break</span>; 20991cb0ef41Sopenharmony_ci } 21001cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 21011cb0ef41Sopenharmony_ci<p>When nesting scopes, there are cases where a handle from an 21021cb0ef41Sopenharmony_ciinner scope needs to live beyond the lifespan of that scope. Node-API supports 21031cb0ef41Sopenharmony_cian 'escapable scope' in order to support this case. An escapable scope 21041cb0ef41Sopenharmony_ciallows one handle to be 'promoted' so that it 'escapes' the 21051cb0ef41Sopenharmony_cicurrent scope and the lifespan of the handle changes from the current 21061cb0ef41Sopenharmony_ciscope to that of the outer scope.</p> 21071cb0ef41Sopenharmony_ci<p>The methods available to open/close escapable scopes are 21081cb0ef41Sopenharmony_ci<a href="#napi_open_escapable_handle_scope"><code>napi_open_escapable_handle_scope</code></a> and 21091cb0ef41Sopenharmony_ci<a href="#napi_close_escapable_handle_scope"><code>napi_close_escapable_handle_scope</code></a>.</p> 21101cb0ef41Sopenharmony_ci<p>The request to promote a handle is made through <a href="#napi_escape_handle"><code>napi_escape_handle</code></a> which 21111cb0ef41Sopenharmony_cican only be called once.</p> 21121cb0ef41Sopenharmony_ci<h5><code>napi_open_handle_scope</code><span><a class="mark" href="#napi_open_handle_scope" id="napi_open_handle_scope">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_open_handle_scope"></a></h5> 21131cb0ef41Sopenharmony_ci<div class="api_metadata"> 21141cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 21151cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 21161cb0ef41Sopenharmony_ci</div> 21171cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_open_handle_scope</span><span class="hljs-params">(napi_env env, 21181cb0ef41Sopenharmony_ci napi_handle_scope* result)</span>;</code> <button class="copy-button">copy</button></pre> 21191cb0ef41Sopenharmony_ci<ul> 21201cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 21211cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the new scope.</li> 21221cb0ef41Sopenharmony_ci</ul> 21231cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 21241cb0ef41Sopenharmony_ci<p>This API opens a new scope.</p> 21251cb0ef41Sopenharmony_ci<h5><code>napi_close_handle_scope</code><span><a class="mark" href="#napi_close_handle_scope" id="napi_close_handle_scope">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_close_handle_scope"></a></h5> 21261cb0ef41Sopenharmony_ci<div class="api_metadata"> 21271cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 21281cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 21291cb0ef41Sopenharmony_ci</div> 21301cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_close_handle_scope</span><span class="hljs-params">(napi_env env, 21311cb0ef41Sopenharmony_ci napi_handle_scope scope)</span>;</code> <button class="copy-button">copy</button></pre> 21321cb0ef41Sopenharmony_ci<ul> 21331cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 21341cb0ef41Sopenharmony_ci<li><code>[in] scope</code>: <code>napi_value</code> representing the scope to be closed.</li> 21351cb0ef41Sopenharmony_ci</ul> 21361cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 21371cb0ef41Sopenharmony_ci<p>This API closes the scope passed in. Scopes must be closed in the 21381cb0ef41Sopenharmony_cireverse order from which they were created.</p> 21391cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 21401cb0ef41Sopenharmony_ci<h5><code>napi_open_escapable_handle_scope</code><span><a class="mark" href="#napi_open_escapable_handle_scope" id="napi_open_escapable_handle_scope">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_open_escapable_handle_scope"></a></h5> 21411cb0ef41Sopenharmony_ci<div class="api_metadata"> 21421cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 21431cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 21441cb0ef41Sopenharmony_ci</div> 21451cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 21461cb0ef41Sopenharmony_ci <span class="hljs-title function_">napi_open_escapable_handle_scope</span><span class="hljs-params">(napi_env env, 21471cb0ef41Sopenharmony_ci napi_handle_scope* result)</span>;</code> <button class="copy-button">copy</button></pre> 21481cb0ef41Sopenharmony_ci<ul> 21491cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 21501cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the new scope.</li> 21511cb0ef41Sopenharmony_ci</ul> 21521cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 21531cb0ef41Sopenharmony_ci<p>This API opens a new scope from which one object can be promoted 21541cb0ef41Sopenharmony_cito the outer scope.</p> 21551cb0ef41Sopenharmony_ci<h5><code>napi_close_escapable_handle_scope</code><span><a class="mark" href="#napi_close_escapable_handle_scope" id="napi_close_escapable_handle_scope">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_close_escapable_handle_scope"></a></h5> 21561cb0ef41Sopenharmony_ci<div class="api_metadata"> 21571cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 21581cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 21591cb0ef41Sopenharmony_ci</div> 21601cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 21611cb0ef41Sopenharmony_ci <span class="hljs-title function_">napi_close_escapable_handle_scope</span><span class="hljs-params">(napi_env env, 21621cb0ef41Sopenharmony_ci napi_handle_scope scope)</span>;</code> <button class="copy-button">copy</button></pre> 21631cb0ef41Sopenharmony_ci<ul> 21641cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 21651cb0ef41Sopenharmony_ci<li><code>[in] scope</code>: <code>napi_value</code> representing the scope to be closed.</li> 21661cb0ef41Sopenharmony_ci</ul> 21671cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 21681cb0ef41Sopenharmony_ci<p>This API closes the scope passed in. Scopes must be closed in the 21691cb0ef41Sopenharmony_cireverse order from which they were created.</p> 21701cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 21711cb0ef41Sopenharmony_ci<h5><code>napi_escape_handle</code><span><a class="mark" href="#napi_escape_handle" id="napi_escape_handle">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_escape_handle"></a></h5> 21721cb0ef41Sopenharmony_ci<div class="api_metadata"> 21731cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 21741cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 21751cb0ef41Sopenharmony_ci</div> 21761cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_escape_handle</span><span class="hljs-params">(napi_env env, 21771cb0ef41Sopenharmony_ci napi_escapable_handle_scope scope, 21781cb0ef41Sopenharmony_ci napi_value escapee, 21791cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 21801cb0ef41Sopenharmony_ci<ul> 21811cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 21821cb0ef41Sopenharmony_ci<li><code>[in] scope</code>: <code>napi_value</code> representing the current scope.</li> 21831cb0ef41Sopenharmony_ci<li><code>[in] escapee</code>: <code>napi_value</code> representing the JavaScript <code>Object</code> to be 21841cb0ef41Sopenharmony_ciescaped.</li> 21851cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the handle to the escaped <code>Object</code> 21861cb0ef41Sopenharmony_ciin the outer scope.</li> 21871cb0ef41Sopenharmony_ci</ul> 21881cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 21891cb0ef41Sopenharmony_ci<p>This API promotes the handle to the JavaScript object so that it is valid 21901cb0ef41Sopenharmony_cifor the lifetime of the outer scope. It can only be called once per scope. 21911cb0ef41Sopenharmony_ciIf it is called more than once an error will be returned.</p> 21921cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 21931cb0ef41Sopenharmony_ci<h4>References to values with a lifespan longer than that of the native method<span><a class="mark" href="#references-to-values-with-a-lifespan-longer-than-that-of-the-native-method" id="references-to-values-with-a-lifespan-longer-than-that-of-the-native-method">#</a></span><a aria-hidden="true" class="legacy" id="n_api_references_to_values_with_a_lifespan_longer_than_that_of_the_native_method"></a></h4> 21941cb0ef41Sopenharmony_ci<p>In some cases, an addon will need to be able to create and reference values 21951cb0ef41Sopenharmony_ciwith a lifespan longer than that of a single native method invocation. For 21961cb0ef41Sopenharmony_ciexample, to create a constructor and later use that constructor 21971cb0ef41Sopenharmony_ciin a request to create instances, it must be possible to reference 21981cb0ef41Sopenharmony_cithe constructor object across many different instance creation requests. This 21991cb0ef41Sopenharmony_ciwould not be possible with a normal handle returned as a <code>napi_value</code> as 22001cb0ef41Sopenharmony_cidescribed in the earlier section. The lifespan of a normal handle is 22011cb0ef41Sopenharmony_cimanaged by scopes and all scopes must be closed before the end of a native 22021cb0ef41Sopenharmony_cimethod.</p> 22031cb0ef41Sopenharmony_ci<p>Node-API provides methods for creating persistent references to values. 22041cb0ef41Sopenharmony_ciCurrently Node-API only allows references to be created for a 22051cb0ef41Sopenharmony_cilimited set of value types, including object, external, function, and symbol.</p> 22061cb0ef41Sopenharmony_ci<p>Each reference has an associated count with a value of 0 or higher, 22071cb0ef41Sopenharmony_ciwhich determines whether the reference will keep the corresponding value alive. 22081cb0ef41Sopenharmony_ciReferences with a count of 0 do not prevent values from being collected. 22091cb0ef41Sopenharmony_ciValues of object (object, function, external) and symbol types are becoming 22101cb0ef41Sopenharmony_ci'weak' references and can still be accessed while they are not collected. 22111cb0ef41Sopenharmony_ciAny count greater than 0 will prevent the values from being collected.</p> 22121cb0ef41Sopenharmony_ci<p>Symbol values have different flavors. The true weak reference behavior is 22131cb0ef41Sopenharmony_cionly supported by local symbols created with the <code>napi_create_symbol</code> function 22141cb0ef41Sopenharmony_cior the JavaScript <code>Symbol()</code> constructor calls. Globally registered symbols 22151cb0ef41Sopenharmony_cicreated with the <code>node_api_symbol_for</code> function or JavaScript <code>Symbol.for()</code> 22161cb0ef41Sopenharmony_cifunction calls remain always strong references because the garbage collector 22171cb0ef41Sopenharmony_cidoes not collect them. The same is true for well-known symbols such as 22181cb0ef41Sopenharmony_ci<code>Symbol.iterator</code>. They are also never collected by the garbage collector.</p> 22191cb0ef41Sopenharmony_ci<p>References can be created with an initial reference count. The count can 22201cb0ef41Sopenharmony_cithen be modified through <a href="#napi_reference_ref"><code>napi_reference_ref</code></a> and 22211cb0ef41Sopenharmony_ci<a href="#napi_reference_unref"><code>napi_reference_unref</code></a>. If an object is collected while the count 22221cb0ef41Sopenharmony_cifor a reference is 0, all subsequent calls to 22231cb0ef41Sopenharmony_ciget the object associated with the reference <a href="#napi_get_reference_value"><code>napi_get_reference_value</code></a> 22241cb0ef41Sopenharmony_ciwill return <code>NULL</code> for the returned <code>napi_value</code>. An attempt to call 22251cb0ef41Sopenharmony_ci<a href="#napi_reference_ref"><code>napi_reference_ref</code></a> for a reference whose object has been collected 22261cb0ef41Sopenharmony_ciresults in an error.</p> 22271cb0ef41Sopenharmony_ci<p>References must be deleted once they are no longer required by the addon. When 22281cb0ef41Sopenharmony_cia reference is deleted, it will no longer prevent the corresponding object from 22291cb0ef41Sopenharmony_cibeing collected. Failure to delete a persistent reference results in 22301cb0ef41Sopenharmony_cia 'memory leak' with both the native memory for the persistent reference and 22311cb0ef41Sopenharmony_cithe corresponding object on the heap being retained forever.</p> 22321cb0ef41Sopenharmony_ci<p>There can be multiple persistent references created which refer to the same 22331cb0ef41Sopenharmony_ciobject, each of which will either keep the object live or not based on its 22341cb0ef41Sopenharmony_ciindividual count. Multiple persistent references to the same object 22351cb0ef41Sopenharmony_cican result in unexpectedly keeping alive native memory. The native structures 22361cb0ef41Sopenharmony_cifor a persistent reference must be kept alive until finalizers for the 22371cb0ef41Sopenharmony_cireferenced object are executed. If a new persistent reference is created 22381cb0ef41Sopenharmony_cifor the same object, the finalizers for that object will not be 22391cb0ef41Sopenharmony_cirun and the native memory pointed by the earlier persistent reference 22401cb0ef41Sopenharmony_ciwill not be freed. This can be avoided by calling 22411cb0ef41Sopenharmony_ci<code>napi_delete_reference</code> in addition to <code>napi_reference_unref</code> when possible.</p> 22421cb0ef41Sopenharmony_ci<p><strong>Change History:</strong></p> 22431cb0ef41Sopenharmony_ci<ul> 22441cb0ef41Sopenharmony_ci<li> 22451cb0ef41Sopenharmony_ci<p>Experimental (<code>NAPI_EXPERIMENTAL</code> is defined):</p> 22461cb0ef41Sopenharmony_ci<p>References can be created for all value types. The new supported value 22471cb0ef41Sopenharmony_citypes do not support weak reference semantic and the values of these types 22481cb0ef41Sopenharmony_ciare released when the reference count becomes 0 and cannot be accessed from 22491cb0ef41Sopenharmony_cithe reference anymore.</p> 22501cb0ef41Sopenharmony_ci</li> 22511cb0ef41Sopenharmony_ci</ul> 22521cb0ef41Sopenharmony_ci<h5><code>napi_create_reference</code><span><a class="mark" href="#napi_create_reference" id="napi_create_reference">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_reference"></a></h5> 22531cb0ef41Sopenharmony_ci<div class="api_metadata"> 22541cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 22551cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 22561cb0ef41Sopenharmony_ci</div> 22571cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_create_reference</span><span class="hljs-params">(napi_env env, 22581cb0ef41Sopenharmony_ci napi_value value, 22591cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> initial_refcount, 22601cb0ef41Sopenharmony_ci napi_ref* result)</span>;</code> <button class="copy-button">copy</button></pre> 22611cb0ef41Sopenharmony_ci<ul> 22621cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 22631cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The <code>napi_value</code> for which a reference is being created.</li> 22641cb0ef41Sopenharmony_ci<li><code>[in] initial_refcount</code>: Initial reference count for the new reference.</li> 22651cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_ref</code> pointing to the new reference.</li> 22661cb0ef41Sopenharmony_ci</ul> 22671cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 22681cb0ef41Sopenharmony_ci<p>This API creates a new reference with the specified reference count 22691cb0ef41Sopenharmony_cito the value passed in.</p> 22701cb0ef41Sopenharmony_ci<h5><code>napi_delete_reference</code><span><a class="mark" href="#napi_delete_reference" id="napi_delete_reference">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_delete_reference"></a></h5> 22711cb0ef41Sopenharmony_ci<div class="api_metadata"> 22721cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 22731cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 22741cb0ef41Sopenharmony_ci</div> 22751cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_delete_reference</span><span class="hljs-params">(napi_env env, napi_ref ref)</span>;</code> <button class="copy-button">copy</button></pre> 22761cb0ef41Sopenharmony_ci<ul> 22771cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 22781cb0ef41Sopenharmony_ci<li><code>[in] ref</code>: <code>napi_ref</code> to be deleted.</li> 22791cb0ef41Sopenharmony_ci</ul> 22801cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 22811cb0ef41Sopenharmony_ci<p>This API deletes the reference passed in.</p> 22821cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 22831cb0ef41Sopenharmony_ci<h5><code>napi_reference_ref</code><span><a class="mark" href="#napi_reference_ref" id="napi_reference_ref">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_reference_ref"></a></h5> 22841cb0ef41Sopenharmony_ci<div class="api_metadata"> 22851cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 22861cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 22871cb0ef41Sopenharmony_ci</div> 22881cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_reference_ref</span><span class="hljs-params">(napi_env env, 22891cb0ef41Sopenharmony_ci napi_ref ref, 22901cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 22911cb0ef41Sopenharmony_ci<ul> 22921cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 22931cb0ef41Sopenharmony_ci<li><code>[in] ref</code>: <code>napi_ref</code> for which the reference count will be incremented.</li> 22941cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The new reference count.</li> 22951cb0ef41Sopenharmony_ci</ul> 22961cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 22971cb0ef41Sopenharmony_ci<p>This API increments the reference count for the reference 22981cb0ef41Sopenharmony_cipassed in and returns the resulting reference count.</p> 22991cb0ef41Sopenharmony_ci<h5><code>napi_reference_unref</code><span><a class="mark" href="#napi_reference_unref" id="napi_reference_unref">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_reference_unref"></a></h5> 23001cb0ef41Sopenharmony_ci<div class="api_metadata"> 23011cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 23021cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 23031cb0ef41Sopenharmony_ci</div> 23041cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_reference_unref</span><span class="hljs-params">(napi_env env, 23051cb0ef41Sopenharmony_ci napi_ref ref, 23061cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 23071cb0ef41Sopenharmony_ci<ul> 23081cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 23091cb0ef41Sopenharmony_ci<li><code>[in] ref</code>: <code>napi_ref</code> for which the reference count will be decremented.</li> 23101cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The new reference count.</li> 23111cb0ef41Sopenharmony_ci</ul> 23121cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 23131cb0ef41Sopenharmony_ci<p>This API decrements the reference count for the reference 23141cb0ef41Sopenharmony_cipassed in and returns the resulting reference count.</p> 23151cb0ef41Sopenharmony_ci<h5><code>napi_get_reference_value</code><span><a class="mark" href="#napi_get_reference_value" id="napi_get_reference_value">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_reference_value"></a></h5> 23161cb0ef41Sopenharmony_ci<div class="api_metadata"> 23171cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 23181cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 23191cb0ef41Sopenharmony_ci</div> 23201cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_get_reference_value</span><span class="hljs-params">(napi_env env, 23211cb0ef41Sopenharmony_ci napi_ref ref, 23221cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 23231cb0ef41Sopenharmony_ci<ul> 23241cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 23251cb0ef41Sopenharmony_ci<li><code>[in] ref</code>: The <code>napi_ref</code> for which the corresponding value is 23261cb0ef41Sopenharmony_cibeing requested.</li> 23271cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The <code>napi_value</code> referenced by the <code>napi_ref</code>.</li> 23281cb0ef41Sopenharmony_ci</ul> 23291cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 23301cb0ef41Sopenharmony_ci<p>If still valid, this API returns the <code>napi_value</code> representing the 23311cb0ef41Sopenharmony_ciJavaScript value associated with the <code>napi_ref</code>. Otherwise, result 23321cb0ef41Sopenharmony_ciwill be <code>NULL</code>.</p> 23331cb0ef41Sopenharmony_ci<h4>Cleanup on exit of the current Node.js environment<span><a class="mark" href="#cleanup-on-exit-of-the-current-nodejs-environment" id="cleanup-on-exit-of-the-current-nodejs-environment">#</a></span><a aria-hidden="true" class="legacy" id="n_api_cleanup_on_exit_of_the_current_node_js_environment"></a></h4> 23341cb0ef41Sopenharmony_ci<p>While a Node.js process typically releases all its resources when exiting, 23351cb0ef41Sopenharmony_ciembedders of Node.js, or future Worker support, may require addons to register 23361cb0ef41Sopenharmony_ciclean-up hooks that will be run once the current Node.js environment exits.</p> 23371cb0ef41Sopenharmony_ci<p>Node-API provides functions for registering and un-registering such callbacks. 23381cb0ef41Sopenharmony_ciWhen those callbacks are run, all resources that are being held by the addon 23391cb0ef41Sopenharmony_cishould be freed up.</p> 23401cb0ef41Sopenharmony_ci<h5><code>napi_add_env_cleanup_hook</code><span><a class="mark" href="#napi_add_env_cleanup_hook" id="napi_add_env_cleanup_hook">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_add_env_cleanup_hook"></a></h5> 23411cb0ef41Sopenharmony_ci<div class="api_metadata"> 23421cb0ef41Sopenharmony_ci<span>Added in: v10.2.0</span> 23431cb0ef41Sopenharmony_ci<span>N-API version: 3</span> 23441cb0ef41Sopenharmony_ci</div> 23451cb0ef41Sopenharmony_ci<pre><code class="language-c">NODE_EXTERN napi_status <span class="hljs-title function_">napi_add_env_cleanup_hook</span><span class="hljs-params">(node_api_nogc_env env, 23461cb0ef41Sopenharmony_ci napi_cleanup_hook fun, 23471cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* arg)</span>;</code> <button class="copy-button">copy</button></pre> 23481cb0ef41Sopenharmony_ci<p>Registers <code>fun</code> as a function to be run with the <code>arg</code> parameter once the 23491cb0ef41Sopenharmony_cicurrent Node.js environment exits.</p> 23501cb0ef41Sopenharmony_ci<p>A function can safely be specified multiple times with different 23511cb0ef41Sopenharmony_ci<code>arg</code> values. In that case, it will be called multiple times as well. 23521cb0ef41Sopenharmony_ciProviding the same <code>fun</code> and <code>arg</code> values multiple times is not allowed 23531cb0ef41Sopenharmony_ciand will lead the process to abort.</p> 23541cb0ef41Sopenharmony_ci<p>The hooks will be called in reverse order, i.e. the most recently added one 23551cb0ef41Sopenharmony_ciwill be called first.</p> 23561cb0ef41Sopenharmony_ci<p>Removing this hook can be done by using <a href="#napi_remove_env_cleanup_hook"><code>napi_remove_env_cleanup_hook</code></a>. 23571cb0ef41Sopenharmony_ciTypically, that happens when the resource for which this hook was added 23581cb0ef41Sopenharmony_ciis being torn down anyway.</p> 23591cb0ef41Sopenharmony_ci<p>For asynchronous cleanup, <a href="#napi_add_async_cleanup_hook"><code>napi_add_async_cleanup_hook</code></a> is available.</p> 23601cb0ef41Sopenharmony_ci<h5><code>napi_remove_env_cleanup_hook</code><span><a class="mark" href="#napi_remove_env_cleanup_hook" id="napi_remove_env_cleanup_hook">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_remove_env_cleanup_hook"></a></h5> 23611cb0ef41Sopenharmony_ci<div class="api_metadata"> 23621cb0ef41Sopenharmony_ci<span>Added in: v10.2.0</span> 23631cb0ef41Sopenharmony_ci<span>N-API version: 3</span> 23641cb0ef41Sopenharmony_ci</div> 23651cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_remove_env_cleanup_hook</span><span class="hljs-params">(node_api_nogc_env env, 23661cb0ef41Sopenharmony_ci <span class="hljs-type">void</span> (*fun)(<span class="hljs-type">void</span>* arg), 23671cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* arg)</span>;</code> <button class="copy-button">copy</button></pre> 23681cb0ef41Sopenharmony_ci<p>Unregisters <code>fun</code> as a function to be run with the <code>arg</code> parameter once the 23691cb0ef41Sopenharmony_cicurrent Node.js environment exits. Both the argument and the function value 23701cb0ef41Sopenharmony_cineed to be exact matches.</p> 23711cb0ef41Sopenharmony_ci<p>The function must have originally been registered 23721cb0ef41Sopenharmony_ciwith <code>napi_add_env_cleanup_hook</code>, otherwise the process will abort.</p> 23731cb0ef41Sopenharmony_ci<h5><code>napi_add_async_cleanup_hook</code><span><a class="mark" href="#napi_add_async_cleanup_hook" id="napi_add_async_cleanup_hook">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_add_async_cleanup_hook"></a></h5> 23741cb0ef41Sopenharmony_ci<div class="api_metadata"> 23751cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 23761cb0ef41Sopenharmony_ci<table> 23771cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 23781cb0ef41Sopenharmony_ci<tr><td>v14.10.0, v12.19.0</td> 23791cb0ef41Sopenharmony_ci<td><p>Changed signature of the <code>hook</code> callback.</p></td></tr> 23801cb0ef41Sopenharmony_ci<tr><td>v14.8.0, v12.19.0</td> 23811cb0ef41Sopenharmony_ci<td><p><span>Added in: v14.8.0, v12.19.0</span></p></td></tr> 23821cb0ef41Sopenharmony_ci</tbody></table> 23831cb0ef41Sopenharmony_ci</details> 23841cb0ef41Sopenharmony_ci<span>N-API version: 8</span> 23851cb0ef41Sopenharmony_ci</div> 23861cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_add_async_cleanup_hook</span><span class="hljs-params">( 23871cb0ef41Sopenharmony_ci node_api_nogc_env env, 23881cb0ef41Sopenharmony_ci napi_async_cleanup_hook hook, 23891cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* arg, 23901cb0ef41Sopenharmony_ci napi_async_cleanup_hook_handle* remove_handle)</span>;</code> <button class="copy-button">copy</button></pre> 23911cb0ef41Sopenharmony_ci<ul> 23921cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 23931cb0ef41Sopenharmony_ci<li><code>[in] hook</code>: The function pointer to call at environment teardown.</li> 23941cb0ef41Sopenharmony_ci<li><code>[in] arg</code>: The pointer to pass to <code>hook</code> when it gets called.</li> 23951cb0ef41Sopenharmony_ci<li><code>[out] remove_handle</code>: Optional handle that refers to the asynchronous cleanup 23961cb0ef41Sopenharmony_cihook.</li> 23971cb0ef41Sopenharmony_ci</ul> 23981cb0ef41Sopenharmony_ci<p>Registers <code>hook</code>, which is a function of type <a href="#napi_async_cleanup_hook"><code>napi_async_cleanup_hook</code></a>, as 23991cb0ef41Sopenharmony_cia function to be run with the <code>remove_handle</code> and <code>arg</code> parameters once the 24001cb0ef41Sopenharmony_cicurrent Node.js environment exits.</p> 24011cb0ef41Sopenharmony_ci<p>Unlike <a href="#napi_add_env_cleanup_hook"><code>napi_add_env_cleanup_hook</code></a>, the hook is allowed to be asynchronous.</p> 24021cb0ef41Sopenharmony_ci<p>Otherwise, behavior generally matches that of <a href="#napi_add_env_cleanup_hook"><code>napi_add_env_cleanup_hook</code></a>.</p> 24031cb0ef41Sopenharmony_ci<p>If <code>remove_handle</code> is not <code>NULL</code>, an opaque value will be stored in it 24041cb0ef41Sopenharmony_cithat must later be passed to <a href="#napi_remove_async_cleanup_hook"><code>napi_remove_async_cleanup_hook</code></a>, 24051cb0ef41Sopenharmony_ciregardless of whether the hook has already been invoked. 24061cb0ef41Sopenharmony_ciTypically, that happens when the resource for which this hook was added 24071cb0ef41Sopenharmony_ciis being torn down anyway.</p> 24081cb0ef41Sopenharmony_ci<h5><code>napi_remove_async_cleanup_hook</code><span><a class="mark" href="#napi_remove_async_cleanup_hook" id="napi_remove_async_cleanup_hook">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_remove_async_cleanup_hook"></a></h5> 24091cb0ef41Sopenharmony_ci<div class="api_metadata"> 24101cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 24111cb0ef41Sopenharmony_ci<table> 24121cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 24131cb0ef41Sopenharmony_ci<tr><td>v14.10.0, v12.19.0</td> 24141cb0ef41Sopenharmony_ci<td><p>Removed <code>env</code> parameter.</p></td></tr> 24151cb0ef41Sopenharmony_ci<tr><td>v14.8.0, v12.19.0</td> 24161cb0ef41Sopenharmony_ci<td><p><span>Added in: v14.8.0, v12.19.0</span></p></td></tr> 24171cb0ef41Sopenharmony_ci</tbody></table> 24181cb0ef41Sopenharmony_ci</details> 24191cb0ef41Sopenharmony_ci</div> 24201cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_remove_async_cleanup_hook</span><span class="hljs-params">( 24211cb0ef41Sopenharmony_ci napi_async_cleanup_hook_handle remove_handle)</span>;</code> <button class="copy-button">copy</button></pre> 24221cb0ef41Sopenharmony_ci<ul> 24231cb0ef41Sopenharmony_ci<li><code>[in] remove_handle</code>: The handle to an asynchronous cleanup hook that was 24241cb0ef41Sopenharmony_cicreated with <a href="#napi_add_async_cleanup_hook"><code>napi_add_async_cleanup_hook</code></a>.</li> 24251cb0ef41Sopenharmony_ci</ul> 24261cb0ef41Sopenharmony_ci<p>Unregisters the cleanup hook corresponding to <code>remove_handle</code>. This will prevent 24271cb0ef41Sopenharmony_cithe hook from being executed, unless it has already started executing. 24281cb0ef41Sopenharmony_ciThis must be called on any <code>napi_async_cleanup_hook_handle</code> value obtained 24291cb0ef41Sopenharmony_cifrom <a href="#napi_add_async_cleanup_hook"><code>napi_add_async_cleanup_hook</code></a>.</p> 24301cb0ef41Sopenharmony_ci<h4>Finalization on the exit of the Node.js environment<span><a class="mark" href="#finalization-on-the-exit-of-the-nodejs-environment" id="finalization-on-the-exit-of-the-nodejs-environment">#</a></span><a aria-hidden="true" class="legacy" id="n_api_finalization_on_the_exit_of_the_node_js_environment"></a></h4> 24311cb0ef41Sopenharmony_ci<p>The Node.js environment may be torn down at an arbitrary time as soon as 24321cb0ef41Sopenharmony_cipossible with JavaScript execution disallowed, like on the request of 24331cb0ef41Sopenharmony_ci<a href="worker_threads.html#workerterminate"><code>worker.terminate()</code></a>. When the environment is being torn down, the 24341cb0ef41Sopenharmony_ciregistered <code>napi_finalize</code> callbacks of JavaScript objects, thread-safe 24351cb0ef41Sopenharmony_cifunctions and environment instance data are invoked immediately and 24361cb0ef41Sopenharmony_ciindependently.</p> 24371cb0ef41Sopenharmony_ci<p>The invocation of <code>napi_finalize</code> callbacks is scheduled after the manually 24381cb0ef41Sopenharmony_ciregistered cleanup hooks. In order to ensure a proper order of addon 24391cb0ef41Sopenharmony_cifinalization during environment shutdown to avoid use-after-free in the 24401cb0ef41Sopenharmony_ci<code>napi_finalize</code> callback, addons should register a cleanup hook with 24411cb0ef41Sopenharmony_ci<code>napi_add_env_cleanup_hook</code> and <code>napi_add_async_cleanup_hook</code> to manually 24421cb0ef41Sopenharmony_cirelease the allocated resource in a proper order.</p> 24431cb0ef41Sopenharmony_ci</section><section><h3>Module registration<span><a class="mark" href="#module-registration" id="module-registration">#</a></span><a aria-hidden="true" class="legacy" id="n_api_module_registration"></a></h3> 24441cb0ef41Sopenharmony_ci<p>Node-API modules are registered in a manner similar to other modules 24451cb0ef41Sopenharmony_ciexcept that instead of using the <code>NODE_MODULE</code> macro the following 24461cb0ef41Sopenharmony_ciis used:</p> 24471cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)</code> <button class="copy-button">copy</button></pre> 24481cb0ef41Sopenharmony_ci<p>The next difference is the signature for the <code>Init</code> method. For a Node-API 24491cb0ef41Sopenharmony_cimodule it is as follows:</p> 24501cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_value <span class="hljs-title function_">Init</span><span class="hljs-params">(napi_env env, napi_value exports)</span>;</code> <button class="copy-button">copy</button></pre> 24511cb0ef41Sopenharmony_ci<p>The return value from <code>Init</code> is treated as the <code>exports</code> object for the module. 24521cb0ef41Sopenharmony_ciThe <code>Init</code> method is passed an empty object via the <code>exports</code> parameter as a 24531cb0ef41Sopenharmony_ciconvenience. If <code>Init</code> returns <code>NULL</code>, the parameter passed as <code>exports</code> is 24541cb0ef41Sopenharmony_ciexported by the module. Node-API modules cannot modify the <code>module</code> object but 24551cb0ef41Sopenharmony_cican specify anything as the <code>exports</code> property of the module.</p> 24561cb0ef41Sopenharmony_ci<p>To add the method <code>hello</code> as a function so that it can be called as a method 24571cb0ef41Sopenharmony_ciprovided by the addon:</p> 24581cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_value <span class="hljs-title function_">Init</span><span class="hljs-params">(napi_env env, napi_value exports)</span> { 24591cb0ef41Sopenharmony_ci napi_status status; 24601cb0ef41Sopenharmony_ci napi_property_descriptor desc = { 24611cb0ef41Sopenharmony_ci <span class="hljs-string">"hello"</span>, 24621cb0ef41Sopenharmony_ci <span class="hljs-literal">NULL</span>, 24631cb0ef41Sopenharmony_ci Method, 24641cb0ef41Sopenharmony_ci <span class="hljs-literal">NULL</span>, 24651cb0ef41Sopenharmony_ci <span class="hljs-literal">NULL</span>, 24661cb0ef41Sopenharmony_ci <span class="hljs-literal">NULL</span>, 24671cb0ef41Sopenharmony_ci napi_writable | napi_enumerable | napi_configurable, 24681cb0ef41Sopenharmony_ci <span class="hljs-literal">NULL</span> 24691cb0ef41Sopenharmony_ci }; 24701cb0ef41Sopenharmony_ci status = napi_define_properties(env, exports, <span class="hljs-number">1</span>, &desc); 24711cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 24721cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> exports; 24731cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 24741cb0ef41Sopenharmony_ci<p>To set a function to be returned by the <code>require()</code> for the addon:</p> 24751cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_value <span class="hljs-title function_">Init</span><span class="hljs-params">(napi_env env, napi_value exports)</span> { 24761cb0ef41Sopenharmony_ci napi_value method; 24771cb0ef41Sopenharmony_ci napi_status status; 24781cb0ef41Sopenharmony_ci status = napi_create_function(env, <span class="hljs-string">"exports"</span>, NAPI_AUTO_LENGTH, Method, <span class="hljs-literal">NULL</span>, &method); 24791cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 24801cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> method; 24811cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 24821cb0ef41Sopenharmony_ci<p>To define a class so that new instances can be created (often used with 24831cb0ef41Sopenharmony_ci<a href="#object-wrap">Object wrap</a>):</p> 24841cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-comment">// <span class="hljs-doctag">NOTE:</span> partial example, not all referenced code is included</span> 24851cb0ef41Sopenharmony_cinapi_value <span class="hljs-title function_">Init</span><span class="hljs-params">(napi_env env, napi_value exports)</span> { 24861cb0ef41Sopenharmony_ci napi_status status; 24871cb0ef41Sopenharmony_ci napi_property_descriptor properties[] = { 24881cb0ef41Sopenharmony_ci { <span class="hljs-string">"value"</span>, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>, GetValue, SetValue, <span class="hljs-literal">NULL</span>, napi_writable | napi_configurable, <span class="hljs-literal">NULL</span> }, 24891cb0ef41Sopenharmony_ci DECLARE_NAPI_METHOD(<span class="hljs-string">"plusOne"</span>, PlusOne), 24901cb0ef41Sopenharmony_ci DECLARE_NAPI_METHOD(<span class="hljs-string">"multiply"</span>, Multiply), 24911cb0ef41Sopenharmony_ci }; 24921cb0ef41Sopenharmony_ci 24931cb0ef41Sopenharmony_ci napi_value cons; 24941cb0ef41Sopenharmony_ci status = 24951cb0ef41Sopenharmony_ci napi_define_class(env, <span class="hljs-string">"MyObject"</span>, New, <span class="hljs-literal">NULL</span>, <span class="hljs-number">3</span>, properties, &cons); 24961cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 24971cb0ef41Sopenharmony_ci 24981cb0ef41Sopenharmony_ci status = napi_create_reference(env, cons, <span class="hljs-number">1</span>, &constructor); 24991cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 25001cb0ef41Sopenharmony_ci 25011cb0ef41Sopenharmony_ci status = napi_set_named_property(env, exports, <span class="hljs-string">"MyObject"</span>, cons); 25021cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 25031cb0ef41Sopenharmony_ci 25041cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> exports; 25051cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 25061cb0ef41Sopenharmony_ci<p>You can also use the <code>NAPI_MODULE_INIT</code> macro, which acts as a shorthand 25071cb0ef41Sopenharmony_cifor <code>NAPI_MODULE</code> and defining an <code>Init</code> function:</p> 25081cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_MODULE_INIT(<span class="hljs-comment">/* napi_env env, napi_value exports */</span>) { 25091cb0ef41Sopenharmony_ci napi_value answer; 25101cb0ef41Sopenharmony_ci napi_status result; 25111cb0ef41Sopenharmony_ci 25121cb0ef41Sopenharmony_ci status = napi_create_int64(env, <span class="hljs-number">42</span>, &answer); 25131cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 25141cb0ef41Sopenharmony_ci 25151cb0ef41Sopenharmony_ci status = napi_set_named_property(env, exports, <span class="hljs-string">"answer"</span>, answer); 25161cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 25171cb0ef41Sopenharmony_ci 25181cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> exports; 25191cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 25201cb0ef41Sopenharmony_ci<p>The parameters <code>env</code> and <code>exports</code> are provided to the body of the 25211cb0ef41Sopenharmony_ci<code>NAPI_MODULE_INIT</code> macro.</p> 25221cb0ef41Sopenharmony_ci<p>All Node-API addons are context-aware, meaning they may be loaded multiple 25231cb0ef41Sopenharmony_citimes. There are a few design considerations when declaring such a module. 25241cb0ef41Sopenharmony_ciThe documentation on <a href="addons.html#context-aware-addons">context-aware addons</a> provides more details.</p> 25251cb0ef41Sopenharmony_ci<p>The variables <code>env</code> and <code>exports</code> will be available inside the function body 25261cb0ef41Sopenharmony_cifollowing the macro invocation.</p> 25271cb0ef41Sopenharmony_ci<p>For more details on setting properties on objects, see the section on 25281cb0ef41Sopenharmony_ci<a href="#working-with-javascript-properties">Working with JavaScript properties</a>.</p> 25291cb0ef41Sopenharmony_ci<p>For more details on building addon modules in general, refer to the existing 25301cb0ef41Sopenharmony_ciAPI.</p> 25311cb0ef41Sopenharmony_ci</section><section><h3>Working with JavaScript values<span><a class="mark" href="#working-with-javascript-values" id="working-with-javascript-values">#</a></span><a aria-hidden="true" class="legacy" id="n_api_working_with_javascript_values"></a></h3> 25321cb0ef41Sopenharmony_ci<p>Node-API exposes a set of APIs to create all types of JavaScript values. 25331cb0ef41Sopenharmony_ciSome of these types are documented under <a href="https://tc39.github.io/ecma262/#sec-ecmascript-data-types-and-values">Section 6</a> 25341cb0ef41Sopenharmony_ciof the <a href="https://tc39.github.io/ecma262/">ECMAScript Language Specification</a>.</p> 25351cb0ef41Sopenharmony_ci<p>Fundamentally, these APIs are used to do one of the following:</p> 25361cb0ef41Sopenharmony_ci<ol> 25371cb0ef41Sopenharmony_ci<li>Create a new JavaScript object</li> 25381cb0ef41Sopenharmony_ci<li>Convert from a primitive C type to a Node-API value</li> 25391cb0ef41Sopenharmony_ci<li>Convert from Node-API value to a primitive C type</li> 25401cb0ef41Sopenharmony_ci<li>Get global instances including <code>undefined</code> and <code>null</code></li> 25411cb0ef41Sopenharmony_ci</ol> 25421cb0ef41Sopenharmony_ci<p>Node-API values are represented by the type <code>napi_value</code>. 25431cb0ef41Sopenharmony_ciAny Node-API call that requires a JavaScript value takes in a <code>napi_value</code>. 25441cb0ef41Sopenharmony_ciIn some cases, the API does check the type of the <code>napi_value</code> up-front. 25451cb0ef41Sopenharmony_ciHowever, for better performance, it's better for the caller to make sure that 25461cb0ef41Sopenharmony_cithe <code>napi_value</code> in question is of the JavaScript type expected by the API.</p> 25471cb0ef41Sopenharmony_ci<h4>Enum types<span><a class="mark" href="#enum-types" id="enum-types">#</a></span><a aria-hidden="true" class="legacy" id="n_api_enum_types"></a></h4> 25481cb0ef41Sopenharmony_ci<h5><code>napi_key_collection_mode</code><span><a class="mark" href="#napi_key_collection_mode" id="napi_key_collection_mode">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_key_collection_mode"></a></h5> 25491cb0ef41Sopenharmony_ci<div class="api_metadata"> 25501cb0ef41Sopenharmony_ci<span>Added in: v13.7.0, v12.17.0, v10.20.0</span> 25511cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 25521cb0ef41Sopenharmony_ci</div> 25531cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 25541cb0ef41Sopenharmony_ci napi_key_include_prototypes, 25551cb0ef41Sopenharmony_ci napi_key_own_only 25561cb0ef41Sopenharmony_ci} napi_key_collection_mode;</code> <button class="copy-button">copy</button></pre> 25571cb0ef41Sopenharmony_ci<p>Describes the <code>Keys/Properties</code> filter enums:</p> 25581cb0ef41Sopenharmony_ci<p><code>napi_key_collection_mode</code> limits the range of collected properties.</p> 25591cb0ef41Sopenharmony_ci<p><code>napi_key_own_only</code> limits the collected properties to the given 25601cb0ef41Sopenharmony_ciobject only. <code>napi_key_include_prototypes</code> will include all keys 25611cb0ef41Sopenharmony_ciof the objects's prototype chain as well.</p> 25621cb0ef41Sopenharmony_ci<h5><code>napi_key_filter</code><span><a class="mark" href="#napi_key_filter" id="napi_key_filter">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_key_filter"></a></h5> 25631cb0ef41Sopenharmony_ci<div class="api_metadata"> 25641cb0ef41Sopenharmony_ci<span>Added in: v13.7.0, v12.17.0, v10.20.0</span> 25651cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 25661cb0ef41Sopenharmony_ci</div> 25671cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 25681cb0ef41Sopenharmony_ci napi_key_all_properties = <span class="hljs-number">0</span>, 25691cb0ef41Sopenharmony_ci napi_key_writable = <span class="hljs-number">1</span>, 25701cb0ef41Sopenharmony_ci napi_key_enumerable = <span class="hljs-number">1</span> << <span class="hljs-number">1</span>, 25711cb0ef41Sopenharmony_ci napi_key_configurable = <span class="hljs-number">1</span> << <span class="hljs-number">2</span>, 25721cb0ef41Sopenharmony_ci napi_key_skip_strings = <span class="hljs-number">1</span> << <span class="hljs-number">3</span>, 25731cb0ef41Sopenharmony_ci napi_key_skip_symbols = <span class="hljs-number">1</span> << <span class="hljs-number">4</span> 25741cb0ef41Sopenharmony_ci} napi_key_filter;</code> <button class="copy-button">copy</button></pre> 25751cb0ef41Sopenharmony_ci<p>Property filter bits. They can be or'ed to build a composite filter.</p> 25761cb0ef41Sopenharmony_ci<h5><code>napi_key_conversion</code><span><a class="mark" href="#napi_key_conversion" id="napi_key_conversion">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_key_conversion"></a></h5> 25771cb0ef41Sopenharmony_ci<div class="api_metadata"> 25781cb0ef41Sopenharmony_ci<span>Added in: v13.7.0, v12.17.0, v10.20.0</span> 25791cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 25801cb0ef41Sopenharmony_ci</div> 25811cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 25821cb0ef41Sopenharmony_ci napi_key_keep_numbers, 25831cb0ef41Sopenharmony_ci napi_key_numbers_to_strings 25841cb0ef41Sopenharmony_ci} napi_key_conversion;</code> <button class="copy-button">copy</button></pre> 25851cb0ef41Sopenharmony_ci<p><code>napi_key_numbers_to_strings</code> will convert integer indices to 25861cb0ef41Sopenharmony_cistrings. <code>napi_key_keep_numbers</code> will return numbers for integer 25871cb0ef41Sopenharmony_ciindices.</p> 25881cb0ef41Sopenharmony_ci<h5><code>napi_valuetype</code><span><a class="mark" href="#napi_valuetype" id="napi_valuetype">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_valuetype"></a></h5> 25891cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 25901cb0ef41Sopenharmony_ci <span class="hljs-comment">// ES6 types (corresponds to typeof)</span> 25911cb0ef41Sopenharmony_ci napi_undefined, 25921cb0ef41Sopenharmony_ci napi_null, 25931cb0ef41Sopenharmony_ci napi_boolean, 25941cb0ef41Sopenharmony_ci napi_number, 25951cb0ef41Sopenharmony_ci napi_string, 25961cb0ef41Sopenharmony_ci napi_symbol, 25971cb0ef41Sopenharmony_ci napi_object, 25981cb0ef41Sopenharmony_ci napi_function, 25991cb0ef41Sopenharmony_ci napi_external, 26001cb0ef41Sopenharmony_ci napi_bigint, 26011cb0ef41Sopenharmony_ci} napi_valuetype;</code> <button class="copy-button">copy</button></pre> 26021cb0ef41Sopenharmony_ci<p>Describes the type of a <code>napi_value</code>. This generally corresponds to the types 26031cb0ef41Sopenharmony_cidescribed in <a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types">Section 6.1</a> of the ECMAScript Language Specification. 26041cb0ef41Sopenharmony_ciIn addition to types in that section, <code>napi_valuetype</code> can also represent 26051cb0ef41Sopenharmony_ci<code>Function</code>s and <code>Object</code>s with external data.</p> 26061cb0ef41Sopenharmony_ci<p>A JavaScript value of type <code>napi_external</code> appears in JavaScript as a plain 26071cb0ef41Sopenharmony_ciobject such that no properties can be set on it, and no prototype.</p> 26081cb0ef41Sopenharmony_ci<h5><code>napi_typedarray_type</code><span><a class="mark" href="#napi_typedarray_type" id="napi_typedarray_type">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_typedarray_type"></a></h5> 26091cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 26101cb0ef41Sopenharmony_ci napi_int8_array, 26111cb0ef41Sopenharmony_ci napi_uint8_array, 26121cb0ef41Sopenharmony_ci napi_uint8_clamped_array, 26131cb0ef41Sopenharmony_ci napi_int16_array, 26141cb0ef41Sopenharmony_ci napi_uint16_array, 26151cb0ef41Sopenharmony_ci napi_int32_array, 26161cb0ef41Sopenharmony_ci napi_uint32_array, 26171cb0ef41Sopenharmony_ci napi_float32_array, 26181cb0ef41Sopenharmony_ci napi_float64_array, 26191cb0ef41Sopenharmony_ci napi_bigint64_array, 26201cb0ef41Sopenharmony_ci napi_biguint64_array, 26211cb0ef41Sopenharmony_ci} napi_typedarray_type;</code> <button class="copy-button">copy</button></pre> 26221cb0ef41Sopenharmony_ci<p>This represents the underlying binary scalar datatype of the <code>TypedArray</code>. 26231cb0ef41Sopenharmony_ciElements of this enum correspond to 26241cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-typedarray-objects">Section 22.2</a> of the <a href="https://tc39.github.io/ecma262/">ECMAScript Language Specification</a>.</p> 26251cb0ef41Sopenharmony_ci<h4>Object creation functions<span><a class="mark" href="#object-creation-functions" id="object-creation-functions">#</a></span><a aria-hidden="true" class="legacy" id="n_api_object_creation_functions"></a></h4> 26261cb0ef41Sopenharmony_ci<h5><code>napi_create_array</code><span><a class="mark" href="#napi_create_array" id="napi_create_array">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_array"></a></h5> 26271cb0ef41Sopenharmony_ci<div class="api_metadata"> 26281cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 26291cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 26301cb0ef41Sopenharmony_ci</div> 26311cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_array</span><span class="hljs-params">(napi_env env, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 26321cb0ef41Sopenharmony_ci<ul> 26331cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 26341cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>Array</code>.</li> 26351cb0ef41Sopenharmony_ci</ul> 26361cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 26371cb0ef41Sopenharmony_ci<p>This API returns a Node-API value corresponding to a JavaScript <code>Array</code> type. 26381cb0ef41Sopenharmony_ciJavaScript arrays are described in 26391cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-array-objects">Section 22.1</a> of the ECMAScript Language Specification.</p> 26401cb0ef41Sopenharmony_ci<h5><code>napi_create_array_with_length</code><span><a class="mark" href="#napi_create_array_with_length" id="napi_create_array_with_length">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_array_with_length"></a></h5> 26411cb0ef41Sopenharmony_ci<div class="api_metadata"> 26421cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 26431cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 26441cb0ef41Sopenharmony_ci</div> 26451cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_array_with_length</span><span class="hljs-params">(napi_env env, 26461cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 26471cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 26481cb0ef41Sopenharmony_ci<ul> 26491cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 26501cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The initial length of the <code>Array</code>.</li> 26511cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>Array</code>.</li> 26521cb0ef41Sopenharmony_ci</ul> 26531cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 26541cb0ef41Sopenharmony_ci<p>This API returns a Node-API value corresponding to a JavaScript <code>Array</code> type. 26551cb0ef41Sopenharmony_ciThe <code>Array</code>'s length property is set to the passed-in length parameter. 26561cb0ef41Sopenharmony_ciHowever, the underlying buffer is not guaranteed to be pre-allocated by the VM 26571cb0ef41Sopenharmony_ciwhen the array is created. That behavior is left to the underlying VM 26581cb0ef41Sopenharmony_ciimplementation. If the buffer must be a contiguous block of memory that can be 26591cb0ef41Sopenharmony_cidirectly read and/or written via C, consider using 26601cb0ef41Sopenharmony_ci<a href="#napi_create_external_arraybuffer"><code>napi_create_external_arraybuffer</code></a>.</p> 26611cb0ef41Sopenharmony_ci<p>JavaScript arrays are described in 26621cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-array-objects">Section 22.1</a> of the ECMAScript Language Specification.</p> 26631cb0ef41Sopenharmony_ci<h5><code>napi_create_arraybuffer</code><span><a class="mark" href="#napi_create_arraybuffer" id="napi_create_arraybuffer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_arraybuffer"></a></h5> 26641cb0ef41Sopenharmony_ci<div class="api_metadata"> 26651cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 26661cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 26671cb0ef41Sopenharmony_ci</div> 26681cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_arraybuffer</span><span class="hljs-params">(napi_env env, 26691cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> byte_length, 26701cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** data, 26711cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 26721cb0ef41Sopenharmony_ci<ul> 26731cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 26741cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length in bytes of the array buffer to create.</li> 26751cb0ef41Sopenharmony_ci<li><code>[out] data</code>: Pointer to the underlying byte buffer of the <code>ArrayBuffer</code>. 26761cb0ef41Sopenharmony_ci<code>data</code> can optionally be ignored by passing <code>NULL</code>.</li> 26771cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>ArrayBuffer</code>.</li> 26781cb0ef41Sopenharmony_ci</ul> 26791cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 26801cb0ef41Sopenharmony_ci<p>This API returns a Node-API value corresponding to a JavaScript <code>ArrayBuffer</code>. 26811cb0ef41Sopenharmony_ci<code>ArrayBuffer</code>s are used to represent fixed-length binary data buffers. They are 26821cb0ef41Sopenharmony_cinormally used as a backing-buffer for <code>TypedArray</code> objects. 26831cb0ef41Sopenharmony_ciThe <code>ArrayBuffer</code> allocated will have an underlying byte buffer whose size is 26841cb0ef41Sopenharmony_cidetermined by the <code>length</code> parameter that's passed in. 26851cb0ef41Sopenharmony_ciThe underlying buffer is optionally returned back to the caller in case the 26861cb0ef41Sopenharmony_cicaller wants to directly manipulate the buffer. This buffer can only be 26871cb0ef41Sopenharmony_ciwritten to directly from native code. To write to this buffer from JavaScript, 26881cb0ef41Sopenharmony_cia typed array or <code>DataView</code> object would need to be created.</p> 26891cb0ef41Sopenharmony_ci<p>JavaScript <code>ArrayBuffer</code> objects are described in 26901cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-arraybuffer-objects">Section 24.1</a> of the ECMAScript Language Specification.</p> 26911cb0ef41Sopenharmony_ci<h5><code>napi_create_buffer</code><span><a class="mark" href="#napi_create_buffer" id="napi_create_buffer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_buffer"></a></h5> 26921cb0ef41Sopenharmony_ci<div class="api_metadata"> 26931cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 26941cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 26951cb0ef41Sopenharmony_ci</div> 26961cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_buffer</span><span class="hljs-params">(napi_env env, 26971cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> size, 26981cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** data, 26991cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 27001cb0ef41Sopenharmony_ci<ul> 27011cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 27021cb0ef41Sopenharmony_ci<li><code>[in] size</code>: Size in bytes of the underlying buffer.</li> 27031cb0ef41Sopenharmony_ci<li><code>[out] data</code>: Raw pointer to the underlying buffer. 27041cb0ef41Sopenharmony_ci<code>data</code> can optionally be ignored by passing <code>NULL</code>.</li> 27051cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a <code>node::Buffer</code>.</li> 27061cb0ef41Sopenharmony_ci</ul> 27071cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 27081cb0ef41Sopenharmony_ci<p>This API allocates a <code>node::Buffer</code> object. While this is still a 27091cb0ef41Sopenharmony_cifully-supported data structure, in most cases using a <code>TypedArray</code> will suffice.</p> 27101cb0ef41Sopenharmony_ci<h5><code>napi_create_buffer_copy</code><span><a class="mark" href="#napi_create_buffer_copy" id="napi_create_buffer_copy">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_buffer_copy"></a></h5> 27111cb0ef41Sopenharmony_ci<div class="api_metadata"> 27121cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 27131cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 27141cb0ef41Sopenharmony_ci</div> 27151cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_buffer_copy</span><span class="hljs-params">(napi_env env, 27161cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 27171cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">void</span>* data, 27181cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** result_data, 27191cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 27201cb0ef41Sopenharmony_ci<ul> 27211cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 27221cb0ef41Sopenharmony_ci<li><code>[in] size</code>: Size in bytes of the input buffer (should be the same as the size 27231cb0ef41Sopenharmony_ciof the new buffer).</li> 27241cb0ef41Sopenharmony_ci<li><code>[in] data</code>: Raw pointer to the underlying buffer to copy from.</li> 27251cb0ef41Sopenharmony_ci<li><code>[out] result_data</code>: Pointer to the new <code>Buffer</code>'s underlying data buffer. 27261cb0ef41Sopenharmony_ci<code>result_data</code> can optionally be ignored by passing <code>NULL</code>.</li> 27271cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a <code>node::Buffer</code>.</li> 27281cb0ef41Sopenharmony_ci</ul> 27291cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 27301cb0ef41Sopenharmony_ci<p>This API allocates a <code>node::Buffer</code> object and initializes it with data copied 27311cb0ef41Sopenharmony_cifrom the passed-in buffer. While this is still a fully-supported data 27321cb0ef41Sopenharmony_cistructure, in most cases using a <code>TypedArray</code> will suffice.</p> 27331cb0ef41Sopenharmony_ci<h5><code>napi_create_date</code><span><a class="mark" href="#napi_create_date" id="napi_create_date">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_date"></a></h5> 27341cb0ef41Sopenharmony_ci<div class="api_metadata"> 27351cb0ef41Sopenharmony_ci<span>Added in: v11.11.0, v10.17.0</span> 27361cb0ef41Sopenharmony_ci<span>N-API version: 5</span> 27371cb0ef41Sopenharmony_ci</div> 27381cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_date</span><span class="hljs-params">(napi_env env, 27391cb0ef41Sopenharmony_ci <span class="hljs-type">double</span> time, 27401cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 27411cb0ef41Sopenharmony_ci<ul> 27421cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 27431cb0ef41Sopenharmony_ci<li><code>[in] time</code>: ECMAScript time value in milliseconds since 01 January, 1970 UTC.</li> 27441cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>Date</code>.</li> 27451cb0ef41Sopenharmony_ci</ul> 27461cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 27471cb0ef41Sopenharmony_ci<p>This API does not observe leap seconds; they are ignored, as 27481cb0ef41Sopenharmony_ciECMAScript aligns with POSIX time specification.</p> 27491cb0ef41Sopenharmony_ci<p>This API allocates a JavaScript <code>Date</code> object.</p> 27501cb0ef41Sopenharmony_ci<p>JavaScript <code>Date</code> objects are described in 27511cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-date-objects">Section 20.3</a> of the ECMAScript Language Specification.</p> 27521cb0ef41Sopenharmony_ci<h5><code>napi_create_external</code><span><a class="mark" href="#napi_create_external" id="napi_create_external">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_external"></a></h5> 27531cb0ef41Sopenharmony_ci<div class="api_metadata"> 27541cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 27551cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 27561cb0ef41Sopenharmony_ci</div> 27571cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_external</span><span class="hljs-params">(napi_env env, 27581cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data, 27591cb0ef41Sopenharmony_ci napi_finalize finalize_cb, 27601cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint, 27611cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 27621cb0ef41Sopenharmony_ci<ul> 27631cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 27641cb0ef41Sopenharmony_ci<li><code>[in] data</code>: Raw pointer to the external data.</li> 27651cb0ef41Sopenharmony_ci<li><code>[in] finalize_cb</code>: Optional callback to call when the external value is being 27661cb0ef41Sopenharmony_cicollected. <a href="#napi_finalize"><code>napi_finalize</code></a> provides more details.</li> 27671cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional hint to pass to the finalize callback during 27681cb0ef41Sopenharmony_cicollection.</li> 27691cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing an external value.</li> 27701cb0ef41Sopenharmony_ci</ul> 27711cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 27721cb0ef41Sopenharmony_ci<p>This API allocates a JavaScript value with external data attached to it. This 27731cb0ef41Sopenharmony_ciis used to pass external data through JavaScript code, so it can be retrieved 27741cb0ef41Sopenharmony_cilater by native code using <a href="#napi_get_value_external"><code>napi_get_value_external</code></a>.</p> 27751cb0ef41Sopenharmony_ci<p>The API adds a <code>napi_finalize</code> callback which will be called when the JavaScript 27761cb0ef41Sopenharmony_ciobject just created has been garbage collected.</p> 27771cb0ef41Sopenharmony_ci<p>The created value is not an object, and therefore does not support additional 27781cb0ef41Sopenharmony_ciproperties. It is considered a distinct value type: calling <code>napi_typeof()</code> with 27791cb0ef41Sopenharmony_cian external value yields <code>napi_external</code>.</p> 27801cb0ef41Sopenharmony_ci<h5><code>napi_create_external_arraybuffer</code><span><a class="mark" href="#napi_create_external_arraybuffer" id="napi_create_external_arraybuffer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_external_arraybuffer"></a></h5> 27811cb0ef41Sopenharmony_ci<div class="api_metadata"> 27821cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 27831cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 27841cb0ef41Sopenharmony_ci</div> 27851cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status 27861cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_create_external_arraybuffer</span><span class="hljs-params">(napi_env env, 27871cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* external_data, 27881cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> byte_length, 27891cb0ef41Sopenharmony_ci napi_finalize finalize_cb, 27901cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint, 27911cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 27921cb0ef41Sopenharmony_ci<ul> 27931cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 27941cb0ef41Sopenharmony_ci<li><code>[in] external_data</code>: Pointer to the underlying byte buffer of the 27951cb0ef41Sopenharmony_ci<code>ArrayBuffer</code>.</li> 27961cb0ef41Sopenharmony_ci<li><code>[in] byte_length</code>: The length in bytes of the underlying buffer.</li> 27971cb0ef41Sopenharmony_ci<li><code>[in] finalize_cb</code>: Optional callback to call when the <code>ArrayBuffer</code> is being 27981cb0ef41Sopenharmony_cicollected. <a href="#napi_finalize"><code>napi_finalize</code></a> provides more details.</li> 27991cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional hint to pass to the finalize callback during 28001cb0ef41Sopenharmony_cicollection.</li> 28011cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>ArrayBuffer</code>.</li> 28021cb0ef41Sopenharmony_ci</ul> 28031cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 28041cb0ef41Sopenharmony_ci<p><strong>Some runtimes other than Node.js have dropped support for external buffers</strong>. 28051cb0ef41Sopenharmony_ciOn runtimes other than Node.js this method may return 28061cb0ef41Sopenharmony_ci<code>napi_no_external_buffers_allowed</code> to indicate that external 28071cb0ef41Sopenharmony_cibuffers are not supported. One such runtime is Electron as 28081cb0ef41Sopenharmony_cidescribed in this issue 28091cb0ef41Sopenharmony_ci<a href="https://github.com/electron/electron/issues/35801">electron/issues/35801</a>.</p> 28101cb0ef41Sopenharmony_ci<p>In order to maintain broadest compatibility with all runtimes 28111cb0ef41Sopenharmony_ciyou may define <code>NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED</code> in your addon before 28121cb0ef41Sopenharmony_ciincludes for the node-api headers. Doing so will hide the 2 functions 28131cb0ef41Sopenharmony_cithat create external buffers. This will ensure a compilation error 28141cb0ef41Sopenharmony_cioccurs if you accidentally use one of these methods.</p> 28151cb0ef41Sopenharmony_ci<p>This API returns a Node-API value corresponding to a JavaScript <code>ArrayBuffer</code>. 28161cb0ef41Sopenharmony_ciThe underlying byte buffer of the <code>ArrayBuffer</code> is externally allocated and 28171cb0ef41Sopenharmony_cimanaged. The caller must ensure that the byte buffer remains valid until the 28181cb0ef41Sopenharmony_cifinalize callback is called.</p> 28191cb0ef41Sopenharmony_ci<p>The API adds a <code>napi_finalize</code> callback which will be called when the JavaScript 28201cb0ef41Sopenharmony_ciobject just created has been garbage collected.</p> 28211cb0ef41Sopenharmony_ci<p>JavaScript <code>ArrayBuffer</code>s are described in 28221cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-arraybuffer-objects">Section 24.1</a> of the ECMAScript Language Specification.</p> 28231cb0ef41Sopenharmony_ci<h5><code>napi_create_external_buffer</code><span><a class="mark" href="#napi_create_external_buffer" id="napi_create_external_buffer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_external_buffer"></a></h5> 28241cb0ef41Sopenharmony_ci<div class="api_metadata"> 28251cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 28261cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 28271cb0ef41Sopenharmony_ci</div> 28281cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_external_buffer</span><span class="hljs-params">(napi_env env, 28291cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 28301cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data, 28311cb0ef41Sopenharmony_ci napi_finalize finalize_cb, 28321cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint, 28331cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 28341cb0ef41Sopenharmony_ci<ul> 28351cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 28361cb0ef41Sopenharmony_ci<li><code>[in] length</code>: Size in bytes of the input buffer (should be the same as the 28371cb0ef41Sopenharmony_cisize of the new buffer).</li> 28381cb0ef41Sopenharmony_ci<li><code>[in] data</code>: Raw pointer to the underlying buffer to expose to JavaScript.</li> 28391cb0ef41Sopenharmony_ci<li><code>[in] finalize_cb</code>: Optional callback to call when the <code>ArrayBuffer</code> is being 28401cb0ef41Sopenharmony_cicollected. <a href="#napi_finalize"><code>napi_finalize</code></a> provides more details.</li> 28411cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional hint to pass to the finalize callback during 28421cb0ef41Sopenharmony_cicollection.</li> 28431cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a <code>node::Buffer</code>.</li> 28441cb0ef41Sopenharmony_ci</ul> 28451cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 28461cb0ef41Sopenharmony_ci<p><strong>Some runtimes other than Node.js have dropped support for external buffers</strong>. 28471cb0ef41Sopenharmony_ciOn runtimes other than Node.js this method may return 28481cb0ef41Sopenharmony_ci<code>napi_no_external_buffers_allowed</code> to indicate that external 28491cb0ef41Sopenharmony_cibuffers are not supported. One such runtime is Electron as 28501cb0ef41Sopenharmony_cidescribed in this issue 28511cb0ef41Sopenharmony_ci<a href="https://github.com/electron/electron/issues/35801">electron/issues/35801</a>.</p> 28521cb0ef41Sopenharmony_ci<p>In order to maintain broadest compatibility with all runtimes 28531cb0ef41Sopenharmony_ciyou may define <code>NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED</code> in your addon before 28541cb0ef41Sopenharmony_ciincludes for the node-api headers. Doing so will hide the 2 functions 28551cb0ef41Sopenharmony_cithat create external buffers. This will ensure a compilation error 28561cb0ef41Sopenharmony_cioccurs if you accidentally use one of these methods.</p> 28571cb0ef41Sopenharmony_ci<p>This API allocates a <code>node::Buffer</code> object and initializes it with data 28581cb0ef41Sopenharmony_cibacked by the passed in buffer. While this is still a fully-supported data 28591cb0ef41Sopenharmony_cistructure, in most cases using a <code>TypedArray</code> will suffice.</p> 28601cb0ef41Sopenharmony_ci<p>The API adds a <code>napi_finalize</code> callback which will be called when the JavaScript 28611cb0ef41Sopenharmony_ciobject just created has been garbage collected.</p> 28621cb0ef41Sopenharmony_ci<p>For Node.js >=4 <code>Buffers</code> are <code>Uint8Array</code>s.</p> 28631cb0ef41Sopenharmony_ci<h5><code>napi_create_object</code><span><a class="mark" href="#napi_create_object" id="napi_create_object">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_object"></a></h5> 28641cb0ef41Sopenharmony_ci<div class="api_metadata"> 28651cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 28661cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 28671cb0ef41Sopenharmony_ci</div> 28681cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_object</span><span class="hljs-params">(napi_env env, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 28691cb0ef41Sopenharmony_ci<ul> 28701cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 28711cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>Object</code>.</li> 28721cb0ef41Sopenharmony_ci</ul> 28731cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 28741cb0ef41Sopenharmony_ci<p>This API allocates a default JavaScript <code>Object</code>. 28751cb0ef41Sopenharmony_ciIt is the equivalent of doing <code>new Object()</code> in JavaScript.</p> 28761cb0ef41Sopenharmony_ci<p>The JavaScript <code>Object</code> type is described in <a href="https://tc39.github.io/ecma262/#sec-object-type">Section 6.1.7</a> of the 28771cb0ef41Sopenharmony_ciECMAScript Language Specification.</p> 28781cb0ef41Sopenharmony_ci<h5><code>napi_create_symbol</code><span><a class="mark" href="#napi_create_symbol" id="napi_create_symbol">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_symbol"></a></h5> 28791cb0ef41Sopenharmony_ci<div class="api_metadata"> 28801cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 28811cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 28821cb0ef41Sopenharmony_ci</div> 28831cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_symbol</span><span class="hljs-params">(napi_env env, 28841cb0ef41Sopenharmony_ci napi_value description, 28851cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 28861cb0ef41Sopenharmony_ci<ul> 28871cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 28881cb0ef41Sopenharmony_ci<li><code>[in] description</code>: Optional <code>napi_value</code> which refers to a JavaScript 28891cb0ef41Sopenharmony_ci<code>string</code> to be set as the description for the symbol.</li> 28901cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>symbol</code>.</li> 28911cb0ef41Sopenharmony_ci</ul> 28921cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 28931cb0ef41Sopenharmony_ci<p>This API creates a JavaScript <code>symbol</code> value from a UTF8-encoded C string.</p> 28941cb0ef41Sopenharmony_ci<p>The JavaScript <code>symbol</code> type is described in <a href="https://tc39.github.io/ecma262/#sec-symbol-objects">Section 19.4</a> 28951cb0ef41Sopenharmony_ciof the ECMAScript Language Specification.</p> 28961cb0ef41Sopenharmony_ci<h5><code>node_api_symbol_for</code><span><a class="mark" href="#node_api_symbol_for" id="node_api_symbol_for">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_symbol_for"></a></h5> 28971cb0ef41Sopenharmony_ci<div class="api_metadata"> 28981cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 28991cb0ef41Sopenharmony_ci<span>N-API version: 9</span> 29001cb0ef41Sopenharmony_ci</div> 29011cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">node_api_symbol_for</span><span class="hljs-params">(napi_env env, 29021cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* utf8description, 29031cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 29041cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 29051cb0ef41Sopenharmony_ci<ul> 29061cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 29071cb0ef41Sopenharmony_ci<li><code>[in] utf8description</code>: UTF-8 C string representing the text to be used as the 29081cb0ef41Sopenharmony_cidescription for the symbol.</li> 29091cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length of the description string in bytes, or 29101cb0ef41Sopenharmony_ci<code>NAPI_AUTO_LENGTH</code> if it is null-terminated.</li> 29111cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>symbol</code>.</li> 29121cb0ef41Sopenharmony_ci</ul> 29131cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 29141cb0ef41Sopenharmony_ci<p>This API searches in the global registry for an existing symbol with the given 29151cb0ef41Sopenharmony_cidescription. If the symbol already exists it will be returned, otherwise a new 29161cb0ef41Sopenharmony_cisymbol will be created in the registry.</p> 29171cb0ef41Sopenharmony_ci<p>The JavaScript <code>symbol</code> type is described in <a href="https://tc39.github.io/ecma262/#sec-symbol-objects">Section 19.4</a> of the ECMAScript 29181cb0ef41Sopenharmony_ciLanguage Specification.</p> 29191cb0ef41Sopenharmony_ci<h5><code>napi_create_typedarray</code><span><a class="mark" href="#napi_create_typedarray" id="napi_create_typedarray">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_typedarray"></a></h5> 29201cb0ef41Sopenharmony_ci<div class="api_metadata"> 29211cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 29221cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 29231cb0ef41Sopenharmony_ci</div> 29241cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_typedarray</span><span class="hljs-params">(napi_env env, 29251cb0ef41Sopenharmony_ci napi_typedarray_type type, 29261cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 29271cb0ef41Sopenharmony_ci napi_value arraybuffer, 29281cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> byte_offset, 29291cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 29301cb0ef41Sopenharmony_ci<ul> 29311cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 29321cb0ef41Sopenharmony_ci<li><code>[in] type</code>: Scalar datatype of the elements within the <code>TypedArray</code>.</li> 29331cb0ef41Sopenharmony_ci<li><code>[in] length</code>: Number of elements in the <code>TypedArray</code>.</li> 29341cb0ef41Sopenharmony_ci<li><code>[in] arraybuffer</code>: <code>ArrayBuffer</code> underlying the typed array.</li> 29351cb0ef41Sopenharmony_ci<li><code>[in] byte_offset</code>: The byte offset within the <code>ArrayBuffer</code> from which to 29361cb0ef41Sopenharmony_cistart projecting the <code>TypedArray</code>.</li> 29371cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>TypedArray</code>.</li> 29381cb0ef41Sopenharmony_ci</ul> 29391cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 29401cb0ef41Sopenharmony_ci<p>This API creates a JavaScript <code>TypedArray</code> object over an existing 29411cb0ef41Sopenharmony_ci<code>ArrayBuffer</code>. <code>TypedArray</code> objects provide an array-like view over an 29421cb0ef41Sopenharmony_ciunderlying data buffer where each element has the same underlying binary scalar 29431cb0ef41Sopenharmony_cidatatype.</p> 29441cb0ef41Sopenharmony_ci<p>It's required that <code>(length * size_of_element) + byte_offset</code> should 29451cb0ef41Sopenharmony_cibe <= the size in bytes of the array passed in. If not, a <code>RangeError</code> exception 29461cb0ef41Sopenharmony_ciis raised.</p> 29471cb0ef41Sopenharmony_ci<p>JavaScript <code>TypedArray</code> objects are described in 29481cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-typedarray-objects">Section 22.2</a> of the ECMAScript Language Specification.</p> 29491cb0ef41Sopenharmony_ci<h5><code>napi_create_dataview</code><span><a class="mark" href="#napi_create_dataview" id="napi_create_dataview">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_dataview"></a></h5> 29501cb0ef41Sopenharmony_ci<div class="api_metadata"> 29511cb0ef41Sopenharmony_ci<span>Added in: v8.3.0</span> 29521cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 29531cb0ef41Sopenharmony_ci</div> 29541cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_dataview</span><span class="hljs-params">(napi_env env, 29551cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> byte_length, 29561cb0ef41Sopenharmony_ci napi_value arraybuffer, 29571cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> byte_offset, 29581cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 29591cb0ef41Sopenharmony_ci<ul> 29601cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 29611cb0ef41Sopenharmony_ci<li><code>[in] length</code>: Number of elements in the <code>DataView</code>.</li> 29621cb0ef41Sopenharmony_ci<li><code>[in] arraybuffer</code>: <code>ArrayBuffer</code> underlying the <code>DataView</code>.</li> 29631cb0ef41Sopenharmony_ci<li><code>[in] byte_offset</code>: The byte offset within the <code>ArrayBuffer</code> from which to 29641cb0ef41Sopenharmony_cistart projecting the <code>DataView</code>.</li> 29651cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>DataView</code>.</li> 29661cb0ef41Sopenharmony_ci</ul> 29671cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 29681cb0ef41Sopenharmony_ci<p>This API creates a JavaScript <code>DataView</code> object over an existing <code>ArrayBuffer</code>. 29691cb0ef41Sopenharmony_ci<code>DataView</code> objects provide an array-like view over an underlying data buffer, 29701cb0ef41Sopenharmony_cibut one which allows items of different size and type in the <code>ArrayBuffer</code>.</p> 29711cb0ef41Sopenharmony_ci<p>It is required that <code>byte_length + byte_offset</code> is less than or equal to the 29721cb0ef41Sopenharmony_cisize in bytes of the array passed in. If not, a <code>RangeError</code> exception is 29731cb0ef41Sopenharmony_ciraised.</p> 29741cb0ef41Sopenharmony_ci<p>JavaScript <code>DataView</code> objects are described in 29751cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-dataview-objects">Section 24.3</a> of the ECMAScript Language Specification.</p> 29761cb0ef41Sopenharmony_ci<h4>Functions to convert from C types to Node-API<span><a class="mark" href="#functions-to-convert-from-c-types-to-node-api" id="functions-to-convert-from-c-types-to-node-api">#</a></span><a aria-hidden="true" class="legacy" id="n_api_functions_to_convert_from_c_types_to_node_api"></a></h4> 29771cb0ef41Sopenharmony_ci<h5><code>napi_create_int32</code><span><a class="mark" href="#napi_create_int32" id="napi_create_int32">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_int32"></a></h5> 29781cb0ef41Sopenharmony_ci<div class="api_metadata"> 29791cb0ef41Sopenharmony_ci<span>Added in: v8.4.0</span> 29801cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 29811cb0ef41Sopenharmony_ci</div> 29821cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_int32</span><span class="hljs-params">(napi_env env, <span class="hljs-type">int32_t</span> value, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 29831cb0ef41Sopenharmony_ci<ul> 29841cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 29851cb0ef41Sopenharmony_ci<li><code>[in] value</code>: Integer value to be represented in JavaScript.</li> 29861cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>number</code>.</li> 29871cb0ef41Sopenharmony_ci</ul> 29881cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 29891cb0ef41Sopenharmony_ci<p>This API is used to convert from the C <code>int32_t</code> type to the JavaScript 29901cb0ef41Sopenharmony_ci<code>number</code> type.</p> 29911cb0ef41Sopenharmony_ci<p>The JavaScript <code>number</code> type is described in 29921cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type">Section 6.1.6</a> of the ECMAScript Language Specification.</p> 29931cb0ef41Sopenharmony_ci<h5><code>napi_create_uint32</code><span><a class="mark" href="#napi_create_uint32" id="napi_create_uint32">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_uint32"></a></h5> 29941cb0ef41Sopenharmony_ci<div class="api_metadata"> 29951cb0ef41Sopenharmony_ci<span>Added in: v8.4.0</span> 29961cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 29971cb0ef41Sopenharmony_ci</div> 29981cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_uint32</span><span class="hljs-params">(napi_env env, <span class="hljs-type">uint32_t</span> value, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 29991cb0ef41Sopenharmony_ci<ul> 30001cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 30011cb0ef41Sopenharmony_ci<li><code>[in] value</code>: Unsigned integer value to be represented in JavaScript.</li> 30021cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>number</code>.</li> 30031cb0ef41Sopenharmony_ci</ul> 30041cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 30051cb0ef41Sopenharmony_ci<p>This API is used to convert from the C <code>uint32_t</code> type to the JavaScript 30061cb0ef41Sopenharmony_ci<code>number</code> type.</p> 30071cb0ef41Sopenharmony_ci<p>The JavaScript <code>number</code> type is described in 30081cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type">Section 6.1.6</a> of the ECMAScript Language Specification.</p> 30091cb0ef41Sopenharmony_ci<h5><code>napi_create_int64</code><span><a class="mark" href="#napi_create_int64" id="napi_create_int64">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_int64"></a></h5> 30101cb0ef41Sopenharmony_ci<div class="api_metadata"> 30111cb0ef41Sopenharmony_ci<span>Added in: v8.4.0</span> 30121cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 30131cb0ef41Sopenharmony_ci</div> 30141cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_int64</span><span class="hljs-params">(napi_env env, <span class="hljs-type">int64_t</span> value, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 30151cb0ef41Sopenharmony_ci<ul> 30161cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 30171cb0ef41Sopenharmony_ci<li><code>[in] value</code>: Integer value to be represented in JavaScript.</li> 30181cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>number</code>.</li> 30191cb0ef41Sopenharmony_ci</ul> 30201cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 30211cb0ef41Sopenharmony_ci<p>This API is used to convert from the C <code>int64_t</code> type to the JavaScript 30221cb0ef41Sopenharmony_ci<code>number</code> type.</p> 30231cb0ef41Sopenharmony_ci<p>The JavaScript <code>number</code> type is described in <a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type">Section 6.1.6</a> 30241cb0ef41Sopenharmony_ciof the ECMAScript Language Specification. Note the complete range of <code>int64_t</code> 30251cb0ef41Sopenharmony_cicannot be represented with full precision in JavaScript. Integer values 30261cb0ef41Sopenharmony_cioutside the range of <a href="https://tc39.github.io/ecma262/#sec-number.min_safe_integer"><code>Number.MIN_SAFE_INTEGER</code></a> <code>-(2**53 - 1)</code> - 30271cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-number.max_safe_integer"><code>Number.MAX_SAFE_INTEGER</code></a> <code>(2**53 - 1)</code> will lose precision.</p> 30281cb0ef41Sopenharmony_ci<h5><code>napi_create_double</code><span><a class="mark" href="#napi_create_double" id="napi_create_double">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_double"></a></h5> 30291cb0ef41Sopenharmony_ci<div class="api_metadata"> 30301cb0ef41Sopenharmony_ci<span>Added in: v8.4.0</span> 30311cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 30321cb0ef41Sopenharmony_ci</div> 30331cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_double</span><span class="hljs-params">(napi_env env, <span class="hljs-type">double</span> value, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 30341cb0ef41Sopenharmony_ci<ul> 30351cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 30361cb0ef41Sopenharmony_ci<li><code>[in] value</code>: Double-precision value to be represented in JavaScript.</li> 30371cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>number</code>.</li> 30381cb0ef41Sopenharmony_ci</ul> 30391cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 30401cb0ef41Sopenharmony_ci<p>This API is used to convert from the C <code>double</code> type to the JavaScript 30411cb0ef41Sopenharmony_ci<code>number</code> type.</p> 30421cb0ef41Sopenharmony_ci<p>The JavaScript <code>number</code> type is described in 30431cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type">Section 6.1.6</a> of the ECMAScript Language Specification.</p> 30441cb0ef41Sopenharmony_ci<h5><code>napi_create_bigint_int64</code><span><a class="mark" href="#napi_create_bigint_int64" id="napi_create_bigint_int64">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_bigint_int64"></a></h5> 30451cb0ef41Sopenharmony_ci<div class="api_metadata"> 30461cb0ef41Sopenharmony_ci<span>Added in: v10.7.0</span> 30471cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 30481cb0ef41Sopenharmony_ci</div> 30491cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_bigint_int64</span><span class="hljs-params">(napi_env env, 30501cb0ef41Sopenharmony_ci <span class="hljs-type">int64_t</span> value, 30511cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 30521cb0ef41Sopenharmony_ci<ul> 30531cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 30541cb0ef41Sopenharmony_ci<li><code>[in] value</code>: Integer value to be represented in JavaScript.</li> 30551cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>BigInt</code>.</li> 30561cb0ef41Sopenharmony_ci</ul> 30571cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 30581cb0ef41Sopenharmony_ci<p>This API converts the C <code>int64_t</code> type to the JavaScript <code>BigInt</code> type.</p> 30591cb0ef41Sopenharmony_ci<h5><code>napi_create_bigint_uint64</code><span><a class="mark" href="#napi_create_bigint_uint64" id="napi_create_bigint_uint64">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_bigint_uint64"></a></h5> 30601cb0ef41Sopenharmony_ci<div class="api_metadata"> 30611cb0ef41Sopenharmony_ci<span>Added in: v10.7.0</span> 30621cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 30631cb0ef41Sopenharmony_ci</div> 30641cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_bigint_uint64</span><span class="hljs-params">(napi_env env, 30651cb0ef41Sopenharmony_ci <span class="hljs-type">uint64_t</span> value, 30661cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 30671cb0ef41Sopenharmony_ci<ul> 30681cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 30691cb0ef41Sopenharmony_ci<li><code>[in] value</code>: Unsigned integer value to be represented in JavaScript.</li> 30701cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>BigInt</code>.</li> 30711cb0ef41Sopenharmony_ci</ul> 30721cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 30731cb0ef41Sopenharmony_ci<p>This API converts the C <code>uint64_t</code> type to the JavaScript <code>BigInt</code> type.</p> 30741cb0ef41Sopenharmony_ci<h5><code>napi_create_bigint_words</code><span><a class="mark" href="#napi_create_bigint_words" id="napi_create_bigint_words">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_bigint_words"></a></h5> 30751cb0ef41Sopenharmony_ci<div class="api_metadata"> 30761cb0ef41Sopenharmony_ci<span>Added in: v10.7.0</span> 30771cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 30781cb0ef41Sopenharmony_ci</div> 30791cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_bigint_words</span><span class="hljs-params">(napi_env env, 30801cb0ef41Sopenharmony_ci <span class="hljs-type">int</span> sign_bit, 30811cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> word_count, 30821cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">uint64_t</span>* words, 30831cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 30841cb0ef41Sopenharmony_ci<ul> 30851cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 30861cb0ef41Sopenharmony_ci<li><code>[in] sign_bit</code>: Determines if the resulting <code>BigInt</code> will be positive or 30871cb0ef41Sopenharmony_cinegative.</li> 30881cb0ef41Sopenharmony_ci<li><code>[in] word_count</code>: The length of the <code>words</code> array.</li> 30891cb0ef41Sopenharmony_ci<li><code>[in] words</code>: An array of <code>uint64_t</code> little-endian 64-bit words.</li> 30901cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>BigInt</code>.</li> 30911cb0ef41Sopenharmony_ci</ul> 30921cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 30931cb0ef41Sopenharmony_ci<p>This API converts an array of unsigned 64-bit words into a single <code>BigInt</code> 30941cb0ef41Sopenharmony_civalue.</p> 30951cb0ef41Sopenharmony_ci<p>The resulting <code>BigInt</code> is calculated as: (–1)<sup><code>sign_bit</code></sup> (<code>words[0]</code> 30961cb0ef41Sopenharmony_ci× (2<sup>64</sup>)<sup>0</sup> + <code>words[1]</code> × (2<sup>64</sup>)<sup>1</sup> + …)</p> 30971cb0ef41Sopenharmony_ci<h5><code>napi_create_string_latin1</code><span><a class="mark" href="#napi_create_string_latin1" id="napi_create_string_latin1">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_string_latin1"></a></h5> 30981cb0ef41Sopenharmony_ci<div class="api_metadata"> 30991cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 31001cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 31011cb0ef41Sopenharmony_ci</div> 31021cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_string_latin1</span><span class="hljs-params">(napi_env env, 31031cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* str, 31041cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 31051cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 31061cb0ef41Sopenharmony_ci<ul> 31071cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 31081cb0ef41Sopenharmony_ci<li><code>[in] str</code>: Character buffer representing an ISO-8859-1-encoded string.</li> 31091cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length of the string in bytes, or <code>NAPI_AUTO_LENGTH</code> if it 31101cb0ef41Sopenharmony_ciis null-terminated.</li> 31111cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>string</code>.</li> 31121cb0ef41Sopenharmony_ci</ul> 31131cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 31141cb0ef41Sopenharmony_ci<p>This API creates a JavaScript <code>string</code> value from an ISO-8859-1-encoded C 31151cb0ef41Sopenharmony_cistring. The native string is copied.</p> 31161cb0ef41Sopenharmony_ci<p>The JavaScript <code>string</code> type is described in 31171cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type">Section 6.1.4</a> of the ECMAScript Language Specification.</p> 31181cb0ef41Sopenharmony_ci<h5><code>node_api_create_external_string_latin1</code><span><a class="mark" href="#node_api_create_external_string_latin1" id="node_api_create_external_string_latin1">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_create_external_string_latin1"></a></h5> 31191cb0ef41Sopenharmony_ci<div class="api_metadata"> 31201cb0ef41Sopenharmony_ci<span>Added in: v18.18.0</span> 31211cb0ef41Sopenharmony_ci</div> 31221cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 31231cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status 31241cb0ef41Sopenharmony_ci<span class="hljs-title function_">node_api_create_external_string_latin1</span><span class="hljs-params">(napi_env env, 31251cb0ef41Sopenharmony_ci <span class="hljs-type">char</span>* str, 31261cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 31271cb0ef41Sopenharmony_ci napi_finalize finalize_callback, 31281cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint, 31291cb0ef41Sopenharmony_ci napi_value* result, 31301cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* copied)</span>;</code> <button class="copy-button">copy</button></pre> 31311cb0ef41Sopenharmony_ci<ul> 31321cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 31331cb0ef41Sopenharmony_ci<li><code>[in] str</code>: Character buffer representing an ISO-8859-1-encoded string.</li> 31341cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length of the string in bytes, or <code>NAPI_AUTO_LENGTH</code> if it 31351cb0ef41Sopenharmony_ciis null-terminated.</li> 31361cb0ef41Sopenharmony_ci<li><code>[in] finalize_callback</code>: The function to call when the string is being 31371cb0ef41Sopenharmony_cicollected. The function will be called with the following parameters: 31381cb0ef41Sopenharmony_ci<ul> 31391cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment in which the add-on is running. This value 31401cb0ef41Sopenharmony_cimay be null if the string is being collected as part of the termination 31411cb0ef41Sopenharmony_ciof the worker or the main Node.js instance.</li> 31421cb0ef41Sopenharmony_ci<li><code>[in] data</code>: This is the value <code>str</code> as a <code>void*</code> pointer.</li> 31431cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: This is the value <code>finalize_hint</code> that was given 31441cb0ef41Sopenharmony_cito the API. 31451cb0ef41Sopenharmony_ci<a href="#napi_finalize"><code>napi_finalize</code></a> provides more details. 31461cb0ef41Sopenharmony_ciThis parameter is optional. Passing a null value means that the add-on 31471cb0ef41Sopenharmony_cidoesn't need to be notified when the corresponding JavaScript string is 31481cb0ef41Sopenharmony_cicollected.</li> 31491cb0ef41Sopenharmony_ci</ul> 31501cb0ef41Sopenharmony_ci</li> 31511cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional hint to pass to the finalize callback during 31521cb0ef41Sopenharmony_cicollection.</li> 31531cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>string</code>.</li> 31541cb0ef41Sopenharmony_ci<li><code>[out] copied</code>: Whether the string was copied. If it was, the finalizer will 31551cb0ef41Sopenharmony_cialready have been invoked to destroy <code>str</code>.</li> 31561cb0ef41Sopenharmony_ci</ul> 31571cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 31581cb0ef41Sopenharmony_ci<p>This API creates a JavaScript <code>string</code> value from an ISO-8859-1-encoded C 31591cb0ef41Sopenharmony_cistring. The native string may not be copied and must thus exist for the entire 31601cb0ef41Sopenharmony_cilife cycle of the JavaScript value.</p> 31611cb0ef41Sopenharmony_ci<p>The JavaScript <code>string</code> type is described in 31621cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type">Section 6.1.4</a> of the ECMAScript Language Specification.</p> 31631cb0ef41Sopenharmony_ci<h5><code>napi_create_string_utf16</code><span><a class="mark" href="#napi_create_string_utf16" id="napi_create_string_utf16">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_string_utf16"></a></h5> 31641cb0ef41Sopenharmony_ci<div class="api_metadata"> 31651cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 31661cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 31671cb0ef41Sopenharmony_ci</div> 31681cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_string_utf16</span><span class="hljs-params">(napi_env env, 31691cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char16_t</span>* str, 31701cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 31711cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 31721cb0ef41Sopenharmony_ci<ul> 31731cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 31741cb0ef41Sopenharmony_ci<li><code>[in] str</code>: Character buffer representing a UTF16-LE-encoded string.</li> 31751cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length of the string in two-byte code units, or 31761cb0ef41Sopenharmony_ci<code>NAPI_AUTO_LENGTH</code> if it is null-terminated.</li> 31771cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>string</code>.</li> 31781cb0ef41Sopenharmony_ci</ul> 31791cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 31801cb0ef41Sopenharmony_ci<p>This API creates a JavaScript <code>string</code> value from a UTF16-LE-encoded C string. 31811cb0ef41Sopenharmony_ciThe native string is copied.</p> 31821cb0ef41Sopenharmony_ci<p>The JavaScript <code>string</code> type is described in 31831cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type">Section 6.1.4</a> of the ECMAScript Language Specification.</p> 31841cb0ef41Sopenharmony_ci<h5><code>node_api_create_external_string_utf16</code><span><a class="mark" href="#node_api_create_external_string_utf16" id="node_api_create_external_string_utf16">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_create_external_string_utf16"></a></h5> 31851cb0ef41Sopenharmony_ci<div class="api_metadata"> 31861cb0ef41Sopenharmony_ci<span>Added in: v18.18.0</span> 31871cb0ef41Sopenharmony_ci</div> 31881cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 31891cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status 31901cb0ef41Sopenharmony_ci<span class="hljs-title function_">node_api_create_external_string_utf16</span><span class="hljs-params">(napi_env env, 31911cb0ef41Sopenharmony_ci <span class="hljs-type">char16_t</span>* str, 31921cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 31931cb0ef41Sopenharmony_ci napi_finalize finalize_callback, 31941cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint, 31951cb0ef41Sopenharmony_ci napi_value* result, 31961cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* copied)</span>;</code> <button class="copy-button">copy</button></pre> 31971cb0ef41Sopenharmony_ci<ul> 31981cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 31991cb0ef41Sopenharmony_ci<li><code>[in] str</code>: Character buffer representing a UTF16-LE-encoded string.</li> 32001cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length of the string in two-byte code units, or 32011cb0ef41Sopenharmony_ci<code>NAPI_AUTO_LENGTH</code> if it is null-terminated.</li> 32021cb0ef41Sopenharmony_ci<li><code>[in] finalize_callback</code>: The function to call when the string is being 32031cb0ef41Sopenharmony_cicollected. The function will be called with the following parameters: 32041cb0ef41Sopenharmony_ci<ul> 32051cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment in which the add-on is running. This value 32061cb0ef41Sopenharmony_cimay be null if the string is being collected as part of the termination 32071cb0ef41Sopenharmony_ciof the worker or the main Node.js instance.</li> 32081cb0ef41Sopenharmony_ci<li><code>[in] data</code>: This is the value <code>str</code> as a <code>void*</code> pointer.</li> 32091cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: This is the value <code>finalize_hint</code> that was given 32101cb0ef41Sopenharmony_cito the API. 32111cb0ef41Sopenharmony_ci<a href="#napi_finalize"><code>napi_finalize</code></a> provides more details. 32121cb0ef41Sopenharmony_ciThis parameter is optional. Passing a null value means that the add-on 32131cb0ef41Sopenharmony_cidoesn't need to be notified when the corresponding JavaScript string is 32141cb0ef41Sopenharmony_cicollected.</li> 32151cb0ef41Sopenharmony_ci</ul> 32161cb0ef41Sopenharmony_ci</li> 32171cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional hint to pass to the finalize callback during 32181cb0ef41Sopenharmony_cicollection.</li> 32191cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>string</code>.</li> 32201cb0ef41Sopenharmony_ci<li><code>[out] copied</code>: Whether the string was copied. If it was, the finalizer will 32211cb0ef41Sopenharmony_cialready have been invoked to destroy <code>str</code>.</li> 32221cb0ef41Sopenharmony_ci</ul> 32231cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 32241cb0ef41Sopenharmony_ci<p>This API creates a JavaScript <code>string</code> value from a UTF16-LE-encoded C string. 32251cb0ef41Sopenharmony_ciThe native string may not be copied and must thus exist for the entire life 32261cb0ef41Sopenharmony_cicycle of the JavaScript value.</p> 32271cb0ef41Sopenharmony_ci<p>The JavaScript <code>string</code> type is described in 32281cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type">Section 6.1.4</a> of the ECMAScript Language Specification.</p> 32291cb0ef41Sopenharmony_ci<h5><code>napi_create_string_utf8</code><span><a class="mark" href="#napi_create_string_utf8" id="napi_create_string_utf8">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_string_utf8"></a></h5> 32301cb0ef41Sopenharmony_ci<div class="api_metadata"> 32311cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 32321cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 32331cb0ef41Sopenharmony_ci</div> 32341cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_string_utf8</span><span class="hljs-params">(napi_env env, 32351cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* str, 32361cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 32371cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 32381cb0ef41Sopenharmony_ci<ul> 32391cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 32401cb0ef41Sopenharmony_ci<li><code>[in] str</code>: Character buffer representing a UTF8-encoded string.</li> 32411cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length of the string in bytes, or <code>NAPI_AUTO_LENGTH</code> if it 32421cb0ef41Sopenharmony_ciis null-terminated.</li> 32431cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing a JavaScript <code>string</code>.</li> 32441cb0ef41Sopenharmony_ci</ul> 32451cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 32461cb0ef41Sopenharmony_ci<p>This API creates a JavaScript <code>string</code> value from a UTF8-encoded C string. 32471cb0ef41Sopenharmony_ciThe native string is copied.</p> 32481cb0ef41Sopenharmony_ci<p>The JavaScript <code>string</code> type is described in 32491cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type">Section 6.1.4</a> of the ECMAScript Language Specification.</p> 32501cb0ef41Sopenharmony_ci<h4>Functions to convert from Node-API to C types<span><a class="mark" href="#functions-to-convert-from-node-api-to-c-types" id="functions-to-convert-from-node-api-to-c-types">#</a></span><a aria-hidden="true" class="legacy" id="n_api_functions_to_convert_from_node_api_to_c_types"></a></h4> 32511cb0ef41Sopenharmony_ci<h5><code>napi_get_array_length</code><span><a class="mark" href="#napi_get_array_length" id="napi_get_array_length">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_array_length"></a></h5> 32521cb0ef41Sopenharmony_ci<div class="api_metadata"> 32531cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 32541cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 32551cb0ef41Sopenharmony_ci</div> 32561cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_array_length</span><span class="hljs-params">(napi_env env, 32571cb0ef41Sopenharmony_ci napi_value value, 32581cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span>* result)</span></code> <button class="copy-button">copy</button></pre> 32591cb0ef41Sopenharmony_ci<ul> 32601cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 32611cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing the JavaScript <code>Array</code> whose length is 32621cb0ef41Sopenharmony_cibeing queried.</li> 32631cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>uint32</code> representing length of the array.</li> 32641cb0ef41Sopenharmony_ci</ul> 32651cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 32661cb0ef41Sopenharmony_ci<p>This API returns the length of an array.</p> 32671cb0ef41Sopenharmony_ci<p><code>Array</code> length is described in <a href="https://tc39.github.io/ecma262/#sec-properties-of-array-instances-length">Section 22.1.4.1</a> of the ECMAScript Language 32681cb0ef41Sopenharmony_ciSpecification.</p> 32691cb0ef41Sopenharmony_ci<h5><code>napi_get_arraybuffer_info</code><span><a class="mark" href="#napi_get_arraybuffer_info" id="napi_get_arraybuffer_info">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_arraybuffer_info"></a></h5> 32701cb0ef41Sopenharmony_ci<div class="api_metadata"> 32711cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 32721cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 32731cb0ef41Sopenharmony_ci</div> 32741cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_arraybuffer_info</span><span class="hljs-params">(napi_env env, 32751cb0ef41Sopenharmony_ci napi_value arraybuffer, 32761cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** data, 32771cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* byte_length)</span></code> <button class="copy-button">copy</button></pre> 32781cb0ef41Sopenharmony_ci<ul> 32791cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 32801cb0ef41Sopenharmony_ci<li><code>[in] arraybuffer</code>: <code>napi_value</code> representing the <code>ArrayBuffer</code> being queried.</li> 32811cb0ef41Sopenharmony_ci<li><code>[out] data</code>: The underlying data buffer of the <code>ArrayBuffer</code>. If byte_length 32821cb0ef41Sopenharmony_ciis <code>0</code>, this may be <code>NULL</code> or any other pointer value.</li> 32831cb0ef41Sopenharmony_ci<li><code>[out] byte_length</code>: Length in bytes of the underlying data buffer.</li> 32841cb0ef41Sopenharmony_ci</ul> 32851cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 32861cb0ef41Sopenharmony_ci<p>This API is used to retrieve the underlying data buffer of an <code>ArrayBuffer</code> and 32871cb0ef41Sopenharmony_ciits length.</p> 32881cb0ef41Sopenharmony_ci<p><em>WARNING</em>: Use caution while using this API. The lifetime of the underlying data 32891cb0ef41Sopenharmony_cibuffer is managed by the <code>ArrayBuffer</code> even after it's returned. A 32901cb0ef41Sopenharmony_cipossible safe way to use this API is in conjunction with 32911cb0ef41Sopenharmony_ci<a href="#napi_create_reference"><code>napi_create_reference</code></a>, which can be used to guarantee control over the 32921cb0ef41Sopenharmony_cilifetime of the <code>ArrayBuffer</code>. It's also safe to use the returned data buffer 32931cb0ef41Sopenharmony_ciwithin the same callback as long as there are no calls to other APIs that might 32941cb0ef41Sopenharmony_citrigger a GC.</p> 32951cb0ef41Sopenharmony_ci<h5><code>napi_get_buffer_info</code><span><a class="mark" href="#napi_get_buffer_info" id="napi_get_buffer_info">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_buffer_info"></a></h5> 32961cb0ef41Sopenharmony_ci<div class="api_metadata"> 32971cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 32981cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 32991cb0ef41Sopenharmony_ci</div> 33001cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_buffer_info</span><span class="hljs-params">(napi_env env, 33011cb0ef41Sopenharmony_ci napi_value value, 33021cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** data, 33031cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* length)</span></code> <button class="copy-button">copy</button></pre> 33041cb0ef41Sopenharmony_ci<ul> 33051cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 33061cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing the <code>node::Buffer</code> or <code>Uint8Array</code> 33071cb0ef41Sopenharmony_cibeing queried.</li> 33081cb0ef41Sopenharmony_ci<li><code>[out] data</code>: The underlying data buffer of the <code>node::Buffer</code> or 33091cb0ef41Sopenharmony_ci<code>Uint8Array</code>. If length is <code>0</code>, this may be <code>NULL</code> or any other pointer value.</li> 33101cb0ef41Sopenharmony_ci<li><code>[out] length</code>: Length in bytes of the underlying data buffer.</li> 33111cb0ef41Sopenharmony_ci</ul> 33121cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 33131cb0ef41Sopenharmony_ci<p>This method returns the identical <code>data</code> and <code>byte_length</code> as 33141cb0ef41Sopenharmony_ci<a href="#napi_get_typedarray_info"><code>napi_get_typedarray_info</code></a>. And <code>napi_get_typedarray_info</code> accepts a 33151cb0ef41Sopenharmony_ci<code>node::Buffer</code> (a Uint8Array) as the value too.</p> 33161cb0ef41Sopenharmony_ci<p>This API is used to retrieve the underlying data buffer of a <code>node::Buffer</code> 33171cb0ef41Sopenharmony_ciand its length.</p> 33181cb0ef41Sopenharmony_ci<p><em>Warning</em>: Use caution while using this API since the underlying data buffer's 33191cb0ef41Sopenharmony_cilifetime is not guaranteed if it's managed by the VM.</p> 33201cb0ef41Sopenharmony_ci<h5><code>napi_get_prototype</code><span><a class="mark" href="#napi_get_prototype" id="napi_get_prototype">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_prototype"></a></h5> 33211cb0ef41Sopenharmony_ci<div class="api_metadata"> 33221cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 33231cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 33241cb0ef41Sopenharmony_ci</div> 33251cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_prototype</span><span class="hljs-params">(napi_env env, 33261cb0ef41Sopenharmony_ci napi_value object, 33271cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 33281cb0ef41Sopenharmony_ci<ul> 33291cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 33301cb0ef41Sopenharmony_ci<li><code>[in] object</code>: <code>napi_value</code> representing JavaScript <code>Object</code> whose prototype 33311cb0ef41Sopenharmony_cito return. This returns the equivalent of <code>Object.getPrototypeOf</code> (which is 33321cb0ef41Sopenharmony_cinot the same as the function's <code>prototype</code> property).</li> 33331cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing prototype of the given object.</li> 33341cb0ef41Sopenharmony_ci</ul> 33351cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 33361cb0ef41Sopenharmony_ci<h5><code>napi_get_typedarray_info</code><span><a class="mark" href="#napi_get_typedarray_info" id="napi_get_typedarray_info">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_typedarray_info"></a></h5> 33371cb0ef41Sopenharmony_ci<div class="api_metadata"> 33381cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 33391cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 33401cb0ef41Sopenharmony_ci</div> 33411cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_typedarray_info</span><span class="hljs-params">(napi_env env, 33421cb0ef41Sopenharmony_ci napi_value typedarray, 33431cb0ef41Sopenharmony_ci napi_typedarray_type* type, 33441cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* length, 33451cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** data, 33461cb0ef41Sopenharmony_ci napi_value* arraybuffer, 33471cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* byte_offset)</span></code> <button class="copy-button">copy</button></pre> 33481cb0ef41Sopenharmony_ci<ul> 33491cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 33501cb0ef41Sopenharmony_ci<li><code>[in] typedarray</code>: <code>napi_value</code> representing the <code>TypedArray</code> whose 33511cb0ef41Sopenharmony_ciproperties to query.</li> 33521cb0ef41Sopenharmony_ci<li><code>[out] type</code>: Scalar datatype of the elements within the <code>TypedArray</code>.</li> 33531cb0ef41Sopenharmony_ci<li><code>[out] length</code>: The number of elements in the <code>TypedArray</code>.</li> 33541cb0ef41Sopenharmony_ci<li><code>[out] data</code>: The data buffer underlying the <code>TypedArray</code> adjusted by 33551cb0ef41Sopenharmony_cithe <code>byte_offset</code> value so that it points to the first element in the 33561cb0ef41Sopenharmony_ci<code>TypedArray</code>. If the length of the array is <code>0</code>, this may be <code>NULL</code> or 33571cb0ef41Sopenharmony_ciany other pointer value.</li> 33581cb0ef41Sopenharmony_ci<li><code>[out] arraybuffer</code>: The <code>ArrayBuffer</code> underlying the <code>TypedArray</code>.</li> 33591cb0ef41Sopenharmony_ci<li><code>[out] byte_offset</code>: The byte offset within the underlying native array 33601cb0ef41Sopenharmony_ciat which the first element of the arrays is located. The value for the data 33611cb0ef41Sopenharmony_ciparameter has already been adjusted so that data points to the first element 33621cb0ef41Sopenharmony_ciin the array. Therefore, the first byte of the native array would be at 33631cb0ef41Sopenharmony_ci<code>data - byte_offset</code>.</li> 33641cb0ef41Sopenharmony_ci</ul> 33651cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 33661cb0ef41Sopenharmony_ci<p>This API returns various properties of a typed array.</p> 33671cb0ef41Sopenharmony_ci<p>Any of the out parameters may be <code>NULL</code> if that property is unneeded.</p> 33681cb0ef41Sopenharmony_ci<p><em>Warning</em>: Use caution while using this API since the underlying data buffer 33691cb0ef41Sopenharmony_ciis managed by the VM.</p> 33701cb0ef41Sopenharmony_ci<h5><code>napi_get_dataview_info</code><span><a class="mark" href="#napi_get_dataview_info" id="napi_get_dataview_info">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_dataview_info"></a></h5> 33711cb0ef41Sopenharmony_ci<div class="api_metadata"> 33721cb0ef41Sopenharmony_ci<span>Added in: v8.3.0</span> 33731cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 33741cb0ef41Sopenharmony_ci</div> 33751cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_dataview_info</span><span class="hljs-params">(napi_env env, 33761cb0ef41Sopenharmony_ci napi_value dataview, 33771cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* byte_length, 33781cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** data, 33791cb0ef41Sopenharmony_ci napi_value* arraybuffer, 33801cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* byte_offset)</span></code> <button class="copy-button">copy</button></pre> 33811cb0ef41Sopenharmony_ci<ul> 33821cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 33831cb0ef41Sopenharmony_ci<li><code>[in] dataview</code>: <code>napi_value</code> representing the <code>DataView</code> whose 33841cb0ef41Sopenharmony_ciproperties to query.</li> 33851cb0ef41Sopenharmony_ci<li><code>[out] byte_length</code>: Number of bytes in the <code>DataView</code>.</li> 33861cb0ef41Sopenharmony_ci<li><code>[out] data</code>: The data buffer underlying the <code>DataView</code>. 33871cb0ef41Sopenharmony_ciIf byte_length is <code>0</code>, this may be <code>NULL</code> or any other pointer value.</li> 33881cb0ef41Sopenharmony_ci<li><code>[out] arraybuffer</code>: <code>ArrayBuffer</code> underlying the <code>DataView</code>.</li> 33891cb0ef41Sopenharmony_ci<li><code>[out] byte_offset</code>: The byte offset within the data buffer from which 33901cb0ef41Sopenharmony_cito start projecting the <code>DataView</code>.</li> 33911cb0ef41Sopenharmony_ci</ul> 33921cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 33931cb0ef41Sopenharmony_ci<p>Any of the out parameters may be <code>NULL</code> if that property is unneeded.</p> 33941cb0ef41Sopenharmony_ci<p>This API returns various properties of a <code>DataView</code>.</p> 33951cb0ef41Sopenharmony_ci<h5><code>napi_get_date_value</code><span><a class="mark" href="#napi_get_date_value" id="napi_get_date_value">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_date_value"></a></h5> 33961cb0ef41Sopenharmony_ci<div class="api_metadata"> 33971cb0ef41Sopenharmony_ci<span>Added in: v11.11.0, v10.17.0</span> 33981cb0ef41Sopenharmony_ci<span>N-API version: 5</span> 33991cb0ef41Sopenharmony_ci</div> 34001cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_date_value</span><span class="hljs-params">(napi_env env, 34011cb0ef41Sopenharmony_ci napi_value value, 34021cb0ef41Sopenharmony_ci <span class="hljs-type">double</span>* result)</span></code> <button class="copy-button">copy</button></pre> 34031cb0ef41Sopenharmony_ci<ul> 34041cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 34051cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing a JavaScript <code>Date</code>.</li> 34061cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Time value as a <code>double</code> represented as milliseconds since 34071cb0ef41Sopenharmony_cimidnight at the beginning of 01 January, 1970 UTC.</li> 34081cb0ef41Sopenharmony_ci</ul> 34091cb0ef41Sopenharmony_ci<p>This API does not observe leap seconds; they are ignored, as 34101cb0ef41Sopenharmony_ciECMAScript aligns with POSIX time specification.</p> 34111cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-date <code>napi_value</code> is passed 34121cb0ef41Sopenharmony_ciin it returns <code>napi_date_expected</code>.</p> 34131cb0ef41Sopenharmony_ci<p>This API returns the C double primitive of time value for the given JavaScript 34141cb0ef41Sopenharmony_ci<code>Date</code>.</p> 34151cb0ef41Sopenharmony_ci<h5><code>napi_get_value_bool</code><span><a class="mark" href="#napi_get_value_bool" id="napi_get_value_bool">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_bool"></a></h5> 34161cb0ef41Sopenharmony_ci<div class="api_metadata"> 34171cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 34181cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 34191cb0ef41Sopenharmony_ci</div> 34201cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_bool</span><span class="hljs-params">(napi_env env, napi_value value, <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 34211cb0ef41Sopenharmony_ci<ul> 34221cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 34231cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript <code>Boolean</code>.</li> 34241cb0ef41Sopenharmony_ci<li><code>[out] result</code>: C boolean primitive equivalent of the given JavaScript 34251cb0ef41Sopenharmony_ci<code>Boolean</code>.</li> 34261cb0ef41Sopenharmony_ci</ul> 34271cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-boolean <code>napi_value</code> is 34281cb0ef41Sopenharmony_cipassed in it returns <code>napi_boolean_expected</code>.</p> 34291cb0ef41Sopenharmony_ci<p>This API returns the C boolean primitive equivalent of the given JavaScript 34301cb0ef41Sopenharmony_ci<code>Boolean</code>.</p> 34311cb0ef41Sopenharmony_ci<h5><code>napi_get_value_double</code><span><a class="mark" href="#napi_get_value_double" id="napi_get_value_double">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_double"></a></h5> 34321cb0ef41Sopenharmony_ci<div class="api_metadata"> 34331cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 34341cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 34351cb0ef41Sopenharmony_ci</div> 34361cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_double</span><span class="hljs-params">(napi_env env, 34371cb0ef41Sopenharmony_ci napi_value value, 34381cb0ef41Sopenharmony_ci <span class="hljs-type">double</span>* result)</span></code> <button class="copy-button">copy</button></pre> 34391cb0ef41Sopenharmony_ci<ul> 34401cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 34411cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript <code>number</code>.</li> 34421cb0ef41Sopenharmony_ci<li><code>[out] result</code>: C double primitive equivalent of the given JavaScript 34431cb0ef41Sopenharmony_ci<code>number</code>.</li> 34441cb0ef41Sopenharmony_ci</ul> 34451cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-number <code>napi_value</code> is passed 34461cb0ef41Sopenharmony_ciin it returns <code>napi_number_expected</code>.</p> 34471cb0ef41Sopenharmony_ci<p>This API returns the C double primitive equivalent of the given JavaScript 34481cb0ef41Sopenharmony_ci<code>number</code>.</p> 34491cb0ef41Sopenharmony_ci<h5><code>napi_get_value_bigint_int64</code><span><a class="mark" href="#napi_get_value_bigint_int64" id="napi_get_value_bigint_int64">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_bigint_int64"></a></h5> 34501cb0ef41Sopenharmony_ci<div class="api_metadata"> 34511cb0ef41Sopenharmony_ci<span>Added in: v10.7.0</span> 34521cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 34531cb0ef41Sopenharmony_ci</div> 34541cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_bigint_int64</span><span class="hljs-params">(napi_env env, 34551cb0ef41Sopenharmony_ci napi_value value, 34561cb0ef41Sopenharmony_ci <span class="hljs-type">int64_t</span>* result, 34571cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* lossless)</span>;</code> <button class="copy-button">copy</button></pre> 34581cb0ef41Sopenharmony_ci<ul> 34591cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under</li> 34601cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript <code>BigInt</code>.</li> 34611cb0ef41Sopenharmony_ci<li><code>[out] result</code>: C <code>int64_t</code> primitive equivalent of the given JavaScript 34621cb0ef41Sopenharmony_ci<code>BigInt</code>.</li> 34631cb0ef41Sopenharmony_ci<li><code>[out] lossless</code>: Indicates whether the <code>BigInt</code> value was converted 34641cb0ef41Sopenharmony_cilosslessly.</li> 34651cb0ef41Sopenharmony_ci</ul> 34661cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-<code>BigInt</code> is passed in it 34671cb0ef41Sopenharmony_cireturns <code>napi_bigint_expected</code>.</p> 34681cb0ef41Sopenharmony_ci<p>This API returns the C <code>int64_t</code> primitive equivalent of the given JavaScript 34691cb0ef41Sopenharmony_ci<code>BigInt</code>. If needed it will truncate the value, setting <code>lossless</code> to <code>false</code>.</p> 34701cb0ef41Sopenharmony_ci<h5><code>napi_get_value_bigint_uint64</code><span><a class="mark" href="#napi_get_value_bigint_uint64" id="napi_get_value_bigint_uint64">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_bigint_uint64"></a></h5> 34711cb0ef41Sopenharmony_ci<div class="api_metadata"> 34721cb0ef41Sopenharmony_ci<span>Added in: v10.7.0</span> 34731cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 34741cb0ef41Sopenharmony_ci</div> 34751cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_bigint_uint64</span><span class="hljs-params">(napi_env env, 34761cb0ef41Sopenharmony_ci napi_value value, 34771cb0ef41Sopenharmony_ci <span class="hljs-type">uint64_t</span>* result, 34781cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* lossless)</span>;</code> <button class="copy-button">copy</button></pre> 34791cb0ef41Sopenharmony_ci<ul> 34801cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 34811cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript <code>BigInt</code>.</li> 34821cb0ef41Sopenharmony_ci<li><code>[out] result</code>: C <code>uint64_t</code> primitive equivalent of the given JavaScript 34831cb0ef41Sopenharmony_ci<code>BigInt</code>.</li> 34841cb0ef41Sopenharmony_ci<li><code>[out] lossless</code>: Indicates whether the <code>BigInt</code> value was converted 34851cb0ef41Sopenharmony_cilosslessly.</li> 34861cb0ef41Sopenharmony_ci</ul> 34871cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-<code>BigInt</code> is passed in it 34881cb0ef41Sopenharmony_cireturns <code>napi_bigint_expected</code>.</p> 34891cb0ef41Sopenharmony_ci<p>This API returns the C <code>uint64_t</code> primitive equivalent of the given JavaScript 34901cb0ef41Sopenharmony_ci<code>BigInt</code>. If needed it will truncate the value, setting <code>lossless</code> to <code>false</code>.</p> 34911cb0ef41Sopenharmony_ci<h5><code>napi_get_value_bigint_words</code><span><a class="mark" href="#napi_get_value_bigint_words" id="napi_get_value_bigint_words">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_bigint_words"></a></h5> 34921cb0ef41Sopenharmony_ci<div class="api_metadata"> 34931cb0ef41Sopenharmony_ci<span>Added in: v10.7.0</span> 34941cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 34951cb0ef41Sopenharmony_ci</div> 34961cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_bigint_words</span><span class="hljs-params">(napi_env env, 34971cb0ef41Sopenharmony_ci napi_value value, 34981cb0ef41Sopenharmony_ci <span class="hljs-type">int</span>* sign_bit, 34991cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* word_count, 35001cb0ef41Sopenharmony_ci <span class="hljs-type">uint64_t</span>* words)</span>;</code> <button class="copy-button">copy</button></pre> 35011cb0ef41Sopenharmony_ci<ul> 35021cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 35031cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript <code>BigInt</code>.</li> 35041cb0ef41Sopenharmony_ci<li><code>[out] sign_bit</code>: Integer representing if the JavaScript <code>BigInt</code> is positive 35051cb0ef41Sopenharmony_cior negative.</li> 35061cb0ef41Sopenharmony_ci<li><code>[in/out] word_count</code>: Must be initialized to the length of the <code>words</code> 35071cb0ef41Sopenharmony_ciarray. Upon return, it will be set to the actual number of words that 35081cb0ef41Sopenharmony_ciwould be needed to store this <code>BigInt</code>.</li> 35091cb0ef41Sopenharmony_ci<li><code>[out] words</code>: Pointer to a pre-allocated 64-bit word array.</li> 35101cb0ef41Sopenharmony_ci</ul> 35111cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 35121cb0ef41Sopenharmony_ci<p>This API converts a single <code>BigInt</code> value into a sign bit, 64-bit little-endian 35131cb0ef41Sopenharmony_ciarray, and the number of elements in the array. <code>sign_bit</code> and <code>words</code> may be 35141cb0ef41Sopenharmony_ciboth set to <code>NULL</code>, in order to get only <code>word_count</code>.</p> 35151cb0ef41Sopenharmony_ci<h5><code>napi_get_value_external</code><span><a class="mark" href="#napi_get_value_external" id="napi_get_value_external">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_external"></a></h5> 35161cb0ef41Sopenharmony_ci<div class="api_metadata"> 35171cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 35181cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 35191cb0ef41Sopenharmony_ci</div> 35201cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_external</span><span class="hljs-params">(napi_env env, 35211cb0ef41Sopenharmony_ci napi_value value, 35221cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** result)</span></code> <button class="copy-button">copy</button></pre> 35231cb0ef41Sopenharmony_ci<ul> 35241cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 35251cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript external value.</li> 35261cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Pointer to the data wrapped by the JavaScript external value.</li> 35271cb0ef41Sopenharmony_ci</ul> 35281cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-external <code>napi_value</code> is 35291cb0ef41Sopenharmony_cipassed in it returns <code>napi_invalid_arg</code>.</p> 35301cb0ef41Sopenharmony_ci<p>This API retrieves the external data pointer that was previously passed to 35311cb0ef41Sopenharmony_ci<code>napi_create_external()</code>.</p> 35321cb0ef41Sopenharmony_ci<h5><code>napi_get_value_int32</code><span><a class="mark" href="#napi_get_value_int32" id="napi_get_value_int32">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_int32"></a></h5> 35331cb0ef41Sopenharmony_ci<div class="api_metadata"> 35341cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 35351cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 35361cb0ef41Sopenharmony_ci</div> 35371cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_int32</span><span class="hljs-params">(napi_env env, 35381cb0ef41Sopenharmony_ci napi_value value, 35391cb0ef41Sopenharmony_ci <span class="hljs-type">int32_t</span>* result)</span></code> <button class="copy-button">copy</button></pre> 35401cb0ef41Sopenharmony_ci<ul> 35411cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 35421cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript <code>number</code>.</li> 35431cb0ef41Sopenharmony_ci<li><code>[out] result</code>: C <code>int32</code> primitive equivalent of the given JavaScript 35441cb0ef41Sopenharmony_ci<code>number</code>.</li> 35451cb0ef41Sopenharmony_ci</ul> 35461cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-number <code>napi_value</code> 35471cb0ef41Sopenharmony_ciis passed in <code>napi_number_expected</code>.</p> 35481cb0ef41Sopenharmony_ci<p>This API returns the C <code>int32</code> primitive equivalent 35491cb0ef41Sopenharmony_ciof the given JavaScript <code>number</code>.</p> 35501cb0ef41Sopenharmony_ci<p>If the number exceeds the range of the 32 bit integer, then the result is 35511cb0ef41Sopenharmony_citruncated to the equivalent of the bottom 32 bits. This can result in a large 35521cb0ef41Sopenharmony_cipositive number becoming a negative number if the value is > 2<sup>31</sup> - 1.</p> 35531cb0ef41Sopenharmony_ci<p>Non-finite number values (<code>NaN</code>, <code>+Infinity</code>, or <code>-Infinity</code>) set the 35541cb0ef41Sopenharmony_ciresult to zero.</p> 35551cb0ef41Sopenharmony_ci<h5><code>napi_get_value_int64</code><span><a class="mark" href="#napi_get_value_int64" id="napi_get_value_int64">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_int64"></a></h5> 35561cb0ef41Sopenharmony_ci<div class="api_metadata"> 35571cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 35581cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 35591cb0ef41Sopenharmony_ci</div> 35601cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_int64</span><span class="hljs-params">(napi_env env, 35611cb0ef41Sopenharmony_ci napi_value value, 35621cb0ef41Sopenharmony_ci <span class="hljs-type">int64_t</span>* result)</span></code> <button class="copy-button">copy</button></pre> 35631cb0ef41Sopenharmony_ci<ul> 35641cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 35651cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript <code>number</code>.</li> 35661cb0ef41Sopenharmony_ci<li><code>[out] result</code>: C <code>int64</code> primitive equivalent of the given JavaScript 35671cb0ef41Sopenharmony_ci<code>number</code>.</li> 35681cb0ef41Sopenharmony_ci</ul> 35691cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-number <code>napi_value</code> 35701cb0ef41Sopenharmony_ciis passed in it returns <code>napi_number_expected</code>.</p> 35711cb0ef41Sopenharmony_ci<p>This API returns the C <code>int64</code> primitive equivalent of the given JavaScript 35721cb0ef41Sopenharmony_ci<code>number</code>.</p> 35731cb0ef41Sopenharmony_ci<p><code>number</code> values outside the range of <a href="https://tc39.github.io/ecma262/#sec-number.min_safe_integer"><code>Number.MIN_SAFE_INTEGER</code></a> 35741cb0ef41Sopenharmony_ci<code>-(2**53 - 1)</code> - <a href="https://tc39.github.io/ecma262/#sec-number.max_safe_integer"><code>Number.MAX_SAFE_INTEGER</code></a> <code>(2**53 - 1)</code> will lose 35751cb0ef41Sopenharmony_ciprecision.</p> 35761cb0ef41Sopenharmony_ci<p>Non-finite number values (<code>NaN</code>, <code>+Infinity</code>, or <code>-Infinity</code>) set the 35771cb0ef41Sopenharmony_ciresult to zero.</p> 35781cb0ef41Sopenharmony_ci<h5><code>napi_get_value_string_latin1</code><span><a class="mark" href="#napi_get_value_string_latin1" id="napi_get_value_string_latin1">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_string_latin1"></a></h5> 35791cb0ef41Sopenharmony_ci<div class="api_metadata"> 35801cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 35811cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 35821cb0ef41Sopenharmony_ci</div> 35831cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_string_latin1</span><span class="hljs-params">(napi_env env, 35841cb0ef41Sopenharmony_ci napi_value value, 35851cb0ef41Sopenharmony_ci <span class="hljs-type">char</span>* buf, 35861cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> bufsize, 35871cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* result)</span></code> <button class="copy-button">copy</button></pre> 35881cb0ef41Sopenharmony_ci<ul> 35891cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 35901cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript string.</li> 35911cb0ef41Sopenharmony_ci<li><code>[in] buf</code>: Buffer to write the ISO-8859-1-encoded string into. If <code>NULL</code> is 35921cb0ef41Sopenharmony_cipassed in, the length of the string in bytes and excluding the null terminator 35931cb0ef41Sopenharmony_ciis returned in <code>result</code>.</li> 35941cb0ef41Sopenharmony_ci<li><code>[in] bufsize</code>: Size of the destination buffer. When this value is 35951cb0ef41Sopenharmony_ciinsufficient, the returned string is truncated and null-terminated.</li> 35961cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Number of bytes copied into the buffer, excluding the null 35971cb0ef41Sopenharmony_citerminator.</li> 35981cb0ef41Sopenharmony_ci</ul> 35991cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-<code>string</code> <code>napi_value</code> 36001cb0ef41Sopenharmony_ciis passed in it returns <code>napi_string_expected</code>.</p> 36011cb0ef41Sopenharmony_ci<p>This API returns the ISO-8859-1-encoded string corresponding the value passed 36021cb0ef41Sopenharmony_ciin.</p> 36031cb0ef41Sopenharmony_ci<h5><code>napi_get_value_string_utf8</code><span><a class="mark" href="#napi_get_value_string_utf8" id="napi_get_value_string_utf8">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_string_utf8"></a></h5> 36041cb0ef41Sopenharmony_ci<div class="api_metadata"> 36051cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 36061cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 36071cb0ef41Sopenharmony_ci</div> 36081cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_string_utf8</span><span class="hljs-params">(napi_env env, 36091cb0ef41Sopenharmony_ci napi_value value, 36101cb0ef41Sopenharmony_ci <span class="hljs-type">char</span>* buf, 36111cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> bufsize, 36121cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* result)</span></code> <button class="copy-button">copy</button></pre> 36131cb0ef41Sopenharmony_ci<ul> 36141cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 36151cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript string.</li> 36161cb0ef41Sopenharmony_ci<li><code>[in] buf</code>: Buffer to write the UTF8-encoded string into. If <code>NULL</code> is passed 36171cb0ef41Sopenharmony_ciin, the length of the string in bytes and excluding the null terminator is 36181cb0ef41Sopenharmony_cireturned in <code>result</code>.</li> 36191cb0ef41Sopenharmony_ci<li><code>[in] bufsize</code>: Size of the destination buffer. When this value is 36201cb0ef41Sopenharmony_ciinsufficient, the returned string is truncated and null-terminated.</li> 36211cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Number of bytes copied into the buffer, excluding the null 36221cb0ef41Sopenharmony_citerminator.</li> 36231cb0ef41Sopenharmony_ci</ul> 36241cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-<code>string</code> <code>napi_value</code> 36251cb0ef41Sopenharmony_ciis passed in it returns <code>napi_string_expected</code>.</p> 36261cb0ef41Sopenharmony_ci<p>This API returns the UTF8-encoded string corresponding the value passed in.</p> 36271cb0ef41Sopenharmony_ci<h5><code>napi_get_value_string_utf16</code><span><a class="mark" href="#napi_get_value_string_utf16" id="napi_get_value_string_utf16">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_string_utf16"></a></h5> 36281cb0ef41Sopenharmony_ci<div class="api_metadata"> 36291cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 36301cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 36311cb0ef41Sopenharmony_ci</div> 36321cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_string_utf16</span><span class="hljs-params">(napi_env env, 36331cb0ef41Sopenharmony_ci napi_value value, 36341cb0ef41Sopenharmony_ci <span class="hljs-type">char16_t</span>* buf, 36351cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> bufsize, 36361cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* result)</span></code> <button class="copy-button">copy</button></pre> 36371cb0ef41Sopenharmony_ci<ul> 36381cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 36391cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript string.</li> 36401cb0ef41Sopenharmony_ci<li><code>[in] buf</code>: Buffer to write the UTF16-LE-encoded string into. If <code>NULL</code> is 36411cb0ef41Sopenharmony_cipassed in, the length of the string in 2-byte code units and excluding the 36421cb0ef41Sopenharmony_cinull terminator is returned.</li> 36431cb0ef41Sopenharmony_ci<li><code>[in] bufsize</code>: Size of the destination buffer. When this value is 36441cb0ef41Sopenharmony_ciinsufficient, the returned string is truncated and null-terminated.</li> 36451cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Number of 2-byte code units copied into the buffer, excluding 36461cb0ef41Sopenharmony_cithe null terminator.</li> 36471cb0ef41Sopenharmony_ci</ul> 36481cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-<code>string</code> <code>napi_value</code> 36491cb0ef41Sopenharmony_ciis passed in it returns <code>napi_string_expected</code>.</p> 36501cb0ef41Sopenharmony_ci<p>This API returns the UTF16-encoded string corresponding the value passed in.</p> 36511cb0ef41Sopenharmony_ci<h5><code>napi_get_value_uint32</code><span><a class="mark" href="#napi_get_value_uint32" id="napi_get_value_uint32">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_value_uint32"></a></h5> 36521cb0ef41Sopenharmony_ci<div class="api_metadata"> 36531cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 36541cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 36551cb0ef41Sopenharmony_ci</div> 36561cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_value_uint32</span><span class="hljs-params">(napi_env env, 36571cb0ef41Sopenharmony_ci napi_value value, 36581cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span>* result)</span></code> <button class="copy-button">copy</button></pre> 36591cb0ef41Sopenharmony_ci<ul> 36601cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 36611cb0ef41Sopenharmony_ci<li><code>[in] value</code>: <code>napi_value</code> representing JavaScript <code>number</code>.</li> 36621cb0ef41Sopenharmony_ci<li><code>[out] result</code>: C primitive equivalent of the given <code>napi_value</code> as a 36631cb0ef41Sopenharmony_ci<code>uint32_t</code>.</li> 36641cb0ef41Sopenharmony_ci</ul> 36651cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-number <code>napi_value</code> 36661cb0ef41Sopenharmony_ciis passed in it returns <code>napi_number_expected</code>.</p> 36671cb0ef41Sopenharmony_ci<p>This API returns the C primitive equivalent of the given <code>napi_value</code> as a 36681cb0ef41Sopenharmony_ci<code>uint32_t</code>.</p> 36691cb0ef41Sopenharmony_ci<h4>Functions to get global instances<span><a class="mark" href="#functions-to-get-global-instances" id="functions-to-get-global-instances">#</a></span><a aria-hidden="true" class="legacy" id="n_api_functions_to_get_global_instances"></a></h4> 36701cb0ef41Sopenharmony_ci<h5><code>napi_get_boolean</code><span><a class="mark" href="#napi_get_boolean" id="napi_get_boolean">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_boolean"></a></h5> 36711cb0ef41Sopenharmony_ci<div class="api_metadata"> 36721cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 36731cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 36741cb0ef41Sopenharmony_ci</div> 36751cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_boolean</span><span class="hljs-params">(napi_env env, <span class="hljs-type">bool</span> value, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 36761cb0ef41Sopenharmony_ci<ul> 36771cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 36781cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The value of the boolean to retrieve.</li> 36791cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing JavaScript <code>Boolean</code> singleton to 36801cb0ef41Sopenharmony_ciretrieve.</li> 36811cb0ef41Sopenharmony_ci</ul> 36821cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 36831cb0ef41Sopenharmony_ci<p>This API is used to return the JavaScript singleton object that is used to 36841cb0ef41Sopenharmony_cirepresent the given boolean value.</p> 36851cb0ef41Sopenharmony_ci<h5><code>napi_get_global</code><span><a class="mark" href="#napi_get_global" id="napi_get_global">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_global"></a></h5> 36861cb0ef41Sopenharmony_ci<div class="api_metadata"> 36871cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 36881cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 36891cb0ef41Sopenharmony_ci</div> 36901cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_global</span><span class="hljs-params">(napi_env env, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 36911cb0ef41Sopenharmony_ci<ul> 36921cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 36931cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing JavaScript <code>global</code> object.</li> 36941cb0ef41Sopenharmony_ci</ul> 36951cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 36961cb0ef41Sopenharmony_ci<p>This API returns the <code>global</code> object.</p> 36971cb0ef41Sopenharmony_ci<h5><code>napi_get_null</code><span><a class="mark" href="#napi_get_null" id="napi_get_null">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_null"></a></h5> 36981cb0ef41Sopenharmony_ci<div class="api_metadata"> 36991cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 37001cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 37011cb0ef41Sopenharmony_ci</div> 37021cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_null</span><span class="hljs-params">(napi_env env, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 37031cb0ef41Sopenharmony_ci<ul> 37041cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 37051cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing JavaScript <code>null</code> object.</li> 37061cb0ef41Sopenharmony_ci</ul> 37071cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 37081cb0ef41Sopenharmony_ci<p>This API returns the <code>null</code> object.</p> 37091cb0ef41Sopenharmony_ci<h5><code>napi_get_undefined</code><span><a class="mark" href="#napi_get_undefined" id="napi_get_undefined">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_undefined"></a></h5> 37101cb0ef41Sopenharmony_ci<div class="api_metadata"> 37111cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 37121cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 37131cb0ef41Sopenharmony_ci</div> 37141cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_undefined</span><span class="hljs-params">(napi_env env, napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 37151cb0ef41Sopenharmony_ci<ul> 37161cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 37171cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing JavaScript Undefined value.</li> 37181cb0ef41Sopenharmony_ci</ul> 37191cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 37201cb0ef41Sopenharmony_ci<p>This API returns the Undefined object.</p> 37211cb0ef41Sopenharmony_ci</section><section><h3>Working with JavaScript values and abstract operations<span><a class="mark" href="#working-with-javascript-values-and-abstract-operations" id="working-with-javascript-values-and-abstract-operations">#</a></span><a aria-hidden="true" class="legacy" id="n_api_working_with_javascript_values_and_abstract_operations"></a></h3> 37221cb0ef41Sopenharmony_ci<p>Node-API exposes a set of APIs to perform some abstract operations on JavaScript 37231cb0ef41Sopenharmony_civalues. Some of these operations are documented under <a href="https://tc39.github.io/ecma262/#sec-abstract-operations">Section 7</a> 37241cb0ef41Sopenharmony_ciof the <a href="https://tc39.github.io/ecma262/">ECMAScript Language Specification</a>.</p> 37251cb0ef41Sopenharmony_ci<p>These APIs support doing one of the following:</p> 37261cb0ef41Sopenharmony_ci<ol> 37271cb0ef41Sopenharmony_ci<li>Coerce JavaScript values to specific JavaScript types (such as <code>number</code> or 37281cb0ef41Sopenharmony_ci<code>string</code>).</li> 37291cb0ef41Sopenharmony_ci<li>Check the type of a JavaScript value.</li> 37301cb0ef41Sopenharmony_ci<li>Check for equality between two JavaScript values.</li> 37311cb0ef41Sopenharmony_ci</ol> 37321cb0ef41Sopenharmony_ci<h4><code>napi_coerce_to_bool</code><span><a class="mark" href="#napi_coerce_to_bool" id="napi_coerce_to_bool">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_coerce_to_bool"></a></h4> 37331cb0ef41Sopenharmony_ci<div class="api_metadata"> 37341cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 37351cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 37361cb0ef41Sopenharmony_ci</div> 37371cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_coerce_to_bool</span><span class="hljs-params">(napi_env env, 37381cb0ef41Sopenharmony_ci napi_value value, 37391cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 37401cb0ef41Sopenharmony_ci<ul> 37411cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 37421cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to coerce.</li> 37431cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the coerced JavaScript <code>Boolean</code>.</li> 37441cb0ef41Sopenharmony_ci</ul> 37451cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 37461cb0ef41Sopenharmony_ci<p>This API implements the abstract operation <code>ToBoolean()</code> as defined in 37471cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-toboolean">Section 7.1.2</a> of the ECMAScript Language Specification.</p> 37481cb0ef41Sopenharmony_ci<h4><code>napi_coerce_to_number</code><span><a class="mark" href="#napi_coerce_to_number" id="napi_coerce_to_number">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_coerce_to_number"></a></h4> 37491cb0ef41Sopenharmony_ci<div class="api_metadata"> 37501cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 37511cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 37521cb0ef41Sopenharmony_ci</div> 37531cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_coerce_to_number</span><span class="hljs-params">(napi_env env, 37541cb0ef41Sopenharmony_ci napi_value value, 37551cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 37561cb0ef41Sopenharmony_ci<ul> 37571cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 37581cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to coerce.</li> 37591cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the coerced JavaScript <code>number</code>.</li> 37601cb0ef41Sopenharmony_ci</ul> 37611cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 37621cb0ef41Sopenharmony_ci<p>This API implements the abstract operation <code>ToNumber()</code> as defined in 37631cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-tonumber">Section 7.1.3</a> of the ECMAScript Language Specification. 37641cb0ef41Sopenharmony_ciThis function potentially runs JS code if the passed-in value is an 37651cb0ef41Sopenharmony_ciobject.</p> 37661cb0ef41Sopenharmony_ci<h4><code>napi_coerce_to_object</code><span><a class="mark" href="#napi_coerce_to_object" id="napi_coerce_to_object">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_coerce_to_object"></a></h4> 37671cb0ef41Sopenharmony_ci<div class="api_metadata"> 37681cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 37691cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 37701cb0ef41Sopenharmony_ci</div> 37711cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_coerce_to_object</span><span class="hljs-params">(napi_env env, 37721cb0ef41Sopenharmony_ci napi_value value, 37731cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 37741cb0ef41Sopenharmony_ci<ul> 37751cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 37761cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to coerce.</li> 37771cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the coerced JavaScript <code>Object</code>.</li> 37781cb0ef41Sopenharmony_ci</ul> 37791cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 37801cb0ef41Sopenharmony_ci<p>This API implements the abstract operation <code>ToObject()</code> as defined in 37811cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-toobject">Section 7.1.13</a> of the ECMAScript Language Specification.</p> 37821cb0ef41Sopenharmony_ci<h4><code>napi_coerce_to_string</code><span><a class="mark" href="#napi_coerce_to_string" id="napi_coerce_to_string">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_coerce_to_string"></a></h4> 37831cb0ef41Sopenharmony_ci<div class="api_metadata"> 37841cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 37851cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 37861cb0ef41Sopenharmony_ci</div> 37871cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_coerce_to_string</span><span class="hljs-params">(napi_env env, 37881cb0ef41Sopenharmony_ci napi_value value, 37891cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 37901cb0ef41Sopenharmony_ci<ul> 37911cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 37921cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to coerce.</li> 37931cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the coerced JavaScript <code>string</code>.</li> 37941cb0ef41Sopenharmony_ci</ul> 37951cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 37961cb0ef41Sopenharmony_ci<p>This API implements the abstract operation <code>ToString()</code> as defined in 37971cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-toobject">Section 7.1.13</a> of the ECMAScript Language Specification. 37981cb0ef41Sopenharmony_ciThis function potentially runs JS code if the passed-in value is an 37991cb0ef41Sopenharmony_ciobject.</p> 38001cb0ef41Sopenharmony_ci<h4><code>napi_typeof</code><span><a class="mark" href="#napi_typeof" id="napi_typeof">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_typeof"></a></h4> 38011cb0ef41Sopenharmony_ci<div class="api_metadata"> 38021cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 38031cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 38041cb0ef41Sopenharmony_ci</div> 38051cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_typeof</span><span class="hljs-params">(napi_env env, napi_value value, napi_valuetype* result)</span></code> <button class="copy-button">copy</button></pre> 38061cb0ef41Sopenharmony_ci<ul> 38071cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 38081cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value whose type to query.</li> 38091cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The type of the JavaScript value.</li> 38101cb0ef41Sopenharmony_ci</ul> 38111cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 38121cb0ef41Sopenharmony_ci<ul> 38131cb0ef41Sopenharmony_ci<li><code>napi_invalid_arg</code> if the type of <code>value</code> is not a known ECMAScript type and 38141cb0ef41Sopenharmony_ci<code>value</code> is not an External value.</li> 38151cb0ef41Sopenharmony_ci</ul> 38161cb0ef41Sopenharmony_ci<p>This API represents behavior similar to invoking the <code>typeof</code> Operator on 38171cb0ef41Sopenharmony_cithe object as defined in <a href="https://tc39.github.io/ecma262/#sec-typeof-operator">Section 12.5.5</a> of the ECMAScript Language 38181cb0ef41Sopenharmony_ciSpecification. However, there are some differences:</p> 38191cb0ef41Sopenharmony_ci<ol> 38201cb0ef41Sopenharmony_ci<li>It has support for detecting an External value.</li> 38211cb0ef41Sopenharmony_ci<li>It detects <code>null</code> as a separate type, while ECMAScript <code>typeof</code> would detect 38221cb0ef41Sopenharmony_ci<code>object</code>.</li> 38231cb0ef41Sopenharmony_ci</ol> 38241cb0ef41Sopenharmony_ci<p>If <code>value</code> has a type that is invalid, an error is returned.</p> 38251cb0ef41Sopenharmony_ci<h4><code>napi_instanceof</code><span><a class="mark" href="#napi_instanceof" id="napi_instanceof">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_instanceof"></a></h4> 38261cb0ef41Sopenharmony_ci<div class="api_metadata"> 38271cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 38281cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 38291cb0ef41Sopenharmony_ci</div> 38301cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_instanceof</span><span class="hljs-params">(napi_env env, 38311cb0ef41Sopenharmony_ci napi_value object, 38321cb0ef41Sopenharmony_ci napi_value constructor, 38331cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 38341cb0ef41Sopenharmony_ci<ul> 38351cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 38361cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The JavaScript value to check.</li> 38371cb0ef41Sopenharmony_ci<li><code>[in] constructor</code>: The JavaScript function object of the constructor function 38381cb0ef41Sopenharmony_cito check against.</li> 38391cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Boolean that is set to true if <code>object instanceof constructor</code> 38401cb0ef41Sopenharmony_ciis true.</li> 38411cb0ef41Sopenharmony_ci</ul> 38421cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 38431cb0ef41Sopenharmony_ci<p>This API represents invoking the <code>instanceof</code> Operator on the object as 38441cb0ef41Sopenharmony_cidefined in <a href="https://tc39.github.io/ecma262/#sec-instanceofoperator">Section 12.10.4</a> of the ECMAScript Language Specification.</p> 38451cb0ef41Sopenharmony_ci<h4><code>napi_is_array</code><span><a class="mark" href="#napi_is_array" id="napi_is_array">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_array"></a></h4> 38461cb0ef41Sopenharmony_ci<div class="api_metadata"> 38471cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 38481cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 38491cb0ef41Sopenharmony_ci</div> 38501cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_array</span><span class="hljs-params">(napi_env env, napi_value value, <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 38511cb0ef41Sopenharmony_ci<ul> 38521cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 38531cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to check.</li> 38541cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the given object is an array.</li> 38551cb0ef41Sopenharmony_ci</ul> 38561cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 38571cb0ef41Sopenharmony_ci<p>This API represents invoking the <code>IsArray</code> operation on the object 38581cb0ef41Sopenharmony_cias defined in <a href="https://tc39.github.io/ecma262/#sec-isarray">Section 7.2.2</a> of the ECMAScript Language Specification.</p> 38591cb0ef41Sopenharmony_ci<h4><code>napi_is_arraybuffer</code><span><a class="mark" href="#napi_is_arraybuffer" id="napi_is_arraybuffer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_arraybuffer"></a></h4> 38601cb0ef41Sopenharmony_ci<div class="api_metadata"> 38611cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 38621cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 38631cb0ef41Sopenharmony_ci</div> 38641cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_arraybuffer</span><span class="hljs-params">(napi_env env, napi_value value, <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 38651cb0ef41Sopenharmony_ci<ul> 38661cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 38671cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to check.</li> 38681cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the given object is an <code>ArrayBuffer</code>.</li> 38691cb0ef41Sopenharmony_ci</ul> 38701cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 38711cb0ef41Sopenharmony_ci<p>This API checks if the <code>Object</code> passed in is an array buffer.</p> 38721cb0ef41Sopenharmony_ci<h4><code>napi_is_buffer</code><span><a class="mark" href="#napi_is_buffer" id="napi_is_buffer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_buffer"></a></h4> 38731cb0ef41Sopenharmony_ci<div class="api_metadata"> 38741cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 38751cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 38761cb0ef41Sopenharmony_ci</div> 38771cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_buffer</span><span class="hljs-params">(napi_env env, napi_value value, <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 38781cb0ef41Sopenharmony_ci<ul> 38791cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 38801cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to check.</li> 38811cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the given <code>napi_value</code> represents a <code>node::Buffer</code> or 38821cb0ef41Sopenharmony_ci<code>Uint8Array</code> object.</li> 38831cb0ef41Sopenharmony_ci</ul> 38841cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 38851cb0ef41Sopenharmony_ci<p>This API checks if the <code>Object</code> passed in is a buffer or Uint8Array. 38861cb0ef41Sopenharmony_ci<a href="#napi_is_typedarray"><code>napi_is_typedarray</code></a> should be preferred if the caller needs to check if the 38871cb0ef41Sopenharmony_civalue is a Uint8Array.</p> 38881cb0ef41Sopenharmony_ci<h4><code>napi_is_date</code><span><a class="mark" href="#napi_is_date" id="napi_is_date">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_date"></a></h4> 38891cb0ef41Sopenharmony_ci<div class="api_metadata"> 38901cb0ef41Sopenharmony_ci<span>Added in: v11.11.0, v10.17.0</span> 38911cb0ef41Sopenharmony_ci<span>N-API version: 5</span> 38921cb0ef41Sopenharmony_ci</div> 38931cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_date</span><span class="hljs-params">(napi_env env, napi_value value, <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 38941cb0ef41Sopenharmony_ci<ul> 38951cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 38961cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to check.</li> 38971cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the given <code>napi_value</code> represents a JavaScript <code>Date</code> 38981cb0ef41Sopenharmony_ciobject.</li> 38991cb0ef41Sopenharmony_ci</ul> 39001cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 39011cb0ef41Sopenharmony_ci<p>This API checks if the <code>Object</code> passed in is a date.</p> 39021cb0ef41Sopenharmony_ci<h4><code>napi_is_error</code><span><a class="mark" href="#napi_is_error_1" id="napi_is_error_1">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_error_1"></a></h4> 39031cb0ef41Sopenharmony_ci<div class="api_metadata"> 39041cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 39051cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 39061cb0ef41Sopenharmony_ci</div> 39071cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_error</span><span class="hljs-params">(napi_env env, napi_value value, <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 39081cb0ef41Sopenharmony_ci<ul> 39091cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 39101cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to check.</li> 39111cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the given <code>napi_value</code> represents an <code>Error</code> object.</li> 39121cb0ef41Sopenharmony_ci</ul> 39131cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 39141cb0ef41Sopenharmony_ci<p>This API checks if the <code>Object</code> passed in is an <code>Error</code>.</p> 39151cb0ef41Sopenharmony_ci<h4><code>napi_is_typedarray</code><span><a class="mark" href="#napi_is_typedarray" id="napi_is_typedarray">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_typedarray"></a></h4> 39161cb0ef41Sopenharmony_ci<div class="api_metadata"> 39171cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 39181cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 39191cb0ef41Sopenharmony_ci</div> 39201cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_typedarray</span><span class="hljs-params">(napi_env env, napi_value value, <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 39211cb0ef41Sopenharmony_ci<ul> 39221cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 39231cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to check.</li> 39241cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the given <code>napi_value</code> represents a <code>TypedArray</code>.</li> 39251cb0ef41Sopenharmony_ci</ul> 39261cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 39271cb0ef41Sopenharmony_ci<p>This API checks if the <code>Object</code> passed in is a typed array.</p> 39281cb0ef41Sopenharmony_ci<h4><code>napi_is_dataview</code><span><a class="mark" href="#napi_is_dataview" id="napi_is_dataview">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_dataview"></a></h4> 39291cb0ef41Sopenharmony_ci<div class="api_metadata"> 39301cb0ef41Sopenharmony_ci<span>Added in: v8.3.0</span> 39311cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 39321cb0ef41Sopenharmony_ci</div> 39331cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_dataview</span><span class="hljs-params">(napi_env env, napi_value value, <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 39341cb0ef41Sopenharmony_ci<ul> 39351cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 39361cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The JavaScript value to check.</li> 39371cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the given <code>napi_value</code> represents a <code>DataView</code>.</li> 39381cb0ef41Sopenharmony_ci</ul> 39391cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 39401cb0ef41Sopenharmony_ci<p>This API checks if the <code>Object</code> passed in is a <code>DataView</code>.</p> 39411cb0ef41Sopenharmony_ci<h4><code>napi_strict_equals</code><span><a class="mark" href="#napi_strict_equals" id="napi_strict_equals">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_strict_equals"></a></h4> 39421cb0ef41Sopenharmony_ci<div class="api_metadata"> 39431cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 39441cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 39451cb0ef41Sopenharmony_ci</div> 39461cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_strict_equals</span><span class="hljs-params">(napi_env env, 39471cb0ef41Sopenharmony_ci napi_value lhs, 39481cb0ef41Sopenharmony_ci napi_value rhs, 39491cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 39501cb0ef41Sopenharmony_ci<ul> 39511cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 39521cb0ef41Sopenharmony_ci<li><code>[in] lhs</code>: The JavaScript value to check.</li> 39531cb0ef41Sopenharmony_ci<li><code>[in] rhs</code>: The JavaScript value to check against.</li> 39541cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the two <code>napi_value</code> objects are equal.</li> 39551cb0ef41Sopenharmony_ci</ul> 39561cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 39571cb0ef41Sopenharmony_ci<p>This API represents the invocation of the Strict Equality algorithm as 39581cb0ef41Sopenharmony_cidefined in <a href="https://tc39.github.io/ecma262/#sec-strict-equality-comparison">Section 7.2.14</a> of the ECMAScript Language Specification.</p> 39591cb0ef41Sopenharmony_ci<h4><code>napi_detach_arraybuffer</code><span><a class="mark" href="#napi_detach_arraybuffer" id="napi_detach_arraybuffer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_detach_arraybuffer"></a></h4> 39601cb0ef41Sopenharmony_ci<div class="api_metadata"> 39611cb0ef41Sopenharmony_ci<span>Added in: v13.0.0, v12.16.0, v10.22.0</span> 39621cb0ef41Sopenharmony_ci<span>N-API version: 7</span> 39631cb0ef41Sopenharmony_ci</div> 39641cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_detach_arraybuffer</span><span class="hljs-params">(napi_env env, 39651cb0ef41Sopenharmony_ci napi_value arraybuffer)</span></code> <button class="copy-button">copy</button></pre> 39661cb0ef41Sopenharmony_ci<ul> 39671cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 39681cb0ef41Sopenharmony_ci<li><code>[in] arraybuffer</code>: The JavaScript <code>ArrayBuffer</code> to be detached.</li> 39691cb0ef41Sopenharmony_ci</ul> 39701cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded. If a non-detachable <code>ArrayBuffer</code> is 39711cb0ef41Sopenharmony_cipassed in it returns <code>napi_detachable_arraybuffer_expected</code>.</p> 39721cb0ef41Sopenharmony_ci<p>Generally, an <code>ArrayBuffer</code> is non-detachable if it has been detached before. 39731cb0ef41Sopenharmony_ciThe engine may impose additional conditions on whether an <code>ArrayBuffer</code> is 39741cb0ef41Sopenharmony_cidetachable. For example, V8 requires that the <code>ArrayBuffer</code> be external, 39751cb0ef41Sopenharmony_cithat is, created with <a href="#napi_create_external_arraybuffer"><code>napi_create_external_arraybuffer</code></a>.</p> 39761cb0ef41Sopenharmony_ci<p>This API represents the invocation of the <code>ArrayBuffer</code> detach operation as 39771cb0ef41Sopenharmony_cidefined in <a href="https://tc39.es/ecma262/#sec-detacharraybuffer">Section 24.1.1.3</a> of the ECMAScript Language Specification.</p> 39781cb0ef41Sopenharmony_ci<h4><code>napi_is_detached_arraybuffer</code><span><a class="mark" href="#napi_is_detached_arraybuffer" id="napi_is_detached_arraybuffer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_detached_arraybuffer"></a></h4> 39791cb0ef41Sopenharmony_ci<div class="api_metadata"> 39801cb0ef41Sopenharmony_ci<span>Added in: v13.3.0, v12.16.0, v10.22.0</span> 39811cb0ef41Sopenharmony_ci<span>N-API version: 7</span> 39821cb0ef41Sopenharmony_ci</div> 39831cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_detached_arraybuffer</span><span class="hljs-params">(napi_env env, 39841cb0ef41Sopenharmony_ci napi_value arraybuffer, 39851cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span></code> <button class="copy-button">copy</button></pre> 39861cb0ef41Sopenharmony_ci<ul> 39871cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 39881cb0ef41Sopenharmony_ci<li><code>[in] arraybuffer</code>: The JavaScript <code>ArrayBuffer</code> to be checked.</li> 39891cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the <code>arraybuffer</code> is detached.</li> 39901cb0ef41Sopenharmony_ci</ul> 39911cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 39921cb0ef41Sopenharmony_ci<p>The <code>ArrayBuffer</code> is considered detached if its internal data is <code>null</code>.</p> 39931cb0ef41Sopenharmony_ci<p>This API represents the invocation of the <code>ArrayBuffer</code> <code>IsDetachedBuffer</code> 39941cb0ef41Sopenharmony_cioperation as defined in <a href="https://tc39.es/ecma262/#sec-isdetachedbuffer">Section 24.1.1.2</a> of the ECMAScript Language 39951cb0ef41Sopenharmony_ciSpecification.</p> 39961cb0ef41Sopenharmony_ci</section><section><h3>Working with JavaScript properties<span><a class="mark" href="#working-with-javascript-properties" id="working-with-javascript-properties">#</a></span><a aria-hidden="true" class="legacy" id="n_api_working_with_javascript_properties"></a></h3> 39971cb0ef41Sopenharmony_ci<p>Node-API exposes a set of APIs to get and set properties on JavaScript 39981cb0ef41Sopenharmony_ciobjects. Some of these types are documented under <a href="https://tc39.github.io/ecma262/#sec-abstract-operations">Section 7</a> of the 39991cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/">ECMAScript Language Specification</a>.</p> 40001cb0ef41Sopenharmony_ci<p>Properties in JavaScript are represented as a tuple of a key and a value. 40011cb0ef41Sopenharmony_ciFundamentally, all property keys in Node-API can be represented in one of the 40021cb0ef41Sopenharmony_cifollowing forms:</p> 40031cb0ef41Sopenharmony_ci<ul> 40041cb0ef41Sopenharmony_ci<li>Named: a simple UTF8-encoded string</li> 40051cb0ef41Sopenharmony_ci<li>Integer-Indexed: an index value represented by <code>uint32_t</code></li> 40061cb0ef41Sopenharmony_ci<li>JavaScript value: these are represented in Node-API by <code>napi_value</code>. This can 40071cb0ef41Sopenharmony_cibe a <code>napi_value</code> representing a <code>string</code>, <code>number</code>, or <code>symbol</code>.</li> 40081cb0ef41Sopenharmony_ci</ul> 40091cb0ef41Sopenharmony_ci<p>Node-API values are represented by the type <code>napi_value</code>. 40101cb0ef41Sopenharmony_ciAny Node-API call that requires a JavaScript value takes in a <code>napi_value</code>. 40111cb0ef41Sopenharmony_ciHowever, it's the caller's responsibility to make sure that the 40121cb0ef41Sopenharmony_ci<code>napi_value</code> in question is of the JavaScript type expected by the API.</p> 40131cb0ef41Sopenharmony_ci<p>The APIs documented in this section provide a simple interface to 40141cb0ef41Sopenharmony_ciget and set properties on arbitrary JavaScript objects represented by 40151cb0ef41Sopenharmony_ci<code>napi_value</code>.</p> 40161cb0ef41Sopenharmony_ci<p>For instance, consider the following JavaScript code snippet:</p> 40171cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> obj = {}; 40181cb0ef41Sopenharmony_ciobj.<span class="hljs-property">myProp</span> = <span class="hljs-number">123</span>;</code> <button class="copy-button">copy</button></pre> 40191cb0ef41Sopenharmony_ci<p>The equivalent can be done using Node-API values with the following snippet:</p> 40201cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status status = napi_generic_failure; 40211cb0ef41Sopenharmony_ci 40221cb0ef41Sopenharmony_ci<span class="hljs-comment">// const obj = {}</span> 40231cb0ef41Sopenharmony_cinapi_value obj, value; 40241cb0ef41Sopenharmony_cistatus = napi_create_object(env, &obj); 40251cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status; 40261cb0ef41Sopenharmony_ci 40271cb0ef41Sopenharmony_ci<span class="hljs-comment">// Create a napi_value for 123</span> 40281cb0ef41Sopenharmony_cistatus = napi_create_int32(env, <span class="hljs-number">123</span>, &value); 40291cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status; 40301cb0ef41Sopenharmony_ci 40311cb0ef41Sopenharmony_ci<span class="hljs-comment">// obj.myProp = 123</span> 40321cb0ef41Sopenharmony_cistatus = napi_set_named_property(env, obj, <span class="hljs-string">"myProp"</span>, value); 40331cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status;</code> <button class="copy-button">copy</button></pre> 40341cb0ef41Sopenharmony_ci<p>Indexed properties can be set in a similar manner. Consider the following 40351cb0ef41Sopenharmony_ciJavaScript snippet:</p> 40361cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> arr = []; 40371cb0ef41Sopenharmony_ciarr[<span class="hljs-number">123</span>] = <span class="hljs-string">'hello'</span>;</code> <button class="copy-button">copy</button></pre> 40381cb0ef41Sopenharmony_ci<p>The equivalent can be done using Node-API values with the following snippet:</p> 40391cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status status = napi_generic_failure; 40401cb0ef41Sopenharmony_ci 40411cb0ef41Sopenharmony_ci<span class="hljs-comment">// const arr = [];</span> 40421cb0ef41Sopenharmony_cinapi_value arr, value; 40431cb0ef41Sopenharmony_cistatus = napi_create_array(env, &arr); 40441cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status; 40451cb0ef41Sopenharmony_ci 40461cb0ef41Sopenharmony_ci<span class="hljs-comment">// Create a napi_value for 'hello'</span> 40471cb0ef41Sopenharmony_cistatus = napi_create_string_utf8(env, <span class="hljs-string">"hello"</span>, NAPI_AUTO_LENGTH, &value); 40481cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status; 40491cb0ef41Sopenharmony_ci 40501cb0ef41Sopenharmony_ci<span class="hljs-comment">// arr[123] = 'hello';</span> 40511cb0ef41Sopenharmony_cistatus = napi_set_element(env, arr, <span class="hljs-number">123</span>, value); 40521cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status;</code> <button class="copy-button">copy</button></pre> 40531cb0ef41Sopenharmony_ci<p>Properties can be retrieved using the APIs described in this section. 40541cb0ef41Sopenharmony_ciConsider the following JavaScript snippet:</p> 40551cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> arr = []; 40561cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> value = arr[<span class="hljs-number">123</span>];</code> <button class="copy-button">copy</button></pre> 40571cb0ef41Sopenharmony_ci<p>The following is the approximate equivalent of the Node-API counterpart:</p> 40581cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status status = napi_generic_failure; 40591cb0ef41Sopenharmony_ci 40601cb0ef41Sopenharmony_ci<span class="hljs-comment">// const arr = []</span> 40611cb0ef41Sopenharmony_cinapi_value arr, value; 40621cb0ef41Sopenharmony_cistatus = napi_create_array(env, &arr); 40631cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status; 40641cb0ef41Sopenharmony_ci 40651cb0ef41Sopenharmony_ci<span class="hljs-comment">// const value = arr[123]</span> 40661cb0ef41Sopenharmony_cistatus = napi_get_element(env, arr, <span class="hljs-number">123</span>, &value); 40671cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status;</code> <button class="copy-button">copy</button></pre> 40681cb0ef41Sopenharmony_ci<p>Finally, multiple properties can also be defined on an object for performance 40691cb0ef41Sopenharmony_cireasons. Consider the following JavaScript:</p> 40701cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> obj = {}; 40711cb0ef41Sopenharmony_ci<span class="hljs-title class_">Object</span>.<span class="hljs-title function_">defineProperties</span>(obj, { 40721cb0ef41Sopenharmony_ci <span class="hljs-string">'foo'</span>: { <span class="hljs-attr">value</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">writable</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">configurable</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">enumerable</span>: <span class="hljs-literal">true</span> }, 40731cb0ef41Sopenharmony_ci <span class="hljs-string">'bar'</span>: { <span class="hljs-attr">value</span>: <span class="hljs-number">456</span>, <span class="hljs-attr">writable</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">configurable</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">enumerable</span>: <span class="hljs-literal">true</span> }, 40741cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 40751cb0ef41Sopenharmony_ci<p>The following is the approximate equivalent of the Node-API counterpart:</p> 40761cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status status = napi_status_generic_failure; 40771cb0ef41Sopenharmony_ci 40781cb0ef41Sopenharmony_ci<span class="hljs-comment">// const obj = {};</span> 40791cb0ef41Sopenharmony_cinapi_value obj; 40801cb0ef41Sopenharmony_cistatus = napi_create_object(env, &obj); 40811cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status; 40821cb0ef41Sopenharmony_ci 40831cb0ef41Sopenharmony_ci<span class="hljs-comment">// Create napi_values for 123 and 456</span> 40841cb0ef41Sopenharmony_cinapi_value fooValue, barValue; 40851cb0ef41Sopenharmony_cistatus = napi_create_int32(env, <span class="hljs-number">123</span>, &fooValue); 40861cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status; 40871cb0ef41Sopenharmony_cistatus = napi_create_int32(env, <span class="hljs-number">456</span>, &barValue); 40881cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status; 40891cb0ef41Sopenharmony_ci 40901cb0ef41Sopenharmony_ci<span class="hljs-comment">// Set the properties</span> 40911cb0ef41Sopenharmony_cinapi_property_descriptor descriptors[] = { 40921cb0ef41Sopenharmony_ci { <span class="hljs-string">"foo"</span>, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>, fooValue, napi_writable | napi_configurable, <span class="hljs-literal">NULL</span> }, 40931cb0ef41Sopenharmony_ci { <span class="hljs-string">"bar"</span>, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>, barValue, napi_writable | napi_configurable, <span class="hljs-literal">NULL</span> } 40941cb0ef41Sopenharmony_ci} 40951cb0ef41Sopenharmony_cistatus = napi_define_properties(env, 40961cb0ef41Sopenharmony_ci obj, 40971cb0ef41Sopenharmony_ci <span class="hljs-keyword">sizeof</span>(descriptors) / <span class="hljs-keyword">sizeof</span>(descriptors[<span class="hljs-number">0</span>]), 40981cb0ef41Sopenharmony_ci descriptors); 40991cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> status;</code> <button class="copy-button">copy</button></pre> 41001cb0ef41Sopenharmony_ci<h4>Structures<span><a class="mark" href="#structures" id="structures">#</a></span><a aria-hidden="true" class="legacy" id="n_api_structures"></a></h4> 41011cb0ef41Sopenharmony_ci<h5><code>napi_property_attributes</code><span><a class="mark" href="#napi_property_attributes" id="napi_property_attributes">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_property_attributes"></a></h5> 41021cb0ef41Sopenharmony_ci<div class="api_metadata"> 41031cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 41041cb0ef41Sopenharmony_ci<table> 41051cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 41061cb0ef41Sopenharmony_ci<tr><td>v14.12.0</td> 41071cb0ef41Sopenharmony_ci<td><p>added <code>napi_default_method</code> and <code>napi_default_property</code>.</p></td></tr> 41081cb0ef41Sopenharmony_ci</tbody></table> 41091cb0ef41Sopenharmony_ci</details> 41101cb0ef41Sopenharmony_ci</div> 41111cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> {</span> 41121cb0ef41Sopenharmony_ci napi_default = <span class="hljs-number">0</span>, 41131cb0ef41Sopenharmony_ci napi_writable = <span class="hljs-number">1</span> << <span class="hljs-number">0</span>, 41141cb0ef41Sopenharmony_ci napi_enumerable = <span class="hljs-number">1</span> << <span class="hljs-number">1</span>, 41151cb0ef41Sopenharmony_ci napi_configurable = <span class="hljs-number">1</span> << <span class="hljs-number">2</span>, 41161cb0ef41Sopenharmony_ci 41171cb0ef41Sopenharmony_ci <span class="hljs-comment">// Used with napi_define_class to distinguish static properties</span> 41181cb0ef41Sopenharmony_ci <span class="hljs-comment">// from instance properties. Ignored by napi_define_properties.</span> 41191cb0ef41Sopenharmony_ci napi_static = <span class="hljs-number">1</span> << <span class="hljs-number">10</span>, 41201cb0ef41Sopenharmony_ci 41211cb0ef41Sopenharmony_ci <span class="hljs-comment">// Default for class methods.</span> 41221cb0ef41Sopenharmony_ci napi_default_method = napi_writable | napi_configurable, 41231cb0ef41Sopenharmony_ci 41241cb0ef41Sopenharmony_ci <span class="hljs-comment">// Default for object properties, like in JS obj[prop].</span> 41251cb0ef41Sopenharmony_ci napi_default_jsproperty = napi_writable | 41261cb0ef41Sopenharmony_ci napi_enumerable | 41271cb0ef41Sopenharmony_ci napi_configurable, 41281cb0ef41Sopenharmony_ci} napi_property_attributes;</code> <button class="copy-button">copy</button></pre> 41291cb0ef41Sopenharmony_ci<p><code>napi_property_attributes</code> are flags used to control the behavior of properties 41301cb0ef41Sopenharmony_ciset on a JavaScript object. Other than <code>napi_static</code> they correspond to the 41311cb0ef41Sopenharmony_ciattributes listed in <a href="https://tc39.github.io/ecma262/#table-2">Section 6.1.7.1</a> 41321cb0ef41Sopenharmony_ciof the <a href="https://tc39.github.io/ecma262/">ECMAScript Language Specification</a>. 41331cb0ef41Sopenharmony_ciThey can be one or more of the following bitflags:</p> 41341cb0ef41Sopenharmony_ci<ul> 41351cb0ef41Sopenharmony_ci<li><code>napi_default</code>: No explicit attributes are set on the property. By default, a 41361cb0ef41Sopenharmony_ciproperty is read only, not enumerable and not configurable.</li> 41371cb0ef41Sopenharmony_ci<li><code>napi_writable</code>: The property is writable.</li> 41381cb0ef41Sopenharmony_ci<li><code>napi_enumerable</code>: The property is enumerable.</li> 41391cb0ef41Sopenharmony_ci<li><code>napi_configurable</code>: The property is configurable as defined in 41401cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#table-2">Section 6.1.7.1</a> of the <a href="https://tc39.github.io/ecma262/">ECMAScript Language Specification</a>.</li> 41411cb0ef41Sopenharmony_ci<li><code>napi_static</code>: The property will be defined as a static property on a class as 41421cb0ef41Sopenharmony_ciopposed to an instance property, which is the default. This is used only by 41431cb0ef41Sopenharmony_ci<a href="#napi_define_class"><code>napi_define_class</code></a>. It is ignored by <code>napi_define_properties</code>.</li> 41441cb0ef41Sopenharmony_ci<li><code>napi_default_method</code>: Like a method in a JS class, the property is 41451cb0ef41Sopenharmony_ciconfigurable and writeable, but not enumerable.</li> 41461cb0ef41Sopenharmony_ci<li><code>napi_default_jsproperty</code>: Like a property set via assignment in JavaScript, 41471cb0ef41Sopenharmony_cithe property is writable, enumerable, and configurable.</li> 41481cb0ef41Sopenharmony_ci</ul> 41491cb0ef41Sopenharmony_ci<h5><code>napi_property_descriptor</code><span><a class="mark" href="#napi_property_descriptor" id="napi_property_descriptor">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_property_descriptor"></a></h5> 41501cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">struct</span> {</span> 41511cb0ef41Sopenharmony_ci <span class="hljs-comment">// One of utf8name or name should be NULL.</span> 41521cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* utf8name; 41531cb0ef41Sopenharmony_ci napi_value name; 41541cb0ef41Sopenharmony_ci 41551cb0ef41Sopenharmony_ci napi_callback method; 41561cb0ef41Sopenharmony_ci napi_callback getter; 41571cb0ef41Sopenharmony_ci napi_callback setter; 41581cb0ef41Sopenharmony_ci napi_value value; 41591cb0ef41Sopenharmony_ci 41601cb0ef41Sopenharmony_ci napi_property_attributes attributes; 41611cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data; 41621cb0ef41Sopenharmony_ci} napi_property_descriptor;</code> <button class="copy-button">copy</button></pre> 41631cb0ef41Sopenharmony_ci<ul> 41641cb0ef41Sopenharmony_ci<li><code>utf8name</code>: Optional string describing the key for the property, 41651cb0ef41Sopenharmony_ciencoded as UTF8. One of <code>utf8name</code> or <code>name</code> must be provided for the 41661cb0ef41Sopenharmony_ciproperty.</li> 41671cb0ef41Sopenharmony_ci<li><code>name</code>: Optional <code>napi_value</code> that points to a JavaScript string or symbol 41681cb0ef41Sopenharmony_cito be used as the key for the property. One of <code>utf8name</code> or <code>name</code> must 41691cb0ef41Sopenharmony_cibe provided for the property.</li> 41701cb0ef41Sopenharmony_ci<li><code>value</code>: The value that's retrieved by a get access of the property if the 41711cb0ef41Sopenharmony_ciproperty is a data property. If this is passed in, set <code>getter</code>, <code>setter</code>, 41721cb0ef41Sopenharmony_ci<code>method</code> and <code>data</code> to <code>NULL</code> (since these members won't be used).</li> 41731cb0ef41Sopenharmony_ci<li><code>getter</code>: A function to call when a get access of the property is performed. 41741cb0ef41Sopenharmony_ciIf this is passed in, set <code>value</code> and <code>method</code> to <code>NULL</code> (since these members 41751cb0ef41Sopenharmony_ciwon't be used). The given function is called implicitly by the runtime when 41761cb0ef41Sopenharmony_cithe property is accessed from JavaScript code (or if a get on the property is 41771cb0ef41Sopenharmony_ciperformed using a Node-API call). <a href="#napi_callback"><code>napi_callback</code></a> provides more details.</li> 41781cb0ef41Sopenharmony_ci<li><code>setter</code>: A function to call when a set access of the property is performed. 41791cb0ef41Sopenharmony_ciIf this is passed in, set <code>value</code> and <code>method</code> to <code>NULL</code> (since these members 41801cb0ef41Sopenharmony_ciwon't be used). The given function is called implicitly by the runtime when 41811cb0ef41Sopenharmony_cithe property is set from JavaScript code (or if a set on the property is 41821cb0ef41Sopenharmony_ciperformed using a Node-API call). <a href="#napi_callback"><code>napi_callback</code></a> provides more details.</li> 41831cb0ef41Sopenharmony_ci<li><code>method</code>: Set this to make the property descriptor object's <code>value</code> 41841cb0ef41Sopenharmony_ciproperty to be a JavaScript function represented by <code>method</code>. If this is 41851cb0ef41Sopenharmony_cipassed in, set <code>value</code>, <code>getter</code> and <code>setter</code> to <code>NULL</code> (since these members 41861cb0ef41Sopenharmony_ciwon't be used). <a href="#napi_callback"><code>napi_callback</code></a> provides more details.</li> 41871cb0ef41Sopenharmony_ci<li><code>attributes</code>: The attributes associated with the particular property. See 41881cb0ef41Sopenharmony_ci<a href="#napi_property_attributes"><code>napi_property_attributes</code></a>.</li> 41891cb0ef41Sopenharmony_ci<li><code>data</code>: The callback data passed into <code>method</code>, <code>getter</code> and <code>setter</code> if this 41901cb0ef41Sopenharmony_cifunction is invoked.</li> 41911cb0ef41Sopenharmony_ci</ul> 41921cb0ef41Sopenharmony_ci<h4>Functions<span><a class="mark" href="#functions" id="functions">#</a></span><a aria-hidden="true" class="legacy" id="n_api_functions"></a></h4> 41931cb0ef41Sopenharmony_ci<h5><code>napi_get_property_names</code><span><a class="mark" href="#napi_get_property_names" id="napi_get_property_names">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_property_names"></a></h5> 41941cb0ef41Sopenharmony_ci<div class="api_metadata"> 41951cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 41961cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 41971cb0ef41Sopenharmony_ci</div> 41981cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_property_names</span><span class="hljs-params">(napi_env env, 41991cb0ef41Sopenharmony_ci napi_value object, 42001cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 42011cb0ef41Sopenharmony_ci<ul> 42021cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 42031cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object from which to retrieve the properties.</li> 42041cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing an array of JavaScript values 42051cb0ef41Sopenharmony_cithat represent the property names of the object. The API can be used to 42061cb0ef41Sopenharmony_ciiterate over <code>result</code> using <a href="#napi_get_array_length"><code>napi_get_array_length</code></a> 42071cb0ef41Sopenharmony_ciand <a href="#napi_get_element"><code>napi_get_element</code></a>.</li> 42081cb0ef41Sopenharmony_ci</ul> 42091cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 42101cb0ef41Sopenharmony_ci<p>This API returns the names of the enumerable properties of <code>object</code> as an array 42111cb0ef41Sopenharmony_ciof strings. The properties of <code>object</code> whose key is a symbol will not be 42121cb0ef41Sopenharmony_ciincluded.</p> 42131cb0ef41Sopenharmony_ci<h5><code>napi_get_all_property_names</code><span><a class="mark" href="#napi_get_all_property_names" id="napi_get_all_property_names">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_all_property_names"></a></h5> 42141cb0ef41Sopenharmony_ci<div class="api_metadata"> 42151cb0ef41Sopenharmony_ci<span>Added in: v13.7.0, v12.17.0, v10.20.0</span> 42161cb0ef41Sopenharmony_ci<span>N-API version: 6</span> 42171cb0ef41Sopenharmony_ci</div> 42181cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_get_all_property_names(napi_env env, 42191cb0ef41Sopenharmony_ci napi_value object, 42201cb0ef41Sopenharmony_ci napi_key_collection_mode key_mode, 42211cb0ef41Sopenharmony_ci napi_key_filter key_filter, 42221cb0ef41Sopenharmony_ci napi_key_conversion key_conversion, 42231cb0ef41Sopenharmony_ci napi_value* result);</code> <button class="copy-button">copy</button></pre> 42241cb0ef41Sopenharmony_ci<ul> 42251cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 42261cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object from which to retrieve the properties.</li> 42271cb0ef41Sopenharmony_ci<li><code>[in] key_mode</code>: Whether to retrieve prototype properties as well.</li> 42281cb0ef41Sopenharmony_ci<li><code>[in] key_filter</code>: Which properties to retrieve 42291cb0ef41Sopenharmony_ci(enumerable/readable/writable).</li> 42301cb0ef41Sopenharmony_ci<li><code>[in] key_conversion</code>: Whether to convert numbered property keys to strings.</li> 42311cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing an array of JavaScript values 42321cb0ef41Sopenharmony_cithat represent the property names of the object. <a href="#napi_get_array_length"><code>napi_get_array_length</code></a> 42331cb0ef41Sopenharmony_ciand <a href="#napi_get_element"><code>napi_get_element</code></a> can be used to iterate over <code>result</code>.</li> 42341cb0ef41Sopenharmony_ci</ul> 42351cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 42361cb0ef41Sopenharmony_ci<p>This API returns an array containing the names of the available properties 42371cb0ef41Sopenharmony_ciof this object.</p> 42381cb0ef41Sopenharmony_ci<h5><code>napi_set_property</code><span><a class="mark" href="#napi_set_property" id="napi_set_property">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_set_property"></a></h5> 42391cb0ef41Sopenharmony_ci<div class="api_metadata"> 42401cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 42411cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 42421cb0ef41Sopenharmony_ci</div> 42431cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_set_property</span><span class="hljs-params">(napi_env env, 42441cb0ef41Sopenharmony_ci napi_value object, 42451cb0ef41Sopenharmony_ci napi_value key, 42461cb0ef41Sopenharmony_ci napi_value value)</span>;</code> <button class="copy-button">copy</button></pre> 42471cb0ef41Sopenharmony_ci<ul> 42481cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 42491cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object on which to set the property.</li> 42501cb0ef41Sopenharmony_ci<li><code>[in] key</code>: The name of the property to set.</li> 42511cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The property value.</li> 42521cb0ef41Sopenharmony_ci</ul> 42531cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 42541cb0ef41Sopenharmony_ci<p>This API set a property on the <code>Object</code> passed in.</p> 42551cb0ef41Sopenharmony_ci<h5><code>napi_get_property</code><span><a class="mark" href="#napi_get_property" id="napi_get_property">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_property"></a></h5> 42561cb0ef41Sopenharmony_ci<div class="api_metadata"> 42571cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 42581cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 42591cb0ef41Sopenharmony_ci</div> 42601cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_property</span><span class="hljs-params">(napi_env env, 42611cb0ef41Sopenharmony_ci napi_value object, 42621cb0ef41Sopenharmony_ci napi_value key, 42631cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 42641cb0ef41Sopenharmony_ci<ul> 42651cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 42661cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object from which to retrieve the property.</li> 42671cb0ef41Sopenharmony_ci<li><code>[in] key</code>: The name of the property to retrieve.</li> 42681cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The value of the property.</li> 42691cb0ef41Sopenharmony_ci</ul> 42701cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 42711cb0ef41Sopenharmony_ci<p>This API gets the requested property from the <code>Object</code> passed in.</p> 42721cb0ef41Sopenharmony_ci<h5><code>napi_has_property</code><span><a class="mark" href="#napi_has_property" id="napi_has_property">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_has_property"></a></h5> 42731cb0ef41Sopenharmony_ci<div class="api_metadata"> 42741cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 42751cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 42761cb0ef41Sopenharmony_ci</div> 42771cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_has_property</span><span class="hljs-params">(napi_env env, 42781cb0ef41Sopenharmony_ci napi_value object, 42791cb0ef41Sopenharmony_ci napi_value key, 42801cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 42811cb0ef41Sopenharmony_ci<ul> 42821cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 42831cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object to query.</li> 42841cb0ef41Sopenharmony_ci<li><code>[in] key</code>: The name of the property whose existence to check.</li> 42851cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the property exists on the object or not.</li> 42861cb0ef41Sopenharmony_ci</ul> 42871cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 42881cb0ef41Sopenharmony_ci<p>This API checks if the <code>Object</code> passed in has the named property.</p> 42891cb0ef41Sopenharmony_ci<h5><code>napi_delete_property</code><span><a class="mark" href="#napi_delete_property" id="napi_delete_property">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_delete_property"></a></h5> 42901cb0ef41Sopenharmony_ci<div class="api_metadata"> 42911cb0ef41Sopenharmony_ci<span>Added in: v8.2.0</span> 42921cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 42931cb0ef41Sopenharmony_ci</div> 42941cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_delete_property</span><span class="hljs-params">(napi_env env, 42951cb0ef41Sopenharmony_ci napi_value object, 42961cb0ef41Sopenharmony_ci napi_value key, 42971cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 42981cb0ef41Sopenharmony_ci<ul> 42991cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 43001cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object to query.</li> 43011cb0ef41Sopenharmony_ci<li><code>[in] key</code>: The name of the property to delete.</li> 43021cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the property deletion succeeded or not. <code>result</code> can 43031cb0ef41Sopenharmony_cioptionally be ignored by passing <code>NULL</code>.</li> 43041cb0ef41Sopenharmony_ci</ul> 43051cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 43061cb0ef41Sopenharmony_ci<p>This API attempts to delete the <code>key</code> own property from <code>object</code>.</p> 43071cb0ef41Sopenharmony_ci<h5><code>napi_has_own_property</code><span><a class="mark" href="#napi_has_own_property" id="napi_has_own_property">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_has_own_property"></a></h5> 43081cb0ef41Sopenharmony_ci<div class="api_metadata"> 43091cb0ef41Sopenharmony_ci<span>Added in: v8.2.0</span> 43101cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 43111cb0ef41Sopenharmony_ci</div> 43121cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_has_own_property</span><span class="hljs-params">(napi_env env, 43131cb0ef41Sopenharmony_ci napi_value object, 43141cb0ef41Sopenharmony_ci napi_value key, 43151cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 43161cb0ef41Sopenharmony_ci<ul> 43171cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 43181cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object to query.</li> 43191cb0ef41Sopenharmony_ci<li><code>[in] key</code>: The name of the own property whose existence to check.</li> 43201cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the own property exists on the object or not.</li> 43211cb0ef41Sopenharmony_ci</ul> 43221cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 43231cb0ef41Sopenharmony_ci<p>This API checks if the <code>Object</code> passed in has the named own property. <code>key</code> must 43241cb0ef41Sopenharmony_cibe a <code>string</code> or a <code>symbol</code>, or an error will be thrown. Node-API will not 43251cb0ef41Sopenharmony_ciperform any conversion between data types.</p> 43261cb0ef41Sopenharmony_ci<h5><code>napi_set_named_property</code><span><a class="mark" href="#napi_set_named_property" id="napi_set_named_property">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_set_named_property"></a></h5> 43271cb0ef41Sopenharmony_ci<div class="api_metadata"> 43281cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 43291cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 43301cb0ef41Sopenharmony_ci</div> 43311cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_set_named_property</span><span class="hljs-params">(napi_env env, 43321cb0ef41Sopenharmony_ci napi_value object, 43331cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* utf8Name, 43341cb0ef41Sopenharmony_ci napi_value value)</span>;</code> <button class="copy-button">copy</button></pre> 43351cb0ef41Sopenharmony_ci<ul> 43361cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 43371cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object on which to set the property.</li> 43381cb0ef41Sopenharmony_ci<li><code>[in] utf8Name</code>: The name of the property to set.</li> 43391cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The property value.</li> 43401cb0ef41Sopenharmony_ci</ul> 43411cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 43421cb0ef41Sopenharmony_ci<p>This method is equivalent to calling <a href="#napi_set_property"><code>napi_set_property</code></a> with a <code>napi_value</code> 43431cb0ef41Sopenharmony_cicreated from the string passed in as <code>utf8Name</code>.</p> 43441cb0ef41Sopenharmony_ci<h5><code>napi_get_named_property</code><span><a class="mark" href="#napi_get_named_property" id="napi_get_named_property">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_named_property"></a></h5> 43451cb0ef41Sopenharmony_ci<div class="api_metadata"> 43461cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 43471cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 43481cb0ef41Sopenharmony_ci</div> 43491cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_named_property</span><span class="hljs-params">(napi_env env, 43501cb0ef41Sopenharmony_ci napi_value object, 43511cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* utf8Name, 43521cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 43531cb0ef41Sopenharmony_ci<ul> 43541cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 43551cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object from which to retrieve the property.</li> 43561cb0ef41Sopenharmony_ci<li><code>[in] utf8Name</code>: The name of the property to get.</li> 43571cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The value of the property.</li> 43581cb0ef41Sopenharmony_ci</ul> 43591cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 43601cb0ef41Sopenharmony_ci<p>This method is equivalent to calling <a href="#napi_get_property"><code>napi_get_property</code></a> with a <code>napi_value</code> 43611cb0ef41Sopenharmony_cicreated from the string passed in as <code>utf8Name</code>.</p> 43621cb0ef41Sopenharmony_ci<h5><code>napi_has_named_property</code><span><a class="mark" href="#napi_has_named_property" id="napi_has_named_property">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_has_named_property"></a></h5> 43631cb0ef41Sopenharmony_ci<div class="api_metadata"> 43641cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 43651cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 43661cb0ef41Sopenharmony_ci</div> 43671cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_has_named_property</span><span class="hljs-params">(napi_env env, 43681cb0ef41Sopenharmony_ci napi_value object, 43691cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* utf8Name, 43701cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 43711cb0ef41Sopenharmony_ci<ul> 43721cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 43731cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object to query.</li> 43741cb0ef41Sopenharmony_ci<li><code>[in] utf8Name</code>: The name of the property whose existence to check.</li> 43751cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the property exists on the object or not.</li> 43761cb0ef41Sopenharmony_ci</ul> 43771cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 43781cb0ef41Sopenharmony_ci<p>This method is equivalent to calling <a href="#napi_has_property"><code>napi_has_property</code></a> with a <code>napi_value</code> 43791cb0ef41Sopenharmony_cicreated from the string passed in as <code>utf8Name</code>.</p> 43801cb0ef41Sopenharmony_ci<h5><code>napi_set_element</code><span><a class="mark" href="#napi_set_element" id="napi_set_element">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_set_element"></a></h5> 43811cb0ef41Sopenharmony_ci<div class="api_metadata"> 43821cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 43831cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 43841cb0ef41Sopenharmony_ci</div> 43851cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_set_element</span><span class="hljs-params">(napi_env env, 43861cb0ef41Sopenharmony_ci napi_value object, 43871cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> index, 43881cb0ef41Sopenharmony_ci napi_value value)</span>;</code> <button class="copy-button">copy</button></pre> 43891cb0ef41Sopenharmony_ci<ul> 43901cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 43911cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object from which to set the properties.</li> 43921cb0ef41Sopenharmony_ci<li><code>[in] index</code>: The index of the property to set.</li> 43931cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The property value.</li> 43941cb0ef41Sopenharmony_ci</ul> 43951cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 43961cb0ef41Sopenharmony_ci<p>This API sets an element on the <code>Object</code> passed in.</p> 43971cb0ef41Sopenharmony_ci<h5><code>napi_get_element</code><span><a class="mark" href="#napi_get_element" id="napi_get_element">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_element"></a></h5> 43981cb0ef41Sopenharmony_ci<div class="api_metadata"> 43991cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 44001cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 44011cb0ef41Sopenharmony_ci</div> 44021cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_element</span><span class="hljs-params">(napi_env env, 44031cb0ef41Sopenharmony_ci napi_value object, 44041cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> index, 44051cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 44061cb0ef41Sopenharmony_ci<ul> 44071cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 44081cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object from which to retrieve the property.</li> 44091cb0ef41Sopenharmony_ci<li><code>[in] index</code>: The index of the property to get.</li> 44101cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The value of the property.</li> 44111cb0ef41Sopenharmony_ci</ul> 44121cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 44131cb0ef41Sopenharmony_ci<p>This API gets the element at the requested index.</p> 44141cb0ef41Sopenharmony_ci<h5><code>napi_has_element</code><span><a class="mark" href="#napi_has_element" id="napi_has_element">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_has_element"></a></h5> 44151cb0ef41Sopenharmony_ci<div class="api_metadata"> 44161cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 44171cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 44181cb0ef41Sopenharmony_ci</div> 44191cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_has_element</span><span class="hljs-params">(napi_env env, 44201cb0ef41Sopenharmony_ci napi_value object, 44211cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> index, 44221cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 44231cb0ef41Sopenharmony_ci<ul> 44241cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 44251cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object to query.</li> 44261cb0ef41Sopenharmony_ci<li><code>[in] index</code>: The index of the property whose existence to check.</li> 44271cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the property exists on the object or not.</li> 44281cb0ef41Sopenharmony_ci</ul> 44291cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 44301cb0ef41Sopenharmony_ci<p>This API returns if the <code>Object</code> passed in has an element at the 44311cb0ef41Sopenharmony_cirequested index.</p> 44321cb0ef41Sopenharmony_ci<h5><code>napi_delete_element</code><span><a class="mark" href="#napi_delete_element" id="napi_delete_element">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_delete_element"></a></h5> 44331cb0ef41Sopenharmony_ci<div class="api_metadata"> 44341cb0ef41Sopenharmony_ci<span>Added in: v8.2.0</span> 44351cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 44361cb0ef41Sopenharmony_ci</div> 44371cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_delete_element</span><span class="hljs-params">(napi_env env, 44381cb0ef41Sopenharmony_ci napi_value object, 44391cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> index, 44401cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 44411cb0ef41Sopenharmony_ci<ul> 44421cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 44431cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object to query.</li> 44441cb0ef41Sopenharmony_ci<li><code>[in] index</code>: The index of the property to delete.</li> 44451cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the element deletion succeeded or not. <code>result</code> can 44461cb0ef41Sopenharmony_cioptionally be ignored by passing <code>NULL</code>.</li> 44471cb0ef41Sopenharmony_ci</ul> 44481cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 44491cb0ef41Sopenharmony_ci<p>This API attempts to delete the specified <code>index</code> from <code>object</code>.</p> 44501cb0ef41Sopenharmony_ci<h5><code>napi_define_properties</code><span><a class="mark" href="#napi_define_properties" id="napi_define_properties">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_define_properties"></a></h5> 44511cb0ef41Sopenharmony_ci<div class="api_metadata"> 44521cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 44531cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 44541cb0ef41Sopenharmony_ci</div> 44551cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_define_properties</span><span class="hljs-params">(napi_env env, 44561cb0ef41Sopenharmony_ci napi_value object, 44571cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> property_count, 44581cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> napi_property_descriptor* properties)</span>;</code> <button class="copy-button">copy</button></pre> 44591cb0ef41Sopenharmony_ci<ul> 44601cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 44611cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object from which to retrieve the properties.</li> 44621cb0ef41Sopenharmony_ci<li><code>[in] property_count</code>: The number of elements in the <code>properties</code> array.</li> 44631cb0ef41Sopenharmony_ci<li><code>[in] properties</code>: The array of property descriptors.</li> 44641cb0ef41Sopenharmony_ci</ul> 44651cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 44661cb0ef41Sopenharmony_ci<p>This method allows the efficient definition of multiple properties on a given 44671cb0ef41Sopenharmony_ciobject. The properties are defined using property descriptors (see 44681cb0ef41Sopenharmony_ci<a href="#napi_property_descriptor"><code>napi_property_descriptor</code></a>). Given an array of such property descriptors, 44691cb0ef41Sopenharmony_cithis API will set the properties on the object one at a time, as defined by 44701cb0ef41Sopenharmony_ci<code>DefineOwnProperty()</code> (described in <a href="https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots-defineownproperty-p-desc">Section 9.1.6</a> of the ECMA-262 44711cb0ef41Sopenharmony_cispecification).</p> 44721cb0ef41Sopenharmony_ci<h5><code>napi_object_freeze</code><span><a class="mark" href="#napi_object_freeze" id="napi_object_freeze">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_object_freeze"></a></h5> 44731cb0ef41Sopenharmony_ci<div class="api_metadata"> 44741cb0ef41Sopenharmony_ci<span>Added in: v14.14.0, v12.20.0</span> 44751cb0ef41Sopenharmony_ci<span>N-API version: 8</span> 44761cb0ef41Sopenharmony_ci</div> 44771cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_object_freeze</span><span class="hljs-params">(napi_env env, 44781cb0ef41Sopenharmony_ci napi_value object)</span>;</code> <button class="copy-button">copy</button></pre> 44791cb0ef41Sopenharmony_ci<ul> 44801cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 44811cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object to freeze.</li> 44821cb0ef41Sopenharmony_ci</ul> 44831cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 44841cb0ef41Sopenharmony_ci<p>This method freezes a given object. This prevents new properties from 44851cb0ef41Sopenharmony_cibeing added to it, existing properties from being removed, prevents 44861cb0ef41Sopenharmony_cichanging the enumerability, configurability, or writability of existing 44871cb0ef41Sopenharmony_ciproperties, and prevents the values of existing properties from being changed. 44881cb0ef41Sopenharmony_ciIt also prevents the object's prototype from being changed. This is described 44891cb0ef41Sopenharmony_ciin <a href="https://tc39.es/ecma262/#sec-object.freeze">Section 19.1.2.6</a> of the 44901cb0ef41Sopenharmony_ciECMA-262 specification.</p> 44911cb0ef41Sopenharmony_ci<h5><code>napi_object_seal</code><span><a class="mark" href="#napi_object_seal" id="napi_object_seal">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_object_seal"></a></h5> 44921cb0ef41Sopenharmony_ci<div class="api_metadata"> 44931cb0ef41Sopenharmony_ci<span>Added in: v14.14.0, v12.20.0</span> 44941cb0ef41Sopenharmony_ci<span>N-API version: 8</span> 44951cb0ef41Sopenharmony_ci</div> 44961cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_object_seal</span><span class="hljs-params">(napi_env env, 44971cb0ef41Sopenharmony_ci napi_value object)</span>;</code> <button class="copy-button">copy</button></pre> 44981cb0ef41Sopenharmony_ci<ul> 44991cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the Node-API call is invoked under.</li> 45001cb0ef41Sopenharmony_ci<li><code>[in] object</code>: The object to seal.</li> 45011cb0ef41Sopenharmony_ci</ul> 45021cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 45031cb0ef41Sopenharmony_ci<p>This method seals a given object. This prevents new properties from being 45041cb0ef41Sopenharmony_ciadded to it, as well as marking all existing properties as non-configurable. 45051cb0ef41Sopenharmony_ciThis is described in <a href="https://tc39.es/ecma262/#sec-object.seal">Section 19.1.2.20</a> 45061cb0ef41Sopenharmony_ciof the ECMA-262 specification.</p> 45071cb0ef41Sopenharmony_ci</section><section><h3>Working with JavaScript functions<span><a class="mark" href="#working-with-javascript-functions" id="working-with-javascript-functions">#</a></span><a aria-hidden="true" class="legacy" id="n_api_working_with_javascript_functions"></a></h3> 45081cb0ef41Sopenharmony_ci<p>Node-API provides a set of APIs that allow JavaScript code to 45091cb0ef41Sopenharmony_cicall back into native code. Node-APIs that support calling back 45101cb0ef41Sopenharmony_ciinto native code take in a callback functions represented by 45111cb0ef41Sopenharmony_cithe <code>napi_callback</code> type. When the JavaScript VM calls back to 45121cb0ef41Sopenharmony_cinative code, the <code>napi_callback</code> function provided is invoked. The APIs 45131cb0ef41Sopenharmony_cidocumented in this section allow the callback function to do the 45141cb0ef41Sopenharmony_cifollowing:</p> 45151cb0ef41Sopenharmony_ci<ul> 45161cb0ef41Sopenharmony_ci<li>Get information about the context in which the callback was invoked.</li> 45171cb0ef41Sopenharmony_ci<li>Get the arguments passed into the callback.</li> 45181cb0ef41Sopenharmony_ci<li>Return a <code>napi_value</code> back from the callback.</li> 45191cb0ef41Sopenharmony_ci</ul> 45201cb0ef41Sopenharmony_ci<p>Additionally, Node-API provides a set of functions which allow calling 45211cb0ef41Sopenharmony_ciJavaScript functions from native code. One can either call a function 45221cb0ef41Sopenharmony_cilike a regular JavaScript function call, or as a constructor 45231cb0ef41Sopenharmony_cifunction.</p> 45241cb0ef41Sopenharmony_ci<p>Any non-<code>NULL</code> data which is passed to this API via the <code>data</code> field of the 45251cb0ef41Sopenharmony_ci<code>napi_property_descriptor</code> items can be associated with <code>object</code> and freed 45261cb0ef41Sopenharmony_ciwhenever <code>object</code> is garbage-collected by passing both <code>object</code> and the data to 45271cb0ef41Sopenharmony_ci<a href="#napi_add_finalizer"><code>napi_add_finalizer</code></a>.</p> 45281cb0ef41Sopenharmony_ci<h4><code>napi_call_function</code><span><a class="mark" href="#napi_call_function" id="napi_call_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_call_function"></a></h4> 45291cb0ef41Sopenharmony_ci<div class="api_metadata"> 45301cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 45311cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 45321cb0ef41Sopenharmony_ci</div> 45331cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_call_function</span><span class="hljs-params">(napi_env env, 45341cb0ef41Sopenharmony_ci napi_value recv, 45351cb0ef41Sopenharmony_ci napi_value func, 45361cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> argc, 45371cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> napi_value* argv, 45381cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 45391cb0ef41Sopenharmony_ci<ul> 45401cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 45411cb0ef41Sopenharmony_ci<li><code>[in] recv</code>: The <code>this</code> value passed to the called function.</li> 45421cb0ef41Sopenharmony_ci<li><code>[in] func</code>: <code>napi_value</code> representing the JavaScript function to be invoked.</li> 45431cb0ef41Sopenharmony_ci<li><code>[in] argc</code>: The count of elements in the <code>argv</code> array.</li> 45441cb0ef41Sopenharmony_ci<li><code>[in] argv</code>: Array of <code>napi_values</code> representing JavaScript values passed in 45451cb0ef41Sopenharmony_cias arguments to the function.</li> 45461cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the JavaScript object returned.</li> 45471cb0ef41Sopenharmony_ci</ul> 45481cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 45491cb0ef41Sopenharmony_ci<p>This method allows a JavaScript function object to be called from a native 45501cb0ef41Sopenharmony_ciadd-on. This is the primary mechanism of calling back <em>from</em> the add-on's 45511cb0ef41Sopenharmony_cinative code <em>into</em> JavaScript. For the special case of calling into JavaScript 45521cb0ef41Sopenharmony_ciafter an async operation, see <a href="#napi_make_callback"><code>napi_make_callback</code></a>.</p> 45531cb0ef41Sopenharmony_ci<p>A sample use case might look as follows. Consider the following JavaScript 45541cb0ef41Sopenharmony_cisnippet:</p> 45551cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">function</span> <span class="hljs-title function_">AddTwo</span>(<span class="hljs-params">num</span>) { 45561cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> num + <span class="hljs-number">2</span>; 45571cb0ef41Sopenharmony_ci} 45581cb0ef41Sopenharmony_ci<span class="hljs-variable language_">global</span>.<span class="hljs-property">AddTwo</span> = <span class="hljs-title class_">AddTwo</span>;</code> <button class="copy-button">copy</button></pre> 45591cb0ef41Sopenharmony_ci<p>Then, the above function can be invoked from a native add-on using the 45601cb0ef41Sopenharmony_cifollowing code:</p> 45611cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-comment">// Get the function named "AddTwo" on the global object</span> 45621cb0ef41Sopenharmony_cinapi_value global, add_two, arg; 45631cb0ef41Sopenharmony_cinapi_status status = napi_get_global(env, &global); 45641cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span>; 45651cb0ef41Sopenharmony_ci 45661cb0ef41Sopenharmony_cistatus = napi_get_named_property(env, global, <span class="hljs-string">"AddTwo"</span>, &add_two); 45671cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span>; 45681cb0ef41Sopenharmony_ci 45691cb0ef41Sopenharmony_ci<span class="hljs-comment">// const arg = 1337</span> 45701cb0ef41Sopenharmony_cistatus = napi_create_int32(env, <span class="hljs-number">1337</span>, &arg); 45711cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span>; 45721cb0ef41Sopenharmony_ci 45731cb0ef41Sopenharmony_cinapi_value* argv = &arg; 45741cb0ef41Sopenharmony_ci<span class="hljs-type">size_t</span> argc = <span class="hljs-number">1</span>; 45751cb0ef41Sopenharmony_ci 45761cb0ef41Sopenharmony_ci<span class="hljs-comment">// AddTwo(arg);</span> 45771cb0ef41Sopenharmony_cinapi_value return_val; 45781cb0ef41Sopenharmony_cistatus = napi_call_function(env, global, add_two, argc, argv, &return_val); 45791cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span>; 45801cb0ef41Sopenharmony_ci 45811cb0ef41Sopenharmony_ci<span class="hljs-comment">// Convert the result back to a native type</span> 45821cb0ef41Sopenharmony_ci<span class="hljs-type">int32_t</span> result; 45831cb0ef41Sopenharmony_cistatus = napi_get_value_int32(env, return_val, &result); 45841cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span>;</code> <button class="copy-button">copy</button></pre> 45851cb0ef41Sopenharmony_ci<h4><code>napi_create_function</code><span><a class="mark" href="#napi_create_function" id="napi_create_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_function"></a></h4> 45861cb0ef41Sopenharmony_ci<div class="api_metadata"> 45871cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 45881cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 45891cb0ef41Sopenharmony_ci</div> 45901cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_function</span><span class="hljs-params">(napi_env env, 45911cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* utf8name, 45921cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 45931cb0ef41Sopenharmony_ci napi_callback cb, 45941cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data, 45951cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 45961cb0ef41Sopenharmony_ci<ul> 45971cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 45981cb0ef41Sopenharmony_ci<li><code>[in] utf8Name</code>: Optional name of the function encoded as UTF8. This is 45991cb0ef41Sopenharmony_civisible within JavaScript as the new function object's <code>name</code> property.</li> 46001cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length of the <code>utf8name</code> in bytes, or <code>NAPI_AUTO_LENGTH</code> if 46011cb0ef41Sopenharmony_ciit is null-terminated.</li> 46021cb0ef41Sopenharmony_ci<li><code>[in] cb</code>: The native function which should be called when this function 46031cb0ef41Sopenharmony_ciobject is invoked. <a href="#napi_callback"><code>napi_callback</code></a> provides more details.</li> 46041cb0ef41Sopenharmony_ci<li><code>[in] data</code>: User-provided data context. This will be passed back into the 46051cb0ef41Sopenharmony_cifunction when invoked later.</li> 46061cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the JavaScript function object for 46071cb0ef41Sopenharmony_cithe newly created function.</li> 46081cb0ef41Sopenharmony_ci</ul> 46091cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 46101cb0ef41Sopenharmony_ci<p>This API allows an add-on author to create a function object in native code. 46111cb0ef41Sopenharmony_ciThis is the primary mechanism to allow calling <em>into</em> the add-on's native code 46121cb0ef41Sopenharmony_ci<em>from</em> JavaScript.</p> 46131cb0ef41Sopenharmony_ci<p>The newly created function is not automatically visible from script after this 46141cb0ef41Sopenharmony_cicall. Instead, a property must be explicitly set on any object that is visible 46151cb0ef41Sopenharmony_cito JavaScript, in order for the function to be accessible from script.</p> 46161cb0ef41Sopenharmony_ci<p>In order to expose a function as part of the 46171cb0ef41Sopenharmony_ciadd-on's module exports, set the newly created function on the exports 46181cb0ef41Sopenharmony_ciobject. A sample module might look as follows:</p> 46191cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_value <span class="hljs-title function_">SayHello</span><span class="hljs-params">(napi_env env, napi_callback_info info)</span> { 46201cb0ef41Sopenharmony_ci <span class="hljs-built_in">printf</span>(<span class="hljs-string">"Hello\n"</span>); 46211cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 46221cb0ef41Sopenharmony_ci} 46231cb0ef41Sopenharmony_ci 46241cb0ef41Sopenharmony_cinapi_value <span class="hljs-title function_">Init</span><span class="hljs-params">(napi_env env, napi_value exports)</span> { 46251cb0ef41Sopenharmony_ci napi_status status; 46261cb0ef41Sopenharmony_ci 46271cb0ef41Sopenharmony_ci napi_value fn; 46281cb0ef41Sopenharmony_ci status = napi_create_function(env, <span class="hljs-literal">NULL</span>, <span class="hljs-number">0</span>, SayHello, <span class="hljs-literal">NULL</span>, &fn); 46291cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 46301cb0ef41Sopenharmony_ci 46311cb0ef41Sopenharmony_ci status = napi_set_named_property(env, exports, <span class="hljs-string">"sayHello"</span>, fn); 46321cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 46331cb0ef41Sopenharmony_ci 46341cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> exports; 46351cb0ef41Sopenharmony_ci} 46361cb0ef41Sopenharmony_ci 46371cb0ef41Sopenharmony_ciNAPI_MODULE(NODE_GYP_MODULE_NAME, Init)</code> <button class="copy-button">copy</button></pre> 46381cb0ef41Sopenharmony_ci<p>Given the above code, the add-on can be used from JavaScript as follows:</p> 46391cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> myaddon = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./addon'</span>); 46401cb0ef41Sopenharmony_cimyaddon.<span class="hljs-title function_">sayHello</span>();</code> <button class="copy-button">copy</button></pre> 46411cb0ef41Sopenharmony_ci<p>The string passed to <code>require()</code> is the name of the target in <code>binding.gyp</code> 46421cb0ef41Sopenharmony_ciresponsible for creating the <code>.node</code> file.</p> 46431cb0ef41Sopenharmony_ci<p>Any non-<code>NULL</code> data which is passed to this API via the <code>data</code> parameter can 46441cb0ef41Sopenharmony_cibe associated with the resulting JavaScript function (which is returned in the 46451cb0ef41Sopenharmony_ci<code>result</code> parameter) and freed whenever the function is garbage-collected by 46461cb0ef41Sopenharmony_cipassing both the JavaScript function and the data to <a href="#napi_add_finalizer"><code>napi_add_finalizer</code></a>.</p> 46471cb0ef41Sopenharmony_ci<p>JavaScript <code>Function</code>s are described in <a href="https://tc39.github.io/ecma262/#sec-function-objects">Section 19.2</a> of the ECMAScript 46481cb0ef41Sopenharmony_ciLanguage Specification.</p> 46491cb0ef41Sopenharmony_ci<h4><code>napi_get_cb_info</code><span><a class="mark" href="#napi_get_cb_info" id="napi_get_cb_info">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_cb_info"></a></h4> 46501cb0ef41Sopenharmony_ci<div class="api_metadata"> 46511cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 46521cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 46531cb0ef41Sopenharmony_ci</div> 46541cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_cb_info</span><span class="hljs-params">(napi_env env, 46551cb0ef41Sopenharmony_ci napi_callback_info cbinfo, 46561cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span>* argc, 46571cb0ef41Sopenharmony_ci napi_value* argv, 46581cb0ef41Sopenharmony_ci napi_value* thisArg, 46591cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** data)</span></code> <button class="copy-button">copy</button></pre> 46601cb0ef41Sopenharmony_ci<ul> 46611cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 46621cb0ef41Sopenharmony_ci<li><code>[in] cbinfo</code>: The callback info passed into the callback function.</li> 46631cb0ef41Sopenharmony_ci<li><code>[in-out] argc</code>: Specifies the length of the provided <code>argv</code> array and 46641cb0ef41Sopenharmony_cireceives the actual count of arguments. <code>argc</code> can 46651cb0ef41Sopenharmony_cioptionally be ignored by passing <code>NULL</code>.</li> 46661cb0ef41Sopenharmony_ci<li><code>[out] argv</code>: C array of <code>napi_value</code>s to which the arguments will be 46671cb0ef41Sopenharmony_cicopied. If there are more arguments than the provided count, only the 46681cb0ef41Sopenharmony_cirequested number of arguments are copied. If there are fewer arguments 46691cb0ef41Sopenharmony_ciprovided than claimed, the rest of <code>argv</code> is filled with <code>napi_value</code> values 46701cb0ef41Sopenharmony_cithat represent <code>undefined</code>. <code>argv</code> can optionally be ignored by 46711cb0ef41Sopenharmony_cipassing <code>NULL</code>.</li> 46721cb0ef41Sopenharmony_ci<li><code>[out] thisArg</code>: Receives the JavaScript <code>this</code> argument for the call. 46731cb0ef41Sopenharmony_ci<code>thisArg</code> can optionally be ignored by passing <code>NULL</code>.</li> 46741cb0ef41Sopenharmony_ci<li><code>[out] data</code>: Receives the data pointer for the callback. <code>data</code> can 46751cb0ef41Sopenharmony_cioptionally be ignored by passing <code>NULL</code>.</li> 46761cb0ef41Sopenharmony_ci</ul> 46771cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 46781cb0ef41Sopenharmony_ci<p>This method is used within a callback function to retrieve details about the 46791cb0ef41Sopenharmony_cicall like the arguments and the <code>this</code> pointer from a given callback info.</p> 46801cb0ef41Sopenharmony_ci<h4><code>napi_get_new_target</code><span><a class="mark" href="#napi_get_new_target" id="napi_get_new_target">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_new_target"></a></h4> 46811cb0ef41Sopenharmony_ci<div class="api_metadata"> 46821cb0ef41Sopenharmony_ci<span>Added in: v8.6.0</span> 46831cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 46841cb0ef41Sopenharmony_ci</div> 46851cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_new_target</span><span class="hljs-params">(napi_env env, 46861cb0ef41Sopenharmony_ci napi_callback_info cbinfo, 46871cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 46881cb0ef41Sopenharmony_ci<ul> 46891cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 46901cb0ef41Sopenharmony_ci<li><code>[in] cbinfo</code>: The callback info passed into the callback function.</li> 46911cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The <code>new.target</code> of the constructor call.</li> 46921cb0ef41Sopenharmony_ci</ul> 46931cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 46941cb0ef41Sopenharmony_ci<p>This API returns the <code>new.target</code> of the constructor call. If the current 46951cb0ef41Sopenharmony_cicallback is not a constructor call, the result is <code>NULL</code>.</p> 46961cb0ef41Sopenharmony_ci<h4><code>napi_new_instance</code><span><a class="mark" href="#napi_new_instance" id="napi_new_instance">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_new_instance"></a></h4> 46971cb0ef41Sopenharmony_ci<div class="api_metadata"> 46981cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 46991cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 47001cb0ef41Sopenharmony_ci</div> 47011cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_new_instance</span><span class="hljs-params">(napi_env env, 47021cb0ef41Sopenharmony_ci napi_value cons, 47031cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> argc, 47041cb0ef41Sopenharmony_ci napi_value* argv, 47051cb0ef41Sopenharmony_ci napi_value* result)</span></code> <button class="copy-button">copy</button></pre> 47061cb0ef41Sopenharmony_ci<ul> 47071cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 47081cb0ef41Sopenharmony_ci<li><code>[in] cons</code>: <code>napi_value</code> representing the JavaScript function to be invoked 47091cb0ef41Sopenharmony_cias a constructor.</li> 47101cb0ef41Sopenharmony_ci<li><code>[in] argc</code>: The count of elements in the <code>argv</code> array.</li> 47111cb0ef41Sopenharmony_ci<li><code>[in] argv</code>: Array of JavaScript values as <code>napi_value</code> representing the 47121cb0ef41Sopenharmony_ciarguments to the constructor. If <code>argc</code> is zero this parameter may be 47131cb0ef41Sopenharmony_ciomitted by passing in <code>NULL</code>.</li> 47141cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the JavaScript object returned, 47151cb0ef41Sopenharmony_ciwhich in this case is the constructed object.</li> 47161cb0ef41Sopenharmony_ci</ul> 47171cb0ef41Sopenharmony_ci<p>This method is used to instantiate a new JavaScript value using a given 47181cb0ef41Sopenharmony_ci<code>napi_value</code> that represents the constructor for the object. For example, 47191cb0ef41Sopenharmony_ciconsider the following snippet:</p> 47201cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">function</span> <span class="hljs-title function_">MyObject</span>(<span class="hljs-params">param</span>) { 47211cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">param</span> = param; 47221cb0ef41Sopenharmony_ci} 47231cb0ef41Sopenharmony_ci 47241cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> arg = <span class="hljs-string">'hello'</span>; 47251cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> value = <span class="hljs-keyword">new</span> <span class="hljs-title class_">MyObject</span>(arg);</code> <button class="copy-button">copy</button></pre> 47261cb0ef41Sopenharmony_ci<p>The following can be approximated in Node-API using the following snippet:</p> 47271cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-comment">// Get the constructor function MyObject</span> 47281cb0ef41Sopenharmony_cinapi_value global, constructor, arg, value; 47291cb0ef41Sopenharmony_cinapi_status status = napi_get_global(env, &global); 47301cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span>; 47311cb0ef41Sopenharmony_ci 47321cb0ef41Sopenharmony_cistatus = napi_get_named_property(env, global, <span class="hljs-string">"MyObject"</span>, &constructor); 47331cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span>; 47341cb0ef41Sopenharmony_ci 47351cb0ef41Sopenharmony_ci<span class="hljs-comment">// const arg = "hello"</span> 47361cb0ef41Sopenharmony_cistatus = napi_create_string_utf8(env, <span class="hljs-string">"hello"</span>, NAPI_AUTO_LENGTH, &arg); 47371cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span>; 47381cb0ef41Sopenharmony_ci 47391cb0ef41Sopenharmony_cinapi_value* argv = &arg; 47401cb0ef41Sopenharmony_ci<span class="hljs-type">size_t</span> argc = <span class="hljs-number">1</span>; 47411cb0ef41Sopenharmony_ci 47421cb0ef41Sopenharmony_ci<span class="hljs-comment">// const value = new MyObject(arg)</span> 47431cb0ef41Sopenharmony_cistatus = napi_new_instance(env, constructor, argc, argv, &value);</code> <button class="copy-button">copy</button></pre> 47441cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 47451cb0ef41Sopenharmony_ci</section><section><h3>Object wrap<span><a class="mark" href="#object-wrap" id="object-wrap">#</a></span><a aria-hidden="true" class="legacy" id="n_api_object_wrap"></a></h3> 47461cb0ef41Sopenharmony_ci<p>Node-API offers a way to "wrap" C++ classes and instances so that the class 47471cb0ef41Sopenharmony_ciconstructor and methods can be called from JavaScript.</p> 47481cb0ef41Sopenharmony_ci<ol> 47491cb0ef41Sopenharmony_ci<li>The <a href="#napi_define_class"><code>napi_define_class</code></a> API defines a JavaScript class with constructor, 47501cb0ef41Sopenharmony_cistatic properties and methods, and instance properties and methods that 47511cb0ef41Sopenharmony_cicorrespond to the C++ class.</li> 47521cb0ef41Sopenharmony_ci<li>When JavaScript code invokes the constructor, the constructor callback 47531cb0ef41Sopenharmony_ciuses <a href="#napi_wrap"><code>napi_wrap</code></a> to wrap a new C++ instance in a JavaScript object, 47541cb0ef41Sopenharmony_cithen returns the wrapper object.</li> 47551cb0ef41Sopenharmony_ci<li>When JavaScript code invokes a method or property accessor on the class, 47561cb0ef41Sopenharmony_cithe corresponding <code>napi_callback</code> C++ function is invoked. For an instance 47571cb0ef41Sopenharmony_cicallback, <a href="#napi_unwrap"><code>napi_unwrap</code></a> obtains the C++ instance that is the target of 47581cb0ef41Sopenharmony_cithe call.</li> 47591cb0ef41Sopenharmony_ci</ol> 47601cb0ef41Sopenharmony_ci<p>For wrapped objects it may be difficult to distinguish between a function 47611cb0ef41Sopenharmony_cicalled on a class prototype and a function called on an instance of a class. 47621cb0ef41Sopenharmony_ciA common pattern used to address this problem is to save a persistent 47631cb0ef41Sopenharmony_cireference to the class constructor for later <code>instanceof</code> checks.</p> 47641cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_value MyClass_constructor = <span class="hljs-literal">NULL</span>; 47651cb0ef41Sopenharmony_cistatus = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor); 47661cb0ef41Sopenharmony_ciassert(napi_ok == status); 47671cb0ef41Sopenharmony_ci<span class="hljs-type">bool</span> is_instance = <span class="hljs-literal">false</span>; 47681cb0ef41Sopenharmony_cistatus = napi_instanceof(env, es_this, MyClass_constructor, &is_instance); 47691cb0ef41Sopenharmony_ciassert(napi_ok == status); 47701cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (is_instance) { 47711cb0ef41Sopenharmony_ci <span class="hljs-comment">// napi_unwrap() ...</span> 47721cb0ef41Sopenharmony_ci} <span class="hljs-keyword">else</span> { 47731cb0ef41Sopenharmony_ci <span class="hljs-comment">// otherwise...</span> 47741cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 47751cb0ef41Sopenharmony_ci<p>The reference must be freed once it is no longer needed.</p> 47761cb0ef41Sopenharmony_ci<p>There are occasions where <code>napi_instanceof()</code> is insufficient for ensuring that 47771cb0ef41Sopenharmony_cia JavaScript object is a wrapper for a certain native type. This is the case 47781cb0ef41Sopenharmony_ciespecially when wrapped JavaScript objects are passed back into the addon via 47791cb0ef41Sopenharmony_cistatic methods rather than as the <code>this</code> value of prototype methods. In such 47801cb0ef41Sopenharmony_cicases there is a chance that they may be unwrapped incorrectly.</p> 47811cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> myAddon = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./build/Release/my_addon.node'</span>); 47821cb0ef41Sopenharmony_ci 47831cb0ef41Sopenharmony_ci<span class="hljs-comment">// `openDatabase()` returns a JavaScript object that wraps a native database</span> 47841cb0ef41Sopenharmony_ci<span class="hljs-comment">// handle.</span> 47851cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> dbHandle = myAddon.<span class="hljs-title function_">openDatabase</span>(); 47861cb0ef41Sopenharmony_ci 47871cb0ef41Sopenharmony_ci<span class="hljs-comment">// `query()` returns a JavaScript object that wraps a native query handle.</span> 47881cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> queryHandle = myAddon.<span class="hljs-title function_">query</span>(dbHandle, <span class="hljs-string">'Gimme ALL the things!'</span>); 47891cb0ef41Sopenharmony_ci 47901cb0ef41Sopenharmony_ci<span class="hljs-comment">// There is an accidental error in the line below. The first parameter to</span> 47911cb0ef41Sopenharmony_ci<span class="hljs-comment">// `myAddon.queryHasRecords()` should be the database handle (`dbHandle`), not</span> 47921cb0ef41Sopenharmony_ci<span class="hljs-comment">// the query handle (`query`), so the correct condition for the while-loop</span> 47931cb0ef41Sopenharmony_ci<span class="hljs-comment">// should be</span> 47941cb0ef41Sopenharmony_ci<span class="hljs-comment">//</span> 47951cb0ef41Sopenharmony_ci<span class="hljs-comment">// myAddon.queryHasRecords(dbHandle, queryHandle)</span> 47961cb0ef41Sopenharmony_ci<span class="hljs-comment">//</span> 47971cb0ef41Sopenharmony_ci<span class="hljs-keyword">while</span> (myAddon.<span class="hljs-title function_">queryHasRecords</span>(queryHandle, dbHandle)) { 47981cb0ef41Sopenharmony_ci <span class="hljs-comment">// retrieve records</span> 47991cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 48001cb0ef41Sopenharmony_ci<p>In the above example <code>myAddon.queryHasRecords()</code> is a method that accepts two 48011cb0ef41Sopenharmony_ciarguments. The first is a database handle and the second is a query handle. 48021cb0ef41Sopenharmony_ciInternally, it unwraps the first argument and casts the resulting pointer to a 48031cb0ef41Sopenharmony_cinative database handle. It then unwraps the second argument and casts the 48041cb0ef41Sopenharmony_ciresulting pointer to a query handle. If the arguments are passed in the wrong 48051cb0ef41Sopenharmony_ciorder, the casts will work, however, there is a good chance that the underlying 48061cb0ef41Sopenharmony_cidatabase operation will fail, or will even cause an invalid memory access.</p> 48071cb0ef41Sopenharmony_ci<p>To ensure that the pointer retrieved from the first argument is indeed a pointer 48081cb0ef41Sopenharmony_cito a database handle and, similarly, that the pointer retrieved from the second 48091cb0ef41Sopenharmony_ciargument is indeed a pointer to a query handle, the implementation of 48101cb0ef41Sopenharmony_ci<code>queryHasRecords()</code> has to perform a type validation. Retaining the JavaScript 48111cb0ef41Sopenharmony_ciclass constructor from which the database handle was instantiated and the 48121cb0ef41Sopenharmony_ciconstructor from which the query handle was instantiated in <code>napi_ref</code>s can 48131cb0ef41Sopenharmony_cihelp, because <code>napi_instanceof()</code> can then be used to ensure that the instances 48141cb0ef41Sopenharmony_cipassed into <code>queryHashRecords()</code> are indeed of the correct type.</p> 48151cb0ef41Sopenharmony_ci<p>Unfortunately, <code>napi_instanceof()</code> does not protect against prototype 48161cb0ef41Sopenharmony_cimanipulation. For example, the prototype of the database handle instance can be 48171cb0ef41Sopenharmony_ciset to the prototype of the constructor for query handle instances. In this 48181cb0ef41Sopenharmony_cicase, the database handle instance can appear as a query handle instance, and it 48191cb0ef41Sopenharmony_ciwill pass the <code>napi_instanceof()</code> test for a query handle instance, while still 48201cb0ef41Sopenharmony_cicontaining a pointer to a database handle.</p> 48211cb0ef41Sopenharmony_ci<p>To this end, Node-API provides type-tagging capabilities.</p> 48221cb0ef41Sopenharmony_ci<p>A type tag is a 128-bit integer unique to the addon. Node-API provides the 48231cb0ef41Sopenharmony_ci<code>napi_type_tag</code> structure for storing a type tag. When such a value is passed 48241cb0ef41Sopenharmony_cialong with a JavaScript object or <a href="#napi_create_external">external</a> stored in a <code>napi_value</code> to 48251cb0ef41Sopenharmony_ci<code>napi_type_tag_object()</code>, the JavaScript object will be "marked" with the 48261cb0ef41Sopenharmony_citype tag. The "mark" is invisible on the JavaScript side. When a JavaScript 48271cb0ef41Sopenharmony_ciobject arrives into a native binding, <code>napi_check_object_type_tag()</code> can be used 48281cb0ef41Sopenharmony_cialong with the original type tag to determine whether the JavaScript object was 48291cb0ef41Sopenharmony_cipreviously "marked" with the type tag. This creates a type-checking capability 48301cb0ef41Sopenharmony_ciof a higher fidelity than <code>napi_instanceof()</code> can provide, because such type- 48311cb0ef41Sopenharmony_citagging survives prototype manipulation and addon unloading/reloading.</p> 48321cb0ef41Sopenharmony_ci<p>Continuing the above example, the following skeleton addon implementation 48331cb0ef41Sopenharmony_ciillustrates the use of <code>napi_type_tag_object()</code> and 48341cb0ef41Sopenharmony_ci<code>napi_check_object_type_tag()</code>.</p> 48351cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-comment">// This value is the type tag for a database handle. The command</span> 48361cb0ef41Sopenharmony_ci<span class="hljs-comment">//</span> 48371cb0ef41Sopenharmony_ci<span class="hljs-comment">// uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'</span> 48381cb0ef41Sopenharmony_ci<span class="hljs-comment">//</span> 48391cb0ef41Sopenharmony_ci<span class="hljs-comment">// can be used to obtain the two values with which to initialize the structure.</span> 48401cb0ef41Sopenharmony_ci<span class="hljs-type">static</span> <span class="hljs-type">const</span> napi_type_tag DatabaseHandleTypeTag = { 48411cb0ef41Sopenharmony_ci <span class="hljs-number">0x1edf75a38336451d</span>, <span class="hljs-number">0xa5ed9ce2e4c00c38</span> 48421cb0ef41Sopenharmony_ci}; 48431cb0ef41Sopenharmony_ci 48441cb0ef41Sopenharmony_ci<span class="hljs-comment">// This value is the type tag for a query handle.</span> 48451cb0ef41Sopenharmony_ci<span class="hljs-type">static</span> <span class="hljs-type">const</span> napi_type_tag QueryHandleTypeTag = { 48461cb0ef41Sopenharmony_ci <span class="hljs-number">0x9c73317f9fad44a3</span>, <span class="hljs-number">0x93c3920bf3b0ad6a</span> 48471cb0ef41Sopenharmony_ci}; 48481cb0ef41Sopenharmony_ci 48491cb0ef41Sopenharmony_ci<span class="hljs-type">static</span> napi_value 48501cb0ef41Sopenharmony_ci<span class="hljs-title function_">openDatabase</span><span class="hljs-params">(napi_env env, napi_callback_info info)</span> { 48511cb0ef41Sopenharmony_ci napi_status status; 48521cb0ef41Sopenharmony_ci napi_value result; 48531cb0ef41Sopenharmony_ci 48541cb0ef41Sopenharmony_ci <span class="hljs-comment">// Perform the underlying action which results in a database handle.</span> 48551cb0ef41Sopenharmony_ci DatabaseHandle* dbHandle = open_database(); 48561cb0ef41Sopenharmony_ci 48571cb0ef41Sopenharmony_ci <span class="hljs-comment">// Create a new, empty JS object.</span> 48581cb0ef41Sopenharmony_ci status = napi_create_object(env, &result); 48591cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 48601cb0ef41Sopenharmony_ci 48611cb0ef41Sopenharmony_ci <span class="hljs-comment">// Tag the object to indicate that it holds a pointer to a `DatabaseHandle`.</span> 48621cb0ef41Sopenharmony_ci status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag); 48631cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 48641cb0ef41Sopenharmony_ci 48651cb0ef41Sopenharmony_ci <span class="hljs-comment">// Store the pointer to the `DatabaseHandle` structure inside the JS object.</span> 48661cb0ef41Sopenharmony_ci status = napi_wrap(env, result, dbHandle, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>); 48671cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 48681cb0ef41Sopenharmony_ci 48691cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> result; 48701cb0ef41Sopenharmony_ci} 48711cb0ef41Sopenharmony_ci 48721cb0ef41Sopenharmony_ci<span class="hljs-comment">// Later when we receive a JavaScript object purporting to be a database handle</span> 48731cb0ef41Sopenharmony_ci<span class="hljs-comment">// we can use `napi_check_object_type_tag()` to ensure that it is indeed such a</span> 48741cb0ef41Sopenharmony_ci<span class="hljs-comment">// handle.</span> 48751cb0ef41Sopenharmony_ci 48761cb0ef41Sopenharmony_ci<span class="hljs-type">static</span> napi_value 48771cb0ef41Sopenharmony_ci<span class="hljs-title function_">query</span><span class="hljs-params">(napi_env env, napi_callback_info info)</span> { 48781cb0ef41Sopenharmony_ci napi_status status; 48791cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> argc = <span class="hljs-number">2</span>; 48801cb0ef41Sopenharmony_ci napi_value argv[<span class="hljs-number">2</span>]; 48811cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span> is_db_handle; 48821cb0ef41Sopenharmony_ci 48831cb0ef41Sopenharmony_ci status = napi_get_cb_info(env, info, &argc, argv, <span class="hljs-literal">NULL</span>, <span class="hljs-literal">NULL</span>); 48841cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 48851cb0ef41Sopenharmony_ci 48861cb0ef41Sopenharmony_ci <span class="hljs-comment">// Check that the object passed as the first parameter has the previously</span> 48871cb0ef41Sopenharmony_ci <span class="hljs-comment">// applied tag.</span> 48881cb0ef41Sopenharmony_ci status = napi_check_object_type_tag(env, 48891cb0ef41Sopenharmony_ci argv[<span class="hljs-number">0</span>], 48901cb0ef41Sopenharmony_ci &DatabaseHandleTypeTag, 48911cb0ef41Sopenharmony_ci &is_db_handle); 48921cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 48931cb0ef41Sopenharmony_ci 48941cb0ef41Sopenharmony_ci <span class="hljs-comment">// Throw a `TypeError` if it doesn't.</span> 48951cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (!is_db_handle) { 48961cb0ef41Sopenharmony_ci <span class="hljs-comment">// Throw a TypeError.</span> 48971cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 48981cb0ef41Sopenharmony_ci } 48991cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 49001cb0ef41Sopenharmony_ci<h4><code>napi_define_class</code><span><a class="mark" href="#napi_define_class" id="napi_define_class">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_define_class"></a></h4> 49011cb0ef41Sopenharmony_ci<div class="api_metadata"> 49021cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 49031cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 49041cb0ef41Sopenharmony_ci</div> 49051cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_define_class</span><span class="hljs-params">(napi_env env, 49061cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* utf8name, 49071cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> length, 49081cb0ef41Sopenharmony_ci napi_callback constructor, 49091cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data, 49101cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> property_count, 49111cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> napi_property_descriptor* properties, 49121cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 49131cb0ef41Sopenharmony_ci<ul> 49141cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 49151cb0ef41Sopenharmony_ci<li><code>[in] utf8name</code>: Name of the JavaScript constructor function. For clarity, 49161cb0ef41Sopenharmony_ciit is recommended to use the C++ class name when wrapping a C++ class.</li> 49171cb0ef41Sopenharmony_ci<li><code>[in] length</code>: The length of the <code>utf8name</code> in bytes, or <code>NAPI_AUTO_LENGTH</code> 49181cb0ef41Sopenharmony_ciif it is null-terminated.</li> 49191cb0ef41Sopenharmony_ci<li><code>[in] constructor</code>: Callback function that handles constructing instances 49201cb0ef41Sopenharmony_ciof the class. When wrapping a C++ class, this method must be a static member 49211cb0ef41Sopenharmony_ciwith the <a href="#napi_callback"><code>napi_callback</code></a> signature. A C++ class constructor cannot be 49221cb0ef41Sopenharmony_ciused. <a href="#napi_callback"><code>napi_callback</code></a> provides more details.</li> 49231cb0ef41Sopenharmony_ci<li><code>[in] data</code>: Optional data to be passed to the constructor callback as 49241cb0ef41Sopenharmony_cithe <code>data</code> property of the callback info.</li> 49251cb0ef41Sopenharmony_ci<li><code>[in] property_count</code>: Number of items in the <code>properties</code> array argument.</li> 49261cb0ef41Sopenharmony_ci<li><code>[in] properties</code>: Array of property descriptors describing static and 49271cb0ef41Sopenharmony_ciinstance data properties, accessors, and methods on the class 49281cb0ef41Sopenharmony_ciSee <code>napi_property_descriptor</code>.</li> 49291cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A <code>napi_value</code> representing the constructor function for 49301cb0ef41Sopenharmony_cithe class.</li> 49311cb0ef41Sopenharmony_ci</ul> 49321cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 49331cb0ef41Sopenharmony_ci<p>Defines a JavaScript class, including:</p> 49341cb0ef41Sopenharmony_ci<ul> 49351cb0ef41Sopenharmony_ci<li>A JavaScript constructor function that has the class name. When wrapping a 49361cb0ef41Sopenharmony_cicorresponding C++ class, the callback passed via <code>constructor</code> can be used to 49371cb0ef41Sopenharmony_ciinstantiate a new C++ class instance, which can then be placed inside the 49381cb0ef41Sopenharmony_ciJavaScript object instance being constructed using <a href="#napi_wrap"><code>napi_wrap</code></a>.</li> 49391cb0ef41Sopenharmony_ci<li>Properties on the constructor function whose implementation can call 49401cb0ef41Sopenharmony_cicorresponding <em>static</em> data properties, accessors, and methods of the C++ 49411cb0ef41Sopenharmony_ciclass (defined by property descriptors with the <code>napi_static</code> attribute).</li> 49421cb0ef41Sopenharmony_ci<li>Properties on the constructor function's <code>prototype</code> object. When wrapping a 49431cb0ef41Sopenharmony_ciC++ class, <em>non-static</em> data properties, accessors, and methods of the C++ 49441cb0ef41Sopenharmony_ciclass can be called from the static functions given in the property 49451cb0ef41Sopenharmony_cidescriptors without the <code>napi_static</code> attribute after retrieving the C++ class 49461cb0ef41Sopenharmony_ciinstance placed inside the JavaScript object instance by using 49471cb0ef41Sopenharmony_ci<a href="#napi_unwrap"><code>napi_unwrap</code></a>.</li> 49481cb0ef41Sopenharmony_ci</ul> 49491cb0ef41Sopenharmony_ci<p>When wrapping a C++ class, the C++ constructor callback passed via <code>constructor</code> 49501cb0ef41Sopenharmony_cishould be a static method on the class that calls the actual class constructor, 49511cb0ef41Sopenharmony_cithen wraps the new C++ instance in a JavaScript object, and returns the wrapper 49521cb0ef41Sopenharmony_ciobject. See <a href="#napi_wrap"><code>napi_wrap</code></a> for details.</p> 49531cb0ef41Sopenharmony_ci<p>The JavaScript constructor function returned from <a href="#napi_define_class"><code>napi_define_class</code></a> is 49541cb0ef41Sopenharmony_cioften saved and used later to construct new instances of the class from native 49551cb0ef41Sopenharmony_cicode, and/or to check whether provided values are instances of the class. In 49561cb0ef41Sopenharmony_cithat case, to prevent the function value from being garbage-collected, a 49571cb0ef41Sopenharmony_cistrong persistent reference to it can be created using 49581cb0ef41Sopenharmony_ci<a href="#napi_create_reference"><code>napi_create_reference</code></a>, ensuring that the reference count is kept >= 1.</p> 49591cb0ef41Sopenharmony_ci<p>Any non-<code>NULL</code> data which is passed to this API via the <code>data</code> parameter or via 49601cb0ef41Sopenharmony_cithe <code>data</code> field of the <code>napi_property_descriptor</code> array items can be associated 49611cb0ef41Sopenharmony_ciwith the resulting JavaScript constructor (which is returned in the <code>result</code> 49621cb0ef41Sopenharmony_ciparameter) and freed whenever the class is garbage-collected by passing both 49631cb0ef41Sopenharmony_cithe JavaScript function and the data to <a href="#napi_add_finalizer"><code>napi_add_finalizer</code></a>.</p> 49641cb0ef41Sopenharmony_ci<h4><code>napi_wrap</code><span><a class="mark" href="#napi_wrap" id="napi_wrap">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_wrap"></a></h4> 49651cb0ef41Sopenharmony_ci<div class="api_metadata"> 49661cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 49671cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 49681cb0ef41Sopenharmony_ci</div> 49691cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_wrap</span><span class="hljs-params">(napi_env env, 49701cb0ef41Sopenharmony_ci napi_value js_object, 49711cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* native_object, 49721cb0ef41Sopenharmony_ci napi_finalize finalize_cb, 49731cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint, 49741cb0ef41Sopenharmony_ci napi_ref* result)</span>;</code> <button class="copy-button">copy</button></pre> 49751cb0ef41Sopenharmony_ci<ul> 49761cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 49771cb0ef41Sopenharmony_ci<li><code>[in] js_object</code>: The JavaScript object that will be the wrapper for the 49781cb0ef41Sopenharmony_cinative object.</li> 49791cb0ef41Sopenharmony_ci<li><code>[in] native_object</code>: The native instance that will be wrapped in the 49801cb0ef41Sopenharmony_ciJavaScript object.</li> 49811cb0ef41Sopenharmony_ci<li><code>[in] finalize_cb</code>: Optional native callback that can be used to free the 49821cb0ef41Sopenharmony_cinative instance when the JavaScript object has been garbage-collected. 49831cb0ef41Sopenharmony_ci<a href="#napi_finalize"><code>napi_finalize</code></a> provides more details.</li> 49841cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional contextual hint that is passed to the 49851cb0ef41Sopenharmony_cifinalize callback.</li> 49861cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Optional reference to the wrapped object.</li> 49871cb0ef41Sopenharmony_ci</ul> 49881cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 49891cb0ef41Sopenharmony_ci<p>Wraps a native instance in a JavaScript object. The native instance can be 49901cb0ef41Sopenharmony_ciretrieved later using <code>napi_unwrap()</code>.</p> 49911cb0ef41Sopenharmony_ci<p>When JavaScript code invokes a constructor for a class that was defined using 49921cb0ef41Sopenharmony_ci<code>napi_define_class()</code>, the <code>napi_callback</code> for the constructor is invoked. 49931cb0ef41Sopenharmony_ciAfter constructing an instance of the native class, the callback must then call 49941cb0ef41Sopenharmony_ci<code>napi_wrap()</code> to wrap the newly constructed instance in the already-created 49951cb0ef41Sopenharmony_ciJavaScript object that is the <code>this</code> argument to the constructor callback. 49961cb0ef41Sopenharmony_ci(That <code>this</code> object was created from the constructor function's <code>prototype</code>, 49971cb0ef41Sopenharmony_ciso it already has definitions of all the instance properties and methods.)</p> 49981cb0ef41Sopenharmony_ci<p>Typically when wrapping a class instance, a finalize callback should be 49991cb0ef41Sopenharmony_ciprovided that simply deletes the native instance that is received as the <code>data</code> 50001cb0ef41Sopenharmony_ciargument to the finalize callback.</p> 50011cb0ef41Sopenharmony_ci<p>The optional returned reference is initially a weak reference, meaning it 50021cb0ef41Sopenharmony_cihas a reference count of 0. Typically this reference count would be incremented 50031cb0ef41Sopenharmony_citemporarily during async operations that require the instance to remain valid.</p> 50041cb0ef41Sopenharmony_ci<p><em>Caution</em>: The optional returned reference (if obtained) should be deleted via 50051cb0ef41Sopenharmony_ci<a href="#napi_delete_reference"><code>napi_delete_reference</code></a> ONLY in response to the finalize callback 50061cb0ef41Sopenharmony_ciinvocation. If it is deleted before then, then the finalize callback may never 50071cb0ef41Sopenharmony_cibe invoked. Therefore, when obtaining a reference a finalize callback is also 50081cb0ef41Sopenharmony_cirequired in order to enable correct disposal of the reference.</p> 50091cb0ef41Sopenharmony_ci<p>Finalizer callbacks may be deferred, leaving a window where the object has 50101cb0ef41Sopenharmony_cibeen garbage collected (and the weak reference is invalid) but the finalizer 50111cb0ef41Sopenharmony_cihasn't been called yet. When using <code>napi_get_reference_value()</code> on weak 50121cb0ef41Sopenharmony_cireferences returned by <code>napi_wrap()</code>, you should still handle an empty result.</p> 50131cb0ef41Sopenharmony_ci<p>Calling <code>napi_wrap()</code> a second time on an object will return an error. To 50141cb0ef41Sopenharmony_ciassociate another native instance with the object, use <code>napi_remove_wrap()</code> 50151cb0ef41Sopenharmony_cifirst.</p> 50161cb0ef41Sopenharmony_ci<h4><code>napi_unwrap</code><span><a class="mark" href="#napi_unwrap" id="napi_unwrap">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_unwrap"></a></h4> 50171cb0ef41Sopenharmony_ci<div class="api_metadata"> 50181cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 50191cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 50201cb0ef41Sopenharmony_ci</div> 50211cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_unwrap</span><span class="hljs-params">(napi_env env, 50221cb0ef41Sopenharmony_ci napi_value js_object, 50231cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** result)</span>;</code> <button class="copy-button">copy</button></pre> 50241cb0ef41Sopenharmony_ci<ul> 50251cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 50261cb0ef41Sopenharmony_ci<li><code>[in] js_object</code>: The object associated with the native instance.</li> 50271cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Pointer to the wrapped native instance.</li> 50281cb0ef41Sopenharmony_ci</ul> 50291cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 50301cb0ef41Sopenharmony_ci<p>Retrieves a native instance that was previously wrapped in a JavaScript 50311cb0ef41Sopenharmony_ciobject using <code>napi_wrap()</code>.</p> 50321cb0ef41Sopenharmony_ci<p>When JavaScript code invokes a method or property accessor on the class, the 50331cb0ef41Sopenharmony_cicorresponding <code>napi_callback</code> is invoked. If the callback is for an instance 50341cb0ef41Sopenharmony_cimethod or accessor, then the <code>this</code> argument to the callback is the wrapper 50351cb0ef41Sopenharmony_ciobject; the wrapped C++ instance that is the target of the call can be obtained 50361cb0ef41Sopenharmony_cithen by calling <code>napi_unwrap()</code> on the wrapper object.</p> 50371cb0ef41Sopenharmony_ci<h4><code>napi_remove_wrap</code><span><a class="mark" href="#napi_remove_wrap" id="napi_remove_wrap">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_remove_wrap"></a></h4> 50381cb0ef41Sopenharmony_ci<div class="api_metadata"> 50391cb0ef41Sopenharmony_ci<span>Added in: v8.5.0</span> 50401cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 50411cb0ef41Sopenharmony_ci</div> 50421cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_remove_wrap</span><span class="hljs-params">(napi_env env, 50431cb0ef41Sopenharmony_ci napi_value js_object, 50441cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** result)</span>;</code> <button class="copy-button">copy</button></pre> 50451cb0ef41Sopenharmony_ci<ul> 50461cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 50471cb0ef41Sopenharmony_ci<li><code>[in] js_object</code>: The object associated with the native instance.</li> 50481cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Pointer to the wrapped native instance.</li> 50491cb0ef41Sopenharmony_ci</ul> 50501cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 50511cb0ef41Sopenharmony_ci<p>Retrieves a native instance that was previously wrapped in the JavaScript 50521cb0ef41Sopenharmony_ciobject <code>js_object</code> using <code>napi_wrap()</code> and removes the wrapping. If a finalize 50531cb0ef41Sopenharmony_cicallback was associated with the wrapping, it will no longer be called when the 50541cb0ef41Sopenharmony_ciJavaScript object becomes garbage-collected.</p> 50551cb0ef41Sopenharmony_ci<h4><code>napi_type_tag_object</code><span><a class="mark" href="#napi_type_tag_object" id="napi_type_tag_object">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_type_tag_object"></a></h4> 50561cb0ef41Sopenharmony_ci<div class="api_metadata"> 50571cb0ef41Sopenharmony_ci<span>Added in: v14.8.0, v12.19.0</span> 50581cb0ef41Sopenharmony_ci<span>N-API version: 8</span> 50591cb0ef41Sopenharmony_ci</div> 50601cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_type_tag_object</span><span class="hljs-params">(napi_env env, 50611cb0ef41Sopenharmony_ci napi_value js_object, 50621cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> napi_type_tag* type_tag)</span>;</code> <button class="copy-button">copy</button></pre> 50631cb0ef41Sopenharmony_ci<ul> 50641cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 50651cb0ef41Sopenharmony_ci<li><code>[in] js_object</code>: The JavaScript object or <a href="#napi_create_external">external</a> to be marked.</li> 50661cb0ef41Sopenharmony_ci<li><code>[in] type_tag</code>: The tag with which the object is to be marked.</li> 50671cb0ef41Sopenharmony_ci</ul> 50681cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 50691cb0ef41Sopenharmony_ci<p>Associates the value of the <code>type_tag</code> pointer with the JavaScript object or 50701cb0ef41Sopenharmony_ci<a href="#napi_create_external">external</a>. <code>napi_check_object_type_tag()</code> can then be used to compare the tag 50711cb0ef41Sopenharmony_cithat was attached to the object with one owned by the addon to ensure that the 50721cb0ef41Sopenharmony_ciobject has the right type.</p> 50731cb0ef41Sopenharmony_ci<p>If the object already has an associated type tag, this API will return 50741cb0ef41Sopenharmony_ci<code>napi_invalid_arg</code>.</p> 50751cb0ef41Sopenharmony_ci<h4><code>napi_check_object_type_tag</code><span><a class="mark" href="#napi_check_object_type_tag" id="napi_check_object_type_tag">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_check_object_type_tag"></a></h4> 50761cb0ef41Sopenharmony_ci<div class="api_metadata"> 50771cb0ef41Sopenharmony_ci<span>Added in: v14.8.0, v12.19.0</span> 50781cb0ef41Sopenharmony_ci<span>N-API version: 8</span> 50791cb0ef41Sopenharmony_ci</div> 50801cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_check_object_type_tag</span><span class="hljs-params">(napi_env env, 50811cb0ef41Sopenharmony_ci napi_value js_object, 50821cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> napi_type_tag* type_tag, 50831cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 50841cb0ef41Sopenharmony_ci<ul> 50851cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 50861cb0ef41Sopenharmony_ci<li><code>[in] js_object</code>: The JavaScript object or <a href="#napi_create_external">external</a> whose type tag to 50871cb0ef41Sopenharmony_ciexamine.</li> 50881cb0ef41Sopenharmony_ci<li><code>[in] type_tag</code>: The tag with which to compare any tag found on the object.</li> 50891cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Whether the type tag given matched the type tag on the 50901cb0ef41Sopenharmony_ciobject. <code>false</code> is also returned if no type tag was found on the object.</li> 50911cb0ef41Sopenharmony_ci</ul> 50921cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 50931cb0ef41Sopenharmony_ci<p>Compares the pointer given as <code>type_tag</code> with any that can be found on 50941cb0ef41Sopenharmony_ci<code>js_object</code>. If no tag is found on <code>js_object</code> or, if a tag is found but it does 50951cb0ef41Sopenharmony_cinot match <code>type_tag</code>, then <code>result</code> is set to <code>false</code>. If a tag is found and it 50961cb0ef41Sopenharmony_cimatches <code>type_tag</code>, then <code>result</code> is set to <code>true</code>.</p> 50971cb0ef41Sopenharmony_ci<h4><code>napi_add_finalizer</code><span><a class="mark" href="#napi_add_finalizer" id="napi_add_finalizer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_add_finalizer"></a></h4> 50981cb0ef41Sopenharmony_ci<div class="api_metadata"> 50991cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 51001cb0ef41Sopenharmony_ci<span>N-API version: 5</span> 51011cb0ef41Sopenharmony_ci</div> 51021cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_add_finalizer</span><span class="hljs-params">(napi_env env, 51031cb0ef41Sopenharmony_ci napi_value js_object, 51041cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_data, 51051cb0ef41Sopenharmony_ci node_api_nogc_finalize finalize_cb, 51061cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint, 51071cb0ef41Sopenharmony_ci napi_ref* result)</span>;</code> <button class="copy-button">copy</button></pre> 51081cb0ef41Sopenharmony_ci<ul> 51091cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 51101cb0ef41Sopenharmony_ci<li><code>[in] js_object</code>: The JavaScript object to which the native data will be 51111cb0ef41Sopenharmony_ciattached.</li> 51121cb0ef41Sopenharmony_ci<li><code>[in] finalize_data</code>: Optional data to be passed to <code>finalize_cb</code>.</li> 51131cb0ef41Sopenharmony_ci<li><code>[in] finalize_cb</code>: Native callback that will be used to free the 51141cb0ef41Sopenharmony_cinative data when the JavaScript object has been garbage-collected. 51151cb0ef41Sopenharmony_ci<a href="#napi_finalize"><code>napi_finalize</code></a> provides more details.</li> 51161cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional contextual hint that is passed to the 51171cb0ef41Sopenharmony_cifinalize callback.</li> 51181cb0ef41Sopenharmony_ci<li><code>[out] result</code>: Optional reference to the JavaScript object.</li> 51191cb0ef41Sopenharmony_ci</ul> 51201cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 51211cb0ef41Sopenharmony_ci<p>Adds a <code>napi_finalize</code> callback which will be called when the JavaScript object 51221cb0ef41Sopenharmony_ciin <code>js_object</code> has been garbage-collected.</p> 51231cb0ef41Sopenharmony_ci<p>This API can be called multiple times on a single JavaScript object.</p> 51241cb0ef41Sopenharmony_ci<p><em>Caution</em>: The optional returned reference (if obtained) should be deleted via 51251cb0ef41Sopenharmony_ci<a href="#napi_delete_reference"><code>napi_delete_reference</code></a> ONLY in response to the finalize callback 51261cb0ef41Sopenharmony_ciinvocation. If it is deleted before then, then the finalize callback may never 51271cb0ef41Sopenharmony_cibe invoked. Therefore, when obtaining a reference a finalize callback is also 51281cb0ef41Sopenharmony_cirequired in order to enable correct disposal of the reference.</p> 51291cb0ef41Sopenharmony_ci<h5><code>node_api_post_finalizer</code><span><a class="mark" href="#node_api_post_finalizer" id="node_api_post_finalizer">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_post_finalizer"></a></h5> 51301cb0ef41Sopenharmony_ci<div class="api_metadata"> 51311cb0ef41Sopenharmony_ci<span>Added in: v18.19.0</span> 51321cb0ef41Sopenharmony_ci</div> 51331cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 51341cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">node_api_post_finalizer</span><span class="hljs-params">(node_api_nogc_env env, 51351cb0ef41Sopenharmony_ci napi_finalize finalize_cb, 51361cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_data, 51371cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* finalize_hint)</span>;</code> <button class="copy-button">copy</button></pre> 51381cb0ef41Sopenharmony_ci<ul> 51391cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 51401cb0ef41Sopenharmony_ci<li><code>[in] finalize_cb</code>: Native callback that will be used to free the 51411cb0ef41Sopenharmony_cinative data when the JavaScript object has been garbage-collected. 51421cb0ef41Sopenharmony_ci<a href="#napi_finalize"><code>napi_finalize</code></a> provides more details.</li> 51431cb0ef41Sopenharmony_ci<li><code>[in] finalize_data</code>: Optional data to be passed to <code>finalize_cb</code>.</li> 51441cb0ef41Sopenharmony_ci<li><code>[in] finalize_hint</code>: Optional contextual hint that is passed to the 51451cb0ef41Sopenharmony_cifinalize callback.</li> 51461cb0ef41Sopenharmony_ci</ul> 51471cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 51481cb0ef41Sopenharmony_ci<p>Schedules a <code>napi_finalize</code> callback to be called asynchronously in the 51491cb0ef41Sopenharmony_cievent loop.</p> 51501cb0ef41Sopenharmony_ci<p>Normally, finalizers are called while the GC (garbage collector) collects 51511cb0ef41Sopenharmony_ciobjects. At that point calling any Node-API that may cause changes in the GC 51521cb0ef41Sopenharmony_cistate will be disabled and will crash Node.js.</p> 51531cb0ef41Sopenharmony_ci<p><code>node_api_post_finalizer</code> helps to work around this limitation by allowing the 51541cb0ef41Sopenharmony_ciadd-on to defer calls to such Node-APIs to a point in time outside of the GC 51551cb0ef41Sopenharmony_cifinalization.</p> 51561cb0ef41Sopenharmony_ci</section><section><h3>Simple asynchronous operations<span><a class="mark" href="#simple-asynchronous-operations" id="simple-asynchronous-operations">#</a></span><a aria-hidden="true" class="legacy" id="n_api_simple_asynchronous_operations"></a></h3> 51571cb0ef41Sopenharmony_ci<p>Addon modules often need to leverage async helpers from libuv as part of their 51581cb0ef41Sopenharmony_ciimplementation. This allows them to schedule work to be executed asynchronously 51591cb0ef41Sopenharmony_ciso that their methods can return in advance of the work being completed. This 51601cb0ef41Sopenharmony_ciallows them to avoid blocking overall execution of the Node.js application.</p> 51611cb0ef41Sopenharmony_ci<p>Node-API provides an ABI-stable interface for these 51621cb0ef41Sopenharmony_cisupporting functions which covers the most common asynchronous use cases.</p> 51631cb0ef41Sopenharmony_ci<p>Node-API defines the <code>napi_async_work</code> structure which is used to manage 51641cb0ef41Sopenharmony_ciasynchronous workers. Instances are created/deleted with 51651cb0ef41Sopenharmony_ci<a href="#napi_create_async_work"><code>napi_create_async_work</code></a> and <a href="#napi_delete_async_work"><code>napi_delete_async_work</code></a>.</p> 51661cb0ef41Sopenharmony_ci<p>The <code>execute</code> and <code>complete</code> callbacks are functions that will be 51671cb0ef41Sopenharmony_ciinvoked when the executor is ready to execute and when it completes its 51681cb0ef41Sopenharmony_citask respectively.</p> 51691cb0ef41Sopenharmony_ci<p>The <code>execute</code> function should avoid making any Node-API calls 51701cb0ef41Sopenharmony_cithat could result in the execution of JavaScript or interaction with 51711cb0ef41Sopenharmony_ciJavaScript objects. Most often, any code that needs to make Node-API 51721cb0ef41Sopenharmony_cicalls should be made in <code>complete</code> callback instead. 51731cb0ef41Sopenharmony_ciAvoid using the <code>napi_env</code> parameter in the execute callback as 51741cb0ef41Sopenharmony_ciit will likely execute JavaScript.</p> 51751cb0ef41Sopenharmony_ci<p>These functions implement the following interfaces:</p> 51761cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*napi_async_execute_callback)</span><span class="hljs-params">(napi_env env, 51771cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data)</span>; 51781cb0ef41Sopenharmony_ci<span class="hljs-keyword">typedef</span> <span class="hljs-title function_">void</span> <span class="hljs-params">(*napi_async_complete_callback)</span><span class="hljs-params">(napi_env env, 51791cb0ef41Sopenharmony_ci napi_status status, 51801cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data)</span>;</code> <button class="copy-button">copy</button></pre> 51811cb0ef41Sopenharmony_ci<p>When these methods are invoked, the <code>data</code> parameter passed will be the 51821cb0ef41Sopenharmony_ciaddon-provided <code>void*</code> data that was passed into the 51831cb0ef41Sopenharmony_ci<code>napi_create_async_work</code> call.</p> 51841cb0ef41Sopenharmony_ci<p>Once created the async worker can be queued 51851cb0ef41Sopenharmony_cifor execution using the <a href="#napi_queue_async_work"><code>napi_queue_async_work</code></a> function:</p> 51861cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_queue_async_work</span><span class="hljs-params">(node_api_nogc_env env, 51871cb0ef41Sopenharmony_ci napi_async_work work)</span>;</code> <button class="copy-button">copy</button></pre> 51881cb0ef41Sopenharmony_ci<p><a href="#napi_cancel_async_work"><code>napi_cancel_async_work</code></a> can be used if the work needs 51891cb0ef41Sopenharmony_cito be cancelled before the work has started execution.</p> 51901cb0ef41Sopenharmony_ci<p>After calling <a href="#napi_cancel_async_work"><code>napi_cancel_async_work</code></a>, the <code>complete</code> callback 51911cb0ef41Sopenharmony_ciwill be invoked with a status value of <code>napi_cancelled</code>. 51921cb0ef41Sopenharmony_ciThe work should not be deleted before the <code>complete</code> 51931cb0ef41Sopenharmony_cicallback invocation, even when it was cancelled.</p> 51941cb0ef41Sopenharmony_ci<h4><code>napi_create_async_work</code><span><a class="mark" href="#napi_create_async_work" id="napi_create_async_work">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_async_work"></a></h4> 51951cb0ef41Sopenharmony_ci<div class="api_metadata"> 51961cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 51971cb0ef41Sopenharmony_ci<table> 51981cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 51991cb0ef41Sopenharmony_ci<tr><td>v8.6.0</td> 52001cb0ef41Sopenharmony_ci<td><p>Added <code>async_resource</code> and <code>async_resource_name</code> parameters.</p></td></tr> 52011cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 52021cb0ef41Sopenharmony_ci<td><p><span>Added in: v8.0.0</span></p></td></tr> 52031cb0ef41Sopenharmony_ci</tbody></table> 52041cb0ef41Sopenharmony_ci</details> 52051cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 52061cb0ef41Sopenharmony_ci</div> 52071cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_async_work</span><span class="hljs-params">(napi_env env, 52081cb0ef41Sopenharmony_ci napi_value async_resource, 52091cb0ef41Sopenharmony_ci napi_value async_resource_name, 52101cb0ef41Sopenharmony_ci napi_async_execute_callback execute, 52111cb0ef41Sopenharmony_ci napi_async_complete_callback complete, 52121cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data, 52131cb0ef41Sopenharmony_ci napi_async_work* result)</span>;</code> <button class="copy-button">copy</button></pre> 52141cb0ef41Sopenharmony_ci<ul> 52151cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 52161cb0ef41Sopenharmony_ci<li><code>[in] async_resource</code>: An optional object associated with the async work 52171cb0ef41Sopenharmony_cithat will be passed to possible <code>async_hooks</code> <a href="async_hooks.html#initasyncid-type-triggerasyncid-resource"><code>init</code> hooks</a>.</li> 52181cb0ef41Sopenharmony_ci<li><code>[in] async_resource_name</code>: Identifier for the kind of resource that is being 52191cb0ef41Sopenharmony_ciprovided for diagnostic information exposed by the <code>async_hooks</code> API.</li> 52201cb0ef41Sopenharmony_ci<li><code>[in] execute</code>: The native function which should be called to execute the 52211cb0ef41Sopenharmony_cilogic asynchronously. The given function is called from a worker pool thread 52221cb0ef41Sopenharmony_ciand can execute in parallel with the main event loop thread.</li> 52231cb0ef41Sopenharmony_ci<li><code>[in] complete</code>: The native function which will be called when the 52241cb0ef41Sopenharmony_ciasynchronous logic is completed or is cancelled. The given function is called 52251cb0ef41Sopenharmony_cifrom the main event loop thread. <a href="#napi_async_complete_callback"><code>napi_async_complete_callback</code></a> provides 52261cb0ef41Sopenharmony_cimore details.</li> 52271cb0ef41Sopenharmony_ci<li><code>[in] data</code>: User-provided data context. This will be passed back into the 52281cb0ef41Sopenharmony_ciexecute and complete functions.</li> 52291cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_async_work*</code> which is the handle to the newly created 52301cb0ef41Sopenharmony_ciasync work.</li> 52311cb0ef41Sopenharmony_ci</ul> 52321cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 52331cb0ef41Sopenharmony_ci<p>This API allocates a work object that is used to execute logic asynchronously. 52341cb0ef41Sopenharmony_ciIt should be freed using <a href="#napi_delete_async_work"><code>napi_delete_async_work</code></a> once the work is no longer 52351cb0ef41Sopenharmony_cirequired.</p> 52361cb0ef41Sopenharmony_ci<p><code>async_resource_name</code> should be a null-terminated, UTF-8-encoded string.</p> 52371cb0ef41Sopenharmony_ci<p>The <code>async_resource_name</code> identifier is provided by the user and should be 52381cb0ef41Sopenharmony_cirepresentative of the type of async work being performed. It is also recommended 52391cb0ef41Sopenharmony_cito apply namespacing to the identifier, e.g. by including the module name. See 52401cb0ef41Sopenharmony_cithe <a href="async_hooks.html#type"><code>async_hooks</code> documentation</a> for more information.</p> 52411cb0ef41Sopenharmony_ci<h4><code>napi_delete_async_work</code><span><a class="mark" href="#napi_delete_async_work" id="napi_delete_async_work">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_delete_async_work"></a></h4> 52421cb0ef41Sopenharmony_ci<div class="api_metadata"> 52431cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 52441cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 52451cb0ef41Sopenharmony_ci</div> 52461cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_delete_async_work</span><span class="hljs-params">(napi_env env, 52471cb0ef41Sopenharmony_ci napi_async_work work)</span>;</code> <button class="copy-button">copy</button></pre> 52481cb0ef41Sopenharmony_ci<ul> 52491cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 52501cb0ef41Sopenharmony_ci<li><code>[in] work</code>: The handle returned by the call to <code>napi_create_async_work</code>.</li> 52511cb0ef41Sopenharmony_ci</ul> 52521cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 52531cb0ef41Sopenharmony_ci<p>This API frees a previously allocated work object.</p> 52541cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 52551cb0ef41Sopenharmony_ci<h4><code>napi_queue_async_work</code><span><a class="mark" href="#napi_queue_async_work" id="napi_queue_async_work">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_queue_async_work"></a></h4> 52561cb0ef41Sopenharmony_ci<div class="api_metadata"> 52571cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 52581cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 52591cb0ef41Sopenharmony_ci</div> 52601cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_queue_async_work</span><span class="hljs-params">(node_api_nogc_env env, 52611cb0ef41Sopenharmony_ci napi_async_work work)</span>;</code> <button class="copy-button">copy</button></pre> 52621cb0ef41Sopenharmony_ci<ul> 52631cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 52641cb0ef41Sopenharmony_ci<li><code>[in] work</code>: The handle returned by the call to <code>napi_create_async_work</code>.</li> 52651cb0ef41Sopenharmony_ci</ul> 52661cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 52671cb0ef41Sopenharmony_ci<p>This API requests that the previously allocated work be scheduled 52681cb0ef41Sopenharmony_cifor execution. Once it returns successfully, this API must not be called again 52691cb0ef41Sopenharmony_ciwith the same <code>napi_async_work</code> item or the result will be undefined.</p> 52701cb0ef41Sopenharmony_ci<h4><code>napi_cancel_async_work</code><span><a class="mark" href="#napi_cancel_async_work" id="napi_cancel_async_work">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_cancel_async_work"></a></h4> 52711cb0ef41Sopenharmony_ci<div class="api_metadata"> 52721cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 52731cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 52741cb0ef41Sopenharmony_ci</div> 52751cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_cancel_async_work</span><span class="hljs-params">(node_api_nogc_env env, 52761cb0ef41Sopenharmony_ci napi_async_work work)</span>;</code> <button class="copy-button">copy</button></pre> 52771cb0ef41Sopenharmony_ci<ul> 52781cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 52791cb0ef41Sopenharmony_ci<li><code>[in] work</code>: The handle returned by the call to <code>napi_create_async_work</code>.</li> 52801cb0ef41Sopenharmony_ci</ul> 52811cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 52821cb0ef41Sopenharmony_ci<p>This API cancels queued work if it has not yet 52831cb0ef41Sopenharmony_cibeen started. If it has already started executing, it cannot be 52841cb0ef41Sopenharmony_cicancelled and <code>napi_generic_failure</code> will be returned. If successful, 52851cb0ef41Sopenharmony_cithe <code>complete</code> callback will be invoked with a status value of 52861cb0ef41Sopenharmony_ci<code>napi_cancelled</code>. The work should not be deleted before the <code>complete</code> 52871cb0ef41Sopenharmony_cicallback invocation, even if it has been successfully cancelled.</p> 52881cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 52891cb0ef41Sopenharmony_ci</section><section><h3>Custom asynchronous operations<span><a class="mark" href="#custom-asynchronous-operations" id="custom-asynchronous-operations">#</a></span><a aria-hidden="true" class="legacy" id="n_api_custom_asynchronous_operations"></a></h3> 52901cb0ef41Sopenharmony_ci<p>The simple asynchronous work APIs above may not be appropriate for every 52911cb0ef41Sopenharmony_ciscenario. When using any other asynchronous mechanism, the following APIs 52921cb0ef41Sopenharmony_ciare necessary to ensure an asynchronous operation is properly tracked by 52931cb0ef41Sopenharmony_cithe runtime.</p> 52941cb0ef41Sopenharmony_ci<h4><code>napi_async_init</code><span><a class="mark" href="#napi_async_init" id="napi_async_init">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_async_init"></a></h4> 52951cb0ef41Sopenharmony_ci<div class="api_metadata"> 52961cb0ef41Sopenharmony_ci<span>Added in: v8.6.0</span> 52971cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 52981cb0ef41Sopenharmony_ci</div> 52991cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_async_init</span><span class="hljs-params">(napi_env env, 53001cb0ef41Sopenharmony_ci napi_value async_resource, 53011cb0ef41Sopenharmony_ci napi_value async_resource_name, 53021cb0ef41Sopenharmony_ci napi_async_context* result)</span></code> <button class="copy-button">copy</button></pre> 53031cb0ef41Sopenharmony_ci<ul> 53041cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 53051cb0ef41Sopenharmony_ci<li><code>[in] async_resource</code>: Object associated with the async work 53061cb0ef41Sopenharmony_cithat will be passed to possible <code>async_hooks</code> <a href="async_hooks.html#initasyncid-type-triggerasyncid-resource"><code>init</code> hooks</a> and can be 53071cb0ef41Sopenharmony_ciaccessed by <a href="async_hooks.html#async_hooksexecutionasyncresource"><code>async_hooks.executionAsyncResource()</code></a>.</li> 53081cb0ef41Sopenharmony_ci<li><code>[in] async_resource_name</code>: Identifier for the kind of resource that is being 53091cb0ef41Sopenharmony_ciprovided for diagnostic information exposed by the <code>async_hooks</code> API.</li> 53101cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The initialized async context.</li> 53111cb0ef41Sopenharmony_ci</ul> 53121cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 53131cb0ef41Sopenharmony_ci<p>The <code>async_resource</code> object needs to be kept alive until 53141cb0ef41Sopenharmony_ci<a href="#napi_async_destroy"><code>napi_async_destroy</code></a> to keep <code>async_hooks</code> related API acts correctly. In 53151cb0ef41Sopenharmony_ciorder to retain ABI compatibility with previous versions, <code>napi_async_context</code>s 53161cb0ef41Sopenharmony_ciare not maintaining the strong reference to the <code>async_resource</code> objects to 53171cb0ef41Sopenharmony_ciavoid introducing causing memory leaks. However, if the <code>async_resource</code> is 53181cb0ef41Sopenharmony_cigarbage collected by JavaScript engine before the <code>napi_async_context</code> was 53191cb0ef41Sopenharmony_cidestroyed by <code>napi_async_destroy</code>, calling <code>napi_async_context</code> related APIs 53201cb0ef41Sopenharmony_cilike <a href="#napi_open_callback_scope"><code>napi_open_callback_scope</code></a> and <a href="#napi_make_callback"><code>napi_make_callback</code></a> can cause 53211cb0ef41Sopenharmony_ciproblems like loss of async context when using the <code>AsyncLocalStorage</code> API.</p> 53221cb0ef41Sopenharmony_ci<p>In order to retain ABI compatibility with previous versions, passing <code>NULL</code> 53231cb0ef41Sopenharmony_cifor <code>async_resource</code> does not result in an error. However, this is not 53241cb0ef41Sopenharmony_cirecommended as this will result in undesirable behavior with <code>async_hooks</code> 53251cb0ef41Sopenharmony_ci<a href="async_hooks.html#initasyncid-type-triggerasyncid-resource"><code>init</code> hooks</a> and <code>async_hooks.executionAsyncResource()</code> as the resource is 53261cb0ef41Sopenharmony_cinow required by the underlying <code>async_hooks</code> implementation in order to provide 53271cb0ef41Sopenharmony_cithe linkage between async callbacks.</p> 53281cb0ef41Sopenharmony_ci<h4><code>napi_async_destroy</code><span><a class="mark" href="#napi_async_destroy" id="napi_async_destroy">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_async_destroy"></a></h4> 53291cb0ef41Sopenharmony_ci<div class="api_metadata"> 53301cb0ef41Sopenharmony_ci<span>Added in: v8.6.0</span> 53311cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 53321cb0ef41Sopenharmony_ci</div> 53331cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_async_destroy</span><span class="hljs-params">(napi_env env, 53341cb0ef41Sopenharmony_ci napi_async_context async_context)</span>;</code> <button class="copy-button">copy</button></pre> 53351cb0ef41Sopenharmony_ci<ul> 53361cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 53371cb0ef41Sopenharmony_ci<li><code>[in] async_context</code>: The async context to be destroyed.</li> 53381cb0ef41Sopenharmony_ci</ul> 53391cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 53401cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 53411cb0ef41Sopenharmony_ci<h4><code>napi_make_callback</code><span><a class="mark" href="#napi_make_callback" id="napi_make_callback">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_make_callback"></a></h4> 53421cb0ef41Sopenharmony_ci<div class="api_metadata"> 53431cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 53441cb0ef41Sopenharmony_ci<table> 53451cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 53461cb0ef41Sopenharmony_ci<tr><td>v8.6.0</td> 53471cb0ef41Sopenharmony_ci<td><p>Added <code>async_context</code> parameter.</p></td></tr> 53481cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 53491cb0ef41Sopenharmony_ci<td><p><span>Added in: v8.0.0</span></p></td></tr> 53501cb0ef41Sopenharmony_ci</tbody></table> 53511cb0ef41Sopenharmony_ci</details> 53521cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 53531cb0ef41Sopenharmony_ci</div> 53541cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_make_callback</span><span class="hljs-params">(napi_env env, 53551cb0ef41Sopenharmony_ci napi_async_context async_context, 53561cb0ef41Sopenharmony_ci napi_value recv, 53571cb0ef41Sopenharmony_ci napi_value func, 53581cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> argc, 53591cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> napi_value* argv, 53601cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 53611cb0ef41Sopenharmony_ci<ul> 53621cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 53631cb0ef41Sopenharmony_ci<li><code>[in] async_context</code>: Context for the async operation that is 53641cb0ef41Sopenharmony_ciinvoking the callback. This should normally be a value previously 53651cb0ef41Sopenharmony_ciobtained from <a href="#napi_async_init"><code>napi_async_init</code></a>. 53661cb0ef41Sopenharmony_ciIn order to retain ABI compatibility with previous versions, passing <code>NULL</code> 53671cb0ef41Sopenharmony_cifor <code>async_context</code> does not result in an error. However, this results 53681cb0ef41Sopenharmony_ciin incorrect operation of async hooks. Potential issues include loss of 53691cb0ef41Sopenharmony_ciasync context when using the <code>AsyncLocalStorage</code> API.</li> 53701cb0ef41Sopenharmony_ci<li><code>[in] recv</code>: The <code>this</code> value passed to the called function.</li> 53711cb0ef41Sopenharmony_ci<li><code>[in] func</code>: <code>napi_value</code> representing the JavaScript function to be invoked.</li> 53721cb0ef41Sopenharmony_ci<li><code>[in] argc</code>: The count of elements in the <code>argv</code> array.</li> 53731cb0ef41Sopenharmony_ci<li><code>[in] argv</code>: Array of JavaScript values as <code>napi_value</code> representing the 53741cb0ef41Sopenharmony_ciarguments to the function. If <code>argc</code> is zero this parameter may be 53751cb0ef41Sopenharmony_ciomitted by passing in <code>NULL</code>.</li> 53761cb0ef41Sopenharmony_ci<li><code>[out] result</code>: <code>napi_value</code> representing the JavaScript object returned.</li> 53771cb0ef41Sopenharmony_ci</ul> 53781cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 53791cb0ef41Sopenharmony_ci<p>This method allows a JavaScript function object to be called from a native 53801cb0ef41Sopenharmony_ciadd-on. This API is similar to <code>napi_call_function</code>. However, it is used to call 53811cb0ef41Sopenharmony_ci<em>from</em> native code back <em>into</em> JavaScript <em>after</em> returning from an async 53821cb0ef41Sopenharmony_cioperation (when there is no other script on the stack). It is a fairly simple 53831cb0ef41Sopenharmony_ciwrapper around <code>node::MakeCallback</code>.</p> 53841cb0ef41Sopenharmony_ci<p>Note it is <em>not</em> necessary to use <code>napi_make_callback</code> from within a 53851cb0ef41Sopenharmony_ci<code>napi_async_complete_callback</code>; in that situation the callback's async 53861cb0ef41Sopenharmony_cicontext has already been set up, so a direct call to <code>napi_call_function</code> 53871cb0ef41Sopenharmony_ciis sufficient and appropriate. Use of the <code>napi_make_callback</code> function 53881cb0ef41Sopenharmony_cimay be required when implementing custom async behavior that does not use 53891cb0ef41Sopenharmony_ci<code>napi_create_async_work</code>.</p> 53901cb0ef41Sopenharmony_ci<p>Any <code>process.nextTick</code>s or Promises scheduled on the microtask queue by 53911cb0ef41Sopenharmony_ciJavaScript during the callback are ran before returning back to C/C++.</p> 53921cb0ef41Sopenharmony_ci<h4><code>napi_open_callback_scope</code><span><a class="mark" href="#napi_open_callback_scope" id="napi_open_callback_scope">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_open_callback_scope"></a></h4> 53931cb0ef41Sopenharmony_ci<div class="api_metadata"> 53941cb0ef41Sopenharmony_ci<span>Added in: v9.6.0</span> 53951cb0ef41Sopenharmony_ci<span>N-API version: 3</span> 53961cb0ef41Sopenharmony_ci</div> 53971cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_open_callback_scope</span><span class="hljs-params">(napi_env env, 53981cb0ef41Sopenharmony_ci napi_value resource_object, 53991cb0ef41Sopenharmony_ci napi_async_context context, 54001cb0ef41Sopenharmony_ci napi_callback_scope* result)</span></code> <button class="copy-button">copy</button></pre> 54011cb0ef41Sopenharmony_ci<ul> 54021cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 54031cb0ef41Sopenharmony_ci<li><code>[in] resource_object</code>: An object associated with the async work 54041cb0ef41Sopenharmony_cithat will be passed to possible <code>async_hooks</code> <a href="async_hooks.html#initasyncid-type-triggerasyncid-resource"><code>init</code> hooks</a>. This 54051cb0ef41Sopenharmony_ciparameter has been deprecated and is ignored at runtime. Use the 54061cb0ef41Sopenharmony_ci<code>async_resource</code> parameter in <a href="#napi_async_init"><code>napi_async_init</code></a> instead.</li> 54071cb0ef41Sopenharmony_ci<li><code>[in] context</code>: Context for the async operation that is invoking the callback. 54081cb0ef41Sopenharmony_ciThis should be a value previously obtained from <a href="#napi_async_init"><code>napi_async_init</code></a>.</li> 54091cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The newly created scope.</li> 54101cb0ef41Sopenharmony_ci</ul> 54111cb0ef41Sopenharmony_ci<p>There are cases (for example, resolving promises) where it is 54121cb0ef41Sopenharmony_cinecessary to have the equivalent of the scope associated with a callback 54131cb0ef41Sopenharmony_ciin place when making certain Node-API calls. If there is no other script on 54141cb0ef41Sopenharmony_cithe stack the <a href="#napi_open_callback_scope"><code>napi_open_callback_scope</code></a> and 54151cb0ef41Sopenharmony_ci<a href="#napi_close_callback_scope"><code>napi_close_callback_scope</code></a> functions can be used to open/close 54161cb0ef41Sopenharmony_cithe required scope.</p> 54171cb0ef41Sopenharmony_ci<h4><code>napi_close_callback_scope</code><span><a class="mark" href="#napi_close_callback_scope" id="napi_close_callback_scope">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_close_callback_scope"></a></h4> 54181cb0ef41Sopenharmony_ci<div class="api_metadata"> 54191cb0ef41Sopenharmony_ci<span>Added in: v9.6.0</span> 54201cb0ef41Sopenharmony_ci<span>N-API version: 3</span> 54211cb0ef41Sopenharmony_ci</div> 54221cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_close_callback_scope</span><span class="hljs-params">(napi_env env, 54231cb0ef41Sopenharmony_ci napi_callback_scope scope)</span></code> <button class="copy-button">copy</button></pre> 54241cb0ef41Sopenharmony_ci<ul> 54251cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 54261cb0ef41Sopenharmony_ci<li><code>[in] scope</code>: The scope to be closed.</li> 54271cb0ef41Sopenharmony_ci</ul> 54281cb0ef41Sopenharmony_ci<p>This API can be called even if there is a pending JavaScript exception.</p> 54291cb0ef41Sopenharmony_ci</section><section><h3>Version management<span><a class="mark" href="#version-management" id="version-management">#</a></span><a aria-hidden="true" class="legacy" id="n_api_version_management"></a></h3> 54301cb0ef41Sopenharmony_ci<h4><code>napi_get_node_version</code><span><a class="mark" href="#napi_get_node_version" id="napi_get_node_version">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_node_version"></a></h4> 54311cb0ef41Sopenharmony_ci<div class="api_metadata"> 54321cb0ef41Sopenharmony_ci<span>Added in: v8.4.0</span> 54331cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 54341cb0ef41Sopenharmony_ci</div> 54351cb0ef41Sopenharmony_ci<pre><code class="language-c"><span class="hljs-keyword">typedef</span> <span class="hljs-class"><span class="hljs-keyword">struct</span> {</span> 54361cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> major; 54371cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> minor; 54381cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span> patch; 54391cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> <span class="hljs-type">char</span>* release; 54401cb0ef41Sopenharmony_ci} napi_node_version; 54411cb0ef41Sopenharmony_ci 54421cb0ef41Sopenharmony_cinapi_status <span class="hljs-title function_">napi_get_node_version</span><span class="hljs-params">(node_api_nogc_env env, 54431cb0ef41Sopenharmony_ci <span class="hljs-type">const</span> napi_node_version** version)</span>;</code> <button class="copy-button">copy</button></pre> 54441cb0ef41Sopenharmony_ci<ul> 54451cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 54461cb0ef41Sopenharmony_ci<li><code>[out] version</code>: A pointer to version information for Node.js itself.</li> 54471cb0ef41Sopenharmony_ci</ul> 54481cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 54491cb0ef41Sopenharmony_ci<p>This function fills the <code>version</code> struct with the major, minor, and patch 54501cb0ef41Sopenharmony_civersion of Node.js that is currently running, and the <code>release</code> field with the 54511cb0ef41Sopenharmony_civalue of <a href="process.html#processrelease"><code>process.release.name</code></a>.</p> 54521cb0ef41Sopenharmony_ci<p>The returned buffer is statically allocated and does not need to be freed.</p> 54531cb0ef41Sopenharmony_ci<h4><code>napi_get_version</code><span><a class="mark" href="#napi_get_version" id="napi_get_version">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_version"></a></h4> 54541cb0ef41Sopenharmony_ci<div class="api_metadata"> 54551cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 54561cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 54571cb0ef41Sopenharmony_ci</div> 54581cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_get_version</span><span class="hljs-params">(node_api_nogc_env env, 54591cb0ef41Sopenharmony_ci <span class="hljs-type">uint32_t</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 54601cb0ef41Sopenharmony_ci<ul> 54611cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 54621cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The highest version of Node-API supported.</li> 54631cb0ef41Sopenharmony_ci</ul> 54641cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 54651cb0ef41Sopenharmony_ci<p>This API returns the highest Node-API version supported by the 54661cb0ef41Sopenharmony_ciNode.js runtime. Node-API is planned to be additive such that 54671cb0ef41Sopenharmony_cinewer releases of Node.js may support additional API functions. 54681cb0ef41Sopenharmony_ciIn order to allow an addon to use a newer function when running with 54691cb0ef41Sopenharmony_civersions of Node.js that support it, while providing 54701cb0ef41Sopenharmony_cifallback behavior when running with Node.js versions that don't 54711cb0ef41Sopenharmony_cisupport it:</p> 54721cb0ef41Sopenharmony_ci<ul> 54731cb0ef41Sopenharmony_ci<li>Call <code>napi_get_version()</code> to determine if the API is available.</li> 54741cb0ef41Sopenharmony_ci<li>If available, dynamically load a pointer to the function using <code>uv_dlsym()</code>.</li> 54751cb0ef41Sopenharmony_ci<li>Use the dynamically loaded pointer to invoke the function.</li> 54761cb0ef41Sopenharmony_ci<li>If the function is not available, provide an alternate implementation 54771cb0ef41Sopenharmony_cithat does not use the function.</li> 54781cb0ef41Sopenharmony_ci</ul> 54791cb0ef41Sopenharmony_ci</section><section><h3>Memory management<span><a class="mark" href="#memory-management" id="memory-management">#</a></span><a aria-hidden="true" class="legacy" id="n_api_memory_management"></a></h3> 54801cb0ef41Sopenharmony_ci<h4><code>napi_adjust_external_memory</code><span><a class="mark" href="#napi_adjust_external_memory" id="napi_adjust_external_memory">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_adjust_external_memory"></a></h4> 54811cb0ef41Sopenharmony_ci<div class="api_metadata"> 54821cb0ef41Sopenharmony_ci<span>Added in: v8.5.0</span> 54831cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 54841cb0ef41Sopenharmony_ci</div> 54851cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_adjust_external_memory</span><span class="hljs-params">(node_api_nogc_env env, 54861cb0ef41Sopenharmony_ci <span class="hljs-type">int64_t</span> change_in_bytes, 54871cb0ef41Sopenharmony_ci <span class="hljs-type">int64_t</span>* result)</span>;</code> <button class="copy-button">copy</button></pre> 54881cb0ef41Sopenharmony_ci<ul> 54891cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 54901cb0ef41Sopenharmony_ci<li><code>[in] change_in_bytes</code>: The change in externally allocated memory that is kept 54911cb0ef41Sopenharmony_cialive by JavaScript objects.</li> 54921cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The adjusted value</li> 54931cb0ef41Sopenharmony_ci</ul> 54941cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 54951cb0ef41Sopenharmony_ci<p>This function gives V8 an indication of the amount of externally allocated 54961cb0ef41Sopenharmony_cimemory that is kept alive by JavaScript objects (i.e. a JavaScript object 54971cb0ef41Sopenharmony_cithat points to its own memory allocated by a native addon). Registering 54981cb0ef41Sopenharmony_ciexternally allocated memory will trigger global garbage collections more 54991cb0ef41Sopenharmony_cioften than it would otherwise.</p> 55001cb0ef41Sopenharmony_ci</section><section><h3>Promises<span><a class="mark" href="#promises" id="promises">#</a></span><a aria-hidden="true" class="legacy" id="n_api_promises"></a></h3> 55011cb0ef41Sopenharmony_ci<p>Node-API provides facilities for creating <code>Promise</code> objects as described in 55021cb0ef41Sopenharmony_ci<a href="https://tc39.github.io/ecma262/#sec-promise-objects">Section 25.4</a> of the ECMA specification. It implements promises as a pair of 55031cb0ef41Sopenharmony_ciobjects. When a promise is created by <code>napi_create_promise()</code>, a "deferred" 55041cb0ef41Sopenharmony_ciobject is created and returned alongside the <code>Promise</code>. The deferred object is 55051cb0ef41Sopenharmony_cibound to the created <code>Promise</code> and is the only means to resolve or reject the 55061cb0ef41Sopenharmony_ci<code>Promise</code> using <code>napi_resolve_deferred()</code> or <code>napi_reject_deferred()</code>. The 55071cb0ef41Sopenharmony_cideferred object that is created by <code>napi_create_promise()</code> is freed by 55081cb0ef41Sopenharmony_ci<code>napi_resolve_deferred()</code> or <code>napi_reject_deferred()</code>. The <code>Promise</code> object may 55091cb0ef41Sopenharmony_cibe returned to JavaScript where it can be used in the usual fashion.</p> 55101cb0ef41Sopenharmony_ci<p>For example, to create a promise and pass it to an asynchronous worker:</p> 55111cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_deferred deferred; 55121cb0ef41Sopenharmony_cinapi_value promise; 55131cb0ef41Sopenharmony_cinapi_status status; 55141cb0ef41Sopenharmony_ci 55151cb0ef41Sopenharmony_ci<span class="hljs-comment">// Create the promise.</span> 55161cb0ef41Sopenharmony_cistatus = napi_create_promise(env, &deferred, &promise); 55171cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 55181cb0ef41Sopenharmony_ci 55191cb0ef41Sopenharmony_ci<span class="hljs-comment">// Pass the deferred to a function that performs an asynchronous action.</span> 55201cb0ef41Sopenharmony_cido_something_asynchronous(deferred); 55211cb0ef41Sopenharmony_ci 55221cb0ef41Sopenharmony_ci<span class="hljs-comment">// Return the promise to JS</span> 55231cb0ef41Sopenharmony_ci<span class="hljs-keyword">return</span> promise;</code> <button class="copy-button">copy</button></pre> 55241cb0ef41Sopenharmony_ci<p>The above function <code>do_something_asynchronous()</code> would perform its asynchronous 55251cb0ef41Sopenharmony_ciaction and then it would resolve or reject the deferred, thereby concluding the 55261cb0ef41Sopenharmony_cipromise and freeing the deferred:</p> 55271cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_deferred deferred; 55281cb0ef41Sopenharmony_cinapi_value undefined; 55291cb0ef41Sopenharmony_cinapi_status status; 55301cb0ef41Sopenharmony_ci 55311cb0ef41Sopenharmony_ci<span class="hljs-comment">// Create a value with which to conclude the deferred.</span> 55321cb0ef41Sopenharmony_cistatus = napi_get_undefined(env, &undefined); 55331cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 55341cb0ef41Sopenharmony_ci 55351cb0ef41Sopenharmony_ci<span class="hljs-comment">// Resolve or reject the promise associated with the deferred depending on</span> 55361cb0ef41Sopenharmony_ci<span class="hljs-comment">// whether the asynchronous action succeeded.</span> 55371cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (asynchronous_action_succeeded) { 55381cb0ef41Sopenharmony_ci status = napi_resolve_deferred(env, deferred, undefined); 55391cb0ef41Sopenharmony_ci} <span class="hljs-keyword">else</span> { 55401cb0ef41Sopenharmony_ci status = napi_reject_deferred(env, deferred, undefined); 55411cb0ef41Sopenharmony_ci} 55421cb0ef41Sopenharmony_ci<span class="hljs-keyword">if</span> (status != napi_ok) <span class="hljs-keyword">return</span> <span class="hljs-literal">NULL</span>; 55431cb0ef41Sopenharmony_ci 55441cb0ef41Sopenharmony_ci<span class="hljs-comment">// At this point the deferred has been freed, so we should assign NULL to it.</span> 55451cb0ef41Sopenharmony_cideferred = <span class="hljs-literal">NULL</span>;</code> <button class="copy-button">copy</button></pre> 55461cb0ef41Sopenharmony_ci<h4><code>napi_create_promise</code><span><a class="mark" href="#napi_create_promise" id="napi_create_promise">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_promise"></a></h4> 55471cb0ef41Sopenharmony_ci<div class="api_metadata"> 55481cb0ef41Sopenharmony_ci<span>Added in: v8.5.0</span> 55491cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 55501cb0ef41Sopenharmony_ci</div> 55511cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_create_promise</span><span class="hljs-params">(napi_env env, 55521cb0ef41Sopenharmony_ci napi_deferred* deferred, 55531cb0ef41Sopenharmony_ci napi_value* promise)</span>;</code> <button class="copy-button">copy</button></pre> 55541cb0ef41Sopenharmony_ci<ul> 55551cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 55561cb0ef41Sopenharmony_ci<li><code>[out] deferred</code>: A newly created deferred object which can later be passed to 55571cb0ef41Sopenharmony_ci<code>napi_resolve_deferred()</code> or <code>napi_reject_deferred()</code> to resolve resp. reject 55581cb0ef41Sopenharmony_cithe associated promise.</li> 55591cb0ef41Sopenharmony_ci<li><code>[out] promise</code>: The JavaScript promise associated with the deferred object.</li> 55601cb0ef41Sopenharmony_ci</ul> 55611cb0ef41Sopenharmony_ci<p>Returns <code>napi_ok</code> if the API succeeded.</p> 55621cb0ef41Sopenharmony_ci<p>This API creates a deferred object and a JavaScript promise.</p> 55631cb0ef41Sopenharmony_ci<h4><code>napi_resolve_deferred</code><span><a class="mark" href="#napi_resolve_deferred" id="napi_resolve_deferred">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_resolve_deferred"></a></h4> 55641cb0ef41Sopenharmony_ci<div class="api_metadata"> 55651cb0ef41Sopenharmony_ci<span>Added in: v8.5.0</span> 55661cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 55671cb0ef41Sopenharmony_ci</div> 55681cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_resolve_deferred</span><span class="hljs-params">(napi_env env, 55691cb0ef41Sopenharmony_ci napi_deferred deferred, 55701cb0ef41Sopenharmony_ci napi_value resolution)</span>;</code> <button class="copy-button">copy</button></pre> 55711cb0ef41Sopenharmony_ci<ul> 55721cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 55731cb0ef41Sopenharmony_ci<li><code>[in] deferred</code>: The deferred object whose associated promise to resolve.</li> 55741cb0ef41Sopenharmony_ci<li><code>[in] resolution</code>: The value with which to resolve the promise.</li> 55751cb0ef41Sopenharmony_ci</ul> 55761cb0ef41Sopenharmony_ci<p>This API resolves a JavaScript promise by way of the deferred object 55771cb0ef41Sopenharmony_ciwith which it is associated. Thus, it can only be used to resolve JavaScript 55781cb0ef41Sopenharmony_cipromises for which the corresponding deferred object is available. This 55791cb0ef41Sopenharmony_cieffectively means that the promise must have been created using 55801cb0ef41Sopenharmony_ci<code>napi_create_promise()</code> and the deferred object returned from that call must 55811cb0ef41Sopenharmony_cihave been retained in order to be passed to this API.</p> 55821cb0ef41Sopenharmony_ci<p>The deferred object is freed upon successful completion.</p> 55831cb0ef41Sopenharmony_ci<h4><code>napi_reject_deferred</code><span><a class="mark" href="#napi_reject_deferred" id="napi_reject_deferred">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_reject_deferred"></a></h4> 55841cb0ef41Sopenharmony_ci<div class="api_metadata"> 55851cb0ef41Sopenharmony_ci<span>Added in: v8.5.0</span> 55861cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 55871cb0ef41Sopenharmony_ci</div> 55881cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_reject_deferred</span><span class="hljs-params">(napi_env env, 55891cb0ef41Sopenharmony_ci napi_deferred deferred, 55901cb0ef41Sopenharmony_ci napi_value rejection)</span>;</code> <button class="copy-button">copy</button></pre> 55911cb0ef41Sopenharmony_ci<ul> 55921cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 55931cb0ef41Sopenharmony_ci<li><code>[in] deferred</code>: The deferred object whose associated promise to resolve.</li> 55941cb0ef41Sopenharmony_ci<li><code>[in] rejection</code>: The value with which to reject the promise.</li> 55951cb0ef41Sopenharmony_ci</ul> 55961cb0ef41Sopenharmony_ci<p>This API rejects a JavaScript promise by way of the deferred object 55971cb0ef41Sopenharmony_ciwith which it is associated. Thus, it can only be used to reject JavaScript 55981cb0ef41Sopenharmony_cipromises for which the corresponding deferred object is available. This 55991cb0ef41Sopenharmony_cieffectively means that the promise must have been created using 56001cb0ef41Sopenharmony_ci<code>napi_create_promise()</code> and the deferred object returned from that call must 56011cb0ef41Sopenharmony_cihave been retained in order to be passed to this API.</p> 56021cb0ef41Sopenharmony_ci<p>The deferred object is freed upon successful completion.</p> 56031cb0ef41Sopenharmony_ci<h4><code>napi_is_promise</code><span><a class="mark" href="#napi_is_promise" id="napi_is_promise">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_is_promise"></a></h4> 56041cb0ef41Sopenharmony_ci<div class="api_metadata"> 56051cb0ef41Sopenharmony_ci<span>Added in: v8.5.0</span> 56061cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 56071cb0ef41Sopenharmony_ci</div> 56081cb0ef41Sopenharmony_ci<pre><code class="language-c">napi_status <span class="hljs-title function_">napi_is_promise</span><span class="hljs-params">(napi_env env, 56091cb0ef41Sopenharmony_ci napi_value value, 56101cb0ef41Sopenharmony_ci <span class="hljs-type">bool</span>* is_promise)</span>;</code> <button class="copy-button">copy</button></pre> 56111cb0ef41Sopenharmony_ci<ul> 56121cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 56131cb0ef41Sopenharmony_ci<li><code>[in] value</code>: The value to examine</li> 56141cb0ef41Sopenharmony_ci<li><code>[out] is_promise</code>: Flag indicating whether <code>promise</code> is a native promise 56151cb0ef41Sopenharmony_ciobject (that is, a promise object created by the underlying engine).</li> 56161cb0ef41Sopenharmony_ci</ul> 56171cb0ef41Sopenharmony_ci</section><section><h3>Script execution<span><a class="mark" href="#script-execution" id="script-execution">#</a></span><a aria-hidden="true" class="legacy" id="n_api_script_execution"></a></h3> 56181cb0ef41Sopenharmony_ci<p>Node-API provides an API for executing a string containing JavaScript using the 56191cb0ef41Sopenharmony_ciunderlying JavaScript engine.</p> 56201cb0ef41Sopenharmony_ci<h4><code>napi_run_script</code><span><a class="mark" href="#napi_run_script" id="napi_run_script">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_run_script"></a></h4> 56211cb0ef41Sopenharmony_ci<div class="api_metadata"> 56221cb0ef41Sopenharmony_ci<span>Added in: v8.5.0</span> 56231cb0ef41Sopenharmony_ci<span>N-API version: 1</span> 56241cb0ef41Sopenharmony_ci</div> 56251cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_run_script</span><span class="hljs-params">(napi_env env, 56261cb0ef41Sopenharmony_ci napi_value script, 56271cb0ef41Sopenharmony_ci napi_value* result)</span>;</code> <button class="copy-button">copy</button></pre> 56281cb0ef41Sopenharmony_ci<ul> 56291cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 56301cb0ef41Sopenharmony_ci<li><code>[in] script</code>: A JavaScript string containing the script to execute.</li> 56311cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The value resulting from having executed the script.</li> 56321cb0ef41Sopenharmony_ci</ul> 56331cb0ef41Sopenharmony_ci<p>This function executes a string of JavaScript code and returns its result with 56341cb0ef41Sopenharmony_cithe following caveats:</p> 56351cb0ef41Sopenharmony_ci<ul> 56361cb0ef41Sopenharmony_ci<li>Unlike <code>eval</code>, this function does not allow the script to access the current 56371cb0ef41Sopenharmony_cilexical scope, and therefore also does not allow to access the 56381cb0ef41Sopenharmony_ci<a href="modules.html#the-module-scope">module scope</a>, meaning that pseudo-globals such as <code>require</code> will not be 56391cb0ef41Sopenharmony_ciavailable.</li> 56401cb0ef41Sopenharmony_ci<li>The script can access the <a href="globals.html">global scope</a>. Function and <code>var</code> declarations 56411cb0ef41Sopenharmony_ciin the script will be added to the <a href="globals.html#global"><code>global</code></a> object. Variable declarations 56421cb0ef41Sopenharmony_cimade using <code>let</code> and <code>const</code> will be visible globally, but will not be added 56431cb0ef41Sopenharmony_cito the <a href="globals.html#global"><code>global</code></a> object.</li> 56441cb0ef41Sopenharmony_ci<li>The value of <code>this</code> is <a href="globals.html#global"><code>global</code></a> within the script.</li> 56451cb0ef41Sopenharmony_ci</ul> 56461cb0ef41Sopenharmony_ci</section><section><h3>libuv event loop<span><a class="mark" href="#libuv-event-loop" id="libuv-event-loop">#</a></span><a aria-hidden="true" class="legacy" id="n_api_libuv_event_loop"></a></h3> 56471cb0ef41Sopenharmony_ci<p>Node-API provides a function for getting the current event loop associated with 56481cb0ef41Sopenharmony_cia specific <code>napi_env</code>.</p> 56491cb0ef41Sopenharmony_ci<h4><code>napi_get_uv_event_loop</code><span><a class="mark" href="#napi_get_uv_event_loop" id="napi_get_uv_event_loop">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_uv_event_loop"></a></h4> 56501cb0ef41Sopenharmony_ci<div class="api_metadata"> 56511cb0ef41Sopenharmony_ci<span>Added in: v9.3.0, v8.10.0</span> 56521cb0ef41Sopenharmony_ci<span>N-API version: 2</span> 56531cb0ef41Sopenharmony_ci</div> 56541cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status <span class="hljs-title function_">napi_get_uv_event_loop</span><span class="hljs-params">(node_api_nogc_env env, 56551cb0ef41Sopenharmony_ci <span class="hljs-keyword">struct</span> uv_loop_s** loop)</span>;</code> <button class="copy-button">copy</button></pre> 56561cb0ef41Sopenharmony_ci<ul> 56571cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 56581cb0ef41Sopenharmony_ci<li><code>[out] loop</code>: The current libuv loop instance.</li> 56591cb0ef41Sopenharmony_ci</ul> 56601cb0ef41Sopenharmony_ci</section><section><h3>Asynchronous thread-safe function calls<span><a class="mark" href="#asynchronous-thread-safe-function-calls" id="asynchronous-thread-safe-function-calls">#</a></span><a aria-hidden="true" class="legacy" id="n_api_asynchronous_thread_safe_function_calls"></a></h3> 56611cb0ef41Sopenharmony_ci<p>JavaScript functions can normally only be called from a native addon's main 56621cb0ef41Sopenharmony_cithread. If an addon creates additional threads, then Node-API functions that 56631cb0ef41Sopenharmony_cirequire a <code>napi_env</code>, <code>napi_value</code>, or <code>napi_ref</code> must not be called from those 56641cb0ef41Sopenharmony_cithreads.</p> 56651cb0ef41Sopenharmony_ci<p>When an addon has additional threads and JavaScript functions need to be invoked 56661cb0ef41Sopenharmony_cibased on the processing completed by those threads, those threads must 56671cb0ef41Sopenharmony_cicommunicate with the addon's main thread so that the main thread can invoke the 56681cb0ef41Sopenharmony_ciJavaScript function on their behalf. The thread-safe function APIs provide an 56691cb0ef41Sopenharmony_cieasy way to do this.</p> 56701cb0ef41Sopenharmony_ci<p>These APIs provide the type <code>napi_threadsafe_function</code> as well as APIs to 56711cb0ef41Sopenharmony_cicreate, destroy, and call objects of this type. 56721cb0ef41Sopenharmony_ci<code>napi_create_threadsafe_function()</code> creates a persistent reference to a 56731cb0ef41Sopenharmony_ci<code>napi_value</code> that holds a JavaScript function which can be called from multiple 56741cb0ef41Sopenharmony_cithreads. The calls happen asynchronously. This means that values with which the 56751cb0ef41Sopenharmony_ciJavaScript callback is to be called will be placed in a queue, and, for each 56761cb0ef41Sopenharmony_civalue in the queue, a call will eventually be made to the JavaScript function.</p> 56771cb0ef41Sopenharmony_ci<p>Upon creation of a <code>napi_threadsafe_function</code> a <code>napi_finalize</code> callback can be 56781cb0ef41Sopenharmony_ciprovided. This callback will be invoked on the main thread when the thread-safe 56791cb0ef41Sopenharmony_cifunction is about to be destroyed. It receives the context and the finalize data 56801cb0ef41Sopenharmony_cigiven during construction, and provides an opportunity for cleaning up after the 56811cb0ef41Sopenharmony_cithreads e.g. by calling <code>uv_thread_join()</code>. <strong>Aside from the main loop thread, 56821cb0ef41Sopenharmony_cino threads should be using the thread-safe function after the finalize callback 56831cb0ef41Sopenharmony_cicompletes.</strong></p> 56841cb0ef41Sopenharmony_ci<p>The <code>context</code> given during the call to <code>napi_create_threadsafe_function()</code> can 56851cb0ef41Sopenharmony_cibe retrieved from any thread with a call to 56861cb0ef41Sopenharmony_ci<code>napi_get_threadsafe_function_context()</code>.</p> 56871cb0ef41Sopenharmony_ci<h4>Calling a thread-safe function<span><a class="mark" href="#calling-a-thread-safe-function" id="calling-a-thread-safe-function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_calling_a_thread_safe_function"></a></h4> 56881cb0ef41Sopenharmony_ci<p><code>napi_call_threadsafe_function()</code> can be used for initiating a call into 56891cb0ef41Sopenharmony_ciJavaScript. <code>napi_call_threadsafe_function()</code> accepts a parameter which controls 56901cb0ef41Sopenharmony_ciwhether the API behaves blockingly. If set to <code>napi_tsfn_nonblocking</code>, the API 56911cb0ef41Sopenharmony_cibehaves non-blockingly, returning <code>napi_queue_full</code> if the queue was full, 56921cb0ef41Sopenharmony_cipreventing data from being successfully added to the queue. If set to 56931cb0ef41Sopenharmony_ci<code>napi_tsfn_blocking</code>, the API blocks until space becomes available in the queue. 56941cb0ef41Sopenharmony_ci<code>napi_call_threadsafe_function()</code> never blocks if the thread-safe function was 56951cb0ef41Sopenharmony_cicreated with a maximum queue size of 0.</p> 56961cb0ef41Sopenharmony_ci<p><code>napi_call_threadsafe_function()</code> should not be called with <code>napi_tsfn_blocking</code> 56971cb0ef41Sopenharmony_cifrom a JavaScript thread, because, if the queue is full, it may cause the 56981cb0ef41Sopenharmony_ciJavaScript thread to deadlock.</p> 56991cb0ef41Sopenharmony_ci<p>The actual call into JavaScript is controlled by the callback given via the 57001cb0ef41Sopenharmony_ci<code>call_js_cb</code> parameter. <code>call_js_cb</code> is invoked on the main thread once for each 57011cb0ef41Sopenharmony_civalue that was placed into the queue by a successful call to 57021cb0ef41Sopenharmony_ci<code>napi_call_threadsafe_function()</code>. If such a callback is not given, a default 57031cb0ef41Sopenharmony_cicallback will be used, and the resulting JavaScript call will have no arguments. 57041cb0ef41Sopenharmony_ciThe <code>call_js_cb</code> callback receives the JavaScript function to call as a 57051cb0ef41Sopenharmony_ci<code>napi_value</code> in its parameters, as well as the <code>void*</code> context pointer used when 57061cb0ef41Sopenharmony_cicreating the <code>napi_threadsafe_function</code>, and the next data pointer that was 57071cb0ef41Sopenharmony_cicreated by one of the secondary threads. The callback can then use an API such 57081cb0ef41Sopenharmony_cias <code>napi_call_function()</code> to call into JavaScript.</p> 57091cb0ef41Sopenharmony_ci<p>The callback may also be invoked with <code>env</code> and <code>call_js_cb</code> both set to <code>NULL</code> 57101cb0ef41Sopenharmony_cito indicate that calls into JavaScript are no longer possible, while items 57111cb0ef41Sopenharmony_ciremain in the queue that may need to be freed. This normally occurs when the 57121cb0ef41Sopenharmony_ciNode.js process exits while there is a thread-safe function still active.</p> 57131cb0ef41Sopenharmony_ci<p>It is not necessary to call into JavaScript via <code>napi_make_callback()</code> because 57141cb0ef41Sopenharmony_ciNode-API runs <code>call_js_cb</code> in a context appropriate for callbacks.</p> 57151cb0ef41Sopenharmony_ci<p>Zero or more queued items may be invoked in each tick of the event loop. 57161cb0ef41Sopenharmony_ciApplications should not depend on a specific behavior other than progress in 57171cb0ef41Sopenharmony_ciinvoking callbacks will be made and events will be invoked 57181cb0ef41Sopenharmony_cias time moves forward.</p> 57191cb0ef41Sopenharmony_ci<h4>Reference counting of thread-safe functions<span><a class="mark" href="#reference-counting-of-thread-safe-functions" id="reference-counting-of-thread-safe-functions">#</a></span><a aria-hidden="true" class="legacy" id="n_api_reference_counting_of_thread_safe_functions"></a></h4> 57201cb0ef41Sopenharmony_ci<p>Threads can be added to and removed from a <code>napi_threadsafe_function</code> object 57211cb0ef41Sopenharmony_ciduring its existence. Thus, in addition to specifying an initial number of 57221cb0ef41Sopenharmony_cithreads upon creation, <code>napi_acquire_threadsafe_function</code> can be called to 57231cb0ef41Sopenharmony_ciindicate that a new thread will start making use of the thread-safe function. 57241cb0ef41Sopenharmony_ciSimilarly, <code>napi_release_threadsafe_function</code> can be called to indicate that an 57251cb0ef41Sopenharmony_ciexisting thread will stop making use of the thread-safe function.</p> 57261cb0ef41Sopenharmony_ci<p><code>napi_threadsafe_function</code> objects are destroyed when every thread which uses 57271cb0ef41Sopenharmony_cithe object has called <code>napi_release_threadsafe_function()</code> or has received a 57281cb0ef41Sopenharmony_cireturn status of <code>napi_closing</code> in response to a call to 57291cb0ef41Sopenharmony_ci<code>napi_call_threadsafe_function</code>. The queue is emptied before the 57301cb0ef41Sopenharmony_ci<code>napi_threadsafe_function</code> is destroyed. <code>napi_release_threadsafe_function()</code> 57311cb0ef41Sopenharmony_cishould be the last API call made in conjunction with a given 57321cb0ef41Sopenharmony_ci<code>napi_threadsafe_function</code>, because after the call completes, there is no 57331cb0ef41Sopenharmony_ciguarantee that the <code>napi_threadsafe_function</code> is still allocated. For the same 57341cb0ef41Sopenharmony_cireason, do not use a thread-safe function 57351cb0ef41Sopenharmony_ciafter receiving a return value of <code>napi_closing</code> in response to a call to 57361cb0ef41Sopenharmony_ci<code>napi_call_threadsafe_function</code>. Data associated with the 57371cb0ef41Sopenharmony_ci<code>napi_threadsafe_function</code> can be freed in its <code>napi_finalize</code> callback which 57381cb0ef41Sopenharmony_ciwas passed to <code>napi_create_threadsafe_function()</code>. The parameter 57391cb0ef41Sopenharmony_ci<code>initial_thread_count</code> of <code>napi_create_threadsafe_function</code> marks the initial 57401cb0ef41Sopenharmony_cinumber of acquisitions of the thread-safe functions, instead of calling 57411cb0ef41Sopenharmony_ci<code>napi_acquire_threadsafe_function</code> multiple times at creation.</p> 57421cb0ef41Sopenharmony_ci<p>Once the number of threads making use of a <code>napi_threadsafe_function</code> reaches 57431cb0ef41Sopenharmony_cizero, no further threads can start making use of it by calling 57441cb0ef41Sopenharmony_ci<code>napi_acquire_threadsafe_function()</code>. In fact, all subsequent API calls 57451cb0ef41Sopenharmony_ciassociated with it, except <code>napi_release_threadsafe_function()</code>, will return an 57461cb0ef41Sopenharmony_cierror value of <code>napi_closing</code>.</p> 57471cb0ef41Sopenharmony_ci<p>The thread-safe function can be "aborted" by giving a value of <code>napi_tsfn_abort</code> 57481cb0ef41Sopenharmony_cito <code>napi_release_threadsafe_function()</code>. This will cause all subsequent APIs 57491cb0ef41Sopenharmony_ciassociated with the thread-safe function except 57501cb0ef41Sopenharmony_ci<code>napi_release_threadsafe_function()</code> to return <code>napi_closing</code> even before its 57511cb0ef41Sopenharmony_cireference count reaches zero. In particular, <code>napi_call_threadsafe_function()</code> 57521cb0ef41Sopenharmony_ciwill return <code>napi_closing</code>, thus informing the threads that it is no longer 57531cb0ef41Sopenharmony_cipossible to make asynchronous calls to the thread-safe function. This can be 57541cb0ef41Sopenharmony_ciused as a criterion for terminating the thread. <strong>Upon receiving a return value 57551cb0ef41Sopenharmony_ciof <code>napi_closing</code> from <code>napi_call_threadsafe_function()</code> a thread must not use 57561cb0ef41Sopenharmony_cithe thread-safe function anymore because it is no longer guaranteed to 57571cb0ef41Sopenharmony_cibe allocated.</strong></p> 57581cb0ef41Sopenharmony_ci<h4>Deciding whether to keep the process running<span><a class="mark" href="#deciding-whether-to-keep-the-process-running" id="deciding-whether-to-keep-the-process-running">#</a></span><a aria-hidden="true" class="legacy" id="n_api_deciding_whether_to_keep_the_process_running"></a></h4> 57591cb0ef41Sopenharmony_ci<p>Similarly to libuv handles, thread-safe functions can be "referenced" and 57601cb0ef41Sopenharmony_ci"unreferenced". A "referenced" thread-safe function will cause the event loop on 57611cb0ef41Sopenharmony_cithe thread on which it is created to remain alive until the thread-safe function 57621cb0ef41Sopenharmony_ciis destroyed. In contrast, an "unreferenced" thread-safe function will not 57631cb0ef41Sopenharmony_ciprevent the event loop from exiting. The APIs <code>napi_ref_threadsafe_function</code> and 57641cb0ef41Sopenharmony_ci<code>napi_unref_threadsafe_function</code> exist for this purpose.</p> 57651cb0ef41Sopenharmony_ci<p>Neither does <code>napi_unref_threadsafe_function</code> mark the thread-safe functions as 57661cb0ef41Sopenharmony_ciable to be destroyed nor does <code>napi_ref_threadsafe_function</code> prevent it from 57671cb0ef41Sopenharmony_cibeing destroyed.</p> 57681cb0ef41Sopenharmony_ci<h4><code>napi_create_threadsafe_function</code><span><a class="mark" href="#napi_create_threadsafe_function" id="napi_create_threadsafe_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_create_threadsafe_function"></a></h4> 57691cb0ef41Sopenharmony_ci<div class="api_metadata"> 57701cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 57711cb0ef41Sopenharmony_ci<table> 57721cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 57731cb0ef41Sopenharmony_ci<tr><td>v12.6.0, v10.17.0</td> 57741cb0ef41Sopenharmony_ci<td><p>Made <code>func</code> parameter optional with custom <code>call_js_cb</code>.</p></td></tr> 57751cb0ef41Sopenharmony_ci<tr><td>v10.6.0</td> 57761cb0ef41Sopenharmony_ci<td><p><span>Added in: v10.6.0</span></p></td></tr> 57771cb0ef41Sopenharmony_ci</tbody></table> 57781cb0ef41Sopenharmony_ci</details> 57791cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 57801cb0ef41Sopenharmony_ci</div> 57811cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 57821cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_create_threadsafe_function</span><span class="hljs-params">(napi_env env, 57831cb0ef41Sopenharmony_ci napi_value func, 57841cb0ef41Sopenharmony_ci napi_value async_resource, 57851cb0ef41Sopenharmony_ci napi_value async_resource_name, 57861cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> max_queue_size, 57871cb0ef41Sopenharmony_ci <span class="hljs-type">size_t</span> initial_thread_count, 57881cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* thread_finalize_data, 57891cb0ef41Sopenharmony_ci napi_finalize thread_finalize_cb, 57901cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* context, 57911cb0ef41Sopenharmony_ci napi_threadsafe_function_call_js call_js_cb, 57921cb0ef41Sopenharmony_ci napi_threadsafe_function* result)</span>;</code> <button class="copy-button">copy</button></pre> 57931cb0ef41Sopenharmony_ci<ul> 57941cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 57951cb0ef41Sopenharmony_ci<li><code>[in] func</code>: An optional JavaScript function to call from another thread. It 57961cb0ef41Sopenharmony_cimust be provided if <code>NULL</code> is passed to <code>call_js_cb</code>.</li> 57971cb0ef41Sopenharmony_ci<li><code>[in] async_resource</code>: An optional object associated with the async work that 57981cb0ef41Sopenharmony_ciwill be passed to possible <code>async_hooks</code> <a href="async_hooks.html#initasyncid-type-triggerasyncid-resource"><code>init</code> hooks</a>.</li> 57991cb0ef41Sopenharmony_ci<li><code>[in] async_resource_name</code>: A JavaScript string to provide an identifier for 58001cb0ef41Sopenharmony_cithe kind of resource that is being provided for diagnostic information exposed 58011cb0ef41Sopenharmony_ciby the <code>async_hooks</code> API.</li> 58021cb0ef41Sopenharmony_ci<li><code>[in] max_queue_size</code>: Maximum size of the queue. <code>0</code> for no limit.</li> 58031cb0ef41Sopenharmony_ci<li><code>[in] initial_thread_count</code>: The initial number of acquisitions, i.e. the 58041cb0ef41Sopenharmony_ciinitial number of threads, including the main thread, which will be making use 58051cb0ef41Sopenharmony_ciof this function.</li> 58061cb0ef41Sopenharmony_ci<li><code>[in] thread_finalize_data</code>: Optional data to be passed to <code>thread_finalize_cb</code>.</li> 58071cb0ef41Sopenharmony_ci<li><code>[in] thread_finalize_cb</code>: Optional function to call when the 58081cb0ef41Sopenharmony_ci<code>napi_threadsafe_function</code> is being destroyed.</li> 58091cb0ef41Sopenharmony_ci<li><code>[in] context</code>: Optional data to attach to the resulting 58101cb0ef41Sopenharmony_ci<code>napi_threadsafe_function</code>.</li> 58111cb0ef41Sopenharmony_ci<li><code>[in] call_js_cb</code>: Optional callback which calls the JavaScript function in 58121cb0ef41Sopenharmony_ciresponse to a call on a different thread. This callback will be called on the 58131cb0ef41Sopenharmony_cimain thread. If not given, the JavaScript function will be called with no 58141cb0ef41Sopenharmony_ciparameters and with <code>undefined</code> as its <code>this</code> value. 58151cb0ef41Sopenharmony_ci<a href="#napi_threadsafe_function_call_js"><code>napi_threadsafe_function_call_js</code></a> provides more details.</li> 58161cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The asynchronous thread-safe JavaScript function.</li> 58171cb0ef41Sopenharmony_ci</ul> 58181cb0ef41Sopenharmony_ci<p><strong>Change History:</strong></p> 58191cb0ef41Sopenharmony_ci<ul> 58201cb0ef41Sopenharmony_ci<li> 58211cb0ef41Sopenharmony_ci<p>Experimental (<code>NAPI_EXPERIMENTAL</code> is defined):</p> 58221cb0ef41Sopenharmony_ci<p>Uncaught exceptions thrown in <code>call_js_cb</code> are handled with the 58231cb0ef41Sopenharmony_ci<a href="process.html#event-uncaughtexception"><code>'uncaughtException'</code></a> event, instead of being ignored.</p> 58241cb0ef41Sopenharmony_ci</li> 58251cb0ef41Sopenharmony_ci</ul> 58261cb0ef41Sopenharmony_ci<h4><code>napi_get_threadsafe_function_context</code><span><a class="mark" href="#napi_get_threadsafe_function_context" id="napi_get_threadsafe_function_context">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_get_threadsafe_function_context"></a></h4> 58271cb0ef41Sopenharmony_ci<div class="api_metadata"> 58281cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 58291cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 58301cb0ef41Sopenharmony_ci</div> 58311cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 58321cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_get_threadsafe_function_context</span><span class="hljs-params">(napi_threadsafe_function func, 58331cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>** result)</span>;</code> <button class="copy-button">copy</button></pre> 58341cb0ef41Sopenharmony_ci<ul> 58351cb0ef41Sopenharmony_ci<li><code>[in] func</code>: The thread-safe function for which to retrieve the context.</li> 58361cb0ef41Sopenharmony_ci<li><code>[out] result</code>: The location where to store the context.</li> 58371cb0ef41Sopenharmony_ci</ul> 58381cb0ef41Sopenharmony_ci<p>This API may be called from any thread which makes use of <code>func</code>.</p> 58391cb0ef41Sopenharmony_ci<h4><code>napi_call_threadsafe_function</code><span><a class="mark" href="#napi_call_threadsafe_function" id="napi_call_threadsafe_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_call_threadsafe_function"></a></h4> 58401cb0ef41Sopenharmony_ci<div class="api_metadata"> 58411cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 58421cb0ef41Sopenharmony_ci<table> 58431cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 58441cb0ef41Sopenharmony_ci<tr><td>v14.5.0</td> 58451cb0ef41Sopenharmony_ci<td><p>Support for <code>napi_would_deadlock</code> has been reverted.</p></td></tr> 58461cb0ef41Sopenharmony_ci<tr><td>v14.1.0</td> 58471cb0ef41Sopenharmony_ci<td><p>Return <code>napi_would_deadlock</code> when called with <code>napi_tsfn_blocking</code> from the main thread or a worker thread and the queue is full.</p></td></tr> 58481cb0ef41Sopenharmony_ci<tr><td>v10.6.0</td> 58491cb0ef41Sopenharmony_ci<td><p><span>Added in: v10.6.0</span></p></td></tr> 58501cb0ef41Sopenharmony_ci</tbody></table> 58511cb0ef41Sopenharmony_ci</details> 58521cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 58531cb0ef41Sopenharmony_ci</div> 58541cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 58551cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_call_threadsafe_function</span><span class="hljs-params">(napi_threadsafe_function func, 58561cb0ef41Sopenharmony_ci <span class="hljs-type">void</span>* data, 58571cb0ef41Sopenharmony_ci napi_threadsafe_function_call_mode is_blocking)</span>;</code> <button class="copy-button">copy</button></pre> 58581cb0ef41Sopenharmony_ci<ul> 58591cb0ef41Sopenharmony_ci<li><code>[in] func</code>: The asynchronous thread-safe JavaScript function to invoke.</li> 58601cb0ef41Sopenharmony_ci<li><code>[in] data</code>: Data to send into JavaScript via the callback <code>call_js_cb</code> 58611cb0ef41Sopenharmony_ciprovided during the creation of the thread-safe JavaScript function.</li> 58621cb0ef41Sopenharmony_ci<li><code>[in] is_blocking</code>: Flag whose value can be either <code>napi_tsfn_blocking</code> to 58631cb0ef41Sopenharmony_ciindicate that the call should block if the queue is full or 58641cb0ef41Sopenharmony_ci<code>napi_tsfn_nonblocking</code> to indicate that the call should return immediately 58651cb0ef41Sopenharmony_ciwith a status of <code>napi_queue_full</code> whenever the queue is full.</li> 58661cb0ef41Sopenharmony_ci</ul> 58671cb0ef41Sopenharmony_ci<p>This API should not be called with <code>napi_tsfn_blocking</code> from a JavaScript 58681cb0ef41Sopenharmony_cithread, because, if the queue is full, it may cause the JavaScript thread to 58691cb0ef41Sopenharmony_cideadlock.</p> 58701cb0ef41Sopenharmony_ci<p>This API will return <code>napi_closing</code> if <code>napi_release_threadsafe_function()</code> was 58711cb0ef41Sopenharmony_cicalled with <code>abort</code> set to <code>napi_tsfn_abort</code> from any thread. The value is only 58721cb0ef41Sopenharmony_ciadded to the queue if the API returns <code>napi_ok</code>.</p> 58731cb0ef41Sopenharmony_ci<p>This API may be called from any thread which makes use of <code>func</code>.</p> 58741cb0ef41Sopenharmony_ci<h4><code>napi_acquire_threadsafe_function</code><span><a class="mark" href="#napi_acquire_threadsafe_function" id="napi_acquire_threadsafe_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_acquire_threadsafe_function"></a></h4> 58751cb0ef41Sopenharmony_ci<div class="api_metadata"> 58761cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 58771cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 58781cb0ef41Sopenharmony_ci</div> 58791cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 58801cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_acquire_threadsafe_function</span><span class="hljs-params">(napi_threadsafe_function func)</span>;</code> <button class="copy-button">copy</button></pre> 58811cb0ef41Sopenharmony_ci<ul> 58821cb0ef41Sopenharmony_ci<li><code>[in] func</code>: The asynchronous thread-safe JavaScript function to start making 58831cb0ef41Sopenharmony_ciuse of.</li> 58841cb0ef41Sopenharmony_ci</ul> 58851cb0ef41Sopenharmony_ci<p>A thread should call this API before passing <code>func</code> to any other thread-safe 58861cb0ef41Sopenharmony_cifunction APIs to indicate that it will be making use of <code>func</code>. This prevents 58871cb0ef41Sopenharmony_ci<code>func</code> from being destroyed when all other threads have stopped making use of 58881cb0ef41Sopenharmony_ciit.</p> 58891cb0ef41Sopenharmony_ci<p>This API may be called from any thread which will start making use of <code>func</code>.</p> 58901cb0ef41Sopenharmony_ci<h4><code>napi_release_threadsafe_function</code><span><a class="mark" href="#napi_release_threadsafe_function" id="napi_release_threadsafe_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_release_threadsafe_function"></a></h4> 58911cb0ef41Sopenharmony_ci<div class="api_metadata"> 58921cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 58931cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 58941cb0ef41Sopenharmony_ci</div> 58951cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 58961cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_release_threadsafe_function</span><span class="hljs-params">(napi_threadsafe_function func, 58971cb0ef41Sopenharmony_ci napi_threadsafe_function_release_mode mode)</span>;</code> <button class="copy-button">copy</button></pre> 58981cb0ef41Sopenharmony_ci<ul> 58991cb0ef41Sopenharmony_ci<li><code>[in] func</code>: The asynchronous thread-safe JavaScript function whose reference 59001cb0ef41Sopenharmony_cicount to decrement.</li> 59011cb0ef41Sopenharmony_ci<li><code>[in] mode</code>: Flag whose value can be either <code>napi_tsfn_release</code> to indicate 59021cb0ef41Sopenharmony_cithat the current thread will make no further calls to the thread-safe 59031cb0ef41Sopenharmony_cifunction, or <code>napi_tsfn_abort</code> to indicate that in addition to the current 59041cb0ef41Sopenharmony_cithread, no other thread should make any further calls to the thread-safe 59051cb0ef41Sopenharmony_cifunction. If set to <code>napi_tsfn_abort</code>, further calls to 59061cb0ef41Sopenharmony_ci<code>napi_call_threadsafe_function()</code> will return <code>napi_closing</code>, and no further 59071cb0ef41Sopenharmony_civalues will be placed in the queue.</li> 59081cb0ef41Sopenharmony_ci</ul> 59091cb0ef41Sopenharmony_ci<p>A thread should call this API when it stops making use of <code>func</code>. Passing <code>func</code> 59101cb0ef41Sopenharmony_cito any thread-safe APIs after having called this API has undefined results, as 59111cb0ef41Sopenharmony_ci<code>func</code> may have been destroyed.</p> 59121cb0ef41Sopenharmony_ci<p>This API may be called from any thread which will stop making use of <code>func</code>.</p> 59131cb0ef41Sopenharmony_ci<h4><code>napi_ref_threadsafe_function</code><span><a class="mark" href="#napi_ref_threadsafe_function" id="napi_ref_threadsafe_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_ref_threadsafe_function"></a></h4> 59141cb0ef41Sopenharmony_ci<div class="api_metadata"> 59151cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 59161cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 59171cb0ef41Sopenharmony_ci</div> 59181cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 59191cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_ref_threadsafe_function</span><span class="hljs-params">(node_api_nogc_env env, napi_threadsafe_function func)</span>;</code> <button class="copy-button">copy</button></pre> 59201cb0ef41Sopenharmony_ci<ul> 59211cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 59221cb0ef41Sopenharmony_ci<li><code>[in] func</code>: The thread-safe function to reference.</li> 59231cb0ef41Sopenharmony_ci</ul> 59241cb0ef41Sopenharmony_ci<p>This API is used to indicate that the event loop running on the main thread 59251cb0ef41Sopenharmony_cishould not exit until <code>func</code> has been destroyed. Similar to <a href="https://docs.libuv.org/en/v1.x/handle.html#c.uv_ref"><code>uv_ref</code></a> it is 59261cb0ef41Sopenharmony_cialso idempotent.</p> 59271cb0ef41Sopenharmony_ci<p>Neither does <code>napi_unref_threadsafe_function</code> mark the thread-safe functions as 59281cb0ef41Sopenharmony_ciable to be destroyed nor does <code>napi_ref_threadsafe_function</code> prevent it from 59291cb0ef41Sopenharmony_cibeing destroyed. <code>napi_acquire_threadsafe_function</code> and 59301cb0ef41Sopenharmony_ci<code>napi_release_threadsafe_function</code> are available for that purpose.</p> 59311cb0ef41Sopenharmony_ci<p>This API may only be called from the main thread.</p> 59321cb0ef41Sopenharmony_ci<h4><code>napi_unref_threadsafe_function</code><span><a class="mark" href="#napi_unref_threadsafe_function" id="napi_unref_threadsafe_function">#</a></span><a aria-hidden="true" class="legacy" id="n_api_napi_unref_threadsafe_function"></a></h4> 59331cb0ef41Sopenharmony_ci<div class="api_metadata"> 59341cb0ef41Sopenharmony_ci<span>Added in: v10.6.0</span> 59351cb0ef41Sopenharmony_ci<span>N-API version: 4</span> 59361cb0ef41Sopenharmony_ci</div> 59371cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 59381cb0ef41Sopenharmony_ci<span class="hljs-title function_">napi_unref_threadsafe_function</span><span class="hljs-params">(node_api_nogc_env env, napi_threadsafe_function func)</span>;</code> <button class="copy-button">copy</button></pre> 59391cb0ef41Sopenharmony_ci<ul> 59401cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 59411cb0ef41Sopenharmony_ci<li><code>[in] func</code>: The thread-safe function to unreference.</li> 59421cb0ef41Sopenharmony_ci</ul> 59431cb0ef41Sopenharmony_ci<p>This API is used to indicate that the event loop running on the main thread 59441cb0ef41Sopenharmony_cimay exit before <code>func</code> is destroyed. Similar to <a href="https://docs.libuv.org/en/v1.x/handle.html#c.uv_unref"><code>uv_unref</code></a> it is also 59451cb0ef41Sopenharmony_ciidempotent.</p> 59461cb0ef41Sopenharmony_ci<p>This API may only be called from the main thread.</p> 59471cb0ef41Sopenharmony_ci</section><section><h3>Miscellaneous utilities<span><a class="mark" href="#miscellaneous-utilities" id="miscellaneous-utilities">#</a></span><a aria-hidden="true" class="legacy" id="n_api_miscellaneous_utilities"></a></h3> 59481cb0ef41Sopenharmony_ci<h4><code>node_api_get_module_file_name</code><span><a class="mark" href="#node_api_get_module_file_name" id="node_api_get_module_file_name">#</a></span><a aria-hidden="true" class="legacy" id="n_api_node_api_get_module_file_name"></a></h4> 59491cb0ef41Sopenharmony_ci<div class="api_metadata"> 59501cb0ef41Sopenharmony_ci<span>Added in: v15.9.0, v14.18.0, v12.22.0</span> 59511cb0ef41Sopenharmony_ci<span>N-API version: 9</span> 59521cb0ef41Sopenharmony_ci</div> 59531cb0ef41Sopenharmony_ci<pre><code class="language-c">NAPI_EXTERN napi_status 59541cb0ef41Sopenharmony_ci<span class="hljs-title function_">node_api_get_module_file_name</span><span class="hljs-params">(node_api_nogc_env env, <span class="hljs-type">const</span> <span class="hljs-type">char</span>** result)</span>; 59551cb0ef41Sopenharmony_ci</code> <button class="copy-button">copy</button></pre> 59561cb0ef41Sopenharmony_ci<ul> 59571cb0ef41Sopenharmony_ci<li><code>[in] env</code>: The environment that the API is invoked under.</li> 59581cb0ef41Sopenharmony_ci<li><code>[out] result</code>: A URL containing the absolute path of the 59591cb0ef41Sopenharmony_cilocation from which the add-on was loaded. For a file on the local 59601cb0ef41Sopenharmony_cifile system it will start with <code>file://</code>. The string is null-terminated and 59611cb0ef41Sopenharmony_ciowned by <code>env</code> and must thus not be modified or freed.</li> 59621cb0ef41Sopenharmony_ci</ul> 59631cb0ef41Sopenharmony_ci<p><code>result</code> may be an empty string if the add-on loading process fails to establish 59641cb0ef41Sopenharmony_cithe add-on's file name during loading.</p></section> 59651cb0ef41Sopenharmony_ci <!-- API END --> 59661cb0ef41Sopenharmony_ci </div> 59671cb0ef41Sopenharmony_ci </div> 59681cb0ef41Sopenharmony_ci </div> 59691cb0ef41Sopenharmony_ci</body> 59701cb0ef41Sopenharmony_ci</html> 5971