@@ -158,7 +158,7 @@ Go to the local installation path, choose **toolchains > 3.x.x.x** (the folder n
...
@@ -158,7 +158,7 @@ Go to the local installation path, choose **toolchains > 3.x.x.x** (the folder n
> **NOTE**: Use the SDK of the latest version. The use of an earlier version may cause errors in some statements.
> **NOTE**: Use the SDK of the latest version. The use of an earlier version may cause errors in some statements.
If the executable file does not exist, download the SDK package from the mirror as instructed in the [Release Notes](../../release-notes). The following uses the [3.2 Beta3](../../release-notes/OpenHarmony-v3.2-beta3.md#acquiring-source-code-from-mirrors) as an example.
If the executable file does not exist, download the SDK package from the mirror as instructed in the [Release Notes](../../release-notes). The following uses the [3.2 Beta5]((../../release-notes/OpenHarmony-v3.2-beta5.md#acquiring-source-code-from-mirrors) as an example.
For details about how to replace the SDK package, see [Guide to Switching to Full SDK](../quick-start/full-sdk-switch-guide.md).
For details about how to replace the SDK package, see [Guide to Switching to Full SDK](../quick-start/full-sdk-switch-guide.md).
@@ -12,4 +12,4 @@ During application development based on the Feature Ability (FA) model, the foll
...
@@ -12,4 +12,4 @@ During application development based on the Feature Ability (FA) model, the foll
| Inter-process communication (IPC)| Learn the process model and common IPC modes of the FA model.| [Common Events](common-event-fa.md)<br>[Background Services](rpc.md) |
| Inter-process communication (IPC)| Learn the process model and common IPC modes of the FA model.| [Common Events](common-event-fa.md)<br>[Background Services](rpc.md) |
| Inter-thread communication| Learn the thread model and common inter-thread communication modes of the FA model.| [Inter-Thread Communication](itc-fa-overview.md)|
| Inter-thread communication| Learn the thread model and common inter-thread communication modes of the FA model.| [Inter-Thread Communication](itc-fa-overview.md)|
| Mission management| Learn the basic concepts and typical scenarios of mission management in the FA model.| [Mission Management](mission-management-fa.md)|
| Mission management| Learn the basic concepts and typical scenarios of mission management in the FA model.| [Mission Management](mission-management-fa.md)|
| Application configuration file| Learn the requirements for developing application configuration files in the FA model.| [Application Configuration File](config-file-fa.md) |
| Application configuration file| Learn the requirements for developing application configuration files in the FA model.| [Application Configuration File](../quick-start/application-configuration-file-overview-fa.md) |
@@ -47,19 +47,19 @@ On device A, touch the **Start** button provided by the initiator application to
...
@@ -47,19 +47,19 @@ On device A, touch the **Start** button provided by the initiator application to
### How to Develop
### How to Develop
1. Request the **ohos.permission.DISTRIBUTED_DATASYNC** permission. For details, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file).
1. Request the **ohos.permission.DISTRIBUTED_DATASYNC** permission. For details, see [Applying for Permissions](../security/accesstoken-guidelines.md#stage-model).
2. Request the data synchronization permission. The sample code for displaying a dialog box to request the permission is as follows:
2. Request the data synchronization permission. The sample code for displaying a dialog box to request the permission is as follows:
console.info("Succeed to request permission from user with data: "+JSON.stringify(data));
console.info("Succeed to request permission from user with data: "+JSON.stringify(data))
}).catch((error)=>{
}).catch((error)=>{
console.info("Failed to request permission from user with error: "+JSON.stringify(error));
console.info("Failed to request permission from user with error: "+JSON.stringify(error))
})
})
}
}
```
```
...
@@ -129,19 +129,19 @@ On device A, touch the **Start** button provided by the initiator application to
...
@@ -129,19 +129,19 @@ On device A, touch the **Start** button provided by the initiator application to
### How to Develop
### How to Develop
1. Request the **ohos.permission.DISTRIBUTED_DATASYNC** permission. For details, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file).
1. Request the **ohos.permission.DISTRIBUTED_DATASYNC** permission. For details, see [Applying for Permissions](../security/accesstoken-guidelines.md#stage-model).
2. Request the data synchronization permission. The sample code for displaying a dialog box to request the permission is as follows:
2. Request the data synchronization permission. The sample code for displaying a dialog box to request the permission is as follows:
console.info("Succeed to request permission from user with data: "+JSON.stringify(data));
console.info("Succeed to request permission from user with data: "+JSON.stringify(data))
}).catch((error)=>{
}).catch((error)=>{
console.info("Failed to request permission from user with error: "+JSON.stringify(error));
console.info("Failed to request permission from user with error: "+JSON.stringify(error))
})
})
}
}
```
```
...
@@ -218,19 +218,31 @@ A system application can connect to a service on another device by calling [conn
...
@@ -218,19 +218,31 @@ A system application can connect to a service on another device by calling [conn
### How to Develop
### How to Develop
1.Request the **ohos.permission.DISTRIBUTED_DATASYNC** permission. For details, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file).
1.Configure the data synchronization permission in the **module.json5** file. The sample code is as follows:
```json
{
"module":{
"requestPermissions":[
{
"name":"ohos.permission.DISTRIBUTED_DATASYNC",
}
]
}
}
```
2. Request the data synchronization permission. The sample code for displaying a dialog box to request the permission is as follows:
2. Request the data synchronization permission. The sample code for displaying a dialog box to request the permission is as follows:
console.info("Succeed to request permission from user with data: "+JSON.stringify(data));
console.info("Succeed to request permission from user with data: "+JSON.stringify(data))
}).catch((error)=>{
}).catch((error)=>{
console.info("Failed to request permission from user with error: "+JSON.stringify(error));
console.info("Failed to request permission from user with error: "+JSON.stringify(error))
})
})
}
}
```
```
...
@@ -279,10 +291,10 @@ A system application can connect to a service on another device by calling [conn
...
@@ -279,10 +291,10 @@ A system application can connect to a service on another device by calling [conn
});
});
},
},
onDisconnect(elementName){
onDisconnect(elementName){
console.info('onDisconnect callback');
console.info('onDisconnect callback')
},
},
onFailed(code){
onFailed(code){
console.info('onFailed callback');
console.info('onFailed callback')
}
}
}
}
// The ID returned after the connection is set up must be saved. The ID will be passed for service disconnection.
// The ID returned after the connection is set up must be saved. The ID will be passed for service disconnection.
...
@@ -305,7 +317,7 @@ A system application can connect to a service on another device by calling [conn
...
@@ -305,7 +317,7 @@ A system application can connect to a service on another device by calling [conn
## Using Cross-Device Ability Call
## Using Cross-Device Ability Call
The basic principle of cross-device ability call is the same as that of intra-device ability call. For details, see [Using Ability Call to Implement UIAbility Interaction](uiability-intra-device-interaction.md#using-ability-call-to-implement-uiability-interaction).
The basic principle of cross-device ability call is the same as that of intra-device ability call. For details, see [Using Ability Call to Implement UIAbility Interaction (System Applications Only)](uiability-intra-device-interaction.md#using-ability-call-to-implement-uiability-interaction-system-applications-only).
The following describes how to implement multi-device collaboration through cross-device ability call.
The following describes how to implement multi-device collaboration through cross-device ability call.
...
@@ -319,45 +331,56 @@ The following describes how to implement multi-device collaboration through cros
...
@@ -319,45 +331,56 @@ The following describes how to implement multi-device collaboration through cros
| startAbilityByCall(want: Want): Promise<Caller>; | Starts a UIAbility in the foreground or background and obtains the caller object for communicating with the UIAbility.|
| startAbilityByCall(want: Want): Promise<Caller>; | Starts a UIAbility in the foreground or background and obtains the caller object for communicating with the UIAbility.|
| on(method: string, callback: CalleeCallBack): void | Callback invoked when the callee ability registers a method.|
| on(method: string, callback: CalleeCallBack): void | Callback invoked when the callee ability registers a method.|
| off(method: string): void | Callback invoked when the callee ability deregisters a method.|
| off(method: string): void | Callback invoked when the callee ability deregisters a method.|
| call(method: string, data: rpc.Sequenceable): Promise<void> | Sends agreed sequenceable data to the callee ability.|
| call(method: string, data: rpc.Parcelable): Promise<void> | Sends agreed parcelable data to the callee ability.|
| callWithResult(method: string, data: rpc.Sequenceable): Promise<rpc.MessageParcel> | Sends agreed sequenceable data to the callee ability and obtains the agreed sequenceable data returned by the callee ability.|
| callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence> | Sends agreed parcelable data to the callee ability and obtains the agreed parcelable data returned by the callee ability.|
| release(): void | Releases the caller object.|
| release(): void | Releases the caller object.|
| on(type: "release", callback: OnReleaseCallback): void | Callback invoked when the caller object is released.|
| on(type: "release", callback: OnReleaseCallback): void | Callback invoked when the caller object is released.|
### How to Develop
### How to Develop
1.Request the **ohos.permission.DISTRIBUTED_DATASYNC** permission. For details, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file).
1.Configure the data synchronization permission in the **module.json5** file. The sample code is as follows:
```json
{
"module":{
"requestPermissions":[
{
"name":"ohos.permission.DISTRIBUTED_DATASYNC",
}
]
}
}
```
2. Request the data synchronization permission. The sample code for displaying a dialog box to request the permission is as follows:
2. Request the data synchronization permission. The sample code for displaying a dialog box to request the permission is as follows:
console.info("Succeed to request permission from user with data: "+JSON.stringify(data));
console.info("Succeed to request permission from user with data: "+JSON.stringify(data))
}).catch((error)=>{
}).catch((error)=>{
console.info("Failed to request permission from user with error: "+JSON.stringify(error));
console.info("Failed to request permission from user with error: "+JSON.stringify(error))
})
})
}
}
```
```
3. Create the callee ability.
3. Create the callee ability.
For the callee ability, implement the callback to receive data and the methods to marshal and unmarshal data. When data needs to be received, use **on()** to register a listener. When data does not need to be received, use **off()** to deregister the listener.
For the callee ability, implement the callback to receive data and the methods to marshal and unmarshal data. When data needs to be received, use **on()** to register a listener. When data does not need to be received, use **off()** to deregister the listener.
1. Configure the launch type of the UIAbility.
1. Configure the launch type of the UIAbility.
Set **launchType** of the callee ability to **singleton** in the **module.json5** file.
Set **launchType** of the callee ability to **singleton** in the **module.json5** file.
| JSON Field| Description|
| JSON Field| Description|
| -------- | -------- |
| -------- | -------- |
| "launchType"| Ability launch type. Set this parameter to **singleton**.|
| "launchType"| Ability launch type. Set this parameter to **singleton**.|
An example of the UIAbility configuration is as follows:
An example of the UIAbility configuration is as follows:
```json
```json
"abilities":[{
"abilities":[{
"name": ".CalleeAbility",
"name": ".CalleeAbility",
...
@@ -371,17 +394,17 @@ The following describes how to implement multi-device collaboration through cros
...
@@ -371,17 +394,17 @@ The following describes how to implement multi-device collaboration through cros
```
```
2. Import the **UIAbility** module.
2. Import the **UIAbility** module.
```ts
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
importAbilityfrom'@ohos.app.ability.UIAbility'
```
```
3. Define the agreed parcelable data.
3. Define the agreed sequenceable data.
The data formats sent and received by the caller and callee abilities must be consistent. In the following example, the data formats are number and string.
The data formats sent and received by the caller and callee abilities must be consistent. In the following example, the data formats are number and string.
```ts
```ts
exportdefaultclassMySequenceable{
export default class MyParcelable {
num: number = 0
num: number = 0
str: string = ""
str: string = ""
...
@@ -390,24 +413,24 @@ The following describes how to implement multi-device collaboration through cros
...
@@ -390,24 +413,24 @@ The following describes how to implement multi-device collaboration through cros
this.str = string
this.str = string
}
}
marshalling(messageParcel){
marshalling(messageSequence) {
messageParcel.writeInt(this.num)
messageSequence.writeInt(this.num)
messageParcel.writeString(this.str)
messageSequence.writeString(this.str)
return true
return true
}
}
unmarshalling(messageParcel){
unmarshalling(messageSequence) {
this.num=messageParcel.readInt()
this.num = messageSequence.readInt()
this.str=messageParcel.readString()
this.str = messageSequence.readString()
return true
return true
}
}
}
}
```
```
4. Implement **Callee.on** and **Callee.off**.
In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate()** of the ability and deregistered in **onDestroy()**. After receiving sequenceable data, the application processes the data and returns the data result. You need to implement processing based on service requirements.
4. Implement **Callee.on** and **Callee.off**.
In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate()** of the ability and deregistered in **onDestroy()**. After receiving parcelable data, the application processes the data and returns the data result. You need to implement processing based on service requirements.
```ts
```ts
const TAG: string = '[CalleeAbility]'
const TAG: string = '[CalleeAbility]'
const MSG_SEND_METHOD: string = 'CallSendMsg'
const MSG_SEND_METHOD: string = 'CallSendMsg'
...
@@ -415,14 +438,14 @@ The following describes how to implement multi-device collaboration through cros
...
@@ -415,14 +438,14 @@ The following describes how to implement multi-device collaboration through cros
function sendMsgCallback(data) {
function sendMsgCallback(data) {
console.info('CalleeSortFunc called')
console.info('CalleeSortFunc called')
// Obtain the sequenceable data sent by the caller ability.
// Obtain the parcelable data sent by the caller ability.
return new MyParcelable(receivedData.num + 1, `send ${receivedData.str} succeed`)
}
}
export default class CalleeAbility extends Ability {
export default class CalleeAbility extends Ability {
...
@@ -436,7 +459,7 @@ The following describes how to implement multi-device collaboration through cros
...
@@ -436,7 +459,7 @@ The following describes how to implement multi-device collaboration through cros
onDestroy() {
onDestroy() {
try {
try {
this.callee.off(MSG_SEND_METHOD)
this.callee.off(MSG_SEND_METHOD)
} catch (error) {
} catch (error) {
console.error(TAG, `${MSG_SEND_METHOD} unregister failed with error ${JSON.stringify(error)}`)
console.error(TAG, `${MSG_SEND_METHOD} unregister failed with error ${JSON.stringify(error)}`)
}
}
...
@@ -448,14 +471,13 @@ The following describes how to implement multi-device collaboration through cros
...
@@ -448,14 +471,13 @@ The following describes how to implement multi-device collaboration through cros
1. Import the **UIAbility** module.
1. Import the **UIAbility** module.
```ts
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
importAbilityfrom'@ohos.app.ability.UIAbility'
```
```
2. Obtain the caller object.
2. Obtain the caller object.
The **context** attribute of the ability implements **startAbilityByCall** to obtain the caller object for communication. The following example uses **this.context** to obtain the **context** attribute of the ability, uses **startAbilityByCall** to start the callee ability, obtain the caller object, and register the **onRelease** listener of the caller ability. You need to implement processing based on service requirements.
The **context** attribute of the ability implements **startAbilityByCall** to obtain the caller object for communication. The following example uses **this.context** to obtain the **context** attribute of the ability, uses **startAbilityByCall** to start the callee ability, obtain the caller object, and register the **onRelease** listener of the caller ability. You need to implement processing based on service requirements.
```ts
```ts
async onButtonGetRemoteCaller() {
async onButtonGetRemoteCaller() {
var caller = undefined
var caller = undefined
...
@@ -469,7 +491,7 @@ The following describes how to implement multi-device collaboration through cros
...
@@ -469,7 +491,7 @@ The following describes how to implement multi-device collaboration through cros
if (data != null) {
if (data != null) {
caller = data
caller = data
console.info('get remote caller success')
console.info('get remote caller success')
// Register the onRelease() listener of the caller ability.
// 注册caller的release监听
caller.onRelease((msg) => {
caller.onRelease((msg) => {
console.info(`remote caller onRelease is called ${msg}`)
console.info(`remote caller onRelease is called ${msg}`)
})
})
...
@@ -483,38 +505,39 @@ The following describes how to implement multi-device collaboration through cros
...
@@ -483,38 +505,39 @@ The following describes how to implement multi-device collaboration through cros
For details about how to implement **getRemoteDeviceId()**, see [Starting UIAbility and ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-and-serviceextensionability-across-devices-no-data-returned).
For details about how to implement **getRemoteDeviceId()**, see [Starting UIAbility and ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-and-serviceextensionability-across-devices-no-data-returned).
5. Sends agreed sequenceable data to the callee ability.
5. Sends agreed parcelable data to the callee ability.
1. The sequenceable data can be sent to the callee ability with or without a return value. The method and sequenceable data must be consistent with those of the callee ability. The following example describes how to send data to the callee ability.
1. The parcelable data can be sent to the callee ability with or without a return value. The method and parcelable data must be consistent with those of the callee ability. The following example describes how to send data to the callee ability.
```ts
```ts
constMSG_SEND_METHOD:string='CallSendMsg';
constMSG_SEND_METHOD:string='CallSendMsg'
asynconButtonCall(){
asynconButtonCall(){
try{
try{
letmsg=newMySequenceable(1,'origin_Msg');
letmsg=newMyParcelable(1,'origin_Msg')
awaitthis.caller.call(MSG_SEND_METHOD,msg);
awaitthis.caller.call(MSG_SEND_METHOD,msg)
}catch(error){
}catch(error){
console.info(`caller call failed with ${error}`);
console.info(`caller call failed with ${error}`)
}
}
}
}
```
```
2. In the following, **CallWithResult** is used to send data **originMsg** to the callee ability and assign the data processed by the **CallSendMsg** method to **backMsg**.
2. In the following, **CallWithResult** is used to send data **originMsg** to the callee ability and assign the data processed by the **CallSendMsg** method to **backMsg**.
@@ -18,7 +18,7 @@ To develop the Worker mode, perform the following steps:
...
@@ -18,7 +18,7 @@ To develop the Worker mode, perform the following steps:
}
}
```
```
2. Create the **worker.js** file based on the configuration in **build-profile.json5**.
2. Create the **worker.ts** file based on the configuration in **build-profile.json5**.
```ts
```ts
importworkerfrom'@ohos.worker';
importworkerfrom'@ohos.worker';
...
@@ -58,7 +58,7 @@ To develop the Worker mode, perform the following steps:
...
@@ -58,7 +58,7 @@ To develop the Worker mode, perform the following steps:
```ts
```ts
import worker from '@ohos.worker';
import worker from '@ohos.worker';
let wk = new worker.ThreadWorker("../workers/worker.js");
let wk = new worker.ThreadWorker("../workers/worker.ts");
// Send a message to the worker thread.
// Send a message to the worker thread.
wk.postMessage("message from main thread.")
wk.postMessage("message from main thread.")
...
@@ -74,6 +74,6 @@ To develop the Worker mode, perform the following steps:
...
@@ -74,6 +74,6 @@ To develop the Worker mode, perform the following steps:
> **NOTE**
> **NOTE**
>
>
> - If the relative path of **worker.ts** configured in **build-profile.json5** is **./src/main/ets/workers/worker.ts**, pass in the path **entry/ets/workers/worker.ts** when creating a worker thread in the stage model, and pass in the path **../workers/worker.js** when creating a worker thread in the FA model.
> - If the relative path of **worker.ts** configured in **build-profile.json5** is **./src/main/ets/workers/worker.ts**, pass in the path **entry/ets/workers/worker.ts** when creating a worker thread in the stage model, and pass in the path **../workers/worker.ts** when creating a worker thread in the FA model.
>
>
> - For details about the data types supported between the main thread and worker thread, see [Sequenceable Data Types](../reference/apis/js-apis-worker.md#sequenceable-data-types).
> - For details about the data types supported between the main thread and worker thread, see [Sequenceable Data Types](../reference/apis/js-apis-worker.md#sequenceable-data-types).
@@ -40,4 +40,4 @@ During application development based on the stage model, the following tasks are
...
@@ -40,4 +40,4 @@ During application development based on the stage model, the following tasks are
| Inter-process communication (IPC)| Learn the process model and common IPC modes of the stage model.| - [Common Events](common-event-overview.md)<br>- [Background Services](background-services.md)|
| Inter-process communication (IPC)| Learn the process model and common IPC modes of the stage model.| - [Common Events](common-event-overview.md)<br>- [Background Services](background-services.md)|
| Inter-thread communication| Learn the thread model and common inter-thread communication modes of the stage model.| - [Emitter](itc-with-emitter.md)<br>- [Worker](itc-with-worker.md)|
| Inter-thread communication| Learn the thread model and common inter-thread communication modes of the stage model.| - [Emitter](itc-with-emitter.md)<br>- [Worker](itc-with-worker.md)|
| Mission management| Learn the basic concepts and typical scenarios of mission management in the stage model.| - [Mission Management Scenarios](mission-management-overview.md)<br>- [Mission Management and Launch Type](mission-management-launch-type.md)<br>- [Page Stack and Mission List](page-mission-stack.md)|
| Mission management| Learn the basic concepts and typical scenarios of mission management in the stage model.| - [Mission Management Scenarios](mission-management-overview.md)<br>- [Mission Management and Launch Type](mission-management-launch-type.md)<br>- [Page Stack and Mission List](page-mission-stack.md)|
| Application configuration file| Learn the requirements for developing application configuration files in the stage model.| [Application Configuration File](config-file-stage.md)|
| Application configuration file| Learn the requirements for developing application configuration files in the stage model.| [Application Configuration File](../quick-start/application-configuration-file-overview-stage.md)|
@@ -412,7 +412,6 @@ In summary, when a UIAbility instance of application A has been created and the
...
@@ -412,7 +412,6 @@ In summary, when a UIAbility instance of application A has been created and the
```
```
> **NOTE**
> **NOTE**
>
> When the [launch type of the callee UIAbility](uiability-launch-type.md) is set to **standard**, a new instance is created each time the callee UIAbility is started. In this case, the [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback will not be invoked.
> When the [launch type of the callee UIAbility](uiability-launch-type.md) is set to **standard**, a new instance is created each time the callee UIAbility is started. In this case, the [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback will not be invoked.
...
@@ -432,7 +431,7 @@ Ability call is usually used in the following scenarios:
...
@@ -432,7 +431,7 @@ Ability call is usually used in the following scenarios:
- Starting the callee ability in the background
- Starting the callee ability in the background
**Table 1** Terms used in the ability call
**Table 1** Terms used in the ability call
| **Term**| Description|
| **Term**| Description|
| -------- | -------- |
| -------- | -------- |
...
@@ -443,9 +442,9 @@ Ability call is usually used in the following scenarios:
...
@@ -443,9 +442,9 @@ Ability call is usually used in the following scenarios:
The following figure shows the ability call process.
The following figure shows the ability call process.
**Figure 1** Ability call process
Figure 1 Ability call process
- The caller ability uses **startAbilityByCall** to obtain a caller object and uses **call()** of the caller object to send data to the callee ability.
- The caller ability uses **startAbilityByCall** to obtain a caller object and uses **call()** of the caller object to send data to the callee ability.
...
@@ -463,15 +462,15 @@ The following figure shows the ability call process.
...
@@ -463,15 +462,15 @@ The following figure shows the ability call process.
The following table describes the main APIs used for the ability call. For details, see [AbilityContext](../reference/apis/js-apis-app-ability-uiAbility.md#caller).
The following table describes the main APIs used for the ability call. For details, see [AbilityContext](../reference/apis/js-apis-app-ability-uiAbility.md#caller).
**Table 2** Ability call APIs
**Table 2** Ability call APIs
| API| Description|
| API| Description|
| -------- | -------- |
| -------- | -------- |
| startAbilityByCall(want: Want): Promise<Caller> | Starts a UIAbility in the foreground (through the **want** configuration) or background (default) and obtains the caller object for communication with the UIAbility. For details, see [AbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstartabilitybycall) or [ServiceExtensionContext](../reference/apis/js-apis-inner-application-serviceExtensionContext.md#serviceextensioncontextstartabilitybycall).|
| startAbilityByCall(want: Want): Promise<Caller> | Starts a UIAbility in the foreground (through the **want** configuration) or background (default) and obtains the caller object for communication with the UIAbility. For details, see [AbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstartabilitybycall) or [ServiceExtensionContext](../reference/apis/js-apis-inner-application-serviceExtensionContext.md#serviceextensioncontextstartabilitybycall).|
| on(method: string, callback: CalleeCallBack): void | Callback invoked when the callee ability registers a method.|
| on(method: string, callback: CalleeCallBack): void | Callback invoked when the callee ability registers a method.|
| off(method: string): void | Callback invoked when the callee ability deregisters a method.|
| off(method: string): void | Callback invoked when the callee ability deregisters a method.|
| call(method: string, data: rpc.Sequenceable): Promise<void> | Sends agreed sequenceable data to the callee ability.|
| call(method: string, data: rpc.Parcelable): Promise<void> | Sends agreed parcelable data to the callee ability.|
| callWithResult(method: string, data: rpc.Sequenceable): Promise<rpc.MessageParcel> | Sends agreed sequenceable data to the callee ability and obtains the agreed sequenceable data returned by the callee ability.|
| callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence> | Sends agreed parcelable data to the callee ability and obtains the agreed parcelable data returned by the callee ability.|
| release(): void | Releases the caller object.|
| release(): void | Releases the caller object.|
| on(type: "release", callback: OnReleaseCallback): void | Callback invoked when the caller object is released.|
| on(type: "release", callback: OnReleaseCallback): void | Callback invoked when the caller object is released.|
...
@@ -487,16 +486,15 @@ The implementation of using the ability call for UIAbility interaction involves
...
@@ -487,16 +486,15 @@ The implementation of using the ability call for UIAbility interaction involves
For the callee ability, implement the callback to receive data and the methods to marshal and unmarshal data. When data needs to be received, use **on()** to register a listener. When data does not need to be received, use **off()** to deregister the listener.
For the callee ability, implement the callback to receive data and the methods to marshal and unmarshal data. When data needs to be received, use **on()** to register a listener. When data does not need to be received, use **off()** to deregister the listener.
1. Configure the ability launch type.
1. Configure the ability launch type.
Set **launchType** of the callee ability to **singleton** in the **module.json5** file.
Set **launchType** of the callee ability to **singleton** in the **module.json5** file.
| JSON Field| Description|
| JSON Field| Description|
| -------- | -------- |
| -------- | -------- |
| "launchType" | Ability launch type. Set this parameter to **singleton**.|
| "launchType" | Ability launch type. Set this parameter to **singleton**.|
An example of the ability configuration is as follows:
An example of the ability configuration is as follows:
```json
```json
"abilities":[{
"abilities":[{
"name":".CalleeAbility",
"name":".CalleeAbility",
...
@@ -510,18 +508,17 @@ An example of the ability configuration is as follows:
...
@@ -510,18 +508,17 @@ An example of the ability configuration is as follows:
```
```
2. Import the **UIAbility** module.
2. Import the **UIAbility** module.
```ts
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
importAbilityfrom'@ohos.app.ability.UIAbility';
```
```
3. Define the agreed sequenceable data.
3. Define the agreed parcelable data.
The data formats sent and received by the caller and callee abilities must be consistent. In the following example, the data formats are number and string.
The data formats sent and received by the caller and callee abilities must be consistent. In the following example, the data formats are number and string.
```ts
```ts
exportdefaultclassMySequenceable{
exportdefaultclassMyParcelable{
num:number=0
num:number=0
str:string=""
str:string=""
...
@@ -530,25 +527,24 @@ An example of the ability configuration is as follows:
...
@@ -530,25 +527,24 @@ An example of the ability configuration is as follows:
this.str=string
this.str=string
}
}
marshalling(messageParcel){
marshalling(messageSequence){
messageParcel.writeInt(this.num)
messageSequence.writeInt(this.num)
messageParcel.writeString(this.str)
messageSequence.writeString(this.str)
returntrue
returntrue
}
}
unmarshalling(messageParcel){
unmarshalling(messageSequence){
this.num=messageParcel.readInt()
this.num=messageSequence.readInt()
this.str=messageParcel.readString()
this.str=messageSequence.readString()
returntrue
returntrue
}
}
}
}
```
```
4. Implement **Callee.on** and **Callee.off**.
4. Implement **Callee.on** and **Callee.off**.
The time to register a listener for the callee ability depends on your application. The data sent and received before the listener is registered and that after the listener is deregistered are not processed. In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate** of the ability and deregistered in **onDestroy**. After receiving parcelable data, the application processes the data and returns the data result. You need to implement processing based on service requirements. The sample code is as follows:
The time to register a listener for the callee ability depends on your application. The data sent and received before the listener is registered and that after the listener is deregistered are not processed. In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate** of the ability and deregistered in **onDestroy**. After receiving sequenceable data, the application processes the data and returns the data result. You need to implement processing based on service requirements. The sample code is as follows:
```ts
```ts
constTAG:string='[CalleeAbility]';
constTAG:string='[CalleeAbility]';
constMSG_SEND_METHOD:string='CallSendMsg';
constMSG_SEND_METHOD:string='CallSendMsg';
...
@@ -556,14 +552,14 @@ An example of the ability configuration is as follows:
...
@@ -556,14 +552,14 @@ An example of the ability configuration is as follows:
functionsendMsgCallback(data){
functionsendMsgCallback(data){
console.info('CalleeSortFunc called');
console.info('CalleeSortFunc called');
// Obtain the sequenceable data sent by the caller ability.
// Obtain the parcelable data sent by the caller ability.
@@ -595,10 +591,9 @@ An example of the ability configuration is as follows:
...
@@ -595,10 +591,9 @@ An example of the ability configuration is as follows:
```
```
2. Obtain the caller interface.
2. Obtain the caller interface.
The **context** attribute of the ability implements **startAbilityByCall** to obtain the caller object for communication. The following example uses **this.context** to obtain the **context** attribute of the ability, uses **startAbilityByCall** to start the callee ability, obtain the caller object, and register the **onRelease** listener of the caller ability. You need to implement processing based on service requirements.
The **context** attribute of the ability implements **startAbilityByCall** to obtain the caller object for communication. The following example uses **this.context** to obtain the **context** attribute of the ability, uses **startAbilityByCall** to start the callee ability, obtain the caller object, and register the **onRelease** listener of the caller ability. You need to implement processing based on service requirements.
```ts
```ts
// Register the onRelease() listener of the caller ability.
// Register the onRelease() listener of the caller ability.
@@ -812,6 +812,6 @@ Enumerates the flags that specify how the Want will be handled.
...
@@ -812,6 +812,6 @@ Enumerates the flags that specify how the Want will be handled.
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that the migration is reversible. |
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that the migration is reversible. |
| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. |
| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. |
| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. |
| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. |
| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object in the **startAbility** API passed to [ohos.app.Context](js-apis-ability-context.md) and must be used together with **flag_ABILITY_NEW_MISSION**.|
| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the [Want](js-apis-application-want.md) object under [parameter](js-apis-inner-ability-startAbilityParameter.md) in the [startAbility](#featureabilitystartability) API passed to the **FeatureAbility** module and must be used together with **flag_ABILITY_NEW_MISSION**.|
| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on an existing mission stack. |
| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on an existing mission stack. |
| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Reuses an ability instance if it is on the top of an existing mission stack; creates an ability instance otherwise.|
| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Reuses an ability instance if it is on the top of an existing mission stack; creates an ability instance otherwise.|
@@ -84,6 +84,6 @@ Enumerates the flags that specify how the Want will be handled.
...
@@ -84,6 +84,6 @@ Enumerates the flags that specify how the Want will be handled.
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that ability continuation is reversible.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that ability continuation is reversible.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. |
| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. |
| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. |
| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. |
| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object in the **startAbility** API passed to [ohos.app.Context](js-apis-ability-context.md) and must be used together with **flag_ABILITY_NEW_MISSION**.|
| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object in the [startAbility](js-apis-ability-featureAbility.md#startability) API passed to the **FeatureAbility** module and must be used together with **flag_ABILITY_NEW_MISSION**.|
| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on the history mission stack. |
| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on the history mission stack. |
| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Reuses an ability instance if it is on the top of an existing mission stack; creates an ability instance otherwise.|
| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Reuses an ability instance if it is on the top of an existing mission stack; creates an ability instance otherwise.|
| START_ABILITY | 1 | The ability is started by calling [startAbility](js-apis-ability-context.md#abilitycontextstartability).|
| START_ABILITY | 1 | The ability is started by calling [startAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability).|
| CALL | 2 | The ability is started by calling [startAbilityByCall](js-apis-ability-context.md#abilitycontextstartabilitybycall).|
| CALL | 2 | The ability is started by calling [startAbilityByCall](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartabilitybycall).|
| CONTINUATION | 3 | The ability is started by means of cross-device migration.|
| CONTINUATION | 3 | The ability is started by means of cross-device migration.|
| APP_RECOVERY | 4 | The ability is automatically started when the application is restored from a fault.|
| APP_RECOVERY | 4 | The ability is automatically started when the application is restored from a fault.|
...
@@ -124,8 +124,8 @@ Enumerates the window modes in which an ability can be displayed at startup. It
...
@@ -124,8 +124,8 @@ Enumerates the window modes in which an ability can be displayed at startup. It
# @ohos.app.ability.ExtensionAbility (ExtensionAbility Base Class)
# @ohos.app.ability.ExtensionAbility (ExtensionAbility Base Class)
**ExtensionAbility** is the base class for scenario-specific ExtensionAbilities. It is inherited from [Ability](js-apis-app-ability-ability.md), with no attribute or method added. You cannot inherit from this base class.
**ExtensionAbility** is the base class for scenario-specific ExtensionAbilities. It provides the callbacks for system configuration updates and memory level updates.
> **NOTE**
> **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.
> 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.
> The APIs of this module can be used only in the stage model.
> The APIs of this module can be used only in the stage model.
The **ServiceExtensionAbility** module provides APIs for ServiceExtensionAbilities.
The **ServiceExtensionAbility** module provides lifecycle callbacks when a ServiceExtensionAbility (background service) is created, destroyed, connected, or disconnected.
> **NOTE**
> **NOTE**
>
>
...
@@ -150,7 +150,7 @@ Called following **onCreate()** when a ServiceExtensionAbility is started by cal
...
@@ -150,7 +150,7 @@ Called following **onCreate()** when a ServiceExtensionAbility is started by cal
onDisconnect(want: Want): void | Promise<void>;
onDisconnect(want: Want): void | Promise<void>;
Called when this ServiceExtensionAbility is disconnected.
Called when a client is disconnected from this ServiceExtensionAbility.
The **StartOptions** module implements ability startup options.
**StartOptions** is used as an input parameter of [startAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability-1) to specify the window mode of an ability.
The **Ability** module manages the ability lifecycle and context, such as creating and destroying an ability, and dumping client information.
UIAbility is an application component that has the UI. The **UIAbility** module provides lifecycle callback such as component creation, destruction, and foreground/background switching. It also provides the following capabilities related to component collaboration:
This module provides the following common ability-related functions:
-[Caller](#caller): an object returned by [startAbilityByCall](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartabilitybycall). The CallerAbility (caller) uses this object to communicate with the CalleeAbility (callee).
-[Caller](#caller): implements sending of sequenceable data to the target ability when an ability (caller ability) invokes the target ability (callee ability).
-[Callee](#callee): an internal object of UIAbility. The CalleeAbility (callee) uses this object to communicate with the CallerAbility (caller).
-[Callee](#callee): implements callbacks for registration and deregistration of caller notifications.
> **NOTE**
> **NOTE**
>
>
...
@@ -23,12 +22,12 @@ import Ability from '@ohos.app.ability.UIAbility';
...
@@ -23,12 +22,12 @@ import Ability from '@ohos.app.ability.UIAbility';
@@ -40,7 +39,7 @@ Called to initialize the service logic when an ability is created.
...
@@ -40,7 +39,7 @@ Called to initialize the service logic when an ability is created.
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-app-ability-want.md) | Yes| Information related to this ability, including the ability name and bundle name.|
| want | [Want](js-apis-app-ability-want.md) | Yes| Information related to this UIAbility, including the ability name and bundle name.|
| param | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Parameters for starting the ability, and the reason for the last abnormal exit.|
| param | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Parameters for starting the ability, and the reason for the last abnormal exit.|
**Example**
**Example**
...
@@ -54,11 +53,11 @@ Called to initialize the service logic when an ability is created.
...
@@ -54,11 +53,11 @@ Called to initialize the service logic when an ability is created.
@@ -227,7 +226,7 @@ Called when a new Want is passed in and this ability is started again.
...
@@ -227,7 +226,7 @@ Called when a new Want is passed in and this ability is started again.
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-app-ability-want.md) | Yes| Want information, such as the ability name and bundle name.|
| want | [Want](js-apis-app-ability-want.md) | Yes| Want information, such as the ability name and bundle name.|
| launchParams | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Reason for the ability startup and the last abnormal exit.|
| launchParams | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Reason for the UIAbility startup and the last abnormal exit.|
**Example**
**Example**
...
@@ -240,7 +239,7 @@ Called when a new Want is passed in and this ability is started again.
...
@@ -240,7 +239,7 @@ Called when a new Want is passed in and this ability is started again.
Called when the framework automatically saves the ability state in the case of an application fault. This API is used together with [appRecovery](js-apis-app-ability-appRecovery.md). If automatic state saving is enabled, **onSaveState** is called to save the state of this ability.
Called when the framework automatically saves the UIAbility state in the case of an application fault. This API is used together with [appRecovery](js-apis-app-ability-appRecovery.md). If automatic state saving is enabled, **onSaveState** is called to save the state of this ability.
@@ -278,7 +277,7 @@ Called when the framework automatically saves the ability state in the case of a
...
@@ -278,7 +277,7 @@ Called when the framework automatically saves the ability state in the case of a
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| reason | [AbilityConstant.StateType](js-apis-application-abilityConstant.md#abilityconstantstatetype) | Yes| Reason for triggering the callback to save the ability state.|
| reason | [AbilityConstant.StateType](js-apis-app-ability-abilityConstant.md#abilityconstantstatetype) | Yes| Reason for triggering the callback to save the UIAbility state.|
| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.|
| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the parcelable data.|
| data | [rpc.Parcelable](js-apis-rpc.md#parcelabledeprecated) | Yes| Sequenceable data. You need to customize the data.|
| data | [rpc.Parcelable](js-apis-rpc.md#parcelable9) | Yes| Parcelable data. You need to customize the data.|
**Return value**
**Return value**
...
@@ -333,13 +332,12 @@ Sends sequenceable data to the target ability.
...
@@ -333,13 +332,12 @@ Sends sequenceable data to the target ability.
| ID| Error Message|
| ID| Error Message|
| ------- | -------------------------------- |
| ------- | -------------------------------- |
| 401 | If the input parameter is not valid parameter. |
| 401 | If the input parameter is not valid parameter. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
**Example**
```ts
```ts
classMyMessageAble{// Custom sequenceable data structure.
classMyMessageAble{// Custom parcelable data structure.
name:''
name:''
str:''
str:''
num:1
num:1
...
@@ -347,15 +345,15 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error
...
@@ -347,15 +345,15 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error
| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.|
| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the parcelable data.|
| data | [rpc.Parcelable](js-apis-rpc.md#parcelabledeprecated) | Yes| Sequenceable data. You need to customize the data.|
| data | [rpc.Parcelable](js-apis-rpc.md#parcelable9) | Yes| Parcelable data. You need to customize the data.|
**Return value**
**Return value**
| Type| Description|
| Type| Description|
| -------- | -------- |
| -------- | -------- |
| Promise<[rpc.MessageParcel](js-apis-rpc.md#sequenceabledeprecated)> | Promise used to return the sequenceable data from the target ability.|
| Promise<[rpc.MessageSequence](js-apis-rpc.md#messagesequence9)> | Promise used to return the parcelable data from the target ability.|
**Error codes**
**Error codes**
| ID| Error Message|
| ID| Error Message|
| ------- | -------------------------------- |
| ------- | -------------------------------- |
| 401 | If the input parameter is not valid parameter. |
| 401 | If the input parameter is not valid parameter. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
**Example**
...
@@ -428,15 +425,15 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error
...
@@ -428,15 +425,15 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error
@@ -576,7 +573,6 @@ Registers a callback that is invoked when the stub on the target ability is disc
...
@@ -576,7 +573,6 @@ Registers a callback that is invoked when the stub on the target ability is disc
| ID| Error Message|
| ID| Error Message|
| ------- | -------------------------------- |
| ------- | -------------------------------- |
| 401 | If the input parameter is not valid parameter. |
| 401 | If the input parameter is not valid parameter. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
**Example**
...
@@ -627,7 +623,7 @@ Deregisters a callback that is invoked when the stub on the target ability is di
...
@@ -627,7 +623,7 @@ Deregisters a callback that is invoked when the stub on the target ability is di
| ID| Error Message|
| ID| Error Message|
| ------- | -------------------------------- |
| ------- | -------------------------------- |
| 401 | If the input parameter is not valid parameter. |
| 401 | If the input parameter is not valid parameter. |
For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
**Example**
...
@@ -678,7 +674,7 @@ Deregisters a callback that is invoked when the stub on the target ability is di
...
@@ -678,7 +674,7 @@ Deregisters a callback that is invoked when the stub on the target ability is di
| ID| Error Message|
| ID| Error Message|
| ------- | -------------------------------- |
| ------- | -------------------------------- |
| 401 | If the input parameter is not valid parameter. |
| 401 | If the input parameter is not valid parameter. |
For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
**Example**
...
@@ -724,17 +720,16 @@ Registers a caller notification callback, which is invoked when the target abili
...
@@ -724,17 +720,16 @@ Registers a caller notification callback, which is invoked when the target abili
**Parameters**
**Parameters**
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| method | string | Yes| Notification message string negotiated between the two abilities.|
| method | string | Yes| Notification message string negotiated between the two abilities.|
| callback | [CalleeCallback](#calleecallback) | Yes| JS notification synchronization callback of the [rpc.MessageParcel](js-apis-rpc.md#sequenceabledeprecated) type. The callback must return at least one empty [rpc.Sequenceable](js-apis-rpc.md#sequenceabledeprecated) object. Otherwise, the function execution fails.|
| callback | [CalleeCallback](#calleecallback) | Yes| JS notification synchronization callback of the [rpc.MessageSequence](js-apis-rpc.md#messagesequence9) type. The callback must return at least one empty [rpc.Parcelable](js-apis-rpc.md#parcelable9) object. Otherwise, the function execution fails.|
**Error codes**
**Error codes**
| ID| Error Message|
| ID| Error Message|
| ------- | -------------------------------- |
| ------- | -------------------------------- |
| 401 | If the input parameter is not valid parameter. |
| 401 | If the input parameter is not valid parameter. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
**Example**
...
@@ -748,15 +743,15 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error
...
@@ -748,15 +743,15 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error
| (indata: [rpc.MessageParcel](js-apis-rpc.md#sequenceabledeprecated)) | Yes| No| [rpc.Parcelable](js-apis-rpc.md#parcelabledeprecated) | Prototype of the listener function registered by the callee.|
| (indata: [rpc.MessageSequence](js-apis-rpc.md#messagesequence9)) | Yes| No| [rpc.Parcelable](js-apis-rpc.md#parcelable9) | Prototype of the listener function registered by the callee.|
| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Yes | No | Context of the FormExtensionAbility. This context is inherited from **ExtensionContext**.|
| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Yes | No | Context of the FormExtensionAbility. This context is inherited from [ExtensionContext](js-apis-inner-application-extensionContext.md).|
## onAddForm
## onAddForm
...
@@ -33,7 +33,7 @@ Called to notify the widget provider that a **Form** instance (widget) has been
...
@@ -33,7 +33,7 @@ Called to notify the widget provider that a **Form** instance (widget) has been
| want | [Want](js-apis-application-want.md) | Yes | Want information related to the ExtensionAbility, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
| want | [Want](js-apis-application-want.md) | Yes | Want information related to the FormExtensionAbility, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-ability-context.md).|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).|
| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
...
@@ -253,7 +253,7 @@ Requests a continuous task from the system. This API uses a promise to return th
...
@@ -253,7 +253,7 @@ Requests a continuous task from the system. This API uses a promise to return th
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-ability-context.md).|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).|
| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
...
@@ -339,7 +339,7 @@ Requests to cancel a continuous task. This API uses an asynchronous callback to
...
@@ -339,7 +339,7 @@ Requests to cancel a continuous task. This API uses an asynchronous callback to
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-ability-context.md).|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
**Example**
...
@@ -395,7 +395,7 @@ Requests to cancel a continuous task. This API uses a promise to return the resu
...
@@ -395,7 +395,7 @@ Requests to cancel a continuous task. This API uses a promise to return the resu
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-ability-context.md).|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).|
| status | bundle.[InstallErrorCode](js-apis-Bundle.md#installerrorcode) | Yes | No | Installation or uninstall error code. The value must be defined in [InstallErrorCode](js-apis-Bundle.md#installerrorcode). |
| status | bundle.[InstallErrorCode](js-apis-Bundle.md#installerrorcode) | Yes | No | Installation or uninstall error code. The value must be defined in [InstallErrorCode](js-apis-Bundle.md#installerrorcode)|
| statusMessage | string | Yes | No | Installation or uninstall status message. <br>**SUCCESS**: install_succeed<br>**STATUS_INSTALL_FAILURE**: Installation failed (no installation file exists).<br>**STATUS_INSTALL_FAILURE_ABORTED**: Installation aborted.<br>**STATUS_INSTALL_FAILURE_INVALID**: Invalid installation parameter.<br>**STATUS_INSTALL_FAILURE_CONFLICT**: Installation conflict. (The basic information of the application to update is inconsistent with that of the existing application.)<br>**STATUS_INSTALL_FAILURE_STORAGE**: Failed to store the bundle information.<br>**STATUS_INSTALL_FAILURE_INCOMPATIBLE**: Installation incompatibility. (A downgrade occurs or the signature information is incorrect.)<br>**STATUS_UNINSTALL_FAILURE**: Uninstallation failed. (The application to be uninstalled is not found.)<br>**STATUS_UNINSTALL_FAILURE_ABORTED**: Uninstallation aborted. (This error code is not in use.)<br>**STATUS_UNINSTALL_FAILURE_ABORTED**: Uninstallation conflict. (Failed to uninstall a system application or end the application process.)<br>**STATUS_INSTALL_FAILURE_DOWNLOAD_TIMEOUT**: Installation failed. (Download timed out.)<br>**STATUS_INSTALL_FAILURE_DOWNLOAD_FAILED**: Installation failed. (Download failed.)<br>**STATUS_RECOVER_FAILURE_INVALID**: Failed to restore the pre-installed application.<br>**STATUS_ABILITY_NOT_FOUND**: Ability not found.<br>**STATUS_BMS_SERVICE_ERROR**: BMS service error.<br>**STATUS_FAILED_NO_SPACE_LEFT**: Insufficient device space.<br>**STATUS_GRANT_REQUEST_PERMISSIONS_FAILED**: Application authorization failed.<br>**STATUS_INSTALL_PERMISSION_DENIED**: No installation permission.<br>**STATUS_UNINSTALL_PERMISSION_DENIED**: No uninstallation permission. |
| statusMessage | string | Yes | No | Installation or uninstall status message. <br>**SUCCESS**: install_succeed<br>**STATUS_INSTALL_FAILURE**: Installation failed (no installation file exists).<br>**STATUS_INSTALL_FAILURE_ABORTED**: Installation aborted.<br>**STATUS_INSTALL_FAILURE_INVALID**: Invalid installation parameter.<br>**STATUS_INSTALL_FAILURE_CONFLICT**: Installation conflict. (The basic information of the application to update is inconsistent with that of the existing application.)<br>**STATUS_INSTALL_FAILURE_STORAGE**: Failed to store the bundle information.<br>**STATUS_INSTALL_FAILURE_INCOMPATIBLE**: Installation incompatibility. (A downgrade occurs or the signature information is incorrect.)<br>**STATUS_UNINSTALL_FAILURE**: Uninstallation failed. (The application to be uninstalled is not found.)<br>**STATUS_UNINSTALL_FAILURE_ABORTED**: Uninstallation aborted. (This error code is not in use.)<br>**STATUS_UNINSTALL_FAILURE_ABORTED**: Uninstallation conflict. (Failed to uninstall a system application or end the application process.)<br>**STATUS_INSTALL_FAILURE_DOWNLOAD_TIMEOUT**: Installation failed. (Download timed out.)<br>**STATUS_INSTALL_FAILURE_DOWNLOAD_FAILED**: Installation failed. (Download failed.)<br>**STATUS_RECOVER_FAILURE_INVALID**: Failed to restore the pre-installed application.<br>**STATUS_ABILITY_NOT_FOUND**: Ability not found.<br>**STATUS_BMS_SERVICE_ERROR**: BMS service error.<br>**STATUS_FAILED_NO_SPACE_LEFT**: Insufficient device space.<br>**STATUS_GRANT_REQUEST_PERMISSIONS_FAILED**: Application authorization failed.<br>**STATUS_INSTALL_PERMISSION_DENIED**: No installation permission.<br>**STATUS_UNINSTALL_PERMISSION_DENIED**: No uninstallation permission. |
## Obtaining the Sandbox Path
## Obtaining the Sandbox Path
For the FA model, the sandbox path of a bundle can be obtained using the APIs in [Context](js-apis-inner-app-context.md). For the stage model, the sandbox path can be obtained using the attribute in [Context](js-apis-ability-context.md#abilitycontext). The following describes how to obtain the sandbox path.
For the FA model, the sandbox path of a bundle can be obtained using the APIs in [Context](js-apis-inner-app-context.md). For the stage model, the sandbox path can be obtained using the attribute in [Context](js-apis-inner-application-uiAbilityContext.md#abilitycontext). The following describes how to obtain the sandbox path.
Validates the X.509 certificate chain. This API uses an asynchronous callback to return the result.
Validates the X.509 certificate chain. This API uses an asynchronous callback to return the result.
The certificate chain validator does not verify the certificate validity period because the system time on the device is untrusted. To check the validity period of a certificate, use the [checkValidityWithDate()](#checkvaliditywithdate) API of the **X509Cert** class. For details, see [Certificate Specifications](./../security/cert-overview.md#certificate-specifications).
The certificate chain validator does not verify the certificate validity period because the system time on the device is untrusted. To check the validity period of a certificate, use the [checkValidityWithDate()](#checkvaliditywithdate) API of the **X509Cert** class. For details, see [Certificate Specifications](../../security/cert-overview.md#certificate-specifications).
Validates the X.509 certificate chain. This API uses a promise to return the result.
Validates the X.509 certificate chain. This API uses a promise to return the result.
The certificate chain validator does not verify the certificate validity period because the system time on the device is untrusted. To check the validity period of a certificate, use the [checkValidityWithDate()](#checkvaliditywithdate) API of the **X509Cert** class. For details, see [Certificate Specifications](./../security/cert-overview.md#certificate-specifications).
The certificate chain validator does not verify the certificate validity period because the system time on the device is untrusted. To check the validity period of a certificate, use the [checkValidityWithDate()](#checkvaliditywithdate) API of the **X509Cert** class. For details, see [Certificate Specifications](../../security/cert-overview.md#certificate-specifications).
| transformation | string | Yes | Combination of the algorithm name (including the key length), encryption mode, and padding algorithm of the **Cipher** instance to create.<br>For details, see **Algorithm String** in [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications). |
| transformation | string | Yes | Combination of the algorithm name (including the key length), encryption mode, and padding algorithm of the **Cipher** instance to create.<br>For details, see **Algorithm String** in [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications). |
> **NOTE**
> **NOTE**
> - In symmetric encryption and decryption, the implementation of PKCS #5 is the same as that of PKCS #7. PKCS #5 and PKCS #7 use the same padding length and block length. That is, data is padded with 8 bytes in 3DES and 16 bytes in AES. **noPadding** indicates that no padding is performed. <br>You need to understand the differences between different block cipher modes and set parameter correctly. For example, padding is required for ECB and CBC. Otherwise, the plaintext length must be an integer multiple of the block size. No padding is recommended for other modes. In this case, the ciphertext length is the same as the plaintext length.
> - In symmetric encryption and decryption, the implementation of PKCS #5 is the same as that of PKCS #7. PKCS #5 and PKCS #7 use the same padding length and block length. That is, data is padded with 8 bytes in 3DES and 16 bytes in AES. **noPadding** indicates that no padding is performed. <br>You need to understand the differences between different block cipher modes and set parameter correctly. For example, padding is required for ECB and CBC. Otherwise, the plaintext length must be an integer multiple of the block size. No padding is recommended for other modes. In this case, the ciphertext length is the same as the plaintext length.
Updates the data to be signed. This API uses an asynchronous callback to return the result.
Updates the data to be signed. This API uses an asynchronous callback to return the result.
> **NOTE**<br>
> **NOTE**<br>
> For details about the sample code for calling **update()** multiple times, see [Signing Data and Verifying Signatures](../../security/cryptoFramework-guidelines.md#signing-data-and-verifying-signatures).
> For details about the sample code for calling **update()** multiple times, see [Generating and Verifying a Signature](../../security/cryptoFramework-guidelines.md#generating-and-verifying-a-signature).
Updates the data to be signed. This API uses a promise to return the result.
Updates the data to be signed. This API uses a promise to return the result.
> **NOTE**<br>
> **NOTE**<br>
> For details about the sample code for calling **update()** multiple times, see [Signing Data and Verifying Signatures](../../security/cryptoFramework-guidelines.md#signing-data-and-verifying-signatures).
> For details about the sample code for calling **update()** multiple times, see [Generating and Verifying a Signature](../../security/cryptoFramework-guidelines.md#generating-and-verifying-a-signature).
Updates the data for signature verification. This API uses an asynchronous callback to return the result.
Updates the data for signature verification. This API uses an asynchronous callback to return the result.
> **NOTE**
> **NOTE**
> For details about the sample code for calling **update()** multiple times, see [Signing Data and Verifying Signatures](../../security/cryptoFramework-guidelines.md#signing-data-and-verifying-signatures).
> For details about the sample code for calling **update()** multiple times, see [Generating and Verifying a Signature](../../security/cryptoFramework-guidelines.md#generating-and-verifying-a-signature).
Updates the data for signature verification. This API uses a promise to return the result.
Updates the data for signature verification. This API uses a promise to return the result.
> **NOTE**
> **NOTE**
> For details about the sample code for calling **update()** multiple times, see [Signing Data and Verifying Signatures](../../security/cryptoFramework-guidelines.md#signing-data-and-verifying-signatures).
> For details about the sample code for calling **update()** multiple times, see [Generating and Verifying a Signature](../../security/cryptoFramework-guidelines.md#generating-and-verifying-a-signature).
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-ability-context.md).|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).|
| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
...
@@ -312,7 +312,7 @@ Requests a continuous task from the system. This API uses a promise to return th
...
@@ -312,7 +312,7 @@ Requests a continuous task from the system. This API uses a promise to return th
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-ability-context.md).|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).|
| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
...
@@ -389,7 +389,7 @@ Requests to cancel a continuous task. This API uses an asynchronous callback to
...
@@ -389,7 +389,7 @@ Requests to cancel a continuous task. This API uses an asynchronous callback to
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-ability-context.md).|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
**Error codes**
...
@@ -445,7 +445,7 @@ Requests to cancel a continuous task. This API uses a promise to return the resu
...
@@ -445,7 +445,7 @@ Requests to cancel a continuous task. This API uses a promise to return the resu
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-ability-context.md).|
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).|
> - The APIs of this module are no longer maintained since API version 7. You are advised to use the new APIs.
> - The APIs of this module are no longer maintained since API version 7. You are advised to use the new APIs.
>
>
> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...
@@ -9,8 +10,8 @@
...
@@ -9,8 +10,8 @@
## Modules to Import
## Modules to Import
```ts
```
importappfrom'@system.app'
import app from '@system.app';
```
```
...
@@ -20,8 +21,8 @@ getInfo(): AppResponse
...
@@ -20,8 +21,8 @@ getInfo(): AppResponse
Obtains the declared information in the **config.json** file of an application.
Obtains the declared information in the **config.json** file of an application.
> **NOTE**
> **NOTE**
>
>
> You are advised to use [@ohos.bundle](js-apis-Bundle.md) since API version 7.
> You are advised to use [@ohos.bundle](js-apis-Bundle.md) since API version 7.
Requests the application to run in full window. You can call this API when the FA runs in a non-full window, for example, semi-modal FA. This API is invalid for an application already in full-window mode.
Requests the application to run in full window. You can call this API when the FA runs in a non-full window, for example, semi-modal FA. This API is invalid for an application already in full-window mode.
This is a system API and cannot be called by third-party applications.
> **NOTE**
>
> **NOTE**
>
> You are advised to use [@ohos.window](js-apis-window.md) since API version 7.
> You are advised to use [@ohos.window](js-apis-window.md) since API version 7.
| options | [RequestFullWindowOptions](#requestfullwindowoptions) | No| Duration for transition from the non-full window to the full window, in milliseconds. By default, the value is in direct proportion to the distance between the non-full window and the full window.|
| options | [RequestFullWindowOptions](#requestfullwindowoptions) | No| Duration for transition from the non-full window to the full window, in milliseconds. By default, the value is in direct proportion to the distance between the non-full window and the full window.|
**Example**
**Example**
```ts
```
exportdefault{
export default {
requestFullWindow(){
requestFullWindow(){
app.requestFullWindow({
app.requestFullWindow({
duration:200
duration: 200});
})
}
}
}
}
```
```
## app.setImageCacheCount<sup>7+</sup>
## app.setImageCacheCount<sup>7+</sup>
...
@@ -104,25 +102,26 @@ Sets the maximum number of decoded images that can be cached in the memory to sp
...
@@ -104,25 +102,26 @@ Sets the maximum number of decoded images that can be cached in the memory to sp
| options | ScreenOnVisibleOptions | No| With keep-alive, the system is prevented from returning to the home screen when the screen is locked, so that the application is visible when the screen is woken up. |
## ScreenOnVisibleOptions
## ScreenOnVisibleOptions
Defines the options of the visible interface on the screen.
Defines the options of the visible interface on the screen.
> - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.bluetooth`](js-apis-bluetooth.md).
> - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.bluetooth`](js-apis-bluetooth.md).
>
>
...
@@ -19,11 +19,10 @@ import bluetooth from '@system.bluetooth';
...
@@ -19,11 +19,10 @@ import bluetooth from '@system.bluetooth';
Scans for Bluetooth Low Energy (BLE) devices nearby. This operation consumes system resources. Call [bluetooth.stopBLEScan](#bluetoothstopblescanobject) to stop the scan after a BLE device is detected and connected.
Scans for Bluetooth Low Energy (BLE) devices nearby. This operation consumes system resources. Call [bluetooth.stopBLEScan](#bluetoothstopblescanobject) to stop the scan after a BLE device is detected and connected.
**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION
> The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>- The APIs provided by this module are deprecated since API version 9. You are advised to use [cryptoFramework-Cipher](js-apis-cryptoFramework.md#Cipher).
## Modules to Import
## Modules to Import
...
@@ -18,9 +18,10 @@ Defines the response to the cipher interface called.
...
@@ -18,9 +18,10 @@ Defines the response to the cipher interface called.
