# NAPI - [Introduction](#section11660541593) - [Directory Structure](#section161941989596) - [When to Use](#section11759141594811) - [Available APIs](#section1611515555510) - [How to Develop](#section937267212) - [Repositories Involved](#section3970193518214) ## Introduction The **foundation/arkui/napi** repository contains a development framework for extending the JS Native Module and provides APIs developed based on Node.js N-API for external use. **Figure 1** Architecture ![](figures/en-us_image_0000001162437581.jpg) - **NativeEngine** NativeEngine is the JS engine abstraction layer. It unifies API behavior of the JS engines at the NAPI layer. - **ModuleManager** ModuleManager is used to load modules and cache module information. - **ScopeManager** ScopeManager manages the NativeValue lifecycle. - **ReferenceManager** ReferenceManager manages the NativeReference lifecycle. ## Directory Structure The source code directory structure of this repository is as follows: ``` foundation/arkui/napi ├── interfaces │ └── kits │ └── napi # NAPI header files ├── module_manager # Module manager ├── native_engine # NativeEngine abstraction layer │ └── impl │ └── ark # Ark-based NativeEngine implementation ├── scope_manager # Scope manager └── test # Test code ``` ## When to Use NAPI is suitable for processing I/O- and CPU-intensive tasks and system tasks. It encapsulates the capabilities and provides them to apps as JS APIs. NAPI can be used to implement mutual access between JS and C/C++ code. You can use NAPI to develop modules such as network communications, serial port access, multimedia decoding, and sensor data collection. ## Available APIs For details about the API implementation, see the **foundation/arkui/napi** repository. **Table 1** Available NAPIs

Category

Description

Module registration

Registers module information with a manager.

Exception & Error handling

Throws exceptions.

Object lifecycle

Manages NAPI object lifecycle within limited scopes.

JS object

Creates standard object types.

C-to-NAPI

Converts data types from C to NAPI.

NAPI-to-C

Converts data types from NAPI to C.

Global instance

Obtains global instances.

JS value

Provides APIs executing ===, typeof, instanceof, and other operations alike.

JS object property

Provides functions for performing operations on object properties.

JS function

Invokes functions and creates instances.

Object encapsulation

Binds the external context of JS objects.

Simple asynchronization

Creates asynchronous tasks.

Promise

Creates a function set for a promise.

Script

Runs JS code.
## How to Develop The following example describes how to use NAPI to develop a JS API for obtaining the application bundle name. The prototype of the JS API is as follows: ``` function getAppName(): string; ``` The implementation code of the JS API is as follows: ``` // app.cpp #include #include #include "napi/native_api.h" #include "napi/native_node_api.h" struct AsyncCallbackInfo { napi_env env; napi_async_work asyncWork; napi_deferred deferred; }; // C/C++ function corresponding to getAppName() napi_value JSGetAppName(napi_env env, napi_callback_info info) { napi_deferred deferred; napi_value promise; // Create a promise. NAPI_CALL(env, napi_create_promise(env, &deferred, &promise)); AsyncCallbackInfo* asyncCallbackInfo = new AsyncCallbackInfo { .env = env, .asyncWork = nullptr, .deferred = deferred, }; napi_value resourceName; napi_create_string_latin1(env, "GetAppName", NAPI_AUTO_LENGTH, &resourceName); // Create a queue of asynchronous tasks. napi_create_async_work( env, nullptr, resourceName, // Callback for an asynchronous task [](napi_env env, void* data) {}, // Callback after the asynchronous task is complete [](napi_env env, napi_status status, void* data) { AsyncCallbackInfo* asyncCallbackInfo = (AsyncCallbackInfo*)data; napi_value appName; const char* str = "com.example.helloworld"; napi_create_string_utf8(env, str, strlen(str), &appName); // Trigger the callback. napi_resolve_deferred(asyncCallbackInfo->env, asyncCallbackInfo->deferred, appName); napi_delete_async_work(env, asyncCallbackInfo->asyncWork); delete asyncCallbackInfo; }, (void*)asyncCallbackInfo, &asyncCallbackInfo->asyncWork); napi_queue_async_work(env, asyncCallbackInfo->asyncWork); return promise; } // Export the module. static napi_value AppExport(napi_env env, napi_value exports) { static napi_property_descriptor desc[] = { DECLARE_NAPI_FUNCTION("getAppName", JSGetAppName), }; NAPI_CALL(env, napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc)); return exports; } // App module description static napi_module appModule = { .nm_version = 1, .nm_flags = 0, .nm_filename = nullptr, .nm_register_func = AppExport, .nm_modname = "app", .nm_priv = ((void*)0), .reserved = {0} }; // Register the module. extern "C" __attribute__((constructor)) void AppRegister() { napi_module_register(&appModule); } ``` The build script is as follows: ``` // BUILD.gn import("//build/ohos.gni") ohos_shared_library("app") { # Specify the source file to build. sources = [ "app.cpp", ] # Specify build dependencies. deps = [ "//foundation/arkui/napi:ace_napi" ] # Specify the directory where the library is generated. relative_install_dir = "module" subsystem_name = "arkui" part_name = "napi" } ``` Test code to run in your app is as follows: ``` import app from '@ohos.app' export default { testGetAppName() { app.getAppName().then(function (data) { console.info('app name: ' + data); }); } } ``` ## Repositories Involved [ArkUI framework](https://gitee.com/openharmony/docs/blob/master/en/readme/arkui.md) [arkui\_ace\_engine](https://gitee.com/openharmony/arkui_ace_engine/blob/master/README.md) [arkui\_ace\_engine\_lite](https://gitee.com/openharmony/arkui_ace_engine_lite/blob/master/README.md) **arkui\_napi**