1# 远端状态订阅开发实例
2
3IPC/RPC提供对远端Stub对象状态的订阅机制，在远端Stub对象消亡时，可触发消亡通知告诉本地Proxy对象。这种状态通知订阅需要调用特定接口完成，当不再需要订阅时也需要调用特定接口取消。使用这种订阅机制的用户，需要实现消亡通知接口DeathRecipient并实现onRemoteDied方法清理资源。该方法会在远端Stub对象所在进程消亡或所在设备离开组网时被回调。值得注意的是，调用这些接口有一定的顺序。首先，需要Proxy订阅Stub消亡通知，若在订阅期间Stub状态正常，则在不再需要时取消订阅；若在订阅期间Stub所在进程退出或者所在设备退出组网，则会自动触发Proxy自定义的后续操作。
4
5## 使用场景
6
7这种订阅机制适用于本地Proxy对象需要感知远端Stub对象所在进程消亡，或所在设备离开组网的场景。当Proxy感知到Stub端消亡后，可适当清理本地资源。此外，RPC目前不提供匿名Stub对象的消亡通知，即只有向SAMgr注册过的服务才能被订阅消亡通知，IPC则支持匿名对象的消亡通知。
8
9<!--Del-->
10## Native侧接口
11
12| 接口名                                                              |  描述                     |
13| ------------------------------------------------------------------- | ------------------------- |
14| bool AddDeathRecipient(const sptr\<DeathRecipient> &recipient);     | 订阅远端Stub对象状态。     |
15| bool RemoveDeathRecipient(const sptr\<DeathRecipient> &recipient);  | 取消订阅远端Stub对象状态。 |
16| void OnRemoteDied(const wptr\<IRemoteObject> &object);              | 当远端Stub对象死亡时回调。 |
17
18### 参考代码
19
20```C++
21#include "iremote_broker.h"
22#include "iremote_stub.h"
23
24//定义消息码
25enum {
26    TRANS_ID_PING_ABILITY = 5,
27    TRANS_ID_REVERSED_MONITOR
28};
29
30const std::string DESCRIPTOR = "test.ITestAbility";
31
32class ITestService : public IRemoteBroker {
33public:
34    // DECLARE_INTERFACE_DESCRIPTOR是必需的，入参需使用std::u16string；
35    DECLARE_INTERFACE_DESCRIPTOR(to_utf16(DESCRIPTOR));
36    virtual int TestPingAbility(const std::u16string &dummy) = 0; // 定义业务函数
37};
38
39class TestServiceProxy : public IRemoteProxy<ITestAbility> {
40public:
41    explicit TestAbilityProxy(const sptr<IRemoteObject> &impl);
42    virtual int TestPingAbility(const std::u16string &dummy) override;
43    int TestAnonymousStub();
44private:
45    static inline BrokerDelegator<TestAbilityProxy> delegator_; // 方便后续使用iface_cast宏
46};
47
48TestServiceProxy::TestServiceProxy(const sptr<IRemoteObject> &impl)
49    : IRemoteProxy<ITestAbility>(impl)
50{
51}
52
53int TestServiceProxy::TestPingAbility(const std::u16string &dummy){
54    MessageOption option;
55    MessageParcel dataParcel, replyParcel;
56    dataParcel.WriteString16(dummy);
57    int error = PeerHolder::Remote()->SendRequest(TRANS_ID_PING_ABILITY, dataParcel, replyParcel, option);
58    int result = (error == ERR_NONE) ? replyParcel.ReadInt32() : -1;
59    return result;
60}
61```
62
63```C++
64#include "iremote_object.h"
65
66class TestDeathRecipient : public IRemoteObject::DeathRecipient {
67public:
68    virtual void OnRemoteDied(const wptr<IRemoteObject>& remoteObject);
69}
70
71void TestDeathRecipient::OnRemoteDied(const wptr<IRemoteObject>& remoteObject)
72{
73}
74```
75
76```c++
77sptr<IPCObjectProxy> object = new IPCObjectProxy(1, to_utf16(DESCRIPTOR));
78sptr<IRemoteObject::DeathRecipient> deathRecipient (new TestDeathRecipient()); // 构造一个消亡通知对象
79bool result = object->AddDeathRecipient(deathRecipient); // 注册消亡通知
80result = object->RemoveDeathRecipient(deathRecipient); // 移除消亡通知
81```
82<!--DelEnd-->
83
84## ArkTS侧接口
85
86> **说明：**
87>
88> - 此文档中的示例代码描述的是系统应用跨进程通信。
89>
90> - 当前不支持三方应用实现ServiceExtensionAbility，三方应用的UIAbility组件可以通过Context连接系统提供的ServiceExtensionAbility。
91>
92> - 当前使用场景： 仅限客户端是三方应用，服务端是系统应用。
93
94| 接口名                                                       | 返回值类型 | 功能描述                                                     |
95| ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ |
96| [registerDeathRecipient](../reference/apis-ipc-kit/js-apis-rpc.md#registerdeathrecipient9-1) | void       | 注册用于接收远程对象消亡通知的回调，增加 proxy 对象上的消亡通知。 |
97| [unregisterDeathRecipient](../reference/apis-ipc-kit/js-apis-rpc.md#unregisterdeathrecipient9-1) | void       | 注销用于接收远程对象消亡通知的回调。                         |
98| [onRemoteDied](../reference/apis-ipc-kit/js-apis-rpc.md#onremotedied) | void       | 在成功添加死亡通知订阅后，当远端对象死亡时，将自动调用本方法。 |
99
100### 参考代码
101
102```ts
103// FA模型需要从@kit.AbilityKit导入featureAbility
104// import { featureAbility } from '@kit.AbilityKit';
105import { Want, common } from '@kit.AbilityKit';
106import { rpc } from '@kit.IPCKit';
107import { hilog } from '@kit.PerformanceAnalysisKit';
108
109let proxy: rpc.IRemoteObject | undefined;
110let connect: common.ConnectOptions = {
111  onConnect: (elementName, remoteProxy) => {
112    hilog.info(0x0000, 'testTag', 'RpcClient: js onConnect called.');
113    proxy = remoteProxy;
114  },
115  onDisconnect: (elementName) => {
116    hilog.info(0x0000, 'testTag', 'RpcClient: onDisconnect');
117  },
118  onFailed: () => {
119    hilog.info(0x0000, 'testTag', 'RpcClient: onFailed');
120  }
121};
122let want: Want = {
123  bundleName: "com.ohos.server",
124  abilityName: "com.ohos.server.EntryAbility",
125};
126// FA模型通过此方法连接服务
127// FA.connectAbility(want, connect);
128
129// 建立连接后返回的Id需要保存下来，在解绑服务时需要作为参数传入
130let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext; // UIAbilityContext
131// 建立连接后返回的Id需要保存下来，在解绑服务时需要作为参数传入
132let connectionId = context.connectServiceExtensionAbility(want, connect);
133```
134
135上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的[unregisterDeathRecipient](../reference/apis-ipc-kit/js-apis-rpc.md#unregisterdeathrecipient9-1)接口方法注销死亡回调
136
137```ts
138import { rpc } from '@kit.IPCKit';
139import { hilog } from '@kit.PerformanceAnalysisKit';
140
141class MyDeathRecipient implements rpc.DeathRecipient{
142  onRemoteDied() {
143    hilog.info(0x0000, 'testTag', 'server died');
144  }
145}
146let deathRecipient = new MyDeathRecipient();
147if (proxy != undefined) {
148  proxy.registerDeathRecipient(deathRecipient, 0);
149  proxy.unregisterDeathRecipient(deathRecipient, 0);
150}
151```
152
153## Stub感知Proxy消亡（匿名Stub的使用）
154
155正向的消亡通知是Proxy感知Stub的状态，若想达到反向的死消亡通知，即Stub感知Proxy的状态，可以巧妙的利用正向消亡通知。如两个进程A（原Stub所在进程）和B（原Proxy所在进程），进程B在获取到进程A的Proxy对象后，在B进程新建一个匿名Stub对象（匿名指未向SAMgr注册），可称之为回调Stub，再通过SendRequest接口将回调Stub传给进程A的原Stub。这样一来，进程A便获取到了进程B的回调Proxy。当进程B消亡或B所在设备离开组网时，回调Stub会消亡，回调Proxy会感知，进而通知给原Stub，便实现了反向消亡通知。
156
157注意：
158
159> 反向死亡通知仅限设备内跨进程通信使用，不可用于跨设备。
160
161> 当匿名Stub对象没有被任何一个Proxy指向的时候，内核会自动回收。
162
163### 参考代码
164
165```c++
166// Proxy
167int TestAbilityProxy::TestAnonymousStub()
168{
169    MessageOption option;
170    MessageParcel dataParcel, replyParcel;
171    dataParcel.UpdateDataVersion(Remote());
172    dataParcel.WriteRemoteObject(new TestAbilityStub());
173    int error = Remote()->SendRequest(TRANS_ID_REVERSED_MONITOR,dataParcel, replyParcel, option);
174    int result = (error == ERR_NONE) ? replyParcel.ReadInt32() : -1;
175    return result;
176}
177
178// Stub
179
180int TestAbilityStub::OnRemoteRequest(uint32_t code, MessageParcel &data, MessageParcel &reply, MessageOption &option)
181{
182    switch (code) {
183        case TRANS_ID_REVERSED_MONITOR: {
184            sptr<IRemoteObject> obj = data.ReadRemoteObject();
185            if (obj == nullptr) {
186                reply.WriteInt32(ERR_NULL_OBJECT);
187                return ERR_NULL_OBJECT;
188            }
189            bool result = obj->AddDeathRecipient(new TestDeathRecipient());
190            result ? reply.WriteInt32(ERR_NONE) : reply.WriteInt32(-1);
191            break;
192        }
193        default:
194            break;
195    }
196    return ERR_NONE;
197}
198```
199
200