From be31fa559d089473b99a3e1e79385360fdda72ba Mon Sep 17 00:00:00 2001 From: Gloria Date: Fri, 4 Jul 2025 16:20:19 +0800 Subject: [PATCH] Update docs Signed-off-by: wusongqing --- en/application-dev/Readme-EN.md | 86 ++-- en/application-dev/application-dev-guide.md | 2 +- en/application-dev/napi/Readme-EN.md | 10 +- en/application-dev/napi/cpu-features.md | 2 +- .../napi/native-bundle-guidelines.md | 294 ++++++++----- en/application-dev/napi/neon-guide.md | 5 +- en/application-dev/napi/ohos-abi.md | 21 +- en/application-dev/napi/use-sendable-napi.md | 388 +++++++++--------- 8 files changed, 452 insertions(+), 356 deletions(-) diff --git a/en/application-dev/Readme-EN.md b/en/application-dev/Readme-EN.md index 4141c6ac65e..86ce165730e 100644 --- a/en/application-dev/Readme-EN.md +++ b/en/application-dev/Readme-EN.md @@ -7,32 +7,70 @@ - [Release Notes](../release-notes/Readme.md) - [Quick Start](quick-start/Readme-EN.md) - Development - - [Application Models](application-models/Readme-EN.md) - - [UI Development](ui/Readme-EN.md) - - [ArkTS Common Library](arkts-utils/Readme-EN.md) - - [Web](web/Readme-EN.md) - - [Notification](notification/Readme-EN.md) - - [Widget](form/Readme-EN.md) - - [Window Manager](windowmanager/Readme-EN.md) - - [WebGL](webgl/Readme-EN.md) - - [Media](media/Readme-EN.md) - - [Security](security/Readme-EN.md) - - [Network Management](network/Readme-EN.md) - - [Basic Communication](connectivity/Readme-EN.md) - - [Data Management](database/Readme-EN.md) - - [File Management](file-management/Readme-EN.md) - - [Telephony Service](telephony/Readme-EN.md) - - [Task Management](task-management/Readme-EN.md) - - [Account Management](basic-services/Readme-EN.md) - - [Device Usage Statistics](device-usage-statistics/Readme-EN.md) - - [DFX](dfx/Readme-EN.md) - - [Internationalization](internationalization/Readme-EN.md) - - [Application Test](application-test/Readme-EN.md) + - Application Framework + - [Ability Kit](application-models/Readme-EN.md) + - [ArkData](database/Readme-EN.md) + - [ArkTS](arkts-utils/Readme-EN.md) + - [ArkUI](ui/Readme-EN.md) + - [ArkWeb](web/Readme-EN.md) + - [Background Tasks Kit](task-management/Readme-EN.md) + - [Core File Kit](file-management/Readme-EN.md) + - [Form Kit](form/Readme-EN.md) + - [IME Kit](inputmethod/Readme-EN.md) + - [IPC Kit](ipc/Readme-EN.md) + - [Localization Kit](internationalization/Readme-EN.md) + - System + - Security + - [Ability Access Control](security/AccessToken/Readme-EN.md) + - [Asset Store Kit](security/AssetStoreKit/Readme-EN.md) + - [Crypto Architecture Kit](security/CryptoArchitectureKit/Readme-EN.md) + - [Data Protection Kit](security/DataProtectionKit/Readme-EN.md) + - [Device Certificate Kit](security/DeviceCertificateKit/Readme-EN.md) + - [Universal Keystore Kit](security/UniversalKeystoreKit/Readme-EN.md) + - [User Authentication Kit](security/UserAuthenticationKit/Readme-EN.md) + - Network + - [Connectivity Kit](connectivity/Readme-EN.md) + - [Distributed Service Kit](distributedservice/Readme-EN.md) + - [Network Kit](network/Readme-EN.md) + - [Telephony Kit](telephony/Readme-EN.md) + - Basic Functions + - [Basics Service Kit](basic-services/Readme-EN.md) + - [Function Flow Runtime Kit](ffrt/Readme-EN.md) + - [Input Kit](device/input/Readme-EN.md) + - [MDM Kit](mdm/Readme-EN.md) + - Hardware + - [Driver Development Kit](device/driver/Readme-EN.md) + - [Multimodal Awareness Kit](device/stationary/Readme-EN.md) + - [Sensor Service Kit](device/sensor/Readme-EN.md) + - Debugging Tools + - [Performance Analysis Kit](dfx/Readme-EN.md) + - [Test Kit](application-test/Readme-EN.md) + - [Debugging Commands](tools/Readme-EN.md) + - Media + - [Audio Kit](media/audio/Readme-EN.md) + - [AVCodec Kit](media/avcodec/Readme-EN.md) + - [AVSession Kit](media/avsession/Readme-EN.md) + - [Camera Kit](media/camera/Readme-EN.md) + - [DRM Kit](media/drm/Readme-EN.md) + - [Image Kit](media/image/Readme-EN.md) + - [Media Kit](media/media/Readme-EN.md) + - [Media Library Kit](media/medialibrary/Readme-EN.md) + - graphics + - [ArkGraphics 2D](graphics/Readme-EN.md) + - [ArkGraphics 3D](graphics3d/Readme-EN.md) + - Applications and Services + - [Ads Kit](ads-service/Readme-EN.md) + - [Calendar Kit](calendarmanager/Readme-EN.md) + - [Contacts Kit](contacts/Readme-EN.md) + - [Location Kit](device/location/Readme-EN.md) + - [Notification Kit](notification/Readme-EN.md) + - AI + - [MindSpore Lite Kit](ai/mindspore/Readme-EN.md) + - [Neural Network Runtime Kit](ai/nnrt/Readme-EN.md) - [IDL Specifications and User Guide](IDL/idl-guidelines.md) - [Native APIs](napi/Readme-EN.md) - - [Performance](performance/readme-EN.md) - Tools - - [DevEco Studio (OpenHarmony) User Guide](quick-start/deveco-studio-user-guide-for-openharmony.md) + - [DevEco Studio (OpenHarmony) User Guide](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-tools-overview) - [Debugging Tools](tools/Readme-EN.md) - Hands-On Tutorials - [Samples](https://gitee.com/openharmony/applications_app_samples/blob/master/README.md) @@ -41,5 +79,3 @@ - [FAQs](faqs/Readme-EN.md) - Contribution - [How to Contribute](../contribute/documentation-contribution.md) - - \ No newline at end of file diff --git a/en/application-dev/application-dev-guide.md b/en/application-dev/application-dev-guide.md index 92fab57693e..cda36ba47f1 100644 --- a/en/application-dev/application-dev-guide.md +++ b/en/application-dev/application-dev-guide.md @@ -16,7 +16,7 @@ You can refer to development guidances of key features in the application framew - Open kit capabilities related to the application framework: Ability Kit, ArkUI, and more -- Open kit capabilities related to application services: Account Kit, Location Kit, and more +- Open kit capabilities related to application services: Calendar Kit, Location Kit, and more - Open kit capabilities related to the system: Network Kit, Universal Keystore Kit, and more - Open kit capabilities related to multimedia: Audio Kit, Media Library Kit, and more - Open kit capabilities related to graphics: ArkGraphics 2D and more diff --git a/en/application-dev/napi/Readme-EN.md b/en/application-dev/napi/Readme-EN.md index 83391b8cffb..1d31119da1b 100644 --- a/en/application-dev/napi/Readme-EN.md +++ b/en/application-dev/napi/Readme-EN.md @@ -8,7 +8,7 @@ - [Building an NDK Project with the Command Line CMake](build-with-ndk-cmake.md) - [Building an NDK Project with Prebuilt Libraries](build-with-ndk-prebuilts.md) - Code Development - - [Code Development Overview](develop-code-overview.md) + - [Development Overview](develop-code-overview.md) - C/C++ Standard Library - [C/C++ Library Mechanisms](c-cpp-overview.md) - [Using fdsan](fdsan.md) @@ -28,7 +28,7 @@ - [Working with Cleanup Hooks Using Node-API](use-napi-about-cleanuphook.md) - [Working with Date Using Node-API](use-napi-about-date.md) - [Error Handling Using Node-API](use-napi-about-error.md) - - [Associating Data with a Running Environment to Tide Their Lifecycle Using Node-API](use-napi-about-environmental-life-cycle.md) + - [Associating Data with a Running Environment to Tie Their Lifecycle Using Node-API](use-napi-about-environmental-life-cycle.md) - [Working with Functions Using Node-API](use-napi-about-function.md) - [Performing Lifecycle Management Using Node-API](use-napi-life-cycle.md) - [Working with Objects Using Node-API](use-napi-about-object.md) @@ -50,7 +50,8 @@ - [Passing a Task with the Specified Priority to an ArkTS Thread from an Asynchronous Thread Using Node-API](use-call-threadsafe-function-with-priority.md) - [Analyzing Exceptions and Crashes Triggered by Using Node-API](use-napi-about-crash.md) - [Calling an ArkTS Method with Return Value of a Promise Using Node-API](use-napi-method-promise.md) - - [Node-API FAQs](use-napi-faqs.md) + - Node-API FAQs + - [Node-API FAQs](use-napi-faqs.md) - Using JSVM-API - [JSVM-API Overview](jsvm-introduction.md) - [JSVM-API Data Types and APIs](jsvm-data-types-interfaces.md) @@ -90,7 +91,7 @@ - [Creating Basic Data Types Using JSVM-API](use-jsvm-basic-data-types.md) - Typical JSVM-API Use Cases - [JSVM-API Debugging](jsvm-debugger-cpuprofiler-heapsnapshot.md) - - [JSVM-API Tracing](use-jsvm-about-trace.md) + - [Working with Trace Using JSVM-API](use-jsvm-about-trace.md) - [Requesting the JIT Profile for JSVMs](jsvm-apply-jit-profile.md) - JSVM-API Tuning and Performant Coding Cases - [Creating and Destroying JSVMs Using JSVM-API](use-jsvm-runtime-task.md) @@ -116,4 +117,3 @@ - [OpenHarmony ABIs](ohos-abi.md) - [CPU Features](cpu-features.md) - [Using Neon Instructions](neon-guide.md) - diff --git a/en/application-dev/napi/cpu-features.md b/en/application-dev/napi/cpu-features.md index 012289eaf16..b0b4763b488 100644 --- a/en/application-dev/napi/cpu-features.md +++ b/en/application-dev/napi/cpu-features.md @@ -31,7 +31,7 @@ Currently, OpenHarmony does not provide APIs for obtaining CPU features. You can 2. Add the statement for determining the support for the CPU features to the code. The following uses the ARM and AArch64 architectures as an example: ```c++ - ... + // ... // Include the header file for CPU architecture target detection. #include "cpu_features_macros.h" // In the ARM architecture, this macro is automatically defined in the preceding header file based on the target. diff --git a/en/application-dev/napi/native-bundle-guidelines.md b/en/application-dev/napi/native-bundle-guidelines.md index ad6d9d45606..f9addf38517 100644 --- a/en/application-dev/napi/native-bundle-guidelines.md +++ b/en/application-dev/napi/native-bundle-guidelines.md @@ -9,141 +9,213 @@ Use the native bundle APIs to obtain application information. | API | Description | | :----------------------------------------------------------- | :--------------------------------------- | | [OH_NativeBundle_GetCurrentApplicationInfo](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_getcurrentapplicationinfo) | Obtains the information about the current application. | -| [OH_NativeBundle_GetAppId](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_getappid) | Obtains the appId information about the current application.| -| [OH_NativeBundle_GetAppIdentifier](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_getappidentifier) | Obtains the appIdentifier information about the current application.| +| [OH_NativeBundle_GetAppId](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_getappid) | Obtains the appId information about the application.| +| [OH_NativeBundle_GetAppIdentifier](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_getappidentifier) | Obtains the appIdentifier information about the application.| +| [OH_NativeBundle_GetMainElementName](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_getmainelementname) | Obtains the entry information of the application.| +| [OH_NativeBundle_GetCompatibleDeviceType](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_getcompatibledevicetype) | Obtains the compatible device type of the application.| + ## How to Develop -1. **Create a project.** +1. Create a project. + +![native](figures/rawfile1.png) -
- -
-2. **Add dependencies.** +2. Add dependencies. - After the project is created, the **cpp** directory is created in the project directory. The directory contains files such as **libentry/index.d.ts**, **hello.cpp**, and **CMakeLists.txt**. +After the project is created, the **cpp** directory is created in the project directory. In the **cpp** directory, there are files such as **types/libentry/index.d.ts**, **napi_init.cpp**, and **CMakeLists.txt**. - 1. Open the **src/main/cpp/CMakeLists.txt** file, and add **libbundle_ndk.z.so** to **target_link_libraries**. +1. Open the **src/main/cpp/CMakeLists.txt** file, and add **libbundle_ndk.z.so** to **target_link_libraries**. - ```c++ - target_link_libraries(entry PUBLIC libace_napi.z.so libbundle_ndk.z.so) - ``` + ```c++ + target_link_libraries(entry PUBLIC libace_napi.z.so libbundle_ndk.z.so) + ``` - 2. Open the **src/main/cpp/hello.cpp** file, and add the header file. +2. Open the **src/main/cpp/napi_init.cpp** file, and add the header file. - ```c++ - #include "bundle/native_interface_bundle.h" - ``` + ```c++ + // Include the header file required for napi. + #include "bundle/native_interface_bundle.h" + // Include the standard library for the free() function. + #include + ``` -3. **Modify the source file.** +3. Modify the source file. - When the **src/main/cpp/hello.cpp** file is opened, **Init** is called to initialize the API, which is **getCurrentApplicationInfo**. +1. When the **src/main/cpp/napi_init.cpp** file is opened, **Init** is called to initialize the API. ```c++ EXTERN_C_START static napi_value Init(napi_env env, napi_value exports) { napi_property_descriptor desc[] = { - { "getCurrentApplicationInfo", nullptr, GetCurrentApplicationInfo, nullptr, nullptr, nullptr, napi_default, nullptr} + { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr }, + { "getCurrentApplicationInfo", nullptr, GetCurrentApplicationInfo, nullptr, nullptr, nullptr, napi_default, nullptr}, // 新增方法 getCurrentApplicationInfo + { "getAppId", nullptr, GetAppId, nullptr, nullptr, nullptr, napi_default, nullptr}, // 新增方法 getAppId + { "getAppIdentifier", nullptr, GetAppIdentifier, nullptr, nullptr, nullptr, napi_default, nullptr}, // 新增方法 getAppIdentifier + { "getMainElementName", nullptr, GetMainElementName, nullptr, nullptr, nullptr, napi_default, nullptr}, // 新增方法 getMainElementName + { "getCompatibleDeviceType", nullptr, GetCompatibleDeviceType, nullptr, nullptr, nullptr, napi_default, nullptr} // 新增方法 getCompatibleDeviceType }; - napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); return exports; } EXTERN_C_END ``` - 1. Add the API to the **src/main/cpp/hello.cpp** file. - - ```c++ - static napi_value GetCurrentApplicationInfo(napi_env env, napi_callback_info info) - ``` - - 2. Obtain the native bundle information object from the **hello.cpp** file and convert it to a JavaScript bundle information object. In this way, you can obtain the application information on the JavaScript side. - - ```c++ - static napi_value GetCurrentApplicationInfo(napi_env env, napi_callback_info info) - { - // Call the native API to obtain the application information. - OH_NativeBundle_ApplicationInfo nativeApplicationInfo = OH_NativeBundle_GetCurrentApplicationInfo(); - napi_value result = nullptr; - napi_create_object(env, &result); - // Convert the bundle name obtained by calling the native API to the bundleName attribute in the JavaScript object. - napi_value bundleName; - napi_create_string_utf8(env, nativeApplicationInfo.bundleName, NAPI_AUTO_LENGTH, &bundleName); - napi_set_named_property(env, result, "bundleName", bundleName); - // Convert the fingerprint information obtained by calling the native API to the fingerprint attribute in the JavaScript object. - napi_value fingerprint; - napi_create_string_utf8(env, nativeApplicationInfo.fingerprint, NAPI_AUTO_LENGTH, &fingerprint); - napi_set_named_property(env, result, "fingerprint", fingerprint); - - char* appId = OH_NativeBundle_GetAppId(); - // Convert the application ID obtained by calling the native API to the appId attribute in the JavaScript object. - napi_value napi_appId; - napi_create_string_utf8(env, appId, NAPI_AUTO_LENGTH, &napi_appId); - napi_set_named_property(env, result, "appId", napi_appId); - - char* appIdentifier = OH_NativeBundle_GetAppIdentifier(); - // Convert the application identifier obtained by calling the native API to the appIdentifier attribute in the JavaScript object. - napi_value napi_appIdentifier; - napi_create_string_utf8(env, appIdentifier, NAPI_AUTO_LENGTH, &napi_appIdentifier); - napi_set_named_property(env, result, "appIdentifier", napi_appIdentifier); - // To prevent memory leak, manually release the memory. - free(nativeApplicationInfo.bundleName); - free(nativeApplicationInfo.fingerprint); - free(appId); - free(appIdentifier); - return result; - } - ``` - -4. **Call APIs on the JavaScript side.** - - 1. Open the **src\main\ets\pages\index.ets** file, and import **libentry.so**. - - 2. Call the native API **getCurrentApplicationInfo()** to obtain application information. An example is as follows: - - ```js - import hilog from '@ohos.hilog'; - import testNapi from 'libentry.so'; - - @Entry - @Component - struct Index { - @State message: string = 'Hello World'; - - build() { - Row() { - Column() { - Text(this.message) - .fontSize(50) - .fontWeight(FontWeight.Bold) - - Button(){ - Text("GetCurrentApplicationInfo").fontSize(30) - }.type(ButtonType.Capsule) - .margin({ - top: 20 - }) - .backgroundColor('#0D9FFB') - .width('70%') - .height('5%') - .onClick(()=>{ - try { - let data = testNapi.getCurrentApplicationInfo(); - console.info("getCurrentApplicationInfo success, data is " + JSON.stringify(data)); - } catch (error) { - console.error("getCurrentApplicationInfo failed"); - this.message = "getCurrentApplicationInfo failed"; - } - }) - } - .width('100%') - } - .height('100%') - } - } - ``` +2. Add the API to the **src/main/cpp/napi_init.cpp** file. + + ```c++ + static napi_value GetCurrentApplicationInfo(napi_env env, napi_callback_info info) + static napi_value GetAppId(napi_env env, napi_callback_info info) + static napi_value GetAppIdentifier(napi_env env, napi_callback_info info) + static napi_value GetMainElementName(napi_env env, napi_callback_info info) + static napi_value GetCompatibleDeviceType(napi_env env, napi_callback_info info) + ``` + +3. Obtain the native bundle information object from the **src/main/cpp/napi_init.cpp** file and convert it to a JavaScript bundle information object. In this way, you can obtain the application information on the JavaScript side. + + ```c++ + static napi_value GetCurrentApplicationInfo(napi_env env, napi_callback_info info) + { + // Call the native API to obtain the application information. + OH_NativeBundle_ApplicationInfo nativeApplicationInfo = OH_NativeBundle_GetCurrentApplicationInfo(); + napi_value result = nullptr; + napi_create_object(env, &result); + // Convert the bundle name obtained by calling the native API to the bundleName property in the JavaScript object. + napi_value bundleName; + napi_create_string_utf8(env, nativeApplicationInfo.bundleName, NAPI_AUTO_LENGTH, &bundleName); + napi_set_named_property(env, result, "bundleName", bundleName); + // Convert the fingerprint information obtained by calling the native API to the fingerprint property in the JavaScript object. + napi_value fingerprint; + napi_create_string_utf8(env, nativeApplicationInfo.fingerprint, NAPI_AUTO_LENGTH, &fingerprint); + napi_set_named_property(env, result, "fingerprint", fingerprint); + + // To prevent memory leak, manually release the memory. + free(nativeApplicationInfo.bundleName); + free(nativeApplicationInfo.fingerprint); + return result; + } + + static napi_value GetAppId(napi_env env, napi_callback_info info) + { + // Call the native API to obtain the appId. + char* appId = OH_NativeBundle_GetAppId(); + // Convert the appId obtained by calling the native API to nAppId and return it. + napi_value nAppId; + napi_create_string_utf8(env, appId, NAPI_AUTO_LENGTH, &nAppId); + // To prevent memory leak, manually release the memory. + free(appId); + return nAppId; + } + + static napi_value GetAppIdentifier(napi_env env, napi_callback_info info) + { + // Call the native API to obtain the appIdentifier. + char* appIdentifier = OH_NativeBundle_GetAppIdentifier(); + // Convert the appIdentifier obtained by calling the native API to nAppIdentifier and return it. + napi_value nAppIdentifier; + napi_create_string_utf8(env, appIdentifier, NAPI_AUTO_LENGTH, &nAppIdentifier); + // To prevent memory leak, manually release the memory. + free(appIdentifier); + return nAppIdentifier; + } + + static napi_value GetMainElementName(napi_env env, napi_callback_info info) + { + // Call the native API to obtain the application entry information. + OH_NativeBundle_ElementName elementName = OH_NativeBundle_GetMainElementName(); + napi_value result = nullptr; + napi_create_object(env, &result); + // Convert the bundle name obtained by calling the native API to the bundleName property in the JavaScript object. + napi_value bundleName; + napi_create_string_utf8(env, elementName.bundleName, NAPI_AUTO_LENGTH, &bundleName); + napi_set_named_property(env, result, "bundleName", bundleName); + // Convert the module name obtained by calling the native API to the moduleName property in the JavaScript object. + napi_value moduleName; + napi_create_string_utf8(env, elementName.moduleName, NAPI_AUTO_LENGTH, &moduleName); + napi_set_named_property(env, result, "moduleName", moduleName); + // Convert the ability name obtained by calling the native API to the abilityName property in the JavaScript object. + napi_value abilityName; + napi_create_string_utf8(env, elementName.abilityName, NAPI_AUTO_LENGTH, &abilityName); + napi_set_named_property(env, result, "abilityName", abilityName); + // To prevent memory leak, manually release the memory. + free(elementName.bundleName); + free(elementName.moduleName); + free(elementName.abilityName); + return result; + } + + static napi_value GetCompatibleDeviceType(napi_env env, napi_callback_info info) + { + // Call the native API to obtain the device type. + char* deviceType = OH_NativeBundle_GetCompatibleDeviceType(); + // Convert the device type obtained by calling the native API to nDeviceType and return it. + napi_value nDeviceType; + napi_create_string_utf8(env, deviceType, NAPI_AUTO_LENGTH, &nDeviceType); + // To prevent memory leak, manually release the memory. + free(deviceType); + return nDeviceType; + } + ``` + +4. Expose APIs. + +Declare the exposed APIs in the **src/main/cpp/types/libentry/Index.d.ts** file. + +```js +export const add: (a: number, b: number) => number; +export const getCurrentApplicationInfo: () => object; // Add the exposed API getCurrentApplicationInfo. +export const getAppId: () => string; // Add the exposed API getAppId. +export const getAppIdentifier: () => string; // Add the exposed API getAppIdentifier. +export const getMainElementName: () => object; // Add the exposed API getMainElementName. +export const getCompatibleDeviceType: () => string; // Add the exposed API getCompatibleDeviceType. +``` + +5. Call APIs on the JavaScript side. + +1. Open the **src\main\ets\pages\index.ets** file, and import **libentry.so**. + + +2. Call the native APIs to print the obtained information. An example is as follows: + + ```js + import { hilog } from '@kit.PerformanceAnalysisKit'; + import testNapi from 'libentry.so'; + + const DOMAIN = 0x0000; + + @Entry + @Component + struct Index { + @State message: string = 'Hello World'; + + build() { + Row() { + Column() { + Text(this.message) + .fontSize($r('app.float.page_text_font_size')) + .fontWeight(FontWeight.Bold) + .onClick(() => { + this.message = 'Welcome'; + hilog.info(DOMAIN, 'testTag', 'Test NAPI 2 + 3 = %{public}d', testNapi.add(2, 3)); + let appInfo = testNapi.getCurrentApplicationInfo(); + console.info("bundleNDK getCurrentApplicationInfo success, data is " + JSON.stringify(appInfo)); + let appId = testNapi.getAppId(); + console.info("bundleNDK getAppId success, appId is " + appId); + let appIdentifier = testNapi.getAppIdentifier(); + console.info("bundleNDK getAppIdentifier success, appIdentifier is " + appIdentifier); + let mainElement = testNapi.getMainElementName(); + console.info("bundleNDK getMainElementName success, data is " + JSON.stringify(mainElement)); + let deviceType = testNapi.getCompatibleDeviceType(); + console.info("bundleNDK getCompatibleDeviceType success, deviceType is " + deviceType); + }) + } + .width('100%') + } + .height('100%') + } + } + ``` For details about the APIs, see [Bundle](../reference/apis-ability-kit/_bundle.md). diff --git a/en/application-dev/napi/neon-guide.md b/en/application-dev/napi/neon-guide.md index a90e18e36db..8bc126251f6 100644 --- a/en/application-dev/napi/neon-guide.md +++ b/en/application-dev/napi/neon-guide.md @@ -71,9 +71,9 @@ The following example describes how to use Neon intrinsics in an armeabi-v7a Ope int16x4_t input_vec = vld1_s16(input + (nn+offset+mm*4)); sum_vec = vmlal_s16(sum_vec, kernel_vec, input_vec); } - ... + // ... } - ... + // ... } ``` @@ -100,4 +100,3 @@ The following example describes how to use Neon intrinsics in an armeabi-v7a Ope ``` Now you can use Neon intrinsics in your project. - diff --git a/en/application-dev/napi/ohos-abi.md b/en/application-dev/napi/ohos-abi.md index b0827d2c246..81122bd3dd3 100644 --- a/en/application-dev/napi/ohos-abi.md +++ b/en/application-dev/napi/ohos-abi.md @@ -1,14 +1,12 @@ # OpenHarmony ABIs - + OpenHarmony supports diverse device forms, instruction sets, and operating system kernels. To ensure application compatibility on different OpenHarmony devices, follow the basic OHOS Application Binary Interface (ABI) standards provided in this topic. - - + ## Byte Order and Word Width OHOS ABIs always use little-endian, ILP32 for 32-bit systems, and LP64 for 64-bit systems. - ## Procedure Call Standards The parameter transfer mode in function calls, register usage rules, and stack operation rules are defined. Different C++ compilers, operating systems, and architectures may use different calling rules. For details, see [Calling conventions for different C++ compilers and operating systems](https://www.agner.org/optimize/calling_conventions.pdf). For details about the architecture-specific call standards, see the following: @@ -17,16 +15,13 @@ The parameter transfer mode in function calls, register usage rules, and stack o - [Procedure Call Standard for the Arm庐 64-bit Architecture (AArch64)](https://github.com/ARM-software/abi-aa/tree/main/aapcs64) - ## C++ ABI OpenHarmony uses libc++ in the LLVM project as the C++ runtime library. It uses the libc++.so library for the underlying system and the libc++_shared.so library for applications, with the same set of code but different C++ namespaces. For details about the symbol mangling rules of C++, see [Itanium C++ ABI](https://itanium-cxx-abi.github.io/cxx-abi/). - ## Floating-Point Format -OpenHarmony uses IEE754 as the floating-point encoding format. For details about the definition of the long double format, see [Supported ABIs](#supported-abis). - +OpenHarmony uses IEEE754 as the floating-point encoding format. For details about the definition of the long double format, see [Supported ABIs](#supported-abis). ## Executable File Format @@ -36,7 +31,6 @@ OpenHarmony uses ELF as the binary file format of the entire system. For details - [ELF for the Arm庐 64-bit Architecture (AArch64)](https://github.com/ARM-software/abi-aa/tree/main/aaelf64) - ## Supported ABIs This section describes the ABIs supported by OpenHarmony and their differences. @@ -46,11 +40,10 @@ This section describes the ABIs supported by OpenHarmony and their differences. armeabi-v7a is developed on the [Application Binary Interface](https://developer.arm.com/Architectures/ABI) and applies to 32-bit ARMv7-A CPUs. It supports ARM processors Cortex-A5, Cortex-A7, Cortex-A8, Cortex-A9, Cortex-A12, Cortex-A15, and Cortex-A17. It also supports ARM32, Thumb-2, and VFPv3-D16 instructions. - This ABI uses **-mfloat-cpu=softfp** to enforce the floating-point rule in function calls. The compiler still uses hardware floating point instructions. Other extensions including Neon are optional in this ABI. For better compatibility, you are advised to use **-mfpu=softvfp** to compile the native libraries. This ABI uses 64-bit long double (IEEE binary64). - + ### arm64-v8a @@ -60,17 +53,14 @@ This ABI uses **-mfloat-cpu=softfp** to enforce the floating-point rule in funct This ABI uses 128-bit long double (IEEE binary128). - ### x86_64 x86_64 is developed on Intel 64 and IA-32 ABI and supports MMX, SSE, SSE2, SSE3, SSSE3, and SSE4.1 instructions. For details about x86 specifications, see **System V Application Binary Interface** and **AMD64 Architecture Processor Supplement**. This ABI uses 128-bit long double (IEEE binary128). Note that many x86 platforms use the float80 format, whereas OpenHarmony uses the 128-bit format. - ## Specifying the ABI in the Architecture at Build Time - ### Setting in DevEco Studio In the C++ project of OpenHarmony, find the **buildOption/externalNativeOptions** field in the **build-profile.json5** file of the project where the C++ code is located, and add the **abiFilters** field. @@ -90,8 +80,7 @@ In the C++ project of OpenHarmony, find the **buildOption/externalNativeOptions* } } ``` - - +Note: If the **abiFilters** field is not set in DevEco Studio, the default architecture is arm64-v8a. ### Setting in .cmake When you develop native code using the SDK, some common environment variables for cross compilation of OpenHarmony are defined in **build/cmake/ohos.toolchain.cmake**. The **OHOS_ARCH** variable defines the target ABI for build, which can be **arm64-v8a**, **armeabi-v7a**, and **x86_64**. diff --git a/en/application-dev/napi/use-sendable-napi.md b/en/application-dev/napi/use-sendable-napi.md index 245e46aca38..5d2719c7abf 100644 --- a/en/application-dev/napi/use-sendable-napi.md +++ b/en/application-dev/napi/use-sendable-napi.md @@ -2,233 +2,233 @@ ## When to Use -You can use **napi_wrap_sendable** to wrap a C++ object in a sendable ArkTS object, and use **napi_unwrap_sendable** to retrieve the C++ object previously wrapped in the sendable ArkTS object for subsequent operations. +You can use **napi_wrap_sendable** to wrap a C++ object in a Sendable ArkTS object, and use **napi_unwrap_sendable** to retrieve the C++ object previously wrapped in the Sendable ArkTS object for subsequent operations. ## Example 1. Declare the APIs, configure compile settings, and register the module. - **Declare the APIs.** + **Declare the APIs.** - ```ts - // index.d.ets - @Sendable - export class MyObject { + ```ts + // index.d.ets + @Sendable + export class MyObject { constructor(arg: number); plusOne(): number; public get value(); public set value(newVal: number); - } - ``` + } + ``` - **Configure compile settings.** + **Configure compile settings.** - ``` - # the minimum version of CMake. - cmake_minimum_required(VERSION 3.5.0) - project(napi_wrap_sendable_demo) + ```cmake + # the minimum version of CMake. + cmake_minimum_required(VERSION 3.5.0) + project(napi_wrap_sendable_demo) - set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}) + set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}) - if(DEFINED PACKAGE_FIND_FILE) - include(${PACKAGE_FIND_FILE}) - endif() + if(DEFINED PACKAGE_FIND_FILE) + include(${PACKAGE_FIND_FILE}) + endif() - include_directories(${NATIVERENDER_ROOT_PATH} - ${NATIVERENDER_ROOT_PATH}/include) + include_directories(${NATIVERENDER_ROOT_PATH} + ${NATIVERENDER_ROOT_PATH}/include) - add_definitions("-DLOG_DOMAIN=0x0000") - add_definitions("-DLOG_TAG=\"testTag\"") + add_definitions("-DLOG_DOMAIN=0x0000") + add_definitions("-DLOG_TAG=\"testTag\"") - add_library(entry SHARED napi_init.cpp) - target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so) - ``` + add_library(entry SHARED napi_init.cpp) + target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so) + ``` - **Register the module.** + **Register the module.** - ```cpp - // napi_init.cpp - #include "napi/native_api.h" - #include "hilog/log.h" + ```cpp + // napi_init.cpp + #include "napi/native_api.h" + #include "hilog/log.h" - // A native class. Its instance is wrapped in a sendable ArkTS object. - class MyObject { - public: - static napi_value Init(napi_env env, napi_value exports); - static void Destructor(napi_env env, void *nativeObject, void *finalize_hint); + // A native class. Its instance is wrapped in a Sendable ArkTS object. + class MyObject { + public: + static napi_value Init(napi_env env, napi_value exports); + static void Destructor(napi_env env, void *nativeObject, void *finalize_hint); - private: - explicit MyObject(double value_ = 0); - ~MyObject(); + private: + explicit MyObject(double value_ = 0); + ~MyObject(); - static napi_value New(napi_env env, napi_callback_info info); - static napi_value GetValue(napi_env env, napi_callback_info info); - static napi_value SetValue(napi_env env, napi_callback_info info); - static napi_value PlusOne(napi_env env, napi_callback_info info); + static napi_value New(napi_env env, napi_callback_info info); + static napi_value GetValue(napi_env env, napi_callback_info info); + static napi_value SetValue(napi_env env, napi_callback_info info); + static napi_value PlusOne(napi_env env, napi_callback_info info); - double value_; - napi_env env_; - }; + double value_; + napi_env env_; + }; - static thread_local napi_ref g_ref = nullptr; + static thread_local napi_ref g_ref = nullptr; - MyObject::MyObject(double value) : value_(value), env_(nullptr) {} + MyObject::MyObject(double value) : value_(value), env_(nullptr) {} - MyObject::~MyObject() {} + MyObject::~MyObject() {} - void MyObject::Destructor(napi_env env, void *nativeObject, [[maybe_unused]] void *finalize_hint) { - OH_LOG_INFO(LOG_APP, "MyObject::Destructor called"); - reinterpret_cast(nativeObject)->~MyObject(); - } + void MyObject::Destructor(napi_env env, void *nativeObject, [[maybe_unused]] void *finalize_hint) { + OH_LOG_INFO(LOG_APP, "MyObject::Destructor called"); + reinterpret_cast(nativeObject)->~MyObject(); + } - napi_value MyObject::Init(napi_env env, napi_value exports) { - napi_value num; - napi_create_double(env, 0, &num); - napi_property_descriptor properties[] = { - {"value", nullptr, nullptr, GetValue, SetValue, nullptr, napi_default, nullptr}, - {"plusOne", nullptr, PlusOne, nullptr, nullptr, nullptr, napi_default, nullptr}, - }; + napi_value MyObject::Init(napi_env env, napi_value exports) { + napi_value num; + napi_create_double(env, 0, &num); + napi_property_descriptor properties[] = { + {"value", nullptr, nullptr, GetValue, SetValue, nullptr, napi_default, nullptr}, + {"plusOne", nullptr, PlusOne, nullptr, nullptr, nullptr, napi_default, nullptr}, + }; - napi_value cons; - // Define a sendable class MyObject. - napi_define_sendable_class(env, "MyObject", NAPI_AUTO_LENGTH, New, nullptr, + napi_value cons; + // Define a Sendable class MyObject. + napi_define_sendable_class(env, "MyObject", NAPI_AUTO_LENGTH, New, nullptr, sizeof(properties) / sizeof(properties[0]), properties, nullptr, &cons); - napi_create_reference(env, cons, 1, &g_ref); - // Mount the MyObject class to the exports object. - napi_set_named_property(env, exports, "MyObject", cons); - return exports; - } - - EXTERN_C_START - // Initialize the module. - static napi_value Init(napi_env env, napi_value exports) { - MyObject::Init(env, exports); - return exports; - } - EXTERN_C_END - - // Information about the module. Record information such as the Init() function and module name. - static napi_module nativeModule = { - .nm_version = 1, - .nm_flags = 0, - .nm_filename = nullptr, - .nm_register_func = Init, - .nm_modname = "entry", - .nm_priv = nullptr, - .reserved = {0}, - }; - - // When the .so file is loaded, this function is automatically called to register the nativeModule module with the system. - extern "C" __attribute__((constructor)) void RegisterObjectWrapModule() { napi_module_register(&nativeModule); } - ``` - -2. Wrap a C++ object in a sendable ArkTS object in a constructor. - - ```cpp - napi_value MyObject::New(napi_env env, napi_callback_info info) { - OH_LOG_INFO(LOG_APP, "MyObject::New called"); - - napi_value newTarget; - napi_get_new_target(env, info, &newTarget); - if (newTarget != nullptr) { - // Invoked as the constructor `new MyObject(...)`. - size_t argc = 1; - napi_value args[1]; - napi_value jsThis; - napi_get_cb_info(env, info, &argc, args, &jsThis, nullptr); - - double value = 0.0; - napi_valuetype valuetype; - napi_typeof(env, args[0], &valuetype); - if (valuetype != napi_undefined) { - napi_get_value_double(env, args[0], &value); - } - - MyObject *obj = new MyObject(value); - - obj->env_ = env; - // Use napi_wrap_sendable to wrap obj (the C++ object) in jsThis (the sendable ArkTS object). - napi_wrap_sendable(env, jsThis, reinterpret_cast(obj), MyObject::Destructor, nullptr); - - return jsThis; - } else { - // Invoked as the plain function `MyObject(...)`. - size_t argc = 1; - napi_value args[1]; - napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); - - napi_value cons; - napi_get_reference_value(env, g_ref, &cons); - napi_value instance; - napi_new_instance(env, cons, argc, args, &instance); - - return instance; - } - } - ``` - -3. Retrieve the C++ object from the sendable ArkTS object and perform subsequent operations on the C++ object. - - ```cpp - napi_value MyObject::GetValue(napi_env env, napi_callback_info info) { - OH_LOG_INFO(LOG_APP, "MyObject::GetValue called"); - - napi_value jsThis; - napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr); - - MyObject *obj; - // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the sendable ArkTS object), and perform subsequent operations. - napi_unwrap_sendable(env, jsThis, reinterpret_cast(&obj)); - napi_value num; - napi_create_double(env, obj->value_, &num); - - return num; - } - - napi_value MyObject::SetValue(napi_env env, napi_callback_info info) { - OH_LOG_INFO(LOG_APP, "MyObject::SetValue called"); - - size_t argc = 1; - napi_value value; - napi_value jsThis; - - napi_get_cb_info(env, info, &argc, &value, &jsThis, nullptr); - - MyObject *obj; - // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the sendable ArkTS object), and perform subsequent operations. - napi_unwrap_sendable(env, jsThis, reinterpret_cast(&obj)); - napi_get_value_double(env, value, &obj->value_); - - return nullptr; - } - - napi_value MyObject::PlusOne(napi_env env, napi_callback_info info) { - OH_LOG_INFO(LOG_APP, "MyObject::PlusOne called"); - - napi_value jsThis; - napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr); - - MyObject *obj; - // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the sendable ArkTS object), and perform subsequent operations. - napi_unwrap_sendable(env, jsThis, reinterpret_cast(&obj)); - obj->value_ += 1; - napi_value num; - napi_create_double(env, obj->value_, &num); - - return num; - } - ``` + napi_create_reference(env, cons, 1, &g_ref); + // Mount the MyObject class to the exports object. + napi_set_named_property(env, exports, "MyObject", cons); + return exports; + } + + EXTERN_C_START + // Initialize the module. + static napi_value Init(napi_env env, napi_value exports) { + MyObject::Init(env, exports); + return exports; + } + EXTERN_C_END + + // Information about the module. Record information such as the Init() function and module name. + static napi_module nativeModule = { + .nm_version = 1, + .nm_flags = 0, + .nm_filename = nullptr, + .nm_register_func = Init, + .nm_modname = "entry", + .nm_priv = nullptr, + .reserved = {0}, + }; + + // When the .so file is loaded, this function is automatically called to register the nativeModule module with the system. + extern "C" __attribute__((constructor)) void RegisterObjectWrapModule() { napi_module_register(&nativeModule); } + ``` + +2. Wrap a C++ object in a Sendable ArkTS object in a constructor. + + ```cpp + napi_value MyObject::New(napi_env env, napi_callback_info info) { + OH_LOG_INFO(LOG_APP, "MyObject::New called"); + + napi_value newTarget; + napi_get_new_target(env, info, &newTarget); + if (newTarget != nullptr) { + // Invoked as the constructor `new MyObject(...)`. + size_t argc = 1; + napi_value args[1]; + napi_value jsThis; + napi_get_cb_info(env, info, &argc, args, &jsThis, nullptr); + + double value = 0.0; + napi_valuetype valuetype; + napi_typeof(env, args[0], &valuetype); + if (valuetype != napi_undefined) { + napi_get_value_double(env, args[0], &value); + } + + MyObject *obj = new MyObject(value); + + obj->env_ = env; + // Use napi_wrap_sendable to wrap obj (the C++ object) in jsThis (the Sendable ArkTS object). + napi_wrap_sendable(env, jsThis, reinterpret_cast(obj), MyObject::Destructor, nullptr); + + return jsThis; + } else { + // Invoked as the plain function `MyObject(...)`. + size_t argc = 1; + napi_value args[1]; + napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); + + napi_value cons; + napi_get_reference_value(env, g_ref, &cons); + napi_value instance; + napi_new_instance(env, cons, argc, args, &instance); + + return instance; + } + } + ``` + +3. Retrieve the C++ object from the Sendable ArkTS object and perform subsequent operations on the C++ object. + + ```cpp + napi_value MyObject::GetValue(napi_env env, napi_callback_info info) { + OH_LOG_INFO(LOG_APP, "MyObject::GetValue called"); + + napi_value jsThis; + napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr); + + MyObject *obj; + // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations. + napi_unwrap_sendable(env, jsThis, reinterpret_cast(&obj)); + napi_value num; + napi_create_double(env, obj->value_, &num); + + return num; + } + + napi_value MyObject::SetValue(napi_env env, napi_callback_info info) { + OH_LOG_INFO(LOG_APP, "MyObject::SetValue called"); + + size_t argc = 1; + napi_value value; + napi_value jsThis; + + napi_get_cb_info(env, info, &argc, &value, &jsThis, nullptr); + + MyObject *obj; + // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations. + napi_unwrap_sendable(env, jsThis, reinterpret_cast(&obj)); + napi_get_value_double(env, value, &obj->value_); + + return nullptr; + } + + napi_value MyObject::PlusOne(napi_env env, napi_callback_info info) { + OH_LOG_INFO(LOG_APP, "MyObject::PlusOne called"); + + napi_value jsThis; + napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr); + + MyObject *obj; + // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations. + napi_unwrap_sendable(env, jsThis, reinterpret_cast(&obj)); + obj->value_ += 1; + napi_value num; + napi_create_double(env, obj->value_, &num); + + return num; + } + ``` 4. ArkTS code: - ```ts - import hilog from '@ohos.hilog'; - import { MyObject } from 'libentry.so'; + ```ts + import hilog from '@ohos.hilog'; + import { MyObject } from 'libentry.so'; - let object : MyObject = new MyObject(0); - object.value = 1023; - hilog.info(0x0000, 'testTag', 'MyObject value after set: %{public}d', object.value); - hilog.info(0x0000, 'testTag', 'MyObject plusOne: %{public}d', object.plusOne()); - ``` + let object : MyObject = new MyObject(0); + object.value = 1023; + hilog.info(0x0000, 'testTag', 'MyObject value after set: %{public}d', object.value); + hilog.info(0x0000, 'testTag', 'MyObject plusOne: %{public}d', object.plusOne()); + ``` -- Gitee