1# Launching a UIAbility in the Background Through the call Event
2
3
4There may be cases you want to provide in a widget access to features available in your application running in the foreground, for example, the play, pause, and stop buttons in a music application widget. This is where the **call** capability of the [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction) API comes in handy. This capability, when used in a widget, can start the specified UIAbility of the widget provider in the background. It also allows the widget to call the specified method of the application and transfer data so that the application, while in the background, can behave accordingly in response to touching of the buttons on the widget.
5
6> **NOTE**
7>
8> This topic describes development for dynamic widgets. For static widgets, see [FormLink](../reference/apis-arkui/arkui-ts/ts-container-formlink.md).
9
10## Constraints
11
12This action type requires that the widget provider should have the [ohos.permission.KEEP_BACKGROUND_RUNNING](../security/AccessToken/permissions-for-all.md#ohospermissionkeep_background_running) permission.
13
14## How to Develop
15
16Typically, the call event is triggered for touching of buttons. Below is an example.
17
18
19- In this example, two buttons are laid out on the widget page. When one button is clicked, the **postCardAction** API is called to send a call event to the target UIAbility. Note that the **method** parameter in the API indicates the method to call in the target UIAbility. It is mandatory and of the string type.
20
21    ```ts
22    @Entry
23    @Component
24    struct WidgetEventCallCard {
25      @LocalStorageProp('formId') formId: string = '12400633174999288';
26
27      build() {
28        Column() {
29          //...
30          Row() {
31            Column() {
32              Button() {
33              //...
34              }
35              //...
36              .onClick(() => {
37                postCardAction(this, {
38                  action: 'call',
39                  abilityName: 'WidgetEventCallEntryAbility', // Only the UIAbility of the current application is allowed. The ability name must be the same as that defined in module.json5.
40                  params: {
41                    formId: this.formId,
42                    method: 'funA' // Set the name of the method to call in the EntryAbility.
43                  }
44                });
45              })
46
47              Button() {
48              //...
49              }
50              //...
51              .onClick(() => {
52                postCardAction(this, {
53                  action: 'call',
54                  abilityName: 'WidgetEventCallEntryAbility', // Only the UIAbility of the current application is allowed. The ability name must be the same as that defined in module.json5.
55                  params: {
56                    formId: this.formId,
57                    method: 'funB', // Set the name of the method to call in the EntryAbility.
58                    num: 1 // Set other parameters to be passed in.
59                  }
60                });
61              })
62            }
63          }.width('100%').height('80%')
64          .justifyContent(FlexAlign.Center)
65        }
66        .width('100%')
67        .height('100%')
68        .alignItems(HorizontalAlign.Center)
69      }
70    }
71    ```
72
73- The UIAbility receives the call event and obtains the transferred parameters. It then executes the target method specified by the **method** parameter. Other data can be obtained through the [readString](../reference/apis-ipc-kit/js-apis-rpc.md#readstring) method. Listen for the method required by the call event in the **onCreate** callback of the UIAbility.
74
75    ```ts
76    import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
77    import { promptAction } from '@kit.ArkUI';
78    import { BusinessError } from '@kit.BasicServicesKit';
79    import { rpc } from '@kit.IPCKit';
80    import { hilog } from '@kit.PerformanceAnalysisKit';
81
82    const TAG: string = 'WidgetEventCallEntryAbility';
83    const DOMAIN_NUMBER: number = 0xFF00;
84    const CONST_NUMBER_1: number = 1;
85    const CONST_NUMBER_2: number = 2;
86
87    class MyParcelable implements rpc.Parcelable {
88      num: number;
89      str: string;
90
91      constructor(num: number, str: string) {
92        this.num = num;
93        this.str = str;
94      }
95
96      marshalling(messageSequence: rpc.MessageSequence): boolean {
97        messageSequence.writeInt(this.num);
98        messageSequence.writeString(this.str);
99        return true;
100      }
101
102      unmarshalling(messageSequence: rpc.MessageSequence): boolean {
103        this.num = messageSequence.readInt();
104        this.str = messageSequence.readString();
105          return true;
106      }
107    }
108
109    export default class WidgetEventCallEntryAbility extends UIAbility {
110      // If the UIAbility is started for the first time, onCreate is triggered after the call event is received.
111      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
112        try {
113          // Listen for the method required by the call event.
114          this.callee.on('funA', (data: rpc.MessageSequence) => {
115            // Obtain all parameters passed in the call event.
116            hilog.info(DOMAIN_NUMBER, TAG, `FunACall param:  ${JSON.stringify(data.readString())}`);
117            promptAction.showToast({
118              message: 'FunACall param:' + JSON.stringify(data.readString())
119            });
120            return new MyParcelable(CONST_NUMBER_1, 'aaa');
121          });
122          this.callee.on('funB', (data: rpc.MessageSequence) => {
123            // Obtain all parameters passed in the call event.
124            hilog.info(DOMAIN_NUMBER, TAG, `FunBCall param:  ${JSON.stringify(data.readString())}`);
125            promptAction.showToast({
126              message: 'FunBCall param:' + JSON.stringify(data.readString())
127            });
128            return new MyParcelable(CONST_NUMBER_2, 'bbb');
129          });
130        } catch (err) {
131          hilog.error(DOMAIN_NUMBER, TAG, `Failed to register callee on. Cause: ${JSON.stringify(err as BusinessError)}`);
132        }
133      }
134
135      // Deregister the listener when the process exits.
136      onDestroy(): void | Promise<void> {
137        try {
138          this.callee.off('funA');
139          this.callee.off('funB');
140        } catch (err) {
141          hilog.error(DOMAIN_NUMBER, TAG, `Failed to register callee off. Cause: ${JSON.stringify(err as BusinessError)}`);
142        }
143      }
144    }
145    ```
146