1# Subscribing to State Changes of a Remote Object
2
3You can subscribe to the state changes of a remote stub object in IPC/RPC. When the remote stub object dies, a death notification will be sent to your local proxy object. Such subscription and unsubscription are controlled by APIs. To be specific, you need to implement the **DeathRecipient** interface and the **onRemoteDied** API to clear resources. This callback is invoked when the process hosting the remote stub object dies, or the device hosting the remote stub object leaves the network. It is worth noting that these APIs should be called in the following order: The proxy object must first subscribe to death notifications of the stub object. If the stub object is in the normal state, the proxy object can cancel the subscription as required. If the process of the stub object exits or the device hosting the stub object goes offline, subsequent operations customized by the proxy object will be automatically triggered.
4
5## When to Use
6
7This subscription mechanism is applicable when the local proxy object needs to detect death of the process hosting the remote stub object or network detach of the device hosting the remote stub object. When the proxy detects death of the remote stub object, the proxy can clear local resources. Currently, IPC supports death notification for anonymous objects, but RPC does not. That is, you can only subscribe to death notifications of services that have been registered with SAMgr.
8
9<!--Del-->
10## Development Using Native APIs
11
12| Name                                                             |  Description                    |
13| ------------------------------------------------------------------- | ------------------------- |
14| bool AddDeathRecipient(const sptr\<DeathRecipient> &recipient);     | Adds a recipient for death notifications of a remote stub object.    |
15| bool RemoveDeathRecipient(const sptr\<DeathRecipient> &recipient);  | Removes the recipient for death notifications of a remote stub object.|
16| void OnRemoteDied(const wptr\<IRemoteObject> &object);              | Called when the remote stub object dies.|
17
18### Example
19
20```C++
21#include "iremote_broker.h"
22#include "iremote_stub.h"
23
24// Define message codes.
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 is mandatory, and the input parameter is std::u16string.
35    DECLARE_INTERFACE_DESCRIPTOR(to_utf16(DESCRIPTOR));
36    virtual int TestPingAbility(const std::u16string &dummy) = 0; // Define functions.
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_; // For use of the iface_cast macro at a later time
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()); // Construct a death notification recipient.
79bool result = object->AddDeathRecipient(deathRecipient); // Add a recipient for death notifications.
80result = object->RemoveDeathRecipient(deathRecipient); // Remove the recipient for death notifications.
81```
82<!--DelEnd-->
83
84## Development Using ArkTS APIs
85
86> **NOTE**
87>
88> - The sample code in this topic implements communication between system applications across processes.
89>
90> - Currently, third-party applications cannot implement ServiceExtensionAbility. The UIAbility components of a third-party application can connect to the ServiceExtensionAbility provided by the system via **Context**.
91>
92> - The development applies only to the scenario, in which the client is a third-party application and the server is a system application.
93
94| Name                                                      | Return Value Type| Description                                                    |
95| ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ |
96| [registerDeathRecipient](../reference/apis-ipc-kit/js-apis-rpc.md#registerdeathrecipient9-1) | void       | Adds a recipient for death notifications of the remote object, including death notifications of the remote proxy.|
97| [unregisterDeathRecipient](../reference/apis-ipc-kit/js-apis-rpc.md#unregisterdeathrecipient9-1) | void       | Removes the recipient for death notifications of the remote object.                        |
98| [onRemoteDied](../reference/apis-ipc-kit/js-apis-rpc.md#onremotedied) | void       | Called to perform subsequent operations when a death notification of the remote object is received.|
99
100### Example
101
102```ts
103// If the FA model is used, import featureAbility from @kit.AbilityKit.
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// Use this method to connect to the ability in the FA model.
127// FA.connectAbility(want, connect);
128
129// Save the connection ID, which will be used for the subsequent service disconnection.
130let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext; // UIAbilityContext
131// Save the connection ID, which will be used for the subsequent service disconnection.
132let connectionId = context.connectServiceExtensionAbility(want, connect);
133```
134
135The **proxy** object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. After that, [unregisterDeathRecipient](../reference/apis-ipc-kit/js-apis-rpc.md#unregisterdeathrecipient9-1) of the **proxy** object can be called to unregister the callback for receiving the death notification of the remote object.
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## Reverse Death Notification (Anonymous Stub)
154
155Forward dead notification is a mechanism that allows the proxy to detect death notifications of the stub. To achieve reverse dead notification, we can leverage the forward dead notification mechanism to allow the stub to detect death notifications of the proxy.
156
157Suppose there are two processes: A (the process hosting the original stub) and B (the process hosting the original proxy). After obtaining the proxy object of process A, process B creates an anonymous stub object (that is, a stub object not registered with SAMgr), which can be called a callback stub. Then, process B calls **SendRequest** to send the callback stub to the original stub of process A. As a result, process A obtains the callback proxy of process B. When process B dies or the device hosting process B detaches from the network, the callback stub dies. The callback proxy detects the death of the callback stub and sends a death notification to the original stub. In this way, reverse death notification is implemented.
158
159**NOTE**
160
161> - Reverse death notification can only be used for cross-process communication within a device.
162> - When an anonymous stub object is not pointed to by any proxy, the kernel automatically reclaims the object.
163
164### Example
165
166```c++
167// Proxy
168int TestAbilityProxy::TestAnonymousStub()
169{
170    MessageOption option;
171    MessageParcel dataParcel, replyParcel;
172    dataParcel.UpdateDataVersion(Remote());
173    dataParcel.WriteRemoteObject(new TestAbilityStub());
174    int error = Remote()->SendRequest(TRANS_ID_REVERSED_MONITOR,dataParcel, replyParcel, option);
175    int result = (error == ERR_NONE) ? replyParcel.ReadInt32() : -1;
176    return result;
177}
178
179// Stub
180
181int TestAbilityStub::OnRemoteRequest(uint32_t code, MessageParcel &data, MessageParcel &reply, MessageOption &option)
182{
183    switch (code) {
184        case TRANS_ID_REVERSED_MONITOR: {
185            sptr<IRemoteObject> obj = data.ReadRemoteObject();
186            if (obj == nullptr) {
187                reply.WriteInt32(ERR_NULL_OBJECT);
188                return ERR_NULL_OBJECT;
189            }
190            bool result = obj->AddDeathRecipient(new TestDeathRecipient());
191            result ? reply.WriteInt32(ERR_NONE) : reply.WriteInt32(-1);
192            break;
193        }
194        default:
195            break;
196    }
197    return ERR_NONE;
198}
199```
200