diff --git a/en/application-dev/Readme-EN.md b/en/application-dev/Readme-EN.md index 4141c6ac65e328dfdde641b9e9996d1cfc23f0a7..86ce165730e2263529046611b4e6c85e7ce17da5 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 92fab57693e76b6cdee47711ea9322fee0471771..b6f89bef6bfe361a6392fbc56d5ce06e609f693d 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 @@ -33,4 +33,4 @@ To make you better understand how functions work together and jumpstart your app ## API References -[API References](reference/development-intro.md) encompass all components and APIs provided by every kit in the OpenHarmony SDK, helping you use and integrate APIs more effectively. +[API References](reference/development-intro-api.md) encompass all components and APIs provided by every kit in the OpenHarmony SDK, helping you use and integrate APIs more effectively. diff --git a/en/application-dev/napi/Readme-EN.md b/en/application-dev/napi/Readme-EN.md index 70ffe65d922fbbb187e33eee0c86f24156da54fa..1d31119da1beeb96bfc52afb027a90963cc48f70 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) @@ -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) @@ -88,16 +89,14 @@ - [Working with Well-Known Symbols Using JSVM-API](use-jsvm-about-well-known-symbols.md) - [Working with Wrapper Objects Using JSVM-API](use-jsvm-about-wrapper-object.md) - [Creating Basic Data Types Using JSVM-API](use-jsvm-basic-data-types.md) - - JSVM-API Use Cases + - 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) - [Accelerating Compilation Using a Code Cache](use-jsvm-about-code-cache.md) - [JSVM Tuning Practices](jsvm-optimizations.md) - - JSVM Performance Debugging Guides - - [Collecting V8 Trace Data Using HiSmartPerf](use-jsvm-about-v8-trace.md) - OpenMP Support - [OpenMP Overview](openmp-overview.md) - [Building and Running Applications Using OpenMP](openmp-guideline.md) @@ -118,5 +117,3 @@ - [OpenHarmony ABIs](ohos-abi.md) - [CPU Features](cpu-features.md) - [Using Neon Instructions](neon-guide.md) - - \ No newline at end of file diff --git a/en/application-dev/napi/cpu-features.md b/en/application-dev/napi/cpu-features.md index 012289eaf165d8c9a0537bbd7355e553df69ae16..b0b4763b488be9f2cedccaa2c04ce269fdb8dc89 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 ad6d9d45606cb0441d92753efd576baf80a37314..c80c3be58034946daedf233068a0cd2a22a7c210 100644 --- a/en/application-dev/napi/native-bundle-guidelines.md +++ b/en/application-dev/napi/native-bundle-guidelines.md @@ -9,141 +9,308 @@ 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.| +| [OH_NativeBundle_IsDebugMode](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_isdebugmode) | Queries the debug mode of the application.| +| [OH_NativeBundle_GetModuleMetadata](../reference/apis-ability-kit/_bundle.md#oh_nativebundle_getmodulemetadata) | Obtains the metadata information 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 "napi/native_api.h" + // Include the header file required for NDK interfaces. + #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}, // Add the getCurrentApplicationInfo API. + { "getAppId", nullptr, GetAppId, nullptr, nullptr, nullptr, napi_default, nullptr}, // Add the getAppId API. + { "getAppIdentifier", nullptr, GetAppIdentifier, nullptr, nullptr, nullptr, napi_default, nullptr}, // Add the getAppIdentifier API. + { "getMainElementName", nullptr, GetMainElementName, nullptr, nullptr, nullptr, napi_default, nullptr}, // Add the getMainElementName method. + { "getCompatibleDeviceType", nullptr, GetCompatibleDeviceType, nullptr, nullptr, nullptr, napi_default, nullptr}, // Add the getCompatibleDeviceType method. + { "isDebugMode", nullptr, IsDebugMode, nullptr, nullptr, nullptr, napi_default, nullptr}, // Add the isDebugMode method. + { "getModuleMetadata", nullptr, GetModuleMetadata, nullptr, nullptr, nullptr, napi_default, nullptr} // Add the getModuleMetadata method. }; - 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); + static napi_value IsDebugMode(napi_env env, napi_callback_info info); + static napi_value GetModuleMetadata(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; + } + + static napi_value IsDebugMode(napi_env env, napi_callback_info info) + { + bool isDebug = false; + // Call the native API to obtain the application debug mode. + bool isSuccess = OH_NativeBundle_IsDebugMode(&isDebug); + // Throw an exception if the native API call fails + if (isSuccess == false) { + napi_throw_error(env, nullptr, "call failed"); + return nullptr; + } + // Convert the debug information obtained by calling the native API to debug and return it. + napi_value debug; + napi_get_boolean(env, isDebug, &debug); + return debug; + } + + static napi_value GetModuleMetadata(napi_env env, napi_callback_info info) + { + size_t moduleCount = 0; + // Call the native API to obtain the application metadata information. + OH_NativeBundle_ModuleMetadata* modules = OH_NativeBundle_GetModuleMetadata(&moduleCount); + if (modules == nullptr || moduleCount == 0) { + napi_throw_error(env, nullptr, "no metadata found"); + return nullptr; + } + + napi_value result; + napi_create_array(env, &result); + + for (size_t i = 0; i < moduleCount; i++) { + napi_value moduleObj; + napi_create_object(env, &moduleObj); + + // 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, modules[i].moduleName, NAPI_AUTO_LENGTH, &moduleName); + napi_set_named_property(env, moduleObj, "moduleName", moduleName); + + napi_value metadataArray; + napi_create_array(env, &metadataArray); + + for (size_t j = 0; j < modules[i].metadataArraySize; j++) { + napi_value metadataObj; + napi_create_object(env, &metadataObj); + + napi_value name; + napi_value value; + napi_value resource; + + napi_create_string_utf8(env, modules[i].metadataArray[j].name, NAPI_AUTO_LENGTH, &name); + napi_create_string_utf8(env, modules[i].metadataArray[j].value, NAPI_AUTO_LENGTH, &value); + napi_create_string_utf8(env, modules[i].metadataArray[j].resource, NAPI_AUTO_LENGTH, &resource); + + // Convert the metadata name obtained by calling the native API to the name property in the JavaScript object. + napi_set_named_property(env, metadataObj, "name", name); + // Convert the metadata value obtained by calling the native API to the value property in the JavaScript object. + napi_set_named_property(env, metadataObj, "value", value); + // Convert the metadata resource obtained by calling the native API to the resource property in the JavaScript object. + napi_set_named_property(env, metadataObj, "resource", resource); + + napi_set_element(env, metadataArray, j, metadataObj); + } + + napi_set_named_property(env, moduleObj, "metadata", metadataArray); + napi_set_element(env, result, i, moduleObj); + } + + // To prevent memory leak, manually release the memory. + for (size_t i = 0; i < moduleCount; i++) { + free(modules[i].moduleName); + for (size_t j = 0; j < modules[i].metadataArraySize; j++) { + free(modules[i].metadataArray[j].name); + free(modules[i].metadataArray[j].value); + free(modules[i].metadataArray[j].resource); + } + free(modules[i].metadataArray); + } + free(modules); + return result; + } + ``` + +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. +export const isDebugMode: () => string; // Add the exposed API isDebugMode. +export const getModuleMetadata: () => object; // Add the exposed API getModuleMetadata. +``` + +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); + let isDebugMode = testNapi.isDebugMode(); + console.info("bundleNDK isDebugMode success, isDebugMode is " + isDebugMode); + let moduleMetadata = testNapi.getModuleMetadata(); + console.info("bundleNDK getModuleMetadata success, data is " + JSON.stringify(moduleMetadata)); + }) + } + .width('100%') + } + .height('100%') + } + } + ``` For details about the APIs, see [Bundle](../reference/apis-ability-kit/_bundle.md). + + \ No newline at end of file diff --git a/en/application-dev/napi/native-netmanager-guidelines.md b/en/application-dev/napi/native-netmanager-guidelines.md deleted file mode 100644 index 402f147236ec0ca5384a6e356e62567b1dd8895a..0000000000000000000000000000000000000000 --- a/en/application-dev/napi/native-netmanager-guidelines.md +++ /dev/null @@ -1,223 +0,0 @@ -# Network Connection Development - -## When to Use - -The **NetConnection** module provides the capability of querying common network information. - -## Available APIs - -The following table lists the common **NetConnection** APIs. For details, see [NetConnection](../reference/apis-network-kit/_net_connection.md). - - -| API| **Test Description**| -| -------- | -------- | -| OH_NetConn_HasDefaultNet(int32_t \*hasDefaultNet) | Checks whether the default data network is activated and determines whether a network connection is available.| -| OH_NetConn_GetDefaultNet(NetConn_NetHandle \*netHandle) | Obtains the default active data network.| -| OH_NetConn_IsDefaultNetMetered(int32_t \*isMetered) | Checks whether the data traffic usage on the current network is metered.| -| OH_NetConn_GetConnectionProperties(NetConn_NetHandle \*netHandle, NetConn_ConnectionProperties *prop) | Obtains network connection information based on the specified **netHandle**.| -| OH_NetConn_GetNetCapabilities (NetConn_NetHandle \*netHandle, NetConn_NetCapabilities \*netCapacities) | Obtains network capability information based on the specified **netHandle**.| -| OH_NetConn_GetDefaultHttpProxy (NetConn_HttpProxy \*httpProxy) | Obtains the default HTTP proxy configuration of the network. If the global proxy is set, the global HTTP proxy configuration is returned. If the application has been bound to the network specified by **netHandle**, the HTTP proxy configuration of this network is returned. In other cases, the HTTP proxy configuration of the default network is returned.| -| OH_NetConn_GetAddrInfo (char \*host, char \*serv, struct addrinfo \*hint, struct addrinfo \*\*res, int32_t netId) | Obtains the DNS result based on the specified **netId**.| -| OH_NetConn_FreeDnsResult(struct addrinfo \*res) | Releases the DNS query result.| -| OH_NetConn_GetAllNets(NetConn_NetHandleList \*netHandleList) | Obtains the list of all connected networks.| -| OHOS_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver) | Registers a custom DNS resolver.
Note: This API is deprecated since API version 13.
You are advised to use **OH_NetConn_RegisterDnsResolver** instead.| -| OHOS_NetConn_UnregisterDnsResolver(void) | Unregisters a custom DNS resolver.
Note: This API is deprecated since API version 13.
You are advised to use **OH_NetConn_UnregisterDnsResolver** instead.| -| OH_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver) | Registers a custom DNS resolver.| -| OH_NetConn_UnregisterDnsResolver(void) | Unregisters a custom DNS resolver.| -| OH_NetConn_SetPacUrl(const char \*pacUrl) | Sets the URL of the system-level proxy auto-config (PAC) script.| -| OH_NetConn_GetPacUrl(char \*pacUrl) | Obtains the URL of the system-level PAC script.| - -## Development Example - -### How to Develop - -To use related APIs to obtain network information, you need to create a Native C++ project, encapsulate the APIs in the source file, and call these APIs at the ArkTs layer. You can use hilog or console.log to print the log information on the console or generate device logs. - -This document describes how to obtain the default active data network as an example. - -For details about other APIs, see the [Complete Sample Code](https://gitee.com/openharmony/applications_app_samples/tree/master/code/DocsSample/NetWork_Kit/NetWorkKit_NetManager/NetConnection_Exploitation_case). - -### Adding Dependencies - -**Adding the Dynamic Link Library** - -Add the following library to **CMakeLists.txt**. - -```txt -libace_napi.z.so -libnet_connection.so -``` - -**Including Header Files** - -```c -#include "napi/native_api.h" -#include "network/netmanager/net_connection.h" -#include "network/netmanager/net_connection_type.h" -``` - -### Building the Project - -1. Write the code for calling the API in the source file, encapsulate it into a value of the `napi_value` type, and return the value to the Node.js environment. - -```C -// Get the execution results of the default network connection. -static napi_value GetDefaultNet(napi_env env, napi_callback_info info) -{ - size_t argc = 1; - napi_value args[1] = {nullptr}; - napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); - int32_t param; - napi_get_value_int32(env, args[0], ¶m); - - NetConn_NetHandle netHandle; - if (param== 0) { - param= OH_NetConn_GetDefaultNet(NULL); - } else { - param= OH_NetConn_GetDefaultNet(&netHandle); - } - - napi_value result; - napi_create_int32(env, param, &result); - return result; -} - -// Get the ID of the default network connection. -static napi_value NetId(napi_env env, napi_callback_info info) { - int32_t defaultNetId; - - NetConn_NetHandle netHandle; - OH_NetConn_GetDefaultNet(&netHandle); - defaultNetId = netHandle.netId; // Get the default netId - - napi_value result; - napi_create_int32(env, defaultNetId, &result); - - return result; -} -``` - -> **NOTE**
The two functions are used to obtain information about the default network connection of the system. Wherein, GetDefaultNet is used to receive the test parameters passed from ArkTs and return the corresponding return value after the API is called. You can change param as needed. If the return value is **0**, the parameters are obtained successfully. If the return value is **401**, the parameters are incorrect. If the return value is **201**, the user does not have the operation permission. NetId indicates the ID of the default network connection. You can use the information for further network operations. - - -2. Initialize and export the `napi_value` objects encapsulated through **NAPI**, and expose the preceding two functions to JavaScript through external function APIs. - -```C -EXTERN_C_START -static napi_value Init(napi_env env, napi_value exports) -{ - // Information used to describe an exported attribute. Two properties are defined here: `GetDefaultNet` and `NetId`. - napi_property_descriptor desc[] = { - {"GetDefaultNet", nullptr, GetDefaultNet, nullptr, nullptr, nullptr, napi_default, nullptr}, - {"NetId", nullptr, NetId, nullptr, nullptr, nullptr, napi_default, nullptr}}; - napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); - return exports; -} -EXTERN_C_END -``` - -3. Register the objects successfully initialized in the previous step into the Node.js file by using the `napi_module_register` function of `RegisterEntryModule`. - -```C -static napi_module demoModule = { - .nm_version = 1, - .nm_flags = 0, - .nm_filename = nullptr, - .nm_register_func = Init, - .nm_modname = "entry", - .nm_priv = ((void*)0), - .reserved = { 0 }, -}; - -extern "C" __attribute__((constructor)) void RegisterEntryModule(void) -{ - napi_module_register(&demoModule); -} -``` - -4. Define the types of the two functions in the `index.d.ts ` file of the project. - -- The `GetDefaultNet ` function accepts the numeric parameter code and returns a numeric value. -- The `NetId` function does not accept parameters and returns a numeric value. - -```ts -export const GetDefaultNet: (code: number) => number; -export const NetId: () => number; -``` - -5. Call the encapsulated APIs in the `index.ets` file. - -```ts -import testNetManager from 'libentry.so'; - -@Entry -@Component -struct Index { - @State message: string = ''; - - build() { - Row() { - Column() { - Text(this.message) - .fontSize(50) - .fontWeight(FontWeight.Bold) - Button('GetDefaultNet').onClick(event => { - this.GetDefaultNet(); - }) - Button('CodeNumber').onClick(event =>{ - this.CodeNumber(); - }) - } - .width('100%') - } - .height('100%') - } - - GetDefaultNet() { - let netid = testNetManager.NetId(); - console.log("The defaultNetId is [" + netid + "]"); - } - - CodeNumber() { - let testParam = 0; - let codeNumber = testNetManager.GetDefaultNet(testParam); - if (codeNumber === 0) { - console.log("Test success. [" + codeNumber + "]"); - } else if (codeNumber === 201) { - console.log("Missing permissions. [" + codeNumber + "]"); - } else if (codeNumber === 401) { - console.log("Parameter error. [" + codeNumber + "]"); - } - } -} - -``` - -6. Configure the `CMakeLists.txt` file. Add the required shared library, that is, `libnet_connection.so`, to `target_link_libraries` in the `CMakeLists.txt` file automatically generated by the project. - -Note: As shown in the following figure, `entry` in `add_library` is the modename automatically generated by the project. If you want to change the `modename`, ensure that it is the same as the `.nm_modname` in step 3. - -![netmanager-4.png](./figures/netmanager-4.png) - -After the preceding steps, the entire project is set up. Then, you can connect to the device to run the project to view logs. - -## **Test Procedure** - -1. Connect the device and use DevEco Studio to open the project. - -2. Run the project. The following figure is displayed on the device. - -> NOTE - -- If you click `GetDefaultNet`, you'll obtain the default network ID. -- If you click `codeNumber`, you'll obtain the status code returned by the API. - -![netmanager-1.png](./figures/netmanager-1.png) - -3. Click `GetDefaultNet`. The following log is displayed, as shown below: - -![netmanager-2.png](./figures/netmanager-2.png) - -4. Click `codeNumber`. The status code is displayed, as shown below: - -![netmanager-3.png](./figures/netmanager-3.png) diff --git a/en/application-dev/napi/neon-guide.md b/en/application-dev/napi/neon-guide.md index a90e18e36dbcadf26a58d89b18f9df9f9560b077..09d59d2f0468122939dba91555ab133b6bcc5f07 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); } - ... + // ... } - ... + // ... } ``` @@ -101,3 +101,4 @@ The following example describes how to use Neon intrinsics in an armeabi-v7a Ope Now you can use Neon intrinsics in your project. + \ No newline at end of file diff --git a/en/application-dev/napi/ohos-abi.md b/en/application-dev/napi/ohos-abi.md index b0827d2c246b409466bebe6d95c81c780efdccb4..81122bd3dd3bdae824c5775c7ea2de4259e87dff 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 245e46aca389239a970bffb2c5cfbdd64cc8a3fd..5d2719c7abfce7af7f5191feb91f6c013b6d6034 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()); + ``` diff --git a/en/contribute/FAQ.md b/en/contribute/FAQ.md index 2c6852a521d719112f42ec9a314e4b2712ff8f02..8a0d1934b9ad1507533808c40d2140719290cd48 100644 --- a/en/contribute/FAQ.md +++ b/en/contribute/FAQ.md @@ -1,71 +1,87 @@ -# FAQs +# FAQ -## How Do I Create PRs at the Same Time If Multiple Code Repositories Have Compilation Dependencies? -During the development of the operating system \(OS\), it is common that multiple code repositories have compilation dependencies. Therefore, the PRs need to be created and merged at the same time. For this reason, Gitee uses issues as the association identifiers for code repositories with dependency dependencies to commit the PRs. Follow the operations below: +## Handling Simultaneous Builds for Multiple Repositories with Compilation Dependencies -1. Create an issue in any of the code repositories. -2. Associate PRs need to be built and merged at the same time with the issue. For details, visit [https://gitee.com/help/articles/4142](https://gitee.com/help/articles/4142). -3. After the build is triggered, the build center identifies the PRs associated with the same issue, downloads the build, and merges the PRs into the code library after the code is approved. +During OS development, it is typical to face situations where changes in multiple repositories are interdependent for compilation, requiring concurrent builds and integrations. To manage this, the Gitee platform employs Issues as a linking identifier for PRs from multiple repositories with such dependencies. Here is how you can do it: -## Sign-off-by Operations +1. Create an issue in any code repository involved in your submission. -#### How to Add signoff Records in Commits? +2. Associate PRs that need to be built and merged at the same time with the issue. For details, visit [https://gitee.com/help/articles/4142](https://gitee.com/help/articles/4142). -Execute the **git commit -s **or **git commit –sigoff** command to submit signoff records. +3. Once the build is initiated (for detailed steps on triggering builds, refer to the relevant help documentation), the build center will recognize PRs linked to the same Issue. It will then download and build these PRs simultaneously and merge them into the repository after the code review is successfully passed. -#### How to Add a signoff record to the Previous Commit? +## Signed-off-by Operations -Execute the **git commit --amend --signoff** command. +### Adding a signoff Record to a Commit -For more options about commit, see [https://](https://git-scm.com/docs/git-commit)[git-scm.com/docs/git-commit](https://git-scm.com/docs/git-commit). +To include a signoff in your commit, use the command `git commit -s` or `git commit –signoff`. -## Handling Exceptions of DCO Verification +### Appending a signoff Record to the Most Recent Commit -After developers submit Pull Request, commenting "**start build**" in the PR will trigger the gated commit. In this sense, you should consider: +Simply run the command `git commit --amend --signoff`. -1. Whether the DCO is signed. -2. Whether the commits contain Signed-off-by information. +For a comprehensive list of commit options, see [https://](https://git-scm.com/docs/git-commit)[git-scm.com/docs/git-commit](https://git-scm.com/docs/git-commit). -The possible causes for a verification failure include: +## DCO Verification Exception Handling -1. The DCO is not signed. The following messages will be displayed: +When you submit a PR and comments **start build**, the system triggers a gate check to verify: - ``` - The following commit users do not signed the DCO: +1. Whether the PR submission includes a Developer Certificate of Origin (DCO) signature. +2. Whether the PR submission contains Signed-off-by information. - •345612 +If the verification fails, here are some possible reasons and solutions: +1. You have not signed the Developer Certificate of Origin (DCO). Example: + + ``` + The following commits have users who have not signed the DCO agreement: + + •345612 + •213123 ``` **Solution** - Click [here](https://dco.openharmony.cn/sign) to sign the DCO or check the signing status. + Click [here](https://dco.openharmony.cn/sign) to sign the DCO and check the signing status. - Enter **check dco** in the Pull Requests comment box and click **Comment**. The system will check the DCO signing status again. + Enter **check dco** in the comment box of this PR and click **Comment**. The system will check DCO status again. -2. The commits do not contain Signed-off-by information. The following messages will be displayed: +2. The commit does not contain Signed-off-by. Example: ``` - The following commits do not contain Sign-off-by information: - + The following commits do not contain the Signed-off-by information: + + •123123 + •345612 - - •213123 ``` **Solution** - Add the Sign-off-by information by referring to **Sign-off-by Operations**. + Follow the Signed-off-by instructions to add the information. The format is: Signed-off-by: user.name + + Enter **check dco** in the comment box of this PR and click **Comment**. The system will check DCO status again. + + +3. The email address used for the PR submission on the web/WebIDE does not match the email address used to sign the DCO agreement. + + + **Solution** + + On the **Settings > Email management** page of Gitee, check whether the email address is correctly configured. Ensure that the commit email address is the same as the email address used for signing the DCO. + + > **NOTE** + > + > If **Keep my email address private** is selected in **Email management**, an *xxxx@user.noreply.gitee.com* email will be used as the PR submission email by default. To use a different email for submissions, uncheck **Keep my email address private**. - Enter **check dco** in the Pull Requests comment box and click **Comment**. The system will check the DCO signing status again. -## Rollback -Visit [https://gitee.com/help/articles/4195](https://gitee.com/help/articles/4195). +## Rolling Back Commits -## Resolving Merge Conflicts +For guidance on rolling back commits, see [https://gitee.com/help/articles/4195](https://gitee.com/help/articles/4195). -Visit [https://gitee.com/help/articles/4194](https://gitee.com/help/articles/4194). +## Resolving conflicts +For instructions on resolving conflicts, see [https://gitee.com/help/articles/4194](https://gitee.com/help/articles/4194). diff --git a/en/contribute/template/errorcodes-template.md b/en/contribute/template/errorcodes-template.md index 3b6e68ab1e1a980b669da62fea2a740da6f373be..3786363cff755d7e0b07fecb08dd02a6c85d7660 100644 --- a/en/contribute/template/errorcodes-template.md +++ b/en/contribute/template/errorcodes-template.md @@ -5,14 +5,17 @@ > 1. Delete all writing instructions from your document after you finish the writing. > > 2. The error code document must be named in the format of **errorcode-*moduleName*.md**, where *moduleName* must be the same as that used in the corresponding API reference document. +> +> *3. If a kit includes only generic error codes, an error code page is not required.* | | Item | Writing Instruction | | ---- | ------------------------------ | ------------------------------------------------------------ | | 1 | error.errorNumber | Use the error code IDs that are designed based on the unified error code numbering rule. | | 2 | error.message | **Meaning of this field**: If an exception occurs, an error object is thrown. The object contains **errorNumber** and **error.message**, which is a short text description of the error code in English.
**Instructions**
1. The description should be concise and specific.
2. The description should be grammatically correct. | -| 3 | Description | **Meaning of this field**: provides detailed description for the error code, including the use case when and the location where the error code is thrown.
**Instructions**
1. Describe the use case when the error code is thrown, for example, when developing a specific service or feature.
2. Describe the symptom and location of the error (for example, the exact module name, class name, and interface name).| -| 4 | Possible Causes | **Meaning of this field**: lists all possible causes of the error.
**Instructions**
1. List all the possible causes.
2. Use concise sentences.
3. Sort the causes by possibility in descending order.| -| 5 | Procedure | **Meaning of this field**: describes how to handle the error based on the symptom and possible causes.
**Instructions**
1. Provide the procedure step by step. Each step should correspond to a possible cause. You can use substeps for complex operations of a step.
2. The steps should be clear, specific, and executable. If judgment is involved, provide clear judgment criteria.
3. If an operation has impact on the system or services, provide warning information in the form of Caution or Warning before the operation. | +| 3 |
|

