diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 4646544abd6e22a632a35faeba6184819d601097..d5df9fa6b163bd6c8b41396443da1b664eecdef1 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -1,5 +1,7 @@ # APIs +- [API Reference Document Description](development-intro.md) + - Ability Framework - [@ohos.ability.dataUriUtils](js-apis-DataUriUtils.md) @@ -47,7 +49,7 @@ - application/[ServiceExtensionContext](js-apis-service-extension-context.md) - application/[shellCmdResult](js-apis-application-shellCmdResult.md) - application/[MissionInfo](js-apis-application-missionInfo.md) - + - Common Event and Notification - [@ohos.commonEvent](js-apis-commonEvent.md) @@ -55,7 +57,7 @@ - [@ohos.notification](js-apis-notification.md) - [@ohos.reminderAgent](js-apis-reminderAgent.md) - application/[EventHub](js-apis-eventhub.md) - + - Bundle Management - [@ohos.bundle](js-apis-Bundle.md) @@ -70,14 +72,14 @@ - bundle/[HapModuleInfo](js-apis-bundle-HapModuleInfo.md) - bundle/[Metadata](js-apis-bundle-Metadata.md) - bundle/[ModuleInfo](js-apis-bundle-ModuleInfo.md) - + - UI Page - [@ohos.animator](js-apis-animator.md) - [@ohos.mediaquery](js-apis-mediaquery.md) - [@ohos.prompt](js-apis-prompt.md) - [@ohos.router](js-apis-router.md) - + - Graphics - [@ohos.display ](js-apis-display.md) @@ -85,7 +87,7 @@ - [@ohos.window](js-apis-window.md) - [webgl](js-apis-webgl.md) - [webgl2](js-apis-webgl2.md) - + - Media - [@ohos.multimedia.audio](js-apis-audio.md) @@ -93,31 +95,32 @@ - [@ohos.multimedia.image](js-apis-image.md) - [@ohos.multimedia.media](js-apis-media.md) - [@ohos.multimedia.medialibrary](js-apis-medialibrary.md) - + - Resource Management + - [@ohos.i18n](js-apis-i18n.md) - [@ohos.intl](js-apis-intl.md) - [@ohos.resourceManager](js-apis-resource-manager.md) - + - Resource Scheduling - [@ohos.backgroundTaskManager](js-apis-backgroundTaskManager.md) - [@ohos.workScheduler ](js-apis-workScheduler.md) - [@ohos.WorkSchedulerExtensionAbility](js-apis-WorkSchedulerExtensionAbility.md) - + - Custom Management - [@ohos.configPolicy](js-apis-config-policy.md) - [@ohos.enterpriseDeviceManager](js-apis-enterprise-device-manager.md) - [@ohos.EnterpriseAdminExtensionAbility](js-apis-EnterpriseAdminExtensionAbility.md) - + - Security - [@ohos.abilityAccessCtrl](js-apis-abilityAccessCtrl.md) - [@ohos.security.huks ](js-apis-huks.md) - [@ohos.userIAM.userAuth ](js-apis-useriam-userauth.md) - [@system.cipher](js-apis-system-cipher.md) - + - Data Management - [@ohos.data.dataAbility ](js-apis-data-ability.md) @@ -127,7 +130,7 @@ - [@ohos.data.rdb](js-apis-data-rdb.md) - [@ohos.settings](js-apis-settings.md) - data/rdb/[resultSet](js-apis-data-resultset.md) - + - File Management - [@ohos.document](js-apis-document.md) @@ -138,7 +141,7 @@ - [@ohos.storageStatistics](js-apis-storage-statistics.md) - [@ohos.volumeManager](js-apis-volumemanager.md) - [@ohos.securityLabel](js-apis-securityLabel.md) - + - Telephony Service - [@ohos.contact](js-apis-contact.md) @@ -148,14 +151,15 @@ - [@ohos.telephony.sim](js-apis-sim.md) - [@ohos.telephony.sms](js-apis-sms.md) - [@ohos.telephony.data](js-apis-telephony-data.md) - + - Network Management + - [@ohos.net.connection](js-apis-net-connection.md) - [@ohos.net.http](js-apis-http.md) - [@ohos.request](js-apis-request.md) - [@ohos.net.socket](js-apis-socket.md) - [@ohos.net.webSocket](js-apis-webSocket.md) - + - Connectivity - [@ohos.bluetooth](js-apis-bluetooth.md) @@ -166,7 +170,7 @@ - [@ohos.rpc](js-apis-rpc.md) - [@ohos.wifi](js-apis-wifi.md) - [@ohos.wifiext](js-apis-wifiext.md) - + - Basic Features - [@ohos.accessibility](js-apis-accessibility.md) @@ -185,7 +189,7 @@ - [@ohos.systemTime](js-apis-system-time.md) - [@ohos.wallpaper](js-apis-wallpaper.md) - [Timer](js-apis-timer.md) - + - Device Management - [@ohos.batteryInfo ](js-apis-battery-info.md) @@ -210,13 +214,13 @@ - [@ohos.update](js-apis-update.md) - [@ohos.usb](js-apis-usb.md) - [@ohos.vibrator](js-apis-vibrator.md) - + - Account Management - [@ohos.account.appAccount](js-apis-appAccount.md) - [@ohos.account.distributedAccount](js-apis-distributed-account.md) - [@ohos.account.osAccount](js-apis-osAccount.md) - + - Language Base Class Library - [@ohos.convertxml](js-apis-convertxml.md) @@ -240,11 +244,12 @@ - [@ohos.util.Vector](js-apis-vector.md) - [@ohos.worker](js-apis-worker.md) - [@ohos.xml](js-apis-xml.md) - + - Test + - [@ohos.application.testRunner](js-apis-testRunner.md) - [@ohos.uitest](js-apis-uitest.md) - + - APIs No Longer Maintained - [@ohos.bytrace](js-apis-bytrace.md) diff --git a/en/application-dev/reference/apis/development-intro.md b/en/application-dev/reference/apis/development-intro.md new file mode 100644 index 0000000000000000000000000000000000000000..8528a10ab6f4ba3dd14186079357ce28e650ee6a --- /dev/null +++ b/en/application-dev/reference/apis/development-intro.md @@ -0,0 +1,51 @@ +# API Reference Document Description + +API references provide the description of APIs used for application development. This topic describes common fields in the API references to help you better use the reference document. + +## Version Description + +In API references, the earliest versions of APIs and components are specified in the following ways: + +- For a new API or component, the version information is provided at the beginning of the reference document. Example: "The initial APIs of this module are supported since API version 7." +- For a new feature of an existing API or component, a superscript is added following the feature. For example, "uid8+" indicates that the **uid** attribute is supported since API version 8. + +## Ability Framework Model Description + +Ability is the minimum unit for the system to schedule applications. An application can contain one or more `Ability` instances. Ability framework models are classified into the FA model and stage model. For details, see [Ability Framework Overview](../../ability/ability-brief.md). + +- If all the APIs of a module support only one model, the following description is provided at the beginning of the reference document: "The APIs of this module can be used only in the FA model." or "The APIs of this module can be used only in the stage model." +- If certain APIs of a module support only one model, the following description is provided individually for these APIs: "This API can be used only in the FA model." or "This API can be used only in the stage model." +- If both models are supported, no special description is provided. + +## Available APIs + +Certain APIs provided by OpenHarmony are system APIs, which can be used only by original equipment manufacturers (OEMs) and cannot be used by non-system applications. + +A description regarding system APIs will be provided in the document. + +- If all the APIs of a module are system APIs, the following description is provided at the beginning of the reference document: "All the APIs of this module are system APIs." +- If a specific API of a module is a system API, the following description is provided individually for the API: "This is a system API." + +## Permission Description + +By default, applications can access limited system resources. However, in some cases, an application needs to access excess data (including personal data) and functions of the system or another application to implement extended functions. For details, see [Access Control Overview](../../security/accesstoken-overview.md). + +To call APIs to access these resources, you must apply for the corresponding permissions by following the instructions provided in [Access Control Development](../../security/accesstoken-guidelines.md). + +- If an application can call an API only after it has obtained a specific permission, the following description is provided for the API: "**Required permissions**: ohos.permission.xxxx" +- If an application can call an API without any permission, no special description is provided. + +To determine whether an application can apply for a specific permission, see [Permission List](../../security/permission-list.md). + +## System Capability Description + +System capability refers to a relatively independent feature in the operating system. Different devices provide different system capabilities, and multiple APIs implement a system capability. You can determine whether an API can be used based on system capabilities. For details, see [SysCap](../../quick-start/syscap.md). + +The following description is provided for each API in the reference document to describe the system capability of the API: "**System capability**: SystemCapability.xxx.xxx" + +## Sample Code Language Description + +OpenHarmony supports two development languages: JS and TS. + +- When a code block is labeled with `js`, the sample code can be used in the JS and eTS projects. +- When a code block is labeled with `ts`, the sample code can be used only in the eTS project. diff --git a/en/application-dev/reference/apis/js-apis-abilityManager.md b/en/application-dev/reference/apis/js-apis-abilityManager.md deleted file mode 100644 index 28c5cd31b0350ca0e8b24c8bfbda21fb039adcd7..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-abilityManager.md +++ /dev/null @@ -1,268 +0,0 @@ -# AbilityManager - -The **AbilityManager** module provides APIs for obtaining, adding, and modifying ability running information and state information. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> The APIs of this module are system APIs and cannot be called by third-party applications. - -# Modules to Import - -```js -import AbilityManager from '@ohos.application.abilityManager' -``` - -## AbilityState - -Enumerates the ability states. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -| Name| Value| Description| -| -------- | -------- | -------- | -| INITIAL | 0 | The ability is in the initial state.| -| FOREGROUND | 9 | The ability is in the foreground state. | -| BACKGROUND | 10 | The ability is in the background state. | -| FOREGROUNDING | 11 | The ability is in the foregrounding state. | -| BACKGROUNDING | 12 | The ability is in the backgrounding state. | - -## updateConfiguration - -updateConfiguration(config: Configuration, callback: AsyncCallback\): void - -Obtains the ability running information. This API uses an asynchronous callback to return the result. - -**Permission required**: ohos.permission.UPDATE_CONFIGURATION - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------- | ---- | -------------- | -| config | Configuration | Yes | New configuration.| -| callback | AsyncCallback\ | Yes | Callback used to return the result. | - -**Example** - -```js -import abilitymanager from '@ohos.application.abilityManager'; - -var config = { - language: 'chinese' -} - -abilitymanager.updateConfiguration(config, () => { - console.log('------------ updateConfiguration -----------'); -}) -``` - -## updateConfiguration - -updateConfiguration(config: Configuration): Promise\ - -Updates the configuration. This API uses a promise to return the result. - -**Permission required**: ohos.permission.UPDATE_CONFIGURATION - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------- | ---- | -------------- | -| config | Configuration | Yes | New configuration.| - -**Return value** - -| Type | Description | -| ---------------------------------------- | ------- | -| Promise\ | Promise used to return the result. | - -**Example** - -```js -import abilitymanager from '@ohos.application.abilityManager'; - -var config = { - language: 'chinese' -} - -abilitymanager.updateConfiguration(config).then(() => { - console.log('updateConfiguration success'); -}).catch((err) => { - console.log('updateConfiguration fail'); -}) -``` - -## getAbilityRunningInfos - -getAbilityRunningInfos(callback: AsyncCallback\>): void - -Obtains the ability running information. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------- | ---- | -------------- | -| callback | AsyncCallback\> | Yes | Callback used to return the result. | - -**Example** - -```js -import abilitymanager from '@ohos.application.abilityManager'; - -abilitymanager.getAbilityRunningInfos((err,data) => { - console.log("getAbilityRunningInfos err: " + err + " data: " + JSON.stringify(data)); -}); -``` - -## getAbilityRunningInfos - -getAbilityRunningInfos(): Promise\> - -Obtains the ability running information. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Return value** - -| Type | Description | -| ---------------------------------------- | ------- | -| Promise\> | Promise used to return the result. | - -**Example** - -```js -import abilitymanager from '@ohos.application.abilityManager'; - -abilitymanager.getAbilityRunningInfos().then((data) => { - console.log("getAbilityRunningInfos data: " + JSON.stringify(data)) -}).catch((err) => { - console.log("getAbilityRunningInfos err: " + err) -}); -``` - -## getExtensionRunningInfos9+ - -getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback\>): void - -Obtains the extension running information. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------- | ---- | -------------- | -| upperLimit | number | Yes| Maximum number of messages that can be obtained.| -| callback | AsyncCallback\> | Yes | Callback used to return the result. | - -**Example** - -```js -import abilitymanager from '@ohos.application.abilityManager'; - -var upperLimit = 0; - -abilitymanager.getExtensionRunningInfos(upperLimit, (err,data) => { - console.log("getExtensionRunningInfos err: " + err + " data: " + JSON.stringify(data)); -}); -``` - -## getExtensionRunningInfos9+ - -getExtensionRunningInfos(upperLimit: number): Promise\> - -Obtains the extension running information. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------- | ---- | -------------- | -| upperLimit | number | Yes| Maximum number of messages that can be obtained.| - -**Return value** - -| Type | Description | -| ---------------------------------------- | ------- | -| Promise\> | Promise used to return the result. | - -**Example** - -```js -import abilitymanager from '@ohos.application.abilityManager'; - -var upperLimit = 0; - -abilitymanager.getExtensionRunningInfos(upperLimit).then((data) => { - console.log("getAbilityRunningInfos data: " + JSON.stringify(data)); -}).catch((err) => { - console.log("getAbilityRunningInfos err: " + err); -}) -``` - -## getTopAbility9+ - -getTopAbility(callback: AsyncCallback\): void; - -Obtains the top ability, which is the ability that has the window focus. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------- | ---- | -------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result. | - -**Example** - -```js -import abilitymanager from '@ohos.application.abilityManager'; - -abilitymanager.getTopAbility((err,data) => { - console.log("getTopAbility err: " + err + " data: " + JSON.stringify(data)); -}); -``` - -## getTopAbility9+ - -getTopAbility(): Promise\; - -Obtains the top ability, which is the ability that has the window focus. This API uses a promise to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Return value** - -| Type | Description | -| ---------------------------------------- | ------- | -| Promise\| Promise used to return the result. | - -**Example** - -```js -import abilitymanager from '@ohos.application.abilityManager'; - -abilitymanager.getTopAbility().then((data) => { - console.log("getTopAbility data: " + JSON.stringify(data)); -}).catch((err) => { - console.log("getTopAbility err: " + err); -}) -``` diff --git a/en/application-dev/reference/apis/js-apis-application-missionInfo.md b/en/application-dev/reference/apis/js-apis-application-missionInfo.md deleted file mode 100644 index 05938521e10970192409f856e68b816c18d3f3f0..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-application-missionInfo.md +++ /dev/null @@ -1,28 +0,0 @@ -# MissionInfo - -> **NOTE** -> -> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. - -## Modules to Import - -```js -import MissionInfo from '@ohos.application.missionInfo' -``` - -## MissionInfo - -Provides the mission information. - -**System capability**: SystemCapability.Ability.AbilityBase - -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| missionId | number | Yes| Yes| Mission ID.| -| runningState | number | Yes| Yes| Running state of the mission.| -| lockedState | boolean | Yes| Yes| Locked state of the mission.| -| timestamp | string | Yes| Yes| Latest time when the mission was created or updated.| -| want | [Want](js-apis-application-Want.md) | Yes| Yes| **Want** information of the mission.| -| label | string | Yes| Yes| Label of the mission.| -| iconPath | string | Yes| Yes| Path of the mission icon.| -| continuable | boolean | Yes| Yes| Whether the mission is continuable.| diff --git a/en/application-dev/reference/apis/js-apis-uripermissionmanager.md b/en/application-dev/reference/apis/js-apis-uripermissionmanager.md deleted file mode 100644 index 6bbf0f941909786361f651546a3fab9fe129c69c..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-uripermissionmanager.md +++ /dev/null @@ -1,86 +0,0 @@ -# uriPermissionManager - -> **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. - - -Implements URI permission management. - - -## Modules to Import - - -``` -import UriPermissionManager from '@ohos.application.uriPermissionManager'; -``` - - -## uriPermissionManager.verifyUriPermission - -verifyUriPermission(uri: string, flag: wantConstant.Flags, accessTokenId: number, callback: AsyncCallback<number>): void - -Checks whether an application has the permission specified by **flag** for an URI. This API uses a callback to return the result. - -**System capability**: - -SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | uri | string | Yes| URI of a file, for example, **fileshare:///com.samples.filesharetest.FileShare/person/10**.| - | flag | wantConstant.Flags | Yes| Read or write permission on the file specified by the URI.| - | accessTokenId | number | Yes| Unique ID of an application, which is obtained through the **BundleManager** API.| - | callback | AsyncCallback<number> | Yes| Callback used to return the check result. The value **0** means that the application has the specified permission, and **-1** means the opposite.| - -**Example** - - ```js - import WantConstant from '@ohos.ability.wantConstant'; - let accessTokenId =1 - let uri = "fileshare:///com.samples.filesharetest.FileShare/person/10" - UriPermissionManager.verifyUriPermission(uri, WantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, accessTokenId, (result) => { - console.log("result.code = " + result.code) - }) // accessTokenId is obtained through the **BundleManager** API. - ``` - - -## uriPermissionManager.verifyUriPermission - -verifyUriPermission(uri: string, flag: wantConstant.Flags, accessTokenId: number): Promise<number> - -Checks whether an application has the permission specified by **flag** for an URI. This API uses a callback to return the result. - -**System capability**: - -SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | uri | string | Yes| URI of a file, for example, **fileshare:///com.samples.filesharetest.FileShare/person/10**.| - | flag | wantConstant.Flags | Yes| Read or write permission on the file specified by the URI.| - | accessTokenId | number | Yes| Unique ID of an application, which is obtained through the **BundleManager** API.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<number> | Promise used to return the check result. The value **0** means that the application has the specified permission, and **-1** means the opposite.| - -**Example** - - ```js - import WantConstant from '@ohos.ability.wantConstant'; - let accessTokenId =1 - let uri = "fileshare:///com.samples.filesharetest.FileShare/person/10" - UriPermissionManager.verifyUriPermission(uri, wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, accessTokenId) - .then((data) => { - console.log('Verification succeeded.' + data) - }).catch((error) => { - console.log('Verification failed.'); - }) - ```