diff --git a/.config/APIConsistency-Profiles-20250318.xlsx b/.config/APIConsistency-Profiles-20250318.xlsx
new file mode 100644
index 0000000000000000000000000000000000000000..f2c09e7f05737c99bb83059fe551ab85ff2f5f6e
Binary files /dev/null and b/.config/APIConsistency-Profiles-20250318.xlsx differ
diff --git a/.config/APIConsistency-Whitelist-20250318.xlsx b/.config/APIConsistency-Whitelist-20250318.xlsx
new file mode 100644
index 0000000000000000000000000000000000000000..5a33a207badfed2b86c85cc1fb605a16eeae122a
Binary files /dev/null and b/.config/APIConsistency-Whitelist-20250318.xlsx differ
diff --git a/.config/Profiles.json b/.config/Profiles.json
new file mode 100644
index 0000000000000000000000000000000000000000..efe95bc7084a477008231ee8a012c19eaa97e9f7
--- /dev/null
+++ b/.config/Profiles.json
@@ -0,0 +1,38 @@
+{
+ "sampleCodeAccuracy": {
+ "AC": [
+ {
+ "branch": "OpenHarmony-5.1.0-Release",
+ "sdkVersion": "18"
+ }
+ ],
+ "CI": [
+ {
+ "branch": "master",
+ "sdkVersion": "20"
+ },
+ {
+ "branch": "OpenHarmony-5.1.0-Release",
+ "sdkVersion": "18"
+ }
+ ]
+ },
+ "deprecatedInterface": {
+ "AC": [
+ {
+ "branch": "master",
+ "sdkVersion": "20"
+ }
+ ],
+ "CI": [
+ {
+ "branch": "master",
+ "sdkVersion": "20"
+ },
+ {
+ "branch": "OpenHarmony-5.1.0-Release",
+ "sdkVersion": "18"
+ }
+ ]
+ }
+}
\ No newline at end of file
diff --git a/.config/SampleCodeAccuracy-Profiles-20250318.xlsx b/.config/SampleCodeAccuracy-Profiles-20250318.xlsx
new file mode 100644
index 0000000000000000000000000000000000000000..a03001197e0f0fb4fcaf9ebec4f1ee4cd2ca0077
Binary files /dev/null and b/.config/SampleCodeAccuracy-Profiles-20250318.xlsx differ
diff --git a/CODEOWNERS b/CODEOWNERS
index a1c0914b1684a1ff45ab78499d473a602614b5f8..092a86593c3fb2da4da39204136ea3729329434b 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -19,24 +19,24 @@ zh-cn/release-notes/changelogs/ @ang-huawei
zh-cn/release-notes/changelogs/**/changelogs-ability.md @ang-huawei @huipeizi
[设备开发]
-zh-cn/device-dev/ @li-yan339 @zengyawen
+zh-cn/device-dev/ @li-yan339 @zengyawen @fang-jinxu
[入门-快速入门]
zh-cn/application-dev/quick-start/start-overview.md @ge-yafang
zh-cn/application-dev/quick-start/start-with-ets-stage.md @ge-yafang
[入门-开发基础知识-应用程序包基础知识与应用配置文件]
-zh-cn/application-dev/quick-start/app*.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/quick-start/module*.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/quick-start/multi-hap*.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/quick-start/deviceconfig-structure.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/quick-start/shared-guide.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/quick-start/har-package.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/quick-start/in-app-hsp.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/quick-start/quickfix*.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
+zh-cn/application-dev/quick-start/app*.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/quick-start/module*.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/quick-start/multi-hap*.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/quick-start/deviceconfig-structure.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/quick-start/shared-guide.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/quick-start/har-package.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/quick-start/in-app-hsp.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/quick-start/quickfix*.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
[入门-资源分类与访问]
-zh-cn/application-dev/quick-start/resource-categories-and-access.md @Buda-Liu @Brilliantry_Rui @budda-wang @yangqing3
+zh-cn/application-dev/quick-start/resource-categories-and-access.md @Brilliantry_Rui @yangqing3 @lliule21 @lpw_work
[入门-学习Arkts语言]
zh-cn/application-dev/quick-start/arkts-get-started.md @zhang_yixin13 @qyhuo32
@@ -244,48 +244,52 @@ zh-cn/application-dev/ui/arkts-layout-development-media-query.md @laigerendaqiu
zh-cn/application-dev/ui/arkts-layout-development-create-list.md @yeyinglong_admin @cc520bf @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/arkts-layout-development-create-grid.md @zcdqs @cc520bf @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/arkts-layout-development-create-looping.md @yan-shuifeng @cc520bf @fredyuan0912 @HelloCrease
-zh-cn/application-dev/ui/arkts-common-components-button.md @luyuxuan1 @HelloCrease @youzhi92
-zh-cn/application-dev/ui/arkts-common-components-radio-button.md @youzhi92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-common-components-switch.md @luyuxuan1 @HelloCrease @youzhi92
+zh-cn/application-dev/ui/arkts-common-components-button.md @li-xinlei007 @HelloCrease @firminly
+zh-cn/application-dev/ui/arkts-common-components-radio-button.md @houguobiao @li-xinlei007 @HelloCrease
+zh-cn/application-dev/ui/arkts-common-components-switch.md @li-xinlei007 @HelloCrease @houguobiao
zh-cn/application-dev/ui/arkts-common-components-progress-indicator.md @yeyinglong_admin @cc520bf @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/arkts-common-components-text-display.md @crazyracing0726 @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/arkts-common-components-text-input.md @crazyracing0726 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/ui/arkts-common-components-custom-dialog.md @luyuxuan1 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-common-components-custom-dialog.md @li-xinlei007 @HelloCrease @houguobiao
zh-cn/application-dev/ui/arkts-common-components-video-player.md @keerecles @ZhangYu-Home @fredyuan0912 @HelloCrease
-zh-cn/application-dev/ui/arkts-common-components-xcomponent.md @keerecles @ZhangYu-Home @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-popup-and-menu-components-popup.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/ui/arkts-popup-and-menu-components-menu.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/ui/arkts-routing.md @raulnaruto_admin @luyuxuan1 @HelloCrease
+zh-cn/application-dev/ui/arkts-common-components-xcomponent.md @keerecles @ZhangYu-Home @HelloCrease
+zh-cn/application-dev/ui/arkts-popup-and-menu-components-popup.md @li-xinlei007 @HelloCrease @firminly
+zh-cn/application-dev/ui/arkts-popup-and-menu-components-uicontext-popup.md @li-xinlei007 @HelloCrease @firminly
+zh-cn/application-dev/ui/arkts-popup-and-menu-components-menu.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-popup-and-menu-components-uicontext-menu.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-popup-overview.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-dialog-overview.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-routing.md @raulnaruto_admin @HelloCrease
zh-cn/application-dev/ui/arkts-navigation-navigation.md @jiangdayuan @raulnaruto_admin @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/arkts-navigation-tabs.md @yan-shuifeng @cc520bf @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/arkts-graphics-display.md @lexiaoyao2 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/ui/arkts-geometric-shape-drawing.md @keerecles @seaside_wu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-drawing-customization-on-canvas.md @keerecles @ZhangYu-Home @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-animation.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-attribute-animation-overview.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-attribute-animation-apis.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-custom-attribute-animation.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-transition-overview.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-enter-exit-transition.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-navigation-transition.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-modal-transition.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-shared-element-transition.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-page-transition-animation.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-component-animation.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-curve-overview.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-traditional-curve.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-spring-curve.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-animation-smoothing.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-blur-effect.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-shadow-effect.md @lightningHo @huaweimaxuchu @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-color-effect.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-event-overview.md @zhaojian2021 @jiangtao92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-common-events-touch-screen-event.md @zhaojian2021 @jiangtao92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-common-events-device-input-event.md @zhaojian2021 @jiangtao92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-common-events-focus-event.md @piggyguy @jiangtao92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-gesture-events-binding.md @zhaojian2021 @jiangtao92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-gesture-events-single-gesture.md @zhaojian2021 @jiangtao92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/ui/arkts-gesture-events-combined-gestures.md @zhaojian2021 @jiangtao92 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/ui/arkts-geometric-shape-drawing.md @keerecles @seaside_wu @HelloCrease
+zh-cn/application-dev/ui/arkts-drawing-customization-on-canvas.md @keerecles @ZhangYu-Home @HelloCrease
+zh-cn/application-dev/ui/arkts-animation.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-attribute-animation-overview.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-attribute-animation-apis.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-custom-attribute-animation.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-transition-overview.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-enter-exit-transition.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-navigation-transition.md @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-modal-transition.md @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-shared-element-transition.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-page-transition-animation.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-component-animation.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-curve-overview.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-traditional-curve.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-spring-curve.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-animation-smoothing.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-blur-effect.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-shadow-effect.md @hehongyang9 @lightningHo @huaweimaxuchu @HelloCrease
+zh-cn/application-dev/ui/arkts-color-effect.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/ui/arkts-event-overview.md @piggyguy @jiangtao92 @HelloCrease
+zh-cn/application-dev/ui/arkts-common-events-touch-screen-event.md @piggyguy @jiangtao92 @HelloCrease
+zh-cn/application-dev/ui/arkts-common-events-device-input-event.md @piggyguy @jiangtao92 @HelloCrease
+zh-cn/application-dev/ui/arkts-common-events-focus-event.md @piggyguy @jiangtao92 @HelloCrease
+zh-cn/application-dev/ui/arkts-gesture-events-binding.md @piggyguy @jiangtao92 @HelloCrease
+zh-cn/application-dev/ui/arkts-gesture-events-single-gesture.md @piggyguy @jiangtao92 @HelloCrease
+zh-cn/application-dev/ui/arkts-gesture-events-combined-gestures.md @piggyguy @jiangtao92 @HelloCrease
zh-cn/application-dev/ui/arkts-user-defined.md @sunfei2021 @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/arkts-user-defined-node.md @sunfei2021 @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/arkts-user-defined-place-hoder.md @sunfei2021 @fredyuan0912 @HelloCrease
@@ -301,16 +305,16 @@ zh-cn/application-dev/ui/ndk-loading-long-list.md @yan-shuifeng @fredyuan0912 @H
zh-cn/application-dev/ui/ndk-build-pop-up-window.md @yan-shuifeng @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/ndk-build-custom-components.md @yan-shuifeng @fredyuan0912 @HelloCrease
zh-cn/application-dev/ui/ndk-embed-arkts-components.md @yan-shuifeng @fredyuan0912 @HelloCrease
-zh-cn/application-dev/ui/arkts-dialog-overview.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/ui/arkts-base-dialog-overview.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/ui/arkts-uicontext-custom-dialog.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/ui/arkts-fixes-style-dialog.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/ui/arkts-modal-overview.md @luyuxuan1 @HelloCrease @cheng-feiwang
-zh-cn/application-dev/ui/arkts-sheet-page.md @luyuxuan1 @HelloCrease @cheng-feiwang
-zh-cn/application-dev/ui/arkts-contentcover-page.md @luyuxuan1 @HelloCrease @cheng-feiwang
-zh-cn/application-dev/ui/arkts-create-toast.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/ui/arkts-create-overlaymanager.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/ui/arkts-advanced-components-arcbutton.md @luyuxuan1 @HelloCrease
+zh-cn/application-dev/ui/arkts-dialog-overview.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-base-dialog-overview.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-uicontext-custom-dialog.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-fixes-style-dialog.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-modal-overview.md @li-xinlei007 @HelloCrease @cheng-feiwang
+zh-cn/application-dev/ui/arkts-sheet-page.md @HelloCrease @cheng-feiwang
+zh-cn/application-dev/ui/arkts-contentcover-page.md @HelloCrease @cheng-feiwang
+zh-cn/application-dev/ui/arkts-create-toast.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-create-overlaymanager.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/ui/arkts-advanced-components-arcbutton.md @li-xinlei007 @HelloCrease
[开发-ArkUI-窗口管理]
zh-cn/application-dev/windowmanager/ @ge-yafang @zhangqiang183 @zhouyaoying @zxg-gitee @nobuggers @qinliwen
@@ -318,19 +322,20 @@ zh-cn/application-dev/application-models/windowextensionability.md @zhangqiang18
[开发-Arkweb]
-zh-cn/application-dev/web/ @bigpumpkin @HelloCrease @litao33 @zhang-xinyue15
-
+zh-cn/application-dev/web/ @bigpumpkin @HelloCrease @litao33 @GHiker
[开发-Background Tasks Kit]
-zh-cn/application-dev/task-management/background-task-overview.md @Brilliantry_Rui
-zh-cn/application-dev/task-management/transient-task.md @Brilliantry_Rui
-zh-cn/application-dev/task-management/continuous-task.md @Brilliantry_Rui
-zh-cn/application-dev/task-management/work-scheduler.md @Brilliantry_Rui
-zh-cn/application-dev/task-management/agent-powered-reminder.md @Brilliantry_Rui
-zh-cn/application-dev/task-management/efficiency-resource-request.md @Brilliantry_Rui
-h-cn/application-dev/task-management/native-transient-task.md @Brilliantry_Rui @Brilliantry_Rui
-zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md @Brilliantry_Rui
-zh-cn/application-dev/device-usage-statistics/device-usage-statistics-use-guide.md @Brilliantry_Rui
+zh-cn/application-dev/task-management/ @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/task-management/background-task-overview.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/task-management/transient-task.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/task-management/continuous-task.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/task-management/work-scheduler.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/task-management/agent-powered-reminder.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/task-management/efficiency-resource-request.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/task-management/native-transient-task.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/device-usage-statistics/ @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/device-usage-statistics/device-usage-statistics-use-guide.md @Brilliantry_Rui @zhouben25 @cooffee10
[开发-Basic Services Kit-帐号]
zh-cn/application-dev/account/ @zengyawen
@@ -374,7 +379,7 @@ zh-cn/application-dev/device/externaldevice-guidelines.md @li-yan339
[开发-Form Kit]
-zh-cn/application-dev/form/ @Eiln @cmz001 @Brilliantry_Rui @yuanzhishuai @ylsnow
+zh-cn/application-dev/form/ @ylsnow @cmz001 @Brilliantry_Rui @Eiln
[开发-DFX]
@@ -394,25 +399,26 @@ zh-cn/application-dev/inputmethod/inputmethod_application_guide.md @illybyy @mur
zh-cn/application-dev/inputmethod/switch_inputmehod_guide.md @illybyy @murphy1984 @feng-aiwen @zhang_yixin13 @SuperShrimp
[开发-Input kit]
-zh-cn/application-dev/device/inputdevice-guidelines.md @Brilliantry_Rui @mayunteng
-zh-cn/application-dev/device/pointerstyle-guidelines.md @Brilliantry_Rui @mayunteng
-zh-cn/application-dev/device/inputmonitor-guidelines.md @Brilliantry_Rui @mayunteng
-zh-cn/application-dev/device/inputeventclient-guidelines.md @Brilliantry_Rui @mayunteng
-zh-cn/application-dev/device/inputconsumer-guidelines.md @Brilliantry_Rui @mayunteng
-zh-cn/application-dev/device/shortkey-guidelines.md @Brilliantry_Rui @mayunteng
-zh-cn/application-dev/device/input-overview.md @Brilliantry_Rui @mayunteng
-zh-cn/application-dev/device/monitor-guidelines.md @Brilliantry_Rui @mayunteng
-zh-cn/application-dev/device/interceptor-guidelines.md @Brilliantry_Rui @mayunteng
+zh-cn/application-dev/device/input @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/inputdevice-guidelines.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/pointerstyle-guidelines.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/inputmonitor-guidelines.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/inputeventclient-guidelines.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/inputconsumer-guidelines.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/shortkey-guidelines.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/input-overview.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/monitor-guidelines.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
+zh-cn/application-dev/device/interceptor-guidelines.md @Brilliantry_Rui @mayunteng @ustblx @hanruofei
[开发-IPC Kit]
-zh-cn/application-dev/connectivity/ipc-rpc-overview.md @zhang_yixin13 @luodh0157 @zhaopeng_gitee @zhang-yang123321
-zh-cn/application-dev/connectivity/ipc-rpc-development-guideline.md @zhang_yixin13 @luodh0157 @zhaopeng_gitee @zhang-yang123321
-zh-cn/application-dev/connectivity/subscribe-remote-state.md @zhang_yixin13 @luodh0157 @zhaopeng_gitee @zhang-yang123321
+zh-cn/application-dev/connectivity/ipc-rpc-overview.md @zhang_yixin13 @xdx1921 @zhaopeng_gitee @zhang-yang123321
+zh-cn/application-dev/connectivity/ipc-rpc-development-guideline.md @zhang_yixin13 @xdx1921 @zhaopeng_gitee @zhang-yang123321
+zh-cn/application-dev/connectivity/subscribe-remote-state.md @zhang_yixin13 @xdx1921 @zhaopeng_gitee @zhang-yang123321
[开发-Localization Kit]
-zh-cn/application-dev/internationalization/ @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu
+zh-cn/application-dev/internationalization/ @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu @lpw_work
zh-cn/application-dev/internationalization/i18n-l10n.md @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu
zh-cn/application-dev/internationalization/i18n-ui-design.md @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu
zh-cn/application-dev/internationalization/i18n-locale-culture.md @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu
@@ -450,9 +456,9 @@ zh-cn/application-dev/device/device-location-geocoding.md @RayShih
zh-cn/application-dev/media/ @zengyawen
[开发-MDM Kit]
-zh-cn/application-dev/mdm/mdm-kit-intro.md @Brilliantry_Rui
-zh-cn/application-dev/mdm/mdm-kit-guide.md @Brilliantry_Rui
-zh-cn/application-dev/mdm/mdm-kit-admin.md @Brilliantry_Rui
+zh-cn/application-dev/mdm/mdm-kit-intro.md @liuzuming @Brilliantry_Rui @yangqing3
+zh-cn/application-dev/mdm/mdm-kit-guide.md @liuzuming @Brilliantry_Rui @yangqing3
+zh-cn/application-dev/mdm/mdm-kit-admin.md @liuzuming @Brilliantry_Rui @yangqing3
[开发-MindSpore Lite Kit]
zh-cn/application-dev/ai/MindSpore-Lite-Kit-Introduction.md @ge-yafang @principal87 @limingjiang
@@ -471,7 +477,7 @@ zh-cn/application-dev/device/stationary-guidelines.md @mayunteng_1 @hu-zhiqiong
[开发-Network Kit]
-zh-cn/application-dev/network/ @zhang_yixin13 @jiayanhong-hw @w30013702 @rain_myf
+zh-cn/application-dev/network/ @zhang_yixin13 @lbch_hw
[开发-Neural NetWork Runtime Kit]
@@ -514,15 +520,15 @@ zh-cn/application-dev/device/sensor/sensor-guidelines-as.md @hu-zhiqiong @lixian
[开发-Telephony Kit]
-zh-cn/application-dev/telephony/telephony-overview.md @zhang_yixin13 @jiayanhong-hw @w30013702 @dingxiaochen
-zh-cn/application-dev/telephony/telephony-call.md @zhang_yixin13 @jiayanhong-hw @w30013702 @dingxiaochen
-zh-cn/application-dev/telephony/telephony-sms.md @zhang_yixin13 @jiayanhong-hw @w30013702 @dingxiaochen
+zh-cn/application-dev/telephony/telephony-overview.md @zhang_yixin13
+zh-cn/application-dev/telephony/telephony-call.md @zhang_yixin13
+zh-cn/application-dev/telephony/telephony-sms.md @zhang_yixin13
[开发-Test Kit]
-zh-cn/application-dev/application-test/arkxtest-guidelines.md @Brilliantry_Rui @inter515
-zh-cn/application-dev/application-test/smartperf-guidelines.md @Brilliantry_Rui @niuguoliang @xielinnan
-zh-cn/application-dev/application-test/wukong-guidelines.md @Brilliantry_Rui
+zh-cn/application-dev/application-test/arkxtest-guidelines.md @Brilliantry_Rui @inter515 @laonie666 @lv_yu_peng
+zh-cn/application-dev/application-test/smartperf-guidelines.md @Brilliantry_Rui @inter515 @niuguoliang @laonie666 @lv_yu_peng
+zh-cn/application-dev/application-test/wukong-guidelines.md @Brilliantry_Rui @qkfg @caixincen
[开发-Webgl]
zh-cn/application-dev/webgl/ @ge-yafang @zhangqiang183 @wind_zj @zxg-gitee
@@ -556,17 +562,18 @@ zh-cn/application-dev/reference/apis-ability-kit/errorcode-DistributedSchedule.m
[API参考-Ability Kit-包管理]
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-bundle*.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-appControl.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-defaultAppManager.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-distributedBundleManager.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-freeInstall.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-installer.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-launcherBundleManager.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-overlay.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/js-apis-zlib.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/errorcode-bundle.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/reference/apis-ability-kit/errorcode-zlib.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-bundle*.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-installer-sys.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-appControl.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-defaultAppManager.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-distributedBundleManager.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-freeInstall.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-installer.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-launcherBundleManager.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-overlay.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/js-apis-zlib.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/errorcode-bundle.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/reference/apis-ability-kit/errorcode-zlib.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
[API参考-Ability Kit-分布式]
zh-cn/application-dev/reference/apis-ability-kit/js-apis-distributedMissionManager.md @chenmingJay @Brilliantry_Rui @nan-xiansen @iceice1001
@@ -638,13 +645,13 @@ zh-cn/application-dev/reference/apis-arkts/js-apis-taskpool.md @gongjunsong @ge-
zh-cn/application-dev/reference/apis-arkui/js-service-widget-ui/ @HelloCrease
[API参考-ArkUI-TS组件]
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-click.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-touch.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-click.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-touch.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-show-hide.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-drag-drop.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-key.md @jiangtao92 @benb365 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-focus-event.md @jiangtao92 @benb365 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-mouse-key.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-mouse-key.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-component-area-change-event.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-component-visible-area-change-event.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-keyboardshortcut.md @jiangtao92 @benb365 @fredyuan0912 @HelloCrease
@@ -653,66 +660,66 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-size
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-location.md @laigerendaqiu @crazyracing0726 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-layout-constraints.md @laigerendaqiu @crazyracing0726 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-flex-layout.md @laigerendaqiu @crazyracing0726 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-border.md @laigerendaqiu @crazyracing0726 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-border-image.md @crazyracing0726 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-background.md @jiangtao92 @sunfei2021 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-opacity.md @lightningHo @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-border.md @laigerendaqiu @crazyracing0726 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-border-image.md @crazyracing0726 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-background.md @jiangtao92 @sunfei2021 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-opacity.md @hehongyang9 @lightningHo @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-visibility.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-enable.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-enable.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-overlay.md @jiangtao92 @benb365 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-z-order.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-transformation.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-image-effect.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md @lightningHo @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-transformation.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-image-effect.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md @hehongyang9 @lightningHo @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-grid.md @laigerendaqiu @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-gradient-color.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-popup.md @zhanghaibo0 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-menu.md @luyuxuan1 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-gradient-color.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-popup.md @zhanghaibo0 @li-xinlei007 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-menu.md @li-xinlei007 @HelloCrease @zhanghaibo0
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-focus.md @benb365 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-hover-effect.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-hover-effect.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-component-id.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-polymorphic-style.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-restoreId.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-color.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-blur-style.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click-effect.md @lightningHo @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-color.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-blur-style.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click-effect.md @lightningHo @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md @lmleon @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-attribute-modifier.md @harmony_zhangjian @sunfei2021 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-outline.md @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-touch-target.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-hit-test-behavior.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-modal-transition.md @raulnaruto_admin @cheng-feiwang @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md @raulnaruto_admin @cheng-feiwang @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-outline.md @hehongyang9 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-touch-target.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-hit-test-behavior.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-modal-transition.md @raulnaruto_admin @cheng-feiwang @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-sheet-transition.md @raulnaruto_admin @cheng-feiwang @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-obscured.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-text-style.md @jyj-0306 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-drag-drop.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-expand-safe-area.md @laigerendaqiu @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-renderfit.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-monopolize-events.md @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-cursor.md @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-use-effect-sys.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-image-effect-sys.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-background-sys.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-blur-style-sys.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-gesture-settings.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-tapgesture.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-longpressgesture.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-pangesture.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-pinchgesture.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-rotationgesture.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-swipegesture.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-combined-gestures.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-gesture-customize-judge.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-renderfit.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-monopolize-events.md @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-cursor.md @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-use-effect-sys.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-image-effect-sys.md @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-background-sys.md @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-blur-style-sys.md @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-gesture-settings.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-tapgesture.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-longpressgesture.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-pangesture.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-pinchgesture.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-rotationgesture.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-gestures-swipegesture.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-combined-gestures.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-gesture-customize-judge.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-alphabet-indexer.md @cc520bf @yeyinglong_admin @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-blank.md @laigerendaqiu @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-button.md @youzhi92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-calendarpicker.md @jinweiliu @lexiaoyao2 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-checkbox.md @youzhi92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-checkboxgroup.md @youzhi92 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-button.md @firminly @li-xinlei007 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-calendarpicker.md @jinweiliu @lexiaoyao2 @li-xinlei007 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-checkbox.md @houguobiao @li-xinlei007 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-checkboxgroup.md @houguobiao @li-xinlei007 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-containerspan.md @jyj-0306 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-datapanel.md @lihaoyn @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-datepicker.md @jinweiliu @lexiaoyao2 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-datepicker.md @jinweiliu @lexiaoyao2 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-divider.md @laigerendaqiu @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-gauge.md @ileft201 @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-image.md @lexiaoyao2 @fredyuan0912 @HelloCrease
@@ -720,9 +727,9 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-imageani
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-imagespan.md @lexiaoyao2 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-loadingprogress.md @ileft201 @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-marquee.md @jyj-0306 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-menu.md @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-menuitem.md @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-menuitemgroup.md @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-menu.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-menuitem.md @li-xinlei007 @HelloCrease @zhanghaibo0
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-menuitemgroup.md @li-xinlei007 @HelloCrease @zhanghaibo0
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md @raulnaruto_admin @jiangdayuan @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navrouter.md @raulnaruto_admin @jiangdayuan @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-navdestination.md @raulnaruto_admin @jiangdayuan @fredyuan0912 @HelloCrease
@@ -730,14 +737,14 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-nodecont
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-patternlock.md @ileft201 @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-progress.md @ileft201 @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-qrcode.md @ileft201 @lihaoyn @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-radio.md @youzhi92 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-rating.md @youzhi92 @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-radio.md @houguobiao @li-xinlei007 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-rating.md @firminly @li-xinlei007 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-richeditor.md @vviinnoo24 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-richtext.md @bigpumpkin @HelloCrease @litao33 @zhang-xinyue15
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-richtext.md @bigpumpkin @HelloCrease @litao33 @GHiker
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-scrollbar.md @cc520bf @yeyinglong_admin @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-search.md @jyj-0306 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-select.md @youzhi92 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-slider.md @youzhi92 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-select.md @zhanghaibo0 @li-xinlei007 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-slider.md @firminly @li-xinlei007 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-span.md @jyj-0306 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-stepper.md @raulnaruto_admin @jiangdayuan @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-stepperitem.md @raulnaruto_admin @jiangdayuan @fredyuan0912 @HelloCrease
@@ -747,10 +754,10 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-text.md
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-textarea.md @jyj-0306 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-textclock.md @ileft201 @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md @jyj-0306 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-textpicker.md @jinweiliu @lexiaoyao2 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-textpicker.md @jinweiliu @lexiaoyao2 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-texttimer.md @ileft201 @lihaoyn @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-timepicker.md @jinweiliu @lexiaoyao2 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-toggle.md @youzhi92 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-timepicker.md @jinweiliu @lexiaoyao2 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-toggle.md @houguobiao @li-xinlei007 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-xcomponent.md @ZhangYu-Home @keerecles @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-component3d-sys.md @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-image-sys.md @crazyracing0726 @fredyuan0912 @HelloCrease
@@ -765,9 +772,9 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-counter.md @ile
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-flex.md @laigerendaqiu @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-flowitem.md @cc520bf @zcdqs @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-folderstack.md @laigerendaqiu @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-formcomponent-sys.md @arondave @hehe9876 @Brilliantry_Rui @ylsnow
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-formlink.md @arondave @hehe9876 @Brilliantry_Rui @ylsnow
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-formmenu.md @Brilliantry_Rui @ylsnow
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-formcomponent-sys.md @Brilliantry_Rui @ylsnow @cmz001 @Eiln
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-formlink.md @Brilliantry_Rui @ylsnow @cmz001 @Eiln
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-formmenu.md @Brilliantry_Rui @ylsnow @cmz001 @Eiln
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-gridcol.md @laigerendaqiu @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-gridrow.md @laigerendaqiu @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-grid.md @cc520bf @zcdqs @lihaoyn @HelloCrease
@@ -777,7 +784,7 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-list.md @cc520b
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-listitem.md @cc520bf @yeyinglong_admin @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-listitemgroup.md @cc520bf @yeyinglong_admin @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-navigator.md @raulnaruto_admin @jiangdayuan @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-panel.md @raulnaruto_admin @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-panel.md @raulnaruto_admin @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-refresh.md @cc520bf @yeyinglong_admin @lihaoyn @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-relativecontainer.md @laigerendaqiu @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-row.md @laigerendaqiu @fredyuan0912 @HelloCrease
@@ -823,7 +830,7 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-Exceptio
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-Filter.md @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-GridObjectSortComponent.md @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-ProgressButton.md @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-Popup.md @youzhi92 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-Popup.md @firminly @li-xinlei007 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-SegmentButton.md @youzhi92 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-SelectionMenu.md @jyj-0306 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-SelectTitleBar.md @HelloCrease
@@ -835,25 +842,25 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-ToolBar.
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-TreeView.md @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-FullScreenLaunchComponent.md @dutie123 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-animatorproperty.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-explicit-animation.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-keyframeAnimateTo.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-page-transition-animation.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-transition-animation-component.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-transition-animation-shared-elements.md @lightningHo @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-transition-animation-geometrytransition.md @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-motion-path-animation.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-particle-animation.md @lightningHo @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-explicit-animatetoimmediately-sys.md @lightningHo @luyuxuan1 @HelloCrease
-
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-alert-dialog-box.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-action-sheet.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-custom-dialog-box.md @luyuxuan1 @HelloCrease @zhanghaibo0
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-calendarpicker-dialog.md @jinweiliu @lexiaoyao2 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-datepicker-dialog.md @jinweiliu @lexiaoyao2 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-timepicker-dialog.md @jinweiliu @lexiaoyao2 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-textpicker-dialog.md @jinweiliu @lexiaoyao2 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-menu.md @youzhi92 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-animatorproperty.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-explicit-animation.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-keyframeAnimateTo.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-page-transition-animation.md @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-transition-animation-component.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-transition-animation-shared-elements.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-transition-animation-geometrytransition.md @hehongyang9 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-motion-path-animation.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-particle-animation.md @hehongyang9 @lightningHo @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-explicit-animatetoimmediately-sys.md @hehongyang9 @lightningHo @HelloCrease
+
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-alert-dialog-box.md @li-xinlei007 @HelloCrease @houguobiao
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-action-sheet.md @li-xinlei007 @HelloCrease @houguobiao
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-custom-dialog-box.md @li-xinlei007 @HelloCrease @houguobiao
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-calendarpicker-dialog.md @jinweiliu @lexiaoyao2 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-datepicker-dialog.md @jinweiliu @lexiaoyao2 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-timepicker-dialog.md @jinweiliu @lexiaoyao2 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-textpicker-dialog.md @jinweiliu @lexiaoyao2 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-methods-menu.md @zhanghaibo0 @li-xinlei007 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md @seaside_wu @s10021109 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-custom-component-api.md @s10021109 @HelloCrease
@@ -863,10 +870,10 @@ zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-appendix-enums.md @jiangt
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-types.md @jiangtao92 @sunfei2021 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-ability-component-sys.md @seaside_wu @keerecles @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-gridcontainer.md @crazyracing0726 @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click.md @jiangtao92 @zhaojian2021 @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click.md @jiangtao92 @piggyguy @fredyuan0912 @HelloCrease
[API参考-ArkUI-ArkTS]
-zh-cn/application-dev/reference/apis-arkui/js-apis-animator.md @lightningHo @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/js-apis-animator.md @hehongyang9 @lightningHo @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-componentSnapshot.md @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-componentUtils.md @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-dragController.md @piggyguy @fredyuan0912 @HelloCrease
@@ -874,22 +881,22 @@ zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-drawableDescriptor.md
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-inspector.md @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-node.md @lightningHo @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-observer.md @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-UIContext.md @sunfei2021 @luyuxuan1 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/js-apis-curve.md @lightningHo @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-UIContext.md @sunfei2021 @fredyuan0912 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/js-apis-curve.md @hehongyang9 @lightningHo @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-font.md @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/js-apis-matrix4.md @lightningHo @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/js-apis-matrix4.md @hehongyang9 @lightningHo @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-measure.md @jyj-0306 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-mediaquery.md @laigerendaqiu @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-plugincomponent.md @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/js-apis-promptAction.md @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/js-apis-promptAction.md @li-xinlei007 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-router.md @raulnaruto_admin @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/js-apis-getContext.md @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/js-apis-getContext.md @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-postCardAction.md @arondave @hehe9876 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-drawableDescriptor-sys.md @crazyracing0726 @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-performancemonitor-sys.md @lushi1202 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-devicestatus-draginteraction-sys.md @piggyguy @fredyuan0912 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-plugincomponent-sys.md @keerecles @fredyuan0912 @HelloCrease
-zh-cn/application-dev/reference/apis-arkui/js-apis-uiappearance-sys.md @lushi1202 @luyuxuan1 @HelloCrease
+zh-cn/application-dev/reference/apis-arkui/js-apis-uiappearance-sys.md @lushi1202 @HelloCrease
zh-cn/application-dev/reference/apis-arkui/js-apis-uiExtensionHost-sys.md @ge-yafang @zhouyaoying @nobuggers
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-uiExtension.md @ge-yafang @zhouyaoying @nobuggers
zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-uiExtension-sys.md @ge-yafang @zhouyaoying @nobuggers
@@ -919,26 +926,27 @@ zh-cn/application-dev/reference/apis-arkui/errorcode-display.md @ge-yafang @acha
[API参考-ArkWeb]
-zh-cn/application-dev/reference/apis-arkweb/js-apis-webview.md @bigpumpkin @HelloCrease @litao33 @zhang-xinyue15
-zh-cn/application-dev/reference/apis-arkweb/ts-basic-components-web.md @bigpumpkin @HelloCrease @litao33 @zhang-xinyue15
-zh-cn/application-dev/reference/apis-arkweb/native_interface_arkweb.md @bigpumpkin @HelloCrease @litao33 @zhang-xinyue15
-zh-cn/application-dev/reference/apis-arkweb/errorcode-webview.md @bigpumpkin @HelloCrease @litao33 @zhang-xinyue15
+zh-cn/application-dev/reference/apis-arkweb/js-apis-webview.md @bigpumpkin @HelloCrease @litao33 @GHiker
+zh-cn/application-dev/reference/apis-arkweb/ts-basic-components-web.md @bigpumpkin @HelloCrease @litao33 @GHiker
+zh-cn/application-dev/reference/apis-arkweb/native_interface_arkweb.md @bigpumpkin @HelloCrease @litao33 @GHiker
+zh-cn/application-dev/reference/apis-arkweb/errorcode-webview.md @bigpumpkin @HelloCrease @litao33 @GHiker
[API参考-Background Tasks Kit]
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-reminderAgentManager.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-reminderAgentManager-sys.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-backgroundTaskManager.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-backgroundTaskManager-sys.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-workScheduler.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-WorkSchedulerExtensionAbility.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-inner-application-WorkSchedulerExtensionContext.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-deviceStandby-sys.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-deviceUsageStatistics-sys.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/errorcode-backgroundTaskMgr.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/errorcode-reminderAgentManager.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/errorcode-workScheduler.md @Brilliantry_Rui
-zh-cn/application-dev/reference/apis-backgroundtasks-kit/errorcode-DeviceUsageStatistics.md @Brilliantry_Rui
+zh-cn/application-dev/reference/apis-backgroundtasks-kit @Brilliantry_Rui @zhouben25 @cooffee10 @cheng-shichang
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-reminderAgentManager.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-reminderAgentManager-sys.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-backgroundTaskManager.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-backgroundTaskManager-sys.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-workScheduler.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-WorkSchedulerExtensionAbility.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-inner-application-WorkSchedulerExtensionContext.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-deviceStandby-sys.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/js-apis-resourceschedule-deviceUsageStatistics-sys.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/errorcode-backgroundTaskMgr.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/errorcode-reminderAgentManager.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/errorcode-workScheduler.md @Brilliantry_Rui @zhouben25 @cooffee10
+zh-cn/application-dev/reference/apis-backgroundtasks-kit/errorcode-DeviceUsageStatistics.md @Brilliantry_Rui @zhouben25 @cooffee10
[API参考-Basic Services Kit-配置策略]
zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-configPolicy-sys.md @Brilliantry_Rui @yangqing3 @liubingbing
@@ -1087,7 +1095,7 @@ zh-cn/application-dev/reference/apis-driverdevelopment-kit/ @li-yan339
[API参考-Form Kit]
-zh-cn/application-dev/reference/apis-form-kit/ @Eiln @cmz001 @Brilliantry_Rui @yuanzhishuai @ylsnow
+zh-cn/application-dev/reference/apis-form-kit/ @ylsnow @cmz001 @Brilliantry_Rui @Eiln
@@ -1096,13 +1104,14 @@ zh-cn/application-dev/reference/apis-ime-kit/ @illybyy @murphy1984 @feng-aiwen
[API参考-Input Kit]
-zh-cn/application-dev/reference/apis-input-kit/ @hhh2 @Brilliantry_Rui @mayunteng @star-wind-snow-and-rain
+zh-cn/application-dev/reference/apis-input-kit/ @Brilliantry_Rui @mayunteng @ustblx @hanruofei
[API参考-IPC Kit]
-zh-cn/application-dev/reference/apis-ipc-kit/js-apis-rpc.md @luodh0157 @zhang_yixin13 @zhaopeng_gitee @zhang-yang123321
+zh-cn/application-dev/reference/apis-ipc-kit/js-apis-rpc.md @xdx1921 @zhang_yixin13 @zhaopeng_gitee @zhang-yang123321
[API参考-Localization Kit]
+zh-cn/application-dev/reference/apis-Localization-kit @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu @lpw_work @lliule21
zh-cn/application-dev/reference/apis-Localization-kit/js-apis-i18n.md @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu
zh-cn/application-dev/reference/apis-Localization-kit/js-apis-intl.md @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu
zh-cn/application-dev/reference/apis-Localization-kit/js-apis-i18n-sys.md @Brilliantry_Rui @yliupy @yangqing3 @sunyaozu
@@ -1186,7 +1195,7 @@ zh-cn/application-dev/reference/apis-multimodalawareness-kit/js-apis-stationary.
[API参考-Network Kit]
-zh-cn/application-dev/reference/apis-network-kit/ @jiayanhong-hw @zhang_yixin13 @w30013702 @rain_myf
+zh-cn/application-dev/reference/apis-network-kit/ @@lbch_hw @zhang_yixin13
[API参考-Neural NetWork Runtime Kit]
@@ -1231,22 +1240,23 @@ zh-cn/application-dev/reference/apis-sensor-service-kit/errorcode-vibrator.md @h
[API参考-Telephony Kit]
-zh-cn/application-dev/reference/apis-telephony-kit/ @jiayanhong-hw @zhang_yixin13 @w30013702 @dingxiaochen
+zh-cn/application-dev/reference/apis-telephony-kit/ @zhang_yixin13
[API参考-Test Kit]
-zh-cn/application-dev/reference/apis-tesk-kit/js-apis-testRunner.md
-zh-cn/application-dev/reference/apis-tesk-kit/js-apis-app-ability-abilityDelegatorRegistry.md
-zh-cn/application-dev/reference/apis-tesk-kit/js-apis-uitest.md @inter515 @Brilliantry_Rui @inter515
-zh-cn/application-dev/reference/apis-tesk-kit/errorcode-uitest.md @Brilliantry_Rui @inter515
+zh-cn/application-dev/reference/apis-tesk-kit/ @Brilliantry_Rui @inter515 @laonie666 @lv_yu_peng
+zh-cn/application-dev/reference/apis-tesk-kit/js-apis-testRunner.md @Brilliantry_Rui @inter515 @laonie666 @lv_yu_peng
+zh-cn/application-dev/reference/apis-tesk-kit/js-apis-app-ability-abilityDelegatorRegistry.md @Brilliantry_Rui @inter515 @laonie666 @lv_yu_peng
+zh-cn/application-dev/reference/apis-tesk-kit/js-apis-uitest.md @Brilliantry_Rui @inter515 @laonie666 @lv_yu_peng
+zh-cn/application-dev/reference/apis-tesk-kit/errorcode-uitest.md @Brilliantry_Rui @inter515 @laonie666 @lv_yu_peng
zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-deviceAttest-sys.md @Brilliantry_Rui @jiyong
[工具-元能力、包管理、通知等]
zh-cn/application-dev/tools/aa-tool.md @huipeizi @ccllee @lxfycode @lixueqing513
-zh-cn/application-dev/tools/bm-tool.md @Brilliantry_Rui @changzheng6 @hou-xiangyu1029 @kongjing2 @small_bricklayer
-zh-cn/application-dev/tools/packing-tool.md @jsjzju @huipeizi @lixueqing513
-zh-cn/application-dev/tools/unpacking-tool.md @jsjzju @huipeizi @lixueqing513
-zh-cn/application-dev/tools/app-check-tool.md @jsjzju @huipeizi @lixueqing513
+zh-cn/application-dev/tools/bm-tool.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/tools/packing-tool.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/tools/unpacking-tool.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
+zh-cn/application-dev/tools/app-check-tool.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
zh-cn/application-dev/tools/cem-tool.md @huipeizi @idanny @shine_hk
zh-cn/application-dev/tools/anm-tool.md @huipeizi @idanny @shine_hk
@@ -1254,5 +1264,5 @@ zh-cn/application-dev/tools/anm-tool.md @huipeizi @idanny @shine_hk
[FAQ]
zh-cn/application-dev/faqs/ @zengyawen
zh-cn/application-dev/faqs/faqs-ability.md @huipeizi @ccllee @lxfycode @lixueqing513
-zh-cn/application-dev/faqs/faqs-bundle-management.md @huipeizi @changzheng6 @hou-xiangyu1029 @kongjing2
+zh-cn/application-dev/faqs/faqs-bundle-management.md @Brilliantry_Rui @changzheng6 @kongjing2 @small_bricklayer
zh-cn/application-dev/faqs/faqs-event-notification.md @huipeizi @idanny @shine_hk
diff --git a/README_zh.md b/README_zh.md
index f665ee65345cf05b811b4e62cc075cae285729e8..c3d7fbcb884c958589bedf68c41207ca48e0961d 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -18,6 +18,8 @@
- master：最新开发版本。
+ - OpenHarmony 5.0.3 Release版本（API Level 15）：点击[此处](zh-cn/release-notes/OpenHarmony-v5.0.3-release.md)了解版本详情。
+
- OpenHarmony 5.0.2 Release版本（API Level 14）：点击[此处](zh-cn/release-notes/OpenHarmony-v5.0.2-release.md)了解版本详情。
- OpenHarmony 5.0.1 Release版本（API Level 13）：点击[此处](zh-cn/release-notes/OpenHarmony-v5.0.1-release.md)了解版本详情。
diff --git a/en/application-dev/ads-service/oaid-service-sys.md b/en/application-dev/ads-service/oaid-service-sys.md
new file mode 100644
index 0000000000000000000000000000000000000000..9edd6cd418f17756010c772c5fb135b9f3c1d4c6
--- /dev/null
+++ b/en/application-dev/ads-service/oaid-service-sys.md
@@ -0,0 +1,78 @@
+# Resetting OAID Information (for System Applications Only)
+
+## When to Use
+
+The OAID changes in the following scenarios:
+- A user restores the factory settings of the device.
+- A system application configures its bundle name in the **etc/advertising/oaid/oaid_service_config.json** file in the device's system directory and calls the **resetOAID()** API to reset the OAID. Note that the bundle name should be appended to the array in the file and separated with others by commas (,).
+The following describes how to configure a system application to reset the OAID.
+
+## Available APIs
+
+| API| Description|
+| -------- | -------- |
+| [resetOAID()](../../reference/apis-ads-kit/js-apis-oaid-sys.md#identifierresetoaid): void | Resets an OAID. This is a system API.|
+
+
+## How to Develop
+
+1. In the **module.json5** file of the module, configure the [ohos.permission.APP_TRACKING_CONSENT](../../security/AccessToken/permissions-for-all-user.md#ohospermissionapp_tracking_consent) permission. The sample code is as follows:
+ ```ts
+ {
+ "module": {
+ "requestPermissions": [
+ {
+ "name": "ohos.permission.APP_TRACKING_CONSENT",
+ "reason": "$string:reason",
+ "usedScene": {
+ "abilities": [
+ "EntryFormAbility"
+ ],
+ "when": "inuse"
+ }
+ }
+ ]
+ }
+ }
+ ```
+
+ Request authorization from the user in a dialog box when the application is started. For details about how to obtain the context, see [Context](../../application-models/application-context-stage.md). The sample code is as follows:
+ ```ts
+ import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
+ import { BusinessError } from '@ohos.base';
+ import hilog from '@ohos.hilog';
+ import common from '@ohos.app.ability.common';
+
+ function requestOAIDTrackingConsentPermissions(context: common.Context): void {
+ // Display a dialog box when the page is displayed to request the user to grant the ad tracking permission.
+ const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
+ try {
+ atManager.requestPermissionsFromUser(context, ["ohos.permission.APP_TRACKING_CONSENT"]).then((data) => {
+ if (data.authResults[0] == 0) {
+ hilog.info(0x0000, 'testTag', '%{public}s', 'request permission success');
+ } else {
+ hilog.error(0x0000, 'testTag', '%{public}s', 'user rejected');
+ }
+ }).catch((err: BusinessError) => {
+ hilog.error(0x0000, 'testTag', '%{public}s', `request permission failed, error: ${err.code} ${err.message}`);
+ })
+ } catch (err) {
+ hilog.error(0x0000, 'testTag', '%{public}s', `catch err->${err.code}, ${err.message}`);
+ }
+ }
+ ```
+
+2. Call **resetOAID()** (a system API) to reset the OAID. The sample code is as follows:
+ ```ts
+ import identifier from '@ohos.identifier.oaid';
+ import hilog from '@ohos.hilog';
+
+ // Reset the OAID.
+ try {
+ identifier.resetOAID();
+ } catch (err) {
+ hilog.error(0x0000, 'testTag', '%{public}s', `reset oaid catch error: ${err.code} ${err.message}`);
+ }
+ ```
+
+
\ No newline at end of file
diff --git a/en/application-dev/ai/mindspore/MindSpore-Lite-Kit-Introduction.md b/en/application-dev/ai/mindspore/MindSpore-Lite-Kit-Introduction.md
index 7eeb9e99e01342c6e633c71f0d5b8efa194a0115..1fb2e6f9a20e48a83645477659f427f48b16d39e 100644
--- a/en/application-dev/ai/mindspore/MindSpore-Lite-Kit-Introduction.md
+++ b/en/application-dev/ai/mindspore/MindSpore-Lite-Kit-Introduction.md
@@ -48,6 +48,6 @@ MindSpore Lite is built in the OpenHarmony standard system as a system component
## Relationship with Other Kits
-Neural Network Runtime (NNRt) functions as a bridge to connect the upper-layer AI inference framework and underlying acceleration chips, implementing cross-chip inference computing of AI models.
+Neural Network Runtime (NNRt) functions as a bridge to connect the upper-layer AI inference framework and underlying acceleration chips, implementing cross-chip inference computing for AI models.
MindSpore Lite natively allows you to configure NNRt for AI-dedicated chips (such as NPUs) to accelerate inference. Therefore, you can configure MindSpore Lite to use the NNRt hardware. The focus of this topic is about how to develop AI applications using MindSpore Lite. For details about how to use NNRt, see [Connecting the Neural Network Runtime to an AI Inference Framework](../nnrt/neural-network-runtime-guidelines.md).
diff --git a/en/application-dev/application-models/Readme-EN.md b/en/application-dev/application-models/Readme-EN.md
index a3e328d98df0eba2773a536490408b969c13df17..c7e6952c94f09eac4129116861ccb3ee15822f37 100644
--- a/en/application-dev/application-models/Readme-EN.md
+++ b/en/application-dev/application-models/Readme-EN.md
@@ -1,12 +1,12 @@
-# Ability Kit
+# Ability Kit
- [Introduction to Ability Kit](abilitykit-overview.md)
- [Application Models](application-models.md)
-- Stage Model Development
+- Stage Model Development
- [Stage Model Development Overview](stage-model-development-overview.md)
- - Stage Model Application Components
+ - Stage Model Application Components
- [Application- or Component-Level Configuration](application-component-configuration-stage.md)
- - UIAbility Component
+ - UIAbility Component
- [UIAbility Overview](uiability-overview.md)
- [UIAbility Lifecycle](uiability-lifecycle.md)
- [UIAbility Launch Type](uiability-launch-type.md)
@@ -25,7 +25,7 @@
- [EmbeddedUIExtensionAbility](embeddeduiextensionability.md)
- [AbilityStage Component Container](abilitystage.md)
- [Context](application-context-stage.md)
- - Want
+ - Want
- [Want Overview](want-overview.md)
- [Matching Rules of Explicit Want and Implicit Want](explicit-implicit-want-mappings.md)
- [Using Explicit Want to Start an Application Component](ability-startup-with-explicit-want.md)
@@ -33,13 +33,13 @@
- [Component Startup Rules (Stage Model)](component-startup-rules.md)
- [AppStartup](app-startup.md)
- - Inter-Device Application Component Interaction (Hopping)
+ - Inter-Device Application Component Interaction (Hopping)
- [Hopping Overview](inter-device-interaction-hop-overview.md)
- [Cross-Device Migration](hop-cross-device-migration.md)
- [Multi-device Collaboration](hop-multi-device-collaboration.md)
- [Subscribing to System Environment Variable Changes](subscribe-system-environment-variable-changes.md)
- - Inter-Application Redirection
+ - Inter-Application Redirection
- [Overview of Application Redirection](link-between-apps-overview.md)
- Starting a Specified Application
- [Overview of Starting a Specified Application](app-startup-overview.md)
@@ -64,18 +64,18 @@
- [Process Model (Stage Model)](process-model-stage.md)
- [Thread Model (Stage Model)](thread-model-stage.md)
- - Mission Management (for System Applications Only)
+ - Mission Management (for System Applications Only)
- [Mission Management Scenarios](mission-management-overview.md)
- - [Mission and Launch Type](mission-management-launch-type.md)
+ - [Mission Management and Launch Type](mission-management-launch-type.md)
- [Page Stack and Mission List](page-mission-stack.md)
- [Setting the Icon and Name of a Mission Snapshot](mission-set-icon-name-for-task-snapshot.md)
- [Application Configuration File](config-file-stage.md)
-- FA Model Development
+- FA Model Development
- [FA Model Development Overview](fa-model-development-overview.md)
- - FA Model Application Components
+ - FA Model Application Components
- [Application- or Component-Level Configuration](application-component-configuration-fa.md)
- - PageAbility Component Development
+ - PageAbility Component Development
- [PageAbility Overview](pageability-overview.md)
- [PageAbility Configuration](pageability-configuration.md)
- [PageAbility Lifecycle](pageability-lifecycle.md)
@@ -83,19 +83,21 @@
- [Creating a PageAbility](create-pageability.md)
- [Starting a Local PageAbility](start-local-pageability.md)
- [Stopping a PageAbility](stop-pageability.md)
+
- [Starting a Remote PageAbility (for System Applications Only)](start-remote-pageability.md)
+
- [Starting a Specified Page](start-page.md)
- [Window Properties](window-properties.md)
- [Requesting Permissions](request-permissions.md)
- [Redirection Rules](redirection-rules.md)
- - ServiceAbility Component Development
+ - ServiceAbility Component Development
- [ServiceAbility Overview](serviceability-overview.md)
- [ServiceAbility Configuration](serviceability-configuration.md)
- [ServiceAbility Lifecycle](serviceability-lifecycle.md)
- [Creating a ServiceAbility](create-serviceability.md)
- [Starting a ServiceAbility](start-serviceability.md)
- [Connecting to a ServiceAbility](connect-serviceability.md)
- - DataAbility Component Development
+ - DataAbility Component Development
- [DataAbility Overview](dataability-overview.md)
- [DataAbility Configuration](dataability-configuration.md)
- [DataAbility Lifecycle](dataability-lifecycle.md)
@@ -113,25 +115,25 @@
- [Application Configuration File](config-file-fa.md)
-- Development of Component Interaction Between the FA Model and Stage Model
+- Development of Component Interaction Between the FA Model and Stage Model
- [Component Interaction Between the FA Model and Stage Model](fa-stage-interaction-overview.md)
- [Starting a UIAbility from the FA Model](start-uiability-from-fa.md)
- [Connecting to a ServiceExtensionAbility from the FA Model](bind-serviceextensionability-from-fa.md)
- [Accessing a DataShareExtensionAbility from the FA Model](access-datashareextensionability-from-fa.md)
- [Starting a PageAbility from the Stage Model](start-pageability-from-stage.md)
- [Connecting to a ServiceAbility from the Stage Model](bind-serviceability-from-stage.md)
-- Switching from the FA Model to the Stage Model
+- Switching from the FA Model to the Stage Model
- [Model Switching Overview](model-switch-overview.md)
- - Configuration File Switching
+ - Configuration File Switching
- [Differences in Configuration Files](configuration-file-diff.md)
- [Switching of app and deviceConfig](app-deviceconfig-switch.md)
- [Switching of module](module-switch.md)
- - Component Switching
+ - Component Switching
- [PageAbility Switching](pageability-switch.md)
- [ServiceAbility Switching](serviceability-switch.md)
- [DataAbility Switching](dataability-switch.md)
- [Widget Switching](widget-switch.md)
- - API Switching
+ - API Switching
- [API Switching Overview](api-switch-overview.md)
- [Context Switching](context-switch.md)
- [featureAbility Switching](featureability-switch.md)
diff --git a/en/application-dev/application-models/access-datashareextensionability-from-fa.md b/en/application-dev/application-models/access-datashareextensionability-from-fa.md
index 1c968aed1561bcf4bf9f746ce73f5b342a7e4326..47e5b62209a6c2ec8bd8cabe2326b51b89c00c25 100644
--- a/en/application-dev/application-models/access-datashareextensionability-from-fa.md
+++ b/en/application-dev/application-models/access-datashareextensionability-from-fa.md
@@ -5,9 +5,9 @@
Regardless of the FA model or stage model, the data read/write function consists of the client and server.
-- In the FA model, the client uses the **DataAbilityHelper** class to provide external APIs, and the server uses the **DataAbility** class to provide database read and write services.
+- In the FA model, the client uses [DataAbilityHelper](../reference/apis-ability-kit/js-apis-inner-ability-dataAbilityHelper.md) to provide external APIs, and the server uses [DataAbility](dataability-overview.md) to provide database read and write services.
-- In the stage model, the client uses the **DataShareHelper** class to provide external APIs, and the server uses the **DataShareExtensionAbility** class to provide database read and write services.
+- In the stage model, the client uses [DataShareHelper](../reference/apis-arkdata/js-apis-data-dataShare-sys.md#datasharehelper) to provide external APIs, and the server uses [DataShareExtensionAbility](../reference/apis-arkdata/js-apis-application-dataShareExtensionAbility-sys.md) to provide database read and write services
If the client uses the FA model whereas the server is upgraded to the stage model, the client cannot access the server.
@@ -31,7 +31,7 @@ Instead of manual modification, the system adopts the following processing:
-3. The **DataShareHelper** class implements only certain APIs of **DataAbilityHelper**. For details about the APIs, see the table below.
+2. The **DataShareHelper** class implements only certain APIs of **DataAbilityHelper**. For details about the APIs, see the table below.
**Table 1** API compatibility when the FA model accesses a DataShareExtensionAbility of the stage model
diff --git a/en/application-dev/application-models/actions-entities.md b/en/application-dev/application-models/actions-entities.md
index a17749fbc3d9ae43572daa8b7d672e77f20d5536..dbfb2ab7f889cf8bd4fc3e5c232f70a21726fb42 100644
--- a/en/application-dev/application-models/actions-entities.md
+++ b/en/application-dev/application-models/actions-entities.md
@@ -4,9 +4,9 @@
>
> Due to the generalized use of the fields **action** and **entities**, the system lacks control over the behavior of applications declaring **action** and **entities**. This loophole allows malicious applications to make false declarations, hijacking traffic and rendering post-redirection features inoperative. As such, the system intends to deprecate unnecessary **action** and **entities**. You are advised to [start an application of the specified type](./start-intent-panel.md).
-The **action** field specifies the common operation (such as viewing, sharing, and application details) to be performed by the caller. In implicit [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md), you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data, for example, viewing URI data. For example, if the URI is a website and the action is **ACTION_VIEW_DATA**, the application component that supports access to the website is matched. Declaring the **action** field in Want indicates that the invoked application should support the declared operation. The **actions** field under **skills** in the configuration file indicates the operations supported by the application.
+The **action** field specifies the common operation (such as viewing, sharing, and application details) to be performed by the caller. In implicit [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md), you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data, for example, viewing URI data. For example, if the URI is a website and the action is **ACTION_VIEW_DATA**, the application component that supports access to the website is matched. Declaring the **action** field in Want indicates that the invoked application should support the declared operation. The **actions** field under [skills](../quick-start/module-configuration-file.md#skills) in the configuration file indicates the operations supported by the application. Common **actions** values are as follows. For details, see [action](../reference/apis-ability-kit/js-apis-ability-wantConstant.md#action).
-The following **action** values are available:
+**Common action values**
- **ACTION_HOME**: action of starting the application entry component. It must be used together with **ENTITY_HOME**. The application icon on the home screen is an explicit entry component. Users can touch the icon to start the entry component. Multiple entry components can be configured for an application.
@@ -17,9 +17,9 @@ The following **action** values are available:
- **ACTION_VIEW_MULTIPLE_DATA**: action of launching the UI for sending multiple data records.
-The **entities** field specifies the additional category information (such as browser and video player) of the target component. It is a supplement to action in implicit [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md). You can define this field to filter application categories, for example, browser. Declaring the **entities** field in Want indicates that the invoked application should belong to the declared category. The **entities** field under **skills** in the configuration file indicates the categories supported by the application.
+The **entities** field specifies the additional category information (such as browser and video player) of the target component. It is a supplement to action in implicit [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md). You can define this field to filter application categories, for example, browser. Declaring the **entities** field in Want indicates that the invoked application should belong to the declared category. The **entities** field under [skills](../quick-start/module-configuration-file.md#skills) in the configuration file indicates the categories supported by the application. Common **entities** values are as follows. For details, see [entity](../reference/apis-ability-kit/js-apis-ability-wantConstant.md#entity).
-The following **entities** values are available:
+**Common entities values**
- **ENTITY_DEFAULT**: default category, which is meaningless.
diff --git a/en/application-dev/application-models/app-linking-startup.md b/en/application-dev/application-models/app-linking-startup.md
index 1717e2391f709bd3c946ec0727e7faf8ac505383..1e3b4d83667dabec99f184dbc97038d12ac5808a 100644
--- a/en/application-dev/application-models/app-linking-startup.md
+++ b/en/application-dev/application-models/app-linking-startup.md
@@ -36,6 +36,11 @@ Configure the [module.json5 file](../quick-start/module-configuration-file.md) o
* The **uris** field must contain an element whose **scheme** is **https** and **host** is a domain name address.
* **domainVerify** must be set to **true**.
+> **NOTE**
+>
+> By default, the **skills** field contains a **skill** object, which is used to identify the application entry. Application redirection links should not be configured in this object. Instead, separate **skill** objects should be used. If there are multiple redirection scenarios, create different **skill** objects under **skills**. Otherwise, the configuration does not take effect.
+
+
For example, the configuration below declares that the application is associated with the domain name www.example.com.
```json
@@ -46,6 +51,14 @@ For example, the configuration below declares that the application is associated
{
// ...
"skills": [
+ {
+ "entities": [
+ "entity.system.home"
+ ],
+ "actions": [
+ "action.system.home"
+ ]
+ },
{
"entities": [
// entities must contain "entity.system.browsable".
@@ -67,7 +80,7 @@ For example, the configuration below declares that the application is associated
],
// domainVerify must be set to true.
"domainVerify": true
- }
+ } // Add a skill object for redirection. If there are multiple redirection scenarios, create multiple skill objects.
]
}
]
diff --git a/en/application-dev/application-models/app-startup.md b/en/application-dev/application-models/app-startup.md
index ac5de1341af1e25a15016f935ed4db70c272cff5..4b5977e5e019e9366e50aefccc2fe2ca863f3326 100644
--- a/en/application-dev/application-models/app-startup.md
+++ b/en/application-dev/application-models/app-startup.md
@@ -3,25 +3,38 @@
## Overview
-During application initialization, a series of startup tasks are triggered. If these tasks are concentratedly placed within the [onCreate](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) lifecycle of the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) of the application's main module ([module](../quick-start/application-package-overview.md#module-types) of the entry type), they must be executed sequentially on the main thread, which significantly affects the application launch speed. In addition, when there are too many tasks, complex dependencies between them make the code difficult to maintain.
+During application launch, a series of startup tasks are often required. If all these tasks are placed within the [onCreate](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) lifecycle of the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) in the application's main module ([module](../quick-start/application-package-overview.md#module-types) of the entry type), they can only be executed sequentially on the main thread, which significantly affects the application launch speed. In addition, when there are too many tasks, complex dependencies between them make the code difficult to maintain.
-AppStartup offers an efficient approach to application initialization. By enabling the asynchronous initiation of startup tasks, it ensures a smoother startup process. The centralized configuration of task execution order and interdependencies in a single file simplifies and clarifies the startup codebase, enhancing maintainability.
+AppStartup offers an efficient approach to application launch. By supporting asynchronous initiation of startup tasks, it ensures a smoother startup process. The centralized configuration of execution order and dependencies of multiple startup tasks in a single file simplifies and clarifies the startup codebase, enhancing maintainability.
-AppStartup supports startup tasks in automatic or manual mode. By default, the automatic mode is used. During the creation of an [AbilityStage](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md), the configured startup tasks are loaded and executed in automatic mode. You can also call [startupManager.run](../reference/apis-ability-kit/js-apis-app-appstartup-startupManager.md#startupmanagerrun) to execute the startup tasks in manual mode after a UIAbility is created.
+## Working Mechanism
+
+AppStartup supports startup tasks in automatic or manual mode. By default, automatic mode is used. During the creation of an [AbilityStage](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md), the configured startup tasks are loaded and executed in automatic mode. You can also call [startupManager.run](../reference/apis-ability-kit/js-apis-app-appstartup-startupManager.md#startupmanagerrun) to execute the startup tasks in manual mode after an AbilityStage is created.
**Figure 1** Startup procedure
+
+## Supported Scope
+
+- AppStartup is only triggered when the entry UIAbility is launched. It is not triggered when ExtensionAbility or non-entry UIAbility are launched.
+
+- Starting from API version 16, AppStartup supports configuring startup tasks in [HSP](../quick-start/har-package.md) and [HAR](../quick-start/in-app-hsp.md) modules. However, startup tasks and .so file preloading tasks in the HSP and HAR modules cannot be explicitly set to automatic mode. They can be initiated by startup tasks and .so file preloading tasks of the entry module that are in automatic mode.
+
+- Starting from API version 16, AppStartup supports the configuration of .so file preloading tasks. For details about how to develop .so files, refer to [Node-API](../napi/use-napi-process.md) to create a native C++ project.
+
+
## Constraints
-- AppStartup can be used only in the UIAbility of an entry [module](../quick-start/application-package-overview.md#module-types).
+- AppStartup must be enabled in the [module.json5 file](../quick-start/module-configuration-file.md) of the entry-type [module](../quick-start/application-package-overview.md#module-types) before being used.
+
+- Circular dependencies between startup tasks or .so file preloading tasks are not allowed.
-- Circular dependencies are not allowed between startup tasks.
## Development Process
-1. [Defining an AppStartup Configuration File](#defining-an-appstartup-configuration-file): Create an AppStartup configuration file in the resource file directory, add the configuration about startup tasks, and reference the configuration file in [module.json5](../quick-start/module-configuration-file.md).
+1. [Defining an AppStartup Configuration File](#defining-an-appstartup-configuration-file): Create an AppStartup configuration file in the resource file directory, add the configuration about startup tasks, and reference this configuration file in [module.json5](../quick-start/module-configuration-file.md).
2. [Setting Startup Parameters](#setting-startup-parameters): In the startup parameter file, set parameters such as the timeout interval and startup task listener.
3. [Adding a Startup Task for Each Component to Be Initialized](#adding-a-startup-task-for-each-component-to-be-initialized): Implement the [StartupTask](../reference/apis-ability-kit/js-apis-app-appstartup-startupTask.md) interface.
@@ -29,24 +42,25 @@ AppStartup supports startup tasks in automatic or manual mode. By default, the a
### Defining an AppStartup Configuration File
-1. Create a AppStartup configuration file in the **resources/base/profile** directory of the application's main module ([module](../quick-start/application-package-overview.md#module-types) of the entry type). The file name can be customized. The following uses **startup_config.json** as an example.
+1. Create an AppStartup configuration file in the **resources/base/profile** directory of the application's main module ([module](../quick-start/application-package-overview.md#module-types) of the entry type). The file name can be customized. The following uses **startup_config.json** as an example.
-2. In the **startup_config.json** file, add the configuration for each startup task in sequence.
+2. In the **startup_config.json** file, add the configuration for each startup task and .so file preloading task in sequence.
- It is assumed that the application has six startup tasks. The dependencies between the tasks are shown in the figure below. To facilitate concurrent execution of startup tasks, a startup task file should contain only one startup task. In this example, each startup task corresponds to a startup task file.
+ It is assumed that the application has six startup tasks and six .so file preloading tasks. The dependencies between the tasks are shown in the figure below. To facilitate concurrent execution of startup tasks, a startup task file should contain only one startup task. In this example, each startup task corresponds to a startup task file. You are not advised to run code logic in the loading callback of .so files, as prolonged .so file loading can adversely affect the main thread's operation.
- **Figure 2** Dependencies between startup tasks
+ **Figure 2** Dependencies between the startup tasks and .so file preloading tasks
1. In the **ets/startup** directory, create six startup task files and a common startup parameter file. The file names must be unique.
1. Create six startup task files. In this example, the six files are named from **StartupTask_001.ets** to **StartupTask_006.ets**.
- 2. Create a startup parameter file. In this example, the file name is **StartupConfig.ets**.
+ 2. Create.so files by referring to [Node-API](../napi/use-napi-process.md). In this example, the six files are named from **libentry_001.so** to **libentry_006.so**.
+ 3. Create a startup parameter file. In this example, the file name is **StartupConfig.ets**.
2. Add the information about the startup task files and startup parameter file to the **startup_config.json** file.
- The following is an example of the **startup_config.json** file:
+ The following is an example of the **startup_config.json** file of the application's main module:
```json
{
@@ -65,6 +79,7 @@ AppStartup supports startup tasks in automatic or manual mode. By default, the a
"name": "StartupTask_002",
"srcEntry": "./ets/startup/StartupTask_002.ets",
"dependencies": [
+ "StartupTask_003",
"StartupTask_004"
],
"runOnThread": "taskPool",
@@ -103,28 +118,88 @@ AppStartup supports startup tasks in automatic or manual mode. By default, the a
"excludeFromAutoStart": true
}
],
+ "appPreloadHintStartupTasks": [
+ {
+ "name": "libentry_001",
+ "srcEntry": "libentry_001.so",
+ "dependencies": [
+ "libentry_002",
+ "libentry_003"
+ ],
+ "runOnThread": "taskPool"
+ },
+ {
+ "name": "libentry_002",
+ "srcEntry": "libentry_002.so",
+ "dependencies": [
+ "libentry_003",
+ "libentry_004"
+ ],
+ "runOnThread": "taskPool"
+ },
+ {
+ "name": "libentry_003",
+ "srcEntry": "libentry_003.so",
+ "dependencies": [
+ "libentry_004"
+ ],
+ "runOnThread": "taskPool"
+ },
+ {
+ "name": "libentry_004",
+ "srcEntry": "libentry_004.so",
+ "runOnThread": "taskPool"
+ },
+ {
+ "name": "libentry_005",
+ "srcEntry": "libentry_005.so",
+ "dependencies": [
+ "libentry_006"
+ ],
+ "runOnThread": "taskPool",
+ "excludeFromAutoStart": true
+ },
+ {
+ "name": "libentry_006",
+ "srcEntry": "libentry_006.so",
+ "runOnThread": "taskPool",
+ "excludeFromAutoStart": true
+ }
+ ],
"configEntry": "./ets/startup/StartupConfig.ets"
}
```
+
**Table 1** Fields in the startup_config.json file
- | Field| Description| Data Type| Default Value Allowed|
+ | Field| Description| Data Type| Optional|
| -------- | -------- | -------- | -------- |
- | startupTasks | Configuration about the startup tasks. For details, see the following table.| Object array| No|
- | configEntry | Path of the startup parameter file.| String| No|
+ | startupTasks | Configuration about the startup tasks. For details, see the following table.| Object array| Optional, defaults to an empty array|
+ | appPreloadHintStartupTasks | Configuration about the .so file preloading tasks. For details, see the following table.| Object array| Optional, defaults to an empty array|
+ | configEntry | Path of the startup parameter file.
**NOTE**
Do not configure this field for the HSP and HAR.| String| Mandatory|
**Table 2** Description of startupTasks
- | Field| Description| Data Type| Default Value Allowed|
+ | Field| Description| Data Type| Optional|
+ | -------- | -------- | -------- | -------- |
+ | name | Class name of the startup task.| String| Mandatory|
+ | srcEntry | Path of the file corresponding to the startup task.| String| Mandatory|
+ | dependencies | Array holding the class names of other startup tasks on which this task depends.| Object array| Optional, defaults to an empty array|
+ | excludeFromAutoStart | Whether to exclude automatic mode. For details, see [Changing the Startup Mode](#optional-changing-the-startup-mode).
- **true**: manual mode.
- **false**: automatic mode.
**NOTE**
This field must be set to **true** for the HSP and HAR.| Boolean| Optional, defaults to **false**|
+ | runOnThread | Thread where the startup task is executed.
- **mainThread**: executed in the main thread.
- **taskPool**: executed in an asynchronous thread.| String| Optional, defaults to **mainThread**|
+ | waitOnMainThread | Whether the main thread needs to wait until the startup task finishes execution. This parameter is valid only when **runOnThread** is set to **taskPool**.
- **true**: The main thread loads the application home page only the startup task finishes execution.
- **false**: The main thread does not wait for the startup task to finish execution.| Boolean| Optional, defaults to **true**|
+
+ **Table 3** appPreloadHintStartupTasks
+
+ | Field| Description| Data Type| Optional|
| -------- | -------- | -------- | -------- |
- | name | Class name of the startup task.| String| No|
- | srcEntry | Path of the file corresponding to the startup task.| String| No|
- | dependencies | Array holding the class names of other startup tasks on which the startup task depends.| Object array| Yes (initial value: left empty)|
- | excludeFromAutoStart | Whether to exclude the automatic mode. For details, see [Changing the Startup Mode](#optional-changing-the-startup-mode).
- **true**: manual mode.
- **false**: automatic mode.| Boolean| Yes (initial value: **false**)|
- | runOnThread | Thread where the startup task is executed.
- **mainThread**: executed in the main thread.
- **taskPool**: executed in an asynchronous thread.| String| Yes (initial value: **mainThread**)|
- | waitOnMainThread | Whether the main thread needs to wait until the startup task finishes execution. This parameter is valid only when **runOnThread** is set to **taskPool**.
- **true**: The main thread loads the application home page only the startup task finishes execution.
- **false**: The main thread does not wait for the startup task to finish execution.| Boolean| Yes (initial value: **true**)|
+ | name | Name of the .so file to preload.| String| Mandatory|
+ | srcEntry | File name of the .so file, including the extension.| String| Mandatory|
+ | dependencies | Array holding the .so file names of other preloading tasks on which this task depends.| Object array| Optional, defaults to an empty array|
+ | excludeFromAutoStart | Whether to exclude automatic mode. For details, see [Changing the Startup Mode](#optional-changing-the-startup-mode).
- **true**: manual mode.
- **false**: automatic mode.
**NOTE**
This field must be set to **true** for the HSP and HAR.| Boolean| Optional, defaults to **false**|
+ | runOnThread | Thread where preloading is performed.
- **taskPool**: executed in an asynchronous thread.
**NOTE**
Preloading of .so files can be executed only in TaskPool threads.| String| Mandatory|
3. Add the index of the AppStartup configuration file to the **appStartup** tag in the [module.json5 file](../quick-start/module-configuration-file.md).
@@ -214,12 +289,109 @@ export default class StartupTask_001 extends StartupTask {
}
```
+ ### (Optional) Using AppStartup in the HSP and HAR
+
+ Large applications often consist of multiple [HSP](../quick-start/har-package.md) and [HAR](../quick-start/in-app-hsp.md) modules. This section provides an example to demonstrate how to use AppStartup in HSP and HAR packages. This example application includes two HSP packages (hsp1, hsp2) and one HAR package (har1), with startup tasks and .so file preloading tasks.
+
+ Perform the following steps:
+
+ 1. Create an AppStartup configuration file under the **resources/base/profile** directory for each HSP and HAR, in addition to the main module. Different modules can use the same file name. The following uses **startup_config.json** as an example.
+
+ 2. Configure the **startup_config.json** file for each module.
+
+ The table below lists the startup tasks and .so file preloading tasks available for the application.
+
+ **Table 4** Startup tasks and .so file preloading tasks
+ | Module| Startup Task| Preloading Task|
+ | ------- | -------------------------------- | -------------------------------- |
+ | entry | HAP_Task_01 | libentry_01 |
+ | hsp1 | HSP1_Task_01
HSP1_Task_02 | libhsp1_01
libhsp1_02 |
+ | hsp2 | HSP2_Task_01 | libhsp2_01 |
+ | har | HAR1_Task_01 | libhar1_01 |
+
+ **Figure 3** Dependencies between the startup tasks and .so file preloading tasks
+
+ 
+
+ For details about the **startup_config.json** file of the entry module, see [Defining an AppStartup Configuration File](#defining-an-appstartup-configuration-file). For the HSP and HAR, do not configure the **configEntry** field in the **startup_config.json** file. The following uses the configuration file of **hsp1** as an example:
+
+ ```json
+ {
+ "startupTasks": [
+ {
+ "name": "HSP1_Task_01",
+ "srcEntry": "./ets/startup/HSP1_Task_01.ets",
+ "dependencies": [
+ "HSP1_Task_02",
+ "HAR1_Task_01"
+ ],
+ "runOnThread": "taskPool",
+ "waitOnMainThread": false,
+ "excludeFromAutoStart": true
+ }
+ ],
+ "appPreloadHintStartupTasks": [
+ {
+ "name": "libhsp1_01",
+ "srcEntry": "libhsp1_01.so",
+ "dependencies": [
+ "libhsp1_02",
+ "libhar1_01"
+ ],
+ "runOnThread": "taskPool",
+ "excludeFromAutoStart": true
+ }
+ ]
+ }
+ ```
+
+ 3. Add the index of the AppStartup configuration file to the **appStartup** tag in the [module.json5 file](../quick-start/module-configuration-file.md) of each module.
+
+ The following are examples of **module.json5** for **hsp1**, **hsp2**, and **har1**:
+
+ ```json
+ {
+ "module": {
+ "name": "hsp1",
+ "type": "shared",
+ // ...
+ "appStartup": "$profile:startup_config," // AppStartup configuration file
+ // ...
+ }
+ }
+ ```
+ ```json
+ {
+ "module": {
+ "name": "hsp2",
+ "type": "shared",
+ // ...
+ "appStartup": "$profile:startup_config," // AppStartup configuration file
+ // ...
+ }
+ }
+ ```
+ ```json
+ {
+ "module": {
+ "name": "har1",
+ "type": "har",
+ // ...
+ "appStartup": "$profile:startup_config," // AppStartup configuration file
+ // ...
+ }
+ }
+ ```
+
+ For details about other steps, see [Setting Startup Parameters](#setting-startup-parameters) and [Adding a Startup Task for Each Component to Be Initialized](#adding-a-startup-task-for-each-component-to-be-initialized).
+
+
### (Optional) Changing the Startup Mode
-AppStartup provides automatic and manual mode. By default, the automatic mode is used. However, you can change the mode to manual as required.
+AppStartup provides two modes for executing startup tasks: automatic and manual. The entry module defaults to automatic mode, but you can change it to manual mode if needed. The HSP and HAR support the configuration of manual mode only.
-- Automatic mode: After an AbilityStage is created, the startup task is automatically executed.
-- Manual mode: After a UIAbility is created, you need to manually call the API to execute the startup task. Modules that are infrequently used do not need to be initialized when the application is started. You can change the startup mode of these modules to manual. After the application is started, you can call [startupManager.run](../reference/apis-ability-kit/js-apis-app-appstartup-startupManager.md#startupmanagerrun) to execute the startup task.
+- Automatic mode: After an AbilityStage is created, startup tasks are automatically executed.
+- Manual mode: After a UIAbility is created, you need to manually call the API to execute the startup tasks and .so file preloading tasks. Modules that are infrequently used do not need to be initialized when the application is launched. You can change the startup mode of these modules to manual. After the application finishes launching, you can call [startupManager.run](../reference/apis-ability-kit/js-apis-app-appstartup-startupManager.md#startupmanagerrun) to execute the startup tasks and .so file preloading tasks.
The following uses the **onCreate** lifecycle of the UIAbility as an example to describe how to manually trigger a startup task. The sample code is as follows:
@@ -231,13 +403,13 @@ import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
- let startParams = ['StartupTask_005', 'StartupTask_006'];
+ let startParams = ["StartupTask_005", "StartupTask_006"];
try {
startupManager.run(startParams).then(() => {
console.log('StartupTest startupManager run then, startParams = ');
}).catch((error: BusinessError) => {
- console.info("StartupTest promise catch error, error = " + JSON.stringify(error));
- console.info("StartupTest promise catch error, startParams = "
+ console.info('StartupTest promise catch error, error = ' + JSON.stringify(error));
+ console.info('StartupTest promise catch error, startParams = '
+ JSON.stringify(startParams));
})
} catch (error) {
@@ -260,8 +432,9 @@ import { startupManager } from '@kit.AbilityKit';
@Entry
@Component
struct Index {
- @State message: string = 'Manual Mode'
- @State startParams: Array = ['StartupTask_006'];
+ @State message: string = "Manual Mode";
+ @State startParams1: Array = ["StartupTask_006"];
+ @State startParams2: Array = ["libentry_006"];
build() {
RelativeContainer() {
@@ -270,8 +443,11 @@ struct Index {
.fontSize(20)
.fontWeight(FontWeight.Bold)
.onClick(() => {
- if (!startupManager.isStartupTaskInitialized("StartupTask_006")) { // Check whether the startup task finishes execution.
- startupManager.run(this.startParams)
+ if (!startupManager.isStartupTaskInitialized("StartupTask_006") ) { // Check whether the startup task finishes execution.
+ startupManager.run(this.startParams1)
+ }
+ if (!startupManager.isStartupTaskInitialized("libentry_006") ) {
+ startupManager.run(this.startParams2)
}
})
.alignRules({
@@ -284,4 +460,3 @@ struct Index {
}
}
```
-
diff --git a/en/application-dev/application-models/app-uri-config.md b/en/application-dev/application-models/app-uri-config.md
index e4bd922dd5055f52d90062e0a8bf275ec6cf7f75..30c457954bcb2412ca3a95f17865dd0c0118831e 100644
--- a/en/application-dev/application-models/app-uri-config.md
+++ b/en/application-dev/application-models/app-uri-config.md
@@ -1,7 +1,7 @@
# Application Link Description
## Description of uris
-**uris** declared in **skills** of the **module.json5** file contains the following fields.
+**uris** declared in [skills](../quick-start/module-configuration-file.md#skills) of the [module.json5 file](../quick-start/module-configuration-file.md) contains the following fields.
> **NOTE**
>
@@ -36,6 +36,11 @@ URIs can be expressed in different formats based on the available fields. Among
### Description of linkFeature
+> **NOTE**
+>
+> The number of **linkFeature** declared in a bundle cannot exceed 150.
+
+
The use of the **linkFeature** field enables an application to deliver a more user-friendly redirection experience. (The declaration of the **linkFeature** field must be reviewed by the application market before being released.) The use scenarios are as follows:
1. Identification of applications of the same type: When the caller starts a vertical application (for example, navigation applications), the system identifies the matched applications based on the **linkFeature** field and displays the applications on the vertical domain panel.
diff --git a/en/application-dev/application-models/application-component-configuration-stage.md b/en/application-dev/application-models/application-component-configuration-stage.md
index 6cfe3b1cb00044fb98134fa69761113fe61b0e3d..a6b9f9be1b5e843d871930d5fe62e5999de8eb08 100644
--- a/en/application-dev/application-models/application-component-configuration-stage.md
+++ b/en/application-dev/application-models/application-component-configuration-stage.md
@@ -7,7 +7,7 @@ During application development, you must configure tags to identify an applicati
The bundle name is specified by the **bundleName** field in the [app.json5 file](../quick-start/app-configuration-file.md) in the **AppScope** directory of the project. This field identifies an application and must be globally unique. You are advised to use the reverse domain name notation, for example, *com.example.demo*, where the first part is the domain suffix **com**, the second part is the vendor/individual name, and the third part is the application name, which can be of multiple levels.
## Configuring Icons and Labels
-Icons and labels are usually configured together. They correspond to the **icon** and **label** fields in the [app.json5 file](../quick-start/app-configuration-file.md) and [module.json5 file](../quick-start/module-configuration-file.md). Since 5.0.3.800, DevEco Studio does not forcibly verify the **icons** and **labels** in the **module.json5** file. Therefore, you can configure them in either **module.json5** or **app.json5**.
+Icons and labels are usually configured together. They correspond to the **icon** and **label** fields in the [app.json5 file](../quick-start/app-configuration-file.md) and [module.json5 file](../quick-start/module-configuration-file.md). In DevEco Studio 5.0.3.800 and later versions, the **icon** and **label** fields are optional in the **module.json5** file, but mandatory in the **app.json5** file. This means that you can skip **icons** and **labels** in the **module.json5** file.
### Generation Mechanism
* If the HAP file contains UIAbility configuration, the following scenarios are possible:
diff --git a/en/application-dev/application-models/application-context-stage.md b/en/application-dev/application-models/application-context-stage.md
index 51cfcd95c32c239a33b68e1af710ee2d8137b52d..89a1cdd926805b35d5049e2234a3df0a777efa53 100644
--- a/en/application-dev/application-models/application-context-stage.md
+++ b/en/application-dev/application-models/application-context-stage.md
@@ -26,7 +26,7 @@
}
}
```
-
+
> **NOTE**
>
> For details about how to obtain the context of a **UIAbility** instance on the page, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability).
@@ -81,135 +81,88 @@ This topic describes how to use the context in the following scenarios:
### Obtaining Application File Paths
-The [base class Context](../reference/apis-ability-kit/js-apis-inner-application-context.md) provides the capability of obtaining application file paths. [ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md), [AbilityStageContext](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md), [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md), and [ExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-extensionContext.md) inherit this capability. The application file paths are a type of application sandbox paths. For details, see [Application Sandbox Directory](../file-management/app-sandbox-directory.md).
-
-The application file paths obtained by the preceding contexts are different.
-
-- The application file path obtained through [ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md) is at the application level. This path is recommended for storing global application information, and the files in the path will be deleted when the application is uninstalled.
-
- | Name| Path|
- | -------- | -------- |
- | bundleCodeDir | \/el1/bundle|
- | cacheDir | \/\/base/cache|
- | filesDir | \/\/base/files|
- | preferencesDir | \/\/base/preferences|
- | tempDir | \/\/base/temp|
- | databaseDir | \/\/database|
- | distributedFilesDir | \/el2/distributedFiles|
- | cloudFileDir12+ | \/el2/cloud|
-
- The sample code is as follows:
-
- ```ts
- import { common } from '@kit.AbilityKit';
- import { hilog } from '@kit.PerformanceAnalysisKit';
- import { promptAction } from '@kit.ArkUI';
+The [base class Context](../reference/apis-ability-kit/js-apis-inner-application-context.md) provides the capability of obtaining application file paths. [ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md), [AbilityStageContext](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md), [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md), and [ExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-extensionContext.md) inherit this capability. However, the specific paths retrieved can differ based on the type of the context used.
- const TAG: string = '[Page_Context]';
- const DOMAIN_NUMBER: number = 0xFF00;
+- [ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md): This context provides access to the application-level file path, which is used to store global application information. Files in this path are removed when the application is uninstalled.
+- [AbilityStageContext](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md), [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md), and [ExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-extensionContext.md): These contexts provide access to [module-level](../quick-start/application-package-overview.md) file paths. Files in these paths are removed when the corresponding [HAP](../quick-start/hap-package.md) or [HSP](../quick-start/in-app-hsp.md) module is uninstalled. Uninstalling an HAP or HSP module does not affect files under the application-level path unless all HAP and HSP modules of the application are uninstalled.
- @Entry
- @Component
- struct Page_Context {
- private context = getContext(this) as common.UIAbilityContext;
-
- build() {
- Column() {
- //...
- List({ initialIndex: 0 }) {
- ListItem() {
- Row() {
- //...
- }
- .onClick(() => {
- let applicationContext = this.context.getApplicationContext();
- let cacheDir = applicationContext.cacheDir;
- let tempDir = applicationContext.tempDir;
- let filesDir = applicationContext.filesDir;
- let databaseDir = applicationContext.databaseDir;
- let bundleCodeDir = applicationContext.bundleCodeDir;
- let distributedFilesDir = applicationContext.distributedFilesDir;
- let preferencesDir = applicationContext.preferencesDir;
- let cloudFileDir = applicationContext.cloudFileDir;
- // Obtain the application file path.
- let filePath = tempDir + 'test.txt';
- hilog.info(DOMAIN_NUMBER, TAG, `filePath: ${filePath}`);
- if (filePath !== null) {
- promptAction.showToast({
- message: filePath
- });
- }
- })
- }
- //...
- }
- //...
- }
- //...
- }
- }
- ```
+ - UIAbilityContext: This context can be used to obtain the file paths of the module containing the UIAbility.
+ - ExtensionContext: This context can be used to obtain the file paths of the module containing the ExtensionAbility.
+ - AbilityStageContext: Given that AbilityStageContext is initialized earlier than UIAbilityContext and ExtensionContext, it is typically used to obtain file paths within the AbilityStage.
-- The application file path obtained through [AbilityStageContext](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md), [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md), and [ExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-extensionContext.md) is at the [HAP](../quick-start/hap-package.md) level. This path is recommended for storing HAP-related information, and the files in this path are deleted when the HAP is uninstalled. However, the deletion does not affect the files in the application-level path unless all HAPs of the application are uninstalled.
+>**NOTE**
+>
+> The application file paths are a type of application sandbox paths. For details, see [Application Sandbox Directory](../file-management/app-sandbox-directory.md).
- | Name| Path|
- | -------- | -------- |
- | bundleCodeDir | \/el1/bundle|
- | cacheDir | \/\/base/**haps/\**/cache|
- | filesDir | \/\/base/**haps/\**/files|
- | preferencesDir | \/\/base/**haps/\**/preferences|
- | tempDir | \/\/base/**haps/\**/temp|
- | databaseDir | \/\/database/**\**|
- | distributedFilesDir | \/el2/distributedFiles/**\**|
- | cloudFileDir12+ | \/el2/cloud/**\**|
+**Table 1** Description of application file paths obtained by different types of contexts
+| Name| Description| Path Obtained by ApplicationContext| Path Obtained by AbilityStageContext, UIAbilityContext, and ExtensionContext|
+| -------- | -------- | -------- | -------- |
+| bundleCodeDir | Bundle code directory.| \/el1/bundle| \/el1/bundle|
+| cacheDir | Cache directory.| \/\/base/cache| \/\/base/**haps/\**/cache|
+| filesDir | File directory.| \/\/base/files| \/\/base/**haps/\**/files|
+| preferencesDir | Preferences directory.| \/\/base/preferences| \/\/base/**haps/\**/preferences|
+| tempDir | Temporary directory.| \/\/base/temp| \/\/base/**haps/\**/temp|
+| databaseDir | Database directory.| \/\/database| \/\/database/**\**|
+| distributedFilesDir | Distributed file directory.| \/el2/distributedFiles| \/el2/distributedFiles/|
+| resourceDir11+ | Resource directory.
**NOTE**
You are required to manually create the **resfile** directory in **\\resource**.| N/A| \/el1/bundle/**\**/resources/resfile|
+| cloudFileDir12+ | Cloud file directory.| \/el2/cloud| \/el2/cloud/|
- The sample code is as follows:
+This section uses ApplicationContext as an example to describe how to obtain the application file path, create a file in the path, and read and write the file. The sample code is as follows:
```ts
import { common } from '@kit.AbilityKit';
+ import { buffer } from '@kit.ArkTS';
+ import { fileIo, ReadOptions } from '@kit.CoreFileKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
- import { promptAction } from '@kit.ArkUI';
const TAG: string = '[Page_Context]';
const DOMAIN_NUMBER: number = 0xFF00;
@Entry
@Component
- struct Page_Context {
+ struct Index {
+ @State message: string = 'Hello World';
private context = getContext(this) as common.UIAbilityContext;
build() {
- Column() {
- //...
- List({ initialIndex: 0 }) {
- ListItem() {
- Row() {
- //...
- }
- .onClick(() => {
- let cacheDir = this.context.cacheDir;
- let tempDir = this.context.tempDir;
- let filesDir = this.context.filesDir;
- let databaseDir = this.context.databaseDir;
- let bundleCodeDir = this.context.bundleCodeDir;
- let distributedFilesDir = this.context.distributedFilesDir;
- let preferencesDir = this.context.preferencesDir;
- let cloudFileDir = applicationContext.cloudFileDir;
- // Obtain the application file path.
- let filePath = tempDir + 'test.txt';
- hilog.info(DOMAIN_NUMBER, TAG, `filePath: ${filePath}`);
- if (filePath !== null) {
- promptAction.showToast({
- message: filePath
- });
- }
- })
+ Row() {
+ Column() {
+ Text(this.message)
+ // ...
+ Button() {
+ Text('create file')
+ // ...
+ .onClick(() => {
+ let applicationContext = this.context.getApplicationContext();
+ // Obtain the application file path.
+ let filesDir = applicationContext.filesDir;
+ hilog.info(DOMAIN_NUMBER, TAG, `filePath: ${filesDir}`);
+ // Create and open the file if it does not exist. Open the file if it already exists.
+ let file = fileIo.openSync(filesDir + '/test.txt', fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
+ // Write data to the file.
+ let writeLen = fileIo.writeSync(file.fd, "Try to write str.");
+ hilog.info(DOMAIN_NUMBER, TAG, `The length of str is: ${writeLen}`);
+ // Create an ArrayBuffer object with a size of 1024 bytes to store the data read from the file.
+ let arrayBuffer = new ArrayBuffer(1024);
+ // Set the offset and length to read.
+ let readOptions: ReadOptions = {
+ offset: 0,
+ length: arrayBuffer.byteLength
+ };
+ // Read the file content to the ArrayBuffer object and return the number of bytes that are actually read.
+ let readLen = fileIo.readSync(file.fd, arrayBuffer, readOptions);
+ // Convert the ArrayBuffer object into a Buffer object and output it as a string.
+ let buf = buffer.from(arrayBuffer, 0, readLen);
+ hilog.info(DOMAIN_NUMBER, TAG, `the content of file: ${buf.toString()}`);
+ // Close the file.
+ fileIo.closeSync(file);
+ })
}
- //...
+ // ...
}
- //...
+ // ...
}
- //...
+ // ...
}
}
```
@@ -316,7 +269,7 @@ struct Page_Context {
### Obtaining the Context of Other Modules in the Current Application
Call [createModuleContext(context: Context, moduleName: string)](../reference/apis-ability-kit/js-apis-app-ability-application.md#applicationcreatemodulecontext12) to obtain the context of another module in the current application. After obtaining the context, you can obtain the resource information of that module.
-
+
```ts
import { common, application } from '@kit.AbilityKit';
import { promptAction } from '@kit.ArkUI';
@@ -344,12 +297,12 @@ Call [createModuleContext(context: Context, moduleName: string)](../reference/ap
console.info(`CreateModuleContext success, data: ${JSON.stringify(data)}`);
if (data !== null) {
promptAction.showToast({
- message: ('Context obtained.')
+ message: ('Context obtained')
});
}
})
.catch((err: BusinessError) => {
- console.error(`CeateMudleContext failed, err code:${err.code}, err msg: ${err.message}`);
+ console.error(`CreateModuleContext failed, err code:${err.code}, err msg: ${err.message}`);
});
})
}
diff --git a/en/application-dev/application-models/application-models.md b/en/application-dev/application-models/application-models.md
index 821a37de6140fdb3b4a69393602081bc142d3b4b..0289e6bc7617ae6b76d7eb10791a70f126828e55 100644
--- a/en/application-dev/application-models/application-models.md
+++ b/en/application-dev/application-models/application-models.md
@@ -50,6 +50,6 @@ The table below describes their differences in detail.
| -------- | -------- | -------- |
| **Application component**| 1. Component classification
- PageAbility: supports user interaction via the UI. For details, see [PageAbility Component Overview](pageability-overview.md).
- ServiceAbility: provides background services without the UI. For details, see [ServiceAbility Component Overview](serviceability-overview.md).
- DataAbility: provides the data sharing capability without the UI. For details, see [DataAbility Component Overview](dataability-overview.md).
2. Development mode
Application components are specified by exporting anonymous objects and fixed entry files. You cannot perform derivation. It is inconvenient for capability expansion.| 1. Component classification
- UIAbility: supports user interaction with the UI. For details, see [UIAbility Component Overview](uiability-overview.md).
- ExtensionAbility: provides scenario-specific extension capabilities (such as widget and input methods). For details, see [ExtensionAbility Component Overview](extensionability-overview.md).
2. Development mode
The object-oriented mode is used to provide open application components as classes. You can derive application components for capability expansion.|
| **Process model**| There are two types of processes:
1. Main process
2. Render process
For details, see [Process Model](process-model-fa.md).| There are three types of processes:
1. Main process
2. ExtensionAbility process
3. Render process
For details, see [Process Model](process-model-stage.md).|
-| **Thread model**| 1. ArkTS engine instance creation
A process can run multiple application component instances, and each application component instance runs in an independent ArkTS engine instance.
2. Thread model
Each ArkTS engine instance is created on an independent thread (non-main thread). The main thread does not have an ArkTS engine instance.
3. Intra-process object sharing: not supported.
For details, see [Thread Model](thread-model-fa.md).| 1. ArkTS engine instance creation
A process can run multiple application component instances, and all application component instances share one ArkTS engine instance.
2. Thread model
The ArkTS engine instance is created on the main thread.
3. Intra-process object sharing: supported.
For details, see [Thread Model](thread-model-stage.md).|
+| **Thread model**| 1. ArkTS engine instance creation
A process can run multiple instances of application components, and each instance runs in an independent ArkTS engine instance.
2. Thread model
Each ArkTS engine instance is created on an independent thread (non-main thread). The main thread does not have an ArkTS engine instance.
3. Intra-process object sharing: not supported.
For details, see [Thread Model](thread-model-fa.md).| 1. ArkTS engine instance creation
A process can run multiple application component instances, and all application component instances share one ArkTS engine instance.
2. Thread model
The ArkTS engine instance is created on the main thread.
3. Intra-process object sharing: supported.
For details, see [Thread Model](thread-model-stage.md).|
|**Mission management model**| - A mission is created for each PageAbility component instance.
- Missions are stored persistently until they are deleted by users or the number of missions exceeds the maximum (customized based on the product configuration).
- PageAbility components do not form a stack structure.| - A mission is created for each UIAbility component instance.
- Missions are stored persistently until they are deleted by users or the number of missions exceeds the maximum (customized based on the product configuration).
- UIAbility components do not form a stack structure.|
| **Configuration file**| The **config.json** file contains the application, HAP, and application component information.
For details, see [Application Configuration File Overview (FA Model)](../quick-start/application-configuration-file-overview-fa.md).| The **app.json5** file contains the application information, and the **module.json5** file contains the HAP and application component information.
For details, see [Application Configuration File Overview (Stage Model)](../quick-start/application-configuration-file-overview-stage.md).|
diff --git a/en/application-dev/application-models/canopenlink.md b/en/application-dev/application-models/canopenlink.md
index 0685288b83b2b4ff4b8cb966a97a1279820eb858..06dd28dd4b81df8c16aeb5874d610d02169489c4 100644
--- a/en/application-dev/application-models/canopenlink.md
+++ b/en/application-dev/application-models/canopenlink.md
@@ -13,7 +13,6 @@ For details about the matching rules, see [Matching Rules of Explicit Want and I
1. Configure the [querySchemes](../quick-start/module-configuration-file.md) field in the **module.json5** file of the entry module to declare the URL schemes.
- A configuration example is as follows:
```json
{
"module": {
@@ -28,7 +27,6 @@ For details about the matching rules, see [Matching Rules of Explicit Want and I
2. Import the **ohos.bundle.bundleManager** module.
3. Call **canOpenLink**.
- The sample code is as follows:
```ts
import { bundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
@@ -46,7 +44,6 @@ For details about the matching rules, see [Matching Rules of Explicit Want and I
### Procedure for the Target Application
Configure the [uris](../quick-start/module-configuration-file.md#skills) field in the **module.json5** file.
-A configuration example is as follows:
```json
{
"module": {
diff --git a/en/application-dev/application-models/capi_nativechildprocess_development_guideline.md b/en/application-dev/application-models/capi_nativechildprocess_development_guideline.md
index 24ec03fd5bc4b6032e4d63e104aaee223a768356..f07925fc43900443f2c98fc85b2c120c1aa04862 100644
--- a/en/application-dev/application-models/capi_nativechildprocess_development_guideline.md
+++ b/en/application-dev/application-models/capi_nativechildprocess_development_guideline.md
@@ -19,7 +19,9 @@ This topic describes how to create a native child process in the main process an
> **NOTE**
>
-> Currently, only 2-in-1 devices are supported, and only one native child process can be started for a process.
+> This function is valid only for 2-in-1 devices.
+>
+> Since API version 15, a single process supports a maximum of 50 native child processes. In API version 14 and earlier versions, a single process supports only one native child process.
### How to Develop
diff --git a/en/application-dev/application-models/component-startup-rules.md b/en/application-dev/application-models/component-startup-rules.md
index 027c7e85640b1b1b72916150a5d367e5260b921e..346bc4c7b82a011dbda2fdd44e5d4dffb9091568 100644
--- a/en/application-dev/application-models/component-startup-rules.md
+++ b/en/application-dev/application-models/component-startup-rules.md
@@ -26,7 +26,7 @@ In view of this, the system formulates a set of component startup rules, as foll
If the **exported** field of the component is set to **true**, the component can be called by other applications. If the field is set to **false**, the component cannot be called by other applications. If this is the case, you must also verify the permission **ohos.permission.START_INVISIBLE_ABILITY**, which is available only for system applications. For details about the **exported** fields, see [abilities](../quick-start/module-configuration-file.md#abilities).
-- Before starting a UIAbility component of a background application, verify the permission **ohos.permission.START_ABILITIES_FROM_BACKGROUND**, which is available only for system applications.
+- Before starting a UIAbility component of a background application, the caller must verify the permission ohos.permission.START_ABILITIES_FROM_BACKGROUND, which is available only for system applications. For 2-in-1 devices, if an application has created a floating window in the foreground, it can start other UIAbility components without verifying this permission after it transitions to the background.
> **NOTE**
>
diff --git a/en/application-dev/application-models/deep-linking-startup.md b/en/application-dev/application-models/deep-linking-startup.md
index 5cd1a67268f64ea8932a469492682b432562a1b9..5a9be6ed35085e3da0f0f8ad024671a451f38a14 100644
--- a/en/application-dev/application-models/deep-linking-startup.md
+++ b/en/application-dev/application-models/deep-linking-startup.md
@@ -11,11 +11,13 @@ Deep Linking searches for an application based on the URI matching rules in impl
### Configuring the module.json5 File
-To be accessed by other applications, an application must configure the [skills](../quick-start/module-configuration-file.md#skills) field of the [module.json5 file](../quick-start/module-configuration-file.md). The value of **scheme** under **uri** can be customized. It can be any string that does not contain special characters or start with **ohos**.
+To be accessed by other applications, an application must configure the [skills](../quick-start/module-configuration-file.md#skills) field of the [module.json5 file](../quick-start/module-configuration-file.md).
> **NOTE**
>
-> The value of **scheme** in Deep Linking cannot be **https**, **http**, or **file**. Otherwise, the default system browser is started.
+> By default, the **skills** field contains a **skill** object, which is used to identify the application entry. Application redirection links should not be configured in this object. Instead, separate **skill** objects should be used. If there are multiple redirection scenarios, create different **skill** objects under **skills**. Otherwise, the configuration does not take effect.
+>
+> In Deep Linking, the **scheme** value can be customized to any string that does not contain special characters and does not start with **ohos**. It is generally recommended to avoid using **https**, **http**, or **file** to prevent the default system browser from being launched.
A configuration example is as follows:
@@ -28,6 +30,14 @@ A configuration example is as follows:
{
// ...
"skills": [
+ {
+ "entities": [
+ "entity.system.home"
+ ],
+ "actions": [
+ "action.system.home"
+ ]
+ },
{
"actions": [
// actions cannot be empty. Otherwise, matching the target application fails.
@@ -41,7 +51,7 @@ A configuration example is as follows:
"host": "www.example.com"
}
]
- }
+ } // Add a skill object for redirection. If there are multiple redirection scenarios, create multiple skill objects.
]
}
]
diff --git a/en/application-dev/application-models/extensionability-overview.md b/en/application-dev/application-models/extensionability-overview.md
index ca26bb071cfe3490a614a4c2d63f2cae50159a98..f10a33a6a2896aff93c840a5b2aa7f0f656b46db 100644
--- a/en/application-dev/application-models/extensionability-overview.md
+++ b/en/application-dev/application-models/extensionability-overview.md
@@ -10,23 +10,24 @@ The table below lists the ExtensionAbility types defined in the system.
> **NOTE**
>
-> - The column **Allow Third-Party Apps to Implement** specifies whether third-party applications can inherit the **ExtensionAbility** parent class and implement their own service logic for a type of ExtensionAbility. The value **Y** means that third-party applications can implement their own service logic for a type of ExtensionAbility, **N** means the opposite.
-> - The column **Allow Third-Party Apps to Access** specifies whether third-party applications can access external services provided by a type of ExtensionAbility. The value **Y** means that third-party applications can access external services provided by a certain type of ExtensionAbility, **N** means that they cannot access external services, and **NA** means that no external services are provided.
-> - The column **Allow Independent ExtensionAbility Sandbox** specifies whether an independent sandbox is provided for an ExtensionAbility. In versions earlier than API version 12, an application and its ExtensionAbilities use the same sandbox. Since API version 12, a new ExtensionAbility uses an independent sandbox. Currently, the InputMethodExtensionAbility runs in an independent sandbox for security purposes. The value **Y** means that an independent sandbox is provided for an ExtensionAbility, and **N** means that no independent sandbox is provided for an ExtensionAbility.
-> - The column **Allow ExtensionAbilities to Access Sendable Data in Strict Mode** specifies whether an ExtensionAbility can access sendable data in strict mode. Sendable data is implemented by configuring [data-group-ids](../security/app-provision-structure.md#bundle-info) and [dataGroupIds](../quick-start/module-configuration-file.md#extensionabilities) of the application. Strict access indicates that the sendable data is read-only, and non-strict access indicates that the data can be read and written. The value **Y** means that an ExtensionAbility uses strict mode to access sendable data, that is, it can read sendable data. The value **N** means that an ExtensionAbility uses non-strict mode to access sendable data, that is, it can read and write sendable data.
+> - The column **Allow Third-Party Apps to Implement** specifies whether third-party applications can inherit the **ExtensionAbility** parent class and implement their own service logic for a type of ExtensionAbility.
+> - The column **Allow Third-Party Apps to Access** specifies whether third-party applications can access external services provided by a type of ExtensionAbility.
+> - The column **Allow Independent ExtensionAbility Sandbox** specifies whether an independent sandbox is provided for an ExtensionAbility. In versions earlier than API version 12, an application and its ExtensionAbilities use the same sandbox. Since API version 12, a new ExtensionAbility uses an independent sandbox. Currently, the InputMethodExtensionAbility runs in an independent sandbox for security purposes.
+> - The column **Allow ExtensionAbilities to Access Sendable Data in Strict Mode** specifies whether an ExtensionAbility can access sendable data in strict mode. Sendable data is implemented by configuring [data-group-ids](../security/app-provision-structure.md#bundle-info) and [dataGroupIds](../quick-start/module-configuration-file.md#extensionabilities) of the application. Strict access indicates that the sendable data is read-only, and non-strict access indicates that the data can be read and written.
System applications are not restricted. They can implement all the ExtensionAbility types defined in the system and access external services provided by all the ExtensionAbility types.
| ExtensionAbility Type | Description| Allow Third-Party Apps to Implement | Allow Third-Party Apps to Access | Allow Independent ExtensionAbility Sandbox | Allow ExtensionAbilities to Access Sendable Data in Strict Mode |
-| ------------------------ | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| [FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md) | ExtensionAbility component of the FORM type, which provides APIs related to [widgets](../form/formkit-overview.md). | Y | N | N | N |
-| [WorkSchedulerExtensionAbility](../reference/apis-backgroundtasks-kit/js-apis-WorkSchedulerExtensionAbility.md) | ExtensionAbility component of the WORK_SCHEDULER type, which provides callbacks for [deferred tasks](../task-management/work-scheduler.md). | Y | NA | N | N |
-| [InputMethodExtensionAbility](../reference/apis-ime-kit/js-apis-inputmethod-extension-ability.md) | ExtensionAbility component of the INPUT_METHOD type, which is used to develop [input method applications](../inputmethod/ime-kit-intro.md). | Y | Y | Y | N if you have enabled the full mode in input method management
Y if you have not enabled the full mode in input method management|
-| [BackupExtensionAbility](../reference/apis-core-file-kit/js-apis-application-backupExtensionAbility.md) | ExtensionAbility component of the BACKUP type, which provides APIs for [backing up and restoring application data](../file-management/app-file-backup-overview.md). | Y | NA | N | N |
-| [DriverExtensionAbility](../reference/apis-driverdevelopment-kit/js-apis-app-ability-driverExtensionAbility.md) | ExtensionAbility component of the DRIVER type, which provides the [driver-related extension framework](../device/driver/driverextensionability.md). | Y | Y | N | N |
-| [EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md) | ExtensionAbility component of the EMBEDDED_UI type, which provides the [embedded UI across processes](embeddeduiextensionability.md).| Y | Y | N | N |
-| [ShareExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-shareExtensionAbility.md) | ExtensionAbility component of the SHARE type, which is used to extend the sharing template service.| Y | Y | N | N |
+| ------------------------ | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
+ | [FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md) | ExtensionAbility component of the FORM type, which provides APIs related to [widgets](../form/formkit-overview.md). | Yes| No| No| In non-strict mode, sendable data can be read and written.|
+| [WorkSchedulerExtensionAbility](../reference/apis-backgroundtasks-kit/js-apis-WorkSchedulerExtensionAbility.md) | ExtensionAbility component of the WORK_SCHEDULER type, which provides callbacks for [deferred tasks](../task-management/work-scheduler.md). | Yes| N/A| No| In non-strict mode, sendable data can be read and written.|
+| [InputMethodExtensionAbility](../reference/apis-ime-kit/js-apis-inputmethod-extension-ability.md) | ExtensionAbility component of the INPUT_METHOD type, which is used to develop [input method applications](../inputmethod/ime-kit-intro.md). | Yes| Yes| Yes| If full mode is enabled in input method management (in non-strict mode), sendable data can be read and written. If full mode is not enabled (in strict mode), sendable data can be read only.|
+| [BackupExtensionAbility](../reference/apis-core-file-kit/js-apis-application-backupExtensionAbility.md) | ExtensionAbility component of the BACKUP type, which provides APIs for [backing up and restoring application data](../file-management/app-file-backup-overview.md). | Yes| N/A| No| In non-strict mode, sendable data can be read and written.|
+| [DriverExtensionAbility](../reference/apis-driverdevelopment-kit/js-apis-app-ability-driverExtensionAbility.md) | ExtensionAbility component of the DRIVER type, which provides the [driver-related extension framework](../device/driver/driverextensionability.md). | Yes| Yes| No| In non-strict mode, sendable data can be read and written.|
+| [EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md) | ExtensionAbility component of the EMBEDDED_UI type, which provides the [embedded UI across processes](embeddeduiextensionability.md).| Yes| Yes| No| In non-strict mode, sendable data can be read and written.|
+| [ShareExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-shareExtensionAbility.md) | ExtensionAbility component of the SHARE type, which is used to extend the sharing template service.| Yes| Yes| No| In non-strict mode, sendable data can be read and written.|
+| [FenceExtension](../reference/apis-location-kit/js-apis-app-ability-FenceExtensionAbility.md) | ExtensionAbility component of the FENCE type, which provides the [geofence](../device/location/fenceExtensionAbility.md) capability.| Yes| No| No| In non-strict mode, sendable data can be read and written.|
diff --git a/en/application-dev/application-models/figures/WidgerCameraCard.png b/en/application-dev/application-models/figures/WidgerCameraCard.png
deleted file mode 100644
index 55e62cdb8791ca6bbc95b7ea4c054e93270ce7a6..0000000000000000000000000000000000000000
Binary files a/en/application-dev/application-models/figures/WidgerCameraCard.png and /dev/null differ
diff --git a/en/application-dev/application-models/figures/app-startup-procedure.png b/en/application-dev/application-models/figures/app-startup-procedure.png
index d78d1d382595f1d8f8fd67235754c0c9670cc4ef..eb14c958c7f887ad6d33622c925eab1ae46a7983 100644
Binary files a/en/application-dev/application-models/figures/app-startup-procedure.png and b/en/application-dev/application-models/figures/app-startup-procedure.png differ
diff --git a/en/application-dev/application-models/figures/app-startup.png b/en/application-dev/application-models/figures/app-startup.png
index 14bfbef88f8ae0b40f57adbce02182d571aa182b..9827d50812a29f2d9321072db6f56c5b53c2900f 100644
Binary files a/en/application-dev/application-models/figures/app-startup.png and b/en/application-dev/application-models/figures/app-startup.png differ
diff --git a/en/application-dev/application-models/figures/application-component-configuration-stage-app-module-1.png b/en/application-dev/application-models/figures/application-component-configuration-stage-app-module-1.png
new file mode 100644
index 0000000000000000000000000000000000000000..5db852e92eb2f4bd782df5c370d3028c7cc65cb1
Binary files /dev/null and b/en/application-dev/application-models/figures/application-component-configuration-stage-app-module-1.png differ
diff --git a/en/application-dev/application-models/figures/common-event.png b/en/application-dev/application-models/figures/common-event.png
deleted file mode 100644
index fe2591d12d5f2c570d7be942d33ec330a6eb6c98..0000000000000000000000000000000000000000
Binary files a/en/application-dev/application-models/figures/common-event.png and /dev/null differ
diff --git a/en/application-dev/application-models/figures/hop-cross-device-migration6.png b/en/application-dev/application-models/figures/hop-cross-device-migration6.png
deleted file mode 100644
index 5cc5cb2ca17b8bddf4776928f01c2bee63905cb2..0000000000000000000000000000000000000000
Binary files a/en/application-dev/application-models/figures/hop-cross-device-migration6.png and /dev/null differ
diff --git a/en/application-dev/application-models/figures/hop-cross-device-migration7.png b/en/application-dev/application-models/figures/hop-cross-device-migration7.png
deleted file mode 100644
index f476e00b8e253e3d6b2fe4bd547674a0448554b4..0000000000000000000000000000000000000000
Binary files a/en/application-dev/application-models/figures/hop-cross-device-migration7.png and /dev/null differ
diff --git a/en/application-dev/application-models/figures/hop-cross-device-migration8.png b/en/application-dev/application-models/figures/hop-cross-device-migration8.png
deleted file mode 100644
index ec39a1b7aee3adea32e6f84a2b25758ac03a69b0..0000000000000000000000000000000000000000
Binary files a/en/application-dev/application-models/figures/hop-cross-device-migration8.png and /dev/null differ
diff --git a/en/application-dev/application-models/figures/hsp-har-startup.png b/en/application-dev/application-models/figures/hsp-har-startup.png
new file mode 100644
index 0000000000000000000000000000000000000000..54e1574787e04760a6bce8aabd8c0dddfdef226a
Binary files /dev/null and b/en/application-dev/application-models/figures/hsp-har-startup.png differ
diff --git a/en/application-dev/application-models/figures/start-express-panel.png b/en/application-dev/application-models/figures/start-express-panel.png
index e3929ce1ca10336ccd5d08d5f03105c7571ccc95..82f320c76925a8eb5a3fce09ba1c413b958fa3d6 100644
Binary files a/en/application-dev/application-models/figures/start-express-panel.png and b/en/application-dev/application-models/figures/start-express-panel.png differ
diff --git a/en/application-dev/application-models/figures/start-finance-panel.png b/en/application-dev/application-models/figures/start-finance-panel.png
index 1ead6627e73bfd6ddef90d742fb0f80a0923d8d8..027623fc9f08ebaeaa273e37526ab5e38472ea08 100644
Binary files a/en/application-dev/application-models/figures/start-finance-panel.png and b/en/application-dev/application-models/figures/start-finance-panel.png differ
diff --git a/en/application-dev/application-models/figures/start-flight-panel.png b/en/application-dev/application-models/figures/start-flight-panel.png
index e3929ce1ca10336ccd5d08d5f03105c7571ccc95..82f320c76925a8eb5a3fce09ba1c413b958fa3d6 100644
Binary files a/en/application-dev/application-models/figures/start-flight-panel.png and b/en/application-dev/application-models/figures/start-flight-panel.png differ
diff --git a/en/application-dev/application-models/figures/start-mail-panel.png b/en/application-dev/application-models/figures/start-mail-panel.png
index 205ac73d4121ae7dd75b58bcd23508ef32786d9d..5f7cbec5c5d6c9855cfa2c87239dceb801993911 100644
Binary files a/en/application-dev/application-models/figures/start-mail-panel.png and b/en/application-dev/application-models/figures/start-mail-panel.png differ
diff --git a/en/application-dev/application-models/figures/start-navigation-panel.png b/en/application-dev/application-models/figures/start-navigation-panel.png
index 1050cbc2a421b6ae4db98f842091624b764979d6..9d6f54d27fdb2a95507cbcb0fcb00d13dfdc8575 100644
Binary files a/en/application-dev/application-models/figures/start-navigation-panel.png and b/en/application-dev/application-models/figures/start-navigation-panel.png differ
diff --git a/en/application-dev/application-models/hop-cross-device-migration.md b/en/application-dev/application-models/hop-cross-device-migration.md
index 9ba5b87d21dd6931767211befdbebc786f751aee..275e343bed6272da714701595350aeb605e8e64d 100644
--- a/en/application-dev/application-models/hop-cross-device-migration.md
+++ b/en/application-dev/application-models/hop-cross-device-migration.md
@@ -290,6 +290,7 @@ To implement special scenarios, for example, where migration is required only fo
> **NOTE**
>
> Currently, only the page stack implemented based on the router module can be automatically restored. The page stack implemented using the **Navigation** component cannot be automatically restored.
+>
> If an application uses the **Navigation** component for routing, you can disable default page stack migration by setting [SUPPORT_CONTINUE_PAGE_STACK_KEY](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#params) to **false**. In addition, save the page (or page stack) to be migrated in **want**, and manually load the specified page on the target device.
By default, the page stack is restored during the migration of a [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md). Before [onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) or [onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant) finishes the execution, call [restoreWindowStage()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#restore) to pass in the current window context, which will be used for page stack loading and restoration. The **restoreWindowStage()** API must be executed in a synchronous API. If it is executed during an asynchronous callback, there is a possibility that the page fails to be loaded during application startup.
@@ -366,13 +367,14 @@ export default class MigrationAbility extends UIAbility {
}
```
-### Supporting Cross-Device Migration Between Different Abilities in the Same Application
+### Migrating Between Abilities in the Same Application Across Devices
Generally, the same ability is involved during a cross-device migration. However, different ability names may be configured for the same service on different device types, resulting in different abilities. To support migration in this scenario, you can configure the **continueType** flag under **abilities** in the [module.json5](../quick-start/module-configuration-file.md) file for association.
The values of the **continueType** tag of the two abilities must be the same. The following is an example:
> **NOTE**
>
> The value of **continueType** must be unique in an application. The value is a string of a maximum of 127 bytes consisting of letters, digits, and underscores (_).
+ >
> The **continueType** tag is a string array. If multiple fields are configured, only the first field takes effect.
```json
@@ -405,6 +407,62 @@ The values of the **continueType** tag of the two abilities must be the same. Th
}
```
+### Migrating Abilities with Different Bundle Names in the Same Application Across Devices
+An application may use different bundle names on different devices. To support migration in this scenario, configure **abilities** in the **module.json5** file of the application as follows:
+
+- **continueBundleName**: bundle name of the application on the peer device.
+- **continueType**: The same value must be used.
+
+ > **NOTE**
+ >
+ > The value of **continueType** must be unique in an application. The value is a string of a maximum of 127 bytes consisting of letters, digits, and underscores (_).
+ >
+ > The **continueType** tag is a string array. If multiple fields are configured, only the first field takes effect.
+
+
+An example is as follows:
+
+An application with different bundle names is migrated between device A and device B. The bundle name of the application on device A is com.demo.example1, and that on device B is com.demo.example2.
+
+```JSON
+// In the configuration file for device A, set continueBundleName to the bundle name of the application on device B.
+{
+ "module": {
+ // ···
+ "abilities": [
+ {
+ "name": "EntryAbility",
+ // ···
+ "continueType": ["continueType"],
+ "continueBundleName": ["com.demo.example2"], // continueBundleName is set to com.demo.example2, which is the bundle name of the application on device B.
+
+ }
+ ]
+
+ }
+}
+```
+
+```JSON
+// In the configuration file for device B, set continueBundleName to the bundle name of the application on device A.
+{
+ "module": {
+ // ···
+ "abilities": [
+ {
+ "name": "EntryAbility",
+ // ···
+ "continueType": ["continueType"],
+ "continueBundleName": ["com.demo.example1"], // continueBundleName is set to com.demo.example1, which is the bundle name of the application on device A.
+
+ }
+ ]
+
+ }
+}
+
+```
+
### Quickly Starting a Target Application
By default, the target application on the peer device is not started immediately when the migration is initiated. It waits until the data to migrate is synchronized from the source device to the peer device. To start the target application immediately upon the initiation of a migration, you can add the **_ContinueQuickStart** suffix to the value of **continueType**. In this way, only the migrated data is restored after the data synchronization, delivering an even better migration experience.
@@ -422,7 +480,11 @@ By default, the target application on the peer device is not started immediately
}
}
```
-With quick start, the target application starts while waiting for the data to migration, minimizing the duration that users wait for the migration to complete. Note that, for the first migration with quick start enabled, the [onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) or [onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant) callback is triggered, in which **launchReason** is **PREPARE_CONTINUATION**. The introduce of the **launchReason** parameter solves problems related to redirection and timing. It also provides a loading screen during quick startup, delivering a better experience. The following figure shows the quick start process.
+With quick start, the target application starts while waiting for the data to migration, minimizing the duration that users wait for the migration to complete. Note that, for the first migration with quick start enabled, the [onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) or [onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant) callback is triggered, in which **launchReason** is **PREPARE_CONTINUATION**. The introduction of the **launchReason** parameter solves problems related to redirection and timing. It also provides a loading screen during quick startup.
+
+Since API version 16, an application that displays a loading page during quick launch can [obtain the quick startup result during cross-device migration](../reference/apis-ability-kit/js-apis-app-ability-continueManager.md#continuemanageron). Depending on this result, the application can take appropriate actions. For example, if the quick startup is successful, the application can dismiss the loading page and proceed to the continuation page.
+
+The following figure shows the quick start process.
@@ -487,7 +549,7 @@ export default class MigrationAbility extends UIAbility {
}
```
-When the target application is quickly started, the [onWindowStageCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) and [onWindowStageRestore()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore) callbacks are triggered in sequence. Generally, in **onWindowStageCreate()**, you call [loadContent()](../reference/apis-arkui/js-apis-window.md#loadcontent9) to load the page. This API throws an asynchronous task to load the home page. This asynchronous task is not synchronous with **onWindowStageRestore()**. If UI-related APIs (such as route APIs) are used in **onWindowStageRestore()**, the invoking time may be earlier than the home page loading time. To ensure the normal loading sequence, you can use [setTimeout()](../reference/common/js-apis-timer.md#settimeout) to throw an asynchronous task for related operations. For details, see the sample code.
+When the target application is quickly started, the [onWindowStageCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) and [onWindowStageRestore()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore) callbacks are triggered in sequence. Generally, in **onWindowStageCreate()**, you call [loadContent()](../reference/apis-arkui/js-apis-window.md#loadcontent9) to load the page. This API throws an asynchronous task to load the home page. This asynchronous task is not synchronous with **onWindowStageRestore()**. If UI-related APIs (such as route APIs) are used in **onWindowStageRestore()**, the invoking time may be earlier than the home page loading time. To ensure the normal loading sequence, you can use [setTimeout()](../reference/common/js-apis-timer.md#settimeout) to throw an asynchronous task for related operations.
The sample code is as follows:
@@ -611,8 +673,10 @@ On the source device, save the data to migrate to a distributed [data object](..
> **NOTE**
>
-> Distributed data objects must be activated before being made persistent. Therefore, the **save()** API must be called after setSessionId().
+> Distributed data objects must be activated before being made persistent. Therefore, the **save()** API must be called after **setSessionId()**.
+>
> For applications that need to exit from the source device after migration, use **await** to wait until the **save()** API finishes execution. This prevents the application from exiting before data is saved. Since API version 12, an asynchronous **onContinue()** API is provided for this scenario.
+>
> Currently, the **sessionId** field in **wantParams** is occupied by the system in the migration process. You are advised to define another key in **wantParams** to store the ID to avoid data exceptions.
The sample code is as follows:
@@ -695,9 +759,11 @@ In [onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#u
> **NOTE**
>
-> 1. The distributed data object of the peer device to be added to the network cannot be a temporary variable. This is because the callback of the **on()** API may be executed after **onCreate()** or **onNewWant()** finishes execution. If the temporary variable is released, a null pointer exception may occur. You can use a class member variable to avoid this problem.
-> 2. The attributes of the object used to create the distributed data object on the peer device must be undefined before the distributed data object is activated. Otherwise, the source data will be overwritten after new data is added to the network, and data restoration will fail.
-> 3. Before activating the distributed data object, call **on()** to listen for the restore event. This helps prevent data restoration failure caused by event missing.
+> The distributed data object of the peer device to be added to the network cannot be a temporary variable. This is because the callback of the **on()** API may be executed after **onCreate()** or **onNewWant()** finishes execution. If the temporary variable is released, a null pointer exception may occur. You can use a class member variable to avoid this problem.
+>
+> The attributes of the object used to create the distributed data object on the peer device must be undefined before the distributed data object is activated. Otherwise, the source data will be overwritten after new data is added to the network, and data restoration will fail.
+>
+> Before activating the distributed data object, call **on()** to listen for the restore event. This helps prevent data restoration failure caused by event missing.
The sample code is as follows:
@@ -1075,4 +1141,3 @@ export default class MigrationAbility extends UIAbility {
If page stack migration is not disabled for an application, the system migrates and loads the page stack of the application by default. In this case, if you use [loadContent()](../reference/apis-arkui/js-apis-window.md#loadcontent9) to trigger the loading of a specific page in the [onWindowStageRestore()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagerestore) lifecycle callback function, the loading does not take effect and the page in the page stack is still restored.
-
\ No newline at end of file
diff --git a/en/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md b/en/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md
index 2a0f47113a8b1ee3244aa2f1ea52e4a1bf12ddc5..056ccc169d62f1d83f98efaaf0e8f2ce57e20d96 100644
--- a/en/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md
+++ b/en/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md
@@ -66,7 +66,7 @@ const DOMAIN_NUMBER: number = 0xFF00;
let context: common.UIAbilityContext = this.context; // UIAbilityContext
// Set a name for the mission snapshot.
context.setMissionLabel('test').then(() => {
- hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in seting mission label.');
+ hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in setting mission label.');
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG, `Failed to set mission label. Code is ${err.code}, message is ${err.message}`);
});
diff --git a/en/application-dev/application-models/process-model-stage.md b/en/application-dev/application-models/process-model-stage.md
index f4f9401e6d30913cc28074d01880eb9b1e3a8e98..ebfebd122fffcb6644f8cdab222aa1a9332bc74a 100644
--- a/en/application-dev/application-models/process-model-stage.md
+++ b/en/application-dev/application-models/process-model-stage.md
@@ -1,11 +1,11 @@
# Process Model (Stage Model)
+A process is the basic unit for a system to allocate resources, and is the basis of an operating system structure.
The process model is shown below.
-
-- Generally, all UIAbility, ServiceExtensionAbility, and DataShareExtensionAbility components of an application (with the same bundle name) run in an independent process, which is **Main process** in green in the figure.
-- All ExtensionAbility components of the same type (except ServiceExtensionAbility and DataShareExtensionAbility) of an application (with the same bundle name) run in an independent process, such as **FormExtensionAbility process**, **InputMethodExtensionAbility process**, and other **ExtensionAbility process** in blue in the figure.
+- Generally, all UIAbility, ServiceExtensionAbility, and DataShareExtensionAbility components of an application (with the same bundle name) run in an independent process, which is **Main process** in green in the figure.
+- All ExtensionAbility components of the same type (except ServiceExtensionAbility and DataShareExtensionAbility) of an application (with the same bundle name) run in an independent process, such as **FormExtensionAbility process**, **InputMethodExtensionAbility process**, and other **ExtensionAbility process** in blue in the figure.
- WebView has an independent render process, which is **Render process** in yellow in the figure.
> **NOTE**
@@ -23,7 +23,7 @@ The process model is shown below.
> - You can create ServiceExtensionAbility and DataShareExtensionAbility only for system applications.
> - To view information about all running processes, run the **hdc shell** command to enter the shell CLI of the device, and run the **ps -ef** command.
-A system application can apply for multi-process permissions (as shown in the following figure) and configure a custom process for an HAP. UIAbility, DataShareExtensionAbility, and ServiceExtensionAbility in the HAP run in the custom process. Different HAPs run in different processes by configuring different process names.
+A system application can apply for multi-process permissions (as shown in the following figure) and configure a custom process for an HAP. In this way, the UIAbilities, DataShareExtensionAbilities, and ServiceExtensionAbilities in the HAP run in the custom process. For details about how to request the permissions, see [Application Privilege Configuration](../../device-dev/subsystems/subsys-app-privilege-config-guide.md). To configure a custom process for an HAP, use **process** in [module.json5](../quick-start/module-configuration-file.md#tags-in-the-configuration-file).
**Figure 2** Multi-process
@@ -34,4 +34,3 @@ The system provides the following inter-process communication (IPC) mechanism:
[Common Events](../basic-services/common-event/common-event-overview.md): This mechanism is used in one-to-many communication scenarios. Multiple subscribers may receive events at the same time.
-
diff --git a/en/application-dev/application-models/start-email-apps.md b/en/application-dev/application-models/start-email-apps.md
index 252aeabc97cb6e1da148dd2e6c3330a622d04998..3225e739023cf5471331324c20b74b65085c7d87 100644
--- a/en/application-dev/application-models/start-email-apps.md
+++ b/en/application-dev/application-models/start-email-apps.md
@@ -15,7 +15,7 @@ If the **type** field in **startAbilityByType** is set to **mail**, **wantParam*
| body | string | No | Email body. |
| ability.params.stream | string[ ] | No | Email attachments (URI list of the attachments). |
| ability.want.params.uriPermissionFlag | [wantConstant.Flags](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#flags) | No | At least the read permission must be granted on the email attachments. This parameter is mandatory when **ability.params.stream** is specified.|
-| sceneType | number | No | 1: Send an email. The default value is **1**. |
+| sceneType | number | No | Intent scene, which indicates the purpose of the current request. 1: Send an email. The default value is **1**. |
> **NOTE**
>
@@ -24,7 +24,7 @@ If the **type** field in **startAbilityByType** is set to **mail**, **wantParam*
> * For parameters of the string[] type displayed in the vertical domain panel of email applications, all elements in the array must be encoded using **encodeURI**.
## Developing a Caller Application
-1. Import the **ohos.app.ability.common** module.
+1. Import the module.
```ts
import { common, wantConstant } from '@kit.AbilityKit';
```
@@ -96,7 +96,7 @@ If the **type** field in **startAbilityByType** is set to **mail**, **wantParam*
2. Parse and process the parameters transferred from the panel.
```ts
- UIAbility::onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
+ UIAbility.onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
```
The **want.parameters** parameter contains the following parameters, which may be slightly different from the ones passed in by the caller.
diff --git a/en/application-dev/application-models/start-express-apps.md b/en/application-dev/application-models/start-express-apps.md
index b8232b27c9505442499198978b9cb012b13aa8cf..3a8a261df465449a0594ce40cc35328ba92ad38e 100644
--- a/en/application-dev/application-models/start-express-apps.md
+++ b/en/application-dev/application-models/start-express-apps.md
@@ -6,22 +6,21 @@ For example, in a messaging application, when a user receives a delivery trackin
## Parameters on the Express Delivery Application Panel
-If the **type** field in **startAbilityByType** is set to **express**, the intent scenario of express delivery query is supported. The corresponding **wantParam** parameter contains the following properties.
+If the **type** field in **startAbilityByType** is set to **express**, the intent scenario of express delivery query is supported. The corresponding **wantParam** parameter contains the following properties.
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | -------------------------------------- |
-| sceneType | number | No | Intent. The default value is **1**. In express delivery query scenarios, set it to **1** or leave it empty.|
+| sceneType | number | No | Intent scene, which indicates the purpose of the current request. The default value is **1**. In express delivery query scenarios, set it to **1** or leave it empty.|
| expressNo | string | Yes | Express delivery tracking number. |
## Developing a Caller Application
-1. Import the **ohos.app.ability.common** module.
+1. Import the module.
```ts
import { common } from '@kit.AbilityKit';
```
-
2. Construct parameters and call the **startAbilityByType** API.
```ts
@@ -86,7 +85,7 @@ If the **type** field in **startAbilityByType** is set to **express**, the inten
2. Parse parameters and perform corresponding processing.
```ts
- UIAbility::onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
+ UIAbility.onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
```
The **want.uri** parameter carries the URI corresponding to **linkFeature** configured by the target application.
diff --git a/en/application-dev/application-models/start-finance-apps.md b/en/application-dev/application-models/start-finance-apps.md
index 91ce78c056de907eb60d160b3678bda52f117c54..bc5e9137736fe5adfb25d8268de77c7739b90bec 100644
--- a/en/application-dev/application-models/start-finance-apps.md
+++ b/en/application-dev/application-models/start-finance-apps.md
@@ -8,11 +8,11 @@ If the **type** field in **startAbilityByType** is set to **finance**, **wantPar
| Name | Type | Mandatory| Description|
| -------------------- | ------------------------------------------------------------ | -------- | -------- |
-| sceneType | number | No| The options are as follows: 1: transfer; 2: credit card repayment. The default value is **1**.|
+| sceneType | number | No| Intent scene, which indicates the purpose of the current request. The options are as follows: 1: transfer; 2: credit card repayment. The default value is **1**.|
| bankCardNo | string | No | Bank card number.|
## Developing a Caller Application
-1. Import the **ohos.app.ability.common** module.
+1. Import the module.
```ts
import { common } from '@kit.AbilityKit';
```
@@ -87,7 +87,7 @@ If the **type** field in **startAbilityByType** is set to **finance**, **wantPar
2. Parse and process the parameters transferred from the panel.
```ts
- UIAbility::onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
+ UIAbility.onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
```
The **want.uri** parameter carries the URI corresponding to **linkFeature** configured by the target application.
diff --git a/en/application-dev/application-models/start-flight-apps.md b/en/application-dev/application-models/start-flight-apps.md
index 71d86d4ed27899668a8c12e5e1d92fd4bc235d1f..af2107cf64e355f6280d83dfc5ec0ea164ce2f3c 100644
--- a/en/application-dev/application-models/start-flight-apps.md
+++ b/en/application-dev/application-models/start-flight-apps.md
@@ -12,7 +12,7 @@ If the **type** field in **startAbilityByType** is set to **flight**, two intent
| Name | Type | Mandatory| Description |
| ------------- | ------ | ---- | ------------------------------------------------------------ |
- | sceneType | number | No | Intent. The default value is **1**. In scenarios of flight query by flight number, set it to **1** or leave it empty. |
+ | sceneType | number | No | Intent scene, which indicates the purpose of the current request. The default value is **1**. In scenarios of flight query by flight number, set it to **1** or leave it empty. |
| flightNo | string | Yes | Flight number, which is a two-digit code of the airline company plus a dight.|
| departureDate | string | No | Flight departure date, in the format of YYYY-MM-DD. |
@@ -20,7 +20,7 @@ If the **type** field in **startAbilityByType** is set to **flight**, two intent
| Name | Type | Mandatory| Description |
| -------------------- | ---------------------- | ---- | -------------------------------------------------------- |
- | sceneType | number | Yes | Intent. In scenarios of flight query by origin and destination, set it to **2**. |
+ | sceneType | number | Yes | Intent scene, which indicates the purpose of the current request. In scenarios of flight query by origin and destination, set it to **2**. |
| originLocation | string | Yes | Departure place. |
| destinationLocation | string | Yes | Destination. |
| departureDate | string | No | Flight departure date, in the format of YYYY-MM-DD. |
@@ -28,7 +28,7 @@ If the **type** field in **startAbilityByType** is set to **flight**, two intent
## Developing a Caller Application
-1. Import the **ohos.app.ability.common** module.
+1. Import the module.
```ts
import { common } from '@kit.AbilityKit';
```
@@ -103,7 +103,7 @@ If the **type** field in **startAbilityByType** is set to **flight**, two intent
2. Parse parameters and perform corresponding processing.
```ts
- UIAbility::onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
+ UIAbility.onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
```
The **want.uri** parameter carries the URI corresponding to **linkFeature** configured by the target application.
diff --git a/en/application-dev/application-models/start-navigation-apps.md b/en/application-dev/application-models/start-navigation-apps.md
index 92c52004b84f86ee6a13b4e753f6e3a905970ac3..de6ef28da69ff35d382d57146324a79878807323 100644
--- a/en/application-dev/application-models/start-navigation-apps.md
+++ b/en/application-dev/application-models/start-navigation-apps.md
@@ -15,7 +15,7 @@ If the **type** field in **startAbilityByType** is set to **navigation**, three
| Name | Type | Mandatory| Description |
| -------------------- | ---------------------- | ---- | ---------------------------------------------------- |
- | sceneType | number | No | Intent. The default value is **1**. In route planning scenarios, set it to **1** or leave it empty. |
+ | sceneType | number | No | Intent scene, which indicates the purpose of the current request. The default value is **1**. In route planning scenarios, set it to **1** or leave it empty. |
| originName | string | No | Name of the source. |
| originLatitude | number | No | Latitude of the source. |
| originLongitude | number | No | Longitude of the source. |
@@ -30,7 +30,7 @@ If the **type** field in **startAbilityByType** is set to **navigation**, three
| Name | Type | Mandatory| Description |
| -------------------- | ---------------------- | ---- | ----------------- |
- | sceneType | number | Yes | Intent. Set it to **2** for navigation scenarios.|
+ | sceneType | number | Yes | Intent scene, which indicates the purpose of the current request. Set it to **2** for navigation scenarios.|
| destinationName | string | No | Name of the destination. |
| destinationLatitude | number | Yes | Latitude of the destination. |
| destinationLongitude | number | Yes | Longitude of the destination. |
@@ -40,21 +40,21 @@ If the **type** field in **startAbilityByType** is set to **navigation**, three
| Name | Type | Mandatory| Description |
| --------------- | ------ | ---- | --------------------- |
- | sceneType | number | Yes | Intent. Set it to **3** for place search scenarios.|
+ | sceneType | number | Yes | Intent scene, which indicates the purpose of the current request. Set it to **3** for place search scenarios.|
| destinationName | string | Yes | Name of the destination. |
## Developing a Caller Application
-1. Import the **ohos.app.ability.common** module.
+1. Import the module.
```ts
import { common } from '@kit.AbilityKit';
```
2. Construct parameters and call the **startAbilityByType** API.
You need to obtain the POI IDs of the destination and origin from each map system and pass the parameters **destinationPoiIds** and **originPoiIds** based on the mappings.
-
-
+
+
```ts
let context = getContext(this) as common.UIAbilityContext;
let wantParam: Record = {
@@ -63,10 +63,10 @@ If the **type** field in **startAbilityByType** is set to **navigation**, three
'destinationLongitude': 118.78315,
'destinationName': 'No.xx, xx Road, xx City',
'destinationPoiIds': {
- 1: '1111', // Key 1 indicates Petal Maps, and the value must be a POI in Petal Maps.
+ 1:'1111', // Key 1 indicates Petal Maps, and the value must be a POI in Petal Maps.
2:'2222' // Key 2 indicates AutoNavi Map, and the value must be a POI in AutoNavi Map.
} as Record,
- 'originName': 'xx Park in xx City',
+ 'originName': 'xx Park in xx City',
'originLatitude': 31.060844,
'originLongitude': 120.78315,
'originPoiIds': {
@@ -108,44 +108,43 @@ If the **type** field in **startAbilityByType** is set to **navigation**, three
| RoutePlan | The application supports route planning. |
| PlaceSearch | The application supports place search. |
2. Set **scheme**, **host**, **port**, and **path** or **pathStartWith** to match the URIs in Want to distinguish different features.
-
- ```json
- {
- "abilities": [
+ ```json
+ {
+ "abilities": [
+ {
+ "skills": [
{
- "skills": [
+ "uris": [
+ {
+ "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
+ "host": "navigation",
+ "path": "",
+ "linkFeature": "Navigation" // Declare that the application supports navigation.
+ },
+ {
+ "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
+ "host": "routePlan",
+ "path": "",
+ "linkFeature": "RoutePlan" // Declare that the application supports route planning.
+ },
{
- "uris": [
- {
- "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
- "host": "navigation",
- "path": "",
- "linkFeature": "Navigation" // Declare that the application supports navigation.
- },
- {
- "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
- "host": "routePlan",
- "path": "",
- "linkFeature": "RoutePlan" // Declare that the application supports route planning.
- },
- {
- "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
- "host": "search",
- "path": "",
- "linkFeature": "PlaceSearch" // Declare that the application supports place search.
- }
- ]
+ "scheme": "maps", // It is for reference only. Ensure that the declared URI can be started by external systems.
+ "host": "search",
+ "path": "",
+ "linkFeature": "PlaceSearch" // Declare that the application supports place search.
}
]
}
]
- }
- ```
-
+ }
+ ]
+ }
+ ```
+
2. Parse parameters and perform corresponding processing.
```ts
- UIAbility::onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
+ UIAbility.onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void
```
The **want.uri** parameter carries the URI corresponding to **linkFeature** configured by the target application.
@@ -181,7 +180,7 @@ If the **type** field in **startAbilityByType** is set to **navigation**, three
| --------------- | ------ | ---- | -------- |
| destinationName | string | Yes | Name of the destination.|
- The application can develop different style pages based on the features defined in [linkFeature](../quick-start/module-configuration-file.md#skills), such as route planning, navigation, and place search, as well as the received URI and parameters.
+The application can develop different style pages based on the features defined in [linkFeature](../quick-start/module-configuration-file.md#skills), such as route planning, navigation, and place search, as well as the received URI and parameters.
**Sample Code**
diff --git a/en/application-dev/application-models/storage-switch.md b/en/application-dev/application-models/storage-switch.md
index 9a32ebd60f84f7553d906948a1982d7fa82a5869..806f137a7f88401890085c1ba149e05a4ecbd767 100644
--- a/en/application-dev/application-models/storage-switch.md
+++ b/en/application-dev/application-models/storage-switch.md
@@ -1,15 +1,13 @@
# Storage Switching
-| API in the FA Model| Corresponding .d.ts File in the Stage Model| Corresponding API in the Stage Model|
+ | API in the FA Model| Corresponding .d.ts File in the Stage Model| Corresponding API in the Stage Model|
| -------- | -------- | -------- |
-| GetStorageOptions | There is no corresponding API in the stage model.| The stage model uses **Prefereces** to replace **Storage** and has redesigned the input parameters.|
-| SetStorageOptions | There is no corresponding API in the stage model.| The stage model uses **Prefereces** to replace **Storage** and has redesigned the input parameters.|
-| ClearStorageOptions | There is no corresponding API in the stage model.| The stage model uses **Prefereces** to replace **Storage** and has redesigned the input parameters.|
-| DeleteStorageOptions | There is no corresponding API in the stage model.| The stage model uses **Prefereces** to replace **Storage** and has redesigned the input parameters.|
+| GetStorageOptions | There is no corresponding API in the stage model.| The stage model uses **Preferences** to replace **Storage** and has redesigned the input parameters.|
+| SetStorageOptions | There is no corresponding API in the stage model.| The stage model uses **Preferences** to replace **Storage** and has redesigned the input parameters.|
+| ClearStorageOptions | There is no corresponding API in the stage model.| The stage model uses **Preferences** to replace **Storage** and has redesigned the input parameters.|
+| DeleteStorageOptions | There is no corresponding API in the stage model.| The stage model uses **Preferences** to replace **Storage** and has redesigned the input parameters.|
| [static get(options: GetStorageOptions): void;](../reference/apis-arkdata/js-apis-system-storage.md#storageget) | \@ohos.data.preferences.d.ts | [get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void;](../reference/apis-arkdata/js-apis-data-preferences.md#get)
[get(key: string, defValue: ValueType): Promise<ValueType>;](../reference/apis-arkdata/js-apis-data-preferences.md#get-1) |
| [static set(options: SetStorageOptions): void;](../reference/apis-arkdata/js-apis-system-storage.md#storageset) | \@ohos.data.preferences.d.ts | [put(key: string, value: ValueType, callback: AsyncCallback<void>): void;](../reference/apis-arkdata/js-apis-data-preferences.md#put)
[put(key: string, value: ValueType): Promise<void>;](../reference/apis-arkdata/js-apis-data-preferences.md#put-1) |
| [static clear(options?: ClearStorageOptions): void;](../reference/apis-arkdata/js-apis-system-storage.md#storageclear) | \@ohos.data.preferences.d.ts | [clear(callback: AsyncCallback<void>): void;](../reference/apis-arkdata/js-apis-data-preferences.md#clear)
[clear(): Promise<void>;](../reference/apis-arkdata/js-apis-data-preferences.md#clear-1) |
| [static delete(options: DeleteStorageOptions): void;](../reference/apis-arkdata/js-apis-system-storage.md#storagedelete) | \@ohos.data.preferences.d.ts | [delete(key: string, callback: AsyncCallback<void>): void;](../reference/apis-arkdata/js-apis-data-preferences.md#delete)
[delete(key: string): Promise<void>;](../reference/apis-arkdata/js-apis-data-preferences.md#delete-1) |
-
-
\ No newline at end of file
diff --git a/en/application-dev/application-models/thread-model-fa.md b/en/application-dev/application-models/thread-model-fa.md
index e899f6d1fa25234e53a6cbc6868869f98f3759ae..5826fd43abaad7715db4864e3b2ee27756260e18 100644
--- a/en/application-dev/application-models/thread-model-fa.md
+++ b/en/application-dev/application-models/thread-model-fa.md
@@ -24,5 +24,3 @@ Based on the thread model, different services run on different threads. Service
> **NOTE**
>
> The FA model provides an independent thread for each ability. Emitter is mainly used for event synchronization within the ability thread, between a pair of ability threads, or between the ability thread and worker thread.
-
-
\ No newline at end of file
diff --git a/en/application-dev/application-models/thread-model-stage.md b/en/application-dev/application-models/thread-model-stage.md
index 56235db215cd47e6b3d141bbb0aa1ccf7f69d199..d7ba1fcd1dd1540cf3612a46475dcf1720f7de7d 100644
--- a/en/application-dev/application-models/thread-model-stage.md
+++ b/en/application-dev/application-models/thread-model-stage.md
@@ -1,5 +1,7 @@
# Thread Model (Stage Model)
+A thread is the basic unit for the operating system to perform computing and scheduling. It is an execution flow within a [process](./process-model-stage.md) and shares the resources of the process. A process can contain multiple threads.
+
## Thread Type
There are three types of threads in the stage model:
- Main thread
diff --git a/en/application-dev/application-models/uiability-lifecycle.md b/en/application-dev/application-models/uiability-lifecycle.md
index 0b509dfeb87337941aa62d0ae3db27043e40778c..453db49387da20bb09b84576e8d481ceeed5d7ff 100644
--- a/en/application-dev/application-models/uiability-lifecycle.md
+++ b/en/application-dev/application-models/uiability-lifecycle.md
@@ -146,7 +146,7 @@ export default class EntryAbility extends UIAbility {
onWindowStageWillDestroy(windowStage: window.WindowStage) {
// Release the resources obtained through the windowStage object.
- // Unsubscribe from the WindowStage events (having or losing focus, switching to the foreground or background, or becoming interactive or non-interactive in the foreground) in the onWindowStageDestroy() callback.
+ // Unsubscribe from the WindowStage events (having or losing focus, switching to the foreground or background, or becoming interactive or non-interactive in the foreground) in the onWindowStageWillDestroy() callback.
try {
if (this.windowStage) {
this.windowStage.off('windowStageEvent');
diff --git a/en/application-dev/application-models/uiability-startup-adjust.md b/en/application-dev/application-models/uiability-startup-adjust.md
index c41e212a94f421698e7dd0407b8522d550df0602..43fade2f7ffb816b07caaa27a3c9568b10cb8848 100644
--- a/en/application-dev/application-models/uiability-startup-adjust.md
+++ b/en/application-dev/application-models/uiability-startup-adjust.md
@@ -1,8 +1,5 @@
# Switching from Explicit Want Redirection to Linking Redirection
-
-## Overview
-
Since API version 12, it is not recommended that third-party applications start other applications by specifying an ability (implicit Want mode). Instead, the [linking mode](app-startup-overview.md#application-links) is recommended.
This section describes how to switch from explicit Want mode to linking mode.
@@ -48,8 +45,6 @@ This section describes how to switch from explicit Want mode to linking mode.
- If **appLinkingOnly** in **options** is set to **true**, the target application must pass domain name verification (Internet connection required). A unique matching item or an unmatched result will be returned.
- If **appLinkingOnly** in **options** is set to **false**, the system preferentially attempts to start the target application in App Linking mode. If no matching application is found, the system starts the application in Deep Linking mode.
- For details, see [Using App Linking for Application Redirection](app-linking-startup.md).
-
```ts
import { common } from '@kit.AbilityKit';
import OpenLinkOptions from '@ohos.app.ability.OpenLinkOptions';
@@ -69,6 +64,7 @@ This section describes how to switch from explicit Want mode to linking mode.
.margin({ bottom: '12vp' })
.onClick(() => {
let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
+ // When using startAbility to explicitly start other UIAbilities, the openLink API is recommended.
// let want: Want = {
// bundleName: "com.test.example",
// moduleName: "entry",
@@ -145,12 +141,10 @@ This section describes how to switch from explicit Want mode to linking mode.
}
```
-2. Call [openLink](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextopenlink12) to trigger redirection. The redirected-to link and [options](../reference/apis-ability-kit/js-apis-app-ability-openLinkOptions.md) must be passed in, but the bundle name, module name, and ability name are not required. The system matches the application that meets the skills configuration based on the link. **AbilityResult** is transferred to the callback function through input parameters and returned to the caller application when the ability is terminated. The startup success or failure result is returned through a promise.
+2. Call [openLink](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextopenlink12) to trigger redirection. The redirected-to link and [options](../reference/apis-ability-kit/js-apis-app-ability-openLinkOptions.md) must be passed in, but the bundle name, module name, and ability name are not required. The system matches the application that meets the skills configuration based on the link. **AbilityResult** is transferred to the callback function through input parameters and returned to the caller application when the ability is terminated. The startup success or failure result is returned through a promise.
- If **appLinkingOnly** in **options** is set to **true**, the target application must pass domain name verification (Internet connection required). A unique matching item or an unmatched result will be returned.
- If **appLinkingOnly** in **options** is set to **false**, the system preferentially attempts to start the target application in App Linking mode. If no matching application is found, the system starts the application in Deep Linking mode.
- For details, see [Using App Linking for Application Redirection](app-linking-startup.md).
-
```ts
import { common } from '@kit.AbilityKit';
import OpenLinkOptions from '@ohos.app.ability.OpenLinkOptions';
@@ -170,6 +164,7 @@ This section describes how to switch from explicit Want mode to linking mode.
.margin({ bottom: '12vp' })
.onClick(() => {
let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
+ // When using startAbility to explicitly start other UIAbilities, the openLink API is recommended.
// let want: Want = {
// bundleName: "com.test.example",
// moduleName: "entry",
diff --git a/en/application-dev/application-models/uiserviceextension-sys.md b/en/application-dev/application-models/uiserviceextension-sys.md
index 726c76bb3b2ebbc939744f4c357d018c90a7e28b..2e11ac17059809df92a7f983e4531f46d77ec8ef 100644
--- a/en/application-dev/application-models/uiserviceextension-sys.md
+++ b/en/application-dev/application-models/uiserviceextension-sys.md
@@ -7,8 +7,8 @@
In this document, the component that starts or connects to a UIServiceExtensionAbility is called the client, and the UIServiceExtensionAbility is called the server.
An application can use a UIServiceExtensionAbility in two modes:
-- Call [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability13) in the [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md), [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md), or [ServiceExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-serviceExtensionContext-sys.md) class to start a UIServiceExtensionAbility.
-- Call [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability13) in the [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) or [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) class to connect to a UIServiceExtensionAbility.
+- Call [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability14) in the [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md), [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md), or [ServiceExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-serviceExtensionContext-sys.md) class to start a UIServiceExtensionAbility.
+- Call [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14) in the [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) or [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) class to connect to a UIServiceExtensionAbility.
Note the following:
@@ -37,7 +37,7 @@ The UIServiceExtensionAbility provides the following lifecycle callbacks: [onCre
- **onRequest**
- This callback is invoked when another component calls [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability13) to start a UIServiceExtensionAbility. After this callback is invoked, the UIServiceExtensionAbility is started and runs in the foreground. This callback is invoked each time [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability13) is called.
+ This callback is invoked when another component calls [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability14) to start a UIServiceExtensionAbility. After This callback is invoked, the UIServiceExtensionAbility is started and runs in the foreground. This callback is invoked each time [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability14) is called.
- **onWindowWillCreate**
@@ -51,7 +51,7 @@ The UIServiceExtensionAbility provides the following lifecycle callbacks: [onCre
- **onConnect**
- This callback is invoked when another component calls [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability13) to connect to a UIServiceExtensionAbility. In this callback, a remote proxy object, namely, [UIServiceHostProxy](../reference/apis-ability-kit/js-apis-inner-application-uiservicehostproxy-sys.md), is returned, through which the server communicates with the client. For the same client, if the values of **DeviceId**, **BundleName**, **ModuleName**, and **AbilityName** in the want object and the callback object are the same, [onConnect()](../reference/apis-ability-kit/js-apis-app-ability-serviceExtensionAbility-sys.md#serviceextensionabilityonconnect) is invoked only for the first connection. If any of them is different, [onConnect()](../reference/apis-ability-kit/js-apis-app-ability-serviceExtensionAbility-sys.md#serviceextensionabilityonconnect) is invoked again.
+ This callback is invoked when another component calls [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14) to connect to a UIServiceExtensionAbility. In this callback, a remote proxy object, namely, [UIServiceHostProxy](../reference/apis-ability-kit/js-apis-inner-application-uiservicehostproxy-sys.md), is returned, through which the server communicates with the client. For the same client, if the values of **DeviceId**, **BundleName**, **ModuleName**, and **AbilityName** in the want object and the callback object are the same, [onConnect()](../reference/apis-ability-kit/js-apis-app-ability-serviceExtensionAbility-sys.md#serviceextensionabilityonconnect) is invoked only for the first connection. If any of them is different, [onConnect()](../reference/apis-ability-kit/js-apis-app-ability-serviceExtensionAbility-sys.md#serviceextensionabilityonconnect) is invoked again.
- **onData**
@@ -59,7 +59,7 @@ The UIServiceExtensionAbility provides the following lifecycle callbacks: [onCre
- **onDisconnect**
- This callback is invoked when the connection is interrupted, which occurs when the client exits or [disconnectServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectuiserviceextensionability13) is called.
+ This callback is invoked when the connection is interrupted, which occurs when the client exits or [disconnectServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectuiserviceextensionability14) is called.
- **onDestroy**
@@ -79,7 +79,7 @@ Only system applications can implement a UIServiceExtensionAbility. You must mak
To manually create a UIServiceExtensionAbility in a project in DevEco Studio, perform the following steps:
-1. In the **ets** directory of a module in the project, right-click and choose **New > Directory** to create a directory named **UIServiceExt**.
+1. In the **ets** directory of the target module, right-click and choose **New > Directory** to create a directory named [UIServiceExtension](../reference/apis-ability-kit/js-apis-app-ability-uiServiceExtensionAbility-sys.md).
2. In the **UIServiceExt** directory, right-click and choose **New > ArkTS File** to create a file named **UIServiceExt.ets**.
@@ -171,7 +171,7 @@ To manually create a UIServiceExtensionAbility in a project in DevEco Studio, pe
### Starting a UIServiceExtensionAbility
-An application calls [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability13) to start a UIServiceExtensionAbility. The [onRequest()](../reference/apis-ability-kit/js-apis-app-ability-uiServiceExtensionAbility-sys.md#uiserviceextensionabilityonrequest) callback is invoked, through which the background service receives the **Want** object passed by the caller. Once the UIServiceExtensionAbility is started, its lifecycle is independent of the client. In other words, even if the client is destroyed, the background service remains alive. However, the service is destroyed if the window fails to be created or is destroyed. Therefore, the background service must be stopped by calling [terminateSelf()](../reference/apis-ability-kit/js-apis-inner-application-uiserviceExtensionContext-sys.md#uiserviceextensioncontextterminateself13) of [UIServiceExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiserviceExtensionContext-sys.md) when its work is complete.
+An application calls [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability14) to start a UIServiceExtensionAbility. The [onRequest()](../reference/apis-ability-kit/js-apis-app-ability-uiServiceExtensionAbility-sys.md#uiserviceextensionabilityonrequest) callback is invoked, through which the background service receives the **Want** object passed by the caller. Once the UIServiceExtensionAbility is started, its lifecycle is independent of the client. In other words, even if the client is destroyed, the background service remains alive. However, the service is destroyed if the window fails to be created or is destroyed. Therefore, the background service must be stopped by calling [terminateSelf()](../reference/apis-ability-kit/js-apis-inner-application-uiserviceExtensionContext-sys.md#uiserviceextensioncontextterminateself13) of [UIServiceExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiserviceExtensionContext-sys.md) when its work is complete.
Start a new UIServiceExtensionAbility in a system application. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability).
@@ -214,11 +214,11 @@ struct Index {
### Connecting to a UIServiceExtensionAbility
-An application can use [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability13) to connect to a service (specified in the [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md) object). The [onConnect()](../reference/apis-ability-kit/js-apis-app-ability-serviceExtensionAbility-sys.md#serviceextensionabilityonconnect) callback is invoked, through which the service receives the [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md) object passed by the caller. In this way, a connection is established.
+An application can use [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14) to connect to a service (specified in the [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md) object). The [onConnect()](../reference/apis-ability-kit/js-apis-app-ability-serviceExtensionAbility-sys.md#serviceextensionabilityonconnect) callback is invoked, through which the service receives the [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md) object passed by the caller. In this way, a connection is established.
-When the client calls [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability13) to connect to the server, the client receives a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object returned by the server and saves it. Through this proxy object, the client sends data to the server, and disconnects from the server by calling [disconnectServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectuiserviceextensionability13).
+When the client calls [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14) to connect to the server, the client receives a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object returned by the server and saves it. Through this proxy object, the client sends data to the server, and disconnects from the server by calling [disconnectServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectuiserviceextensionability14).
-- Call [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability13) to connect to a UIServiceExtensionAbility. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability).
+- Call [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14) to connect to a UIServiceExtensionAbility. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability).
```ts
import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
@@ -262,7 +262,7 @@ When the client calls [connectUIServiceExtensionAbility()](../reference/apis-abi
}
```
-- Call [disconnectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectuiserviceextensionability13) to disconnect from a UIServiceExtensionAbility.
+- Call [disconnectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectuiserviceextensionability14) to disconnect from a UIServiceExtensionAbility.
```ts
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
@@ -297,7 +297,7 @@ When the client calls [connectUIServiceExtensionAbility()](../reference/apis-abi
After a UIServiceExtensionAbility is started, the following operations are possible:
-1. The client calls [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md#uiextensioncontextconnectuiserviceextensionability13) to obtain a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object, through which it can send data to the server.
+1. The client calls [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md#uiextensioncontextconnectuiserviceextensionability14) to obtain a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object, through which it can send data to the server.
2. The server obtains a [UIServiceHostProxy](../reference/apis-ability-kit/js-apis-inner-application-uiservicehostproxy-sys.md) object through the [onConnect()](../reference/apis-ability-kit/js-apis-app-ability-uiServiceExtensionAbility-sys.md#uiserviceextensionabilityonconnect) callback and sends data to the client through this proxy.
@@ -306,7 +306,7 @@ After a UIServiceExtensionAbility is started, the following operations are possi
### Communication Between the Client and Server
- Data transmission on the client
- The client connects to the server through [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md#uiextensioncontextconnectuiserviceextensionability13) and obtains a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object. The client calls [sendData()](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md#uiserviceproxysenddata) of the proxy object to send data to the server. The server receives data through the [onData()](../reference/apis-ability-kit/js-apis-app-ability-uiServiceExtensionAbility-sys.md#uiserviceextensionabilityondata) callback.
+ The client connects to the server through [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md#uiextensioncontextconnectuiserviceextensionability14) and obtains a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object. The client calls [sendData()](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md#uiserviceproxysenddata) of the proxy object to send data to the server. The server receives data through the [onData()](../reference/apis-ability-kit/js-apis-app-ability-uiServiceExtensionAbility-sys.md#uiserviceextensionabilityondata) callback.
```ts
import { common, Want} from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
diff --git a/en/application-dev/application-models/uiserviceextension.md b/en/application-dev/application-models/uiserviceextension.md
index 19f25a7fc5f8e6f60f62aa41bf21ca944d08aa39..eb8ab998d06b3291b3d71e9f0842edd3f87c7fd4 100644
--- a/en/application-dev/application-models/uiserviceextension.md
+++ b/en/application-dev/application-models/uiserviceextension.md
@@ -7,8 +7,8 @@ UIServiceExtensionAbility is an [ExtensionAbility](../reference/apis-ability-kit
In this document, the component that starts or connects to a UIServiceExtensionAbility is called the client, and the UIServiceExtensionAbility is called the server.
An application can use a UIServiceExtensionAbility in two modes:
-- Call [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability13) in the [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) class to start a UIServiceExtensionAbility.
-- Call [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability13) in the [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) or [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) class to connect to a UIServiceExtensionAbility.
+- Call [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability14) in the [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) class to start a UIServiceExtensionAbility.
+- Call [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14) in the [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) or [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) class to connect to a UIServiceExtensionAbility.
> **NOTE**
@@ -22,7 +22,7 @@ An application can use a UIServiceExtensionAbility in two modes:
## Starting a UIServiceExtensionAbility
-An application (client) calls [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability13) to start a UIServiceExtensionAbility. Once the UIServiceExtensionAbility is started, its lifecycle is independent of the client. Even if the client is destroyed, the background service remains alive. However, the service is destroyed if the window fails to be created or is destroyed.
+An application (client) calls [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability14) to start a UIServiceExtensionAbility. Once the UIServiceExtensionAbility is started, its lifecycle is independent of the client. Even if the client is destroyed, the background service remains alive. However, the service is destroyed if the window fails to be created or is destroyed.
For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability).
@@ -65,7 +65,7 @@ struct Index {
## Connecting to a UIServiceExtensionAbility
-The client connects to the server through [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability13) and obtains a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object. The client calls [sendData()](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md#uiserviceproxysenddata) of the proxy object to send data to the server. The server calls the system API **onData()** of the UIServiceExtensionAbility class to receive data from the client.
+The client connects to the server through [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14) and obtains a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object. The client calls [sendData()](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md#uiserviceproxysenddata) of the proxy object to send data to the server. The server calls the system API **onData()** of the UIServiceExtensionAbility class to receive data from the client.
```ts
diff --git a/en/application-dev/application-test/Readme-EN.md b/en/application-dev/application-test/Readme-EN.md
index e7f7280007a0540f9eb12178adfad4359ec08989..4364e57f6ca6fe8e433d893d157db6c2266250fa 100644
--- a/en/application-dev/application-test/Readme-EN.md
+++ b/en/application-dev/application-test/Readme-EN.md
@@ -1,4 +1,4 @@
-# Test Kit (Application Test Service)
+# Test Kit
- [arkXtest User Guide](arkxtest-guidelines.md)
- [SmartPerf User Guide](smartperf-guidelines.md)
diff --git a/en/application-dev/application-test/arkxtest-guidelines.md b/en/application-dev/application-test/arkxtest-guidelines.md
index 1134dff3e3e4e55785a9c6cd5380be054f04c79c..6b6687d521c77c7dadcf4a1266b90685991a3e86 100644
--- a/en/application-dev/application-test/arkxtest-guidelines.md
+++ b/en/application-dev/application-test/arkxtest-guidelines.md
@@ -203,7 +203,7 @@ The table below lists the keywords in **aa** test commands.
| Keyword | Abbreviation| Description | Example |
| ------------- | ------------ | -------------------------------------- | ---------------------------------- |
-| --bundleName | -b | Application bundle name. | - b com.test.example |
+| --bundleName | -b | Application bundle name. | - b com.test.example |
| --packageName | -p | Application module name, which is applicable to applications developed in the FA model. | - p com.test.example.entry |
| --moduleName | -m | Application module name, which is applicable to applications developed in the stage model. | -m entry |
| NA | -s | \ pair.| - s unittest /ets/testrunner/OpenHarmonyTestRunner |
@@ -213,7 +213,7 @@ The framework supports multiple test case execution modes, which are triggered b
| Name | Description | Value | Example |
| ------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------- |
| unittest | **OpenHarmonyTestRunner** object used for test case execution. | **OpenHarmonyTestRunner** or custom runner name. | - s unittest OpenHarmonyTestRunner |
-| class | Test suite or test case to be executed. | {describeName}#{itName}, {describeName} | -s class attributeTest#testAttributeIt |
+| class | Test suite or test case to be executed. | {describeName}#{itName}, {describeName} | -s class attributeTest#testAttributeIt |
| notClass | Test suite or test case that does not need to be executed. | {describeName}#{itName}, {describeName} | -s notClass attributeTest#testAttributeIt |
| itName | Test case to be executed. | {itName} | -s itName testAttributeIt |
| timeout | Timeout interval for executing a test case. | Positive integer (unit: ms). If no value is set, the default value **5000** is used. | -s timeout 15000 |
@@ -421,7 +421,7 @@ The following describes the fields in the recording data:
"MAX_VEL": "40000", // Maximum velocity.
"VELO": "0.000000", // Hands-off velocity.
"W1_BOUNDS": "{"bottom":361,"left":37,"right":118,"top":280}", // Starting component bounds.
- "W1_HIER": "ROOT,3,0,0,0,0,0,0,0,0,0,0,5,0,0,0,0,0,0,0,0", // Starting component hierarchy.
+ "W1_HIER": "ROOT,3,0,0,0,0,0,0,0,0,5,0,0,0,0,0,0,0", // Starting component hierarchy.
"W1_ID": "", // ID of the starting component.
"W1_Text": "", // Text of the starting component.
"W1_Type": "Image", // Type of the starting component.
@@ -443,18 +443,19 @@ The following describes the fields in the recording data:
### Injecting Simulated UI Operations
-| Command | Mandatory| Description |
+| Command | Mandatory| Description |
|------|------|-----------------|
| help | Yes | Displays help information about the uiInput commands.|
-| click | Yes | Simulates a click event. |
-| doubleClick | Yes | Simulates a double-click event. |
-| longClick | Yes | Simulates a long-click event. |
-| fling | Yes | Simulates a fling event. |
-| swipe | Yes | Simulates a swipe event. |
-| drag | Yes | Simulates a drag event. |
+| click | Yes | Simulates a click event. |
+| doubleClick | Yes | Simulates a double-click event. |
+| longClick | Yes | Simulates a long-click event. |
+| fling | Yes | Simulates a fling event. |
+| swipe | Yes | Simulates a swipe event. |
+| drag | Yes | Simulates a drag event. |
| dircFling | Yes | Simulates a directional fling event. |
-| inputText | Yes | Simulates a text input event. |
-| keyEvent | Yes | Simulates a physical key event (such as pressing a keyboard key, pressing the power key, returning to the previous page, or returning to the home screen) or a key combination. |
+| inputText | Yes | Simulates text input in a text box at specified coordinates. |
+| text | Yes | Simulates text input in a text box at the focused position without specifying coordinates. |
+| keyEvent | Yes | Simulates a physical key event (such as pressing a keyboard key, pressing the power key, returning to the previous page, or returning to the home screen) or a key combination. |
#### Example of Running the click/doubleClick/longClick Commands
@@ -477,30 +478,30 @@ hdc shell uitest uiInput longClick 100 100
#### Example of Running the uiInput fling Command
-| Parameter | Mandatory | Description |
+| Parameter | Mandatory | Description |
|------|------------------|-----------------|
-| from_x | Yes | The x-coordinate of the start point.|
-| from_y | Yes | The y-coordinate of the start point.|
+| from_x | Yes | The x-coordinate of the start point.|
+| from_y | Yes | The y-coordinate of the start point.|
| to_x | Yes | The x-coordinate of the stop point.|
| to_y | Yes | The y-coordinate of the stop point.|
-| swipeVelocityPps_ | No | Swipe speed, in px/s. Value range: 200 to 40000.
The default value is 600.|
-| stepLength_ | No| The step length. The default value is the sliding distance divided by 50.
To achieve better simulation effect, you are advised to use the default values. |
+| swipeVelocityPps_ | No | Swipe speed, in px/s. The value ranges from 200 to 40000.
The default value is **600**.|
+| stepLength_ | No| Step length. The default value is the swipe distance divided by 50.
To achieve better simulation effect, you are advised to use the default value. |
```shell
# Execute the fling event. The default value of stepLength_ is used.
hdc shell uitest uiInput fling 10 10 200 200 500
-```
+```
#### Example of Running the uiInput swipe/drag Command
-| Parameter | Mandatory | Description |
+| Parameter | Mandatory | Description |
|------|------------------|-----------------|
-| from_x | Yes | The x-coordinate of the start point.|
-| from_y | Yes | The y-coordinate of the start point.|
+| from_x | Yes | The x-coordinate of the start point.|
+| from_y | Yes | The y-coordinate of the start point.|
| to_x | Yes | The x-coordinate of the stop point.|
| to_y | Yes | The y-coordinate of the stop point.|
-| swipeVelocityPps_ | No | Swipe speed, in px/s. Value range: 200 to 40000.
The default value is 600.|
+| swipeVelocityPps_ | No | Swipe speed, in px/s. Value range: 200 to 40000.
The default value is 600.|
```shell
# Execute the swipe event.
@@ -514,9 +515,9 @@ hdc shell uitest uiInput drag 10 10 100 100 500
| Parameter | Mandatory | Description|
|-------------------|-------------|----------|
-| direction | No| Fling direction, which can be **0**, **1**, **2**, or **3**. The default value is **0**.
The value **0** indicates leftward fling, **1** indicates rightward fling, **2** indicates upward fling, and **3** indicates downward fling. |
-| swipeVelocityPps_ | No| Swipe speed, in px/s. Value range: 200 to 40000.
The default value is 600. |
-| stepLength | No | The step length.
The default value is the sliding distance divided by 50. To achieve better simulation effect, you are advised to use the default values.|
+| direction | No| Fling direction, which can be **0**, **1**, **2**, or **3**. The default value is **0**.
The value **0** indicates leftward fling, **1** indicates rightward fling, **2** indicates upward fling, and **3** indicates downward fling. |
+| swipeVelocityPps_ | No| Swipe speed, in px/s. Value range: 200 to 40000.
The default value is 600. |
+| stepLength | No | Step length.
The default value is the swipe distance divided by 50. To achieve better simulation effect, you are advised to use the default value.|
```shell
# Execute the leftward fling event.
@@ -531,9 +532,9 @@ hdc shell uitest uiInput dircFling 3
#### Example of Running the uiInput inputText Command
-| Parameter | Mandatory | Description|
+| Parameter | Mandatory | Description|
|------|------------------|----------|
-| point_x | Yes | The x-coordinate of the input box.|
+| point_x | Yes | The x-coordinate of the input box.|
| point_y | Yes | The y-coordinate of the input box.|
| text | Yes | Text in the input box. |
@@ -542,11 +543,22 @@ hdc shell uitest uiInput dircFling 3
hdc shell uitest uiInput inputText 100 100 hello
```
+#### Example of Running the uiInput text Command
+
+| Parameter | Mandatory | Description|
+|------|------------------|----------|
+| text | Yes | Text in the input box. |
+
+```shell
+# Execute the text input in the text box at the focused position. If the current focused position does not support text input, no effect is displayed.
+hdc shell uitest uiInput text hello
+```
+
#### Example of Running the uiInput keyEvent Command
-| Parameter | Mandatory | Description|
+| Parameter | Mandatory | Description|
|------|------|----------|
-| keyID1 | Yes | ID of a physical key, which can be **KeyCode**, **Back**, **Home**, or **Power**.
When the value is set to **Back**, **Home**, or **Power**, the combination keys are not supported.|
+| keyID1 | Yes | ID of a physical key, which can be **KeyCode**, **Back**, **Home**, or **Power**.
When the value is set to **Back**, **Home**, or **Power**, the combination keys are not supported.|
| keyID2 | No | ID of a physical key.|
| keyID3 | No | ID of a physical key.|
@@ -580,7 +592,7 @@ hdc shell uitest start-daemon
>
> Only the test HAP started by the **aa test** ability can call the ability of the UiTest.
>
-> The [Ability Privilege Level (APL)](../security/AccessToken/app-permission-mgmt-overview.md#basic-concepts-in-the-permission-mechanism) of the test HAP must be **system_basic** or **normal**.
+> The [Ability Privilege Level (APL)](../security/AccessToken/app-permission-mgmt-overview.md#basic-concepts-in-the-permission-mechanism) of the test HAP must be **system_basic** or **normal**.
## Examples
@@ -645,7 +657,7 @@ For details about how to simulate a window size adjustment and direction specifi
### FAQs About Unit Test Cases
-1. The logs in the test case are printed after the test case result
+**1. What should I do if logs in the test case are printed after the test case result?**
**Problem**
@@ -659,7 +671,7 @@ More than one asynchronous API is called in the test case.
In principle, logs
If more than one asynchronous API is called, you are advised to encapsulate the API invoking into the promise mode.
-**Error "fail to start ability" is reported during test case execution**
+**2. What should I do if the message "error: fail to start ability" is reported during test case execution?**
**Problem**
@@ -673,7 +685,7 @@ An error occurs during the packaging of the test package, and the test framework
Check whether the test package contains the **OpenHarmonyTestRunner.abc** file. If the file does not exist, rebuild and pack the file and perform the test again.
-Test case execution timeout
+**3. What should I do if a timeout error is reported during case execution?**
**Problem**
@@ -681,7 +693,7 @@ After the test case execution is complete, the console displays the error messag
**Possible Causes**
-1. The test case is executed through an asynchronous interface, but the **done** function is not executed during the execution. As a result, the test case execution does not end until it times out.
+1. The test case is executed through an asynchronous API, but the **done** function is not executed during the execution. As a result, the test case execution does not end until it times out.
2. The time taken for API invocation is longer than the timeout interval set for test case execution.
@@ -696,7 +708,7 @@ After the test case execution is complete, the console displays the error messag
3. Check the code logic and assertion result of the test case and make sure that the assertion is passed.
### FAQs About UI Test Cases
-**The failure log contains "Get windows failed/GetRootByWindow failed"**
+**1. What should I do if the failure log contains "Get windows failed/GetRootByWindow failed"?**
**Problem**
@@ -714,7 +726,7 @@ Run the following command, restart the device, and execute the test case again:
hdc shell param set persist.ace.testmode.enabled 1
```
-**The failure log contains "uitest-api does not allow calling concurrently"**
+**2. What should I do if the failure log contains "uitest-api does not allow calling concurrently"?**
**Problem**
@@ -732,7 +744,7 @@ The UI test case fails to be executed. The HiLog file contains the error message
2. Do not execute UI test cases in multiple processes.
-The failure log contains "does not exist on current UI! Check if the UI has changed after you got the widget object".
+**3. What should I do if the failure log contains "does not exist on current UI! Check if the UI has changed after you got the widget object"?**
**Problem**
diff --git a/en/application-dev/application-test/smartperf-guidelines.md b/en/application-dev/application-test/smartperf-guidelines.md
index 958ff96098f078721176d544292b6fa0cf027cd6..87397233cf85535de299b8f20aa091866c459ba4 100644
--- a/en/application-dev/application-test/smartperf-guidelines.md
+++ b/en/application-dev/application-test/smartperf-guidelines.md
@@ -4,9 +4,9 @@
SmartPerf Device is a reliable, easy-to-use performance and power consumption test tool. In this tool, you can monitor the performance and power consumption of your application and device with quantitative indicators, such as FPS, CPU, GPU, RAM, and Temp.
-Targeted at devices with or without screens, SmartPerf Device provides two modes: Device-hap and Device-daemon. Device-hap is applicable to devices with screens and provides a visualized, intuitive UI that simplifies your operations. You can start and pause a test with a floating window, view performance data in real time, and save the test results for further analysis. Device-daemon is applicable to devices with and without screens and works with shell commands.
+Targeted at devices with or without screens, SmartPerf Device provides two modes: Device-hap and Device-daemon. Device-hap is applicable to devices with screens and provides a visualized, intuitive UI that simplifies your operations. You can start and pause a test with a floating window, view performance data in real time, and save the test results for further analysis. Device-daemon is applicable to devices with and without screens and works with shell commands.
-### The following are the available indicators:
+### Indicators
- CPU: The tool reads the frequencies and usage of CPU cores on the test device on a per second basis to measure the CPU usage of the target application. Sustained high CPU may lead to overheating.
- GPU: The tool reads the GPU frequency and load information of the test device on a per second basis to measure the GPU usage of the target application. High GPU usage can lead to performance drops and application slowdowns.
@@ -17,20 +17,19 @@ SmartPerf Device is a reliable, easy-to-use performance and power consumption te
## Principles
-The figure below demonstrates the main functions of SmartPerf Device. Set data collection items and parameters on Device-hap, start the application, and then send data requests for KPIs (such as FPS, RAM, and Trace) from Device-hap to Device-daemon through messages. Device-daemon collects, persists, and analyzes data as requested, and then sends the data to Device-hap for display.
+The figure below demonstrates the main functions of SmartPerf Device. Set data collection items and parameters on Device-hap, start the application, and then send data requests for KPIs (such as FPS, RAM, and Trace) from Device-hap to Device-daemon through messages. Device-daemon collects, persists, and analyzes data as requested, and then sends the data to Device-hap for display.
## Constraints
-1. Device-daemon and Device-hap are pre-installed since API version 9.
+1. Device-daemon and Device-hap are pre-installed since API version 9.
-2. Device-daemon must be connected to a hardware device, and Device-hap can only be used on devices with a screen.
+2. Device-daemon must be connected to a hardware device, and Device-hap can only be used on devices with a screen.
-3. Before using the Device-Daemon, configure the [HDC environment](https://gitee.com/openharmony/developtools_hdc).
-
-
+3. Before using Device-Daemon, configure the [hdc environment](https://gitee.com/openharmony/developtools_hdc).
+
## SmartPerf Device-hap
The RK3568 development board is used as an example below.
@@ -47,7 +46,7 @@ Start SmartPerf Device-hap. On the home screen, click **Select an app**.
After the target application is selected, return to the start page and set the test indicators. You can also change the test name (which includes the name of the target application and the test time and will be displayed in the report), and specify whether to capture traces and whether to enable the screenshot feature. When you are done, click the **Start** button at the bottom.
-### Using the Floating Window to Manage Data Collection.
+### Using the Floating Window to Manage Data Collection
To start collection, touch **Start** in the floating window. To pause, touch the timer in the floating window. To resume, touch the timer again. To view the collected data in real time, double-touch the timer. To stop, touch and hold the timer.
You can drag the floating window to anywhere you like.
@@ -60,22 +59,19 @@ Click **Report** to access the report list. Touch a report to view its details.
-
-
## SmartPerf Device-daemon
-
### Collection Prerequisites
-#### Switch to shell.
+#### Switching to Shell
```
C:\Users\issusser>hdc shell
#
```
-#### Start and view the daemon process.
+#### Starting and Viewing the daemon Process
```
C:\Users\issusser>hdc shell
@@ -88,9 +84,7 @@ Click **Report** to access the report list. Touch a report to view its details.
#
```
-#### View the help information.
-
-
+#### Viewing the Help Information
```
# SP_daemon --help
@@ -151,7 +145,6 @@ Click **Report** to access the report list. Touch a report to view its details.
command exec finished!
#
```
-
### Basic Collection
@@ -164,14 +157,13 @@ Click **Report** to access the report list. Touch a report to view its details.
| -c |No| Collects the CPU frequency and usage.
When the application bundle name is set, the system and application CPU information is collected.
Otherwise, only the system CPU information is collected. |
| -g |No| Collects the GPU frequency and load information. |
| -f |No| Collects the screen refresh rate and frame rate of the target application. The application bundle name must be specified. |
-| -t |No| Collects the temperature of the GPU and system chip. |
+| -t |No| Collects the temperature of GPU and system chip. |
| -r |No| Collects the memory.
When the application bundle name is set, the system and application memory information is obtained.
Otherwise, only the system memory information is obtained. |
-| -snapshot |No| Takes screenshots. |
+| -snapshot |No| Takes a screenshot. |
| -net |No| Collects the network speed. |
| -VIEW |No| Sets the view layer. You must obtain the layer name first. |
| -d |No| Collects the DDR data. |
| -sections|No| Sets segment-based collection. |
-
##### Samples
@@ -180,43 +172,51 @@ Click **Report** to access the report list. Touch a report to view its details.
```
# SP_daemon -N 2 -c
- order:0 timestamp=1503078645909
- order:1 cpu0Frequency=1992000
- order:2 cpu0Usage=34.042553
- order:3 cpu0idleUsage=65.957447
- order:4 cpu0ioWaitUsage=0.000000
- order:5 cpu0irqUsage=0.000000
- order:6 cpu0niceUsage=0.000000
- order:7 cpu0softIrqUsage=0.000000
- order:8 cpu0systemUsage=15.957447
- order:9 cpu0userUsage=18.085106
- order:10 cpu1Frequency=1992000
- order:11 cpu1Usage=43.877551
- order:12 cpu1idleUsage=56.122449
- order:13 cpu1ioWaitUsage=0.000000
- order:14 cpu1irqUsage=0.000000
- order:15 cpu1niceUsage=0.000000
- order:16 cpu1softIrqUsage=0.000000
- order:17 cpu1systemUsage=17.346939
- order:18 cpu1userUsage=26.530612
- order:19 cpu2Frequency=1992000
- order:20 cpu2Usage=38.043478
- order:21 cpu2idleUsage=61.956522
- order:22 cpu2ioWaitUsage=0.000000
- order:23 cpu2irqUsage=0.000000
- order:24 cpu2niceUsage=0.000000
- order:25 cpu2softIrqUsage=0.000000
- order:26 cpu2systemUsage=11.956522
- order:27 cpu2userUsage=26.086957
- order:28 cpu3Frequency=1992000
- order:29 cpu3Usage=68.421053
- order:30 cpu3idleUsage=31.578947
- order:31 cpu3ioWaitUsage=0.000000
- order:32 cpu3irqUsage=0.000000
- order:33 cpu3niceUsage=0.000000
- order:34 cpu3softIrqUsage=0.000000
- order:35 cpu3systemUsage=13.684211
- order:36 cpu3userUsage=54.736842
+ order:0 timestamp=1501839064260
+ order:1 TotalcpuUsage=0.502513
+ order:2 TotalcpuidleUsage=99.497487
+ order:3 TotalcpuioWaitUsage=0.000000
+ order:4 TotalcpuirqUsage=0.000000
+ order:5 TotalcpuniceUsage=0.000000
+ order:6 TotalcpusoftIrqUsage=0.000000
+ order:7 TotalcpusystemUsage=0.251256
+ order:8 TotalcpuuserUsage=0.251256
+ order:9 cpu0Frequency=1992000
+ order:10 cpu0Usage=1.000000
+ order:11 cpu0idleUsage=99.000000
+ order:12 cpu0ioWaitUsage=0.000000
+ order:13 cpu0irqUsage=0.000000
+ order:14 cpu0niceUsage=0.000000
+ order:15 cpu0softIrqUsage=0.000000
+ order:16 cpu0systemUsage=0.000000
+ order:17 cpu0userUsage=1.000000
+ order:18 cpu1Frequency=1992000
+ order:19 cpu1Usage=0.000000
+ order:20 cpu1idleUsage=100.000000
+ order:21 cpu1ioWaitUsage=0.000000
+ order:22 cpu1irqUsage=0.000000
+ order:23 cpu1niceUsage=0.000000
+ order:24 cpu1softIrqUsage=0.000000
+ order:25 cpu1systemUsage=0.000000
+ order:26 cpu1userUsage=0.000000
+ order:27 cpu2Frequency=1992000
+ order:28 cpu2Usage=1.000000
+ order:29 cpu2idleUsage=99.000000
+ order:30 cpu2ioWaitUsage=0.000000
+ order:31 cpu2irqUsage=0.000000
+ order:32 cpu2niceUsage=0.000000
+ order:33 cpu2softIrqUsage=0.000000
+ order:34 cpu2systemUsage=1.000000
+ order:35 cpu2userUsage=0.000000
+ order:36 cpu3Frequency=1992000
+ order:37 cpu3Usage=0.000000
+ order:38 cpu3idleUsage=100.000000
+ order:39 cpu3ioWaitUsage=0.000000
+ order:40 cpu3irqUsage=0.000000
+ order:41 cpu3niceUsage=0.000000
+ order:42 cpu3softIrqUsage=0.000000
+ order:43 cpu3systemUsage=0.000000
+ order:44 cpu3userUsage=0.000000
...
@@ -227,56 +227,62 @@ Click **Report** to access the report list. Touch a report to view its details.
- Collect twice the frequency and usage of CPU cores and CPU usage and load of processes.
```
- # SP_daemon -N 2 -PKG com.ohos.settings -c
-
-
-
- order:0 timestamp=1503078694916
- order:1 ProcAppName=com.ohos.settings
- order:2 ProcCpuLoad=0
- order:3 ProcCpuUsage=0
- order:4 ProcId=0
- order:5 ProcSCpuUsage=0
- order:6 ProcUCpuUsage=0
- order:7 cpu0Frequency=1992000
- order:8 cpu0Usage=31.868132
- order:9 cpu0idleUsage=68.131868
- order:10 cpu0ioWaitUsage=0.000000
- order:11 cpu0irqUsage=0.000000
- order:12 cpu0niceUsage=0.000000
- order:13 cpu0softIrqUsage=0.000000
- order:14 cpu0systemUsage=15.384615
- order:15 cpu0userUsage=16.483516
- order:16 cpu1Frequency=1992000
- order:17 cpu1Usage=44.791667
- order:18 cpu1idleUsage=55.208333
- order:19 cpu1ioWaitUsage=0.000000
- order:20 cpu1irqUsage=0.000000
- order:21 cpu1niceUsage=0.000000
- order:22 cpu1softIrqUsage=0.000000
- order:23 cpu1systemUsage=13.541667
- order:24 cpu1userUsage=31.250000
- order:25 cpu2Frequency=1992000
- order:26 cpu2Usage=37.894737
- order:27 cpu2idleUsage=62.105263
- order:28 cpu2ioWaitUsage=0.000000
- order:29 cpu2irqUsage=0.000000
- order:30 cpu2niceUsage=0.000000
- order:31 cpu2softIrqUsage=1.052632
- order:32 cpu2systemUsage=13.684211
- order:33 cpu2userUsage=23.157895
- order:34 cpu3Frequency=1992000
- order:35 cpu3Usage=81.632653
- order:36 cpu3idleUsage=18.367347
- order:37 cpu3ioWaitUsage=0.000000
- order:38 cpu3irqUsage=0.000000
- order:39 cpu3niceUsage=0.000000
- order:40 cpu3softIrqUsage=0.000000
- order:41 cpu3systemUsage=15.306122
- order:42 cpu3userUsage=66.326531
+ # SP_daemon -N 2 -PKG ohos.samples.ecg -c
+ order:0 timestamp=1501839151499
+ order:1 ProcAppName=ohos.samples.ecg
+ order:2 ProcCpuLoad=0.000000
+ order:3 ProcCpuUsage=36.177645
+ order:4 ProcId=2111
+ order:5 ProcSCpuUsage=8.982036
+ order:6 ProcUCpuUsage=27.195609
+ order:7 TotalcpuUsage=62.500000
+ order:8 TotalcpuidleUsage=37.500000
+ order:9 TotalcpuioWaitUsage=0.000000
+ order:10 TotalcpuirqUsage=0.000000
+ order:11 TotalcpuniceUsage=0.000000
+ order:12 TotalcpusoftIrqUsage=0.000000
+ order:13 TotalcpusystemUsage=21.614583
+ order:14 TotalcpuuserUsage=40.885417
+ order:15 cpu0Frequency=1992000
+ order:16 cpu0Usage=77.083333
+ order:17 cpu0idleUsage=22.916667
+ order:18 cpu0ioWaitUsage=0.000000
+ order:19 cpu0irqUsage=0.000000
+ order:20 cpu0niceUsage=0.000000
+ order:21 cpu0softIrqUsage=0.000000
+ order:22 cpu0systemUsage=21.875000
+ order:23 cpu0userUsage=55.208333
+ order:24 cpu1Frequency=1992000
+ order:25 cpu1Usage=57.731959
+ order:26 cpu1idleUsage=42.268041
+ order:27 cpu1ioWaitUsage=0.000000
+ order:28 cpu1irqUsage=0.000000
+ order:29 cpu1niceUsage=0.000000
+ order:30 cpu1softIrqUsage=0.000000
+ order:31 cpu1systemUsage=21.649485
+ order:32 cpu1userUsage=36.082474
+ order:33 cpu2Frequency=1992000
+ order:34 cpu2Usage=59.793814
+ order:35 cpu2idleUsage=40.206186
+ order:36 cpu2ioWaitUsage=0.000000
+ order:37 cpu2irqUsage=0.000000
+ order:38 cpu2niceUsage=0.000000
+ order:39 cpu2softIrqUsage=0.000000
+ order:40 cpu2systemUsage=19.587629
+ order:41 cpu2userUsage=40.206186
+ order:42 cpu3Frequency=1992000
+ order:43 cpu3Usage=55.789474
+ order:44 cpu3idleUsage=44.210526
+ order:45 cpu3ioWaitUsage=0.000000
+ order:46 cpu3irqUsage=0.000000
+ order:47 cpu3niceUsage=0.000000
+ order:48 cpu3softIrqUsage=0.000000
+ order:49 cpu3systemUsage=23.157895
+ order:50 cpu3userUsage=32.631579
+
...
-
+
command exec finished!
#
```
@@ -286,12 +292,10 @@ Click **Report** to access the report list. Touch a report to view its details.
>- Make sure you are on the application screen when running this command.
- Collect once the GPU frequency and load of the system.
-
+
```
# SP_daemon -N 1 -g
-
-
-
+
order:0 timestamp=1503078740268
order:1 gpuFrequency=200000000
order:2 gpuLoad=38.000000
@@ -304,16 +308,15 @@ Click **Report** to access the report list. Touch a report to view its details.
```
# SP_daemon -N 2 -t
-
+
order:0 timestamp=1502720711191
order:1 gpu-thermal=42500.000000
order:2 soc-thermal=43.125000
-
-
+
order:0 timestamp=1502720712191
order:1 gpu-thermal=41875.000000
order:2 soc-thermal=42.500000
-
+
command exec finished!
#
```
@@ -326,12 +329,12 @@ Click **Report** to access the report list. Touch a report to view its details.
order:1 memAvailable=7339224
order:2 memFree=7164708
order:3 memTotal=11641840
-
+
order:0 timestamp=1705041563527
order:1 memAvailable=7339136
order:2 memFree=7164684
order:3 memTotal=11641840
-
+
command exec finished!
#
```
@@ -340,7 +343,7 @@ Click **Report** to access the report list. Touch a report to view its details.
```
# SP_daemon -N 1 -PKG ohos.samples.ecg -r
-
+
order:0 timestamp=1720427095197
order:1 arktsHeapPss=17555
order:2 gpuPss=7021
@@ -361,7 +364,6 @@ Click **Report** to access the report list. Touch a report to view its details.
order:17 swap=122076
order:18 swapPss=122076
-
command exec finished!
#
```
@@ -374,41 +376,37 @@ Click **Report** to access the report list. Touch a report to view its details.
```
# SP_daemon -N 2 -snapshot
+
+ order:0 timestamp=1501837609657
+ order:1 capture=data/local/tmp/capture/screenCap_1501837609657.png
- order:0 timestamp=1705041753321
- order:1 capture=data/local/tmp/capture/screenCap_1705041753321.png
-
- /data/local/tmp/capture created!
-
- order:0 timestamp=1705041754324
+ order:0 timestamp=1501837610657
order:1 capture=NA
-
+
command exec finished!
#
```
>**NOTE**
>
- >- Screenshots are collected every 2 seconds.
- >
- >-
+ >- Screenshots are collected every 2 seconds.
>
>- When the collection is complete, you can view the screenshots in **data/local/tmp/capture**.
>
- >- To export the screenshots to drive D, open a new CLI and run the **hdc file recv data/local/tmp/capture/screenCap_1700725192774.png D:\** command.
+ >- To export the screenshots to drive D, open a new CLI and run the **hdc file recv data/local/tmp/capture/screenCap_1700725192774.png D:\\** command.
- Collect the network speeds twice.
```
# SP_daemon -N 2 -net
-
+
order:0 timestamp=1705041904832
order:1 networkDown=0
order:2 networkUp=0
-
+
order:0 timestamp=1705041905870
order:1 networkDown=22931
order:2 networkUp=2004
-
+
command exec finished!
#
```
@@ -417,27 +415,27 @@ Click **Report** to access the report list. Touch a report to view its details.
```
# SP_daemon -N 5 -PKG ohos.samples.ecg -f
-
+
order:0 timestamp=1705306472232
order:1 fps=43
order:2 fpsJitters=602261688;;8352083;;8267708;;8305209;;8298437;;8308854;;8313542;;8569271;;8061458;;8300521;;8308333;;8309896;;8429167;;8241667;;8258333;;8318229;;8312500;;8304167;;41760937;;16418750;;8298959;;8319270;;8308334;;8313541;;8302605;;8320312;;8298958;;8326042;;8321354;;8301042;;8310417;;8309895;;8308855;;8331250;;8286458;;8343229;;8278125;;8311458;;8306250;;8312500;;8320834;;8346875;;8283333
- order:3 refreshrate=120
-
+ order:3 refreshrate=69
+
order:0 timestamp=1705306473234
order:1 fps=40
order:2 fpsJitters=674427313;;8191145;;8310417;;8319271;;8301562;;8318750;;8302084;;8314062;;8333334;;8283854;;8307812;;8311979;;8310417;;8307813;;8309375;;8323958;;8306250;;8308333;;8317709;;8296875;;8721875;;7895833;;8320833;;8340625;;8276563;;8409896;;8216145;;8310938;;8301042;;8362500;;8252604;;8317708;;8376042;;8256250;;8292187;;8303125;;8313542;;8310417;;8520312
- order:3 refreshrate=120
+ order:3 refreshrate=69
...
-
+
command exec finished!
#
```
>**NOTE**
>
>- When running this command, make sure you are on the application screen, and then swipe on the screen or switch between screens.
- >- When dynamic refresh rate (DRR) is enabled, the refresh rate changes in real time (multiple changes may occur within one second). The value of **refreshrate** is collected at a timestamp.
+ >- When dynamic refresh rate (DRR) is enabled, the refresh rate changes in real time (multiple changes may occur within one second). The value of **refreshrate** is obtained at a timestamp.
+
-
- Collect the frame rate of the specified view layer for 10 times.
```
@@ -445,14 +443,14 @@ Click **Report** to access the report list. Touch a report to view its details.
order:0 timestamp=1705306822850
order:1 fps=15
order:2 fpsJitters=876291843;;8314062;;8308334;;8314583;;8310417;;8308333;;8326042;;8314583;;8292708;;8492709;;8143750;;8340104;;8294271;;8302604;;8297396
- order:3 refreshrate=120
-
+ order:3 refreshrate=69
+
order:0 timestamp=1705306823852
order:1 fps=12
order:2 fpsJitters=906667363;;8279167;;8311458;;8315625;;8291146;;8313021;;8323438;;8293750;;8303125;;8313541;;8301563;;8317708
- order:3 refreshrate=120
+ order:3 refreshrate=69
...
-
+
command exec finished!
#
```
@@ -475,152 +473,166 @@ Click **Report** to access the report list. Touch a report to view its details.
command exec finished!
#
```
-
- Collect the full information of the system, including the CPU, GPU, temperature, memory, DDR, network speed, and screenshot information.
-
+
```
# SP_daemon -N 10 -c -g -t -r -d -net -snapshot
-
- order:0 timestamp=1502725274844
- order:1 cpu0Frequency=1992000
- order:2 cpu0Usage=37.634409
- order:3 cpu0idleUsage=62.365591
- order:4 cpu0ioWaitUsage=0.000000
- order:5 cpu0irqUsage=0.000000
- order:7 cpu0softIrqUsage=1.075269
- order:8 cpu0systemUsage=17.204301
- order:9 cpu0userUsage=19.354839
- order:10 cpu1Frequency=1992000
- order:11 cpu1Usage=87.878788
- order:12 cpu1idleUsage=12.121212
- order:13 cpu1ioWaitUsage=0.000000
- order:14 cpu1irqUsage=0.000000
- order:15 cpu1niceUsage=0.000000
- order:16 cpu1softIrqUsage=0.000000
- order:17 cpu1systemUsage=15.151515
- order:18 cpu1userUsage=72.727273
- order:19 cpu2Frequency=1992000
- order:20 cpu2Usage=45.544554
- order:21 cpu2idleUsage=54.455446
- order:22 cpu2ioWaitUsage=0.000000
- order:23 cpu2irqUsage=0.000000
- order:24 cpu2niceUsage=0.000000
- order:25 cpu2softIrqUsage=0.990099
- order:26 cpu2systemUsage=14.851485
- order:27 cpu2userUsage=29.702970
- order:28 cpu3Frequency=1992000
- order:29 cpu3Usage=39.175258
- order:30 cpu3idleUsage=60.824742
- order:31 cpu3ioWaitUsage=0.000000
- order:32 cpu3irqUsage=0.000000
- order:33 cpu3niceUsage=0.000000
- order:34 cpu3softIrqUsage=1.030928
- order:35 cpu3systemUsage=14.432990
- order:36 cpu3userUsage=23.711340
- order:37 gpuFrequency=300000000
- order:38 gpuLoad=25.000000
- order:39 gpu-thermal=43750.000000
- order:40 soc-thermal=45.555000
- order:41 memAvailable=1118792
- order:42 memFree=688032
- order:43 memTotal=1990104
- order:44 ddrFrequency=0
- order:45 networkDown=0
- order:46 networkUp=0
- order:47 capture=data/local/tmp/capture/screenCap_1502725274893.png
-
+
+ order:0 timestamp=1501837838664
+ order:1 TotalcpuUsage=0.751880
+ order:2 TotalcpuidleUsage=99.248120
+ order:3 TotalcpuioWaitUsage=0.000000
+ order:4 TotalcpuirqUsage=0.000000
+ order:5 TotalcpuniceUsage=0.000000
+ order:6 TotalcpusoftIrqUsage=0.000000
+ order:7 TotalcpusystemUsage=0.501253
+ order:8 TotalcpuuserUsage=0.250627
+ order:9 cpu0Frequency=1992000
+ order:10 cpu0Usage=0.000000
+ order:11 cpu0idleUsage=100.000000
+ order:12 cpu0ioWaitUsage=0.000000
+ order:13 cpu0irqUsage=0.000000
+ order:14 cpu0niceUsage=0.000000
+ order:15 cpu0softIrqUsage=0.000000
+ order:16 cpu0systemUsage=0.000000
+ order:17 cpu0userUsage=0.000000
+ order:18 cpu1Frequency=1992000
+ order:19 cpu1Usage=0.000000
+ order:20 cpu1idleUsage=100.000000
+ order:21 cpu1ioWaitUsage=0.000000
+ order:22 cpu1irqUsage=0.000000
+ order:23 cpu1niceUsage=0.000000
+ order:24 cpu1softIrqUsage=0.000000
+ order:25 cpu1systemUsage=0.000000
+ order:26 cpu1userUsage=0.000000
+ order:27 cpu2Frequency=1992000
+ order:28 cpu2Usage=1.000000
+ order:29 cpu2idleUsage=99.000000
+ order:30 cpu2ioWaitUsage=0.000000
+ order:31 cpu2irqUsage=0.000000
+ order:32 cpu2niceUsage=0.000000
+ order:33 cpu2softIrqUsage=0.000000
+ order:34 cpu2systemUsage=1.000000
+ order:35 cpu2userUsage=0.000000
+ order:36 cpu3Frequency=1992000
+ order:37 cpu3Usage=0.000000
+ order:38 cpu3idleUsage=100.000000
+ order:39 cpu3ioWaitUsage=0.000000
+ order:40 cpu3irqUsage=0.000000
+ order:41 cpu3niceUsage=0.000000
+ order:42 cpu3softIrqUsage=0.000000
+ order:43 cpu3systemUsage=0.000000
+ order:44 cpu3userUsage=0.000000
+ order:45 gpuFrequency=200000000
+ order:46 gpuLoad=0.000000
+ order:47 gpu-thermal=40000.000000
+ order:48 soc-thermal=40.625000
+ order:49 memAvailable=1142820
+ order:50 memFree=687988
+ order:51 memTotal=1935948
+ order:52 ddrFrequency=800000000
+ order:53 networkDown=0
+ order:54 networkUp=0
+ order:55 capture=data/local/tmp/capture/screenCap_1501837838669.png
+
...
-
+
command exec finished!
#
```
- Collect the full information of the specified application, including the CPU, GPU, temperature, frame rate, memory, DDR, network speed, and screenshot information.
-
-
+
```
# SP_daemon -N 10 -PKG ohos.samples.ecg -c -g -t -f -r -d -net -snapshot
-
- order:0 timestamp=1502725340425
- order:1 ProcAppName=com.ohos.settings
+
+ order:0 timestamp=1501837949706
+ order:1 ProcAppName=ohos.samples.ecg
order:2 ProcCpuLoad=0.000000
- order:3 ProcCpuUsage=35.950135
- order:4 ProcId=3912
- order:5 ProcSCpuUsage=6.721698
- order:6 ProcUCpuUsage=29.228437
- order:7 cpu0Frequency=1992000
- order:8 cpu0Usage=64.539007
- order:9 cpu0idleUsage=35.460993
- order:10 cpu0ioWaitUsage=0.000000
- order:11 cpu0irqUsage=0.000000
- order:12 cpu0niceUsage=0.000000
- order:13 cpu0softIrqUsage=0.000000
- order:14 cpu0systemUsage=26.241135
- order:15 cpu0userUsage=38.297872
- order:16 cpu1Frequency=1992000
- order:17 cpu1Usage=73.758865
- order:18 cpu1idleUsage=26.241135
- order:19 cpu1ioWaitUsage=0.000000
- order:20 cpu1irqUsage=0.000000
- order:21 cpu1niceUsage=0.000000
- order:22 cpu1softIrqUsage=0.000000
- order:23 cpu1systemUsage=29.078014
- order:24 cpu1userUsage=44.680851
- order:25 cpu2Frequency=1992000
- order:26 cpu2Usage=75.172414
- order:27 cpu2idleUsage=24.827586
- order:28 cpu2ioWaitUsage=0.000000
- order:29 cpu2irqUsage=0.000000
- order:30 cpu2niceUsage=0.000000
- order:31 cpu2softIrqUsage=0.000000
- order:32 cpu2systemUsage=18.620690
- order:33 cpu2userUsage=56.551724
- order:34 cpu3Frequency=1992000
- order:35 cpu3Usage=80.419580
- order:36 cpu3idleUsage=19.580420
- order:37 cpu3ioWaitUsage=0.000000
- order:38 cpu3irqUsage=0.000000
- order:39 cpu3niceUsage=0.000000
- order:40 cpu3softIrqUsage=0.699301
- order:41 cpu3systemUsage=21.678322
- order:42 cpu3userUsage=58.041958
- order:43 gpuFrequency=800000000
- order:44 gpuLoad=45.000000
- order:45 gpu-thermal=44375.000000
- order:46 soc-thermal=46.111000
- order:47 fps=40
- order:48 fpsJitters=14482127;;28966003;;28971836;;14484751;;28952878;;28970962;;14480959;;28968337;;14476001;;28967461;;28968045;;14477751;;28966878;;28975337;;14475126;;28962795;;28967461;;14496710;;28953169;;28966003;;14483002;;28963961;;28965711;;28964836;;28966295;;14550085;;28898628;;28964544;;28975628;;14497293;;28938878;;43454546;;28966003;;28973295;;28959878;;28964252;;14476585;;28965128;;28970670;;14478626
- order:49 refreshrate=69
- order:50 arktsHeapPss=8482
- order:51 gpuPss=0
- order:52 graphicPss=10800
- order:53 heapAlloc=0
- order:54 heapFree=0
- order:55 heapSize=0
- order:56 memAvailable=1113084
- order:57 memFree=681968
- order:58 memTotal=1990104
- order:59 nativeHeapPss=24630
- order:60 privateClean=7072
- order:61 privateDirty=43304
- order:62 pss=71001
- order:63 sharedClean=93024
- order:64 sharedDirty=45060
- order:65 stackPss=1784
- order:66 swap=0
- order:67 swapPss=0
- order:68 ddrFrequency=0
- order:69 networkDown=0
- order:70 networkUp=0
- order:71 capture=data/local/tmp/capture/screenCap_1502725341222.png
-
+ order:3 ProcCpuUsage=38.775000
+ order:4 ProcId=1960
+ order:5 ProcSCpuUsage=8.875000
+ order:6 ProcUCpuUsage=29.900000
+ order:7 TotalcpuUsage=85.416667
+ order:8 TotalcpuidleUsage=14.583333
+ order:9 TotalcpuioWaitUsage=0.000000
+ order:10 TotalcpuirqUsage=0.000000
+ order:11 TotalcpuniceUsage=0.000000
+ order:12 TotalcpusoftIrqUsage=0.000000
+ order:13 TotalcpusystemUsage=33.072917
+ order:14 TotalcpuuserUsage=52.343750
+ order:15 cpu0Frequency=1992000
+ order:16 cpu0Usage=92.929293
+ order:17 cpu0idleUsage=7.070707
+ order:18 cpu0ioWaitUsage=0.000000
+ order:19 cpu0irqUsage=0.000000
+ order:20 cpu0niceUsage=0.000000
+ order:21 cpu0softIrqUsage=0.000000
+ order:22 cpu0systemUsage=40.404040
+ order:23 cpu0userUsage=52.525253
+ order:24 cpu1Frequency=1992000
+ order:25 cpu1Usage=82.291667
+ order:26 cpu1idleUsage=17.708333
+ order:27 cpu1ioWaitUsage=0.000000
+ order:28 cpu1irqUsage=0.000000
+ order:29 cpu1niceUsage=0.000000
+ order:30 cpu1softIrqUsage=0.000000
+ order:31 cpu1systemUsage=29.166667
+ order:32 cpu1userUsage=53.125000
+ order:33 cpu2Frequency=1992000
+ order:34 cpu2Usage=81.111111
+ order:35 cpu2idleUsage=18.888889
+ order:36 cpu2ioWaitUsage=0.000000
+ order:37 cpu2irqUsage=0.000000
+ order:38 cpu2niceUsage=0.000000
+ order:39 cpu2softIrqUsage=0.000000
+ order:40 cpu2systemUsage=31.111111
+ order:41 cpu2userUsage=50.000000
+ order:42 cpu3Frequency=1992000
+ order:43 cpu3Usage=85.858586
+ order:44 cpu3idleUsage=14.141414
+ order:45 cpu3ioWaitUsage=0.000000
+ order:46 cpu3irqUsage=0.000000
+ order:47 cpu3niceUsage=0.000000
+ order:48 cpu3softIrqUsage=0.000000
+ order:49 cpu3systemUsage=32.323232
+ order:50 cpu3userUsage=53.535354
+ order:51 gpuFrequency=200000000
+ order:52 gpuLoad=29.000000
+ order:53 gpu-thermal=41875.000000
+ order:54 soc-thermal=45.000000
+ order:55 fps=40
+ order:56 fpsJitters=14482127;;28966003;;28971836;;14484751;;28952878;;28970962;;14480959;;28968337;;14476001;;28967461;;28968045;;14477751;;28966878;;28975337;;14475126;;28962795;;28967461;;14496710;;28953169;;28966003;;14483002;;28963961;;28965711;;28964836;;28966295;;14550085;;28898628;;28964544;;28975628;;14497293;;28938878;;43454546;;28966003;;28973295;;28959878;;28964252;;14476585;;28965128;;28970670;;14478626
+ order:57 refreshrate=69
+ order:58 arktsHeapPss=10970
+ order:59 gpuPss=0
+ order:60 graphicPss=10800
+ order:61 heapAlloc=0
+ order:62 heapFree=0
+ order:63 heapSize=0
+ order:64 memAvailable=1137784
+ order:65 memFree=682592
+ order:66 memTotal=1935948
+ order:67 nativeHeapPss=21398
+ order:68 privateClean=24816
+ order:69 privateDirty=44932
+ order:70 pss=91587
+ order:71 sharedClean=100512
+ order:72 sharedDirty=36832
+ order:73 stackPss=1444
+ order:74 swap=0
+ order:75 swapPss=0
+ order:76 ddrFrequency=800000000
+ order:77 networkDown=0
+ order:78 networkUp=0
+ order:79 capture=data/local/tmp/capture/screenCap_1501837950216.png
+
...
-
+
command exec finished!
#
```
-
>**NOTE**
>
@@ -637,21 +649,25 @@ Run the **start** command to start collection, operate the device or application
| -stop |Yes| Stops collection. A report is generated when collection is complete. |
##### Samples
-
- ```
+
+ ```
Start data collection.
# SP_daemon -start -c
SP_daemon Collection begins
+
+
command exec finished!
#
Stop data collection.
# SP_daemon -stop
SP_daemon Collection ended
- Output Path: data/local/tmp/smartperf/1/t_index_info_csv
+ Output Path: data/local/tmp/smartperf/1/t_index_info.csv
+
+
command exec finished!
#
- ```
+ ```
>**NOTE**
>
>- To start collecting the system data, run the **SP_daemon -start -c -g -t -r -d -net -snapshot** command.
@@ -668,20 +684,20 @@ If the collection result is saved in a CSV file, perform the following steps to
- To check the path to the test result file:
- ```
+ ```
C:\Users\issusser>hdc shell
# cd data/local/tmp
# ls
data.csv
#
- ```
+ ```
- To export the test result file:
```
C:\Users\issusser>hdc file recv data/local/tmp/data.csv D:\
[I][2023-11-08 16:16:41] HdcFile::TransferSummary success
FileTransfer finish, Size:429, File count = 1, time:6ms rate:71.50kB/s
-
+
C:\Users\issusser>
```
@@ -693,23 +709,23 @@ If the collection result is saved in a CSV file, perform the following steps to
| :-----| :--------------------- |:-----|
| cpuFrequency | CPU core frequency. |Unit: Hz|
| cpuUasge | CPU core usage. |%|
- | cpuidleUsage | CPU usage in idle state. |%|
+ | cpuidleUsage | CPU usage in idle state. |%|
| cpuioWaitUsage | CPU usage of I/O wait. |%|
- | cpuirqUsage | CPU usage of hardware interrupts. |%|
+ | cpuirqUsage | CPU usage of hardware interrupts. |%|
| cpuniceUsage | CPU usage of user level processes with lower scheduling priority. |%|
- | cpusoftIrqUsage | CPU usage of software interrupts. |%|
+ | cpusoftIrqUsage | CPU usage of software interrupts. |%|
| cpusystemUsage | CPU usage in kernel mode. |%|
- | cpuuserUsage | CPU usage in user mode. |%|
- | ProcId | PID. |-|
- | ProcAppName | App package name. |-|
+ | cpuuserUsage | CPU usage in user mode. |%|
+ | ProcId | Process ID. |-|
+ | ProcAppName | Application bundle name. |-|
| ProcCpuLoad | Process CPU load. |%|
- | ProcCpuUsage | CPU usage of the process. |%|
+ | ProcCpuUsage | CPU usage of the process. |%|
| ProcUCpuUsage | CPU usage of the process in user mode. |%|
- | ProcSCpuUsage | CPU usage of the process in kernel mode. |%|
+ | ProcSCpuUsage | CPU usage of the process in kernel mode. |%|
| gpuFrequ | GPU frequency of the system. |%|
| gpuLoad | GPU load of the system. |%|
- | currentNow | Current value. |Unit: mA|
- | voltageNow | Voltage value. |Unit: μV|
+ | currentNow | Current value. |Unit: mA|
+ | voltageNow | Voltage value. |Unit: μV|
| fps | Number of frames per second. |Unit: FPS|
| fpsJitters | Frame interval. |Unit: ns|
| refreshrate | Screen refresh rate. |Unit: Hz|
@@ -736,28 +752,25 @@ If the collection result is saved in a CSV file, perform the following steps to
| arktsHeapPss | Used ArkTS memory size. |Unit: KB|
| nativeHeapPss | Used native memory size. |Unit: KB|
| stackPss | Used stack memory size. |Unit: KB|
- | timeStamp | Timestamp. |Collection time.|
-
+ | timeStamp | Timestamp. |Collection time.|
### Scenario Collection
-
-
In addition to basic collection, the response and completion delay can be collected. The scenario collection result is displayed in the CLI instead of being written into the **data.csv** file.
| Command |Mandatory| Description |
| :-----|:-----| :--------------------- |
-| -editor|Yes| Scenario collection tag, which can be followed by parameter configuration options. |
-| -responseTime|No| Response delay. |
-| -completeTime|No| Completion delay. |
+| -editor|Yes| Identifies scenario collection. Parameter options can be added after. |
+| -responseTime|No| Collects the response latency. |
+| -completeTime|No| Collects the completion delay. |
| -fpsohtest|No| A validator used to collect the frame rate every second. The frame rate is collected 10 times by default. |
#### Samples
-- Collect the application response delay.
+- Collect the application response latency. (This command supports only the RK3568 device.)
```
- # SP_daemon -editor responseTime com.ohos.settings
+ # SP_daemon -editor responseTime ohos.samples.ecg ohtest
time:544ms
command exec finished!
@@ -766,10 +779,10 @@ In addition to basic collection, the response and completion delay can be collec
>
>- Open the application before collection, press **Enter** in the CLI, switch to the application page, and wait for the collection result to be printed.
-- Collect the application completion delay.
+- Collect the application completion latency. (This command supports only the RK3568 device.)
```
- # SP_daemon -editor completeTime com.ohos.settings
+ # SP_daemon -editor completeTime ohos.samples.ecg ohtest
time:677ms
command exec finished!
@@ -788,8 +801,6 @@ In addition to basic collection, the response and completion delay can be collec
>
>- You need to swipe or switch the current page after running the command, and the collection result will be printed after 10s.
-
-
### Other Collection
The power collection result of the current device can be written into the **data.csv** file. Other data is collected separately and the collection result is displayed only in the command box.
@@ -800,7 +811,7 @@ The power collection result of the current device can be written into the **data
| -deviceinfo|No| Obtains device information. |
| -server|No| Starts a daemon process by starting or stopping collection. |
| -clear|No| Clears all the SP_daemon processes. |
-| -ohtestfps|No| Obtains the frame rate. The number of collection times can be set (collection is performed every second). |
+| -ohtestfps|No| Obtains the frame rate. You can set the number of collection times (collection is performed every second). |
| -editorServer|No| Starts a daemon process by using an editor. |
| -recordcapacity|No| Obtains the battery level of the current device. |
| -profilerfps |No| Collects the frame rate of the current page. |
@@ -811,7 +822,9 @@ The power collection result of the current device can be written into the **data
```
# SP_daemon -screen
- activeMode: 1260x2720, refreshrate=120
+ activeMode: 720x1280, refreshrate=69
+
+
command exec finished!
#
```
@@ -831,15 +844,16 @@ The power collection result of the current device can be written into the **data
cpu_c1_max: 1992000
cpu_c1_min: 408000
cpu_cluster_name: policy0
+ daemonPerfVersion: 1.0.5
deviceTypeName: rk3568
- fullname: OpenHarmony-5.0.2.43
+ fullname: OpenHarmony-5.1.0.46
gpu_max_freq: 800000000
gpu_min_freq: 200000000
model: ohos
name: OpenHarmony 3.2
- sn: 7001005458323933328a26dbb7bd3900
- version: OpenHarmony 5.0.2.43
-
+ sn: 150100424a5444345209d941bec6b900
+ version: OpenHarmony 5.1.0.46
+
command exec finished!
#
```
@@ -852,9 +866,6 @@ The power collection result of the current device can be written into the **data
# pidof SP_daemon
7024
#
-
- command exec finished!
- #
```
>**NOTE**
>
@@ -864,14 +875,14 @@ The power collection result of the current device can be written into the **data
```
# pidof SP_daemon
- 9923 11402
+ 2725
# SP_daemon -clear
+
+
+ command exec finished!
#
# pidof SP_daemon
#
-
- command exec finished!
- #
```
>**NOTE**
>
@@ -894,9 +905,6 @@ The power collection result of the current device can be written into the **data
fps:41|1501926693532
SP_daemon exec finished!
#
-
- command exec finished!
- #
```
>**NOTE**
>
@@ -907,11 +915,9 @@ The power collection result of the current device can be written into the **data
```
# SP_daemon -editorServer
- Socket Process called!
- Socket TCP Init called!
- Socket Process called!
- Socket Process called!
- —
+
+
+ command exec finished!
```
@@ -979,3 +985,6 @@ The power collection result of the current device can be written into the **data
>**NOTE**
>
>- In this command, **100** indicates the number of collection times (collection is performed every second) and can be set to a positive integer. **10** indicates collection by segment. Currently, the number of collection segments can be set to a positive integer ranging from 1 to 10.
+
+
+
diff --git a/en/application-dev/application-test/wukong-guidelines.md b/en/application-dev/application-test/wukong-guidelines.md
index 5712a6fb1bf3830c8ef2fec416b7c2b7e5621473..5853fadca258d8bf03bd8f3c60bbfe37f68f8648 100644
--- a/en/application-dev/application-test/wukong-guidelines.md
+++ b/en/application-dev/application-test/wukong-guidelines.md
@@ -114,7 +114,12 @@ The following figure shows the wukong component architecture and the responsibil
-r, --rotate rotate event percent
-e, --allow ability the ability name of allowlist
-E, --block ability the ability name of blocklist
+ -Y, --blockCompId the id list of block component
+ -y, --blockCompType the type list of block component
-I, --screenshot get screenshot(only in random input)
+ -B, --checkBWScreen black and white screen detection
+ -U, --Uri set Uri pages
+ -x, --Uri-type set Uri-type
# wukong special -help // Help menu for wukong special testing.
usage: wukong special []
These are wukong special arguments list:
@@ -143,12 +148,12 @@ The following figure shows the wukong component architecture and the responsibil
| Command | Description | Mandatory| Description |
| --------------- | ------------------------------------ | ---- | ---------------------------------------- |
| -h,--help | Obtains the help information about the test. | No | - |
-| -c,--count | Sets the number of execution times. This command conflicts with the **-T** command. Select either of them. | No | The default value is 10, in times. |
+| -c,--count | Sets the number of execution times. This command conflicts with the **-T** command. Set either of them. | No | The default value is 10, in times. |
| -i,--interval | Sets the test interval. | No | The default value is 1500, in millisecond. |
| -s,--seed | Sets the random seed. | No | If the same random seed is set, the same random event sequence is generated.|
-| -b,--bundle[bundlename, ......, bundlename] | Sets the allowed bundles for the test. This command conflicts with the **-p** command.| No | By default, all bundles on the device are allowed. Use commas (,) to separate bundle names. |
-| -p,--prohibit[bundlename, ......, bundlename] | Sets the blocked bundles for the test. This command conflicts with the **-b** command.| No | By default, no bundle is blocked. Use commas (,) to separate bundle names. |
-| -d,--page[page, ......, page] | Sets the blocked pages for the test.| No | By default, the **pages/system** pages are blocked. Use commas (,) to separate page names.|
+| -b,--bundle[bundlename, ......, bundlename] | Sets allowed bundles for the test. This command conflicts with the **-p** command.| No | By default, all bundles on the device are allowed. Use commas (,) to separate bundle names. |
+| -p,--prohibit[bundlename, ......, bundlename] | Sets blocked bundles for the test. This command conflicts with the **-b** command.| No | By default, no bundle is blocked. Use commas (,) to separate bundle names. |
+| -d,--page[page, ......, page] | Sets blocked pages for the test.| No | By default, the **pages/system** pages are blocked. Use commas (,) to separate page names.|
| -a,--appswitch | Sets the proportion of the random application startup event test. | No | The default value is 10%. |
| -t,--touch | Sets the proportion of the random touch event test. | No | The default value is 10%. |
| -S,--swap | Sets the proportion of the random swipe event test. | No | The default value is 3%. |
@@ -244,10 +249,10 @@ The following figure shows the wukong component architecture and the responsibil
| -c,--count | Sets the number of test times. This command conflicts with the **-T** command. Set either of them. | No | The default value is 10, in times. |
| -i,--interval | Sets the test interval. | No | The default value is 1500, in millisecond. |
| -s,--seed | Sets the random seed. | No | If the same random seed is set, the same random event sequence is generated.|
-| -b,--bundle[bundlename, ......, bundlename] | Sets the bundle name of allowlist for the test. This command conflicts with the **-p** command.| No | By default, all applications on the device are allowed. (Use commas (,) to separate application names.) |
-| -p,--prohibit[bundlename, ......, bundlename] | Sets the bundle name of blocklist for the test. This command conflicts with the **-b** command.| No | By default, no application is blocked. (Use commas (,) to separate application names.) |
-| -d,--page[page, ......, page] | Sets the list of blocked pages for the test.| No | By default, the pages/system pages are blocked. (Use commas (,) to separate page names.)|
-| -a,--appswitch | Sets the proportion of random application startup test. | No | The default value is 10%. |
+| -b,--bundle[bundlename, ......, bundlename] | Sets allowed bundles for the test. This command conflicts with the **-p** command.| No | By default, all bundles on the device are allowed. Use commas (,) to separate bundle names. |
+| -p,--prohibit[bundlename, ......, bundlename] | Sets blocked bundles for the test. This command conflicts with the **-b** command.| No | By default, no bundle is blocked. Use commas (,) to separate bundle names. |
+| -d,--page[page, ......, page] | Sets blocked pages for the test.| No | By default, the **pages/system** pages are blocked. Use commas (,) to separate page names.|
+| -a,--appswitch | Sets the proportion of the random application startup event test. | No | The default value is 10%. |
| -t,--touch | Sets the proportion of the random touch event test. | No | The default value is 10%. |
| -S,--swap | Sets the proportion of the random swipe event test. | No | The default value is 3%. |
| -m,--mouse | Sets the proportion of the random mouse event test. | No | The default value is 1%. |
@@ -272,7 +277,7 @@ The following figure shows the wukong component architecture and the responsibil
The parameters in the command are described as follows.
| Command | Value |Description |
| -------------- | -------------- | -------------- |
-| wukong exec | - | Works as the main command. |
+| wukong focus | - | Works as the main command. |
| -s | 10 | Sets the random seed. The seed value is **10**. |
| -i | 1000 | Sets the application startup interval to **1000** ms.|
| -a | 0.28 | Sets the proportion of the random application startup test to **28%**. |
@@ -298,7 +303,7 @@ After the test commands are executed, the test result is automatically generated
| wukong_report.csv | Stores the test report summary. |
| wukong.log | Indicates the test operation history. |
-### Viewing Operation Logs
+### View operation logs
You can run the hdc command to obtain logs to the local host and view the operation history.
@@ -316,3 +321,41 @@ C:\Users\xxx>hdc file recv /data/local/tmp/wukong/report/20170805_170053/wukong.
[I][2024-01-03 20:08:02] HdcFile::TransferSummary success
FileTransfer finish, Size:76492, File count = 1, time:16ms rate:4780.75kB/s
```
+
+## FAQs
+### failed to connect to AAMS
+ **Symptom**
+
+failed to connect to AAMS.
+
+ **Possible Cause**
+
+AAMS is occupied by Hypium or the UIViewer of DevEco Testing. AAMS can be connected to only one program at a time.
+
+ **Solution**
+
+Stop the process that occupies AAMS or restart the device.
+### Errorcode:(4005)
+ **Symptom**
+
+Errorcode:(4005).
+
+ **Possible Cause**
+
+The size of the screen display area changes. As a result, the page information fails to be obtained.
+
+ **Solution**
+
+This error does not affect the test process and does not need to be handled.
+### Errorcode:(4007)
+ **Symptom**
+
+Errorcode:(4007).
+
+ **Possible Cause**
+
+The size of the screen display area changes. As a result, the page information fails to be obtained.
+
+ **Solution**
+
+This error does not affect the test process and does not need to be handled.
diff --git a/en/application-dev/arkts-utils/arkts-sendable.md b/en/application-dev/arkts-utils/arkts-sendable.md
index 8386e5a6bf517d2b3b0a89374489fe0e6124efe3..5d85b206fb945e7b972c6137608fc8a7aa672a93 100644
--- a/en/application-dev/arkts-utils/arkts-sendable.md
+++ b/en/application-dev/arkts-utils/arkts-sendable.md
@@ -60,7 +60,7 @@ A Sendable interface must meet the following requirements:
2. It must meet the Sendable constraints. For details, see [Usage Rules and Constraints for Sendable](sendable-constraints.md).
-### Supported Data Types for Sendable
+### Sendable Data Types
- All ArkTS basic data types: boolean, number, string, bigint, null, and undefined.
@@ -94,7 +94,7 @@ A Sendable interface must meet the following requirements:
## Implementation Principle of Sendable
-To implement pass-by-reference of [Sendable data](#supported-data-types-for-sendable) between different concurrent instances, Sendable objects are allocated in a shared heap to achieve memory sharing across concurrent instances.
+To implement pass-by-reference of [Sendable data](#sendable-data-types) between different concurrent instances, Sendable objects are allocated in a shared heap to achieve memory sharing across concurrent instances.
The shared heap is a process-level heap space. Unlike the local heap of a virtual machine, which can only be accessed by a single concurrent instance, the shared heap can be accessed by all threads. The cross-thread behavior of a Sendable object is pass-by-reference. Therefore, a Sendable object may be referenced by multiple concurrent instances, and its liveness depends on whether any concurrent instance holds a reference to it.
diff --git a/en/application-dev/arkts-utils/figures/obfuscation-product.png b/en/application-dev/arkts-utils/figures/obfuscation-product.png
index 0555b52cfbccdef01e50fbf42fbcb79d40724a14..1908045ea14fea19a0291d052f44119b34f4b5dd 100644
Binary files a/en/application-dev/arkts-utils/figures/obfuscation-product.png and b/en/application-dev/arkts-utils/figures/obfuscation-product.png differ
diff --git a/en/application-dev/arkts-utils/source-obfuscation-guide.md b/en/application-dev/arkts-utils/source-obfuscation-guide.md
index 0cfab1631ad551c0a7c3df88b4cea6fbbb573211..85369c0e210b36f6d7e8e1cd81cab94c0234b72f 100644
--- a/en/application-dev/arkts-utils/source-obfuscation-guide.md
+++ b/en/application-dev/arkts-utils/source-obfuscation-guide.md
@@ -147,6 +147,6 @@ After obfuscation is complete, intermediate products are generated. You can find
## Deobfuscating Error Stacks
-In applications that have undergone obfuscation, code names are changed, making the error stacks printed during crashes harder to understand because they do not match the source code exactly. You can use the [hstack plugin](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-command-line-hstack-V5) in Command Line Tools of DevEco Studio to deobfuscate the source code stack and analyze issues. The deobfuscation tool requires the **sourceMaps.json** file and the obfuscation name mapping file **nameCache.json** generated during compilation. Be sure to back them up locally.
+In applications that have undergone obfuscation, code names are changed, making the error stacks printed during crashes harder to understand because they do not match the source code exactly. You can use the [hstack plugin](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-command-line-hstack-V5) in Command Line Tools of DevEco Studio to deobfuscate the source code stack and analyze issues. The deobfuscation tool requires the **sourceMaps.map** file and the obfuscation name mapping file **nameCache.json** generated during compilation. Be sure to back them up locally.
diff --git a/en/application-dev/basic-services/account/control-os-account-by-constraints.md b/en/application-dev/basic-services/account/control-os-account-by-constraints.md
index dae9cfd267c8c2463cdf0662075ca5d93ac7f804..66c1b335895fda1438b9532e1a5e65e96821ce01 100644
--- a/en/application-dev/basic-services/account/control-os-account-by-constraints.md
+++ b/en/application-dev/basic-services/account/control-os-account-by-constraints.md
@@ -48,8 +48,7 @@ The user can set constraints to restrict the system account behaviors. For examp
## Checking Whether a Constraint Can be Enabled for a System Account
-Before a constraint is enabled for a system account, the application needs to check whether the constraint can be enabled.
-You can use [isOsAccountConstraintEnabled](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#isosaccountconstraintenabled11) to implement this operation.
+Before a constraint is enabled for a system account, the application needs to check whether the constraint can be enabled. You can use [isOsAccountConstraintEnabled](../../reference/apis-basic-services-kit/js-apis-osAccount-sys.md#isosaccountconstraintenabled11) to implement this operation.
**Procedure**
diff --git a/en/application-dev/basic-services/account/manage-os-account.md b/en/application-dev/basic-services/account/manage-os-account.md
index fc75038f1a0479eb5816706e122b5a2bae41904c..d6a7b56b5c9c5b3d00e2b80f096725d39c0227f8 100644
--- a/en/application-dev/basic-services/account/manage-os-account.md
+++ b/en/application-dev/basic-services/account/manage-os-account.md
@@ -1,11 +1,10 @@
# Managing System Accounts (for System Applications Only)
-The system provides APIs for managing system accounts.
-After applying for required permissions for your system application, you can use the APIs to create, activate, modify, and delete system accounts. For third-party applications, you can use the APIs to query basic information about system accounts to develop service logic related to system accounts.
+The system provides APIs for managing system accounts. After applying for required permissions for your system application, you can use the APIs to create, activate, modify, and delete system accounts. For third-party applications, you can use the APIs to query basic information about system accounts to develop service logic related to system accounts.
## Basic Concepts
-### System Account Type
+### Account Type
Currently, only the following types of system accounts can be created:
| Name | Value| Description |
@@ -13,7 +12,7 @@ Currently, only the following types of system accounts can be created:
| ADMIN | 0 | Administrator account.|
| NORMAL | 1 | Normal account. |
| GUEST | 2 | Guest account. |
-| PRIVATE12+ | 1024 | Private account. |
+| PRIVATE12+ | 1024 | Private account. |
### Account Information
@@ -84,7 +83,7 @@ accountManager.queryOsAccountById(localId, (err: BusinessError, accountInfo: osA
});
```
-## Changing the Profile Photo and Nickname of a System Account
+## Changing the ProfilePhoto and Nickname of a System Account
Change the profile photo and nickname of a system account as required.
diff --git a/en/application-dev/basic-services/basic-services-kit-overview.md b/en/application-dev/basic-services/basic-services-kit-overview.md
index 63732bc4dabc182ab24d62a05e9264436f7c53fd..95201066ac5aa98ba0e6c2fb3f75628d750cfbb0 100644
--- a/en/application-dev/basic-services/basic-services-kit-overview.md
+++ b/en/application-dev/basic-services/basic-services-kit-overview.md
@@ -21,7 +21,7 @@ Basic Services Kit is typically used in the following scenarios:
## Capability Scope
-This kit provides the following capabilities:
+Depending on different use cases, this kit provides the following capabilities:
- Data file processing
- [Pasteboard](../reference/apis-basic-services-kit/js-apis-pasteboard.md): provides the copy and paste support. You can use the provided APIs to operate pasteboard content of the plain text, HTML, URI, pixel map, and other types.
@@ -40,7 +40,7 @@ This kit provides the following capabilities:
- [Power management](../reference/apis-basic-services-kit/js-apis-power.md): provides system power management capabilities, such as querying the screen status.
- [Running lock](../reference/apis-basic-services-kit/js-apis-runninglock.md): provides APIs for creating, querying, holding, and releasing running locks.
- [Thermal management](../reference/apis-basic-services-kit/js-apis-thermal.md): provides thermal management capabilities, such as thermal level query.
- - [USB management](../reference/apis-basic-services-kit/js-apis-usbManager.md): provides USB device management capabilities, including USB device list query, bulk data transfer, control transfer, and permission control. For details about the development guide, see [USB Service Development Overview](usb/usb-overview.md).
+ - [USB management](../reference/apis-basic-services-kit/js-apis-usbManager.md): provides USB device management capabilities, including USB device list query, bulk data transfer, control transfer, and permission control. For details about the development guide, see [USB Service Development Overview](usb/usbManager/usbHost-overview.md).
- Others:
- [App account management](../reference/apis-basic-services-kit/js-apis-appAccount.md): provides application account management and data management capabilities. For details, see [Managing App Accounts](account/manage-application-account.md).
@@ -54,6 +54,3 @@ This kit provides the following capabilities:
- [Ability Kit](../application-models/abilitykit-overview.md): Common events in this kit are required for inter-process communication in Ability Kit.
- [Core File Kit](../file-management/core-file-kit-intro.md): Core File Kit provides file access and management capabilities. You can use Core File Kit for application file access, file sharing, and data backup and restore, and use this kit to implement file compression, file upload and download, and file printing.
-
-
-
diff --git a/en/application-dev/basic-services/common-event/common-event-static-subscription.md b/en/application-dev/basic-services/common-event/common-event-static-subscription.md
index a483307811b2f636579a7e3980a84aa0bed5ec2a..45c284d25fa117f646ecdc76e55b6f7ead179ea0 100644
--- a/en/application-dev/basic-services/common-event/common-event-static-subscription.md
+++ b/en/application-dev/basic-services/common-event/common-event-static-subscription.md
@@ -122,7 +122,7 @@ The [StaticSubscriberExtensionAbility](../../reference/apis-basic-services-kit/j
| name | Name of the ExtensionAbility, which must be the same as the name of **extensionAbility** declared in **module.json5**.| String | No |
| permission | Permissions required by the publisher. | String | Yes (initial value: left empty)|
| events | List of subscribed target events. | String array | No |
- | filter | Filter criteria for static events. This attribute is supported since API version 16.
For details about the values, see the following table.| Object array | Yes (initial value: left empty)|
+ | filter | Filter criteria for static events. This attribute is supported since API version 18.
For details about the values, see the following table.| Object array | Yes (initial value: left empty)|
The **filter** tag identifies the static subscription events that can be filtered by the subscriber as required. The tag value is of the object array type and contains two subtags: **event** and **conditions**.
@@ -141,7 +141,7 @@ The [StaticSubscriberExtensionAbility](../../reference/apis-basic-services-kit/j
| ------------ | ------------------------------------------ | ------------------ | -------------------------- |
| code | Result code to filter. | Integer | Yes (initial value: left empty)|
| data | Custom result data to filter.| String | Yes (initial value: left empty)|
- | parameters | Additional information to filter. | Boolean/Number/String| Yes (initial value: left empty)|
+ | parameters | Additional information to filter for a static subscription event. Only data of the Boolean, number, or string type can be configured.| Object| Yes (initial value: left empty)|
4. Modify the [preset configuration file](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_capability.json) of the device, that is, the **/system/variant/phone/base/etc/app/install_list_capability.json** file. When the device is started, this file is read. During application installation, the common event type specified by **allowCommonEvent** in the file is authorized. The **install_list_capability.json** file contains the following fields:
diff --git a/en/application-dev/basic-services/common-event/native-common-event-publish.md b/en/application-dev/basic-services/common-event/native-common-event-publish.md
index 2f8523de4a8b19e6ee23a43bea7705e863f70dc8..6ce4d8eb46af9212e403d09ba07247c8fdba3189 100644
--- a/en/application-dev/basic-services/common-event/native-common-event-publish.md
+++ b/en/application-dev/basic-services/common-event/native-common-event-publish.md
@@ -27,11 +27,9 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
#include
#include
#include
- #include
#include
#include "hilog/log.h"
#include "BasicServicesKit/oh_commonevent.h"
- #include "BasicServicesKit/oh_commonevent_support.h"
```
2. Add dynamic link libraries to the CMake script.
@@ -58,50 +56,50 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Set the additional information and key of the int type.
ret = OH_CommonEvent_SetIntToParameters(param, "intKey", 10);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetIntToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetIntToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the int array type.
int intArray[] = {123, 234, 567};
size_t arraySize = 3;
ret = OH_CommonEvent_SetIntArrayToParameters(param, "intArrayKey", intArray, arraySize);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetIntArrayToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetIntArrayToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the long type.
ret = OH_CommonEvent_SetLongToParameters(param, "longKey", 2147483646);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetLongToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetLongToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the long array type.
long longArray[] = {2147483646, 555, 2147483645};
ret = OH_CommonEvent_SetLongArrayToParameters(param, "longArrayKey", longArray, arraySize);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetLongArrayToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetLongArrayToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the double type.
ret = OH_CommonEvent_SetDoubleToParameters(param, "doubleKey", 11.22);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetDoubleToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetDoubleToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the double array type.
double doubleArray[] = {11.22, 33.44, 55.66};
ret = OH_CommonEvent_SetDoubleArrayToParameters(param, "doubleArrayKey", doubleArray, arraySize);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetDoubleArrayToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetDoubleArrayToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the Boolean type.
ret = OH_CommonEvent_SetBoolToParameters(param, "boolKey", true);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetBoolToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetBoolToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the Boolean array type.
bool boolArray[] = {true, false, true};
ret = OH_CommonEvent_SetBoolArrayToParameters(param, "boolArrayKey", boolArray, arraySize);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetBoolArrayToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetBoolArrayToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the char type.
ret = OH_CommonEvent_SetCharToParameters(param, "charKey", 'A');
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetCharToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetCharToParameters ret <%{public}d>.", ret);
// Set the additional information and key of the char array type.
char* value= "AAAAAAAAAAAAAA";
size_t valueLength = strlen(value);
ret = OH_CommonEvent_SetCharArrayToParameters(param, "charArrayKey", value, valueLength);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetCharArrayToParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetCharArrayToParameters ret <%{public}d>.", ret);
return param;
}
@@ -114,25 +112,25 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Set the bundle name of a common event.
ret = OH_CommonEvent_SetPublishInfoBundleName(info, bundleName);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetPublishInfoBundleName ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoBundleName ret <%{public}d>.", ret);
// Set the common event permission. The parameters consist of the permission array and the number of permissions.
ret = OH_CommonEvent_SetPublishInfoPermissions(info, permissions, num);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetPublishInfoPermissions ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoPermissions ret <%{public}d>.", ret);
// Set the result code of a common event.
ret = OH_CommonEvent_SetPublishInfoCode(info, code);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetPublishInfoCode ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoCode ret <%{public}d>.", ret);
// Set the result data of a common event.
size_t dataLength = strlen(data);
ret = OH_CommonEvent_SetPublishInfoData(info, data, dataLength);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetPublishInfoData ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoData ret <%{public}d>.", ret);
// Set the additional information of a common event.
CommonEvent_Parameters* param = CreateParameters();
ret = OH_CommonEvent_SetPublishInfoParameters(info, param);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetPublishInfoParameters ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublishInfoParameters ret <%{public}d>.", ret);
}
```
@@ -148,7 +146,7 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
void Publish(const char* event)
{
int32_t ret = OH_CommonEvent_Publish(event);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_Publish ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_Publish ret <%{public}d>.", ret);
}
```
@@ -159,7 +157,7 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
{
// Create a common event with the attribute object.
int32_t ret = OH_CommonEvent_PublishWithInfo(event, info);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_PublishWithInfo ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_PublishWithInfo ret <%{public}d>.", ret);
}
```
diff --git a/en/application-dev/basic-services/common-event/native-common-event-subscription.md b/en/application-dev/basic-services/common-event/native-common-event-subscription.md
index 06d58fb9fdf20505faed1ef6c58edf3269c7aef4..da6aa2017e46d9034768692c8ccdb958d2e8d086 100644
--- a/en/application-dev/basic-services/common-event/native-common-event-subscription.md
+++ b/en/application-dev/basic-services/common-event/native-common-event-subscription.md
@@ -28,11 +28,9 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
#include
#include
#include
- #include
#include
#include "hilog/log.h"
#include "BasicServicesKit/oh_commonevent.h"
- #include "BasicServicesKit/oh_commonevent_support.h"
```
2. Add dynamic link libraries to the CMake script.
@@ -57,11 +55,11 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Set the subscriber permission.
ret = OH_CommonEvent_SetPublisherPermission(info, permission);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetPublisherPermission ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublisherPermission ret <%{public}d>.", ret);
// Set a bundle name of the subscriber.
ret = OH_CommonEvent_SetPublisherBundleName(info, bundleName);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_SetPublisherBundleName ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_SetPublisherBundleName ret <%{public}d>.", ret);
return info;
}
@@ -93,7 +91,7 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Obtain the additional information of a common event.
const CommonEvent_Parameters *parameters = OH_CommonEvent_GetParametersFromRcvData(data);
- OH_LOG_INFO(LOG_APP, "event: %{public}s, code: %{public}d, data: %{public}s, bundle: %{public}s", event, code, retData, bundle);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "event: %{public}s, code: %{public}d, data: %{public}s, bundle: %{public}s", event, code, retData, bundle);
}
```
@@ -109,38 +107,38 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
exists = OH_CommonEvent_HasKeyInParameters(parameters, "intKey");
// Obtain the int data from the additional information of a common event.
int intValue = OH_CommonEvent_GetIntFromParameters(parameters, "intKey", 10);
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, intValue = %{public}d", exists, intValue);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, intValue = %{public}d", exists, intValue);
exists = OH_CommonEvent_HasKeyInParameters(parameters, "boolKey");
// Obtain the Boolean data from the additional information of a common event.
bool boolValue = OH_CommonEvent_GetBoolFromParameters(parameters, "boolKey", false);
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, boolValue = %{public}d", exists, boolValue);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, boolValue = %{public}d", exists, boolValue);
exists = OH_CommonEvent_HasKeyInParameters(parameters, "longKey");
// Obtain the long data from the additional information of a common event.
long longValue = OH_CommonEvent_GetLongFromParameters(parameters, "longKey", 1111111111);
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, longValue = %{public}ld", exists, longValue);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, longValue = %{public}ld", exists, longValue);
exists = OH_CommonEvent_HasKeyInParameters(parameters, "doubleKey");
// Obtain the double data from the additional information of a common event.
double doubleValue = OH_CommonEvent_GetDoubleFromParameters(parameters, "doubleKey", 11.11);
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, doubleValue = %{public}f", exists, doubleValue);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, doubleValue = %{public}f", exists, doubleValue);
exists = OH_CommonEvent_HasKeyInParameters(parameters, "charKey");
// Obtain the char data from the additional information of a common event.
char charValue = OH_CommonEvent_GetCharFromParameters(parameters, "charKey", 'A');
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, charValue = %{public}c", exists, charValue);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, charValue = %{public}c", exists, charValue);
int** arr = new int*;
exists = OH_CommonEvent_HasKeyInParameters(parameters, "intArrayKey");
// Obtain the int array from the additional information of a common event.
int32_t intArraySize = OH_CommonEvent_GetIntArrayFromParameters(parameters, "intArrayKey", arr);
if (intArraySize <= 0 || *arr == nullptr) {
- OH_LOG_ERROR(LOG_APP, "exists = %{public}d, Failed to get int array or invalid size: %{public}d", exists, intArraySize);
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get int array or invalid size: %{public}d", exists, intArraySize);
} else {
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, intArraySize = %{public}d", exists, intArraySize);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, intArraySize = %{public}d", exists, intArraySize);
for (int i = 0; i < intArraySize; i++) {
- OH_LOG_INFO(LOG_APP, "<%{public}d>", *((*arr) + i));
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}d>", *((*arr) + i));
}
}
@@ -149,11 +147,11 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Obtain the long array from the additional information of a common event.
int32_t longArraySize = OH_CommonEvent_GetLongArrayFromParameters(parameters, "longArrayKey", longArray);
if (longArraySize <= 0 || *longArray == nullptr) {
- OH_LOG_ERROR(LOG_APP, "exists = %{public}d, Failed to get long array or invalid size: %{public}d", exists, longArraySize);
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get long array or invalid size: %{public}d", exists, longArraySize);
} else {
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, longArraySize = %{public}d", exists, longArraySize);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, longArraySize = %{public}d", exists, longArraySize);
for (int i = 0; i < longArraySize; i++) {
- OH_LOG_INFO(LOG_APP, "<%{public}ld>", *((*longArray) + i));
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}ld>", *((*longArray) + i));
}
}
@@ -162,11 +160,11 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Obtain the double array from the additional information of a common event.
int32_t doubleArraySize = OH_CommonEvent_GetDoubleArrayFromParameters(parameters, "doubleArrayKey", doubleArray);
if (doubleArraySize <= 0 || *doubleArray == nullptr) {
- OH_LOG_ERROR(LOG_APP, "exists = %{public}d, Failed to get double array or invalid size: %{public}d", exists, doubleArraySize);
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get double array or invalid size: %{public}d", exists, doubleArraySize);
} else {
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, doubleArraySize = %{public}d", exists, doubleArraySize);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, doubleArraySize = %{public}d", exists, doubleArraySize);
for (int i = 0; i < doubleArraySize; i++) {
- OH_LOG_INFO(LOG_APP, "<%{public}f>", *((*doubleArray) + i));
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}f>", *((*doubleArray) + i));
}
}
@@ -175,9 +173,9 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Obtain the char array from the additional information of a common event.
int32_t charArraySize = OH_CommonEvent_GetCharArrayFromParameters(parameters, "charArrayKey", charArray);
if (charArraySize <= 0 || *charArray == nullptr) {
- OH_LOG_ERROR(LOG_APP, "exists = %{public}d, Failed to get charArray or invalid size: %{public}d", exists, charArraySize);
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get charArray or invalid size: %{public}d", exists, charArraySize);
} else {
- OH_LOG_INFO(LOG_APP, "charArray as string: %{public}s", *charArray);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "charArray as string: %{public}s", *charArray);
}
bool** boolArray = new bool*;
@@ -185,11 +183,11 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Obtain the Boolean array from the additional information of a common event.
int32_t boolArraySize = OH_CommonEvent_GetBoolArrayFromParameters(parameters, "boolArrayKey", boolArray);
if (boolArraySize <= 0 || *boolArray == nullptr) {
- OH_LOG_ERROR(LOG_APP, "exists = %{public}d, Failed to get boolArray or invalid size: %{public}d", exists, boolArraySize);
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "exists = %{public}d, Failed to get boolArray or invalid size: %{public}d", exists, boolArraySize);
} else {
- OH_LOG_INFO(LOG_APP, "exists = %{public}d, boolArraySize = %{public}d", exists, boolArraySize);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "exists = %{public}d, boolArraySize = %{public}d", exists, boolArraySize);
for (int i = 0; i < boolArraySize; i++) {
- OH_LOG_INFO(LOG_APP, "<%{public}d>", *((*boolArray) + i));
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "<%{public}d>", *((*boolArray) + i));
}
}
}
@@ -218,7 +216,7 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
void Subscribe(CommonEvent_Subscriber* subscriber) {
// Subscribe to an event by passing a subscriber.
int32_t ret = OH_CommonEvent_Subscribe(subscriber);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_Subscribe ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_Subscribe ret <%{public}d>.", ret);
}
```
@@ -238,17 +236,18 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
void AbortCommonEvent(CommonEvent_Subscriber* subscriber) {
// Check whether the event is an ordered common event.
if(!OH_CommonEvent_IsOrderedCommonEvent(subscriber)) {
- OH_LOG_INFO(LOG_APP, "Not ordered common event.");
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Not ordered common event.");
return;
}
// Abort an ordered common event.
if(OH_CommonEvent_AbortCommonEvent(subscriber)) {
if(OH_CommonEvent_FinishCommonEvent(subscriber)) {
// Obtain the result of the abort state of an ordered common event.
- OH_LOG_INFO(LOG_APP, "Abort common event success, Get abort <%{public}d>.", OH_CommonEvent_GetAbortCommonEvent(subscriber));
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Abort common event success, Get abort <%{public}d>.", OH_CommonEvent_GetAbortCommonEvent(subscriber));
}
+ } else {
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Abort common event failed.");
}
- OH_LOG_ERROR(LOG_APP, "Abort common event failed.");
}
```
@@ -260,22 +259,23 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
void ClearAbortCommonEvent(CommonEvent_Subscriber* subscriber) {
// Check whether the event is an ordered common event.
if(!OH_CommonEvent_IsOrderedCommonEvent(subscriber)) {
- OH_LOG_INFO(LOG_APP, "Not ordered common event.");
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Not ordered common event.");
return;
}
// Abort an ordered common event.
if(!OH_CommonEvent_AbortCommonEvent(subscriber)) {
- OH_LOG_ERROR(LOG_APP, "Abort common event failed.");
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Abort common event failed.");
return;
}
// Clear the aborted state of an ordered event.
if(OH_CommonEvent_ClearAbortCommonEvent(subscriber)) {
if(OH_CommonEvent_FinishCommonEvent(subscriber)) {
// Obtain the result of the abort state of an ordered common event.
- OH_LOG_INFO(LOG_APP, "Clear abort common event success, Get abort <%{public}d>.", OH_CommonEvent_GetAbortCommonEvent(subscriber));
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Clear abort common event success, Get abort <%{public}d>.", OH_CommonEvent_GetAbortCommonEvent(subscriber));
}
+ } else {
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "Clear abort common event failed.");
}
- OH_LOG_ERROR(LOG_APP, "Clear abort common event failed.");
}
```
@@ -287,13 +287,13 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
void SetToSubscriber(CommonEvent_Subscriber* subscriber, const int32_t code, const char* data) {
// Set the result code of an ordered common event.
if(!OH_CommonEvent_SetCodeToSubscriber(subscriber, code)) {
- OH_LOG_ERROR(LOG_APP, "OH_CommonEvent_SetCodeToSubscriber failed.");
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "OH_CommonEvent_SetCodeToSubscriber failed.");
return;
}
// Set the result data for an ordered common event.
size_t dataLength = strlen(data);
if(!OH_CommonEvent_SetDataToSubscriber(subscriber, data, dataLength)) {
- OH_LOG_ERROR(LOG_APP, "OH_CommonEvent_SetDataToSubscriber failed.");
+ OH_LOG_Print(LOG_APP, LOG_ERROR, 1, "CES_TEST", "OH_CommonEvent_SetDataToSubscriber failed.");
return;
}
}
@@ -302,7 +302,7 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
// Obtain the result data and code of an ordered common event.
const char* data = OH_CommonEvent_GetDataFromSubscriber(subscriber);
int32_t code = OH_CommonEvent_GetCodeFromSubscriber(subscriber);
- OH_LOG_INFO(LOG_APP, "Subscriber data <%{public}s>, code <%{public}d>.", data, code);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "Subscriber data <%{public}s>, code <%{public}d>.", data, code);
}
```
diff --git a/en/application-dev/basic-services/common-event/native-common-event-unsubscription.md b/en/application-dev/basic-services/common-event/native-common-event-unsubscription.md
index 8b06e63fcf5b8815adaa0b5305182afb00621cb2..00dfec282f9c81449296af36f7ea00fd952fcb45 100644
--- a/en/application-dev/basic-services/common-event/native-common-event-unsubscription.md
+++ b/en/application-dev/basic-services/common-event/native-common-event-unsubscription.md
@@ -19,13 +19,8 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
```c++
#include
- #include
- #include
- #include
- #include
#include "hilog/log.h"
#include "BasicServicesKit/oh_commonevent.h"
- #include "BasicServicesKit/oh_commonevent_support.h"
```
2. Add dynamic link libraries to the CMake script.
@@ -47,6 +42,6 @@ For details about the APIs, see [CommonEvent](../../reference/apis-basic-service
void Unsubscribe(CommonEvent_Subscriber* subscriber) {
// Unsubscribe from a common event by passing a subscriber.
int32_t ret = OH_CommonEvent_UnSubscribe(subscriber);
- OH_LOG_INFO(LOG_APP, "OH_CommonEvent_UnSubscribe ret <%{public}d>.", ret);
+ OH_LOG_Print(LOG_APP, LOG_INFO, 1, "CES_TEST", "OH_CommonEvent_UnSubscribe ret <%{public}d>.", ret);
}
```
diff --git a/en/application-dev/basic-services/request/app-file-upload-download.md b/en/application-dev/basic-services/request/app-file-upload-download.md
index ee7e18e5cd347fec73cc250a40cf091b2dadb311..1758d0ade146babbd22d2f72863dab31931948f0 100644
--- a/en/application-dev/basic-services/request/app-file-upload-download.md
+++ b/en/application-dev/basic-services/request/app-file-upload-download.md
@@ -173,7 +173,12 @@ try {
// Way 2: Use request.agent.
// pages/xxx.ets
// Download the network resource file to the local application file directory, and read data from the file.
+import { common } from '@kit.AbilityKit';
+import fs from '@ohos.file.fs';
import { BusinessError, request } from '@kit.BasicServicesKit';
+import { buffer } from '@kit.ArkTS';
+
+// Obtain the application file path.
let context = getContext(this) as common.UIAbilityContext;
let filesDir = context.filesDir;
@@ -210,3 +215,46 @@ request.agent.create(context, config).then((task: request.agent.Task) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
```
+
+## Adding Network Configuration
+
+### Intercepting HTTP
+
+You can set the configuration file to intercept HTTP. After HTTP is disabled for the upload and download module, upload and download tasks using plaintext HTTP cannot be created. The configuration file is stored in the **src/main/resources/base/profile/network_config.json** directory of the application.
+
+The sample configuration file is as follows:
+
+```ts
+{
+ "network-security-config": {
+ "base-config": {
+ "cleartextTrafficPermitted": true,
+ "trust-anchors": [
+ {
+ "certificates": "/etc/security/certificates"
+ }
+ ]
+ },
+ "domain-config": [
+ {
+ "cleartextTrafficPermitted": true,
+ "domains": [
+ {
+ "include-subdomains": true,
+ "name": "*.example.com"
+ }
+ ],
+ }
+ ]
+ }
+}
+
+```
+
+The table below lists the description of each field.
+
+| Field | Type | Description |
+| --------------------------| --------------- | -------------------------------------- |
+| base-config:
cleartextTrafficPermitted | boolean | Whether plaintext transfer is allowed in the global configuration. The value **true** means that plaintext transfer is allowed, that is, HTTP is not intercepted, and **false** means the opposite.|
+| domain-config:
cleartextTrafficPermitted | boolean | Whether plaintext transfer is allowed in a specified domain. The value **true** means that plaintext transfer is allowed, that is, HTTP is not intercepted, and **false** means the opposite.|
+| include-subdomains | boolean | Whether a rule applies to subdomains. The value **true** means that the regular expression is used to match the domain name, and **false** means the opposite.|
diff --git a/en/application-dev/basic-services/usb/Readme-EN.md b/en/application-dev/basic-services/usb/Readme-EN.md
index cf103267508782de18a57b64d2253400a32079c3..5a0cca273f5d7df5ef60de310a0568b8b525bbed 100644
--- a/en/application-dev/basic-services/usb/Readme-EN.md
+++ b/en/application-dev/basic-services/usb/Readme-EN.md
@@ -1,5 +1,22 @@
# USB Service
+
- [USB Service Overview](usb-overview.md)
- [USB Service Development](usb-guidelines.md)
+
+- Developing USB Services
+ - [USB Service Development Overview](usbManager/usbHost-overview.md)
+ - USB Host Development
+ - [USB Device Management](usbManager/usbHost/deviceManager.md)
+ - [USB Control Transfer](usbManager/usbHost/controlTransfer.md)
+ - [USB Interrupt Transfer](usbManager/usbHost/interruptTransfer.md)
+ - [USB Bulk Transfer](usbManager/usbHost/bulkTransfer.md)
+ - [USB Isochronous Transfer](usbManager/usbHost/isochronousTransfer.md)
+- Developing USB Serial Communication Services.
+ - [USB Serial Communication Development Overview](usbSerial/usbSerial-overview.md)
+ - [USB Serial Configuration Management](usbSerial/usbSerial-configuration.md)
+ - [USB Serial Communication Management](usbSerial/usbSerial-communication.md)
- [FAQs](faqs-usb.md)
+- [Glossary](usb-glossary.md)
+
+
\ No newline at end of file
diff --git a/en/application-dev/basic-services/usb/faqs-usb.md b/en/application-dev/basic-services/usb/faqs-usb.md
index c92e6d07e5fff983fed668cc1fce3c0be012ca5d..34431bf5df783c6472bf53b2110a893f70f589eb 100644
--- a/en/application-dev/basic-services/usb/faqs-usb.md
+++ b/en/application-dev/basic-services/usb/faqs-usb.md
@@ -14,11 +14,52 @@ If the current device functions as the USB host, the **usbManager.getDevices** A
Based on the preceding description:
-- When a device, for example, a phone, is connected to a PC using a USB cable, the PC is the USB host by default, and the phone is a USB device.
-It is normal if the device list obtained by calling **usbManager.getDevices** on the phone is empty.
-- When a device, for example, a phone, is connected to a mouse or keyboard using a USB cable, the phone is the USB host by default, and the mouse or keyboard is the USB device.
-In this case, you can call the **usbManager.getDevices** API on the phone to obtain the device list.
+- When a device, for example, a phone, is connected to a PC using a USB cable, the PC is the USB host by default, and the phone is a USB device. It is normal if the device list obtained by calling **usbManager.getDevices** on the phone is empty.
+- When a device, for example, a phone, is connected to a mouse or keyboard using a USB cable, the phone is the USB host by default, and the mouse or keyboard is the USB device. In this case, you can call the **usbManager.getDevices** API on the phone to obtain the device list.
### Solution
Ensure that the current device is the USB host and the connected device is the USB device. (Some devices can serve both as the USB host and USB device. In this case, you need to set such devices as USB devices so that the device list can be obtained by the USB host.)
+
+## What should I do if garbled characters are displayed when data is transferred through the USB?
+
+### Symptom
+
+Garbled characters are displayed during data transfer.
+
+### Possible Causes
+
+The baud rate does not match.
+
+### Solution
+
+Check whether the baud rates at both ends are the same. If not, reconfigure the baud rates.
+
+## What should I do if communication fails when data is transferred through the USB?
+
+### Symptom
+
+The connection cannot be set up between the two ends. No data is transferred or received, or the transferred data frames are incomplete (for example, only some bytes are received).
+
+### Possible Causes
+
+The parity bit or stop bit is incorrectly configured.
+
+### Solution
+
+Check whether the settings of the parity bit or stop bit at both ends are the same as those required by the device.
+
+## What should I do if packet loss occurs when data is transferred through the USB?
+
+
+### Symptom
+
+Occasional packet loss occurs during data transfer.
+
+### Possible Causes
+
+Noise interference or insufficient stop bit.
+
+### Solution
+
+Check whether interference exists. Modify the stop bit to improve the anti-interference capability (for example, change the stop bit from 1 to 2).
diff --git a/en/application-dev/basic-services/usb/figures/en-us_image_22989BBB5490.png b/en/application-dev/basic-services/usb/figures/en-us_image_22989BBB5490.png
new file mode 100644
index 0000000000000000000000000000000000000000..fe32b8a7db1408d851c3ef85d7f0325591f908f1
Binary files /dev/null and b/en/application-dev/basic-services/usb/figures/en-us_image_22989BBB5490.png differ
diff --git a/en/application-dev/basic-services/usb/usb-glossary.md b/en/application-dev/basic-services/usb/usb-glossary.md
new file mode 100644
index 0000000000000000000000000000000000000000..c95122e868811e411d8ece89e41b687c3ea01966
--- /dev/null
+++ b/en/application-dev/basic-services/usb/usb-glossary.md
@@ -0,0 +1,75 @@
+# USB Service Terms
+
+## B
+
+### Baud rate
+
+The baud rate indicates the number of symbols transmitted by a serial port device per second. A symbol is a binary bit, including the data bit, start bit, stop bit, and parity bit. The unit is baud. For example, 9600 baud indicates that 9600 symbols are transmitted per second. The sender and receiver must use the same baud rate. Otherwise, data cannot be correctly parsed.
+
+### Bulk transfer
+
+A one-way data transfer mode of the USB service, which is applicable to the scenario where a large amount of data needs to be transferred. During the transfer, the bulk transactions (IN/OUT token packet, data packet, and handshake packet) are used to increase the overall transfer volume, and the error detection and retransfer mechanisms are used to ensure the reliability of data transfer. However, bulk transfer has the lowest priority among the USB transfer modes. It is mainly used in devices that require low real-time performance but high reliability, such as USB flash drives, printers, and scanners.
+
+## C
+
+### Control transfer
+
+A two-way data transfer mode of the USB service, which is applicable to device configuration, status query, and command transfer. Its process consists of three phases: setup phase (SETUP transaction), data phase (optional batch transaction), and status phase (handshake confirmation). This mode is mainly used for basic control operations such as device enumeration (such as descriptor reading), initialization configuration, and firmware upgrade.
+
+## D
+
+### Data bit
+
+The data bit indicates the number of valid binary bits actually transmitted in each data packet, which determines the data capacity of a single character. Commonly, a data bit may consist of five to eight digits. The data bit determines the amount of information transmitted at a time. The more the data bits, the larger the amount of information transmitted at a time, but more time is required for synchronization.
+
+### Device
+
+A device is a peripheral connected to the host. It executes specific functions (such as storage and data input/output) and passively responds to instructions from the host. For example, a USB flash drive, mouse, or printer is a device.
+
+## E
+
+### Endpoint
+
+An endpoint is a logical end point for data transfer between a device and a host. It is a basic unit for USB communication. Each endpoint has a unique address and direction (**IN** indicates device-to-host, and **OUT** indicates host-to-device). Each endpoint represents a one-way or two-way data transfer pipe.
+
+## H
+
+### Host
+
+The host is a device that controls and manages the USB. It manages the connected devices on the bus and coordinates data transfer and communication. The host is usually a calculator or another host, such as a PC, a smartphone, or a tablet, which can connect to and control multiple devices through the USB port to provide data transfer and charging.
+
+## I
+
+### Interface
+
+An interface is a logical abstraction of a functional module in a USB device, and represents an independent function (such as audio, storage, or communication) of the device. Each interface contains a group of endpoints and manages their activation status through USB configuration. Through flexible interface configuration, USB devices can reuse multiple functions and dynamically switch functions. This is the core mechanism for the USB protocol to support plug-and-play and complex peripherals.
+
+### Interrupt transfer
+
+A one-way data transfer mode of the USB service. The host periodically polls the device (for example, 1 ms to 255 ms) to ensure isochronous performance and accuracy. The transaction structure is similar to that of bulk transfer, but the priority is higher. It is applicable to input devices that require low-latency response, such as keyboard, mouse, and game controller.
+
+### Isochronous transfer
+
+A one-way data transfer mode of the USB service. No handshake packet is transferred. The fixed bandwidth is used to ensure isochronous performance but allow data loss. A transaction contains only tokens and data phases and is suitable for streaming media transfer. It is applicable to devices that require high continuity and fault tolerance, such as cameras, USB speakers, and video conferencing devices.
+
+## P
+
+### Parity bit
+
+A parity bit is a 1-bit binary value appended to a data frame. It is generated based on the content of the data bit according to specific rules. Commonly, for an odd parity check, the total number of **1** in the data bits and parity bit is an odd number; for an even parity check, the total number of **1** is an even number; for no parity check, no parity bit is added to the data bit. By verifying the number of **1** in the data bit, the parity bit determines whether errors such as bit flipping and noise interference occur during data transfer. Increasing the parity bit slightly reduces the transfer efficiency but improves the error tolerance.
+
+### Pipe
+
+A pipe is a logical communication channel between a host and an endpoint for data transfer. A pipe is not a physical connection, but an abstract communication path between a host and a device endpoint. Each pipe corresponds to a specific endpoint of the device. Pipes provide one-way data transfer, and the direction is determined by the endpoint. For example, the IN endpoint indicates that the data is transferred from a pipe to the host, while the OUT endpoint indicates that the data is transferred from the host to a pipe.
+
+## S
+
+### Stop bit
+
+The stop bit is located at the end of a data frame. It is a logic high-level signal and is used to identify the end of a character (data packet) transfer. Its length can be 1 bit, 1.5 bits, or 2 bits. (In actual development, 1 bit is most commonly used, and 1.5 bits and 2 bits are mainly used in anti-interference scenarios.) A core function of this bit is to provide a space to tolerate the errors that may occur during time-sequence synchronization for a receiver and ensure data integrity.
+
+## U
+
+### USBConfiguration
+
+USBConfiguration indicates a function set of the USB device. A USB device supports multiple configurations, but only one of them can be activated at a time. Each USBconfiguration contains multiple interfaces, and each interface represents an independent function (such as data transfer and audio output). In addition, each interface contains multiple endpoints for data transfer (such as control transfer and bulk transfer).
diff --git a/en/application-dev/basic-services/usb/usb-guidelines.md b/en/application-dev/basic-services/usb/usb-guidelines.md
index 200789ae157151a23b8271e16a5245965bb4891a..318c234105da7806c74ce83193b87889c5558559 100644
--- a/en/application-dev/basic-services/usb/usb-guidelines.md
+++ b/en/application-dev/basic-services/usb/usb-guidelines.md
@@ -20,8 +20,8 @@ The following table lists the USB APIs currently available. For details, see the
| hasRight(deviceName: string): boolean | Checks whether the user has the device access permissions.|
| requestRight(deviceName: string): Promise<boolean> | Requests the device access permissions for the application. This API uses a promise to return the result. |
| removeRight(deviceName: string): boolean | Revokes the device access permissions of the application.|
-| connectDevice(device: USBDevice): Readonly<USBDevicePipe> | Connects to the USB device based on the device information returned by `getDevices()`. |
-| getDevices(): Array<Readonly<USBDevice>> | Obtains the list of USB devices connected to the host. If no device is connected, an empty list is returned. |
+| connectDevice(device: USBDevice): Readonly<USBDevicePipe> | Connects to the USB device based on the device information returned by `getDevices()`. If the USB service is abnormal, `undefined` may be returned. Check whether the return value of the API is empty. |
+| getDevices(): Array<Readonly<USBDevice>> | Obtains the list of USB devices connected to the host. If no device is connected, an empty list is returned. When the developer mode is disabled, `undefined` may be returned if no device is connected. Check whether the return value of the API is empty. |
| setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number | Sets the USB device configuration. |
| setInterface(pipe: USBDevicePipe, iface: USBInterface): number | Sets a USB interface. |
| claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number | Claims a USB interface. |
@@ -29,7 +29,7 @@ The following table lists the USB APIs currently available. For details, see the
| closePipe(pipe: USBDevicePipe): number | Closes a USB device pipe. |
| releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number | Releases a USB interface. |
| getFileDescriptor(pipe: USBDevicePipe): number | Obtains the file descriptor. |
-| getRawDescriptor(pipe: USBDevicePipe): Uint8Array | Obtains the raw USB descriptor. |
+| getRawDescriptor(pipe: USBDevicePipe): Uint8Array | Obtains the raw USB descriptor. If the USB service is abnormal, `undefined` may be returned. Check whether the return value of the API is empty. |
| usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout?: number): Promise<number> | Performs control transfer. |
diff --git a/en/application-dev/basic-services/usb/usb-overview.md b/en/application-dev/basic-services/usb/usb-overview.md
index 1cfdfa215c5dfe606796af3e9848d1373be8843a..fa4af7646a13ef3e340c49d9b63011192ed9e48b 100644
--- a/en/application-dev/basic-services/usb/usb-overview.md
+++ b/en/application-dev/basic-services/usb/usb-overview.md
@@ -1,4 +1,4 @@
-# USB Service Development Overview
+# USB Service Overview
## Basic Concepts
diff --git a/en/application-dev/basic-services/usb/usbManager/bulkTransfer.md b/en/application-dev/basic-services/usb/usbManager/usbhost/bulkTransfer.md
similarity index 90%
rename from en/application-dev/basic-services/usb/usbManager/bulkTransfer.md
rename to en/application-dev/basic-services/usb/usbManager/usbhost/bulkTransfer.md
index 4e67993b1073d080c043d093bbb11c97e0178397..a07c1cb393c63924ab09bacb821128f1c626f481 100644
--- a/en/application-dev/basic-services/usb/usbManager/bulkTransfer.md
+++ b/en/application-dev/basic-services/usb/usbManager/usbhost/bulkTransfer.md
@@ -4,9 +4,9 @@
Bulk transfer is used to transfer and receive a large amount of data without bandwidth or interval requirements, for example, file or image transfer. Devices such as printers and scanners support this type of transfer.
-## Environment Preparation
+## Preparing the Environment
-### Requirements
+### Environment Requirements
- Development tool and configuration:
@@ -22,9 +22,9 @@ Bulk transfer is used to transfer and receive a large amount of data without ban
HarmonyOS Device Connector (hdc) is a command-line tool for debugging. It can be used to interact with real devices or the Emulators on Windows, Linux, and macOS. For details about the configuration, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
-### Setting Up the Environment
+### Environment Setup
-- Download and install DevEco Studio on the PC. For details, see [Downloading Software](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-software-download-V5) and [Installing DevEco Studio](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-software-install-V5). The DevEco Studio version must be 4.1 or later.
+- Install [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 4.1 or later on the PC.
- Update the public-SDK to API version 16 or later. For details, see [Switching to Full SDK](https://gitee.com/openharmony/docs/blob/master/en/application-dev/faqs/full-sdk-switch-guide.md).
- Install hdc on the PC. You can use it to interact with a real device or emulator on Windows, Linux, or macOS. For details, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
- Use a USB cable to connect an OpenHarmony device to the PC.
@@ -37,7 +37,7 @@ Bulk transfer is used to transfer and receive a large amount of data without ban
|-------------------------------------------------------------------------------------------------------------------|-----------------------|
| bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number> | Performs bulk transfer. |
-For details about the APIs of device management and transfer modes, see [@ohos.usbManager (USB Manager)](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis-basic-services-kit/js-apis-usbManager.md).
+For details about the APIs of device management and transfer modes, see [@ohos.usbManager (USB Manager)](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md).
### Development Procedure
@@ -165,7 +165,7 @@ Connect a host to a device and use the **bulkTransfer** API to transfer data. Th
});
```
-6. Release the USB interface, and close the USB device.
+6. Release the USB interface, and close the USB device pipe.
```ts
usbManager.releaseInterface(pipe, interface1);
diff --git a/en/application-dev/basic-services/usb/usbManager/controlTransfer.md b/en/application-dev/basic-services/usb/usbManager/usbhost/controlTransfer.md
similarity index 89%
rename from en/application-dev/basic-services/usb/usbManager/controlTransfer.md
rename to en/application-dev/basic-services/usb/usbManager/usbhost/controlTransfer.md
index bc4df13ebe0b630491aee2c9302398965dcf8ecb..6c6e1009c3d72a4f746154c4b867a544b4b4d6e0 100644
--- a/en/application-dev/basic-services/usb/usbManager/controlTransfer.md
+++ b/en/application-dev/basic-services/usb/usbManager/usbhost/controlTransfer.md
@@ -4,9 +4,9 @@
The control transfer is used to obtain and set the device status, and control the device attribute status. You can determine whether the control transfer can read or write data based on the endpoint types supported by the device.
-## Environment Preparation
+## Preparing the Environment
-### Requirements
+### Environment Requirements
- Development tool and configuration:
@@ -22,9 +22,9 @@ The control transfer is used to obtain and set the device status, and control th
HarmonyOS Device Connector (hdc) is a command-line tool for debugging. It can be used to interact with real devices or the Emulators on Windows, Linux, and macOS. For details about the configuration, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
-### Setting Up the Environment
+### Environment Setup
-- Download and install DevEco Studio on the PC. For details, see [Downloading Software](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-software-download-V5) and [Installing DevEco Studio](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-software-install-V5). The DevEco Studio version must be 4.1 or later.
+- Install [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 4.1 or later on the PC.
- Update the public-SDK to API version 16 or later. For details, see [Switching to Full SDK](https://gitee.com/openharmony/docs/blob/master/en/application-dev/faqs/full-sdk-switch-guide.md).
- Install hdc on the PC. You can use it to interact with a real device or the Emulator on Windows, Linux, or macOS. For details, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
- Use a USB cable to connect an OpenHarmony device to the PC.
@@ -37,7 +37,7 @@ The control transfer is used to obtain and set the device status, and control th
| ------------------------------------------------------------ |--------|
| usbControlTransfer(pipe: USBDevicePipe, requestparam: USBDeviceRequestParams, timeout?: number): Promise<number> | Performs control transfer. |
-For details about the APIs of device management and transfer modes, see [@ohos.usbManager (USB Manager)](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis-basic-services-kit/js-apis-usbManager.md).
+For details about the APIs of device management and transfer modes, see [@ohos.usbManager (USB Manager)](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md).
### Development Procedure
@@ -156,7 +156,7 @@ Connect a host to a device and use the **usbControlTransfer** API to transfer da
})
```
-6. Release the USB interface, and close the USB device.
+6. Release the USB interface, and close the USB device pipe.
```ts
usbManager.releaseInterface(pipe, interface1);
diff --git a/en/application-dev/basic-services/usb/usbManager/usbhost/deviceManager.md b/en/application-dev/basic-services/usb/usbManager/usbhost/deviceManager.md
new file mode 100644
index 0000000000000000000000000000000000000000..e3ef88cc5849305fefc05a65a565ada42c9109f2
--- /dev/null
+++ b/en/application-dev/basic-services/usb/usbManager/usbhost/deviceManager.md
@@ -0,0 +1,159 @@
+# USB Device Management
+
+## When to Use
+
+When a USB device is inserted, you can use **usbManager** to obtain basic information about the USB device, such as the device type and supported functions. The host communicates with the USB device through the encapsulated pipe. In OpenHarmony, the USB management service is the core component that manages the connection and communication with USB devices. With the USB management service, applications can detect the USB connection and disconnection, manage permission requests and device configurations of USB devices, and perform data transfer and device control.
+
+## Environment Preparation
+
+### Environment Requirements
+
+- Development tool and configuration:
+
+ DevEco Studio, as the driver development tool, allows you to develop, debug, and package drivers. [Download and install](https://developer.huawei.com/consumer/cn/download/) DevEco Studio and verify basic operations to ensure that it can function properly. For details, see [Creating and Running a Project](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-create-new-project-V14) in [DevEco Studio User Guide](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-tools-overview-V14).
+
+
+- SDK version configuration:
+
+ The ArkTs APIs for peripheral management can be used only when the SDK is of API version 16 or later.
+
+
+- HDC configuration:
+
+ HarmonyOS Device Connector (hdc) is a command-line tool for debugging. It can be used to interact with real devices or the Emulators on Windows, Linux, and macOS. For details about the configuration, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
+
+### Environment Setup
+
+- Install [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 4.1 or later on the PC.
+- Update the public SDK to API version 16 or later. For details, see [Update Guide](https://gitee.com/openharmony/docs/blob/master/en/application-dev/faqs/full-sdk-switch-guide.md).
+- Install hdc on the PC. You can use it to interact with a real device or the Emulator on Windows, Linux, or macOS. For details, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
+- Use a USB cable to connect an OpenHarmony device to the PC.
+
+## How to Develop
+
+### Available APIs
+
+USB device management provides the following functions: querying the USB device list, controlling USB device permissions, and setting USB device configurations.
+
+The following table lists the USB APIs currently available. For details, see [@ohos.usbManager (USB Manager)](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md).
+
+**Table 1** Open USB APIs
+
+| API | Description |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| hasRight(deviceName: string): boolean | Checks whether the USB has the device access permissions.|
+| requestRight(deviceName: string): Promise<boolean> | Requests the temporary permission for the application to access the USB device. This API uses a promise to return the result. |
+| removeRight(deviceName: string): boolean | Removes the device access permissions of the application.|
+| connectDevice(device: USBDevice): Readonly<USBDevicePipe> | Connects to the USB device based on the device information returned by **getDevices()**. |
+| getDevices(): Array<Readonly<USBDevice>> | Obtains the list of USB devices connected to the host. If no device is connected, an empty list is returned. |
+| setConfiguration(pipe: USBDevicePipe, config: USBConfiguration): number | Sets the USB device configuration. |
+| setInterface(pipe: USBDevicePipe, iface: USBInterface): number | Sets a USB interface. |
+| claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number | Claims a USB interface. |
+| closePipe(pipe: USBDevicePipe): number | Closes a USB device pipe. |
+| releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number | Releases a USB interface. |
+| getFileDescriptor(pipe: USBDevicePipe): number | Obtains the file descriptor of a USB device. |
+| getRawDescriptor(pipe: USBDevicePipe): Uint8Array | Obtains the raw USB descriptor. |
+
+### How to Develop
+
+A USB device can be used as a host to connect to a device for management. The procedure is as follows:
+
+
+1. Import modules.
+
+ ```ts
+ // Import the usbManager module.
+ import { usbManager } from '@kit.BasicServicesKit';
+ import { BusinessError } from '@kit.BasicServicesKit';
+ ```
+
+2. Obtain the USB device list.
+
+ ```ts
+ // Obtain the USB device list.
+ let deviceList : Array = usbManager.getDevices();
+ /*
+ Example deviceList structure:
+ [
+ {
+ name: "1-1",
+ serial: "",
+ manufacturerName: "",
+ productName: "",
+ version: "",
+ vendorId: 7531,
+ productId: 2,
+ clazz: 9,
+ subClass: 0,
+ protocol: 1,
+ devAddress: 1,
+ busNum: 1,
+ configs: [
+ {
+ id: 1,
+ attributes: 224,
+ isRemoteWakeup: true,
+ isSelfPowered: true,
+ maxPower: 0,
+ name: "1-1",
+ interfaces: [
+ {
+ id: 0,
+ protocol: 0,
+ clazz: 9,
+ subClass: 0,
+ alternateSetting: 0,
+ name: "1-1",
+ endpoints: [
+ {
+ address: 129,
+ attributes: 3,
+ interval: 12,
+ maxPacketSize: 4,
+ direction: 128,
+ number: 1,
+ type: 3,
+ interfaceId: 0,
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ */
+ ```
+
+3. Obtain the device operation permissions.
+
+ ```ts
+ let deviceName : string = deviceList[0].name;
+ // Request the permissions to operate a specified device.
+ usbManager.requestRight(deviceName).then((hasRight : boolean) => {
+ console.info("usb device request right result: " + hasRight);
+ }).catch((error : BusinessError)=> {
+ console.info("usb device request right failed : " + error);
+ });
+ ```
+
+4. Open the device.
+
+ ```ts
+ // Open the device, and obtain the USB device pipe for data transfer.
+ let pipe : usbManager.USBDevicePipe = usbManager.connectDevice(deviceList[0]);
+ let interface1 : usbManager.USBInterface = deviceList[0].configs[0].interfaces[0];
+ /*
+ Claim the corresponding interface from **deviceList**.
+ interface1 must be one present in the device configuration.
+ */
+ usbManager.claimInterface(pipe, interface1, true);
+ ```
+
+5. Release the USB interface, and close the USB device.
+
+ ```ts
+ usbManager.releaseInterface(pipe, interface1);
+ usbManager.closePipe(pipe);
+ ```
+
diff --git a/en/application-dev/basic-services/usb/usbManager/usbhost/interruptTransfer.md b/en/application-dev/basic-services/usb/usbManager/usbhost/interruptTransfer.md
new file mode 100644
index 0000000000000000000000000000000000000000..a497587c8866a1289c7d7ca89af5e6644ed5867a
--- /dev/null
+++ b/en/application-dev/basic-services/usb/usbManager/usbhost/interruptTransfer.md
@@ -0,0 +1,162 @@
+# USB Interrupt Transfer
+
+## When to Use
+
+The interrupt transfer is mainly used by the host to receive a data packet sent by a device. The endpoint mode of a device determines whether the interface supports interrupt reading or interrupt writing. This mode is applicable to the transfer of a small number of scattered and unpredictable data input by devices such as the mouse, keyboard, and joystick. In addition, the endpoints of these devices support only interrupt reading.
+
+## Preparing the Environment
+
+### Environment Requirements
+
+- Development tool and configuration:
+
+ DevEco Studio, as the driver development tool, allows you to develop, debug, and package drivers. [Download and install](https://developer.huawei.com/consumer/cn/download/) DevEco Studio and verify basic operations to ensure that it can function properly. For details, see [Creating and Running a Project](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-create-new-project-V14) in [DevEco Studio User Guide](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-tools-overview-V14).
+
+
+- SDK version configuration:
+
+ The ArkTs APIs for peripheral management can be used only when the SDK is of API version 16 or later.
+
+
+- HDC configuration:
+
+ HarmonyOS Device Connector (hdc) is a command-line tool for debugging. It can be used to interact with real devices or the Emulators on Windows, Linux, and macOS. For details about the configuration, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
+
+### Environment Setup
+
+- Install [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 4.1 or later on the PC.
+- Update the public SDK to API version 16 or later. For details, see [Switching to Full SDK](https://gitee.com/openharmony/docs/blob/master/en/application-dev/faqs/full-sdk-switch-guide.md).
+- Install hdc on the PC. You can use it to interact with a real device or the Emulator on Windows, Linux, or macOS. For details, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
+- Use a USB cable to connect an OpenHarmony device to the PC.
+
+## How to Develop
+
+### Available APIs
+
+| API | Description |
+|------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
+| usbSubmitTransfer(transfer: UsbDataTransferParams): void | Submits isochronous, bulk, or interrupt transfer in an asynchronous manner. |
+| usbCancelTransfer(transfer: UsbDataTransferParams): void | Cancels the submitted asynchronous transfer. |
+
+For details about the APIs of device management and transfer modes, see [@ohos.usbManager (USB Manager)](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md).
+
+### How to Develop
+
+Connect a host to a device and use the **usbSubmitTransfer** API to transfer data. The following steps describe how to implement an interrupt transfer:
+
+1. Import modules.
+
+ ```ts
+ // Import the usbManager module.
+ import { usbManager } from '@kit.BasicServicesKit';
+ ```
+
+2. Obtain the USB device list.
+
+ ```ts
+ // Obtain the list of USB devices connected to the host.
+ let usbDevices: Array = usbManager.getDevices();
+ console.info('usbDevices: ', JSON.stringify(usbDevices));
+ if(usbDevices.length === 0) {
+ console.info('usbDevices is empty');
+ return;
+ }
+ ```
+
+3. Obtain the device operation permissions.
+
+ ```ts
+ // Check whether the first USB device in the list has the access permission.
+ let usbDevice: usbManager.USBDevice = usbDevices[0];
+ if(!usbManager.hasRight(usbDevice.name)) {
+ await usbManager.requestRight(usbDevice.name).then(result => {
+ if(!result) {
+ // If the USB device does not have the access permission and is not granted by the user, the device exits.
+ console.info('user is not granted the operation permission');
+ return;
+ }
+ });
+ }
+ ```
+
+4. Obtain the endpoint for reading data through interrupt transfer.
+
+ ```ts
+ let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(usbDevice);
+ let usbConfigs: usbManager.USBConfiguration[] = usbDevice.configs;
+ let usbInterfaces: usbManager.USBInterface[] = [];
+ let usbInterface: usbManager.USBInterface | undefined = undefined
+ let usbEndpoints: usbManager.USBEndpoint[] = [];
+ let usbEndprint: usbManager.USBEndpoint | undefined = undefined
+ for (let i = 0; i < usbConfigs.length; i++) {
+ usbInterfaces = usbConfigs[i].interfaces;
+ for (let i = 0; i < usbInterfaces.length; i++) {
+ usbEndpoints = usbInterfaces[i].endpoints;
+ usbEndprint = usbEndpoints.find((value) => {
+ return value.direction === 128 && value.type === usbManager.UsbEndpointTransferType.TRANSFER_TYPE_INTERRUPT;
+ })
+ if (usbEndprint !== undefined) {
+ usbInterface = usbInterfaces[i];
+ break;
+ }
+ }
+ }
+ if (usbEndprint === undefined) {
+ console.error(`get usbEndprint error`)
+ return;
+ }
+ ```
+
+5. Connect to the device and register the communication interface.
+
+ ```ts
+ // Register a communication interface. If the registration is successful, 0 is returned; otherwise, other error codes are returned.
+ let claimInterfaceResult: number = usbManager.claimInterface(devicePipe, usbInterface, true);
+ if (claimInterfaceResult !== 0) {
+ console.error(`claimInterface error = ${claimInterfaceResult}`)
+ return;
+ }
+ ```
+
+6. Perform data transfer.
+
+ ```ts
+ try {
+ // The communication interface is successfully registered and performs data transfer.
+ let transferParams: usbManager.UsbDataTransferParams = {
+ devPipe: devicePipe,
+ flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK,
+ endpoint: usbEndprint.address,
+ type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_INTERRUPT,
+ timeout: 2000,
+ length: 10,
+ callback: () => {},
+ userData: new Uint8Array(10),
+ buffer: new Uint8Array(10),
+ isoPacketCount: 2,
+ };
+
+ transferParams.callback = (err: Error, callBackData: usbManager.SubmitTransferCallback) => {
+ console.info('callBackData = ' + JSON.stringify(callBackData));
+ console.info('transfer success, result = ' + transferParams.buffer.toString());
+ }
+ usbManager.usbSubmitTransfer(transferParams);
+ console.info('USB transfer request submitted.');
+ } catch (error) {
+ console.error('USB transfer failed:', error);
+ }
+ ```
+
+7. Cancels the data transfer, releases the interface, and closes the USB device pipe.
+
+ ```ts
+ usbManager.usbCancelTransfer(transferParams);
+ usbManager.releaseInterface(devicePipe, usbInterface);
+ usbManager.closePipe(devicePipe);
+ ```
+
+### Verification
+
+1. Connect the host to a terminal device (such as a mouse or a keyboard) that supports interrupt transfer through a USB interface.
+2. Execute the preceding code.
+3. Search for the keyword **transfer success** in the log. If the keyword is found, the interrupt transfer interface is successfully called.
diff --git a/en/application-dev/basic-services/usb/usbManager/usbhost/isochronousTransfer.md b/en/application-dev/basic-services/usb/usbManager/usbhost/isochronousTransfer.md
new file mode 100644
index 0000000000000000000000000000000000000000..a2af8a69e32468706253cd67b48c01c76e73283d
--- /dev/null
+++ b/en/application-dev/basic-services/usb/usbManager/usbhost/isochronousTransfer.md
@@ -0,0 +1,172 @@
+# USB Isochronous Transfer
+
+## When to Use
+
+Isochronous transfer is a transfer mode in which data is transferred in a fixed time window through the USB protocol. This ensures the timing stability and low latency of data streams, but allows a small amount of data loss (such as video frame loss and audio noise). This transfer mode is applicable to scenarios that have high requirements on continuity and fault tolerance, such as USB headsets, USB speakers, and video conferencing devices.
+
+## Preparing the Environment
+
+### Environment Requirements
+
+- Development tool and configuration:
+
+ DevEco Studio, as the driver development tool, allows you to develop, debug, and package drivers. [Download and install](https://developer.huawei.com/consumer/cn/download/) DevEco Studio and verify basic operations to ensure that it can function properly. For details, see [Creating and Running a Project](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-create-new-project-V14) in [DevEco Studio User Guide](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-tools-overview-V14).
+
+
+- SDK version configuration:
+
+ The ArkTs APIs for peripheral management can be used only when the SDK is of API version 16 or later.
+
+
+- HDC configuration:
+
+ HarmonyOS Device Connector (hdc) is a command-line tool for debugging. It can be used to interact with real devices or the Emulators on Windows, Linux, and macOS. For details about the configuration, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
+
+### Environment Setup
+
+- Install [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 4.1 or later on the PC.
+- Update the public SDK to API version 16 or later. For details, see [Switching to Full SDK](https://gitee.com/openharmony/docs/blob/master/en/application-dev/faqs/full-sdk-switch-guide.md).
+- Install hdc on the PC. You can use it to interact with a real device or the Emulator on Windows, Linux, or macOS. For details, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
+- Use a USB cable to connect an OpenHarmony device to the PC.
+
+## How to Develop
+
+### Available APIs
+
+| API | Description |
+|------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
+| usbSubmitTransfer(transfer: UsbDataTransferParams): void | Submits isochronous, bulk, or interrupt transfer in an asynchronous manner. |
+| usbCancelTransfer(transfer: UsbDataTransferParams): void | Cancels the submitted asynchronous transfer. |
+
+For details about the APIs of device management and transfer modes, see [@ohos.usbManager (USB Manager)](../../../../reference/apis-basic-services-kit/js-apis-usbManager.md).
+
+### How to Develop
+
+Connect a host to a device and use the **usbSubmitTransfer** API to transfer data. The following steps describe how to implement an interrupt transfer:
+
+1. Import modules.
+
+ ```ts
+ // Import the usbManager module.
+ import { usbManager } from '@kit.BasicServicesKit';
+ ```
+
+2. Obtain the USB device list.
+
+ ```ts
+ // Obtain the list of USB devices connected to the host.
+ let usbDevices: Array = usbManager.getDevices();
+ console.info('usbDevices: ', JSON.stringify(usbDevices));
+ if(usbDevices.length === 0) {
+ console.info('usbDevices is empty');
+ return;
+ }
+ ```
+
+3. Obtain the device operation permissions.
+
+ ```ts
+ // Check whether the first USB device in the list has the access permission.
+ let usbDevice: usbManager.USBDevice = usbDevices[0];
+ if(!usbManager.hasRight(usbDevice.name)) {
+ await usbManager.requestRight(usbDevice.name).then(result => {
+ if(!result) {
+ // If the USB device does not have the access permission and is not granted by the user, the device exits.
+ console.info('user is not granted the operation permission');
+ return;
+ }
+ });
+ }
+ ```
+
+4. Obtain the endpoint for reading data through interrupt transfer.
+
+ ```ts
+ let devicePipe: usbManager.USBDevicePipe = usbManager.connectDevice(usbDevice);
+ let usbConfigs: usbManager.USBConfiguration[] = usbDevice.configs;
+ let usbInterfaces: usbManager.USBInterface[] = [];
+ let usbInterface: usbManager.USBInterface | undefined = undefined
+ let usbEndpoints: usbManager.USBEndpoint[] = [];
+ let usbEndprint: usbManager.USBEndpoint | undefined = undefined
+ for (let i = 0; i < usbConfigs.length; i++) {
+ usbInterfaces = usbConfigs[i].interfaces;
+ for (let i = 0; i < usbInterfaces.length; i++) {
+ usbEndpoints = usbInterfaces[i].endpoints;
+ usbEndprint = usbEndpoints.find((value) => {
+ // direction indicates the request direction. The value 0 indicates the written data, and the value 128 indicates the read data.
+ return value.direction === 128 && value.type === usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS;
+ })
+ if (usbEndprint !== undefined) {
+ usbInterface = usbInterfaces[i];
+ break;
+ }
+ }
+ }
+ if (usbEndprint === undefined) {
+ console.error(`get usbEndprint error`)
+ return;
+ }
+ ```
+
+5. Connect to the device and register the communication interface.
+
+ ```ts
+ // Register a communication interface. If the registration is successful, 0 is returned; otherwise, other error codes are returned.
+ let claimInterfaceResult: number = usbManager.claimInterface(devicePipe, usbInterface, true);
+ if (claimInterfaceResult !== 0) {
+ console.error(`claimInterface error = ${claimInterfaceResult}`)
+ return;
+ }
+
+ // When the transfer is of the isochronous type, you need to register a device interface. If the registration is successful, 0 is returned; otherwise, other error codes are returned.
+ if (this.type === usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS) {
+ let setInterfaceResult = usbManager.setInterface(devicePipe, usbInterface);
+ if (setInterfaceResult !== 0) {
+ console.info(`setInterfaceResult error = ${setInterfaceResult}`)
+ return;
+ }
+ }
+ ```
+
+6. Perform data transfer.
+
+ ```ts
+ try {
+ // The communication interface is successfully registered and performs data transfer.
+ let transferParams: usbManager.UsbDataTransferParams = {
+ devPipe: devicePipe,
+ flags: usbManager.UsbTransferFlags.USB_TRANSFER_SHORT_NOT_OK,
+ endpoint: usbEndprint.address,
+ type: usbManager.UsbEndpointTransferType.TRANSFER_TYPE_ISOCHRONOUS,
+ timeout: 2000,
+ length: 10,
+ callback: () => {},
+ userData: new Uint8Array(10),
+ buffer: new Uint8Array(10),
+ isoPacketCount: 2,
+ };
+
+ transferParams.callback = (err: Error, callBackData: usbManager.SubmitTransferCallback) => {
+ console.info('callBackData = ' + JSON.stringify(callBackData));
+ console.info('transfer success, result = ' + transferParams.buffer.toString());
+ }
+ usbManager.usbSubmitTransfer(transferParams);
+ console.info('USB transfer request submitted.');
+ } catch (error) {
+ console.error('USB transfer failed:', error);
+ }
+ ```
+
+7. Cancels the data transfer, releases the interface, and closes the USB device pipe.
+
+ ```ts
+ usbManager.usbCancelTransfer(transferParams);
+ usbManager.releaseInterface(devicePipe, usbInterface);
+ usbManager.closePipe(devicePipe);
+ ```
+
+### Verification
+
+1. Connect the host to a device (such as a USB headset) that supports isochronous transfer through a USB interface.
+2. Execute the preceding code.
+3. Search for the keyword **transfer success** in the log. If the keyword is found, the isochronous transfer interface is successfully called.
diff --git a/en/application-dev/basic-services/usb/usbserial/usbSerial-communication.md b/en/application-dev/basic-services/usb/usbserial/usbSerial-communication.md
new file mode 100644
index 0000000000000000000000000000000000000000..91a8bfb47caaa5bbca9f564668feda13c81b5794
--- /dev/null
+++ b/en/application-dev/basic-services/usb/usbserial/usbSerial-communication.md
@@ -0,0 +1,136 @@
+# USB Serial Communication Management
+
+## Overview
+
+In the USB serial communication service, the USB port of the host is connected to the serial port of the serial port device for serial data transmission. The core objective of communication management is to implement efficient and stable data transmission and collaborative control between devices. It is mainly used in scenarios such as industrial automation and remote management, IoT device interconnection, and medical device management.
+
+## Preparing the Environment
+
+For details, see [Preparing the Environment](usbSerial-overview.md#preparing-the-environment) in *USB Serial Communication Development Overview*.
+
+## How to Develop
+
+### Available APIs
+
+| API | Description |
+|------------------------------------------------------------------------------|--------------------------|
+| getPortList(): Readonly<SerialPort>[] | Obtains the serial port device list. |
+| hasSerialRight(portId: number): boolean | Checks whether the application has the permission to access the serial port device. |
+| requestSerialRight(portId: number): Promise<boolean> | Requests the permission to access the serial port device. |
+| open(portId: number): void | Opens a serial port device. |
+| close(portId: number): void | Closes a serial port device. |
+| read(portId: number, buffer: Uint8Array, timeout?: number): Promise<number> | Reads data from a serial port device. This API uses a promise to return the result.|
+| readSync(portId: number, buffer: Uint8Array, timeout?: number): number | Reads data from a serial port device in a synchronous manner. |
+| write(portId: number, buffer: Uint8Array, timeout?: number): Promise<number> | Writes data to a serial port device. This API uses a promise to return the result.|
+| writeSync(portId: number, buffer: Uint8Array, timeout?: number): number | Writes data to a serial port device in a synchronous manner. |
+
+
+### Development Procedure
+
+You can read and write data as follows:
+
+1. Import the **usbManager** module.
+
+ ```ts
+ // Import the usbManager module.
+ import serial from '@ohos.usbManager.serial';
+ import { buffer } from '@kit.ArkTS';
+ ```
+
+2. Obtain the USB device list.
+
+ ```ts
+ // Obtain the list of USB devices connected to the host.
+ let portList: serial.SerialPort[] = serial.getPortList();
+ console.info('usbSerial portList: ' + JSON.stringify(portList));
+ if (portList === undefined || portList.length === 0) {
+ console.info('usbSerial portList is empty');
+ return;
+ }
+ ```
+
+3. Obtain the device operation permissions.
+
+ ```ts
+ // Check whether the first USB device in the list has the access permission.
+ let portId: number = portList[0].portId;
+ if (!serial.hasSerialRight(portId)) {
+ await serial.requestSerialRight(portId).then(result => {
+ if(!result) {
+ // If the device does not have the access permission and is not granted by the user, the device exits.
+ console.info('usbSerial user is not granted the operation permission');
+ return;
+ }
+ });
+ }
+ ```
+
+4. Open the device based on the serial port.
+
+ ```ts
+ try {
+ serial.open(portId)
+ console.info('open usbSerial success, portId: ' + portId);
+ } catch (error) {
+ console.error('open usbSerial error, ' + JSON.stringify(error));
+ }
+ ```
+
+5. Read data through the serial port.
+
+ ```ts
+ // Read data asynchronously.
+ let readBuffer: Uint8Array = new Uint8Array(64);
+ serial.read(portId, readBuffer, 2000).then((size: number) => {
+ console.info('read usbSerial success, readBuffer: ' + readBuffer.toString());
+ }).catch((error: Error) => {
+ console.error('read usbSerial error, ' + JSON.stringify(error));
+ })
+
+ // Read data synchronously.
+ let readSyncBuffer: Uint8Array = new Uint8Array(64);
+ try {
+ serial.readSync(portId, readSyncBuffer, 2000);
+ console.info('readSync usbSerial success, readSyncBuffer: ' + readSyncBuffer.toString());
+ } catch (error) {
+ console.error('readSync usbSerial error, ' + JSON.stringify(error));
+ }
+ ```
+
+6. Write data through the serial port.
+
+ ```ts
+ // Write data asynchronously.
+ let writeBuffer: Uint8Array = new Uint8Array(buffer.from('Hello World', 'utf-8').buffer)
+ serial.write(portId, writeBuffer, 2000).then((size: number) => {
+ console.info('write usbSerial success, writeBuffer: ' + writeBuffer.toString());
+ }).catch((error: Error) => {
+ console.error('write usbSerial error, ' + JSON.stringify(error));
+ })
+
+ // Write data synchronously.
+ let writeSyncBuffer: Uint8Array = new Uint8Array(buffer.from('Hello World', 'utf-8').buffer)
+ try {
+ serial.writeSync(portId, writeSyncBuffer, 2000);
+ console.info('writeSync usbSerial success, writeSyncBuffer: ' + writeSyncBuffer.toString());
+ } catch (error) {
+ console.error('writeSync usbSerial error, ' + JSON.stringify(error));
+ }
+ ```
+
+7. Close a serial port device.
+
+ ```ts
+ try {
+ serial.close(portId);
+ console.info('close usbSerial success, portId: ' + portId);
+ } catch (error) {
+ console.error('close usbSerial error, ' + JSON.stringify(error));
+ }
+ ```
+
+### Debugging and Verification
+
+1. Prepare a USB-to-serial cable. Connect the USB port and the serial port of the cable to that of the OpenHarmony device.
+2. Execute the preceding sample code on the OpenHarmony device.
+3. Return **usbSerial success** if the related API is successfully called and the serial port communication of the device runs properly; return **usbSerial error** otherwise.
diff --git a/en/application-dev/basic-services/usb/usbserial/usbSerial-configuration.md b/en/application-dev/basic-services/usb/usbserial/usbSerial-configuration.md
new file mode 100644
index 0000000000000000000000000000000000000000..578792167a9b89b1f075960aef7f2bce5a2c1fec
--- /dev/null
+++ b/en/application-dev/basic-services/usb/usbserial/usbSerial-configuration.md
@@ -0,0 +1,128 @@
+# USB Serial Configuration Management
+
+## Overview
+
+In the USB serial configuration management, the baud rate, data bit, parity bit, and stop bit are the core parameters of the serial port communication protocol. They define the format and rules of data transmission. By properly setting these parameters, you can significantly improve the reliability and efficiency of serial port communication.
+
+### Basic Concepts
+
+Before developing the USB serial port, you should have a basic understanding of the following concepts:
+
+- Baud rate
+
+ The baud rate indicates the number of symbols transmitted by a serial port device per second. A symbol is a binary bit, including the data bit, start bit, stop bit, and parity bit. The unit is baud. For example, 9600 baud indicates that 9600 symbols are transmitted per second. The sender and receiver must use the same baud rate. Otherwise, data cannot be correctly parsed.
+
+
+- Data bit
+
+ The data bit indicates the number of valid binary bits actually transmitted in each data packet, which determines the data capacity of a single character. Commonly, a data bit may consist of five to eight digits. The data bit determines the amount of information transmitted at a time. The more the data bits, the larger the amount of information transmitted at a time, but more time is required for synchronization.
+
+
+- Parity bit
+
+ A parity bit is a 1-bit binary value appended to a data frame. It is generated based on the content of the data bit according to specific rules. Commonly, for an odd parity check, the total number of **1** in the data bits and parity bit is an odd number; for an even parity check, the total number of **1** is an even number; for no parity check, no parity bit is added to the data bit. By verifying the number of **1** in the data bit, the parity bit determines whether errors such as bit flipping and noise interference occur during data transfer. Increasing the parity bit slightly reduces the transfer efficiency but improves the error tolerance.
+
+
+- Stop bit
+
+ The stop bit is located at the end of a data frame. It is a logic high-level signal and is used to identify the end of a character (data packet) transfer. Its length can be 1 bit, 1.5 bits, or 2 bits. (In actual development, 1 bit is most commonly used, and 1.5 bits and 2 bits are mainly used in anti-interference scenarios.) A core function of this bit is to provide a space to tolerate the errors that may occur during time-sequence synchronization for a receiver and ensure data integrity.
+
+
+## Preparing the Environment
+
+For details, see [Preparing the Environment](usbSerial-overview.md#preparing-the-environment) in *USB Serial Communication Development Overview*.
+
+## How to Develop
+
+### Available APIs
+
+| API | Description |
+|------------------------------------------------------------------------------|-----------|
+| getAttribute(portId: number): Readonly<SerialAttribute> | Obtains the serial port device configuration.|
+| setAttribute(portId: number, attribute: SerialAttribute): void | Sets the serial port device configuration.|
+
+### Development Procedure
+
+You can obtain and set the serial port configuration as follows:
+
+1. Import the **usbManager** module.
+
+ ```ts
+ // Import the usbManager module.
+ import serial from '@ohos.usbManager.serial';
+ ```
+
+2. Obtain the USB device list.
+
+ ```ts
+ // Obtain the list of USB devices connected to the host.
+ let portList: serial.SerialPort[] = serial.getPortList();
+ console.info('usbSerial portList: ' + JSON.stringify(portList));
+ if (portList === undefined || portList.length === 0) {
+ console.info('usbSerial portList is empty');
+ return;
+ }
+ ```
+
+3. Obtain the device operation permissions.
+
+ ```ts
+ // Check whether the first USB device in the list has the access permission.
+ let portId: number = portList[0].portId;
+ if (!serial.hasSerialRight(portId)) {
+ await serial.requestSerialRight(portId).then(result => {
+ if(!result) {
+ // If the device does not have the access permission and is not granted by the user, the device exits.
+ console.info('usbSerial user is not granted the operation permission');
+ return;
+ }
+ });
+ }
+ ```
+
+4. Open the device based on the serial port.
+
+ ```ts
+ try {
+ serial.open(portId)
+ console.info('open usbSerial success, portId: ' + portId);
+ } catch (error) {
+ console.error('open usbSerial error, ' + JSON.stringify(error));
+ }
+ ```
+
+5. Obtain and modify serial port configurations.
+
+ ```ts
+ // Obtain the serial port configuration.
+ try {
+ let attribute: serial.SerialAttribute = serial.getAttribute(portId);
+ if (attribute === undefined) {
+ console.error('getAttribute usbSerial error, attribute is undefined');
+ } else {
+ console.info('getAttribute usbSerial success, attribute: ' + JSON.stringify(attribute));
+ }
+ } catch (error) {
+ console.error('getAttribute usbSerial error, ' + JSON.stringify(error));
+ }
+
+ // Set the serial port configuration.
+ try {
+ let attribute: serial.SerialAttribute = {
+ baudRate: serial.BaudRates.BAUDRATE_9600,
+ dataBits: serial.DataBits.DATABIT_8,
+ parity: serial.Parity.PARITY_NONE,
+ stopBits: serial.StopBits.STOPBIT_1
+ }
+ serial.setAttribute(portId, attribute);
+ console.info('setAttribute usbSerial success, attribute: ' + JSON.stringify(attribute));
+ } catch (error) {
+ console.error('setAttribute usbSerial error, ' + JSON.stringify(error));
+ }
+ ```
+
+### Debugging and Verification
+
+1. Prepare a USB-to-serial cable. Connect the USB port and the serial port of the cable to that of the OpenHarmony device.
+2. Execute the preceding sample code on the OpenHarmony device.
+3. Return **getAttribute usbSerial success** and **setAttribute usbSerial success** if related APIs are successfully called. You can view the current serial port configuration.
diff --git a/en/application-dev/basic-services/usb/usbserial/usbSerial-overview.md b/en/application-dev/basic-services/usb/usbserial/usbSerial-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..8b93123b3a2572d3c94938b4e4237c9df32c7c3c
--- /dev/null
+++ b/en/application-dev/basic-services/usb/usbserial/usbSerial-overview.md
@@ -0,0 +1,62 @@
+# USB Serial Communication Development Overview
+
+## Overview
+
+The USB serial communication service provides the USB host-to-serial port communication. With this service, you can obtain the list of connected ports that comply with the USB host-to-serial protocol and be able to enable and disable ports, set parameters, obtain parameters, read data, write data, and manage device permissions.
+
+For details about configuration management and communication management, see [USB Serial Configuration Management](usbSerial-configuration.md) and [USB Serial Communication Management](usbSerial-communication.md) respectively.
+
+### Basic Concepts
+
+Before developing the service, you should have a basic understanding of the following concepts:
+
+- Serial port
+
+ It is an expansion interface that uses serial communication, where data is transmitted sequentially one bit at a time. The serial port features simple communication lines. Only one pair of transmission lines is required to implement a two-way communication in a long distance.
+
+### Implementation Principles
+
+The USB serial port service consists of two phases:
+
+- Identify the device and load the driver.
+
+ After a USB-to-serial device is inserted, the USB host initiates an enumeration process over the USB bus to obtain the device descriptor (such as the vendor ID, device ID, and USB identifier of the communication device class). The OS matches the driver based on the descriptor to initialize the device and register the virtual serial port.
+
+- Transmit and receive data.
+
+ Transmitting data:
+ The application layer sends data. → The driver transmits the data to the device through the USB channel. → The device parses the data and sends the data to the serial port device through the physical serial port.
+
+ Receiving data:
+ The device receives the data from the physical serial port. → The device packages and uploads data to the USB host. → The driver receives and stores data in the serial port buffer. → The application layer reads the data.
+
+
+**Figure 1** Process of transmitting and receiving data
+
+
+
+### Constraints
+
+- Before data transmission between the host and the serial port device, you need to request a permission to access the device. Data can be transmitted only after the user grants the permission.
+
+- If the configuration parameters during data transmission are not set, the default configuration parameters are used (baud rate: 9600 bit/s; data bit: 8; parity bit: 0; stop bit: 1).
+
+## Preparing the Environment
+
+### Environment Requirements
+
+- Development tool and configuration:
+
+ As a development tool, DevEco Studio is a prerequisite for developing the USB serial communication service. You can use DevEco Studio to perform development, debugging, and packaging. [Download and install](https://developer.huawei.com/consumer/cn/download/) DevEco Studio and verify basic operations to ensure that it can function properly. For details, see [Creating and Running a Project](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-create-new-project-V14) in [DevEco Studio User Guide](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/ide-tools-overview-V14).
+
+- SDK version configuration:
+
+ API version 18 or later.
+
+### Environment Setup
+
+- Install [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 4.1 or later on the PC.
+- Update the public-SDK to API version 18 or later. For details, see [OpenHarmony SDK Upgrade Assistant](../../../tools/openharmony_sdk_upgrade_assistant.md).
+- Prepare a USB-to-serial cable. Connect the USB port and the serial port of the cable to that of the OpenHarmony device.
+
+
\ No newline at end of file
diff --git a/en/application-dev/calendarmanager/calendarmanager-calendar-developer.md b/en/application-dev/calendarmanager/calendarmanager-calendar-developer.md
index 4c42cb800c49a6bf5e89d955653ad40293cf4206..00d6bb3b11e9dd9960644bcb38d9a3d0685d88c4 100644
--- a/en/application-dev/calendarmanager/calendarmanager-calendar-developer.md
+++ b/en/application-dev/calendarmanager/calendarmanager-calendar-developer.md
@@ -11,15 +11,15 @@ You can create an application-specific calendar, and add, delete, update, and qu
The table below lists the main APIs used for calendar management. For details about more APIs and their usage, see [@ohos.calendarManager](../reference/apis-calendar-kit/js-apis-calendarManager.md).
| API | Description |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| getCalendarManager(context : Context): CalendarManager | Obtains the **CalendarManager** object based on the context to manage calendars. |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| getCalendarManager(context: Context): CalendarManager | Obtains the **CalendarManager** object based on the context to manage calendars. |
| createCalendar(calendarAccount: CalendarAccount): Promise\ | Creates a **Calendar** object based on the calendar account information. This API uses a promise to return the result.|
| getCalendar(calendarAccount?: CalendarAccount): Promise\ | Obtains the default or specified **Calendar** object. This API uses a promise to return the result.
The default **Calendar** object is created when the data storage runs for the first time. You can call this API instead of **createCalendar()** to use the default calendar for a new event.|
-| getAllCalendars(): Promise\ | Obtains the created and default **Calendar** objects of the current application. This API uses a promise to return the result.|
-| deleteCalendar(calendar: Calendar): Promise\ | Deletes a specified **Calendar** object. This API uses a promise to return the result. |
-| getConfig(): CalendarConfig | Obtains the calendar configuration information. |
-| setConfig(config: CalendarConfig): Promise\ | Sets the calendar configuration information. This API uses a promise to return the result. |
-| getAccount(): CalendarAccount | Obtains the calendar account information. |
+| getAllCalendars(): Promise\ | Obtains the created and default **Calendar** objects of the current application. This API uses a promise to return the result.|
+| deleteCalendar(calendar: Calendar): Promise\ | Deletes a specified **Calendar** object. This API uses a promise to return the result. |
+| getConfig(): CalendarConfig | Obtains the calendar configuration information. |
+| setConfig(config: CalendarConfig): Promise\ | Sets the calendar configuration information. This API uses a promise to return the result. |
+| getAccount(): CalendarAccount | Obtains the calendar account information. |
## How to Develop
@@ -67,7 +67,7 @@ The table below lists the main APIs used for calendar management. For details ab
const permissions: Permissions[] = ['ohos.permission.READ_CALENDAR', 'ohos.permission.WRITE_CALENDAR'];
let atManager = abilityAccessCtrl.createAtManager();
atManager.requestPermissionsFromUser(mContext, permissions).then((result: PermissionRequestResult) => {
- console.log(`get Permission success, result: ${JSON.stringify(result)}`);
+ console.info(`get Permission success, result: ${JSON.stringify(result)}`);
calendarMgr = calendarManager.getCalendarManager(mContext);
}).catch((error: BusinessError) => {
console.error(`get Permission error, error. Code: ${error.code}, message: ${error.message}`);
@@ -150,7 +150,7 @@ The table below lists the main APIs used for calendar management. For details ab
}).catch((err: BusinessError) => {
console.error(`Failed to get calendar. Code: ${err.code}, message: ${err.message}`);
});
- ```
+ ```
7. Query a default calendar. The default **Calendar** object is created when the data storage runs for the first time. You can use the default calendar for a new event.
@@ -161,7 +161,7 @@ The table below lists the main APIs used for calendar management. For details ab
}).catch((err: BusinessError) => {
console.error(`Failed to get calendar. Code: ${err.code}, message: ${err.message}`);
});
- ```
+ ```
8. Obtain the created and default **Calendar** objects of the current application.
@@ -189,4 +189,4 @@ The table below lists the main APIs used for calendar management. For details ab
}).catch((err: BusinessError) => {
console.error(`Failed to delete calendar. Code: ${err.code}, message: ${err.message}`);
});
- ```
+ ```
diff --git a/en/application-dev/calendarmanager/calendarmanager-event-developer.md b/en/application-dev/calendarmanager/calendarmanager-event-developer.md
index 89287df1f2bd1e5070c2e3f62655086e2b01af60..73c45066d6ce9965fa9bebc4233a522964719e56 100644
--- a/en/application-dev/calendarmanager/calendarmanager-event-developer.md
+++ b/en/application-dev/calendarmanager/calendarmanager-event-developer.md
@@ -10,14 +10,14 @@ After obtaining the **Calendar** object, you can create, delete, modify and quer
The table below lists the main APIs used for event management. For details about more APIs and their usage, see [@ohos.calendarManager](../reference/apis-calendar-kit/js-apis-calendarManager.md).
-| API | Description |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| getCalendarManager(context : Context): CalendarManager | Obtains a **CalendarManager** object based on the context. |
+| API | Description |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| getCalendarManager(context: Context): CalendarManager | Obtains a **CalendarManager** object based on the context. |
| createCalendar(calendarAccount: CalendarAccount): Promise\ | Creates a **Calendar** object based on the calendar account information. This API uses a promise to return the result.|
-| addEvent(event: Event): Promise\ | Creates an event, with no event ID specified in **Event**. This API uses a promise to return the result. |
-| editEvent(event: Event): Promise\ | Creates a single event. If the input parameter **Event** is not set to the event ID, the event creation screen is displayed when this API is called. This API uses a promise to return the result.|
-| deleteEvent(id: number): Promise\ | Deletes an event with the specified ID. This API uses a promise to return the result. |
-| updateEvent(event: Event): Promise\ | Updates an event. This API uses a promise to return the result. |
+| addEvent(event: Event): Promise\ | Creates an event, with no event ID specified in **Event**. This API uses a promise to return the result. |
+| editEvent(event: Event): Promise\ | Creates a single event. If the input parameter **Event** is not set to the event ID, the event creation screen is displayed when this API is called. This API uses a promise to return the result.|
+| deleteEvent(id: number): Promise\ | Deletes an event with the specified ID. This API uses a promise to return the result. |
+| updateEvent(event: Event): Promise\ | Updates an event. This API uses a promise to return the result. |
| getEvents(eventFilter?: EventFilter, eventKey?: (keyof Event)[]): Promise\ | Obtains all events in a calendar that match the filter criteria. This API uses a promise to return the result. |
## How to Develop
@@ -65,7 +65,7 @@ The table below lists the main APIs used for event management. For details about
const permissions: Permissions[] = ['ohos.permission.READ_CALENDAR', 'ohos.permission.WRITE_CALENDAR'];
let atManager = abilityAccessCtrl.createAtManager();
atManager.requestPermissionsFromUser(mContext, permissions).then((result: PermissionRequestResult) => {
- console.log(`get Permission success, result: ${JSON.stringify(result)}`);
+ console.info(`get Permission success, result: ${JSON.stringify(result)}`);
calendarMgr = calendarManager.getCalendarManager(mContext);
}).catch((error: BusinessError) => {
console.error(`get Permission error, error. Code: ${error.code}, message: ${error.message}`);
@@ -138,7 +138,7 @@ The table below lists the main APIs used for event management. For details about
Currently, you can create an event in either of the following methods:
- Method 1: Use **addEvent()** to create a single event or use **addEvents()** to create events in batches under a calendar account. The following describes how to create a single event.
+ Method 1: Use **addEvent()** to create a single event or **addEvents()** to create events in batches. The following describes how to create a single event.
Method 2: After obtaining the **calendarManager** object, you can use **editEvent()** to create a single event. In this case, the event creation page is displayed, where you can perform related operations to create an event. Note that **editEvent()** does not support the creation of custom periodic events.
@@ -265,7 +265,7 @@ The table below lists the main APIs used for event management. For details about
});
```
-8. Delete a specified event by event ID. You can use the **deleteEvent()** API to create a single event or use the **deleteEvents()** API to delete events in batches. The following describes how to delete a single event.
+8. Delete a specified event by event ID. You can use **deleteEvent()** to create a single event or use **deleteEvents()** to delete events in batches. The following describes how to delete a single event.
```ts
// Index.ets
diff --git a/en/application-dev/calendarmanager/calendarmanager-overview.md b/en/application-dev/calendarmanager/calendarmanager-overview.md
index 33285a2375bd67f7df4bfc3e78b9860cfd4e1d74..bc1a2c9f3f4336378fbc97d9cdfd3dd575c4873d 100644
--- a/en/application-dev/calendarmanager/calendarmanager-overview.md
+++ b/en/application-dev/calendarmanager/calendarmanager-overview.md
@@ -1,19 +1,51 @@
# Introduction to Calendar Kit
-## Key Concepts
+Calendar Kit provides calendar and event management capabilities, which usually refer to APIs that can be used to access and operate calendar data. These APIs allow you to integrate time-related event services (such as travel, catering, sports, and entertainment) in other applications with the system calendar to implement functions such as event management, creation, and query.
-Calendar: a tool used to record dates, holidays, and important events.
+## Available Capabilities
-## Introduction
+Calendar Kit provides management capability for accounts and events.
-Calendar Kit provides calendar and event management capabilities, including capabilities to obtain and create calendar events. A **CalendarManager** object is used to manage **Calendar** objects. A **Calendar** object contains the account information (**CalendarAccount**) and configuration information (**CalendarConfig**). Calendars and events are in the one-to-many relationship. That is, a calendar can have multiple events, but an event belongs to only one calendar.
+- Create a calendar account.
+
+ You can create a calendar account specific to your application, after which an account ID is returned. The account ID is the auto-increment primary key of the data table and is used as the unique identifier of the account.
+
+- Obtain the calendar account.
+
+ You can obtain information about a specified calendar account or all calendar accounts created by the current application.
+
+- Delete a calendar account.
+
+ You can delete a specified calendar account, after which all events associated with the calendar account will be deleted.
+
+- Create a calendar event.
+
+ After obtaining the calendar account information, you can create an event under the obtained calendar account. When creating an event, you can set an event reminder and its notification is displayed when the set time arrives.
+
+ After a calendar account is created, an account ID is returned. The account ID is the auto-increment primary key of the data table and is used as the unique identifier of the account.
+
+- Delete an event.
+
+ You can delete one or more events with specified event IDs at a time.
+
+- Update an event.
+
+ You can update event information based on the event ID, including the event title, location, start time, end time, and reminder time.
+
+- Query events.
+
+ You can query events by event ID, event title, event start time, and event end time.
+
+## Features
+
+**One-click event service**: With the permanent authorization mechanism, after the user allows your application to read and write the system calendar, the corresponding event service can be written into the calendar in the form of deeplink. According to the reminder rules set by yourself, when an event is about to expire or expires, the corresponding service button will be displayed in the calendar application, notification, and widgets. Users can tap the button to redirect to the service landing page in one step.
## Working Principles
-Calendar Kit provides a set of APIs for obtaining calendar accounts and writing calendar events to the obtained accounts. If an event has a reminder time set, the system sends a reminder to the user when the set time arrives.
+Calendar Kit provides a set of APIs for obtaining calendar accounts, and writing calendar events to or reading events from the obtained accounts. If an event has a reminder time set, the system sends a reminder to the user when the set time arrives.
## Constraints
-- Calendar Kit requires manual authorization from the user for the permissions to read and write calendar events.
+- To use the capabilities of Calendar Kit, you need to obtain the **ohos.permission.READ_CALENDAR** and **ohos.permission.WRITE_CALENDAR** permissions to read or write calendars and events. For details, see [Declaring Permissions](../security/AccessToken/declare-permissions.md).
-- Calendar Kit is only available in the stage model.
+- Currently, the capabilities and APIs of Calendar Kit can be used only in the stage model.
diff --git a/en/application-dev/connectivity/Readme-EN.md b/en/application-dev/connectivity/Readme-EN.md
index a349609ea828b0c0a7feb3e7312a60d93afbc3b0..179cc92dc7f5867c18ceafd536a2865c3de9d379 100755
--- a/en/application-dev/connectivity/Readme-EN.md
+++ b/en/application-dev/connectivity/Readme-EN.md
@@ -1,16 +1,16 @@
-# Connectivity Kit (Short-Range Communication Service)
+# Connectivity Kit
- [Introduction to Connectivity Kit](connectivity-kit-intro.md)
-- Bluetooth
+- Bluetooth
- [Bluetooth Overview](bluetooth/bluetooth-overview.md)
- [Bluetooth Setting Development](bluetooth/br-development-guide.md)
- [BLE Development](bluetooth/ble-development-guide.md)
- [GATT Development](bluetooth/gatt-development-guide.md)
- [SPP Development](bluetooth/spp-development-guide.md)
-- NFC
+- NFC
- [NFC Tag Read/Write Development](nfc/nfc-tag-access-guide.md)
- [HCE Development](nfc/nfc-hce-guide.md)
- [SE Access Development](nfc/nfc-se-access-guide.md)
-- WLAN
+- WLAN
- [WLAN Service Development Overview](wlan/wlan-overview.md)
- - [P2P Mode Development](wlan/p2p-development-guide.md)
+ - [P2P Development Guide](wlan/p2p-development-guide.md)
diff --git a/en/application-dev/connectivity/bluetooth/Readme-EN.md b/en/application-dev/connectivity/bluetooth/Readme-EN.md
index 37cd9847b51c1a13e73633994173952dd80bf73a..58d61e8effbfb94216f34aae9ca531c5ec922441 100644
--- a/en/application-dev/connectivity/bluetooth/Readme-EN.md
+++ b/en/application-dev/connectivity/bluetooth/Readme-EN.md
@@ -1,6 +1,6 @@
- # Bluetooth
+# Bluetooth
- [Bluetooth Overview](bluetooth-overview.md)
- [Bluetooth Setting Development](br-development-guide.md)
- [BLE Development](ble-development-guide.md)
- [GATT Development](gatt-development-guide.md)
- - [SPP Development](spp-development-guide.md)
+ - [SPP Development](spp-development-guide.md)
\ No newline at end of file
diff --git a/en/application-dev/connectivity/bluetooth/gatt-development-guide.md b/en/application-dev/connectivity/bluetooth/gatt-development-guide.md
index cc3ff935152e9627024f8ad282035f05f3524dd4..4d0ff29cc951ced93b6fa18b3d10eed6d5ddb1ce 100644
--- a/en/application-dev/connectivity/bluetooth/gatt-development-guide.md
+++ b/en/application-dev/connectivity/bluetooth/gatt-development-guide.md
@@ -1,7 +1,9 @@
# GATT Development
## Introduction
-Generic Attribute Profile (GATT) provides profile discovery and description services for BLE protocol. It defines how ATT attributes are organized and exchanged over a BLE connection.
A GATT server (referred to as server in this topic) is a device that stores attribute data locally and provides data access to a remote GATT client paired via BLE. A GATT client (referred to as client in this topic) is a device that accesses data on the remote GATT server via read, write, notify, or indicate operations.
+Generic Attribute Profile (GATT) provides profile discovery and description services for BLE protocol. It defines how ATT attributes are organized and exchanged over a BLE connection.
+
+A GATT server (referred to as server in this topic) is a device that stores attribute data locally and provides data access to a remote GATT client paired via BLE. A GATT client (referred to as client in this topic) is a device that accesses data on the remote GATT server via read, write, notify, or indicate operations.
## When to Use
@@ -63,7 +65,7 @@ The following table describes the related APIs.
4. Read characteristics and descriptors from the server.
5. Write characteristics and descriptors to the server.
6. Disconnect from the server and destroy the **gattClient** instance.
-7. Example:
+Example:
```ts
import { ble } from '@kit.ConnectivityKit';
@@ -351,7 +353,7 @@ The following table describes the related APIs.
export default gattClientManager as GattClientManager;
```
-9. For details about the error codes, see [Bluetooth Error Codes](../../reference/apis-connectivity-kit/errorcode-bluetoothManager.md).
+For details about the error codes, see [Bluetooth Error Codes](../../reference/apis-connectivity-kit/errorcode-bluetoothManager.md).
### Managing Services on the Server and Notifying the Client
@@ -361,7 +363,7 @@ The following table describes the related APIs.
4. Notify the client after a characteristic is written to the server.
5. Remove services.
6. Close the gattServer instance.
-7. Example:
+Example:
```ts
import { ble } from '@kit.ConnectivityKit';
@@ -636,4 +638,4 @@ The following table describes the related APIs.
export default gattServerManager as GattServerManager;
```
-8. For details about the error codes, see [Bluetooth Error Codes](../../reference/apis-connectivity-kit/errorcode-bluetoothManager.md).
+For details about the error codes, see [Bluetooth Error Codes](../../reference/apis-connectivity-kit/errorcode-bluetoothManager.md).
diff --git a/en/application-dev/connectivity/bluetooth/spp-development-guide.md b/en/application-dev/connectivity/bluetooth/spp-development-guide.md
index b2bd9ac27ca96812714cacc24cbcbb49a909f4a3..8ef5b5c53d434e20d439f3a8c8e49af24fdb6cb1 100644
--- a/en/application-dev/connectivity/bluetooth/spp-development-guide.md
+++ b/en/application-dev/connectivity/bluetooth/spp-development-guide.md
@@ -38,7 +38,7 @@ The following table describes the related APIs.
7. (Optional) Subscribe to the data written by the client.
8. Close the server socket.
9. Close the client socket.
-10. Example:
+Example:
```ts
import { socket } from '@kit.ConnectivityKit';
@@ -112,7 +112,7 @@ The following table describes the related APIs.
console.info('sppCloseClientSocket success');
```
-11. For details about the error codes, see [Bluetooth Error Codes](../../reference/apis-connectivity-kit/errorcode-bluetoothManager.md).
+For details about the error codes, see [Bluetooth Error Codes](../../reference/apis-connectivity-kit/errorcode-bluetoothManager.md).
### Connecting to the Peer Device over a Socket
1. Import the **socket** module.
@@ -120,7 +120,7 @@ The following table describes the related APIs.
3. Enable Bluetooth on the device.
4. Start Bluetooth scanning to obtain the MAC address of the peer device.
5. Connect to the peer device.
-6. Example:
+Example:
```ts
import { socket } from '@kit.ConnectivityKit';
@@ -143,4 +143,4 @@ The following table describes the related APIs.
})
```
-7. For details about the error codes, see [Bluetooth Error Codes](../../reference/apis-connectivity-kit/errorcode-bluetoothManager.md).
+For details about the error codes, see [Bluetooth Error Codes](../../reference/apis-connectivity-kit/errorcode-bluetoothManager.md).
diff --git a/en/application-dev/connectivity/nfc/Readme-EN.md b/en/application-dev/connectivity/nfc/Readme-EN.md
index 4be7067f6380d287fc8f3f86181ab765f831bd37..02089c9d307089143c4f94375f87cd004f816c70 100644
--- a/en/application-dev/connectivity/nfc/Readme-EN.md
+++ b/en/application-dev/connectivity/nfc/Readme-EN.md
@@ -1,4 +1,4 @@
- # NFC
+# NFC
- [NFC Tag Read/Write Development](nfc-tag-access-guide.md)
- [HCE Development](nfc-hce-guide.md)
- [SE Access Development](nfc-se-access-guide.md)
diff --git a/en/application-dev/connectivity/nfc/nfc-hce-guide.md b/en/application-dev/connectivity/nfc/nfc-hce-guide.md
index a20a5e0e66ff70cb6f45da3872488d9396ead22f..c8878db914649655891f2dbf22f791df736d5fab 100644
--- a/en/application-dev/connectivity/nfc/nfc-hce-guide.md
+++ b/en/application-dev/connectivity/nfc/nfc-hce-guide.md
@@ -5,21 +5,12 @@ Near Field Communication (NFC) is a high-frequency radio technology that enables
## When to Use
An application emulates a card and communicates with an NFC card reader through the NFC service. The device can communicate with an NFC card reader by using a started application (foreground mode) or without starting an application (background mode).
-- HCE foreground mode
-
- The application started by the user communicates with the NFC card reader. Specifically, the user starts the application, opens the application page, and taps the device on the NFC card reader. In this case, the transaction data is distributed only to the foreground application.
-
-- HCE background mode
-
- The user taps the device on an NFC card reader without starting any HCE application. Then, the device selects an HCE application based on the application ID (AID) provided by the NFC card reader, and completes the card swiping transaction. If multiple HCE applications are matched, an application selector will be displayed, listing all the available applications for the user to choose.
-
-- Constraints
-
- No matter whether the foreground mode or background mode is used, the NFC service can be implemented only when the device screen is unlocked and illuminated.
-
- The permission for NFC card emulation must be declared in the **module.json5** file. For details, see the example below.
-
- The foreground application needs to call **start()** to register AIDs and call **stop()** to release the registered AIDs. For details, see the example below.
+- HCE foreground mode
+The application started by the user communicates with the NFC card reader. Specifically, the user starts the application, opens the application page, and taps the device on the NFC card reader. In this case, the transaction data is distributed only to the foreground application.
+- HCE background mode
+The user taps the device on an NFC card reader without starting any HCE application. Then, the device selects an HCE application based on the application ID (AID) provided by the NFC card reader, and completes the card swiping transaction. If multiple HCE applications are matched, an application selector will be displayed, listing all the available applications for the user to choose.
+- Constraints
+1. No matter whether the foreground mode or background mode is used, the NFC service can be implemented only when the device screen is unlocked and illuminated.
2. The the NFC card emulation permission must be declared in the **module.json5** file. For details, see the example below.
3. For foreground applications, the **start** and **stop** functions need to be called to register and deregister the AID. See the following development example for details.
## Available APIs
@@ -30,8 +21,8 @@ The following table describes the APIs for implementing HCE.
| API | Description |
| ---------------------------------- | ------------------------------------------------------------------------------ |
| start(elementName: ElementName, aidList: string[]): void | Starts HCE, including enabling this application to run in the foreground preferentially and dynamically registering the AID list. |
-| stop(elementName: ElementName): void | Stops HCE, including canceling the subscription of APDU data, exiting this application from the foreground, and releasing the dynamically registered AID list.|
-| on(type: 'hceCmd', callback: AsyncCallback\): void | Registers a callback to receive APDUs from the peer card reader.|
+| stop(elementName: ElementName): void | Stops HCE, including canceling the subscription of APDU data, exiting this application from the foreground, and releasing the dynamically registered AID list.
+| on(type: 'hceCmd', callback: AsyncCallback\): void | Registers a callback to receive APDUs from the peer card reader.
| transmit(response: number[]): Promise\ | Transmits APDU data to the peer card reader.| |
## How to Develop
@@ -64,7 +55,7 @@ The following table describes the APIs for implementing HCE.
"actions": [
"action.system.home",
- // Add the nfc card emulation action to filter out for this application.
+ // Make sure that ohos.nfc.cardemulation.action.HOST_APDU_SERVICE is present in actions.
"ohos.nfc.cardemulation.action.HOST_APDU_SERVICE"
]
}
@@ -73,7 +64,7 @@ The following table describes the APIs for implementing HCE.
],
"requestPermissions": [
{
- // Add the permission for nfc card emulation.
+ // Add the permission required for NFC card emulation.
"name": "ohos.permission.NFC_CARD_EMULATION",
"reason": "$string:app_name",
}
@@ -132,7 +123,7 @@ export default class EntryAbility extends UIAbility {
}
onForeground() {
- // Ability is brought to foreground.
+ // Ability has brought to foreground
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
if (hceElementName != undefined) {
try {
@@ -270,7 +261,7 @@ export default class EntryAbility extends UIAbility {
}
onForeground() {
- // Ability is brought to foreground.
+ // Ability has brought to foreground
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
}
diff --git a/en/application-dev/connectivity/nfc/nfc-tag-access-guide.md b/en/application-dev/connectivity/nfc/nfc-tag-access-guide.md
index e4b587deff2c67c27d0ace2cd2a7213b7d5ca27a..9a7b8c245a4a14e11229020f78b7f07c135dbeaa 100644
--- a/en/application-dev/connectivity/nfc/nfc-tag-access-guide.md
+++ b/en/application-dev/connectivity/nfc/nfc-tag-access-guide.md
@@ -15,7 +15,7 @@ NFC tags support one or more communications technologies listed as follows:
## When to Use
An electronic device touches an NFC tag via the NFC antenna to read and write the NFC tag data. NFC tags can be read and written by a started application (foreground mode) on a device or without starting an application (background mode).
- Reading/Writing an NFC tag by a started application
-An application started on a device reads or writes the NFC tag. That is, the user starts the application to read and write the NFC tag. The user starts the application, opens the application page, and taps the device on the NFC tag. In this case, the tag data read can be distributed only to the foreground application.
+An application started on a device reads or writes the NFC tag. That is, the user starts the application to read and write the NFC tag. The user starts the application, opens the application page, and taps the device on the NFC tag. In this case, the retrieved tag data can be distributed only to the foreground application.
- Reading/Writing an NFC tag without starting an application
The user taps the device on an NFC tag without starting any application. Then, the device selects an application based on the type of the NFC tag technology. If multiple applications are matched, an application selector will be displayed, listing all the available applications for the user to choose. After the user selects an application, the NFC tag read/write page of the application is automatically displayed.
- Constraints
@@ -68,7 +68,7 @@ The following table describes the APIs for obtaining objects of the tags that us
"actions": [
"action.system.home",
- // Add the NFC tag action to match this application.
+ // Make sure that ohos.nfc.tag.action.TAG_FOUND is present in actions.
"ohos.nfc.tag.action.TAG_FOUND"
]
}
@@ -77,7 +77,7 @@ The following table describes the APIs for obtaining objects of the tags that us
],
"requestPermissions": [
{
- // Add the permission required for NFC tag operations.
+ // Add the NFC tag operation permission.
"name": "ohos.permission.NFC_TAG",
"reason": "$string:app_name",
}
@@ -110,7 +110,7 @@ async function readerModeCb(error : BusinessError, tagInfo : tag.TagInfo) {
}
// Read and write the tag data.
- // Use ISO-DEP to access this NFC tag.
+ // Access the NFC tag using IsoDep.
let isoDep : tag.IsoDepTag | null = null;
for (let i = 0; i < tagInfo.technology.length; i++) {
if (tagInfo.technology[i] == tag.ISO_DEP) {
@@ -121,14 +121,14 @@ async function readerModeCb(error : BusinessError, tagInfo : tag.TagInfo) {
return;
}
}
- // use other technology to access this nfc tag if necessary.
+ // Access the NFC tag using other technologies.
}
if (isoDep == undefined) {
hilog.error(0x0000, 'testTag', 'readerModeCb getIsoDep is invalid');
return;
}
- // Connect to this NFC tag using ISO-DEP.
+ // Connect to the NFC tag using IsoDep.
try {
isoDep.connect();
} catch (error) {
@@ -140,8 +140,8 @@ async function readerModeCb(error : BusinessError, tagInfo : tag.TagInfo) {
return;
}
- // Transmit data to the connected tag.
- let cmdData = [0x01, 0x02, 0x03, 0x04]; // please change the raw data to be correct.
+ // Send an instruction to the connected tag.
+ let cmdData = [0x01, 0x02, 0x03, 0x04]; // Specify the instruction of the protocol corresponding to the tag type.
try {
isoDep.transmit(cmdData).then((response : number[]) => {
hilog.info(0x0000, 'testTag', 'readerModeCb isoDep.transmit() response = %{public}s.', JSON.stringify(response));
@@ -176,7 +176,7 @@ export default class EntryAbility extends UIAbility {
}
onForeground() {
- // Ability is brought to foreground.
+ // Switch the application to the foreground.
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
if (nfcTagElementName != undefined) {
// Register a listener for the NFC tag read event so that the tag can be preferentially dispatched to a foreground application.
@@ -191,7 +191,7 @@ export default class EntryAbility extends UIAbility {
}
onBackground() {
- // Ability is back to background.
+ // Switch the application to the background.
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground');
// When exiting the NFC tag page of the application, call the tag module API to exit the foreground mode.
if (foregroundRegister) {
@@ -231,7 +231,7 @@ export default class EntryAbility extends UIAbility {
"actions": [
"action.system.home",
- // Add the NFC tag action to match this application.
+ // Make sure that ohos.nfc.tag.action.TAG_FOUND is present in actions.
"ohos.nfc.tag.action.TAG_FOUND"
],
"uris": [
@@ -241,8 +241,8 @@ export default class EntryAbility extends UIAbility {
{
"type":"tag-tech/IsoDep"
}
- // Add other technologies if necessary,
- // such as: NfcB/NfcF/NfcV/Ndef/MifareClassic/MifareUL/NdefFormatable
+ // Add other technologies if necessary.
+ // Example: NfcB/NfcF/NfcV/Ndef/MifareClassic/MifareUL/NdefFormatable
]
}
]
@@ -250,7 +250,7 @@ export default class EntryAbility extends UIAbility {
],
"requestPermissions": [
{
- // Add the permission required for NFC tag operations.
+ // Add NFC tag operation permission.
"name": "ohos.permission.NFC_TAG",
"reason": "$string:app_name",
}
@@ -290,7 +290,7 @@ export default class EntryAbility extends UIAbility {
}
// Read and write the tag data.
- // Use ISO-DEP to access this NFC tag.
+ // Access the NFC tag via IsoDep.
let isoDep : tag.IsoDepTag | null = null;
for (let i = 0; i < tagInfo.technology.length; i++) {
if (tagInfo.technology[i] == tag.ISO_DEP) {
@@ -301,14 +301,14 @@ export default class EntryAbility extends UIAbility {
return;
}
}
- // use other technology to access this nfc tag if necessary.
+ // Access the NFC tag using other technologies.
}
if (isoDep == undefined) {
hilog.error(0x0000, 'testTag', 'getIsoDep is invalid');
return;
}
- // Connect to this NFC tag using ISO-DEP.
+ // Connect to the NFC tag using IsoDep.
try {
isoDep.connect();
} catch (error) {
@@ -320,8 +320,8 @@ export default class EntryAbility extends UIAbility {
return;
}
- // Transmit data to the connected tag.
- let cmdData = [0x01, 0x02, 0x03, 0x04]; // please change the raw data to be correct.
+ // Send an instruction to the connected tag.
+ let cmdData = [0x01, 0x02, 0x03, 0x04]; // Specify the instruction of the protocol corresponding to the tag type.
try {
isoDep.transmit(cmdData).then((response : number[]) => {
hilog.info(0x0000, 'testTag', 'isoDep.transmit() response = %{public}s.', JSON.stringify(response));
diff --git a/en/application-dev/connectivity/wlan/Readme-EN.md b/en/application-dev/connectivity/wlan/Readme-EN.md
index 7bd988c69ec950012e0d60b40ca0da7cde900c87..2055733a92f0d8e658a85e922e4e4d322b849ca5 100644
--- a/en/application-dev/connectivity/wlan/Readme-EN.md
+++ b/en/application-dev/connectivity/wlan/Readme-EN.md
@@ -1,3 +1,4 @@
- # WLAN
+# WLAN
+
- [WLAN Service Development Overview](wlan-overview.md)
- [P2P Mode Development](p2p-development-guide.md)
diff --git a/en/application-dev/connectivity/wlan/wlan-overview.md b/en/application-dev/connectivity/wlan/wlan-overview.md
index ad4c4ef83d58812db7d9385f4c1e26d3716284f5..bb22656c186e89b631c1bd501aa7496def4c6b73 100644
--- a/en/application-dev/connectivity/wlan/wlan-overview.md
+++ b/en/application-dev/connectivity/wlan/wlan-overview.md
@@ -11,8 +11,14 @@ The WLAN system provides users with WLAN access (STA mode), peer-to-peer data tr
WLAN uses radio electromagnetic waves to transmit data. Currently, it operates in 2.4 GHz and 5 GHz bands. A WLAN involves both wired connections, in which the Ethernet protocol is used to connect access points (APs) to the Internet, and wireless connections, in which IEEE 802.11 is used to connect stations (STAs) and APs.
## WLAN Modes
-- STA mode: In STA mode, a Wi-Fi device, such as a smartphone or tablet, works as a client. It connects to a routing network, such as a home router, to access the Internet. For details, see [@ohos.wifiManager](../../reference/apis-connectivity-kit/js-apis-wifiManager.md).
+- STA mode
-- P2P mode (Wi-Fi Direct): The P2P mode is also referred to as Wi-Fi Direct, which allows a TCP/IP connection between two STAs without an AP. In a P2P connection, one STA functions as a traditional AP and is called a group owner (GO). The other STA is called a group client (GC), which is connected to the GO like an AP. For details, see [@ohos.wifiManager](../../reference/apis-connectivity-kit/js-apis-wifiManager.md).
+ In STA mode, a Wi-Fi device, such as a smartphone or tablet, works as a client. It connects to a routing network, such as a home router, to access the Internet. For details, see [@ohos.wifiManager](../../reference/apis-connectivity-kit/js-apis-wifiManager.md).
-- AP mode (hotspot mode): In AP mode, a Wi-Fi device acts as a wireless AP and creates its own network (hotspot) that other devices (STAs) can connect to. It allows multiple devices to connect simultaneously. For details, see [@ohos.wifiManager](../../reference/apis-connectivity-kit/js-apis-wifiManager.md).
+- P2P mode (Wi-Fi Direct)
+
+ The P2P mode is also referred to as Wi-Fi Direct, which allows a TCP/IP connection between two STAs without an AP. In a P2P connection, one STA functions as a traditional AP and is called a group owner (GO). The other STA is called a group client (GC), which is connected to the GO like an AP. For details, see [@ohos.wifiManager](../../reference/apis-connectivity-kit/js-apis-wifiManager.md).
+
+- AP mode (hotspot mode)
+
+ In AP mode, a Wi-Fi device acts as a wireless AP and creates its own network (hotspot) that other devices (STAs) can connect to. It allows multiple devices to connect simultaneously. For details, see [@ohos.wifiManager](../../reference/apis-connectivity-kit/js-apis-wifiManager.md).
diff --git a/en/application-dev/database/Readme-EN.md b/en/application-dev/database/Readme-EN.md
index d23b60222b581c7a54f937d1ebbc2af3fbf53f41..8af6068f201985545a5d7bfb05dd1a173fcf8988 100644
--- a/en/application-dev/database/Readme-EN.md
+++ b/en/application-dev/database/Readme-EN.md
@@ -1,36 +1,45 @@
# ArkData (Ark Data Management)
- [Introduction to ArkData](data-mgmt-overview.md)
-- Unified Data Definition
+- Unified Data Definition
- [Unified Data Definition Overview](unified-data-definition-overview.md)
- [UTDs](uniform-data-type-descriptors.md)
- [Uniform Data Structs](uniform-data-structure.md)
- [Prebuilt UTDs](uniform-data-type-list.md)
-- Application Data Persistence
+- Application Data Persistence
- [Application Data Persistence Overview](app-data-persistence-overview.md)
- [Persisting Preferences Data](data-persistence-by-preferences.md)
- [Persisting KV Store Data](data-persistence-by-kv-store.md)
- [Persisting RDB Store Data](data-persistence-by-rdb-store.md)
-- Distributed Application Data Sync
- - [Distributed Application Data Sync Overview](sync-app-data-across-devices-overview.md)
+ - [Persisting Vector Store Data (ArkTS)](data-persistence-by-vector-store.md)
+ - [Persisting Vector Store Data (C/C++)](native-vector-store-guidelines.md)
+
+ - [Persisting Graph Store Data (for System Applications Only)](data-persistence-by-graph-store.md)
+
+- Distributed Application Data Sync
+ - [Overview of Distributed Application Data Sync](sync-app-data-across-devices-overview.md)
- [Cross-Device Sync of KV Stores](data-sync-of-kv-store.md)
- [Cross-Device Sync of RDB Stores](data-sync-of-rdb-store.md)
- [Cross-Device Sync of Distributed Data Objects](data-sync-of-distributed-data-object.md)
-- Data Reliability and Security
+- Data Reliability and Security
- [Data Reliability and Security Overview](data-reliability-security-overview.md)
- [Database Backup and Restore](data-backup-and-restore.md)
- [Database Encryption](data-encryption.md)
- [Access Control by Device and Data Level](access-control-by-device-and-data-level.md)
- [Using an EL5 Database](encrypted_estore_guidelines.md)
-- Cross-Application Data Sharing
- - [Data Sharing Overview](data-share-overview.md)
+- Cross-Application Data Sharing
+ - [Overview of Cross-Application Data Sharing](data-share-overview.md)
- - One-to-Many Data Sharing (for System Applications Only)
+ - One-to-Many Data Sharing (for System Applications Only)
- [Sharing Data via DataShareExtensionAbility](share-data-by-datashareextensionability.md)
- [Silent Access via DatamgrService](share-data-by-silent-access.md)
- - Many-to-Many Data Sharing
- - [Sharing Data Using Unified Data Channels](unified-data-channels.md)
+ - Many-to-Many Data Sharing
+ - [Sharing Data via Unified Data Channels](unified-data-channels.md)
+- Intelligent Data Construction and Retrieval
+ - [AIP Overview](aip-data-intelligence-overview.md)
+ - [Application Data Vectorization](aip-data-intelligence-embedding.md)
- [RelationalStore Development (C/C++)](native-relational-store-guidelines.md)
- [UDMF Development Guide (C/C++)](native-unified-data-management-framework-guidelines.md)
- [Persisting User Preferences (C/C++)](preferences-guidelines.md)
+
diff --git a/en/application-dev/database/aip-data-intelligence-embedding.md b/en/application-dev/database/aip-data-intelligence-embedding.md
new file mode 100644
index 0000000000000000000000000000000000000000..d0ef8909c53fc95a93de5b11ed6b0626342d7586
--- /dev/null
+++ b/en/application-dev/database/aip-data-intelligence-embedding.md
@@ -0,0 +1,194 @@
+# Application Data Vectorization
+
+## When to Use
+
+Application data vectorization leverages embedding models to convert multi-modal data such as unstructured text and images into semantic vectors. In scenarios like intelligent retrieval and Retrieval-Augmented Generation (RAG), embedding models act as a bridge, mapping discrete textual and visual data into a unified vector space for cross-modal data retrieval. Vectorization applies to the following scenarios:
+
+- Efficient retrieval: enables rapid recall of document fragments that are most relevant to query terms from a vector database by calculating vector similarities. Compared with traditional inverted indexing, efficient retrieval can identify implicit semantic associations, enhancing the contextual relevance of retrieved content.
+- RAG: a leading approach to addressing the hallucination problem in large language models (LLMs). A vector knowledge base plays a crucial role in RAG technology. By retrieving precise context from the knowledge base (Top-K relevant vectors corresponding to text) and using it as input prompts for the generation model, RAG significantly reduces the occurrence of hallucinations.
+
+## Basic Concepts
+
+### Multi-Modal Embedding Model
+Embedding models are used to implement application data vectorization. The system supports multimodal embedding models, which can map different data modalities, such as text and images, into a unified vector space. These models support both single-modal semantic representation (text-to-text and image-to-image retrieval) and cross-modal capabilities (text-to-image and image-to-text retrieval).
+
+### Text Segmentation
+To address length limitations when textual data is vectorized, you can use the APIs provided by the ArkData Intelligence Platform (AIP) to split the input text into smaller sections based on the specified maximum length. This approach ensures efficient and effective data vectorization.
+
+## Working Principles
+Application data vectorization involves converting raw application data into vector formats and storing them in a vector database (store).
+
+## Constraints
+- The model can process up to 512 characters of text per inference, supporting both Chinese and English.
+- The model can handle images below 20 MB in size in a single inference.
+
+## Available APIs
+
+The following table lists the APIs related to application data vectorization. For more APIs and their usage, see [ArkData Intelligence Platform](../reference/apis-arkdata/js-apis-data-intelligence.md).
+
+| API| Description|
+| -------- | -------- |
+| getTextEmbeddingModel(config: ModelConfig): Promise<TextEmbedding> | Obtains a text embedding model.|
+| loadModel(): Promise<void> | Loads this embedding model.|
+| splitText(text: string, config: SplitConfig): Promise<Array<string>> | Splits text.|
+| getEmbedding(text: string): Promise<Array<number>> | Obtains the embedding vector of the given text.|
+| getEmbedding(batchTexts: Array<string>): Promise<Array<Array<number>>> | Obtains the embedding vector of a given batch of text.|
+| releaseModel(): Promise<void> | Releases this text embedding model.|
+| getImageEmbeddingModel(config: ModelConfig): Promise<ImageEmbedding> | Obtains an image embedding model.|
+| loadModel(): Promise<void> | Loads this image embedding model.|
+| getEmbedding(image: Image): Promise<Array<number>> | Obtains the embedding vector of the given image.|
+| releaseModel(): Promise<void> | Releases this image embedding model.|
+
+
+## How to Develop
+
+1. Import the **intelligence** module.
+
+ ```ts
+ import { intelligence } from '@kit.ArkData';
+ ```
+
+2. Obtain a text embedding model.
+
+ ```ts
+ import { BusinessError } from '@kit.BasicServicesKit';
+
+ let textConfig:intelligence.ModelConfig = {
+ version:intelligence.ModelVersion.BASIC_MODEL,
+ isNpuAvailable:false,
+ cachePath:"/data"
+ }
+ let textEmbedding:intelligence.TextEmbedding;
+
+ intelligence.getTextEmbeddingModel(textConfig)
+ .then((data:intelligence.TextEmbedding) => {
+ console.info("Succeeded in getting TextModel");
+ textEmbedding = data;
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to get TextModel and code is " + err.code);
+ })
+ ```
+
+3. Load this embedding model.
+
+ ```ts
+ textEmbedding.loadModel()
+ .then(() => {
+ console.info("Succeeded in loading Model");
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to load Model and code is " + err.code);
+ })
+ ```
+
+4. Split text. If the data to be vectorized is too long, call **splitText()** to split the data into smaller text blocks and then vectorize them.
+
+ ```ts
+ let splitConfig:intelligence.SplitConfig = {
+ size:10,
+ overlapRatio:0.1
+ }
+ let splitText = 'text';
+
+ intelligence.splitText(splitText, splitConfig)
+ .then((data:Array) => {
+ console.info("Succeeded in splitting Text");
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to split Text and code is " + err.code);
+ })
+ ```
+
+5. Obtain the embedding vector of the given text. The given text can be a single piece of text or a collection of multiple text entries.
+
+ ```ts
+ let text = 'text';
+ textEmbedding.getEmbedding(text)
+ .then((data:Array) => {
+ console.info("Succeeded in getting Embedding");
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to get Embedding and code is " + err.code);
+ })
+ ```
+
+ ```ts
+ let batchTexts = ['text1','text2'];
+ textEmbedding.getEmbedding(batchTexts)
+ .then((data:Array>) => {
+ console.info("Succeeded in getting Embedding");
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to get Embedding and code is " + err.code);
+ })
+ ```
+
+6. Release this text embedding model.
+
+ ```ts
+ textEmbedding.releaseModel()
+ .then(() => {
+ console.info("Succeeded in releasing Model");
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to release Model and code is " + err.code);
+ })
+ ```
+
+7. Obtain an image embedding model.
+
+ ```ts
+ let imageConfig:intelligence.ModelConfig = {
+ version:intelligence.ModelVersion.BASIC_MODEL,
+ isNpuAvailable:false,
+ cachePath:"/data"
+ }
+ let imageEmbedding:intelligence.ImageEmbedding;
+
+ intelligence.getImageEmbeddingModel(imageConfig)
+ .then((data:intelligence.ImageEmbedding) => {
+ console.info("Succeeded in getting ImageModel");
+ imageEmbedding = data;
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to get ImageModel and code is " + err.code);
+ })
+ ```
+
+8. Load this image embedding model.
+
+ ```ts
+ imageEmbedding.loadModel()
+ .then(() => {
+ console.info("Succeeded in loading Model");
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to load Model and code is " + err.code);
+ })
+ ```
+
+9. Obtain the embedding vector of the given image.
+
+ ```ts
+ let image = "file:///data/storage/el2/base/haps/entry/files/xxx.jpg";
+ imageEmbedding.getEmbedding(image)
+ .then((data:Array) => {
+ console.info("Succeeded in getting Embedding");
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to get Embedding and code is " + err.code);
+ })
+ ```
+
+10. Release this image embedding model.
+
+ ```ts
+ imageEmbedding.releaseModel()
+ .then(() => {
+ console.info("Succeeded in releasing Model");
+ })
+ .catch((err:BusinessError) => {
+ console.error("Failed to release Model and code is " + err.code);
+ })
+ ```
diff --git a/en/application-dev/database/aip-data-intelligence-overview.md b/en/application-dev/database/aip-data-intelligence-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..9656a54edc4e3f729c59905e9f083016631d998d
--- /dev/null
+++ b/en/application-dev/database/aip-data-intelligence-overview.md
@@ -0,0 +1,29 @@
+# AIP Overview
+
+## When to Use
+
+In the pivotal shift from digital transformation to AI advancement, creating intelligent services is essential for boosting product competitiveness.
+
+The system provides the ArkData Intelligence Platform (AIP) to offer on-device intelligent data solution with four fundamental features: semantic data processing, structured data storage, knowledge generation, and integrated knowledge retrieval — implementing AI-powered data processing on devices.
+
+For example, in personal office scenarios, you can vectorize the semantics of user documents, save them in a vector store (database), and uncover similar documents to generate personalized knowledge, which supports intelligent retrieval, recommendation, content generation, and Q&A.
+
+## Basic Concepts
+
+To get started, it's helpful to understand the following concepts:
+
+### Vectorization
+The process of vectorization uses embedding models to convert high-dimensional unstructured data (such as text and images) into low-dimensional continuous vector representations. This approach captures the semantic relationships with the data, translating abstract information into a format that can be analyzed and processed by computers. Embedding technology is widely used in fields such as natural language processing (semantic search), image recognition (feature extraction), and recommendation systems (user/item representation).
+
+## Implementation Mechanism
+
+By leveraging the AIP, you can implement intelligent data construction and retrieval. All these capabilities operate within the application processes, ensuring that data always remains in the application environment. This ensures data security and safeguards user privacy.
+
+Intelligent data construction is a process that converts application data into computable vectors for intelligent data storage and retrieval. For details about the development guide, see application data vectorization.
+
+Intelligent data retrieval involves integrated queries across various data types, such as images and text, or multiple databases. It supports condition filtering and relationship inference. Currently, the intelligent data retrieval capability is not supported.
+
+## Restrictions
+
+- Considering the significant computing workload and resources of data vectorization processing, the APIs are only available to 2-in-1 device applications.
+- You can use NPUs to accelerate the inference process of embedding models. NPUs are recommended because pure CPU computation falls far behind in latency and energy efficiency.
diff --git a/en/application-dev/database/app-data-persistence-overview.md b/en/application-dev/database/app-data-persistence-overview.md
index c46d3552d43db21ad61f713c091fc5ffc448e422..289a5d4844957184b98c28490733683548f23713 100644
--- a/en/application-dev/database/app-data-persistence-overview.md
+++ b/en/application-dev/database/app-data-persistence-overview.md
@@ -14,4 +14,8 @@ You can use proper data storage forms to implement data persistence:
- **KV-Store**: used to store data in KV pairs, in which the key uniquely identifies the data. A KV store is a kind of non-relational database. It is ideal for storing service data with few data and service relationships. It has been widely used because it poses fewer database version compatibility issues in distributed scenarios and simplifies conflict handling in data sync. KV databases feature higher cross-device and cross-version compatibility than relational databases.
-- **RelationalStore**: used to store data in rows and columns. It is widely used to process relational data in applications. RelationalStore provides a set of APIs for adding, deleting, modifying, and querying data. You can also define and use SQL statements for complex service scenarios.
+- **RelationalStore**: used to store data in rows and columns. It is widely used to process relational data in applications. RelationalStore provides a set of APIs for adding, deleting, modifying, and querying data. You can also define and use SQL statements for complex service scenarios. **RelationalStore** also provides the vector store capabilities to calculate the similarity between vector data. It is applicable to recommendation scenarios, similar image retrieval, and natural language processing.
+
+
+- **GraphStore**: Used to store and query graph data in vertexes and edges. It provides APIs for read, write, and transaction operations and can run customized GQL statements to meet the requirements of complex service scenarios. Compared with RDB stores, graph stores can process a large number of complex relational operations more efficiently. Common use cases include social network and relationship analysis, knowledge graph, and real-time recommendation systems.
+
diff --git a/en/application-dev/database/data-backup-and-restore.md b/en/application-dev/database/data-backup-and-restore.md
index bd71b55a47f2069fadb4a6ad5dcf84b88416a39a..89572dd93f2f7f7ab38df50261be145d7427a6df 100644
--- a/en/application-dev/database/data-backup-and-restore.md
+++ b/en/application-dev/database/data-backup-and-restore.md
@@ -73,7 +73,7 @@ You can use **backup()** to back up a KV store, use **restore()** to restore a K
}
```
-2. Use **put()** to insert data to the KV store.
+2. Call **put()** to insert data to the KV store.
```ts
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
@@ -92,7 +92,7 @@ You can use **backup()** to back up a KV store, use **restore()** to restore a K
}
```
-3. Use **backup()** to back up the KV store.
+3. Call **backup()** to back up the KV store.
```ts
let backupFile = 'BK001';
@@ -110,7 +110,7 @@ You can use **backup()** to back up a KV store, use **restore()** to restore a K
}
```
-4. Use **delete()** to delete data to simulate unexpected deletion or data tampering.
+4. Call **delete()** to delete data to simulate unexpected deletion or data tampering.
```ts
try {
@@ -127,7 +127,7 @@ You can use **backup()** to back up a KV store, use **restore()** to restore a K
}
```
-5. Use **restore()** to restore the KV store.
+5. Call **restore()** to restore the KV store.
```ts
try {
@@ -144,7 +144,7 @@ You can use **backup()** to back up a KV store, use **restore()** to restore a K
}
```
-6. Use **deleteBackup()** to delete the backup file to release storage space.
+6. Call **deleteBackup()** to delete the backup file to release storage space.
```ts
let files = [backupFile];
@@ -162,13 +162,13 @@ You can use **backup()** to back up a KV store, use **restore()** to restore a K
## Backing Up an RDB Store
-A database backup can be used to quickly restore a corrupted RDB store.
+A database backup can be used to quickly restore an RDB store in abnormal state.
Two backup modes are available: manual backup and automatic backup. Automatic backup is available only for system applications.
### Manual Backup
-Use [backup()](../reference/apis-arkdata/js-apis-data-relationalStore.md#backup) to manually back up an RDB store.
Example:
+Call [backup()](../reference/apis-arkdata/js-apis-data-relationalStore.md#backup) to manually back up an RDB store.
Example:
```ts
import { relationalStore } from '@kit.ArkData';
@@ -190,17 +190,19 @@ Use [backup()](../reference/apis-arkdata/js-apis-data-relationalStore.md#backup)
console.error(`Failed to get RdbStore. Code:${err.code},message:${err.message}`);
return;
}
- store.executeSql('CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)', (err) => {
- })
console.info('Succeeded in getting RdbStore.');
-
- // Backup.db indicates the name of the database backup file. By default, it is in the same directory as the RdbStore file. You can also specify the directory in the customDir + backup.db format.
+ store.executeSql('CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)', (err) => {
+ /**
+ * Backup.db specifies the database backup file. By default, it is in the same directory as the RDB store.
+ * You can also specify an absolute path, for example, /data/storage/el2/database/Backup.db. The file path must exist and will not be automatically created.
+ */
(store as relationalStore.RdbStore).backup("Backup.db", (err: BusinessError) => {
if (err) {
console.error(`Failed to backup RdbStore. Code:${err.code}, message:${err.message}`);
return;
}
console.info(`Succeeded in backing up RdbStore.`);
+ })
})
})
```
@@ -220,7 +222,7 @@ To implement hot backup of an RDB store, set **haMode** in [StoreConfig](../refe
allowRebuild: true
}
- // Use getRdbStore() to create an RDB store instance.
+ // Call getRdbStore() to create an RDB store instance.
relationalStore.getRdbStore(context, AUTO_BACKUP_CONFIG, (err, store) => {
if (err) {
console.error(`Failed to get RdbStore. Code:${err.code}, message:${err.message}`);
@@ -234,11 +236,11 @@ To implement hot backup of an RDB store, set **haMode** in [StoreConfig](../refe
## Rebuilding an RDB Store
-If error code 14800011 is reported during the creation or use of an RDB store, the database is corrupted. If this occurs, you can rebuild the RDB store and restore data from a backup.
+If error 14800011 is displayed when an RDB store is created or used, an exception occurs in the database. You can delete the database and restore data.
-To enable automatic rebuild of an RDB store, set **allowRebuild** in [StoreConfig](../reference/apis-arkdata/js-apis-data-relationalStore.md#storeconfig) to **true**. The newly rebuilt RDB store is empty. You need to create tables and restore data from the database backup. For details about how to back up RDB store data, see [Backing Up an RDB Store](#backing-up-an-rdb-store). For details about how to restore RDB store data, see [Restoring RDB Store Data](#restoring-rdb-store-data).
+You can set **allowRebuild** in [StoreConfig](../reference/apis-arkdata/js-apis-data-relationalStore.md#storeconfig) to **true**, which allows the database to be automatically deleted when an exception occurs. The newly rebuilt RDB store is empty. You need to create tables and restore data from the database backup. For details about how to back up RDB store data, see [Backing Up an RDB Store](#backing-up-an-rdb-store). For details about how to restore RDB store data, see [Restoring RDB Store Data](#restoring-rdb-store-data).
-If **allowRebuild** in **StoreConfig** is set to **true** before the database is corrupted, the database will be automatically rebuilt when corrupted.
+If **allowRebuild** in **StoreConfig** is set to **true** before the database is abnormal, the database will be automatically deleted when an exception occurs.
If **allowRebuild** in **StoreConfig** is not set or is set to **false**, set **allowRebuild** to **true** and open the rebuilt RDB store.
Example:
@@ -269,7 +271,7 @@ If **allowRebuild** in **StoreConfig** is not set or is set to **false**, set **
## Restoring RDB Store Data
-If an RDB store is corrupted, you can restore it by using the database backup.
+If an RDB store is abnormal, you can restore it by using the database backup.
You can restore data from either the manual backup data or automatic backup data. The latter is available only for system applications.
@@ -279,7 +281,7 @@ You can use **backup()** to [perform manual backup](#manual-backup) and use **re
The following example contains only the code snippet for the restore process. The complete code must also contain the code for backing up data and rebuilding an RDB store.
-1. Throw an exception that indicates database corruption.
+1. Throws an error code to indicate a database exception.
```ts
let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
@@ -332,12 +334,15 @@ The following example contains only the code snippet for the restore process. Th
```ts
try {
let context = getContext();
- // Backup.db indicates the name of the database backup file. By default, it is in the same directory as the RdbStore file. You can also specify the directory in the customDir + backup.db format.
- let backup = context.databaseDir + '/backup/test_backup.db';
- if(!fileIo.access(backup)) {
+ /**
+ * Backup.db specifies the database backup file. By default, it is in the same directory as the current database.
+ * If an absolute path is specified for the database backup file, for example, /data/storage/el2/database/Backup.db, pass in the absolute path.
+ */
+ let backup = context.databaseDir + '/entry/rdb/Backup.db';
+ if (!fileIo.access(backup)) {
console.info("no backup file");
try {
- (store as relationalStore.RdbStore).close;
+ (store as relationalStore.RdbStore).close();
store = undefined;
} catch (e) {
if (e.code != 14800014) {
@@ -354,7 +359,7 @@ The following example contains only the code snippet for the restore process. Th
return
}
// Call restore() to restore data.
- (store as relationalStore.RdbStore).restore(backup);
+ (store as relationalStore.RdbStore).restore("Backup.db");
} catch (e) {
console.error(`Code:${e.code}, message:${e.message}`);
}
@@ -364,7 +369,7 @@ The following example contains only the code snippet for the restore process. Th
### Restoring from Automatic Backup Data (for System Applications Only)
-Use [restore()](../reference/apis-arkdata/js-apis-data-relationalStore-sys.md#restore12) to restore data from the [automatic backup data](#automatic-backup-for-system-applications-only). Only system applications support this operation.
+Call [restore()](../reference/apis-arkdata/js-apis-data-relationalStore-sys.md#restore12) to restore data from the [automatic backup data](#automatic-backup-for-system-applications-only). Only system applications support this operation.
The following example contains only the code snippet for the restore process. The complete code must also contain the code for backing up data and rebuilding an RDB store.
diff --git a/en/application-dev/database/data-mgmt-overview.md b/en/application-dev/database/data-mgmt-overview.md
index da68e74b82d3eca4e27d821d46e5eadc0aa412d6..19ecda86af74974164da8bc3aa3f9802fc1212f2 100644
--- a/en/application-dev/database/data-mgmt-overview.md
+++ b/en/application-dev/database/data-mgmt-overview.md
@@ -4,9 +4,9 @@
## Function
ArkData provides data storage, management, and sync capabilities. For example, you can store the Contacts application data in database for secure management and shared access, and synchronize the contacts information with a smart watch.
-- Unified data definition: OpenHarmony provides unified data definitions, including the data types and structs, for different applications and devices.
+- Unified data definition: provides unified data definitions, including the data types and structs, for different applications and devices.
-- Data storage: provides capabilities for persisting user preference data, key-value (KV) store data, and relational database (RDB) store data.
+- Data storage: provides data persistence capabilities, including preferences, key-value (KV) stores, relational database (RDB stores), and graph stores (available only to system applications).
- Data management: provides efficient data management capabilities, including permission management, data backup and restore, and dataShare framework.
@@ -19,7 +19,7 @@ The database stores created by an application are saved to the application sandb
The data management module includes preferences, KV data management (KV-Store), relational data management (RelatoinalStore), distributed data object (DataObject), cross-application data management (DataShare), and unified data management framework (UDMF). The interface layer provides standard JavaScript APIs for application development. The Frameworks & System service layer implements storage and sync of component data, and provides dependencies for SQLite and other subsystems.
-**Figure 1** Data management architecture
+ **Figure 1** Data management architecture
@@ -28,12 +28,12 @@ The data management module includes preferences, KV data management (KV-Store),
- **KV-Store**: implements read, write, encryption, and manual backup of data in KV stores and notification subscription. When an application needs to use the distributed capabilities of a KV store, KV-Store sends a sync request to DatamgrService, which implements data sync across devices.
-- **RelationalStore**: implements addition, deletion, modification, query, encryption, manually backup of data in RDB stores, and notification subscription. When an application needs to use the distributed capabilities of an RDB store, RelationalStore sends a sync request to DatamgrService, which implements data sync across devices.
+- **RelationalStore**: provides the capabilities for managing an RDB store, including create, read, update, delete (CRUD) operations, encryption, manual backup, and subscription notifications. It also provides the capabilities of storing and managing data in a vector store, searching for vector data, and calculating vector data similarity. When an application needs to use the distributed capabilities of an RDB store, RelationalStore sends a sync request to DatamgrService, which implements data sync across devices.
- **DataObject**: independently provides distributed capabilities for data objects. **DatamgrService** implements temporary storage of the object data, which is still required after the application (either the application of your device or cross-device application) is restarted.
- **DataShare**: provides the data provider-consumer mode to implement addition, deletion, modification, and query of cross-application data on a device, and notification subscription. **DataShare** is not bound to any database and can interact with RDB and KV stores. You can also encapsulate your own databases for C/C++ applications.
In addition to the provider-consumer mode, **DataShare** provides silent access, which allows direct access to the provider's data via the DatamgrService proxy instead of starting the provider. Currently, only the RDB stores support silent access.
-- **UDMF**: defines the language and data standards for cross-application and cross-device data interaction, improving data interaction efficiency. The UDMF provides secure and standard data transmission channels and supports different levels of data access permissions and lifecycle management policies. It helps implement efficient data sharing across applications and devices.
+- UDMF: defines the data standards for cross-application and cross-device data interaction, improving data interaction efficiency. The UDMF provides secure and standard data transmission channels and supports different levels of data access permissions and lifecycle management policies. It helps implement efficient data sharing across applications and devices.
- **DatamgrService**: implements sync and cross-application sharing for other components, including cross-device sync of **RelationalStore** and **KV-Store**, silent access to provider data of **DataShare**, and temporary storage of **DataObject** data.
diff --git a/en/application-dev/database/data-persistence-by-graph-store.md b/en/application-dev/database/data-persistence-by-graph-store.md
new file mode 100644
index 0000000000000000000000000000000000000000..a4d4a6cd3330083098f9c1211f52d75bc70e2d8a
--- /dev/null
+++ b/en/application-dev/database/data-persistence-by-graph-store.md
@@ -0,0 +1,460 @@
+# Persisting Graph Store Data (for System Applications Only)
+
+
+## When to Use
+
+A graph store is a database management system dedicated to processing complex relational data. It stores and queries data through the structure of nodes (vertexes) and relationships (edges), enabling efficient processing of large-scale complex relational operations. A graph store stands out with its ability to directly traverse relationships through stored edges, which is more efficient than the RDB store that relies on multi-table joins. Common use cases include social network and relationship analysis, knowledge graph, and real-time recommendation systems. Currently, all the APIs for graph stores are available only to system applications.
+
+
+## Basic Concepts
+
+- Graph: a data struct consisting of nodes (vertexes) and relationships (edges), which represent entities and their relationships.
+
+- Schema: outlines the structural definition of data, similar to the table structure design in an RDB store. It defines how nodes, relationships, and properties are organized in a graph store and constraints to ensure data consistency and query efficiency.
+
+- Node (vertex): a fundamental unit in a graph store, representing an entity or object.
+
+- Relationship (edge): connects nodes and defines how nodes are related.
+
+- Path: a sequence of connected vertexes and edges from the starting point to the end point.
+
+- Label: used to classify or group nodes or relationships in a graph store, for example, **Person** and **Friend** in the following graph creation statements.
+
+- Property: a key-value (KV) pair attached to a node or relationship to provide additional information. Examples include **name: 'name_1'** and **age: 11** in the following vertex insertion statement.
+
+- Vertex table: a table used to store vertex information in a graph store. It provides a structured view of all the nodes in the grph. The table name is the vertex label (for example, **Person** in the graph creation statement below). The table includes the vertex IDs and properties.
+
+- Edge table: a table used to store edge information. It visualizes and stores connections between nodes. The table name is the label of the edge (for example, **Friend** in the graph creation statement below). The table includes the edge IDs, start and end point IDs, and properties.
+
+- Variable: an identifier used in a Graph Query language (GQL) statement to temporarily store and reference graph data (a node, edge, or path) in queries. There are three types of variables:
+ - Vertex variable: indicates a vertex in a graph. A variable name is used to reference the property or and label of a node (for example, **person** in the GQL statement for querying a vertex below).
+ - Edge variable: indicates an edge in a graph. A variable name is used to reference the property or and label of an edge (for example, **relation** in the GQL statement for querying an edge below).
+ - Path variable: indicates a path in a graph, that is, a sequence of connected vertexes and edges, which is usually generated by a path traversal operation (for example, **path** in the GQL statement for querying a path below).
+```ts
+const CREATE_GRAPH = "CREATE GRAPH test { (person:Person {name STRING, age INT}),(person)-[:Friend {year INT}]->(person) };"
+
+const INSERT_VERTEX = "INSERT (:Person {name: 'name_1', age: 11});"
+
+const QUERY_VERTEX = "MATCH (person:Person) RETURN person;"
+
+const QUERY_EDGE = "MATCH ()-[relation:Friend]->() RETURN relation;"
+
+const QUERY_PATH = "MATCH path=(a:Person {name: 'name_1'})-[]->{2, 2}(b:Person {name: 'name_3'}) RETURN path;"
+```
+
+
+## Working Principles
+
+The **graphStore** module provides APIs for applications. The underlying uses its own component as the persistent storage engine to support features such as transactions, indexes, and encryption.
+
+
+## Constraints
+
+### Supported Data Types and Specifications
+
+ArkTS supports number, string, and boolean. The following table lists the specifications and restrictions of each data type.
+
+| Data Type| Specifications|
+| - | - |
+| NULL | **nullptr**, which indicates an item without a value. The data type cannot be set to **NULL** during graph creation.|
+| number | 1. INTEGER, with the same value range as int64_t. NUMERIC, DATE, DATETIME, and INT are mapped to int64_t.
2. DOUBLE, with the same value range as double. REAL and FLOAT are mapped to double.|
+| string | 1. The maximum length is 64 x 1024 bytes, including the terminator '\0'.
2. CHARACTER(20), VARXHAR(255), VARYING CHARACTER(255), NCHAR(55), NATIVE CHARACTER(70), and NVARCHAR (100) are mapped to STRING, and the numbers have no practical significance.
3. A string literal must be enclosed in matching single quotes. Double quotes are not allowed. Single quotes are not allowed inside a string.|
+| boolean | The value can be **true** or **false**. BOOL and BOOLEAN are mapped to int64_t.|
+
+### Property Graph DDL Specifications
+
+Data Definition Language (DDL) is used to define the schema of a graph. Common DDL statement keywords include **CREATE**. The following table lists the DDL specifications and constraints.
+
+> **NOTE**
+>
+> The current implementation is a subset of the GQL standard syntax. Except the content in "Column constraints", other specifications and constraints are not specified in the GQL standards.
+
+| Category| Specifications|
+| - | - |
+| Property graph creation| 1. A database instance can be used to create only one property graph.
2. A vertex table and an edge table cannot be defined in the same clause, for example, **(person:Person {name STRING, age INT})-[:Friend {year INT}]->(person)**.
3. When creating a property graph, you must specify the direction in the edge table. Currently, only the left-to-right direction is allowed, that is, '-[',']->'.
4. The property graph name is case-insensitive and cannot exceed 128 bytes.
5. Variable names are case sensitive. Variable names must be specified for a vertex table. The variable name cannot start with **anon_** or exceed 128 bytes. Variable names should not be specified for edge tables. Variable names corresponding to different vertex tables must be unique.
6. No space is allowed in **-[**, **]->**, **]-**, and **<-[**. For example, **- [** is not allowed.
7. When creating a property graph, you must define a vertex table and then an edge table. At least one vertex table must be defined. The edge table does not need to be defined.
8. The vertex label and edge label cannot have the same name.
9. The GQL system table uses variable-length fields to hold graph creation statements. Therefore, the length of a graph creation statement must be less than 64 x 1024 bytes.|
+| Total number of vertex or edge tables| 1. The name of the vertex or edge table created by the user cannot be the same as the system table name (starting with table prefix **GM_**).
2. System tables cannot be modified.
3. Currently, system tables cannot be queried.
4. For a single process in non-sharing mode, a database instance allows a maximum of 2000 vertex tables and 10,000 edge tables.
5. Due to the 64 x 1024 bytes limit of variable-length fields, the actual maximum number of vertex or edge tables that can be created may be less than the upper limit. For example, if the graph creation statements for 10,000 edge tables exceed 64 x 1024 bytes, the creation of the property graph will fail.|
+| Number of vertex or edge table properties| 1. A vertex or edge table can contain a maximum of 1023 properties (excluding the default **identity** properties added in the database).
2. The property name cannot be **rowid** or **identity**. The database adds the **identity** property to each vertex and edge label by default.
3. The property name is case-insensitive and cannot exceed 128 bytes.
4. The **identity** property cannot have its value specified during insertion, cannot be updated, or queried using the property name **identity**. It can only be retrieved by using **element_id (v)**.|
+| Table name length| The table name is case-insensitive and cannot exceed 128 bytes. For example, **table** and **TABLE** refer to the same table.|
+| Property name length| The property name is case-insensitive and cannot exceed 128 bytes.|
+| Length of the variable-length field type| The property value of the string type cannot exceed 64 x 1024 bytes.|
+| Default value| 1. Only constant expressions can be used to set default values, such as **100** and **China**.
2. If the default value is a time keyword (**CURRENT_DATE**, **CURRENT_TIMESTAMP**, or **CURRENT_TIME**), the corresponding data type should be string rather than int64_t.|
+| Column constraints| If **NOT NULL** is set for a property, the property value cannot be **NULL**.|
+
+### Property Graph DML/DQL Specifications
+
+Data Manipulation Language (DML) is used to add, delete, and modify data. Common DML statement keywords include **INSERT**, **SET**, and **DETACH DELETE**.
Data Query Language (DQL) is used to query data. Common DQL statement keywords include **MATCH** and **WHERE**.
+
+#### Keyword Specifications and Constraints
+
+| Keyword| Specifications| Difference with the GQL Standard|
+| - | - | - |
+| MATCH | 1. Unlimited variable-length hops ( 0 ≤ next N hops ≤ 3) are not supported.
2. The variable name is case-sensitive and cannot start with **anon_**.
3. Variable-length edges and fixed-length edges cannot appear together. An incorrect example is **MATCH p = (a: A)-[e1]->(b)-[e2]->{1, 2}(c)**, where **e1** is a fixed-length edge and **e2** is a variable-length edge.
4. The number of paths cannot exceed 2 in the **MATCH** clause of the **INSERT** statement, and cannot exceed 1 in other statements.
5. The next variable-length hops (N hops) can appear only once. The table name, property filter list (for example, **{id: 1}**), and **WHERE** clause cannot be specified for the edges of variable-length hops.
6. The same variable name cannot correspond to multiple paths or edges. However, the same variable name can correspond to multiple vertex tables. If a vertex table is specified, the same label name must be specified.
7. No space is allowed in **-[**, **]->**, **]-**, and **<-[**. For example, **- [** is not allowed.
8. A GQL statement cannot contain two or more **MATCH** clauses.
9. Empty {} is not allowed in a matching pattern. For example, **MATCH (n: Person {}) RETURN n** will result in a syntax error.| The GQL standard does not clearly define the constraints except for No 9.|
+| WHERE | 1. Variable-length variables and path variables cannot be used after **WHERE**. Property names must be specified for vertex variables and edge variables.
2. If **WHERE** is followed by a property column (for example, **WHERE id**), it will be converted into a bool value and then evaluated. **id=0** converts to **false**; otherwise, it converts to **true**.
3. The **WHERE** clause cannot be followed by graph matching forms like **()-[]->()**.| The GQL standard does not include the constraints except for No. 3.|
+| INSERT | 1. The **INSERT** statement must be specified with the label (table) name, to which the vertex and edge are to be inserted.
2. **INSERT** cannot be followed by **RETURN**.
3. A vertex and an edge cannot be inserted together.
4. The combination of **MATCH+WHERE+INSERT** is not supported.
5. Empty {} is not allowed in a matching pattern. For example, **INSERT (: Person {})** will result in a syntax error.| The GQL standard does not include the constraints except for No. 5.|
+| SET | 1. Updating the label (table) name of a vertex or edge is not supported. A vertex cannot have multiple labels.
2. **SET** cannot be followed by **RETURN**.
3. Updating without setting any property value (for example, **SET p = {}**) is not supported. At least one property must be set.
4. The **SET** clause cannot be followed by graph matching forms like **()-[]->()**.| The GQL standard does not include the constraints except for No. 4.|
+| DETACH DELETE | 1. When a vertex is deleted from a graph, all edges connected to it will also be deleted. When an edge is deleted, only the edge itself is removed.
2. **DETACH DELETE** cannot be followed by **RETURN**.
3. Variable-length variables and path variables cannot be deleted. The **DELETE** clause cannot be followed by graph matching forms like **()-[]->()**.
4. **DELETE** without keywords (synonyms: **NODETACH DELETE**) is not supported.| The GQL standard does not include the constraints except for No. 1 and No. 3.|
+| RETURN | 1. Returning variable-length edge variables is not supported. For example, in **MATCH p=(a: Person)-[e]->{0, 2}(d) RETURN e;**, only variables **p**, **a**, and **b** can be returned, not the variable-length edge variable **e**.
2. **RETURN \*** is not supported.
3. The **RETURN** clause cannot be followed by graph matching forms like **()-[]->()**.
4. Each column in the returned result (variables, properties, and expressions) is limited to 64 x 1024 bytes, including the null terminator **\0**.
5. If vertex, edge, or path variables are returned, the results (JSON strings) will not include columns with null values.
6. For aggregate queries without explicitly specified **GROUP KEY**, returning **variable.property** fields is not allowed. Duplicate columns are permitted, including duplicate field columns, aggregate function extended columns, and **COUNT (\*)**.
7. For aggregate queries with explicitly specified **GROUP KEY**, the **variable.property** fields in **RETURN** must match **GROUP KEY**. It is not allowed to return partial **GROUP KEY** fields, non-existent **variable.property** fields, or duplicate columns (including duplicate field columns, aggregate function extended columns, and **COUNT (\*)**).
8. For aggregate queries with explicitly specified **GROUP KEY**, the columns returned are arranged as: **GROUP KEY** fields followed by extended columns of the aggregate function.
9. In aggregate queries, expressions and basic functions cannot be returned in **RETURN**.
10. If a GQL statement includes an aggregate function, only the property column or aggregate function column can be returned. Returning vertex, edge, or path variables is not supported.
11. Column aliases can be used in **ORDER BY**, but not in **GROUP BY**.
12. Duplicate column aliases are not allowed.
13. Column aliases are case-insensitive.| The GQL standard does not include the constraints except for No. 3.|
+| LIMIT | Using negative numbers after **LIMIT** is not supported.| None|
+| OFFSET | Using negative numbers after **OFFSET** is not supported.| **SKIP** cannot be used as a synonym for **OFFSET**.|
+| ORDER BY | 1. Numeric references to projection columns in the **RETURN** clause for sorting are not supported.
2. Sorting entire variables is not supported.
3. Aggregate functions cannot be used after **ORDER BY**.
4. The following keywords are added:
Reserved keywords **ORDER**, **BY**, **ASC**, **ASCENDING**, **DESC**, **DESCENDING** and **NULLS**, and non-reserved keywords **FIRST** and **LAST**.
5. When performing aggregate queries, **ORDER BY** must be used with **GROUP BY**.
6. When **ORDER BY** is used with **GROUP BY**, the property column used in the sorting key must exist in the projection result.
7. The default sorting order is ascending order.
8. If the priority for **NULL** values is not specified, the **NULL** values have the lowest priority by default.| The GQL standard does not clearly define constraint 1 and not include constraints 2 and 3.|
+| GROUP BY | 1. The maximum number of group keys is 32.
2. **GROUP KEY** does not support grouping of variables without labels. That is, the variables in the **MATCH** clause that are used as keys in **GROUP BY** must have labels.
3. **GROUP KEY** can only be in the format **variable.property**, for example, **a.prop**. It cannot be used to group vertex or edge labels, vertex or edge variables, paths, variable-length edges, and their fields.
4. Duplicate **Group Key** values are not allowed, including duplicate field columns and duplicate extension focus columns.| The constraints are a subset of the GQL standard.|
+
+#### Operation and Function Specifications
+
+| Operation/Function| Specifications| Difference with the GQL Standard|
+| - | - | - |
+| Arithmetic operations| 1. Addition (+), subtraction (-), multiplication (*), division(/), and modulus (%) are supported.
2. Operations between fixed-length types are supported. Arithmetic operations involving variable-length types or between fixed-length and variable-length types are not supported.
3. When high-precision data is assigned to low-precision fields, precision loss will occur.| The GQL standard does not include constraint 2.|
+| Comparison operations| 1. Operations equal to (=), not equal to (!=), greater than (>), greater than or equal to (>=), less than (<), less than and equal to (<=), and exclusive inequality (<>) are supported.
2. Consecutive operations are not supported. For example, **0<=F1<=10** is not supported. It must be rewritten as **0<=F1 AND F1<=10**. The operation **0<=F1<=10** is equivalent to **(0<=F1)<=10**.
3. Operations between fixed-length types or variable-length types are supported. Operations between fixed-length and variable-length types are not supported.
4. Floating-point precision error is +/-0.000000000000001.
5. Comparisons like **(a, b) < (1, 2)** are not supported.| The GQL standard does not include the constraints except for No.1.|
+| Logical operation| 1. Supported operations include **AND**, **OR**, **NOT**, **IS NULL**, **IS NOT NULL**, **IN**, **NOT IN**, **LIKE**, **NOT LIKE** and **\|\|** (string concatenation).
2. For operators **AND**, **OR**, and **NOT**, their operands are forcibly converted to bool type. For example, in **WHERE 0.00001 AND '0.1'**, **0.00001** is a floating-point number. Given a precision error of +/-0.000000000000001, **0.00001** is not equal to **0** and is converted to **true**. **'0.1'** is a string that is first converted to a double type (**0.1**), which is also not equal to **0**. Therefore, it is converted to **true**.
3. For operators **LIKE** and **NOT LIKE**, their operands are forcibly converted to string type. For example, in **WHERE 0.5 LIKE 0.5**, **0.5** is forcibly converted to string **'0.5'**. This is equivalent to **WHERE '0.5' LIKE '0.5'**, which evaluates to **true**.
4. Currently, **IN** and **NOT IN** do not support right-hand subqueries and will trigger error code 31300009. | The GQL standard does not include the constraints except for No.1.|
+| Time functions| 1. Only **DATE()**, **LOCAL_TIME()**, and **LOCAL_DATETIME()** are supported.
2. The input parameters support the following time-value formats:
YYYY-MM-DD
YYYY-MM-DD HH:MM
YYYY-MM-DD HH:MM:SS
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MM:SS
HH:MM
HH:MM:SS
3. Function nesting is not supported.
4. The input parameters must be string literals.| Date parsed from records, for example, **date({year: 1984, month: 11, day: 27})** is not supported.|
+| Rounding functions| 1. **FLOOR()** and **CEIL()**/**CEILING()** are supported.
2. The input parameters must be numeric.
3. Function nesting is not supported.
4. Scientific notation cannot be used as a function parameter.| The GQL standard does not include constraint 4.|
+| String functions| 1. **CHAR_LENGTH()**/**CHARACTER_LENGTH()**, **LOWER()**, **UPPER()**, **SUBSTR()**/**SUBSTRING()** and **SUBSET_OF()** are supported.
2. Except **SUBSTR()** and **SUBSTRING()**, the parameters of other functions must be strings. For **SUBSTR()**/**SUBSTRING()**, the first parameter must be a string, and the second and third parameters must be numeric.
3. When the string concatenation operator **\|\|** is used, numeric types can be concatenated.
4. The parameters of **SUBSTR()**/**SUBSTRING()** and **SUBSET_OF()** can be nested. Other functions do not support function nesting.
5. Scientific notation cannot be used as a function parameter.
6. The number of parameters for **SUBSTR()**/**SUBSTRING()** must be 3. The first parameter is the original string. The second parameter specifies the start position for the substring (**1** for the first character from the left and **-1** for the first character from the right). The third parameter indicates the length of the substring. If the second and third parameters are floating-point numbers, the values will be rounded down.
7. For **SUBSET_OF()**, the first parameter is the original string, the second parameter is the query string, and the third parameter is the delimiter. The return value is a boolean (**1** or **0**). The length of the delimiter string must be 1. The first and last characters of the first two parameters cannot contain extra delimiters, and consecutive delimiters are not allowed. | The GQL standard does not include constraint 4.|
+| Aggregate functions| 1. Only **SUM**, **MAX**, **MIN**, **AVG**, and **COUNT** are supported. **FIRST** and **LAST** are not supported.
2. Only single, valid **variable.property** fields are allowed in aggregate functions. Null values, multiple fields, non-existent fields, expressions, and variables are not allowed. Properties of unlabelled variables are not supported.
3. Expression calculations (intra/inter) and nesting of aggregate functions are not supported.
4. The field types used in aggregate function calculations must be one of the following: INTEGER, BOOLEAN, DOUBLE, and STRING, consistent with the data types supported by GQL.
5. If a single query in GQL scenarios exceeds 100 MB, temporary files will not be used and error code 31300004 will be triggered.| The constraints are a subset of the GQL standard.|
+| Type conversion functions| 1. Function nesting is not supported.
2. Scientific notation cannot be used as a function parameter.
3. CAST AS INT
i. Parameters of the STRING, INTEGER, BOOLEAN, or DOUBLE type are supported.
ii. If the input parameter is **true**, **1** is returned. If the input parameter is **false**, **0** is returned.
iii. Strings that cannot be converted to INT will result in an error.
iv. If the input parameter is a floating-point number, the value is truncated to return an integer.
4. CAST AS BOOL
i. Parameters of the INTEGER, BOOLEAN, or DOUBLE type are supported.
ii. **CAST('true' AS BOOL)** is not supported.
ii. Internally, BOOLEAN is represented as INT: **0** represents **false**, and **1** represents **true**. Converting any other INTEGER to BOOLEAN will return its value unchanged.
5. CAST AS DOUBLE
i. Parameters of the STRING, INTEGER, BOOLEAN, or DOUBLE type are supported.
ii. Strings that cannot be converted to DOUBLE will result in an error.
6. CAST AS STRING
i. Parameters of the STRING, INTEGER, BOOLEAN, or DOUBLE type are supported.
ii. The return value of **CAST(true AS STRING)** is **1**.| The GQL standard does not support conversions between BOOL and INT or DOUBLE.|
+
+### Index Specifications
+
+Indexes are essential for optimizing query performance, primarily accelerating property lookups for nodes and edges. The following table lists the specifications and constraints.
+
+> **NOTE**
+>
+> The GQL standard does not contain index-related syntax.
+
+| Category| Specifications|
+| - | - |
+| Index name length| The index name is case-insensitive and cannot exceed 128 bytes or be the same as a label name (also case-insensitive).|
+| Index size| In a single index, the total size of all index columns cannot exceed 1024 bytes.|
+| Length of the variable-length field index| If a variable-length field is used as a key, its size must be less than 1024 bytes.|
+| Index usage constraints| Indexes must follow the continuous leftmost match principle; otherwise, the indexing functionality will not be effective and will result in a full table scan.
1. **BTree** does not support range queries on multiple fields with a composite index, for example, **{02. **BTree** does not support non-continuous field queries with a composite index. For example, given a composite index on **F1**, **F2**, **F3**, and **F4**, a condition like **{F1, F3}** violates the continuous prefix rule.|
+| Composite index| A composite index can contain a maximum of 32 columns.|
+| Index name uniqueness| Index names can be identical across different labels. For example, **t1.id** and **t2.id** can both use the index name **id**.|
+| Index creation| 1. In unique indexes, duplicate NULL values will not trigger index conflicts.
2. A maximum of 10 indexes can be created for a single label.
3. When creating a property graph, you cannot use the **Primary Key** and **Unique** keywords to create an index. Indexes must be created explicitly using index creation statements.
4. Unique indexes can be created by specifying the **Unique** keyword.|
+| Index deletion| When deleting an index, you must specify the name of the label to which the index belongs, for example, **Drop Index label.index**.|
+| Index sorting order| **ASC** indicates ascending order; **DESC** indicates descending order. The default value is **ASC**. Currently, custom sorting order is not supported.|
+| Expression index| It is not supported currently.|
+
+### Transaction Specifications
+
+| Category| Specifications| Difference with the GQL Standard|
+| - | - | - |
+| Explicit transactions| 1. The default isolation level is **serializable**.
2. **SAVEPOINT** is not supported. **SAVEPOINT** is an important mechanism in database transaction management that allows markers to be created in transactions for partial rollbacks.
3. Mixed transactions of DDL and DML, standalone DDL transactions, and DDL transaction rollbacks are not supported.
4. If a single statement in the current transaction fails to be executed, only that statement will be rolled back.
5. Transactions must be explicitly committed or rolled back. Otherwise, the transaction will be rolled back.
6. It is not allowed to commit or roll back a transaction that is not in the transaction state.
7. When two transactions are created at the same time, write-write operations, read-write operations, and write-read operations are mutually exclusive, and read-read operations can execute concurrently.
8. The operation limit and cache size of a transaction depend on **undo log** and are limited by the file system space. The number of threads waiting for locks correlates with the maximum connections allowed in the database.| The GQL standard supports basic transaction syntax, including enabling read-only and read-write transactions, but does not support **SAVEPOINT**.|
+| Concurrent operations| Multi-concurrency is supported. Only the serializable isolation level is supported. Concurrent threads involving write operations may encounter some degree of blocking.| The GQL standard supports all isolation levels used in SQL.|
+
+### Other Specifications and Constraints
+
+- By default, the Write Ahead Log (WAL) and the **FULL** flushing mode are used.
+
+- To ensure data accuracy, only one write operation is allowed at a time.
+
+- Once an application is uninstalled, related database files and temporary files are automatically deleted from the device.
+
+- The multi-process mode is not supported.
+
+- Currently, backup and restore of graph stores are not supported.
+
+
+## Available APIs
+
+The following lists only the APIs for persisting graph store data. For details about more APIs and their usage, see [Graph Store (System APIs)](../reference/apis-arkdata/js-apis-data-graphStore-sys.md).
+
+| API| Description|
+| -------- | -------- |
+| getStore(context: Context, config: StoreConfig): Promise<GraphStore> | Obtains a **GraphStore** instance for graph store operations. You can set **GraphStore** parameters based on actual requirements and use the created instance to call related APIs to perform data operations.|
+| read(gql: string): Promise<Result> | Reads data from the graph store.|
+| write(gql: string): Promise<Result> | Writes data to the graph store.|
+| close(): Promise<void> | Closes the graph store. All uncommitted transactions will be rolled back.|
+| createTransaction(): Promise<Transaction> | Creates a transaction instance.|
+| Transaction.read(gql: string): Promise<Result> | Reads data with the transaction instance.|
+| Transaction.write(gql: string): Promise<Result> | Writes data with the transaction instance. |
+| Transaction.commit(): Promise<void> | Commits the GQL statements that have been executed in this transaction.|
+| Transaction.rollback(): Promise<void> | Rolls back the GQL statements that have been executed in this transaction.|
+| deleteStore(context: Context, config: StoreConfig): Promise<void> | Deletes a graph store.|
+
+
+## How to Develop
+
+The following provides only the sample code in the stage model.
+
+1. Call **getStore()** to obtain a **GraphStore** instance, including creating a database, setting the security level, and changing the database to an encrypted database. The example code is as follows:
+
+ ```ts
+ import { graphStore } from '@kit.ArkData'; // Import the graphStore module.
+ import { UIAbility } from '@kit.AbilityKit';
+ import { BusinessError } from '@kit.BasicServicesKit';
+ import { window } from '@kit.ArkUI';
+
+ let store: graphStore.GraphStore | null = null;
+
+ const STORE_CONFIG: graphStore.StoreConfig = {
+ name: "testGraphDb," // Database file name without the file name extension .db.
+ securityLevel: graphStore.SecurityLevel.S2, // Database security level.
+ encrypt: false, // Whether to encrypt the database. This parameter is optional. By default, the database is not encrypted.
+ };
+
+ const STORE_CONFIG_NEW: graphStore.StoreConfig = {
+ name: "testGraphDb", // The database file name must be the same as the file name used for creating the database.
+ securityLevel: graphStore.SecurityLevel.S3,
+ encrypt: true,
+ };
+
+ // In this example, EntryAbility is used to obtain a GraphStore instance. You can use other implementations as required.
+ class EntryAbility extends UIAbility {
+ onWindowStageCreate(windowStage: window.WindowStage) {
+ graphStore.getStore(this.context, STORE_CONFIG).then(async (gdb: graphStore.GraphStore) => {
+ store = gdb;
+ console.info('Get GraphStore successfully.')
+ }).catch((err: BusinessError) => {
+ console.error(`Get GraphStore failed, code is ${err.code}, message is ${err.message}`);
+ })
+
+ // Before changing the database security level and encryption property, call close() to close the database.
+ if(store != null) {
+ (store as graphStore.GraphStore).close().then(() => {
+ console.info(`Close successfully`);
+
+ graphStore.getStore(this.context, STORE_CONFIG_NEW).then(async (gdb: graphStore.GraphStore) => {
+ store = gdb;
+ console.info('Update StoreConfig successfully.')
+ }).catch((err: BusinessError) => {
+ console.error(`Update StoreConfig failed, code is ${err.code}, message is ${err.message}`);
+ })
+ }).catch ((err: BusinessError) => {
+ console.error(`Close failed, code is ${err.code}, message is ${err.message}`);
+ })
+ }
+ }
+ }
+ ```
+
+2. Call **write()** to create a graph. The example code is as follows:
+
+ ```ts
+ const CREATE_GRAPH = "CREATE GRAPH test " +
+ "{ (person:Person {name STRING, age INT}),(person)-[:Friend {year INT}]->(person) };"
+
+ if(store != null) {
+ (store as graphStore.GraphStore).write(CREATE_GRAPH).then(() => {
+ console.info('Create graph successfully');
+ }).catch((err: BusinessError) => {
+ console.error(`Create graph failed, code is ${err.code}, message is ${err.message}`);
+ })
+ }
+ ```
+
+3. Call **write()** to insert or update vertexes and edges. The example code is as follows:
+
+ > **NOTE**
+ >
+ > **graphStore** does not provide explicit flush operations for data persistence. The data inserted is persisted.
+
+ ```ts
+ const INSERT_VERTEX_1 = "INSERT (:Person {name: 'name_1', age: 11});";
+ const INSERT_VERTEX_2 = "INSERT (:Person {name: 'name_2', age: 22});";
+ const INSERT_VERTEX_3 = "INSERT (:Person {name: 'name_3', age: 0});";
+
+ const UPDATE_VERTEX_3 = "MATCH (p:Person) WHERE p.name='name_3' SET p.age=33;"
+
+ const INSERT_EDGE_12 = "MATCH (p1:Person {name: 'name_1'}), (p2:Person {name: 'name_2'}) " +
+ "INSERT (p1)-[:Friend {year: 12}]->(p2);";
+ const INSERT_EDGE_23 = "MATCH (p2:Person {name: 'name_2'}), (p3:Person {name: 'name_3'}) " +
+ "INSERT (p2)-[:Friend {year: 0}]->(p3);";
+
+ const UPDATE_EDGE_23 = "MATCH (p2:Person {name: 'name_2'})-[relation:Friend]->(p3:Person {name: 'name_3'})" +
+ " SET relation.year=23;";
+
+ let writeList = [
+ INSERT_VERTEX_1,
+ INSERT_VERTEX_2,
+ INSERT_VERTEX_3,
+ UPDATE_VERTEX_3,
+ INSERT_EDGE_12,
+ INSERT_EDGE_23,
+ UPDATE_EDGE_23,
+ ]
+
+ if(store != null) {
+ writeList.forEach((gql) => {
+ (store as graphStore.GraphStore).write(gql).then(() => {
+ console.info('Write successfully');
+ }).catch((err: BusinessError) => {
+ console.error(`Write failed, code is ${err.code}, message is ${err.message}`);
+ });
+ });
+ }
+ ```
+
+4. Call **read()** to query vertexes, edges, and paths. The example code is as follows:
+
+ ```ts
+ const QUERY_VERTEX = "MATCH (person:Person) RETURN person;"
+
+ const QUERY_EDGE = "MATCH ()-[relation:Friend]->() RETURN relation;"
+
+ const QUERY_PATH = "MATCH path=(a:Person {name: 'name_1'})-[]->{2, 2}(b:Person {name: 'name_3'}) RETURN path;"
+
+ if(store != null) {
+ (store as graphStore.GraphStore).read(QUERY_VERTEX).then((result: graphStore.Result) => {
+ console.info('Query vertex successfully');
+ result.records?.forEach((data) => {
+ for (let item of Object.entries(data)) {
+ const key = item[0];
+ const value = item[1];
+ const vertex = value as graphStore.Vertex;
+ console.info(`key : ${key}, vertex.properties : ${JSON.stringify(vertex.properties)}`);
+ }
+ });
+ }).catch((err: BusinessError) => {
+ console.error(`Query vertex failed, code is ${err.code}, message is ${err.message}`);
+ });
+
+ (store as graphStore.GraphStore).read(QUERY_EDGE).then((result: graphStore.Result) => {
+ console.info('Query edge successfully');
+ result.records?.forEach((data) => {
+ for (let item of Object.entries(data)) {
+ const key = item[0];
+ const value = item[1];
+ const edge = value as graphStore.Edge;
+ console.info(`key : ${key}, edge.properties : ${JSON.stringify(edge.properties)}`);
+ }
+ });
+ }).catch((err: BusinessError) => {
+ console.error(`Query edge failed, code is ${err.code}, message is ${err.message}`);
+ });
+
+ (store as graphStore.GraphStore).read(QUERY_PATH).then((result: graphStore.Result) => {
+ console.info('Query path successfully');
+ result.records?.forEach((data) => {
+ for (let item of Object.entries(data)) {
+ const key = item[0];
+ const value = item[1];
+ const path = value as graphStore.Path;
+ console.info(`key : ${key}, path.length : ${path.length}`);
+ }
+ });
+ }).catch((err: BusinessError) => {
+ console.error(`Query path failed, code is ${err.code}, message is ${err.message}`);
+ })
+ }
+ ```
+
+5. Call **write()** to delete vertexes and edges. The example code is as follows:
+
+ ```ts
+ const DELETE_VERTEX_AND_RELATED_EDGE = "MATCH (p:Person {name: 'name_1'}) DETACH DELETE p;"
+
+ const DELETE_EDGE_ONLY = "MATCH (p2:Person {name: 'name_2'})-[relation: Friend]->(p3:Person {name: 'name_3'})" +
+ " DETACH DELETE relation;"
+
+ if(store != null) {
+ (store as graphStore.GraphStore).write(DELETE_VERTEX_AND_RELATED_EDGE).then(() => {
+ console.info('Delete vertex and related edge successfully');
+ }).catch((err: BusinessError) => {
+ console.error(`Delete vertex and related edge failed, code is ${err.code}, message is ${err.message}`);
+ });
+
+ (store as graphStore.GraphStore).write(DELETE_EDGE_ONLY).then(() => {
+ console.info('Delete edge only successfully');
+ }).catch((err: BusinessError) => {
+ console.error(`Delete edge only failed, code is ${err.code}, message is ${err.message}`);
+ })
+ }
+ ```
+
+6. Create a transaction instance and use it to write, query, commit, and roll back data. The example code is as follows:
+
+ ```ts
+ let transactionRead: graphStore.Transaction | null = null;
+ let transactionWrite: graphStore.Transaction | null = null;
+
+ const INSERT = "INSERT (:Person {name: 'name_5', age: 55});";
+
+ const QUERY = "MATCH (person:Person) RETURN person;";
+
+ if(store != null) {
+ (store as graphStore.GraphStore).createTransaction().then((trans: graphStore.Transaction) => {
+ transactionRead = trans;
+ console.info('Create transactionRead successfully');
+ }).catch((err: BusinessError) => {
+ console.error(`Create transactionRead failed, code is ${err.code}, message is ${err.message}`);
+ });
+
+ (store as graphStore.GraphStore).createTransaction().then((trans: graphStore.Transaction) => {
+ transactionWrite = trans;
+ console.info('Create transactionWrite successfully');
+ }).catch((err: BusinessError) => {
+ console.error(`Create transactionWrite failed, code is ${err.code}, message is ${err.message}`);
+ });
+
+ if(transactionRead != null) {
+ (transactionRead as graphStore.Transaction).read(QUERY).then((result: graphStore.Result) => {
+ console.info('Transaction read successfully');
+ result.records?.forEach((data) => {
+ for (let item of Object.entries(data)) {
+ const key = item[0];
+ const value = item[1];
+ const vertex = value as graphStore.Vertex;
+ console.info(`key : ${key}, vertex.properties : ${JSON.stringify(vertex.properties)}`);
+ }
+ });
+ }).catch((err: BusinessError) => {
+ console.error(`Transaction read failed, code is ${err.code}, message is ${err.message}`);
+ });
+
+ (transactionRead as graphStore.Transaction).rollback().then(() => {
+ console.info(`Rollback successfully`);
+ transactionRead = null;
+ }).catch ((err: BusinessError) => {
+ console.error(`Rollback failed, code is ${err.code}, message is ${err.message}`);
+ })
+ }
+
+ if(transactionWrite != null) {
+ (transactionWrite as graphStore.Transaction).write(INSERT).then(() => {
+ console.info('Transaction write successfully');
+ }).catch((err: BusinessError) => {
+ console.error(`Transaction write failed, code is ${err.code}, message is ${err.message}`);
+ });
+
+ (transactionWrite as graphStore.Transaction).commit().then(() => {
+ console.info(`Commit successfully`);
+ transactionWrite = null;
+ }).catch ((err: BusinessError) => {
+ console.error(`Commit failed, code is ${err.code}, message is ${err.message}`);
+ })
+ }
+ }
+ ```
+
+7. Delete the graph store. Call **deleteStore()** to delete the graph store and related database files. The example code is as follows:
+
+ ```ts
+ const DROP_GRAPH_GQL = "DROP GRAPH test;"
+
+ class EntryAbility extends UIAbility {
+ onWindowStageDestroy() {
+ if(store != null) {
+ // Delete the graph. This process is skipped here.
+ (store as graphStore.GraphStore).write(DROP_GRAPH_GQL).then(() => {
+ console.info('Drop graph successfully');
+ }).catch((err: BusinessError) => {
+ console.error(`Drop graph failed, code is ${err.code}, message is ${err.message}`);
+ });
+
+ // Close the database. EntryAbility is used as an example.
+ (store as graphStore.GraphStore).close().then(() => {
+ console.info(`Close successfully`);
+ }).catch ((err: BusinessError) => {
+ console.error(`Close failed, code is ${err.code}, message is ${err.message}`);
+ })
+ }
+
+ // The StoreConfig used for deleting a database must be the same as that used for creating the database.
+ graphStore.deleteStore(this.context, STORE_CONFIG_NEW).then(() => {
+ store = null;
+ console.info('Delete GraphStore successfully.');
+ }).catch((err: BusinessError) => {
+ console.error(`Delete GraphStore failed, code is ${err.code},message is ${err.message}`);
+ })
+ }
+ }
+ ```
diff --git a/en/application-dev/database/data-persistence-by-preferences.md b/en/application-dev/database/data-persistence-by-preferences.md
index fa4f2cdcebe235d500dce3a2cf5e029a874bc546..e355f343a04b0a76e683ebc2fe4700b5b1a61112 100644
--- a/en/application-dev/database/data-persistence-by-preferences.md
+++ b/en/application-dev/database/data-persistence-by-preferences.md
@@ -17,38 +17,44 @@ The preference persistent file of an application is stored in the application sa
## Storage Types
-By default, user preferences are stored in XML format. Since API version 16, the CLKV format is provided.
+By default, user preferences are stored in XML format. Since API version 18, the GSKV format is provided.
### XML
Data is stored in the form of XML files, which allow high versatility and cross-platform operations. When XML is used, preference data operations are primarily performed in the memory. You can call **flush()** to persist the data when necessary. This storage type is recommended for single-process, small data volume scenarios.
-### CLKV
-CLKV is available since API version 16. It supports concurrent read and write in multiple processes. When CLKV is used, preference data operations are flushed to the storage device in real time. This storage type is recommended for multi-process concurrency scenarios.
+### GSKV
+GSKV is available since API version 18. It supports concurrent read and write in multiple processes. When GSKV is used, preference data operations are flushed to the storage device in real time. This storage type is recommended for multi-process concurrency scenarios.
## Constraints
### Preferences Constraints
- The key in a KV pair must be a string and cannot be empty or exceed 1024 bytes.
+
- If the value is of the string type, use the UTF-8 encoding format. It can be empty. If not empty, it cannot exceed 16 MB.
+- If the data to be stored contains a string that is not in UTF-8 format, store it in an Uint8Array. Otherwise, the persistent file may be damaged due to format errors.
+
+- After **removePreferencesFromCache** or **deletePreferences** is called, the subscription to data changes will be automatically canceled. After **getPreferences** is called again, you need to subscribe to data changes again.
+
+- Do not call **deletePreferences** concurrently with other APIs in multi-thread or multi-process mode. Otherwise, unexpected behavior may occur.
+
### XML Constraints
- The XML type (default for preferences) cannot ensure process concurrency safety, posing risks of file corruption and data loss. It is not recommended for use in multi-process scenarios.
- Memory usage will increase with the amount of stored data. You are advised to keep the stored data below 50 MB. When the stored data is large, using synchronous APIs to create **Preferences** objects and persist data will become time consuming. Avoid using it in the main thread, as it may cause appfreeze problems.
-### CLKV Constraints
+### GSKV Constraints
-- CLKV does not support cross-platform operations. Before using this type, call **isStorageTypeSupported** to check whether it is supported.
-- Do not call **deletePreferences** concurrently with other APIs in multi-thread or multi-process mode. Otherwise, unexpected behavior may occur.
-- In OpenHarmony, a user group is a logical collection of users with the same characteristics. These users share certain rights. User groups are used to facilitate system management and control user access rights. If the user group is involved when CLKV is used by multiple processes, ensure that the processes belong to the same group.
+- GSKV does not support cross-platform operations. Before using it, call **isStorageTypeSupported** to check whether it is supported.
+- In OpenHarmony, a user group is a logical collection of users with the same characteristics. These users share certain rights. User groups are used to facilitate system management and control user access rights. If the user group is involved when GSKV is used by multiple processes, ensure that the processes belong to the same group.
## Available APIs
-The following table lists the APIs used for persisting user preference data. For more information about the APIs, see [User Preferences](../reference/apis-arkdata/js-apis-data-preferences.md).
+The following table lists the APIs related to user preference persistence. For more information about the APIs, see [User Preferences](../reference/apis-arkdata/js-apis-data-preferences.md).
| API | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
@@ -74,15 +80,15 @@ The following table lists the APIs used for persisting user preference data. For
2. (Optional) Set the storage type.
- This step is optional. By default, preferences data is stored in XML format. Since API version 16, CLKV is supported.
+ This step is optional. By default, preferences data is stored in XML format. Since API version 18, GSKV is supported.
- Before using CLKV, call **isStorageTypeSupported()** to check whether the current platform supports CLKV.
+ Before using GSKV, call **isStorageTypeSupported()** to check whether the current platform supports it.
- If **false** is returned, the platform does not support CLKV. In this case, use XML.
+ If **false** is returned, the platform does not support GSKV. In this case, use XML.
```ts
- let isClkvSupported = preferences.isStorageTypeSupported(preferences.StorageType.CLKV);
- console.info("Is clkv supported on this platform: " + isClkvSupported);
+ let isGskvSupported = preferences.isStorageTypeSupported(preferences.StorageType.GSKV);
+ console.info("Is gskv supported on this platform: " + isGskvSupported);
```
3. Obtain a **Preferences** instance.
@@ -119,9 +125,9 @@ The following table lists the APIs used for persisting user preference data. For
```
- Obtain a **Preferences** instance in CLKV format.
+ Obtain a **Preferences** instance in GSKV format.
- If you want to use CLKV and the platform supports it, you can obtain the **Preferences** instance as follows. However, the storage type cannot be changed once selected.
+ If you want to use GSKV and the platform supports it, you can obtain the **Preferences** instance as follows. However, the storage type cannot be changed once selected.
Stage model:
```ts
@@ -133,7 +139,7 @@ The following table lists the APIs used for persisting user preference data. For
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' , storageType: preferences.StorageType.CLKV};
+ let options: preferences.Options = { name: 'myStore' , storageType: preferences.StorageType.GSKV};
dataPreferences = preferences.getPreferencesSync(this.context, options);
}
}
@@ -147,7 +153,7 @@ The following table lists the APIs used for persisting user preference data. For
import { BusinessError } from '@kit.BasicServicesKit';
let context = featureAbility.getContext();
- let options: preferences.Options = { name: 'myStore' , storageType: preferences.StorageType.CLKV};
+ let options: preferences.Options = { name: 'myStore' , storageType: preferences.StorageType.GSKV};
let dataPreferences: preferences.Preferences = preferences.getPreferencesSync(context, options);
```
@@ -159,7 +165,7 @@ The following table lists the APIs used for persisting user preference data. For
For the data stored in the default mode (XML), you can call **flush()** to persist the data written if required.
- If CLKV is used, the data is persisted in a file on realtime basis after being written.
+ If GSKV is used, the data is persisted in a file on realtime basis after being written.
> **NOTE**
>
@@ -251,7 +257,7 @@ The following table lists the APIs used for persisting user preference data. For
})
```
- If the preferences data is stored in CLKV format, the observer callback will be triggered after the subscribed value changes (without the need for calling **flush()**).
+ If the preferences data is stored in GSKV format, the observer callback will be triggered after the subscribed value changes (without the need for calling **flush()**).
Example:
```ts
@@ -278,7 +284,7 @@ The following table lists the APIs used for persisting user preference data. For
>
> - The deleted data and files cannot be restored.
>
- > - If CLKV is used, this API cannot be called concurrently with other APIs (including multiple processes). Otherwise, unexpected behavior may occur.
+ > - If GSKV is used, this API cannot be called concurrently with other APIs (including multiple processes). Otherwise, unexpected behavior may occur.
Example:
diff --git a/en/application-dev/database/data-persistence-by-rdb-store.md b/en/application-dev/database/data-persistence-by-rdb-store.md
index 220aee5eab45f0229f7f16f593828147dff0c4b0..53ae374946988c459c23d67f3a1bc3a74589c2bb 100644
--- a/en/application-dev/database/data-persistence-by-rdb-store.md
+++ b/en/application-dev/database/data-persistence-by-rdb-store.md
@@ -54,12 +54,12 @@ The following table lists the APIs used for RDB data persistence. Most of the AP
| delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void | Deletes data from the RDB store based on the specified **predicates** instance.|
| query(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void | Queries data in the RDB store based on specified conditions.|
| deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void | Deletes an RDB store.|
-
+| isTokenizerSupported(tokenizer: Tokenizer): boolean | Checks whether the specified tokenizer is supported.|
## How to Develop
Unless otherwise specified, the sample code without "stage model" or "FA model" applies to both models.
-If error code 14800011 is reported, the RDB store is corrupted and needs to be rebuilt. For details, see [Rebuilding an RDB Store](data-backup-and-restore.md#rebuilding-an-rdb-store).
+If error 14800011 is thrown, you need to rebuild the database and restore data to ensure normal application development. For details, see [Rebuilding a RDB Store](data-backup-and-restore.md#rebuilding-an-rdb-store).
1. Obtain an **RdbStore** instance, which includes operations of creating an RDB store and tables, and upgrading or downgrading the RDB store.
Example:
@@ -74,12 +74,19 @@ If error code 14800011 is reported, the RDB store is corrupted and needs to be r
// In this example, Ability is used to obtain an RdbStore instance. You can use other implementations as required.
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage) {
+ // Before using a tokenizer, call isStorageTypeSupported to check whether the tokenizer is supported by the current platform.
+ let tokenType = relationalStore.Tokenizer.ICU_TOKENIZER;
+ let tokenTypeSupported = relationalStore.isTokenizerSupported(tokenType);
+ if (!tokenTypeSupported) {
+ console.error(`ICU_TOKENIZER is not supported on this platform.`);
+ }
const STORE_CONFIG :relationalStore.StoreConfig= {
name: 'RdbTest.db', // Database file name.
securityLevel: relationalStore.SecurityLevel.S3, // Database security level.
encrypt: false, // Whether to encrypt the database. This parameter is optional. By default, the database is not encrypted.
customDir: 'customDir/subCustomDir' // (Optional) Customized database path. The database is created in the context.databaseDir + '/rdb/' + customDir directory, where context.databaseDir indicates the application sandbox path, '/rdb/' indicates a relational database, and customDir indicates the customized path. If this parameter is not specified, an RdbStore instance is created in the sandbox directory of the application.
isReadOnly: false // (Optional) Specify whether the RDB store is opened in read-only mode. The default value is false, which means the RDB store is readable and writable. If this parameter is true, data can only be read from the RDB store. If write operation is performed, error code 801 is returned.
+ tokenizer: tokenType // (Optional) Type of the tokenizer used in full-text search (FTS). If this parameter is left blank, only English word segmentation is supported in FTS.
};
// Check the RDB store version. If the version is incorrect, upgrade or downgrade the RDB store.
diff --git a/en/application-dev/database/data-persistence-by-vector-store.md b/en/application-dev/database/data-persistence-by-vector-store.md
new file mode 100644
index 0000000000000000000000000000000000000000..af5fd2e55448b8064bc837254e472bf465d01bbd
--- /dev/null
+++ b/en/application-dev/database/data-persistence-by-vector-store.md
@@ -0,0 +1,337 @@
+# Persisting Vector Store Data (ArkTS)
+
+
+## When to Use
+
+Vector stores are designed to store, manage, and retrieve vector data while also supporting relational data processing for scalar values. The data type **floatvector** is used to store data vectorization results, enabling rapid retrieval and similarity searches for such data.
+
+## Basic Concepts
+
+- **ResultSet**: a set of query results, which allows access to the required data in flexible modes.
+- **floatvector**: vector data, for example, **[1.0, 3.0, 2.4, 5.1, 6.2, 11.7]**.
+
+## Constraints
+
+- By default, the Write Ahead Log (WAL) and the **FULL** flushing mode are used.
+
+- A vector store supports a maximum of four read connections and one write connection at a time by default. A thread can perform the read operation when acquiring an idle read connection. If there is no idle read connection, a new read connection will be created.
+
+- To ensure data accuracy, the database supports only one write operation at a time. Concurrent write operations are performed in serial mode.
+
+- Once an application is uninstalled, related database files and temporary files are automatically deleted from the device.
+
+- ArkTS supports basic data types such as number, string, binary, and boolean, and the special data type ValueType.
+
+- To ensure successful data access, limit the size of a data record to 2 MB. Data records larger than this may be inserted correctly but fail to read.
+
+## Available APIs
+
+The following lists only the APIs for persisting vector store data. For details about more APIs and their usage, see [RDB Store](../reference/apis-arkdata/js-apis-data-relationalStore.md).
+
+| API| Description|
+| -------- | -------- |
+| getRdbStore(context: Context, config: StoreConfig): Promise<RdbStore> | Obtains an **RdbStore** instance for data operations.|
+| execute(sql: string, txId: number, args?: Array<ValueType>): Promise<ValueType> | Executes SQL statements that contain specified parameters. The number of operators (such as =, >, and <) in the SQL statements cannot exceed 1000.|
+| querySql(sql: string, bindArgs?: Array<ValueType>):Promise<ResultSet> | Queries data in the RDB store using the specified SQL statement. The number of operators (such as =, >, and <) in the SQL statements cannot exceed 1000.|
+| beginTrans(): Promise<number> | Starts the transaction before executing the SQL statements.|
+| commit(txId : number):Promise<void> | Commits the executed SQL statements. This API must be used together with **beginTrans**.|
+| rollback(txId : number):Promise<void> | Rolls back the executed SQL statements. This API must be used together with **beginTrans**.|
+| deleteRdbStore(context: Context, config: StoreConfig): Promise<void> | Deletes an RDB store.|
+| isVectorSupported(): boolean | Checks whether the system supports vector stores.|
+
+## How to Develop
+
+1. Check whether the current system supports vector stores. The sample code is as follows:
+
+ ```ts
+ import { relationalStore } from '@kit.ArkData'; // Import the relationalStore module.
+ import { UIAbility } from '@kit.AbilityKit';
+ import { BusinessError } from '@kit.BasicServicesKit';
+ import { window } from '@kit.ArkUI';
+ // In this example, Ability is used to obtain an RdbStore instance. You can use other implementations as required.
+ class EntryAbility extends UIAbility {
+ async onWindowStageCreate(windowStage: window.WindowStage) {
+ // Check whether the current system supports vector stores.
+ let ret = relationalStore.isVectorSupported();
+ if (!ret) {
+ console.error(`vectorDB is not supported .`);
+ return;
+ }
+ // Open the database, and add, delete, and modify data.
+ }
+ }
+ ```
+
+2. If the system supports vector stores, obtain an **RdbStore** instance. Call **getRdbStore()** to create a database and create a table.
+
+ > **NOTE**
+ >
+ > - The RDB store created by an application varies with the context. Multiple RDB stores are created for the same database name with different application contexts. For example, each UIAbility has its own context.
+ >
+ > - When an application calls **getRdbStore()** to obtain an RDB store instance for the first time, the corresponding database file is generated in the application sandbox. When the RDB store is used, temporary files ended with **-wal** and **-shm** may be generated in the same directory as the database file. If you want to move the database files to other places, you must also move these temporary files. After the application is uninstalled, the database files and temporary files generated on the device are also removed.
+ >
+ > - For details about the error codes, see [Universal Error Codes](../reference/errorcode-universal.md) and [RDB Store Error Codes](../reference/apis-arkdata/errorcode-data-rdb.md).
+
+ The sample code is as follows:
+
+ ```ts
+ let store: relationalStore.RdbStore | undefined = undefined;
+ const STORE_CONFIG :relationalStore.StoreConfig= {
+ name: 'VectorTest.db', // Database file name.
+ securityLevel: relationalStore.SecurityLevel.S1 // Database security level.
+ vector: true // Optional. This parameter must be true for a vector store.
+ };
+
+ relationalStore.getRdbStore(this.context, STORE_CONFIG).then(async (rdbStore: relationalStore.RdbStore) => {
+ store = rdbStore;
+ // Create a table. floatvector (2) indicates that repr is 2-dimensional.
+ const SQL_CREATE_TABLE = 'CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY, repr floatvector(2));';
+ // The second parameter indicates that transaction is not enabled. The third parameter undefined indicates that parameter binding is not used.
+ await store!.execute(SQL_CREATE_TABLE, 0, undefined);
+ }).catch((err: BusinessError) => {
+ console.error(`Get RdbStore failed, code is ${err.code}, message is ${err.message}`);
+ });
+ ```
+
+3. Call **execute()** to insert data to the vector store.
+
+ > **NOTE**
+ >
+ > **RelationalStore** does not provide explicit flush operations for data persistence. The data inserted is persisted.
+
+ The sample code is as follows:
+
+ ```ts
+ try {
+ // Use parameter binding.
+ const vectorValue: Float32Array = Float32Array.from([1.2, 2.3]);
+ await store!.execute("insert into test VALUES(?, ?);", 0, [0, vectorValue]);
+ // Do not use parameter binding.
+ await store!.execute("insert into test VALUES(1, '[1.3, 2.4]');", 0, undefined);
+ } catch (err) {
+ console.error(`execute insert failed, code is ${err.code}, message is ${err.message}`);
+ }
+ ```
+
+4. Call **execute()** to modify or delete data. The sample code is as follows:
+
+ ```ts
+ // Modify data.
+ try {
+ // Use parameter binding.
+ const vectorValue1: Float32Array = Float32Array.from([2.1, 3.2]);
+ await store!.execute("update test set repr = ? where id = ?", 0, [vectorValue1, 0]);
+ // Do not use parameter binding.
+ await store!.execute("update test set repr = '[5.1, 6.1]' where id = 0", 0, undefined);
+ } catch (err) {
+ console.error(`execute update failed, code is ${err.code}, message is ${err.message}`);
+ }
+
+ // Delete data.
+ try {
+ // Use parameter binding.
+ await store!.execute("delete from test where id = ?", 0, [0]);
+ // Do not use parameter binding.
+ await store!.execute("delete from test where id = 0", 0, undefined);
+ } catch (err) {
+ console.error(`execute delete failed, code is ${err.code}, message is ${err.message}`);
+ }
+ ```
+
+5. Call **querySql()** to query data. A **ResultSet** instance is returned.
+
+ > **NOTE**
+ >
+ > Use **close()** to close the **ResultSet** that is no longer used in a timely manner so that the memory allocated can be released.
+
+ The sample code is as follows:
+
+ ```ts
+ // Perform single-table queries.
+ try {
+ // Use parameter binding.
+ const QUERY_SQL = "select id, repr <-> ? as distance from test where id > ? order by repr <-> ? limit 5;";
+ const vectorValue2: Float32Array = Float32Array.from([6.2, 7.3]);
+ let resultSet = await store!.querySql(QUERY_SQL, [vectorValue2, 0, vectorValue2]);
+ while (resultSet!.goToNextRow()) {
+ let id = resultSet.getValue(0);
+ let dis = resultSet.getValue(1);
+ }
+ resultSet!.close();
+
+ // Do not use parameter binding.
+ const QUERY_SQL1 = "select id, repr <-> '[6.2, 7.3]' as distance from test where id > 0 order by repr <-> '[6.2, 7.3]' limit 5;";
+ resultSet = await store!.querySql(QUERY_SQL1);
+ resultSet!.close();
+ } catch (err) {
+ console.error(`query failed, code is ${err.code}, message is ${err.message}`);
+ }
+
+ // Perform subqueries.
+ try {
+ // Create the second table.
+ let CREATE_SQL = "CREATE TABLE IF NOT EXISTS test1(id text PRIMARY KEY);";
+ await store!.execute(CREATE_SQL);
+ let resultSet = await store!.querySql("select * from test where id in (select id from test1);");
+ resultSet!.close();
+ } catch (err) {
+ console.error(`query failed, code is ${err.code}, message is ${err.message}`);
+ }
+
+ // Perform aggregate queries.
+ try {
+ let resultSet = await store!.querySql("select * from test where repr <-> '[1.0, 1.0]' > 0 group by id having max(repr <=> '[1.0, 1.0]');");
+ resultSet!.close();
+ } catch (err) {
+ console.error(`query failed, code is ${err.code}, message is ${err.message}`);
+ }
+
+ // Perform multi-table queries.
+ try {
+ // Different union all, union will delete duplicate data.
+ let resultSet = await store!.querySql("select id, repr <-> '[1.5, 5.6]' as distance from test union select id, repr <-> '[1.5, 5.6]' as distance from test order by distance limit 5;");
+ resultSet!.close();
+ } catch (err) {
+ console.error(`query failed, code is ${err.code}, message is ${err.message}`);
+ }
+ ```
+
+6. Create a view and query data. The sample code is as follows:
+
+ ```ts
+ // Perform view queries.
+ try {
+ // Create a view.
+ await store!.execute("CREATE VIEW v1 as select * from test where id > 0;");
+ let resultSet = await store!.querySql("select * from v1;");
+ resultSet!.close();
+ } catch (err) {
+ console.error(`query failed, code is ${err.code}, message is ${err.message}`);
+ }
+ ```
+
+7. Query data using vector indexes.
+
+ The vector store uses vectors as keys to provide efficient and fast search capabilities.
+
+ It supports the basic syntax and extended syntax as follows:
+
+ - Basic syntax:
+
+ ```sql
+ // index_name indicates the index name, index_type indicates the index type, and dist_function indicates the type of distance function for similarity measurement.
+ CREATE INDEX [IF NOT EXISTS] index_name ON table_name USING index_type (column_name dist_function);
+
+ DROP INDEX table_name.index_name;
+ ```
+ - Extended syntax:
+
+ ```sql
+ CREATE INDEX [Basic syntax] [WITH(parameter = value [, ...])];
+ ```
+
+ **Table 1** index_type
+
+ | Type | Description |
+ | --------- | ------------------------------------------------------------ |
+ | gsdiskann | Index for processing high-dimensional dense vector data, such as text embedding and image features. |
+
+ **Table 2** dist_function
+
+ | Type | Operator| Description |
+ | ------ | -------- | ---------- |
+ | L2 | <-> | Euclidean distance.|
+ | COSINE | <=> | Cosine distance.|
+
+ **Table 3** parameter (extended syntax parameters)
+
+ | Parameter | Value Range| Description |
+ | ------ | -------- | ---------- |
+ | QUEUE_SIZE | Value range: [10, 1000]
Default value: **20** | Size of the candidate queue when an index is created for nearest neighbor search. A larger value indicates a lower construction speed and a slightly higher recall rate.|
+ | OUT_DEGREE | Value range: [1, 1200]
Default value: **60** | Number of outgoing edges of a node in the graph. The value of **OUT_DEGREE** cannot exceed **pageSize**. Otherwise, the error GRD_INVALID_ARGS will be thrown.|
+
+ > **NOTE**
+ >
+ > - When deleting an index, you need to specify the table name, that is, **Drop Index table.index_name**.
+ >
+ > - The index created with a table cannot be deleted, for example, the primary key cannot be deleted.
+ >
+ > - When querying data based on vector indexes, you must use **ORDER BY** and **LIMIT**. **ORDER BY** has only one sorting condition, that is, the vector distance condition. If **ORDER BY** is used with **DESC**, vector indexes will not be used. The distance metric used for querying must match the metric used when the index is created. For example, if the vector index is created using **L2**, <-> must be used for the query. Otherwise, the index cannot be hit.
+
+ The sample code is as follows:
+
+ ```ts
+ // Basic syntax
+ try {
+ // Create an index using the basic syntax. The index name is diskann_l2_idx, index column is repr, type is gsdiskann, and the distance metric is L2.
+ await store!.execute("CREATE INDEX diskann_l2_idx ON test USING GSDISKANN(repr L2);");
+ // Delete the diskann_l2_idx index from the test table.
+ await store!.execute("DROP INDEX test.diskann_l2_idx;");
+ } catch (err) {
+ console.error(`create index failed, code is ${err.code}, message is ${err.message}`);
+ }
+
+ // Extended syntax
+ try {
+ // Set QUEUE_SIZE to 20 and OUT_DEGREE to 50.
+ await store!.execute("CREATE INDEX diskann_l2_idx ON test USING GSDISKANN(repr L2) WITH (queue_size=20, out_degree=50);");
+ } catch (err) {
+ console.error(`create ext index failed, code is ${err.code}, message is ${err.message}`);
+ }
+ ```
+
+8. Configure the data aging policy, which allows the application data to be automatically deleted by time or space.
+
+ The syntax is as follows:
+
+ ```sql
+ CREATE TABLE table_name(column_name type [, ...]) [WITH(parameter = value [, ...])];
+ ```
+
+ **parameter** specifies the parameter to set, and **value** specifies the value of the parameter. The following table describes the fields contained in **parameter**.
+
+ **Table 4** parameter (data aging policy parameters)
+
+ | Parameter| Mandatory| Value Range|
+ | ------ | -------- | ---------- |
+ | time_col | Yes| Column name. The value must be an integer and cannot be empty.|
+ | interval | No| Interval for executing the aging task thread. If a write operation is performed after the interval, an aging task will be triggered to delete the data that meets the aging conditions. If the write operation is performed within the interval, no aging task will be triggered.
Value range: [5 second, 1 year]
Default value: **1 day**
Time units supported include **second**, **minute**, **hour**, **day**, **month** and **year**. The value is case-insensitive and supports both singular and plural forms (for example, **2 hour** and **2 hours** are acceptable).|
+ | ttl | No| Data retention period.
Value range: [1 hour, 1 year]
Default value: **3 month**
Time units supported include **second**, **minute**, **hour**, **day**, **month** and **year**. The value is case-insensitive and supports both singular and plural forms (for example, **2 hour** and **2 hours** are acceptable).|
+ | max_num | No| Maximum data volume allowed.
Value range: [100, 1024]
Default value: **1024**
After the aging task deletes expired data, if the remaining data in the table exceeds the value of **max_num**, data tied to the nearest expiration-adjacent time point will be deleted until the total row count falls below **max_num**.|
+
+ Time-related parameters are converted into seconds as follows.
+
+ | Unit| Value in Seconds|
+ | ------ | -------- |
+ | year | 365 * 24 * 60 * 60 |
+ | month | 30 * 24 * 60 * 60 |
+ | day | 24 * 60 * 60 |
+ | hour | 60 * 60 |
+ | minute | 60 |
+
+ For example, if **ttl** is set to **3 months**, the value will be converted into 7,776,000 seconds (3 x (30 * 24 * 60 * 60)).
+
+ The sample code is as follows:
+
+ ```ts
+ try {
+ // The write operation performed every 5 minutes will trigger a data aging task.
+ await store!.execute("CREATE TABLE test2(rec_time integer not null) WITH (time_col = 'rec_time', interval = '5 minute');");
+ } catch (err) {
+ console.error(`configure data aging failed, code is ${err.code}, message is ${err.message}`);
+ }
+ ```
+
+9. Delete the database.
+
+ Call **deleteRdbStore()** to delete the vector store and related database files. The sample code is as follows:
+
+ ```ts
+ try {
+ await relationalStore.deleteRdbStore(this.context, STORE_CONFIG);
+ } catch (err) {
+ console.error(`delete rdbStore failed, code is ${err.code},message is ${err.message}`);
+ }
+ ```
+
+
diff --git a/en/application-dev/database/data-share-overview.md b/en/application-dev/database/data-share-overview.md
index 58c50930f6b7d0ee6ea7b45932e8bd6773be39a7..440384ea3efd42584151ab42dcb4c84f10d9d61a 100644
--- a/en/application-dev/database/data-share-overview.md
+++ b/en/application-dev/database/data-share-overview.md
@@ -1,4 +1,4 @@
-# Cross-Application Data Sharing
+# Overview of Cross-Application Data Sharing
## Introduction
diff --git a/en/application-dev/database/data-sync-of-kv-store.md b/en/application-dev/database/data-sync-of-kv-store.md
index 75aed5cab3ac4e860048cc5b4864ee5c30d218d0..f6738acc38b10e013800809795c2fa6a5b658823 100644
--- a/en/application-dev/database/data-sync-of-kv-store.md
+++ b/en/application-dev/database/data-sync-of-kv-store.md
@@ -81,14 +81,14 @@ When data is added, deleted, or modified, a notification is sent to the subscrib
The following table lists the APIs for cross-device data sync of the single KV store. Most of the APIs are executed asynchronously, using a callback or promise to return the result. The following table uses the callback-based APIs as an example. For more information about the APIs, see [Distributed KV Store](../reference/apis-arkdata/js-apis-distributedKVStore.md).
-| API| Description|
+| API| Description|
| -------- | -------- |
-| createKVManager(config: KVManagerConfig): KVManager | Creates a **KvManager** instance to manage database objects.|
-| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | Obtains a KV store of the specified type.|
-| put(key: string, value: Uint8Array \| string \| number \| boolean, callback: AsyncCallback<void>): void | Inserts and updates data.|
-| on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void | Subscribes to data changes in the KV store.|
-| get(key: string, callback: AsyncCallback<boolean \| string \| number \| Uint8Array>): void | Queries the value of the specified key.|
-| sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void | Triggers a manual sync of the KV store.|
+| createKVManager(config: KVManagerConfig): KVManager | Creates a **KvManager** instance to manage database objects.|
+| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | Obtains a KV store of the specified type.|
+| put(key: string, value: Uint8Array \| string \| number \| boolean, callback: AsyncCallback<void>): void | Inserts and updates data.|
+| on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void | Subscribes to data changes in the KV store.|
+| get(key: string, callback: AsyncCallback<boolean \| string \| number \| Uint8Array>): void | Queries the value of the specified key.|
+| sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void | Triggers a manual sync of the KV store.|
## How to Develop
@@ -102,7 +102,7 @@ The following uses a single KV store as an example to describe how to implement
> The security level of the destination device (to which data is synced) cannot be higher than that of the source device. For details, see [Access Control Mechanism in Cross-Device Sync](access-control-by-device-and-data-level.md#access-control-mechanism-in-cross-device-sync).
1. Import the module.
-
+
```ts
import { distributedKVStore } from '@kit.ArkData';
```
@@ -117,7 +117,7 @@ The following uses a single KV store as an example to describe how to implement
(1) Create a **kvManagerConfig** object based on the application context.
(2) Create a **KvManager** instance.
-
+
```ts
// Obtain the context of the stage model.
import { window } from '@kit.ArkUI';
@@ -164,7 +164,7 @@ The following uses a single KV store as an example to describe how to implement
(1) Declare the ID of the distributed KV store to create, for example, **'storeId'** in the sample code.
(2) Disable the auto sync function (**autoSync:false**) to facilitate subsequent verification of the sync function. If sync is required, call the **sync()** interface.
-
+
```ts
let kvStore: distributedKVStore.SingleKVStore | undefined = undefined;
try {
@@ -219,7 +219,7 @@ The following uses a single KV store as an example to describe how to implement
```
5. Subscribe to distributed data changes. To unsubscribe from the data changes, call [off('dataChange')](../reference/apis-arkdata/js-apis-distributedKVStore.md#offdatachange).
-
+
```ts
try {
kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => {
@@ -236,7 +236,7 @@ The following uses a single KV store as an example to describe how to implement
(1) Construct the key and value to be written to the single KV store.
(2) Write KV pairs to the single KV store.
-
+
```ts
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
// If schema is not defined, pass in other values that meet the requirements.
@@ -260,7 +260,7 @@ The following uses a single KV store as an example to describe how to implement
(1) Construct the key to be queried from the single KV store.
(2) Query data from the single KV store.
-
+
```ts
try {
kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
@@ -320,4 +320,3 @@ The following uses a single KV store as an example to describe how to implement
console.error("createDeviceManager errCode:" + error.code + ",errMessage:" + error.message);
}
```
-
diff --git a/en/application-dev/database/data-sync-of-rdb-store.md b/en/application-dev/database/data-sync-of-rdb-store.md
index 1c85c7c8da15f770281eac3054755ce9c2487905..1a6e14721afad10ae134f5440eace33636bbe6ad 100644
--- a/en/application-dev/database/data-sync-of-rdb-store.md
+++ b/en/application-dev/database/data-sync-of-rdb-store.md
@@ -44,6 +44,7 @@ When data is added, deleted, or modified, a notification is sent to the subscrib
- Each RDB store supports a maximum of eight callbacks for subscription of data change notifications.
+- A table containing composite keys cannot be set as a distributed table.
## Available APIs
diff --git a/en/application-dev/database/encrypted_estore_guidelines.md b/en/application-dev/database/encrypted_estore_guidelines.md
index 471a6404d26a3ec13e11d1669e14a03eb756692b..842da21544a552265714d3eeba70cbd41d78ecf1 100644
--- a/en/application-dev/database/encrypted_estore_guidelines.md
+++ b/en/application-dev/database/encrypted_estore_guidelines.md
@@ -14,9 +14,7 @@ Both the KV store and RDB store can be used as an EL5 database.
The following classes are encapsulated to implement the data operations and transfer between EL2 and EL5 databases:
- **Mover** class: provides APIs for moving data from an EL2 database to an EL5 database after the screen is unlocked.
-
- **Store** class: provides APIs for obtaining a database instance, adding, deleting, and updating data, and obtaining the data count in the database.
-
- **SecretKeyObserver** class: provides APIs for obtaining the key status. After the key is destroyed, the EL5 database will be closed.
- **ECStoreManager** class: provides APIs for managing the EL2 and EL5 databases.
@@ -388,7 +386,7 @@ export default class EntryAbility extends UIAbility {
autoSync: false,
// If kvStoreType is left empty, a device KV store is created by default.
kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
- // kvStoreType is distributedKVStore.KVStoreType.DEVICE_COLLABORATION for a device KV store.
+ // The value distributedKVStore.KVStoreType.DEVICE_COLLABORATION indicates a device KV store.
securityLevel: distributedKVStore.SecurityLevel.S3
}
}
@@ -407,7 +405,7 @@ export default class EntryAbility extends UIAbility {
autoSync: false,
// If kvStoreType is left empty, a device KV store is created by default.
kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
- // kvStoreType is distributedKVStore.KVStoreType.DEVICE_COLLABORATION for a device KV store.
+ // The value distributedKVStore.KVStoreType.DEVICE_COLLABORATION indicatates a device KV store.
securityLevel: distributedKVStore.SecurityLevel.S3
}
}
diff --git a/en/application-dev/database/figures/dataManagement.jpg b/en/application-dev/database/figures/dataManagement.jpg
index 6555d34202927dc202fcb0ab233bc42740f39dbe..af428d9659944731a4731da326c430a7c383c62e 100644
Binary files a/en/application-dev/database/figures/dataManagement.jpg and b/en/application-dev/database/figures/dataManagement.jpg differ
diff --git a/en/application-dev/database/native-relational-store-guidelines.md b/en/application-dev/database/native-relational-store-guidelines.md
index 1b339381391919057ba41a2a1a2fa91077000e01..58c9aa5ddcca63050c555ae03356e37f0e43a9ce 100644
--- a/en/application-dev/database/native-relational-store-guidelines.md
+++ b/en/application-dev/database/native-relational-store-guidelines.md
@@ -35,15 +35,15 @@ For details about the interfaces, see [RDB](../reference/apis-arkdata/_r_d_b.md)
| OH_Rdb_GetOrOpen(const OH_Rdb_Config *config, int *errCode) | Obtains an **OH_Rdb_Store** instance for RDB store operations.|
| OH_Rdb_Execute(OH_Rdb_Store *store, const char *sql) | Executes an SQL statement that contains specified arguments but returns no value.|
| OH_Rdb_Insert(OH_Rdb_Store *store, const char *table, OH_VBucket *valuesBucket) | Inserts a row of data into a table.|
-| OH_Rdb_Update(OH_Rdb_Store *store, OH_VBucket *valuesBucket, OH_Predicates *predicates) | Updates data in an RDB store. |
-| OH_Rdb_Delete(OH_Rdb_Store *store, OH_Predicates *predicates) | Deletes data from an RDB store. |
-| OH_Rdb_Query(OH_Rdb_Store *store, OH_Predicates *predicates, const char *const *columnNames, int length) | Queries data in an RDB store. |
+| OH_Rdb_Update(OH_Rdb_Store *store, OH_VBucket *valuesBucket, OH_Predicates *predicates) | Updates data in an RDB store.|
+| OH_Rdb_Delete(OH_Rdb_Store *store, OH_Predicates *predicates) | Deletes data from an RDB store.|
+| OH_Rdb_Query(OH_Rdb_Store *store, OH_Predicates *predicates, const char *const *columnNames, int length) | Queries data in an RDB store.|
| OH_Rdb_DeleteStore(const OH_Rdb_Config *config) | Deletes an RDB store.|
| OH_VBucket_PutAsset(OH_VBucket *bucket, const char *field, Rdb_Asset *value) | Puts an RDB asset into an **OH_VBucket** object.|
| OH_VBucket_PutAssets(OH_VBucket *bucket, const char *field, Rdb_Asset *value, uint32_t count) | Puts RDB assets into an **OH_VBucket** object.|
| OH_Rdb_SetDistributedTables(OH_Rdb_Store *store, const char *tables[], uint32_t count, Rdb_DistributedType type, const Rdb_DistributedConfig *config) | Sets distributed database tables.|
-| OH_Rdb_FindModifyTime(OH_Rdb_Store *store, const char *tableName, const char *columnName, OH_VObject *values) | Obtains the last modification time of the data in the specified column of a table. |
-| OH_Rdb_CloudSync(OH_Rdb_Store *store, Rdb_SyncMode mode, const char *tables[], uint32_t count, const Rdb_ProgressObserver *observer) | Manually performs device-cloud sync for a table. The cloud service must be available. |
+| OH_Rdb_FindModifyTime(OH_Rdb_Store *store, const char *tableName, const char *columnName, OH_VObject *values) | Obtains the last modification time of the data in the specified column of a table.|
+| OH_Rdb_CloudSync(OH_Rdb_Store *store, Rdb_SyncMode mode, const char *tables[], uint32_t count, const Rdb_ProgressObserver *observer) | Manually performs device-cloud sync for a table. The cloud service must be available.|
| int OH_Data_Asset_SetName(Data_Asset *asset, const char *name) | Sets the name for a data asset.|
| int OH_Data_Asset_SetUri(Data_Asset *asset, const char *uri) | Sets the absolute path for a data asset.|
| int OH_Data_Asset_SetPath(Data_Asset *asset, const char *path) | Sets the relative path in the application sandbox directory for a data asset.|
@@ -90,11 +90,7 @@ libnative_rdb_ndk.z.so
#include
```
-1. Obtain an **OH_Rdb_Store** instance and create a database file.
-
- The **dataBaseDir** variable specifies the application sandbox path. In the stage model, you are advised to use the database directory. For details, see the **databaseDir** attribute of [Context](../reference/apis-ability-kit/js-apis-inner-application-context.md). The FA model does not provide any API for obtaining the database sandbox path. Use the application directory instead. For details, see **getFilesDir** of [Context](../reference/apis-ability-kit/js-apis-inner-app-context.md).
-
- **area** indicates the security level of the directory for database files. For details, see [contextConstant](../reference/apis-ability-kit/js-apis-app-ability-contextConstant.md). During development, you need to implement the conversion from **AreaMode** to **Rdb_SecurityArea**.
Example:
+1. Obtain an **OH_Rdb_Store** instance and create a database file.
The **dataBaseDir** variable specifies the application sandbox path. In the stage model, you are advised to use the database directory. For details, see the **databaseDir** attribute of [Context](../reference/apis-ability-kit/js-apis-inner-application-context.md). The FA model does not provide any API for obtaining the database sandbox path. Use the application directory instead. For details, see **getFilesDir** of [Context](../reference/apis-ability-kit/js-apis-inner-app-context.md).
**area** indicates the security level of the directory for database files. For details, see [contextConstant](../reference/apis-ability-kit/js-apis-app-ability-contextConstant.md). During development, you need to implement the conversion from **AreaMode** to **Rdb_SecurityArea**.
Example:
```c
// Create an OH_Rdb_Config object.
@@ -147,7 +143,7 @@ libnative_rdb_ndk.z.so
>
> **RelationalStore** does not provide explicit flush operations for data persistence. The **insert()** API stores data persistently.
-3. Modify or delete data based on the conditions specified by **OH_Predicates**.
+3. Modify or delete data based on the conditions specified by **OH_Predicates**.
Call **OH_Rdb_Update** to modify data, and call **OH_Rdb_Delete** to delete data.
Example:
@@ -189,7 +185,7 @@ libnative_rdb_ndk.z.so
predicates->destroy(predicates);
```
-4. Query data based on the conditions specified by **OH_Predicates**.
+4. Query data based on the conditions specified by **OH_Predicates**.
Call **OH_Rdb_Query** to query data. The data obtained is returned in an **OH_Cursor** object.
Example:
@@ -300,9 +296,7 @@ libnative_rdb_ndk.z.so
cursor->destroy(cursor);
```
-7. Obtain the last modification time of data.
-
- Call **OH_Rdb_FindModifyTime** to obtain the last modification time of data in the specified column of a table. This API returns an **OH_Cursor** object with two columns of data. The first column is the input primary key or row ID, and the second column is the last modification time.
Example:
+7. Obtain the last modification time of data.
Call **OH_Rdb_FindModifyTime** to obtain the last modification time of data in the specified column of a table. This API returns an **OH_Cursor** object with two columns of data. The first column is the input primary key or row ID, and the second column is the last modification time.
Example:
```c
OH_VObject *values = OH_Rdb_CreateValueObject();
@@ -312,9 +306,7 @@ libnative_rdb_ndk.z.so
cursor = OH_Rdb_FindModifyTime(store_, "EMPLOYEE", "ROWID", values);
```
-8. Create distributed tables.
-
- Call **OH_Rdb_SetDistributedTables** to set distributed tables for the table (created by using **OH_Rdb_Execute**). Before using this API, ensure that the cloud service is available.
Example:
+8. Create distributed tables.
Call **OH_Rdb_SetDistributedTables** to set distributed tables for the table (created by using **OH_Rdb_Execute**). Before using this API, ensure that the cloud service is available.
Example:
```c
constexpr int TABLE_COUNT = 1;
@@ -323,11 +315,9 @@ libnative_rdb_ndk.z.so
int errcode = OH_Rdb_SetDistributedTables(store_, table, TABLE_COUNT, Rdb_DistributedType::DISTRIBUTED_CLOUD, &config);
```
-9. Manually perform device-cloud sync for the distributed tables.
-
- Call **OH_Rdb_CloudSync** to perform device-cloud sync for the tables. Before using this API, ensure that the cloud service is available.
Example:
-
- ```c
+9. Manually perform device-cloud sync for the distributed tables.
Call **OH_Rdb_CloudSync** to perform device-cloud sync for the tables. Before using this API, ensure that the cloud service is available.
Example:
+
+ ```c
// Define a callback.
void CloudSyncObserverCallback(void *context, Rdb_ProgressDetails *progressDetails)
{
@@ -338,7 +328,7 @@ libnative_rdb_ndk.z.so
```
10. Register a data observer for the specified event type for an RDB store. When the data changes, the registered callback will be invoked to process the observation. Call **OH_Rdb_Subscribe** to subscribe to data changes. Before using this API, ensure that the cloud service is available.
Example:
-
+
```c
// Define a callback.
void RdbSubscribeBriefCallback(void *context, const char *values[], uint32_t count)
@@ -374,7 +364,7 @@ libnative_rdb_ndk.z.so
Rdb_DataObserver observer = { nullptr, { callback } };
// Subscribe to the local database data changes.
OH_Rdb_Subscribe(store_, Rdb_SubscribeType::RDB_SUBSCRIBE_TYPE_LOCAL_DETAILS, &observer);
-
+
OH_VBucket* valueBucket = OH_Rdb_CreateValuesBucket();
valueBucket->putText(valueBucket, "NAME", "Lisa");
valueBucket->putInt64(valueBucket, "AGE", 18);
@@ -388,34 +378,38 @@ libnative_rdb_ndk.z.so
valueBucket->destroy(valueBucket);
```
-11. Unsubscribe from the events of the specified type for an RDB store. After that, the callback will not be invoked to process the observation. Call **OH_Rdb_Unsubscribe** to unsubscribe from data changes. Before using this API, ensure that the cloud service is available.
Example:
-
- ```c
- // Define a callback.
- void RdbSubscribeBriefCallback(void *context, const char *values[], uint32_t count)
- {
- // Do something.
- }
- Rdb_BriefObserver briefObserver = RdbSubscribeBriefCallback;
- const Rdb_DataObserver briefObs = { .context = nullptr, .callback.briefObserver = briefObserver };
- // Unsubscribe from data changes.
- OH_Rdb_Unsubscribe(store_, Rdb_SubscribeType::RDB_SUBSCRIBE_TYPE_CLOUD, &briefObs);
- ```
+11. Unsubscribe from the events of the specified type for an RDB store. After that, the callback will not be invoked to process the observation.
+
+ Call **OH_Rdb_Unsubscribe** to unsubscribe from data changes. Before using this API, ensure that the cloud service is available.
Example:
+
+ ```c
+ // Define a callback.
+ void RdbSubscribeBriefCallback(void *context, const char *values[], uint32_t count)
+ {
+ // Do something.
+ }
+ Rdb_BriefObserver briefObserver = RdbSubscribeBriefCallback;
+ const Rdb_DataObserver briefObs = { .context = nullptr, .callback.briefObserver = briefObserver };
+ // Unsubscribe from data changes.
+ OH_Rdb_Unsubscribe(store_, Rdb_SubscribeType::RDB_SUBSCRIBE_TYPE_CLOUD, &briefObs);
+ ```
Call **OH_Rdb_Unsubscribe** to unsubscribe from local database data changes.
Example:
- ```c
- // Define a callback.
- void LocalDataChangeObserverCallback1(void *context, const Rdb_ChangeInfo **changeInfo, uint32_t count)
- {
- // Do something.
- }
- Rdb_DetailsObserver callback = LocalDataChangeObserverCallback1;
- Rdb_DataObserver observer = { nullptr, { callback } };
- // Unsubscribe from the local database data changes.
- OH_Rdb_Unsubscribe(store_, Rdb_SubscribeType::RDB_SUBSCRIBE_TYPE_LOCAL_DETAILS, &observer);
- ```
-
-
-12. Register an observer for auto sync progress of an RDB store. When auto sync is performed on the RDB store, the registered callback will be invoked to process the observation. Call **OH_Rdb_SubscribeAutoSyncProgress** to subscribe to the auto sync progress. Before using this API, ensure that the cloud service is available.
Example:
+ ```c
+ // Define a callback.
+ void LocalDataChangeObserverCallback1(void *context, const Rdb_ChangeInfo **changeInfo, uint32_t count)
+ {
+ // Do something.
+ }
+ Rdb_DetailsObserver callback = LocalDataChangeObserverCallback1;
+ Rdb_DataObserver observer = { nullptr, { callback } };
+ // Unsubscribe from the local database data changes.
+ OH_Rdb_Unsubscribe(store_, Rdb_SubscribeType::RDB_SUBSCRIBE_TYPE_LOCAL_DETAILS, &observer);
+ ```
+
+
+12. Register an observer for auto sync progress of an RDB store. When auto sync is performed on the RDB store, the registered callback will be invoked to process the observation.
+
+ Call **OH_Rdb_SubscribeAutoSyncProgress** to subscribe to the auto sync progress. Before using this API, ensure that the cloud service is available.
Example:
```c
// Define a callback.
@@ -424,11 +418,13 @@ libnative_rdb_ndk.z.so
// Do something.
}
const Rdb_ProgressObserver observer = { .context = nullptr, .callback = RdbProgressObserverCallback };
- OH_Rdb_SubscribeAutoSyncProgress(store_, &observer);
+OH_Rdb_SubscribeAutoSyncProgress(store_, &observer);
```
-
-13. Unsubscribe from the auto sync progress from an RDB store. After that, the callback will not be invoked to process the observation. Call **OH_Rdb_UnsubscribeAutoSyncProgress** to unsubscribe from the auto sync progress. Before using this API, ensure that the cloud service is available.
Example:
+13. Unsubscribe from the auto sync progress from an RDB store. After that, the callback will not be invoked to process the observation.
+
+ Call **OH_Rdb_UnsubscribeAutoSyncProgress** to unsubscribe from the auto sync progress. Before using this API, ensure that the cloud service is available.
Example:
+
```c
// Define a callback.
void RdbProgressObserverCallback(void *context, Rdb_ProgressDetails *progressDetails)
@@ -439,17 +435,15 @@ libnative_rdb_ndk.z.so
OH_Rdb_UnsubscribeAutoSyncProgress(store_, &observer);
```
-14. Delete an RDB store.
-
- Call **OH_Rdb_DeleteStore** to delete the RDB store and related database file.
Example:
-
+14. Delete the database.
Call **OH_Rdb_DeleteStore** to delete the RDB store and related database file.
Example:
+
```c
// Close the database instance.
OH_Rdb_CloseStore(store_);
// Delete the database file.
-OH_Rdb_DeleteStore(&config);
+ OH_Rdb_DeleteStore(&config);
```
-
+
diff --git a/en/application-dev/database/native-vector-store-guidelines.md b/en/application-dev/database/native-vector-store-guidelines.md
new file mode 100644
index 0000000000000000000000000000000000000000..f2e38f7b7638cea23b94a87f3890ba87f5cb93dd
--- /dev/null
+++ b/en/application-dev/database/native-vector-store-guidelines.md
@@ -0,0 +1,298 @@
+# Persisting Vector Store Data (C/C++)
+
+
+## When to Use
+
+Vector stores are designed to store, manage, and retrieve vector data while also supporting relational data processing for scalar values. The data type **floatvector** is used to store data vectorization results, enabling rapid retrieval and similarity searches for such data.
+
+## Basic Concepts
+
+- **ResultSet**: a set of query results, which allows access to the required data in flexible modes.
+- **floatvector**: vector data, for example, **[1.0, 3.0, 2.4, 5.1, 6.2, 11.7]**.
+
+## Constraints
+
+- By default, the Write Ahead Log (WAL) and the **FULL** flushing mode are used.
+
+- A vector store supports a maximum of four read connections and one write connection at a time by default. A thread can perform the read operation when acquiring an idle read connection. If there is no idle read connection, a new read connection will be created.
+
+- To ensure data accuracy, the database supports only one write operation at a time. Concurrent write operations are performed in serial mode.
+
+- Once an application is uninstalled, related database files and temporary files are automatically deleted from the device.
+
+- To ensure successful data access, limit the size of a data record to 2 MB. Data records larger than this may be inserted correctly but fail to read.
+
+## Available APIs
+
+For details about the APIs, see [RDB](../reference/apis-arkdata/_r_d_b.md).
+
+| API| Description|
+| -------- | -------- |
+| int OH_Rdb_SetDbType(OH_Rdb_ConfigV2 *config, int dbType) | Sets the database type.|
+| OH_Rdb_Store *OH_Rdb_CreateOrOpen(const OH_Rdb_ConfigV2 *config, int *errCode) | Obtains an **OH_Rdb_Store** instance (**dbType** is set to **RDB_CAYLEY** by using **OH_Rdb_SetDbType**) for vector operations.|
+| int OH_Rdb_ExecuteV2(OH_Rdb_Store *store, const char *sql, const OH_Data_Values *args, OH_Data_Value **result) | Executes SQL statements with a return value to perform write operations. Parameter binding is supported. The number of operators (such as =, >, and <) in the SQL statements cannot exceed 1000.|
+| int OH_Rdb_ExecuteByTrxId(OH_Rdb_Store *store, int64_t trxId, const char *sql) | Executes the SQL statement that does not return a value with the specified transaction ID. If the transaction ID is **0**, no transaction is used.|
+| OH_Cursor *OH_Rdb_ExecuteQuery(OH_Rdb_Store *store, const char *sql) | Queries data in a store using the specified SQL statements.|
+| OH_Cursor *OH_Rdb_ExecuteQueryV2(OH_Rdb_Store *store, const char *sql, const OH_Data_Values *args) | Queries data in a store using the specified SQL statements. Parameter binding is supported. The number of operators (such as =, >, and <) in the SQL statements cannot exceed 1000.|
+| int OH_Rdb_DeleteStoreV2(const OH_Rdb_ConfigV2 *config) | Deletes a vector store.|
+| int OH_Cursor_GetFloatVectorCount(OH_Cursor *cursor, int32_t columnIndex, size_t *length) | Obtains the length of the floating-point array in the specified column of the current row.|
+| int OH_Cursor_GetFloatVector(OH_Cursor *cursor, int32_t columnIndex, float *val, size_t inLen, size_t *outLen) | Obtains the value in the specified column of the current row as a floating-point array. The value of **inLen** cannot be less than the actual array size.|
+
+## How to Develop
+
+**Adding Dynamic Link Libraries**
+
+Add the following libraries to **CMakeLists.txt**.
+
+```txt
+libnative_rdb_ndk.z.so
+```
+
+**Including Header Files**
+
+```c++
+#include
+#include
+#include
+```
+
+1. Check whether the system supports vector stores. The sample code is as follows:
+
+ ```c
+ int numType = 0;
+ // If numType is 2, the system supports vector stores. If numType 1, the system does not support vector stores.
+ OH_Rdb_GetSupportedDbType(&numType);
+ ```
+
+2. If the system supports vector stores, obtain an **OH_Rdb_Store** instance. The sample code is as follows:
+
+ ```c
+ // Create an OH_Rdb_Config instance.
+ OH_Rdb_ConfigV2 *config = OH_Rdb_CreateConfig();
+ // The path must be an application sandbox path.
+ OH_Rdb_SetDatabaseDir(config, "xxx");
+ // Set the store name, which is the database file name.
+ OH_Rdb_SetStoreName(config, "rdb_vector_test.db");
+ // Set the application bundle name.
+ OH_Rdb_SetBundleName(config, "xxx");
+ // Specify whether the database is encrypted.
+ OH_Rdb_SetEncrypted(config, false);
+ // Set the security level of the database files.
+ OH_Rdb_SetSecurityLevel(config, OH_Rdb_SecurityLevel::S1);
+ // Set the encryption level for the directory holding the database files.
+ OH_Rdb_SetArea(config, RDB_SECURITY_AREA_EL1);
+ // Set the storage type.
+ OH_Rdb_SetDbType(config, RDB_CAYLEY);
+
+ // Create an OH_Rdb_Store instance.
+ int errCode = 0;
+ OH_Rdb_Store *store_ = OH_Rdb_CreateOrOpen(config, &errCode);
+ ```
+
+3. Create a table and insert data into the table.
+
+ > **NOTE**
+ >
+ > **VectorStore** does not provide explicit flush operations for data persistence. The data inserted is persisted.
+
+ The sample code is as follows:
+
+ ```c
+ char createTableSql[] = "CREATE TABLE test (id INTEGER PRIMARY KEY AUTOINCREMENT, data1 floatvector(2));";
+ // Create a table.
+ OH_Rdb_ExecuteByTrxId(store_, 0, createTableSql);
+
+ // Insert data without parameter binding.
+ OH_Rdb_ExecuteV2(store_, "INSERT INTO test (id, data1) VALUES (0, '[3.4, 4.5]');", nullptr, nullptr);
+ // Insert data with parameter binding.
+ OH_Data_Values *values = OH_Values_Create();
+ OH_Values_PutInt(values, 1);
+ float test[] = { 1.2, 2.3 };
+ size_t len = sizeof(test) / sizeof(test[0]);
+ OH_Values_PutFloatVector(values, test, len);
+ char insertSql[] = "INSERT INTO test (id, data1) VALUES (?, ?);";
+ OH_Rdb_ExecuteV2(store_, insertSql, values, nullptr);
+ OH_Values_Destroy(values);
+ ```
+
+4. Modify or delete data. The sample code is as follows:
+
+ ```c
+ // Modify data without parameter binding.
+ OH_Rdb_ExecuteV2(store_, "update test set data1 = '[5.1, 6.1] where id = 0;", nullptr, nullptr);
+
+ // Modify data with parameter binding.
+ float test1[2] = { 5.5, 6.6 };
+ OH_Data_Values *values1 = OH_Values_Create();
+ OH_Values_PutFloatVector(values1, test1, 2);
+ OH_Values_PutInt(values1, 1);
+ OH_Rdb_ExecuteV2(store_, "update test set data1 = ? where id = ?", values1, nullptr);
+ OH_Values_Destroy(values1);
+
+ // Delete data without parameter binding.
+ OH_Rdb_ExecuteV2(store_, "delete from test where id = 0", nullptr, nullptr);
+
+ // Delete data with parameter binding.
+ OH_Data_Values *values2 = OH_Values_Create();
+ OH_Values_PutInt(values2, 01);
+ OH_Rdb_ExecuteV2(store_, "delete from test where id = ?", values2, nullptr);
+ OH_Values_Destroy(values2);
+ ```
+
+5. Query data.
+
+ > **NOTE**
+ >
+ > Use **destroy()** to destroy the **ResultSet** that is no longer used in a timely manner so that the memory allocated can be released.
+
+ The sample code is as follows:
+
+ ```c
+ // Query data without parameter binding.
+ OH_Cursor *cursor = OH_Rdb_ExecuteQueryV2(store_, "select * from test where id = 1;", nullptr);
+ int rowCount = 0;
+ cursor->getRowCount(cursor, &rowCount);
+ cursor->goToNextRow(cursor);
+ size_t count = 0;
+ // The floatvector array is the second column of data.
+ OH_Cursor_GetFloatVectorCount(cursor, 1, &count);
+ float test2[count];
+ size_t outLen;
+ OH_Cursor_GetFloatVector(cursor, 1, test2, count, &outLen);
+ cursor->destroy(cursor);
+
+ // Query data with parameter binding.
+ char querySql[] = "select * from test where id = ?;";
+ OH_Data_Values *values3 = OH_Values_Create();
+ OH_Values_PutInt(values3, 1);
+ cursor = OH_Rdb_ExecuteQueryV2(store_, querySql, values3);
+ OH_Values_Destroy(values3);
+ cursor->destroy(cursor);
+
+ // Query data in another table, and create the table if it does not exist.
+ OH_Rdb_ExecuteV2(store_, "CREATE TABLE IF NOT EXISTS test1(id text PRIMARY KEY);", nullptr, nullptr);
+ cursor = OH_Rdb_ExecuteQueryV2(store_, "select * from test where id in (select id from test1);", nullptr);
+ cursor->destroy(cursor);
+
+ // Perform aggregate query.
+ cursor = OH_Rdb_ExecuteQueryV2(store_, "select * from test where data1 <-> '[1.0, 1.0]' > 0 group by id having max(data1 <=> '[1.0, 1.0]');", nullptr);
+ cursor->destroy(cursor);
+
+ // Perform multi-table query.
+ cursor = OH_Rdb_ExecuteQueryV2(store_, "select id, data1 <-> '[1.5, 5.6]' as distance from test union select id, data1 <-> '[1.5, 5.6]' as distance from test order by distance limit 5;", nullptr);
+ cursor->destroy(cursor);
+ ```
+
+6. Create a view and query data. The sample code is as follows:
+
+ ```c
+ OH_Rdb_ExecuteV2(store_, "CREATE VIEW v1 as select * from test where id > 0;", nullptr, nullptr);
+ OH_Cursor *cursor = OH_Rdb_ExecuteQueryV2(store_, "select * from v1;", nullptr);
+ cursor->destroy(cursor);
+ ```
+
+7. Query data using vector indexes.
+
+ The vector store uses vectors as keys to provide efficient and fast search capabilities.
+
+ It supports the basic syntax and extended syntax as follows:
+
+ - Basic syntax:
+
+ ```sql
+ // index_name indicates the index name, index_type indicates the index type, and dist_function indicates the type of distance function for similarity measurement.
+ CREATE INDEX [IF NOT EXISTS] index_name ON table_name USING index_type (column_name dist_function);
+
+ DROP INDEX table_name.index_name;
+ ```
+ - Extended syntax:
+
+ ```sql
+ CREATE INDEX [Basic syntax] [WITH(parameter = value [, ...])];
+ ```
+
+ **Table 1** index_type
+
+ | Type | Description |
+ | --------- | ------------------------------------------------------------ |
+ | gsdiskann | Index for processing high-dimensional dense vector data, such as text embedding and image features. |
+
+ **Table 2** dist_function
+
+ | Type | Operator| Description |
+ | ------ | -------- | ---------- |
+ | L2 | <-> | Euclidean distance.|
+ | COSINE | <=> | Cosine distance.|
+
+ **Table 3** parameter (extended syntax parameters)
+
+ | Name | Value Range| Description |
+ | ------ | -------- | ---------- |
+ | QUEUE_SIZE | Value range: [10, 1000]
Default value: **20** | Size of the candidate queue when an index is created for nearest neighbor search. A larger value indicates a lower construction speed and a slightly higher recall rate.|
+ | OUT_DEGREE | Value range: [1, 1200]
Default value: **60** | Number of outgoing edges of a node in the graph. The value of **OUT_DEGREE** cannot exceed **pageSize**. Otherwise, the error GRD_INVALID_ARGS will be thrown.|
+
+ > **NOTE**
+ >
+ > - When deleting an index, you need to specify the table name, that is, **Drop Index table.index_name**.
+ >
+ > - The index created with a table cannot be deleted, for example, the primary key cannot be deleted.
+ >
+ > - When querying data based on vector indexes, you must use **ORDER BY** and **LIMIT**. **ORDER BY** has only one sorting condition, that is, the vector distance condition. If **ORDER BY** is used with **DESC**, vector indexes will not be used. The distance metric used for querying must match the metric used when the index is created. For example, if the vector index is created using **L2**, <-> must be used for the query. Otherwise, the index cannot be hit.
+
+ The sample code is as follows:
+
+ ```c
+ // Create an index using the basic syntax. The index name is diskann_l2_idx, index column is repr, type is gsdiskann, and the distance metric is L2.
+ OH_Rdb_ExecuteV2(store_, "CREATE INDEX diskann_l2_idx ON test USING GSDISKANN(data1 L2);", nullptr, nullptr);
+
+ // Delete the diskann_l2_idx index from the test table.
+ OH_Rdb_ExecuteV2(store_, "DROP INDEX test.diskann_l2_idx;", nullptr, nullptr);
+
+ // Set QUEUE_SIZE to 20 and OUT_DEGREE to 50 using the extended syntax.
+ OH_Rdb_ExecuteV2(store_, "CREATE INDEX diskann_l2_idx ON test USING GSDISKANN(repr L2) WITH (queue_size=20, out_degree=50);", nullptr, nullptr);
+ ```
+
+8. Configure the data aging policy, which allows the application data to be automatically deleted by time or space.
+
+ The syntax is as follows:
+
+ ```sql
+ CREATE TABLE table_name(column_name type [, ...]) [WITH(parameter = value [, ...])];
+ ```
+
+ **parameter** specifies the parameter to set, and **value** specifies the value of the parameter. The following table describes the fields contained in **parameter**.
+
+ **Table 4** parameter (data aging policy parameters)
+
+ | Name| Mandatory| Description|
+ | ------ | -------- | ---------- |
+ | time_col | Yes| Column name The value must be an integer and cannot be empty.|
+ | interval | No| Interval for executing the aging task thread. If a write operation is performed after the interval, an aging task will be triggered to delete the data that meets the aging conditions. If the write operation is performed within the interval, no aging task will be triggered.
Value range: [5 second, 1 year]
Default value: **1 day**
Time units supported include **second**, **minute**, **hour**, **day**, **month** and **year**. The value is case-insensitive and supports both singular and plural forms (for example, **2 hour** and **2 hours** are acceptable).|
+ | ttl | No| Data retention period.
Value range: [1 hour, 1 year]
Default value: **3 month**
Time units supported include **second**, **minute**, **hour**, **day**, **month** and **year**. The value is case-insensitive and supports both singular and plural forms (for example, **2 hour** and **2 hours** are acceptable).|
+ | max_num | No| Maximum data volume allowed.
Value range: [100, 1024]
Default value: **1024**
After the aging task deletes expired data, if the remaining data in the table exceeds the value of **max_num**, data tied to the nearest expiration-adjacent time point will be deleted until the total row count falls below **max_num**.|
+
+ Time-related parameters are converted into seconds as follows.
+
+ | Unit| Value in Seconds|
+ | ------ | -------- |
+ | year | 365 * 24 * 60 * 60 |
+ | month | 30 * 24 * 60 * 60 |
+ | day | 24 * 60 * 60 |
+ | hour | 60 * 60 |
+ | minute | 60 |
+
+ For example, if **ttl** is set to **3 months**, the value will be converted into 7,776,000 seconds (3 x (30 x 24 x 60 x 60)).
+
+ The sample code is as follows:
+
+ ```c
+ // The write operation performed every 5 minutes will trigger a data aging task.
+ OH_Rdb_ExecuteV2(store_, "CREATE TABLE test2(rec_time integer not null) WITH (time_col = 'rec_time', interval = '5 minute');", nullptr, nullptr);
+ ```
+
+9. Delete the database. The sample code is as follows:
+
+ ```c
+ OH_Rdb_CloseStore(store_);
+ OH_Rdb_DeleteStoreV2(config);
+ ```
diff --git a/en/application-dev/database/preferences-guidelines.md b/en/application-dev/database/preferences-guidelines.md
index 124854c6c82cad52a94cd125b26ab8db3e7785c9..d09c884021078b30991ebc4aeb9377dba3804b45 100644
--- a/en/application-dev/database/preferences-guidelines.md
+++ b/en/application-dev/database/preferences-guidelines.md
@@ -5,7 +5,8 @@ The **Preferences** module allows quick access to data in KV pairs and storage o
## Constraints
-The C APIs and ArkTS APIs of the **Preferences** module cannot be used together.
+- The C APIs and ArkTS APIs of the **Preferences** module cannot be used together.
+- The maximum key length is 1024 bytes, and the maximum value length is 16 MB.
## Available APIs
@@ -28,7 +29,7 @@ For details about the APIs, see [Preferences](../reference/apis-arkdata/_prefere
| int OH_Preferences_UnregisterDataObserver (OH_Preferences \*preference, void \*context, OH_PreferencesDataObserver observer, const char \*keys[], uint32_t keyCount) | Unsubscribes from data changes of the specified keys.|
| int OH_Preferences_IsStorageTypeSupported (Preferences_StorageType type, bool \*isSupported) | Checks whether the specified storage type is supported.|
| OH_PreferencesOption \* OH_PreferencesOption_Create (void) | Creates an **OH_PreferencesOption** instance and a pointer to it. If this pointer is no longer required, use **OH_PreferencesOption_Destroy** to destroy it. Otherwise, memory leaks may occur.|
-| int OH_PreferencesOption_SetFileName (OH_PreferencesOption \*option, const char \*fileName) | Sets the file name for an **OH_PreferencesOption** instance.|
+| int OH_PreferencesOption_SetFileName (OH_PreferencesOption \*option, const char \*fileName) | Sets the file name for an **OH_PreferencesOption** instance. The name must be longer than 0 bytes and less than or equal to 255 bytes, and cannot contain or end with slashes (/).|
| int OH_PreferencesOption_SetBundleName (OH_PreferencesOption \*option, const char \*bundleName) | Sets the bundle name for an OH_PreferencesOption instance.|
| int OH_PreferencesOption_SetDataGroupId (OH_PreferencesOption \*option, const char \*dataGroupId) | Sets the application group ID for an **OH_PreferencesOption** instance.|
| int OH_PreferencesOption_SetStorageType (OH_PreferencesOption \*option, Preferences_StorageType type) | Sets the storage type for an **OH_PreferencesOption** instance.|
@@ -128,14 +129,14 @@ if (ret != PREFERENCES_OK) {
}
// Set the storage type for the PreferencesOption instance. Before the setting, call OH_Preferences_IsStorageTypeSupported to check whether the storage type is supported.
-bool isClkvSupported = false;
-ret = OH_Preferences_IsStorageTypeSupported(Preferences_StorageType::PREFERENCES_STORAGE_CLKV, &isClkvSupported);
+bool isGskvSupported = false;
+ret = OH_Preferences_IsStorageTypeSupported(Preferences_StorageType::PREFERENCES_STORAGE_GSKV, &isGskvSupported);
if (ret != PREFERENCES_OK) {
(void)OH_PreferencesOption_Destroy(option);
// Error handling.
}
-if (isClkvSupported) {
- ret = OH_PreferencesOption_SetStorageType(option, Preferences_StorageType::PREFERENCES_STORAGE_CLKV);
+if (isGskvSupported) {
+ ret = OH_PreferencesOption_SetStorageType(option, Preferences_StorageType::PREFERENCES_STORAGE_GSKV);
if (ret != PREFERENCES_OK) {
(void)OH_PreferencesOption_Destroy(option);
// Error handling.
diff --git a/en/application-dev/database/share-data-by-datashareextensionability.md b/en/application-dev/database/share-data-by-datashareextensionability.md
index b3de68a61fd9c54cc0d6f5013b95e18df6e20c72..56555ab4f1eb86fef8fc2964d9dfb44d32fb4656 100644
--- a/en/application-dev/database/share-data-by-datashareextensionability.md
+++ b/en/application-dev/database/share-data-by-datashareextensionability.md
@@ -5,7 +5,7 @@
If complex services are involved in cross-application data access, you can use **DataShareExtensionAbility** to start the application of the data provider to implement data access.
-You need to implement flexible service logics via callbacks of the service provider.
+You need to implement flexible service logics via callbacks of the service provider.
## Working Principles
@@ -27,7 +27,6 @@ There are two roles in **DataShare**:
- The **ResultSet** module is implemented through shared memory. Shared memory stores the result sets, and interfaces are provided to traverse result sets.
-
## How to Develop
@@ -144,24 +143,28 @@ Before implementing a **DataShare** service, you need to create a **DataShareExt
| -------- | -------- | -------- |
| name | Ability name, corresponding to the **ExtensionAbility** class name derived from **Ability**.| Yes|
| type | Ability type. The value **dataShare** indicates that the development is based on the **datashare** template.| Yes|
- | uri | Unique identifier for the data consumer to access the data provider.| Yes|
+ | uri | Unique identifier for the data consumer to access the data provider.
You can add suffix parameters to set the target access object. The suffix parameters must be added to the end of the URI and start with a question mark (?).
- Currently, only the **user** parameter is supported.
- The value of **user** must be an integer. It indicates the user ID of the data provider. If It is not specified, the user ID of the data consumer is used. For details about the definition of **user** and how to obtain it, see [user](../reference/apis-basic-services-kit/js-apis-osAccount.md#getactivatedosaccountlocalids9).
- Currently, the data consumer in cross-user access must have the ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission.| Yes|
| exported | Whether it is visible to other applications. Data sharing is allowed only when the value is **true**.| Yes|
- | readPermission | Permission required for accessing data. If this parameter is not set, read permission verification is not performed by default.| No|
- | writePermission | Permission required for modifying data. If this parameter is not set, write permission verification is not performed by default.| No|
+ | readPermission | Permission required for accessing data. If this parameter is not set, read permission verification is not performed by default.
**NOTE**: The permission constraints for **DataShareExtensionAbility** are different from that for silent access. It is important to understand the difference and prevent confusion. For details, see [Silent Access via DatamgrService](share-data-by-silent-access.md).| No|
+ | writePermission | Permission required for modifying data. If this parameter is not set, write permission verification is not performed by default.
**NOTE**: The permission constraints for **DataShareExtensionAbility** are different from that for silent access. It is important to understand the difference and prevent confusion. For details, see [Silent Access via DatamgrService](share-data-by-silent-access.md).| No|
| metadata | Silent access configuration, which includes the following:
- **name**: identifies the configuration, which has a fixed value of **ohos.extension.dataShare**.
- **resource**: has a fixed value of **$profile:data_share_config**, which indicates that the profile name is **data_share_config.json**.| **metadata** is mandatory when the ability launch type is **singleton**. For details about the ability launch type, see **launchType** in the [Internal Structure of the abilities Attribute](../quick-start/module-structure.md#internal-structure-of-the-abilities-attribute).|
**module.json5 example**
```json
+ // The following uses settingsdata as an example.
"extensionAbilities": [
{
- "srcEntry": "./ets/DataShareExtAbility/DataShareExtAbility.ets",
- "name": "DataShareExtAbility",
+ "srcEntry": "./ets/DataAbility/DataExtAbility.ets",
+ "name": "DataExtAbility",
"icon": "$media:icon",
"description": "$string:description_datashareextability",
"type": "dataShare",
- "uri": "datashare://com.samples.datasharetest.DataShare",
+ "uri": "datashare://com.ohos.settingsdata.DataAbility",
"exported": true,
+ // Configure permissions based on actual situation. The permissions configured here are examples only.
+ "readPermission": "ohos.permission.MANAGE_SECURE_SETTINGS",
+ "writePermission": "ohos.permission.MANAGE_SECURE_SETTINGS",
"metadata": [{"name": "ohos.extension.dataShare", "resource": "$profile:data_share_config"}]
}
]
@@ -172,8 +175,8 @@ Before implementing a **DataShare** service, you need to create a **DataShareExt
| Field | Description | Mandatory|
| ------------------- | ------------------------------------------------------------ | ---- |
| tableConfig | Configuration label, which includes **uri** and **crossUserMode**.
- **uri**: specifies the range for which the configuration takes effect. The URI supports the following formats in descending order by priority:
1. *****: indicates all databases and tables.
2. **datashare:///{*bundleName*}/{*moduleName*}/{*storeName*}**: specifies a database.
3. **datashare:///{*bundleName*}/{*moduleName*}/{*storeName*}/{*tableName*}**: specifies a table.
If URIs of different formats are configured, only the URI with the higher priority takes effect.
- **crossUserMode**: Whether to share data between multiple users.
The value **1** means to share data between multiple users, and the value **2** means the opposite.| Yes |
- | isSilentProxyEnable | Whether to enable silent access for this ExtensionAbility.
The value **true** means to enable silent access, and the value **false** means the opposite.
The default value is **true**.
If an application has multiple ExtensionAbilities and this field is set to **false** for one of them, silent access is disabled for the application.
If the data provider has called **enableSilentProxy** or **disableSilentProxy**, silent access is enabled or disabled based on the API settings. Otherwise, the setting here takes effect.| No |
- | launchInfos | Launch information, which includes **storeId** and **tableNames**.
If the data in a table involved in the configuration changes, an extensionAbility will be started based on the URI in **extensionAbilities**. You need to set this parameter only when the service needs to start an extensionAbility to process data that is not actively changed by the service.
- **storeId**: database name, excluding the file name extension. For example, if the database name is **test.db**, set this parameter to **test**.
- **tableNames**: names of the database tables. Any change in a table will start an an extensionAbility. | No |
+ | isSilentProxyEnable | Whether to enable silent access for this ExtensionAbility.
The value **true** means to enable silent access, and the value **false** means the opposite.
The default value is **true**.
If an application has multiple ExtensionAbilities and this field is set to **false** for one of them, silent access is disabled for the application.
If the data provider has called **enableSilentProxy** or **disableSilentProxy**, silent access is enabled or disabled based on the API settings. Otherwise, the setting here takes effect.| No |
+ | launchInfos | Launch information, which includes **storeId** and **tableNames**.
If the data in a table involved in the configuration changes, an extensionAbility will be started based on the URI in **extensionAbilities**. You need to set this parameter only when the service needs to start an extensionAbility to process data that is not actively changed by the service.
- **storeId**: database name, excluding the file name extension. For example, if the database name is **test.db**, set this parameter to **test**.
- **tableNames**: names of the database tables. Any change in a table will start an extensionAbility.| No |
**data_share_config.json Example**
@@ -185,7 +188,7 @@ Before implementing a **DataShare** service, you need to create a **DataShareExt
"crossUserMode":1
},
{
- "uri":"datashare:///com.acts.datasharetest/entry/DB00",
+ "uri":"datashare:///com.ohos.settingsdata/entry/DB00",
"crossUserMode":1
},
{
@@ -219,7 +222,7 @@ Before implementing a **DataShare** service, you need to create a **DataShareExt
```ts
// Different from the URI defined in the module.json5 file, the URI passed in the parameter has an extra slash (/), because there is a DeviceID parameter between the second and the third slash (/).
- let dseUri = ('datashare:///com.samples.datasharetest.DataShare');
+ let dseUri = ('datashare:///com.ohos.settingsdata.DataAbility');
```
3. Create a **DataShareHelper** instance.
@@ -307,4 +310,4 @@ Before implementing a **DataShare** service, you need to create a **DataShareExt
// Close the DataShareHelper instance.
(dsHelper as dataShare.DataShareHelper).close();
}
- ```
\ No newline at end of file
+ ```
diff --git a/en/application-dev/database/share-data-by-silent-access.md b/en/application-dev/database/share-data-by-silent-access.md
index 6fc7a1679e48f29f07737310ccdcc26f46209048..d7f1e22b3e916acf05a5962dce3ae4626e114219 100644
--- a/en/application-dev/database/share-data-by-silent-access.md
+++ b/en/application-dev/database/share-data-by-silent-access.md
@@ -24,7 +24,7 @@ If the service processing is too complex to be encapsulated, use [DataShareExten
- Process data: process data, in the JSON or byte format, managed by **DatamgrService**. It is stored in the **DatamgrService** sandbox directory, and is automatically deleted 10 days after no subscription.
-- Dynamic data: data stored in the memory of a device. It is automatically deleted after the device is restarted. Currently, the dynamic data refers to only the data set by **enableSilentProxy** and **disableSilentProxy**.
+- Dynamic data: data stored in the memory of a device. It is automatically deleted after the device is restarted. The dynamic data refers to only the data set by **enableSilentProxy** and **disableSilentProxy**.
| Data Type | Location | Data Format | Validity Period | Usage |
@@ -49,13 +49,17 @@ If the service processing is too complex to be encapsulated, use [DataShareExten
- You can add parameters to the URI to specify the access mode and target object. When adding parameters to a URI, note that the URI must be in the **datashareproxy://{*bundleName*}/{*dataPath*}?{*arg1*}&{*arg2*}** format. Otherwise, the parameters do not take effect.
- The parameters to add start with a question mark (?) and separated by an ampersand (&). Consecutive symbols (for example, ???? or &&&) are considered as one. Currently, only **Proxy** and **appIndex** can be added. If the URI contains multiple question marks (?), the parameter following the question mark (?) must be **Proxy**. Otherwise, this parameter does not take effect.
+ The parameters to add start with a question mark (?) and separated by an ampersand (&). Consecutive symbols (for example, ???? or &&&) are considered as one. Currently, only the **Proxy**, **appIndex**, and **user** parameters are supported. If the URI contains multiple question marks (?), the parameter following the question mark (?) must be **Proxy**. Otherwise, this parameter does not take effect.
- **Proxy** specifies the data access mode used by the data consumer. The value can be **true** or **false**. The value **true** indicates the silent access mode, and **false** indicates the non-silent access mode.
- - **appIndex** specifies the index of an application clone. The value must be an integer starting from 1. This parameter takes effect only for cloned applications. For details about **appIndex**, see [BundleInfo](../reference/apis-ability-kit/js-apis-bundleManager-bundleInfo.md). If **appIndex** is **0** or left empty, the data consumer accesses the data provider application.
+ - **appIndex** specifies the index of an application clone. The value must be an integer starting from 1. This parameter takes effect only for cloned applications. For details about **appIndex**, see [BundleInfo](../reference/apis-ability-kit/js-apis-bundleManager-bundleInfo.md). If **appIndex** is **0** or left empty, the data consumer accesses the application of the data provider.
- Currently, cloned applications can be accessed only in silent mode. When setting the URI and parameters for accessing an application clone, both **Proxy** and **appIndex** are mandatory. For example, **datashareproxy://{bundleName}/{dataPath}?Proxy=true&appIndex=1** indicates that the data consumer accesses the first clone of the application in silent access mode.
+ Currently, cloned applications are supported only in silent access mode. When setting the URI and parameters for accessing an application clone, both **Proxy** and **appIndex** must be set. For example, **datashareproxy://{bundleName}/{dataPath}?Proxy=true&appIndex=1** indicates that the data consumer will access the first clone of the application in silent access mode.
+
+ - The value of **user** must be an integer. It is the user ID of the data provider. For details about the definition of **user** and how to obtain it, see [user](../reference/apis-basic-services-kit/js-apis-osAccount.md#getactivatedosaccountlocalids9). If **user** is not set, the user ID of the data consumer is used.
+
+ Currently, only the main space and privacy space support cross-user access, and the data consumer must have the ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission.
## Constraints
@@ -84,7 +88,7 @@ Most of the APIs for silent access are executed asynchronously in callback or pr
| query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void | Queries data in the database. |
| update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void | Updates data in the database. |
| addTemplate(uri: string, subscriberId: string, template: Template): void | Adds a data template with the specified subscriber. |
-| on(type: 'rdbDataChange', uris: Array<string>, templateId: TemplateId, callback: AsyncCallback<RdbDataChangeNode>): Array<OperationResult | Subscribes to the changes of the data corresponding to the specified URI and template.|
+| on(type: 'rdbDataChange', uris: Array<string>, templateId: TemplateId, callback: AsyncCallback<RdbDataChangeNode>): Array<OperationResult> | Subscribes to the changes of the data corresponding to the specified URI and template.|
### APIs for Accessing Process Data
@@ -106,7 +110,7 @@ Most of the APIs for silent access are executed asynchronously in callback or pr
The following walks you through on how to share an RDB store.
-### Data Provider Application
+### Data Provider Application Development
1. In the **module.json5** file, set the data to be shared in **proxyData**. For details about the configuration, see [module.json5 Configuration File](../quick-start/module-configuration-file.md).
@@ -115,18 +119,22 @@ The following walks you through on how to share an RDB store.
| Name | Description | Mandatory |
| ----------------------- | ---------------------------------------- | ---- |
| uri | URI of the data proxy, which is the unique identifier for cross-application data access. | Yes |
- | requiredReadPermission | Permission required for reading data from the data proxy. If this parameter is not set, other applications are not allowed to access data. For details about the permissions, see [Application Permissions](../security/AccessToken/app-permissions.md). | No |
- | requiredWritePermission | Permission required for writing data to the data proxy. If this parameter is not set, other applications are not allowed to write data to the data proxy. For details about the permissions, see [Application Permissions](../security/AccessToken/app-permissions.md). | No |
+ | requiredReadPermission | Permission required for reading data from the data proxy. If this parameter is not set, other applications are not allowed to access data. For details about the permissions, see [Application Permissions](../security/AccessToken/app-permissions.md).
**NOTE**: The permission constraints for silent access are different from that for **DataShareExtensionAbility**. It is important to understand the difference and prevent confusion. For details, see [DataShareExtensionAbility](share-data-by-datashareextensionability.md). | No |
+ | requiredWritePermission | Permission required for writing data to the data proxy. If this parameter is not set, other applications are not allowed to write data to the data proxy. For details about the permissions, see [Application Permissions](../security/AccessToken/app-permissions.md).
**NOTE**: The permission constraints for silent access are different from that for **DataShareExtensionAbility**. It is important to understand the difference and prevent confusion. For details, see [DataShareExtensionAbility](share-data-by-datashareextensionability.md). | No |
| metadata | Metadata of the data source, including the **name** and **resource** fields.
The **name** field identifies the configuration, which has a fixed value of **dataProperties**.
The value of **resource** is **$profile:{fileName}**, indicating that the name of the configuration file is **{fileName}.json**.| Yes |
+ A data table contains all the data accessible through a URI. Ensure that all data in a table falls under the same permission scope. To effectively implement data isolation at the table level, you are advised to store data with different scopes in separate tables and configure appropriate permission constraints for each table. For security-critical data, you are advised to configure an allowlist of data consumers to prevent unauthorized access. For details, see the **allowLists** field in the **my_config.json** example.
+
**module.json5 example**
```json
- "proxyData":[
+ // The following uses settingsdata as an example.
+ "proxyData": [
{
- "uri": "datashareproxy://com.acts.ohos.data.datasharetest/test",
- "requiredReadPermission": "ohos.permission.GET_BUNDLE_INFO",
- "requiredWritePermission": "ohos.permission.KEEP_BACKGROUND_RUNNING",
+ "uri": "datashareproxy://com.ohos.settingsdata/entry/settingsdata/USER_SETTINGSDATA_SECURE",
+ // Configure permissions based on actual situation. The permissions configured here are examples only.
+ "requiredReadPermission": "ohos.permission.MANAGE_SECURE_SETTINGS",
+ "requiredWritePermission": "ohos.permission.MANAGE_SECURE_SETTINGS",
"metadata": {
"name": "dataProperties",
"resource": "$profile:my_config"
@@ -138,9 +146,10 @@ The following walks you through on how to share an RDB store.
| Name | Description | Mandatory |
| ----- | ---------------------------------------- | ---- |
- | path | Data source path, in the **Database_name/Table_name** format. Currently, only RDB stores are supported. | Yes |
+ | path | Data source path, in the **Database_name/Table_name** format. Currently, only RDB stores are supported. | Yes |
| type | Database type. Currently, only **rdb** is supported. | Yes |
- | scope | Scope of the database.
- **module** indicates that the database is located in this module.
- **application** indicates that the database is located in this application.| No |
+ | scope | Scope of the database.
1. **module** indicates that the database is located in this module.
2. **application** indicates that the database is located in this application.| No |
+ | allowLists | List of applications that can access the data.
It allows a maximum of 256 records. In cross-application data access, the data consumers are checked against the settings here. If the data consumer is not listed in **allowlists**, the data access will be rejected.
If **allowLists** is not configured, allowlist verification is skipped. No matter whether **allowLists** is configured, the read and write permissions in [Table 1](#data-provider-application-development) are always verified.
**allowLists** consists of two fields:
- **appIdentifier**: unique identifier (string) of the application allocated by the cloud. The data provider should obtain it from the data consumer. For details about **appIdentifier**, see [SignatureInfo](../reference/apis-ability-kit/js-apis-bundleManager-bundleInfo.md#signatureinfo).
- **onlyMain**: a Boolean value indicating whether the data is accessible only to the application. The value **true** means only the application can access the data. The value **false** means both the application and its clone can access the data. This feature is available only to silent access. | No |
**my_config.json example**
@@ -148,11 +157,15 @@ The following walks you through on how to share an RDB store.
{
"path": "DB00/TBL00",
"type": "rdb",
- "scope": "application"
+ "scope": "application",
+ "allowLists":[
+ {"appIdentifier": "appIdentifier1", "onlyMain": false},
+ {"appIdentifier": "appIdentifier2", "onlyMain": true}
+ ]
}
```
-### Data Consumer Application
+### Data Consumer Application Development
1. Import dependencies.
@@ -167,7 +180,7 @@ The following walks you through on how to share an RDB store.
2. Define the URI string for communicating with the data provider.
```ts
- let dseUri = ('datashareproxy://com.acts.ohos.data.datasharetest/test');
+ let dseUri = ('datashareproxy://com.ohos.settingsdata/entry/settingsdata/USER_SETTINGSDATA_SECURE');
```
3. Create a **DataShareHelper** instance.
@@ -256,7 +269,7 @@ The following walks you through on how to share an RDB store.
}
let templateId: dataShare.TemplateId = {
subscriberId: "111",
- bundleNameOfOwner: "com.acts.ohos.data.datasharetestclient"
+ bundleNameOfOwner: "com.ohos.settingsdata"
}
if(dsHelper != undefined) {
// When DatamgrService modifies data, onCallback is invoked to return the data queried based on the rules in the template.
@@ -268,7 +281,7 @@ The following walks you through on how to share an RDB store.
The following walks you through on how to host process data.
-### (Optional) Data Provider Application
+### (Optional) Data Provider Application Development
In the **module.json5** file, set the data to be hosted in **proxyData**. For details about the configuration, see [module.json5 Configuration File](../quick-start/module-configuration-file.md).
@@ -283,22 +296,24 @@ In the **module.json5** file, set the data to be hosted in **proxyData**. For de
| Name | Description | Mandatory |
| ----------------------- | ----------------------------- | ---- |
| uri | URI of the data proxy, which is the unique identifier for cross-application data access. | Yes |
-| requiredReadPermission | Permission required for reading data from the data proxy. If this parameter is not set, other applications are not allowed to access data. For details about the permissions, see [Application Permissions](../security/AccessToken/app-permissions.md).| No |
-| requiredWritePermission | Permission required for writing data to the data proxy. If this parameter is not set, other applications are not allowed to write data to the dta proxy. For details about the permissions, see [Application Permissions](../security/AccessToken/app-permissions.md).| No |
+| requiredReadPermission | Permission required for reading data from the data proxy. If this parameter is not set, other applications are not allowed to access data. For details about the permissions, see [Application Permissions](../security/AccessToken/app-permissions.md).
**NOTE**: The permission constraints for silent access are different from that for **DataShareExtensionAbility**. It is important to understand the difference and prevent confusion. For details, see [DataShareExtensionAbility](share-data-by-datashareextensionability.md).| No |
+| requiredWritePermission | Permission required for writing data to the data proxy. If this parameter is not set, other applications are not allowed to write data to the dta proxy. For details about the permissions, see [Application Permissions](../security/AccessToken/app-permissions.md).
**NOTE**: The permission constraints for silent access are different from that for **DataShareExtensionAbility**. It is important to understand the difference and prevent confusion. For details, see [DataShareExtensionAbility](share-data-by-datashareextensionability.md).| No |
**module.json5 example**
```json
+// The following is an example only. Configure it as required.
"proxyData": [
{
"uri": "datashareproxy://com.acts.ohos.data.datasharetest/weather",
- "requiredReadPermission": "ohos.permission.GET_BUNDLE_INFO",
+ // Configure permissions based on actual situation. The permissions configured here are examples only.
+ "requiredReadPermission": "ohos.permission.READ_WEATHER_DATA",
"requiredWritePermission": "ohos.permission.KEEP_BACKGROUND_RUNNING"
}
]
```
-### Data Consumer Application
+### Data Consumer Application Development
1. Import dependencies.
@@ -360,7 +375,7 @@ In the **module.json5** file, set the data to be hosted in **proxyData**. For de
Only the data provider is involved. The following walks you through on how to dynamically enable silent access.
-### Data Provider Application
+### Data Provider Application Development
The data provider calls the **enableSilentProxy** API to dynamically enable silent access. This API must be used with the **isSilentProxyEnable** field in the **data_share_config.json** file. For details, see [**data_share_config.json** configuration](./share-data-by-datashareextensionability.md).
@@ -382,7 +397,7 @@ The data provider calls the **enableSilentProxy** API to dynamically enable sile
2. Define the URI string for communicating with the data provider.
```ts
- let dseUri = ('datashare:///com.acts.datasharetest/entry/DB00/TBL00');
+ let dseUri = ('datashare:///com.ohos.settingsdata/entry/DB00/TBL00');
```
3. Create a **DataShareHelper** instance.
@@ -397,3 +412,5 @@ The data provider calls the **enableSilentProxy** API to dynamically enable sile
}
}
```
+
+
diff --git a/en/application-dev/database/sync-app-data-across-devices-overview.md b/en/application-dev/database/sync-app-data-across-devices-overview.md
index 131d8a3ac85dd78e0cc3331d19eb2aece714094c..0405ce79d275337fbb9a15025004bb8759b0417e 100644
--- a/en/application-dev/database/sync-app-data-across-devices-overview.md
+++ b/en/application-dev/database/sync-app-data-across-devices-overview.md
@@ -1,4 +1,4 @@
-# Distributed Application Data Sync Overview
+# Overview of Distributed Application Data Sync
## When to Use
diff --git a/en/application-dev/database/unified-data-channels.md b/en/application-dev/database/unified-data-channels.md
index 437895deac49ed04ef87531d23b6effa5f5bb609..59d69b606f87fa8f58de61640f967c27fc9b7932 100644
--- a/en/application-dev/database/unified-data-channels.md
+++ b/en/application-dev/database/unified-data-channels.md
@@ -13,6 +13,8 @@ The unified data channel provides cross-application data access for various serv
The unified data channel is implemented by the system ability provided by the UDMF. When an application (data provider) needs to share data, it calls the **insertData()** method provided by the UDMF to write the data to the UDMF data channel, and calls UDMF **updateData()** or **deleteData()** to update or delete the data saved by the application. The target application (data consumer) can access the data by the APIs provided by the UDMF. The UDMF manages the data lifecycle in a unified manner and deletes the data that has been stored for more than one hour every hour.
+Avoid using **unifiedDataChannel** APIs in multi-threaded calls.
+
The unified data object (**UnifiedData**) is uniquely identified by a URI in the UDMF data channel. The URI is in the **udmf://*intention*/*bundleName*/*groupId*** format, where:
+ **udmf**: protocol used to provide the data channel.
diff --git a/en/application-dev/database/uniform-data-structure.md b/en/application-dev/database/uniform-data-structure.md
index 5fb9204e287fbcdd7ede8374c5337e18d49e19e5..3534ea4d32eaa8e98a4a33a0fde32757fb181244 100644
--- a/en/application-dev/database/uniform-data-structure.md
+++ b/en/application-dev/database/uniform-data-structure.md
@@ -13,11 +13,11 @@ The following table lists the uniform data structs provided by the UDMF.
| Data Struct | Data Type | Description |
|-----------------------------------------------------------------------------------------------------| :-------------------: |------|
-| [PlainText](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#plaintext) | 'general.plain-text' | Plain text |
-| [Hyperlink](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#hyperlink) | 'general.hyperlink' | Hyperlink |
-| [HTML](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#html) | 'general.html' | HyperText Markup Language (HTML) |
-| [OpenHarmonyAppItem](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#openharmonyappitem) | 'openharmony.app-item' | Icon |
-| [ContentForm](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#contentform14) | 'general.content-form' | Content widget|
+| [PlainText](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#plaintext) | 'general.plain-text' | Plain text. |
+| [Hyperlink](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#hyperlink) | 'general.hyperlink' | Hyperlink. |
+| [HTML](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#html) | 'general.html' | HyperText Markup Language (HTML). |
+| [OpenHarmonyAppItem](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#openharmonyappitem) | 'openharmony.app-item' | Icon. |
+| [ContentForm](../reference/apis-arkdata/js-apis-data-uniformDataStruct.md#contentform14) | 'general.content-form' | Content widget.|
## How to Develop
diff --git a/en/application-dev/database/uniform-data-type-list.md b/en/application-dev/database/uniform-data-type-list.md
index 18d61615b81ba229db9b95459034763ee3656190..d782b0cbd1f97335d074f40bf72168a2674b8ff5 100644
--- a/en/application-dev/database/uniform-data-type-list.md
+++ b/en/application-dev/database/uniform-data-type-list.md
@@ -17,12 +17,12 @@ Generic UTDs define universal data types that can be identified by a majority of
| general.file | general.entity | - | - | Generic file type. |
| general.directory | general.entity | - | - | Generic directory type. |
| general.folder | general.directory | - | - | Generic folder type. |
-| general.symlink | general.entity | - | - | Generic symbolic link type. |
+| general.symlink | general.entity | - | - | Generic symbolic link type. |
| general.composite-object | general.object | - | - | Generic composite content type, for example, a PDF file that contains text and images.|
| general.media | general.object | - | - | Generic media type. |
-| general.content-form | general.object | - | - | Data content card type|
+| general.content-form | general.object | - | - | Data content widget type.|
| general.image | general.media | - | - | Generic image type. |
-| general.png | general.image | .png | image/png | PNG image format. |
+| general.png | general.image | .png | image/png | PNG image format. |
| general.jpeg | general.image | .jpg, .jpeg,.jpe | image/jpeg | JPEG image format. |
| general.tiff | general.image | .tif, .tiff | image/tiff | TIFF image format. |
| general.raw-image | general.image | - | - | Generic raw image type. |
@@ -51,7 +51,7 @@ Generic UTDs define universal data types that can be identified by a majority of
| general.mpeg-4 | general.video | .mp4, .mp4v, .mpeg4 | video/mp4, video/mp4v | MPEG-4 video format. |
| general.3gpp | general.video | .3gp, .3gpp | video/3gpp | 3GPP video format. |
| general.3gpp2 | general.video | .3g2, .3gp2, .3gpp2 | video/3gpp2 | 3GPP2 video format. |
-| general.vob | general.video | .vob | video/mpeg, video/x-ms-vob | Video Object (VOB) format, a container format in DVD video media. |
+| general.vob | general.video | .vob | video/mpeg, video/x-ms-vob | Video Object (VOB) format, a container format in DVD video media. |
| general.dif-video | general.video | .dif | video/dv | DIF video format. |
| general.dv-video | general.video | .dv | video/dv | DV video format. |
| general.flc-animation | general.video | .fli, .flc | video/fli, video/flc | FLIC animation file format. |
@@ -85,7 +85,7 @@ Generic UTDs define universal data types that can be identified by a majority of
| general.mp2 | general.audio | .mp2 | audio/mpeg | MP2 audio format. |
| general.mpeg-audio | general.audio | .mpga | audio/mpeg | MPEG audio format. |
| general.mxmf | general.audio | .mxmf | audio/mobile-xmf | Mobile XMF audio format. |
-| general.ota | general.audio | .ota | audio/midi | OTA ringtone audio format. |
+| general.ota | general.audio | .ota | audio/midi | OTA ringtone audio format. |
| general.pls | general.audio | .pls | audio/x-scpls | Multimedia playlist format. |
| general.rtttl | general.audio | .rtttl | audio/midi | RTTTL format. |
| general.psid | general.audio | .sid, .psid | audio/prs.sid | SID audio format. |
@@ -139,7 +139,7 @@ Generic UTDs define universal data types that can be identified by a majority of
| general.calendar | general.text | - | - | Generic calendar data type. |
| general.vcs | general.calendar | .vcs | text/calendar | vCalendar format. |
| general.ics | general.calendar | .ics | text/calendar | iCalendar format. |
-| general.comma-separated-values-text | general.delimited-values-text | .csv | text/csv | Comma-separated values (CSV). |
+| general.comma-separated-values-text | general.delimited-values-text | .csv | text/csv | Comma-separated values (CSV). |
| general.tab-separated-values-text | general.delimited-values-text | .tsv | text/tab-separated-values | Tab-separated values (TSV). |
| general.mathml | general.xml | .mml | text/mathml,application/mathml+xml | Mathematical markup language file format. |
| general.xhtml | general.xml | .xhtml | application/xhtml+xml | Extended hypertext markup language file format. |
@@ -152,9 +152,9 @@ Generic UTDs define universal data types that can be identified by a majority of
| general.c-source | general.source-code | .c | text/x-csrc | C source code. |
| general.c-header | general.source-code | .h | text/x-chdr | C header file. |
| general.c-plus-plus-source | general.source-code | .cp, .cpp, .c++, .cc, .cxx | text/x-c++src | C++ source code. |
-| general.c-plus-plus-header | general.source-code | .hpp, .h++ , .hxx, .hh | text/x-c++hdr | C++ header file. |
+| general.c-plus-plus-header | general.source-code | .hpp, .h++ , .hxx, .hh | text/x-c++hdr | C++ header file. |
| general.java-source | general.source-code | .java, .jav | text/x-java | Java source code. |
-| general.boo-source | general.source-code | .boo | text/x-boo | BOO source code. |
+| general.boo-source | general.source-code | .boo | text/x-boo | BOO source code. |
| general.d-source | general.source-code | .d | text/x-dsrc | D source code. |
| general.html-component | general.source-code | .htc | text/x-component | HTML component. |
| general.pascal-source | general.source-code | .p,.pas | text/x-pascal | Pascal source code. |
@@ -177,7 +177,7 @@ Generic UTDs define universal data types that can be identified by a majority of
| general.python-script | general.shell-script | .py | text/x-python-script | Python script. |
| general.ruby-script | general.shell-script | .rb, .rbw | text/ruby-script | Ruby script. |
| general.php-script | general.shell-script | .php, .php3, .php4, .ph3, .ph4, .phtml | text/x-php-script, text/php, application/php | PHP script. |
-| general.uri | general.object | - | - | Uniform Resource Identifier (URI). |
+| general.uri | general.object | - | - | Uniform Resource Identifier (URI). |
| general.file-uri | general.uri | - | - | File URI. |
| general.navigation | general.object | - | - | Generic navigation data type. |
| general.location | general.navigation | - | - | Navigation location. |
@@ -189,7 +189,7 @@ Generic UTDs define universal data types that can be identified by a majority of
| general.c-object | general.executable | .o | application/x-object | Compiled C file. |
| general.octet-stream | general.object | - | application/octet-stream - | Any binary data type. |
| general.mesh-model | general.object | .msh,.mesh,.silo | model/mesh | 3D mesh model format. |
-| general.certificate | general.object | - | - | Basic certificate type. |
+| general.certificate | general.object | - | - | Generic certificate type. |
| general.cer-certificate | general.certificate | .cer | application/pkix-cert | Internet certificate format. |
| general.crt-certificate | general.certificate | .crt | application/x-x509-ca-cert,application/x-x509-server-cert,application/x-x509-user-cert | Certificate format. |
| general.crl-certificate | general.certificate | .crl | application/x-pkix-crl | Certificate revocation list (CRL) format. |
@@ -201,7 +201,7 @@ Generic UTDs define universal data types that can be identified by a majority of
| general.opentype-font | general.font | .otf | font/otf | OpenType font. |
| general.ofd | general.composite-object | .ofd | - | Open Fixed-layout Document (OFD) format. |
| general.prn | general.composite-object | .prn | - | PRN format. |
-| general.ebook | general.composite-object | - | - | Generic eBook type. |
+| general.ebook | general.composite-object | - | - | Generic eBook type. |
| general.epub | general.ebook | .epub | application/epub+zip | Electronic Publication (EPUB) format. |
@@ -209,20 +209,20 @@ Generic UTDs define universal data types that can be identified by a majority of
The system-specific UTDs are closely related to a platform or an operating system and are used for cross-application interaction within the system or platform. The IDs of system-specific UTDs are in the **os-name**.xxx format. The following table lists the system-specific UTDs prebuilt in the system.
| UTD ID | **BelongingTo** | **File Name Extension** | **MIME Type** | **Description** |
|----------------------------|--------------------------|---------------------------------------|--------------------------------------------------------------------|----------------------------------|
-| openharmony.form | general.object | - |- | Form type defined for OpenHarmony. |
-| openharmony.app-item | general.object | - |- | Home screen icon defined for OpenHarmony. |
-| openharmony.want | general.object | - |- | Want data type defined for OpenHarmony. |
-| openharmony.atomic-service | general.object | - |- | Atomic service defined for OpenHarmony. |
-| openharmony.package | general.directory | - |- | Package defined for OpenHarmony. |
-| openharmony.hap | openharmony.package | .hap |- | Harmony Ability Package (HAP) defined for OpenHarmony. |
+| openharmony.form | general.object | - |- | Form type defined by OpenHarmony. |
+| openharmony.app-item | general.object | - |- | Home screen icon defined by OpenHarmony. |
+| openharmony.want | general.object | - |- | Want data type defined by OpenHarmony. |
+| openharmony.atomic-service | general.object | - |- | Atomic service defined by OpenHarmony. |
+| openharmony.package | general.directory | - |- | Package defined by OpenHarmony. |
+| openharmony.hap | openharmony.package | .hap |- | Harmony Ability Package (HAP) defined by OpenHarmony. |
| openharmony.app | openharmony.package | .app |- | Application package type defined by the system. |
| openharmony.hsp | openharmony.package | .hsp |- | Dynamic shared package defined by the system. |
| openharmony.har | openharmony.package | .har |- | Static shared package defined by the system. |
-| openharmony.hdoc | general.composite-object | .hdoc |- | Notepad file format defined for OpenHarmony. |
-| openharmony.hinote | general.composite-object | .hinote |- | Note file format defined for OpenHarmony. |
-| openharmony.styled-string | general.composite-object | - |- | String type defined for OpenHarmony. |
-| openharmony.moving-photo | general.media | - |- | Moving photo defined for OpenHarmony.|
-| openharmony.pixel-map | general.image | - |- | Pixel Map defined for OpenHarmony. |
+| openharmony.hdoc | general.composite-object | .hdoc |- | Notepad file format defined by OpenHarmony. |
+| openharmony.hinote | general.composite-object | .hinote |- | Note file format defined by OpenHarmony. |
+| openharmony.styled-string | general.composite-object | - |- | String type defined by OpenHarmony. |
+| openharmony.moving-photo | general.media | - |- | Moving photo defined by OpenHarmony.|
+| openharmony.pixel-map | general.image | - |- | Pixel Map defined by OpenHarmony. |
| macos.dmg | general.disk-image | .dmg | application/x-apple-diskimage | Installation package format defined by MacOS. |
| debian.deb | general.archive | .deb,.udeb | application/x-debian-package,application/vnd.debian.binary-package | Software package format defined by Debian. |
| com.android.apk | general.archive | .apk, .apks, .aab, .xapk, .apkm, .akp | application/vnd.android.package-archive | Android application installation package format. |
@@ -240,7 +240,7 @@ Application-specific UTDs are defined and maintained by a specific application o
| com.microsoft.windows-media-wm | general.video,com.microsoft.advanced-systems-format | .wm | video/x-ms-wm | Microsoft Windows WM video format. |
| com.microsoft.windows-media-wmv | general.video,com.microsoft.advanced-systems-format | .wmv | video/x-ms-wmv | Microsoft Windows WMV video format. |
| com.microsoft.windows-media-wmp | general.video,com.microsoft.advanced-systems-format | .wmp | video/x-ms-wmp | Microsoft Windows WMP video format. |
-| com.microsoft.windows-media-wma | general.audio,com.microsoft.advanced-systems-format | .wma | audio/x-ms-wma | Microsoft Windows WMA video format. |
+| com.microsoft.windows-media-wma | general.audio,com.microsoft.advanced-systems-format | .wma | audio/x-ms-wma | Microsoft Windows WMA video format. |
| com.microsoft.windows-media-wmx | general.video,com.microsoft.advanced-systems-format | .wmx | video/x-ms-wmx | Microsoft Windows WMX video format. |
| com.microsoft.windows-media-wvx | general.video,com.microsoft.advanced-systems-format | .wvx | video/x-ms-wvx | Microsoft Windows WVX video format. |
| com.microsoft.windows-media-wax | general.audio,com.microsoft.advanced-systems-format | .wax | audio/x-ms-wax | Microsoft Windows WAX audio format. |
@@ -273,7 +273,7 @@ Application-specific UTDs are defined and maintained by a specific application o
| com.microsoft.powerpoint.pot | general.composite-object | .pot | application/vnd.ms-powerpoint | Microsoft PowerPoint template. |
| com.microsoft.excel.xlt | general.composite-object | .xlt | application/vnd.ms-excel | Microsoft Excel template. |
| com.microsoft.visio.vsd | general.composite-object | .vsd | application/vnd.visio | Microsoft Visio. |
-| com.microsoft.excel.dif | general.composite-object | .dif | - | Microsoft Excel Data Interchange Format. |
+| com.microsoft.excel.dif | general.composite-object | .dif | - | Microsoft Excel Data Interchange Format. |
| com.microsoft.lsf-video | general.video | .lsf, .lsx | video/x-la-asf | Streaming media format.|
| org.openxmlformats.openxml | general.archive | - | - | Generic OpenXML format. |
| org.openxmlformats.wordprocessingml.document | org.openxmlformats.openxml, general.composite-object | .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document | OpenXML-formatted Microsoft Word document. |
@@ -292,18 +292,18 @@ Application-specific UTDs are defined and maintained by a specific application o
| org.openxmlformats.spreadsheetml.binary.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .xlsb | application/vnd.ms-excel.sheet.binary.macroEnabled.12 | OpenXML-formatted, macro-enabled Excel file in binary format. |
| org.openxmlformats.spreadsheetml.sheet.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .xlsm | application/vnd.ms-excel.sheet.macroEnabled.12 | OpenXML-formatted Excel file with macros written in VBA. |
| org.openxmlformats.presentationml.addin.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .ppam | application/vnd.ms-powerpoint.addin.macroEnabled.12 | OpenXML-formatted PowerPoint add-in file with enabled macros. |
-| org.openxmlformats.presentationml.presentation.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .pptm | application/vnd.ms-powerpoint.presentation.macroEnabled.12 | OpenXML-formatted PowerPoint file with macros written in VBA. |
-| org.openxmlformats.presentationml.slideshow.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .ppsm | application/vnd.ms-powerpoint.slideshow.macroEnabled.12 | OpenXML-formatted PowerPoint slideshow file with enabled macros. |
-| org.openxmlformats.presentationml.template.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .potm | application/vnd.ms-powerpoint.template.macroEnabled.12 | OpenXML-formatted PowerPoint template file with enabled macros. |
-| org.openxmlformats.drawingml.visio.macroenabled | org.openxmlformats.openxml, general.composite-object | .vsdm | - | OpenXML-formatted Visio drawing with enabled macros. |
-| org.openxmlformats.drawingml.template.macroenabled | org.openxmlformats.openxml, general.composite-object | .vstm | - | OpenXML-formatted Visio template with enabled macros. |
+| org.openxmlformats.presentationml.presentation.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .pptm | application/vnd.ms-powerpoint.presentation.macroEnabled.12 | OpenXML-formatted PowerPoint file with macros written in VBA. |
+| org.openxmlformats.presentationml.slideshow.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .ppsm | application/vnd.ms-powerpoint.slideshow.macroEnabled.12 | OpenXML-formatted PowerPoint slideshow file with enabled macros. |
+| org.openxmlformats.presentationml.template.macroenabled | org.openxmlformats.openxml, general.composite-object, general.executable | .potm | application/vnd.ms-powerpoint.template.macroEnabled.12 | OpenXML-formatted PowerPoint template file with enabled macros. |
+| org.openxmlformats.drawingml.visio.macroenabled | org.openxmlformats.openxml, general.composite-object | .vsdm | - | OpenXML-formatted Visio drawing with enabled macros. |
+| org.openxmlformats.drawingml.template.macroenabled | org.openxmlformats.openxml, general.composite-object | .vstm | - | OpenXML-formatted Visio template with enabled macros. |
| com.kingsoft.office | general.archive | - | - | Generic Kingsoft Office document type. |
| com.kingsoft.office.writer.wps | com.kingsoft.office,general.composite-object | .wps | - | Kingsoft WPS Office document. |
| com.kingsoft.office.writer.wpt | com.kingsoft.office,general.composite-object | .wpt | - | Kingsoft WPS Office document template. |
| com.kingsoft.office.presentation.dps | com.kingsoft.office,general.composite-object | .dps | - | Kingsoft WPS Presentation. |
| com.kingsoft.office.presentation.template | com.kingsoft.office,general.composite-object | .dpt | - | Kingsoft WPS Presentation template. |
-| com.kingsoft.office.spreadsheets.et | com.kingsoft.office,general.composite-object | .et | - | Kingsoft electronic spreadsheet. |
-| com.kingsoft.office.spreadsheets.template | com.kingsoft.office,general.composite-object | .ett | - | Kingsoft electronic spreadsheet template. |
+| com.kingsoft.office.spreadsheets.et | com.kingsoft.office,general.composite-object | .et | - | Kingsoft electronic spreadsheet. |
+| com.kingsoft.office.spreadsheets.template | com.kingsoft.office,general.composite-object | .ett | - | Kingsoft electronic spreadsheet template. |
| com.kingsoft.office.spreadsheets.etx | com.kingsoft.office,general.composite-object | .etx | - | Kingsoft electronic spreadsheet in plain text format for exchanging data between different applications. |
| com.kingsoft.office.spreadsheets.ettx | com.kingsoft.office,general.composite-object | .ettx | - | Kingsoft encrypted electronic spreadsheet. |
| org.oasis.opendocument | general.archive | - | - | Generic OpenDocument type. |
@@ -356,7 +356,7 @@ Application-specific UTDs are defined and maintained by a specific application o
| com.adobe.photoshop-image | general.image | .psd | image/x-photoshop, image/photoshop, image/psd, application/photoshop | Adobe Photoshop document. |
| com.adobe.illustrator.ai-image | general.image | .ai | - | Adobe Illustrator document. |
| com.adobe.dcr | general.video | .dcr | application/x-director | Adobe Shockwave document. |
-| com.adobe.dir | general.video | .dir | application/x-director | Adobe Director document. |
+| com.adobe.dir | general.video | .dir | application/x-director | Adobe Director document. |
| com.adobe.dxr | general.video | .dxr | application/x-director | Adobe Director Protected Movie document. |
| com.adobe.futuresplash | general.video | .spl | application/futuresplash, application/x-futuresplash | FutureSplash animation format. |
| com.adobe.flash | general.video | .swf, .flv | application/x-shockwave-flash, video/x-flv | Adobe Flash file format. |
@@ -372,13 +372,13 @@ Application-specific UTDs are defined and maintained by a specific application o
| com.amazon.mobi | general.ebook | .mobi | application/x-mobipocket-ebook | MOBI eBook format. |
| com.amazon.azw | general.ebook | .azw | application/vnd.amazon.ebook | AZW eBook format. |
| com.amazon.azw3 | general.ebook | .azw3 | application/vnd.amazon.mobi8-ebook, application/x-mobi8-ebook | AZW3 eBook format. |
-| com.amazon.kfx | general.ebook | .kfx | - | KFX eBook format. |
+| com.amazon.kfx | general.ebook | .kfx | - | KFX eBook format. |
| com.autodesk.dwg | general.composite-object | .dwg | image/vnd.dwg | AutoCAD file format. |
| com.autodesk.dxf | general.composite-object | .dxf | image/vnd.dxf | AutoCAD Drawing Exchange Format (DXF). |
| com.autodesk.dws | general.composite-object | .dws | - | AutoCAD drawing standards file. |
| com.autodesk.dwt | general.composite-object | .dwt | - | AutoCAD drawing template. |
| com.autodesk.dwf | general.composite-object | .dwf | model/vnd.dwf | AutoCAD Design Web Format (DWF). |
-| com.autodesk.dwfx | general.composite-object | .dwfx | - | Autodesk format used for sharing 2D/3D design data. |
+| com.autodesk.dwfx | general.composite-object | .dwfx | - | Autodesk format used for sharing 2D/3D design data. |
| com.autodesk.shp | general.composite-object | .shp | - | AutoCAD 3D vector data format. |
| com.autodesk.shx | general.composite-object | .shx | - | Format of a shape index file associated with AutoCAD. |
| com.autodesk.slide-library | general.composite-object | .slb | - | AutoCAD slide library file format. |
@@ -421,7 +421,7 @@ Application-specific UTDs are defined and maintained by a specific application o
| com.j2.jfx-fax | general.fax | .jfx | - | J2 jConnect fax file format. |
| com.js.efx-fax | general.fax | .efx | image/efax | Electronic fax file format. |
| com.canon.cr2-raw-image | general.raw-image | .cr2 | image/x-canon-cr2 | Canon Raw 2 image file format. |
-| com.canon.cr3-raw-image | general.raw-image | .cr3 | image/x-canon-cr3 | Canon Raw 3 image file format. |
+| com.canon.cr3-raw-image | general.raw-image | .cr3 | image/x-canon-cr3 | Canon Raw 3 image file format. |
| com.canon.crw-raw-image | general.raw-image | .crw | image/x-canon-crw | Canon Raw CIFF image file format. |
| com.sony.arw-raw-image | general.raw-image | .arw | image/x-sony-arw | Sony Raw image format used by Sony digital cameras. |
| com.nikon.nef-raw-image | general.raw-image | .nef | image/x-nikon-nef | Nikon Raw image format used by Nikon digital cameras. |
diff --git a/en/application-dev/device/driver/Readme-EN.md b/en/application-dev/device/driver/Readme-EN.md
index 9756b0ad993c6a8883c63371e46e8d021e440b13..9b585a7dbaae965dded260d308e9249d8a4d1268 100644
--- a/en/application-dev/device/driver/Readme-EN.md
+++ b/en/application-dev/device/driver/Readme-EN.md
@@ -1,6 +1,14 @@
# Driver Development Kit
- - [Introduction to Driver Development Kit](driverdevelopment-overview.md)
- - [Peripheral Driver Client Development](externaldevice-guidelines.md)
- - [DriverExtensionAbility Development](driverextensionability.md)
- - [FAQs](externaldevice-faqs.md)
+- [Introduction to Driver Development Kit](driverdevelopment-overview.md)
+- [Environment Preparation](environmental-preparation.md)
+- Basic Peripheral Driver Development
+ - [UI-free Driver Development](driverextensionability.md)
+ - [UI-based Driver Development](externaldevice-guidelines.md)
+- Dedicated Peripheral Driver Development
+ - [USB DDK Development](usb-ddk-guidelines.md)
+ - [HID DDK Development](hid-ddk-guidelines.md)
+ - [USB Serial DDK Development](usb-serial-ddk-guidelines.md)
+ - [SCSI Peripheral DDK Development](scsi-peripheral-ddk-guidelines.md)
+- [FAQs](externaldevice-faqs.md)
+- [Terms](terms.md)
diff --git a/en/application-dev/device/driver/driverdevelopment-overview.md b/en/application-dev/device/driver/driverdevelopment-overview.md
index 39415998f29ce12b0530c2806c5bdce9d309043d..ece2d5083b9eb42c9f41a02918a315af16c2a594 100644
--- a/en/application-dev/device/driver/driverdevelopment-overview.md
+++ b/en/application-dev/device/driver/driverdevelopment-overview.md
@@ -1,16 +1,12 @@
# Introduction to Driver Development Kit
-Empowered by the C-API solution, Driver Development Kit provides easy-to-use, secure, and diversified C APIs to elevate your experience in developing peripheral drivers, which bring ultimate plug-and-play experience to users.
-
-1. You can develop advanced peripheral functions to meet user requirements.
-
-2. The extended driver framework supports lifecycle management of peripheral drivers and provides APIs for querying and binding peripheral devices.
+Empowered by the C-API solution, Driver Development Kit provides easy-to-use, secure, and diversified ArkTs-API and C APIs to elevate your experience in developing peripheral drivers, which bring ultimate plug-and-play experience to users.
## When to Use
-You can use Driver Development Kit to:
+With Driver Development Kit, you can develop dedicated or extended peripheral drivers in an efficient and secure manner.
-1. Develop drivers of special
+1. Develop drivers of dedicated
peripherals for bank counters, enterprise office, and medical detection, such as high-speed document scanners, ID card scanners, fingerprint scanners, and blood oxygen and blood glucose meters.
@@ -18,33 +14,68 @@ You can use Driver Development Kit to:
such as customizing handwriting pad shortcut keys, setting the pressure sensing/drawing area, setting extended enhancement capabilities, setting the mouse lighting effect, customizing mouse extended buttons, and setting DPI and X and Y axes.
-## Working Principles
+## Typical Use Cases
+
+- You can develop advanced peripheral functions to meet user requirements.
+
+- The extended driver framework supports lifecycle management of peripheral drivers and provides APIs for querying and binding peripheral devices.
+
+## Basic Concepts
+
+- Peripheral driver client: [basic UI-based driver](externaldevice-guidelines.md), which is used to query and bind drivers, and customize the communication mode and data processing mode.
+- Peripheral driver: [basic UI-free driver](driverextensionability.md), which is the dedicated peripheral driver or enhanced peripheral driver developed based on the DDK.
+- External Device Manager: performs lifecycle management of peripheral devices and driver packages.
+- Bundle Manager Service (BMS): manages application installation, uninstallation, and data on the system.
+- Ability Manager Service (AMS): starts and stops **DriverExtensionAbility**.
+
+## Implementation Principles
The HDF extended driver framework provides unified APIs for you to leverage the DDK capabilities for user-mode peripheral driver development.
-The driver extension system ability (SA), the core service of user-mode peripheral management, performs lifecycle management of peripherals and peripheral drivers. In addition, standard ArkTS APIs are provided to query, bind, and unbind peripherals.
+External Device Manager, the core service of user-mode peripheral management, performs lifecycle management of peripherals and peripheral drivers. In addition, standard ArkTS APIs are provided to query, bind, and unbind peripherals.
+
+### Peripheral Driver Architecture
**Figure 1** Peripheral driver working mechanism
-### **Module Functions**
-- Peripheral application: queries and binds the driver, and customizes the device-driver communication mode and data processing mode. For details, see [Peripheral Driver Client Development](externaldevice-guidelines.md).
-- Peripheral driver (application): dedicated peripheral driver or enhanced peripheral driver developed using HDF-DDK. For details, see [Peripheral Driver Development](driverextensionability.md).
-- Driver extension SA: performs lifecycle management of peripheral devices and driver packages.
-- AMS: starts and disables **DriverExtensionAbility**.
+### Operation Process
-### **Process Description**
+Figure 2 shows the process for matching a peripheral driver client with a peripheral driver when a peripheral is connected.
-Figure 2 shows the process of matching a peripheral with a driver when a peripheral is connected.
-
-**Figure 2** Process for matching a peripheral with a driver
+**Figure 2** Process for matching a peripheral driver client with a peripheral driver
-Figure 2 shows the process of binding the peripheral driver client with a peripheral driver when a peripheral application is run.
+Figure 3 shows the process for binding the peripheral driver client with a peripheral driver.
**Figure 3** Process of binding the peripheral driver client with a peripheral driver
+
+## Notes and Constraints
+
+To call the ArkTs or C APIs provided by Driver Development Kit, you need to apply for specified permissions.
+
+The following table lists the required permissions.
+
+| API Type| DDK Type| Permission|
+| --------- | --------- | --------- |
+| ArkTs-API | NA| ohos.permission.ACCESS_EXTENSIONAL_DEVICE_DRIVER |
+| C-API | USB DDK | ohos.permission.ACCESS_DDK_USB |
+| C-API | HID DDK | ohos.permission.ACCESS_DDK_HID |
+| C-API | USB Serial DDK | ohos.permission.ACCESS_DDK_USB_SERIAL |
+| C-API | SCSI Peripheral DDK | ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL |
+
+## Associated Modules
+
+The following table lists the associated modules you may use during development of peripheral drivers.
+
+| Name| Description|
+| --------- | --------- |
+| PerformanceAnalysisKit | Introduces {hilog} for log printing.|
+| BasicServicesKit | Introduces {BusinessError} to capture error information.|
+| IPCKit | Introduces {rpc} to implement inter-process communication between the driver and the client.|
+| AbilityKit | Introduces {want} for lifecycle management.|
diff --git a/en/application-dev/device/driver/driverextensionability.md b/en/application-dev/device/driver/driverextensionability.md
index 7b830a8abc7378b68f4d6a1109feca65c4380173..7daf69c8feba57abf66fa1766ecac53e72e0ada4 100644
--- a/en/application-dev/device/driver/driverextensionability.md
+++ b/en/application-dev/device/driver/driverextensionability.md
@@ -1,23 +1,19 @@
-# Peripheral Driver Development
+# UI-free Driver Development
## When to Use
-[DriverExtensionAbility](../../reference/apis-driverdevelopment-kit/js-apis-app-ability-driverExtensionAbility.md) is an **ExtensionAbility** of the driver type that provides the driver-related extension framework. If the capabilities of a device can be expanded by inserting an external hardware module, you can install the driver of the hardware module through an application. **DriverExtensionAbility** can be used to develop such applications.
+Basic UI-free drivers are applicable to simple devices that do not require setting of driver capabilities via a UI, such as mice and keyboards. These drivers are designed to ensure that these devices can be used immediately upon connection, enabling seamless plug-and-play functionality. You can use **DriverExtensionAbility** to develop such applications.
+## Basic Concepts
-You can bind a [DriverExtensionAbility](../../reference/apis-driverdevelopment-kit/js-apis-app-ability-driverExtensionAbility.md) object to an application through **DriverExtensionManager** so that related transactions can be processed in the background based on the application request information.
-Each type of **ExtensionAbility** has its own context. The **DriverExtensionAbility** provides related capabilities through the [DriverExtensionContext](../../reference/apis-driverdevelopment-kit/js-apis-inner-application-driverExtensionContext.md).
+ - DriverExtensionAbility
-## Environment Setup
-
-Set up the environment following the instructions in [Peripheral Driver Client Development](externaldevice-guidelines.md).
+ [DriverExtensionAbility](../../reference/apis-driverdevelopment-kit/js-apis-app-ability-driverExtensionAbility.md) is an **ExtensionAbility** of the driver type that provides the driver-related extension framework. If the capabilities of a device can be expanded by inserting an external hardware module, you can install the driver of the hardware module through an application. You can bind a [DriverExtensionAbility](../../reference/apis-driverdevelopment-kit/js-apis-app-ability-driverExtensionAbility.md) object to an application through **DriverExtensionManager** so that related transactions can be processed in the background based on the application request information.
+ Each type of **ExtensionAbility** has its own context. The **DriverExtensionAbility** provides related capabilities through the [DriverExtensionContext](../../reference/apis-driverdevelopment-kit/js-apis-inner-application-driverExtensionContext.md).
-The following table lists the SDK version requirements.
+## Environment Setup
-| NDK API| SDK Version|
-|---------|--------|
-| USB DDK | API version 10 or later|
-| HID DDK | API version 11 or later|
+Before you get started, make necessary preparations by following instructions in [Environment Preparation](environmental-preparation.md).
## How to Develop
@@ -168,12 +164,12 @@ To implement a driver, create a DriverExtensionAbility in the DevEco Studio proj
## Driver Development
-**DriverExtensionAbility** provides two development modes, namely, HID DDK and USB DDK, for driver development.
-
-Choose either mode depending on your need:
+Currently, **DriverExtensionAbility** provides four capabilities: HID DDK, USB DDK, USB serial DDK, and SCSI peripheral DDK, which are used to develop dedicated drivers for extended peripherals. Choose either mode depending on your need:
-* [HID DDK Development](https://gitee.com/openharmony/docs/blob/master/en/application-dev/napi/hid-ddk-guidelines.md)
-* [USB DDK Development](https://gitee.com/openharmony/docs/blob/master/en/application-dev/napi/usb-ddk-guidelines.md)
+* [HID DDK Development](hid-ddk-guidelines.md)
+* [USB DDK Development](usb-ddk-guidelines.md)
+* [USB Serial DDK Development](usb-serial-ddk-guidelines.md)
+* [SCSI Peripheral DDK Development](scsi-peripheral-ddk-guidelines.md)
## Application Signing
diff --git a/en/application-dev/device/driver/environmental-preparation.md b/en/application-dev/device/driver/environmental-preparation.md
new file mode 100644
index 0000000000000000000000000000000000000000..5222cc13ad2d39f1cf6aee72a190b98e546dfb0f
--- /dev/null
+++ b/en/application-dev/device/driver/environmental-preparation.md
@@ -0,0 +1,40 @@
+# Preparing the Environment
+
+### Development Tool and Configuration
+
+DevEco Studio, as the driver development tool, allows you to develop, debug, and package drivers.
+
+[Download and install](https://developer.huawei.com/consumer/en/download/) DevEco Studio and verify basic operations to ensure that it can function properly. For details, see [Creating and Running a Project](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V13/ide-create-new-project-V13) in [DevEco Studio User Guide](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V13/ide-tools-overview-V13).
+
+### SDK Version Configuration
+
+The ArkTs APIs for peripheral management can be used only when the SDK is of API version 10 or later. For details about how to update the SDK, see [OpenHarmony SDK Upgrade Assistant](../../tools/openharmony_sdk_upgrade_assistant.md).
+
+The SDK version must meet the following requirements when you develop dedicated peripheral drivers or enhanced peripheral drivers based on the DDK.
+
+| NDK API | SDK Version |
+|----------------|----------|
+| USB DDK | API version 10 or later|
+| HID DDK | API version 11 or later|
+| USB Serial DDK | API version 18 or later|
+| SCSI Peripheral DDK | API version 18 or later|
+
+### Verifying the Environment
+
+Check whether DevEco Studio is connected to the OpenHarmony device.
+
+
+
+### HDC Configuration
+
+HarmonyOS Device Connector (hdc) is a command-line tool for debugging. It can be used to interact with real devices or the Emulators on Windows, Linux, and macOS. For details about the configuration, see [hdc](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
+
+**NOTE**
Configuration of the environment variable **hdc_server_port** and global environment variables is mandatory.
+
+### Development Device
+
+* Currently, RK3568 is used as the device for development, debugging, and verification. For details about how to compile and burn the RK3568, see [Quick Start](https://gitee.com/openharmony/docs/blob/master/en/device-dev/quick-start/quickstart-pkg-3568-burn.md).
+* During peripheral client and driver development, you need to connect an external USB device for debugging. Currently, **only an external USB device is supported**.
+* The product ID and vendor ID of the USB device are required for defining drivers and implementing IPC.
+
+
\ No newline at end of file
diff --git a/en/application-dev/device/driver/externaldevice-faqs.md b/en/application-dev/device/driver/externaldevice-faqs.md
index 4d918650b2b68e5c3a08ae8b155cd1e432d19c54..e2ef125430609c78c01ac5fdf20981c39ffc4e57 100644
--- a/en/application-dev/device/driver/externaldevice-faqs.md
+++ b/en/application-dev/device/driver/externaldevice-faqs.md
@@ -25,10 +25,12 @@ The message "compileSdkVersion and releaseType of the app do not match the apiVe
### Version Mapping
| API Type| Minimum API Version| OpenHarmony Version|
-| ------------ | ------------ | ------------ |
+| --------- | --------- | --------- |
| Application development APIs (ArkTS APIs)| API10 | 4.0 Release or later|
| USB DDK APIs| API10 | 4.0 Release or later|
| HID DDK APIs| API11 | 4.0 Release or later|
+| USB Serial DDK API| API16 | 5.1 Release or later|
+| SCSI Peripheral DDK API| API16 | 5.1 Release or later|
## Failed to Parse the Local .so File During HAP Installation
@@ -39,4 +41,4 @@ The message "code:9568347 error: install parse native so failed" is displayed du
### Solution
-Configure the value of `abiFilters` in `buildOption/externalNativeOptions` in the `build-profile.json5` file. For details, see [Application Debugging](https://developer.huawei.com/consumer/en/doc/harmonyos-faqs-V5/faqs-app-debugging-14-V5).
+Configure the value of `abiFilters` in `buildOption/externalNativeOptions` in the `build-profile.json5` file. For details, see [Application Debugging] (https://developer.huawei.com/consumer/en/doc/harmonyos-faqs-V5/faqs-app-debugging-14-V5).
diff --git a/en/application-dev/device/driver/externaldevice-guidelines.md b/en/application-dev/device/driver/externaldevice-guidelines.md
index 8610fb7eab766d5d4ab0197308f97376f6a6d2e2..b079d16b86370391e2dbff0023d9391c30c71e24 100644
--- a/en/application-dev/device/driver/externaldevice-guidelines.md
+++ b/en/application-dev/device/driver/externaldevice-guidelines.md
@@ -1,34 +1,12 @@
-# Peripheral Driver Client Development
+# UI-based Driver Development
## When to Use
-Peripheral devices (or simply peripherals) are auxiliary devices connected to a device through physical ports, such as handwriting tablets, printers, and scanners. Applications can query and bind peripherals via peripheral management, so that the peripherals can use the customized capabilities provided by the peripheral drivers, such as the printer software.
-
-Peripheral management applies to all devices that can be ported to the OpenHarmony.
+UI-based basic drivers are applicable to a wide variety of composite devices. When developing these drivers, you may set the corresponding unique driver capabilities through the UI, or display the information retrieved from the devices on the UI. Examples of such devices include mice with side buttons, handwriting tablets, and ID card readers.
## Environment Setup
-### Development Tool and Configuration
-
-DevEco Studio, as the driver development tool, allows you to develop, debug, and package drivers.
-
-[Download and install](https://developer.huawei.com/consumer/en/download/) DevEco Studio and verify basic operations to ensure that it can function properly. For details, see [Creating and Running a Project](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V13/ide-create-new-project-V13) in [DevEco Studio User Guide](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V13/ide-tools-overview-V13).
-
-### SDK Version Configuration
-
-The ArkTs APIs for peripheral management can be used only when the SDK is of API version 10 or later.
-
-### HDC Configuration
-
-HarmonyOS Device Connector (HDC) is a command-line tool for debugging. It can be used to interact with real devices or emulators on Windows, Linux, and Mac. For details, see [HDC Configuration](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/hdc-V5).
-
-**NOTE**
Configuration of the environment variable **hdc_server_port** and global environment variables is mandatory.
-
-### Development Device
-
-* Currently, RK3568 is used as the device for development, debugging, and verification. For details about how to compile and burn the RK3568, see [Quick Start](https://gitee.com/openharmony/docs/blob/master/en/device-dev/quick-start/quickstart-pkg-3568-burn.md).
-* During client and driver development, you need to connect an external USB device for debugging. **Currently, only an external USB device is supported.**
-* The product ID and vendor ID of the USB device are required for defining drivers and implementing IPC.
+Before you get started, make necessary preparations by following instructions in [Environment Preparation](environmental-preparation.md).
## Available APIs
@@ -195,7 +173,7 @@ The following sample code is a demo that illustrates how to develop both the cli
}
```
-8. Develop the driver code. For details, see [Peripheral Driver Development](driverextensionability.md).
+8. Develop peripheral drivers by following instructions in [UI-free Driver Development](driverextensionability.md).
System applications can query detailed information about peripherals and drivers to implement management. The development procedure is as follows:
diff --git a/en/application-dev/device/driver/figures/ddk-schematic-diagram.png b/en/application-dev/device/driver/figures/ddk-schematic-diagram.png
new file mode 100644
index 0000000000000000000000000000000000000000..a71aaafa9ac220c2177ca02572198bdeca9dd36c
Binary files /dev/null and b/en/application-dev/device/driver/figures/ddk-schematic-diagram.png differ
diff --git "a/zh-cn/application-dev/napi/figures/\350\256\276\345\244\207\350\277\236\346\216\245.png" b/en/application-dev/device/driver/figures/device-connected.png
similarity index 100%
rename from "zh-cn/application-dev/napi/figures/\350\256\276\345\244\207\350\277\236\346\216\245.png"
rename to en/application-dev/device/driver/figures/device-connected.png
diff --git a/en/application-dev/napi/hid-ddk-guidelines.md b/en/application-dev/device/driver/hid-ddk-guidelines.md
similarity index 80%
rename from en/application-dev/napi/hid-ddk-guidelines.md
rename to en/application-dev/device/driver/hid-ddk-guidelines.md
index 3537afce9f0e5e5d2b885db951408f6edcd9fa4c..977130072ae89d566074074da5ce57eaeac86954 100644
--- a/en/application-dev/napi/hid-ddk-guidelines.md
+++ b/en/application-dev/device/driver/hid-ddk-guidelines.md
@@ -1,14 +1,36 @@
# HID DDK Development
-## When to Use
+## Overview
-The Human Interface Device (HID) driver development kit (DDK) is a toolset that helps you develop HID drivers at the application layer based on the user mode. It provides APIs for accessing HID devices on a host, including creating a HID device, sending an event to a device, destroying a device, opening or closing a device, reading and writing a report, and obtaining device information.
+The Human Interface Device (HID) Driver Development Kit (DDK) is a toolset that helps you develop HID drivers at the application layer based on the user mode. It provides APIs for accessing HID devices on a host, including creating a HID device, sending events to a device, destroying a device, opening or closing a device, reading and writing a report, and obtaining device information.
+
+The HID DDK can be used to develop drivers for devices that use HID protocol to transfer data over a USB bus, or for devices that use peripheral drivers to create virtual devices to exchange information with non-standard devices.
+
+### Basic Concepts
+
+Before developing the HID DDK, you must understand the following basic concepts:
+
+- **HID**
+
+ HID is a type of hardware device that implements interaction between a person and a computer or another electronic device. The primary function of HID is to convert user input (such as a key, a click, or a movement) into a data signal, and send the signal to a host device (such as a computer, tablet, or game console), so that the user can control and operate the device.
+
+- **DDK**
+
+ DDK is a tool package provided by OpenHarmony for developing drivers for non-standard USB serial port devices based on the peripheral framework.
+
+### Implementation Principles
+
+A non-standard peripheral application obtains the HID device ID by using the peripheral management service, and delivers the ID and the action to the HID device driver application through RPC. The driver application calls the HID DDK API to create and destroy a HID device, send events to a HID device, or obtain and parse packets sent from a HID device. The DDK API uses the HDI service to deliver instructions to the kernel driver, and the kernel driver uses instructions to communicate with the device.
+
+**Figure 1** Principles of invoking the HID DDK
+
+
## Constraints
* The APIs provided by the HID DDK can be used to develop drivers of non-standard HID devices.
-* The APIs provided by the HID DDK can be used only within the DriverExtensionAbility lifecycle.
+* The open APIs of HID DDK can be used only within the lifecycle of **DriverExtensionAbility**.
* Before using the open APIs of the HID DDK, you must declare the matching ACL permissions in **module.json5**, for example, **ohos.permission.ACCESS_DDK_HID**.
@@ -25,17 +47,17 @@ The Human Interface Device (HID) driver development kit (DDK) is a toolset that
| int32_t OH_Hid_Close(Hid_DeviceHandle **dev) | Closes a HID device.|
| int32_t OH_Hid_Write(Hid_DeviceHandle *dev, uint8_t *data, uint32_t length, uint32_t *bytesWritten) | Writes a report to a HID device.|
| int32_t OH_Hid_ReadTimeout(Hid_DeviceHandle *dev, uint8_t *data, uint32_t buffSize, int timeout, uint32_t *bytesRead) | Reads a report from a HID device within the specified time.|
-| int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t buffSize, uint32_t *bytesRead) | Reads a report from a HID device in the specified mode. The blocking mode (blocking remains active until data can be read) is used by default. You can call **OH_Hid_SetNonBlocking** to change the mode. |
+| int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t buffSize, uint32_t *bytesRead) | Reads a report from a HID device in the specified mode. The blocking mode (blocking remains active until data can be read) is used by default. You can call **OH_Hid_SetNonBlocking** to change the mode.|
| int32_t OH_Hid_SetNonBlocking(Hid_DeviceHandle *dev, int nonblock) | Sets the device read mode to non-blocking mode.|
| int32_t OH_Hid_GetRawInfo(Hid_DeviceHandle *dev, Hid_RawDevInfo *rawDevInfo) | Obtains the raw information of a HID device.|
| int32_t OH_Hid_GetRawName(Hid_DeviceHandle *dev, char *data, uint32_t buffSize) | Obtains the raw name of a HID device.|
| int32_t OH_Hid_GetPhysicalAddress(Hid_DeviceHandle *dev, char *data, uint32_t buffSize) | Obtains the physical address of a HID device.|
| int32_t OH_Hid_GetRawUniqueId(Hid_DeviceHandle *dev, uint8_t *data, uint32_t buffSize) | Obtains the raw unique identifier of a HID device.|
| int32_t OH_Hid_SendReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, const uint8_t *data, uint32_t length) | Sends a report to a HID device.|
-| int32_t OH_Hid_GetReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, uint8_t *data, uint32_t buffSize) | Obtains a report from a HID device. |
+| int32_t OH_Hid_GetReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, uint8_t *data, uint32_t buffSize) | Obtains a report from a HID device.|
| int32_t OH_Hid_GetReportDescriptor(Hid_DeviceHandle *dev, uint8_t *buf, uint32_t buffSize, uint32_t *bytesRead) | Obtains the report descriptor of a HID device.|
-For details about the APIs, see [HID DDK](../reference/apis-driverdevelopment-kit/_hid_ddk.md).
+For details about the APIs, see [HID DDK](../../reference/apis-driverdevelopment-kit/_hid_ddk.md).
## How to Develop
@@ -43,9 +65,9 @@ For details about the APIs, see [HID DDK](../reference/apis-driverdevelopment-ki
The following steps you through on how to develop a HID device driver using the HID DDK.
-**Adding the Dynamic Link Library**
+**Adding Dynamic Link Libraries**
-Add the following library to **CMakeLists.txt**.
+Add the following libraries to **CMakeLists.txt**.
```txt
libhid.z.so
```
@@ -90,7 +112,7 @@ libhid.z.so
};
// Create a device. The device ID of the device created is returned.
int32_t deviceId = OH_Hid_CreateDevice(&hidDevice, &hidEventProp);
- ```
+ ```
2. Send an event to the HID device.
@@ -118,9 +140,9 @@ libhid.z.so
The following steps you through on how to develop a HID packet communication driver using the HID DDK.
-**Adding the Dynamic Link Library**
+**Adding Dynamic Link Libraries**
-Add the following library to **CMakeLists.txt**.
+Add the following libraries to **CMakeLists.txt**.
```txt
libhid.z.so
```
@@ -140,7 +162,7 @@ libhid.z.so
OH_Hid_Init();
```
-2. Open a HID device.
+2. Open the device.
Call **OH_Hid_Open** in **hid_ddk_api.h** to open a HID device.
@@ -234,7 +256,7 @@ libhid.z.so
int32_t ret = OH_Hid_GetReport(dev, HID_INPUT_REPORT, data6, sizeof(data6));
```
- - If the report type is **HID_FEATURE_REPORT** (feature report), call **OH_Hid_GetReport** in **hid_ddk_api.h** to obtain a feature report from the HID device.
+ - If the report type is **HID_FEATURE_REPORT** (feature report), call **OH_Hid_GetReport** in **hid_ddk_api.h** to obtain a feature report from a HID device.
```c++
uint8_t data7[8] = {0};
@@ -245,22 +267,20 @@ libhid.z.so
int32_t ret = OH_Hid_GetReport(devFeature, HID_FEATURE_REPORT, data7, sizeof(data7));
```
-5. Obtain the raw device information, raw name, physical address, and raw unique identifier of the HID device.
+5. Obtain the raw device information, raw name, physical address, and raw unique identifier of a HID device.
- Call **OH_Hid_GetRawInfo** in **hid_ddk_api.h** to obtain the raw information about the HID device.
Call **OH_Hid_GetRawName** to obtain the raw name of the HID device.
Call **OH_Hid_GetPhysicalAddress** to obtain the physical address of the HID device.
Call **OH_Hid_GetRawUniqueId** to obtain the raw unique identifier of the HID device.
-
- The obtained information can be referenced by applications, for example, displaying device information on the GUI.
+ Call **OH_Hid_GetRawInfo** in **hid_ddk_api.h** to obtain the raw information about a HID device.
Call **OH_Hid_GetRawName** to obtain the raw name of a HID device.
Call **OH_Hid_GetPhysicalAddress** to obtain the physical address of a HID device.
Call **OH_Hid_GetRawUniqueId** to obtain the raw unique identifier of a HID device. The obtained information can be referenced by applications, for example, displaying device information on the GUI.
```c++
struct Hid_RawDevInfo rawDevInfo;
int32_t ret = OH_Hid_GetRawInfo(dev, &rawDevInfo);
-
+
char rawName[1024] = {0};
ret = OH_Hid_GetRawName(dev, rawName, sizeof(rawName));
-
+
char physicalAddress[1024] = {0};
ret = OH_Hid_GetPhysicalAddress(dev, physicalAddress, sizeof(physicalAddress));
-
+
uint8_t uniqueIdData[64] = {0};
ret = OH_Hid_GetRawUniqueId(dev, uniqueIdData, sizeof(uniqueIdData));
```
diff --git a/en/application-dev/device/driver/scsi-peripheral-ddk-guidelines.md b/en/application-dev/device/driver/scsi-peripheral-ddk-guidelines.md
new file mode 100644
index 0000000000000000000000000000000000000000..ba16e88b374a3748460057c8d64d34277d410c00
--- /dev/null
+++ b/en/application-dev/device/driver/scsi-peripheral-ddk-guidelines.md
@@ -0,0 +1,297 @@
+# SCSI Peripheral DDK Development
+
+## Overview
+
+Small Computer System Interface (SCSI) devices, such as disk arrays, tape libraries, and specific types of storage servers, are widely used in enterprise-level storage solutions and industrial application scenarios. If the operating system does not have an adaptation driver for these devices, the devices cannot be identified or used after being connected. SCSI Peripheral Driver Development Kit (DDK) is a suite provided for SCSI device driver development. It allows you to develop SCSI device drivers at the application layer based on the user mode.
+
+The SCSI Peripheral DDK supports seven common commands (including INQUIRY, READ CAPACITY, TEST UNIT READY, REQUEST SENSE, READ, WRITE, and VERIFY) in the three command sets: SCSI Primary Commands (SPC), SCSI Block Commands (SBC), and Multimedia Commands (MMC). You can use these commands at your preference.
+
+### Basic Concepts
+
+Before developing the SCSI Peripheral DDK, you must understand the following basic concepts:
+
+- **SCSI**
+
+ SCSI is a standard protocol set used for communication between computers and peripherals such as hard disk drives, tape drives, optical disk drives, and scanners.
+
+- **AMS**
+
+ The Ability Manager Service (AMS) is a system service used to coordinate the running relationships of abilities and schedule the lifecycle of abilities.
+
+- **BMS**
+
+ The Bundle Manager Service (BMS) is responsible for application installation, uninstallation, and data management on OpenHarmony.
+
+- **DDK**
+
+ The Driver Development Kit (DDK) is a tool package provided by OpenHarmony for developing drivers for non-standard SCSI peripherals based on the peripheral framework.
+
+- **Non-standard peripherals**
+
+ Non-standard peripherals (also called custom peripherals or dedicated peripherals) are peripherals that do not comply with general standards or are customized for specific application scenarios. This type of device usually requires special software support or special interfaces to implement communication with the host system.
+
+- **Standard peripherals**
+
+ Standard peripherals refer to peripherals (such as USB keyboards and mouse devices) that comply with industry standards and specifications. Such devices typically have uniform interface protocols, physical dimensions, and electrical characteristics, so that they can be used interchangeably between different systems.
+
+- **Logical block**
+
+ A logical block is a basic data storage unit. It represents a data area of a fixed size on a device and is usually used for data read and write operations. The size of a logical block may be 512 bytes, 1024 bytes, 2048 bytes, and so on. A specific size depends on a configuration of the device and a design of the file system.
+
+- **CDB**
+
+ A command descriptor block (CDB) is a standard data structure used to send commands in the SCSI protocol. A CDB is a byte array with a fixed length. It contains the operation code (Opcode) and related parameters of the SCSI command and is used to instruct the device to perform operations (such as read, write, and query).
+
+### Implementation Principles
+
+A non-standard peripheral application obtains the SCSI device ID by using the peripheral management service, and delivers the ID and the action to the SCSI driver application through RPC. The SCSI driver application can obtain the basic information about the SCSI device and read and write data by invoking the SCSI Peripheral DDK API. Then, the DDK API uses the HDI service to deliver instructions to the kernel driver, and the kernel driver uses instructions to communicate with the device.
+
+**Figure 1** Principle of invoking the SCSI Peripheral DDK
+
+
+
+### Constraints
+
+- The open APIs of SCSI Peripheral DDK support the development of standard SCSI peripheral drivers.
+
+- The open APIs of SCSI Peripheral DDK can be used only within the lifecycle of **DriverExtensionAbility**.
+
+- To use the open APIs of SCSI Peripheral DDK, you need to declare the corresponding ACL permission **ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL** in **module.json5**.
+
+## Environment Setup
+
+Before you get started, make necessary preparations by following instructions in [Environment Preparation](environmental-preparation.md).
+
+## How to Develop
+
+### Available APIs
+
+| **Name**| Description|
+| -------- | -------- |
+| int32_t OH_ScsiPeripheral_Init(void) | Initializes the SCSI Peripheral DDK.|
+| int32_t OH_ScsiPeripheral_Release(void) | Releases the SCSI Peripheral DDK.|
+| int32_t OH_ScsiPeripheral_Open(uint64_t deviceId, uint8_t interfaceIndex, ScsiPeripheral_Device **dev) | Opens the SCSI device specified by **deviceId** and **interfaceIndex**.|
+| int32_t OH_ScsiPeripheral_Close(ScsiPeripheral_Device **dev) | Disables the SCSI device.|
+| int32_t OH_ScsiPeripheral_TestUnitReady(ScsiPeripheral_Device *dev, ScsiPeripheral_TestUnitReadyRequest *request, ScsiPeripheral_Response *response) | Checks whether the logical units are ready.|
+| int32_t OH_ScsiPeripheral_Inquiry(ScsiPeripheral_Device *dev, ScsiPeripheral_InquiryRequest *request, ScsiPeripheral_InquiryInfo *inquiryInfo, ScsiPeripheral_Response *response) | Queries basic information about the SCSI device.|
+| int32_t OH_ScsiPeripheral_ReadCapacity10(ScsiPeripheral_Device *dev, ScsiPeripheral_ReadCapacityRequest *request, ScsiPeripheral_CapacityInfo *capacityInfo, ScsiPeripheral_Response *response) | Obtains the capacity information about the SCSI device.|
+| int32_t OH_ScsiPeripheral_RequestSense(ScsiPeripheral_Device *dev, ScsiPeripheral_RequestSenseRequest *request, ScsiPeripheral_Response *response) | Obtains sense data, that is, information returned by the SCSI device to the host, which is used to report the device status, error information, and diagnosis information.|
+| int32_t OH_ScsiPeripheral_Read10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request, ScsiPeripheral_Response *response) | Reads data from a specified logical block.|
+| int32_t OH_ScsiPeripheral_Write10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request, ScsiPeripheral_Response *response) | Writes data to a specified logical block of a device.|
+| int32_t OH_ScsiPeripheral_Verify10(ScsiPeripheral_Device *dev, ScsiPeripheral_VerifyRequest *request, ScsiPeripheral_Response *response) | Verifies a specified logical block.|
+| int32_t OH_ScsiPeripheral_SendRequestByCdb(ScsiPeripheral_Device *dev, ScsiPeripheral_Request *request, ScsiPeripheral_Response *response) | Sends the SCSI command in CDB mode.|
+| int32_t OH_ScsiPeripheral_CreateDeviceMemMap(ScsiPeripheral_Device *dev, size_t size, ScsiPeripheral_DeviceMemMap **devMmap) | Creates a buffer.|
+| int32_t OH_ScsiPeripheral_DestroyDeviceMemMap(ScsiPeripheral_DeviceMemMap *devMmap) | Destroys a buffer.|
+| int32_t OH_ScsiPeripheral_ParseBasicSenseInfo(uint8_t *senseData, uint8_t senseDataLen, ScsiPeripheral_BasicSenseInfo *senseInfo) | Parses basic sense data, including the **Information**, **Command specific information**, and **Sense key specific** fields.|
+
+For details about the interface, see [SCSI Peripheral DDK](../../reference/apis-driverdevelopment-kit/_s_c_s_i.md).
+
+### How to Develop
+
+The following describes how to use the SCSI Peripheral DDK to develop non-standard SCSI peripheral drivers.
+
+**Adding Dynamic Link Libraries**
+
+Add the following libraries to **CMakeLists.txt**.
+```txt
+libscsi.z.so
+```
+
+**Including Header Files**
+```c++
+#include
+#include
+```
+
+1. Initialize the SCSI Peripheral DDK.
+
+ Use **OH_ScsiPeripheral_Init** in **scsi_peripheral_api.h** to initialize the SCSI Peripheral DDK.
+
+ ```c++
+ // Initialize the SCSI Peripheral DDK.
+ int32_t ret = OH_ScsiPeripheral_Init();
+ ```
+
+2. Open the device.
+
+ After the SCSI Peripheral DDK is initialized, use **OH_ScsiPeripheral_Open** in **scsi_peripheral_api.h** to open the SCSI device.
+
+ ```c++
+ uint64_t deviceId = 0x100000003;
+ uint8_t interfaceIndex = 0;
+ ScsiPeripheral_Device *dev = NULL;
+ // Open the SCSI device specified by deviceId and interfaceIndex1.
+ ret = OH_ScsiPeripheral_Open(deviceId, interfaceIndex, &dev);
+ ```
+
+3. Create a buffer.
+
+ Use **OH_ScsiPeripheral_CreateDeviceMemMap** in **scsi_peripheral_api.h** to create the memory buffer **devMmap**.
+
+ ```c++
+ constexpr size_t DEVICE_MEM_MAP_SIZE = 1024;
+ ScsiPeripheral_DeviceMemMap *g_scsiDeviceMemMap = nullptr;
+ ret = OH_ScsiPeripheral_CreateDeviceMemMap(dev, DEVICE_MEM_MAP_SIZE, &g_scsiDeviceMemMap);
+ ```
+
+4. Check whether the logical units are ready.
+
+ Use **OH_ScsiPeripheral_TestUnitReady** in **scsi_peripheral_api.h** to check whether the logical unit is ready.
+
+ ```c++
+ ScsiPeripheral_TestUnitReadyRequest testUnitReadyRequest = {0};
+ testUnitReadyRequest.timeout = 5000;
+ ScsiPeripheral_Response testUnitReadyResponse = {0};
+ ret = OH_ScsiPeripheral_TestUnitReady(dev, &testUnitReadyRequest, &testUnitReadyResponse);
+ ```
+
+5. Query basic information about the SCSI device.
+
+ Use **OH_ScsiPeripheral_Inquiry** in **scsi_peripheral_api.h** to obtain the basic information about the SCSI device.
+
+ ```c++
+ ScsiPeripheral_InquiryRequest inquiryRequest = {0};
+ inquiryRequest.allocationLength = 512;
+ inquiryRequest.timeout = 5000;
+ ScsiPeripheral_InquiryInfo inquiryInfo = {0};
+ inquiryInfo.data = g_scsiDeviceMemMap;
+ ScsiPeripheral_Response inquiryResponse = {0};
+ ret = OH_ScsiPeripheral_Inquiry(dev, &inquiryRequest, &inquiryInfo, &inquiryResponse);
+ ```
+
+6. Obtain the capacity information about the SCSI device.
+
+ Use **OH_ScsiPeripheral_ReadCapacity10** in **scsi_peripheral_api.h** to obtain the SCSI device capacity information.
+
+ ```c++
+ ScsiPeripheral_ReadCapacityRequest readCapacityRequest = {0};
+ readCapacityRequest.lbAddress = 0;
+ readCapacityRequest.control = 0;
+ readCapacityRequest.byte8 = 0;
+ readCapacityRequest.timeout = 5000;
+ ScsiPeripheral_CapacityInfo capacityInfo = {0};
+ ScsiPeripheral_Response readCapacityResponse = {0};
+ ret = OH_ScsiPeripheral_ReadCapacity10(dev, &readCapacityRequest, &capacityInfo, &readCapacityResponse);
+ ```
+
+7. Obtain sense data.
+
+ Use **OH_ScsiPeripheral_RequestSense** in **scsi_peripheral_api.h** to obtain sense data.
+
+ ```c++
+ ScsiPeripheral_RequestSenseRequest senseRequest = {0};
+ senseRequest.allocationLength = SCSIPERIPHERAL_MAX_SENSE_DATA_LEN + 1;
+ senseRequest.control = 0;
+ senseRequest.byte1 = 0;
+ senseRequest.timeout = 5000;
+ ScsiPeripheral_Response senseResponse = {0};
+ // Information returned by the SCSI device to the host, used to report the device status, error information, and diagnosis information.
+ ret = OH_ScsiPeripheral_RequestSense(dev, &senseRequest, &senseResponse);
+ ```
+
+8. Parse the sense data.
+
+ Use **OH_ScsiPeripheral_ParseBasicSenseInfo** in **scsi_peripheral_api.h** to parse basic sense data, including the **Information**, **Command specific information**, and **Sense key specific** fields.
+
+ ```c++
+ ScsiPeripheral_BasicSenseInfo senseInfo = {0};
+ ret = OH_ScsiPeripheral_ParseBasicSenseInfo(senseResponse.senseData, SCSIPERIPHERAL_MAX_SENSE_DATA_LEN, &senseInfo);
+ ```
+
+9. Read data.
+
+ Use **OH_ScsiPeripheral_Read10** in **scsi_peripheral_api.h** to read data from a specified logical block.
+
+ ```c++
+ ScsiPeripheral_IORequest readRequest = {0};
+ readRequest.lbAddress = 1;
+ readRequest.transferLength = 1;
+ readRequest.control = 0;
+ readRequest.byte1 = 0;
+ readRequest.byte6 = 0;
+ readRequest.timeout = 20000;
+ readRequest.data = g_scsiDeviceMemMap;
+ ScsiPeripheral_Response readResponse = {0};
+ ret = OH_ScsiPeripheral_Read10(dev, &readRequest, &readResponse);
+ ```
+
+10. Write data.
+
+ Use **OH_ScsiPeripheral_Write10** in **scsi_peripheral_api.h** to write data to a specified logical block of the device.
+
+ ```c++
+ ScsiPeripheral_IORequest writeRequest = {0};
+ writeRequest.lbAddress = 1;
+ writeRequest.transferLength = 1;
+ writeRequest.control = 0;
+ writeRequest.byte1 = 0;
+ writeRequest.byte6 = 0;
+ writeRequest.timeout = 5000;
+ writeRequest.data = g_scsiDeviceMemMap;
+ ScsiPeripheral_Response writeResponse = {0};
+ ret = OH_ScsiPeripheral_Write10(dev, &writeRequest, &writeResponse);
+ ```
+
+11. Verifies a specified logical block.
+
+ Use **OH_ScsiPeripheral_Verify10** in **scsi_peripheral_api.h** to verify a specified logical block.
+
+ ```c++
+ ScsiPeripheral_VerifyRequest verifyRequest = {0};
+ verifyRequest.lbAddress = 1;
+ verifyRequest.verificationLength = 1;
+ verifyRequest.timeout = 5000;
+ ScsiPeripheral_Response verifyResponse = {0};
+ ret = OH_ScsiPeripheral_Verify10(dev, &verifyRequest, &verifyResponse);
+ ```
+
+12. Send SCSI commands in CDB mode.
+
+ Use **OH_SCSIPeripheral_SendRequestByCdb** in **scsi_peripheral_api.h** to send SCSI commands.
+
+ ```c++
+ ScsiPeripheral_Request sendRequest = {0};
+ uint8_t cdbData[SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN] = {0x28, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; // The cstring header file needs to be imported.
+ memcpy(sendRequest.commandDescriptorBlock, cdbData, SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN);
+ sendRequest.cdbLength = 10;
+ sendRequest.dataTransferDirection = -3;
+ sendRequest.timeout = 5000;
+ sendRequest.data = g_scsiDeviceMemMap;
+ ScsiPeripheral_Response sendResponse = {0};
+ ret = OH_ScsiPeripheral_SendRequestByCdb(dev, &sendRequest, &sendResponse);
+ ```
+
+13. Destroy the buffer.
+
+ After all requests are processed and before the program exits, use **OH_ScsiPeripheral_DestroyDeviceMemMap** in **scsi_peripheral_api.h** to destroy the buffer.
+
+ ```c++
+ ret = OH_ScsiPeripheral_DestroyDeviceMemMap(g_scsiDeviceMemMap);
+ ```
+
+14. Close the HID device.
+
+ After the buffer is destroyed, use **OH_ScsiPeripheral_Close** in **scsi_peripheral_api.h** to close the device.
+
+ ```c++
+ // Stop the SCSI device.
+ ret = OH_ScsiPeripheral_Close(&dev);
+ ```
+
+15. Release the SCSI Peripheral DDK.
+
+ After the SCSI device is closed, use **OH_ScsiPeripheral_Release** in **scsi_peripheral_api.h** to release the SCSI Peripheral DDK.
+
+ ```c++
+ // Release the SCSI Peripheral DDK.
+ ret = OH_ScsiPeripheral_Release();
+ ```
+
+### Debugging and Verification
+
+Upon completion of driver application development, you can install the application on the OpenHarmony device. The test procedure is as follows:
+
+1. Click the driver application on the device. The application is started on the device.
+2. Check whether the application can read the basic information about the SCSI device.
+3. Select a SCSI command, enter parameters, and click the **Send** button.
+4. (Optional) Set the direction, CDB data, and CDB length, and click the **Send** button to run the corresponding SCSI command.
diff --git a/en/application-dev/device/driver/terms.md b/en/application-dev/device/driver/terms.md
new file mode 100644
index 0000000000000000000000000000000000000000..bd8d10e8fc3c3a256792fa98b14fda7dcf09b5fc
--- /dev/null
+++ b/en/application-dev/device/driver/terms.md
@@ -0,0 +1,61 @@
+# Terms
+
+## A
+
+- AMS
+
+ The Ability Manager Service (AMS) is a system service used to coordinate the running relationships of abilities and schedule the lifecycle of abilities. You can use it to start and disable **DriverExtensionAbility** during driver development.
+
+## B
+
+- BMS
+
+ The Bundle Manager Service (BMS) is responsible for application installation, uninstallation, and data management on OpenHarmony.
+
+## C
+
+- CDB
+
+ A command descriptor block (CDB) is a standard data structure used to send commands in the SCSI protocol. A CDB is a byte array with a fixed length. It contains the operation code (Opcode) and related parameters of the SCSI command and is used to instruct the device to perform operations (such as read, write, and query).
+
+## D
+
+- DDK
+
+ The Driver Development Kit (DDK) is a tool package provided by OpenHarmony for developing drivers for non-standard USB serial port devices based on the peripheral framework.
+
+## H
+
+- HID device
+
+ HID is short for Human Interface Device. An HID device is used for interaction between a person and a computer or another electronic device, and is mainly used for input and output operations.
+
+- HID protocol
+
+ The HID protocol is a standard communication protocol specially designed for human-machine interaction devices. It implements efficient communication between devices and hosts through report descriptors and data reports. It boasts features like plug-and-play, low latency, low bandwidth, and high compatibility, and is widely used in various input and control devices.
+
+## L
+
+- Logical Block
+
+ A logical block is a basic data storage unit. It represents a data area of a fixed size on a device and is usually used for data read and write operations. The size of a logical block may be 512 bytes, 1024 bytes, 2048 bytes, and so on. A specific size depends on a configuration of the device and a design of the file system.
+
+## S
+
+- SCSI
+
+ SCSI is a standard protocol set used for communication between computers and peripherals such as hard disk drives, tape drives, optical disk drives, and scanners.
+
+## U
+
+- USB serial port
+
+ USB-to-Serial is an interface conversion technology that allows data communication with traditional serial ports (such as RS-232 and RS-485) over USB interfaces. This technology is usually implemented by using a dedicated hardware adapter or a specific built-in chip.
+
+## Non-standard peripherals
+
+ Non-standard peripherals (also called custom peripherals or dedicated peripherals) are peripherals that do not comply with general standards or are customized for specific application scenarios. This type of device usually requires special software support or special interfaces to implement communication with the host system.
+
+## Standard peripherals
+
+ Standard peripherals refer to peripherals (such as USB keyboards and mouse devices) that comply with industry standards and specifications. Such devices typically have uniform interface protocols, physical dimensions, and electrical characteristics, so that they can be used interchangeably between different systems.
diff --git a/en/application-dev/device/driver/usb-ddk-guidelines.md b/en/application-dev/device/driver/usb-ddk-guidelines.md
new file mode 100644
index 0000000000000000000000000000000000000000..fb73b7385451d1ad21ebac1de9ca6c7513c8611e
--- /dev/null
+++ b/en/application-dev/device/driver/usb-ddk-guidelines.md
@@ -0,0 +1,195 @@
+# USB DDK Development
+
+## Overview
+
+The USB Driver Development Kit (DDK) is a toolset that helps you develop USB device drivers at the application layer based on the user mode. It provides a series of device access APIs, for example, opening and closing USB interfaces, and performing non-isochronous transfer, isochronous transfer, control transfer, and interrupt transfer over USB pipes.
+
+The USB DDK can be used to develop device drivers for all devices that use the USB protocol to transfer data over a USB bus. For the peripherals that are not supported by standard kernel drivers, you can use the peripheral driver application developed based on the USB DDK to implement unique device capabilities.
+
+### Basic Concepts
+
+Before developing the USB DDK, you must understand the following basic concepts:
+
+- **USB**
+
+ Universal Serial Bus (USB) is a widely used interface technology that connects a computer to various external devices, such as a keyboard, mouse, printer, storage device, and smartphone. The USB is designed to provide a standardized, efficient, and easy-to-use connection mode that replaces the traditional serial and parallel interface communication.
+
+- **DDK**
+
+ DDK is a tool package provided by OpenHarmony for developing drivers for non-standard USB serial port devices based on the peripheral framework.
+
+### Implementation Principles
+
+A non-standard peripheral application obtains the USB device ID by using the peripheral management service, and delivers the ID and the action to the USB driver application through RPC. The USB driver application can obtain or set the device descriptor and initiate a control transfer or interrupt transfer request by calling the USB DDK API. Then, the DDK API uses the HDI service to deliver instructions to the kernel driver, and the kernel driver uses instructions to communicate with the device.
+
+**Figure 1** Principles of invoking the USB DDK
+
+
+
+## Constraints
+
+* The open APIs of USB DDK can be used to develop drivers of non-standard USB peripherals.
+
+* The open APIs of USB DDK can be used only within the lifecycle of **DriverExtensionAbility**.
+
+* To use the open APIs of the USB DDK, you need to declare the matching ACL permissions in **module.json5**, for example, **ohos.permission.ACCESS_DDK_USB**.
+
+## Environment Setup
+
+Before you get started, make necessary preparations by following instructions in [Environment Preparation](environmental-preparation.md).
+
+## How to Develop
+
+### Available APIs
+
+| Name| Description|
+| -------- | -------- |
+| OH_Usb_Init(void) | Initializes the USB DDK.|
+| OH_Usb_Release(void) | Releases the USB DDK.|
+| OH_Usb_GetDeviceDescriptor(uint64_t deviceId, struct UsbDeviceDescriptor *desc) | Obtains the device descriptor of a USB device.|
+| OH_Usb_GetConfigDescriptor(uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config) | Obtains a USB configuration descriptor. To avoid memory leakage, use **OH_Usb_FreeConfigDescriptor()** to release a descriptor after use.|
+| OH_Usb_FreeConfigDescriptor(const struct UsbDdkConfigDescriptor *const config) | Releases a configuration descriptor. To avoid memory leakage, release a descriptor in time after use.|
+| OH_Usb_ClaimInterface(uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle) | Declares a USB interface.|
+| OH_Usb_SelectInterfaceSetting(uint64_t interfaceHandle, uint8_t settingIndex) | Activates the alternate setting of a USB interface.|
+| OH_Usb_GetCurrentInterfaceSetting(uint64_t interfaceHandle, uint8_t \*settingIndex) | Obtains the alternate setting of a USB interface.|
+| OH_Usb_SendControlReadRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup \*setup, uint32_t timeout, uint8_t \*data, uint32_t \*dataLen) | Sends a control read transfer request. This API returns the result synchronously.|
+| OH_Usb_SendControlWriteRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup \*setup, uint32_t, const uint8_t \*data, uint32_t dataLen) | Sends a control write transfer request. This API returns the result synchronously.|
+| OH_Usb_ReleaseInterface(uint64_t interfaceHandle) | Releases a USB interface.|
+| OH_Usb_SendPipeRequest(const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap) | Sends a pipe request. This API returns the result synchronously. It applies to interrupt transfer and bulk transfer.|
+| OH_Usb_CreateDeviceMemMap(uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap) | Create a buffer. To avoid resource leakage, use **OH_Usb_DestroyDeviceMemMap()** to destroy a buffer after use.|
+| OH_Usb_DestroyDeviceMemMap(UsbDeviceMemMap *devMmap) | Destroy a buffer. To avoid resource leakage, destroy a buffer in time after use.|
+| OH_Usb_GetDevices(struct Usb_DeviceArray *devices) | Obtains the USB device ID list. Ensure that the input pointer is valid and the number of devices does not exceed 128. To prevent resource leakage, release the member memory after usage. Besides, make sure that the obtained USB device ID has been filtered by **vid** in the driver configuration information.|
+
+For details about the APIs, see [USB DDK](../../reference/apis-driverdevelopment-kit/_usb_ddk.md).
+
+### How to Develop
+
+To develop a USB driver using the USB DDK, perform the following steps:
+
+**Adding Dynamic Link Libraries**
+
+Add the following libraries to **CMakeLists.txt**.
+```txt
+libusb_ndk.z.so
+```
+
+**Including Header Files**
+```c++
+#include
+#include
+```
+
+1. Obtain the device descriptor of a USB device.
+
+ Call **OH_Usb_Init** of **usb_ddk_api.h** to initialize the USB DDK, and call **OH_Usb_GetDeviceDescriptor** to obtain the device descriptor.
+
+ ```c++
+ // Initialize the USB DDK.
+ OH_Usb_Init();
+ struct UsbDeviceDescriptor devDesc;
+ uint64_t deviceId = 0;
+ // Obtain the device descriptor.
+ OH_Usb_GetDeviceDescriptor(deviceId, &devDesc);
+ ```
+
+2. Obtain a configuration descriptor, and declare the USB interface.
+
+ Call **OH_Usb_GetConfigDescriptor** of **usb_ddk_api.h** to obtain the configuration descriptor **config**, and call **OH_Usb_ClaimInterface** to declare claiming of the USB interface.
+
+ ```c++
+ struct UsbDdkConfigDescriptor *config = nullptr;
+ // Obtain the configuration descriptor.
+ OH_Usb_GetConfigDescriptor(deviceId, 1, &config);
+ // Obtain the index of the target USB interface based on the configuration descriptor.
+ uint8_t interfaceIndex = 0;
+ // Declare the USB interface.
+ uint64_t interfaceHandle = 0;
+ OH_Usb_ClaimInterface(deviceId, interfaceIndex, &interfaceHandle);
+ // Release the configuration descriptor.
+ OH_Usb_FreeConfigDescriptor(config);
+ ```
+3. Obtain the activated alternate setting of a USB interface.
+
+ Call **OH_Usb_GetCurrentInterfaceSetting** of **usb_ddk_api.h** to obtain the alternate setting, and call **OH_Usb_SelectInterfaceSetting** to activate it.
+
+ ```c++
+ uint8_t settingIndex = 0;
+ // Obtain the alternate setting.
+ OH_Usb_GetCurrentInterfaceSetting(interfaceHandle, &settingIndex);
+
+ // Activate the alternate setting.
+ OH_Usb_SelectInterfaceSetting(interfaceHandle, &settingIndex);
+ ```
+4. Send control read requests and control write requests.
+
+ Call **OH_Usb_SendControlReadRequest** of **usb_ddk_api.h** to send a control read request, or call **OH_Usb_SendControlWriteRequest** to send a control write request.
+
+ ```c++
+ // Timeout interval. Set it to 1s.
+ uint32_t timeout = 1000;
+
+ struct UsbControlRequestSetup setupRead;
+ setupRead.bmRequestType = 0x80;
+ setupRead.bRequest = 0x08;
+ setupRead.wValue = 0;
+ setupRead.wIndex = 0;
+ setupRead.wLength = 0x01;
+ uint8_t dataRead[256] = {0};
+ uint32_t dataReadLen = 256;
+ // Send a control read request.
+ OH_Usb_SendControlReadRequest(interfaceHandle, &setupRead, timeout, dataRead, &dataReadLen);
+
+ struct UsbControlRequestSetup setupWrite;
+ setupWrite.bmRequestType = 0;
+ setupWrite.bRequest = 0x09;
+ setupWrite.wValue = 1;
+ setupWrite.wIndex = 0;
+ setupWrite.wLength = 0;
+ uint8_t dataWrite[256] = {0};
+ uint32_t dataWriteLen = 256;
+ // Send a control write request.
+ OH_Usb_SendControlWriteRequest(interfaceHandle, &setupWrite, timeout, dataWrite, &dataWriteLen);
+ ```
+
+5. Create a buffer, and send a request.
+
+ Call **OH_Usb_CreateDeviceMemMap** of **usb_ddk_api.h** to create the buffer **devMmap**, and call **OH_Usb_SendPipeRequest** to send a request.
+
+ ```c++
+ struct UsbDeviceMemMap *devMmap = nullptr;
+ // Create a buffer for storing data.
+ size_t bufferLen = 10;
+ OH_Usb_CreateDeviceMemMap(deviceId, bufferLen, &devMmap);
+ struct UsbRequestPipe pipe;
+ pipe.interfaceHandle = interfaceHandle;
+ // Obtain the target endpoint based on the configuration descriptor.
+ pipe.endpoint = 128;
+ pipe.timeout = UINT32_MAX;
+ // Send a request.
+ OH_Usb_SendPipeRequest(&pipe, devMmap);
+ ```
+
+6. Release resources.
+
+ After all requests are processed and before the application exits, call **OH_Usb_DestroyDeviceMemMap** of **usb_ddk_api.h** to destroy the buffer, call **OH_Usb_ReleaseInterface** to release the USB interface, , and call **OH_Usb_Release** to release the USB DDK.
+
+ ```c++
+ // Destroy the buffer.
+ OH_Usb_DestroyDeviceMemMap(devMmap);
+ // Release the USB interface.
+ OH_Usb_ReleaseInterface(interfaceHandle);
+ // Release the USB DDK.
+ OH_Usb_Release();
+ ```
+7. (Optional) Obtain the USB device ID list.
+
+ After the driver is started, call **OH_Usb_GetDevices** to obtain the device ID that matches the VID in the driver configuration for subsequent application development. (VID is the ID of the device vendor and is configured in the driver application to indicate the applicable devices. The queried device IDs need to be filtered by VID.)
+
+ ```c++
+ OH_Usb_Init();
+ constexpr size_t MAX_USB_DEVICE_NUM = 128;
+ struct Usb_DeviceArray deviceArray;
+ deviceArray.deviceIds = new uint64_t[MAX_USB_DEVICE_NUM];
+ // Obtain the USB device list.
+ OH_Usb_GetDevices(&deviceArray);
+ ```
diff --git a/en/application-dev/device/driver/usb-serial-ddk-guidelines.md b/en/application-dev/device/driver/usb-serial-ddk-guidelines.md
new file mode 100644
index 0000000000000000000000000000000000000000..7046e252637c96542656a8dc23c466025c271ed1
--- /dev/null
+++ b/en/application-dev/device/driver/usb-serial-ddk-guidelines.md
@@ -0,0 +1,194 @@
+# USB Serial DDK Development
+
+## Overview
+
+Non-standard serial port devices, such as temperature and humidity meters and special identity card readers, are used in industrial scenarios and on some legacy devices. If the system does not have a driver that adapts to the devices, the devices cannot be used after being connected. The USB Serial Driver Development Kit (DDK) is a toolset that helps you develop USB serial drivers at the application layer based on the user mode. The USB Serial DDK provides a series of APIs for the host to access devices, including APIs for enabling and disabling devices on the host and read/write data through serial ports. With the driver development APIs provided by OpenHarmony, third-party peripherals are able to access the ecosystem conveniently.
+
+### Basic Concepts
+
+Before developing the SCSI Peripheral DDK, you must understand the following basic concepts:
+
+- **USB serial port**
+
+ USB-to-Serial is an interface conversion technology that allows data communication with traditional serial ports (such as RS-232 and RS-485) over USB interfaces. This technology is usually implemented by using a dedicated hardware adapter or a specific built-in chip.
+
+- **AMS**
+
+ The Ability Manager Service (AMS) is a system service used to coordinate the running relationships of abilities and schedule the lifecycle of abilities. You can use it to start and disable **DriverExtensionAbility** during driver development.
+
+- **BMS**
+
+ The Bundle Manager Service (BMS) is responsible for application installation, uninstallation, and data management on OpenHarmony.
+
+- **DDK**
+
+ DDK is a tool package provided by OpenHarmony for developing drivers for non-standard USB serial port devices based on the peripheral framework.
+
+- **Non-standard peripherals**
+
+ Non-standard peripherals (also called custom peripherals or dedicated peripherals) are peripherals that do not comply with general standards or are customized for specific application scenarios. This type of device usually requires special software support or special interfaces to implement communication with the host system.
+
+- **Standard peripherals**
+
+ Standard peripherals refer to peripherals (such as USB keyboards and mouse devices) that comply with industry standards and specifications. Such devices typically have uniform interface protocols, physical dimensions, and electrical characteristics, so that they can be used interchangeably between different systems.
+
+### Implementation Principles
+
+A non-standard peripheral application obtains the USB serial port device ID by using the peripheral management service, and delivers the ID and the action to the USB serial port driver application through RPC. The USB serial port driver application can set the serial port attributes (such as the baud rate, data bit, and parity bit) and read the serial port data by calling the USB Serial DDK API. Then, the DDK API uses the HDI service to deliver instructions to the kernel driver, and the kernel driver uses instructions to communicate with the device.
+
+**Figure 1** Principles of invoking the USB Serial DDK
+
+
+
+### Constraints
+
+- The open APIs of USB Serial DDK can be used to develop drivers of non-standard USB peripherals that use USB serial ports.
+
+- The open APIs of USB Serial DDK can be used only within the **DriverExtensionAbility** lifecycle.
+
+- To use the open APIs of USB Serial DDK, you need to declare the matching ACL permissions in **module.json5**, for example, **ohos.permission.ACCESS_DDK_USB_SERIAL**.
+
+## Environment Setup
+
+Before you get started, make necessary preparations by following instructions in [Environment Preparation](environmental-preparation.md).
+
+## How to Develop
+
+### Available APIs
+
+| Name| Description|
+| -------- | -------- |
+| OH_UsbSerial_Init(void) | Initializes the USB Serial DDK.|
+| OH_UsbSerial_Release(void) | Releases the USB Serial DDK.|
+| OH_UsbSerial_Open(uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_Device **dev) | Opens the USB serial port device based on the specified **deviceId** and **interfaceIndex**. Call **OH_UsbSerial_Close ()** to close the device after use. Otherwise, memory leakage occurs.|
+| OH_UsbSerial_Close(UsbSerial_Device **dev) | Closes the USB serial port device after use. Otherwise, memory leakage occurs.|
+| OH_UsbSerial_Read(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesRead) | Reads data from the USB serial port device to the buffer.|
+| OH_UsbSerial_Write(UsbSerial_Device *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesWritten) | Writes the data in the buffer to the USB serial port device.|
+| OH_UsbSerial_SetBaudRate(UsbSerial_DeviceHandle *dev, uint32_t baudRate) | Sets the baud rate for a USB serial port device. Call this API if the data bit of the serial port is **8**, the stop bit is **1**, and parity check is not performed.|
+| OH_UsbSerial_SetParams(UsbSerial_Device *dev, UsbSerial_Params *params) | Sets the parameters of the USB serial port device, including the baud rate, data transfer bit, stop bit, and parity check.|
+| OH_UsbSerial_SetTimeout(UsbSerial_Device *dev, int timeout) | Sets the timeout interval for reading data reported by a USB serial port device. The default value is **0**.|
+| OH_UsbSerial_SetFlowControl(UsbSerial_Device *dev, UsbSerial_FlowControl flowControl) | Sets flow control parameters.|
+| OH_UsbSerial_Flush(UsbSerial_Device *dev) | Flushes the input and output buffers after the write operation is complete.|
+| OH_UsbSerial_FlushInput(UsbSerial_Device *dev) | Refreshes the input buffer. The data in the buffer is cleared immediately.|
+| OH_UsbSerial_FlushOutput(UsbSerial_Device *dev) | Refreshes the output buffer. The data in the buffer is cleared immediately.|
+
+For details about the APIs, see [USB Serial DDK](../../reference/apis-driverdevelopment-kit/_serial_ddk.md).
+
+### How to Develop
+
+To develop the USB serial port driver by using the USB Serial DDK, perform the following steps:
+
+**Adding Dynamic Link Libraries**
+
+Add the following libraries to **CMakeLists.txt**.
+```txt
+libusb_serial_ndk.z.so
+```
+
+**Including Header Files**
+```c++
+#include
+#include
+```
+
+1. Initialize the USB Serial DDK.
+
+ Use **OH_UsbSerial_Init** in **usb_serial_api.h** to initialize the USB Serial DDK.
+
+ ```c++
+ // Initialize the USB Serial DDK.
+ OH_UsbSerial_Init();
+ ```
+
+2. Open the USB serial port device.
+
+ Use **OH_UsbSerial_Open** in **usb_serial_api.h** to enable the device.
+
+ ```c++
+ UsbSerial_Device *dev = NULL;
+ uint64_t deviceId = 1688858450198529;
+ uint8_t interfaceIndex = 0;
+ // Open the USB serial port device specified by deviceId and interfaceIndex.
+ OH_UsbSerial_Open(deviceId, interfaceIndex, &dev);
+ ```
+
+3. Sets the parameters of the USB serial port device.
+
+ Use **OH_UsbSerial_SetParams** in **usb_serial_api.h** to set the serial port parameters, or directly use **OH_UsbSerial_SetBaudRate** to set the baud rate, and use **OH_UsbSerial_SetTimeout** to set the timeout interval for reading data.
+
+ ```c++
+ UsbSerial_Params params;
+ params.baudRate = 9600;
+ params.nDataBits = 8;
+ params.nStopBits = 1;
+ params.parity = 0;
+ // Set serial port parameters.
+ OH_UsbSerial_SetParams(dev, ¶ms);
+
+ // Set the baud rate.
+ uint32_t baudRate = 9600;
+ OH_UsbSerial_SetBaudRate(dev, baudRate);
+
+ // Set the timeout interval.
+ int timeout = 500;
+ OH_UsbSerial_SetTimeout(dev, timeout);
+ ```
+
+4. Set flow control and flush the buffer.
+
+ Use **OH_UsbSerial_SetFlowControl** in **usb_serial_api.h** to set the flow control mode, use **OH_UsbSerial_Flush** to flush the buffer, use **OH_UsbSerial_FlushInput** to flush the input buffer, and use **OH_UsbSerial_FlushOutput** to flush the output buffer.
+
+ ```c++
+ // Set flow control.
+ OH_UsbSerial_SetFlowControl(dev, USB_SERIAL_SOFTWARE_FLOW_CONTROL);
+
+ // Flush the buffer.
+ OH_UsbSerial_Flush(dev);
+
+ // Flush the input buffer.
+ OH_UsbSerial_FlushInput(dev);
+
+ // Flush the output buffer.
+ OH_UsbSerial_FlushOutput(dev);
+ ```
+5. Write or read data to or from a USB serial port device.
+
+ Use **OH_UsbSerial_Write** in **usb_serial_api.h** to send data to the device, and use **OH_UsbSerial_Read** to read the data sent by the device.
+
+ ```c++
+ uint32_t bytesWritten = 0;
+ // Command used by the test device to read data. The command varies depending on the device protocol.
+ uint8_t writeBuff[8] = {0x01, 0x03, 0x00, 0x00, 0x00, 0x01, 0x84, 0xA};
+ // Send data over the connection.
+ OH_UsbSerial_Write(dev, writeBuff, sizeof(writeBuff), &bytesWritten);
+
+ // Callback invoked to receive data.
+ uint8_t readBuff[100];
+ uint32_t bytesRead = 0;
+ OH_UsbSerial_Read(dev, readBuff, sizeof(readBuff), &bytesRead);
+ ```
+
+6. Close the USB serial port device.
+
+ After all requests are processed and before the program exits, use **OH_UsbSerial_Close** in **usb_serial_api.h** to close the device.
+ ```c++
+ // Close the device.
+ OH_UsbSerial_Close(&dev);
+ ```
+
+7. Release the USB Serial DDK.
+
+ After the USB serial port device is closed, use **OH_UsbSerial_Release** in **usb_serial_api.h** to release the USB Serial DDK.
+
+ ```c++
+ // Release the USB Serial DDK.
+ OH_UsbSerial_Release();
+ ```
+
+### Debugging and Verification
+
+Upon completion of driver application development, you can install the application on the OpenHarmony device. The test procedure is as follows:
+
+1. Click the driver application on the device. The application is started on the device.
+2. Click the set button to set serial port attributes such as the baud rate.
+3. Click the data read button to read the data of the serial port device.
diff --git a/en/application-dev/device/input/Readme-EN.md b/en/application-dev/device/input/Readme-EN.md
index 42388f2623b378adc5885b19435b2a9317fc44f8..9c00dae272a1e09b8d427cb17be9481950ee9a38 100644
--- a/en/application-dev/device/input/Readme-EN.md
+++ b/en/application-dev/device/input/Readme-EN.md
@@ -1,4 +1,4 @@
-# Input Kit (Multimodal Input)
+# Input Kit (Multimodal Input)
- [Introduction to Input Kit](input-overview.md)
- [Input Device Development](inputdevice-guidelines.md)
@@ -6,7 +6,6 @@
- [Input Monitor Development](inputmonitor-guidelines.md)
- [Event Injection Development](inputeventclient-guidelines.md)
- [Input Consumer Development](inputconsumer-guidelines.md)
-- [Shortcut Key Development](shortkey-guidelines.md)
+- [Shortcut Key Development](shortkey-guidelines.md)
- [Event Listening Development (C/C++)](monitor-guidelines.md)
- [Event Interception Development (C/C++)](interceptor-guidelines.md)
-
diff --git a/en/application-dev/device/input/inputconsumer-guidelines.md b/en/application-dev/device/input/inputconsumer-guidelines.md
index aaaa871f1c112ea36dce494e98e24cd69e1eb9e3..84b58e4e7e54fcb22a7e618b9b0e74646815d24c 100644
--- a/en/application-dev/device/input/inputconsumer-guidelines.md
+++ b/en/application-dev/device/input/inputconsumer-guidelines.md
@@ -26,7 +26,9 @@ The following table lists the common APIs provided by the inputConsumer module.
## How to Develop
-When an application that uses specific combination keys is started, call [on](../../reference/apis-input-kit/js-apis-inputconsumer-sys.md#inputconsumeron) to subscribe to combination key events. When the application is stopped, call [off](../../reference/apis-input-kit/js-apis-inputconsumer-sys.md#inputconsumeroff) to unsubscribe from combination key events.
+When an application that uses specific combination keys is started, [on](../../reference/apis-input-kit/js-apis-inputconsumer-sys.md#inputconsumeron) is called to subscribe to combination key events.
+
+When the application is stopped, [off](../../reference/apis-input-kit/js-apis-inputconsumer-sys.md#inputconsumeroff) is called to unsubscribe from combination key events.
```js
let leftAltKey = 2045;
diff --git a/en/application-dev/device/input/inputdevice-guidelines.md b/en/application-dev/device/input/inputdevice-guidelines.md
index 17b04f7eb35ba20932bec387e56cc70c9529e04d..60f7dc6452111f4c1df1ceb2d7efd124e0ef1615 100644
--- a/en/application-dev/device/input/inputdevice-guidelines.md
+++ b/en/application-dev/device/input/inputdevice-guidelines.md
@@ -25,7 +25,7 @@ The following table lists the common APIs for input device management. For detai
When a user enters text, the input method determines whether to launch the virtual keyboard based on whether a physical keyboard is currently inserted. Your application can determine whether a physical keyboard is inserted by listening to device hot swap events.
-### How to Develop
+## How to Develop
1. Call the [getDeviceList](../../reference/apis-input-kit/js-apis-inputdevice.md#inputdevicegetdevicelist9) API to obtain the list of connected input devices. Call the [getKeyboardType](../../reference/apis-input-kit/js-apis-inputdevice.md#inputdevicegetkeyboardtype9) API to traverse all connected devices to check whether a physical keyboard exists. If a physical keyboard exists, mark the physical keyboard as connected. This step ensures that your application detects all inserted input devices before listening for device hot swap events.
2. Call the [on](../../reference/apis-input-kit/js-apis-inputdevice.md#inputdeviceon9) API to listen for device hot swap events. If a physical keyboard is inserted, mark the physical keyboard as connected. If a physical keyboard is removed, mark the physical keyboard as disconnected.
diff --git a/en/application-dev/device/location/Readme-EN.md b/en/application-dev/device/location/Readme-EN.md
index ecc5b857748c228cc7f753c2130fa174cc7e72cf..22d812dcac046dddb37a13646f5155fea9c23260 100644
--- a/en/application-dev/device/location/Readme-EN.md
+++ b/en/application-dev/device/location/Readme-EN.md
@@ -1,8 +1,10 @@
# Location Kit
- [Introduction to Location Kit](location-kit-intro.md)
-- [Applying for Location Permissions](location-permission-guidelines.md)
-- [Obtaining Device Location Information](location-guidelines.md)
-- [Geocoding and Reverse Geocoding](geocode-guidelines.md)
-- [Geofencing](geofence-guidelines.md)
-- [Samples](app-samples.md)
\ No newline at end of file
+- [Applying for Location Permissions (ArkTS)](location-permission-guidelines.md)
+- [Obtaining Device Location Information (C/C++)](location-guidelines-capi.md)
+- [Obtaining Device Location Information (ArkTS)](location-guidelines.md)
+- [Geocoding and Reverse Geocoding (ArkTS)](geocode-guidelines.md)
+- [Geofencing (ArkTS)](geofence-guidelines.md)
+- [FenceExtensionAbility](fenceExtensionAbility.md)
+- [Samples](app-samples.md)
diff --git a/en/application-dev/device/location/app-samples.md b/en/application-dev/device/location/app-samples.md
index 4b1267ac1937e359f89bd45c772c704f489ef17a..1b9fec311bd9d00256143df7a20811055af12054 100644
--- a/en/application-dev/device/location/app-samples.md
+++ b/en/application-dev/device/location/app-samples.md
@@ -2,4 +2,4 @@
The following sample is provided to help you better understand how to develop location services:
-- [Location (ArkTS)](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DeviceManagement/Location)
+- [Location (ArkTS)] (https://gitee.com/harmonyos_samples/location-service)
diff --git a/en/application-dev/application-models/fenceExtensionAbility.md b/en/application-dev/device/location/fenceExtensionAbility.md
similarity index 30%
rename from en/application-dev/application-models/fenceExtensionAbility.md
rename to en/application-dev/device/location/fenceExtensionAbility.md
index 38cb9870153de8486fbf27d092b6f8fd3457efcb..2ddbfac77ba8abc70f0d2a6612b3b439b1ed6490 100644
--- a/en/application-dev/application-models/fenceExtensionAbility.md
+++ b/en/application-dev/device/location/fenceExtensionAbility.md
@@ -1,16 +1,16 @@
# FenceExtensionAbility
## Overview
-[FenceExtensionAbility](../reference/apis-location-kit/js-apis-app-ability-FenceExtensionAbility.md) is an ExtensionAbility of the geofence type. It enables you to efficiently implement geofencing functionalities.
+[FenceExtensionAbility](../../reference/apis-location-kit/js-apis-app-ability-FenceExtensionAbility.md) is an ExtensionAbility of the geofence type. It enables you to efficiently implement geofencing functionalities.
-## How to Use
+## When to Use
-1. Subscribe to geofence status change events through the [geoLocationManager.on('gnssFenceStatusChange')](../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagerongnssfencestatuschange) API of the location service, and pass the FenceExtensionAbility parameters in the **want** parameter.
+1. Subscribe to geofence status change events through the [geoLocationManager.on('gnssFenceStatusChange')](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagerongnssfencestatuschange) API of the location service, and pass the FenceExtensionAbility parameters in the **want** parameter.
2. After the event is triggered, the system reports the geofence event and data through the **onFenceStatusChange** API. Based on the event received, the application can perform corresponding service processing, for example, sending notifications.
## Available APIs
-For details about the APIs, see [FenceExtensionAbility](../reference/apis-location-kit/js-apis-app-ability-FenceExtensionAbility.md).
-| API| Description|
+For details about the APIs, see [FenceExtensionAbility](../../reference/apis-location-kit/js-apis-app-ability-FenceExtensionAbility.md).
+| Available APIs| Description|
| ---- | ---- |
| onFenceStatusChange(transition: geoLocationManager.GeofenceTransition, additions: Record<string, string>): void | Callback invoked when a geofence status change event is received. Service processing is then performed based on the event type and data.|
| onDestroy(): void | Callback invoked when a FenceExtensionAbility destruction event is received.|
@@ -19,7 +19,7 @@ For details about the APIs, see [FenceExtensionAbility](../reference/apis-locati
### Implementing a FenceExtensionAbility
-Implement the capability of the [FenceExtensionAbility](../reference/apis-location-kit/js-apis-app-ability-FenceExtensionAbility.md) provider.
+Implement the capability of the [FenceExtensionAbility](../../reference/apis-location-kit/js-apis-app-ability-FenceExtensionAbility.md) provider.
To manually create a FenceExtensionAbility in a project in DevEco Studio, perform the following steps:
@@ -27,73 +27,67 @@ To manually create a FenceExtensionAbility in a project in DevEco Studio, perfor
2. Right-click the **fenceextensionability** directory, and choose **New > File** to create a file named **MyFenceExtensionAbility.ets**.
3. Open the **MyFenceExtensionAbility.ets** file and import its dependencies. Customize a class that inherits from **FenceExtensionAbility** and implement the **onFenceStatusChange** and **onDestroy** APIs.
- The code snippet is as follows:
+The sample code is as follows:
- ```ts
- import { notificationManager } from '@kit.NotificationKit';
- import { wantAgent } from '@kit.AbilityKit';
- import { FenceExtensionAbility, geoLocationManager } from '@kit.LocationKit';
-
- export default class MyFenceExtensionAbility extends FenceExtensionAbility {
- async onFenceStatusChange(transition: geoLocationManager.GeofenceTransition,
- additions: Record): Promise {
- // Receive the geofence status change event and process the service logic.
- console.log(`on geofence transition,id:${transition.geofenceId},event:${transition.transitionEvent},additions:${JSON.stringify(additions)}`);
-
- // Send a geofence notification.
- let wantAgentInfo: wantAgent.WantAgentInfo = {
- wants: [
- {
- bundleName: 'com.example.myapplication',
- abilityName: 'EntryAbility',
- parameters:
- {
- "geofenceId": transition?.geofenceId,
- "transitionEvent": transition?.transitionEvent,
- }
- } as Want
- ],
- actionType: wantAgent.OperationType.START_ABILITY,
- requestCode: 100
- };
- let wantAgentMy = await wantAgent.getWantAgent(wantAgentInfo);
- let notificationRequest: notificationManager.NotificationRequest = {
- id: 1,
- content: {
- notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
- normal: {
- title: `Geofence Notification`,
- text: `on geofence transition,id:${transition.geofenceId},event:${transition.transitionEvent},additions:${JSON.stringify(additions)}`,
- }
- },
- notificationSlotType: notificationManager.SlotType.SOCIAL_COMMUNICATION,
- wantAgent: wantAgentMy
- };
- notificationManager.publish(notificationRequest);
- }
-
- onDestroy(): void {
- // Process the FenceExtensionAbility destruction event.
- console.log(`on ability destroy`);
- }
- }
- export default MyFenceExtensionAbility;
- ```
+```ts
+import { FenceExtensionAbility, geoLocationManager } from '@kit.LocationKit';
+import { notificationManager } from '@kit.NotificationKit';
+import { Want, wantAgent } from '@kit.AbilityKit';
-4. Register the FenceExtensionAbility in the [module.json5 file](../quick-start/module-configuration-file.md) of the module in the project. Set **type** to **"fence"** and **srcEntry** to the code path of the FenceExtensionAbility component.
+export class MyFenceExtensionAbility extends FenceExtensionAbility {
+ onFenceStatusChange(transition: geoLocationManager.GeofenceTransition, additions: Record): void {
+ // Receive the geofence status change event and process the service logic.
+ console.info(`on geofence transition,id:${transition.geofenceId},event:${transition.transitionEvent},additions:${JSON.stringify(additions)}`);
- ```json
- {
- "module": {
- "extensionAbilities": [
+ // Send a geofence notification.
+ let wantAgentInfo: wantAgent.WantAgentInfo = {
+ wants: [
+ {
+ bundleName: 'com.example.myapplication',
+ abilityName: 'EntryAbility',
+ parameters:
{
- "name": "MyFenceExtensionAbility",
- "srcEntry": "./ets/fenceExtensionability/MyFenceExtensionAbility.ets",
- "description": "MyFenceExtensionAbility",
- "type": "fence",
- "exported": true
- },
- ]
- }
- }
- ```
\ No newline at end of file
+ "geofenceId": transition?.geofenceId,
+ "transitionEvent": transition?.transitionEvent,
+ }
+ } as Want
+ ],
+ actionType: wantAgent.OperationType.START_ABILITY,
+ requestCode: 100
+ };
+ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentMy) => {
+ let notificationRequest: notificationManager.NotificationRequest = {
+ id: 1,
+ content: {
+ notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
+ normal: {
+ title: `Geofence Notification`,
+ text: `on geofence transition,id:${transition.geofenceId},event:${transition.transitionEvent},additions:${JSON.stringify(additions)}`,
+ }
+ },
+ notificationSlotType: notificationManager.SlotType.SOCIAL_COMMUNICATION,
+ wantAgent: wantAgentMy
+ };
+ notificationManager.publish(notificationRequest);
+ });
+ }
+}
+```
+
+4. Register the FenceExtensionAbility in the [module.json5 file](../../quick-start/module-configuration-file.md) of the module in the project. Set **type** to **"fence"** and **srcEntry** to the code path of the FenceExtensionAbility component.
+
+```json
+{
+ "module": {
+ "extensionAbilities": [
+ {
+ "name": "MyFenceExtensionAbility",
+ "srcEntry": "./ets/fenceExtensionability/MyFenceExtensionAbility.ets",
+ "description": "MyFenceExtensionAbility",
+ "type": "fence",
+ "exported": true
+ },
+ ]
+ }
+}
+```
diff --git a/en/application-dev/device/location/figures/001.png b/en/application-dev/device/location/figures/001.png
new file mode 100644
index 0000000000000000000000000000000000000000..71722d671b3bb5cee09c698e904b0a59fbe77765
Binary files /dev/null and b/en/application-dev/device/location/figures/001.png differ
diff --git a/en/application-dev/device/location/geocode-guidelines.md b/en/application-dev/device/location/geocode-guidelines.md
index 092ddc6cdce62006107a87b8e4b1d42c8494b604..f041325197d7f15ead4ea441f6283dd4cb2fe81d 100644
--- a/en/application-dev/device/location/geocode-guidelines.md
+++ b/en/application-dev/device/location/geocode-guidelines.md
@@ -1,4 +1,4 @@
-# Geocoding and Reverse Geocoding
+# Geocoding and Reverse Geocoding (ArkTS)
## Scenario
@@ -14,8 +14,6 @@ The geocoding information describes a location using several attributes, includi
The following table lists the APIs used for mutual conversion between coordinates and geographic descriptions. For details, see [Location Kit](../../reference/apis-location-kit/js-apis-geoLocationManager.md).
-**Table 3** Geocoding and reverse geocoding APIs
-
| API| Description|
| -------- | -------- |
| [isGeocoderAvailable(): boolean;](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagerisgeocoderavailable) | Checks whether the geocoding and reverse geocoding services are available.|
@@ -53,9 +51,9 @@ The following table lists the APIs used for mutual conversion between coordinate
try {
geoLocationManager.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => {
if (err) {
- console.log('getAddressesFromLocation err: ' + JSON.stringify(err));
+ console.error('getAddressesFromLocation err: ' + JSON.stringify(err));
} else {
- console.log('getAddressesFromLocation data: ' + JSON.stringify(data));
+ console.info('getAddressesFromLocation data: ' + JSON.stringify(data));
}
});
} catch (err) {
@@ -70,9 +68,9 @@ The following table lists the APIs used for mutual conversion between coordinate
try {
geoLocationManager.getAddressesFromLocationName(geocodeRequest, (err, data) => {
if (err) {
- console.log('getAddressesFromLocationName err: ' + JSON.stringify(err));
+ console.error('getAddressesFromLocationName err: ' + JSON.stringify(err));
} else {
- console.log('getAddressesFromLocationName data: ' + JSON.stringify(data));
+ console.info('getAddressesFromLocationName data: ' + JSON.stringify(data));
}
});
} catch (err) {
diff --git a/en/application-dev/device/location/geofence-guidelines.md b/en/application-dev/device/location/geofence-guidelines.md
index 0af05095f9b5ee10a26d9a99c444aab0701c2536..fd58a730b79706263c0431230fa7b8f5138d403c 100644
--- a/en/application-dev/device/location/geofence-guidelines.md
+++ b/en/application-dev/device/location/geofence-guidelines.md
@@ -1,4 +1,4 @@
-# Geofencing
+# Geofencing (ArkTS)
## Scenario
@@ -12,8 +12,6 @@ A typical application of geofencing is to create a geofence around an enterprise
Geo-fencing uses the following interfaces. For details, see [Location Kit](../../reference/apis-location-kit/js-apis-geoLocationManager.md).
-**Table 4** Geofencing APIs
-
| API| Description|
| -------- | -------- |
| [on(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): void;](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagerongnssfencestatuschange) | Registers a listener for status change events of the specified geofence.|
@@ -24,73 +22,111 @@ Geo-fencing uses the following interfaces. For details, see [Location Kit](../..
1. Declare the **ohos.permission.APPROXIMATELY_LOCATION** permission. For details, see [Applying for Location Permissions](#location-permission-guidelines.md).
2. Import the **geoLocationManager**, **wantAgent**, and **BusinessError** modules.
-
+
```ts
import { geoLocationManager } from '@kit.LocationKit';
- import { wantAgent } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit'
+ import { BusinessError } from '@kit.BasicServicesKit';
+ import { notificationManager } from '@kit.NotificationKit';
```
-3. Create a **WantAgentInfo** object.
-
- Scenario 1: Create a **WantAgentInfo** object for starting an ability.
+3. Create a geofence.
```ts
// Set the action type through operationType of WantAgentInfo.
- let wantAgentInfo:wantAgent.WantAgentInfo = {
- wants: [
- {
- deviceId: '',
- bundleName: 'com.example.myapplication',
- abilityName: 'EntryAbility',
- action: '',
- entities: [],
- uri: '',
- parameters: {}
- }
- ],
- operationType: wantAgent.OperationType.START_ABILITY,
- requestCode: 0,
- wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
- };
+ let geofence: geoLocationManager.Geofence = {
+ "latitude": 34.12, "longitude": 124.11, "radius": 10000.0, "expiration": 10000.0
+ }
```
- Scenario 2: Create a **WantAgentInfo** object for releasing a public event.
+4. Specify the types of geofence transition events to listen for. Geofence entry and exit events are used as an example.
```ts
- // Set the action type through operationType of WantAgentInfo.
- let wantAgentInfo:wantAgent.WantAgentInfo = {
- wants: [
- {
- action: 'event_name', // Set the action name.
- parameters: {},
- }
- ],
- operationType: wantAgent.OperationType.SEND_COMMON_EVENT,
- requestCode: 0,
- wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG],
- }
+ let transitionStatusList: Array = [
+ geoLocationManager.GeofenceTransitionEvent.GEOFENCE_TRANSITION_EVENT_ENTER,
+ geoLocationManager.GeofenceTransitionEvent.GEOFENCE_TRANSITION_EVENT_EXIT,
+ ];
```
-4. Call **getWantAgent()** to create a **WantAgent** object.
+4. Create a notification object for **GEOFENCE_TRANSITION_EVENT_ENTER** and **GEOFENCE_TRANSITION_EVENT_EXIT**.
- Call the geofencing API to add a geofence after obtaining the **WantAgent** object, and have the system automatically trigger the action defined for the **WantAgent** object when a device enters or exits the geofence.
+ ```ts
+ // GEOFENCE_TRANSITION_EVENT_ENTER event
+ let notificationRequest1: notificationManager.NotificationRequest = {
+ id: 1,
+ content: {
+ notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
+ normal: {
+ title: "Geofence Notification",
+ text: "Geofence Entry",
+ additionalText: ""
+ }
+ }
+ };
+ // Create a notification object for GEOFENCE_TRANSITION_EVENT_EXIT.
+ let notificationRequest2: notificationManager.NotificationRequest = {
+ id: 2,
+ content: {
+ notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
+ normal: {
+ title: "Geofence Notification",
+ text: 'Geofence Exit',
+ additionalText: ""
+ }
+ }
+ };
+ ```
+
+5. Add a geofence.
```ts
- let wantAgentObj : object | undefined = undefined;
- // Create a WantAgent object.
- wantAgent.getWantAgent(wantAgentInfo, (err, data) => {
+ // Save the created notification objects to Array in the same sequence as in transitionStatusList.
+ let notificationRequestList: Array =
+ [notificationRequest1, notificationRequest2];
+ // Construct a gnssGeofenceRequest object.
+ let gnssGeofenceRequest: geoLocationManager.GnssGeofenceRequest = {
+ // Geofence attributes, including the circle center and radius.
+ geofence: geofence,
+ // Specify the types of geofence transition events to listen for.
+ monitorTransitionEvents: transitionStatusList,
+ // Specify the notification objects for geofence transition events. This parameter is optional.
+ notifications: notificationRequestList,
+ // Specify the callback used to receive geofence transition events.
+ geofenceTransitionCallback: (err : BusinessError, transition : geoLocationManager.GeofenceTransition) => {
if (err) {
- console.error('getWantAgent err=' + JSON.stringify(err));
- return;
- }
- console.info('getWantAgent success');
- wantAgentObj = data;
- let requestInfo:geoLocationManager.GeofenceRequest = {'scenario': 0x301, "geofence": {"latitude": 31.12, "longitude": 121.11, "radius": 100, "expiration": 10000}};
- try {
- geoLocationManager.on('gnssFenceStatusChange', requestInfo, wantAgentObj);
- } catch (err) {
- console.error("errCode:" + JSON.stringify(err));
+ console.error('geofenceTransitionCallback: err=' + JSON.stringify(err));
}
- });
+ if (transition) {
+ console.info("GeofenceTransition: %{public}s", JSON.stringify(transition));
+ }
+ }
+ }
+ try {
+ // Add a geofence.
+ geoLocationManager.addGnssGeofence(gnssGeofenceRequest).then((id) => {
+ // Obtain the geofence ID after the geofence is successfully added.
+ console.info("addGnssGeofence success, fence id: " + id);
+ let fenceId = id;
+ }).catch((err: BusinessError) => {
+ console.error("addGnssGeofence failed, promise errCode:" + (err as BusinessError).code +
+ ",errMessage:" + (err as BusinessError).message);
+ });
+ } catch(error) {
+ console.error("addGnssGeofence failed, err:" + JSON.stringify(error));
+ }
+ ```
+
+5. Delete a geofence.
+
+ ```ts
+ // fenceId is obtained after geoLocationManager.addGnssGeofence is successfully executed.
+ let fenceId = 1;
+ try {
+ geoLocationManager.removeGnssGeofence(fenceId).then(() => {
+ console.info("removeGnssGeofence success fenceId:" + fenceId);
+ }).catch((error : BusinessError) => {
+ console.error("removeGnssGeofence: error=" + JSON.stringify(error));
+ });
+ } catch(error) {
+ console.error("removeGnssGeofence: error=" + JSON.stringify(error));
+ }
```
diff --git a/en/application-dev/device/location/location-guidelines-capi.md b/en/application-dev/device/location/location-guidelines-capi.md
new file mode 100644
index 0000000000000000000000000000000000000000..d45d035fa3c691704639fe25bbd05c331371526a
--- /dev/null
+++ b/en/application-dev/device/location/location-guidelines-capi.md
@@ -0,0 +1,154 @@
+# Obtaining Device Location Information (C/C++)
+
+
+## When to Use
+
+You can call location-related APIs to listen for device location changes.
+
+## Function Description
+
+| Name | Description |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| OH_Location_IsLocatingEnabled(bool* enabled) | Checks whether the location switch is enabled. |
+| OH_Location_StartLocating(const Location_RequestConfig* requestConfig) | Starts locating and subscribes to location changes.|
+| Location_ResultCode OH_Location_StopLocating(const Location_RequestConfig* requestConfig) | Stops locating and unsubscribes from location changes.|
+| OH_LocationInfo_GetBasicInfo(Location_Info* location) | Obtains basic information from the location result, such as the longitude, latitude, altitude, and speed.|
+| OH_LocationInfo_GetAdditionalInfo(Location_Info* location, char* additionalInfo, uint32_t length) | Obtains additional information from the location result. The additional information is a string in JSON format.|
+| OH_Location_CreateRequestConfig(void) | Creates a **Location_RequestConfig** instance. |
+| OH_Location_DestroyRequestConfig(Location_RequestConfig* requestConfig) | Destroys the **Location_RequestConfig** instance and reclaims the memory. |
+| OH_LocationRequestConfig_SetUseScene(Location_RequestConfig* requestConfig, Location_UseScene useScene) | Sets the user activity scenario in a location request.
If **useScene** is set, **powerConsumptionScene** is invalid.
Otherwise, **powerConsumptionScene** takes effect.
If neither of the two parameters is set, **useScene** is defaulted to **LOCATION_USE_SCENE_DAILY_LIFE_SERVICE**, and **powerConsumptionCenario** is invalid. |
+| OH_LocationRequestConfig_SetPowerConsumptionScene(Location_RequestConfig* requestConfig, Location_PowerConsumptionScene powerConsumptionScene) | Sets the power consumption scenario in a location request. |
+| OH_LocationRequestConfig_SetInterval(Location_RequestConfig* requestConfig, int interval) | Sets the interval for reporting location results. |
+| OH_LocationRequestConfig_SetCallback(Location_RequestConfig* requestConfig, Location_InfoCallback callback, void* userData) | Sets the callback for receiving reported location information. |
+
+
+## How to Develop
+1. Create a native C++ project.
+ 
+
+2. Before using system basic location capabilities, check whether your application has been granted the permission to access the device location information. If not, your application first needs to apply for the required permission. For details, see [Applying for Location Permissions](location-permission-guidelines.md).
+
+
+3. Add the dynamic dependency libraries into the **CMakeLists.txt** file.
+
+ ```c
+ target_link_libraries(entry PUBLIC libace_napi.z.so)
+ target_link_libraries(entry PUBLIC libhilog_ndk.z.so)
+ target_link_libraries(entry PUBLIC liblocation_ndk.so)
+ ```
+
+4. Write the **napi_init.cpp** file to import related modules.
+
+ ```c
+ #include "napi/native_api.h"
+ #include "LocationKit/oh_location.h"
+ #include "LocationKit/oh_location_type.h"
+ #include "hilog/log.h"
+ #include
+ ```
+
+5. Call **isLocationEnabled** to check whether the location switch is enabled.
+ The return result is a Boolean value. The value **true** indicates that the location switch is enabled, and the value **false** indicates the opposite.
+
+ ```c
+ static napi_value OhLocationIsEnabled(napi_env env, napi_callback_info info)
+ {
+ bool isEnabled = false;
+ int resultCode = OH_Location_IsLocatingEnabled(&isEnabled);
+ napi_value result = NULL;
+ napi_get_boolean(env, isEnabled, &result);
+ return result;
+ }
+ // Add related APIs to the Init function.
+ EXTERN_C_START
+ static napi_value Init(napi_env env, napi_value exports)
+ {
+ napi_property_descriptor desc[] = {
+ {"ohLocationIsEnabled", NULL, OhLocationIsEnabled, NULL, NULL, NULL, napi_default, NULL},
+ };
+ napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+ return exports;
+ }
+ EXTERN_C_END
+ ```
+
+6. Start positioning and subscribe to location changes.
+
+ ```c
+ // Define a location request.
+ struct Location_RequestConfig *g_requestConfig = NULL;
+ void *mydata = NULL;
+
+ // Define a callback to receive location information.
+ void reportLocation(Location_Info* location, void* userData)
+ {
+ Location_BasicInfo baseInfo = OH_LocationInfo_GetBasicInfo(location);
+ char additionalInfo[1024] = "";
+ Location_ResultCode result = OH_LocationInfo_GetAdditionalInfo(location, additionalInfo, sizeof(additionalInfo));
+ if (mydata == userdata) {
+ OH_LOG_INFO(LOG_APP, "userData is mydata");
+ }
+ return;
+ }
+
+ // Subscribe to location information.
+ static napi_value OhLocationStartLocating(napi_env env, napi_callback_info info)
+ {
+ if (g_requestConfig == NULL) {
+ g_requestConfig = OH_Location_CreateRequestConfig();
+ }
+ OH_LocationRequestConfig_SetUseScene(g_requestConfig, LOCATION_USE_SCENE_NAVIGATION);
+ OH_LocationRequestConfig_SetInterval(g_requestConfig, 1);
+ mydata = (void *) malloc (sizeof ("mydata")); // Custom data, which is transparently returned through callback.
+ OH_LocationRequestConfig_SetCallback(g_requestConfig, reportLocation, mydata);
+ OH_Location_StartLocating(g_requestConfig);
+ int32_t ret = 0;
+ napi_value result = NULL;
+ napi_create_int32(env, ret, &result);
+ return result;
+ }
+
+ // Unsubscribe from location information. The value of g_requestConfig must be the same as the object passed during subscription.
+ static napi_value OhLocationStopLocating(napi_env env, napi_callback_info info)
+ {
+ OH_Location_StopLocating(g_requestConfig);
+ if (g_requestConfig != NULL) {
+ OH_Location_DestroyRequestConfig(g_requestConfig);
+ g_requestConfig = NULL;
+ }
+ free(mydata);
+ mydata = NULL;
+ int32_t ret = 0;
+ napi_value result = NULL;
+ napi_create_int32(env, ret, &result);
+ return result;
+ }
+
+ // Add related APIs to the Init function.
+ EXTERN_C_START
+ static napi_value Init(napi_env env, napi_value exports)
+ {
+ napi_property_descriptor desc[] = {
+ {"ohLocationStartLocating", NULL, OhLocationStartLocating, NULL, NULL, NULL, napi_default, NULL},
+ {"ohLocationStopLocating", NULL, OhLocationStopLocating, NULL, NULL, NULL, napi_default, NULL},
+ };
+ napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+ return exports;
+ }
+ EXTERN_C_END
+ ```
+
+6. Introduce the NAPI APIs to the **index.d.ts** file in **types/libentry**.
+ ```c
+ export const ohLocationIsEnabled: () => boolean;
+ export const ohLocationStartLocating: () => number;
+ export const ohLocationStopLocating: () => number;
+ ```
+
+7. Delete deprecated functions from the **Index.ets** file.
+
+ ```js
+ .onClick(() => {
+ hilog.info(0x0000, 'testTag', 'Test NAPI 2 + 3 = %{public}d', testNapi.add(2, 3));
+ })
+ ```
diff --git a/en/application-dev/device/location/location-guidelines.md b/en/application-dev/device/location/location-guidelines.md
index 7e2274feb9024fad06fbea47c920baf11af1bfc7..afdd6c1200724b302fc2933688e535d604226356 100644
--- a/en/application-dev/device/location/location-guidelines.md
+++ b/en/application-dev/device/location/location-guidelines.md
@@ -1,4 +1,4 @@
-# Obtaining Device Location Information
+# Obtaining Device Location Information (ArkTS)
## When to Use
@@ -12,8 +12,6 @@ The following table lists the APIs used to obtain the device location informatio
This module supports only the WGS-84 coordinate system.
-**Table 2** APIs for obtaining device location information
-
| API| Description|
| -------- | -------- |
| [on(type: 'locationChange', request: LocationRequest | ContinuousLocationRequest, callback: Callback<Location>): void](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanageronlocationchange) | Registers a listener for location changes with a location request initiated.|
@@ -81,7 +79,7 @@ This module supports only the WGS-84 coordinate system.
}
try {
geoLocationManager.getCurrentLocation(request).then((result) => { // Call getCurrentLocation to obtain the current device location by using a promise.
- console.log('current location: ' + JSON.stringify(result));
+ console.info('current location: ' + JSON.stringify(result));
})
.catch((error:BusinessError) => { // Receive the reported error code.
console.error('promise, getCurrentLocation: error=' + JSON.stringify(error));
@@ -110,7 +108,7 @@ This module supports only the WGS-84 coordinate system.
'locationScenario': geoLocationManager.UserActivityScenario.NAVIGATION
}
let locationCallback = (location:geoLocationManager.Location):void => {
- console.log('locationCallback: data: ' + JSON.stringify(location));
+ console.info('locationCallback: data: ' + JSON.stringify(location));
};
try {
geoLocationManager.on('locationChange', request, locationCallback);
@@ -120,5 +118,6 @@ This module supports only the WGS-84 coordinate system.
```
If your application no longer needs the device location, stop obtaining the device location to avoid high power consumption.
```ts
+ // The callback must be the same as that passed by the **on** API.
geoLocationManager.off('locationChange', locationCallback);
```
diff --git a/en/application-dev/device/location/location-permission-guidelines.md b/en/application-dev/device/location/location-permission-guidelines.md
index bb125c16f728f05fcbdb02a85abc33e69801333f..99bb145bc29975e76bd8a6f5a9bde5216cf4e162 100644
--- a/en/application-dev/device/location/location-permission-guidelines.md
+++ b/en/application-dev/device/location/location-permission-guidelines.md
@@ -1,4 +1,4 @@
-# Applying for Location Permissions
+# Applying for Location Permissions (ArkTS)
## Scenario
@@ -20,8 +20,6 @@ For details about the permissions required for each API of Location Kit, see [Lo
2. If your application needs to access the device location when running in the foreground, declare the location permission as described in the following table.
-**Table 1** Description of location permissions
-
| Permission| Declarable or Not| Location Accuracy|
| -------- | -------- | -------- |
| ohos.permission.APPROXIMATELY_LOCATION| Yes| Location accurate to 5 kilometers.|
diff --git a/en/application-dev/device/sensor/sensor-overview.md b/en/application-dev/device/sensor/sensor-overview.md
index df3402eb42fddd0ffd32f7f215bb9fd705dce85e..daa978986d742dad5cc1db332325ac2f44d2460a 100644
--- a/en/application-dev/device/sensor/sensor-overview.md
+++ b/en/application-dev/device/sensor/sensor-overview.md
@@ -1,4 +1,4 @@
-# Introduction to Sensor Service Kit
+# Sensor Overview
## Sensor Types
diff --git a/en/application-dev/device/sensor/vibrator-guidelines.md b/en/application-dev/device/sensor/vibrator-guidelines.md
index 5a010faea53a2dd15ec726cdbaf5d03e1b417683..bb46a551395e3fc0e0638348a34171ef25b83182 100644
--- a/en/application-dev/device/sensor/vibrator-guidelines.md
+++ b/en/application-dev/device/sensor/vibrator-guidelines.md
@@ -97,7 +97,7 @@ The custom vibration configuration file is in JSON format. An example file is as
}
```
-This JSON file contains two attributes: **MetaData** and **Channels**.
+This JSON file contains three attributes: **MetaData**, **Channels**, and **Parameters**.
1. **MetaData** contains information about the file header. You can add the following attributes under **MetaData**.
| Name | Mandatory| Description |
diff --git a/en/application-dev/device/stationary/Readme-EN.md b/en/application-dev/device/stationary/Readme-EN.md
index f896237291f3af1bf677a758bfdd57b65696e89f..6282f30bfb2e1cdb7730853bae338748ae08038c 100644
--- a/en/application-dev/device/stationary/Readme-EN.md
+++ b/en/application-dev/device/stationary/Readme-EN.md
@@ -1,4 +1,5 @@
# Multimodal Awareness Kit
- [Introduction to Multimodal Awareness Kit](multimodalawareness-kit-intro.md)
-- [Stationary Development](stationary-guidelines.md)
\ No newline at end of file
+- [Stationary Development](stationary-guidelines.md)
+- [Motion Sensing Development](motion-guidelines.md)
\ No newline at end of file
diff --git a/en/application-dev/device/stationary/motion-guidelines.md b/en/application-dev/device/stationary/motion-guidelines.md
new file mode 100644
index 0000000000000000000000000000000000000000..1f9b4fc69f087a84267452d1e85f6017b3847717
--- /dev/null
+++ b/en/application-dev/device/stationary/motion-guidelines.md
@@ -0,0 +1,54 @@
+# Motion Sensing Development
+
+## When to Use
+
+An application can call the motion module to identify user actions, for example, whether the user is operating the device screen with the left hand or the right hand.
+
+For details about the APIs, see [Motion API Reference](../../reference/apis-multimodalawareness-kit/js-apis-awareness-motion.md).
+
+## Available APIs
+
+| API | Description |
+| ------------------------------------------------------------ | -------------------------------------- |
+| on(type:'operatingHandChanged',callback:Callback<OperatingHandStatus>):void; | Subscribes to operating hand change events. This API uses an asynchronous callback to return the result.|
+| off(type: 'operatingHandChanged', callback?: Callback<OperatingHandStatus>): void; | Unsubscribes from operating hand change events. |
+| getRecentOperatingHandStatus(): OperatingHandStatus; | Obtains the latest operating hand status. |
+
+## Constraints
+
+The device has a touchscreen and supports specific chips.
+
+
+
+## How to Develop
+
+```ts
+import { motion } from '@kit.MultimodalAwarenessKit';
+```
+
+1. Subscribe to operating hand change events.
+
+ ```
+ motion.on('operatingHandChanged', (data:motion.OperatingHandStatus) => {
+ console.info('on success' + data);
+ })
+
+ ```
+
+2. Unsubscribe from operating hand change events.
+
+ ```
+ motion.off('operatingHandChanged', (data:motion.OperatingHandStatus) => {
+ console.info('off success' + data);
+ })
+
+ ```
+
+3. Obtain the latest operating hand status.
+
+ ```
+ let data:motion.OperatingHandStatus = motion.getRecentOperatingHandStatus();
+ console.info('get success' + data);
+ ```
+
+
diff --git a/en/application-dev/device/stationary/multimodalawareness-kit-intro.md b/en/application-dev/device/stationary/multimodalawareness-kit-intro.md
index e13522cf83444aa640d01e5a723cdd1936002e99..dae09e456e928588931dbc0c7f885e4b0b602916 100644
--- a/en/application-dev/device/stationary/multimodalawareness-kit-intro.md
+++ b/en/application-dev/device/stationary/multimodalawareness-kit-intro.md
@@ -1,11 +1,11 @@
# Introduction to Multimodal Awareness Kit
-Multimodal Awareness Kit allows an application to identify user activities (walking, running, driving, etc.) or postures based on the data collected by sensors including gyroscopes and acceleration sensors built in a device.
+Multimodal Awareness Kit allows an application to identify user activities (walking, running, driving, etc.) or postures based on the data collected by sensors including gyroscopes and acceleration sensors built in a HarmonyOS device.
-## How MultimodalAwareness Kit Works
+## How Multimodal Awareness Kit Works
-MultimodalAwareness Kit is offered by the system as a basic service for applications. Depending on the service scenario, an application needs to initiate a subscription request to the system and cancel the subscription when the service scenario ends. In this process, the system reports the device status information to the application on a real-time basis.
+Multimodal Awareness Kit is offered by the system as a basic service for applications. Depending on the service scenario, an application needs to initiate a subscription request to the system and cancel the subscription when the service scenario ends. In this process, the system reports the device status information to the application on a real-time basis.
## Constraints
-To use MultimodalAwareness Kit, you need to apply for required permissions. The device must support the sensors required by the corresponding capabilities.
+To use Multimodal Awareness Kit, you need to apply for required permissions. The device must support the sensors required by the corresponding capabilities.
diff --git a/en/application-dev/dfx/Readme-EN.md b/en/application-dev/dfx/Readme-EN.md
index b441654d3958b4925a0d14d5f6642555440d6cc7..a379642780ceae3216180d3464d68d8bdeed8327 100644
--- a/en/application-dev/dfx/Readme-EN.md
+++ b/en/application-dev/dfx/Readme-EN.md
@@ -1,62 +1,65 @@
-# Performance Analysis Kit
+# Performance Analysis Kit
- [Introduction to Performance Analysis Kit](performance-analysis-kit-overview.md)
-- HiLog
+- HiLog
- [Using HiLog (ArkTS)](hilog-guidelines-arkts.md)
- [Using HiLog (C/C++)](hilog-guidelines-ndk.md)
-- HiAppEvent
+- HiAppEvent
- [Introduction to HiAppEvent](hiappevent-intro.md)
- - Event Subscription
- - Application Event
+ - Event Subscription
+ - Application Events
- [Subscribing to Application Events (ArkTS)](hiappevent-watcher-app-events-arkts.md)
- [Subscribing to Application Events (C/C++)](hiappevent-watcher-app-events-ndk.md)
- - System Event
- - Crash Event
+ - System Events
+ - Crash Events
- [Crash Event Overview](hiappevent-watcher-crash-events.md)
- [Subscribing to Crash Events (ArkTS)](hiappevent-watcher-crash-events-arkts.md)
- [Subscribing to Crash Events (C/C++)](hiappevent-watcher-crash-events-ndk.md)
- - Freeze Event
+ - Freeze Events
- [Freeze Event Overview](hiappevent-watcher-freeze-events.md)
- [Subscribing to Freeze Events (ArkTS)](hiappevent-watcher-freeze-events-arkts.md)
- [Subscribing to Freeze Events (C/C++)](hiappevent-watcher-freeze-events-ndk.md)
- - Resource Leak Event
+ - Resource Leak Events
- [Resource Leak Event Overview](hiappevent-watcher-resourceleak-events.md)
- [Subscribing to Resource Leak Events (ArkTS)](hiappevent-watcher-resourceleak-events-arkts.md)
- [Subscribing to Resource Leak Events (C/C++)](hiappevent-watcher-resourceleak-events-ndk.md)
- - Address Sanitizer Event
+ - Address Sanitizer Events
- [Address Sanitizer Event Overview](hiappevent-watcher-address-sanitizer-events.md)
- [Subscribing to Address Sanitizer Events (ArkTS)](hiappevent-watcher-address-sanitizer-events-arkts.md)
- [Subscribing to Address Sanitizer Events (C/C++)](hiappevent-watcher-address-sanitizer-events-ndk.md)
- - Main Thread Jank Event
+ - Main Thread Jank Events
- [Main Thread Jank Event Overview](hiappevent-watcher-mainthreadjank-events.md)
- [Subscribing to Main Thread Jank Events (ArkTS)](hiappevent-watcher-mainthreadjank-events-arkts.md)
- [Subscribing to Main Thread Jank Events (C/C++)](hiappevent-watcher-mainthreadjank-events-ndk.md)
+ - Task Execution Timeout Events
+ - [Task Execution Timeout Event Overview](hiappevent-watcher-apphicollie-events.md)
+ - [Subscribing to Task Execution Timeout Events (C/C++)](hiappevent-watcher-apphicollie-events-ndk.md)
- [Event Reporting](hiappevent-event-reporting.md)
-- HiTraceMeter
+- HiTraceMeter
- [Using HiTraceMeter (ArkTS/JS)](hitracemeter-guidelines-arkts.md)
- [Using HiTraceMeter (C/C++)](hitracemeter-guidelines-ndk.md)
- [Viewing HiTraceMeter Logs](hitracemeter-view.md)
-- HiTraceChain
+- HiTraceChain
- [Using HiTraceChain (ArkTS/JS)](hitracechain-guidelines-arkts.md)
- [Using HiTraceChain (C/C++)](hitracechain-guidelines-ndk.md)
-- HiChecker
+- HiChecker
- [Using HiChecker (ArkTS/JS)](hichecker-guidelines-arkts.md)
-- HiDebug
+- HiDebug
- [Using HiDebug (ArkTS)](hidebug-guidelines-arkts.md)
- [Using HiDebug (C/C++)](hidebug-guidelines-ndk.md)
-- HiCollie
+- HiCollie
- [Using HiCollie to Detect Service Thread Stuck and Jank Events](hicollie-guidelines-ndk.md)
- [Using HiCollie to Monitor the Function Execution Time (C/C++)](hicollie-settimer-guidelines-ndk.md)
-- Error Management
+- Error Management
- [Development of Error Manager](errormanager-guidelines.md)
- [Development of Application Recovery](apprecovery-guidelines.md)
-- Fault Analysis
+- Fault Analysis
- [Analyzing JS Crash](jscrash-guidelines.md)
- - [Analyzing CPP Crash](cppcrash-guidelines.md)
- - [Analyzing AppFreeze](appfreeze-guidelines.md)
-- Command Line Tools
+ - [Analyzing Cpp Crash](cppcrash-guidelines.md)
+ - [Analyzing App Freeze](appfreeze-guidelines.md)
+- Command Line Tools
- [hdc](hdc.md)
- [hilog](hilog.md)
- [hidumper](hidumper.md)
@@ -66,3 +69,4 @@
- [hisysevent](hisysevent.md)
- [uinput](uinput.md)
+
diff --git a/en/application-dev/dfx/appfreeze-guidelines.md b/en/application-dev/dfx/appfreeze-guidelines.md
index c95be185a4a7ebb7184a27e49d79228d28cf0583..68483a43640e907714637a020178348f5ee76ad9 100644
--- a/en/application-dev/dfx/appfreeze-guidelines.md
+++ b/en/application-dev/dfx/appfreeze-guidelines.md
@@ -1,8 +1,9 @@
# Analyzing App Freeze
-Appfreeze occurs when an application does not respond a click event within a certain period of time. OpenHarmony provides a mechanism for detecting appfreeze and generates appfreeze logs for fault analysis.
+App freeze (appfreeze) means that an application does not respond to a click event within a certain period of time. OpenHarmony provides a mechanism for detecting appfreeze and generates appfreeze logs for fault analysis.
> **NOTE**
+>
> This guide applies only to applications in the stage model. Before using this guide, you must have basic knowledge about the JS applications, C++ program stacks, and application-related subsystems.
## AppFreeze Detection
@@ -19,7 +20,7 @@ Currently, appfreeze detection supports the fault types listed in the following
This fault indicates that the main thread of this application is suspended or too many tasks are executed, which affects task execution smoothness and experience.
-Such a fault can be detected as follows: The watchdog thread of the application periodically inserts an activation detection to the main thread and inserts a timeout reporting mechanism to its own thread. If the activation detection is not executed within 3 seconds, the **THREAD_BLOCK_3S** event is reported. If the activation detection is not executed within 6 seconds, the **THREAD_BLOCK_6S** event is reported. The two events together form an appfreeze log.
+Such a fault can be detected as follows: The watchdog thread of the application periodically inserts an activation detection to the main thread and inserts a timeout reporting mechanism to its own thread. If the activation detection is not executed within 3 seconds, the **THREAD_BLOCK_3S** event is reported. If the activation detection is not executed within 6 seconds, the **THREAD_BLOCK_6S** event is reported. The two events constitute an AppFreeze log.
The following figure shows the working principle.
@@ -64,14 +65,14 @@ To identify the cause of appfreeze, analyze the appfreeze logs together with HiL
The following example shows an appfreeze log analysis. You can analyze the fault based on actual situation.
-Appfreeze logs consist of header information, and general and specific information in the body.
+AppFreeze logs consist of header information, and general and specific information in the body.
### Header Information
| Field| Description|
| -------- | -------- |
-| Reason | Reason why the application does not respond. For details, see [appfreeze Detection](#appfreeze-detection).|
-| PID | PID of the failed process, which can be used to search for related process information in the Hilog logs.|
+| Reason | Reason why the application does not respond. For details, see [AppFreeze Detection](#appfreeze-detection).|
+| PID | PID of the failed process, which can be used to search for related process information in the HiLog logs.|
| PACKAGE_NAME | Application process package name.|
```
@@ -92,7 +93,7 @@ PID:1561
UID:20010039
PACKAGE_NAME:com.xxx.xxx
PROCESS_NAME:com.xxx.xxx
-MSG:ablity:EntryAbility background timeout
+MSG:ability:EntryAbility background timeout
```
### General Information in the Log Body
@@ -101,9 +102,9 @@ General information is present in all the aforementioned logs. It contains the f
| Field| Description|
| -------- | -------- |
-| EVENTNAME | One or more fault events that constitute the cause of main thread freeze event.|
-| TIMESTAMP | Time when the fault event is reported. You can narrow down the time range to view HiLog logs based on the timeout duration described in [AppFreeze Detection](#appfreeze-detection).|
-| PID | PID of the failed process, which can be used with the timestamp and timeout duration to search for related process information in the Hilog logs.|
+| EVENTNAME | One or more fault events that constitute the cause of main thread freeze.|
+| TIMESTAMP | Time when a fault event is reported. You can narrow down the time range to view HiLog logs based on the timeout duration described in [AppFreeze Detection](#appfreeze-detection).|
+| PID | PID of the failed process, which can be used with the timestamp and timeout duration to search for related process information in the HiLog logs.|
| PACKAGE_NAME | Application process package name.|
| MSG | Dump information or description of the fault.|
| BinderCatcher | Information about IPC calls between a process and other system processes, such as the call waiting time.|
@@ -130,12 +131,12 @@ The task information in the main thread queue includes:
Locate the application stack information by searching for the **PID**. In the following stack, the window stays in the IPC communication phase when it sends events to the system through the IPC.
```
-OpenStacktraceCatcher -pid==1561 packageName is com.ohos.huawei.myapplication
+OpenStacktraceCatcher -pid==1561 packageName is com.example.myapplication
Result: 0 ( no error )
Timestamp:2017-08-0817:06:53.000
Pid:1561
Uid:20010039
-Process name:com.ohos.huawei.myapplication
+Process name:com.example.myapplication
Tid:1561,Name:i.myapplication
#00 pc 0017888c /system/lib/libark_jsruntime.so
#01 pc 00025779 /system/lib/platformsdk/libipc_core.z.so(OHOS:BinderConnector:WriteBinder(unsigned Long,void*)+56)
@@ -278,8 +279,8 @@ TIMESTAMP = 2017/08/08-17:06:24:363
PID = 1561
UID = 20010039
TID = 1566
-PACKAGE_NAME com.ohos.huawei.myapplication
-PROCESS_NAME com.ohos.huawei.myapplication
+PACKAGE_NAME com.example.myapplication
+PROCESS_NAME com.example.myapplication
eventLog_action pb:1 eventLog_interval 10
MSG = App main thread is not response!EventHandler dump begin curTime:2017-08-08 05:06:24.362
Event runner (Thread name =Thread ID 1561)is running
@@ -298,9 +299,9 @@ MSG = App main thread is not response!EventHandler dump begin curTime:2017-08-08
Timestamp: 2017-08-0817:06:24.4142447784
Pid: 1561
Uid: 20010039
- Process name: com.ohos.huawei.myapplication
+ Process name: com.example.myapplication
Tid:1561 Name:i.myapplication
- at anonymous entry (D:/project/OpenHarmonyOS/MyApplication_test/entry/build/default/intermediates/loader_out/default/ets,pages/Index_.js:0:1)
+ at anonymous entry (D:/project/MyApplication_test/entry/build/default/intermediates/loader_out/default/ets/pages/Index_.js:0:1)
#00 pc 0017909c /system/lib/libark_jsruntime.so
#01 pc 00177ebb /system/lib/libark_jsruntime.so
#02 pc 0024b4bb /system/lib/libark_jsruntime.so
@@ -309,7 +310,7 @@ MSG = App main thread is not response!EventHandler dump begin curTime:2017-08-08
...
```
-THREAD_BLOCK_6S:
+THREAD_BLOCK_6S:
```
start time: 2017/08/08-17:06:27:299
DOMAIN = AAFWK
@@ -318,8 +319,8 @@ TIMESTAMP = 2017/08/08-17:06:27:292
PID = 1561
UID = 20010039
TID = 1566
-PACKAGE_NAME com.ohos.huawei.myapplication
-PROCESS NAME com.ohos.huawei.myapplication eventLog_action cmd:c,cmd:m,tr,k:SysRqFile
+PACKAGE_NAME com.example.myapplication
+PROCESS NAME com.example.myapplication eventLog_action cmd:c,cmd:m,tr,k:SysRqFile
eventLog_interval 10
MSG = App main thread is not response!EventHandler dump begin curTime:2017-08-08 05:06:27.291
Event runner (Thread name =Thread ID =1561)is running
@@ -339,9 +340,9 @@ MSG = App main thread is not response!EventHandler dump begin curTime:2017-08-08
Timestamp:2017-08-0817:0k:27,4142447784
Pid:1561
Uid:20010039
-Process name:com.ohos.huawei.myapplication
+Process name:com.example.myapplication
Tid:1561 Name:i.myapplication
- at anonymous entry (D:/project/OpenHarmony0S/MyApplication_test/entry/build/default/intermediates/loader_out/default/ets/pages/Index_.js:0:1)
+ at anonymous entry (D:/project/MyApplication_test/entry/build/default/intermediates/loader_out/default/ets/pages/Index_.js:0:1)
#00 pc 00178dcc /system/lib/libark_jsruntime.so
#01 pc 00177ebb /system/lib/libark_jsruntime.so
#02 pc 0024b4bb /system/lib/libark_jsruntime.so(panda:FunctionRef:Call(panda:ecmascript:EcmaVM const*,panda:Local,par
@@ -350,7 +351,7 @@ Tid:1561 Name:i.myapplication
#05 pc 00d7af1b /system/lib/libace.z.so
```
-Check the code being executed on the application side based on the Hilog log.
+Check the code being executed on the application side based on the HiLog log.
Generally, you can view the [General Information in the Log Body](#general-information-in-the-log-body) to determine the cause of an appfreeze event, including peer communication suspension, high CPU usage, memory leaks, or a large amount of memory.
@@ -368,7 +369,7 @@ For details, see [General Information in the Log Body](#general-information-in-t
**MSG** indicates the lifecycle that encounters a timeout.
-In the following example, **LIFECYCLE_TIMEOUT** indicates that the process times out when **Ability** is switched to background. You can find Hilog information based on the timeout duration of [Lifecycle Switching Timeout](#lifecycle-switching-timeout).
+In the following example, **LIFECYCLE_TIMEOUT** indicates that the process times out when **Ability** is switched to background. You can find HiLog information based on the timeout duration of [Lifecycle Switching Timeout](#lifecycle-switching-timeout).
LIFECYCLE_TIMEOUT:
@@ -378,8 +379,8 @@ STRINGID:LIFECYCLE
TIMEOUT TIMESTAMP:2023/03/10-17:06:53:65
PID:1561
UID:20010039
-PACKAGE_NAME:com.ohos.huawei.myapplication
-PROCESS_NAME:com.ohos.huawei.myapplication
+PACKAGE_NAME:com.example.myapplication
+PROCESS_NAME:com.example.myapplication
MSG:ability:EntryAbility background timeout
```
@@ -407,7 +408,7 @@ The appfreeze log is managed together with the native process crash, JS applicat
DevEco Studio collects device fault logs and saves them to **FaultLog**. For details, see [DevEco Studio User Guide-FaultLog](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-fault-log-V5).
-- Method 2: hiAppEvent APIs
+- Method 2: HiAppEvent APIs
hiAppEvent provides APIs to subscribe to various fault information. For details, see [Introduction to HiAppEvent](hiappevent-intro.md).
@@ -442,7 +443,7 @@ DisplayPowerInfo:powerState: AWAKE
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
```
-#### Obtain the fault occurrence time.
+#### Obtain the fault occurrence time
Fault report time:
@@ -478,7 +479,7 @@ The fault occurrence time can be obtained based on the detection duration and th
You can search for the keyword **mainHandler dump is** to view the **eventHandler dump** information in logs.
-1. dump begin curTime & Current Running
+1. **dump begin curTime** & **Current Running**.
```
mainHandler dump is:
@@ -494,7 +495,7 @@ If the task running duration is longer than the fault detection duration, the ru
If the current task running duration is short, the task is only one of the tasks running in the main thread within the detection duration and may not be the task that consumes most time. You are advised to check the task that consumes the longest time recently (in **History event queue information**). In this case, the watchdog cannot be scheduled because the thread is busy.
-2. History event queue information
+2. **History event queue information**.
```
Current Running: start at 2024-08-08 12:17:16.629, Event { send thread = 35882, send time = 2024-08-08 12:17:16.628, handle time = 2024-08-08 12:17:16.629, trigger time = 2024-08-08 12:17:16.630, task name = , caller = [extension_ability_thread.cpp(ScheduleAbilityTransaction:393)]}
@@ -507,11 +508,11 @@ If the current task running duration is short, the task is only one of the tasks
No. 5 : Event { send thread = 35852, send time = 2024-08-08 12:17:16.629, handle time = 2024-08-08 12:17:16.629, trigger time = 2024-08-08 12:17:16.629, completeTime time = , priority = Low, task name = }
```
-You can search for time-consuming tasks in History event queue information. The task whose **completeTime time** is empty is the current task.
-Task running duration = completeTime time – trigger time.
+You can search for time-consuming tasks in History event queue information. The task whose **completeTime time** is empty is the current task.
+Task running duration = completeTime time – trigger time.
Filter out the tasks that take a longer time and check the running status of the tasks.
-3. VIP priority event queue information
+3. **VIP priority event queue information**.
```
VIP priority event queue information:
@@ -529,7 +530,7 @@ Filter out the tasks that take a longer time and check the running status of the
To ensure timely response to the user, all tasks in the user input event propagation are high-priority tasks. The VIP priority event queue is created by the system and records the transmission process of user input -> screen -> window -> ArkUI -> application. It is irrelevant to third-party application events and does not need to be concerned.
-4. High priority event queue information
+4. **High priority event queue information**.
```
High priority event queue information:
@@ -576,7 +577,7 @@ In the preceding example, the block queue is longer than the warning queue, but
Check the stack using the obtained PID and TID. The result may show as follows:
-1. The stack information is clearly displayed.
+1. The stack information shows that the process is suspended.
```
Tid:3025, Name: xxx
@@ -717,7 +718,7 @@ As shown in the stack, the number of threads in the ready state of process 1386
3. Check whether the value of **waitTime** is too small.
-**waitTime** indicates the IPC duration. If the value of **waitTime** is far less than the fault detection duration, the suspension is not caused by the IPC request.
+**waitTime** indicates the IPC duration. If the value of **waitTime** is far less than the fault detection duration, the suspension is not caused by the IPC request.
If the main thread on the application sends multiple IPC requests in a short period of time, the value of **waitTime** will be large. As a result, the thread is suspended.
In this case, you can check the following items:
@@ -726,32 +727,32 @@ In this case, you can check the following items:
4. Check whether there is no calling relationship and whether the stack is an IPC stack.
-Check whether the stack is a temporary stack, that is, whether the warning stack is the same as the block stack. It is possible that the warning stack is an IPC stack, and the block stack is a temporary stack because the IPC request has ended when the binder is captured, and the IPC request takes a short time.
+Check whether the stack is a temporary stack, that is, whether the warning stack is the same as the block stack. It is possible that the warning stack is an IPC stack, and the block stack is a temporary stack because the IPC request has ended when the binder is captured, and the IPC request takes a short time.
It should be noted that binder information is not obtained in real time when a fault occurs and is delayed. For faults that require half-period detection, binder information is accurately captured because most binder information can be collected within the fault period. For other faults, the off-site binder information may be captured when the reporting is delayed.
You can view the execution duration of binder based on [Analyzing Trace Logs](#analyzing-trace logs).
-### Analyzing Hilog logs
+### Analyzing HiLog logs
#### DFX-related Logs
-1. Fault report (reportEvent):
+1. Fault report (reportEvent).
-2. Stack capture (signal: 35):
+2. Stack capture (signal: 35).
-3. Background application check for five times before reporting, about 21s:
+3. Background application check for five times before reporting, about 21s.
-4. Exit reason record:
+4. Application exit reason record.
-5. APP_FREEZE kills the application:
+5. APP_FREEZE kills the application.
@@ -759,7 +760,7 @@ You can view the execution duration of binder based on [Analyzing Trace Logs](#a
View [Obtain the fault occurrence time](#obtain-the-fault-occurrence-time), and determine the fault occurrence time based on the fault type. Analyze the HiLog logs in the specific period to obtain the status of the running thread.
-- If no application log is printed, the application is frozen when the logging API is invoked.
+- If no application log is printed, the application freezes when the logging API is called.
@@ -787,7 +788,7 @@ The possible causes are as follows:
-In the preceding figure, the **ohos.animator** in **PriviewArea::updateShotComponent** is executed for 9.2s.
+In the preceding figure, the **animator** in **PriviewArea::updateShotComponent** is executed for 9.2s.
The thread is busy executing a service cyclically and analyzing each service segment.
@@ -835,11 +836,11 @@ The background application freezes and related functions are unavailable, but it
Extract the key fault logs.
```
-appfreeze: com.huawei.hmsapp.xxx THREAD_BLOCK_6S at 20240408082432
+appfreeze: com.example.hmsapp.xxx THREAD_BLOCK_6S at 20240408082432
DisplayPowerInfo:powerState:AWAKE
```
-The value of **Foreground** indicates that **hiai** is a background application. Therefore, it can be inferred that when the 3s event is reported, the background application freezes for **18s**.
+The value of **Foreground** indicates that the application is a background application. Therefore, it can be inferred that when the 3s event is reported, the background application is frozen for 18s.
```
Module name:com.xxx.xxx.xxx
@@ -852,7 +853,7 @@ Uid:20020029
Reason:THREAD_BLOCK_6S
```
-The **THREAD_BLOCK_3S** event is reported at **08:24:29:612**.
+The **THREAD_BLOCK_3S** event is reported at **08:24:29:612**.
The **THREAD_BLOCK_6S** event is reported at **08:24:32:638**. The interval is 3s as expected.
```
@@ -1050,7 +1051,7 @@ which severely affect user experience.
Extract the key fault logs.
```
-appfreeze: com.ohos.sceneboard APP_INPUT_BLOCK at 20240319022527
+appfreeze: com.example.sceneboard APP_INPUT_BLOCK at 20240319022527
DisplayPowerInfo:powerState:AWAKE
```
@@ -1062,11 +1063,11 @@ STRINGID:APP_INPUT_BLOCK
TIMESTAMP:2024/03/14-14:40:59:440 --> Fault report time.
PID:2918
UID:20020017
-PACKAGE_NAME:com.ohos.sceneboard
-PROCESS_NAME:com.ohos.sceneboard
+PACKAGE_NAME:com.example.sceneboard
+PROCESS_NAME:com.example.sceneboard
```
-The reported cause is "User input does not respond!".
+The reported cause is "User input does not respond!". There is no response to the user input event.
The running task of the main thread (Thread ID == PID) starts at **14:40:53.499** and is not complete until the **Fault time** **14:40:58**.
```
@@ -1112,13 +1113,13 @@ In the following example, more than 200 input events are blocked in the queue.
No.205 : Event { send thread = 3370, send time = 2024-03-14 02:40:56.305, handle time = 2024-03-14 02:40:56.305, task name = , caller = [input_manager_impl.cpp(OnPointerEvent:465)] }
```
-The input event triggers the main thread task of the application. However, the execution is not complete within 6 seconds and no response is returned. As a result, the ANR times out.
+The input event triggers the main thread task of the application. However, the execution is not complete within 6 seconds and no response is returned. As a result, the ANR times out.
In this case, you only need to find out the task that the input triggers and why the task execution times out.
In the running main thread stack, the **ark_jsruntime GetCurrentThreadId** function at the stack top does not hold a lock or is time-consuming. The captured stack is a transient stack that is useless for analysis.
```
-Tid:2918, Name:ohos.sceneboard
+Tid:2918, Name:example.sceneboard
# 00 pc 000000000009f73c /system/lib/ld-musl-aarch64.so.1(8fa55898166cd804dad43d909b5319cc)
# 01 pc 000000000054b7b4 /system/lib64/platformsdk/libark_jsruntime.so(panda::os::thread::GetCurrentThreadId()+12)(7715646e48f750f3dc31e660b056eb43)
# 02 pc 00000000002107a4 /system/lib64/platformsdk/libark_jsruntime.so(panda::ecmascript::EcmaVM::CheckThread() const+200)(7715646e48f750f3dc31e660b056eb43)
@@ -1137,9 +1138,9 @@ Tid:2918, Name:ohos.sceneboard
...
```
-Check the Hilog logs.
+Check the HiLog logs.
-The **APP_INPUT_BLOCK** event is reported at about **13:40:59.448**, and then DFX kills the freezed SCB.
+The **APP_INPUT_BLOCK** event is reported at about **13:40:59.448**, and then DFX kills the suspended SCB.
@@ -1157,9 +1158,9 @@ Check the trace log within the 6 seconds.
It shows that the SCB main thread is fully occupied. The **CustomNodeUpdate SwiperPage** task takes a longer time. Therefore, you need to check why this component keeps refreshing.
-It is found that **themeStyle** is added to the **key** on **swiperPage**. When the **key** value changes, a new control is created.
+It is found that **themeStyle** is added to the **key** on **swiperPage**. When the **key** value changes, a new component is created.
-When a user switches the theme or icon style, all controls on the home screen are created. As a result, the main thread is busy and cannot respond the input event.
+When a user switches the theme or icon style, all components on the home screen are created. As a result, the main thread is busy and cannot respond the input event.
#### Solution
@@ -1222,7 +1223,7 @@ client:
312522; AbilityThread::ScheduleAbilityTransaction; the foreground lifecycle.
```
-The **LIFECYCLE_HALF_TIMEOUT** event is reported at **10:04:57:538**.
+The **LIFECYCLE_HALF_TIMEOUT** event is reported at **10:04:57:538**.
The **LIFECYCLE_TIMEOUT** event is reported at **10:04:59:965**. The interval of the two events is about 2.5s, which is as expected.
```
@@ -1232,8 +1233,8 @@ STRINGID:LIFECYCLE_TIMEOUT
TIMESTAMP:2024/02/01-10:04:59:965
PID:18083
UID:20020041
-PACKAGE_NAME:com.huawei.hmos.notepad
-PROCESS_NAME:com.huawei.hmos.notepad
+PACKAGE_NAME:com.example.notepad
+PROCESS_NAME:com.example.notepad
*******************************************
start time: 2024/02/01-10:04:57:555
DOMAIN = AAFWK
@@ -1242,8 +1243,8 @@ TIMESTAMP = 2024/02/01-10:04:57:538
PID = 18083
UID = 20020041
TID = 17286
-PACKAGE_NAME = com.huawei.hmos.notepad
-PROCESS_NAME = com.huawei.hmos.notepad
+PACKAGE_NAME = com.example.notepad
+PROCESS_NAME = com.example.notepad
```
The task starts at **10:04:54.798**, and the interval between the start time and **LIFECYCLE_HALF_TIMEOUT** is about 2.5s, which is as expected.
@@ -1263,10 +1264,10 @@ mainHandler dump is:
...
```
-Check the stack information at **libfs.z.so -> libdatashare_consumer.z.so -> libipc_core.z.so**.
+Check the stack information at **libfs.z.so > libdatashare_consumer.z.so > libipc_core.z.so**.
```
-Tid:18083, Name:ei.hmos.notepad
+Tid:18083, Name:ei.example.notepad
# 00 pc 00000000001617a4 /system/lib/ld-musl-aarch64.so.1(ioctl+180)(4ca73cff61bea7c4a687eb0f71c9df69)
# 01 pc 000000000003e8a0 /system/lib64/platformsdk/libipc_core.z.so(OHOS::BinderConnector::WriteBinder(unsigned long, void*)+72)(3248fceb1fa676994734e0437430ce37)
# 02 pc 0000000000049f38 /system/lib64/platformsdk/libipc_core.z.so(OHOS::BinderInvoker::TransactWithDriver(bool)+296)(3248fceb1fa676994734e0437430ce37)
@@ -1303,7 +1304,7 @@ Result: 0 ( no error )
Timestamp:2024-02-01 10:04:57.000
Pid:5235
Uid:20020079
-Process name:com.ohos.medialibrary.medialibrarydata
+Process name:com.medialibrary.medialibrarydata
Tid:5235, Name:edialibrarydata
# 00 pc 0000000000142d1c /system/lib/ld-musl-aarch64.so.1(epoll_wait+84)(4ca73cff61bea7c4a687eb0f71c9df69)
# 01 pc 000000000000fb74 /system/lib64/chipset-pub-sdk/libeventhandler.z.so(OHOS::AppExecFwk::EpollIoWaiter::WaitFor(std::__h::unique_lock&, long)+224)(a4d21072c08fd3ac639d5cf5b8fb8b51)
diff --git a/en/application-dev/dfx/apprecovery-guidelines.md b/en/application-dev/dfx/apprecovery-guidelines.md
index c514d3b877e0c81050113e4e01c7e3996fb62482..d2437eeab8686fbd682677d60ee5ca00a62e8ecc 100644
--- a/en/application-dev/dfx/apprecovery-guidelines.md
+++ b/en/application-dev/dfx/apprecovery-guidelines.md
@@ -15,15 +15,15 @@ In API version 10, application recovery is applicable to multiple abilities of a
The application recovery APIs are provided by the **appRecovery** module, which can be imported via **import**. For details, see [Development Example](#development-example).
-### Application Recovery APIs
+### Available APIs
| API | Description |
| ------------------------------------------------------------ | ---------------------------------------------------- |
-| enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void;9+ | Enables application recovery. After this API is called, the first ability that is displayed when the application is started from the initiator can be restored.|
-| saveAppState(): boolean;9+ | Saves the state of the ability that supports recovery in the current application.|
-| restartApp(): void;9+ | Restarts the current process and starts the ability specified by **setRestartWant**. If no ability is specified, a foreground ability that supports recovery is restarted.|
-| saveAppState(context?: UIAbilityContext): boolean;10+ | Saves the ability state specified by **Context**.|
-| setRestartWant(want: Want): void;10+ | Sets the abilities to restart when **restartApp** is actively called and **RestartFlag** is not **NO_RESTART**. The abilities must be under the same bundle name and must be a **UIAbility**.|
+| enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void9+ | Enables application recovery. After this API is called, the first ability that is displayed when the application is started from the initiator can be restored.|
+| saveAppState(): boolean9+ | Saves the state of the ability that supports recovery in the current application.|
+| restartApp(): void9+ | Restarts the current process and starts the ability specified by **setRestartWant**. If no ability is specified, a foreground ability that supports recovery is restarted.|
+| saveAppState(context?: UIAbilityContext): boolean10+ | Saves the ability state specified by **Context**.|
+| setRestartWant(want: Want): void10+ | Sets the abilities to restart when **restartApp** is actively called and **RestartFlag** is not **NO_RESTART**. The abilities must be under the same bundle name and must be a **UIAbility**.|
No error will be thrown if the preceding APIs are used in the troubleshooting scenario. The following are some notes on API usage:
@@ -60,6 +60,7 @@ Fault management is an important way for applications to deliver a better user e
The figure below does not illustrate the time when [faultLogger](../reference/apis-performance-analysis-kit/js-apis-faultLogger.md) is called. You can refer to the [LastExitReason](../reference/apis-ability-kit/js-apis-app-ability-abilityConstant.md#abilityconstantlastexitreason) passed during application initialization to determine whether to call [faultLogger](../reference/apis-performance-analysis-kit/js-apis-faultLogger.md) to query information about the previous fault.
+
It is recommended that you call [errorManager](../reference/apis-ability-kit/js-apis-app-ability-errorManager.md) to handle the exception. After the processing is complete, you can call the **saveAppState** API and restart the application.
If you do not register an [ErrorObserver](../reference/apis-ability-kit/js-apis-inner-application-errorObserver.md) instance or enable application recovery, the application process will exit according to the default processing logic of the system. Users can restart the application from the home screen.
If you have enabled application recovery, the recovery framework first checks whether application state saving is supported and whether the application state saving is enabled. If so, the recovery framework invokes [onSaveState](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonsavestate) of the [ability](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md). Finally, the application is restarted.
diff --git a/en/application-dev/dfx/cppcrash-guidelines.md b/en/application-dev/dfx/cppcrash-guidelines.md
index e2ba7ce073a9e61ac809023ed71af1faeb14ae64..2e6dbb3c86ab9a32efedea5746b0f2c020fe82b9 100644
--- a/en/application-dev/dfx/cppcrash-guidelines.md
+++ b/en/application-dev/dfx/cppcrash-guidelines.md
@@ -19,69 +19,69 @@ Process crash detection is based on the posix signal mechanism. Currently, the e
| 16 | SIGSTKFLT | Stack error| The processor performs an incorrect stack operation, such as a pop when the stack is empty or a push when the stack is full.|
| 31 | SIGSYS | Incorrect system call| An incorrect or invalid parameter is used in a system call.|
-Some of the preceding fault signals are classified into codes based on specific scenarios.
+Some of the preceding fault signals are classified into codes based on specific scenarios.
**SIGILL** occurs in Unix and Unix-like operating systems. It indicates an invalid instruction exception. The **SIGILL** signal is usually triggered by the following causes:
-| No.| Code| Description| Trigger Cause|
+| Code| Signal| Description| Trigger Cause|
| -------- | -------- | -------- | -------- |
-| 1 | ILL_ILLOPC | Illegal operation code| A privileged instruction or an instruction that is unsupported by the CPU is executed.|
-| 2 | ILL_ILLOPN | Illegal operand| An incorrect operand or improper operand type is used.|
-| 3 | ILL_ILLADR | Illegal address| A program accesses an invalid memory address or an unaligned memory address.|
-| 4 | ILL_ILLTRP | Illegal trap| A program performs an illegal trap instruction or an undefined operation.|
-| 5 | ILL_PRVOPC | Illegal privileged operation code| A common user executes a privileged instruction.|
-| 6 | ILL_PRVREG | Illegal privileged register| A common user accesses a privileged register.|
-| 7 | ILL_COPROC | Illegal coprocessor| A program performs an undefined coprocessor instruction.|
-| 8 | ILL_BADSTK | Illegal stack| A program performs an operation at an invalid stack address, or when the stack overflows.|
+| 1 | ILL_ILLOPC | Illegal operation code.| A privileged instruction or an instruction that is unsupported by the CPU is executed.|
+| 2 | ILL_ILLOPN | Illegal operand.| An incorrect operand or improper operand type is used.|
+| 3 | ILL_ILLADR | Illegal address.| A program accesses an invalid memory address or an unaligned memory address.|
+| 4 | ILL_ILLTRP | Illegal trap.| A program performs an illegal trap instruction or an undefined operation.|
+| 5 | ILL_PRVOPC | Illegal privileged operation code.| A common user executes a privileged instruction.|
+| 6 | ILL_PRVREG | Illegal privileged register.| A common user accesses a privileged register.|
+| 7 | ILL_COPROC | Illegal coprocessor.| A program performs an undefined coprocessor instruction.|
+| 8 | ILL_BADSTK | Illegal stack.| A program performs an operation at an invalid stack address, or when the stack overflows.|
**SIGTRAP** usually occurs in debugging and tracking. The four scenarios of the **SIGTRAP** signal are described as follows.
-| No.| Code| Description| Trigger Cause|
+| Code| Signal| Description| Trigger Cause|
| -------- | -------- | -------- | -------- |
-| 1 | TRAP_BRKPT | Software breakpoint| The software breakpoint is reached in a program. When debugging a program, a software breakpoint at the key position can be used to pause the program execution and check information such as variable values.|
-| 2 | TRAP_TRACE | Single-step debugging| A single instruction is executed in a program. Single instruction can be used to check the execution result of each instruction.|
-| 3 | TRAP_BRANCH | Branch Tracing| A branch instruction is executed in a program. Branch instruction can be used to control the execution process of a program, such as if statements and loop statements.|
-| 4 | TRAP_HWBKPT | Hardware breakpoint| The hardware breakpoint is reached in a program. When debugging a program, a hardware breakpoint at the key position can be used to pause the program execution and check information such as variable values. Different from a software breakpoint, a hardware breakpoint is implemented in CPU hardware. Therefore, whether a hardware breakpoint is triggered can be detected in real time during program execution.|
+| 1 | TRAP_BRKPT | Software breakpoint.| The software breakpoint is reached in a program. When debugging a program, a software breakpoint at the key position can be used to pause the program execution and check information such as variable values.|
+| 2 | TRAP_TRACE | Single-step debugging.| A single instruction is executed in a program. Single instruction can be used to check the execution result of each instruction.|
+| 3 | TRAP_BRANCH | Branch tracing.| A branch instruction is executed in a program. Branch instruction can be used to control the execution process of a program, such as if statements and loop statements.|
+| 4 | TRAP_HWBKPT | Hardware breakpoint.| The hardware breakpoint is reached in a program. When debugging a program, a hardware breakpoint at the key position can be used to pause the program execution and check information such as variable values. Different from a software breakpoint, a hardware breakpoint is implemented in CPU hardware. Therefore, whether a hardware breakpoint is triggered can be detected in real time during program execution.|
The **SIGBUS** signal is sent by the operating system to a process. It usually indicates a memory access error. The codes of the **SIGBUS** signal are described as follows:
-| No.| Code| Description| Trigger Cause|
+| Code| Signal| Description| Trigger Cause|
| -------- | -------- | -------- | -------- |
-| 1 | BUS_ADRALN | Unaligned memory address| A program accesses an unaligned memory address, for example, a non-even address of a 4-byte integer.|
-| 2 | BUS_ADRERR | Invalid memory address| A program accesses a memory address that does not exist in the Process Address Space, such as a null pointer.|
-| 3 | BUS_OBJERR | Invalid object access| A program accesses an object that is deleted or not initialized.|
-| 4 | BUS_MCEERR_AR | Invalid hardware memory check| A checksum error is detected when the hardware memory is accessed.|
-| 5 | BUS_MCEERR_AO | Invalid hardware memory check| An address check error is detected when the hardware memory is accessed.|
+| 1 | BUS_ADRALN | Unaligned memory address.| A program accesses an unaligned memory address, for example, a non-even address of a 4-byte integer.|
+| 2 | BUS_ADRERR | Invalid memory address.| A program accesses a memory address that does not exist in the Process Address Space, such as a null pointer.|
+| 3 | BUS_OBJERR | Invalid object access.| A program accesses an object that is deleted or not initialized.|
+| 4 | BUS_MCEERR_AR | Invalid hardware memory check.| A checksum error is detected when the hardware memory is accessed.|
+| 5 | BUS_MCEERR_AO | Invalid hardware memory check.| An address check error is detected when the hardware memory is accessed.|
The **SIGFPE** signal indicates a floating-point exception or an arithmetic exception. The codes of the **SIGFPE** signal are described as follows:
-| No.| Code| Description| Trigger Cause|
+| Code| Signal| Description| Trigger Cause|
| -------- | -------- | -------- | -------- |
-| 1 | FPE_INTDIV | Invalid integer division| The divisor in an integer division is zero. |
-| 2 | FPE_INTOVF | Integer overflow| The divisor in an integer division is negative. |
-| 3 | FPE_FLTDIV | Invalid floating-point division| The divisor in a floating-point division is zero. |
-| 4 | FPE_FLTOVF | Floating-point overflow| The divisor in a floating-point division is negative. |
-| 5 | FPE_FLTUND | Floating-point underflow| The divisor in a floating-point division is zero. |
-| 6 | FPE_FLTRES | Invalid floating-point result| The divisor in a floating-point division is positive. |
-| 7 | FPE_FLTINV | Invalid floating-point operation| The divisor in a floating-point division is negative. |
-| 8 | FPE_FLTSUB | Floating-point trap| The divisor in a floating-point division is zero. |
+| 1 | FPE_INTDIV | Invalid integer division.| The divisor in an integer division is zero. |
+| 2 | FPE_INTOVF | Integer overflow.| The divisor in an integer division is negative. |
+| 3 | FPE_FLTDIV | Invalid floating-point division.| The divisor in a floating-point division is zero. |
+| 4 | FPE_FLTOVF | Floating-point overflow.| The divisor in a floating-point division is negative. |
+| 5 | FPE_FLTUND | Floating-point underflow.| The divisor in a floating-point division is zero. |
+| 6 | FPE_FLTRES | Invalid floating-point result.| The divisor in a floating-point division is positive. |
+| 7 | FPE_FLTINV | Invalid floating-point operation.| The divisor in a floating-point division is negative. |
+| 8 | FPE_FLTSUB | Floating-point trap.| The divisor in a floating-point division is zero. |
The **SIGSEGV** signal occurs when a process accesses a non-existent memory address or an inaccessible address. The codes of the **SIGSEGV** signal are described as follows:
-| No.| Code| Description| Trigger Cause|
+| Code| Signal| Description| Trigger Cause|
| -------- | -------- | -------- | -------- |
-| 1 | SEGV_MAPERR | Non-existent memory address| A process accesses a memory address that does not exist or that is not mapped to the Process Address Space. This exception is usually caused by pointer errors or memory leaks.|
-| 2 | SEGV_ACCERR | Inaccessible memory address| A process accesses an inaccessible memory address marked by the operating system, such as a read-only memory address or a memory address without execution permission. This exception is usually caused by buffer overflow or modifying read-only memory.|
+| 1 | SEGV_MAPERR | Non-existent memory address.| A process accesses a memory address that does not exist or that is not mapped to the Process Address Space. This exception is usually caused by pointer errors or memory leaks.|
+| 2 | SEGV_ACCERR | Inaccessible memory address.| A process accesses an inaccessible memory address marked by the operating system, such as a read-only memory address or a memory address without execution permission. This exception is usually caused by buffer overflow or modifying read-only memory.|
The classification of codes cannot only be based on **signo**, but also be based on the causes of the signal. The preceding describes the codes classified based on the **signo** of each signal, while the following describes the codes classified based on causes of all signals:
-| No.| Code| Description| Trigger Cause|
+| Code| Signal| Description| Trigger Cause|
| -------- | -------- | -------- | -------- |
-| 0 | SI_USER | User space signal|This signal is sent by a process in user space to another process, usually using the **kill()**. For example, when a user presses **Ctrl+C** on the terminal, a **SIGINT** signal is sent to all foreground processes.|
-| 0x80 | SI_KERNEL | Kernel signal|This signal is sent by the kernel to the process. It is usually sent when the kernel detects some errors or exceptions. For example, when a process accesses an invalid memory address or executes an invalid instruction, the kernel sends a **SIGSEGV** signal to the process.|
-| -1 | SI_QUEUE | **sigqueue()** signal|This signal is sent by **sigqueue()**, and an additional integer value and a pointer can be carried. It is usually used for advanced communication between processes, such as transferring data or notifying a process that an event occurs.|
-| -2 | SI_TIMER | Timer signal|This signal is sent by a timer and is usually used to execute a scheduled task or a periodic task. For example, when a timer expires, the kernel sends a **SIGALRM** signal to the process.|
-| -3 | SI_MESGQ | Message queue signal|This signal is sent by a message queue and is usually used for communication across processes. For example, when a process sends a message to a message queue, the kernel sends a **SIGIO** signal to the receiving process.|
-| -4 | SI_ASYNCIO | Asynchronous I/O signal|This signal is sent by an asynchronous I/O and is usually used for a non-blocking I/O. For example, when an I/O operation on a file descriptor is complete, the kernel sends a **SIGIO** signal to the process.|
-| -5 | SI_SIGIO | Synchronous I/O signal|This signal is sent by a synchronous I/O and is usually used for a non-blocking I/O. For example, when an I/O operation on a file descriptor is complete, the kernel sends a **SIGIO** signal to the process.|
-| -6 | SI_TKILL | **tkill()** signal|This signal is sent by the function **tkill()**, which is similar to the function **kill()**. In addition, you can specify the ID of the thread that sends the signal. It is usually used to send a signal to a specified thread in a multithreaded program.|
+| 0 | SI_USER | User space.|This signal is sent by a process in user space to another process, usually using the **kill()**. For example, when a user presses **Ctrl+C** on the terminal, a **SIGINT** signal is sent to all foreground processes.|
+| 0x80 | SI_KERNEL | Kernel.|This signal is sent by the kernel to the process. It is usually sent when the kernel detects some errors or exceptions. For example, when a process accesses an invalid memory address or executes an invalid instruction, the kernel sends a **SIGSEGV** signal to the process.|
+| -1 | SI_QUEUE | The **sigqueue()** function.|This signal is sent by **sigqueue()**, and an additional integer value and a pointer can be carried. It is usually used for advanced communication between processes, such as transferring data or notifying a process that an event occurs.|
+| -2 | SI_TIMER | Timer.|This signal is sent by a timer and is usually used to execute a scheduled task or a periodic task. For example, when a timer expires, the kernel sends a **SIGALRM** signal to the process.|
+| -3 | SI_MESGQ | Message queue.|This signal is sent by a message queue and is usually used for communication across processes. For example, when a process sends a message to a message queue, the kernel sends a **SIGIO** signal to the receiving process.|
+| -4 | SI_ASYNCIO | Asynchronous I/O.|This signal is sent by an asynchronous I/O and is usually used for a non-blocking I/O. For example, when an I/O operation on a file descriptor is complete, the kernel sends a **SIGIO** signal to the process.|
+| -5 | SI_SIGIO | Synchronous I/O.|This signal is sent by an asynchronous I/O and is usually used for a non-blocking I/O. For example, when an I/O operation on a file descriptor is complete, the kernel sends a **SIGIO** signal to the process.|
+| -6 | SI_TKILL | The **tkill()** function.|This signal is sent by the function **tkill()**, which is similar to the function **kill()**. In addition, you can specify the ID of the thread that sends the signal. It is usually used to send a signal to a specified thread in a multithreaded program.|
## Fault Analysis
@@ -356,7 +356,7 @@ OpenFiles: <- FD information of the file opened by the process when the fault
25->/dev/ptmx native object of unknown type 0
26->/dev/ptmx native object of unknown type 0
-HiLog: <- Hilog logs when the fault occurs
+HiLog: <- HiLog logs when the fault occurs
05-06 20:10:51.301 9623 9623 E C03f00/MUSL-SIGCHAIN: signal_chain_handler call 2 rd sigchain action for signal: 11
05-06 20:10:51.306 9623 9623 I C02d11/DfxSignalHandler: DFX_SigchainHandler :: sig(11), pid(9623), tid(9623).
05-06 20:10:51.307 9623 9623 I C02d11/DfxSignalHandler: DFX_SigchainHandler :: sig(11), pid(9623), processName(./crasher_cpp), threadName(crasher_cpp).
@@ -450,7 +450,7 @@ Tid:18257, Name:crasher_cpp <- Thread ID, thread name
**Logs of Custom Information About System Framework Services**
-When a process crashes, the custom maintenance and test information of the system framework service can be printed to help you locate faults. The information can be the string, memory, callback, or stack type. Currently, the ARM64 architecture is supported. Since API 16, the **LastFatalMessage** field carries only the last fatal-level log printed by using HiLog or the last message set by using the **set_fatal_memssage** API of libc before the process crashes. The callback type information and stack type information are moved from the **LastFatalMessage** field to the **ExtraCrashInfo** (Callback) and **ExtraCrashInfo** (Unwindstack) fields, respectively. The following is the core content of the process crash logs archived by DevEco Studio in FaultLog, which contains four types of custom information about system framework services.
+When a process crashes, the custom maintenance and test information of the system framework service can be printed to help you locate faults. The information can be the string, memory, callback, or stack type. Currently, the ARM64 architecture is supported. Since API 18, the **LastFatalMessage** field carries only the last fatal-level log printed by using HiLog or the last message set by using the **set_fatal_message** API of libc before the process crashes. The callback type information and stack type information are moved from the **LastFatalMessage** field to the **ExtraCrashInfo** (Callback) and **ExtraCrashInfo** (Unwindstack) fields, respectively. The following is the core content of the process crash logs archived by DevEco Studio in FaultLog, which contains four types of custom information about system framework services.
- String information:
@@ -497,7 +497,7 @@ When a process crashes, the custom maintenance and test information of the syste
3. Callback information:
- From API 16, the callback information is moved from the **LastFatalMessage** field to the **ExtraCrashInfo(Callback)** field.
+ From API 18, the callback information is moved from the **LastFatalMessage** field to the **ExtraCrashInfo(Callback)** field.
```text
...
@@ -508,7 +508,7 @@ When a process crashes, the custom maintenance and test information of the syste
4. Stack information:
- From API 16, the stack information is moved from the **LastFatalMessage** field to the **ExtraCrashInfo(Unwindstack)** field.
+ From API 18, the callback information is moved from the **LastFatalMessage** field to the **ExtraCrashInfo(Unwindstack)** field.
```text
...
@@ -531,8 +531,8 @@ In application development, you can locate the problematic code in the cppcrash
#### Method 2: SDK llvm-addr2line
-- Obtain the symbol list
- Obtain the .so file with symbols in the crash stack, which should be the same as that of the application or system.
+- Obtain the symbol list.
+ Obtain the .so file with symbols in the crash stack, which should be the same as that of the application or system.
Compiled and built in DevEco Studio, the .so file of dynamic library is generated with symbols by default in **/build/default/intermediates/libs**. You can run the **Linux file** command to check whether the BuildID of two .so files match. Generated by a compiler, BuildID is the unique identifier of a binary file, in which "not stripped" indicates that a symbol table is included.
```text
@@ -540,10 +540,10 @@ In application development, you can locate the problematic code in the cppcrash
libbabel.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, BuildID[sha1]=fdb1b5432b9ea4e2a3d29780c3abf30e2a22da9d, with debug_info, not stripped
```
- Note: The symbol table of the system dynamic library is archived with the version.
+ **Note**: The symbol table of the system dynamic library is archived with the version.
-- Locate the line number using llvm-addr2line
- You can find llvm-addr2line in **[SDK DIR PATH]\OpenHarmony\11\native\llvm\bin**, or you need to search for the path as it varies based on the SDK version.
+- Locate the line number using llvm-addr2line.
+ You can find llvm-addr2line in **[SDK DIR PATH]\OpenHarmony\11\native\llvm\bin**, or you need to search for the path as it varies based on the SDK version.
The sample stack is as follows (part are omitted):
```text
@@ -631,7 +631,7 @@ Procedure:
Obtain the PC address at the top of the stack from the CPPCRASH log file and disassemble the corresponding ELF file (using the unstrip .so file and the **llvm-objdump -d -l xxx.so** command).
- For example, when a **data_abort** issue occurs during the execution of the instruction corresponding to the **00000000000a87e4** address, decompile the libc.so file corresponding to the buildId (**3c3e7fb27680dc2ee99aa08dd0f81e85**).
+ For example, when a **data_abort** issue occurs during the execution of the instruction corresponding to the **00000000000a87e4** address, decompile the libc.so file corresponding to the buildId **3c3e7fb27680dc2ee99aa08dd0f81e85**.
Disassemble the code to view the information displayed in the **a87e4** offset address:
@@ -685,7 +685,7 @@ Procedure:
3. Determine the fault type of the code object.
- Check the memory address near the register in **Memory near registers** in the CPPCRASH log.
+ Check **Memory near registers** in the CPPCRASH log.
```text
x1(/data/medialibrary/database/kvdb/3ddb6fb8b2fcb38d2f431e86bfb806dab771637860d6e86bb9430fa15df04248/single_ver/main/gen_natural_st):
@@ -761,15 +761,15 @@ Procedure:
### Common CppCrash Faults and Causes
-- Null pointer dereference
- When a crash log is in format **SIGSEGV(SEGV_MAPERR)@0x00000000** or the values of the input parameter registers such as **r0** and **r1** printed in the **Register** are **0**, check whether a null pointer is input when invoking a method.
+- Null pointer dereference.
+ When a crash log is in format **SIGSEGV(SEGV_MAPERR)@0x00000000** or the values of the input parameter registers such as **r0** and **r1** printed in the **Register** are **0**, check whether a null pointer is input when invoking a method.
When a crash log is in format **SIGSEGV(SEGV_MAPERR)@0x0000000c** or the value of the input parameter register such as **r1** printed in the **Register** is small, check whether the called structs contain a null pointer.
-- SIGABRT
+- SIGABRT.
Generally, this fault is triggered by the user, framework, or C library, and you can locate the problematic code in the first frame of the framework library. In this case, check whether resources such as thread and file descriptor are properly used, and whether the invoking sequence of APIs is correct.
-- SIGSEGV
- - Multithreading operation collection in STD library is not thread-safe. If the collection is added or deleted on multiple threads, the **SIGSEGV** crash occurs. If **llvm-addr2line** is used and the result code involve operations on collections, this could be the reason for the crash.
+- SIGSEGV.
+ - Multithreading operation collection in STD library is not thread-safe. If the collection is added or deleted on multiple threads, the **SIGSEGV** crash occurs. If **llvm-addr2line** is used and the result code involve operations on collections, this could be the reason for the crash.
- If the pointer does not match the lifecycle of an object, for example, using a raw pointer to store the **sptr** type and **shared_ptr** type, can lead to memory leak and dangling pointer. A raw pointer is a pointer that does not have features such as encapsulation and automatic memory management. It is only a simple pointer to the memory address. The memory to which the pointer points is not protected or managed. A raw pointer can directly access the pointed memory, but problems such as memory leak and null pointer reference may also occur. Therefore, when using a raw pointer, pay attention to potential security problems. You are advised to use smart pointers to manage memory.
-- Use after free
+- Use after free.
This fault occurs when the reference of a released stack variable is not set to null and the access continues.
```text
@@ -812,18 +812,18 @@ Procedure:
}
```
- When a **RecursiveClass** object is created, its constructor is called. When this object is destroyed, its destructor is called. In the destructor, a new **RecursiveClass** object is created, which causes recursive calls until the stack overflows. Recursive calls are infinite. As a result, the stack space is used up and the application crashes.
+ When a **RecursiveClass** object is created, its constructor is called. When this object is destroyed, its destructor is called. In the destructor, a new **RecursiveClass** object is created, which causes recursive calls until the stack overflows. Recursive calls are infinite. As a result, the stack space is used up and the application crashes.
- Binary mismatch usually indicates the mismatch of the Application Binary Interface (ABI). For example, when a compiled binary interface or its data structure definition does not match the ABI, a random crash stack is generated.
- Memory corruption occurs when the memory of a valid wild pointer is changed to an invalid value, which results in out-of-bounds access and data overwrite. In this case, a random crash stack is generated.
-- SIGBUS (Aligment) occurs when the address is in the unaligned state after the pointer is forcibly converted.
+- SIGBUS (Alignment) occurs when the address is in the unaligned state after the pointer is forcibly converted.
- When the length of a function name exceeds 256 bytes, the stack frame does not contain the function name.
- If the ELF file does not contain **.note.gnu.build-id**, the stack frame does not contain the **build-id** information.
## Case Study
-The following analyzes the typical CppCrash cases based on signals, scenarios, and tools respectively.
-The analysis based on signals introduces common crash signals and provides a typical case for each type of signal.
-The analysis based on scenarios concludes a common scenario for frequent problems, and provides a typical case for each scenario.
+The following analyzes the typical CppCrash cases based on signals, scenarios, and tools respectively.
+The analysis based on signals introduces common crash signals and provides a typical case for each type of signal.
+The analysis based on scenarios concludes a common scenario for frequent problems, and provides a typical case for each scenario.
The analysis based on tools describes how to use various maintenance and debugging tools, and provides a typical case for each tool.
### Analyzing CppCrash Based on Signals
@@ -839,7 +839,7 @@ The **SIGSEGV** signal indicates a Segmentation Fault of the program. This fault
In most cases, **SIGSEGV** is caused by pointer overwriting. However, not all pointer overwriting causes **SIGSEGV**. The **SIGSEGV** crash would not be triggered unless an out-of-bounds pointer is dereferenced. In addition, even if an out-of-bounds pointer is dereferenced, the **SIGSEGV** crash may not be caused. The **SIGSEGV** crash involves the operating system, C library, compiler, and linker. The examples are as follows:
-- The memory area is read-only memory.
+- The memory area is read-only memory.
The sample code is as follows:
```text
@@ -855,8 +855,7 @@ In most cases, **SIGSEGV** is caused by pointer overwriting. However, not all po
-- The memory area is out of the process address space.
-
+- The memory area is out of the process address space.
The sample code is as follows:
```text
@@ -900,7 +899,7 @@ In most cases, **SIGSEGV** is caused by pointer overwriting. However, not all po
# 40 pc 00000000000a4b98 /system/lib/ld-musl-aarch64.so.1(libc_start_main_stage2+64)(ff4c94d996663814715bedb2032b2bbc)
```
-3. The memory does not exist.
+3. The memory does not exist.
The sample code is as follows:
```text
@@ -916,7 +915,7 @@ In most cases, **SIGSEGV** is caused by pointer overwriting. However, not all po
-4. Double free.
+4. Double free.
The sample code is as follows:
```text
@@ -940,8 +939,8 @@ In most cases, **SIGSEGV** is caused by pointer overwriting. However, not all po
The **SIGABRT** signal is sent to abort the process. This signal can be called by the process executing **abort()** in C standard library, or it can be sent to the process from outside like other signals.
-- Executing the **abort()** function.
- The sample code is as follows:
+-
+ The sample code of executing the **abort()** function:
```text
static napi_value TriggerCrash(napi_env env, napi_callback_info info)
@@ -956,8 +955,8 @@ The **SIGABRT** signal is sent to abort the process. This signal can be called b
-- Executing the **assert()** function.
- The sample code is as follows:
+-
+ The sample code of executing the **assert()** function:
```text
static napi_value TriggerCrash(napi_env env, napi_callback_info info)
@@ -1049,7 +1048,6 @@ previously allocated by thread T0 (thread name) here:
...
```
-Continue the analysis based on the stack.
When **JsiWeak** is destructed or reset, **CopyableGlobal** in the parent class **JsiType** of its member (**JsiObject**/**JsiValue**/**JsiFunction**) is released, as shown in the following figure.
@@ -1092,7 +1090,7 @@ The **env** created by a thread should not be transferred to another thread.
**Suggestions**
-You can select the **Multi Thread Check** option to locate multi thread faults. For details, see "Ark Multi Thread Check" in guideline.
+You can select the **Multi Thread Check** option to locate multi thread faults. For details, see "Ark Runtime Multi Thread Check" in guideline.
Note: **env** in the **napi** interface is the **arkNativeEngine** when the engine is created.
@@ -1143,13 +1141,13 @@ Add protective null checks for the pointer.
Pointers should be null-checked before using it to prevent null pointers and process crashes and exits.
-### Analyzing CppCrash Based on Tools
+### Analyzing Cpp Crash Based on Tools
#### Tool 1: ASAN
-[ASan Check](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-asan-V5)
+[ASan Check](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-asan-V5).
-#### Tool 2: Ark Multi Thread Check
+#### Tool 2: Ark Runtime Multi Thread Check
**Fundamentals**
@@ -1167,7 +1165,7 @@ If the stack of crash logs is difficult to analyze and the probability of this p
**Cases**
-After the function is enabled, the crash is triggered again. If the problem is caused by multiple threads, fatal information is displayed. The following is an example:
+After the multi thread check is enabled, the crash is triggered again. If the problem is caused by multiple threads, fatal information is displayed. The following is an example:
```text
Fatal: ecma_vm cannot run in multi-thread! thread:xxx currentThread:yyy
@@ -1190,8 +1188,8 @@ Tid:17585, Name:xxxxx
# 06 pc 00000000005d9770 /data/ storage/el1/bundle/libs/arm64/xxxxx.so (c0f1735eada49fadc5197745f5afOc0a52246270)
```
-To analyze the multi-thread problem, perform the following steps:
-i. Check the first stack frame under **libace_napi.z.so**. The preceding figure shows **xxxxx.so**. Check whether the **napi_env** of thread **17688** is transferred to thread **17585**.
+To analyze the multi-thread problem, perform the following steps:
+i. Check the first stack frame under **libace_napi.z.so**. The preceding figure shows **xxxxx.so**. Check whether the **napi_env** of thread **17688** is transferred to thread **17585**.
ii. If the stack frame under **libace_napi.z.so** does not transfer the **napi_env** parameter, check whether the parameter is transferred as a struct member variable.
#### Tool 3: objdump
@@ -1256,5 +1254,5 @@ Registers: x0:0000007f0fe31560 x1:0000000000000003 x2:0000000000000000 x3:000000
x28:0000007f9f21a1c0 x29:00000055a0e19700 lr:0000007f9cb4b584 sp:00000055a0e19700 pc:0000007f9cb492d4
```
-**ldrb w8, [x20]** corresponds to **packedData_.flags_.spaceFlag_** because **packedData_** is the first field of **region**, **flags_** is the first field of **packedData_**, and **spaceFlag_** is the first field of **flags_**. Therefore, the first byte corresponding to the **objectRegion** address is used.
+**ldrb w8, [x20]** corresponds to **packedData_.flags_.spaceFlag_** because **packedData_** is the first field of **region**, **flags_** is the first field of **packedData_**, and **spaceFlag_** is the first field of **flags_**. Therefore, the first byte corresponding to the **objectRegion** address is used.
To view assembly code, you need to be familiar with common assembly instructions and parameter transfer rules. For example, the non-inline member function **r0** in C++ stores the **this** pointer. In addition, due to compiler optimization, the mapping between source code and assembly code may not be clear. The mapping can be quickly obtained based on some feature values (constants) in the code.
diff --git a/en/application-dev/dfx/errormanager-guidelines.md b/en/application-dev/dfx/errormanager-guidelines.md
index f8684acd4ecc6a58b822cfc490247662c7614bd6..9dc23a6d43de6487b288de358d5c4d7ef083e31f 100644
--- a/en/application-dev/dfx/errormanager-guidelines.md
+++ b/en/application-dev/dfx/errormanager-guidelines.md
@@ -23,6 +23,8 @@ Application error management APIs are provided by the [errorManager](../referenc
| off(type: 'globalUnhandledRejectionDetected', observer?: GlobalObserver): void | Unregisters the previously registered callback observer. (**Recommended**) |
| on(type: 'loopObserver', timeout: number, observer: LoopObserver): void12+ | Registers an observer for the message processing duration of the main thread. A callback will be invoked if a main thread jank event occurs. This API can be called only in the main thread. A new observer will overwrite the previous one. |
| off(type: 'loopObserver', observer?: LoopObserver): void12+ | Unregisters the observer for message processing timeouts of the main thread. |
+| on(type: 'freeze', observer: FreezeObserver): void18+ | Registers an observer for the main thread freeze event of the application. This API can be called only in the main thread. A new observer will overwrite the previous one. |
+| off(type: 'freeze', observer?: FreezeObserver): void18+ | Unregisters an observer for the main thread freeze event of the application. This API can be called only in the main thread. |
When an asynchronous callback is used, the return value can be processed directly in the callback. If a promise is used, the return value can also be processed in the promise in a similar way. For details about the result codes, see [Result Codes for Unregistering an Observer](#result-codes-for-unregistering-an-observer).
@@ -250,3 +252,60 @@ export default class EntryAbility extends UIAbility {
}
};
```
+
+### Listening for Main Thread Freeze Exceptions
+
+```ts
+import { AbilityConstant, errorManager, UIAbility, Want } from '@kit.AbilityKit';
+import { window } from '@kit.ArkUI';
+import process from '@ohos.process';
+
+// Define freezeCallback
+function freezeCallback() {
+ console.log("freezecallback");
+}
+
+
+let abilityWant: Want;
+
+export default class EntryAbility extends UIAbility {
+ onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
+ console.log("[Demo] EntryAbility onCreate");
+ errorManager.on("freeze", freezeCallback);
+ abilityWant = want;
+ }
+
+ onDestroy() {
+ console.log("[Demo] EntryAbility onDestroy");
+ errorManager.off("freeze", freezeCallback);
+ }
+
+ onWindowStageCreate(windowStage: window.WindowStage) {
+ // Main window is created, set main page for this ability
+ console.log("[Demo] EntryAbility onWindowStageCreate");
+
+ windowStage.loadContent("pages/index", (err, data) => {
+ if (err.code) {
+ console.error('Failed to load the content. Cause:' + JSON.stringify(err));
+ return;
+ }
+ console.info('Succeeded in loading the content. Data: ' + JSON.stringify(data));
+ });
+ }
+
+ onWindowStageDestroy() {
+ // Main window is destroyed, release UI related resources
+ console.log("[Demo] EntryAbility onWindowStageDestroy");
+ }
+
+ onForeground() {
+ // Ability has brought to foreground
+ console.log("[Demo] EntryAbility onForeground");
+ }
+
+ onBackground() {
+ // Ability has back to background
+ console.log("[Demo] EntryAbility onBackground");
+ }
+};
+```
diff --git a/en/application-dev/dfx/hdc.md b/en/application-dev/dfx/hdc.md
index 797a7f8a83922edffb44089ab1ee174468ac767e..1da120002618b766fb3d3749f6993e22afb35389 100644
--- a/en/application-dev/dfx/hdc.md
+++ b/en/application-dev/dfx/hdc.md
@@ -177,23 +177,23 @@ When multiple devices are connected, use the **-t** parameter to specify the tar
```
**Parameters**
-| Name| Description|
-| -------- | -------- |
-| connect-key| Device ID, which is the return value of the **hdc list targets** command.|
-| command | Command to be executed.|
+ | Name| Description|
+ | -------- | -------- |
+ | connect-key| Device ID, which is the return value of the **hdc list targets** command.|
+ | command | Command to be executed.|
> **NOTE**
>
> The *connect-key* uniquely identifies a device. If the device is connected over the network, the *connect-key* is the IP address and port number. If the device is connected through USB, the *connect-key* is the USB SN.
**Return value**
-| Return Value| Description|
-| -------- | -------- |
-| Command output| Command execution result, which may vary with the command.|
-| [Fail]Not match target founded, check connect-key please | No device matches the *connect-key*.|
-| [Fail]Device not founded or connected | The device is not found or connected.|
-| [Fail]ExecuteCommand need connect-key? please confirm a device by help info | You must specify one device if there are multiple devices available.|
-| Unknown operation command... | The command is not supported.|
+ | Return Value| Description|
+ | -------- | -------- |
+ | Command output| Command execution result, which may vary with the command.|
+ | [Fail]Not match target founded, check connect-key please | No device matches the *connect-key*.|
+ | [Fail]Device not founded or connected | The device is not found or connected.|
+ | [Fail]ExecuteCommand need connect-key? please confirm a device by help info | You must specify one device if there are multiple devices available.|
+ | Unknown operation command... | The command is not supported.|
> **NOTE**
>
@@ -218,9 +218,9 @@ Run the following commands:
```
**Return value**
-| Return Value| Description|
-| -------- | -------- |
-| None| The **hdc wait** command ends when a properly connected device is identified.|
+ | Return Value| Description|
+ | -------- | -------- |
+ | None| The **hdc wait** command ends when a properly connected device is identified.|
**Usage**
@@ -461,29 +461,29 @@ You are advised to enable or disable the USB debugging and network debugging on
## Running the Interactive Command
-The command format is as follows:
+Run the following commands:
```shell
hdc shell [-b bundlename] [command]
```
**Parameters**
-| Parameter| Description|
-| -------- | -------- |
-| [-b _bundlename_] | The bundle name of a debug application. The command is executed in non-interactive mode in the data directory of the debug application.
Currently, this parameter can be used only in non-interactive mode, and the **command** parameter must be specified to enter an interactive shell session.
Otherwise, commands are executed in the system root directory by default.|
-| [command] | A single command to execute on the device. The command varies depending on the system type or version. You can run the **hdc shell ls /system/bin** command to obtain the supported command list. Currently, many commands are provided by [toybox](../tools/toybox.md). You can run the **hdc shell toybox --help** command to obtain the help information.
If this parameter is not specified, hdc starts an interactive shell session, in which you can enter commands such as **ls**, **cd**, and **pwd** at the command prompt.|
+ | Parameter| Description|
+ | -------- | -------- |
+ | [-b _bundlename_] | The bundle name of a debug application. The command is executed in non-interactive mode in the data directory of the debug application.
Currently, this parameter can be used only in non-interactive mode, and the **command** parameter must be specified to enter an interactive shell session.
Otherwise, commands are executed in the system root directory by default.|
+ | [command] | A single command to execute on the device. The command varies depending on the system type or version. You can run the **hdc shell ls /system/bin** command to obtain the supported command list. Currently, many commands are provided by [toybox](../tools/toybox.md). You can run the **hdc shell toybox --help** command to obtain the help information.
If this parameter is not specified, hdc starts an interactive shell session, in which you can enter commands such as **ls**, **cd**, and **pwd** at the command prompt.|
**Return value**
-| Return Value| Description|
-| -------- | -------- |
-| Command execution result| Execution result of the command. For details, see the corresponding command output.|
-| /bin/sh: XXX : inaccessible or not found | The specified command is not supported.|
-| [Fail]Error information| The execution fails. For details, see [hdc Error Codes](#hdc-error-codes).|
+ | Return Value| Description|
+ | -------- | -------- |
+ | Command execution result| Execution result of the command. For details, see the corresponding command output.|
+ | /bin/sh: XXX : inaccessible or not found | The specified command is not supported.|
+ | [Fail]Error information| The execution fails. For details, see [hdc Error Codes](#hdc-error-codes).|
**Usage**
```shell
- # Enter the interactive mode to run a commands
+ # Enter the interactive mode to run a command.
hdc shell
# Run the command in non-interactive mode.
@@ -799,7 +799,7 @@ Port forwarding type supported by the device: TCP, DEV, localabstract, localfile
**Return value**
| Return Value| Description|
| -------- | -------- |
- | Connect server failed | Fails to connect to the server.|
+ | Connect server failed | Fails to connect to the server.|
**Usage**
@@ -1055,7 +1055,7 @@ Port forwarding type supported by the device: TCP, DEV, localabstract, localfile
### Server Logs
-#### Log level
+#### Log Level
Specify the hdc log level. The default value is **LOG_INFO**.
@@ -1064,10 +1064,10 @@ Specify the hdc log level. The default value is **LOG_INFO**.
```
**Parameters**
-| Parameter| Description|
-| -------- | -------- |
-| [level] | Log level.
0: LOG_OFF
1: LOG_FATAL
2: LOG_WARN
3: LOG_INFO
4: LOG_DEBUG
5: LOG_ALL
6: LOG_LIBUSB|
-| command | Command to be executed.|
+ | Parameter| Description|
+ | -------- | -------- |
+ | [level] | Log level.
0: LOG_OFF
1: LOG_FATAL
2: LOG_WARN
3: LOG_INFO
4: LOG_DEBUG
5: LOG_ALL
6: LOG_LIBUSB|
+ | command | Command to be executed.|
> **NOTE**
>
@@ -1075,10 +1075,10 @@ Specify the hdc log level. The default value is **LOG_INFO**.
> 2. You can change only the log levels of the current client and server processes.
**Return value**
-| Return Value| Description|
-| -------- | -------- |
-| Command output| Command execution result, which may vary with the command.|
-| Log information| Logs of the specified level.|
+ | Return Value| Description|
+ | -------- | -------- |
+ | Command output| Command execution result, which may vary with the command.|
+ | Log information| Logs of the specified level.|
**Usage**
@@ -1117,28 +1117,17 @@ hdc -l5 start
The collected logs are stored in the following path.
-| OS| Path
(Version 3.1.0c or later)| Path
(Versions earlier than 3.1.0c)| Remarks|
-| -------- | -------- | -------- | -------- |
-| Windows | %temp%\hdc_logs | %temp% | The following are examples. Replace *Username* with the actual one.
**C:\Users\Username\AppData\Local\Temp\hdc_logs** (Version 3.1.0c or later)
**C:\Users\Username\AppData\Local\Temp** (Versions earlier than 3.1.0c)|
-| Linux | /tmp/hdc_logs | /tmp | - |
-| macOS| $TMPDIR/hdc_logs | $TMPDIR | - |
-
-The hdc_logs folder contains the following types of logs:
-
-|Type| Name Format| Function| Remarks|
-| -------- | -------- | -------- | -------- |
-| Real-time log| hdc.log | Records hdc server logs in real time.| Each time the hdc server is restarted, the original log is renamed and a new **hdc.log** file is recorded.|
-| Temporary historical log| hdc-%Y%m%d-%H%M%S.log | Dumps intermediate files generated during historical log archiving.| For example, **16:18:57.921 on September 19, 2024** is recorded as
**20240919-161857921**.
The temporary log file is stored in the format of **hdc-20240919-161857921.log**.|
-| Archived historical logs| hdc-%Y%m%d-%H%M%S.log.tgz | Compresses and stores historical logs.| The archive file is a compressed file of the **.tgz** type. You can use a decompression tool to obtain the file.
For example, if the name of a temporary historical log file is **hdc-20240919-161857921.log**,
the name of the corresponding archived historical log file is **hdc-20240919-161857921.log.tgz**.
After an archived historical log file is generated, the corresponding temporary historical log file is automatically deleted.|
-| Temporary real-time log| .hdc.cache.log | Records temporary caches generated by real-time logs.| |
+| OS| Path| Remarks|
+| -------- | -------- | -------- |
+| Windows | %temp% | Example: **C:\Users\Username\AppData\Local\Temp**.
Replace *Username* with the actual one.|
+| Linux | /tmp | - |
+| macOS| $TMPDIR | - |
Log-related environment variables
| Environment Variable | Default Value| Description |
|--------------------|-----|--------------------------------|
| OHOS_HDC_LOG_LEVEL | 5 | The log level of the server process.
For details, see [Server Logs](#server-logs). |
-| OHOS_HDC_LOG_LIMIT | 300 | The threshold of the number of log entries.
When the number of log entries exceeds the threshold,
the system automatically starts the log deletion mechanism
to optimize the log storage space.
In the current system, the upper limit of the log storage space is 3 GB,
which cannot be adjusted.|
-
Configure environment variables as follows:
@@ -1156,8 +1145,8 @@ Enable HiLog to obtain the corresponding logs.
```shell
hdc shell hilog -w start // Enable the function of storing HiLog logs.
-hdc shell ls /data/log/hilog // View the stored HilLog logs.
-hdc file recv /data/log/hilog // Obtain the stored HilLog logs (including kernel logs).
+hdc shell ls /data/log/hilog // View the stored HiLog logs.
+hdc file recv /data/log/hilog // Obtain the stored HiLog logs (including kernel logs).
```
## FAQs
@@ -1346,7 +1335,7 @@ The **hdc.exe**/hdc binary file cannot be executed using the CLI.
1. Run the **hdc list targets** command.
2. Check whether **HDC Device** exists in **Device Manager**.
-3. Run the **hdc kill** command to terminate the server, and then run the **hdc -l5 start** command to collect logs. (The **hdc.log** file is stored in the **hdc_logs** folder of the **TEMP** directory on the execution end. The directory location varies with the OS. For details, see [Server Logs](#server-logs).)
+3. Run the **hdc kill** command to terminate the server, and then run the **hdc -l5 start** command to collect logs. (The **hdc.log** file is stored in the **TEMP** directory on the execution end. The directory location varies with the OS. For details, see [Server Logs](#server-logs).)
4. Locate the problem based on the **hdc.log** file.
## hdc Error Codes
diff --git a/en/application-dev/dfx/hiappevent-watcher-apphicollie-events-ndk.md b/en/application-dev/dfx/hiappevent-watcher-apphicollie-events-ndk.md
new file mode 100644
index 0000000000000000000000000000000000000000..21ef34101463ed8e7c14fe9fe921d61cf923a33b
--- /dev/null
+++ b/en/application-dev/dfx/hiappevent-watcher-apphicollie-events-ndk.md
@@ -0,0 +1,326 @@
+# Subscribing to Task execution timeout events (C/C++)
+
+## Available APIs
+
+For details about how to use the APIs (such as parameter usage restrictions and value ranges), see [HiAppEvent](../reference/apis-performance-analysis-kit/_hi_app_event.md#hiappevent).
+
+**Subscription APIs**
+
+| API | Description |
+| ------------------------------------------------------------ | -------------------------------------------- |
+| int OH_HiAppEvent_AddWatcher (HiAppEvent_Watcher *watcher) | Adds a watcher to listen for application events.|
+| int OH_HiAppEvent_RemoveWatcher (HiAppEvent_Watcher *watcher) | Removes a watcher for the specified application events.|
+
+## How to Develop
+
+The following describes how to subscribe to the freeze event triggered by a button click.
+
+1. Create a native C++ project and import the **jsoncpp** file to the project. The directory structure is as follows:
+
+ ```yml
+ entry:
+ src:
+ main:
+ cpp:
+ - json:
+ - json.h
+ - json-forwards.h
+ - types:
+ libentry:
+ - index.d.ts
+ - CMakeLists.txt
+ - napi_init.cpp
+ - jsoncpp.cpp
+ ets:
+ - entryability:
+ - EntryAbility.ets
+ - pages:
+ - Index.ets
+ ```
+
+2. In the **CMakeLists.txt** file, add the source file and dynamic libraries.
+
+ ```cmake
+ # Add the jsoncpp.cpp file, which is used to parse the JSON strings in the subscription events.
+ add_library(entry SHARED napi_init.cpp jsoncpp.cpp)
+ # Add libhiappevent_ndk.z.so, libhilog_ndk.z.so (log output), and libohhicollie.so (HiCollie detection).
+ target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so libohhicollie.so libhiappevent_ndk.z.so)
+ ```
+
+3. Import the dependencies to the **napi_init.cpp** file, and define **LOG_TAG**.
+
+ ```c++
+ #include "napi/native_api.h"
+ #include "json/json.h"
+ #include "hilog/log.h"
+ #include "hiappevent/hiappevent.h"
+
+ #undef LOG_TAG
+ #define LOG_TAG "testTag"
+ ```
+
+4. Subscribe to system events.
+
+ - Watcher of the onReceive type.
+
+ In the **napi_init.cpp** file, define the methods related to the watcher of the **onReceive** type.
+
+ ```c++
+ // Define a variable to cache the pointer to the created watcher.
+ static HiAppEvent_Watcher *systemEventWatcher;
+
+ static void OnReceive(const char *domain, const struct HiAppEvent_AppEventGroup *appEventGroups, uint32_t groupLen) {
+ for (int i = 0; i < groupLen; ++i) {
+ for (int j = 0; j < appEventGroups[i].infoLen; ++j) {
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.domain=%{public}s", appEventGroups[i].appEventInfos[j].domain);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.name=%{public}s", appEventGroups[i].appEventInfos[j].name);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.eventType=%{public}d", appEventGroups[i].appEventInfos[j].type);
+ if (strcmp(appEventGroups[i].appEventInfos[j].domain, DOMAIN_OS) == 0 &&
+ strcmp(appEventGroups[i].appEventInfos[j].name, EVENT_APP_HICOLLIE) == 0) {
+ Json::Value params;
+ Json::Reader reader(Json::Features::strictMode());
+ Json::FastWriter writer;
+ if (reader.parse(appEventGroups[i].appEventInfos[j].params, params)) {
+ auto time = params["time"].asInt64();
+ auto foreground = params["foreground"].asBool();
+ auto bundleVersion = params["bundle_version"].asString();
+ auto processName = params["process_name"].asString();
+ auto pid = params["pid"].asInt();
+ auto uid = params["uid"].asInt();
+ auto uuid = params["uuid"].asString();
+ auto exception = writer.write(params["exception"]);
+ auto hilogSize = params["hilog"].size();
+ auto peerBindSize = params["peer_binder"].size();
+ auto memory = writer.write(params["memory"]);
+ auto externalLog = writer.write(params["external_log"]);
+ auto logOverLimit = params["log_over_limit"].asBool();
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.time=%{public}lld", time);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.foreground=%{public}d", foreground);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.bundle_version=%{public}s", bundleVersion.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.process_name=%{public}s", processName.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.pid=%{public}d", pid);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.uid=%{public}d", uid);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.uuid=%{public}s", uuid.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.exception=%{public}s", exception.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.hilog.size=%{public}d", hilogSize);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.peer_binder.size=%{public}d", peerBindSize);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.memory=%{public}s", memory.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.external_log=%{public}s", externalLog.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.log_over_limit=%{public}d", logOverLimit);
+ }
+ }
+ }
+ }
+ }
+
+ static napi_value RegisterWatcher(napi_env env, napi_callback_info info) {
+ // Set the watcher name. The system identifies different watchers based on their names.
+ systemEventWatcher = OH_HiAppEvent_CreateWatcher("onReceiverWatcher");
+ // Set the event to watch to EVENT_APP_HICOLLIE.
+ const char *names[] = {EVENT_APP_HICOLLIE};
+ // Add the events to watch, for example, system events.
+ OH_HiAppEvent_SetAppEventFilter(systemEventWatcher, DOMAIN_OS, 0, names, 1);
+ // Set the implemented callback. After receiving the event, the watcher immediately triggers the OnReceive callback.
+ OH_HiAppEvent_SetWatcherOnReceive(systemEventWatcher, OnReceive);
+ // Add a watcher to listen for the specified event.
+ OH_HiAppEvent_AddWatcher(systemEventWatcher);
+ return {};
+ }
+ ```
+
+ - Watcher of the **onTrigger** type:
+
+ In the **napi_init.cpp** file, define the methods related to the watcher of the **OnTrigger** type.
+
+ ```c++
+ // Define a variable to cache the pointer to the created watcher.
+ static HiAppEvent_Watcher *systemEventWatcher;
+
+ // Implement the callback function used to return the listened events. The content pointed to by the events pointer is valid only in this function.
+ static void OnTake(const char *const *events, uint32_t eventLen) {
+ Json::Reader reader(Json::Features::strictMode());
+ Json::FastWriter writer;
+ for (int i = 0; i < eventLen; ++i) {
+ Json::Value eventInfo;
+ if (reader.parse(events[i], eventInfo)) {
+ auto domain = eventInfo["domain_"].asString();
+ auto name = eventInfo["name_"].asString();
+ auto type = eventInfo["type_"].asInt();
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.domain=%{public}s", domain.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.name=%{public}s", name.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.eventType=%{public}d", type);
+ if (domain == DOMAIN_OS && name == EVENT_APP_HICOLLIE) {
+ auto time = eventInfo["time"].asInt64();
+ auto foreground = eventInfo["foreground"].asBool();
+ auto bundleVersion = eventInfo["bundle_version"].asString();
+ auto processName = eventInfo["process_name"].asString();
+ auto pid = eventInfo["pid"].asInt();
+ auto uid = eventInfo["uid"].asInt();
+ auto uuid = eventInfo["uuid"].asString();
+ auto exception = writer.write(eventInfo["exception"]);
+ auto hilogSize = eventInfo["hilog"].size();
+ auto peerBindSize = eventInfo["peer_binder"].size();
+ auto memory = writer.write(eventInfo["memory"]);
+ auto externalLog = writer.write(eventInfo["external_log"]);
+ auto logOverLimit = eventInfo["log_over_limit"].asBool();
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.time=%{public}lld", time);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.foreground=%{public}d", foreground);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.bundle_version=%{public}s", bundleVersion.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.process_name=%{public}s", processName.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.pid=%{public}d", pid);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.uid=%{public}d", uid);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.uuid=%{public}s", uuid.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.exception=%{public}s", exception.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.hilog.size=%{public}d", hilogSize);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.peer_binder.size=%{public}d", peerBindSize);
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.memory=%{public}s", memory.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.external_log=%{public}s", externalLog.c_str());
+ OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.params.log_over_limit=%{public}d", logOverLimit);
+ }
+ }
+ }
+ }
+
+ // Implement the subscription callback function to apply custom processing to the obtained event logging data.
+ static void OnTrigger(int row, int size) {
+ // After the callback is received, obtain the specified number of received events.
+ OH_HiAppEvent_TakeWatcherData(systemEventWatcher, row, OnTake);
+ }
+
+ static napi_value RegisterWatcher(napi_env env, napi_callback_info info) {
+ // Set the watcher name. The system identifies different watchers based on their names.
+ systemEventWatcher = OH_HiAppEvent_CreateWatcher("onTriggerWatcher");
+ // Set the event to watch to EVENT_APP_HICOLLIE.
+ const char *names[] = {EVENT_APP_HICOLLIE};
+ // Add the events to watch, for example, system events.
+ OH_HiAppEvent_SetAppEventFilter(systemEventWatcher, DOMAIN_OS, 0, names, 1);
+ // Set the implemented callback function. The callback function will be triggered when the conditions set by OH_HiAppEvent_SetTriggerCondition are met.
+ OH_HiAppEvent_SetWatcherOnTrigger(systemEventWatcher, OnTrigger);
+ // Set the conditions for triggering the subscription callback. For example, trigger this onTrigger callback when the number of new event logs is 1.
+ OH_HiAppEvent_SetTriggerCondition(systemEventWatcher, 1, 0, 0);
+ // Add a watcher to listen for the specified event.
+ OH_HiAppEvent_AddWatcher(systemEventWatcher);
+ return {};
+ }
+ ```
+
+5. Register **RegisterWatcher** as an ArkTS API.
+
+ In the **napi_init.cpp** file, register **RegisterWatcher** as an ArkTS API.
+
+ ```c++
+ static napi_value Init(napi_env env, napi_value exports)
+ {
+ napi_property_descriptor desc[] = {
+ { "registerWatcher", nullptr, RegisterWatcher, nullptr, nullptr, nullptr, napi_default, nullptr },
+ };
+ napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+ return exports;
+ }
+ ```
+
+ In the **index.d.ts** file, define the ArkTS API.
+
+ ```typescript
+ export const registerWatcher: () => void;
+ ```
+
+6. Register **TestHiCollieTimerNdk** as an ArkTS API.
+
+ In the **napi_init.cpp** file, register **testHiCollieTimerNdk** as an ArkTS API.
+
+ ```c++
+ static napi_value Init(napi_env env, napi_value exports)
+ {
+ napi_property_descriptor desc[] = {
+ { "registerWatcher", nullptr, RegisterWatcher, nullptr, nullptr, nullptr, napi_default, nullptr },
+ { "testHiCollieTimerNdk", nullptr, TestHiCollieTimerNdk, nullptr, nullptr, nullptr, napi_default, nullptr },
+ };
+ napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+ return exports;
+ }
+
+ // Import the hicollie.h file.
+ #include "hicollie/hicollie.h"
+ static napi_value TestHiCollieTimerNdk(napi_env env, napi_value exports)
+ {
+ // Define the task execution timeout ID.
+ int id;
+ // Define the task timeout detection parameters. When a task times out for 1s, logs are generated.
+ HiCollie_SetTimerParam param = {"testTimer", 1, nullptr, nullptr, HiCollie_Flag::HICOLLIE_FLAG_LOG};
+ // Set the detection.
+ HiCollie_ErrorCode = OH_HiCollie_SetTimer(param, &id);
+ if (errorCode == HICOLLIE_SUCCESS) {
+ OH_LOG_INFO(LogType::LOG_APP, "Timer Id is %{public}d", id);
+ // Construct a timeout interval of 2s.
+ sleep(2);
+ OH_HiCollie_CancelTimer(id);
+ }
+ return 0;
+ }
+ ```
+
+7. In the **EntryAbility.ets** file, add the following API to **onCreate()**.
+
+ ```typescript
+ // Import the dependent module.
+ import testNapi from 'libentry.so'
+
+ // Add the API to onCreate().
+ // Register the system event watcher at startup.
+ testNapi.registerWatcher();
+ ```
+
+8. In the **Index.ets** file, add a button to trigger the task execution timeout event.
+
+ ```typescript
+ Button("testHiCollieTimerNdk")
+ .fontSize(50)
+ .fontWeight(FontWeight.Bold)
+ .onClick(testNapi.testHiCollieTimerNdk);
+ ```
+
+9. In DevEco Studio, click the **Run** button to run the project. Then, click the **testHiCollieTimerNdk** button to trigger a task execution timeout event.
+
+10. The application crashes. After restarting the application, you can view the following event information in the **Log** window.
+
+ ```text
+ HiAppEvent eventInfo.domain=OS
+ HiAppEvent eventInfo.name=APP_HICOLLIE
+ HiAppEvent eventInfo.eventType=1
+ HiAppEvent eventInfo.params.time=1740993639620
+ HiAppEvent eventInfo.params.foreground=1
+ HiAppEvent eventInfo.params.bundle_version=1.0.0
+ HiAppEvent eventInfo.params.process_name=com.example.myapplication
+ HiAppEvent eventInfo.params.pid=26251
+ HiAppEvent eventInfo.params.uid=20020172
+ HiAppEvent eventInfo.params.uuid=4e5d7d0e18f5d6d84cf4f0c9e80d66d0b646c1cc2343d3595f07abb0d3547feb
+ HiAppEvent eventInfo.params.exception={"message":"","name":"APP_HICOLLIE"}
+ HiAppEvent eventInfo.params.hilog.size=77
+ HiAppEvent eventInfo.params.peer_binder.size=18
+ HiAppEvent eventInfo.params.threads.size=28
+ HiAppEvent eventInfo.params.memory={"pss":0,"rss":124668,"sys_avail_mem":2220032,"sys_free_mem":526680,"sys_total_mem":11692576,"vss":4238700}
+ HiAppEvent eventInfo.params.external_log=["/data/storage/el2/log/hiappevent/APP_HICOLLIE_1740993644458_26215.log"]
+ HiAppEvent eventInfo.params.log_over_limit=0
+ ```
+
+11. Remove the event watcher.
+
+ ```c++
+ static napi_value RemoveWatcher(napi_env env, napi_callback_info info) {
+ // Remove the watcher.
+ OH_HiAppEvent_RemoveWatcher(systemEventWatcher);
+ return {};
+ }
+ ```
+
+12. Destroy the event watcher.
+
+ ```c++
+ static napi_value DestroyWatcher(napi_env env, napi_callback_info info) {
+ // Destroy the created watcher and set systemEventWatcher to nullptr.
+ OH_HiAppEvent_DestroyWatcher(systemEventWatcher);
+ systemEventWatcher = nullptr;
+ return {};
+ }
+ ```
diff --git a/en/application-dev/dfx/hiappevent-watcher-apphicollie-events.md b/en/application-dev/dfx/hiappevent-watcher-apphicollie-events.md
new file mode 100644
index 0000000000000000000000000000000000000000..70826f977ef29165937c1070d808831be492c7cd
--- /dev/null
+++ b/en/application-dev/dfx/hiappevent-watcher-apphicollie-events.md
@@ -0,0 +1,43 @@
+# Task Execution Timeout Event Overview
+
+HiAppEvent provides APIs for subscribing to task execution timeout events.
+
+- [Subscribing to Task Execution Timeout Events (C/C++)](hiappevent-watcher-apphicollie-events-ndk.md)
+
+The **params** parameter in the event information is described as follows:
+
+**params**
+
+| Name | Type | Description |
+| ------- | ------ | ------------------------- |
+| time | number | Event triggering time, in ms.|
+| foreground | boolean | Whether the application is running in the foreground.|
+| bundle_version | string | Application version.|
+| process_name | string | Process name of the application.|
+| pid | number | Process ID of the application.|
+| uid | number | User ID of the application.|
+| uuid | string | Error ID.|
+| exception | object | Exception information. For details, see **exception**.|
+| hilog | string[] | Log information.|
+| peer_binder | string[] | Binder call, binder call chain, and related stack capture information.|
+| memory | object | Memory information. For details, see **memory**.|
+| external_log | string[] | Path of the error log file. If the directory files exceed the threshold (for details, see **log_over_limit**), new log files may fail to be written. Therefore, delete the log files immediately after they are processed.|
+| log_over_limit | boolean | Whether the size of generated fault log files and existing log files exceeds the upper limit (5 MB). The value **true** indicates that the upper limit is exceeded and logs fail to be written. The value **false** indicates that the upper limit is not exceeded.|
+
+**exception**
+
+| Name | Type | Description |
+| ------- | ------ | ------------------------- |
+| name | string | Exception type.|
+| message | string | Exception cause.|
+
+**memory**
+
+| Name | Type | Description |
+| ------- | ------ | ------------------------- |
+| rss | number | Size of the memory allocated for a process, in KB.|
+| vss | number | Size of the virtual memory applied by a process from the system, in KB.|
+| pss | number | Size of the physical memory actually used by a process, in KB.|
+| sys_free_mem | number | Size of free memory, in KB.|
+| sys_avail_mem | number | Size of available memory, in KB.|
+| sys_total_mem | number | Total memory size, in KB.|
diff --git a/en/application-dev/dfx/hiappevent-watcher-crash-events-arkts.md b/en/application-dev/dfx/hiappevent-watcher-crash-events-arkts.md
index 93c2b84d7a37debeb50ea796eb901e131a4d44e4..311252e471472db6459f798b61ba6fdfc47fc927 100644
--- a/en/application-dev/dfx/hiappevent-watcher-crash-events-arkts.md
+++ b/en/application-dev/dfx/hiappevent-watcher-crash-events-arkts.md
@@ -111,7 +111,10 @@ The following describes how to subscribe to a crash event triggered by a button
5. In DevEco Studio, click the **Run** button to run the project. Then, click the **appCrash** button to trigger a crash event. After a crash occurs, the system uses different stack backtracking methods to generate crash logs based on the crash type (JsError or NativeCrash) and then invokes callback. The NativeCrash stack backtracking takes about 2s. In practice, the duration depends on the number of service threads and the duration of inter-process communication. JsError triggers in-process stack backtracking, and NativeCrash triggers out-of-process stack backtracking. Therefore, NativeCrash stack backtracking is more time-consuming than JsError stack backtracking. You can subscribe to crash events so that the stack backtracking result is asynchronously reported without blocking the current service.
-6. When the application is restarted, HiAppEvent reports the crash event to the registered watcher. You can view the following event information in the **Log** window.
+6. If the application does not capture the crash event, the application exits after the system crashes. When the application is restarted, HiAppEvent reports the crash event to the registered watcher.
+
If the application captures the crash event. HiAppEvent reports the event before the application exits in the following scenarios:
+
Scenario 1: The application does not exit during exception handling. For example, when [errorManger.on](../reference/apis-ability-kit/js-apis-app-ability-errorManager.md#errormanageronerror) is used to capture JsError, the application registers the NativeCrash signal processing function and does not exit.
Scenario 2: Exception handling takes a long time, and the application exit time is delayed.
+
After HiAppEvent reports the event, you can view the processing logs of the system event data in the **Log** window.
```text
HiAppEvent onReceive: domain=OS
diff --git a/en/application-dev/dfx/hiappevent-watcher-crash-events-ndk.md b/en/application-dev/dfx/hiappevent-watcher-crash-events-ndk.md
index 3ef89f18ae499da6c93491d1d5f1db39b1a515f0..8a8bb8503e656efcb1dc61215272ea9cd45b71f8 100644
--- a/en/application-dev/dfx/hiappevent-watcher-crash-events-ndk.md
+++ b/en/application-dev/dfx/hiappevent-watcher-crash-events-ndk.md
@@ -246,7 +246,10 @@ The following describes how to subscribe to the crash event triggered by a butto
8. In DevEco Studio, click the **Run** button to run the project. Then, click the **appCrash** button to trigger a crash event. After a crash occurs, the system uses different stack backtracking methods to generate crash logs based on the crash type (JsError or NativeCrash) and then invokes callback. The NativeCrash stack backtracking takes about 2s. In practice, the duration depends on the number of service threads and the duration of inter-process communication. JsError triggers in-process stack backtracking, and NativeCrash triggers out-of-process stack backtracking. Therefore, NativeCrash stack backtracking is more time-consuming than JsError stack backtracking. You can subscribe to crash events so that the stack backtracking result is asynchronously reported without blocking the current service.
-9. When the application is started next time, HiAppEvent reports the crash event to the registered watcher. You can view the processing logs of system event data in the **Log** window.
+9. If the application does not capture the crash event, the application exits after the system crashes. When the application is restarted, HiAppEvent reports the crash event to the registered watcher.
+
If the application captures the crash event. HiAppEvent reports the event before the application exits in the following scenarios:
+
Scenario 1: The application does not exit during exception handling. For example, when [errorManger.on](../reference/apis-ability-kit/js-apis-app-ability-errorManager.md#errormanageronerror) is used to capture JsError, the application registers the NativeCrash signal processing function and does not exit.
Scenario 2: Exception handling takes a long time, and the application exit time is delayed.
+
After HiAppEvent reports the event, you can view the processing logs of the system event data in the **Log** window.
```text
HiAppEvent eventInfo.domain=OS
diff --git a/en/application-dev/dfx/hiappevent-watcher-crash-events.md b/en/application-dev/dfx/hiappevent-watcher-crash-events.md
index 1dc2f8a6aa53bf6e0e7d1889806e4be9f47d9313..c62b342ae44148550e929881ccf1b90214f2befd 100644
--- a/en/application-dev/dfx/hiappevent-watcher-crash-events.md
+++ b/en/application-dev/dfx/hiappevent-watcher-crash-events.md
@@ -47,9 +47,9 @@ The **params** parameter in the event information is described as follows.
| Name | Type | Description |
| ------- | ------ | ------------------------- |
-| signo | number | Signal value (**si_signo** in **siginfo_t**)|
-| code | number | Level-2 classification of signal values (**si_code** in **siginfo_t**)|
-| address | string | Signal error address (**si_address** attribute in **siginfo_t**)|
+| signo | number | Signal value (**si_signo** in **siginfo_t**).|
+| code | number | Level-2 classification of signal values (**si_code** in **siginfo_t**).|
+| address | string | Signal error address (**si_address** attribute in **siginfo_t**).|
[Signal Value & Level-2 Classification of Signal Values](cppcrash-guidelines.md)
diff --git a/en/application-dev/dfx/hiappevent-watcher-mainthreadjank-events-arkts.md b/en/application-dev/dfx/hiappevent-watcher-mainthreadjank-events-arkts.md
index 4877cbbe4e9c31331ec609aa323fbc399369c69a..2f2a9f96eccffbb3609d18221aa062fd77102af1 100644
--- a/en/application-dev/dfx/hiappevent-watcher-mainthreadjank-events-arkts.md
+++ b/en/application-dev/dfx/hiappevent-watcher-mainthreadjank-events-arkts.md
@@ -148,7 +148,7 @@ The following describes how to subscribe to the main thread jank event in sampli
// The number of event reporting times.
"report_times_per_app": "3",
};
- hiAppEvent.setEventConfig("MAIN_THREAD_JANK", params).then(() => {
+ hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => {
hilog.info(0x0000, 'testTag', `HiAppEvent success to set event params.`)
}).catch((err: BusinessError) => {
hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`)
diff --git a/en/application-dev/dfx/hiappevent-watcher-resourceleak-events-ndk.md b/en/application-dev/dfx/hiappevent-watcher-resourceleak-events-ndk.md
index f7692264f694b44db67cd81cc9ae2a7b55575a6f..59812255573e2aef93324c4a15b237a430686979 100644
--- a/en/application-dev/dfx/hiappevent-watcher-resourceleak-events-ndk.md
+++ b/en/application-dev/dfx/hiappevent-watcher-resourceleak-events-ndk.md
@@ -123,6 +123,9 @@ For details about how to use the APIs (such as parameter usage restrictions and
In the **napi_init.cpp** file, define the methods related to the watcher of the OnTrigger type.
```c++
+ // Define a variable to cache the pointer to the created watcher.
+ static HiAppEvent_Watcher *systemEventWatcher;
+
// Implement the callback function used to return the listened events. The content pointed to by the events pointer is valid only in this function.
static void OnTake(const char *const *events, uint32_t eventLen) {
Json::Reader reader(Json::Features::strictMode());
diff --git a/en/application-dev/dfx/hichecker-guidelines-arkts.md b/en/application-dev/dfx/hichecker-guidelines-arkts.md
index df2b9d048599d5aa3d8bb432230d831f664e9bf7..d9d5c3691deffb67f5a546ec419e94646acee67c 100644
--- a/en/application-dev/dfx/hichecker-guidelines-arkts.md
+++ b/en/application-dev/dfx/hichecker-guidelines-arkts.md
@@ -10,8 +10,7 @@ HiChecker is provided to check issues that may be easily ignored during applicat
## Working Principles
-1. The application calls HiChecker APIs to add, remove, query, and modify rules.
-
+1. The application calls HiChecker APIs to add, remove, query, and modify rules. \n
2. When a time-consuming call or ability resource leakage occurs, HiChecker reports an event based on the rule triggered.
## Constraints
diff --git a/en/application-dev/dfx/hicollie-guidelines-ndk.md b/en/application-dev/dfx/hicollie-guidelines-ndk.md
index 8dae16baeeecb395cceeeb5a7bbee7a7f9838dd2..5643113881bcb058b6d11203eaeefbe091ac0dfc 100644
--- a/en/application-dev/dfx/hicollie-guidelines-ndk.md
+++ b/en/application-dev/dfx/hicollie-guidelines-ndk.md
@@ -1,27 +1,29 @@
# Using HiCollie to Detect Service Thread Stuck and Jank Events (C/C++)
+## Overview
+
HiCollie provides APIs for detecting service thread stuck and jank events and reporting stuck events.
## Availability APIs
+
| API | Description |
| ------------------------------- | --------------------------------- |
| OH_HiCollie_Init_StuckDetection | Registers a callback to periodically detect service thread stuck events. |
-| OH_HiCollie_Init_JankDetection | Registers a callback to detect service thread jank events. To monitor thread jank events, you should implement two callbacks as instrumentation functions, placing them before and after the service thread processing event. |
+| OH_HiCollie_Init_StuckDetectionWithTimeout | Registers a callback to periodically detect service thread stuck events. You can set the detection time.|
+| OH_HiCollie_Init_JankDetection | Registers a callback to detect service thread jank events. To monitor service thread jank events, you can implement two callbacks as instrumentation functions, placing them before and after the service thread event. |
| OH_HiCollie_Report | Reports service thread stuck events and generates timeout logs to help locate application timeout events. This API is used together with **OH_HiCollie_Init_StuckDetection()**, which initializes the stuck event detection at first, and then **OH_HiCollie_Report()** reports the stuck event when it occurs.|
-> **NOTE**
->
-> The service thread stuck faultlog starts with **appfreeze-** and is generated in **Device/data/log/faultlog/faultlogger/**. The log files are named in the format of **appfreeze-application bundle name-application UID-time (seconds)**. For details, see [appfreeze Log Analysis](./appfreeze-guidelines.md#appfreeze-log-analysis).
->
-> For details about the specifications of service thread jank event logs, see [Main Thread Jank Event Specifications](./hiappevent-watcher-mainthreadjank-events.md#main-thread-jank-event-specifications).
+The usage of HiCollie:
-
-For details (such as parameter usage and value ranges), see [HiCollie](../reference/apis-performance-analysis-kit/_hi_hicollie.md).
+- For details (such as parameter usage and value ranges), see [HiCollie](../reference/apis-performance-analysis-kit/_hi_collie.md).
+- The service thread stuck faultlog starts with **appfreeze-** and is generated in **Device/data/log/faultlog/faultlogger/**. The log files are named in the format of **appfreeze-application bundle name-application UID-time (seconds)**. For details, see [appfreeze Log Analysis](./appfreeze-guidelines.md#appfreeze-log-analysis).
+- For details about the specifications of service thread jank event logs, see [Main Thread Jank Event Specifications](./hiappevent-watcher-mainthreadjank-events.md#main-thread-jank-event-specifications).
## How to Develop
+
The following describes how to add a button in the application and click the button to call the HiCollie APIs.
-1. Create a native C++ project and import the **jsoncpp** file to the project. The directory structure is as follows:
+1. Create a native C++ project. The directory structure is as follows:
```yml
entry:
@@ -47,169 +49,402 @@ The following describes how to add a button in the application and click the but
target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so libohhicollie.so)
```
-3. Import the dependencies to the **napi_init.cpp** file, and define **LOG_TAG** and the test method.
-
- ```c++
- #include "napi/native_api.h"
- #include "hilog/log.h"
- #include "hicollie/hicollie.h"
- #include
- #include
- #include
- #include
-
- #undef LOG_TAG
- #define LOG_TAG "testTag"
-
- static OH_HiCollie_BeginFunc beginFunc_; // Define the callback object used before the processing event.
- static OH_HiCollie_EndFunc endFunc_; // Define the callback object used after the processing event.
- HiCollie_DetectionParam param {.sampleStackTriggerTime = 150, .reserved = 0}; // Define a struct.
- int64_t lastWatchTime = 0; // Record the last detection time.
- const int64_t CHECK_INTERNAL_TIME = 3000; // Set the detection interval.
- std::shared_ptr> isReport = std::make_shared>(false); // Set the flag for reporting stuck events.
- int count = 0; // Record the first initialization.
- bool needReport = false; // Set whether to report the stuck events.
-
- // Define the callback.
- void InitBeginFunc(const char* eventName)
- {
- std::string str(eventName);
- OH_LOG_INFO(LogType::LOG_APP, "InitBeginFunc eventName: %{public}s", str.c_str());
- }
- void InitEndFunc(const char* eventName)
- {
- std::string str(eventName);
- OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_EndFunc eventName: %{public}s", str.c_str());
- }
- // Define the callback of the subthread.
- void TestJankDetection()
- {
- beginFunc_ = InitBeginFunc; // Initialize the callback.
- endFunc_ = InitEndFunc;
- int initResult = OH_HiCollie_Init_JankDetection(&beginFunc_, &endFunc_, param); // Initialize the function for detecting thread jank events.
- OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Init_JankDetection: %{public}d", initResult); // Display the success result 0.
- int count = 0;
- while (count < 2) {
- beginFunc_("TestBegin"); // Set the callback used to record the start time of the processing event.
- usleep(350 * 1000); // Simulate a thread jank event by putting the thread to sleep for 350 ms.
- endFunc_("TestEnd"); // Set the callback used to record the end time of the processing event.
- count++;
- }
- }
+3. Import the dependencies to the **napi_init.cpp** file, and define **LOG_TAG**. The following code steps are used to simulate the jank and stuck scenarios. Use the code based on service requirements. The sample code is as follows:
- static napi_value TestHiCollieJankNdk(napi_env env, napi_callback_info info)
- {
- std::thread threadObj(TestJankDetection); // Create a subthread.
- threadObj.join(); // Execute the callback.
- return 0;
- }
+ (1) **OH_HiCollie_Init_JankDetection**:
- int64_t GetCurrentTime()
- {
- return std::chrono::duration_cast(std::chrono::
- system_clock::now().time_since_epoch()).count();
- }
+ ```c++
+ #include
+ #include
+ #include
+ #include
+ #include "napi/native_api.h"
+ #include "hilog/log.h"
+ #include "hicollie/hicollie.h"
+
+ #undef LOG_TAG
+ #define LOG_TAG "JankTest"
+
+ //Define two callback objects.
+ static OH_HiCollie_BeginFunc beginFunc_;
+ static OH_HiCollie_EndFunc endFunc_;
+
+ //Define the callbacks for monitoring application display start and end.
+ void InitBeginFunc(const char* eventName)
+ {
+ std::string str(eventName);
+ OH_LOG_INFO(LogType::LOG_APP, "InitBeginFunc eventName: %{public}s", str.c_str());
+ }
+ void InitEndFunc(const char* eventName)
+ {
+ std::string str(eventName);
+ OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_EndFunc eventName: %{public}s", str.c_str());
+ }
- bool ReportEvent()
- {
- if ((GetCurrentTime() - lastWatchTime) > CHECK_INTERNAL_TIME) {
- return true;
+ void StartDelayTimer()
+ {
+ //Wait for 10s.
+ std::chrono::seconds delay(10);
+ OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Init_JankDetection delay before");
+ std::this_thread::sleep_for(delay);
+ OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Init_JankDetection delay after");
+ }
+
+ // Define the callback of the subthread.
+ void TestJankDetection()
+ {
+ // Initialize the callback parameters.
+ beginFunc_ = InitBeginFunc;
+ endFunc_ = InitEndFunc;
+ HiCollie_DetectionParam param {0};
+ // Initialize the thread jank detection function.
+ int initResult = OH_HiCollie_Init_JankDetection(&beginFunc_, &endFunc_, param);
+ // Set the thread to be not detected within 10s after being started.
+ StartDelayTimer();
+ // Success result: 0
+ OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Init_JankDetection: %{public}d", initResult);
+ int count = 0;
+ while (count < 3) {
+ // Set the callback used to record the start time of the processing event.
+ beginFunc_("TestBegin");
+ // Simulate a thread jank event by putting the thread to sleep for 350 ms.
+ usleep(350 * 1000);
+ // Set the callback used to record the end time of the processing event.
+ endFunc_("TestEnd");
+ count++;
}
- return false;
+ }
+
+ static napi_value TestHiCollieJankNdk(napi_env env, napi_callback_info info)
+ {
+ // Create a subthread.
+ std::thread threadObj(TestJankDetection);
+ // Execute the TestJankDetection task.
+ threadObj.detach();
+ return 0;
+ }
+
+ EXTERN_C_START
+ static napi_value Init(napi_env env, napi_value exports)
+ {
+ napi_property_descriptor desc[] = {
+ { "testHiCollieJankNdk", nullptr, TestHiCollieJankNdk, nullptr, nullptr, nullptr, napi_default, nullptr },
+ };
+ napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+ return exports;
+ }
+ EXTERN_C_END
+
+ 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);
+ }
+ ```
+
+ (2) **OH_HiCollie_Init_StuckDetection**:
+
+ ```c++
+ #include "napi/native_api.h"
+ #include "hilog/log.h"
+ #include "hicollie/hicollie.h"
+ #include
+ #include
+ #include
+
+ #undef LOG_TAG
+ #define LOG_TAG "StruckTest"
+
+ // Check whether the thread is running properly. The value 1 indicates that the thread is running properly, and the value 0 indicates that the thread is stuck.
+ const int64_t CHECK_BUSSINESS_THREAD_IS_ALIVE = 1;
+ // Simulate a thread stuck event by putting the thread to sleep for a custom time.
+ const int64_t BLOCK_TIME = 3;
+ // Set the task execution status flag of the application thread. The value true indicates the thread is normal and the value false indicates the thread is stuck.
+ std::shared_ptr> appThreadIsAlive_ = std::make_shared>(true);
+ // Set the flag for reporting the application thread stuck event.
+ std::shared_ptr> isSixSecondEvent_ = std::make_shared>(false);
+
+ void ReportEvent() {
+ bool temp = isSixSecondEvent_->load();
+ int reportResult = OH_HiCollie_Report(&temp);
+ // Success result: 0
+ OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Report: %{public}d, isSixSecondEvent: %{public}d", reportResult, isSixSecondEvent_->load());
+ isSixSecondEvent_->store(temp);
+ }
+
+ void SetTimeout()
+ {
+ int64_t now = std::chrono::duration_cast(std::chrono::
+ system_clock::now().time_since_epoch()).count();
+ sleep(BLOCK_TIME);
+ int64_t currentTime = std::chrono::duration_cast(std::chrono::
+ system_clock::now().time_since_epoch()).count();
+ if (currentTime - now < BLOCK_TIME) {
+ appThreadIsAlive_->store(true);
+ return;
}
+ appThreadIsAlive_->store(false);
+ }
- void TestTask()
- {
- if (needReport && ReportEvent()) {
- bool temp = isReport->load();
- int reportResult = OH_HiCollie_Report(&temp);
- OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Report: %{public}d", reportResult); // Display the success result 0.
- OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Report isReport: %{public}d", temp);
- needReport = false;
- }
- int64_t now = GetCurrentTime();
- if ((now - lastWatchTime) >= (CHECK_INTERNAL_TIME / 2)) {
- lastWatchTime = now;
- }
+ // You can customize periodic detection tasks.
+ void Timer()
+ {
+ // Check whether the application thread runs properly every 3 seconds.
+ if (appThreadIsAlive_->load()) {
+ OH_LOG_INFO(LogType::LOG_APP, "Check appThread isAlive.");
+ // Update appThreadIsAlive_. The value true indicates that the application thread runs properly.
+ appThreadIsAlive_->store(false);
+ // Simulate a timeout scenario.
+ SetTimeout();
+ return;
}
+ ReportEvent();
+ }
- // Define the callback of the subthread.
- void TestStuckDetection()
- {
- int initResult = -1;
- if(count == 0) {
- initResult = OH_HiCollie_Init_StuckDetection(TestTask); // Initialize the function for detecting thread stuck events.
- OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Init_StuckDetection: %{public}d", initResult); // Display the success result 0.
- count++;
- }
+ // Define the callback of the subthread.
+ void InitStuckDetection()
+ {
+ // Initialize the thread stuck detection function.
+ int initResult = OH_HiCollie_Init_StuckDetection(Timer);
+ // Success result: 0
+ OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Init_StuckDetection: %{public}d", initResult);
+ }
+
+ static napi_value TestHiCollieStuckNdk(napi_env env, napi_callback_info info)
+ {
+ // Create a subthread.
+ std::thread threadObj(InitStuckDetection);
+ // Execute a task.
+ threadObj.join();
+ return 0;
+ }
+
+ EXTERN_C_START
+ static napi_value Init(napi_env env, napi_value exports)
+ {
+ napi_property_descriptor desc[] = {
+ { "testHiCollieStuckNdk", nullptr, TestHiCollieStuckNdk, nullptr, nullptr, nullptr, napi_default, nullptr },
+ };
+ napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+ return exports;
+ }
+ EXTERN_C_END
+
+ 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);
+ }
+ ```
+
+ (3) **OH_HiCollie_Init_StuckDetectionWithTimeout**:
+
+ ```c++
+ #include "napi/native_api.h"
+ #include "hilog/log.h"
+ #include "hicollie/hicollie.h"
+ #include
+ #include
+ #include
+
+ #undef LOG_TAG
+ #define LOG_TAG "StruckTest"
+
+ // Check whether the thread is running properly. The value 1 indicates that the thread is running properly, and the value 0 indicates that the thread is stuck.
+ const int64_t CHECK_BUSSINESS_THREAD_IS_ALIVE = 1;
+ // Simulate a thread stuck event by putting the thread to sleep for a custom time.
+ const int64_t BLOCK_TIME = 5;
+ // Set the task execution status flag of the application thread. The value true indicates the thread is normal and the value false indicates the thread is stuck.
+ std::shared_ptr> appThreadIsAlive_ = std::make_shared>(true);
+ // Set the flag for reporting the application thread stuck event.
+ std::shared_ptr> isSixSecondEvent_ = std::make_shared>(false);
+
+ void ReportEvent() {
+ bool temp = isSixSecondEvent_->load();
+ int reportResult = OH_HiCollie_Report(&temp);
+ // Success result: 0
+ OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Report: %{public}d, isSixSecondEvent: %{public}d", reportResult, isSixSecondEvent_->load());
+ isSixSecondEvent_->store(temp);
+ }
+
+ void SetTimeout()
+ {
+ int64_t now = std::chrono::duration_cast(std::chrono::
+ system_clock::now().time_since_epoch()).count();
+ sleep(BLOCK_TIME);
+ int64_t currentTime = std::chrono::duration_cast(std::chrono::
+ system_clock::now().time_since_epoch()).count();
+ if (currentTime - now < BLOCK_TIME) {
+ appThreadIsAlive_->store(true);
+ return;
}
- static napi_value TestHiCollieStuckNdk(napi_env env, napi_callback_info info)
- {
- std::thread threadObj(TestStuckDetection); // Create a subthread.
- threadObj.join(); // Execute the callback.
- return 0;
+ appThreadIsAlive_->store(false);
+ }
+
+ // You can customize periodic detection tasks.
+ void Timer()
+ {
+ // Check whether the application thread runs properly every 5 seconds.
+ if (appThreadIsAlive_->load()) {
+ OH_LOG_INFO(LogType::LOG_APP, "Check appThread isAlive.");
+ // Update appThreadIsAlive_. The value true indicates that the application thread runs properly.
+ appThreadIsAlive_->store(false);
+ // Simulate a timeout scenario.
+ SetTimeout();
+ return;
}
- ```
+ ReportEvent();
+ }
+
+ // Define the callback of the subthread.
+ void InitStuckDetectionWithTimeout()
+ {
+ // Initialize the thread stuck detection function.
+ int initResult = OH_HiCollie_Init_StuckDetectionWithTimeout(Timer, BLOCK_TIME);
+ // Success result: 0
+ OH_LOG_INFO(LogType::LOG_APP, "OH_HiCollie_Init_StuckDetection: %{public}d", initResult);
+ }
+
+ static napi_value TestHiCollieStuckWithTimeoutNdk(napi_env env, napi_callback_info info)
+ {
+ // Create a subthread.
+ std::thread threadObj(InitStuckDetectionWithTimeout);
+ // Execute a task.
+ threadObj.join();
+ return 0;
+ }
+
+ EXTERN_C_START
+ static napi_value Init(napi_env env, napi_value exports)
+ {
+ napi_property_descriptor desc[] = {
+ { "testHiCollieStuckWithTimeoutNdk", nullptr, TestHiCollieStuckWithTimeoutNdk, nullptr, nullptr, nullptr, napi_default, nullptr },
+ };
+ napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+ return exports;
+ }
+ EXTERN_C_END
+
+ 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. Register **TestHiCollieNdk** as an ArkTS API.
- In the **napi_init.cpp** file, register **TestHiCollieNdk** as an ArkTS API.
-
- ```c++
- static napi_value Init(napi_env env, napi_value exports)
- {
- napi_property_descriptor desc[] = {
- { "testHiCollieJankNdk", nullptr, TestHiCollieJankNdk, nullptr, nullptr, nullptr, napi_default, nullptr },
- { "testHiCollieStuckNdk", nullptr, TestHiCollieStuckNdk, nullptr, nullptr, nullptr, napi_default, nullptr }};
- };
- napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
- return exports;
- }
- ```
+ (1) **OH_HiCollie_Init_JankDetection**:
- In the **index.d.ts** file, define the ArkTS API.
+ ```typescript
+ export const testHiCollieJankNdk: () => void;
+ ```
- ```typescript
- export const testHiCollieJankNdk: () => void;
- export const testHiCollieStuckNdk: () => void;
- ```
+ (2) **OH_HiCollie_Init_StuckDetection**:
+
+ ```typescript
+ export const testHiCollieStuckNdk: () => void;
+ ```
+
+ (3) **OH_HiCollie_Init_StuckDetectionWithTimeout**:
+
+ ```typescript
+ export const testHiCollieStuckWithTimeoutNdk: () => void;
+ ```
5. Edit the **Index.ets** file.
- ```ts
- import testNapi from 'libentry.so'
-
- @Entry
- @Component
- struct Index {
- @State message: string = 'Hello World'
-
- build() {
- Row() {
- Column() {
- Button("testHiCollieJankNdk")
- .fontSize(50)
- .fontWeight(FontWeight.Bold)
- .onClick(testNapi.testHiCollieJankNdk);// Add a click event to trigger testHiCollieJankNdk().
- Button("testHiCollieStuckNdk")
- .fontSize(50)
- .fontWeight(FontWeight.Bold)
- .onClick(testNapi.testHiCollieStuckNdk);// Add a click event to trigger testHiCollieStuckNdk().
- }
- .width('100%')
- }
- .height('100%')
- }
- }
- ```
+ ```ts
+ import testNapi from 'libentry.so'
+
+ @Entry
+ @Component
+ struct Index {
+ build() {
+ RelativeContainer() {
+ Column() {
+ //Add the click event corresponding to the detection.
+
+ }.width('100%')
+ }
+ .height('100%')
+ .width('100%')
+ }
+ }
+ ```
+
+ (1) Add a click event to trigger **OH_HiCollie_Init_JankDetection()**.
+
+ ```ts
+ Button("testHiCollieJankNdk", { stateEffect:true, type: ButtonType.Capsule})
+ .width('75%')
+ .height(50)
+ .margin(15)
+ .fontSize(20)
+ .fontWeight(FontWeight.Bold)
+ .onClick(testNapi.testHiCollieJankNdk);
+ ```
+
+ (2) Add a click event to trigger **OH_HiCollie_Init_StuckDetection()**.
+
+ ```ts
+ Button("testHiCollieStuckNdk", { stateEffect:true, type: ButtonType.Capsule})
+ .width('75%')
+ .height(50)
+ .margin(15)
+ .fontSize(20)
+ .fontWeight(FontWeight.Bold)
+ .onClick(testNapi.testHiCollieStuckNdk);
+ ```
+
+ (3) Add a click event to trigger **OH_HiCollie_Init_StuckDetectionWithTimeout()**.
+
+ ```ts
+ Button("testHiCollieStuckWithTimeoutNdk", { stateEffect:true, type: ButtonType.Capsule})
+ .width('75%')
+ .height(50)
+ .margin(15)
+ .fontSize(20)
+ .fontWeight(FontWeight.Bold)
+ .onClick(testNapi.testHiCollieStuckWithTimeoutNdk);
+ ```
6. Click the **Run** button in DevEco Studio to run the project.
-7. At the bottom of DevEco Studio, switch to the **Log** tab and set the filter criteria to **testTag**.
+7. At the bottom of DevEco Studio, switch to the **Log** tab and filter the custom **LOG_TAG**.
+
+ (1) Wait for 10s and click the **testHiCollieJankNdk** button. (The jank event detection is not performed within 10s after the thread starts.)
+ The thread timeout information of the sampling stack obtained through **OH_HiCollie_Init_JankDetection()** is displayed. You can obtain the corresponding event by [subscribing to the main thread timeout event](./hiappevent-watcher-mainthreadjank-events-arkts.md).
- (1) Wait for 10s and click the **testHiCollieJankNdk** button. (The jank event detection is not performed within 10s after the thread starts.)
- The thread timeout information of the sampling stack obtained through **OH_HiCollie_Init_JankDetection()** is displayed
- in **/data/app/el2/100/log/application bundle name/watchdog/BUSSINESS_THREAD_JANK_XXX.txt.**
+ (2) Click the **testHiCollieStuckNdk** button.
+ The callback used for detecting stuck events is initialized through **OH_HiCollie_Init_StuckDetection()**. You can define the detection function for stuck events as required.
- (2) Click the **testHiCollieStuckNdk** button.
- The callback used for detecting stuck events is initialized through **OH_HiCollie_Init_StuckDetection()**. You can define the detection function for stuck events as required.
+ (3) Click the **testHiCollieStuckWithTimeoutNdk** button.
+ The callback used for detecting stuck events is initialized through **OH_HiCollie_Init_StuckDetectionWithTimeout**. You can define the detection function and time for stuck events as required.
diff --git a/en/application-dev/dfx/hicollie-settimer-guidelines-ndk.md b/en/application-dev/dfx/hicollie-settimer-guidelines-ndk.md
index ed2a5bb05b0725f9c8f27d1d25f02ea866042f4e..ab973d30eeafc1a4d77d6ad50fd5b8e755a2b854 100644
--- a/en/application-dev/dfx/hicollie-settimer-guidelines-ndk.md
+++ b/en/application-dev/dfx/hicollie-settimer-guidelines-ndk.md
@@ -3,6 +3,7 @@
HiCollie provides APIs for detecting the function execution timeout events.
## Available APIs
+
| API | Description |
| ------------------------------ | --------------------------------- |
| OH_HiCollie_SetTimer | Enables a timer for checking the function execution duration. Use this function before calling a time-consuming function or code block. |
@@ -10,12 +11,14 @@ HiCollie provides APIs for detecting the function execution timeout events.
> **NOTE**
>
-> You can obtain the function execution timeout logs in the following paths: 1. The **APP_HICOLLIE-*process ID*-*time*.log** file in **device/data/log/eventlog/**. 2. The **syswarning-*bundle name*-*application UID*-*second-level time*** file in **device/data/log/faultlog/faultlogger/**.
-
+> You can obtain the function execution timeout log in the following paths:
+> 1. The **APP_HICOLLIE-*process ID*-*time*.log** file in **device/data/log/eventlog/**.
+> 2. 2. The **syswarning-*bundle name*-*application UID*-*second-level time*** file in **device/data/log/faultlog/faultlogger/**.
-For details (such as parameter usage and value ranges), see [HiCollie](../reference/apis-performance-analysis-kit/_hi_hicollie.md).
+For details (such as parameter usage and value ranges), see [HiCollie](../reference/apis-performance-analysis-kit/_hi_collie.md).
## How to Develop
+
The following describes how to add a button in the application and click the button to call the HiCollie APIs.
1. Create a native C++ project. The directory structure is as follows:
@@ -128,5 +131,8 @@ The following describes how to add a button in the application and click the but
6. Click the **Run** button in DevEco Studio to run the project.
-7. At the bottom of DevEco Studio, switch to the **Log** tab and set the filter criteria to **testTag**. Click the **testHiCollieTimerNdk** button to execute the program. In the log window, the task ID is displayed. After 2 seconds, the callback content is displayed.
+7. At the bottom of DevEco Studio, switch to the **Log** tab and set the filter criteria to **testTag**.
+
+ Click the **testHiCollieTimerNdk** button to execute the program. In the log window, the task ID is displayed. After 2 seconds, the callback content is displayed.
+
The timeout logs are stored in: **data/log/eventlog/APP_HICOLLIE-*process ID*-*time*.log** and **syswarning-*bundle name*-*application UID*-*second-level time***.
diff --git a/en/application-dev/dfx/hidebug-guidelines-arkts.md b/en/application-dev/dfx/hidebug-guidelines-arkts.md
index 55a800e7e326e670f93a337e4f914a2cc8e35f48..0c808e9a6536cf191081da24f26c72c25cc3b65b 100644
--- a/en/application-dev/dfx/hidebug-guidelines-arkts.md
+++ b/en/application-dev/dfx/hidebug-guidelines-arkts.md
@@ -14,6 +14,7 @@ HiDebug provides APIs for system debugging, which allow you to obtain the inform
| hidebug.getSharedDirty | Obtains the size of the shared dirty memory of a process. |
| hidebug.getPrivateDirty | Obtains the size of the private dirty memory of a process. |
| hidebug.getCpuUsage | Obtains the CPU usage of a process. |
+| hidebug.getServiceDump | Obtains system service information. |
| hidebug.dumpJsHeapData | Exports the heap data. |
| hidebug.startJsCpuProfiling | Starts the VM profiling method. |
| hidebug.stopJsCpuProfiling | Stops the VM profiling method. |
@@ -28,8 +29,10 @@ HiDebug provides APIs for system debugging, which allow you to obtain the inform
| hidebug.getSystemMemInfo | Obtains system memory information. |
| hidebug.getVMRuntimeStats | Obtains all system GC statistics. |
| hidebug.getVMRuntimeStat | Obtains the specified system GC statistics based on parameters. |
+| hidebug.isDebugState | Obtains the debugging state of an application process. |
| hidebug.getGraphicsMemory | Obtains the size of the GPU memory asynchronously. |
| hidebug.getGraphicsMemorySync | Obtains the size of the GPU memory synchronously. |
+| hidebug.dumpJsRawHeapData | Dumps the original heap snapshot of the VM for the calling thread. |
For details about how to use HiDebug, see the API Reference (../reference/apis-performance-analysis-kit/js-apis-hidebug.md).
@@ -83,6 +86,7 @@ The following describes how to add a button in the application and click the but
4. Run the project on a real device and click "Hello World" on the app/service.
5. At the bottom of DevEco Studio, switch to the **Log** tab and set the filter criteria to **testTag**.
+
Then, the CPU usage logs obtained using **hidebug.getSystemCpuUsage()** are displayed in the window.
```Text
08-20 11:06:01.891 1948-1948 A03d00/JSAPP com.examp...lication I getSystemCpuUsage: 0.4722222222222222
diff --git a/en/application-dev/dfx/hilog-guidelines-arkts.md b/en/application-dev/dfx/hilog-guidelines-arkts.md
index 0656b47bd3e9c328822236692ad9fa51cb683544..323bf661db351c582393e759ffd93067d62e1740 100644
--- a/en/application-dev/dfx/hilog-guidelines-arkts.md
+++ b/en/application-dev/dfx/hilog-guidelines-arkts.md
@@ -115,7 +115,7 @@ Add a click event in a button, which prints a log when the button is clicked.
```txt
'%{public}s World %{public}d'
```
- *%{public}s* indicates a string, and *%{public}d* indicates an integer. Both of them are displayed in plaintext.
+ *%{public}s* indicates a string, and *%{public}d* indicates an integer. Both of them are displayed in plaintext.
4. Run the project on a real device, and click the **Next** button on the app/service.
diff --git a/en/application-dev/dfx/hilog-guidelines-ndk.md b/en/application-dev/dfx/hilog-guidelines-ndk.md
index e0f744f51a4c3b7222b4ef4c1430ef9be5425b74..f76efe8bad934202eb073382b6d7b60ab38614a7 100644
--- a/en/application-dev/dfx/hilog-guidelines-ndk.md
+++ b/en/application-dev/dfx/hilog-guidelines-ndk.md
@@ -118,7 +118,7 @@ static void Test(void)
// 1. Register a callback.
OH_LOG_SetCallback(MyHiLog);
- // 2. Call the hilog API to print logs. Logs are output to HiLog and returned to **MyHiLog()** through the registered callback. Then, **MyHiLog()** is called to process the logs.
+ // 2. Call the hilog API to print logs. Logs are output to HiLog and returned to MyHiLog() through the registered callback. Then, MyHiLog() is called to process the logs.
HiLog::Info(LABEL, "hello world");
}
```
diff --git a/en/application-dev/dfx/hilog.md b/en/application-dev/dfx/hilog.md
index a5eff8d7f8936d4ae419cad83b3b239ded319953..d9fe8433d3a67afb206272cfe3a8689774e7111f 100644
--- a/en/application-dev/dfx/hilog.md
+++ b/en/application-dev/dfx/hilog.md
@@ -15,21 +15,21 @@ HiLog is a log system that provides logging for the system framework, services,
| Short Option| Long Option| Parameter| Description|
| -------- | -------- | -------- | -------- |
-| -h | --help | | Shows help information.|
-| Default| Default| | Performs a blocking read on logs, with no exiting after the read finishes.|
-| -x | --exit | | Performs a non-blocking read on logs, with exiting after the read finishes.|
-| -g | | | Checks the buffer size for logs of a specified type. This option is used together with **-t**, which specifies a log type. By default, the **app** or **core** types are used.|
+| -h | --help | - | Shows help information.|
+| Default| Default| - | Performs a blocking read on logs, with no exiting after the read finishes.|
+| -x | --exit | - | Performs a non-blocking read on logs, with exiting after the read finishes.|
+| -g | - | - | Checks the buffer size for logs of a specified type. This option is used together with **-t**, which specifies a log type. By default, the **app** or **core** types are used.|
| -G | --buffer-size | <size> | Sets the size of the buffer for logs of a specified type. This option is used together with **-t**, which specifies a log type. By default, the **app** or **core** types are used. The unit can be B, KB, MB, or GB. The value ranges from 64 KB to 16 MB.|
-| -r | | | Clears the buffer for logs of a specified type. This option is used together with **-t**, which specifies a log type. By default, the **app** or **core** types are used.|
+| -r | - | - | Clears the buffer for logs of a specified type. This option is used together with **-t**, which specifies a log type. By default, the **app** or **core** types are used.|
| -p | --privacy | <on/off> | Specifies whether to enable privacy for logs during system debugging.|
| | | on | Enables privacy so that parameters are displayed as **\** in printed logs.|
| | | off | Disables privacy so that parameters are displayed as they are in printed logs.|
-| -k | | <on/off> | Specifies whether to enable kernel logging.|
+| -k | - | <on/off> | Specifies whether to enable kernel logging.|
| | | on | Enables kernel logging.|
| | | off | Disables kernel logging.|
-| -s | --statistics | | Shows statistics. This option must be used together with **-t** or **-D**.|
-| -S | | | Clears statistics. This option must be used together with **-t** or **-D**.|
-| -Q | | <control-type> | Specifies whether to enable the default quota for flow control.|
+| -s | --statistics | - | Shows statistics. This option must be used together with **-t** or **-D**.|
+| -S | - | - | Clears statistics. This option must be used together with **-t** or **-D**.|
+| -Q | - | <control-type> | Specifies whether to enable the default quota for flow control.|
| | | pidon | Enables process flow control.|
| | | pidoff | Disables process flow control.|
| | | domainon | Enables domain flow control.|
@@ -56,7 +56,7 @@ HiLog is a log system that provides logging for the system framework, services,
| | | none | Indicates that data is flushed to disks in non-compression mode.|
| | | zlib | Indicates that data is flushed to disks using the zlib compression algorithm. The flushed file is in .gz format.|
| | | zstd | Indicates that data is flushed to disks using the zstd compression algorithm. The flushed file is in .zst format.|
-| -v | --format | <format> | |
+| -v | --format | <format> | Sets the display format.|
| | | time | Displays the local time.|
| | | color | Adds colors to logs at different levels. By default, logs are displayed in black and white.|
| | | epoch | Displays the amount of time elapsed since the epoch time.|
@@ -67,7 +67,7 @@ HiLog is a log system that provides logging for the system framework, services,
| | | zone | Displays the time with the local time zone.|
| | | wrap | Displays logs in different lines without adding prefixes such as the timestamp to the new line.|
| -b | --baselevel | <loglevel> | Sets the lowest level of logs that can be printed: D(DEBUG)/I(INFO)/W(WARN)/E(ERROR)/F(FATAL).|
-| | --persist||Persists the log level setting command. (The setting will not be lost after the system is restarted.)|
+| | --persist| - |Persists the log level setting command. (The setting will not be lost after the system is restarted.)|
## Examples
@@ -263,7 +263,7 @@ HiLog is a log system that provides logging for the system framework, services,
```
$ hilog -L E
- 08-28 09:01:25.730 2678 2678 E A00F00/com.huawei.hmos.aidataservice/AiDataService_5.10.7.320: DataChangeNotifyManager: notifyDataChange CommonEntity no valid entity to notify
+ 08-28 09:01:25.730 2678 2678 E A00F00/com.aidataservice/AiDataService_5.10.7.320: DataChangeNotifyManager: notifyDataChange CommonEntity no valid entity to notify
08-28 09:01:56.058 8560 8560 E A00500/com.ohos.settingsdata/SettingsData: DB not ready request = datashare:///com.ohos.settingsdata/entry/settingsdata/SETTINGSDATA?Proxy=true&key=analysis_service_switch_on , retry after DB startup
08-28 09:01:56.082 8560 8560 E A00500/com.ohos.settingsdata/SettingsData: decoder failure: /data/migrate/settings_global.xml , error code:-1
08-28 09:01:56.082 8560 8560 E A00500/com.ohos.settingsdata/SettingsData: clearXml failed:No such file or directory, error code:13900002
@@ -337,13 +337,13 @@ HiLog is a log system that provides logging for the system framework, services,
```
$ hilog -a 8
11-15 16:04:08.628 0 0 I I00000/HiLog: ========Zeroth log of type: init
- 11-15 16:04:08.603 506 506 I I02C01/hmos_cust_carrier_mount/CustCarrierMount: MountCarrierToShared start
- 11-15 16:04:08.604 506 506 I I02C01/hmos_cust_carrier_mount/CustCarrierMount: success to mount carrier to shared
- 11-15 16:04:15.394 972 972 I I02C01/hmos_cust_carrier_mount/CustCarrierMount: UpdateCotaOpkeyLink start
- 11-15 16:04:15.396 972 972 W I02C01/hmos_cust_carrier_mount/CustCarrierMount: not exsit CUST_GLOBAL_CARRIER_DIR or COTA_PARAM_CARRIER_DIR
- 11-15 16:04:15.887 972 972 I I02C01/hmos_cust_carrier_mount/CustCarrierMount: success to update cota carrier
- 11-15 16:04:48.749 5777 5901 I A00001/com.huawei.hmsapp.hiai.core/HiAI_Metadata: metadata is null
- 11-15 16:04:48.749 5777 5901 I A00001/com.huawei.hmsapp.hiai.core/HiAI_PluginAbilityInfo: abilityInfo is null
+ 11-15 16:04:08.603 506 506 I I02C01/cust_carrier_mount/CustCarrierMount: MountCarrierToShared start
+ 11-15 16:04:08.604 506 506 I I02C01/cust_carrier_mount/CustCarrierMount: success to mount carrier to shared
+ 11-15 16:04:15.394 972 972 I I02C01/cust_carrier_mount/CustCarrierMount: UpdateCotaOpkeyLink start
+ 11-15 16:04:15.396 972 972 W I02C01/cust_carrier_mount/CustCarrierMount: not exsit CUST_GLOBAL_CARRIER_DIR or COTA_PARAM_CARRIER_DIR
+ 11-15 16:04:15.887 972 972 I I02C01/cust_carrier_mount/CustCarrierMount: success to update cota carrier
+ 11-15 16:04:48.749 5777 5901 I A00001/com.hiai.core/HiAI_Metadata: metadata is null
+ 11-15 16:04:48.749 5777 5901 I A00001/com.hiai.core/HiAI_PluginAbilityInfo: abilityInfo is null
```
### Displaying Logs in the Last N Lines of the Buffer
diff --git a/en/application-dev/dfx/hiperf.md b/en/application-dev/dfx/hiperf.md
index 2df004cfb21b76d72a5ab5ab4e7177cc2d7385e3..4deeb5dab1e96eecbe302af71907e8cfda32b93f 100644
--- a/en/application-dev/dfx/hiperf.md
+++ b/en/application-dev/dfx/hiperf.md
@@ -125,7 +125,7 @@ Specifies the target program for sampling and saves the sampled data to a file (
| --dumpoptions | Dumps the command options.|
```
-Usage: hiperf record [options] [command [command-args]]
+Usage: hiperf record [options] [command [command-args]]
```
Sample the process 267 for 10 seconds and use **dwarf** to collect and unwind stack memory of the process.
@@ -252,7 +252,7 @@ You can use a script to sample data and generate flame graphs. You can obtain th
Run **command_script.py** to sample data. This script packages the **report** command.
```
- usage: command_script.py [-h]
+ usage: command_script.py [-h]
(-app PACKAGE_NAME | -lp LOCAL_PROGRAM | -cmd CMD | -p [PID [PID ...]] | -t [TID [TID ...]] | -sw)
[-a ABILITY] [-r RECORD_OPTIONS] [-lib LOCAL_LIB_DIR]
[-o OUTPUT_PERF_DATA] [--not_hdc_root]
diff --git a/en/application-dev/dfx/hitrace.md b/en/application-dev/dfx/hitrace.md
index d5ccfdc8763e8061639acc33c142fc1d152f7b92..c50760d483830f28596b010cf3cbb23e8c044834 100644
--- a/en/application-dev/dfx/hitrace.md
+++ b/en/application-dev/dfx/hitrace.md
@@ -5,27 +5,27 @@
## Environment Requirements
- The [environment setup](hdc.md#environment-setup) is complete.
-
- The devices are properly connected.
## Command Description
-| Command| Description|
-| -------- | -------- |
-| -h | Displays help information.|
-| -l | Displays the tag list.|
-| --trace_begin | Starts capturing trace data.|
-| --trace_finish | Stops capturing trace data.|
-| --trace_dump | Dumps trace information.|
-| -b N | Sets the buffer size (in KB) for trace data. The default buffer size is 2048 KB.|
-| -t N | Sets the trace uptime in seconds, which depends on the time required for analysis. The default value is 5 seconds.|
-| -o | Specifies the target file name (**stdout** by default).|
-| -z | Compresses the trace data.|
-| --trace_clock | Sets the type of the clock for adding a timestamp to a trace. The value can be **boot** (default), **global**, **mono**, **uptime**, or **perf**.|
-| --trace_finish_nodump | Stops printing when trace capturing is stopped.|
-| --start_bgsrv | Starts trace collection in the snapshot mode.|
-| --dump_bgsrv | Dumps the trace data in the snapshot mode to a file.|
-| --stop_bgsrv | Stops trace collection in the snapshot mode.|
+| Command | Description |
+| --------------------- | ------------------------------------------------------------ |
+| -h | Displays help information. |
+| -l | Displays the tag list. |
+| --trace_begin | Starts capturing trace data. |
+| --trace_finish | Stops capturing trace data. |
+| --trace_dump | Dumps trace information. |
+| -b N | Sets the buffer size (in KB) for trace data. The default buffer size is 2048 KB.|
+| -t N | Sets the trace uptime in seconds, which depends on the time required for analysis. The default value is 5 seconds.|
+| -o | Specifies the target file name (**stdout** by default). |
+| -z | Compresses the trace data. |
+| --trace_clock | Sets the type of the clock for adding a timestamp to a trace. The value can be **boot** (default), **global**, **mono**, **uptime**, or **perf**.|
+| --trace_finish_nodump | Stops printing when trace capturing is stopped. |
+| --start_bgsrv | Starts trace collection in the snapshot mode. |
+| --dump_bgsrv | Dumps the trace data in the snapshot mode to a file. |
+| --stop_bgsrv | Stops trace collection in the snapshot mode. |
+| --trace_level | Sets the trace level threshold. The trace level lower than the threshold does not take effect. The value can be **Debug**, **Info**, **Critical**, **Commercial**, or **D**, **I**, **C**, or **M**. The logging level priority is **D** < **I** < **C** < **M**. You can use the logging APIs with the trace level in [js-apis-hitracemeter](../reference/apis-performance-analysis-kit/js-apis-hitracemeter.md) and [_hitrace](../reference/apis-performance-analysis-kit/_hitrace.md) to check whether the trace output of different thresholds meets the expectation.|
> **Description**
>
@@ -37,13 +37,12 @@ Run the following commands in the hdc shell:
1. Display the tag list in hitrace.
- ```
+ ```shell
hitrace -l
```
-
**Example**
- ```
+ ```shell
$ hitrace -l
2024/11/14 11:43:00 hitrace enter, running_state is SHOW_LIST_CATEGORY
tagName: description:
@@ -123,78 +122,73 @@ Run the following commands in the hdc shell:
zimage - OpenHarmony Image Module
zmedia - OpenHarmony Media Module
```
-
2. Start to capture the trace data of a specified tag.
- ```
+ ```shell
hitrace --trace_begin --record app
```
-
**Example**
- ```
+ ```shell
$ hitrace --trace_begin --record app
2024/11/14 11:48:45 hitrace enter, running_state is RECORDING_LONG_BEGIN_RECORD
2024/11/14 11:48:45 args: tags:app bufferSize:18432 overwrite:1
2024/11/14 11:48:45 OpenRecording done.
```
-
3. Stop to capture the trace data.
- ```
- hitrace --trace_finish --record: Display the trace data in the CLI by default.
- ```
+ By default, the trace data is displayed in the CLI.
+ ```shell
+ hitrace --trace_finish --record
+ ```
**Example 1**
- ```
+ ```shell
$ hitrace --trace_finish --record
2024/11/14 11:50:33 hitrace enter, running_state is RECORDING_LONG_FINISH_RECORD
2024/11/14 11:50:33 capture done, output files:
/data/log/hitrace/record_trace_20241114115033@3010728-656499531.sys
```
+ Add the output path to export the trace data to the corresponding file.
+ ```shell
+ hitrace --trace_finish -o /data/local/tmp/test.ftrace
```
- hitrace --trace_finish -o /data/local/tmp/test.ftrace: Add the output path to export the trace data to the corresponding file.
- ```
-
**Example 2**
- ```
+ ```shell
$ hitrace --trace_finish -o /data/local/tmp/test.ftrace
2024/11/14 11:50:33 start to read trace.
2024/11/14 11:50:33 trace read done, output: /data/local/tmp/test.ftrace
```
+4. Capture trace data with the following settings:
-4. Run the **hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability** command to capture trace data with the following settings:
-
- ```
- hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability.
+ ```shell
+ hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability
```
-
**Example**
- ```
+ ```shell
$ hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability
2024/11/14 11:52:13 start capture, please wait 10s ...
2024/11/14 11:52:23 capture done, start to read trace.
2024/11/14 11:52:23 trace read done, output: /data/local/tmp/test2.ftrace
```
-
- Buffer size: 10240 KB
- Trace uptime: 10s
- - Output path: **/data/local/tmp/test1.htrace**
+ - Output path: **/data/local/tmp/test2.ftrace**.
- Tags: app and ability
-
5. Dump trace information.
- ```
- hitrace --trace_dump: Display the information in the CLI by default.
- ```
+ By default, the trace data is displayed in the CLI.
+ ```shell
+ hitrace --trace_dump
+ ```
**Example 1**
- ```
+ ```shell
$ hitrace --trace_dump
2024/11/14 11:54:23 start to read trace.
# tracer: nop
@@ -208,112 +202,113 @@ Run the following commands in the hdc shell:
# ||| / delay
# TASK-PID TGID CPU# |||| TIMESTAMP FUNCTION
# | | | | |||| | |
- <...>-21829 ( 19280) [003] .... 3011033.731844: tracing_mark_write: trace_event_clock_sync: realtime_ts=1732002022239
- <...>-21829 ( 19280) [003] .... 3011033.731865: tracing_mark_write: trace_event_clock_sync: parent_ts=3011033.750000
+ <...>-21829 ( 19280) [003] .... 3011033.731844: tracing_mark_write: trace_event_clock_sync: realtime_ts=1732002022239
+ <...>-21829 ( 19280) [003] .... 3011033.731865: tracing_mark_write: trace_event_clock_sync: parent_ts=3011033.750000
#
```
+ Add the output path to export the trace data to the corresponding file.
+ ```shell
+ hitrace --trace_dump -o /data/local/tmp/test3.ftrace
```
- hitrace --trace_dump -o /data/local/tmp/test3.ftrace: Add the output path to export the trace information to the corresponding file.
- ```
-
**Example 2**
- ```
- $ hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability
+ ```shell
+ $ hitrace --trace_dump -o /data/local/tmp/test3.ftrace
2024/11/14 11:54:23 start to read trace.
- 2024/11/14 11:54:23 trace read done, output: /data/local/tmp/test3
- ```
-
- ```
- You can also run the **`hitrace --trace_dump |grep \***\***\***`** command to dump trace data based on keywords.
+ 2024/11/14 11:54:23 trace read done, output: /data/local/tmp/test3.ftrace
```
-
+ You can also run the **hitrace --trace_dump | grep xxx** command to dump trace data based on keywords.
6. Start trace collection in the snapshot mode.
- ```
+ ```shell
hitrace --start_bgsrv
```
-
**Example**
- ```
- $ `hitrace --start_bgsrv
+ ```shell
+ $ hitrace --start_bgsrv
2024/11/14 11:55:53 hitrace enter, running_state is SNAPSHOT_START
2024/11/14 11:55:54 OpenSnapshot done.
```
-
7. Dump the trace data in snapshot mode.
By default, the trace data is stored in the binary format in **/data/log/hitrace/**. The file is named in the format of **trace-YYMMDDHHmmSS@[BOOT_TIME].sys**. You can view the file using [SmartPerf](https://www.smartperf.host).
- ```
+ ```shell
hitrace --dump_bgsrv
```
-
**Example**
- ```
+ ```shell
$ hitrace --dump_bgsrv
2024/11/14 12:12:56 hitrace enter, running_state is SNAPSHOT_DUMP
2024/11/14 12:12:57 DumpSnapshot done, output:
/data/log/hitrace/record_trace_20241114121257@2566589-103807063.sys
```
-
8. Stop trace collection in the snapshot mode.
- ```
+ ```shell
hitrace --stop_bgsrv
```
-
**Example**
- ```
+ ```shell
$ hitrace --stop_bgsrv
2024/11/14 11:59:43 hitrace enter, running_state is SNAPSHOT_STOP
2024/11/14 11:59:43 CloseSnapshot done.
```
-
9. Compress the trace data.
- ```
+ ```shell
hitrace -z -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace
```
-
**Example**
- ```
+ ```shell
$ hitrace -z -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace
2024/11/14 12:00:18 start capture, please wait 10s ...
2024/11/14 12:00:28 capture done, start to read trace.
2024/11/14 12:00:29 trace read done, output: /data/local/tmp/test.ftrace
```
-
10. Set the trace output clock to **boot** (system time of the device).
- ```
- hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace
- ```
+ ```shell
+ hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace
+ ```
+ **Example**
+
+ ```shell
+ $ hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace
+ 2024/11/14 12:01:42 start capture, please wait 10s ...
+ 2024/11/14 12:01:52 capture done, start to read trace.
+ 2024/11/14 12:01:52 trace read done, output: /data/local/tmp/test.ftrace
+ ```
+11. Stop capturing and printing trace data in the CLI.
- **Example**
+ By default, the trace data is saved in **/data/log/hitrace/**.
- ```
- $ hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace
- 2024/11/14 12:01:42 start capture, please wait 10s ...
- 2024/11/14 12:01:52 capture done, start to read trace.
- 2024/11/14 12:01:52 trace read done, output: /data/local/tmp/test.ftrace
- ```
+ ```shell
+ hitrace --trace_finish_nodump
+ ```
+ **Example**
-11. Stop capturing and printing trace data in the CLI.
+ ```shell
+ $ hitrace --trace_finish_nodump
+ 2024/11/14 12:03:07 hitrace enter, running_state is RECORDING_LONG_FINISH_NODUMP
+ 2024/11/14 12:03:07 end capture trace.
+ ```
+12. Set the trace level threshold to **Info**.
- ```
- hitrace --trace_finish_nodump: Saves the trace data to the /data/log/hitrace/ directory by default.
- ```
+ ```shell
+ hitrace --trace_level Info
+ ```
+ **Example**
- **Example**
+ ```shell
+ $ hitrace --trace_level Info
+ 2024/11/14 12:05:07 hitrace enter, running_state is SET_TRACE_LEVEL
+ 2024/11/14 12:05:07 success to set trace level.
+ ```
- ```
- $ hitrace --trace_finish_nodump
- 2024/11/14 12:03:07 hitrace enter, running_state is RECORDING_LONG_FINISH_NODUMP
- 2024/11/14 12:03:07 end capture trace.
- ```
+
\ No newline at end of file
diff --git a/en/application-dev/dfx/hitracemeter-guidelines-arkts.md b/en/application-dev/dfx/hitracemeter-guidelines-arkts.md
index 702f2bacb728febb8f2da6b9048b153089149809..a864bc9bf9548fa00bb615f68a770996a9e22649 100644
--- a/en/application-dev/dfx/hitracemeter-guidelines-arkts.md
+++ b/en/application-dev/dfx/hitracemeter-guidelines-arkts.md
@@ -1,40 +1,53 @@
-# Using hiTraceMeter (ArkTS/JS)
+# Using HiTraceMeter (ArkTS/JS)
## Overview
-**hiTraceMeter** provides APIs for system performance tracing. You can call the APIs provided by **hiTraceMeter** in key codes to track service processes and check the system performance.
+HiTraceMeter provides APIs for system performance tracing. You can call the HiTraceMeter APIs in key codes to track service processes and check the system performance.
## Basic Concepts
-**hiTraceMeter Tag**: tag specifying the category of the data to trace. It is also known as **HiTraceMeter Category**. Generally, one subsystem maps to a tag. The tag is passed in by the **Tag** parameter in performance tracing APIs. When you use the hiTraceMeter CLI tool to collect tracing data, only the data specified by the **Tag** parameter is collected.
+**HiTraceMeter Tag**: Tag used for tracing data categorization. It is also known as **HiTraceMeter Category**. Generally, one subsystem maps to a tag. When you use the [HiTrace](hitrace.md) CLI tool to collect tracing data, only the data specified by the **Tag** parameter is collected. The HiTraceMeter tag for applications is **HITRACE_TAG_APP**, which corresponds to **app** in the tag list displayed by running the **[hitrace](hitrace.md) -l** command.
## Working Principles
-1. The application calls hiTraceMeter APIs to trace and output the tracing data to the kernel's ftrace buffer through the kernel's sysfs file interface.
-
-2. The hiTraceMeter CLI tool reads the tracing data in the ftrace buffer and saves the trace data as a text file on the device.
+1. The application calls HiTraceMeter APIs to trace and input the tracing data to the kernel's ftrace buffer through the kernel's sysfs file interface.
+2. The [HiTrace](hitrace.md) CLI tool reads the trace data in the kernel ftrace buffer and outputs the trace data to the file on the device.
## Available APIs
-The performance tracing APIs are provided by the **hiTraceMeter** module. For details, see [Hitrace](../reference/apis-performance-analysis-kit/js-apis-hitracemeter.md).
+The performance tracing APIs are provided by the **HiTraceMeter** module. For details, see [Hitrace](../reference/apis-performance-analysis-kit/js-apis-hitracemeter.md).
+
+| API | Description |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| startSyncTrace(level: HiTraceOutputLevel, name: string, customArgs?: string): void | Starts a synchronous time slice trace with the trace output level specified. |
+| finishSyncTrace(level: HiTraceOutputLevel): void | Stops a synchronous time slice trace with the trace output level specified. The value of **level** must be the same as that of **startSyncTrace**.|
+| startAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number, customCategory: string, customArgs?: string): void | Starts an asynchronous time slice trace with the trace output level specified. If multiple tracing tasks with the same name need to be performed at the same time, different task IDs must be specified through **taskId**. If the tracing tasks with the same name are not performed at the same time, the same task ID can be used.|
+| finishAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number): void | Stops an asynchronous time slice trace with the trace output level specified. Stops a tracing task. The values of **name** and **taskId** must be the same as those in **startAsyncTrace**.|
+| traceByValue(level: HiTraceOutputLevel, name: string, count: number): void | Traces an integer with the trace output level specified. **name** and **count** are used to identify the name and value of an integer variable to be traced.|
+| isTraceEnabled(): boolean | Checks whether application trace capture is enabled. If not, HiTraceMeter performance tracing is invalid.|
+
+HiTraceMeter logging APIs are classified into three types by functionality/behavior: API for synchronous time slice tracing, API for asynchronous time slice tracing, and API for integer tracing. Both synchronous and asynchronous time slice tracing APIs are synchronous APIs. You can use HiTraceMeter APIs with [HiTraceChain](./hitracechain-guidelines-arkts.md) to perform tracing and analysis across devices, processes, and threads.
-| API| Description|
-| -------- | -------- |
-| hiTraceMeter.startTrace(name: string, taskId: number) | Starts an asynchronous time slice trace task. If multiple tracing tasks with the same name need to be performed at the same time, different task IDs must be specified through **taskId**. If the tracing tasks with the same name are not performed at the same time, the same task ID can be used.|
-| hiTraceMeter.finishTrace(name: string, taskId: number) | Stops an asynchronous time slice trace task. The values of **name** and **taskId** must be the same as those of **hiTraceMeter.startTrace**. |
-| hiTraceMeter.traceByValue(name: string, value: number) | Traces the value changes of a numeric variable, which is an integer.|
+- The synchronous time slice tracing APIs are used in the scenario where tasks are executed in sequence.
+- The asynchronous time slice tracing APIs are used in the scenario where tasks are executed asynchronously. The start and end of an asynchronous trace task are not in sequence. Therefore, the **name** and **taskId** parameters are used to identify the start and end of an asynchronous trace task.
+- The integer tracing API is used to trace integer variables.
-HiTraceMeter logging APIs are classified into three types by functionality/behavior: API for synchronous time slice tracing, API for asynchronous time slice tracing, and API for integer tracing. APIs for synchronous and asynchronous time slice tracing are synchronous and are used in the same thread. Cross-thread logging and analysis are not supported.
+**Parameters**
-- The API for synchronous time slice tracing is used for sequential logging, which is not supported in ArkTS/JS.
-- The API for asynchronous time slice tracing is used to start logging before an operation is called and end longing after the operation is complete. Since the start and end of asynchronous tracing do not occur in sequence, a unique task ID is used to identify the start and end of asynchronous tracing. The task ID is passed as a parameter of the API for asynchronous tracing.
-- The integer tracing API is used to trace numeric variables.
+| Name | Type | Mandatory| Description |
+| -------------- | ------ | ---- | ------------------------------------------------------------ |
+| level | enum | Yes | Trace output level. Trace data whose levels are lower than the system threshold will not be output.
The log version threshold is **INFO**, and the nolog version threshold is **COMMERCIAL**.|
+| name | string | Yes | Name of the task or integer variable to trace. The value contains a maximum of 320 characters. If the value length exceeds this limit, excess content will be truncated.|
+| taskId | number | Yes | Task ID. If multiple tasks with the same **name** are executed at the same time, you must set different **taskId** when calling **startAsyncTrace**.|
+| count | number | Yes | Value of an integer variable. |
+| customCategory | string | Yes | Custom category name, which is used to collect asynchronous trace data of the same type. The value contains a maximum of 64 characters. If the value length exceeds this limit, excess content will be truncated.
If the category is not required, pass in an empty string.|
+| customArgs | string | No | Custom key-value pair. If there are multiple key-value pairs, separate them with commas (,), for example, **key1=value1,key2=value2**.
A maximum of 512 characters are output. If the **name** and **customCategory** parameters occupy too many characters, the value of **customArgs** may be truncated.
If this parameter is not required, do not pass in it or pass in an empty string.|
## How to Develop
-In this example, distributed call chain tracing begins when the application startup execution page is loaded and stops when the service usage is completed.
+In this example, distributed call chain tracing begins when the application startup execution page is loaded and stops when the service usage is completed. In the following example, the **startAsyncTrace**, **finishAsyncTrace**, and **traceByValue** APIs of HiTraceMeter are used in ArkTS.
-1. In DevEco Studio, create an ArkTS application project. In the **Project** window, choose **entry** > **src** > **main** > **ets** > **pages** > **index**, and double-click **index.ets**. Add the code to the file to implement performance tracing upon page loading. The sample code of tracing task **myTraceTest** is as follows:
+1. In DevEco Studio, create an ArkTS application project. In the **Project** window, choose **entry** > **src** > **main** > **ets** > **pages** > **index**, and double-click **index.ets**. Add the code to the file to implement performance tracing upon page loading. The sample code of tracing task **myTestAsyncTrace** is as follows:
```ts
import hiTraceMeter from '@ohos.hiTraceMeter';
@@ -52,29 +65,29 @@ In this example, distributed call chain tracing begins when the application star
.fontWeight(FontWeight.Bold)
.onClick(() => {
this.message = 'Hello Hitrace';
-
+ const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL;
+
let traceCount = 0;
// Start the first tracing task.
- hiTraceMeter.startTrace("myTraceTest", 1001);
+ hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestAsyncTrace", 1001, "categoryTest", "key=value");
// Start counting the task.
traceCount++;
- hiTraceMeter.traceByValue("myTestCount", traceCount);
+ hiTraceMeter.traceByValue(COMMERCIAL, "myTestCountTrace", traceCount);
// Keep the service process running.
console.log(`myTraceTest running, taskid: 1001`);
-
+
// Start the second tracing task with the same name while the first task is still running. The tasks are running concurrently and therefore their taskId must be different.
- hiTraceMeter.startTrace("myTraceTest", 1002);
+ hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestAsyncTrace", 1002, "categoryTest", "key=value");
// Start counting the task.
traceCount++;
- hiTraceMeter.traceByValue("myTestCount", traceCount);
+ hiTraceMeter.traceByValue(COMMERCIAL, "myTestCountTrace", traceCount);
// Keep the service process running.
console.log(`myTraceTest running, taskid: 1002`);
// End the tracing task whose task ID is 1001.
- hiTraceMeter.finishTrace("myTraceTest", 1001);
+ hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestAsyncTrace", 1001);
// End the tracing task whose task ID is 1002.
- hiTraceMeter.finishTrace("myTraceTest", 1002);
-
+ hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestAsyncTrace", 1002);
})
}
.width('100%')
@@ -83,30 +96,27 @@ In this example, distributed call chain tracing begins when the application star
}
}
```
+2. Click the **Run** button in DevEco Studio to run the project. Then, run the [HiTrace](hitrace.md) command to obtain the tracing task logs.
-2. Click the **Run** button in DevEco Studio to run the project. Then, run the [hitrace](hitrace.md) command to obtain the tracing task logs.
-
- Run the following command in DevEco Studio Terminal:
+ Run the following command in DevEco Studio Terminal to enable trace capture:
```shell
PS D:\xxx\xxx> hdc shell
$ hitrace --trace_begin app
```
-
- After the **trace** command is executed, call the HiTraceMeter APIs in your service logic on the device. Then, run the following commands in sequence:
+ Start the application, execute the service call logic (including HiTraceMeter APIs), and run the following commands in sequence:
```shell
- $ hitrace --trace_dump | grep tracing_mark_write
+ $ hitrace --trace_dump | grep myTest
$ hitrace --trace_finish
```
-
The following is an example of the captured trace data:
```text
- <...>-3310 (-------) [005] .... 351382.921936: tracing_mark_write: S|3310|H:myTraceTest 1001
- <...>-3310 (-------) [005] .... 351382.922233: tracing_mark_write: C|3310|H:myTestCount 1
- <...>-3310 (-------) [005] .... 351382.922138: tracing_mark_write: S|3310|H:myTraceTest 1002
- <...>-3310 (-------) [005] .... 351382.922233: tracing_mark_write: C|3310|H:myTestCount 2
- <...>-3310 (-------) [005] .... 351382.922165: tracing_mark_write: F|3310|H:myTestCount 1001
- <...>-3310 (-------) [005] .... 351382.922175: tracing_mark_write: F|3310|H:myTestCount 1002
+ <...>-23649 (-------) [007] .... 2078.630872: tracing_mark_write: S|23649|H:myTestAsyncTrace|1001|M62|categoryTest|key=value
+ <...>-23649 (-------) [007] .... 2078.630887: tracing_mark_write: C|23649|H:myTestCountTrace|1|M62
+ <...>-23649 (-------) [007] .... 2078.630989: tracing_mark_write: S|23649|H:myTestAsyncTrace|1002|M62|categoryTest|key=value
+ <...>-23649 (-------) [007] .... 2078.630996: tracing_mark_write: C|23649|H:myTestCountTrace|2|M62
+ <...>-23649 (-------) [007] .... 2078.631027: tracing_mark_write: F|23649|H:myTestAsyncTrace|1001|M62
+ <...>-23649 (-------) [007] .... 2078.631033: tracing_mark_write: F|23649|H:myTestAsyncTrace|1002|M62
```
diff --git a/en/application-dev/dfx/hitracemeter-guidelines-ndk.md b/en/application-dev/dfx/hitracemeter-guidelines-ndk.md
index 62326d9c1192279e8a8924dd781de73dc86d2101..8a11373ff47220d96f638b6969bd4ba8ece4bb10 100644
--- a/en/application-dev/dfx/hitracemeter-guidelines-ndk.md
+++ b/en/application-dev/dfx/hitracemeter-guidelines-ndk.md
@@ -1,87 +1,116 @@
# Using HiTraceMeter (C/C++)
-**HiTrace** provides APIs to implement call chain tracing throughout a service process. You can use these APIs to quickly obtain the run log specific to the call chain of a service process and locate faults in inter-device, inter-process, or inter-thread communications.
+## Overview
-## Available APIs
-
-The performance tracing APIs are provided by the **HiTraceMeter** module. For details, see [Hitrace](../reference/apis-performance-analysis-kit/_hitrace.md).
-
-| API| Description|
-| -------- | -------- |
-| void OH_HiTrace_StartTrace(const char* name) | Starts a synchronous time slice trace.|
-| void OH_HiTrace_FinishTrace() | Ends a synchronous time slice trace.|
-| void OH_HiTrace_StartAsyncTrace(const char* name, int32_t taskId) | Starts an asynchronous time slice trace.|
-| void OH_HiTrace_FinishAsyncTrace(const char* name, int32_t taskId) | Ends an asynchronous time slice trace.|
-| void OH_HiTrace_CountTrace(const char* name, int64_t count) | Performs an integer trace.|
+HiTraceMeter provides APIs for system performance tracing. You can call the HiTraceMeter APIs in key codes to track service processes and check the system performance.
-**Parameter Description**
-
-| Name| Type| Mandatory| Description |
-| ------ | ------ | ---- | ------------------------------------------------------------ |
-| name | string | Yes | Name of the variable.|
-| taskId | number | Yes | ID used to indicate the association of APIs in a trace. If multiple traces with the same name need to be performed at the same time, different task IDs must be specified in **startTrace**.|
-| count | number | Yes | Value of the variable. |
-
-## How to Develop
+## Basic Concepts
-1. Add **libhitrace_ndk.z.so** to **CMakeLists.txt**.
+**HiTraceMeter Tag**: Tag used for tracing data categorization. It is also known as **HiTraceMeter Category**. Generally, one subsystem maps to a tag. When you use the [HiTrace](hitrace.md) CLI tool to collect tracing data, only the data specified by the **Tag** parameter is collected. The HiTraceMeter tag for applications is **HITRACE_TAG_APP**, which corresponds to **app** in the tag list displayed by running the **[hitrace](hitrace.md) -l** command.
- ```
- target_link_libraries(entry PUBLIC libhitrace_ndk.z.so)
- ```
+## Implementation Principles
-2. Include the **trace.h** header file in the source file.
+1. The application calls HiTraceMeter APIs to trace and input the trace data to the kernel's ftrace buffer through the kernel's sysfs file interface.
+2. The [HiTrace](hitrace.md) CLI tool reads the trace data in the kernel ftrace buffer and outputs the trace data as a text file on the device.
- ```c++
- #include "hitrace/trace.h"
- ```
+## Available APIs
-3. Trace performance data. The following uses an asynchronous trace as an example. (The sample code is a part of the default **hello.cpp** file. You only need to add related APIs at the required positions. For details about the APIs, see "Available APIs".)
+The performance tracing APIs are provided by the **HiTraceMeter** module. For details, see [Hitrace](../reference/apis-performance-analysis-kit/_hitrace.md).
- ```c++
- #include "napi/native_api.h"
- #include "hitrace/trace.h"
- static napi_value Add(napi_env env, napi_callback_info info)
- {
- // Start an asynchronous time slice trace.
- OH_HiTrace_StartAsyncTrace("hitraceTest", 123);
- // End the asynchronous time slice trace (The start and end points are for reference only. Add them to the code lines where you want to start and end the trace.)
- OH_HiTrace_FinishAsyncTrace("hitraceTest", 123);
- size_t requireArgc = 2;
- size_t argc = 2;
- napi_value args[2] = {nullptr};
+| API | Description |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| void OH_HiTrace_StartTraceEx(HiTrace_Output_Level level, const char* name, const char* customArgs) | Starts a synchronous time slice trace with the trace output level specified. |
+| void OH_HiTrace_FinishTraceEx(HiTrace_Output_Level level) | Stops a synchronous time slice trace with the trace output level specified. The value of **level** must be the same as that of **OH_HiTrace_StartTraceEx**.|
+| void OH_HiTrace_StartAsyncTraceEx(HiTrace_Output_Level level, const char* name, int32_t taskId, const char* customCategory, const char* customArgs) | Starts an asynchronous time slice trace with the trace output level specified. If multiple tracing tasks with the same name need to be performed at the same time, different task IDs must be specified through **taskId**. If the tracing tasks with the same name are not performed at the same time, the same task ID can be used.|
+| void OH_HiTrace_FinishAsyncTraceEx(HiTrace_Output_Level level, const char* name, int32_t taskId) | Stops an asynchronous time slice trace with the trace output level specified. Stops a tracing task. The values of **name** and **taskId** must be the same as those in **OH_HiTrace_StartAsyncTraceEx**.|
+| void OH_HiTrace_CountTraceEx(HiTrace_Output_Level level, const char* name, int64_t count) | Traces an integer with the trace output level specified. Traces the value changes of an integer variable.|
+| bool OH_HiTrace_IsTraceEnabled(void) | Checks whether application trace capture is enabled. If not, HiTraceMeter performance tracing is invalid.|
- napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);
+HiTraceMeter logging APIs are classified into three types by functionality/behavior: API for synchronous time slice tracing, API for asynchronous time slice tracing, and API for integer tracing. Both synchronous and asynchronous time slice tracing APIs are synchronous APIs. You can use HiTraceMeter APIs with [HiTraceChain](./hitracechain-guidelines-ndk.md) to perform tracing and analysis across devices, processes, and threads.
- napi_valuetype valuetype0;
- napi_typeof(env, args[0], &valuetype0);
+- The synchronous time slice tracing APIs are used in the scenario where tasks are executed in sequence.
+- The asynchronous time slice tracing APIs are used in the scenario where tasks are executed asynchronously. The start and end of an asynchronous trace task are not in sequence. Therefore, the **name** and **taskId** parameters are used to identify the start and end of an asynchronous trace task.
+- The integer tracing API is used to trace integer variables.
- napi_valuetype valuetype1;
- napi_typeof(env, args[1], &valuetype1);
+**Parameter Description**
- double value0;
- napi_get_value_double(env, args[0], &value0);
+| Name | Type | Description |
+| -------------- | ----------- | ------------------------------------------------------------ |
+| level | enum | Trace output level. Trace data whose levels are lower than the system threshold will not be output.
The log version threshold is **HITRACE_LEVEL_INFO**, and the nolog version threshold is **HITRACE_LEVEL_COMMERCIAL**.|
+| name | const char* | Name of the task or integer variable to trace. The value contains a maximum of 320 characters. If the value length exceeds this limit, excess content will be truncated.|
+| taskId | int32_t | Task ID. If multiple tasks with the same **name** are executed at the same time, you must set different **taskId** when calling **OH_HiTrace_StartAsyncTraceEx**.|
+| count | int64_t | Value of an integer variable. |
+| customCategory | const char* | Custom category name, which is used to collect asynchronous trace data of the same type. The value contains a maximum of 64 characters. If the value length exceeds this limit, excess content will be truncated.
If the category is not required, pass in an empty string.|
+| customArgs | const char* | Custom key-value pair. If there are multiple key-value pairs, separate them with commas (,), for example, **key1=value1,key2=value2**.
A maximum of 512 characters are output. If the **name** and **customCategory** parameters occupy too many characters, the value of **customArgs** may be truncated.
If this parameter is not required, pass in an empty string.|
- double value1;
- napi_get_value_double(env, args[1], &value1);
+## How to Develop
- napi_value sum;
- napi_create_double(env, value0 + value1, &sum);
+In the following example, the **OH_HiTrace_StartAsyncTraceEx** and **OH_HiTrace_FinishAsyncTraceEx** APIs are used in an NDK C/C++ application.
- return sum;
+1. Add **libhitrace_ndk.z.so** to **CMakeLists.txt**.
- }
- ```
+ ```
+ target_link_libraries(entry PUBLIC libhitrace_ndk.z.so)
+ ```
-4. Install the compiled HAP in the device. In the **cmd** window, run **hdc shell** to connect to the device, and run **hitrace --trace_begin app** to start trace.
-
- ```shell
- capturing trace...
- ```
+2. Include the **trace.h** header file in the source file.
-5. Click the newly installed HAP several times on the device, and then run **hitrace --trace_dump | grep hitraceTest** in the **shell** window to view the trace result.
-
- ```shell
- <...>-2477 (-------) [001] .... 396.427165: tracing_mark_write: S|2477|H:hitraceTest 123
- <...>-2477 (-------) [001] .... 396.427196: tracing_mark_write: F|2477|H:hitraceTest 123
- ```
+ ```c++
+ #include "hitrace/trace.h"
+ ```
+
+3. Trace performance data. The following uses an asynchronous trace as an example. (The sample code is a part of the default **hello.cpp** file. You only need to add related APIs at the required positions.)
+
+ ```c++
+ #include "napi/native_api.h"
+ #include "hitrace/trace.h"
+ static napi_value Add(napi_env env, napi_callback_info info)
+ {
+ // Start an asynchronous time slice trace.
+ OH_HiTrace_StartAsyncTraceEx(HITRACE_LEVEL_COMMERCIAL, "hitraceTest", 123, "categoryTest", "key=value");
+ // End the asynchronous time slice trace (The start and end points are for reference only. Add them to the code lines where you want to start and end the trace.)
+ OH_HiTrace_FinishAsyncTraceEx(HITRACE_LEVEL_COMMERCIAL, "hitraceTest", 123);
+ size_t requireArgc = 2;
+ size_t argc = 2;
+ napi_value args[2] = {nullptr};
+
+ napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);
+
+ napi_valuetype valuetype0;
+ napi_typeof(env, args[0], &valuetype0);
+
+ napi_valuetype valuetype1;
+ napi_typeof(env, args[1], &valuetype1);
+
+ double value0;
+ napi_get_value_double(env, args[0], &value0);
+
+ double value1;
+ napi_get_value_double(env, args[1], &value1);
+
+ napi_value sum;
+ napi_create_double(env, value0 + value1, &sum);
+
+ return sum;
+ }
+ ```
+
+4. Install the compiled HAP in the device. In the **cmd** window, run **hdc shell** to connect to the device, and run the following command to start tracing.
+
+ ```shell
+ $ hitrace --trace_begin app
+ ```
+
+5. Start the application, execute the service call logic (including HiTraceMeter APIs), and run the following commands to view trace data.
+
+ ```shell
+ $ hitrace --trace_dump | grep hitraceTest
+ $ hitrace --trace_finish
+ ```
+
+ The following is an example of the captured trace data:
+
+ ```text
+ <...>-26889 (-------) [001] .... 3100.023070: tracing_mark_write: S|26889|H:hitraceTest|123|M62|categoryTest|key=value
+ <...>-26889 (-------) [001] .... 3100.023080: tracing_mark_write: F|26889|H:hitraceTest|123|M62
+ ```
diff --git a/en/application-dev/displaymanager/displayManager-overview.md b/en/application-dev/displaymanager/displayManager-overview.md
index 219acd806831e44e6108e491763fc00543d89ba3..2e88af5b76d3c5ef42a2d2530ecd79fc7313bb49 100644
--- a/en/application-dev/displaymanager/displayManager-overview.md
+++ b/en/application-dev/displaymanager/displayManager-overview.md
@@ -12,5 +12,5 @@ For details about how to obtain display properties and listen for status changes
## Constraints
-- The Display and Screen APIs must be used in the system that supports the SystemCapability.Window.SessionManager capability. For details, see [SystemCapability](../reference/syscap.md).
+- The Display and Screen APIs must be used in the system that supports the SystemCapability.Window.SessionManager capability. For details, see [SystemCapability](../reference/syscap.md).
- In multi-display implementation, the Screen API is available only for system applications only, and certain APIs require the ohos.permission.CAPTURE_SCREEN permission.
diff --git a/en/application-dev/distributedservice/Readme-EN.md b/en/application-dev/distributedservice/Readme-EN.md
index eadddbaabf4180b6f0e1b46c85c8365d69094ab6..e9c7f1ae83431fb67d5f5699ed59432d89028c7b 100644
--- a/en/application-dev/distributedservice/Readme-EN.md
+++ b/en/application-dev/distributedservice/Readme-EN.md
@@ -1,4 +1,11 @@
-# Distributed Service Kit (Distributed Management Service)
+# Distributed Service Kit
- [Introduction to Distributed Service Kit](distributedservice-kit-intro.md)
- [Distributed Device Management Development](devicemanager-guidelines.md)
+- Distributed Ability Connection Management
+ - [UIAbility Connection Development](abilityconnectmanager-guidelines.md)
+
+ - [UIAbility and Extension Connection Development](distributedextension-guidelines.md)
+
+- Distributed Hardware Connection Management
+ - [Distributed Camera Development](camera-distributed.md)
\ No newline at end of file
diff --git a/en/application-dev/distributedservice/abilityconnectmanager-guidelines.md b/en/application-dev/distributedservice/abilityconnectmanager-guidelines.md
index ceb5936e3fed3cf386beb269504a2eae111a85d5..4082b32d8193fb42e7d648a9bb320388c2505e85 100644
--- a/en/application-dev/distributedservice/abilityconnectmanager-guidelines.md
+++ b/en/application-dev/distributedservice/abilityconnectmanager-guidelines.md
@@ -1,38 +1,47 @@
-# Cross-Device Connection Management
+# UIAbility Connection Development
## Introduction
-Cross-device connection management allows for mutual capability assistance between devices that form a Super Device through a distributed OS, providing users with a more efficient, immersive experience compared to that of a single device. For example, a camera application of the watch can start a camera function of the mobile phone to implement real-time image preview and remote photographing.
+Cross-device connection management allows for mutual capability assistance between devices that form a Super Device through a distributed OS, providing users with a more efficient, immersive experience compared to that of a single device. For example, a camera application of the watch can start a camera function of the mobile phone to implement real-time image preview and remote photographing.
### Available Capabilities
- Cross-device application startup: uses the application on the local device to start the same application on another device and perform collaborative operations.
-- Data interaction: implements cross-device transmission of data, including text messages, byte streams, images, and transport streams. (Only text interaction is supported for third-party applications.)
+- Data interaction: implements cross-device transmission of data.Such data includes text messages, byte streams, images, and transport streams (text interaction supported only for third-party applications).
### Typical Use Cases
-The transport stream feature allows users to start the peer camera from the local camera to access capabilities such as camera preview, text-based interaction, photo reception, and remote camera shutter.
+The transport stream feature allows users to start the peer camera from the local camera to access capabilities such as text-based interaction, camera preview, photo reception, and remote camera shutter.
### Basic Concepts
Before you get started, familiarize yourself with the following concepts:
-- **DMS**
+- **Distributed Management Service (DMS)**
- Distributed Management Service (DMS) is a framework that provides distributed component management capabilities.
+ A framework that provides distributed component management capabilities.
+- **UIAbility**
+
+ A component that implements tasks specific to application UIs, such as lifecycle management, user interaction, and UI rendering.
+
+- **Extension**
+
+ A component that extends application functions or implements cross-device collaboration. It allows applications to run some tasks in the background or migrates some functions to other devices for execution, implementing distributed capabilities.
+
+
- **Byte stream**
- Byte streams are data of the [ArrayBuffer](../arkts-utils/arraybuffer-object.md) type. They can be used to store binary data, for example, image or audio data.
+ Data of the [ArrayBuffer](../arkts-utils/arraybuffer-object.md) type, which can be used to store binary data, for example, image or audio data.
- **Transport stream**
- Transport streams are media streams that can be used to transmit images and video streams.
-
+ Media streams that can be used to transmit images and video streams.
+
### Implementation Principles
Cross-device connection management is built on a distributed component management framework. It implements JS object encapsulation on the distributed component management framework and establishes sessions between applications through this framework to perform cross-device collaboration. The data-based interaction capabilities are provided by the system.
@@ -47,9 +56,9 @@ Cross-device connection management is built on a distributed component managemen
- You need to log in with the same HUAWEI ID on different devices.
- Cross-device collaboration is supported only for UIAbility applications with the same bundle name on different devices.
-
+
- The byte stream, image, and transport stream capabilities are supported only for system applications.
-
+
- After the service collaboration is complete, the collaboration status must be ended in a timely manner. If an application does not apply for a continuous task, the collaboration lifecycle will be ended when the screen is locked or the application is switched to the background for more than 5 seconds.
- The distributed component management framework does not censor the transmitted content during the collaboration process. If privacy data is involved, it is recommended that the application employs measures such as data encryption and pop-up notification to enhance information security.
@@ -65,7 +74,7 @@ You have logged in to devices A and B with the same HUAWEI ID and the two device
### Setting Up the Environment
1. Download and install DevEco Studio on the PC. For details, see [Downloading Software](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-software-download-V5) and [Installing DevEco Studio](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-software-install-V5). The DevEco Studio version must be 4.1 or later.
-2. Update the public-SDK to API 16 or later. For details, see [Switching to Full SDK](../faqs/full-sdk-switch-guide.md).
+2. Update the public-SDK to API 18 or later. For details about how to update the SDK, see [OpenHarmony SDK Upgrade Assistant]( ../tools/openharmony_sdk_upgrade_assistant.md).
3. Connect device A and device B to the PC using USB cables.
4. Enable Bluetooth on device A and device B to implement networking.
@@ -100,18 +109,18 @@ The following table describes the APIs for cross-device connection management. F
| connect(sessionId: number): Promise<ConnectResult>; | Connects to the ability on the source side.|
| acceptConnect(sessionId: number, token: string): Promise<void>; | Connects to the ability on the sink side.|
| disconnect(sessionId: number): void; | Disconnects the ability connection.|
-| on(type: 'connect' \| 'disconnect' \| 'receiveMessage' \| 'receiveData' \| 'receiveImage', sessionId: number, callback: Callback<EventCallbackInfo>): void | Enables listening for the **connect**, **disconnect**, **receiveMessage**, **receiveData**, and **receiveImage** events.|
-| off(type: 'connect' \| 'disconnect' \| 'receiveMessage' \| 'receiveData' \| 'receiveImage', 'connect', sessionId: number, callback?: Callback<EventCallbackInfo>): void | Disables listening for the **connect**, **disconnect**, **receiveMessage**, **receiveData**, and **receiveImage** events.|
+| on(type: 'connect' \| 'disconnect' \| 'receiveMessage' \| 'receiveData' \| 'receiveImage', sessionId: number, callback: Callback<EventCallbackInfo>): void | Enable listening for the **connect**, **disconnect**, **receiveMessage**, **receiveData**, and **receiveImage **events.|
+| off(type: 'connect' \| 'disconnect' \| 'receiveMessage' \| 'receiveData' \| 'receiveImage', 'connect', sessionId: number, callback?: Callback<EventCallbackInfo>): void | Cancels listening for the **connect**, **disconnect**, **receiveMessage**, **receiveData**, and **receiveImage **events.|
| sendMessage(sessionId: number, msg: string): Promise<void>; | Sends a text message.|
-| sendData(sessionId: number, data: ArrayBuffer): Promise<void>; | Sends byte streams (supported only for system applications).|
-| sendImage(sessionId: number, image: image.PixelMap): Promise<void>; | Sends an image (supported only for system applications).|
-| createStream(sessionId: number, param: StreamParam): Promise<number>; | Creates transport streams (supported only for system applications).|
-| destroyStream(sessionId: number): void; | Destroys transport streams (supported only for system applications).|
+| sendData(sessionId: number, data: ArrayBuffer): Promise<void>; | Sends byte streams (supported only for system applications).|
+| sendImage(sessionId: number, image: image.PixelMap): Promise<void>; | Sends an image (supported only for system applications).|
+| createStream(sessionId: number, param: StreamParam): Promise<number>; | Creates transport streams (supported only for system applications).|
+| destroyStream(sessionId: number): void; | Destroys transport streams (supported only for system applications).|
### Development Procedure
-The application on device A starts and connects to the application on device B through the cross-device application management module. After the connection is successful, the applications on device A and device B register a callback listener for corresponding events through the **on** interface. The application on device A or device B calls **sendMessage**, **sendData**, **sendImage**, or **createStream** to send text messages, byte streams, or transport streams. The peer end performs subsequent service coordination based on the received callback.
+The application on device A starts and connects to the application on device B through the cross-device application management module. After the connection is successful, the applications on device A and device B register a callback listener for corresponding events through the **on** interface. The application on device A or device B calls **sendMessage**, **sendData**, **sendImage**, or **createStream** to send text messages, byte streams, or transport streams. The peer end performs subsequent service coordination based on the received callback.
#### Importing the AbilityConnectionManager Module File
@@ -125,9 +134,9 @@ The application on device A starts and connects to the application on device B t
The application on device A needs to discover device B and use its **netWorkId** as the input parameter of the collaboration API. You can call APIs of the distributed device management module to discover and select the peer device. For details, see [Distributed Device Management Development](devicemanager-guidelines.md).
-#### Create a session between applications and set up a connection between them.
+#### Initiating a Session Between Applications
-During the session and connection establishment, the applications on device A and device B perform different operations. In the subsequent development procedure, the application on device A serves as the connection initiator, while the application on device B serves as the connection receiver.
+During session establishment, the applications on device A and device B perform different operations. In the subsequent development procedure, the application on device A serves as the connection initiator, while the application on device B serves as the connection receiver.
##### Device A
@@ -270,7 +279,7 @@ After the application on device A calls **connect()**, the application on device
#### Enabling Event Listening
After the application creates a session and obtains the session ID, you can call **on()** to listen for the corresponding events and notify the listener through a callback.
-
+
```ts
import { abilityConnectionManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
@@ -290,7 +299,7 @@ After the application creates a session and obtains the session ID, you can call
abilityConnectionManager.on("receiveImage", this.sessionId,(callbackInfo) => {
hilog.info(0x0000, 'testTag', 'session receiveImage, sessionId is', callbackInfo.sessionId);
});
- ```
+ ```
#### Sending Data
@@ -307,7 +316,7 @@ After the applications are successfully connected, you can call **sendMessage()*
hilog.error(0x0000, 'testTag', "connect failed");
})
```
-
+
##### Sending Byte Streams
After the applications are successfully connected, you can call **sendData()** on device A or device B to send byte streams to the peer application. (This function is supported only for system applications.)
@@ -388,7 +397,7 @@ After the applications are successfully connected, you can call **createStream()
abilityConnectionManager.startStream(streamId);
})
```
-
+
#### Ending Collaboration
After the service collaboration is complete, the collaboration status must be ended in a timely manner. If service collaboration is required in a near future, you can call **disconnect()** to disconnect the connection between applications while retaining the session ID. This allows you to reuse the same session ID for establishing a connection next time. If service coordination is not required, you can directly call **destroyAbilityConnectionSession()** to destroy the session. In this case, the connection is automatically disconnected.
@@ -415,12 +424,13 @@ After application development is complete, you can install the application on de
1. Tap the **Connect** button of the application on device A. The application on device B is started.
2. Tap the **sendMessage** button of the application on device A. The application on device B triggers the callback of the **on()** API to receive the text strings.
+
3. Tap the **sendData** button of the application on device A. The application on device B triggers the callback of the **on()** API to receive the byte streams.
4. Tap the **sendImage** button of the application on device A. The application on device B triggers the callback of the **on()** API to receive the images.
5. Tap the **createStream** button of the application on device A. The application on device B triggers the callback of the **on()** API to receive the transport streams.
+
6. Tap the **Disconnect** button of the application on device A or device B. The connection between the two devices is disconnected. The callback of the **connect()** API is triggered to report a disconnection event to the applications on both devices.
-
## FAQs
### What should I do if the application on device A fails to start the application on device B?
diff --git a/en/application-dev/distributedservice/camera-distributed.md b/en/application-dev/distributedservice/camera-distributed.md
new file mode 100644
index 0000000000000000000000000000000000000000..dc782c12484b48cabdc2b8ac9c0b54b38c49cc5b
--- /dev/null
+++ b/en/application-dev/distributedservice/camera-distributed.md
@@ -0,0 +1,445 @@
+# Distributed Camera Development
+
+
+## Overview
+
+ OpenHarmony distributed camera implements collaboration across devices by breaking hardware boundaries. For example, after devices A and B running OpenHarmony are networked, the application on device A can call the camera resources of device B in real time to obtain images (preview stream, photo stream, or video stream) from device B. In addition, in-depth controls such as resolution adjustment and settings synchronization are supported on device A. Distributed camera achieves the following breakthroughs:
+ - Collaborative creation with multiple users
+ - Remote collaboration with experts
+ - Immersive security system
+ - Distributed audio and video interaction
+
+
+### Basic Concepts
+
+ Before started, you are advised to read the following topics to have a basic understanding of related functions:
+ - [UIAbility Connection Development](abilityconnectmanager-guidelines.md)
+ - [Camera Device Management (ArkTS)](../media/camera/camera-device-management.md)
+ - [Camera Development Preparations](../media/camera/camera-preparation.md)
+ - [Camera Session Management (ArkTS)](../media/camera/camera-session-management.md)
+ - [Photo Capture (ArkTS)](../media/camera/camera-shooting.md)
+ - [Video Recording (ArkTS)](../media/camera/camera-recording.md)
+
+
+## Preparing the Environment
+
+### Environment Requirements
+
+ Successful networking between device A and device B.
+
+
+### Environment Setup
+
+ 1. Install [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 5.0 or later.
+ 2. Update the public-SDK to API version 16 or later. For details, see [OpenHarmony SDK Upgrade Assistant](../tools/openharmony_sdk_upgrade_assistant.md).
+ 3. Connect device A and device B to the PC using USB cables.
+ 4. Connect device A and device B to the same Wi-Fi, identify each other, and start networking. For details, see [UIAbility Connection Development](abilityconnectmanager-guidelines.md#initiating-a-session-between-applications).
+
+
+### Environment Verification
+
+ Run the following shell command on the PC:
+
+ ```shell
+ hdc shell
+ hidumper -s 4700 -a "buscenter -l remote_device_info"
+ ```
+
+ If the networking is successful, the number of networking devices is displayed, for example, **remote device num = 1**.
+
+
+## How to Develop
+
+ OpenHarmony pools cameras on multiple devices to provide users with the capability of using cameras across devices.
+
+### Development Process
+
+ The figure below shows the recommended development process.
+
+ 
+
+
+### Development Procedure
+
+#### Importing the Camera and Multimedia Modules
+
+ ```ts
+ import { camera } from '@kit.CameraKit';
+ import { media } from '@kit.MediaKit';
+ ```
+
+#### Granting the Access Permission to the Application
+
+ The application should apply for required permissions, which include but are not limited to the following:
+ - For accessing the location of an image or a video: ohos.permission.MEDIA_LOCATION
+ - For reading files: ohos.permission.READ_MEDIA
+ - For writing files: ohos.permission.WRITE_MEDIA
+ - For using camera: ohos.permission.CAMERA
+ - For multi-device collaboration: ohos.permission.DISTRIBUTED_DATASYNC
+
+ For example, you can call **requestPermissionsFromUser()** to request the corresponding permissions for the UIAbility.
+ ```ts
+ //EntryAbility.ets
+ export default class EntryAbility extends UIAbility {
+ onCreate(want, launchParam) {
+ Logger.info('Sample_VideoRecorder', 'Ability onCreate,requestPermissionsFromUser');
+ let permissionNames: Array = ['ohos.permission.MEDIA_LOCATION', 'ohos.permission.READ_MEDIA',
+ 'ohos.permission.WRITE_MEDIA', 'ohos.permission.CAMERA', 'ohos.permission.MICROPHONE', 'ohos.permission.DISTRIBUTED_DATASYNC'];
+ abilityAccessCtrl.createAtManager().requestPermissionsFromUser(this.context, permissionNames).then((data)=> {
+ console.log("testTag", data);
+ })
+ .catch((err : BusinessError) => {
+ console.log("testTag", err.message);
+ });
+ }
+ ```
+
+
+#### Initiating the Preview Stream and Photo Stream on the Distributed Camera
+
+##### 1. Obtaining the Camera Information of a Remote Device
+
+ After the application networking is successful, you can use **getCameraManager()** to obtain the camera manager instance and **getSupportedCameras()** to obtain the supported camera device object.
+
+ ```ts
+ private cameras?: Array;
+ private cameraManager?: camera.CameraManager;
+ private cameraOutputCapability?: camera.CameraOutputCapability;
+ private cameraIndex: number = 0;
+ private curVideoProfiles?: Array;
+
+ function initCamera(): void {
+ console.info('init remote camera called');
+ if (this.cameraManager) {
+ console.info('cameraManager already exits');
+ return;
+ }
+ console.info('[camera] case to get cameraManager');
+ this.cameraManager = camera.getCameraManager(globalThis.abilityContext);
+ if (this.cameraManager) {
+ console.info('[camera] case getCameraManager success');
+ } else {
+ console.info('[camera] case getCameraManager failed');
+ return;
+ }
+ this.cameras = this.cameraManager.getSupportedCameras();
+ if (this.cameras) {
+ console.info('[camera] case getCameras success, size ', this.cameras.length);
+ for (let i = 0; i < this.cameras.length; i++) {
+ let came: camera.CameraDevice = this.cameras[i];
+ console.info('[came] camera json:', JSON.stringify(came));
+ if (came.connectionType == camera.ConnectionType.CAMERA_CONNECTION_REMOTE) {
+ this.cameraIndex = i;
+ this.cameraOutputCapability = this.cameraManager.getSupportedOutputCapability(came);
+ this.curVideoProfiles = this.cameraOutputCapability.videoProfiles;
+ console.info('init remote camera done'); // The remote camera is successfully initialized.
+ break;
+ }
+ }
+ } else {
+ console.info('[camera] case getCameras failed');
+ }
+ }
+ ```
+
+##### 2. Creating a CameraInput Instance
+
+ After obtaining the **CameraManager** instance and the supported camera device object, call **createCameraInput()** to create a **CameraInput** instance.
+
+ ```ts
+ // create camera input
+ async createCameraInput(): Promise {
+ console.log('createCameraInput called');
+ if (this.cameras && this.cameras.length > 0) {
+ let came: camera.CameraDevice = this.cameras[this.cameraIndex];
+ console.log('[came]createCameraInput camera json:', JSON.stringify(came));
+ this.cameraInput = this.cameraManager?.createCameraInput(came);
+ if (this.cameraInput) {
+ console.log('[camera] case createCameraInput success');
+ await this.cameraInput.open().then(() => {
+ console.log('[camera] case cameraInput.open() success');
+ }).catch((err: Error) => {
+ console.log('[camera] cameraInput.open then.error:', json.stringify(err));
+ });
+ } else {
+ console.log('[camera] case createCameraInput failed');
+ return;
+ }
+ }
+ }
+ ```
+
+##### 3. Obtaining the PreviewOutput Object
+
+ Use **createPreviewOutput()** to create a **PreviewOutput** object.
+
+ ```ts
+ private previewOutput?: camera.PreviewOutput;
+ private avConfig: media.AVRecorderConfig = {
+ videoSourceType: media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV,
+ profile: this.avProfile,
+ url: 'fd://',
+ }
+
+ // create camera preview
+ async createPreviewOutput(): Promise {
+ console.log('createPreviewOutput called');
+ if (this.cameraOutputCapability && this.cameraManager) {
+ this.previewProfiles = this.cameraOutputCapability.previewProfiles;
+ console.log('[camera] this.previewProfiles json ', json.stringify(this.previewProfiles));
+ if (this.previewProfiles[0].format === camera.CameraFormat.CAMERA_FORMAT_YUV_420_SP) {
+ console.log('[camera] case format is VIDEO_SOURCE_TYPE_SURFACE_YUV');
+ this.avConfig.videoSourceType = media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV;
+ } else {
+ console.log('[camera] case format is VIDEO_SOURCE_TYPE_SURFACE_ES');
+ this.avConfig.videoSourceType = media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_ES;
+ }
+ this.previewOutput = this.cameraManager.createPreviewOutput(this.previewProfiles[0], this.surfaceId);
+ if (!this.previewOutput) {
+ console.log('create previewOutput failed!');
+ }
+ console.log('createPreviewOutput done');
+ }
+ }
+ ```
+
+
+##### 4. Obtaining the PhotoOutput Object
+
+ Use **createPhotoOutput()** to create a **PhotoOutput** object and **createImageReceiver()** to create an **ImageReceiver** instance.
+
+ ```ts
+ import fileio from '@ohos.fileio';
+
+ private photoReceiver?: image.ImageReceiver;
+ private photoOutput?: camera.PhotoOutput;
+ private mSaveCameraAsset: SaveCameraAsset = new SaveCameraAsset('Sample_VideoRecorder');
+
+ async getImageFileFd(): Promise {
+ console.info'getImageFileFd called');
+ this.mFileAssetId = await this.mSaveCameraAsset.createImageFd();
+ this.fdPath = 'fd://' + this.mFileAssetId.toString();
+ this.avConfig.url = this.fdPath;
+ console.info('ImageFileFd is: ' + this.fdPath);
+ console.info('getImageFileFd done');
+ }
+
+ // close file fd
+ async closeFd(): Promise {
+ console.info('case closeFd called');
+ if (this.mSaveCameraAsset) {
+ await this.mSaveCameraAsset.closeVideoFile();
+ this.mFileAssetId = undefined;
+ this.fdPath = undefined;
+ console.info('case closeFd done');
+ }
+ }
+
+ async createPhotoOutput() {
+ const photoProfile: camera.Profile = {
+ format: camera.CameraFormat.CAMERA_FORMAT_JPEG,
+ size: {
+ "width": 1280,
+ "height": 720
+ }
+ }
+ if (!this.cameraManager) {
+ console.log('createPhotoOutput cameraManager is null')
+ }
+ if (!this.photoReceiver) {
+ this.photoReceiver = image.createImageReceiver(photoProfile.size.width, photoProfile.size.height, photoProfile.format, 8)
+ this.photoReceiver.on("imageArrival",()=>{
+ this.photoReceiver?.readNextImage((err,image)=>{
+ if (err || image === undefined) {
+ console.log('photoReceiver imageArrival on error')
+ return
+ }
+ image.getComponent(4, async (err, img) => {
+ if (err || img === undefined) {
+ console.log('image getComponent on error')
+ return
+ }
+ await this.getImageFileFd()
+ fileio.write(this.mFileAssetId, img.byteBuffer)
+ await this.closeFd()
+ await image.release()
+ console.log('photoReceiver image.getComponent save success')
+ })
+ })
+ })
+ await this.photoReceiver.getReceivingSurfaceId().then((surfaceId: string) => {
+ this.photoOutput = this.cameraManager?.createPhotoOutput(photoProfile, surfaceId)
+ if (!this.photoOutput) {
+ console.log('cameraManager.createPhotoOutput on error')
+ }
+ console.log('cameraManager.createPhotoOutput success')
+ this.photoOutput?.on("captureStart", (err, captureId) => {
+ console.log('photoOutput.on captureStart')
+ })
+ }).catch((err: Error) => {
+ console.error('photoReceiver.getReceivingSurfaceId on error:' + err)
+ })
+ }
+ }
+ ```
+
+##### 5. Creating a CaptureSession Instance
+
+ Use **createCaptureSession()** to create a **CaptureSession** instance. You can call **beginConfig()** to configure a session, call **addInput()** and **addOutput()** to add **CameraInput()** and **CameraOutput()** to the session, call **commitConfig()** to submit the configuration information, and use a promise to return the result.
+
+ ```ts
+ private captureSession?: camera.CaptureSession;
+
+ function failureCallback(error: BusinessError): Promise {
+ console.log('case failureCallback called,errMessage is ', json.stringify(error));
+ }
+
+ function catchCallback(error: BusinessError): Promise {
+ console.log('case catchCallback called,errMessage is ', json.stringify(error));
+ }
+
+ // create camera capture session
+ async createCaptureSession(): Promise {
+ console.log('createCaptureSession called');
+ if (this.cameraManager) {
+ this.captureSession = this.cameraManager.createCaptureSession();
+ if (!this.captureSession) {
+ console.log('createCaptureSession failed!');
+ return
+ }
+ try {
+ this.captureSession.beginConfig();
+ this.captureSession.addInput(this.cameraInput);
+ } catch (e) {
+ console.log('case addInput error:' + json.stringify(e));
+ }
+ try {
+ this.captureSession.addOutput(this.previewOutput);
+ } catch (e) {
+ console.log('case addOutput error:' + json.stringify(e));
+ }
+ await this.captureSession.commitConfig().then(() => {
+ console.log('captureSession commitConfig success');
+ }, this.failureCallback).catch(this.catchCallback);
+ }
+ }
+ ```
+
+##### 6. Starting the Session
+
+ Use **start()** of the **CaptureSession** instance to start the session and use a promise to return the result.
+
+ ```ts
+ // start captureSession
+ async startCaptureSession(): Promise {
+ console.log('startCaptureSession called');
+ if (!this.captureSession) {
+ console.log('CaptureSession does not exists!');
+ return
+ }
+ await this.captureSession.start().then(() => {
+ console.log('case start captureSession success');
+ }, this.failureCallback).catch(this.catchCallback);
+ }
+ ```
+
+#### Releasing Distributed Camera Resources
+
+ After the service collaboration is complete, the collaboration status needs to be ended in a timely manner to release distributed camera resources.
+
+ ```ts
+ // Release the camera.
+ async releaseCameraInput(): Promise {
+ console.log('releaseCameraInput called');
+ if (this.cameraInput) {
+ this.cameraInput = undefined;
+ }
+ console.log('releaseCameraInput done');
+ }
+
+ // Release the preview.
+ async releasePreviewOutput(): Promise {
+ console.log('releasePreviewOutput called');
+ if (this.previewOutput) {
+ await this.previewOutput.release().then(() => {
+ console.log('[camera] case main previewOutput release called');
+ }, this.failureCallback).catch(this.catchCallback);
+ this.previewOutput = undefined;
+ }
+ console.log('releasePreviewOutput done');
+ }
+
+ // Release the video output.
+ async releaseVideoOutput(): Promise {
+ console.log('releaseVideoOutput called');
+ if (this.videoOutput) {
+ await this.videoOutput.release().then(() => {
+ console.log('[camera] case main videoOutput release called');
+ }, this.failureCallback).catch(this.catchCallback);
+ this.videoOutput = undefined;
+ }
+ console.log('releaseVideoOutput done');
+ }
+
+ // Stop the capture session.
+ async stopCaptureSession(): Promise {
+ console.log('stopCaptureSession called');
+ if (this.captureSession) {
+ await this.captureSession.stop().then(() => {
+ console.log('[camera] case main captureSession stop success');
+ }, this.failureCallback).catch(this.catchCallback);
+ }
+ console.log('stopCaptureSession done');
+ }
+
+ // Release the capture session.
+ async releaseCaptureSession(): Promise {
+ console.log('releaseCaptureSession called');
+ if (this.captureSession) {
+ await this.captureSession.release().then(() => {
+ console.log('[camera] case main captureSession release success');
+ }, this.failureCallback).catch(this.catchCallback);
+ this.captureSession = undefined;
+ }
+ console.log('releaseCaptureSession done');
+ }
+
+ // Release the camera resource.
+ async releaseCamera(): Promise {
+ console.log('releaseCamera called');
+ await this.stopCaptureSession();
+ await this.releaseCameraInput();
+ await this.releasePreviewOutput();
+ await this.releaseVideoOutput();
+ await this.releaseCaptureSession();
+ console.log('releaseCamera done');
+ }
+ ```
+
+### Debugging and Verification
+
+ After application development is complete, you can install the application on device A and device B. The test procedure is as follows:
+
+ 1. Device A starts the distributed camera on device B and initiates a preview. Device A can receive the preview stream.
+ 2. Device A starts the distributed camera on device B and takes a photo. Device A can receive the photo.
+
+## FAQs
+
+
+### What should I do if the application on device A cannot start the camera on device B?
+
+**Possible Causes**
+
+ Devices are not networked or are disconnected after networking.
+
+**Solution**
+
+ Enable USB debugging on device A and device B, and use a USB cable to connect the devices to the PC. Run the following shell command on the PC:
+
+ ```shell
+ hdc shell
+ hidumper -s 4700 -a "buscenter -l remote_device_info"
+ ```
+ If **remote device num = 0** is displayed in the command output, the networking fails. In this case, disable and then enable Wi-Fi, and connect devices to the same Wi-Fi again. If the networking is successful, run the shell command again and the number of networking devices is displayed, for example, **remote device num = 1**.
+
+
\ No newline at end of file
diff --git a/en/application-dev/distributedservice/distributedextension-guidelines.md b/en/application-dev/distributedservice/distributedextension-guidelines.md
new file mode 100644
index 0000000000000000000000000000000000000000..11dbb69c8edeb6b6cfb3e05692d83406b89438d3
--- /dev/null
+++ b/en/application-dev/distributedservice/distributedextension-guidelines.md
@@ -0,0 +1,188 @@
+# UIAbility and Extension Connection Development
+
+## Introduction
+
+The distributed service allows a device to extend its capabilities by cooperating with other devices in various complex scenarios.
+
+As it is inconvenient for users to use a single account on different devices, the cross-device collaboration capability is provided, enabling a message synchronization mechanism for collaboration between applications on mobile phones and other devices such as watches.
+
+### Available Capabilities
+
+Data interaction: implements cross-device transmission of data, including text messages, byte streams, images, and transport streams. (Only text interaction is supported for third-party applications.)
+
+### Typical Use Cases
+
+During cross-device collaboration, when device A is running in the background and device B is running in the foreground, Distributed Management Service (DMS) allows the system to activate **DistributedExtension** to implement synchronous data transmission across devices. For example, when an application runs in the background on the mobile phone and in the foreground on the watch, DMS starts **DistributedExtension** to synchronize uplink messages on the watch to the application on the mobile phone.
+
+### Basic Concepts
+
+Before you get started, familiarize yourself with the following concepts:
+
+* **Distributed Management Service (DMS)**
+
+ A framework that provides distributed component management capabilities.
+* **UIAbility**
+
+ A component that implements tasks specific to application UIs, such as lifecycle management, user interaction, and UI rendering.
+* **Extension**
+
+ A component that extends application functions or implements cross-device collaboration. It allows applications to run some tasks in the background or migrates some functions to other devices for execution, implementing distributed capabilities.
+* **Byte stream**
+
+ Data of the [ArrayBuffer](https://gitee.com/openharmony/docs/blob/master/en/application-dev/arkts-utils/arraybuffer-object.md) type, which can be used to store binary data, for example, image or audio data.
+* **Transport stream**
+
+ Media streams that can be used to transmit images, audios, text information, and bytes.
+
+## Implementation Principles
+
+The application on device A integrates **DistributedExtension**. When DSoftBus on device A receives a message from the application, **DistributedExterntion** starts the application background service on device A to send the application message from device B to the application service.
+
+
+
+## Constraints
+
+* You need to log in with the same HUAWEI ID on different devices.
+* Cross-device collaboration is supported only for UIAbility applications with the same bundle name on different devices.
+
+## Setting Up the Environment
+
+### Environment Requirements
+
+You have logged in to devices A and B with the same HUAWEI ID and the two devices are successfully networked through Bluetooth.
+
+### Environment Setup
+
+1. Install [DevEco Studio](https://gitee.com/link?target=https%3A%2F%2Fdeveloper.huawei.com%2Fconsumer%2Fcn%2Fdownload%2Fdeveco-studio) 4.1 or later on the PC.
+2. Update the public-SDK to API 18 or later. For details about how to update the SDK, see [OpenHarmony SDK Upgrade Assistant](../tools/openharmony_sdk_upgrade_assistant.md).
+3. Enable Bluetooth on devices A and B to implement networking.
+
+### Verifying the Environment
+
+Connect devices A and B to the PC and run the shell command on the PC:
+
+```shell
+hdc shell
+hidumper -s 4700 -a "buscenter -l remote_device_info"
+```
+
+If the networking is successful, the number of networking devices is displayed, for example, **remote device num = 1**.
+
+## How to Develop
+
+Cross-device connection management enables real-time processing of application background messages through the distributed OS, providing users with more efficient experience.
+
+### Available APIs
+
+For details about how to use the **DistributedExtensionAbility** APIs, see [DistributedExtensionAbility API Reference](../reference/apis-distributedservice-kit/js-apis-distributedExtensionAbility-sys.md).
+
+| API | Description |
+| -------------------------------------------------------------------- | -------------------------- |
+| onCreate(want: Want): void; | Creates a distributed collaboration task. |
+| onDestroy(): void; | Destroys a distributed collaboration task. |
+| onCollaborate(wantParam: Record): AbilityConstant.CollaborateResult; | Called when distributed collaboration is requested.|
+
+### Development Procedure
+
+1. Register the `Extension` component in the configuration file.
+
+ In the application configuration file `module.json5`, add the `"extensionAbilities"` field, set `"type"` to `"distributed"`, and add an entry whose `"name"` is `"ohos.extension.DistributedExtension"` to [metadata](../reference/apis-ability-kit/js-apis-bundleManager-metadata.md).
+
+ Example:
+
+ ```json
+ "extensionAbilities": [
+ {
+ "name": "EntrydistributedAbility",
+ "srcEntry": "./ets/entrybackupability/EntryDistributedAbility.ets",
+ "type": "distributed",
+ "exported": false,
+ "metadata": [
+ {
+ "name": "ohos.extension.DistributedExtension",
+ }
+ ],
+ "srcEntry": "./ets/common/MDSExtension.ts",
+ }
+ ]
+ ```
+2. Import the required modules.
+
+ ```ts
+ import { AbilityConstant } from '@kit.AbilityKit';
+ import { connection } from '@kit.NetworkKit';
+ import { AsyncCallback,BusinessError } from '@kit.BasicServicesKit';
+ import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit'
+ import {DistributedExtensionAbility} from '@kit.DistributedServiceKit';
+ ```
+3. Customize the `MDSExtension.ets` file. Specifically, inherit the `DistributedExtensionAbility` class and rewrite the `onCreate`, `onDestroy`, and `onCollaborate` methods to create and destroy **DistributedExtension** and implement connection callback.
+
+ The following is an empty `MDSExtension.ets` file. You can observe its lifecycle based on the corresponding **Logger**.
+
+ ```ts
+ import DistributedExtensionAbility from '@ohos.application.DistributedExtensionAbility';
+ import Logger from '../common/Logger'
+ import abilityConnectionManager from '@ohos.distributedsched.abilityConnectionManager';
+ import { AbilityConstant } from '@kit.AbilityKit';
+ import { connection } from '@kit.NetworkKit';
+ import { AsyncCallback,BusinessError } from '@kit.BasicServicesKit';
+ import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit'
+
+
+ const TAG = `FileDistributedExtensionAbility`;
+
+ export default class DistributedExtension extends DistributedExtensionAbility {
+ onCreate (want) {
+ Logger.info(TAG, `DistributedExterntion Create ok`);
+ Logger.info(TAG, `DistributedExterntion on Create want : ${JSON.stringify(want)}`);
+ Logger.info(TAG, `DistributedExterntion on Create end`);
+ }
+
+ onCollaborate (wantParam: Record) {
+ Logger.info(TAG, `DistributedExterntionon onCollabRequest Accept to the result of Ability collaborate`);
+ let sessionId = -1;
+ const collabrationType = wantParam["CollaborationKeys.COLLABORATE_TYPE"] as abilityConnectionManager.CollabrationType;
+ if (collabrationType == undefined) {
+ return sessionId;
+ }
+
+ Logger.info(TAG, `onCollab, peerInfo: ${JSON.stringify(collabrationType)}`);
+ return AbilityConstant.CollaborateResult.ACCEPT;
+ }
+
+ onDestroy () {
+ Logger.info(TAG, `DistributedExterntion onDestroy ok`);
+ }
+ }
+ ```
+
+## FAQs
+
+### What should I do if device B does not receive the response message from device A?
+
+**Possible Cause**
+
+Devices are not networking. As a result, the connection between device A and device B times out.
+
+**Solution**
+
+Enable USB debugging on device A and device B, and use a USB cable to connect the devices to the PC. Run the following shell command on the PC:
+
+```
+hdc shell
+hidumper -s 4700 -a "buscenter -l remote_device_info"
+```
+
+If **remote device num = 0** is displayed in the command output, the networking has failed. Ensure that you log in to devices using the same HUAWEI ID and connect them through Bluetooth. If the networking is successful, the number of networking devices is displayed, for example, **remote device num = 1**.
+
+### What should I do if ongoing collaboration services are interrupted because no operation is performed on the application for a long time?
+
+**Possible Cause**
+
+During service collaboration, DMS keeps listening for the collaboration lifecycle. After the operation lasts for 10 seconds, the collaboration is ended.
+
+**Solution**
+
+Resend the message to restart the collaboration.
+
+
\ No newline at end of file
diff --git a/en/application-dev/distributedservice/figures/camera-distributed-process.png b/en/application-dev/distributedservice/figures/camera-distributed-process.png
new file mode 100644
index 0000000000000000000000000000000000000000..cccd836e5704fb8187b787d01fef7fae45ee1afd
Binary files /dev/null and b/en/application-dev/distributedservice/figures/camera-distributed-process.png differ
diff --git a/en/application-dev/distributedservice/figures/distributedextension.png b/en/application-dev/distributedservice/figures/distributedextension.png
new file mode 100644
index 0000000000000000000000000000000000000000..ddcaf6669eed39acfb1e1f23eea9e581e780e0b4
Binary files /dev/null and b/en/application-dev/distributedservice/figures/distributedextension.png differ
diff --git a/en/application-dev/ffrt/Readme-EN.md b/en/application-dev/ffrt/Readme-EN.md
index 905f1596ff19dd2e05e08084f1eda9bba8d7ae3e..6f7a3dd55c5498f406c136abbe49d8223c28d113 100644
--- a/en/application-dev/ffrt/Readme-EN.md
+++ b/en/application-dev/ffrt/Readme-EN.md
@@ -1,4 +1,14 @@
# FFRT
- [Introduction to Function Flow Runtime Kit](ffrt-overview.md)
+- [Function Flow Runtime Paradigms](ffrt-concurrency-paradigm.md)
+- Function Flow Runtime Development Samples (C)
+ - [Serial Queue (C)](ffrt-concurrency-serial-queue-c.md)
+ - [Concurrent Queue (C)](ffrt-concurrency-concurrent-queue-c.md)
+ - [Task Graph (C)](ffrt-concurrency-graph-c.md)
+- Function Flow Runtime Development Samples (C++)
+ - [Serial Queue (C++)](ffrt-concurrency-serial-queue-cpp.md)
+ - [Concurrent Queue (C++)](ffrt-concurrency-concurrent-queue-cpp.md)
+ - [Task Graph (C++)](ffrt-concurrency-graph-cpp.md)
- [Function Flow Runtime Development](ffrt-development-guideline.md)
+- [Function Flow Runtime C APIs](ffrt-api-guideline-c.md)
diff --git a/en/application-dev/ffrt/ffrt-api-guideline-c.md b/en/application-dev/ffrt/ffrt-api-guideline-c.md
new file mode 100644
index 0000000000000000000000000000000000000000..c8ef1d5f9dff9689d1190a07c78572826ae682af
--- /dev/null
+++ b/en/application-dev/ffrt/ffrt-api-guideline-c.md
@@ -0,0 +1,2362 @@
+# Function Flow Runtime C APIs
+
+## Task Management
+
+### ffrt_deps_t
+
+#### Declaration
+
+```c
+typedef enum {
+ ffrt_dependence_data,
+ ffrt_dependence_task,
+} ffrt_dependence_type_t;
+
+typedef struct {
+ ffrt_dependence_type_t type;
+ const void* ptr;
+} ffrt_dependence_t;
+
+typedef struct {
+ uint32_t len;
+ const ffrt_dependence_t* items;
+} ffrt_deps_t;
+```
+
+#### Parameters
+
+- `len`: number of data dependencies.
+- `items`: data dependency array. The data length is equal to `len`.
+- `ptr`: data address.
+- `type`: data type. It is different from `task_handle`.
+
+#### Description
+
+The function of `ffrt_dependence_t` is the same as that of `dependence` in C++, and the function of `ffrt_deps_t` is the same as that of `std::vector` in C++.
+
+#### Example
+
+```c
+// Create a data dependency.
+int x = 0;
+ffrt_dependence_t dependence[1];
+dependence[0].type = ffrt_dependence_data;
+dependence[0].ptr = &x;
+ffrt_deps_t deps;
+deps.len = 1;
+deps.items = dependence;
+
+// Create a task dependency.
+ffrt_task_handle_t task = ffrt_submit_h_base(user_function_header, NULL, NULL, &attr);
+ffrt_dependence_t dependence[1];
+dependence[0].type = ffrt_dependence_task;
+dependence[0].ptr = task;
+ffrt_deps_t deps;
+deps.len = 1;
+deps.items = dependence;
+```
+
+### ffrt_task_attr_t
+
+#### Declaration
+
+```c
+typedef struct {
+ uint32_t storage[(ffrt_task_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)];
+} ffrt_task_attr_t;
+```
+
+#### Description
+
+Describes the task attribute, which can be configured using `ffrt_task_attr_t` when submitting a common task or queue task.
+
+#### Methods
+
+##### ffrt_task_attr_init
+
+```c
+FFRT_C_API int ffrt_task_attr_init(ffrt_task_attr_t* attr);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+
+Return Values
+
+- The value **0** indicates success, and the value **-1** indicates failure.
+
+Description
+
+- Initializes an `ffrt_task_attr_t` object.
+
+##### ffrt_task_attr_destroy
+
+```c
+FFRT_C_API void ffrt_task_attr_destroy(ffrt_task_attr_t* attr);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+
+Description
+
+- Destroys an `ffrt_task_attr_t` object.
+
+##### ffrt_task_attr_set_name
+
+```c
+FFRT_C_API void ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+- `name`: task name.
+
+Description
+
+- Sets the task name, which is valid for printing maintenance and test information.
+
+##### ffrt_task_attr_get_name
+
+```c
+FFRT_C_API const char* ffrt_task_attr_get_name(const ffrt_task_attr_t* attr);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+
+Return Values
+
+- Task name.
+
+Description
+
+- Obtains the task name.
+
+##### ffrt_task_attr_set_qos
+
+```c
+FFRT_C_API void ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+- `qos`: QoS.
+
+Description
+
+- Sets the task QoS, which determines the system resource supply during task execution. If QoS is not set, the queue QoS is inherited by default. The default QoS of a common task is `ffrt_qos_default`.
+
+##### ffrt_task_attr_get_qos
+
+```c
+FFRT_C_API ffrt_qos_t ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+
+Return Values
+
+- QoS.
+
+Description
+
+- Obtains the configured QoS.
+
+##### ffrt_task_attr_set_delay
+
+```c
+FFRT_C_API void ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+- `delay_us`: scheduling delay. The unit is μs.
+
+Description
+
+- Sets the scheduling delay of a task. The task is scheduled and executed after the delay interval. If delay is not set, the value is **0** by default.
+
+##### ffrt_task_attr_get_delay
+
+```c
+FFRT_C_API uint64_t ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+
+Return Values
+
+- Scheduling delay.
+
+Description
+
+- Obtains the configured scheduling delay.
+
+##### ffrt_task_attr_set_queue_priority
+
+```c
+FFRT_C_API void ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+- `priority`: task priority.
+
+Description
+
+- Sets the task priority. Currently, only concurrent queue tasks support the priority function. Tasks in the same concurrent queue are scheduled based on their priorities. If the priority is not set, `ffrt_queue_priority_low` is used by default.
+
+##### ffrt_task_attr_get_queue_priority
+
+```c
+FFRT_C_API ffrt_queue_priority_t ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+
+Return Values
+
+- Task priority.
+
+Description
+
+- Obtains the configured priority.
+
+##### ffrt_task_attr_set_stack_size
+
+```c
+FFRT_C_API void ffrt_task_attr_set_stack_size(ffrt_task_attr_t* attr, uint64_t size);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+- `size`: size of the coroutine stack, in bytes.
+
+Description
+
+- Sets the size of the coroutine stack, which affects the maximum space used by the call stack during task execution. If this parameter is not set, the default size of the coroutine stack is 1 MB.
+
+##### ffrt_task_attr_get_stack_size
+
+```c
+FFRT_C_API uint64_t ffrt_task_attr_get_stack_size(const ffrt_task_attr_t* attr);
+```
+
+Parameters
+
+- `attr`: pointer to the `ffrt_task_attr_t` object.
+
+Return Values
+
+- Size of the coroutine stack.
+
+Description
+
+- Obtains the size of the coroutine stack.
+
+#### Example
+
+```c
+// Submit a common task. The task name is sample_task, the QoS is background, the scheduling delay is 1 ms, and the coroutine stack size is 2 MB.
+ffrt_task_attr_t attr;
+ffrt_task_attr_init(&attr);
+ffrt_task_attr_set_name(&attr, "sample_task");
+ffrt_task_attr_set_qos(&attr, ffrt_qos_background);
+ffrt_task_attr_set_delay(&attr, 1000);
+ffrt_task_attr_set_stack_size(&attr, 2 * 1024 * 1024);
+ffrt_submit_base(user_function_header, NULL, NULL, &attr);
+ffrt_task_attr_destroy(&attr);
+```
+
+### ffrt_alloc_auto_managed_function_storage_base
+
+#### Declaration
+
+```c
+typedef enum {
+ ffrt_function_kind_general,
+ ffrt_function_kind_queue,
+} ffrt_function_kind_t;
+
+typedef void(*ffrt_function_t)(void*);
+typedef struct {
+ ffrt_function_t exec;
+ ffrt_function_t destroy;
+ uint64_t reserve[2];
+} ffrt_function_header_t;
+
+FFRT_C_API void *ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind);
+```
+
+#### Parameters
+
+- `kind`: `ffrt_function_kind_general` for submitting a common task; `ffrt_function_kind_queue` for submitting a queue task.
+- `exec`: function pointer invoked during task execution.
+- `destroy`: function pointer invoked after a task is complete. It can be used to destroy resources.
+- `reserve`: internal reserved space. It cannot be used by users.
+
+#### Return Values
+
+- Pointer to the executor of the user task.
+
+#### Description
+
+Allocates memory space. The header of the memory space is in the `ffrt_function_header_t` structure. The return pointer can be converted into the `ffrt_function_header_t*` pointer. A 64-byte space is reserved after the header for customizing the space for storing input parameters or return values.
+
+#### Example
+
+- Example 1: Generate a task executor without parameters and return values.
+
+ ```c
+ #include
+ #include "ffrt/task.h"
+
+ void foo(void* data)
+ {
+ printf("foo\n");
+ }
+
+ void after_foo(void* data)
+ {
+ printf("after_foo\n");
+ }
+
+ int main()
+ {
+ ffrt_function_header_t* func = (ffrt_function_header_t*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
+
+ func->exec = foo;
+ func->destroy = after_foo;
+
+ ffrt_submit_base(func, NULL, NULL, NULL);
+ ffrt_wait();
+
+ return 0;
+ }
+ ```
+
+- Example 2: Generate a task executor with parameters and return values.
+
+ ```c
+ #include
+ #include "ffrt/task.h"
+
+ int foo(int x, int y)
+ {
+ printf("foo: x = %d, y = %d\n", x, y);
+ return x + y;
+ }
+
+ void after_foo(void* data)
+ {
+ printf("after_foo\n");
+ }
+
+ // Custom task executor, which can carry parameters and return values.
+ typedef struct {
+ ffrt_function_header_t header; // The header space is ffrt_function_header_t.
+ int arg1; // Argument 1
+ int arg2; // Argument 2
+ int ret; // Return value
+ } user_defined_function;
+
+ // Wrap foo into the exec function type of void(*)(void*).
+ void exec_func_wrapper(void* header)
+ {
+ user_defined_function* func = (user_defined_function*)header;
+ func->ret = foo(func->arg1, func->arg2); // Expand the foo function, pass arguments, and obtain the return value.
+ }
+
+ int main()
+ {
+ user_defined_function* func = (user_defined_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
+
+ func->header.exec = exec_func_wrapper;
+ func->header.destroy = after_foo;
+ func->arg1 = 1;
+ func->arg2 = 2;
+
+ ffrt_submit_base((ffrt_function_header_t*)func, NULL, NULL, NULL);
+ ffrt_wait();
+
+ printf("ret = %d\n", func->ret);
+ return 0;
+ }
+ ```
+
+### ffrt_submit_base
+
+#### Declaration
+
+```c
+FFRT_C_API void ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr);
+```
+
+#### Parameters
+
+- `f`: task executor of a user. The value can be of the native `ffrt_function_header_t` type or a custom extension type based on `ffrt_function_header_t`.
+- `in_deps`: input data dependency of a task. It is usually expressed as the actual data address. `ffrt_task_handle_t` can also be used as a special input dependency.
+- `out_deps`: output data dependency of a task. It is usually expressed as the actual data address. `ffrt_task_handle_t` is not supported.
+- `attr`: task attribute.
+
+#### Description
+
+Submits a common task that supports attribute settings. After the input dependency is removed, the task can be scheduled and executed. After the task is executed, the output dependency is removed.
+
+#### Example
+
+- Example 1: Submit a task with attributes.
+
+ ```c
+ #include
+ #include "ffrt/task.h"
+
+ void foo(void* data)
+ {
+ printf("foo\n");
+ }
+
+ void after_foo(void* data)
+ {
+ printf("after_foo\n");
+ }
+
+ int main()
+ {
+ // Submit a task.
+ ffrt_function_header_t* func = (ffrt_function_header_t*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
+ func->exec = foo;
+ func->destroy = after_foo;
+ ffrt_submit_base(func, NULL, NULL, NULL);
+
+ // Submit a task with attributes.
+ ffrt_task_attr_t attr;
+ ffrt_task_attr_init(&attr);
+ ffrt_task_attr_set_name(&attr, "sample_task");
+ ffrt_task_attr_set_qos(&attr, ffrt_qos_background);
+ ffrt_submit_base(func, NULL, NULL, &attr);
+
+ return 0;
+ }
+ ```
+
+- Example 2: Submit a task with data dependency.
+
+ ```c
+ // Submit two tasks with data dependency. The Read-After-Write dependency exists between tasks.
+ #include
+ #include
+ #include "ffrt/task.h"
+
+ void cos_func(float* x, float* y)
+ {
+ *y = cos(*x);
+ }
+
+ void tan_func(float* y, float* z)
+ {
+ *z = tan(*y);
+ }
+
+ typedef struct {
+ ffrt_function_header_t header;
+ float* arg1; // Argument 1
+ float* arg2; // Argument 2
+ } user_defined_function;
+
+ void cos_func_wrapper(void* header)
+ {
+ user_defined_function* func = (user_defined_function*)header;
+ cos_func(func->arg1, func->arg2);
+ }
+
+ void tan_func_wrapper(void* header)
+ {
+ user_defined_function* func = (user_defined_function*)header;
+ tan_func(func->arg1, func->arg2);
+ }
+
+ void destroy(void* header) {}
+
+ int main()
+ {
+ float x = 0.5f, y, z;
+
+ user_defined_function* func1 = (user_defined_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
+ func1->header.exec = cos_func_wrapper;
+ func1->header.destroy = destroy;
+ func1->arg1 = &x;
+ func1->arg2 = &y;
+
+ user_defined_function* func2 = (user_defined_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
+ func2->header.exec = tan_func_wrapper;
+ func2->header.destroy = destroy;
+ func2->arg1 = &y;
+ func2->arg2 = &z;
+
+ ffrt_dependence_t dependence_x[1];
+ dependence_x[0].type = ffrt_dependence_data;
+ dependence_x[0].ptr = &x;
+ ffrt_deps_t deps_x;
+ deps_x.len = 1;
+ deps_x.items = dependence_x;
+ ffrt_dependence_t dependence_y[1];
+ dependence_y[0].type = ffrt_dependence_data;
+ dependence_y[0].ptr = &y;
+ ffrt_deps_t deps_y;
+ deps_y.len = 1;
+ deps_y.items = dependence_y;
+ ffrt_dependence_t dependence_z[1];
+ dependence_z[0].type = ffrt_dependence_data;
+ dependence_z[0].ptr = &z;
+ ffrt_deps_t deps_z;
+ deps_z.len = 1;
+ deps_z.items = dependence_z;
+
+ ffrt_submit_base((ffrt_function_header_t*)func1, &deps_x, &deps_y, NULL);
+ ffrt_submit_base((ffrt_function_header_t*)func2, &deps_y, &deps_z, NULL);
+
+ ffrt_wait();
+ printf("x = %f, y = %f, z = %f\n", x, y, z);
+ return 0;
+ }
+ ```
+
+### ffrt_submit_h_base
+
+#### Declaration
+
+```c
+typedef void* ffrt_task_handle_t;
+
+FFRT_C_API ffrt_task_handle_t ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr);
+```
+
+#### Parameters
+
+- `f`: task executor of a user. The value can be of the native `ffrt_function_header_t` type or a custom extension type based on `ffrt_function_header_t`.
+- `in_deps`: input data dependency of a task. It is usually expressed as the actual data address. `ffrt_task_handle_t` can also be used as a special input dependency.
+- `out_deps`: output data dependency of a task. It is usually expressed as the actual data address. `ffrt_task_handle_t` is not supported.
+- `attr`: task attribute.
+
+#### Return Values
+
+- `ffrt_task_handle_t` task handle.
+
+#### Description
+
+Compared with the `ffrt_submit_base` API, the return value of the task handle is added.
+
+#### Example
+
+```c
+// Submit a task and obtain the task handle.
+ffrt_function_header_t* func = (ffrt_function_header_t*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
+func->exec = foo;
+func->destroy = after_foo;
+ffrt_task_handle_t t = ffrt_submit_h_base(func, NULL, NULL, NULL);
+// Note that ffrt_task_handle_t of the C API needs to be explicitly destroyed by calling ffrt_task_handle_destroy.
+ffrt_task_handle_destroy(t);
+```
+
+### ffrt_task_handle_inc_ref
+
+#### Declaration
+
+```c
+FFRT_C_API uint32_t ffrt_task_handle_inc_ref(ffrt_task_handle_t handle);
+```
+
+#### Parameters
+
+- `handle`: task handle.
+
+#### Return Values
+
+- Reference count of a task.
+
+#### Description
+
+Increases the reference count of the task through the task handle by one each time the task handle is invoked. It is used to control the task lifecycle. When the reference count is not 0, the corresponding task resources are not released. Note that `ffrt_task_handle_t` returned by `ffrt_submit_h_base` has a reference count by default. By default, you can subtract a reference count when using `ffrt_task_handle_destroy` to destroy `ffrt_task_handle_t`.
+
+### ffrt_task_handle_dec_ref
+
+#### Declaration
+
+```c
+FFRT_C_API uint32_t ffrt_task_handle_dec_ref(ffrt_task_handle_t handle);
+```
+
+#### Parameters
+
+- `handle`: task handle.
+
+#### Return Values
+
+- Reference count of a task.
+
+#### Description
+
+Subtracts the reference count of the task through the task handle by one each time the task handle is invoked.
+
+### ffrt_task_handle_destroy
+
+#### Declaration
+
+```c
+FFRT_C_API void ffrt_task_handle_destroy(ffrt_task_handle_t handle);
+```
+
+#### Parameters
+
+- `handle`: task handle.
+
+#### Description
+
+Destroys a task handle and subtracts a task reference count by default.
+
+### ffrt_wait
+
+#### Declaration
+
+```c
+FFRT_C_API void ffrt_wait(void);
+```
+
+#### Description
+
+Waits until all tasks of the same level submitted earlier are complete.
+
+#### Example
+
+```c
+// Wait until three tasks are complete.
+ffrt_submit_base(func1, NULL, NULL, NULL);
+ffrt_submit_base(func2, NULL, NULL, NULL);
+ffrt_submit_base(func3, NULL, NULL, NULL);
+ffrt_wait();
+```
+
+### ffrt_wait_deps
+
+#### Declaration
+
+```c
+FFRT_C_API void ffrt_wait_deps(const ffrt_deps_t* deps);
+```
+
+#### Parameters
+
+- `deps`: data dependency to be synchronized.
+
+#### Description
+
+Waits until the data dependency is removed.
+
+#### Example
+
+```c
+// Build the data dependency of x.
+int x = 0;
+ffrt_dependence_t dependence[1];
+dependence[0].type = ffrt_dependence_data;
+dependence[0].ptr = &x;
+ffrt_deps_t deps;
+deps.len = 1;
+deps.items = dependence;
+
+// Submit a write task.
+ffrt_submit_base(func, NULL, &deps, NULL);
+
+// Wait until the data dependency of the write task is removed.
+ffrt_wait_deps(&deps);
+```
+
+### ffrt_this_task_update_qos
+
+#### Declaration
+
+```c
+FFRT_C_API int ffrt_this_task_update_qos(ffrt_qos_t qos);
+```
+
+#### Parameters
+
+- `qos`: QoS.
+
+#### Return Values
+
+- The value **0** indicates success, and the value **1** indicates failure.
+
+#### Description
+
+Updates the task QoS dynamically during task execution. Note that this API is used in the function closure of a task to update the QoS of the task that is being executed. If this API is invoked, the task is suspended and then resumed.
+
+#### Example
+
+```c
+// Dynamically update the QoS during the execution of a qos_background task.
+ffrt::submit([]() {
+ // ...
+ int ret = ffrt_this_task_update_qos(ffrt_qos_user_initiated);
+ // ...
+}, ffrt::task_attr().qos(ffrt::qos_background));
+```
+
+### ffrt_this_task_get_qos
+
+#### Declaration
+
+```c
+FFRT_C_API ffrt_qos_t ffrt_this_task_get_qos(void);
+```
+
+#### Return Values
+
+- QoS.
+
+#### Description
+
+Obtains the QoS of the task that is being executed.
+
+#### Example
+
+```c
+// Dynamically obtain the QoS during the execution of a task.
+ffrt::submit([]() {
+ // ...
+ // The obtained QoS is ffrt_qos_background.
+ ffrt_qos_t qos = ffrt_this_task_get_qos();
+ // ...
+}, ffrt::task_attr().qos(ffrt::qos_background));
+```
+
+### ffrt_this_task_get_id
+
+#### Declaration
+
+```c
+FFRT_C_API uint64_t ffrt_this_task_get_id(void);
+```
+
+#### Return Values
+
+- Task ID.
+
+#### Description
+
+Obtains the ID of the task that is being executed.
+
+#### Example
+
+```c
+// Dynamically obtain the task ID during task execution.
+ffrt::submit([]() {
+ // ...
+ // Obtain the unique task ID.
+ uint64_t task_id = ffrt_this_task_get_id();
+ // ...
+}, ffrt::task_attr().qos(ffrt::qos_background));
+```
+
+## Task Queue
+
+### ffrt_queue_attr_t
+
+#### Declaration
+
+```c
+typedef struct {
+ uint32_t storage[(ffrt_queue_attr_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)];
+} ffrt_queue_attr_t;
+```
+
+#### Description
+
+Configures queue attributes, such as the QoS, timeout, callback function, and maximum concurrency.
+
+#### Methods
+
+##### ffrt_queue_attr_init
+
+```c
+int ffrt_queue_attr_init(ffrt_queue_attr_t* attr)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+
+Return Values
+
+- The value **0** indicates success while other values indicate failure.
+
+Description
+
+- Initializes a queue attribute object.
+
+##### ffrt_queue_attr_destroy
+
+```c
+void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+
+Description
+
+- Destroys a queue attribute object.
+
+##### ffrt_queue_attr_set_qos
+
+```c
+void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+- `qos`: QoS.
+
+Description
+
+- Sets the queue QoS.
+
+##### ffrt_queue_attr_get_qos
+
+```c
+ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+
+Return Values
+
+- Current QoS.
+
+Description
+
+- Obtains the QoS set in the current attribute.
+
+##### ffrt_queue_attr_set_timeout
+
+```c
+void ffrt_queue_attr_set_timeout(ffrt_queue_attr_t* attr, uint64_t timeout_us)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+- `timeout_us`: timeout (μs).
+
+Description
+
+- Sets the queue timeout (unit: μs).
+
+##### ffrt_queue_attr_get_timeout
+
+```c
+uint64_t ffrt_queue_attr_get_timeout(const ffrt_queue_attr_t* attr)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+
+Return Values
+
+- Current timeout threshold (μs).
+
+Description
+
+- Obtains the timeout set in the current attribute.
+
+##### ffrt_queue_attr_set_callback
+
+```c
+void ffrt_queue_attr_set_callback(ffrt_queue_attr_t* attr, ffrt_function_header_t* f)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+- `f`: pointer to the task executor, which describes how to execute and destroy the CPU task.
+
+Description
+
+- Sets the callback function to be executed after a queue task times out.
+
+##### ffrt_queue_attr_get_callback
+
+```c
+ffrt_function_header_t* ffrt_queue_attr_get_callback(const ffrt_queue_attr_t* attr)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+
+Return Values
+
+- Pointer to the task executor, which describes how to execute and destroy the CPU task.
+
+Description
+
+- Obtains the timeout callback function set in the current attribute.
+
+##### ffrt_queue_attr_set_max_concurrency
+
+```c
+void ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+- `max_concurrency`: maximum concurrency.
+
+Description
+
+- Sets the maximum queue concurrency. (Only concurrent queues are supported.)
+
+##### ffrt_queue_attr_get_max_concurrency
+
+```c
+int ffrt_queue_attr_get_max_concurrency(const ffrt_queue_attr_t* attr)
+```
+
+Parameters
+
+- `attr`: pointer to the queue attribute.
+
+Return Values
+
+- Maximum concurrency.
+
+Description
+
+- Obtains the maximum concurrency set in the current attribute. (Only concurrent queues are supported).
+
+#### Example
+
+```cpp
+#include
+#include "ffrt/queue.h"
+#include "ffrt/cpp/task.h"
+
+int main()
+{
+ ffrt_queue_attr_t queue_attr;
+ // (Mandatory) Initialize the queue attribute.
+ ffrt_queue_attr_init(&queue_attr);
+
+ ffrt_queue_attr_set_qos(&queue_attr, static_cast(ffrt_qos_utility));
+
+ ffrt_queue_attr_set_timeout(&queue_attr, 10000);
+
+ int x = 0;
+ std::function&& basicFunc = [&x]() { x += 1; };
+ ffrt_function_header_t* func = ffrt_queue_attr_get_callback(&queue_attr);
+
+ ffrt_queue_attr_set_callback(&queue_attr, ffrt::create_function_wrapper(basicFunc, ffrt_function_kind_queue));
+ // Destroy the queue attribute. This is mandatory.
+ ffrt_queue_attr_destroy(&queue_attr);
+ return 0;
+}
+```
+
+### ffrt_queue_t
+
+#### Declaration
+
+```c
+typedef void* ffrt_queue_t;
+```
+
+#### Description
+
+Pointer to queues. It provides a series of C APIs for submitting, canceling, and waiting queue tasks and querying the number of queuing tasks.
+
+#### Methods
+
+##### ffrt_queue_create
+
+```c
+ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr)
+```
+
+Parameters
+
+- `type`: queue type, for example, `ffrt_queue_serial` or `ffrt_queue_concurrent`.
+- `name`: queue name.
+- `attr`: pointer to the queue attribute.
+
+Return Values
+
+- `ffrt_queue_t`: If the function is called successfully, a non-null queue handle is returned. Otherwise, a null pointer is returned.
+
+Description
+
+- Creates a queue with a specified type and name.
+
+##### ffrt_queue_destroy
+
+```c
+void ffrt_queue_destroy(ffrt_queue_t queue)
+```
+
+Parameters
+
+- `queue`: queue handle.
+
+Description
+
+- Destroys a queue.
+
+##### ffrt_queue_submit
+
+```c
+void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)
+```
+
+Parameters
+
+- `queue`: queue handle.
+- `f`: pointer to the task executor, which describes how to execute and destroy the CPU task.
+- `attr`: task attribute.
+
+Description
+
+- Submits a task to a queue.
+
+##### ffrt_queue_submit_h
+
+```c
+ffrt_task_handle_t ffrt_queue_submit_h(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr)
+```
+
+Parameters
+
+- `queue`: queue handle.
+- `f`: pointer to the task executor, which describes how to execute and destroy the CPU task.
+- `attr`: task attribute.
+
+Return Values
+
+- `ffrt_task_handle_t`: If the function is called successfully, a non-null task handle is returned. Otherwise, a null pointer is returned.
+
+Description
+
+- Submits a task to a queue and returns a task handle.
+
+##### ffrt_queue_wait
+
+```c
+void ffrt_queue_wait(ffrt_task_handle_t handle)
+```
+
+Parameters
+
+- `ffrt_task_handle_t`: task handle.
+
+Description
+
+- Waits for a queue task to complete.
+
+##### ffrt_queue_cancel
+
+```c
+int ffrt_queue_cancel(ffrt_task_handle_t handle)
+```
+
+Parameters
+
+- `ffrt_task_handle_t`: task handle.
+
+Return Values
+
+- The value **0** indicates success while other values indicate failure.
+
+Description
+
+- Cancels a queue task.
+
+##### ffrt_get_main_queue
+
+```c
+ffrt_queue_t ffrt_get_main_queue();
+```
+
+Return Values
+
+- Main thread queue.
+
+Description
+
+- Obtains the main thread queue for the FFRT thread to communicate with the main thread.
+
+##### ffrt_get_current_queue
+
+```c
+ffrt_queue_t ffrt_get_current_queue();
+```
+
+Return Values
+
+- ArkTS Worker thread queue.
+
+Description
+
+- This API has been deprecated since API version 18. You are not advised to use it.
+- Obtains the ArkTS Worker thread queue for the FFRT thread to communicate with the ArkTS Worker thread.
+
+#### Example
+
+```cpp
+#include "ffrt/queue.h"
+#include "ffrt/cpp/task.h"
+
+int main()
+{
+ ffrt_queue_attr_t queue_attr;
+ // 1. Initialize the queue attribute. This is mandatory.
+ (void)ffrt_queue_attr_init(&queue_attr);
+
+ // 2. Create a serial queue and return queue_handle.
+ ffrt_queue_t queue_handle = ffrt_queue_create(ffrt_queue_serial, "test_queue", &queue_attr);
+
+ int result = 0;
+ std::function&& basicFunc = [&result]() { result += 1; };
+
+ // 3. Submit a serial task.
+ ffrt_queue_submit(queue_handle, ffrt::create_function_wrapper(basicFunc, ffrt_function_kind_queue), nullptr);
+
+ // 4. Submit the serial task and return the task handle.
+ ffrt_task_handle_t t1 = ffrt_queue_submit_h(queue_handle, ffrt::create_function_wrapper(basicFunc, ffrt_function_kind_queue), nullptr);
+ // 5. Wait until the specified task is complete.
+ ffrt_queue_wait(t1);
+
+ ffrt_task_handle_t t2 = ffrt_queue_submit_h(queue_handle, ffrt::create_function_wrapper(basicFunc, ffrt_function_kind_queue), nullptr);
+ // 6. Cancel the task with handle t2.
+ ffrt_queue_cancel(t2);
+
+ // 7. Destroy the handles t1 and t2 submitted to the serial queue task. This is mandatory.
+ ffrt_task_handle_destroy(t1);
+ ffrt_task_handle_destroy(t2);
+ // 8. Destroy the queue attribute. This is mandatory.
+ ffrt_queue_attr_destroy(&queue_attr);
+ // 9. Destroy the queue handle. This is mandatory.
+ ffrt_queue_destroy(queue_handle);
+ return 0;
+}
+```
+
+## Synchronization Primitive
+
+### ffrt_mutexattr_t
+
+#### Declaration
+
+```c
+typedef enum {
+ ffrt_error = -1,
+ ffrt_success = 0,
+ ffrt_error_nomem = ENOMEM,
+ ffrt_error_timedout = ETIMEDOUT,
+ ffrt_error_busy = EBUSY,
+ ffrt_error_inval = EINVAL
+} ffrt_error_t;
+
+typedef enum {
+ ffrt_mutex_normal = 0,
+ ffrt_mutex_recursive = 2,
+ ffrt_mutex_default = ffrt_mutex_normal
+} ffrt_mutex_type;
+
+struct ffrt_mutexattr_t;
+
+int ffrt_mutexattr_init(ffrt_mutexattr_t* attr);
+int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type);
+int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type);
+int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr);
+```
+
+#### Description
+
+- Provides performance implementation similar to pthread mutex.
+
+#### Methods
+
+##### ffrt_mutexattr_init
+
+```c
+FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr);
+```
+
+Parameters
+
+- `attr`: FFRT mutex attribute.
+
+Return Values
+
+- `ffrt_success` is returned if `attr` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Initializes `mutexattr`.
+
+##### ffrt_mutexattr_destroy
+
+```c
+FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr);
+```
+
+Parameters
+
+- `attr`: FFRT mutex attribute.
+
+Return Values
+
+- `ffrt_success` is returned if `attr` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Destroys `mutexattr`.
+
+##### ffrt_mutexattr_settype
+
+```c
+FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type);
+```
+
+Parameters
+
+- `attr`: FFRT mutex attribute.
+- `type`: FFRT mutex type. Currently, only `ffrt_mutex_normal` and `ffrt_mutex_recursive` are supported.
+
+Return Values
+
+- `ffrt_success` is returned if `attr` is not empty and `type` is valid. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Sets the FFRT mutex attribute.
+
+##### ffrt_mutexattr_gettype
+
+```c
+FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type);
+```
+
+Parameters
+
+- `attr`: FFRT mutex attribute.
+- `type`: pointer to the FFRT mutex type.
+
+Return Values
+
+- `ffrt_success` is returned if neither `attr` nor `type` is empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Obtains the FFRT mutex attribute.
+
+#### Example
+
+```c
+ffrt_mutexattr_t attr;
+// Initialize the mutex attribute.
+ffrt_mutexattr_init(&attr);
+// Set a mutex.
+ffrt_mutexattr_settype(&attr, ffrt_mutex_normal);
+// Set a recursive lock.
+ffrt_mutexattr_settype(&attr, ffrt_mutex_recursive);
+// Obtain the mutex type.
+int type = ffrt_mutex_default;
+ffrt_mutexattr_gettype(&attr, &type);
+// Destroy the mutex attribute.
+ffrt_mutexattr_destroy(&attr);
+```
+
+### ffrt_mutex_t
+
+- Implements `pthread_mutex_t`, but does not supports initialization of `PTHREAD_MUTEX_INITIALIZER`.
+
+#### Declaration
+
+```c
+struct ffrt_mutex_t;
+struct ffrt_mutexattr_t;
+
+int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr);
+int ffrt_mutex_lock(ffrt_mutex_t* mutex);
+int ffrt_mutex_unlock(ffrt_mutex_t* mutex);
+int ffrt_mutex_trylock(ffrt_mutex_t* mutex);
+int ffrt_mutex_destroy(ffrt_mutex_t* mutex);
+```
+
+#### Description
+
+- This API can be called inside or outside an FFRT task.
+- The traditional function `pthread_mutex_t` may cause unexpected kernel mode trap when it fails to lock a mutex. **ffrt_mutex_t** solves this problem and therefore provides better performance if used properly.
+- `ffrt_mutexattr_t` in the C API needs to be created and destroyed by calling `ffrt_mutexattr_init` and `ffrt_mutexattr_destroy`. Otherwise, undefined behavior may occur.
+- `ffrt_mutex_t` in the C API needs to be explicitly created and destroyed by calling `ffrt_mutex_init` and `ffrt_mutex_destroy`. Otherwise, undefined behavior may occur.
+- You need to set the `ffrt_mutex_t` object in the C code to null or destroy the object. For the same `ffrt_mutex_t` object, `ffrt_mutex_destroy` can be called only once. Otherwise, undefined behavior may occur.
+- The same `ffrt_mutexattr_t` in the C API can call `ffrt_mutexattr_init` and `ffrt_mutexattr_destroy` only once. Repeated calling may cause undefined behavior.
+- You need to explicitly call `ffrt_mutex_destroy` after `ffrt_mutex_init` and before `ffrt_mutexattr_destroy`.
+- If `ffrt_mutex_t` is accessed after `ffrt_mutex_destroy`, undefined behavior may occur.
+
+#### Methods
+
+##### ffrt_mutex_init
+
+```c
+FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr);
+```
+
+Parameters
+
+- `mutex`: pointer to the operated mutex.
+- `attr`: FFRT mutex attribute. Its valid value can be a null pointer, `ffrt_mutex_normal`, or `ffrt_mutex_recursive`.
+
+Return Values
+
+- `ffrt_success` is returned if `mutex` is not empty and `attr` is within the valid value range. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Initializes the FFRT mutex.
+
+##### ffrt_mutex_destroy
+
+```c
+FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex);
+```
+
+Parameters
+
+- `mutex`: pointer to the operated mutex.
+
+Return Values
+
+- `ffrt_success` is returned if `mutex` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Destroys a specified mutex or recursive lock.
+
+##### ffrt_mutex_lock
+
+```c
+FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex);
+```
+
+Parameters
+
+- `mutex`: pointer to the operated mutex.
+
+Return Values
+
+- `ffrt_success` is returned if `mutex` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Locks a specified mutex or recursive lock. This method blocks the current task until the mutex is successfully obtained.
+
+##### ffrt_mutex_unlock
+
+```c
+FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex);
+```
+
+Parameters
+
+- `mutex`: pointer to the operated mutex.
+
+Return Values
+
+- `ffrt_success` is returned if `mutex` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Unlocks a specified mutex or recursive lock.
+
+##### ffrt_mutex_trylock
+
+```c
+FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex);
+```
+
+Parameters
+
+- `mutex`: pointer to the operated mutex.
+
+Return Values
+
+- **ffrt_error_inval** is returned if `mutex` is empty. `ffrt_success` is returned if `mutex` is not empty and the mutex is successfully held. `ffrt_error_busy` is returned if `mutex` is not empty and the mutex fails to be held.
+
+Description
+
+- Locks a specified mutex or recursive lock.
+
+#### Example
+
+```cpp
+#include "ffrt/mutex.h"
+#include "ffrt/cpp/task.h"
+
+int main()
+{
+ ffrt_mutexattr_t attr;
+ ffrt_mutex_t lock;
+ int sum = 0;
+ int type = ffrt_mutex_default;
+ ffrt_mutexattr_init(&attr);
+ ffrt_mutexattr_settype(&attr, ffrt_mutex_recursive);
+ ffrt_mutexattr_gettype(&attr, &type);
+ ffrt_mutex_init(&lock, &attr);
+ ffrt::submit([&]() {
+ ffrt_mutex_lock(&lock);
+ ffrt_mutex_trylock(&lock);
+ sum++;
+ ffrt_mutex_lock(&lock);
+ ffrt_mutex_trylock(&lock);
+ sum++;
+ ffrt_mutex_unlock(&lock);
+ ffrt_mutex_unlock(&lock);
+ ffrt_mutex_unlock(&lock);
+ ffrt_mutex_unlock(&lock);
+ }, {}, {});
+
+ ffrt::wait();
+
+ ffrt_mutexattr_destroy(&attr);
+ ffrt_mutex_destroy(&lock);
+ return 0;
+}
+```
+
+### ffrt_rwlock_t
+
+- Implements `pthread_rwlock_t`.
+
+#### Declaration
+
+```c
+struct ffrt_rwlock_t;
+struct ffrt_rwlockattr_t;
+
+int ffrt_rwlock_init(ffrt_rwlock_t* rwlock, const ffrt_rwlockattr_t* attr);
+int ffrt_rwlock_wrlock(ffrt_rwlock_t* rwlock);
+int ffrt_rwlock_rdlock(ffrt_rwlock_t* rwlock);
+int ffrt_rwlock_trywrlock(ffrt_rwlock_t* rwlock);
+int ffrt_rwlock_tryrdlock(ffrt_rwlock_t* rwlock);
+int ffrt_rwlock_unlock(ffrt_rwlock_t* rwlock);
+int ffrt_rwlock_destroy(ffrt_rwlock_t* rwlock);
+```
+
+#### Description
+
+- This API can be called inside or outside an FFRT task.
+- This API can avoid the issue that `pthread_rwlock_t` sleeps without releasing threads. The performance is better when the API is properly used.
+- `ffrt_rwlock_t` in the C API needs to be explicitly created and destroyed by calling `ffrt_rwlock_init` and `ffrt_rwlock_destroy`. Otherwise, undefined behavior may occur.
+- When `ffrt_rwlockattr_t` is called, the input parameter of `ffrt_rwlockattr_t` must be a null pointer.
+- You need to set the `ffrt_rwlock_t` object in the C code to null or destroy the object. For the same `ffrt_rwlock_t` object, `ffrt_rwlock_destroy` can be called only once. Otherwise, undefined behavior may occur.
+- If `ffrt_rwlock_t` is accessed after `ffrt_rwlock_destroy` is called, undefined behavior may occur.
+
+#### Methods
+
+##### ffrt_rwlock_init
+
+```c
+FFRT_C_API int ffrt_rwlock_init(ffrt_rwlock_t* rwlock, const ffrt_rwlockattr_t* attr);
+```
+
+Parameters
+
+- `rwlock`: pointer to the operated RW lock.
+- `attr`: pointer to the RW lock attribute.
+
+Return Values
+
+- `ffrt_success` is returned if neither `rwlock` nor `attr` is empty. Otherwise, `ffrt_error_inval` is returned or the current task is blocked.
+
+Description
+
+- Initializes the RW lock.
+
+##### ffrt_rwlock_wrlock
+
+```c
+FFRT_C_API int ffrt_rwlock_wrlock(ffrt_rwlock_t* rwlock);
+```
+
+Parameters
+
+- `rwlock`: pointer to the operated RW lock.
+
+Return Values
+
+- `ffrt_success` is returned if `rwlock` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Adds a write lock to the specified RW lock.
+
+##### ffrt_rwlock_rdlock
+
+```c
+FFRT_C_API int ffrt_rwlock_rdlock(ffrt_rwlock_t* rwlock);
+```
+
+Parameters
+
+- `rwlock`: pointer to the operated RW lock.
+
+Return Values
+
+- `ffrt_success` is returned if `rwlock` is not empty. Otherwise, **ffrt_error_inval** is returned.
+
+Description
+
+- Adds a read lock to the specified RW lock.
+
+##### ffrt_rwlock_trywrlock
+
+```c
+FFRT_C_API int ffrt_rwlock_trywrlock(ffrt_rwlock_t* rwlock);
+```
+
+Parameters
+
+- `rwlock`: pointer to the operated RW lock.
+
+Return Values
+
+- `ffrt_success` is returned if `rwlock` is not empty and no other thread holds the RW lock. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Adds a write lock to the specified RW lock.
+
+##### ffrt_rwlock_tryrdlock
+
+```c
+FFRT_C_API int ffrt_rwlock_tryrdlock(ffrt_rwlock_t* rwlock);
+```
+
+Parameters
+
+- `rwlock`: pointer to the operated RW lock.
+
+Return Values
+
+- `ffrt_success` is returned if `rwlock` is not empty and no other thread holds the write lock. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Adds a read lock to the specified RW lock.
+
+##### ffrt_rwlock_unlock
+
+```c
+FFRT_C_API int ffrt_rwlock_unlock(ffrt_rwlock_t* rwlock);
+```
+
+Parameters
+
+- `rwlock`: pointer to the operated RW lock.
+
+Return Values
+
+- `ffrt_success` is returned if `rwlock` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Unlocks the specified RW lock.
+
+##### ffrt_rwlock_destroy
+
+```c
+FFRT_C_API int ffrt_rwlock_destroy(ffrt_rwlock_t* rwlock);
+```
+
+Parameters
+
+- `rwlock`: pointer to the operated RW lock.
+
+Return Values
+
+- `ffrt_success` is returned if `rwlock` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Destroys a specified RW lock.
+
+#### Example
+
+```cpp
+#include "ffrt/shared_mutex.h"
+#include "ffrt/sleep.h"
+#include "ffrt/cpp/task.h"
+
+int main()
+{
+ ffrt_rwlock_t rwlock;
+ int x = 0;
+ ffrt_rwlock_init(&rwlock, nullptr);
+ ffrt::submit([&]() {
+ ffrt_rwlock_wrlock(&rwlock);
+ ffrt_usleep(10);
+ x++;
+ ffrt_rwlock_unlock(&rwlock);
+ },{},{});
+
+ ffrt::submit([&]() {
+ ffrt_usleep(2);
+ ffrt_rwlock_rdlock(&rwlock);
+ ffrt_rwlock_unlock(&rwlock);
+ },{},{});
+
+ ffrt::submit([&]() {
+ ffrt_usleep(2);
+ if(ffrt_rwlock_trywrlock(&rwlock)){
+ x++;
+ ffrt_rwlock_unlock(&rwlock);
+ }
+ },{},{});
+
+ ffrt::submit([&]() {
+ ffrt_usleep(2);
+ if(ffrt_rwlock_tryrdlock(&rwlock)){
+ ffrt_rwlock_unlock(&rwlock);
+ }
+ },{},{});
+
+ ffrt::wait();
+
+ ffrt_rwlock_destroy(&rwlock);
+ return 0;
+}
+```
+
+### ffrt_cond_t
+
+- Implements the pthread semaphore function, but does not supports initialization of `PTHREAD_COND_INITIALIZER`.
+
+#### Declaration
+
+```c
+typedef enum {
+ ffrt_error = -1,
+ ffrt_success = 0,
+ ffrt_error_nomem = ENOMEM,
+ ffrt_error_timedout = ETIMEDOUT,
+ ffrt_error_busy = EBUSY,
+ ffrt_error_inval = EINVAL
+} ffrt_error_t;
+
+typedef struct {
+ uint32_t storage[(ffrt_cond_storage_size + sizeof(uint32_t) - 1) / sizeof(uint32_t)];
+} ffrt_cond_t;
+
+int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr);
+int ffrt_cond_signal(ffrt_cond_t* cond);
+int ffrt_cond_broadcast(ffrt_cond_t* cond);
+int ffrt_cond_wait(ffrt_cond_t*cond, ffrt_mutex_t* mutex);
+int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point);
+int ffrt_cond_destroy(ffrt_cond_t* cond);
+```
+
+#### Description
+
+- This API can be called inside or outside an FFRT task.
+- The traditional function `pthread_cond_t` may cause unexpected kernel mode trap when the conditions are not met. **ffrt_cond_t** solves this problem and therefore provides better performance if being used properly.
+- Note that `ffrt_cond_t` in the C API needs to be explicitly created and destroyed by calling `ffrt_cond_init` and `ffrt_cond_destroy`. However, in the C++ API, the dependency construction and destruction are automatically completed.
+- You need to set the `ffrt_cond_t` object in the C code to null or destroy the object. For the same `ffrt_cond_t` object, `ffrt_cond_destroy` can be called only once. Otherwise, undefined behavior may occur.
+- If `ffrt_cond_t` is accessed after `ffrt_cond_destroy` is called, undefined behavior may occur.
+
+#### Methods
+
+##### ffrt_cond_init
+
+```c
+FFRT_C_API int ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr);
+```
+
+Parameters
+
+- `cond`: pointer to the target semaphore.
+- `attr`: pointer to the attribute. A null pointer indicates that the default attribute is used.
+
+Return Values
+
+- `ffrt_success` is returned if `cond` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Initializes the FFRT condition variable.
+
+##### ffrt_cond_destroy
+
+```c
+FFRT_C_API int ffrt_cond_destroy(ffrt_cond_t* cond);
+```
+
+Parameters
+
+- `cond`: pointer to the target semaphore.
+
+Return Values
+
+- `ffrt_success` is returned if `cond` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Destroys an FFRT condition variable.
+
+##### ffrt_cond_signal
+
+```c
+FFRT_C_API int ffrt_cond_signal(ffrt_cond_t* cond);
+```
+
+Parameters
+
+- `cond`: pointer to the target semaphore.
+
+Return Values
+
+- `ffrt_success` is returned if `cond` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Unblocks at least one of the threads that are blocked on a condition variable.
+
+##### ffrt_cond_broadcast
+
+```c
+FFRT_C_API int ffrt_cond_broadcast(ffrt_cond_t* cond);
+```
+
+Parameters
+
+- `cond`: pointer to the target semaphore.
+
+Return Values
+
+- `ffrt_success` is returned if `cond` is not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Unblocks all threads currently blocked on a condition variable.
+
+##### ffrt_cond_wait
+
+```c
+FFRT_C_API int ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex);
+```
+
+Parameters
+
+- `cond`: pointer to the target semaphore.
+- `mutex`: pointer to the target mutex.
+
+Return Values
+
+- `ffrt_success` is returned if neither `cond` nor `mutex` is empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Blocks a task on a condition variable. When using this method, a task releases the input mutex and enters the waiting state. The task obtains the mutex again and continues to execute until another task notifies the condition variable.
+- This method is usually used together with `ffrt_mutex_lock` or `ffrt_mutex_trylock` to ensure that the mutex is held before entering the wait state.
+
+##### ffrt_cond_timedwait
+
+```c
+FFRT_C_API int ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point);
+```
+
+Parameters
+
+- `cond`: pointer to the target semaphore.
+- `mutex`: pointer to the target mutex.
+- `time_point`: pointer to the maximum duration during which the thread is blocked.
+
+Return Values
+
+- `ffrt_success` is returned if `cond`, `mutex`, and `time_point` are not empty. Otherwise, `ffrt_error_inval` is returned.
+
+Description
+
+- Blocks a task on a condition variable until the specified timeout is reached.
+- Unlike `ffrt_cond_wait`, the `ffrt_cond_timedwait` method allows a task to wait for a period of time on a condition variable. If no notification is received within the specified period of time, the task is woken up and the function returns.
+
+#### Example
+
+```cpp
+#include
+#include "ffrt/condition_variable.h"
+#include "ffrt/mutex.h"
+#include "ffrt/sleep.h"
+#include "ffrt/cpp/task.h"
+
+struct timespec timeoutms_to_tm(int timeout_ms) {
+ struct timespec ts;
+ clock_gettime(CLOCK_REALTIME, &ts);
+ ts.tv_sec += timeout_ms / 1000;
+ ts.tv_nsec += (timeout_ms % 1000) * 1000000;
+ if (ts.tv_nsec >= 1000000000) {
+ ts.tv_sec += 1;
+ ts.tv_nsec -= 1000000000;
+ }
+ return ts;
+}
+
+int main()
+{
+ int a = 0;
+ ffrt_cond_t cond;
+ ffrt_mutex_t lock_;
+ ffrt_cond_init(&cond, nullptr);
+ ffrt_mutex_init(&lock_, nullptr);
+
+ for (int i = 0; i < 3; i++) {
+ ffrt::submit([&]() {
+ int timeout = 2000;
+ struct timespec tm = timeoutms_to_tm(timeout);
+ ffrt_mutex_lock(&lock_);
+ auto start = std::chrono::high_resolution_clock::now();
+ ffrt_cond_timedwait(&cond, &lock_, &tm);
+ auto end = std::chrono::high_resolution_clock::now();
+ a = 123;
+ ffrt_mutex_unlock(&lock_);
+ std::chrono::duration elapsed = end - start;
+ double t = elapsed.count();
+ std::cout << "ffrt_cond_timedwait " << t << " ms" << std::endl;
+ }, {}, {});
+ }
+
+ ffrt::submit([&]() {
+ ffrt_usleep(1000 * 1000);
+ ffrt_mutex_lock(&lock_);
+ a = 5;
+ ffrt_cond_broadcast(&cond);
+ ffrt_mutex_unlock(&lock_);
+ }, {}, {});
+ ffrt::wait();
+ ffrt_cond_destroy(&cond);
+ ffrt_mutex_destroy(&lock_);
+ return 0;
+}
+```
+
+## Blocking Primitive
+
+### ffrt_usleep
+
+#### Declaration
+
+```c
+FFRT_C_API int ffrt_usleep(uint64_t usec);
+```
+
+#### Parameters
+
+- `usec`: sleep duration, in μs.
+
+#### Description
+
+- Provides performance implementation similar to C11 sleep and Linux usleep.
+- This API can be called only inside an FFRT task. If it is called outside an FFRT task, undefined behavior may occur.
+- The sleep precision of this API is μs.
+- The traditional function `sleep` may cause unexpected kernel mode trap. **ffrt_usleep** solves this problem and therefore provides better performance if used properly.
+
+#### Example
+
+```cpp
+#include "ffrt/sleep.h"
+#include "ffrt/cpp/task.h"
+
+int main()
+{
+ ffrt::submit([=]() { ffrt_usleep(10); }, {}, {});
+ ffrt::wait();
+ return 0;
+}
+```
+
+## Cooperative Primitive
+
+### ffrt_yield
+
+#### Declaration
+
+```c
+FFRT_C_API void ffrt_yield();
+```
+
+#### Description
+
+- Yields CPU execution resources for other executable tasks. If there is no other executable task, `yield` is invalid.
+- This API can be called only inside an FFRT task. If it is called outside an FFRT task, undefined behavior may occur.
+- The exact behavior of this API depends on the implementation, especially the mechanism and system state of the FFRT scheduler in use.
+
+#### Example
+
+```cpp
+#include
+#include "ffrt/sleep.h"
+#include "ffrt/cpp/task.h"
+
+int main()
+{
+ int count = 12;
+ for (int i = 0; i < count; i++) {
+ ffrt::submit([&]() {
+ ffrt_usleep(100);
+ std::cout << "test" << std::endl;
+ ffrt_yield();
+ }, {}, {});
+ }
+ ffrt::wait();
+ return 0;
+}
+```
+
+## Timer
+
+### ffrt_timer_t
+
+#### Declaration
+
+```c
+typedef int ffrt_timer_t;
+typedef void (*ffrt_timer_cb)(void* data);
+```
+
+#### Description
+
+Provides timer-related functions.
+
+#### Methods
+
+##### ffrt_timer_start
+
+Declaration
+
+```c
+FFRT_C_API ffrt_timer_t ffrt_timer_start(ffrt_qos_t qos, uint64_t timeout, void* data, ffrt_timer_cb cb, bool repeat);
+```
+
+Parameters
+
+- `qos`: QoS.
+- `timeout`: timer timeout, in ms.
+- `cb`: callback function after expiration.
+- `data`: input parameter of the callback function.
+- `repeat`: whether the timer is triggered repeatedly.
+
+Return Values
+
+- `ffrt_timer_t`, which indicates the timer handle.
+
+Description
+
+- Starts a timer. If the timer expires and is not stopped, the callback function is executed. If `repeat` is set to `repeat`, the timer is set again after it expires.
+
+##### ffrt_timer_stop
+
+Declaration
+
+```c
+FFRT_C_API int ffrt_timer_stop(ffrt_qos_t qos, ffrt_timer_t handle);
+```
+
+Parameters
+
+- `qos`: QoS.
+- `handle`: timer handle.
+
+Return Values
+
+- The value **0** indicates success, and the value **-1** indicates failure.
+
+Description
+
+- Stops a timer. It is used with `ffrt_timer_start`.
+
+#### Example
+
+- Example 1: Use a one-shot timer.
+
+ ```c
+ #include
+ #include
+ #include "ffrt/timer.h"
+
+ static void test_fun(void *data)
+ {
+ *(int *)data += 1;
+ }
+
+ void (*cb)(void *) = test_fun;
+
+ int main()
+ {
+ static int x = 0;
+ void *data = &x;
+ uint64_t timeout = 200;
+ // Start a timer and execute the callback function after 200 ms.
+ int handle = ffrt_timer_start(ffrt_qos_default, timeout, data, cb, false);
+ usleep(300000);
+ // The timer has been executed and cannot be stopped.
+ ffrt_timer_stop(ffrt_qos_default, handle);
+ printf("data: %d\n", x); // Set the value of x to 1.
+ return 0;
+ }
+ ```
+
+- Example 2: Use a repeating timer.
+
+ ```c
+ #include
+ #include
+ #include "ffrt/timer.h"
+
+ static void test_fun(void *data)
+ {
+ *(int *)data += 1;
+ }
+
+ void (*cb)(void *) = test_fun;
+
+ int main()
+ {
+ static int x = 0;
+ void *data = &x;
+ uint64_t timeout = 200;
+ // Start a repeating timer and execute the callback function every 200 ms.
+ int handle = ffrt_timer_start(ffrt_qos_default, timeout, data, cb, true);
+ usleep(500000);
+ // Stops the repeating timer.
+ ffrt_timer_stop(ffrt_qos_default, handle);
+ printf("data: %d\n", x); // Set the value of x to 2.
+ return 0;
+ }
+ ```
+
+## Loop
+
+### ffrt_loop_t
+
+#### Declaration
+
+```c
+typedef void* ffrt_loop_t;
+```
+
+#### Description
+
+Provides loop-related functions.
+
+#### Methods
+
+##### ffrt_loop_create
+
+Declaration
+
+```c
+FFRT_C_API ffrt_loop_t ffrt_loop_create(ffrt_queue_t queue);
+```
+
+Parameters
+
+- `queue`: a concurrent queue that needs to be bound with a loop.
+
+Return Values
+
+- `ffrt_loop_t` object.
+
+Description
+
+- Creates a loop and bind a concurrent queue for storing tasks. You can submit a task to the queue so that the task can be executed in the loop.
+
+##### ffrt_loop_destroy
+
+Declaration
+
+```c
+FFRT_C_API int ffrt_loop_destroy(ffrt_loop_t loop);
+```
+
+Parameters
+
+- `loop`: loop object.
+
+Return Values
+
+- The value **0** indicates success, and the value **-1** indicates failure.
+
+Description
+
+- Destroys a loop and unbinds it from the queue.
+
+##### ffrt_loop_run
+
+Declaration
+
+```c
+FFRT_C_API int ffrt_loop_run(ffrt_loop_t loop);
+```
+
+Parameters
+
+- `loop`: loop object.
+
+Return Values
+
+- The value **0** indicates success, and the value **-1** indicates failure.
+
+Description
+
+- Runs a loop. The thread that invokes this method executes the loop at the same time, executes queue tasks, and listens for the poller and timer.
+
+##### ffrt_loop_stop
+
+Declaration
+
+```c
+FFRT_C_API void ffrt_loop_stop(ffrt_loop_t loop);
+```
+
+Parameters
+
+- `loop`: loop object.
+
+Description
+
+- Stops a loop. This method is invoked to enable the thread that executes the loop to exit the loop.
+
+##### ffrt_loop_epoll_ctl
+
+Declaration
+
+```c
+int ffrt_loop_epoll_ctl(ffrt_loop_t loop, int op, int fd, uint32_t events, void *data, ffrt_poller_cb cb)
+```
+
+Parameters
+
+- `loop`: loop object.
+- `op`: FD operator. For details, see the operation type of **epoll_ctl**.
+- `fd`: event descriptor.
+- `events`: event. For details, see the event type of **epoll_ctl**.
+- `data`: input parameter of the callback function.
+- `cb`: callback function.
+
+Return Values
+
+- The value **0** indicates success, and the value **-1** indicates failure.
+
+Description
+
+- Manages FD listening on the loop. Event listening and callback are processed on the loop thread.
+
+##### ffrt_loop_timer_start
+
+Declaration
+
+```c
+FFRT_C_API ffrt_timer_t ffrt_loop_timer_start(ffrt_loop_t loop, uint64_t timeout, void* data, ffrt_timer_cb cb, bool repeat);
+```
+
+Parameters
+
+- `loop`: loop object.
+- `timeout`: timer timeout, in ms.
+- `cb`: callback function after expiration.
+- `data`: input parameter of the callback function.
+- `repeat`: whether the timer is triggered repeatedly.
+
+Return Values
+
+- `ffrt_timer_t`, which indicates the timer handle.
+
+Description
+
+- Starts a timer on the loop. The usage is the same as that of `ffrt_timer_start`. The only difference is that the listening and callback execution of the timer are processed on the loop thread.
+
+##### ffrt_loop_timer_stop
+
+Declaration
+
+```c
+FFRT_C_API int ffrt_loop_timer_stop(ffrt_loop_t loop, ffrt_timer_t handle);
+```
+
+Parameters
+
+- `loop`: loop object.
+- `handle`: timer handle.
+
+Return Values
+
+- The value **0** indicates success, and the value **-1** indicates failure.
+
+Description
+
+- Stops a timer. The usage is the same as that of `ffrt_timer_stop`.
+
+#### Example
+
+- Example 1: loop and concurrent queue.
+
+ ```c
+ #include
+ #include
+ #include "ffrt/loop.h"
+
+ void* ThreadFunc(void* p)
+ {
+ int ret = ffrt_loop_run(p);
+ if (ret == 0) {
+ printf("loop normal operation.");
+ }
+ return NULL;
+ }
+
+ int main()
+ {
+ // Create a concurrent queue.
+ ffrt_queue_attr_t queue_attr;
+ (void)ffrt_queue_attr_init(&queue_attr);
+ ffrt_queue_t queue_handle = ffrt_queue_create(ffrt_queue_concurrent, "test_queue", &queue_attr);
+
+ // Create a loop.
+ ffrt_loop_t loop = ffrt_loop_create(queue_handle);
+
+ // Create a separate thread to perform the loop.
+ pthread_t thread;
+ pthread_create(&thread, 0, ThreadFunc, loop);
+
+ // Stop and destroy the loop.
+ ffrt_loop_stop(loop);
+ ffrt_loop_destroy(loop);
+
+ // Destroy the concurrent queue.
+ ffrt_queue_attr_destroy(&queue_attr);
+ ffrt_queue_destroy(queue_handle);
+ return 0;
+ }
+ ```
+
+- Example 2: loop, concurrent queue, and timer.
+
+ ```cpp
+ #include
+ #include
+ #include
+ #include
+ #include
+ #include
+ #include "ffrt/loop.h"
+ #include "ffrt/cpp/task.h"
+
+ void* ThreadFunc(void* p)
+ {
+ ffrt_loop_run(p);
+ return nullptr;
+ }
+
+ static void test_fun(void* data)
+ {
+ *(int*)data += 1;
+ }
+
+ static void (*cb)(void*) = test_fun;
+
+ void testCallBack(void *data, unsigned int events) {}
+
+ struct TestData {
+ int fd;
+ uint64_t expected;
+ };
+
+ int main()
+ {
+ // Create a concurrent queue.
+ ffrt_queue_attr_t queue_attr;
+ (void)ffrt_queue_attr_init(&queue_attr);
+ ffrt_queue_t queue_handle = ffrt_queue_create(ffrt_queue_concurrent, "test_queue", &queue_attr);
+
+ // Create a loop.
+ auto loop = ffrt_loop_create(queue_handle);
+ int result1 = 0;
+
+ // Submit a task to the loop queue.
+ std::function &&basicFunc1 = [&result1]() { result1 += 10; };
+ ffrt_task_handle_t task = ffrt_queue_submit_h(queue_handle, ffrt::create_function_wrapper(basicFunc1, ffrt_function_kind_queue), nullptr);
+
+ // Create a separate thread to perform the loop.
+ pthread_t thread;
+ pthread_create(&thread, 0, ThreadFunc, loop);
+
+ static int x = 0;
+ int* xf = &x;
+ void* data = xf;
+ uint64_t timeout1 = 20;
+ uint64_t timeout2 = 10;
+ uint64_t expected = 0xabacadae;
+
+ int testFd = eventfd(0, EFD_NONBLOCK | EFD_CLOEXEC);
+ struct TestData testData {.fd = testFd, .expected = expected};
+
+ // Register a timer with the loop.
+ ffrt_timer_t timeHandle = ffrt_loop_timer_start(loop, timeout1, data, cb, false);
+
+ // Register an FD listener with the loop.
+ int ret = ffrt_loop_epoll_ctl(loop, EPOLL_CTL_ADD, testFd, EPOLLIN, (void*)(&testData), testCallBack);
+ if (ret == 0) {
+ printf("ffrt_loop_epoll_ctl executed successfully.\n");
+ }
+ ssize_t n = write(testFd, &expected, sizeof(uint64_t));
+ usleep(25000);
+ // Delete the FD listener.
+ ffrt_loop_epoll_ctl(loop, EPOLL_CTL_DEL, testFd, 0, nullptr, nullptr);
+
+ // Stop the loop.
+ ffrt_loop_stop(loop);
+ pthread_join(thread, nullptr);
+
+ // Delete the timer.
+ ffrt_loop_timer_stop(loop, timeHandle);
+
+ // Destroy the loop.
+ ret = ffrt_loop_destroy(loop);
+
+ // Destroy the concurrent queue.
+ ffrt_queue_attr_destroy(&queue_attr);
+ ffrt_queue_destroy(queue_handle);
+ return 0;
+ }
+ ```
diff --git a/en/application-dev/ffrt/ffrt-concurrency-concurrent-queue-c.md b/en/application-dev/ffrt/ffrt-concurrency-concurrent-queue-c.md
new file mode 100644
index 0000000000000000000000000000000000000000..ef5f387bffe42b77012c58804476746964a1d7fe
--- /dev/null
+++ b/en/application-dev/ffrt/ffrt-concurrency-concurrent-queue-c.md
@@ -0,0 +1,172 @@
+# Function Flow Runtime Concurrent Queue (C)
+
+## Overview
+
+The FFRT concurrent queue provides the capability of setting the priority and queue concurrency. Tasks in the queue can be executed on multiple threads at the same time, achieving better effect.
+
+- **Queue concurrency**: You can set the maximum concurrency of a queue to control the number of tasks that can be executed at the same time. This avoids system resource impact caused by excessive concurrent tasks, ensuring system stability and performance.
+- **Task priority**: You can set a priority for each task. Different tasks are scheduled and executed strictly based on the priority. Tasks with the same priority are executed in sequence. Tasks with higher priorities are executed prior to those with lower priorities to ensure that key tasks can be processed in a timely manner.
+
+## Example: Bank Service System
+
+For example, each customer (common customer or VIP customer) submits a service request to the bank service system. The service request of the VIP customer can be processed first.
+The bank system has two windows for handling service requests submitted by customers. You can use the FFRT paradigm to perform the following modeling:
+
+- **Queuing logic**: concurrent queue.
+- **Service window**: concurrency of the concurrent queue, which also equals the number of FFRT Worker threads.
+- **Customer level**: priority of concurrent queue tasks.
+
+The implementation code is as follows:
+
+```c
+#include
+#include
+#include "ffrt/queue.h"
+#include "ffrt/task.h"
+
+ffrt_queue_t create_bank_system(const char *name, int concurrency)
+{
+ ffrt_queue_attr_t queue_attr;
+ (void)ffrt_queue_attr_init(&queue_attr);
+ ffrt_queue_attr_set_max_concurrency(&queue_attr, concurrency);
+
+ // Create a concurrent queue.
+ ffrt_queue_t queue = ffrt_queue_create(ffrt_queue_concurrent, name, &queue_attr);
+
+ // Destroy the queue attributes after the queue is created.
+ ffrt_queue_attr_destroy(&queue_attr);
+ if (!queue) {
+ printf("create queue failed\n");
+ return NULL;
+ }
+
+ printf("create bank system successfully\n");
+ return queue;
+}
+
+void destroy_bank_system(ffrt_queue_t queue_handle)
+{
+ ffrt_queue_destroy(queue_handle);
+ printf("destroy bank system successfully\n");
+}
+
+void bank_business(void *arg)
+{
+ usleep(100 * 1000);
+ const char *data = (const char *)arg;
+ printf("saving or withdraw for %s\n", data);
+}
+
+// Encapsulate the operation of submitting a task to a queue into a function.
+ffrt_task_handle_t commit_request(ffrt_queue_t bank, void (*func)(void *), const char *name,
+ ffrt_queue_priority_t level, int delay)
+{
+ ffrt_task_attr_t task_attr;
+ (void)ffrt_task_attr_init(&task_attr);
+ ffrt_task_attr_set_name(&task_attr, name);
+ ffrt_task_attr_set_queue_priority(&task_attr, level);
+ ffrt_task_attr_set_delay(&task_attr, delay);
+
+ return ffrt_queue_submit_h(bank, ffrt_create_function_wrapper(func, NULL, name), &task_attr);
+}
+
+// Encapsulate the operation of canceling a task in a queue into a function.
+int cancel_request(ffrt_task_handle_t request)
+{
+ return ffrt_queue_cancel(request);
+}
+
+// Encapsulate the operation of waiting for a task in a queue into a function.
+void wait_for_request(ffrt_task_handle_t task)
+{
+ ffrt_queue_wait(task);
+}
+
+int main()
+{
+ ffrt_queue_t bank = create_bank_system("Bank", 2);
+ if (!bank) {
+ printf("create bank system failed\n");
+ return -1;
+ }
+ commit_request(bank, bank_business, "customer1", ffrt_queue_priority_low, 0);
+ commit_request(bank, bank_business, "customer2", ffrt_queue_priority_low, 0);
+ commit_request(bank, bank_business, "customer3", ffrt_queue_priority_low, 0);
+ commit_request(bank, bank_business, "customer4", ffrt_queue_priority_low, 0);
+
+ // VIP customers have the priority to enjoy services.
+ commit_request(bank, bank_business, "VIP", ffrt_queue_priority_high, 0);
+
+ ffrt_task_handle_t task = commit_request(bank, bank_business, "customer5", ffrt_queue_priority_low, 0);
+ ffrt_task_handle_t task_last = commit_request(bank, bank_business, "customer6", ffrt_queue_priority_low, 0);
+
+ // Cancel the service for customer 5.
+ cancel_request(task);
+
+ // Wait until all customer services are complete.
+ wait_for_request(task_last);
+ destroy_bank_system(bank);
+
+ return 0;
+}
+```
+
+C-style FFRT construction requires additional encapsulation using common code and is irrelevant to specific service scenarios.
+
+```c
+typedef struct {
+ ffrt_function_header_t header;
+ ffrt_function_t func;
+ ffrt_function_t after_func;
+ void* arg;
+} c_function_t;
+
+static inline void ffrt_exec_function_wrapper(void* t)
+{
+ c_function_t* f = (c_function_t *)t;
+ if (f->func) {
+ f->func(f->arg);
+ }
+}
+
+static inline void ffrt_destroy_function_wrapper(void* t)
+{
+ c_function_t* f = (c_function_t *)t;
+ if (f->after_func) {
+ f->after_func(f->arg);
+ }
+}
+
+#define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
+static inline ffrt_function_header_t *ffrt_create_function_wrapper(const ffrt_function_t func,
+ const ffrt_function_t after_func, void *arg)
+{
+ FFRT_STATIC_ASSERT(sizeof(c_function_t) <= ffrt_auto_managed_function_storage_size,
+ size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
+
+ c_function_t* f = (c_function_t *)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_queue);
+ f->header.exec = ffrt_exec_function_wrapper;
+ f->header.destroy = ffrt_destroy_function_wrapper;
+ f->func = func;
+ f->after_func = after_func;
+ f->arg = arg;
+ return (ffrt_function_header_t *)f;
+}
+```
+
+## Available APIs
+
+The main FFRT APIs involved in the preceding example are as follows:
+
+| Name | Description |
+| -------------------------------------------------------------------------------------------------- | ---------------------- |
+| [ffrt_queue_create](ffrt-api-guideline-c.md#ffrt_queue_create) | Creates a queue. |
+| [ffrt_queue_destroy](ffrt-api-guideline-c.md#ffrt_queue_destroy) | Destroys a queue. |
+| [ffrt_task_attr_set_queue_priority](ffrt-api-guideline-c.md#ffrt_task_attr_set_queue_priority) | Sets the priority of a task in a queue. |
+| [ffrt_queue_attr_set_max_concurrency](ffrt-api-guideline-c.md#ffrt_queue_attr_set_max_concurrency) | Sets the concurrency of the concurrent queue.|
+
+## Constraints
+
+1. `ffrt_queue_attr_t` must be initialized by calling `ffrt_queue_attr_init` before the attribute is set or obtained. If `ffrt_queue_attr_t` is no longer used, `ffrt_queue_attr_destroy` needs to be explicitly called to release resources.
+2. `ffrt_queue_t` must explicitly call `ffrt_queue_destroy` to release resources before the process exits.
+3. It is recommended that the maximum concurrency of a concurrent queue be within a proper range. If the value is too large, it is meaningless to exceed the number of Worker threads. If the value is too small, the system resource utilization may be low.
diff --git a/en/application-dev/ffrt/ffrt-concurrency-concurrent-queue-cpp.md b/en/application-dev/ffrt/ffrt-concurrency-concurrent-queue-cpp.md
new file mode 100644
index 0000000000000000000000000000000000000000..e29af56f5e573a0d77fff41d08bcf98e14f2495f
--- /dev/null
+++ b/en/application-dev/ffrt/ffrt-concurrency-concurrent-queue-cpp.md
@@ -0,0 +1,116 @@
+# Function Flow Runtime Concurrent Queue (C++)
+
+## Overview
+
+The FFRT concurrent queue provides the capability of setting the priority and queue concurrency. Tasks in the queue can be executed on multiple threads at the same time, achieving better effect.
+
+- **Queue concurrency**: You can set the maximum concurrency of a queue to control the number of tasks that can be executed at the same time. This avoids system resource impact caused by excessive concurrent tasks, ensuring system stability and performance.
+- **Task priority**: You can set a priority for each task. Different tasks are scheduled and executed strictly based on the priority. Tasks with the same priority are executed in sequence. Tasks with higher priorities are executed prior to those with lower priorities to ensure that key tasks can be processed in a timely manner.
+
+## Example: Bank Service System
+
+For example, each customer (common customer or VIP customer) submits a service request to the bank service system. The service request of the VIP customer can be processed first.
+The bank system has two windows for handling service requests submitted by customers. You can use the FFRT paradigm to perform the following modeling:
+
+- **Queuing logic**: concurrent queue.
+- **Service window**: concurrency of the concurrent queue, which also equals the number of FFRT Worker threads.
+- **Customer level**: priority of concurrent queue tasks.
+
+The implementation code is as follows:
+
+```cpp
+#include
+#include
+#include "ffrt/cpp/queue.h"
+#include "ffrt/cpp/task.h"
+
+class BankQueueSystem {
+private:
+ std::unique_ptr queue_;
+
+public:
+ BankQueueSystem(const char *name, int concurrency)
+ {
+ queue_ = std::make_unique(
+ ffrt::queue_concurrent, name, ffrt::queue_attr().max_concurrency(concurrency));
+ std::cout << "bank system has been initialized" << std::endl;
+ }
+
+ ~BankQueueSystem()
+ {
+ queue_ = nullptr;
+ std::cout << "bank system has been destroyed" << std::endl;
+ }
+
+ // Start to queue, that is, submit queue tasks.
+ ffrt::task_handle Enter(const std::function& func, const char *name, ffrt_queue_priority_t level, int delay)
+ {
+ return queue_->submit_h(func, ffrt::task_attr().name(name).priority(level).delay(delay));
+ }
+
+ // Exit the queue, that is, cancel queue tasks.
+ int Exit(const ffrt::task_handle &t)
+ {
+ return queue_->cancel(t);
+ }
+
+ // Wait for tasks in the queue.
+ void Wait(const ffrt::task_handle& handle)
+ {
+ queue_->wait(handle);
+ }
+};
+
+void BankBusiness()
+{
+ usleep(100 * 1000);
+ std::cout << "saving or withdraw ordinary customer" << std::endl;
+}
+
+void BankBusinessVIP()
+{
+ usleep(100 * 1000);
+ std::cout << "saving or withdraw VIP" << std::endl;
+}
+
+int main()
+{
+ BankQueueSystem bankQueue("Bank", 2);
+
+ bankQueue.Enter(BankBusiness, "customer1", ffrt_queue_priority_low, 0);
+ bankQueue.Enter(BankBusiness, "customer2", ffrt_queue_priority_low, 0);
+ bankQueue.Enter(BankBusiness, "customer3", ffrt_queue_priority_low, 0);
+ bankQueue.Enter(BankBusiness, "customer4", ffrt_queue_priority_low, 0);
+
+ // VIP customers have the priority to enjoy services.
+ bankQueue.Enter(BankBusinessVIP, "vip", ffrt_queue_priority_high, 0);
+
+ ffrt::task_handle handle = bankQueue.Enter(BankBusiness, "customer5", ffrt_queue_priority_low, 0);
+ ffrt::task_handle handleLast = bankQueue.Enter(BankBusiness, "customer6", ffrt_queue_priority_low, 0);
+
+ // Cancel the service for customer 5.
+ bankQueue.Exit(handle);
+
+ // Wait until all customer services are complete.
+ bankQueue.Wait(handleLast);
+ return 0;
+}
+```
+
+## Available APIs
+
+The main FFRT APIs involved in the preceding example are as follows:
+
+| Name | Description |
+| ----------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| class [task_attr](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#task_attr) | Task attribute class.|
+| class [queue_attr](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#queue_attr) | Queue attribute class.|
+| class [queue](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#queue) | Queue class. |
+
+> **NOTE**
+>
+> For details about how to use FFRT C++ APIs, see [Using FFRT C++ APIs](ffrt-development-guideline.md#using-ffrt-c-api-1).
+
+## Constraints
+
+1. It is recommended that the maximum concurrency of a concurrent queue be within a proper range. If the value is too large, it is meaningless to exceed the number of Worker threads. If the value is too small, the system resource utilization may be low.
diff --git a/en/application-dev/ffrt/ffrt-concurrency-graph-c.md b/en/application-dev/ffrt/ffrt-concurrency-graph-c.md
new file mode 100644
index 0000000000000000000000000000000000000000..8a15d88ac56eaecbbd83c611539d75de9aa1b552
--- /dev/null
+++ b/en/application-dev/ffrt/ffrt-concurrency-graph-c.md
@@ -0,0 +1,293 @@
+# Function Flow Runtime Task Graph (C)
+
+## Overview
+
+The FFRT task graph supports task dependency and data dependency. Each node in the task graph indicates a task, and each edge indicates the dependency between tasks. Task dependency is classified into input dependency (`in_deps`) and output dependency (`out_deps`).
+
+You can use either of the following ways to build a task graph:
+
+- Use the task dependency to build a task graph. The task `handle` is used to indicate a task object.
+- Use the data dependency to build a task graph. The data object is abstracted as a data signature, and each data signature uniquely indicates a data object.
+
+### Task dependency
+
+> **NOTE**
+>
+> When a task handle appears in `in_deps`, the corresponding task is the previous task. When a task handle appears in `out_deps`, the corresponding task is the subsequent task.
+
+Task dependency applies to scenarios where tasks have specific sequence or logical process requirements. For example:
+
+- Tasks with sequence. For example, a data preprocessing task is executed before a model training task.
+- Logic process control. For example, in a typical commodity transaction process, orders are placed, followed by production and then logistics transportation.
+- Multi-level chain: For example, during video processing, you can perform tasks such as transcoding, generating thumbnails, adding watermarks, and releasing the final video.
+
+### Data Dependency
+
+> **NOTE**
+>
+> When the signature of a data object appears in `in_deps` of a task, the task is referred to as a consumer task that executes without modifying the original input data object.
+> When the signature of a data object appears in `out_deps` of a task, the task is referred to as a producer task that updates the output data object's content to create a new version.
+
+Data dependency applies to scenarios where tasks are triggered by data production and consumption relationships.
+
+A data object may have multiple versions. Each version corresponds to one producer task and zero, one, or more consumer tasks. A sequence of the data object versions and the version-specific producer task and consumer tasks are defined according to the delivery sequence of the producer task and consumer tasks.
+
+When all producer tasks and consumer tasks of the data object of all the available versions are executed, the data dependency is removed. In this case, the task enters the ready state and can be scheduled for execution.
+
+FFRT can dynamically build producer/consumer-based data dependencies between tasks at runtime and perform scheduling based on the task data dependency status, including:
+
+- Producer-Consumer dependency
+
+ A dependency formed between the producer task of a data object of a specific version and a consumer task of the data object of the same version. It is also referred to as a read-after-write dependency.
+
+- Consumer-Producer dependency
+
+ A dependency formed between a consumer task of a data object of a specific version and the producer task of the data object of the next version. It is also referred to as a write-after-read dependency.
+
+- Producer-Producer dependency
+
+ A dependency formed between the producer task of a data object of a specific version and a producer task of the data object of the next version. It is also referred to as a write-after-write dependency.
+
+For example, the relationship between a group of tasks and data A is expressed as follows:
+
+```cpp
+task1(OUT A);
+task2(IN A);
+task3(IN A);
+task4(OUT A);
+task5(OUT A);
+```
+
+
+
+For ease of description, circles are used to represent tasks and squares are used to represent data.
+
+The following conclusions can be drawn:
+
+- task1 and task2/task3 form a producer-consumer dependency. This means that task2/task3 can read data A only after task1 writes data A.
+- task2/task3 and task4 form a consumer-producer dependency. This means that task4 can write data A only after task2/task3 reads data A.
+- task 4 and task 5 form a producer-producer dependency. This means that task 5 can write data A only after task 4 writes data A.
+
+## Example: Streaming Video Processing
+
+A user uploads a video to the platform. The processing steps include: parsing, transcoding, generating a thumbnail, adding a watermark, and releasing the video. Transcoding and thumbnail generation can occur simultaneously. The following figure shows the task process.
+
+
+
+The FFRT provides task graph that can describe the task dependency and parallelize the preceding video processing process. The code is as follows:
+
+```c
+#include
+#include "ffrt/task.h"
+
+static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
+ void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
+{
+ ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
+}
+
+static inline ffrt_task_handle_t ffrt_submit_h_c(ffrt_function_t func, const ffrt_function_t after_func,
+ void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
+{
+ return ffrt_submit_h_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
+}
+
+void func_TaskA(void* arg)
+{
+ printf("Parse\n");
+}
+
+void func_TaskB(void* arg)
+{
+ printf("Transcode\n");
+}
+
+void func_TaskC(void* arg)
+{
+ printf("Generate a thumbnail\n");
+}
+
+void func_TaskD(void* arg)
+{
+ printf("Add watermark\n");
+}
+
+void func_TaskE(void* arg)
+{
+ printf("Release\n");
+}
+
+int main()
+{
+ // Submit task A.
+ ffrt_task_handle_t hTaskA = ffrt_submit_h_c(func_TaskA, NULL, NULL, NULL, NULL, NULL);
+
+ // Submit tasks B and C.
+ ffrt_dependence_t taskA_deps[] = {{ffrt_dependence_task, hTaskA}};
+ ffrt_deps_t dTaskA = {1, taskA_deps};
+ ffrt_task_handle_t hTaskB = ffrt_submit_h_c(func_TaskB, NULL, NULL, &dTaskA, NULL, NULL);
+ ffrt_task_handle_t hTaskC = ffrt_submit_h_c(func_TaskC, NULL, NULL, &dTaskA, NULL, NULL);
+
+ // Submit task D.
+ ffrt_dependence_t taskBC_deps[] = {{ffrt_dependence_task, hTaskB}, {ffrt_dependence_task, hTaskC}};
+ ffrt_deps_t dTaskBC = {2, taskBC_deps};
+ ffrt_task_handle_t hTaskD = ffrt_submit_h_c(func_TaskD, NULL, NULL, &dTaskBC, NULL, NULL);
+
+ // Submit task E.
+ ffrt_dependence_t taskD_deps[] = {{ffrt_dependence_task, hTaskD}};
+ ffrt_deps_t dTaskD = {1, taskD_deps};
+ ffrt_submit_c(func_TaskE, NULL, NULL, &dTaskD, NULL, NULL);
+
+ // Wait until all tasks are complete.
+ ffrt_wait();
+ return 0;
+}
+```
+
+C-style FFRT construction requires additional encapsulation using common code and is irrelevant to specific service scenarios.
+
+```c
+typedef struct {
+ ffrt_function_header_t header;
+ ffrt_function_t func;
+ ffrt_function_t after_func;
+ void* arg;
+} c_function_t;
+
+static inline void ffrt_exec_function_wrapper(void* t)
+{
+ c_function_t* f = (c_function_t *)t;
+ if (f->func) {
+ f->func(f->arg);
+ }
+}
+
+static inline void ffrt_destroy_function_wrapper(void* t)
+{
+ c_function_t* f = (c_function_t *)t;
+ if (f->after_func) {
+ f->after_func(f->arg);
+ }
+}
+
+#define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
+static inline ffrt_function_header_t *ffrt_create_function_wrapper(const ffrt_function_t func,
+ const ffrt_function_t after_func, void *arg)
+{
+ FFRT_STATIC_ASSERT(sizeof(c_function_t) <= ffrt_auto_managed_function_storage_size,
+ size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
+
+ c_function_t* f = (c_function_t *)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
+ f->header.exec = ffrt_exec_function_wrapper;
+ f->header.destroy = ffrt_destroy_function_wrapper;
+ f->func = func;
+ f->after_func = after_func;
+ f->arg = arg;
+ return (ffrt_function_header_t *)f;
+}
+```
+
+The expected output may be as follows:
+
+```plain
+Video parsing
+Video transcoding
+Thumbnails generation
+Watermark adding
+Video release
+```
+
+## Example: Fibonacci Sequence
+
+Each number in the Fibonacci sequence is the sum of the first two numbers. The process of calculating the Fibonacci number can well express the task dependency through the data object. The code for calculating the Fibonacci number using the FFRT framework is as follows:
+
+```c
+#include
+#include "ffrt/task.h"
+
+typedef struct {
+ int x;
+ int* y;
+} fib_ffrt_s;
+
+static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
+ void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
+{
+ ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
+}
+
+void fib_ffrt(void* arg)
+{
+ fib_ffrt_s* p = (fib_ffrt_s*)arg;
+ int x = p->x;
+ int* y = p->y;
+
+ if (x <= 1) {
+ *y = x;
+ } else {
+ int y1, y2;
+ fib_ffrt_s s1 = {x - 1, &y1};
+ fib_ffrt_s s2 = {x - 2, &y2};
+
+ // Build data dependencies.
+ ffrt_dependence_t dx_deps[] = {{ffrt_dependence_data, &x}};
+ ffrt_deps_t dx = {1, dx_deps};
+ ffrt_dependence_t dy1_deps[] = {{ffrt_dependence_data, &y1}};
+ ffrt_deps_t dy1 = {1, dy1_deps};
+ ffrt_dependence_t dy2_deps[] = {{ffrt_dependence_data, &y2}};
+ ffrt_deps_t dy2 = {1, dy2_deps};
+ ffrt_dependence_t dy12_deps[] = {{ffrt_dependence_data, &y1}, {ffrt_dependence_data, &y2}};
+ ffrt_deps_t dy12 = {2, dy12_deps};
+
+ // Submit tasks separately.
+ ffrt_submit_c(fib_ffrt, NULL, &s1, &dx, &dy1, NULL);
+ ffrt_submit_c(fib_ffrt, NULL, &s2, &dx, &dy2, NULL);
+
+ // Wait until the task is complete.
+ ffrt_wait_deps(&dy12);
+ *y = y1 + y2;
+ }
+}
+
+int main()
+{
+ int r;
+ fib_ffrt_s s = {5, &r};
+ ffrt_dependence_t dr_deps[] = {{ffrt_dependence_data, &r}};
+ ffrt_deps_t dr = {1, dr_deps};
+ ffrt_submit_c(fib_ffrt, NULL, &s, NULL, &dr, NULL);
+
+ // Wait until the task is complete.
+ ffrt_wait_deps(&dr);
+ printf("Fibonacci(5) is %d\n", r);
+ return 0;
+}
+```
+
+Expected output:
+
+```plain
+Fibonacci(5) is 5
+```
+
+In the example, `fibonacci(x-1)` and `fibonacci(x-2)` are submitted to FFRT as two tasks. After the two tasks are complete, the results are accumulated. Although a single task is split into two subtasks, the subtasks can be further split. Therefore, the concurrency of the entire computational graph is very high.
+
+Each task forms a call tree in the FFRT.
+
+
+
+## Available APIs
+
+The main FFRT APIs involved in the preceding example are as follows:
+
+| Name | Description |
+| ---------------------------------------------------------------- | -------------------------------------- |
+| [ffrt_submit_base](ffrt-api-guideline-c.md#ffrt_submit_base) | Submits a task. |
+| [ffrt_submit_h_base](ffrt-api-guideline-c.md#ffrt_submit_h_base) | Submits a task, and obtains the task handle. |
+| [ffrt_wait_deps](ffrt-api-guideline-c.md#ffrt_wait_deps) | Waits until the dependent tasks are complete.|
+
+## Constraints
+
+- For `ffrt_submit_base`, the total number of input dependencies and output dependencies of each task cannot exceed 8.
+- For `ffrt_submit_h_base`, the total number of input dependencies and output dependencies of each task cannot exceed 7.
+- When a parameter is used as both an input dependency and an output dependency, it is counted as one dependency. For example, if the input dependency is `{&x}` and the output dependency is also `{&x}`, then the number of dependencies is 1.
diff --git a/en/application-dev/ffrt/ffrt-concurrency-graph-cpp.md b/en/application-dev/ffrt/ffrt-concurrency-graph-cpp.md
new file mode 100644
index 0000000000000000000000000000000000000000..cf316c5949fe22355bb6541e83552a3637ca4586
--- /dev/null
+++ b/en/application-dev/ffrt/ffrt-concurrency-graph-cpp.md
@@ -0,0 +1,171 @@
+# Function Flow Runtime Task Graph (C++)
+
+## Overview
+
+The FFRT task graph supports task dependency and data dependency. Each node in the task graph indicates a task, and each edge indicates the dependency between tasks. Task dependency is classified into input dependency (`in_deps`) and output dependency (`out_deps`).
+
+You can use either of the following ways to build a task graph:
+
+- Use the task dependency to build a task graph. The task `handle` is used to indicate a task object.
+- Use the data dependency to build a task graph. The data object is abstracted as a data signature, and each data signature uniquely indicates a data object.
+
+### Task dependency
+
+> **NOTE**
+>
+> When a task handle appears in `in_deps`, the corresponding task is the previous task. When a task handle appears in `out_deps`, the corresponding task is the subsequent task.
+
+Task dependency applies to scenarios where tasks have specific sequence or logical process requirements. For example:
+
+- Tasks with sequence. For example, a data preprocessing task is executed before a model training task.
+- Logic process control. For example, in a typical commodity transaction process, orders are placed, followed by production and then logistics transportation.
+- Multi-level chain: For example, during video processing, you can perform tasks such as transcoding, generating thumbnails, adding watermarks, and releasing the final video.
+
+### Data Dependency
+
+> **NOTE**
+>
+> When the signature of a data object appears in `in_deps` of a task, the task is referred to as a consumer task that executes without modifying the original input data object.
+> When the signature of a data object appears in `out_deps` of a task, the task is referred to as a producer task that updates the output data object's content to create a new version.
+
+Data dependency applies to scenarios where tasks are triggered by data production and consumption relationships.
+
+A data object may have multiple versions. Each version corresponds to one producer task and zero, one, or more consumer tasks. A sequence of the data object versions and the version-specific producer task and consumer tasks are defined according to the delivery sequence of the producer task and consumer tasks.
+
+When all producer tasks and consumer tasks of the data object of all the available versions are executed, the data dependency is removed. In this case, the task enters the ready state and can be scheduled for execution.
+
+FFRT can dynamically build producer/consumer-based data dependencies between tasks at runtime and perform scheduling based on the task data dependency status, including:
+
+- Producer-Consumer dependency
+
+ A dependency formed between the producer task of a data object of a specific version and a consumer task of the data object of the same version. It is also referred to as a read-after-write dependency.
+
+- Consumer-Producer dependency
+
+ A dependency formed between a consumer task of a data object of a specific version and the producer task of the data object of the next version. It is also referred to as a write-after-read dependency.
+
+- Producer-Producer dependency
+
+ A dependency formed between the producer task of a data object of a specific version and a producer task of the data object of the next version. It is also referred to as a write-after-write dependency.
+
+For example, the relationship between a group of tasks and data A is expressed as follows:
+
+```cpp
+task1(OUT A);
+task2(IN A);
+task3(IN A);
+task4(OUT A);
+task5(OUT A);
+```
+
+
+
+For ease of description, circles are used to represent tasks and squares are used to represent data.
+
+The following conclusions can be drawn:
+
+- task1 and task2/task3 form a producer-consumer dependency. This means that task2/task3 can read data A only after task1 writes data A.
+- task2/task3 and task4 form a consumer-producer dependency. This means that task4 can write data A only after task2/task3 reads data A.
+- task 4 and task 5 form a producer-producer dependency. This means that task 5 can write data A only after task 4 writes data A.
+
+## Example: Streaming Video Processing
+
+A user uploads a video to the platform. The processing steps include: parsing, transcoding, generating a thumbnail, adding watermark, and releasing the video. Transcoding and thumbnail generation can occur simultaneously. The following figure shows the task process.
+
+
+
+The FFRT provides task graph that can describe the task dependency and parallelize the preceding video processing process. The code is as follows:
+
+```cpp
+#include
+#include "ffrt/cpp/task.h"
+
+int main()
+{
+ // Submit a task.
+ auto handle_A = ffrt::submit_h([] () { std::cout << "Parse" << std::endl; });
+ auto handle_B = ffrt::submit_h([] () { std::cout << "Transcode" << std::endl; }, {handle_A});
+ auto handle_C = ffrt::submit_h([] () { std::cout << "Generate a thumbnail" << std::endl; }, {handle_A});
+ auto handle_D = ffrt::submit_h([] () { std::cout << "Add watermark" << std::endl; }, {handle_B, handle_C});
+ ffrt::submit([] () { std::cout << "Release" << std::endl; }, {handle_D});
+
+ // Wait until all tasks are complete.
+ ffrt::wait();
+ return 0;
+}
+```
+
+The expected output may be as follows:
+
+```plain
+Video parsing
+Video transcoding
+Thumbnails generation
+Watermark adding
+Video release
+```
+
+## Example: Fibonacci Sequence
+
+Each number in the Fibonacci sequence is the sum of the first two numbers. The process of calculating the Fibonacci number can well express the task dependency through the data object. The code for calculating the Fibonacci number using the FFRT framework is as follows:
+
+```cpp
+#include
+#include "ffrt/cpp/task.h"
+
+void Fib(int x, int& y)
+{
+ if (x <= 1) {
+ y = x;
+ } else {
+ int y1, y2;
+
+ // Submit the task and build data dependencies.
+ ffrt::submit([&]() { Fib(x - 1, y1); }, {&x}, {&y1});
+ ffrt::submit([&]() { Fib(x - 2, y2); }, {&x}, {&y2});
+
+ // Wait until the task is complete.
+ ffrt::wait({&y1, &y2});
+ y = y1 + y2;
+ }
+}
+
+int main()
+{
+ int y;
+ Fib(5, y);
+ std::cout << "Fibonacci(5) is " << y << std::endl;
+}
+```
+
+Expected output:
+
+```plain
+Fibonacci(5) is 5
+```
+
+In the example, `fibonacci(x-1)` and `fibonacci(x-2)` are submitted to FFRT as two tasks. After the two tasks are complete, the results are accumulated. Although a single task is split into two subtasks, the subtasks can be further split. Therefore, the concurrency of the entire computational graph is very high.
+
+Each task forms a call tree in the FFRT.
+
+
+
+## Available APIs
+
+The main FFRT APIs involved in the preceding example are as follows:
+
+| Name | Description |
+| ------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| [submit](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#submit) | Submits a task. |
+| [submit_h](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#submit_h) | Submits a task, and obtains the task handle.|
+| [wait](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#wait) | Waits until all tasks in the context are complete. |
+
+> **NOTE**
+>
+> For details about how to use FFRT C++ APIs, see [Using FFRT C++ APIs](ffrt-development-guideline.md#using-ffrt-c-api-1).
+
+## Constraints
+
+- For `submit`, the total number of input dependencies and output dependencies of each task cannot exceed 8.
+- For `submit_h`, the total number of input dependencies and output dependencies of each task cannot exceed 7.
+- When a parameter is used as both an input dependency and an output dependency, it is counted as one dependency. For example, if the input dependency is `{&x}` and the output dependency is also `{&x}`, then the number of dependencies is 1.
diff --git a/en/application-dev/ffrt/ffrt-concurrency-paradigm.md b/en/application-dev/ffrt/ffrt-concurrency-paradigm.md
new file mode 100644
index 0000000000000000000000000000000000000000..9b2f3c498207ac49cb096f832c129065a6791f3e
--- /dev/null
+++ b/en/application-dev/ffrt/ffrt-concurrency-paradigm.md
@@ -0,0 +1,43 @@
+# Function Flow Runtime Paradigms
+
+To cope with fixed task execution sequence, flexible priority-based scheduling, and complex task dependencies in actual services, Function Flow Runtime (FFRT) supports three paradigms: serial queue, concurrent queue, and task graph.
+
+## Serial Queue
+
+The serial queue is often used for:
+
+1. **Sequential execution**: The serial queue ensures that tasks are executed one by one in sequence, avoiding data inconsistency and errors caused by out-of-order execution.
+2. **Data security**: The serial queue prevents multiple threads from competing for shared resources concurrently, ensuring data consistency and security.
+3. **Task scheduling**: The serial queue can schedule the execution sequence of complex tasks. For example, it ensures that a task begins after the previous one completes when tasks with multiple dependencies are performed.
+4. **Simplified development**: The serial queue is more simple and clear compared with manual mutex management and synchronization. You only need to add tasks to the queue for automatic system scheduling and execution, simplifying development and debugging.
+5. **Resource management**: The serial queue can limit the number of concurrent tasks and avoid resource competition and overload, optimizing system resource usage.
+
+
+
+For details about the development sample, see [Serial Queue (C)](ffrt-concurrency-serial-queue-c.md) or [Serial Queue (C++)](ffrt-concurrency-serial-queue-cpp.md).
+
+## Concurrent Queue
+
+The concurrent queue is often used for:
+
+1. **Concurrency improvement**: The concurrent queue allows concurrent execution of multiple tasks, fully utilizing the computing capability of the multi-core processor and significantly improving the concurrency and overall performance of the system.
+2. **Efficient resource utilization**: The concurrent queue can allocate tasks to available CPU cores to optimize resource usage and reduce task waiting time and resource competition.
+3. **Flexible task scheduling**: The concurrent queue can schedule tasks based on priorities and QoS to ensure that key tasks can be executed in a timely manner and improve the system response speed.
+4. **Resource impact prevention**: The concurrent queue can set the maximum concurrency to avoid system resource impact caused by excessive concurrent tasks, ensuring system stability and performance.
+
+
+
+For details about the development sample, see [Concurrent Queue (C)](ffrt-concurrency-concurrent-queue-c.md) or [Concurrent Queue (C++)](ffrt-concurrency-concurrent-queue-cpp.md).
+
+## Task Graph
+
+The task graph is often used for:
+
+1. **Complex task dependency**: In actual applications, tasks have complex dependencies among each other. The task graph represents task dependencies by using directed graphs to clearly manage and schedule tasks.
+2. **Dynamic task scheduling**: The task graph can dynamically adjust task scheduling and dependencies and execution sequence according to the running conditions.
+3. **Concurrent task execution**: The task graph allows multiple independent tasks to be executed concurrently, making full use of system computing resources and improving concurrency and execution efficiency.
+4. **Structured concurrency**: The clear task lifecycles and dependencies in the task graph ensure that the creation and completion of concurrent tasks are explicit in the code structure, reducing the complexity and errors of concurrent programming.
+
+
+
+For details about the development sample, see [Task Graph (C)](ffrt-concurrency-graph-c.md) or [Task Graph (C++)](ffrt-concurrency-graph-cpp.md).
diff --git a/en/application-dev/ffrt/ffrt-concurrency-serial-queue-c.md b/en/application-dev/ffrt/ffrt-concurrency-serial-queue-c.md
new file mode 100644
index 0000000000000000000000000000000000000000..a6d549bed2d9c17af4d849aa94b8b0b23b0d6e17
--- /dev/null
+++ b/en/application-dev/ffrt/ffrt-concurrency-serial-queue-c.md
@@ -0,0 +1,196 @@
+# Function Flow Runtime Serial Queue (C)
+
+## Overview
+
+The FFRT serial queue is implemented based on the coroutine scheduling model. It provides efficient message queue functions and supports multiple service scenarios, such as asynchronous communication, mobile data peak clipping, lock-free status and resource management, and architecture decoupling. The following functions are supported:
+
+- **Queue creation and destruction**: The queue name and priority can be specified during creation. Each queue is equivalent to an independent thread. Tasks in the queue are executed asynchronously compared with user threads.
+- **Task delay**: The `delay` can be set when a task is submitted. The unit is `μs`. The delayed task will be scheduled and executed after `uptime` (submission time + delay time).
+- **Serial scheduling**: Tasks in the same queue are sorted in ascending order of `uptime` and executed in serial mode. Ensure that the next task starts to be executed only after the previous task in the queue is complete.
+- **Task canceling**: You can cancel a task that is not dequeued based on the task handle. The task cannot be canceled if it has been started or completed.
+- **Task waiting**: You can wait for a task to complete based on the task handle. When a specified task is complete, all tasks whose `uptime` is earlier than the specified task in the queue have been executed.
+- **Task priority**: You can set the priority of a single task when submitting the task. Priorities take effect only after a task is dequeued relative to other system loads, and do not affect the serial task order in the same queue. If the task priority is not set, the priority of the queue is inherited by default.
+
+## Example: Asynchronous Log System
+
+The following is an example of implementing an asynchronous log system. The main thread submits the log task to the queue, and the background thread obtains the task from the queue and writes the task to the file. It ensures the log sequence and prevents the main thread from being blocked by the file write operation.
+
+With FFRT APIs, you only need to focus on service logic implementation and do not need to pay attention to asynchronous thread management, thread security, and scheduling efficiency.
+
+The example simplifies the logic for handling exceptions and ensuring thread security. The code is as follows:
+
+```c
+#include
+#include
+#include
+#include
+#include "ffrt/queue.h"
+#include "ffrt/task.h"
+
+typedef struct {
+ FILE *logFile; // Pointer to a log file.
+ ffrt_queue_t queue; // Task queue.
+} logger_t;
+
+// Global logger variable.
+logger_t* g_logger = NULL;
+
+// Initialize the log system.
+logger_t *logger_create(const char *filename)
+{
+ logger_t *logger = (logger_t *)malloc(sizeof(logger_t));
+ if (!logger) {
+ perror("Failed to allocate memory for logger_t");
+ return NULL;
+ }
+
+ // Open the log file.
+ logger->logFile = fopen(filename, "a");
+ if (!logger->logFile) {
+ perror("Failed to open log file");
+ free(logger);
+ return NULL;
+ }
+ printf("Log file opened: %s\n", filename);
+
+ // Create a task queue.
+ logger->queue = ffrt_queue_create(ffrt_queue_serial, "logger_queue_c", NULL);
+ if (!logger->queue) {
+ perror("Failed to create queue");
+ fclose(logger->logFile);
+ free(logger);
+ return NULL;
+ }
+
+ return logger;
+}
+
+// Destroy the log system.
+void logger_destroy(logger_t *logger)
+{
+ if (logger) {
+ // Destroy the queue.
+ if (logger->queue) {
+ ffrt_queue_destroy(logger->queue);
+ }
+
+ // Close the log file.
+ if (logger->logFile) {
+ fclose(logger->logFile);
+ printf("Log file closed\n");
+ }
+
+ free(logger);
+ }
+}
+
+// Log task.
+void write_task(void *arg)
+{
+ char *message = (char *)arg;
+ if (g_logger && g_logger->logFile) {
+ fprintf(g_logger->logFile, "%s\n", message);
+ fflush(g_logger->logFile);
+ }
+
+ free(message);
+}
+
+// Add a log task.
+void logger_log(logger_t *logger, const char *message)
+{
+ if (!logger || !logger->queue) {
+ return;
+ }
+
+ // Copy the message string.
+ char *messageCopy = strdup(message);
+ if (!messageCopy) {
+ perror("Failed to allocate memory for message");
+ return;
+ }
+
+ ffrt_queue_submit(logger->queue, ffrt_create_function_wrapper(write_task, NULL, messageCopy), NULL);
+}
+
+int main()
+{
+ // Initialize the global logger.
+ g_logger = logger_create("log_c.txt");
+ if (!g_logger) {
+ return -1;
+ }
+
+ // Use the global logger to add a log task.
+ logger_log(g_logger, "Log message 1");
+ logger_log(g_logger, "Log message 2");
+ logger_log(g_logger, "Log message 3");
+
+ // Simulate the main thread to continue executing other tasks.
+ sleep(1);
+
+ // Destroy the global logger.
+ logger_destroy(g_logger);
+ g_logger = NULL;
+ return 0;
+}
+```
+
+C-style FFRT construction requires additional encapsulation using common code and is irrelevant to specific service scenarios.
+
+```c
+typedef struct {
+ ffrt_function_header_t header;
+ ffrt_function_t func;
+ ffrt_function_t after_func;
+ void* arg;
+} c_function_t;
+
+static inline void ffrt_exec_function_wrapper(void* t)
+{
+ c_function_t* f = (c_function_t *)t;
+ if (f->func) {
+ f->func(f->arg);
+ }
+}
+
+static inline void ffrt_destroy_function_wrapper(void* t)
+{
+ c_function_t* f = (c_function_t *)t;
+ if (f->after_func) {
+ f->after_func(f->arg);
+ }
+}
+
+#define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
+static inline ffrt_function_header_t *ffrt_create_function_wrapper(const ffrt_function_t func,
+ const ffrt_function_t after_func, void *arg)
+{
+ FFRT_STATIC_ASSERT(sizeof(c_function_t) <= ffrt_auto_managed_function_storage_size,
+ size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
+
+ c_function_t* f = (c_function_t *)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_queue);
+ f->header.exec = ffrt_exec_function_wrapper;
+ f->header.destroy = ffrt_destroy_function_wrapper;
+ f->func = func;
+ f->after_func = after_func;
+ f->arg = arg;
+ return (ffrt_function_header_t *)f;
+}
+```
+
+## Available APIs
+
+The main FFRT APIs involved in the preceding example are as follows:
+
+| Name | Description |
+| ---------------------------------------------------------------- | ------------------------------ |
+| [ffrt_queue_create](ffrt-api-guideline-c.md#ffrt_queue_create) | Creates a queue. |
+| [ffrt_queue_destroy](ffrt-api-guideline-c.md#ffrt_queue_destroy) | Destroys a queue. |
+| [ffrt_queue_submit](ffrt-api-guideline-c.md#ffrt_queue_submit) | Submits a task to a queue.|
+
+## Constraints
+
+- **Avoid submitting ultra-long tasks.** The FFRT has a built-in process-level queue task timeout detection mechanism. When the execution time of a serial task exceeds the preset threshold (30 seconds by default), the system prints and reports exception logs and triggers the preset process timeout callback function (if configured).
+- **Use synchronization primitives correctly.** Do not use `std::mutex`, `std::condition_variable`, or `std::recursive_mutex` in the task closure submitted to FFRT. As synchronization primitives in the standard library will occupy the FFRT Worker thread for a long time, you should use the synchronization primitives provided by FFRT: `ffrt::mutex`, `ffrt::condition_variable`, or `ffrt::recursive_mutex`. The usage is the same as that of the standard library.
+- **Manage queues in global variables.** If serial queues are managed in global variables and destroyed with service processes, pay attention to lifecycle decoupling in the test program. When the test is complete, the serial queue needs to be explicitly released. Other resources can be released with global variables. The reason is that global variables are destructed after the main function ends, and the release of serial queues depends on other resources in the FFRT framework, and the resources may have been destroyed.
diff --git a/en/application-dev/ffrt/ffrt-concurrency-serial-queue-cpp.md b/en/application-dev/ffrt/ffrt-concurrency-serial-queue-cpp.md
new file mode 100644
index 0000000000000000000000000000000000000000..99a66f177de9cdf54ba569e0bf489db761e30b52
--- /dev/null
+++ b/en/application-dev/ffrt/ffrt-concurrency-serial-queue-cpp.md
@@ -0,0 +1,99 @@
+# Function Flow Runtime Serial Queue (C++)
+
+## Overview
+
+The FFRT serial queue is implemented based on the coroutine scheduling model. It provides efficient message queue functions and supports multiple service scenarios, such as asynchronous communication, mobile data peak clipping, lock-free status and resource management, and architecture decoupling. The following functions are supported:
+
+- **Queue creation and destruction**: The queue name and priority can be specified during creation. Each queue is equivalent to an independent thread. Tasks in the queue are executed asynchronously compared with user threads.
+- **Task delay**: The `delay` can be set when a task is submitted. The unit is `μs`. The delayed task will be scheduled and executed after `uptime` (submission time + delay time).
+- **Serial scheduling**: Tasks in the same queue are sorted in ascending order of `uptime` and executed in serial mode. Ensure that the next task starts to be executed only after the previous task in the queue is complete.
+- **Task canceling**: You can cancel a task that is not dequeued based on the task handle. The task cannot be canceled if it has been started or completed.
+- **Task waiting**: You can wait for a task to complete based on the task handle. When a specified task is complete, all tasks whose `uptime` is earlier than the specified task in the queue have been executed.
+- **Task priority**: You can set the priority of a single task when submitting the task. Priorities take effect only after a task is dequeued relative to other system loads, and do not affect the serial task order in the same queue. If the task priority is not set, the priority of the queue is inherited by default.
+
+## Example: Asynchronous Log System
+
+The following is an example of implementing an asynchronous log system. The main thread submits the log task to the queue, and the background thread obtains the task from the queue and writes the task to the file. It ensures the log sequence and prevents the main thread from being blocked by the file write operation.
+
+With FFRT APIs, you only need to focus on service logic implementation and do not need to pay attention to asynchronous thread management, thread security, and scheduling efficiency.
+
+The example simplifies the logic for handling exceptions and ensuring thread security. The code is as follows:
+
+```cpp
+#include
+#include
+#include
+#include
+#include "ffrt/cpp/queue.h"
+
+class Logger {
+public:
+ Logger(const std::string& filename)
+ {
+ // Create a queue.
+ queue_ = std::make_unique("loggerQueue");
+
+ // Open a file in append mode.
+ logFile_.open(filename, std::ios::app);
+ if (!logFile_.is_open()) {
+ throw std::runtime_error("Failed to open log file: " + filename);
+ }
+ std::cout << "Log file opened: " << filename << std::endl;
+ }
+
+ ~Logger() {
+ // Destroy the queue.
+ queue_ = nullptr;
+
+ if (logFile_.is_open()) {
+ logFile_.close();
+ std::cout << "Log file closed" << std::endl;
+ }
+ }
+
+ // Add a log task.
+ void log(const std::string& message) {
+ queue_->submit([this, message] {
+ logFile_ << message << std::endl;
+ });
+ }
+
+private:
+ std::ofstream logFile_;
+ std::unique_ptr queue_;
+};
+
+int main()
+{
+ Logger logger("log.txt");
+
+ // The main thread adds the log task.
+ logger.log("Log message 1");
+ logger.log("Log message 2");
+ logger.log("Log message 3");
+
+ // Simulate the main thread to continue executing other tasks.
+ std::this_thread::sleep_for(std::chrono::seconds(1));
+
+ return 0;
+}
+```
+
+## Available APIs
+
+The main FFRT APIs involved in the preceding example are as follows:
+
+| Name | Description |
+| --------------------------------------------------------------------------------------------------------------------- | -------------- |
+| class [queue](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#queue) | Queue class. |
+| [sleep_for](https://gitee.com/openharmony/resourceschedule_ffrt/blob/master/docs/ffrt-api-guideline-cpp.md#sleep_for) | Delays a task for some time.|
+
+> **NOTE**
+>
+> For details about how to use FFRT C++ APIs, see [Using FFRT C++ APIs](ffrt-development-guideline.md#using-ffrt-c-api-1).
+
+## Constraints
+
+- **Avoid submitting ultra-long tasks.** The FFRT has a built-in process-level queue task timeout detection mechanism. When the execution time of a serial task exceeds the preset threshold (30 seconds by default), the system prints and reports exception logs and triggers the preset process timeout callback function (if configured).
+- **Use synchronization primitives correctly.** Do not use `std::mutex`, `std::condition_variable`, or `std::recursive_mutex` in the task closure submitted to FFRT. As synchronization primitives in the standard library will occupy the FFRT Worker thread for a long time, you should use the synchronization primitives provided by FFRT: `ffrt::mutex`, `ffrt::condition_variable`, or `ffrt::recursive_mutex`. The usage is the same as that of the standard library.
+- **Manage queues in global variables.** If serial queues are managed in global variables and destroyed with service processes, pay attention to lifecycle decoupling in the test program. When the test is complete, the serial queue needs to be explicitly released. Other resources can be released with global variables. The reason is that global variables are destructed after the main function ends, and the release of serial queues depends on other resources in the FFRT framework, and the resources may have been destroyed.
diff --git a/en/application-dev/ffrt/ffrt-development-guideline.md b/en/application-dev/ffrt/ffrt-development-guideline.md
index 602f6492c3016433f6e31d3b9f85817817541f8e..f93297a801ac76fccadaa472426a908b6d2a7c47 100644
--- a/en/application-dev/ffrt/ffrt-development-guideline.md
+++ b/en/application-dev/ffrt/ffrt-development-guideline.md
@@ -1,2387 +1,258 @@
# Function Flow Runtime Development
-## When to Use
-
-Function Flow is a task-based and data-driven concurrent programming model that allows you to develop an application by creating tasks and describing their dependencies. Function Flow Runtime (FFRT) is a software runtime library that works with the Function Flow programming model. It is used to schedule and execute tasks of an application developed on the Function Flow programming model. Specifically, FFRT automatically and concurrently schedules and executes tasks of the application based on the task dependency status and available resources, so that you can focus on feature development.
-
-This topic walks you through how to implement parallel programming based on the Function Flow programming model and FFRT.
-
-## Available APIs
-
-| API | Description |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| ffrt_condattr_init (ffrt_condattr_t* attr) | Initializes a condition variable attribute.|
-| ffrt_condattr_destroy(ffrt_condattr_t* attr) | Destroys a condition variable attribute.|
-| ffrt_condattr_setclock(ffrt_condattr_t* attr, ffrt_clockid_t clock) | Sets the clock of a condition variable attribute.|
-| ffrt_condattr_getclock(const ffrt_condattr_t* attr, ffrt_clockid_t* clock) | Obtains the clock of a condition variable attribute. |
-| ffrt_cond_init(ffrt_cond_t* cond, const ffrt_condattr_t* attr) | Initializes a condition variable. |
-| ffrt_cond_signal(ffrt_cond_t* cond) | Unblocks at least one of the threads that are blocked on a condition variable.|
-| ffrt_cond_broadcast(ffrt_cond_t* cond) | Unblocks all threads currently blocked on a condition variable.|
-| ffrt_cond_wait(ffrt_cond_t* cond, ffrt_mutex_t* mutex) | Blocks the calling thread on a condition variable.|
-| ffrt_cond_timedwait(ffrt_cond_t* cond, ffrt_mutex_t* mutex, const struct timespec* time_point) | Blocks the calling thread on a condition variable for a given duration.|
-| ffrt_cond_destroy(ffrt_cond_t* cond) | Destroys a condition variable.|
-| ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr) | Initializes a mutex.|
-| ffrt_mutex_lock(ffrt_mutex_t* mutex) | Locks a mutex.|
-| ffrt_mutex_unlock(ffrt_mutex_t* mutex) | Unlocks a mutex.|
-| ffrt_mutex_trylock(ffrt_mutex_t* mutex) | Attempts to lock a mutex.|
-| ffrt_mutex_destroy(ffrt_mutex_t* mutex) | Destroys a mutex.|
-| ffrt_queue_attr_init(ffrt_queue_attr_t* attr) | Initializes a queue attribute.|
-| ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr) | Destroys a queue attribute.|
-| ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos) | Sets the queue QoS.|
-| ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr) | Obtains the queue QoS.|
-| ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr) | Creates a queue.|
-| ffrt_queue_destroy(ffrt_queue_t queue) | Destroys a queue.|
-| ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr) | Submits a task to a queue.|
-| ffrt_queue_submit_h(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr) | Submits a task to a queue, and obtains the task handle.|
-| ffrt_queue_wait(ffrt_task_handle_t handle) | Waits until a task in the queue is complete.|
-| ffrt_queue_cancel(ffrt_task_handle_t handle) | Cancels a task in the queue.|
-| ffrt_queue_attr_set_max_concurrency(ffrt_queue_attr_t* attr, const int max_concurrency) | Sets the maximum concurrency for a queue, which must be a concurrent queue.|
-| ffrt_queue_attr_get_max_concurrency(ffrt_queue_attr_t* attr) | Obtains the maximum concurrency of a queue, which must be a concurrent queue.|
-| ffrt_get_main_queue() | Obtains the main thread queue.|
-| ffrt_get_current_queue() | Obtains the ArkTS Worker thread queue.|
-| ffrt_usleep(uint64_t usec) | Suspends the calling thread for a given duration.|
-| ffrt_yield(void) | Passes control to other tasks so that they can be executed.|
-| ffrt_task_attr_init(ffrt_task_attr_t* attr) | Initializes a task attribute.|
-| ffrt_task_attr_set_name(ffrt_task_attr_t* attr, const char* name) | Sets a task name.|
-| ffrt_task_attr_get_name(const ffrt_task_attr_t* attr) | Obtains a task name.|
-| ffrt_task_attr_destroy(ffrt_task_attr_t* attr) | Destroys a task attribute.|
-| ffrt_task_attr_set_qos(ffrt_task_attr_t* attr, ffrt_qos_t qos) | Sets the task QoS.|
-| ffrt_task_attr_get_qos(const ffrt_task_attr_t* attr) | Obtains the task QoS.|
-| ffrt_task_attr_set_delay(ffrt_task_attr_t* attr, uint64_t delay_us) | Sets the task delay time.|
-| ffrt_task_attr_get_delay(const ffrt_task_attr_t* attr) | Obtains the task delay time.|
-| ffrt_task_attr_set_queue_priority(ffrt_task_attr_t* attr, ffrt_queue_priority_t priority) | Sets the task priority in the queue.|
-| ffrt_task_attr_get_queue_priority(const ffrt_task_attr_t* attr) | Obtains the task priority in the queue.|
-| ffrt_this_task_get_qos() | Obtains the QoS of this task.|
-| ffrt_this_task_update_qos(ffrt_qos_t qos) | Updates the QoS of this task.|
-| ffrt_this_task_get_id(void) | Obtains the ID of this task.|
-| ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind) | Applies for memory for the function execution structure.|
-| ffrt_submit_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr) | Submits a task.|
-| ffrt_submit_h_base(ffrt_function_header_t* f, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr) | Submits a task, and obtains the task handle.|
-| ffrt_task_handle_destroy(ffrt_task_handle_t handle) | Destroys a task handle.|
-| ffrt_skip(ffrt_task_handle_t handle) | Skips a task.|
-| ffrt_wait_deps(const ffrt_deps_t* deps) | Waits until the dependent tasks are complete.|
-| ffrt_loop_create(ffrt_queue_t queue) | Creates a loop.|
-| ffrt_loop_destroy(ffrt_loop_t loop) | Destroys a loop.|
-| ffrt_loop_run(ffrt_loop_t loop) | Runs a loop.|
-| ffrt_loop_stop(ffrt_loop_t loop) | Stops a loop.|
-| ffrt_loop_epoll_ctl(ffrt_loop_t loop, int op, int fd, uint32_t events, void* data, ffrt_poller_cb cb) | Manages listening events on a loop.|
-| ffrt_loop_timer_start(ffrt_loop_t loop, uint64_t timeout, void* data, ffrt_timer_cb cb, bool repeat) | Starts the timer on a loop.|
-| ffrt_loop_timer_stop(ffrt_loop_t loop, ffrt_timer_t handle) | Stops the timer on a loop.|
-| ffrt_timer_start(ffrt_qos_t qos, uint64_t timeout, void* data, ffrt_timer_cb cb, bool repeat) | Starts the timer.|
-| ffrt_timer_stop(ffrt_qos_t qos, ffrt_timer_t handle); | Stops the timer.|
-
-## API Introduction
-
-
-### Task Management APIs
-
-#### ffrt_submit_base
-
-Exports an FFRT dynamic library. You can encapsulate this API into the C API **ffrt_submit** for binary compatibility.
-
-##### Declaration
-
-```{.c}
-const int ffrt_auto_managed_function_storage_size = 64 + sizeof(ffrt_function_header_t);
-typedef enum {
- ffrt_function_kind_general,
- ffrt_function_kind_queue
-} ffrt_function_kind_t;
-
-void* ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_t kind);
-
-typedef void(*ffrt_function_t)(void*);
-typedef struct {
- ffrt_function_t exec;
- ffrt_function_t destroy;
- uint64_t reserve[2];
-} ffrt_function_header_t;
-
-void ffrt_submit_base(ffrt_function_header_t* func, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr);
-```
-
-##### Parameters
-
-`kind`
-
-Subtype of **function**. It is used to optimize the internal data structure. The default value is **ffrt_function_kind_general**.
-
-`func`
-
-Pointer to the CPU function. The struct executed by the pointer describes two function pointers, namely, **exec** and **destroy**, according to the **ffrt_function_header_t** definition. FFRT executes and destroys the task by using the two function pointers.
-
-`in_deps`
-
-* Optional.
-* Input dependencies of the task. FFRT establishes the dependency by using the virtual address of the data as the data signature.
-
-`out_deps`
-
-* Optional.
-
-* Output dependencies of the task.
-
- **NOTE**
-
- The dependency is essentially a value. FFRT cannot determine whether the value is reasonable. It always treats the input value reasonable. However, you are not advised to use inappropriate values such as **NULL**, **1**, or **2** to establish dependencies because doing this will establish unnecessary dependencies and affect concurrency. Instead, use the actual memory address.
-
-`attr`
-
-* Optional.
-* Task attribute, such as QoS. For details, see [ffrt_task_attr_t](#ffrt_task_attr_t).
-
-##### Return value
-
-N/A
-
-##### Description
-* You are advised to encapsulate **ffrt_submit_base** first. For details, see **Example** below.
-* As an underlying capability, **ffrt_submit_base** must meet the following requirements:
- * The **func** pointer can be allocated by calling **ffrt_alloc_auto_managed_function_storage_base**, and the two function pointers in the struct must be in the specified sequence (**exec** prior to **destroy**).
- * The memory allocated by calling **ffrt_alloc_auto_managed_function_storage_base** is of the size specified by **ffrt_auto_managed_function_storage_size**. Its lifecycle is managed by FFRT. When the task is complete, FFRT automatically releases the memory.
-* The following two function pointers are defined in **ffrt_function_header_t**:
- * **exec**: describes how the task is executed. It is called by FFRT to execute the task.
- * **destroy**: describes how a task is destroyed. It is called by FFRT to destroy the task.
-
-##### Example
-
-
-```{.c}
-template
-struct function {
- template
- function(ffrt_function_header_t h, CT&& c) : header(h), closure(std::forward(c)) {}
- ffrt_function_header_t header;
- T closure;
-};
-
-template
-void exec_function_wrapper(void* t)
-{
- auto f = (function>*)t;
- f->closure();
-}
-
-template
-void destroy_function_wrapper(void* t)
-{
- auto f = (function>*)t;
- f->closure = nullptr;
-}
-
-template
-inline ffrt_function_header_t* create_function_wrapper(T&& func)
-{
- using function_type = function>;
- static_assert(sizeof(function_type) <= ffrt_auto_managed_function_storage_size,
- "size of function must be less than ffrt_auto_managed_function_storage_size");
-
- auto p = ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
- auto f = new (p) function_type(
- {exec_function_wrapper, destroy_function_wrapper},
- std::forward(func));
- return (ffrt_function_header_t*)f;
-}
-
-static inline void submit(std::function&& func)
-{
- return ffrt_submit_base(create_function_wrapper(std::move(func)), NULL, NULL, NULL);
-}
-```
-
-#### ffrt_wait
-
-- Used together with **ffrt_submit_base**.
-- Waits by suspending the current execution context, until the specified data is produced or all subtasks of the current task are complete.
-
-##### Declaration
-
-```{.c}
-void ffrt_wait_deps(ffrt_deps_t* deps);
-void ffrt_wait();
-```
-
-##### Parameters
-
-`deps`
-
-Virtual addresses of the data to be produced. These addresses may be used as **out_deps** in **submit()** of some tasks. For details about how to generate the dependency, see **ffrt_deps_t**. Note that a null pointer indicates no dependency.
-
-##### Return value
-
-N/A
-
-##### Description
-* **ffrt_wait_deps(deps)** is used to suspend code execution before the data specified by **deps** is produced.
-* **ffrt_wait()** is used to suspend code execution before all subtasks (excluding grandchild tasks and lower-level subtasks) submitted by the current context are complete.
-* This API can be called inside or outside an FFRT task.
-* **ffrt_wait_deps(deps)** or **ffrt_wait()** called outside an FFRT task can be sensed by the OS, and therefore it is more expensive than that called inside an FFRT task. As such, you are advised to use **ffrt_wait()** inside an FFRT task whenever possible.
-
-##### Example
-
-**Recursive Fibonacci**
-
-The Fibonacci Sequence implemented in serial mode is as follows:
-
-```{.c}
-#include
-
-void fib(int x, int* y) {
- if (x <= 1) {
- *y = x;
- } else {
- int y1, y2;
- fib(x - 1, &y1);
- fib(x - 2, &y2);
- *y = y1 + y2;
- }
-}
-int main(int narg, char** argv)
-{
- int r;
- fib(10, &r);
- printf("fibonacci 10: %d\n", r);
- return 0;
-}
-```
-
-Use FFRT to implement the Fibonacci Sequence in parallel mode: (For Fibonacci, the computing workload of a single task is small and parallel acceleration is not required. However, this pattern requires high flexibility of the parallel programming model.)
-
-```{.c}
-#include
-#include "ffrt.h" // All header files related to FFRT are included.
-
-typedef struct {
- int x;
- int* y;
-} fib_ffrt_s;
-
-typedef struct {
- ffrt_function_header_t header;
- ffrt_function_t func;
- ffrt_function_t after_func;
- void* arg;
-} c_function;
-
-static void ffrt_exec_function_wrapper(void* t)
-{
- c_function* f = (c_function*)t;
- if (f->func) {
- f->func(f->arg);
- }
-}
-
-static void ffrt_destroy_function_wrapper(void* t)
-{
- c_function* f = (c_function*)t;
- if (f->after_func) {
- f->after_func(f->arg);
- }
-}
-
-#define FFRT_STATIC_ASSERT(cond, msg) int x(int static_assertion_##msg[(cond) ? 1 : -1])
-static inline ffrt_function_header_t* ffrt_create_function_wrapper(const ffrt_function_t func,
- const ffrt_function_t after_func, void* arg)
-{
- FFRT_STATIC_ASSERT(sizeof(c_function) <= ffrt_auto_managed_function_storage_size,
- size_of_function_must_be_less_than_ffrt_auto_managed_function_storage_size);
- c_function* f = (c_function*)ffrt_alloc_auto_managed_function_storage_base(ffrt_function_kind_general);
- f->header.exec = ffrt_exec_function_wrapper;
- f->header.destroy = ffrt_destroy_function_wrapper;
- f->func = func;
- f->after_func = after_func;
- f->arg = arg;
- return (ffrt_function_header_t*)f;
-}
-
-static inline void ffrt_submit_c(ffrt_function_t func, const ffrt_function_t after_func,
- void* arg, const ffrt_deps_t* in_deps, const ffrt_deps_t* out_deps, const ffrt_task_attr_t* attr)
-{
- ffrt_submit_base(ffrt_create_function_wrapper(func, after_func, arg), in_deps, out_deps, attr);
-}
-
-void fib_ffrt(void* arg)
-{
- fib_ffrt_s* p = (fib_ffrt_s*)arg;
- int x = p->x;
- int* y = p->y;
-
- if (x <= 1) {
- *y = x;
- } else {
- int y1, y2;
- fib_ffrt_s s1 = {x - 1, &y1};
- fib_ffrt_s s2 = {x - 2, &y2};
- const std::vector dx_deps = {{ffrt_dependence_data, &x}};
- ffrt_deps_t dx{static_cast(dx_deps.size()), dx_deps.data()};
- const std::vector dy1_deps = {{ffrt_dependence_data, &y1}};
- ffrt_deps_t dy1{static_cast(dy1_deps.size()), dy1_deps.data()};
- const std::vector