| +| 4 |
Description | **Meaning of this field**: provides detailed description for the error code, including the use case when and the location where the error code is thrown.
**Instructions**
1. Describe the use case when the error code is thrown, for example, when developing a specific service or feature.
2. Describe the symptom and location of the error (for example, the exact module name, class name, and interface name).| +| 5 | Possible cause
Possible Causes | **Meaning of this field**: lists all possible causes of the error.
**Instructions**
1. List all the possible causes.
2. Use concise sentences.
3. Sort the causes by possibility in descending order.| +| 6 | Procedure
Procedure | **Meaning of this field**: describes how to handle the error based on the symptom and possible causes.
**Instructions**
1. Provide the procedure step by step. Each step should correspond to a possible cause. You can use substeps for complex operations of a step.
2. The steps should be clear, specific, and executable. If judgment is involved, provide clear judgment criteria.
3. If an operation has impact on the system or services, provide warning information in the form of Caution or Warning before the operation. | ## 1300001 Repeated Operation (Error Code + Space + Error Description) @@ -93,7 +96,7 @@ xxx **Possible Causes** -1. xxx +xxx **Procedure** diff --git a/en/contribute/template/guide-template.md b/en/contribute/template/guide-template.md index 62645067bba7f469b8fd5ce5ca21b3e39450ad55..ab0e3a9b8a38845dee6215894aed82fe6bed6865 100644 --- a/en/contribute/template/guide-template.md +++ b/en/contribute/template/guide-template.md @@ -204,7 +204,7 @@ _What are the constraints for using the kit/solution/feature/function/module? Ho _**[Key Writing Points]**_ - _Describe perceptible constraints that affect development activities, including but not limited to the following:_ - - _Function constraints_ + - **_Function constraints_** - _Application scope of the solution/feature/function/module (Specify scenarios that are not supported.)_ - _Specification constraints_ - _**Operation constraints**_ @@ -215,7 +215,7 @@ _**[Key Writing Points]**_ ***[Example]*** -- This function is available only for XXX devices of XXX and later versions. +- Device constraints: XXX (the official device category name, such as 2-in-1) devices do not support using this kit. or This kit is only applicable to (the official device category name, such as 2-in-1) devices. or Only XXX devices of version XXXXXX and above can use this kit. - Data synchronization can be implemented across devices only for the applications with the same bundleName. diff --git a/en/contribute/template/js-template.md b/en/contribute/template/js-template.md index d0b8eb4b80ce3f76136f4eb005ecf2c8eeea5d1e..4bbeba22180632fb7e71bb7529cb9c831b1aa457 100644 --- a/en/contribute/template/js-template.md +++ b/en/contribute/template/js-template.md @@ -25,13 +25,14 @@ For a property or interface table, if a tag has the same value for all the items | d.ts Tag| Description| Document Field| | ---------- | ---- | ------- | -| @since | Version description| 1. Use the greater-than sign (>) followed by a space to indent the description about the initial version of the module. Unless otherwise marked, all APIs in the module have the same initial version.
2. When introducing an API to an existing module, use the `` tag to mark its earliest version. The format is `versionNumber+`, for example, `7+`.

