diff --git a/en/application-dev/quick-start/application-package-update.md b/en/application-dev/quick-start/application-package-update.md new file mode 100644 index 0000000000000000000000000000000000000000..0137bc47e7ad78345da1128cf423e445d8456f97 --- /dev/null +++ b/en/application-dev/quick-start/application-package-update.md @@ -0,0 +1,5 @@ +# Application Package Update Process +The OpenHarmony bundle manager service allows application packages to be updated under the following scenarios: + +1. In the application market: The application market notifies the user of an available update, and the user can install the update by following the onscreen instructions. +2. In the application: When the application for which an update is available starts up, the application market notifies the user of the update, and the user can install the update by following the onscreen instructions. diff --git a/en/application-dev/quick-start/figures/quick-fix-debug.png b/en/application-dev/quick-start/figures/quick-fix-debug.png new file mode 100644 index 0000000000000000000000000000000000000000..4e7084f30e2d2b26be811c8b8a6c9ec34a005c9e Binary files /dev/null and b/en/application-dev/quick-start/figures/quick-fix-debug.png differ diff --git a/en/application-dev/quick-start/figures/quick-fix-devel_release.png b/en/application-dev/quick-start/figures/quick-fix-devel_release.png new file mode 100644 index 0000000000000000000000000000000000000000..34b701fafe5d319da6b552c5d86305151e8e28b3 Binary files /dev/null and b/en/application-dev/quick-start/figures/quick-fix-devel_release.png differ diff --git a/en/application-dev/quick-start/figures/quick_fix_bundle_struct.png b/en/application-dev/quick-start/figures/quick_fix_bundle_struct.png new file mode 100644 index 0000000000000000000000000000000000000000..730414e3ba2fccbb58a27f83ce1afc572544f366 Binary files /dev/null and b/en/application-dev/quick-start/figures/quick_fix_bundle_struct.png differ diff --git a/en/application-dev/quick-start/figures/quick_fix_gen_abc.png b/en/application-dev/quick-start/figures/quick_fix_gen_abc.png new file mode 100644 index 0000000000000000000000000000000000000000..3e549ec79cad4a76a55ccab4dbb769b756d9936a Binary files /dev/null and b/en/application-dev/quick-start/figures/quick_fix_gen_abc.png differ diff --git a/en/application-dev/quick-start/figures/quick_fix_gen_so.png b/en/application-dev/quick-start/figures/quick_fix_gen_so.png new file mode 100644 index 0000000000000000000000000000000000000000..31717ca38c7e64983b9b3c95672fe966decf6945 Binary files /dev/null and b/en/application-dev/quick-start/figures/quick_fix_gen_so.png differ diff --git a/en/application-dev/quick-start/module-configuration-file.md b/en/application-dev/quick-start/module-configuration-file.md index 67361fccfd749495e2f5825d5ccac6efe1505ed9..2f308d7e5936d4fd62fbf5c22cee827e7bbc38a4 100644 --- a/en/application-dev/quick-start/module-configuration-file.md +++ b/en/application-dev/quick-start/module-configuration-file.md @@ -72,7 +72,7 @@ As shown above, the **module.json5** file contains several tags. | Name| Description| Data Type| Initial Value Allowed| | -------- | -------- | -------- | -------- | | name | Name of the module. The value is a string with a maximum of 31 bytes and must be unique in the entire application. Chinese characters are not allowed.| String| No| -| type | Type of the module. The value can be **entry** or **feature**.
- **entry**: main module of the application.
- **feature**: dynamic feature module of the application.| String| No| +| type | Type of the module. The options are as follows:
- **entry**: main module of the application.
- **feature**: dynamic feature module of the application.
- **har**: static shared module.
- **shared**: dynamic shared module.| String| No| | srcEntry | Code path corresponding to the module. The value is a string with a maximum of 127 bytes.| String| Yes (initial value: left empty)| | description | Description of the module. The value is a string with a maximum of 255 bytes or a string resource index.| String| Yes (initial value: left empty)| | process | Process name of the current module. The value is a string with a maximum of 31 bytes. If **process** is configured under **HAP**, all UIAbility, DataShareExtensionAbility, and ServiceExtensionAbility components of the application run in the specified process.
**NOTE**
This tag applies only to system applications and does not take effect for third-party applications.| String| Yes (initial value: value of **bundleName** under **app** in the **app.json5** file)| @@ -150,7 +150,7 @@ Define the **main_pages.json** file under **resources/base/profile** in the deve The **metadata** tag represents the custom metadata of the HAP file. The tag value is an array and contains three subtags: **name**, **value**, and **resource**. - **Table 3** metadata +**Table 3** metadata | Name| Description| Data Type| Initial Value Allowed| | -------- | -------- | -------- | -------- | @@ -210,9 +210,10 @@ Touching this icon will direct the user to the application details screen in **S To hide an application icon from the home screen, you must configure the **AllowAppDesktopIconHide** privilege. For details, see [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md). + **Setting the application icon to be displayed on the home screen**: -Set **icon**, **label**, and **skills** under **abilities** in the **module.json5** file. In addition, the **skills** configuration must contain **ohos.want.action.home **and **entity.system.home**. +Set **icon**, **label**, and **skills** under **abilities** in the **module.json5** file. In addition, make sure the **skills** configuration contains **ohos.want.action.home** and **entity.system.home**. ``` { @@ -284,7 +285,7 @@ Set **icon**, **label**, and **skills** under **abilities** in the **module.json | removeMissionAfterTerminate | Whether to remove the relevant task from the task list after the UIAbility component is destroyed.
- **true**: Remove the relevant task from the task list after the UIAbility component is destroyed.
- **false**: Do not remove the relevant task from the task list after the UIAbility component is destroyed.| Boolean| Yes (initial value: **false**)| | orientation | Orientation of the UIAbility component when it is started. The options are as follows:
- **unspecified**: automatically determined by the system.
- **landscape**: landscape mode.
- **portrait**: portrait mode.
- **landscape_inverted**: inverted landscape mode.
- **portrait_inverted**: inverted portrait mode.
- **auto_rotation**: determined by the sensor.
- **auto_rotation_landscape**: determined by the sensor in the horizontal direction, including landscape and inverted landscape modes.
- **auto_rotation_portrait**: determined by the sensor in the vertical direction, including portrait and inverted portrait modes.
- **auto_rotation_restricted**: determined by the sensor when the sensor switch is enabled.
- **auto_rotation_landscape_restricted**: determined by the sensor in the horizontal direction, including landscape and inverted landscape modes, when the sensor switch is enabled.
- **auto_rotation_portrait_restricted**: determined by the sensor in the vertical direction, including portrait and inverted portrait modes, when the sensor switch is enabled.
- **locked**: auto rotation disabled.| String| Yes (initial value: **"unspecified"**)| | supportWindowMode | Window mode supported by the UIAbility component. The options are as follows:
- **fullscreen**: full-screen mode.
- **split**: split-screen mode.
- **floating**: floating window mode.| String array| Yes (initial value:
["fullscreen", "split", "floating"])| -| priority | Priority of the UIAbility component. This attribute applies only to system applications and does not take effect for third-party applications. In the case of [implicit query](../application-models/explicit-implicit-want-mappings.md), UIAbility components with a higher priority are at the higher place of the returned list. The value is an integer ranging from 0 to 10. The greater the value, the higher the priority.| Number| Yes (initial value: **0**)| +| priority | Priority of the UIAbility component. In the case of [implicit query](../application-models/explicit-implicit-want-mappings.md), UIAbility components with a higher priority are at the higher place of the returned list. The value is an integer ranging from 0 to 10. The greater the value, the higher the priority.
**NOTE**
This tag applies only to system applications and does not take effect for third-party applications.| Number| Yes (initial value: **0**)| | maxWindowRatio | Maximum aspect ratio supported by the UIAbility component. The minimum value is 0.| Number| Yes (initial value: maximum aspect ratio supported by the platform)| | minWindowRatio | Minimum aspect ratio supported by the UIAbility component. The minimum value is 0.| Number| Yes (initial value: minimum aspect ratio supported by the platform)| | maxWindowWidth | Maximum window width supported by the UIAbility component, in vp. The minimum value is 0, and the value cannot be less than the value of **minWindowWidth** or greater than the maximum window width allowed by the platform. For details about the window size, see [Constraints](../windowmanager/window-overview.md#constraints).| Number| Yes (initial value: maximum window width supported by the platform)| @@ -396,22 +397,22 @@ Example of the **skills** structure: } ``` -**Enhance implicit query** +**Enhanced implicit query** URI-level prefix matching is supported. -When only **scheme** or a combination of **scheme** and **host** or **scheme**, **host**, and **port** are configured in the configuration file, the configuration is successful if the URI prefixed with the configuration file is passed in. +When only **scheme** or a combination of **scheme** and **host** or **scheme**, **host**, and **port** are configured in the configuration file, the configuration is successful if a URI prefixed with the configuration file is passed in. * The query enhancement involves the following APIs: [@ohos.bundle.bundleManager](../reference/apis/js-apis-bundleManager.md#bundlemanagerqueryabilityinfo)
- 1. function queryAbilityInfo(want: Want, abilityFlags: number, callback: AsyncCallback>): void;
- 2. function queryAbilityInfo(want: Want, abilityFlags: number, userId: number, callback: AsyncCallback>): void;
- 3. function queryAbilityInfo(want: Want, abilityFlags: number, userId?: number): Promise>; + 1. function queryAbilityInfo(want: Want, abilityFlags: number, callback: AsyncCallback>): void;
+ 2. function queryAbilityInfo(want: Want, abilityFlags: number, userId: number, callback: AsyncCallback>): void;
+ 3. function queryAbilityInfo(want: Want, abilityFlags: number, userId?: number): Promise>; * Configuration requirements
abilities -> skills -> uris object
Configuration 1: only **scheme = 'http'**
- Configuration 2: only **(scheme = 'http' ) + ( host = 'example.com')**
- Configuration 3: only **(scheme = 'http' ) + ( host = 'example.com' ) + ( port = '8080')**
+ Configuration 2: only **(scheme = 'http') + (host = 'example.com')**
+ Configuration 3: only **(scheme = 'http') + (host = 'example.com') + (port = '8080')** * Prefix match
If the value of **uri** under [want](../application-models/want-overview.md) is obtained by calling the **queryAbilityInfo** API: 1. uri = 'https://': No matches
@@ -429,8 +430,6 @@ When only **scheme** or a combination of **scheme** and **host** or **scheme**, 13. uri = 'http://example.com:9180/path': Matches configuration 1 and configuration 2
14. uri = 'http://example.com:8080/path': Matches configuration 1, configuration 2, and configuration 3
- - ## extensionAbilities The **extensionAbilities** tag represents the configuration of extensionAbilities, which is valid only for the current extensionAbility. @@ -446,8 +445,8 @@ The **extensionAbilities** tag represents the configuration of extensionAbilitie | label | Name of the ExtensionAbility component displayed to users. The value is a string resource index.
**NOTE**
If **ExtensionAbility** is set to **MainElement** of the current module, this attribute is mandatory and its value must be unique in the application.| String| No| | type | Type of the ExtensionAbility component. The options are as follows:
- **form**: ExtensionAbility of a widget.
- **workScheduler**: ExtensionAbility of a Work Scheduler task.
- **inputMethod**: ExtensionAbility of an input method.
- **service**: service component running in the background.
- **accessibility**: ExtensionAbility of an accessibility feature.
- **dataShare**: ExtensionAbility for data sharing.
- **fileShare**: ExtensionAbility for file sharing.
- **staticSubscriber**: ExtensionAbility for static broadcast.
- **wallpaper**: ExtensionAbility of the wallpaper.
- **backup**: ExtensionAbility for data backup.
- **window**: ExtensionAbility of a window. This type of ExtensionAbility creates a window during startup for which you can develop the GUI. The window is then combined with other application windows through **abilityComponent**.
- **thumbnail**: ExtensionAbility for obtaining file thumbnails. You can provide thumbnails for files of customized file types.
- **preview**: ExtensionAbility for preview. This type of ExtensionAbility can parse the file and display it in a window. You can combine the window with other application windows.
- **print**: ExtensionAbility for the print framework.
**NOTE**
The **service** and **dataShare** types apply only to system applications and do not take effect for third-party applications.| String| No| | permissions | Permissions required for another application to access the ExtensionAbility component.
The value is generally in the reverse domain name notation and contains a maximum of 255 bytes. It is an array of permission names predefined by the system or customized. The name of a customized permission must be the same as the **name** value of a permission defined in the **defPermissions** attribute.| String array| Yes (initial value: left empty)| -| uri | Data URI provided by the ExtensionAbility component. The value is a string with a maximum of 255 bytes, in the reverse domain name notation.
**NOTE**
This attribute is mandatory when **type** of the ExtensionAbility component is set to **dataShare**.| String| Yes (initial value: left empty)| -|skills | Feature set of [wants](../application-models/want-overview.md) that can be received by the ExtensionAbility component.
Configuration rule: In an entry package, you can configure multiple **skills** attributes with the entry capability. (A **skills** attribute with the entry capability is the one that has **ohos.want.action.home** and **entity.system.home** configured.) The **label** and **icon** in the first ExtensionAbility that has **skills** configured are used as the **label** and **icon** of the entire OpenHarmony service/application.
**NOTE**
The **skills** attribute with the entry capability can be configured for the feature-type package of an OpenHarmony application,
but not for an OpenHarmony service.| Array| Yes (initial value: left empty)| +| uri | Data URI provided by the ExtensionAbility component. The value is a string with a maximum of 255 bytes, in the reverse domain name notation.
**NOTE**
This attribute is mandatory when the type of the **ExtensionAbility** component is set to **dataShare**. | String| Yes (initial value: left empty)| +|skills | Feature set of [wants](../application-models/want-overview.md) that can be received by the ExtensionAbility component.
Configuration rule: In an entry package, you can configure multiple **skills** attributes with the entry capability. (A **skills** attribute with the entry capability is the one that has **ohos.want.action.home** and **entity.system.home** configured.) The **label** and **icon** in the first ExtensionAbility that has **skills** configured are used as the **label** and **icon** of the entire OpenHarmony service/application.
**NOTE**
The **skills** attribute with the entry capability can be configured for the feature-type package of an OpenHarmony application, but not for an OpenHarmony service. | Array| Yes (initial value: left empty)| | [metadata](#metadata)| Metadata of the ExtensionAbility component.| Object| Yes (initial value: left empty)| | exported | Whether the ExtensionAbility component can be called by other applications.
- **true**: The ExtensionAbility component can be called by other applications.
- **false**: The UIAbility component cannot be called by other applications.| Boolean| Yes (initial value: **false**)| @@ -540,7 +539,7 @@ The **shortcut** information is identified in **metadata**, where: | shortcutId | ID of the shortcut. The value is a string with a maximum of 63 bytes.| String| No| | label | Label of the shortcut, that is, the text description displayed for the shortcut. The value can be a string or a resource index to the label, with a maximum of 255 bytes.| String| Yes (initial value: left empty)| | icon | Icon of the shortcut. The value is an icon resource index.| String| Yes (initial value: left empty)| -| [wants](../application-models/want-overview.md) | Wants to which the shortcut points. Each want consists of the **bundleName** and **abilityName** sub-attributes.
**bundleName**: target bundle name of the shortcut. The value is a string.
**abilityName**: target component name of the shortcut. The value is a string.| Object| Yes (initial value: left empty)| +| [wants](../application-models/want-overview.md) | Wants to which the shortcut points. Each want consists of the **bundleName** and **abilityName** sub-attributes.
- **bundleName**: target bundle name of the shortcut. The value is a string.
- **abilityName**: target component name of the shortcut. The value is a string.| Object| Yes (initial value: left empty)| 1. Configure the **shortcuts_config.json** file in **/resource/base/profile/**. @@ -699,7 +698,7 @@ Configure **metadata** in the **module** tag in the **module.json5** file. The **testRunner** tag represents the supported test runner. - **Table 14** testRunner +**Table 14** testRunner | Name| Description| Data Type| Initial Value Allowed| | -------- | -------- | -------- | -------- | diff --git a/en/application-dev/quick-start/module-structure.md b/en/application-dev/quick-start/module-structure.md index e4aee36db107109fcaa7e6d068cbc907009c69d4..352a993d5042116105ef5c50ae9138df51c622c9 100644 --- a/en/application-dev/quick-start/module-structure.md +++ b/en/application-dev/quick-start/module-structure.md @@ -21,7 +21,7 @@ The **module** tag contains the HAP configuration. | reqPermissions | Permissions that the application requests from the system when it is running.| Object array| Yes (initial value: left empty)| | colorMode | Color mode of the application. The options are as follows:
- **dark**: Resources applicable for the dark mode are used.
- **light**: Resources applicable for the light mode are used.
- **auto**: Resources are used based on the color mode of the system.| String| Yes (initial value: **auto**)| | distroFilter | Distribution rules of the application. This attribute defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when the application market distributes applications. Distribution rules cover three factors: API version, screen shape, and screen resolution. During distribution, a unique HAP is determined based on the mapping between **deviceType** and these three factors.| Object| Yes (initial value: left empty) Set this attribute when an application has multiple entry modules.| -|commonEvents | Information about the common event static subscriber, which must contain the subscriber name, required permissions, and list of the subscribed common events. When a subscribed event is sent, the static subscriber is started. Unlike the common dynamic subscriber, the static subscriber does not need to actively call the common event subscription API in the service code, and may not be started when the common event is released. In constrast, the dynamic subscriber actively calls the common event subscription API and therefore requires the application to stay active.| Object array| Yes (initial value: left empty)| +|commonEvents | Information about the common event static subscriber, which must contain the subscriber name, required permissions, and list of the common events subscribed to. When a subscribed event is sent, the static subscriber is started. Unlike the dynamic subscriber, the static subscriber does not need to proactively call the common event subscription API in the service code, and may not be running when the common event is published.| Object array| Yes (initial value: left empty)| | entryTheme | Keyword of an OpenHarmony internal theme. Set it to the resource index of the name.| String| Yes (initial value: left empty)| |testRunner | Test runner configuration.| Object| Yes (initial value: left empty)| @@ -190,12 +190,73 @@ Example of the metadata attribute: ## Internal Structure of the abilities Attribute +**By default, application icons cannot be hidden from the home screen in OpenHarmony.** + +The OpenHarmony system imposes a strict rule on the presence of application icons. If no icon is configured in the HAP file of an application, the system creates a default icon for the application and displays it on the home screen.
+Touching this icon will direct the user to the application details screen in **Settings**. +To hide an application icon from the home screen, you must configure the **AllowAppDesktopIconHide** privilege. For details, see [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md). + + +**Setting the application icon to be displayed on the home screen**:
Set **icon**, **label**, and **skills** under **abilities** in the **config.json** file. In addition, make sure the **skills** configuration contains **ohos.want.action.home** and **entity.system.home**. +``` +{ + "module":{ + + ... + + "abilities": [{ + "icon": "$media:icon", + "label": "Login", + "skills": [{ + "actions": ["ohos.want.action.home"], + "entities": ["entity.system.home"], + "uris": [] + }] + }], + + ... + + } +} +``` + +**Querying an application icon:** +* The HAP file contains Page ability configuration. + * The application icon is set under **abilities** in the **config.json** file. + * The application does not have the privilege to hide its icon from the home screen. + * The returned home screen icon is the icon configured for the ability. + * The returned home screen label is the label configured for the ability. If no label is configured, the bundle name is returned. + * The returned component name is the component name of the ability. + * When the user touches the home screen icon, the home screen of the ability is displayed. + * The application has the privilege to hide its icon from the home screen. + * The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen. + * The application icon is not set under **abilities** in the **config.json** file. + * The application does not have the privilege to hide its icon from the home screen. + * The returned home screen icon is the default icon. + *The returned home screen label is the bundle name of the application. + * The returned component name is the component name displayed on the application details screen (this component is built in the system). + * Touching the home screen icon will direct the user to the application details screen. + * The application has the privilege to hide its icon from the home screen. + * The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen. +* The HAP file does not contain Page ability configuration. + * The application does not have the privilege to hide its icon from the home screen. + * The returned home screen icon is the default icon. + *The returned home screen label is the bundle name of the application. + * The returned component name is the component name displayed on the application details screen (this component is built in the system). + * Touching the home screen icon will direct the user to the application details screen. + * The application has the privilege to hide its icon from the home screen. + * The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen. + +> **NOTE** +> +> The icon and label displayed on the application details page may be different from those displayed on the home screen. For non-Page abilities, they are the entry icon and label set under **abilities**, if any. + **Table 8** Internal structure of the abilities attribute | Name| Description| Data Type| Initial Value Allowed| | -------- | -------- | -------- | -------- | | process | Name of the process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. If this attribute is set to the name of the process running other applications, all these applications can run in the same process, provided they have the same unified user ID and the same signature. The value can contain a maximum of 31 bytes.| String| Yes (initial value: left empty)| -| name | Ability name. The value can be a reverse domain name, in the format of "*bundleName*.*className*", for example, **"com.example.myapplication.EntryAbility"**. Alternatively, the value can start with a period (.) followed by the class name, for example, **".EntryAbility"**.
The ability name must be unique in an application. Note: If you use DevEco Studio to create the project, an ability named **EntryAbility** will be created by default, and its configuration will be saved to the **config.json** file. The value of this attribute can be customized if you use other IDEs. The value can contain a maximum of 127 bytes.| String| No| +| name | Ability name. The value can be a reverse domain name, in the format of "*bundleName*.*className*", for example, **"com.example.myapplication.EntryAbility"**. Alternatively, the value can start with a period (.) followed by the class name, for example, **".EntryAbility"**.
The ability name must be unique in an application. Note: If you use DevEco Studio to create the project, an ability named **EntryAbility** will be created by default, and its configuration will be saved to the **config.json** file. If you use other IDEs, the value of this attribute can be customized. The value can contain a maximum of 127 bytes.| String| No| | description | Description of the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 bytes.| String| Yes (initial value: left empty)| | icon | Index to the ability icon file. Example value: **$media:ability_icon**. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the icon of the ability is also used as the icon of the application. If multiple abilities address this condition, the icon of the first candidate ability is used as the application icon.
Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels.| String| Yes (initial value: left empty)| | label | Ability name displayed to users. The value can be a name string or a resource index to names in multiple languages. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the label of the ability is also used as the label of the application. If multiple abilities address this condition, the label of the first candidate ability is used as the application label.
Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels. The value can be a reference to a string defined in a resource file or a string enclosed in brackets ({}). The value can contain a maximum of 255 characters.| String| Yes (initial value: left empty)| @@ -212,13 +273,13 @@ Example of the metadata attribute: | grantPermission | Whether permissions can be granted for any data in the ability.| Boolean| Yes (initial value: left empty)| | readPermission | Permission required for reading data in the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String| Yes (initial value: left empty)| | writePermission | Permission required for writing data to the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| -| configChanges | System configurations that the ability concerns. Upon any changes on the concerned configurations, the **onConfigurationUpdated** callback will be invoked to notify the ability. The options are as follows:
**mcc**: indicates that the mobile country code (MCC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MCC is updated.
**mnc**: indicates that the mobile network code (MNC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MNC is updated.
**locale**: indicates that the locale is changed. Typical scenario: The user selectes a new language for the text display of the device.
**layout**: indicates that the screen layout is changed. Typical scenario: Currently, different display forms are all in the active state.
**fontSize**: indicates that font size is changed. Typical scenario: A new global font size is set.
**orientation**: indicates that the screen orientation is changed. Typical scenario: The user rotates the device.
**density**: indicates that the display density is changed. Typical scenario: The user may specify different display ratios, or different display forms are active at the same time.
**size**: indicates that the size of the display window is changed.
**smallestSize**: indicates that the length of the shorter side of the display window is changed.
**colorMode**: indicates that the color mode is changed.| String array| Yes (initial value: left empty)| +| configChanges | System configurations that the ability concerns. Upon any changes on the concerned configurations, the **onConfigurationUpdated** callback will be invoked to notify the ability. The options are as follows:
**mcc**: indicates that the mobile country code (MCC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MCC is updated.
**mnc**: indicates that the mobile network code (MNC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MNC is updated.
**locale**: indicates that the locale is changed. Typical scenario: The user selects a new language for the text display of the device.
**layout**: indicates that the screen layout is changed. Typical scenario: Currently, different display forms are all in the active state.
**fontSize**: indicates that font size is changed. Typical scenario: A new global font size is set.
**orientation**: indicates that the screen orientation is changed. Typical scenario: The user rotates the device.
**density**: indicates that the display density is changed. Typical scenario: The user may specify different display ratios, or different display forms are active at the same time.
**size**: indicates that the size of the display window is changed.
**smallestSize**: indicates that the length of the shorter side of the display window is changed.
**colorMode**: indicates that the color mode is changed.| String array| Yes (initial value: left empty)| | mission | Task stack of the ability. This attribute applies only to the ability using the Page template. By default, all abilities in an application belong to the same task stack.| String| Yes (initial value: bundle name of the application)| | targetAbility | Target ability that this ability alias points to. This attribute applies only to the ability using the Page template. If the **targetAbility** attribute is set, only **name**, **icon**, **label**, **visible**, **permissions**, and **skills** take effect in the current ability (ability alias). Other attributes use the values of the **targetAbility** attribute. The target ability must belong to the same application as the alias and must be declared in **config.json** ahead of the alias.| String| Yes (initial value: left empty, indicating that the current ability is not an alias)| | formsEnabled | Whether the ability can provide widgets. This attribute applies only to the ability using the Page template.
**true**: This ability can provide widgets.
**false**: This ability cannot provide widgets.| Boolean| Yes (initial value: **false**)| | forms | Information about the widgets used by the ability. This attribute is valid only when **formsEnabled** is set to **true**.| Object array| Yes (initial value: left empty)| | srcLanguage | Programming language of the ability, which you can specify when creating the project.| String| Yes (initial value: **"js"**)| -| srcPath | JS code path corresponding to the ability. The value can contain maximum of 127 bytes.| String| No| +| srcPath | JS code path corresponding to the ability. The value can contain a maximum of 127 bytes.| String| No| | uriPermission | Application data that the ability can access. This attribute consists of the **mode** and **path** sub-attributes. This attribute is valid only for the capability of the type provider.| Object| Yes (initial value: left empty)| | startWindowIcon | Index to the icon file of the ability startup page. This attribute applies only to the ability using the Page template. Example: **$media:icon**.| String| Yes (initial value: left empty)| | startWindowBackground | Index to the background color resource file of the ability startup page. This attribute applies only to the ability using the Page template. Example: **$color:red**.| String| Yes (initial value: left empty)| @@ -351,9 +412,42 @@ Example of the **skills** attribute structure: ] ``` -## reqPermissions Attributes - -**Table 12** reqPermissions attributes +**Enhanced implicit query** + +URI-level prefix matching is supported. + +When only **scheme** or a combination of **scheme** and **host** or **scheme**, **host**, and **port** are configured in the configuration file, the configuration is successful if a URI prefixed with the configuration file is passed in. + + * The query enhancement involves the following APIs:
+ [@ohos.bundle.bundleManager](../reference/apis/js-apis-bundleManager.md#bundlemanagerqueryabilityinfo)
+ 1. function queryAbilityInfo(want: Want, abilityFlags: number, callback: AsyncCallback>): void;
+ 2. function queryAbilityInfo(want: Want, abilityFlags: number, userId: number, callback: AsyncCallback>): void;
+ 3. function queryAbilityInfo(want: Want, abilityFlags: number, userId?: number): Promise>; + * Configuration requirements
+ abilities -> skills -> uris object
+ Configuration 1: only **scheme = 'http'** + Configuration 2: only **(scheme = 'http') + (host = 'www.example.com')** + Configuration 3: only **(scheme = 'http') + (host = 'www.example.com') + (port = '8080')** + * Prefix match
+ If the value of **uri** under [want](../application-models/want-overview.md) is obtained by calling the **queryAbilityInfo** API:
+ 1. uri = 'https://': No matches
+ 2. uri = 'http://': Matches configuration 1
+ 3. uri = 'https://www.example.com': No matches
+ 4. uri = 'https://www.exa.com': No matches
+ 5. uri = 'http://www.exa.com': Matches configuration 1
+ 6. uri = 'http://www.example.com': Matches configuration 1 and configuration 2
+ 7. uri = 'https://www.example.com:8080': No matches
+ 8. uri = 'http://www.exampleaa.com:8080': Matches configuration 1
+ 9. uri = 'http://www.example.com:9180': Matches configuration 1 and configuration 2
+ 10. uri = 'http://www.example.com:8080': Matches configuration 1, configuration 2, and configuration 3
+ 11. uri = 'https://www.example.com:9180/query/student/name' : No matches
+ 12. uri = 'http://www.exampleap.com:8080/query/student/name': Matches configuration 1
+ 13. uri = 'http://www.example.com:9180/query/student/name': Matches configuration 1 and configuration 2
+ 14. uri = 'http://www.example.com:8080/query/student/name': Matches configuration 1, configuration 2, and configuration 3
+ +## Internal Structure of the reqPermissions Attribute + +**Table 12** Internal structure of the reqPermissions attribute | Name| Description| Data Type| Initial Value Allowed| | -------- | -------- | -------- | -------- | @@ -687,7 +781,7 @@ Example of the **commonEvents** attribute structure: | -------- | -------- | -------- | -------- | | name | Name of a permission. The value can contain a maximum of 255 bytes.| String| No| | grantMode | Permission grant mode. The options are as follows:
- **system_grant**: The permission is automatically granted by the system after the application is installed.
- **user_grant**: The permission is dynamically requested when needed and must be granted by the user.| String| Yes (initial value: **"system_grant"**)| -| availableLevel | Permission type. The options are as follows:
- **system_core**: system core permission.
- **system_basic**: basic system permission.
- **normal**: normal permission, which can be requsted by all applications.| String| Yes (initial value: **"normal"**)| +| availableLevel | Permission type. The options are as follows:
- **system_core**: system core permission.
- **system_basic**: basic system permission.
- **normal**: normal permission, which can be requested by all applications.| String| Yes (initial value: **"normal"**)| | provisionEnable | Whether the permission can be requested in provision mode, including high-level permissions. The value **true** means that the permission can be requested in provision mode.| Boolean| Yes (initial value: **true**)| | distributedSceneEnabled | Whether the permission can be used in distributed scenarios.| Boolean| Yes (initial value: **false**)| | label | Brief description of the permission. The value is a resource index to the description.| String| Yes (initial value: left empty)| diff --git a/en/application-dev/quick-start/quickfix-debug.md b/en/application-dev/quick-start/quickfix-debug.md new file mode 100644 index 0000000000000000000000000000000000000000..b7cdf872c72198e796be1f1b65e635cb52ce04e6 --- /dev/null +++ b/en/application-dev/quick-start/quickfix-debug.md @@ -0,0 +1,92 @@ +# CLI-based Quick Fix Development + +You can use the command-line tool to develop a quick fix file, an expeditious approach to resolve application bugs. In this document, an application with the bundle name of **com.ohos.quickfix** in version 1000000 is used as an example to describe how to develop a quick fix file with the command-line tool. + +## Writing the patch.json File + +Write a **patch.json** file that meets your project requirements and place it in any directory of the project. (Configuring the **patch.json** file is not supported in DevEco Studio.) Create a **patch.json** file on the local computer. Below is an example of the file content: +```json +{ + "app" : { + "bundleName" : "com.ohos.quickfix", + "versionCode": 1000000, // Application version + "versionName" : "1.0.0.1", + "patchVersionCode": 1000000, // Patch version + "patchVersionName" : "1.0.0.1" + }, + "module" : { + "name" : "entry", + "type" : "patch", + "deviceTypes" : [ + "default", + "tablet" + ], + "originalModuleHash": "11223344556677889900" // SHA-256 value of the HAP file to restore + } +} +``` + +## Generating a Quick Fix File +### Quick Fix for TS Code +* After modifying the TS code file in DevEco Studio and build it into a HAP file, you can find the corresponding .abc file in the project directory, for example, **build\default\cache\default\LegacyCompileETS\jsbundle\temporary\pages\index.abc**. + +### Quick Fix for C++ Code + +* In DevEco Studio, build the original C++ code into a .so file. Fix bugs in the code and rebuild the code into a new .so file. You can find this .so file in the project directory, for example, **build\default\intermediates\libs\default\arm64-v8a\libentry.so**. +* Locate the **diff.exe** tool in the **toolchains** folder in the local OpenHarmony SDK path. Use this tool to generate a quick fix .so file based on the old and new .so files. The command is as follows: +```shell +$ diff.exe -s Example.z.so -d Example.z.so -p Example.z.so.diff +``` +The command contains the following options: +- -**s**: path to the old .so file +- -**d**: path to the new .so file +- -**p**: path of the generated differential file + +## Generating a Quick Fix File in .hqf Format + +With the preceding **patch.json**, .abc, and .so files, run the following command to generate an .hqf file using the **app_packing_tool.jar** tool in the **toolchains** folder in the local OpenHarmony SDK path: +```shell +$ java -jar app_packing_tool.jar --mode hqf --json-path patch.json --lib-path libs --ets-patch patchs --out-path entry-default-unsigned.hqf --force true +``` + +The command contains the following options. +| Option|Description | Remarks| +| --- | --- |---| +| mode |Mode. | Mandatory| +| json-path|Path to the **patch.json** file.|Mandatory| +| lib-path|Path to the quick fix .so file. For details about the path, see [Structure of the Quick Fix Package](quickfix-principles.md#structure-of-the-quick-fix-package).|Optional| +| ets-path|Path to the quick fix .abc file.|Optional| + +## Signing the Quick Fix File + +Use the [hapsigner](../security/hapsigntool-guidelines.md) tool to sign the **entry-default-unsigned.hqf** file, in the same way you sign a HAP file. To be specific, run the following command to use **hap-sign-tool.jar** in the **toolchains** folder in the local OpenHarmony SDK path: + +```shell +$ java -jar hap-sign-tool.jar sign-app -keyAlias "OpenHarmony Application Release" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "OpenHarmonyApplication.pem" -profileFile "ohos_provision_release.p7b" -inFile "entry-default-unsigned.hqf" -keystoreFile "OpenHarmony.p12" -outFile "entry-signed-release.hqf" -keyPwd "123456" -keystorePwd "123456" +``` + +## Installing the Quick Fix File + +Push the **entry-signed-release.hqf** file to the device. +```shell +hdc.exe file send .\entry-signed-release.hqf /data/ +``` + +Run the following command to install the quick fix file as a patch: +```shell +$ bm quickfix -a -f /data/entry-signed-release.hqf +``` + +The complete commands are as follows: +``` +$ bm quickfix -h +usage: bm quickfix +options list: +-h, --help list available commands +-q, --query indicates query quickfix, used with -b or --bundle-name +-b, --bundle-name query quickfix status and information by a specified bundle name +-a, --apply indicates apply quickfix, used with -f or --file-path +-f, --file-path apply a quickfix file by a specified path +-f, --file-path ... apply some quickfix files of one bundle +-f, --file-path apply quickfix files by direction, under which are quickfix files +``` diff --git a/en/application-dev/quick-start/quickfix-principles.md b/en/application-dev/quick-start/quickfix-principles.md new file mode 100644 index 0000000000000000000000000000000000000000..4c0a1f684cfc1ff71c5ad9a2594ae8823e178e82 --- /dev/null +++ b/en/application-dev/quick-start/quickfix-principles.md @@ -0,0 +1,105 @@ +# Quick Fix Overview + +Quick fix is a technical means provided by the OpenHarmony system for developers to fix application bugs in a manner that is far faster than application upgrades. Compared with the full application upgrade, the quick fix provides a better user experience by being smaller and faster. It allows users to fix application bugs quickly, without restarting their application. + +## Rules for Using Quick Fix + +* The quick fix only works for TypeScript (TS) and C++ code of applications, that is, .abc files (created after TS code compilation) and .so files (created after C++ code compilation). It does not work for resource files. +* No new .abc and .so files are allowed. +* Before deploying a quick fix package, make sure the corresponding application has been installed. Otherwise, the deployment will fail. +* The bundle name and application version number configured in the quick fix package must be the same as those of the installed application. Otherwise, the deployment will fail. +* Make sure the version of the quick fix package to deploy is later than that of the one previously deployed. Otherwise, the deployment will fail. +* The signature information of the quick fix package must be the same as that of the application to be fixed. Otherwise, the deployment will fail. +* Installing an application update will delete quick fix package. + +## Structure of the Quick Fix Package + +![Quick Fix Package Structure](figures/quick_fix_bundle_struct.png) +
The preceding figure shows the structure of the quick fix package released by an OpenHarmony application. +* As shown in the figure, the quick fix package comes in two formats: + * .appqf (Application Quick Fix) +
There is a one-to-one mapping between the .appqf file and App Pack of an application. For details, see [Application Package Structure in Stage Model](application-package-structure-stage). + * The .appqf file is used to release OpenHarmony applications to the application market and cannot be directly installed on devices. + * An .appqf file consists of one or more .hqf (Harmony Ability Package Quick Fix) files, which are extracted from the .appqf file by the application market and then distributed to specific devices. + * The .appqf file must contain the developer's signature information before being released to the application market. For details about how to sign the file, see [hapsigner Overview](../security/hapsigntool-overview.md). + * .hqf (Harmony Ability Package Quick Fix) +
The .hqf file is a quick fix to bugs in a HAP file. It can be installed on devices. An .hqf file contains .abc and .so files. The .abc files provide the quick fix, and the .so files provide package configuration information as well as the quick fix. + * .abc file: modified TS code in the application, which is a bytecode file created after the build. + * **libs** directory: a collection of .so.diff files, which are differential files of the .so library files, organized by system CPU architecture, such as arm and x86. + * **patch.json**: +
This file is used to describe the version information of the .hqf file and is filled in by developers. The details are as follows: + ```json + { + "app" : { + "bundleName" : "com.ohos.quickfix", + "versionCode" : 1000000, + "versionName" : "1.0.0", + "patchVersionCode" : 1000000, + "patchVersionName" : "1.0.0" + }, + "module" : { + "name" : "entry", + "type" : "patch", + "deviceTypes" : [ + "default", + "tablet" + ], + "originalModuleHash" : "11223344556677889900" + } + } + ``` + The following describes the parameters: + | Parameter|Type |Description |Initial Value Allowed| + | --- | --- | --- | --- | + |bundleName | string | Bundle name of the application. | No| + |versionCode | int |Version of the application. | No | + |versionName |string |Version name of the application.| No for the patch| + |patchVersionCode |int |Version of the patch. | No| + |patchVersionName |string |Version name of the patch.| No for the patch| + |name |string |Module name of the application, which is used to restore the module.| No| + |type | string|Type of the patch. The value can only be **patch**.| No| + |deviceTypes |array |Device types supported by the patch.| No| + |originalModuleHash| string |Hash value of the bundle corresponding to the original module name.| No| + +## Quick Fix to .abc Files Created After TS Code Compilation + +![.abc File Quick Fix](figures/quick_fix_gen_abc.png) + +The preceding figure shows the process of creating an .abc file quick fix using the TS compiler. +* An application build creates .abc and .map files. The .abc file is a bytecode file created after TS code compilation. It is used when the application is running. The .map file is an intermediate file created when the TS code is compiled using the TS compiler. It stores information such as functions and classes in the code. +* After bugs in the application are fixed, the application code is compiled again. During the compilation, the difference between the source and the target is obtained based on the preceding .map file and the current TS code, and an .abc file for quick fix is generated based on the difference. This .abc file will be placed in the .hqf file. + +## Quick Fix to .so Files Created After C++ Code Compilation + +![.so File Quickly Fix](figures/quick_fix_gen_so.png) + +The preceding figure shows the process of creating a .so file quick fix using the differential tool. +* The C++ source code of the original application is built into a .so file by using a compiler. The .so file is used when the application is running. +* After bugs in the application are fixed, the C++ code is compiled again into a .so file. With the two .so files before and after bug fixes, the differential tool generates a .so file for quick fix. This .so file will also be placed in the .hqf file. + +## Quick Fix Release and Deployment Process + +![Quick Fix File Release](figures/quick-fix-devel_release.png) + +As shown above, the modules involved in the release process are as follows: +* DevEco Studio: an integrated development environment for developing code projects. It can be used to create a quick fix file based on the original application code and the code after bug fixes, and sign the created quick repair file for release to the application market. +* Application market server: place where you release the quick fix file. It verifies the signature, scans for risks, unpacks and resigns the file, and then distributes the file to the client. +* Application market client: tool that receives the quick fix file from the application market server and triggers installation. +* Bundle manager service: system service used to manage the installation and uninstallation of application packages and quick fix files on the device. +* Quick fix engine: system service used to manage switching to quick fix code on the device. If the target application is running, the quick fix engine instructs it to switch to the quick fix file upon completion of the quick fix file deployment. +* File system: location where the application package and quick repair file are deployed on the device. + +In the end-to-end release and deployment process of the quick repair file: +1. DevEco Studio is used to create a quick fix file through building and packaging based on the original application source code and the source code after bug fixes, and sign the created quick fix file. +2. The signed quick repair file is released to the application market, which then distributes the file after verifying the signature, scanning for risks, and unpacking and resigning the file. +3. When the on-device application market client detects that a new quick fix file is available on the application market server, it downloads the file, and then installs and deploys the file through the bundle manager service in the system. +4. After the quick fix file is deployed, the quick fix engine triggers the application to switch to the quick fix file, ensuring that the user can instantly use the functions where bugs are fixed. + +## Quick Fix File Debugging Process + +![Quick Fix File Debugging](figures/quick-fix-debug.png) + +* As the quick fix capability is not yet available in DevEco Studio, for the time being, you can use the provided command-line tool to develop a quick fix file. The procedure is as follows: +1. With the original application source code and the source code after bug fixes, use the command-line tool to build and create quick fix files in .hpf format. Sign the .hpf files before installing them on the device. As aforementioned, the .appqf file cannot be installed on the device. +2. Install and deploy the .hqf files on the device using the command-line tool. +3. After the .hqf files are deployed, a callback is called to instruct the quick fix engine to trigger the application to switch to the quick fix file, ensuring that the user can instantly use the functions where bugs are fixed.