翻译完成:Media + Media Library Kit 批量更新 - API 21
Created-by: wusongqing
Commit-by: Gloria
Merged-by: openharmony_ci
Description: Media + Media Library Kit 批量更新 - API 21
See merge request: openharmony/docs!121504
bundleName: 'com.samples.stagemodelabilityinteraction', // Replace the bundle name and page name with those of the local application.
abilityName: 'CollaborateAbility',
moduleName: 'entry', // moduleName is optional.
};
@@ -479,7 +479,7 @@ A system application can connect to a service on another device by calling [conn
3. (Optional) [Implement a background service](serviceextensionability-sys.md#implementing-a-background-service-for-system-applications-only). Perform this operation only if no background service is available. This operation is available only for system applications.
4. Connect to the background service.
- Implement the **IAbilityConnection** class. **IAbilityConnection** provides the following callbacks that you should implement: [onConnect()](../reference/apis-ability-kit/js-apis-inner-ability-connectOptions.md#onconnect), [onDisconnect()](../reference/apis-ability-kit/js-apis-inner-ability-connectOptions.md#ondisconnect), and [onFailed()](../reference/apis-ability-kit/js-apis-inner-ability-connectOptions.md#onfailed). The **onConnect()** callback is invoked when a service is connected, **onDisconnect()** is invoked when a service is unexpectedly disconnected, and **onFailed()** is invoked when the connection to a service fails.
- Implement the **AbilityConnection** API. **AbilityConnection** provides the following callbacks that you should implement: [onConnect()](../reference/apis-ability-kit/js-apis-inner-ability-connectOptions.md#onconnect), [onDisconnect()](../reference/apis-ability-kit/js-apis-inner-ability-connectOptions.md#ondisconnect), and [onFailed()](../reference/apis-ability-kit/js-apis-inner-ability-connectOptions.md#onfailed). The **onConnect()** callback is invoked when a service is connected, **onDisconnect()** is invoked when a service is unexpectedly disconnected, and **onFailed()** is invoked when the connection to a service fails.
- Set the target component parameters, including the target device ID, bundle name, and ability name.
- Call **connectServiceExtensionAbility()** to initiate a connection.
- Receive the service handle returned by the target device when the connection is successful.
@@ -570,7 +570,7 @@ A system application can connect to a service on another device by calling [conn
The **encrypt** property in [StoreConfig](../reference/apis-arkdata/arkts-apis-data-relationalStore-i.md#storeconfig) specifies whether to encrypt the RDB store. The value **true** means to encrypt the RDB store, and **false** means the opposite.
| getPreferencesSync(context: Context, options: Options): Preferences | Obtains a **Preferences** instance. This API returns the result synchronously. An asynchronous API is also provided. |
| putSync(key: string, value: ValueType): void | Writes data to the **Preferences** instance. This API returns the result synchronously. An asynchronous API is also provided.|
| putSync(key: string, value: ValueType): void | Writes data to the **Preferences** instance. You can use **flush()** to persist the **Preferences** instance data. This API returns the result synchronously. An asynchronous API is also provided.|
| hasSync(key: string): boolean | Checks whether the **Preferences** instance contains the KV pair with the given key. The value **true** means the instance contains the KV pair; the value **false** means the opposite. The key cannot be empty. This API returns the result synchronously. An asynchronous API is also provided.|
| getSync(key: string, defValue: ValueType): ValueType | Obtains the value of the specified key. If the value is null or not of the default value type, **defValue** is returned. This API returns the result synchronously. An asynchronous API is also provided.|
| deleteSync(key: string): void | Deletes a KV pair from the **Preferences** instance. This API returns the result synchronously. An asynchronous API is also provided.|
@@ -236,7 +236,7 @@ The following table lists the APIs related to user preference persistence. For m
Specify an observer as the callback to return the data changes for an application.
If the preferences data is stored in the default format (XML), the observer callback will be triggered only after the subscribed value changes and **flush()** is executed.
If the preferences data is stored in the default format (XML), the observer callback will be triggered only after the subscribed **key** value changes and **flush()** is executed.
Example:
@@ -264,7 +264,7 @@ The following table lists the APIs related to user preference persistence. For m
})
```
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()**).
If the preferences data is stored in GSKV format, the observer callback will be triggered after the subscribed **key** value changes (without the need for calling **flush()**).
@@ -113,7 +113,7 @@ Since API version 20, synchronization of [assets](../reference/apis-arkdata/js-a
## Constraints
<!--RP5-->
- Currently, distributed data objects can be used only in [cross-device migration](../application-models/hop-cross-device-migration.md) and [multi-device collaboration using the cross-device call](../application-models/hop-multi-device-collaboration.md#using-cross-device-call).
- Currently, distributed data objects can be used only in [cross-device migration](../application-models/hop-cross-device-migration.md) and [multi-device collaboration using the cross-device call](../application-models/hop-multi-device-collaboration.md#using-cross-device-call). The size of each distributed data object cannot exceed 150 KB in the cross-device migration scenario, whereas it cannot exceed 500 KB in the multi-device collaboration scenario.
- Currently, the cross-device continuation capability supports the following scenarios:
- [Migrating between abilities in the same application across devices](../application-models/hop-cross-device-migration.md#migrating-between-abilities-in-the-same-application-across-devices)
@@ -121,10 +121,6 @@ Since API version 20, synchronization of [assets](../reference/apis-arkdata/js-a
<!--RP5End-->
- Data can be synced for the distributed data objects with the same session ID.
- Each distributed data object occupies 100 KB to 150 KB of memory. Therefore, you are advised not to create too many distributed data objects.
- The maximum size of a distributed data object is 500 KB.
- If data of 1 KB data is modified on device A, device B can complete data update within 50 ms after receiving a data change notification.
- A maximum of 16 distributed data object instances can be created for an application.
@@ -158,7 +154,7 @@ Most of the APIs for cross-device sync of distributed data objects are executed
| on(type: 'change', callback: DataObserver<void>): void | Subscribes to data changes of a distributed data object.|
| off(type: 'change', callback?: DataObserver<void>): void | Unsubscribes from data changes of a distributed data object.|
| on(type: 'status', callback: StatusObserver<void>): void | Subscribes to the status changes of a distributed data object.|
| on(type: 'status', callback: StatusObserver<void>): void | Subscribes to the status changes of a distributed data object.|
| off(type: 'status', callback?: StatusObserver<void>): void | Unsubscribes from status changes of a distributed data object.|
@@ -196,7 +192,7 @@ Most of the APIs for cross-device sync of distributed data objects are executed
>
> - The initial value of the service data must be set to **undefined** on the target device so that the data saved on the source device can be restored on the target device. Otherwise, the data on the source device will be overwritten by the data set on the target device. For asset data, you need to set each attribute of the asset data to an empty string instead of setting the entire asset data to **undefined**.
>
> - Currently, the asset array is not supported. If multiple files need to be migrated, define an asset data record for each file to migrate.
> - Before API version 20, the asset array is not supported. If multiple files need to be migrated, define an asset data record for each file to migrate. Since API version 20, the asset array can be synced.
>
> - Currently, only files in distributed file directory can be migrated. Files in other directories can be copied or moved to distributed file directory before migration. For details about how to move or copy files and obtain URIs, see [File Management](../reference/apis-core-file-kit/js-apis-file-fs.md) and [File URI](../reference/apis-core-file-kit/js-apis-file-fileuri.md).
@@ -29,7 +29,7 @@ Currently, AppFreeze detection supports the fault types listed in the following
| APP_INPUT_BLOCK | The user input response times out.|
| LIFECYCLE_TIMEOUT | Ability lifecycle switching times out.|
When any of the preceding faults occurs in an application, the application is killed to ensure that it is recoverable and the application freeze event is reported. You can subscribe to the [application freeze event](hiappevent-watcher-freeze-events.md) by using HiAppEvent.
When any of the preceding faults occurs in an application, the application is killed to ensure that it is recoverable and the application freeze event is reported. You can subscribe to the [application freeze event](hiappevent-watcher-freeze-events.md) using HiAppEvent.
### THREAD_BLOCK_6S Application Main Thread Timeout
@@ -203,10 +203,42 @@ All the three types of AppFreeze events include the following information.
| PACKAGE_NAME | Application process package name.|
| PROCESS_NAME | Application process name.|
| MSG | Time when the fault occurs and **EventHandler** information.|
**EventHandler** information. The details are as follows:
Structure of the dump information.
| Field| Description|
| -------- | -------- |
| EventHandler dump begin curTime | Time when the dump information is obtained.|
| Event runner | Thread name and thread ID corresponding to **EventHandler**.|
| Current Running | Complete information about the task that is being executed.|
| History event queue information | Information about historical tasks.|
| Immediate priority event queue information | Information about the task queue that is executed immediately.|
| High priority event queue information | Information about the high-priority task queue.|
| Low priority event queue information | Information about the low-priority task queue.|
| Idle priority event queue information | Information about the suspended task queue.|
Task components.
| Field| Description|
| -------- | -------- |
| send thread | Thread ID of the submitted task.|
| send time | Time when a task is submitted.|
| task name | Task name in the task queue.|
| priority | Task priority.|
| caller | Method of submitting a task.|
| handle time | Expected execution time of a task. The value may be different from the actual task execution time (**trigger time**).|
| trigger time | Task execution time.|
| completeTime time | Time when the task is complete. (If no information is displayed, the task is not complete.)|
> **NOTE**
>
> In the **EventHandler** information, you only need to pay attention to **EventHandler dump begin curTime**, **trigger time**, and **completeTime time**.
>
>
### Stack Information
Stack information of the faulty process is displayed.
@@ -283,24 +315,24 @@ pid context request started max ready free_async_space
The IPC information is described as follows.
| | |
| Field| Description|
| -------- | -------- |
| xxx:xxx to xxx:xxx | Client process ID, thread ID to server process ID, thread ID. **async** indicates asynchronous; no **async** indicates synchronous.|
| code | Service code agreed by the client and server.|
| wait | Communication waiting duration.|
| frz_state | Process freeze status.<br>**-1**: Unknown.<br>**1**: Default.<br>**2**: The binder status information is being sent to the user mode.<br>**3**: The binder receiving thread is reached.|
| ns | Client process ID, thread ID to server process ID, thread ID (-1 for non-DroiTong processes). |
| debug | Supplementary information about the IPC parties.|
| active_code | The asynchronous message code being processed. |
| active_thread | Thread that processes the asynchronous message.|
| pending_async_proc | Process blocked by the asynchronous message.|
| pid | Process ID.|
| context | Communication mode.|
| request | Number of IPC threads requested.|
| started | Number of started IPC threads.|
| max | Maximum number of IPC threads that can be requested.|
| ready | Free IPC thread. |
| free_async_space | Free asynchronous space, which is used to observe asynchronous information blocking.|
| xxx:xxx to xxx:xxx | Client process ID and thread ID to server process ID and thread ID. **async** indicates asynchronous; no **async** indicates synchronous.|
| code | Service code agreed by the client and server.|
| wait | Communication waiting duration.|
| frz_state | Process freeze state.<br>**-1**: Unknown.<br>**1**: Default.<br>**2**: The binder status information is being sent to the user mode.<br>**3**: The binder receiving thread is reached.|
| ns | Client process ID and thread ID to server process ID and thread ID (**-1** for non-DroiTong processes).|
| debug | Supplementary information about the IPC parties.|
| active_code | Code of the asynchronous message that is being processed.|
| active_thread | Thread that processes the asynchronous message.|
| pending_async_proc | Process blocked by the asynchronous message.|
| pid | Process ID.|
| context | Communication mode.|
| request | Number of IPC threads requested.|
| started | Number of started IPC threads.|
| max | Maximum number of IPC threads that can be requested.|
| ready | Idle IPC thread.|
| free_async_space | Free asynchronous space, which is used to observe asynchronous information blocking.|
(2) **PeerBinder Stacktrace**: Stack traces of unresponsive peer processes communicating with the faulty process.
@@ -341,15 +373,15 @@ Details of Processes:
1685 0.53% 0.31% 0.22% 879838 59636 foundation
```
| | |
| Field| Description|
| -------- | -------- |
| PID | Process ID.|
| Total Usage | CPU usage. **Total Usage** = **User Space** + **Kernel Space**.|
| User Space | User space usage. |
| Kernel Space | Kernel space usage. |
| Page Fault Minor | Minor page fault.|
| Page Fault Major | Major page fault.|
| Name | Process name. |
| PID | Process ID.|
| Total Usage | CPU usage. **Total Usage** = **User Space** + **Kernel Space**.|
| User Space | CPU usage in user mode.|
| Kernel Space | CPU usage in kernel mode.|
| Page Fault Minor | Minor page fault.|
| Page Fault Major | Major page fault.|
| Name | Name of the process.|
### Memory Information
@@ -366,7 +398,7 @@ The preceding shows the system memory information. **ReclaimAvailBuffer** indica
## Log Differences
Lifecycle timeout event.
**Lifecycle timeout event**
```
DOMAIN:AAFWK
@@ -401,59 +433,78 @@ The following describes the MSG information with two complete lifecycle switchov
(1) Events in the load phase (when the application process is not created)
| | | |
| server | client | Description|
| -------- | -------- | -------- |
| server | client | Description |
| AbilityRecord::LoadAbility; the LoadAbility lifecycle starts. |- | Start. |
| AppMgrServiceInner::LoadAbility | -| The process is yet to be created. |
| AppMgrService::AttachApplication | -| The process is successfully created and attached. |
| ServiceInner::AttachApplication | -| The process is attached. |
| ServiceInner::LaunchApplication | -| The application is scheduled to execute the loading process. |
| AppRunningRecord::LaunchApplication | -| The application is scheduled to execute the loading process. |
| AppScheduler::ScheduleLaunchApplication | -| The application is scheduled to execute the loading process. |
| -| ScheduleLaunchApplication | The application receives a loading scheduling request. |
| -| HandleLaunchApplication begin | The application loading starts. |
| -| HandleLaunchApplication end | The application loading ends. |
| AppRunningRecord::LaunchPendingAbilities | -| The application is scheduled to start ability. |
| -| MainThread::ScheduleLaunchAbility | The application receives a request to load ability. |
| -| MainThread::HandleLaunchAbility | The main thread processes the request. |
| -| JsAbilityStage::Create | An AbilityStage is loaded. |
| -| JsAbilityStage::OnCreate begin | The **onCreate** lifecycle of AbilityStage starts. |
| -| JsAbilityStage::OnCreate end | The **onCreate** lifecycle of **AbilityStage** ends. |
| -| AbilityThread::Attach | The ability is attached to AMS, and the loading process ends. |
| AbilityRecord::LoadAbility; the LoadAbility lifecycle starts. |- | The lifecycle starts.|
| AppMgrServiceInner::LoadAbility | -| Before the process is created.|
| AppMgrService::AttachApplication | -| The process is created and attached.|
| ServiceInner::AttachApplication | -| The process is attached.|
| ServiceInner::LaunchApplication | -| The application is scheduled to execute the loading process.|
| AppRunningRecord::LaunchApplication | -| The application is scheduled to execute the loading process.|
| AppScheduler::ScheduleLaunchApplication | -| The application is scheduled to execute the loading process.|
| -| ScheduleLaunchApplication | The application receives a loading scheduling request.|
| -| HandleLaunchApplication begin | The application loading starts.|
| -| HandleLaunchApplication end | The application loading ends.|
| AppRunningRecord::LaunchPendingAbilities | -| The application is scheduled to start an ability.|
| -| MainThread::ScheduleLaunchAbility | The application receives a request to load an ability.|
| -| MainThread::HandleLaunchAbility | The main thread processes the request.|
| -| JsAbilityStage::Create | The AbilityStage is loaded.|
| -| JsAbilityStage::OnCreate begin | The **onCreate** lifecycle of the AbilityStage starts.|
| -| JsAbilityStage::OnCreate end | The **onCreate** lifecycle of the AbilityStage ends.|
| -| AbilityThread::Attach | The ability is attached to AMS, and the loading process ends.|
(2) Foreground phase event – cold start
| | | |
| server | client | Description|
| -------- | -------- | -------- |
| server | client | Description |
| AbilityRecord::ProcessForegroundAbility; the ProcessForegroundAbility lifecycle starts. | | Start. |
| ServiceInner::UpdateAbilityState | -| The application frontend is scheduled first. |
| AppRunningRecord::ScheduleForegroundRunning | -| The application foreground is scheduled. |
| AppScheduler::ScheduleForegroundApplication | -| The application foreground is scheduled. |
| -| ScheduleForegroundApplication | The application receives a scheduling request. |
| -| HandleForegroundApplication | The main thread executes the scheduling request. |
| AppMgrService::AppForegrounded | -| The application enters the foreground. |
| ServiceInner::AppForegrounded | -| The application enters the foreground. |
| -| AbilityThread::ScheduleAbilityTransaction | The application receives an ability foreground scheduling request. |
| -| AbilityThread::HandleAbilityTransaction | The main thread executes the ability foreground scheduling. |
| -| JsUIAbility::OnStart begin | The **onCreate** lifecycle starts. |
| -| JsUIAbility::OnStart end | The **onCreate** lifecycle ends. |
| -| JsUIAbility::OnSceneCreated begin | The window scene creation starts. |
| -| JsUIAbility::OnSceneCreated end | The window scene creation ends. |
| AbilityRecord::ProcessForegroundAbility; the ProcessForegroundAbility lifecycle starts. | | The lifecycle starts.|
| ServiceInner::UpdateAbilityState | -| The application foregrounding scheduling is initiated first.|
| AppRunningRecord::ScheduleForegroundRunning | -| The application foregrounding is scheduled.|
| AppScheduler::ScheduleForegroundApplication | -| The application foregrounding is scheduled.|
| -| ScheduleForegroundApplication | The application receives the scheduling.|
| -| HandleForegroundApplication | The main thread executes scheduling.|
| AppMgrService::AppForegrounded | -| The application foregrounding is complete.|
| ServiceInner::AppForegrounded | -| The application foregrounding is complete.|
| -| AbilityThread::ScheduleAbilityTransaction | The application receives the ability foregrounding scheduling.|
| -| AbilityThread::HandleAbilityTransaction | The main thread executes ability foregrounding scheduling.|
| -| JsUIAbility::OnStart begin | The **onCreate** lifecycle starts.|
| -| JsUIAbility::OnStart end | The **onCreate** lifecycle ends.|
| -| JsUIAbility::OnSceneCreated begin | The window scene creation starts.|
| -| JsUIAbility::OnSceneCreated end | The window scene creation ends.|
| -| JsUIAbility::OnWillForeground begin | -|
| -| JsUIAbility::OnWillForeground end |- |
| -| JsUIAbility::WindowScene::GoForeground begin | The window API is called to execute **goForeground**.|
| -| UIAbilityImpl::WindowLifeCycleImpl::AfterForeground | The callback after the window migration. |
| -| JsUIAbility::OnForeground begin | The **onForeground** lifecycle starts.|
| -| JsUIAbility::OnForeground end | The **onForeground** lifecycle ends.|
| -| | The foreground lifecycle ends after both the window callback and **onForeground** are complete. |
| -| JsUIAbility::WindowScene::GoForeground begin | The window API is called to execute **goForeground**.|
| -| UIAbilityImpl::WindowLifeCycleImpl::AfterForeground | Calledback after the window is in the foreground.|
| -| JsUIAbility::OnForeground begin | The **onForeground** lifecycle starts.|
| -| JsUIAbility::OnForeground end | The **onForeground** lifecycle ends.|
| -| | After the window callback and **onForeground** are complete, the foreground lifecycle ends.|
You can analyze other log information by referring to [Log Specifications](#log-specifications). Note that the main thread is suspended during lifecycle switching in most cases. You can compare the stack and BinderCatcher information in the two event logs.
appfreeze: com.samples.freezedebug APP_INPUT_BLOCK at 20251129123745
Wait Event(430) to be marked exceed 8000ms, lastDispatchEvent(430), lastProcessEvent(429), lastMarkedEvent(428)
DisplayPowerInfo:powerState:AWAKE
...
```
Since API version 22, when an **APP_INPUT_BLOCK** fault occurs, the log will output a timeout event (**Wait Event**) for multi-mode input (including mouse, keyboard, touchpad, and touchscreen). The event information includes the event ID, event detection timeout threshold, and previous event ID.
Event detection timeout threshold: 8000 ms for the log version and 5000 ms for the nolog version.
Previous events: **lastDispatchEvent** indicates the event dispatched last time; **lastProcessEvent** indicates the event processed last time; **lastMarkedEvent** indicates the event marked last time.
In the preceding example, the last dispatched event is **430**, the last processed event is **429**, and the last marked event is **428**, indicating that the event 430 has been dispatched and the processing times out for 8000 ms. This log can be used to determine the **APP_INPUT_BLOCK** event and help analyze the problem.
## Enhanced AppFreeze Logs
Since API version 21, enhanced AppFreeze logs can be obtained. In these logs, the running loads of the device and main thread are collected, and multiple call stacks of the main thread are captured to help you accurately analyze the cause. Compared with the original logs, the enhanced AppFreeze logs address the following issues:
Since API version 21, enhanced AppFreeze logs can be obtained. In these logs, the running loads of the device and main thread are collected, and multiple call stacks of the main thread are captured to help you analyze the cause. Compared with the original logs, the enhanced AppFreeze logs address the following issues:
1. It is difficult to locate the main thread hotspot during the fault.
@@ -533,7 +584,7 @@ The following table lists the stack information fields in enhanced logs.
### Enhanced Log Specifications
The following describes the common enhanced AppFreeze log specifications:
The following describes the common enhanced AppFreeze log specifications: You can use the [clustering script](#clustering-script) to obtain key information of the main thread stack, improving the efficiency and accuracy of fault locating.
#05 at anonymous (sample|sample|1.0.0|src/main/ets/pages/Index.ts:381:36)
.......
```
**Native Stack Frame Content**
For details, see the call stack frame description in [Log Specification of C++ Crash Common Faults](./cppcrash-guidelines.md#common-faults).
**JS Hybrid Stack Frame Content**
For details, see [JS Crash Exception Code Call Stack Formats](./jscrash-guidelines.md#exception-code-call-stack-formats).
### Clustering Rules for Enhanced Logs
**Clustering Rules**
In a log file that contains multiple application main thread stacks (for example, 10 stacks), perform the following operations on each sampling stack:
1. Filter out the system stack.
Filter out system stack frames (for example, **/system/lib/...** and **ld-musl**) as required. Example of the system stack frame format:
```text
# 00 pc 000e8400 /system/lib/ld-musl-arm.so.1(raise+176)(a40044d0acb68107cfc4adb5049c0725)
```
2. Retain the service stack.
Retain service stack frames (starting with **at** or containing **/data/storage**). JS stack frames are considered as service stack frames (from application code) by default. Example of the service stack frame format:
```text
at onPageShow har1 (har1/src/main/ets/pages/Index.ets:7:13)
```
3. Standardize stack frames.
Define the content of the standard stack frame, remove variable information (such as the line number, byte offset, and build ID), and retain the key information for clustering as required.
Perform the following cleaning operations on each service stack frame:
(1) Native stack frame standardization
| Original Stack Frame Content| Standardized Stack Frame Content|
| ------------- | ---------------- |
| # 01 pc 00006e95 /data/crasher_cpp(DfxCrasher::RaiseSegmentFaultException()+92)(d6cead5be17c9bb7eee2a9b4df4b7626) | /data/crasher_cpp(DfxCrasher::RaiseSegmentFaultException()+92) |
Steps:
a. Extract the function signature (including the class name, function name, and parameters in the brackets).
b. Ignore the PC offset and build ID.
c. Retain the complete function signature (including **const** and parameter types, if parsed in logs).
(2) JS stack frame standardization
| Original Stack Frame Content| Standardized Stack Frame Content|
| ------------- |---------------- |
| # 00 at onPageShow (entry\|har1\|1.0.0\|src/main/ets/pages/Index.ts:7:13) | onPageShow (entry\|har1\|1.0.0\|src/main/ets/pages/Index.ts:7:13) |
Steps:
a. Remove the line number.
b. Retain the function name (for example, **onPageShow**).
c. Retain the file path (for example, **src/main/ets/pages/Index.ts**).
d. Generate a standardized service call stack sequence for subsequent cluster analysis.
4. Generate cluster features.
|Original Sampling Stack|Final Cluster Features (Calling Sequence from Top to Bottom)|
| ----------- |-------------- |
| # 00 pc 000e8400 /system/lib/ld-musl-arm.so.1(raise+176)(a40044d0...)<br># 01 pc 00006e95 /data/crasher_cpp(DfxCrasher::RaiseSegmentFaultException()+92)(d6ce...)<br># 02 pc 00008909 /data/crasher_cpp(DfxCrasher::ParseAndDoCrash(char const*) const+612)(d6ce...)<br># 03 at onPageShow (entry\|har1\|1.0.0\|src/main/ets/pages/Index.ts:7:13) | /data/crasher_cpp(DfxCrasher::RaiseSegmentFaultException()+92)<br>/data/crasher_cpp(DfxCrasher::ParseAndDoCrash(char const*) const+612)<br>at onPageShow (entry\|har1\|1.0.0\|src/main/ets/pages/Index.ts:7:13) |
Cluster all sampling stacks based on cluster features.
### Clustering Script
This script is used only for [appfreeze enhanced logs](#enhanced-log-specifications). When the log content is too long and the main thread stack is repeated for multiple times, this script is used to extract service stack clustering information (service stack content, total number of occurrences, and typical complete stack) to quickly locate faults.
1. Script functionalities
This script is used to process .zip log files in a specified folder in batches. Perform the following steps:
(1) Read the sampling stack files from all .zip files in the input folder.
(2) Automatically decompress, parse, and convert the files one by one.
(3) Output the processing result to the specified folder.
2. Running method
```
get_all_result(input_dir: str, output_dir: str)
```
| Parameter| Mandatory| Type| Description|
|----|----|----|----|
| input_dir |Yes| String| Path of the input folder, which must contain several .zip log files.|
| output_dir |Yes| String| Path of the output folder. The script writes the processing result to this directory.|
Example:
```
get_all_result(r"D:\log\input", r"D:\log\output")
```
3. Input requirements
The **input_dir** directory must contain several.zip files.
The file name is not limited. The file can be a nested structure (the script can support .zip files in .zip files).
The .zip file must contain sampling stack log files.
4. Output description
The script generates the processing result in **output_dir**, for example:
```
output_dir/
├─stack_summary.txt
├─ Service stack clustering .txt
└─ Service stack clustering .xlsx
```
The output type depends on the script logic (for example, decompressed file, converted file, summary text, JSON, or CSV).
5. Preparations before running
Ensure that the local host or deployment environment meets the following requirements:
(1) Python 3.x has been installed.
(2) Script dependencies (such as **os**, **zipfile**, and **pandas**) have been installed.
(3) If **output_dir** does not exist, the script will be automatically created. (If the script does not support automatic creation, create the directory in advance.)
(4) This script cannot be executed in DevEco Studio. Run it in the Python environment.
6. Clustering script source code
``` Python
import re
from collections import Counter, defaultdict
import os
import pandas as pd
import zipfile
import glob
from pathlib import Path
# Log directory
log_dir = r"D:\log\input" # Change it to your log directory.
| HiTraceId | HiTraceChain ID.| 20 | No| This field is displayed when the HiTraceChain functionality is enabled for the process. For details, see [HiTraceId](../reference/apis-performance-analysis-kit/capi-trace-h.md).|
| HiTraceId | HiTraceChain ID.| 20 | No| This field is displayed when the HiTraceChain functionality is enabled for the process. For details, see [HiTraceId](../reference/apis-performance-analysis-kit/capi-hitrace-hitraceid.md).|
| Process name | Name of the faulty process.| 8 | Yes| - |
| Process life time | Lifetime of the faulty process.| 8 | Yes| - |
| Process Memory(kB) | Memory usage of the faulty process.| 20 | Yes| - |
@@ -244,21 +244,21 @@ The following describes the common crash log specifications and other log specif
HiTraceId:a92ab1c7eae68fa <- HiTrace ID. (Optional. If the process does not have HiTraceId, it is not printed.)
Process name:./crasher_cpp <- Process name.
Process life time:1s <- Process life time.
Process Memory(kB): 11902(Rss) <- Memory used by the process.
Device Memory(kB): Total 1935820, Free 516244, Available 1205608 <- Device memory status (optional).
Reason:Signal:SIGSEGV(SI_TKILL)@0x000027e0 from:10208:0 <- Fault cause. For details, see the signal value description.
Fault thread info: <- Faulty thread information
Tid:10208, Name:crasher_cpp <- ID and name of the faulty thread
Fault thread info: <- Faulty thread information.
Tid:10208, Name:crasher_cpp <- ID and name of the faulty thread.
#00 pc 000e8400 /system/lib/ld-musl-arm.so.1(raise+176)(a40044d0acb68107cfc4adb5049c0725) <- Call stack. The call sequence is #06->#05->...->#00, and the crash occurs in the functions of #00.
#01 pc 00006e95 /data/crasher_cpp(DfxCrasher::RaiseSegmentFaultException()+92)(d6cead5be17c9bb7eee2a9b4df4b7626)
#02 pc 00008909 /data/crasher_cpp(DfxCrasher::ParseAndDoCrash(char const*) const+612)(d6cead5be17c9bb7eee2a9b4df4b7626)
@@ -266,20 +266,20 @@ Tid:10208, Name:crasher_cpp <- ID and name of the faulty thread
#04 pc 00073370 /system/lib/ld-musl-arm.so.1(libc_start_main_stage2+72)(a40044d0acb68107cfc4adb5049c0725)
#05 pc 00005ad8 /data/crasher_cpp(_start_c+84)(d6cead5be17c9bb7eee2a9b4df4b7626)
#06 pc 00005a7c /data/crasher_cpp(d6cead5be17c9bb7eee2a9b4df4b7626)
cpsr:20870010 <- Value of status register (cpsr for the ARM32 architecture and pstate and esr for the AArch64 architecture)
Other thread info: <- Other thread information
Tid:10209, Name:crasher_cpp <- Thread ID, thread name
#00 pc 00116974 /system/lib/ld-musl-arm.so.1(sleep+132)(a40044d0acb68107cfc4adb5049c0725) <- Call stack
cpsr:20870010 <- Value of status register (cpsr for the ARM32 architecture and pstate and esr for the AArch64 architecture).
Other thread info: <- Other thread information.
Tid:10209, Name:crasher_cpp <- Thread ID and thread name.
#00 pc 00116974 /system/lib/ld-musl-arm.so.1(sleep+132)(a40044d0acb68107cfc4adb5049c0725) <- Call stack.
#01 pc 0000a137 /data/crasher_cpp(void* std::__h::__thread_proxy[abi:v15004]<std::__h::tuple<std::__h::unique_ptr<std::__h::__thread_struct, std::__h::default_delete<std::__h::__thread_struct>>, DfxCrasher::MultiThreadCrash()::$_1>>(void*)+122)(d6cead5be17c9bb7eee2a9b4df4b7626)
#02 pc 00109104 /system/lib/ld-musl-arm.so.1(start+248)(a40044d0acb68107cfc4adb5049c0725)
#03 pc 00074134 /system/lib/ld-musl-arm.so.1(a40044d0acb68107cfc4adb5049c0725)
Memory near registers: <- Memory values near the address (which must be in valid memory) of the register at the fault site. The content in the brackets indicates the memory segment where the address in the register is located.
r1([stack]): <- Memory value near the address of the r1 register at the fault site
r1([stack]): <- Memory value near the address of the r1 register at the fault site.
### Application Crash Log Configured by HiAppEvent
The system provides a common crash log generation functionality. To meet personalized requirements of some applications on the crash log content, HiAppEvent provides the [setEventConfig](hiappevent-watcher-crash-events.md#customizing-crash-log-specifications) API to set crash log configuration parameters. The following is the core content of a 32-bit system crash log archived by DevEco Studio in FaultLog:
The system provides a common crash log generation functionality. To meet personalized requirements of some applications on the crash log content, HiAppEvent provides the [setEventConfig](hiappevent-watcher-crash-events.md#customizing-crash-log-specifications) API to set crash log configuration parameters since API version 20. The following is the core content of a 32-bit system crash log archived by DevEco Studio in FaultLog:
| src | Used to specify the path of the application installation package. You can install [HAP](../quick-start/hap-package.md) and inter-application [HSP](../quick-start/in-app-hsp.md).|
| src | Used to specify the path of the application installation package. You can install [HAP](../quick-start/hap-package.md) and inter-application [HSP](../quick-start/in-app-hsp.md).|
| -cwd | Modifies the working directory.<br>This parameter is used to switch the **src** directory to the specified path during application installation. For example, when the new application is **test.hap** and the directory is **C:\\**, the actual installation file path is **C:\\test.hap**. If **-cwd "D:\\"** is executed, the actual installation file path is **D:\\test.hap**.|
| -r | Used to overwrite an existing HAP or HSP file. This parameter is optional. This parameter is not specified by default, indicating that the existing file will be overwritten.|
| -s | Used to specify the path where the inter-application HSP is to be installed. This parameter is mandatory for installing the application HSP and optional in other scenarios. Each directory can contain only one HSP file.|
| -w | Used to wait for a specified time before installing a HAP. The minimum waiting time is 180s, and the maximum waiting time is 600s. The default waiting time is 180s. This parameter is optional.|
| -u | Used to specify the [user](../tools/bm-tool.md#userid). By default, the application is installed for the current active user. This parameter is optional.|
| -p | Used to specify the path of the HAP file. This parameter is optional. If multiple HAPs are required, you can specify the folder path of the HAPs.|
| -p | Used to specify the path of the HAP file. This parameter is optional. If multiple HAPs are required, you can specify the folder paths of the HAPs.|
| -h | Used to display the help information about the [install command](../tools/bm-tool.md#install) of the bm module. This parameter is optional.|
**Return value**
@@ -698,7 +698,7 @@ AppMod finish
The [uninstall command](../tools/bm-tool.md#uninstall) is integrated into the bm module on the device, which simplifies the uninstallation process. You can run the command on the PC to uninstall applications. Run the following commands:
| -n | Used to uninstall an application with a specified bundle name. This parameter is optional.|
| -m | Used to specify the name of an application module to be uninstalled. This parameter is optional. By default, all modules are uninstalled.|
| -k | Used to uninstall an application with or without retaining the application data. This parameter is optional. By default, the application data is deleted along the uninstall.|
| -s | Used to uninstall an HSP. This parameter is mandatory only for the HSP uninstallation.|
| -v | Used to uninstall an HSP of a given version number. This parameter is optional. By default, all HSPs with the specified bundle name are uninstalled.|
| -u | Used to specify the [user](../tools/bm-tool.md#userid). By default, the application is uninstalled for the current active user. This parameter is optional.|
| -h | Used to display the help information about the [uninstall command](../tools/bm-tool.md#uninstall) of the bm module. This parameter is optional.|
| [Info]App uninstall path: msg:uninstall bundle successfully.<br>AppMod finish. | The uninstallation is successful.|
| Reason why the uninstallation fails.| The uninstallation failed.|
| Error information.| The uninstallation fails.|
**Usage**
> **NOTE**
>
> When the **uninstall** command and bm module parameters are executed, the **-m**, **-v**, and **-u** parameters (which require values) must be enclosed in quotes along with their values, such as **"-m entry"**, **"-v 100001"**, and **"-u 100"**, to prevent parameter parsing errors that could cause command execution to fail.
# Uninstall the com.ohos.example file (-m is supported by the uninstall command of the bm module, which specifies the module of the application to be uninstalled).
# Uninstall the com.ohos.example file (-k is supported by the uninstall command of the bm module, which is used to save application data during uninstallation).
# Uninstall the com.ohos.example file (-v is supported by the uninstall command of the bm module, which specifies the version number of the shared package).
| fport [IP:port] [IP:port] | Sets up a local port forwarding, which forwards data from a local port to a remote port. The port number ranges from 1 to 65535.|
| rport [IP:port] [IP:port] | Sets up a remote port forwarding, which forwards data from a remote port to a local port. The port number ranges from 1024 to 65535.|
| fport rm [IP:port] [IP:port] | Deletes a port forwarding task.|
| fport ls | Displays all port forwarding tasks.|
| fport localnode remotenode | Sets a local port forwarding, which listens for requests from the local node and forwards the requests to the remote node. The task format is **<Forwarding type>:<Forwarding port>**, for example, **tcp:1234**.|
| rport remotenode localnode | Sets a remote port forwarding, which listens for requests from the remote node and forwards the requests to the local node. The task format is **<Forwarding type>:<Forwarding port>**, for example, **tcp:1234**.|
| fport rm taskstr | Deletes a port forwarding task.|
> **NOTE**
>
> Port forwarding type supported by the computer: TCP.
>
> Port forwarding type supported by the device: TCP, dev, localabstract, localfilesystem, jdwp, ark.
> Port forwarding type supported by the device: TCP, dev, localabstract, localreserved, localfilesystem, jdwp, ark.
### Querying the Port Forwarding Task List
Run the following commands:
Query all local and remote port forwarding tasks.
```shell
hdc fport ls
@@ -896,15 +874,16 @@ hdc fport ls
```shell
$ hdc fport ls
[Empty]
connect-key tcp:2080 tcp:2345 [Reverse]
connect-key tcp:1234 tcp:1080 [Forward]
```
### Creating a Local Port Forwarding
Set up a local port forwarding, which forwards data from a local port to a remote port.
Set a local port forwarding, which forwards data from the local node to the remote node.
> In the local port forwarding, if the local port uses TCP, the specified port is **port**, and the **-e** parameter is used when the service process is started, the local host listens for the port of the IP address specified by the **-e** parameter. If the **-e** parameter is not used when the server is started, the local host listens for **127.0.0.1:port**.
> When creating a local port forwarding task, the PC uses the TCP protocol and the specified **port**. By default, **127.0.0.1:port** is listened for. If the **-e** parameter is used to specify the IP address of the host that to be listened when the service process starts, the PC listens for the **IP:port** specified by **-e**.
### Creating a Remote Port Forwarding
@@ -933,7 +913,7 @@ Forwardport result:OK
Set up a remote port forwarding, which forwards data from a remote port to a local port.
```shell
hdc rport [IP:port] [IP:port]
hdc rport remotenode localnode
```
**Return value**
@@ -954,17 +934,21 @@ Forwardport result:OK
### Deleting a Port Forwarding Task
Delete a specified port forwarding task.
Delete a specified local port forwarding task or remote port forwarding task.
```shell
hdc fport rm [IP:port][IP:port]
hdc fport rm taskstr
```
> **NOTE**
>
> **taskstr** specifies the local or remote port forwarding task to be deleted. You are advised to run the **hdc fport ls** command to query the task and then delete it.
**Parameters**
| Parameter| Description|
| -------- | -------- |
| IP:port | Port forwarding task, in the format of **tcp:XXXX tcp:XXXX**.|
| taskstr | Port forwarding task, in the format of **tcp:XXXX tcp:XXXX**.|
**Return value**
@@ -1455,7 +1439,7 @@ The collected logs are stored in the following path.
| OS| Path| Remarks|
| -------- | -------- | -------- |
| Windows | %temp%\ | Example: **C:\\Users\Username\AppData\Local\Temp**.<br>Replace *Username* with the actual one.|
| Linux | /tmp/ | |
| Linux | /tmp/ | - |
| macOS| $TMPDIR/ | You can run the **echo $TMPDIR** command to view the actual path, and **cd $TMPDIR** to go to the corresponding directory.|
The log file types are as follows.
@@ -1465,7 +1449,7 @@ The log file types are as follows.
| Real-time log| hdc.log | Records server logs in real time.| Each time the hdc server is restarted, the original log is renamed and a new **hdc.log** is recorded.|
| Temporary historical log| hdc-%Y%m%d-%H%M%S.log | Dumps intermediate files generated during historical log archiving.| For example, if the time is 16:18:57.921 on September 19, 2024, the time format is **20240919-161857921**, and the name of the generated temporary log file is **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 temporary name of a historical log file is **hdc-20240919-161857921.log**, the name of the corresponding archived historical log file is **hdc-20240919-161857921.log.tgz**. After the 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.| |
| Temporary real-time log| .hdc.cache.log | Records temporary caches generated by real-time logs.| - |
### Device Logs
@@ -1504,9 +1488,9 @@ Used to set whether to enable the heartbeat functionality for the server and dae
After the server and daemon are started, they send heartbeat packets to each other and record the heartbeat packets in hdc logs for checking the device connection status.
When the environment variable OHOS_HDC_HEARTBEAT is set to **1** for the server, its heartbeat functionality is disabled. When the device is connected to the PC, the server notifies the daemon that the heartbeat functionality is disabled and does not send heartbeat packets to each other.
When the environment variable *OHOS_HDC_HEARTBEAT* is set to **1** for the server, its heartbeat functionality is disabled. When the device is connected to the PC, the server notifies the daemon that the heartbeat functionality is disabled and does not send heartbeat packets to each other.
When **OHOS_HDC_HEARTBEAT** is set to other values, the heartbeat functionality is enabled.
When *OHOS_HDC_HEARTBEAT* is set to other values, the heartbeat functionality is enabled.
### OHOS_HDC_CMD_RECORD
@@ -1523,8 +1507,8 @@ The recording log files are stored in the following paths:
| OS| Path| Remarks|
| -------- | -------- | -------- |
| Windows | %temp%\hdc_cmd\ | Example: **C:\\Users\Username\AppData\Local\Temp\hdc_cmd\<br/>** (Replace the user name with the actual one.)|
@@ -13,7 +13,7 @@ For details, see [Application Killed Event Overview](./hiappevent-watcher-app-ki
## 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/capi-hiappevent-h.md).
For details about how to use the APIs (such as parameter usage restrictions and value ranges), see [HiAppEvent](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md).
@@ -189,7 +189,7 @@ To ensure that event callbacks can be successfully received in the development p
}
```
8. In DevEco Studio, click the **Run** button to run the project. Then, click the **testHiCollieTimerNdk** button to trigger a task execution timeout event.
8. In DevEco Studio, click the **Run** button to run the project. Then, click the **TestHiCollieTimerNdk** button to trigger a task execution timeout event.
@@ -832,7 +832,7 @@ The fields in the I/O information are described as follows:
- **write_bytes**: number of bytes written by the process to the file system and network since it starts, in bytes.
- **cancelled_write_bytes**: number of bytes that are not written due to write cancellation since the process starts, in bytes. Generally, the value of this field is 0 unless an error occurs when data is written to the disk or the write operation is interrupted.
- **cancelled_write_bytes**: number of bytes that are not written due to write cancellation since the process starts, in bytes. Generally, the value of this field is 0 unless an error occurs when data is written to the disk or the write operation is interrupted.
@@ -131,7 +131,7 @@ See 'hiperf help [command]' for more information on a specific command.
1. Count the **1745** and **1910** processes for 10 seconds.
```
```shell
$ hiperf stat -d 10 -p 1745,1910
Profiling duration is 10.000 seconds.
Start Profiling...
@@ -150,7 +150,7 @@ See 'hiperf help [command]' for more information on a specific command.
2. Count processes **1745** and **1910** for **10** seconds, with event types set to **hw-cpu-cycles**, **hw-instructions**, and **sw-task-clock**, and a print interval of **3000** ms.
@@ -176,7 +176,7 @@ See 'hiperf help [command]' for more information on a specific command.
3. Count the process **1910** for **3** seconds, with the event types to **hw-cpu-cycles** and **hw-instructions**, and print detailed information.
```
```shell
$ hiperf stat -d 3 -p 1910 -e hw-cpu-cycles,hw-instructions --verbose
Profiling duration is 3.000 seconds.
Start Profiling...
@@ -197,30 +197,6 @@ See 'hiperf help [command]' for more information on a specific command.
```
## Debug-Type Applications
> **NOTE**
>
> The **hiperf record/stat -p [pid]** command should be used for applications signed by the debug certificate.
>
> Run the **hdc shell "bm dump -n bundlename | grep appProvisionType"** command to check whether the application specified in the command is a debug-type application. The expected output is **"appProvisionType": "debug"**.
>
> For example, run the following command to check the bundle name **com.example.myapplication**:
> If the application is a debug-type application, the following information is displayed:
>
> ```shell
> "appProvisionType": "debug",
> ```
>
> To build a debug-type application, you need to use a debug certificate for signature. For details about how to request and use the debug certificate, see [Requesting a Debug Certificate](https://developer.huawei.com/consumer/en/doc/app/agc-help-add-debugcert-0000001914263178).
## list
Displays the performance event types supported by the system, which can be used as parameters of the **-e** option in the **record** and **stat** commands.
@@ -238,14 +214,14 @@ Displays the performance event types supported by the system, which can be used
**Example**
```
```shell
Usage: hiperf list [event type name]
```
Query the supported hardware event types.
```
```shell
$ hiperf list hw
event not support hw-ref-cpu-cycles
@@ -266,6 +242,10 @@ Supported events for hardware:
Collects the performance data of a specified process or application, including the CPU cycle, number of instructions, and function calls, and saves the sampling data to a specified file. (For the default path, run the **hiperf record -h/--help** command to view the description of the **-o** parameter.)
> **NOTE**
>
> The process collected by the command must be that of a [debug-type application](hiperf.md#what-should-i-do-if-hiperf-fails-to-collect-applications-without-the-debug-certificate-signature).
**Parameters of the record command**
<!--RP1-->
@@ -313,19 +293,19 @@ Collects the performance data of a specified process or application, including t
| -a | Collects the device performance data.|
| --exclude-hiperf | Excludes the performance data of the hiperf process. This parameter must be used together with **-a**.|
| --exclude-process | Specifies the process name not to collect. This parameter must be used together with **-a**.|
| --pipe_input | Establishes a command input pipe when the client process calls hiperf. For details about how to use this capability, see [hiperf](https://gitcode.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hiperf.md). This parameter serves no practical purpose in application development and can be safely ignored.|
| --pipe_output | Establishes an output pipe when the client process calls hiperf. For details about how to use this capability, see [hiperf](https://gitcode.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hiperf.md). This parameter serves no practical purpose in application development and can be safely ignored.|
| --pipe_input | Establishes a command input pipe when the client process calls hiperf in device development. For details about how to use this capability, see [hiperf](https://gitcode.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hiperf.md). This parameter is not required for application development.|
| --pipe_output | Establishes an output pipe when the client process calls hiperf in device development. For details about how to use this capability, see [hiperf](https://gitcode.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hiperf.md). This parameter is not required for application development.|
<!--RP1End-->
**Example**
```
```shell
Usage: hiperf record [options] [command [command-args]]
```
Sample the process 267 for 10 seconds and use **dwarf** to unwind the stack.
Monitors the specified application and periodically prints the values of performance counters.
> **NOTE**
>
> The process collected by the command must be that of a [debug-type application](hiperf.md#what-should-i-do-if-hiperf-fails-to-collect-applications-without-the-debug-certificate-signature).
**Parameters of the stat command**
<!--RP2-->
@@ -361,13 +345,13 @@ Monitors the specified application and periodically prints the values of perform
**Example**
```
```shell
hiperf stat [options] [command [command-args]]
```
Run the **stat** command to monitor the performance data of the process **2349** that runs on CPU 0 for three seconds.
```
```shell
$ hiperf stat -p 1745 -d 3 -c 0
```
@@ -393,13 +377,13 @@ Converts performance data files in different formats (for example, **perf.data**
**Example**
```
```shell
Usage: hiperf dump [option] \<filename\>
```
Run the **dump** command to read the **/data/local/tmp/perf.data** file and export it to the **/data/local/tmp/perf.dump** file.
### What should I do if hiperf fails to collect applications without the debug certificate signature
**Symptom**
Only applications with the debug certificate signature can be collected. The message "only support debug application" is displayed.
**Possible Causes and Solution**
**Causes**
The application does not have the debug certificate signature.
**Solution**
When the **hiperf record/stat -p [pid]** command is used, the process to be collected must be that of an application signed with the debug certificate.
Run the **hdc shell "bm dump -n bundlename | grep appProvisionType"** command to check whether the application specified in the command is a debug-type application. The expected output is **"appProvisionType": "debug"**.
For example, run the following command to check the bundle name **com.example.myapplication**:
If the application is a debug-type application, the following information is displayed:
```shell
"appProvisionType": "debug",
```
To build a debug-type application, you need to use a debug certificate for signature. For details about how to request and use the debug certificate, see [Requesting a Debug Certificate](https://developer.huawei.com/consumer/en/doc/app/agc-help-add-debugcert-0000001914263178).
hiprofiler provides the performance profiling capabilities for you to analyze memory and performance issues.
Its overall architecture comprises the profiling data display page on the PC and performance profiling service on the device. The services on the PC and device use the C/S model, and the profiling data on the PC is displayed on the [DevEco Studio](https://cbg.huawei.com/#/group/ipd/DevEcoToolsList) and [SmartPerf](https://gitcode.com/openharmony/developtools_smartperf_host) web page. The device program consists of multiple parts that run in the system environment. The **hiprofilerd** process communicates with DevEco Studio to provide profiling services. The device also contains the CLI tool (**hiprofiler_cmd**) and data collection process (**hiprofiler_plugins**). Based on the Producer-Consumer model, the profiling service controls the data collection process to obtain profiling data and sends the data to DevEco Studio. Currently, plugins such as nativehook, CPU, ftrace, GPU, hiperf, xpower, and memory have been implemented, providing comprehensive profiling capabilities for CPU, GPU, memory, and power consumption.
The overall architecture includes the PC and device. The main part is the data display page on the PC and the performance tuning service on the device. The services on the PC and device use the C/S model, and the profiling data on the PC is displayed on the [DevEco Studio](https://cbg.huawei.com/#/group/ipd/DevEcoToolsList) and [SmartPerf](https://gitcode.com/openharmony/developtools_smartperf_host) web page. The device program consists of multiple parts that run in the system environment. The **hiprofilerd** process communicates with DevEco Studio to provide profiling services. The device also contains the CLI tool (**hiprofiler_cmd**) and data collection process (**hiprofiler_plugins**). Based on the Producer-Consumer model, the profiling service controls the data collection process to obtain profiling data and sends the data to DevEco Studio. Currently, plugins such as nativehook, CPU, ftrace, GPU, hiperf, xpower, and memory have been implemented, providing comprehensive profiling capabilities for CPU, GPU, memory, and power consumption.
@@ -134,7 +134,7 @@ Download the generated trace file to the local PC by running the **hdc file recv
> **NOTE**
>
> Run the **hdc shell "bm dump -n bundlename | grep appProvisionType"** command to check whether the application specified in the command can be debugged. The expected output is **"appProvisionType": "debug"**.
> Run the **hdc shell "bm dump -n bundlename | grep appProvisionType"** command to check whether the application specified in the command is a debug-type application. The expected output is **"appProvisionType": "debug"**.
For example, run the following command to check the bundle name **com.example.myapplication**:
@@ -169,6 +169,7 @@ Obtains the call stack information of heap memory allocations (by the **malloc**
| malloc_free_matching_interval | int | Matching interval, in seconds. **malloc** and **free** are matched within the interval. If matched, the stack is not flushed to the disk.| Within the matching interval, the allocated and released call stacks are not recorded, reducing the overhead of the stack capture service process. If this parameter is set to a value greater than 0, **statistics_interval** cannot be set to **true**.|
| offline_symbolization | bool | Whether to enable offline symbolization.<br>The value **true** means to enable offline symbolization;<br>the value **false** means the opposite.| When offline symbolization is used, the operation of matching symbols based on IP is performed on SmartPerf, reducing process freezes during profiling. However, since the offline symbol table is written into the trace file, the trace file generated under offline symbolization is larger in size than that under online symbolization.|
| sample_interval | int | Sampling size.| When this parameter is set, the sampling mode is enabled. In sampling mode, malloc allocations smaller than the sampling size are accounted for probabilistically. The larger the call-stack allocation size, the more frequently it occurs and the greater its chance of being sampled.|
| restrace_tag | string | Type of the GPU memory to be captured.| This parameter can be added repeatedly. Currently, this parameter can only be set to **RES_GPU_VK**, **RES_GPU_GLES_BUFFER**, **RES_GPU_GLES_IMAGE**, **RES_GPU_CL_BUFFER**, or **RES_GPU_CL_IMAGE**, which are used to specify the GPU memory allocation stack of Vulkan, OpenGLES, OpenCL, image, and buffer types.<br>Note: This parameter is supported since API version 21.|
**Result analysis**
@@ -354,7 +355,7 @@ This command reads the basic memory statistics of the system. After the command
You can go to **DevEco Studio** -> **Profiler** -> **Allocation** and select **Memory** to use the **memory plug-in** feature of the profiler. The preceding figure shows the process smaps memory information in the selected time range.
You can go to **DevEco Studio** -> **Profiler** -> **Allocation** and select **Memory** to use the **memory plugin** feature of the profiler. The preceding figure shows the process smaps memory information in the selected time range.
### xpower-plugin
@@ -691,7 +692,50 @@ $ hiprofiler_cmd \
CONFIG
```
Capture the GPU memory call stack of a specified process. (The latest smartperf release version is required for parsing files. Download link: [smartperf](https://gitcode.com/openharmony/developtools_smartperf_host/releases).)
```shell
$ hiprofiler_cmd \
-c - \
-t 30 \
-s \
-k \
<<CONFIG
request_id: 1
session_config {
buffers {
pages: 16384
}
}
plugin_configs {
plugin_name: "nativehook"
sample_interval: 5000
config_data {
save_file: false
smb_pages: 16384
max_stack_depth: 20
pid: 11237
string_compressed: true
fp_unwind: true
blocked: true
callframe_compress: true
record_accurately: true
offline_symbolization: true
startup_mode: false
statistics_interval: 10
malloc_disable: true
memtrace_enable: true
restrace_tag: "RES_GPU_VK"
restrace_tag: "RES_GPU_GLES_BUFFER"
restrace_tag: "RES_GPU_GLES_IMAGE"
restrace_tag: "RES_GPU_CL_BUFFER"
js_stack_report: 1
max_js_stack_depth: 10
}
}
CONFIG
```
The **malloc_disable** parameter is used in the command to filter the native heap stack data. If the **restrace_tag** parameter does not contain **RES_GPU_CL_IMAGE**, the GPU memory allocation stack of the OpenCL image type is not captured.
## FAQs
@@ -715,7 +759,7 @@ The captured trace file is empty.
**Possible Causes and Solution**
Check whether the generated file is in the **/data/local/tmp/** directory. If the target path is a folder in **/data/local/tmp**, run the **chmod 777** command on the folder. If the user version uses **nativehook** or **network profiler** to capture a no-debug application, no data can be captured. (For details, see changelog https://gitcode.com/openharmony/docs/pulls/57419.)
Check whether the generated file is in the **/data/local/tmp/** directory. If the target path is a folder in **/data/local/tmp**, run the **chmod 777** command on the folder. If the application captured by the nativehook or network profiler plugin in the user version is not a [debug-type application](#applications-signed-by-the-debug-certificate), no data can be captured.
### What should I do if the profiling data may be inaccurate?
@@ -26,7 +26,7 @@ ArkCompiler runtime captures process exceptions. The fault log generation proces
## Constraints
If an exception is thrown in an asynchronous function, no JS crash will occur. You can observe the exception through [ErrorManager](../reference/apis-ability-kit/js-apis-app-ability-errorManager.md#errormanageronerror).
If an exception is thrown in an asynchronous function, no JS crash will occur. You can observe the exception through [ErrorManager](../reference/apis-ability-kit/js-apis-app-ability-errorManager.md#errormanageronerror). For details about the sample code, see [Exception Handling in Async Functions](../arkts-utils/arkts-runtime-faq.md#exception-handling-in-async-functions).
@@ -47,11 +47,11 @@ Performance Analysis Kit provides a collection of capabilities for improving app
## Features
**Convenient APM System Setup**
**Hassle-free APM System Setup**
- Provides [HiDebug](hidebug-guidelines.md), [HiAppEvent](hiappevent-intro.md) and [HiLog](hilog-guidelines-arkts.md) APIs to build an Application Performance Management (APM) SDK on the device for interconnection with the APM developed by vendors.
- Provides the functionalities of customizing [application events](event-subscription-overview.md#application-events) and subscribing to system events so that you can quickly collect events required for O&M.
- Provides [HiAppEvent system events](event-subscription-overview.md#system-events) and [application events](event-subscription-overview.md#application-events) for subscribing to events (such as crash and application freeze events) triggered during application running, and quickly records and collects event information required for O&M.
**Powerful Exception Detection and Handling Mechanism**
@@ -162,7 +162,7 @@ Include the [lowpower_audio_sink_base.h](../../reference/apis-media-kit/capi-low
## Running the Sample Project
1. Create a project. Download the [sample project](https://gitee.com/harmonyos_samples/guide-snippets/tree/master/MediaKit/LowPowerAVSInk/lowPowerAVSinkSample), and copy its resources to the corresponding directories.
1. Create a project. Download the [sample project](https://gitcode.com/HarmonyOS_Samples/guide-snippets/tree/master/MediaKit/LowPowerAVSInk/lowPowerAVSinkSample), and copy its resources to the corresponding directories.
@@ -56,9 +56,9 @@ The required permissions must be authorized by the user. After adding the permis
**How to Develop**
<!--RP1-->
1. Request the required permissions via the ACL. For details, see [Requesting Restricted Permissions](../../security/AccessToken/declare-permissions-in-acl.md).
<!--RP1End-->
2. [Declare the required permissions in the **module.json5** file](../../security/AccessToken/declare-permissions.md).
3. [Request user authorization](../../security/AccessToken/request-user-authorization.md).
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides APIs for managing data in an RDB store.
Before using the following APIs, you should obtain an **RdbStore** instance by calling the [getRdbStore](arkts-apis-data-relationalStore-f.md#relationalstoregetrdbstore-1) method and then call the corresponding method through the instance.
In addition, use [execute](arkts-apis-data-relationalStore-RdbStore.md#execute12) to initialize the database table structure and related data first, ensuring that the prerequisites for related API calls are met.
> **NOTE**
>
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
```ts
@@ -446,7 +446,7 @@ Inserts a row of data into a table. This API returns the result synchronously. D
| table | string | Yes | Name of the target table. |
| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | Yes | Row of data to insert. |
| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| No | Resolution used to resolve the conflict.<br>Default value: **relationalStore.ConflictResolution.ON_CONFLICT_NONE**.|
| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| No | Resolution used to resolve the conflict.<br>Default value: **relationalStore.ConflictResolution.ON_CONFLICT_NONE**.|
**Return value**
@@ -533,7 +533,7 @@ Inserts a row of Sendable data into a table. This API returns the result synchro
| table | string | Yes | Name of the target table. |
| values | [sendableRelationalStore.ValuesBucket](js-apis-data-sendableRelationalStore.md#valuesbucket) | Yes | Sendable data to insert. |
| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10) | No | Resolution used to resolve the conflict.<br>Default value: **relationalStore.ConflictResolution.ON_CONFLICT_NONE**.|
| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10) | No | Resolution used to resolve the conflict.<br>Default value: **relationalStore.ConflictResolution.ON_CONFLICT_NONE**.|
Inserts data into a table in batches. You can specify a resolution used to resolve the conflict. This API uses a promise to return the result.
Inserts data into a table in batches. You can use the **conflict** parameter to specify [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10). This API uses a promise to return the result.
A maximum of 32766 parameters can be inserted at a time. If the number of parameters exceeds the upper limit, the error code 14800000 is returned. The product of the number of inserted data records and the size of the union of all fields in the inserted data equals the number of parameters.
For example, if the size of the union is 10, a maximum of 3276 data records can be inserted (3276 × 10 = 32760).
Ensure that your application complies with this constraint when calling this API to avoid errors caused by excessive parameters.
Inserts data into a table in batches. You can use the **conflict** parameter to specify [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10).
A maximum of 32766 parameters can be inserted at a time. If the number of parameters exceeds the upper limit, the error code 14800000 is returned. The product of the number of inserted data records and the size of the union of all fields in the inserted data equals the number of parameters.
For example, if the size of the union is 10, a maximum of 3276 data records can be inserted (3276 × 10 = 32760).
Ensure that your application complies with this constraint when calling this API to avoid errors caused by excessive parameters.
| values | [ValuesBucket](arkts-apis-data-relationalStore-t.md#valuesbucket) | Yes | Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.|
| predicates | [RdbPredicates](arkts-apis-data-relationalStore-RdbPredicates.md) | Yes | Update conditions specified by the **RdbPredicates** object. |
| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| No | Resolution used to resolve the conflict.<br>Default value: **relationalStore.ConflictResolution.ON_CONFLICT_NONE**.|
| conflict | [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10)| No | Resolution used to resolve the conflict.<br>Default value: **relationalStore.ConflictResolution.ON_CONFLICT_NONE**.|
**Return value**
@@ -1534,7 +1560,7 @@ Deletes data from the RDB store based on the specified **RdbPredicates** object.
| tables | Array<string> | Yes | Names of the distributed tables to set. |
| type | [DistributedType](arkts-apis-data-relationalStore-e.md#distributedtype10) | No | Distributed type of the tables.<br>Default value: **relationalStore.DistributedType.DISTRIBUTED_DEVICE**.|
| type | [DistributedType](arkts-apis-data-relationalStore-e.md#distributedtype10) | No | Distributed type of the tables.<br>Default value: **relationalStore.DistributedType.DISTRIBUTED_DEVICE**.|
| config | [DistributedConfig](arkts-apis-data-relationalStore-i.md#distributedconfig10) | No | Configuration of the distributed mode. If this parameter is not specified, the value of **autoSync** is **false** by default, which means only manual sync is supported. |
Obtains the distributed table name of a remote device based on the local table name of the device. The distributed table name is required when the RDB store of a remote device is queried.
Obtains the distributed table name of a remote device based on the local table name of the device. The distributed table name is required when the RDB store of a remote device is queried. This API uses a promise to return the result.
> **NOTE**
>
@@ -4516,7 +4542,7 @@ Subscribes to the intra-process or inter-process events of this RDB store. The r
Inserts data into a table with conflict resolutions in batches. You can use the **conflict** parameter to specify [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10). This API uses a promise to return the result.
A maximum of 32766 parameters can be inserted at a time. If the number of parameters exceeds the upper limit, the error code 14800000 is returned. The number of inserted data records multiplied by the size of the union across all fields in the inserted data equals the number of parameters.
A maximum of 32766 parameters can be inserted at a time. If the number of parameters exceeds the upper limit, the error code 14800000 is returned. The product of the number of inserted data records and the size of the union of all fields in the inserted data equals the number of parameters.
For example, if the size of the union is 10, a maximum of 3276 data records can be inserted (3276 × 10 = 32760).
Ensure that you comply with this constraint when calling this API to avoid errors caused by excessive parameters.
Ensure that your application complies with this constraint when calling this API to avoid errors caused by excessive parameters.
Inserts data into a table with conflict resolutions in batches. You can use the **conflict** parameter to specify [ConflictResolution](arkts-apis-data-relationalStore-e.md#conflictresolution10).
A maximum of 32766 parameters can be inserted at a time. If the number of parameters exceeds the upper limit, the error code 14800000 is returned. The number of inserted data records multiplied by the size of the union across all fields in the inserted data equals the number of parameters.
A maximum of 32766 parameters can be inserted at a time. If the number of parameters exceeds the upper limit, the error code 14800000 is returned. The product of the number of inserted data records and the size of the union of all fields in the inserted data equals the number of parameters.
For example, if the size of the union is 10, a maximum of 3276 data records can be inserted (3276 × 10 = 32760).
Ensure that you comply with this constraint when calling this API to avoid errors caused by excessive parameters.
Ensure that your application complies with this constraint when calling this API to avoid errors caused by excessive parameters.
@@ -60,7 +60,7 @@ Represents the asset (such as a document, image, or video).
| path | string | No| No| Path of an asset in the application sandbox.|
| createTime | string | No| No| Time when an asset is created.|
| modifyTime | string | No| No| Time when an asset is last modified.|
| size | string | No| No| Asset size.|
| size | string | No| No| Asset size. In the device-cloud synchronization mechanism, this field is one of the key bases for determining whether an asset is changed. Ensure that the storage format and value logic are consistent across the end-to-end link. It is recommended that all system nodes use the standard processing format (unit: byte; value: a non-negative integer) to avoid synchronization exceptions or misjudgment caused by format differences.|
| status | [AssetStatus](arkts-apis-data-relationalStore-e.md#assetstatus10) | No | Yes | Asset status. <br>Default value: **ASSET_NORMAL**.|
| int | Error code. For details, see [OH_Preferences_ErrCode](capi-oh-preferences-err-code-h.md#oh_preferences_errcode).<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
| int | Returns an error code. For details, see [OH_Preferences_ErrCode](capi-oh-preferences-err-code-h.md#oh_preferences_errcode).<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
### OH_Preferences_GetInt()
@@ -146,7 +146,7 @@ Obtains an integer corresponding to the specified key in a **Preferences** insta
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.|
### OH_Preferences_GetBool()
@@ -173,7 +173,7 @@ Obtains a Boolean value corresponding to the specified key in a **Preferences**
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.|
### OH_Preferences_GetString()
@@ -201,7 +201,7 @@ Obtains a string corresponding to the specified key in a **Preferences** instanc
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_KEY_NOT_FOUND** indicates the specified key does not exist.|
### OH_Preferences_FreeString()
@@ -247,7 +247,7 @@ Sets an integer based on the specified key in a **Preferences** instance.
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
### OH_Preferences_SetBool()
@@ -274,7 +274,7 @@ Sets a Boolean value based on the specified key in a **Preferences** instance.
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
### OH_Preferences_SetString()
@@ -301,7 +301,7 @@ Sets a string based on the specified key in a **Preferences** instance.
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
### OH_Preferences_Delete()
@@ -327,7 +327,7 @@ Deletes the KV data corresponding to the specified key from a **Preferences** in
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
**See**
@@ -360,7 +360,7 @@ Subscribes to data changes of the specified keys. If the value of the specified
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT** indicates a failure in obtaining the data change subscription service.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.<br>**PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT** indicates a failure in obtaining the data change subscription service.|
### OH_Preferences_UnregisterDataObserver()
@@ -389,7 +389,7 @@ Unsubscribes from data changes of the specified keys.
| int | Error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
| int | Returns an error code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.<br>**PREFERENCES_ERROR_STORAGE** indicates the storage is abnormal.<br>**PREFERENCES_ERROR_MALLOC** indicates a failure in memory allocation.|
**See**
@@ -416,4 +416,4 @@ int OH_Preferences_IsStorageTypeSupported(Preferences_StorageType type, bool *is
| int | Operation status code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.|
| int | Returns an operation status code.<br>**PREFERENCES_OK** indicates the operation is successful.<br>**PREFERENCES_ERROR_INVALID_PARAM** indicates invalid parameters are specified.|
| [int (*putText)(OH_VBucket *bucket, const char *field, const char *value)](#puttext) | Puts a char* value into the **OH_VBucket** object in the given column. |
| [int (*putInt64)(OH_VBucket *bucket, const char *field, int64_t value)](#putint64) | Puts an int64_t value into the **OH_VBucket** object in the given column. |
| [int (*putReal)(OH_VBucket *bucket, const char *field, double value)](#putreal) | Puts a double value into the **OH_VBucket** object in the given column. |
| [int (*putBlob)(OH_VBucket *bucket, const char *field, const uint8_t *value, uint32_t size)](#putblob) | Puts a const uint8_t * value into the **OH_VBucket** object in the given column.|
| [int (*putNull)(OH_VBucket *bucket, const char *field)](#putnull) | Puts a null value into the **OH_VBucket** object in the given column. |
| [int (*clear)(OH_VBucket *bucket)](#clear) | Clears an **OH_VBucket** object. |
| [int (*destroy)(OH_VBucket *bucket)](#destroy) | Destroys an **OH_VBucket** object and reclaims the memory occupied. |
| [int (*putText)(OH_VBucket *bucket, const char *field, const char *value)](#puttext) | Puts a char* value into the **OH_VBucket** object in the given column. |
| [int (*putInt64)(OH_VBucket *bucket, const char *field, int64_t value)](#putint64) | Puts an int64_t value into the **OH_VBucket** object in the given column. |
| [int (*putReal)(OH_VBucket *bucket, const char *field, double value)](#putreal) | Puts a double value into the **OH_VBucket** object in the given column. |
| [int (*putBlob)(OH_VBucket *bucket, const char *field, const uint8_t *value, uint32_t size)](#putblob) | Puts a const uint8_t * value into the **OH_VBucket** object in the given column.|
| [int (*putNull)(OH_VBucket *bucket, const char *field)](#putnull) | Puts a null value into the **OH_VBucket** object in the given column. |
| [int (*clear)(OH_VBucket *bucket)](#clear) | Clears an **OH_VBucket** object. |
| [int (*destroy)(OH_VBucket *bucket)](#destroy) | Destroys an **OH_VBucket** object and reclaims the memory occupied. |
@@ -613,7 +613,7 @@ Sets the custom directory of the database.
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.|
### OH_Rdb_SetReadOnly()
@@ -639,7 +639,7 @@ Sets whether the RDB store is in read-only mode.
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.|
### OH_Rdb_SetPlugins()
@@ -666,7 +666,7 @@ Sets the dynamic library with specific capabilities (such as full-text search).
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.|
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.|
### OH_Rdb_IsTokenizerSupported()
@@ -1051,7 +1051,7 @@ Inserts a row of data into the target table and supports conflict resolution.
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_WAL_SIZE_OVER_LIMIT** indicates that the size of the WAL log file exceeds the default value.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_WAL_SIZE_OVER_LIMIT** indicates that the size of the WAL log file exceeds the default value.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
### OH_Rdb_BatchInsert()
@@ -1086,7 +1086,7 @@ Ensure that you comply with this constraint when calling this API to avoid error
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_WAL_SIZE_OVER_LIMIT** indicates that the size of the WAL log file exceeds the default value.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_WAL_SIZE_OVER_LIMIT** indicates that the size of the WAL log file exceeds the default value.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
### OH_Rdb_Update()
@@ -1142,7 +1142,7 @@ Updates data in the database based on specified conditions and supports conflict
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_WAL_SIZE_OVER_LIMIT** indicates that the size of the WAL log file exceeds the default value.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_WAL_SIZE_OVER_LIMIT** indicates that the size of the WAL log file exceeds the default value.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
### OH_Rdb_Delete()
@@ -1254,7 +1254,7 @@ Executes an SQL statement with a return value. This API supports vector stores.
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_WAL_SIZE_OVER_LIMIT** indicates that the size of the WAL log file exceeds the default value.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_WAL_SIZE_OVER_LIMIT** indicates that the size of the WAL log file exceeds the default value.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.|
**See**
@@ -2033,7 +2033,7 @@ Creates a transaction object.
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_DATABASE_BUSY** indicates that the database does not respond.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_CANT_OPEN** indicates an SQLite error: unable to open the database file.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_DATABASE_BUSY** indicates that the database does not respond.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_CANT_OPEN** indicates an SQLite error: unable to open the database file.|
### OH_Rdb_Attach()
@@ -2062,7 +2062,7 @@ Attaches a database file to the database that is currently connected.
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_NOT_SUPPORTED** indicates that the operation is not supported.<br>**RDB_E_DATABASE_BUSY** indicates that the database does not respond.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_NOT_SUPPORTED** indicates that the operation is not supported.<br>**RDB_E_DATABASE_BUSY** indicates that the database does not respond.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
### OH_Rdb_Detach()
@@ -2090,7 +2090,7 @@ Detaches a specified store from the current database.
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_NOT_SUPPORTED** indicates that the operation is not supported.<br>**RDB_E_DATABASE_BUSY** indicates that the database does not respond.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_E_ERROR** indicates a common database error.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_NOT_SUPPORTED** indicates that the operation is not supported.<br>**RDB_E_DATABASE_BUSY** indicates that the database does not respond.<br>**RDB_E_SQLITE_FULL** indicates an SQLite error: the database is full.<br>**RDB_E_SQLITE_CORRUPT** indicates that the database is corrupted.<br>**RDB_E_SQLITE_PERM** indicates an SQLite error: access denied.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_LOCKED** indicates an SQLite error: database table locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.<br>**RDB_E_SQLITE_READONLY** indicates an SQLite error: attempt to write a read-only database.<br>**RDB_E_SQLITE_IOERR** indicates an SQLite: disk I/O error.<br>**RDB_E_SQLITE_TOO_BIG** indicates an SQLite error: TEXT or BLOB exceeds the limit.<br>**RDB_E_SQLITE_MISMATCH** indicates an SQLite error: data types mismatch.<br>**RDB_E_SQLITE_CONSTRAINT** indicates an SQLite error code: SQLite constraint.|
### OH_Rdb_SetLocale()
@@ -2116,4 +2116,4 @@ Sets locale.
| Type| Description|
| -- | -- |
| int | Returns the execution result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_ERR** indicates that the operation fails.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.|
| int | Returns the operation result.<br>**RDB_OK** indicates that the operation is successful.<br>**RDB_ERR** indicates that the operation fails.<br>**RDB_E_INVALID_ARGS** indicates that invalid parameters are specified.<br>**RDB_E_ALREADY_CLOSED** indicates that the database is already closed.<br>**RDB_E_SQLITE_BUSY** indicates an SQLite error: database file locked.<br>**RDB_E_SQLITE_NOMEM** indicates an SQLite: insufficient database memory.|
| const char** | Returns a pointer to the uniform data types obtained.<br>If it is no longer required, use [OH_Utd_DestroyStringList](capi-utd-h.md#oh_utd_destroystringlist) to destroy it. Otherwise, memory leakage occurs.|
| const char** | Returns a pointer to the UTDs obtained.<br>If it is no longer required, use [OH_Utd_DestroyStringList](capi-utd-h.md#oh_utd_destroystringlist) to destroy it. Otherwise, memory leakage occurs.|
| const char** | Returns a double pointer to the uniform data types obtained.<br>If it is no longer required, use [OH_Utd_DestroyStringList](capi-utd-h.md#oh_utd_destroystringlist) to destroy it. Otherwise, memory leakage occurs.|
| const char** | Returns a double pointer to the UTDs obtained.<br>If it is no longer required, use [OH_Utd_DestroyStringList](capi-utd-h.md#oh_utd_destroystringlist) to destroy it. Otherwise, memory leakage occurs.|
| eventId | string | No | No | Event ID. The value **cloud_data_change** indicates cloud data changes. |
| extraData | string | No | No | Data to be transmitted transparently. **extraData** is a JSON string that must contain the **data** field. The **data** field contains information required for a change notification, including the account ID, application name, database name, database type, and database table name. All the fields cannot be empty.
| extraData | string | No | No | Data to be transmitted transparently. **extraData** is a JSON string that must contain the **data** field. The **data** field contains information required for a change notification, including the account ID, application name, database name, database type, and database table name. All the fields cannot be empty. |
@@ -46,7 +46,7 @@ Represents asset (such as a file, image, or video) information. For details, see
| path | string | No | No | Application sandbox path of the asset. |
| createTime | string | No | No | Time when the asset was created. |
| modifyTime | string | No | No | Time when the asset was last modified. |
| size | string | No | No | Size of the asset. |
| size | string | No | No | Size of the asset. Ensurethatthestorageformatandvaluelogicareconsistentacrosstheend-to-endlink. It is recommended that all system nodes use the standard processing format (unit: byte; value: a non-negative integer).|
| status | [AssetStatus](#assetstatus) | No | Yes | Asset status. The default value is **ASSET_NORMAL**.|
@@ -12,7 +12,7 @@ The APIs provided by **DataSharePredicates** correspond to the filter criteria o
**DataSharePredicates** applies to the following scenario:
- It is used as a search criteria when APIs of the [RDB store](js-apis-data-relationalStore-sys.md) and [KV store](js-apis-distributedKVStore-sys.md) are called. In this scenario, use the corresponding predicate based on the database type.
- It is used as the search criteria when APIs of the [RDB store](js-apis-data-relationalStore-sys.md) and [KV store](js-apis-distributedKVStore-sys.md) are called. In this scenario, use the corresponding predicate based on the database type.
> **NOTE**
>
@@ -37,9 +37,9 @@ Provides methods for setting different **DataSharePredicates** objects. This typ
Sets a **DataSharePredicates** object to match the data that is within the specified range, including the start and end values. The data type must be int.
Creates a **DataSharePredicates** object to match the data that is within the specified range, including the start and end values.
Currently, only RDB store supports this predicate.
@@ -422,9 +422,9 @@ Currently, only RDB store supports this predicate.
| field | string | Yes | Column name in the database table.|
| low | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes | The lowest value of the range.|
| high | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes | The highest value of the range.|
| field | string | Yes | Column name in the database table.|
| low | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes | Minimum value of the range to set.<br>If **low** is set to a number, the matching range is specified based on the numeric order.<br>If **low** is set to a string, the matching range is specified based on the lexicographical order.<br>If **low** is set to boolean, the matching range is specified based on the numeric order.|
| high | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes | Maximum value to match the **DataAbilityPredicates**.<br>If **high** is set to a number, the matching range is specified based on the numeric order.<br>If **high** is set to a string, the matching range is specified based on the lexicographical order.<br>If **high** is set to boolean, the matching range is specified based on the numeric order.|
Sets a **DataSharePredicates** object to match the data that is out of the specified range, excluding the start and end values. The data type must be int.
Creates a **DataSharePredicates** object to match the data that is out of the specified range, excluding the start and end values.
Currently, only RDB store supports this predicate.
@@ -455,9 +455,9 @@ Currently, only RDB store supports this predicate.
| field | string | Yes | Column name in the database table.|
| low | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes | The lowest value of the range.|
| high | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes | The highest value of the range.|
| field | string | Yes | Column name in the database table.|
| low | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes | Minimum value of the range to set.<br>If **low** is set to a number, the matching range is specified based on the numeric order.<br>If **low** is set to a string, the matching range is specified based on the lexicographical order.<br>If **low** is set to boolean, the matching range is specified based on the numeric order.|
| high | [ValueType](js-apis-data-valuesBucket.md#valuetype) | Yes | Maximum value to match the **DataAbilityPredicates**.<br>If **high** is set to a number, the matching range is specified based on the numeric order.<br>If **high** is set to a string, the matching range is specified based on the lexicographical order.<br>If **high** is set to boolean, the matching range is specified based on the numeric order.|
@@ -1416,7 +1416,7 @@ Defines type and quantity of the data to load.
type DataLoadHandler = (acceptableInfo?: DataLoadInfo) => UnifiedData | null
Defines a processing function for lazy data loading. The data sender can dynamically generate data based on the information passed by the data receiver to implement more flexible and precise data interaction policies.
Defines a handler for lazy data loading. The data sender can dynamically generate data based on the information passed by the data receiver to implement more flexible and precise data interaction policies.
**Atomic service API**: This API can be used in atomic services since API version 20.
@@ -1446,7 +1446,7 @@ Defines the data loading policy for the data sender in the lazy loading scenario
| Name | Type | Read-Only| Optional| Description |
| nullable | boolean | No | No | Whether the field can be null. The value **true** means the node field can be null; the value **false** means the opposite.|
| default | string | No | No | Default value of **FieldNode**. |
| default | string | No | No | Default value of **FieldNode**. The value of **default** must be a string literal that can be parsed by the type. Ensure that the value type is the same as **type**.|
| type | number | No | No | **FieldNode** data type, which is a value of [ValueType](#valuetype). Currently, the BYTE_ARRAY type is not supported. Using this type may cause a failure in calling [getKVStore](#getkvstore).|
### constructor
constructor(name: string)
A constructor used to create a **FieldNode** instance with a string field.
Defines a constructor used to create a **FieldNode** instance with a string field.
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name | Type| Mandatory | Description |
@@ -1559,6 +1565,12 @@ Creates a **Query** object to match the specified field whose value is not equal
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name | Type| Mandatory | Description |
@@ -1606,6 +1618,12 @@ Creates a **Query** object to match the specified field whose value is greater t
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
@@ -1700,6 +1724,12 @@ Creates a **Query** object to match the specified field whose value is greater t
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
@@ -1748,6 +1778,12 @@ Creates a **Query** object to match the specified field whose value is less than
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
@@ -1796,6 +1832,12 @@ Creates a **Query** object to match the specified field whose value is **null**.
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name| Type| Mandatory| Description |
@@ -1842,6 +1884,12 @@ Creates a **Query** object to match the specified field whose value is within th
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name | Type| Mandatory| Description |
@@ -1889,6 +1937,12 @@ Creates a **Query** object to match the specified field whose value is within th
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name | Type| Mandatory| Description |
@@ -1936,6 +1990,12 @@ Creates a **Query** object to match the specified field whose value is not withi
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name | Type| Mandatory| Description |
@@ -1983,6 +2043,12 @@ Creates a **Query** object to match the specified field whose value is not withi
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name | Type| Mandatory| Description |
@@ -2030,6 +2096,12 @@ Creates a **Query** object to match the specified field whose value is similar t
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name| Type| Mandatory| Description |
@@ -2077,6 +2149,12 @@ Creates a **Query** object to match the specified field whose value is not simil
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name| Type| Mandatory| Description |
@@ -2190,6 +2268,12 @@ Creates a **Query** object to sort the query results in ascending order.
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name| Type| Mandatory| Description |
@@ -2237,6 +2321,12 @@ Creates a **Query** object to sort the query results in descending order.
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
**Parameters**
| Name| Type| Mandatory| Description |
@@ -2334,6 +2424,12 @@ Creates a **Query** object to match the specified field whose value is not **nul
> This API should be used together with [Schema](#schema).
>
> For details about how to use **Schema** to create a database, see the example of creating and obtaining a KV store using the **getKVStore()** method in [Persisting KV Store Data](../../database/data-persistence-by-kv-store.md#how-to-develop).
@@ -37,7 +37,7 @@ In addition to the [universal styles](js-components-common-styles.md), the follo
| object-fit | string | cover | No | Image scale type. This style is not supported for SVG images. For details about available values, see **object-fit**.|
| match-text-direction | boolean | false | No | Whether image orientation changes with the text direction. This style is not supported for SVG images. |
| fit-original-size | boolean | false | No | Whether the **\<image>** component adapts to the image source size when its width and height are not set. If this style is set to **true**, **object-fit** will not take effect. This style is not supported for SVG images.|
| object-position<sup>7+</sup> | string | 0px 0px | No | Position of the image in the component.<br>The options are as follows:<br>1. Pixels, in px. For example, **15px 15px** indicates the position to move along the x-axis or y-axis.<br>2. Characters. Optional values are as follows:<br>- **left**: The image is displayed on the left of the component.<<br>- **top**: The image is displayed on the top of the component.<br>- **right**: The image is displayed on the right of the component.<br>- **bottom**: The image is displayed at the bottom of the component.|
| object-position<sup>7+</sup> | string | 0px 0px | No | Position of the image in the component.<br>The options are as follows:<br>1. Pixels, in px. For example, **15px 15px** indicates the position to move along the x-axis or y-axis.<br>2. Characters. Optional values are as follows:<br>- **left**: The image is displayed on the left of the component.<br>- **top**: The image is displayed on the top of the component.<br>- **right**: The image is displayed on the right of the component.<br>- **bottom**: The image is displayed at the bottom of the component.|
| appId | string | Yes| - | Application ID for the atomic service.<br>**Atomic service API**: This API can be used in atomic services since API version 18.|
| options | [AtomicServiceOptions](../../apis-ability-kit/js-apis-app-ability-atomicServiceOptions.md) | No| - | Parameters for starting the atomic service. The default value is empty.<br>**Atomic service API**: This API can be used in atomic services since API version 18.|
| onError |[ErrorCallback](../../apis-basic-services-kit/js-apis-base.md#errorcallback) | No| - | Invoked when an error occurs during the running of the atomic service.<br>**Atomic service API**: This API can be used in atomic services since API version 18.|
| onTerminated | [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<TerminationInfo> | No| - | Callback used to return the result of the atomic service. The input parameter is of type **TerminationInfo**.<br>**Atomic service API**: This API can be used in atomic services since API version 18.|
| onTerminated | [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<[TerminationInfo](ts-container-embedded-component.md#terminationinfo)> | No| - | Callback used to return the result of the atomic service. The input parameter is of type **TerminationInfo**.<br>**Atomic service API**: This API can be used in atomic services since API version 18.|
| onReceive<sup>20+<sup> | [Callback](../../apis-basic-services-kit/js-apis-base.md#callback)\<Record<string, Object>> | No| - | Callback triggered when the embedded atomic service is launched through [Window](../../../windowmanager/application-window-stage.md) API calls.<br>**Atomic service API**: This API can be used in atomic services since API version 20.|
MediaAlbumChangeRequest provides APIs for managing the media album change request.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this class are supported since API version 11.
Obtains the album in the current album change request.
**NOTE**: For the change request for creating an album, this API returns **null** before [applyChanges](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11) is called to apply the changes.
> **NOTE**
>
> For the change request for creating an album, this API returns **null** before [applyChanges](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11) is called to apply the changes.
MediaAssetChangeRequest represents a media asset change request.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this class are supported since API version 11.
**NOTE**: For the change request used to create an asset, this API returns **null** before [applyChanges](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11) is called to apply the changes.
> **NOTE**
>
> For the change request used to create an asset, this API returns **null** before [applyChanges](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#applychanges11) is called to apply the changes.
**Atomic service API**: This API can be used in atomic services since API version 12.
@@ -459,9 +459,11 @@ async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
getWriteCacheHandler(): Promise<number>
Obtains the handler used for writing a file to cache.
Obtains the handler used for writing a file to cache. This API uses a promise to return the result.
**NOTE**: For the same asset change request, this API cannot be repeatedly called after a temporary file write handle is successfully obtained.
> **NOTE**
>
> For the same asset change request, this API cannot be repeatedly called after a temporary file write handle is successfully obtained.
Adds a resource using [fileUri](../apis-core-file-kit/js-apis-file-fileuri.md).
**NOTE**: For the same asset change request, this API cannot be repeatedly called after the resource is successfully added. For a moving photo, you can call this API twice to add the image and video resources.
> **NOTE**
>
> For the same asset change request, this API cannot be repeatedly called after the resource is successfully added. For a moving photo, you can call this API twice to add the image and video resources.
**Atomic service API**: This API can be used in atomic services since API version 11.
**NOTE**: For the same asset change request, this API cannot be repeatedly called after the resource is successfully added. For a moving photo, you can call this API twice to add the image and video resources.
> **NOTE**
>
> For the same asset change request, this API cannot be repeatedly called after the resource is successfully added. For a moving photo, you can call this API twice to add the image and video resources.
**Atomic service API**: This API can be used in atomic services since API version 11.
MediaAssetDataHandler is a media asset handler used to customize the media asset processing logic in **onDataPrepared**.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this interface are supported since API version 11.
MediaAssetDataHandler is a media asset handler used to customize the media asset processing logic in **onDataPrepared**.
The MediaAssetManager class is used for manipulating the read and write operations of media assets.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this class are supported since API version 11.
The MediaAssetManager class is used for manipulating the read and write operations of media assets.
MediaAssetProgressHandler is used to obtain the media asset processing progress from **onProgress()**.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this interface are supported since API version 15.
MediaAssetProgressHandler is used to obtain the media asset processing progress from **onProgress()**.
MovingPhoto provides APIs for managing a moving photo instance.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this interface are supported since API version 12.
MovingPhoto provides APIs for managing a moving photo instance.
| photoType | [PhotoType](arkts-apis-photoAccessHelper-e.md#phototype) | Yes | Type of the file to create, which can be **IMAGE** or **VIDEO**. |
| extension | string | Yes | File name extension, for example, **'jpg'**. |
| options | [CreateOptions](arkts-apis-photoAccessHelper-i.md#createoptions) | Yes | Options used for creation. Currently, only **title** is supported, for example, **{title: 'testPhoto'}**.<br>Note: If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved.<br>The file name must not contain any invalid characters, which are:.. \ / : * ? " ' ` < > \| { } [ ] |
| options | [CreateOptions](arkts-apis-photoAccessHelper-i.md#createoptions) | Yes | Options used for creation. Currently, only **title** is supported, for example, **{title: 'testPhoto'}**.<br>**NOTE**<br>If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved.<br>The file name must not contain any invalid characters, which are:.. \ / : * ? " ' ` < > \| { } [ ] |
| callback | AsyncCallback<string> | Yes | Callback used to return the URI of the created image or video asset.|
**Error codes**
@@ -345,7 +345,7 @@ If you do not have the ohos.permission.WRITE_IMAGEVIDEO permission, you can crea
| photoType | [PhotoType](arkts-apis-photoAccessHelper-e.md#phototype) | Yes | Type of the file to create, which can be **IMAGE** or **VIDEO**. |
| extension | string | Yes | File name extension, for example, **'jpg'**. |
| options | [CreateOptions](arkts-apis-photoAccessHelper-i.md#createoptions) | No | Options used for creation. Currently, only **title** is supported, for example, **{title: 'testPhoto'}**.<br>Note: If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved.<br>The file name must not contain any invalid characters, which are:.. \ / : * ? " ' ` < > \| { } [ ] |
| options | [CreateOptions](arkts-apis-photoAccessHelper-i.md#createoptions) | No | Options used for creation. Currently, only **title** is supported, for example, **{title: 'testPhoto'}**.<br>**NOTE**<br>If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved.<br>The file name must not contain any invalid characters, which are:.. \ / : * ? " ' ` < > \| { } [ ] |
**Return value**
@@ -836,7 +836,9 @@ async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
Shows the dialog box for the user to confirm whether to save the photos or videos. If the user agrees to save the images or videos, a list of URIs granted with the save permission is returned. The list takes effect permanently, and the application can write the images or videos based on the URIs. If the user refuses to save the images or videos, an empty list is returned. To display the application name in the dialog box, the API relies on the configuration of **label** and **icon** under **abilities** in the **module.json5** file. If they are not configured, no application name is displayed in the dialog box.
Displays a dialog box for the user to confirm whether to save the images or videos. If the user agrees to save the images or videos, this API returns a list of URIs that have been created and granted save permissions (this list is permanent), and the application can use these URIs to write the images or videos. If the user declines to save the images or videos, this API returns an empty list.
The dialog box must display the application name, but this cannot be directly obtained. Therefore, when calling this API, ensure that the **abilities** tag in the **module.json5** file is configured with **label** and **icon** items. Note that the icon is not affected by the **icon** item in the **abilities** tag and cannot be modified.
> **NOTE**
>
@@ -851,7 +853,7 @@ Shows the dialog box for the user to confirm whether to save the photos or video
| srcFileUris | Array<string> | Yes| [URIs](../../file-management/user-file-uri-intro.md#media-file-uri) of the images or videos to be saved to the media library.<br>**NOTE**<br>- A maximum of 100 images can be saved at a time.<br>- Only image and video URIs are supported.<br>- URIs cannot be manually constructed. You must call APIs to obtain them. For details, see [Obtaining a Media File URI](../../file-management/user-file-uri-intro.md#obtaining-a-media-file-uri). |
| photoCreationConfigs | Array<[PhotoCreationConfig](arkts-apis-photoAccessHelper-i.md#photocreationconfig12)> | Yes| Configuration for saving the images or videos, including the file names. The value must be consistent with that of **srcFileUris**.<br>Note: If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved.|
| photoCreationConfigs | Array<[PhotoCreationConfig](arkts-apis-photoAccessHelper-i.md#photocreationconfig12)> | Yes| Configuration for saving the images or videos, including the file names. The value must be consistent with that of **srcFileUris**.<br>**NOTE**<br>If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved.|
**Return value**
@@ -914,7 +916,7 @@ within 5 minutes after the user agrees to save the asset. If the same applicatio
| photoCreationConfig | [PhotoCreationConfig](arkts-apis-photoAccessHelper-i.md#photocreationconfig12); | Yes| Configuration for saving a media asset (image or video) to the media library, including the file name.<br>Note: If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved.|
| photoCreationConfig | [PhotoCreationConfig](arkts-apis-photoAccessHelper-i.md#photocreationconfig12); | Yes| Configuration for saving a media asset (image or video) to the media library, including the file name.<br>**NOTE**<br>If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved.|
| srcFileUris | Array<string> | Yes| [URIs](../../file-management/user-file-uri-intro.md#media-file-uri) of the images or videos to be granted with the permission.<br>Note: Only image and video URIs are supported, and the maximum number of URIs is 100.|
| srcFileUris | Array<string> | Yes| [URIs](../../file-management/user-file-uri-intro.md#media-file-uri) of the images or videos to be granted with the permission.<br>**NOTE**<br>Only image and video URIs are supported, and the maximum number of URIs is 100.|
**Return value**
@@ -1103,7 +1105,7 @@ Registers a listener for the **'photoChange'** event to monitor media asset chan
| type | string | Yes | Event type. The value is fixed at **'photoChange'**. After the registration is complete, any change to the media assets is returned through the callback.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | Yes | Callback used to return the media asset information after change, which is [PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20).<br>**NOTE**: You can register multiple listeners using this API, and you can call [off('photoChange')](#offphotochange20) to unregister all listeners or a specific one.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | Yes | Callback used to return the media asset information after change, which is [PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20).<br>**NOTE**<br>You can register multiple listeners using this API, and you can call [off('photoChange')](#offphotochange20) to unregister all listeners or a specific one.|
**Error codes**
@@ -1160,7 +1162,7 @@ Unregisters the listener for the **'photoChange'** event to stop monitoring medi
| type | string | Yes | Event type. The value is fixed at **'photoChange'**. After the unregistration is complete, any change to the media assets is no longer returned through the callback.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | No | Exact callback you previously registered with [on('photoChange')](#onphotochange20). If this parameter is left unspecified, all listeners for the **'photoChange'** event are unregistered.<br>**NOTE**: Once a specific callback is unregistered, it will not be invoked when a media asset changes.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | No | Exact callback you previously registered with [on('photoChange')](#onphotochange20). If this parameter is left unspecified, all listeners for the **'photoChange'** event are unregistered.<br>**NOTE**<br>Once a specific callback is unregistered, it will not be invoked when a media asset changes.|
**Error codes**
@@ -1220,7 +1222,7 @@ Registers a listener for the **'photoAlbumChange'** event to monitor album chang
| type | string | Yes | Event type. The value is fixed at **'photoAlbumChange'**. After the registration is complete, any change to the albums is returned through the callback.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | Yes | Callback used to return the album information after change, which is [AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20).<br>**NOTE**: You can register multiple listeners using this API, and you can call [off('photoAlbumChange')](#offphotoalbumchange20) to unregister all listeners or a specific one.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | Yes | Callback used to return the album information after change, which is [AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20).<br>**NOTE**<br>You can register multiple listeners using this API, and you can call [off('photoAlbumChange')](#offphotoalbumchange20) to unregister all listeners or a specific one.|
**Error codes**
@@ -1277,7 +1279,7 @@ Unregisters a listener for the **'photoAlbumChange'** event to stop monitoring a
| type | string | Yes | Event type. The value is fixed at **'photoAlbumChange'**. After the unregistration is complete, any change to the albums is no longer returned through the callback.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | No | Exact callback you previously registered with [on('photoAlbumChange')](#onphotoalbumchange20). If this parameter is left unspecified, all listeners for the **'photoAlbumChange'** event are unregistered.<br>**NOTE**: Once a specific callback is unregistered, it will not be invoked when an album changes.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | No | Exact callback you previously registered with [on('photoAlbumChange')](#onphotoalbumchange20). If this parameter is left unspecified, all listeners for the **'photoAlbumChange'** event are unregistered.<br>**NOTE**<br>Once a specific callback is unregistered, it will not be invoked when an album changes.|
PhotoAsset provides APIs for encapsulating file asset attributes.
> **NOTE**
>
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
PhotoAsset provides APIs for encapsulating file asset attributes.
## Modules to Import
```ts
@@ -576,7 +576,7 @@ async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
clone(title: string): Promise<PhotoAsset>
Clones a media asset. The file name can be set, but the file type cannot be changed.
Clones a media asset. The file name can be set, but the file type cannot be changed. This API uses a promise to return the result.
Opens this file in read-only mode. This API uses an asynchronous callback to return the result.
The returned FD must be closed when it is not required.
> **NOTE**
>
> - This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided.
>
> - The returned FD must be closed when it is not required.
> This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided.
Opens this file in read-only mode. This API uses a promise to return the result.
The returned FD must be closed when it is not required.
> **NOTE**
>
> - This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided.
>
> - The returned FD must be closed when it is not required.
> This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided.
PhotoViewPicker provides APIs for the user to select images and videos. Before using the APIs of PhotoViewPicker, you need to create a PhotoViewPicker instance.
> **NOTE**
>
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
PhotoViewPicker provides APIs for the user to select images and videos. Before using the APIs of PhotoViewPicker, you need to create a PhotoViewPicker instance.
**Atomic service API**: This API can be used in atomic services since API version 11.
Starts a **photoPicker** page for the user to select one or more images or videos. This API uses a promise to return the result. You can pass in **PhotoSelectOptions** to specify the media file type and the maximum number of files to select.
**NOTE**: The **photoUris** in the PhotoSelectResult object returned by this API has permanent authorization and can be used only by calling [photoAccessHelper.getAssets()](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri).
> **NOTE**
>
> **photoUris** in the PhotoSelectResult object returned by this API has permanent authorization and can be used only by calling [photoAccessHelper.getAssets](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri).
**Atomic service API**: This API can be used in atomic services since API version 11.
Starts a **photoPicker** page for the user to select one or more images or videos. This API uses an asynchronous callback to return the result. You can pass in **PhotoSelectOptions** to specify the media file type and the maximum number of files to select.
**NOTE**: The **photoUris** in the PhotoSelectResult object returned by this API has permanent authorization and can be used only by calling [photoAccessHelper.getAssets()](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri).
> **NOTE**
>
> **photoUris** in the PhotoSelectResult object returned by this API has permanent authorization and can be used only by calling [photoAccessHelper.getAssets](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri).
**Atomic service API**: This API can be used in atomic services since API version 11.
Starts a **photoPicker** page for the user to select one or more images or videos. This API uses an asynchronous callback to return the result.
**NOTE**: The **photoUris** in the PhotoSelectResult object returned by this API has permanent authorization and can be used only by calling [photoAccessHelper.getAssets()](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri).
> **NOTE**
>
> **photoUris** in the PhotoSelectResult object returned by this API has permanent authorization and can be used only by calling [photoAccessHelper.getAssets](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets). For details, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri).
**Atomic service API**: This API can be used in atomic services since API version 11.
QuickImageDataHandler is a media asset handler used to customize the media asset processing logic in **onDataPrepared**.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this interface are supported since API version 13.
QuickImageDataHandler is a media asset handler used to customize the media asset processing logic in **onDataPrepared**.
@@ -22,7 +22,7 @@ Defines the image recommendation options. The image recommendation feature depen
| recommendationType | [RecommendationType](arkts-apis-photoAccessHelper-e.md#recommendationtype11) | No | Yes| Type of the recommended image.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
| textContextInfo<sup>12+</sup> | [TextContextInfo](arkts-apis-photoAccessHelper-i.md#textcontextinfo12) | No | Yes| Text based on which images are recommended. If both **recommendationType** and **textContextInfo** are set, **textContextInfo** takes precedence over **recommendationType**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
## BaseSelectOptions<sup>10+</sup>
## BaseSelectOptions
Defines the basic options for selecting media files from Gallery.
@@ -48,17 +48,18 @@ Defines the basic options for selecting media files from Gallery.
PhotoSelectOptions extends BaseSelectOptions
Defines additional options for selecting media files from Gallery. It inherits from [BaseSelectOptions](#baseselectoptions10).
Defines additional options for selecting media files from Gallery. It inherits from [BaseSelectOptions](#baseselectoptions).
| isEditSupported<sup>11+</sup> | boolean | No | Yes| Whether the image can be edited. **true** if editable, **false** otherwise.<br>**Atomic service API**: This API can be used in atomic services since API version 11. |
| isOriginalSupported<sup>12+</sup> | boolean | No | Yes| Whether to display the button for selecting the original image. **true** to display, **false** otherwise. The default value is **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. |
| isOriginalSupported<sup>12+</sup> | boolean | No | Yes| Whether to display the button for selecting the original image. **true** to display, **false** otherwise. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. |
| subWindowName<sup>12+</sup> | string | No | Yes| Name of the child window.<br>**Atomic service API**: This API can be used in atomic services since API version 12. |
| completeButtonText<sup>14+</sup> | [CompleteButtonText](arkts-apis-photoAccessHelper-e.md#completebuttontext14) | No | Yes| Text displayed on the complete button.<br>The complete button is located in the lower-right corner of the page. It is used by users to signify that they have finished selecting images.<br>**Atomic service API**: This API can be used in atomic services since API version 14. |
| contextRecoveryInfo<sup>21+</sup> | [ContextRecoveryInfo](#contextrecoveryinfo21) | No | Yes| Information for restoring the PhotoPicker's state from the last exit.<br>When the selection process is complete, the PhotoPicker returns **contextRecoveryInfo** to the application. The application can then use the information to restore the PhotoPicker's state and the last viewed grid interface the next time it starts the PhotoPicker.<br>**Atomic service API**: This API can be used in atomic services since API version 21. |
## PhotoSelectResult
Defines information about the images or videos selected.
@@ -67,8 +68,8 @@ Defines information about the images or videos selected.
| Name | Type | Read-Only| Optional| Description |
| photoUris | Array<string> | No | No| URIs of the images or videos selected. The URI array can be used only by calling [photoAccessHelper.getAssets](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets) with temporary authorization. For details about how to use the media file URI, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri).<br>**Atomic service API**: This API can be used in atomic services since API version 11. |
| isOriginalPhoto | boolean | No | No| Whether the selected media file is the original image. **true** if yes, **false** otherwise. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 11. |
| photoUris | Array<string> | No | No| URIs of the images or videos selected. The URI array can be used only by calling [photoAccessHelper.getAssets](arkts-apis-photoAccessHelper-PhotoAccessHelper.md#getassets) with temporary authorization. For details about how to use the media file URI, see [Using a Media File URI](../../file-management/user-file-uri-intro.md#using-a-media-file-uri).<br>**Atomic service API**: This API can be used in atomic services since API version 11. |
| isOriginalPhoto | boolean | No | No| Whether the selected media file is the original image. **true** if yes, **false** otherwise. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 11. |
| contextRecoveryInfo<sup>21+</sup> | [ContextRecoveryInfo](#contextrecoveryinfo21) | No | No| Information about the context of exiting the PhotoPicker. This information is returned when the selection process is complete and is used by the application within **PhotoSelectOptions** during the subsequent launch of the PhotoPicker to restore the state from the previous exit.<br>**Atomic service API**: This API can be used in atomic services since API version 21.|
## MimeTypeFilter<sup>19+</sup>
@@ -161,5 +162,5 @@ Describes the information about the context of exiting the PhotoPicker. It can b
| time | number | No | No| Time of the top-left image in the grid interface when the user last selected an image.<br>- For albums sorted by capture time, the capture time is returned.<br>- For albums sorted by save time, the save time is returned. The default value is **0**.|
| displayName | string | No | No| File name of the top-left image in the grid interface when the user last selected an image. The default value is an empty string.|
| recommendationType | number | No | No| Enumerated value of the recommended content set by the user during the last selection. For details, see [RecommendationType](arkts-apis-photoAccessHelper-e.md#recommendationtype11).<br>If no recommendation was set during the last selection, the default value is **0**.|
| selectRecommendationType | number | No | No| Enumerated value of the recommended content selected by the user during the last selection. For details, see [RecommendationType](arkts-apis-photoAccessHelper-e.md#recommendationtype11).<br>If no recommendation was selected during the last selection or **All** is selected, the default value is **0**.|
| selectedRecommendationType | number | No | No| Enumerated value of the recommended content selected by the user during the last selection. For details, see [RecommendationType](arkts-apis-photoAccessHelper-e.md#recommendationtype11).<br>If no recommendation was selected during the last selection or **All** is selected, the default value is **0**.|
| version | number | No | No| Version number of the state data, used to verify the compatibility of the state information data with the state recovery capability.<br>The version number must be greater than or equal to 1.0.|
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
```ts
import { photoAccessHelper } from '@kit.MediaLibraryKit';
```
## PhotoType
Enumerates the media file types.
@@ -93,7 +99,7 @@ Enumerates the keys available for image or video files.
| URI | 'uri' | URI of the file.<br>Note: Only the [DataSharePredicates.equalTo](../apis-arkdata/js-apis-data-dataSharePredicates.md#equalto10) predicate can be used for this field during photo query.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| URI | 'uri' | URI of the file.<br>**NOTE**<br>Only the [DataSharePredicates.equalTo](../apis-arkdata/js-apis-data-dataSharePredicates.md#equalto10) predicate can be used for this field during photo query.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| PHOTO_TYPE | 'media_type' | Type of the file.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| DISPLAY_NAME | 'display_name' | File name displayed. The file name must meet the following requirements:<br>- A valid file name must include a base name and a supported image or video extension.<br>- The total length of the file name must be between 1 and 255 characters.<br>- The base name must not contain any invalid characters, which are:.. \ / : * ? " ' ` < > \| { } [ ]<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| SIZE | 'size' | File size, in bytes. The size of a moving photo includes the total size of the image and video.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
@@ -106,8 +112,8 @@ Enumerates the keys available for image or video files.
| ORIENTATION | 'orientation' | Orientation of the file, in degrees.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| FAVORITE | 'is_favorite' | Whether the file is marked as favorites.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| TITLE | 'title' | Title of the file.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| DATE_ADDED_MS<sup>12+</sup> | 'date_added_ms' | Unix timestamp when the file was created, in milliseconds.<br>**NOTE**: The photos queried cannot be sorted based on this field.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| DATE_MODIFIED_MS<sup>12+</sup> | 'date_modified_ms' | Unix timestamp when the file was modified, in milliseconds. This value is updated when the file content is modified, but not when the file name is modified.<br>**NOTE**: The photos queried cannot be sorted based on this field.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| DATE_ADDED_MS<sup>12+</sup> | 'date_added_ms' | Unix timestamp when the file was created, in milliseconds.<br>**NOTE**<br>The photos queried cannot be sorted based on this field.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| DATE_MODIFIED_MS<sup>12+</sup> | 'date_modified_ms' | Unix timestamp when the file was modified, in milliseconds. This value is updated when the file content is modified, but not when the file name is modified.<br>**NOTE**<br>The photos queried cannot be sorted based on this field.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| PHOTO_SUBTYPE<sup>12+</sup> | 'subtype' | Subtype of the media file.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| DYNAMIC_RANGE_TYPE<sup>12+</sup> | 'dynamic_range_type' | Dynamic range type of the media asset.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
| COVER_POSITION<sup>12+</sup> | 'cover_position' | Position of the moving photo cover, which is the video timestamp (in μs) corresponding to the cover frame.<br>**Atomic service API**: This API can be used in atomic services since API version 20. |
@@ -215,6 +221,7 @@ Enumerates the types of recommended images.
```ts
import { BusinessError } from '@kit.BasicServicesKit';
async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
try {
let recommendOptions: photoAccessHelper.RecommendationOptions = {
@@ -330,3 +337,4 @@ Enumerates the sources of the image or video data.
| ALL | 0 | Images and videos from all sources.<br>**Atomic service API**: This API can be used in atomic services since API version 20.|
| CAMERA | 1 | Image or video taken by the camera.<br>**Atomic service API**: This API can be used in atomic services since API version 20.|
| SCREENSHOT | 2 | Screenshot or screen capture video.<br>**Atomic service API**: This API can be used in atomic services since API version 20.|
@@ -52,7 +52,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ
```ts
// The phAccessHelper instance obtained is a global object. It is used by default in subsequent operations. If the code snippet is not added, an error will be reported indicating that phAccessHelper is not defined.
// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext.
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
```ts
import { photoAccessHelper } from '@kit.MediaLibraryKit';
```
## MediaChangeRequest<sup>11+</sup>
Media change request, which is the parent class of the asset change request and album change request.
@@ -89,6 +95,7 @@ Represents the text information about the recommended images.
```ts
import { BusinessError } from '@kit.BasicServicesKit';
async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
try {
let textInfo: photoAccessHelper.TextContextInfo = {
@@ -165,7 +172,7 @@ Describes the notification information about the change of a media asset.
| ---- | ------- | ---- | ---- | ----- |
| type | [NotifyChangeType](arkts-apis-photoAccessHelper-e.md#notifychangetype20) | No| No| Type of the media asset change.|
| assetChangeDatas | [PhotoAssetChangeData](#photoassetchangedata20)[] \| null | No| No| Array of changed media assets. If all media assets need to be queried again, **assetChangeDatas** is null. |
| isForRecheck | boolean | No| No| Whether the application should query all media assets again. **true** if the application should query all assets again, **false** otherwise.<br>**NOTE**: In special cases or abnormal notification scenarios, **isForRecheck** will be **true**. In this case, the application should query all assets again. |
| isForRecheck | boolean | No| No| Whether the application should query all media assets again. **true** if the application should query all assets again, **false** otherwise.<br>**NOTE**<br>In scenarios involving bulk asset operations or abnormal notifications, **isForRecheck** will be **true**. In this case, the application should query all assets again. |
## AlbumChangeInfo<sup>20+</sup>
@@ -205,4 +212,4 @@ Describes the notification information about the change of an album.
| ---- | ------- | ---- | ---- | ----- |
| type | [NotifyChangeType](arkts-apis-photoAccessHelper-e.md#notifychangetype20) | No| No| Type of the album change.|
| albumChangeDatas | [AlbumChangeData](#albumchangedata20)[] \| null | No| No| Array of changed albums. If all albums need to be queried again, **albumChangeDatas** is null. |
| isForRecheck | boolean | No| No| Whether the application should query all albums again. **true** if the application should query all albums again, **false** otherwise.<br>**NOTE**: In special cases or abnormal notification scenarios, **isForRecheck** will be **true**. In this case, the application should query all albums again. |
| isForRecheck | boolean | No| No| Whether the application should query all albums again. **true** if the application should query all albums again, **false** otherwise.<br>**NOTE**<br>In scenarios involving bulk album operations or abnormal notifications, **isForRecheck** will be **true**. In this case, the application should query all albums again. |
The module provides APIs for album management, including creating an album and accessing and modifying media data in an album.
> **NOTE**
>
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
The module provides APIs for album management, including creating an album and accessing and modifying media data in an album.
| analysisType | [AnalysisType](#analysistype11) | Yes | Analysis type. The default value is null.<br>This parameter is mandatory in API versions 12 to 21 and optional from API version 22 onwards.|
**Return value**
@@ -2135,7 +2135,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ
| 201 | Permission denied. |
| 202 | Called by non-system application. |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 14000011 | Internal system error.
| 14000011 | Internal system error. |
**Example**
@@ -2510,7 +2510,7 @@ Registers a listener for the **'hiddenPhotoChange'** event to monitor hidden med
| type | string | Yes | Event type. The value is fixed at **'hiddenPhotoChange'**. After the registration is complete, any change to the hidden media assets is returned through the callback.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | Yes | Callback used to return the hidden media asset information after change, which is [PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20).<br>**NOTE**: You can register multiple listeners using this API, and you can call [off('hiddenPhotoChange')](#offhiddenphotochange20) to unregister all listeners or a specific one.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | Yes | Callback used to return the hidden media asset information after change, which is [PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20).<br>**NOTE**<br>You can register multiple listeners using this API, and you can call [off('hiddenPhotoChange')](#offhiddenphotochange20) to unregister all listeners or a specific one.|
**Error codes**
@@ -2570,7 +2570,7 @@ Unregisters a listener for the **'hiddenPhotoChange'** event to stop monitoring
| type | string | Yes | Event type. The value is fixed at **'hiddenPhotoChange'**. After the unregistration is complete, any change to the hidden media assets is no longer returned through the callback.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | No | Exact callback you previously registered with [on('hiddenPhotoChange')](#onhiddenphotochange20). If this parameter is left unspecified, all listeners for the **'hiddenPhotoChange'** event are unregistered.<br>**NOTE**: Once a specific callback is unregistered, it will not be invoked when a hidden media asset changes.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | No | Exact callback you previously registered with [on('hiddenPhotoChange')](#onhiddenphotochange20). If this parameter is left unspecified, all listeners for the **'hiddenPhotoChange'** event are unregistered.<br>**NOTE**<br>Once a specific callback is unregistered, it will not be invoked when a hidden media asset changes.|
**Error codes**
@@ -2633,7 +2633,7 @@ Registers a listener for the **'trashedPhotoChange'** event to monitor media ass
| type | string | Yes | Event type. The value is fixed at **'trashedPhotoChange'**. After the registration is complete, any change to the trashed media assets is returned through the callback.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | Yes | Callback used to return the trashed media asset information after change, which is [PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20).<br>**NOTE**: You can register multiple listeners using this API, and you can call [off('trashedPhotoChange')](#offtrashedphotochange20) to unregister all listeners or a specific one.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | Yes | Callback used to return the trashed media asset information after change, which is [PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20).<br>**NOTE**<br>You can register multiple listeners using this API, and you can call [off('trashedPhotoChange')](#offtrashedphotochange20) to unregister all listeners or a specific one.|
**Error codes**
@@ -2693,7 +2693,7 @@ Unregisters a listener for the **'trashedPhotoChange'** event to stop monitoring
| type | string | Yes | Event type. The value is fixed at **'trashedPhotoChange'**. After the unregistration is complete, any change to the trashed media assets is no longer returned through the callback.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | No | Exact callback you previously registered with [on('trashedPhotoChange')](#ontrashedphotochange20). If this parameter is left unspecified, all listeners for the **'trashedPhotoChange'** event are unregistered.<br>**NOTE**: Once a specific callback is unregistered, it will not be invoked when a trashed media asset changes.|
| callback | Callback<[PhotoAssetChangeInfos](arkts-apis-photoAccessHelper-i.md#photoassetchangeinfos20)> | No | Exact callback you previously registered with [on('trashedPhotoChange')](#ontrashedphotochange20). If this parameter is left unspecified, all listeners for the **'trashedPhotoChange'** event are unregistered.<br>**NOTE**<br>Once a specific callback is unregistered, it will not be invoked when a trashed media asset changes.|
**Error codes**
@@ -2756,7 +2756,7 @@ Registers a listener for the **'hiddenAlbumChange'** event to monitor hidden alb
| type | string | Yes | Event type. The value is fixed at **'hiddenAlbumChange'**. After the registration is complete, any change to the hidden albums is returned through the callback.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | Yes | Callback used to return the hidden album information after change, which is [AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20).<br>**NOTE**: You can register multiple listeners using this API, and you can call [off('hiddenAlbumChange')](#offhiddenalbumchange20) to unregister all listeners or a specific one.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | Yes | Callback used to return the hidden album information after change, which is [AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20).<br>**NOTE**<br>You can register multiple listeners using this API, and you can call [off('hiddenAlbumChange')](#offhiddenalbumchange20) to unregister all listeners or a specific one.|
**Error codes**
@@ -2816,7 +2816,7 @@ Unregisters a listener for the **'hiddenAlbumChange'** event to stop monitoring
| type | string | Yes | Event type. The value is fixed at **'hiddenAlbumChange'**. After the unregistration is complete, any change to the hidden albums is no longer returned through the callback.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | No | Exact callback you previously registered with [on('hiddenAlbumChange')](#onhiddenalbumchange20). If this parameter is left unspecified, all listeners for the **'hiddenAlbumChange'** event are unregistered.<br>**NOTE**: Once a specific callback is unregistered, it will not be invoked when a hidden album changes.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | No | Exact callback you previously registered with [on('hiddenAlbumChange')](#onhiddenalbumchange20). If this parameter is left unspecified, all listeners for the **'hiddenAlbumChange'** event are unregistered.<br>**NOTE**<br>Once a specific callback is unregistered, it will not be invoked when a hidden album changes.|
**Error codes**
@@ -2879,7 +2879,7 @@ Registers a listener for the **'trashedAlbumChange'** event to monitor album cha
| type | string | Yes | Event type. The value is fixed at **'trashedAlbumChange'**. After the registration is complete, any change to the trashed albums is returned through the callback.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | Yes | Callback used to return the trashed album information after change, which is [AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20).<br>**NOTE**: You can register multiple listeners using this API, and you can call [off('trashedAlbumChange')](#offtrashedalbumchange20) to unregister all listeners or a specific one.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | Yes | Callback used to return the trashed album information after change, which is [AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20).<br>**NOTE**<br>You can register multiple listeners using this API, and you can call [off('trashedAlbumChange')](#offtrashedalbumchange20) to unregister all listeners or a specific one.|
**Error codes**
@@ -2939,7 +2939,7 @@ Unregisters a listener for the **'trashedAlbumChange'** event to stop monitoring
| type | string | Yes | Event type. The value is fixed at **'trashedAlbumChange'**. After the unregistration is complete, any change to the trashed albums is no longer returned through the callback.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | No | Exact callback you previously registered with [on('trashedAlbumChange')](#ontrashedalbumchange20). If this parameter is left unspecified, all listeners for the **'trashedAlbumChange'** event are unregistered.<br>**NOTE**: Once a specific callback is unregistered, it will not be invoked when an album in the trash changes.|
| callback | Callback<[AlbumChangeInfos](arkts-apis-photoAccessHelper-i.md#albumchangeinfos20)> | No | Exact callback you previously registered with [on('trashedAlbumChange')](#ontrashedalbumchange20). If this parameter is left unspecified, all listeners for the **'trashedAlbumChange'** event are unregistered.<br>**NOTE**<br>Once a specific callback is unregistered, it will not be invoked when an album in the trash changes.|
Opens this file asset. This API uses an asynchronous callback to return the result.
The returned FD must be closed when it is not required.
> **NOTE**
>
> This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided.
**NOTE**: A file can be opened in only one mode at a time. Use **close()** to close the FD returned when it is not required.
**System API**: This is a system API.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO or ohos.permission.WRITE_IMAGEVIDEO
Opens this file asset. This API uses a promise to return the result.
The returned FD must be closed when it is not required.
> **NOTE**
>
> This API is supported since API version 10 and deprecated since API version 11. For security purposes, the API for obtaining the media file handle is no longer provided.
**NOTE**: A file can be opened in only one mode at a time. Use **close()** to close the FD returned when it is not required.
**System API**: This is a system API.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO or ohos.permission.WRITE_IMAGEVIDEO
@@ -3800,11 +3800,13 @@ async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
getExif(): Promise<string>
Obtains the EXIF data from a JPG image and returns a JSON string. This API uses a promise to return the result.
Obtains the Exif data from a JPG image and returns a JSON string. This API uses a promise to return the result.
The EXIF information obtained are provided by the [image](../apis-image-kit/arkts-apis-image.md) module. For details about the EXIF information, see [image.PropertyKey](../apis-image-kit/arkts-apis-image-e.md#propertykey7).
The Exif data obtained are provided by the [image](../apis-image-kit/arkts-apis-image.md) module. For details about the Exif data, see [image.PropertyKey](../apis-image-kit/arkts-apis-image-e.md#propertykey7).
**NOTE**: This API returns a JSON string consisting of EXIF tags. The complete EXIF information consists of **all_exif** and [PhotoKeys.USER_COMMENT](#photokeys). These two fields must be passed in via **fetchColumns**.
> **NOTE**
>
> This API returns a JSON string consisting of of Exif tags. The complete Exif data consists of **all_exif** and [PhotoKeys.USER_COMMENT](#photokeys). These two fields must be passed in via [FetchOptions](./arkts-apis-photoAccessHelper-i.md#fetchoptions).fetchColumns.
**System API**: This is a system API.
@@ -3816,7 +3818,7 @@ The EXIF information obtained are provided by the [image](../apis-image-kit/arkt
Obtains the EXIF data from a JPG image and returns a JSON string. This API uses an asynchronous callback to return the result.
Obtains the Exif data from a JPG image and returns a JSON string. This API uses an asynchronous callback to return the result.
The EXIF information obtained are provided by the [image](../apis-image-kit/arkts-apis-image.md) module. For details about the EXIF information, see [image.PropertyKey](../apis-image-kit/arkts-apis-image-e.md#propertykey7).
The Exif data obtained are provided by the [image](../apis-image-kit/arkts-apis-image.md) module. For details about the Exif data, see [image.PropertyKey](../apis-image-kit/arkts-apis-image-e.md#propertykey7).
**NOTE**: This API returns a JSON string consisting of EXIF tags. The complete EXIF information consists of **all_exif** and [PhotoKeys.USER_COMMENT](#photokeys). These two fields must be passed in via **fetchColumns**.
> **NOTE**
>
> This API returns a JSON string consisting of of Exif tags. The complete Exif data consists of **all_exif** and [PhotoKeys.USER_COMMENT](#photokeys). These two fields must be passed in via [FetchOptions](./arkts-apis-photoAccessHelper-i.md#fetchoptions).fetchColumns.
**System API**: This is a system API.
@@ -3880,7 +3884,7 @@ The EXIF information obtained are provided by the [image](../apis-image-kit/arkt
| callback | AsyncCallback<string> | Yes | Callback used to return the EXIF data, in JSON strings.|
| callback | AsyncCallback<string> | Yes | Callback used to return the Exif data, in JSON strings.|
**Error codes**
@@ -3941,8 +3945,6 @@ Sets user comment information of an image or video. This API uses a promise to r
>
> This API is supported since API version 10 and deprecated since API version 11. Use [MediaAssetChangeRequest.setUserComment](#setusercomment11) instead.
**NOTE**: This API can be used to modify the comment information of only images or videos.
@@ -4010,8 +4012,6 @@ Sets user comment information of an image or video. This API uses an asynchronou
>
> This API is supported since API version 10 and deprecated since API version 11. Use [MediaAssetChangeRequest.setUserComment](#setusercomment11) instead.
**NOTE**: This API can be used to modify the comment information of only images or videos.
@@ -4078,7 +4078,9 @@ Sets the pending state for this image or video asset. This API uses an asynchron
The pending state can be removed only through **setPending(false)**. You can use **photoAsset.get(photoAccessHelper.PhotoKeys.PENDING)** to check whether the asset state is pending. If the asset is in pending state, **true** is returned. Otherwise, **false** is returned.
**NOTE**: **setPending** can be used only during the file creation process. Once the FD is closed, **setPending(true)** cannot be used to set the pending state for the file.
> **NOTE**
>
> **setPending** can be used only during the file creation process. Once the FD is closed, **setPending(true)** cannot be used to set the pending state for the file.
**System API**: This is a system API.
@@ -4141,7 +4143,9 @@ Sets the pending state for this image or video asset. This API uses a promise to
The pending state can be removed only through **setPending(false)**. You can use **photoAsset.get(photoAccessHelper.PhotoKeys.PENDING)** to check whether the asset state is pending. If the asset is in pending state, **true** is returned. Otherwise, **false** is returned.
**NOTE**: **setPending** can be used only during the file creation process. Once the FD is closed, **setPending(true)** cannot be used to set the pending state for the file.
> **NOTE**
>
> **setPending** can be used only during the file creation process. Once the FD is closed, **setPending(true)** cannot be used to set the pending state for the file.
**System API**: This is a system API.
@@ -4661,7 +4665,9 @@ Commits the edited image or video asset. This API uses an asynchronous callback
The edited file is transferred to the media library based on the URI, which is **FileUri** of the edited file in the application sandbox directory. For details, see [File URI](../apis-core-file-kit/js-apis-file-fileuri.md).
**NOTE**: The commit operation overwrites the previous edited data.
> **NOTE**
>
> The commit operation overwrites the previous edited data.
**System API**: This is a system API.
@@ -4732,7 +4738,9 @@ Commits the edited image or video asset. This API uses a promise to return the r
The edited file is transferred to the media library based on the URI, which is **FileUri** of the edited file in the application sandbox directory. For details, see [File URI](../apis-core-file-kit/js-apis-file-fileuri.md).
**NOTE**: The commit operation overwrites the previous edited data.
> **NOTE**
>
> The commit operation overwrites the previous edited data.
Reverts to the state of the file before being edited. This API uses an asynchronous callback to return the result.
**NOTE**: This API deletes the edited data and edited image or video asset, and the deleted data cannot be restored. Exercise caution when using this API.
> **NOTE**
>
> This API deletes the edited data and edited image or video asset, and the deleted data cannot be restored. Exercise caution when using this API.
Reverts to the state of the file before being edited. This API uses a promise to return the result.
**NOTE**: This API deletes the edited data and edited image or video asset, and the deleted data cannot be restored. Exercise caution when using this API.
> **NOTE**
>
> This API deletes the edited data and edited image or video asset, and the deleted data cannot be restored. Exercise caution when using this API.
**System API**: This is a system API.
@@ -5450,10 +5462,10 @@ Deletes image or video assets from the trash. Before the operation, ensure that
> **NOTE**
>
> This operation is irreversible. The assets deleted cannot be restored. Exercise caution when performing this operation.
>
> This API is supported since API version 10 and deprecated since API version 11. Use [MediaAlbumChangeRequest.deleteAssets](#deleteassets11) instead.
**NOTE**: This operation is irreversible. The file assets deleted cannot be restored. Exercise caution when performing this operation.
| SOURCE<sup>18+</sup> | 2048 | Source album.<br>**System API**: This is a system API.|
| SOURCE<sup>18+</sup> | 2048 | Source album.<br>**System API**: This is a system API.|
| SMART<sup>11+</sup> | 4096 | Smart analysis album.<br>**System API**: This is a system API.|
## AlbumSubtype
@@ -10581,7 +10595,7 @@ Enumerate the album subtypes.
| TRASH | 1028 | Trash. **System API**: This is a system API. |
| SCREENSHOT | 1029 | Album for screenshots and screen recording files. **System API**: This is a system API. |
| CAMERA | 1030 | Album for images and videos taken by the camera. **System API**: This is a system API.|
| SOURCE\_GENERIC<sup>11+</sup> | 2049 | Source album. **System API**: This is a system API. |
| SOURCE\_GENERIC<sup>11+</sup> | 2049 | Source album. **System API**: This is a system API. |
| CLASSIFY<sup>11+</sup> | 4097 | Classified album. **System API**: This is a system API. |
| GEOGRAPHY\_LOCATION<sup>11+</sup> | 4099 | Geographic location album. **System API**: This is a system API. |
| GEOGRAPHY\_CITY<sup>11+</sup> | 4100 | City album. **System API**: This is a system API. |
@@ -10629,7 +10643,7 @@ Defines the key information about an image or video file.
| THUMBNAIL_VISIBLE<sup>14+</sup> | 'thumbnail_visible' | Whether a thumbnail is visible. **System API**: This is a system API. |
| SUPPORTED_WATERMARK_TYPE<sup>14+</sup> | 'supported_watermark_type' | Watermark type to set. **System API**: This is a system API. |
| IS_CE_AUTO<sup>18+</sup> | 'is_auto' | Whether automatic cloud enhancement is supported. **System API**: This is a system API. |
| OWNER_ALBUM_ID<sup>18+</sup> | 'owner_album_id' | ID of the album to which the photo belongs. **System API**: This is a system API. |
| OWNER_ALBUM_ID<sup>18+</sup> | 'owner_album_id' | ID of the album to which the photo belongs. **System API**: This is a system API. |
| IS_RECENT_SHOW<sup>18+</sup> | 'is_recent_show' | Whether the asset is displayed in the **Recent** list. **System API**: This is a system API. |
| SUM_SIZE<sup>19+</sup> | 'sum(size)' | Total size of files. When **SUM_SIZE** is filled in **fetchColumns**, only the first asset is obtained, and the property includes the total size of all assets. **System API**: This is a system API. |
| EXIF_ROTATE<sup>21+</sup> | 'exif_rotate' | Rotational angle of the file. **System API**: This is a system API. |
@@ -10644,7 +10658,7 @@ Enumerates the album keys.
| albumPickerOptions | [AlbumPickerOptions](#albumpickeroptions) | No | **AlbumPicker** configuration.<br> **Atomic service API**: This API can be used in atomic services since API version 12. |
| onAlbumClick | (albumInfo: [AlbumInfo](#albuminfo)) => boolean | No | Callback used to return the album URI when an album is selected by a user. No special processing is performed on the return value.<br> **Atomic service API**: This API can be used in atomic services since API version 12. |
| onEmptyAreaClick<sup>13+</sup> | [EmptyAreaClickCallback](#emptyareaclickcallback13) | No | Callback to be invoked when the blank area of the **AlbumPickerComponent** is tapped, which is used to notify the application of the tap.<br> **Atomic service API**: This API can be used in atomic services since API version 13.|
| onEmptyAreaClick<sup>13+</sup> | [EmptyAreaClickCallback](#emptyareaclickcallback13) | No | Callback to be invoked when the blank area of the **AlbumPickerComponent** is tapped, which is used to notify the application of the tap.<br> **Atomic service API**: This API can be used in atomic services since API version 13.|
| albumPickerController<sup>20+</sup> | [AlbumPickerController](#albumpickercontroller20) | No | A controller that enables applications to send data to the **AlbumPickerComponent**.<br> **Atomic service API**: This API can be used in atomic services since API version 20.|
@@ -75,11 +75,11 @@ Allows the application to access images or videos in the user directory without
| onExceedMaxSelected<sup>13+</sup> | [ExceedMaxSelectedCallback](#exceedmaxselectedcallback13) | No | - | Callback to be invoked when the number of selected media assets exceeds the limit (maximum number of selected images, selected videos, or selected items).<br>- If the number of selected images reaches the maximum but does not reach the maximum count of selected items, **exceedMaxCountType** in the callback is [MaxCountType](#maxcounttype).PHOTO_MAX_COUNT.<br>- If the number of selected videos reaches the maximum but does not reach the maximum count of selected items, **exceedMaxCountType** in the callback is [MaxCountType](#maxcounttype).VIDEO_MAX_COUNT.<br>- If the number of selected media assets reaches the maximum count of selected items, **exceedMaxCountType** in the callback is [MaxCountType](#maxcounttype).TOTAL_MAX_COUNT.<br>**Atomic service API**: This API can be used in atomic services since API version 13.|
| onCurrentAlbumDeleted<sup>13+</sup> | [CurrentAlbumDeletedCallback](#currentalbumdeletedcallback13) | No | - | Callback to be invoked when the current album is deleted.<br>The album is specified by **currentAlbumUri** in pickerController.[setData](#setdata)([DataType](#datatype).SET_ALBUM_URI, currentAlbumUri).<br>To refresh the grid page to display the default album after the current album is deleted, you can set the title bar name to the default album name, for example, **Photos and videos**, **Photos**, or **Videos**, and call pickerController.[setData](#setdata)([DataType](#datatype).SET_ALBUM_URI, '') with an empty string.<br>**Atomic service API**: This API can be used in atomic services since API version 13. |
| onVideoPlayStateChanged<sup>14+</sup> | [videoPlayStateChangedCallback](#videoplaystatechangedcallback14) | No | - | Callback to be invoked when the video playback state on a photo browser page changes.<br>**Atomic service API**: This API can be used in atomic services since API version 14. |
| pickerController | [PickerController](#pickercontroller) | Yes | @ObjectLink | Instance used to send data to the **PhotoPickerComponent**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
| pickerController | [PickerController](#pickercontroller) | Yes | @ObjectLink | Instance used to send data to the **PhotoPickerComponent**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
## PickerOptions
Describes the configuration of a Picker. It inherits from [photoAccessHelper.BaseSelectOptions](arkts-apis-photoAccessHelper-class.md#baseselectoptions10).
Describes the configuration of a Picker. It inherits from [photoAccessHelper.BaseSelectOptions](arkts-apis-photoAccessHelper-class.md#baseselectoptions).
| trustedUris | Array<string> | Yes| URIs of the images or videos in the application sandbox path. Generally, **trustedUris** comes from **newUri** of new images generated by [replacePhotoPickerPreview](#replacephotopickerpreview15).|
| callback | AsyncCallback<Array<string>> | Yes| URIs of the new files in Gallery. |
| configs | Array<[photoAccessHelper.PhotoCreationConfig](arkts-apis-photoAccessHelper-i.md#photocreationconfig12)> | No| Configuration parameters corresponding to the original files.<br>Note: If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved. |
| configs | Array<[photoAccessHelper.PhotoCreationConfig](arkts-apis-photoAccessHelper-i.md#photocreationconfig12)> | No| Configuration parameters corresponding to the original files.<br>**NOTE**<br>If a **subtype** option is passed, the configuration does not take effect. Only DEFAULT images can be saved. |
| saveMode | [SaveMode](#savemode15) | No| Mode for saving the files. |
## BaseItemInfo
Represents basic image and video information.
@@ -338,8 +354,8 @@ Represents basic image and video information.
| size | number | No| Yes | Size of the image or video, in bytes.<br>This parameter is supported only when [ItemType](#itemtype) is set to **THUMBNAIL**. Otherwise, it is left empty.<br>**Atomic service API**: This API can be used in atomic services since API version 12. |
| duration | number | No| Yes | Video duration, in milliseconds. For an image or a moving photo, the value **-1** is returned.<br>This parameter is supported only when [ItemType](#itemtype) is set to **THUMBNAIL**. Otherwise, it is left empty.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
| photoSubType<sup>21+</sup> | [photoAccessHelper.PhotoSubtype](arkts-apis-photoAccessHelper-e.md#photosubtype12) | No| Yes | Subtype of the photo. The options are **DEFAULT**, **MOVING_PHOTO**, and **BRUST**.<br>The default value is **DEFAULT (0)**.<br>**Atomic service API**: This API can be used in atomic services since API version 21.|
| dynamicRangeType<sup>21+</sup> | [photoAccessHelper.DynamicRangeType](arkts-apis-photoAccessHelper-e.md#dynamicrangetype12) | No| Yes | Dynamic range type of the media file. The options are **HDR** and **SDR**.<br>For moving photos, this parameter specifies the dynamic range type of the cover image.<br>**Atomic service API**: This API can be used in atomic services since API version 21.
| orientation<sup>21+</sup> | number | No| Yes | Image or video direction information.<br>1: **TOP-left**: The image is not rotated.<br>2: **TOP-right**: The image is flipped horizontally.<br>3: **Bottom-right**: The image is rotated by 180°.<br>4: **Bottom-left**: The image is flipped vertically.<br>5: **Left-top**: The image is flipped horizontally and then rotated clockwise by 270°.<br>6: **Right-top**: The image is rotated clockwise by 90°.<br>7: **Right-bottom**: The image is vertically flipped and then rotated clockwise by 90°.<br>8: **Left-bottom**: The image is rotated clockwise by 270°.<br>Images with mirroring information retain their original width and height attributes regardless of rotation, whereas images without such information have these attributes updated to reflect the post-rotation dimensions.<br>**Atomic service API**: This API can be used in atomic services since API version 21.
| dynamicRangeType<sup>21+</sup> | [photoAccessHelper.DynamicRangeType](arkts-apis-photoAccessHelper-e.md#dynamicrangetype12) | No| Yes | Dynamic range type of the media file. The options are **HDR** and **SDR**.<br>For moving photos, this parameter specifies the dynamic range type of the cover image.<br>**Atomic service API**: This API can be used in atomic services since API version 21.|
| orientation<sup>21+</sup> | number | No| Yes | Image or video direction information.<br>1: **TOP-left**: The image is not rotated.<br>2: **TOP-right**: The image is flipped horizontally.<br>3: **Bottom-right**: The image is rotated by 180°.<br>4: **Bottom-left**: The image is flipped vertically.<br>5: **Left-top**: The image is flipped horizontally and then rotated clockwise by 270°.<br>6: **Right-top**: The image is rotated clockwise by 90°.<br>7: **Right-bottom**: The image is vertically flipped and then rotated clockwise by 90°.<br>8: **Left-bottom**: The image is rotated clockwise by 270°.<br>Images with mirroring information retain their original width and height attributes regardless of rotation, whereas images without such information have these attributes updated to reflect the post-rotation dimensions.<br>**Atomic service API**: This API can be used in atomic services since API version 21.|
## ItemInfo
@@ -431,6 +447,10 @@ Describes the information about the preselected files and their corresponding **
| uri | string | No | No|URI of the preselected media file.|
| preselectablePickerIndex | number | No | Yes| Index of the **PhotoPickerComponent** that can be used in automatic selection. The default value is **-1**, which allows automatic selection in any **PhotoPickerComponent**.|
## DataType
Enumerates the types of data sent from **PickerController** to the **PhotoPickerComponent**.
@@ -172,7 +172,7 @@ Registers a callback used to periodically detect service thread stuck events. <
| Type| Description|
| -- | -- |
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br>[HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br>[HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
### OH_HiCollie_Init_StuckDetectionWithTimeout()
@@ -192,13 +192,13 @@ Registers a callback used to periodically detect service thread stuck events. <
| Name| Description|
| -- | -- |
| [OH_HiCollie_Task](capi-hicollie-h.md#oh_hicollie_task) task | Periodic detection task that is executed every **stuckTimeout** time to check whether a service thread is stuck.|
| uint32_t stuckTimeout | Threshold for reporting a service thread stuck event, in seconds. When the task execution time exceeds the value of **stuckTimeout**, a stuck warning event is reported. When the task execution time exceeds twice the value of **stuckTimeout**, a stuck event is reported.<br> The maximum value is **15s** and the minimum value is **3s**.|
| uint32_t stuckTimeout | Threshold for reporting a service thread stuck event, in seconds. When the task execution time exceeds the value of **stuckTimeout**, a stuck warning event is reported. When the task execution time exceeds twice the value of **stuckTimeout**, a stuck event is reported.<br> The maximum value is **15s** and the minimum value is **3s**.|
**Returns**
| Type| Description|
| -- | -- |
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - Invalid detection time.<br>[HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - Invalid detection time.<br>[HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
### OH_HiCollie_Init_JankDetection()
@@ -225,7 +225,7 @@ Registers a callback used to detect service thread jank events.<br> To monitor s
| Type| Description|
| -- | -- |
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - The begin and end functions are not both set or both unset; they must either both have valid values or both be empty.<br>[HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - The begin and end functions are not both set or both unset; they must either both have valid values or both be empty.<br>[HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
### OH_HiCollie_Report()
@@ -250,7 +250,7 @@ Reports a service thread stuck event and generates logs to help locate applicati
| Type| Description|
| -- | -- |
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - The begin and end functions are not both set or both unset; they must either both have valid values or both be empty.<br>[HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br>[HICOLLIE_REMOTE_FAILED](capi-hicollie-h.md#hicollie_errorcode) 29800002 - Remote call error. The IPC remote service fails to be called.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_ARGUMENT](capi-hicollie-h.md#hicollie_errorcode) 401 - The begin and end functions are not both set or both unset; they must either both have valid values or both be empty.<br>[HICOLLIE_WRONG_THREAD_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800001 - Incorrect calling thread. This function should be called in a non-main thread.<br>[HICOLLIE_REMOTE_FAILED](capi-hicollie-h.md#hicollie_errorcode) 29800002 - Remote call error. The IPC remote service fails to be called.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
### OH_HiCollie_Callback()
@@ -288,7 +288,7 @@ Registers a timer to check whether the execution time of a function or code bloc
| Type| Description|
| -- | -- |
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_TIMER_NAME](capi-hicollie-h.md#hicollie_errorcode) 29800003 - Invalid timer name. The timer name cannot be NULL or an empty string.<br>[HICOLLIE_INVALID_TIMEOUT_VALUE](capi-hicollie-h.md#hicollie_errorcode) 29800004 - Invalid timeout value.<br>[HICOLLIE_WRONG_PROCESS_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800005 - Invalid process context for detection. This function cannot be called in the **appspawn** and **nativespawn** processes.<br>[HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM](capi-hicollie-h.md#hicollie_errorcode) 29800006 - The pointer used to save the returned timer ID is NULL.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
| [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode) | [HICOLLIE_SUCCESS](capi-hicollie-h.md#hicollie_errorcode) 0 - Operation successful.<br> [HICOLLIE_INVALID_TIMER_NAME](capi-hicollie-h.md#hicollie_errorcode) 29800003 - Invalid timer name. The timer name cannot be NULL or an empty string.<br>[HICOLLIE_INVALID_TIMEOUT_VALUE](capi-hicollie-h.md#hicollie_errorcode) 29800004 - Invalid timeout value.<br>[HICOLLIE_WRONG_PROCESS_CONTEXT](capi-hicollie-h.md#hicollie_errorcode) 29800005 - Invalid process context for detection. This function cannot be called in the **appspawn** and **nativespawn** processes.<br>[HICOLLIE_WRONG_TIMER_ID_OUTPUT_PARAM](capi-hicollie-h.md#hicollie_errorcode) 29800006 - The pointer used to save the returned timer ID is NULL.<br>For details, see [HiCollie_ErrorCode](capi-hicollie-h.md#hicollie_errorcode).|
@@ -879,7 +879,7 @@ Obtains the specified system [GC](../../arkts-utils/gc-introduction.md) statisti
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- |-------------|
| item | string | Yes | Type of the statistics to obtain. The following statistics can be obtained:<br>**"ark.gc.gc-count"**: number of GC times of the current thread.<br>**"ark.gc.gc-time"**: total GC duration triggered by the current thread, in milliseconds.<br>**"ark.gc.gc-bytes-allocated"**: size of the Ark VM memory allocated to the current thread, in bytes.<br>**"ark.gc.gc-bytes-freed"**: memory freed by the GC of the current thread, in bytes.<br> **"ark.gc.fullgc-longtime-count"**: number of longtime full GCs triggered by the current thread.|
| item | string | Yes | Type of the statistics to obtain. The following statistics can be obtained:<br>**"ark.gc.gc-count"**: number of GC times of the current thread.<br>**"ark.gc.gc-time"**: total GC duration triggered by the current thread, in milliseconds.<br>**"ark.gc.gc-bytes-allocated"**: size of the Ark VM memory allocated to the current thread, in bytes.<br>**"ark.gc.gc-bytes-freed"**: memory freed by GC of the current thread, in bytes.<br> **"ark.gc.fullgc-longtime-count"**: number of longtime full GC times triggered by the current thread.|
**Return value**
@@ -1042,7 +1042,7 @@ Describes the key-value pair used to store GC statistics. This type does not sup
| Type | Description |
| -----------| ---------------------------- |
| Record<string, number> | Key-value pair format used to store GC statistics. It contains the following information:<br>**"ark.gc.gc-count"**: number of GC times of the current thread.<br>**"ark.gc.gc-time"**: total GC duration triggered by the current thread, in milliseconds.<br>**"ark.gc.gc-bytes-allocated"**: size of the Ark VM memory allocated to the current thread, in bytes.<br>**"ark.gc.gc-bytes-freed"**: memory freed by the GC of the current thread, in bytes.<br> **"ark.gc.fullgc-longtime-count"**: number of longtime full GCs triggered by the current thread. |
| Record<string, number> | Key-value pair format used to store GC statistics. It contains the following information:<br>**"ark.gc.gc-count"**: number of GC times of the current thread.<br>**"ark.gc.gc-time"**: total GC duration triggered by the current thread, in milliseconds.<br>**"ark.gc.gc-bytes-allocated"**: size of the Ark VM memory allocated to the current thread, in bytes.<br>**"ark.gc.gc-bytes-freed"**: memory freed by GC of the current thread, in bytes.<br> **"ark.gc.fullgc-longtime-count"**: number of longtime full GC times triggered by the current thread. |
## JsRawHeapTrimLevel<sup>20+</sup>
@@ -1395,5 +1395,5 @@ Describes the GPU memory data of an application, including the GL and Graph part
| Name | Type | Read Only | Optional| Description |
| gl | number | No | No | GL memory size (DMA memory usage of the process), in KB, including the DMA buffers obtained directly through the API and those obtained through **allocator_host**.|
| graph | number | No | No | Graph memory size (memory occupied by RenderService for loading required resources, such as images and textures), in KB. |
| gl | number | No | No | GL memory size (memory occupied by RenderService for loading required resources, such as images and textures), in KB.|
| graph | number | No | No | Graph memory size (DMA memory usage of the process), in KB, including the DMA buffers obtained directly through the API and those obtained through **allocator_host**.|
@@ -88,17 +88,19 @@ DEBUG logs are not recorded in official versions by default. They are available
**Example**
This example is used to output a DEBUG log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
This example is used to output a DEBUG log with the format string being **"%{public}s World %{private}d"**. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
```js
hilog.debug(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
```
If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
If **"hello"** is filled in **%{public}s** and **3** in **%{private}d**, the output log is as follows:
<!--RP3-->
```
08-05 12:21:47.579 2695 2703 D A00001/testTag: hello World <private>
08-05 12:21:47.579 2695-2703 A00001/testTag com.example.hilogDemo D hello World <private>
```
<!--RP3End-->
## hilog.info
@@ -121,17 +123,19 @@ Prints INFO logs.
**Example**
This example is used to output an INFO log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
This example is used to output an INFO log with the format string being **"%{public}s World %{private}d"**. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
```js
hilog.info(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
```
If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
If **"hello"** is filled in **%{public}s** and **3** in **%{private}d**, the output log is as follows:
<!--RP4-->
```
08-05 12:21:47.579 2695 2703 I A00001/testTag: hello World <private>
08-05 12:21:47.579 2695-2703 A00001/testTag com.example.hilogDemo I hello World <private>
```
<!--RP4End-->
## hilog.warn
@@ -154,17 +158,19 @@ Prints WARN logs.
**Example**
This example is used to output a WARN log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
This example is used to output a WARN log with the format string being **"%{public}s World %{private}d"**. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
```js
hilog.warn(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
```
If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
If **"hello"** is filled in **%{public}s** and **3** in **%{private}d**, the output log is as follows:
<!--RP5-->
```
08-05 12:21:47.579 2695 2703 W A00001/testTag: hello World <private>
08-05 12:21:47.579 2695-2703 A00001/testTag com.example.hilogDemo W hello World <private>
```
<!--RP5End-->
## hilog.error
@@ -187,17 +193,19 @@ Prints ERROR logs.
**Example**
This example is used to output an ERROR log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
This example is used to output an ERROR log with the format string being **"%{public}s World %{private}d"**. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
```js
hilog.error(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
```
If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
If **"hello"** is filled in **%{public}s** and **3** in **%{private}d**, the output log is as follows:
<!--RP6-->
```
08-05 12:21:47.579 2695 2703 E A00001/testTag: hello World <private>
08-05 12:21:47.579 2695-2703 A00001/testTag com.example.hilogDemo E hello World <private>
```
<!--RP6End-->
## hilog.fatal
@@ -220,17 +228,19 @@ Prints FATAL logs.
**Example**
This example is used to output a FATAL log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
This example is used to output a FATAL log with the format string being **"%{public}s World %{private}d"**. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
```js
hilog.fatal(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
```
If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
If **"hello"** is filled in **%{public}s** and **3** in **%{private}d**, the output log is as follows:
<!--RP7-->
```
08-05 12:21:47.579 2695 2703 F A00001/testTag: hello World <private>
08-05 12:21:47.579 2695-2703 A00001/testTag com.example.hilogDemo F hello World <private>
@@ -378,7 +378,7 @@ Defines parameters of subscription filtering conditions of a [Watcher](#watcher)
> **NOTE**
>
> In system events, address sanitizer events and task execution timeout events cannot be subscribed to in atomic services. Time-consuming launch events, frame loss events, high CPU load events, battery usage statistics events, and audio jank events cannot be subscribed to in atomic services and application clones.
> In system events, address sanitizer events and task execution timeout events cannot be subscribed to in atomic services. High CPU load events, battery usage statistics events, and audio jank events cannot be subscribed to in atomic services and application clones. Time-consuming launch events and frame loss events cannot be subscribed to in application clones.
## AppEventPackageHolder
@@ -759,14 +759,14 @@ Adds the configuration information of the data processor. The configuration file
| Name | Type | Mandatory| Description |
| --------- | ---------- | ---- | ------------- |
| processorName | string | Yes | <!--RP2-->Processor name, which can contain only letters, digits, underscores (_), and dollar signs ($). It cannot start with a digit and cannot exceed 256 characters.<!--RP2End-->|
| processorName | string | Yes | <!--RP2-->Name of a data processor. It can contain only letters, digits, underscores (_), and dollar signs ($). It cannot start with a digit and cannot exceed 256 characters.<!--RP2End-->|
| configName | string | No | <!--RP3-->Name of the data processor configuration. The corresponding configuration can be loaded from the configuration file. The default value is **SDK_OCG**. It can contain only letters, digits, underscores (_), and dollar signs ($). It cannot start with a digit and cannot exceed 256 characters.<!--RP3End-->|
**Return value**
| Type | Description |
| ------ | ---------------------- |
| Promise<number> | Promise that returns the unique ID of the added event data processor, which can be used to remove the data processor. If the adding fails, error code **11105001** is returned.|
| Promise<number> | Promise that returns the unique ID of the added event data processor, which can be used to remove the data processor. If the adding fails, error code **11105001** is returned.|
| -c/--recent-count | Maximum number of recent notifications stored in the memory.|
| -e/--enable-notification | Whether to enable the notification capability. |
| -k/--collaboration-switch | Whether notifications can be sent to devices of a specified type through cross-device collaboration.<br>`anm setting -k <deviceType>:<status>`<br>**Note**: This parameter is supported since API version 18.<br>**deviceType**: device type. The value can be **wearable**, **litewearable**, or **headset**.<br>**status**: status of the cross-device collaboration switch. The value **0** indicates that the cross-device collaboration is disabled, and the value **1** indicates the opposite.
| -k/--collaboration-switch | Whether notifications can be sent to devices of a specified type through cross-device collaboration.<br>`anm setting -k <deviceType>:<status>`<br>**Note**: This parameter is supported since API version 18.<br>**deviceType**: device type. The value can be **wearable**, **litewearable**, or **headset**.<br>**status**: status of the cross-device collaboration switch. The value **0** indicates that the cross-device collaboration is disabled, and the value **1** indicates the opposite.|
| -b/--collaboration-switch-bundle | Whether notifications of a specified bundle can be sent to devices of a specified type through cross-device collaboration.<br>`anm setting -b <deviceType>:<bundleName>:<uid>:<status>`<br>**Note**: This parameter is supported since API version 18.<br>**deviceType**: device type. The value can be **wearable**, **litewearable**, or **headset**.<br>**status**: status of the cross-device collaboration switch. The value **0** indicates that the cross-device collaboration is disabled, and the value **1** indicates the opposite.|
| -o/--collaboration-switch-slot | Whether notifications of a specified slot can be sent to devices of a specified type through cross-device collaboration.<br>`anm setting -o <deviceType>:<slotType>:<status>`<br>**Note**: This parameter is supported since API version 18.<br>**deviceType**: device type. The value can be **wearable**, **litewearable**, or **headset**.<br>**slotType**: notification slot type. For details about the value range, see [SlotType](../reference/apis-notification-kit/js-apis-notificationManager.md#slottype).<br>**status**: status of the cross-device collaboration switch. The value **0** indicates that the cross-device collaboration is disabled, and the value **1** indicates the opposite.|
| -h | Displays help information.| Commands supported by the **atm perm** command.|
| -h | Displays help information. Commands supported by the **atm perm** command.|
| -g -i \<token-id\> -p \<permission-name\> | Grants a specified permission to an application based on the token ID of the application process. The **-g**, **-i**, and **-p** parameters are mandatory. The return value indicates whether the operation is successful. |
| -c -i \<token-id\> -p \<permission-name\> | Cancels a specified permission for an application based on the token ID of the application process. The **-c**, **-i**, and **-p** parameters are mandatory. The return value indicates whether the operation is successful. |
@@ -547,9 +547,9 @@ The system account ID does not exist during bundle installation.
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
hdc file recv /data/log/hilog/
```
```shell
hdc file recv /data/log/hilog/
```
### 304 The HAP File Is Not Installed for the Current System Account
**Error Message**
@@ -800,9 +800,10 @@ When you start debugging or run an application, the error message "error: instal
c. Use the keytool (available in the **jbr/bin** folder of the DevEco Studio installation directory) to obtain the SHA-256 value of the certificate fingerprint from the .cer file:
```
keytool -printcert -file xxx.cer
```
```shell
keytool -printcert -file xxx.cer
```
d. Remove the colon from the SHA-256 content in the certificate fingerprint. What you get is the signature fingerprint.
The following figure shows an example.
@@ -814,25 +815,28 @@ When you start debugging or run an application, the error message "error: instal
2. Obtain the **install_list_capability.json** file of the device.
a. Connect to the device and enter the shell.
```
hdc shell
```
```shell
hdc shell
```
b. Run the following command to view the **install_list_capability.json** file of the device:
```
// Locate the file on the device.
find /system -name install_list_capability.json
```
```shell
// Locate the file on the device.
find /system -name install_list_capability.json
```
c. Run the following command to obtain the **install_list_capability.json** file:
3. Add the signature fingerprint obtained to **app_signature** in the **install_list_capability.json** file. Note that the signature fingerprint must be configured under the corresponding bundle name.
3. Add the UDID of the device to the **device-ids** field in the **UnsgnedDebugProfileTemplate.json** file.
@@ -1201,9 +1205,9 @@ During bundle installation or update, the token update API of the ability is cal
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
hdc file recv /data/log/hilog/
```
```shell
hdc file recv /data/log/hilog/
```
<!--Del-->
@@ -1263,7 +1267,7 @@ The SDK version used for build and packing does not match the device image versi
**Solution**
* Scenario 1: The device image version is earlier than the SDK version for build and packing. Update the device image version. Run the following command to query the device image version:
```
```bash
hdc shell param get const.ohos.apiversion
```
If the API version provided by the image is 10 and the SDK version used for bundle build is also 10, the possible cause is that the image version is too early to be compatible with the SDK verification rules of the new version. In this case, update the image version to the latest version.
@@ -1454,7 +1458,7 @@ The signature file is abnormal or the installation package is damaged.
**Solution**
Use [automatic signing](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V13/ide-signing-V13#section18815157237) or [manual signing](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V13/ide-signing-V13#section297715173233) to re-sign the bundle for installation and debugging.
Use [automatic signing](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-signing#section18815157237) or [manual signing](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-signing#section297715173233) to re-sign the bundle for installation and debugging.
### 9568325 Signature Verification Failed Due to Oversized File
**Error Message**
@@ -1527,9 +1531,9 @@ User 0 installs an application with the non-singleton permission.
**Solution**
1. If the bundle does not have the singleton permission, you can directly install the bundle without specifying a user.
```bash
hdc shell bm install -p /data/HAP name.hap
```
```bash
hdc shell bm install -p /data/HAP name.hap
```
### 9568263 Installation Version Cannot Be Downgraded
@@ -1676,7 +1680,7 @@ When the inter-bundle HSP is uninstalled, the specified bundle does not exist.
**Solution**
Check whether the inter-bundle HSP to be uninstalled exists.
```
```bash
hdc shell bm dump-shared -n com.xxx.xxx.demo
```
@@ -1717,14 +1721,14 @@ The installation fails because **isolationMode** of the bundle is not supported
**Solution**
1. Set the value of **isolationMode** in the HAP configuration file based on the isolation mode of the device.
```bash
# Query the value of persist.bms.supportIsolationMode. If errNum is:106 is returned, persist.bms.supportIsolationMode is not configured.
hdc shell
param get persist.bms.supportIsolationMode
# Set persist.bms.supportIsolationMode.
hdc shell
param set persist.bms.supportIsolationMode [true|false]
```
```bash
# Query the value of persist.bms.supportIsolationMode. If errNum is:106 is returned, persist.bms.supportIsolationMode is not configured.
hdc shell
param get persist.bms.supportIsolationMode
# Set persist.bms.supportIsolationMode.
hdc shell
param set persist.bms.supportIsolationMode [true|false]
```
### 9568310 The Compatibility Policies Are Different
@@ -1765,7 +1769,7 @@ An unknown system exception occurs.
2. If the installation still fails after the preceding steps are performed for three to five times, check whether a crash file containing **foundation** exists in the **/data/log/faultlog/faultlogger/** directory of the device.
```
```bash
hdc shell
cd /data/log/faultlog/faultlogger/
ls -ls
@@ -1773,7 +1777,7 @@ An unknown system exception occurs.
3. Export the crash file and log file and submit them to [online tickets](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
```bash
hdc file recv /data/log/faultlog/faultlogger/
hdc file recv /data/log/hilog/
```
@@ -1813,9 +1817,9 @@ The file copy operation fails during bundle installation.
2. Failed to open the source file.
3. Failed to obtain the source file status.
4. The size of the source file is invalid.
6. Failed to copy the source file.
7. You do not have the permission to access the source file.
8. Failed to change the file permission.
5. Failed to copy the source file.
6. You do not have the permission to access the source file.
7. Failed to change the file permission.
**Solution**
@@ -1823,9 +1827,9 @@ The file copy operation fails during bundle installation.
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
hdc file recv /data/log/hilog/
```
```bash
hdc file recv /data/log/hilog/
```
### 9568401 The Bundle to Debug Can Run Only on Devices in Developer Mode
**Error Message**
@@ -1871,9 +1875,9 @@ The installation fails because an exception occurs when the code signature confi
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
hdc file recv /data/log/hilog/
```
```bash
hdc file recv /data/log/hilog/
```
### 9568405 Failed to Delete the Signature Configuration File
@@ -1897,9 +1901,9 @@ The bundle fails to be uninstalled because the signature configuration file fail
2. If the uninstallation still fails after repeating the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
hdc file recv /data/log/hilog/
```
```bash
hdc file recv /data/log/hilog/
```
### 9568381 Failed to Delete the Application Process
**Error Message**
@@ -1954,6 +1958,11 @@ The bm tool process is abnormal or the permission is lost. As a result, the bm t
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568385 Service Uninstallation Exception
**Error Message**
@@ -1973,7 +1982,7 @@ An unknown system exception occurs.
2. If the installation still fails after the preceding steps are performed for three to five times, check whether a crash file containing **foundation** exists in the **/data/log/faultlog/faultlogger/** directory of the device.
```
```bash
hdc shell
cd /data/log/faultlog/faultlogger/
ls -ls
@@ -1981,7 +1990,7 @@ An unknown system exception occurs.
3. Export the crash file and log file and submit them to [online tickets](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
```bash
hdc file recv /data/log/faultlog/faultlogger/
hdc file recv /data/log/hilog/
```
@@ -2039,6 +2048,11 @@ The installation fails due to an unknown system error.
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568284 Installation Version Not Compatible
**Error Message**
@@ -2277,10 +2291,10 @@ The passed-in parameter is invalid or the passed-in directory is empty during th
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
# Export the log file.
hdc file recv /data/log/hilog/
```
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568351 Installation Failure Due to a File Directory Creation Exception
@@ -2302,10 +2316,10 @@ You do not have the write permission when creating a file directory.
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
# Export the log file.
hdc file recv /data/log/hilog/
```
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568354 Installation Failure Due to a File Directory Deletion Exception
@@ -2327,10 +2341,10 @@ The directory to be deleted does not exist, or you do not have the write permiss
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
# Export the log file.
hdc file recv /data/log/hilog/
```
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568355 Failed to Extract Files from the Installation Bundle
@@ -2352,10 +2366,10 @@ During the installation, the .so file fails to be extracted from the HAP file be
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
# Export the log file.
hdc file recv /data/log/hilog/
```
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568356 Failed to Rename a Directory During Installation
@@ -2377,10 +2391,10 @@ The directory name contains more than 260 characters, or you do not have the wri
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
# Export the log file.
hdc file recv /data/log/hilog/
```
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568357 Failed to Clear Files
**Error Message**
@@ -2401,10 +2415,10 @@ You do not have the write permission on the files to be cleared.
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
# Export the log file.
hdc file recv /data/log/hilog/
```
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568359 The SELinux Fails to be Installed and Set
@@ -2773,7 +2787,7 @@ The values of **pluginDistributionIDs** of the bundle and plugin are different.
**Solution**
Reconfigure **pluginDistributionIDs** in the <!--RP5-->[profile](../security/app-provision-structure.md)<!--RP5End--> of the application or plugin. The configuration format is as follows:
```
```json
"app-services-capabilities":{
"ohos.permission.kernel.SUPPORT_PLUGIN":{
"pluginDistributionIDs":"value-1,value-2,···"
@@ -2968,7 +2982,7 @@ The Bundle Binary Interface (ABI) supported by the device does not match that co
2. Run the [hdc command](#environment-requirements-hdc) to query ABIs supported on this device.
```
```bash
hdc shell
param get const.product.cpu.abilist
```
@@ -2976,7 +2990,7 @@ The Bundle Binary Interface (ABI) supported by the device does not match that co
<!--Del-->
* If the list includes only **default**, run the following command to check whether the **lib64** folder exists:
```
```bash
cd /system/
ls
```
@@ -3025,10 +3039,10 @@ The bundle manager or other services are abnormal.
2. If the installation still fails after you repeat the preceding steps three to five times, export the log file and submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#/) for help.
```
# Export the log file.
hdc file recv /data/log/hilog/
```
```bash
# Export the log file.
hdc file recv /data/log/hilog/
```
### 9568434 Plugin Capability Unavailable on Device
**Error Message**
@@ -3099,7 +3113,7 @@ The **pluginDistributionIDs** configuration in the plugin signature information
**Solution**
Reconfigure the **app-services-capabilities** field in <!--RP5-->[the profile](../security/app-provision-structure.md)<!--RP5End--> by referring to the following format:
@@ -35,7 +35,7 @@ The packaging tool verifies the validity of the attributes in the **module.json*
## Constraints
- The packing tool must run in Java 8 or later.
- Parameters and parameter values must be in pairs. For example, in the HAP packing command <b class="+ topic/ph hi-d/b " id="b11910162317201">--resources-path \<path></b>, <b class="+ topic/ph hi-d/b " id="b18184127152015">--resources-path</b> is the command parameter and <b class="+ topic/ph hi-d/b " id="b316819352201">path</b> is the parameter value. The two parameters must be used together.
- Parameters and parameter values must be in pairs. For example, in the HAP packing command **--resources-path \<path>**, **--resources-path** is the command parameter and **path** is the parameter value. The two parameters must be used together.
## HAP Packing Command
@@ -68,7 +68,7 @@ Packing command example:
| Name | Mandatory| Option | Description | Remarks |
| --json-path | Yes | NA | Path of the JSON file. The file name must be **config.json** in the FA model and **module.json** in the stage model.| NA |
| --json-path | Yes | NA | Path of the .json file. The file name must be **config.json** in the FA model and **module.json** in the stage model.| NA |
| --profile-path | No | NA | Path of the **CAPABILITY.profile** file. | NA |
| --maple-so-path | No | NA | Path of the Maple SO file. The file name extension must be .so. If there are multiple SO files, separate them with commas (,).| NA |
| --maple-so-dir | No | NA | Path of the maple SO directory (folder). | NA |
@@ -81,7 +81,7 @@ Packing command example:
| --js-path | No | NA | Path of the JS file. | This parameter is valid only in the stage model.|
| --ets-path | No | NA | Path of the ETS file. | This parameter is valid only in the stage model.|
| --out-path | Yes | NA | Path of the target file. The file name extension must be .hap. | NA |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. | NA |
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. | NA |
| --an-path | No | NA | Path of the [.an file](https://developer.huawei.com/consumer/en/doc/harmonyos-faqs-V5/faqs-arkts-52-V5).| This parameter is valid only in the stage model.|
| --ap-path | No | NA | Path of the [.ap file](https://developer.huawei.com/consumer/en/doc/harmonyos-faqs-V5/faqs-arkts-52-V5).| This parameter is valid only in the stage model.|
| --dir-list | No | NA | List of directories (folders) to be packed into the HAP file. | NA |
| --out-path | Yes | NA | Path of the target file. The file name extension must be .hsp. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. |
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. |
| --compress-level | No | number | Compress level of files in the **lib** library. The default value is **1**. The value ranges from 1 to 9. This parameter is valid only when **compressNativeLibs** is set to **true**. A larger value indicates a higher compression rate and a slower compression speed.|
| --pkg-context-path | No | NA | Path of the **pkgContextInfo.json** file, which contains the context information. This parameter is mandatory when **bundleType** in the **app.json5** configuration file is not set to **appPlugin** and **requestPermissions** in the **module.json5** configuration file contains **"ohos.permission.kernel.SUPPORT_PLUGIN"**.|
| --signature-path | No | NA | Path of the signature file. |
| --certificate-path | No | NA | Path of the certificate file. |
| --pack-res-path | No | NA | Path of the **pack.res** file. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. |
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. |
| --encrypt-path | No | NA | The file name must be **encrypt.json**. |
| --pac-json-path | No | NA | <!--RP1-->Path of the **pac.json**<!--RP1End--> file. The file name must be **pac.json**.<br>This parameter is supported since API version 20.|
| --atomic-service-entry-size-limit | No | NA | Size limit of the entry package (including the size of the dependency package) of the atomic service. This parameter is valid only in the stage model and **bundleType** is set to **atomicService**. The value is an integer ranging from 0 to 4194304, in KB. The value **0** indicates that the size is not limited. If this parameter is not set, the default value **2048 KB** is used. If the entry package is in release mode (the **type** field in the **module.json5** file is set to **entry** and the **debug** field in the **app.json5** file is set to **false**), this limit applies to the compressed entry package size (including the size of the dependency package) during APP packing. |
| --hsp-list | No | Path of the HSP files | Path of the HSP files. The file name extension must be .hsp. If there are multiple HSP files, separate them with commas (,).<br>The value can also be the directory (folder) where the HSP files are stored. |
| --app-list | No | Path of the APP files | Path of the APP files. The file name extension must be .app. If there are multiple APP files, separate them with commas (,).<br>The value can also be the directory (folder) where the APP files are stored.<br>You must specify **--hap-list**, **--hsp-list**, or **--app-list**, or any of their combinations.|
| --out-path | Yes | NA | Path of the target file. The file name extension must be .app.|
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. |
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. |
| --encrypt-path | No | Path of **encrypt.json**| The file name must be **encrypt.json**. |
| --pac-json-path | No | NA | <!--RP1-->Path of the **pac.json**<!--RP1End--> file. The file name must be **pac.json**.<br>If this parameter is not set, the app product does not contain the **pac.json** file.<br>The **pac.json** file in the APP file specified by **--app-list** is not packed into the final app.<br>This parameter is supported since API version 20.|
| --atomic-service-entry-size-limit | No | NA | Size limit of the entry package (including the size of the dependency package) of the atomic service. This parameter is valid only in the stage model and **bundleType** is set to **atomicService**. The value is an integer ranging from 0 to 4194304, in KB. The value **0** indicates that the size is not limited. If this parameter is not set, the default value **2048 KB** is used. If the entry package is in release mode (the **type** field in the **module.json5** file is set to **entry** and the **debug** field in the **app.json5** file is set to **false**), this limit applies to the compressed entry package size (including the size of the dependency package) during APP packing. |
| --resources-path | No | NA | Path of the resources file. |
| --out-path | Yes | NA | Path of the target file. The file name extension must be .hqf. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking.|
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists.|
| --hqf-list | Yes | NA | Path of the [HQF file](packing-tool.md#hqf-packing-command). Use commas (,) to separate multiple HQF files. |
| --out-path | Yes | NA | Path of the target file. The file name extension must be .appqf. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking.|
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists.|
| --input-list | Yes | Path of the HAP or HSP files | 1. Path of the HAP or HSP files. The file name extension must be .hap or .hsp. Use commas (,) to separate the paths of multiple HAP or HSP files.<br>2. The value can also be the directory (folder) where the HAP and HSP files are stored. If this is the case, all HAP and HSP files in the directory (folder) are read.|
| --bundle-name | No | Bundle name | New bundle name, to which the passed-in bundle name will be changed. The value cannot be empty. For details about the definition and specifications of this field, see the <b class="+ topic/ph hi-d/b " id="b14907122752517">bundleName</b> field in [app.json5](../quick-start/app-configuration-file.md#tags-in-the-configuration-file).|
| --bundle-name | No | Bundle name | New bundle name, to which the passed-in bundle name will be changed. The value cannot be empty. For details about the definition and specifications of this field, see the **bundleName** field in [app.json5](../quick-start/app-configuration-file.md#tags-in-the-configuration-file).|
| --version-code | No | Internal version number | New version number, to which the passed-in version number will be changed. The value is an integer ranging from 0 to 2147483647. The value cannot be empty. For details about the definition and specifications of this field, see the **versionCode** field in [app.json5](../quick-start/app-configuration-file.md#tags-in-the-configuration-file).|
| --version-name | No | Version name | Version name. The version name of the input package will be changed to this version name. The value cannot be empty. For details about the definition and specifications of this field, see the **versionName** field in [app.json5](../quick-start/app-configuration-file.md#tags-in-the-configuration-file).|
| --min-compatible-version-code | No | Earliest compatible version number | New earliest compatible version number, to which the passed-in earliest compatible version number will be changed. The value is an integer ranging from 0 to 2147483647 and cannot be empty. For details about the definition and specifications of this field, see the **minCompatibleVersionCode** field in [app.json5](../quick-start/app-configuration-file.md#tags-in-the-configuration-file).|
| --entrycard-path | Yes | NA | Path of the **pack.res** file. |
| --pack-info-path | Yes | NA | Path of the **pack.info** file. |
| --out-path | Yes | NA | Path of the target file. The file name extension must be .res. |
| --force | No | true or false | The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking.|
| --force | No | true or false | The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists.|
| --mode | Yes | fastApp | Packing mode. Each HAP file to pack into the APP file must pass the validity check. |
| --hap-path | No | NA | Path of the HAP file directory, which contains all files of the HAP. If there are multiple HAP file directories, separate them with commas (,). |
| --hsp-path | No | NA | 1. Path of the HSP files. The file name extension must be .hsp. If there are multiple HSP files, separate them with commas (,).<br>2. Path of the HSP file directory, which contains all files of the HSP. If there are multiple HSP file directories, separate them with commas (,).|
| --hap-path | No | NA | Path of the HAP file directory, which contains all files of the HAP. If there are multiple HAP file paths, separate them with commas (,). |
| --hsp-path | No | NA | 1. Path of the HSP files. The file name extension must be .hsp. If there are multiple HSP files, separate them with commas (,).<br>2. Path of the HSP file directory, which contains all files of the HSP. If there are multiple HAP file paths, separate them with commas (,).|
| --pack-info-path | Yes | NA | Path of the **pack.info** file. The file name must be **pack.info**. |
| --out-path | Yes | NA | Path of the target file. The file name extension must be .app. |
| --signature-path | No | NA | Path of the signature file. |
| --certificate-path | No | NA | Path of the certificate file. |
| --pack-res-path | No | NA | Path of the **pack.res** file. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. |
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. |
| --encrypt-path | No | NA | The file name must be **encrypt.json**. |
| --pac-json-path | No | NA | <!--RP1-->Path of the **pac.json**<!--RP1End--> file. The file name must be **pac.json**.<br>This parameter is supported since API version 20.|
| --atomic-service-entry-size-limit | No | NA | Size limit of the entry package (including the size of the dependency package) of the atomic service. This parameter is valid only in the stage model and **bundleType** is set to **atomicService**. The value is an integer ranging from 0 to 4194304, in KB. The value **0** indicates that the size is not limited. If this parameter is not set, the default value **2048 KB** is used. If the entry package is in release mode (the **type** field in the **module.json5** file is set to **entry** and the **debug** field in the **app.json5** file is set to **false**), this limit applies to the compressed entry package size (including the size of the dependency package) during APP packing. |
@@ -642,7 +642,7 @@ When the [bundleType](../quick-start/app-configuration-file.md#tags-in-the-confi
1. There are more than two [HSP files](../quick-start/in-app-hsp.md). For example, as shown in the following figure, when DevEco Studio is used to build an app, the project contains two HSP files **library** and **library1**. In this case, the APP file fails to be packed.
The rawheap-file size and generation time are strongly and positively correlated with the current ArkTS heap size and the number of live objects. When the ArkTS heap memory usage is high and the number of live objects is large, the generated rawheap file is larger and the generation takes longer. You can subscribe to the [resource leak events](../dfx/hiappevent-watcher-resourceleak-events.md) and customize the event processing logic.
Since API version 20, the VM supports two specifications of heap dump.
Since API version 20, the VM supports two specifications of heap dump. For details about how to switch between the specifications, see [hidebug.setJsRawHeapTrimLevel](../reference/apis-performance-analysis-kit/js-apis-hidebug.md#hidebugsetjsrawheaptrimlevel20)
| Specifications| Features|
| :--- | :--- |
| TRIM_LEVEL_1 | The dump speed is fast, and the generated rawheap file is large.<br>Before API version 20, the VM uses **TRIM_LEVEL_1** by default.|
@@ -15,7 +15,7 @@ restool is a resource compilation tool that creates resource indexes and parses
| -j | No| Yes| Path of the **config.json** or **module.json** file.|
| -o | No| Yes| Output path of the compiled resource.|
| -p | No| Yes| Bundle name of the compiled resource.|
| -r | No| Yes| Output path of the header file of the resource. The file contains the mapping between resource names and resource IDs. The file can be in **.txt**, **.js**, or **.h** format.<br>**NOTE**<br>- The files contain the resource mapping tables in all resource directories specified by **-i**.|
| -r | No| Yes| Output path of the header file of the resource. The file contains the mapping between resource names and resource IDs. The file can be in **.txt**, **.js**, or **.h** format.<br>**NOTE**<br> The file contains the resource mapping tables in all resource directories specified by **-i**.|
| -e | Yes| Yes| Start ID of the generated resource, for example, **0x01000000**. The value range is [0x01000000, 0x06FFFFFF) and [0x08000000, 0x41FFFFFF).|
| -f | Yes| No| An existing output path will be forcibly deleted and a new one will be generated.|
| -h | Yes| No| Help information.|
@@ -26,9 +26,9 @@ restool is a resource compilation tool that creates resource indexes and parses
| --ids | Yes| Yes| Output directory of the generated **id_defined.json** file.|
| --defined-ids | Yes| Yes| Path of the **id_defined.json** file. Generally, the file is generated by using **--ids**.<br>**id_defined.json** contains a list of resource types, names, and IDs.<br>You can customize resource IDs in **id_defined.json**.|
| --icon-check | Yes| No| Whether to enable PNG image verification for icons and startWindowIcons.|
| --thread | Yes| Yes| Number of child threads enabled during resource compilation.<br>**Note**: This option is supported since API version 18.|
| --thread | Yes| Yes| Number of child threads enabled during resource compilation.<br>**NOTE**<br> This option is supported since API version 18.|
| --target-config | Yes| Yes| Used together with the **-i** command to support compilation selection.<br>For details, see **target-config Parameters**.|
| --ignored-file | Yes| Yes| Ignoring rule for resource files and resource directories. The value is a regular expression. Multiple rules are separated by colons. Files and directories whose names match the regular expression are ignored.<br>For example, **\\.git:\\.svn** can ignore all files and directories whose names contain **.git** and **.svn**.<br>**Note**: This option is supported since API version 19.|
| --ignored-file | Yes| Yes| Ignoring rule for resource files and resource directories. The value is a regular expression. Multiple rules are separated by colons. Files and directories whose names match the regular expression are ignored.<br>For example, **\\.git:\\.svn** can ignore all files and directories whose names contain **.git** and **.svn**.<br>**NOTE**<br> This option is supported since API version 19.|
**target-config** Parameters
@@ -56,7 +56,7 @@ Example: Locale[zh_CN,en_US];Device[phone]. This configuration uses the language
**dump**
```
```sh
restool dump [-h] [config] filePath
```
@@ -79,7 +79,7 @@ restool dump config entry.hap
## Example
An example **entry** directory structure is as follows:
```
```text
entry/src/main
| |----resource
| | |----base
@@ -97,7 +97,7 @@ There are three resource compilation modes: full resource compilation, increment
1. To compile all resources, run the following command:
@@ -997,7 +997,7 @@ The **order** value in the **id_defined.json** file is inconsistent with the dec
The **order** value in the **id_defined.json** file is incorrect. The following is an incorrect example:
```
```json
{
"startId": "0x07800000",
"record": [
@@ -1202,7 +1202,7 @@ The **parent** value of the **theme** resource is empty.
**Possible Causes**
The **parent** property of the **theme** resource is optional. Its value must be the name of another **theme** resource and cannot be an empty string. The following is a correct example:
```
```json
{
"theme": [
{
@@ -1290,7 +1290,7 @@ The plural resource type is duplicate.
**Possible Causes**
The same type is declared repeatedly in the plural resource. For example, the **one** type is declared repeatedly for **eat_apple** in the following error example:
| --rpcid | No | true or false| Whether to extract the rpcid file from the HAP file to a specified directory. If the value is **true**, only the rpcid file is extracted and the HAP file is not unpacked.|
| --out-path | Yes | NA | Path of the target files. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. |
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. |
| --out-path | Yes | NA | Path of the target files. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking.|
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists.|
| --rpcid | No | true or false| Whether to extract the rpcid file from the HAP file to a specified directory. If the value is **true**, only the rpcid file is extracted and the HAP file is not unpacked.|
| --hap-path | Yes | NA | Path of the HAP file. |
| --out-path | Yes | NA | Path of the target rpcid file. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. |
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. |
### Unpacking HAP Files Based on the Architecture Type
| --out-path | Yes | NA | Path of the target files. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. |
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. |
| --libs | No | true or false| Whether to unpack HAP files based on the architecture type of the **libs** directory. The value **true** indicates that HAP files are unpacked based on the architecture type.|
| --cpu-abis | No | NA | Architecture type of the **libs** to be unpacked. You can specify multiple architecture types and use commas (,) to separate them. This parameter does not take effect when **--libs** is set to **false**.|
| --out-path | Yes | NA | Path of the target files. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking.|
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists.|
### Unpacking HSP Files Based on the Architecture Type
| --out-path | Yes | NA | Path of the target files. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking. |
| --libs | No | true or false| Whether to unpack HAP files based on the architecture type of the **libs** directory. The value **true** indicates that HAP files are unpacked based on the architecture type.|
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists. |
| --libs | No | true or false| Whether to unpack HSP files based on the architecture type of the **libs** directory. The value **true** indicates that HSP files are unpacked based on the architecture type.|
| --cpu-abis | No | NA | Architecture type of the **libs** to be unpacked. You can specify multiple architecture types and use commas (,) to separate them. This parameter does not take effect when **--libs** is set to **false**.|
| --appqf-path | Yes | NA | Path of the APPQF package. |
| --out-path | Yes | NA | Path of the target files. |
| --force | No | true or false| The default value is **false**. If the value is **true**, an existing target file will be forcibly deleted during unpacking.|
| --force | No | true or false| The default value is **false**. If the value is **true**, the target file is forcibly deleted when it exists.|
## Package Parsing APIs
@@ -251,7 +251,7 @@ The package parsing APIs are used by the application market to parse an HAP, HSP
| defPermissionsGroups | List\<DefPermissionsGroups> | Default permission groups of the HAP. | NA |
| distro | Distro struct | Distro description of the HAP file. | NA |
| reqCapabilities | List\<String> | Required capabilities of the HAP. | NA |
| deviceType | List\<String> | Type of devices on which the HAP can run. This field corresponds to **deviceTypes** in the stage model. |
| deviceType | List\<String> | Type of devices on which the HAP can run. This field corresponds to **deviceTypes** in the stage model. | NA |
| metaData | metaData struct (see **metaData Struct** below)| Custom metadata of the HAP. | NA |
| dependencies | List\<DependencyItem> | Dependencies of the HAP. | NA |
| isJs | boolean | Whether the application is a JS application. The value **true** indicates that the application is a JS application, and **false** indicates the opposite. | This field is unique to the FA model. |
@@ -566,7 +566,7 @@ The package parsing APIs are used by the application market to parse an HAP, HSP
> 从API version 9开始支持,从API version 10开始废弃,建议使用[AccessibilityExtensionContext.injectGestureSync](#accessibilityextensioncontextinjectgesturesyncdeprecated)替代。
> 从API version 9开始支持,从API version 10开始废弃,建议使用[AccessibilityExtensionContext.injectGestureSync](#accessibilityextensioncontextinjectgesturesyncdeprecated)替代。
| SURFACE | 用于EGL/OpenGLES和媒体数据写入,单独展示开发者定制的绘制内容到屏幕上。背景色设置为黑色时走显示子系统(DSS)。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
| COMPONENT<sup>(deprecated)</sup> | 使用XComponent作为容器组件,支持在其中执行非UI逻辑以动态加载显示内容。<br/>**说明:**<br/>从API version 12开始,该接口废弃,建议使用其他容器组件替代。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
| COMPONENT<sup>(deprecated)</sup> | 使用XComponent作为容器组件,支持在其中执行非UI逻辑以动态加载显示内容。<br/>**说明:**<br/>从API version 10开始支持,从API version 12开始废弃,建议使用其他容器组件替代。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
| TEXTURE | 用于EGL/OpenGLES和媒体数据写入,开发者定制的绘制内容将与XComponent组件的内容合成后展示到屏幕上。1、保持帧同步,保持在同一帧将图形处理器(GPU)纹理和ArkUI其他的绘制指令统一发给渲染服务(RenderService)。2、动效和系统组件统一。3、走图形处理器(GPU)合成,相比surface可能走显示子系统(DSS)功耗更高。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
| NODE<sup>(deprecated)</sup> | 用于Native UI节点的占位容器,开发者通过Native接口开发的页面组件可展示在此容器区域内。<br/>**说明:**<br/>从API version 20开始,该接口废弃,推荐使用[ContentSlot](../../../ui/rendering-control/arkts-rendering-control-contentslot.md)组件替代。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
| NODE<sup>(deprecated)</sup> | 用于Native UI节点的占位容器,开发者通过Native接口开发的页面组件可展示在此容器区域内。<br/>**说明:**<br/>从API version 12开始支持,从API version 20开始废弃,推荐使用[ContentSlot](../../../ui/rendering-control/arkts-rendering-control-contentslot.md)组件替代。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
| Auto | 2 |API version 9之前:窗口宽度>=520vp时,采用Split模式显示;窗口宽度<520vp时,采用Stack模式显示。<br/>API version 10及以上:窗口宽度>=600vp时,采用Split模式显示;窗口宽度<600vp时,采用Stack模式显示,600vp等于minNavBarWidth(240vp) + minContentWidth (360vp)。 |
Thank you for your continuous support to the Openl Qizhi Community AI Collaboration Platform. In order to protect your usage rights and ensure network security, we updated the Openl Qizhi Community AI Collaboration Platform Usage Agreement in January 2024. The updated agreement specifies that users are prohibited from using intranet penetration tools. After you click "Agree and continue", you can continue to use our services. Thank you for your cooperation and understanding.