When introducing a property to an existing module, suffix the `` tag to the new property name, for example, `newProperty7+`.
When introducing a method to an existing module, suffix the `` tag to the method name, for example, `sim.getSimIccId7+`. The same rule applies to new interfaces, classes, and enums.| +| @since | Version description| 1. Use the greater-than sign (>) followed by a space to indent the description about the initial version of the module. Unless otherwise marked, all APIs in the module have the same initial version.
2. When introducing an API to an existing module, use the `` tag to mark its earliest version. The format is `versionNumber+`, for example, `7+`.

When introducing a property to an existing module, suffix the `` tag to the new property name, for example, `newProperty7+`.
When introducing a method to an existing module, suffix the `` tag to the method name, for example, `sim.getSimIccId7+`. The same rule applies to new interfaces, classes, and enums.
Due to the rectification of anonymous objects, the version number of the outer element of some APIs is later than that of the inner element. To avoid any confusion for developers, a uniform explanation should be added in the **Interface Description** section: To standardize the definition of anonymous objects, the element definitions have been modified in API version *XX*. The initial version information of the historical anonymous objects has been retained, which may result in the outer element's @since version number being later than the inner element's version number. However, this does not affect the use of the API.| | @deprecated | Deprecated description| Do not delete the deprecated content from the document. Instead, suffix `deprecated` as a superscript to the content, and use the greater-than sign (>) to introduce the initial version and deprecated version.
Example: abandonmentMethod(deprecated)
> This API is supported since API version 4 and deprecated since API version 7. You are advised to use [newMethod]\(#newmethod) instead.| | @FAModelOnly / @StageModelOnly | Model restriction description| **Model restriction**: This API can be used only in the FA model. **Model restriction**: This API can be used only in the stage model.| | @form | Widget capability description| **Widget capability**: Since API version *x*, this feature is supported in ArkTS widgets.| +| @atomicservice | Atomic service description| **Atomic service API**: This API can be used in atomic services since API version *x*.| | @systemapi | System API description| **System API**: This is a system API.| -| @syscap | System capability description| **System capability**: SystemCapability.*A.B*| -| @permission | Permission description| 1. If only one permission is required for using the API, use the following format:
**Required permissions**: ohos.permission.examplePermission
2. If multiple permissions are required for using the API, provide the permissions with **and** or **or** in the following format:
**Required permissions**: ohos.permission.examplePermissionA and ohos.permission.examplePermissionB
**Required permissions**: ohos.permission.examplePermissionA or ohos.permission.examplePermissionB| +| @syscap | System capability description| **System capability**: SystemCapability.*A.B*| 1. If only one permission is required for using the API, use the following format:
**Required permissions**: ohos.permission.examplePermission
2. If multiple permissions are required for using the API, provide the permissions with **and** or **or** in the following format:
**Required permissions**: ohos.permission.examplePermissionA and ohos.permission.examplePermissionB
**Required permissions**: ohos.permission.examplePermissionA or ohos.permission.examplePermissionB| +| @permission | Permission description| 1. If only one permission is required for using the API, use the following format:
**Required permissions**: ohos.permission.examplePermission
2. If multiple permissions are required for using the API, provide the permissions with **and** or **or** in the following format:
**Required permissions**: ohos.permission.examplePermissionA and ohos.permission.examplePermissionB
**Required permissions**: ohos.permission.examplePermissionA or ohos.permission.examplePermissionB
3. When there is a version change involved, follow the current version's permission requirement after **Required permissions**, and describe the historical version's permission requirement in a new line as a list. Example:
**Required permissions**: ohos.permission.A
- ohos.permission.A and ohos.permission.B for API x-(y-1)
- ohos.permission.A from API y
4. When permissions are required only in certain fixed scenarios, follow the @permission in the .d.ts file consistently after **Required permissions**, and then supplement with a situation description. There are two types of situations. When the situation is relatively simple, use parentheses to add a description. When the situation is more complex, use a new line for the description.
Example 1:
**Required permissions**: ohos.permission.A (required only when the window type is **AA**.)
Example 2:
**Required permissions**: ohos.permission.A
- When the application is in situation xx, ohos.permission.B is also required.
- When the application is in situation yy, no permission is required.| | @extends | Inheritance| If the tag is carried or the extends relationship exists but the tag is not carried, clearly state the following information: *ExampleA* inherits from *ExampleB* (provide the link of *ExampleB*).| The following describes the instructions for writing a specific API reference document. @@ -124,7 +125,7 @@ import { call } from '@kit.TelephonyKit'; > *Writing Instructions* > > - This section is optional. Delete it if there is no constant. It corresponds to `const` in the .d.ts file. -> +> - Some constants are used to define read-only variables and have no values. In this case, the table contains four columns: Name, Type, Read Only, and Description. > - If a property is of a custom type, create a link to the corresponding interface or enum. **System capability**: SystemCapability.*A.B* (This part is mandatory.) @@ -203,9 +204,10 @@ For details about the error codes, see [moduleName Error Codes]\(link to the err ```js // This part is mandatory. -// Check all sample code provided in the example. +// All example code must be self-checked to ensure that the execution results meet expectations. // Minor errors such as missing symbols and variable inconsistency are unacceptable. // Declare all variables that are used. +// When the interface parameters are abnormal, it is necessary to verify whether the code can catch the error and throw the corresponding error code. // Write an actual case that can be easily used, rather than the parameter names themselves. Use comments to describe the content that are not user-defined. // Example: let result = xxx.createExample(parameterOne); // parameterOne is automatically obtained by scanning. @@ -244,7 +246,7 @@ Describe the method. For details, see the fourth and fifth points in "Writing In | Name | Type | Mandatory| Description | | -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Describe the event and when or how it will be triggered. If a method involves multiple events, describe them separately.
**Example 1 (single event):**
Type of the event. The **'play'** event is triggered when the **play()** API is called and audio playback starts.
Example 2 (multiple events):
Type of the event. The following events are supported:
- **'play'**: triggered when the **play()** API is called and audio playback starts.
- **'dataLoad'**: triggered when the audio data is loaded, that is, when the **src** property is configured.
- **'finish'**: triggered when the audio playback is finished.| +| type | string | Yes | Describe the event and when or how it will be triggered. If a method involves multiple events, describe them separately.
**Example 1 (single event):**
Type of the event. The **'play'** event is triggered when the **play()** API is called and audio playback starts.
Example 2 (multiple events):
Type of the event. The following events are supported:| |
- **'play'**: triggered when the **play()** API is called and audio playback starts.
- **'dataLoad'**: triggered when the audio data is loaded, that is, when the **src** property is configured.
- **'finish'**: triggered when the audio playback is finished.| | callback | Callback\<[CustomType](#classinterface)> | No | Describe the parameter. The instructions are the same as those provided under [Methods](#methods). | **Return value** (This part is optional. Delete it if there is no return value.) @@ -287,7 +289,7 @@ Describe the class or interface. If there are usage restrictions, describe them > *Writing Instructions* > -> Except that level-3 headings are used, other requirements are the same as those in [Properties](#properties). Write the interface name in the form of level-2 headings. +> Except that level-3 headings are used, other requirements are the same as those in [Properties](#properties). Write the interface name in the form of level-2 heading. ### Methods in Classes/Interfaces @@ -348,7 +350,7 @@ Provide the logic for obtaining the actual value of this type. Example: The valu ### Type Template 2 -(The function alias is used as an example. If the type is an interface alias, refer to the interface template.) +*(The function alias is used as an example.)* (Provide the definition of the type here.) type Xxx\ = (param1: number, param2: string) => Interface1 @@ -367,9 +369,30 @@ Provide the logic for obtaining the actual value of this type. Example: The valu | ------ | ------------------------------------- | | [Interface1](#interface1) | Describe the return value. The instructions are the same as those provided under [Methods](#methods).| +### Type Template 3 + +*(Here, an Interface alias containing multiple property fields is used as an example)* + +*Provide the specific definition form of type here: type Xxx = { aaa: string; bbb?: number; }* + +**System capability**: SystemCapability.*A.B* (This part is mandatory.) + + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | +| aaa | string | Yes| Describes the property.| +| bbb | number | No| Describes the property.| + ## Change History + | Change Description | Date | | ----------------------------------------------------------------------- | ------------ | +| Streamlined the standard wording for Promise\. New content should use the new wording. There is no need to actively revise existing content if it already conveys the intended meaning. | 2025/06/10 | +| Added a standard wording for "Explanation of the @since version number for anonymous object rectification."| 2025/06/03 | +| Optimized the writing standards for permissions to cover various types of permission descriptions and meet the requirements of scanning tools.| 2025/03/12 | +| Added Type template 3, which includes an interface alias with multiple property fields.| 2025/03/04 | +| Added a requirement for example code to capture parameter exceptions.| 2025/03/03 | +| Added a template for read-only variables defined by constants.| 2024/12/31 | | 1. Updated the method template by adding the description of methods carrying the declaration of keywords such as `static`.| 2024/05/16 | | 1. Updated the type template. In addition to the union type, the intersection type and the type used as the alias of a function or interface were added.
2. Updated the property template to specify the rules for determining optional properties in the interfaces and interface definitions.| 2024/05/10 | | 1. Changed the template for **Properties** from **Read**, **Write**, and **Mandatory** to **Read Only** and **Mandatory**.
2. Changed the template for **Types** by using **Value Range** and **Description**, and provided the related description.
3. Deleted the custom type, and incorporated the related description under **Classes/Interfaces**.| 2023/02/01 |