1# ipc_cremote_object.h 2<!--Kit: IPC Kit--> 3<!--Subsystem: Communication--> 4<!--Owner: @xdx19211@luodonghui0157--> 5<!--SE: @zhaopeng_gitee--> 6<!--TSE: @maxiaorong2--> 7 8## Overview 9 10Provides C APIs for creating and destroying a remote object, transferring data, and observing the dead status of a remote object. 11 12**Library**: libipc_capi.so 13 14**System capability**: SystemCapability.Communication.IPC.Core 15 16**Since**: 12 17 18**Related module**: [OHIPCRemoteObject](capi-ohipcremoteobject.md) 19 20## Summary 21 22### Structs 23 24| Name| typedef Keyword| Description| 25| ---- | ------------- | ---- | 26| [OH_IPC_MessageOption](capi-ohipcremoteobject-oh-ipc-messageoption.md) | - | Defines an IPC message.| 27| [OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md) | OHIPCDeathRecipient | Defines an object that receives death notifications.| 28 29### Enums 30 31| Name| typedef Keyword| Description| 32| ---- | ------------- | ---- | 33| [OH_IPC_RequestMode](#oh_ipc_requestmode) | OH_IPC_RequestMode | Enumerates the IPC request modes.| 34 35### Function 36 37| Name| typedef Keyword| Description| 38| ---- | ------------- | ---- | 39| [typedf int (\*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, void *userData)](#oh_onremoterequestcallback) | OH_OnRemoteRequestCallback | Called to process the peer request at the stub.| 40| [typedef void (\*OH_OnRemoteDestroyCallback)(void *userData)](#oh_onremotedestroycallback) | OH_OnRemoteDestroyCallback | Called when an observed object is destroyed.| 41| [OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequestCallback requestCallback, OH_OnRemoteDestroyCallbac destroyCallback, void *userData)](#oh_ipcremotestub_create) | - | Creates an **OHIPCRemoteStub** object.| 42| [void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub)](#oh_ipcremotestub_destroy) | - | Destroys an **OHIPCRemoteStub** object.| 43| [void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy)](#oh_ipcremoteproxy_destroy) | - | Destroys an **OHIPCRemoteProxy** object.| 44| [int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, const OH_IPC_MessageOption *option)](#oh_ipcremoteproxy_sendrequest) | - | Sends an IPC message.| 45| [int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy *proxy, char **descriptor, int32_t *len, OH_IPC_MemAllocator allocator)](#oh_ipcremoteproxy_getinterfacedescriptor) | - | Obtains the interface descriptor from the stub.| 46| [typedof void (\*OH_OnDeathRecipientCallback)(void *userData)](#oh_ondeathrecipientcallback) | OH_OnDeathRecipientCallback | Defines a callback to be invoked when the remote **OHIPCRemoteStub** object dies unexpectedly.| 47| [typedef void (\*OH_OnDeathRecipientDestroyCallback)(void *userData)](#oh_ondeathrecipientdestroycallback) | OH_OnDeathRecipientDestroyCallback | Defines a callback to be invoked when the **OHIPCDeathRecipient** object is destroyed.| 48| [OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData)](#oh_ipcdeathrecipient_create) | - | Creates an **OHIPCDeathRecipient** object.| 49| [void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient)](#oh_ipcdeathrecipient_destroy) | - | Destroys an **OHIPCDeathRecipient** object.| 50| [int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient)](#oh_ipcremoteproxy_adddeathrecipient) | - | Subscribes to the death of an **OHIPCRemoteStub** object for an **OHIPCRemoteProxy** object.| 51| [int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient)](#oh_ipcremoteproxy_removedeathrecipient) | - | Unsubscribes from the death of the **OHIPCRemoteStub** object for an **OHIPCRemoteProxy** object.| 52| [int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy)](#oh_ipcremoteproxy_isremotedead)| - | Checks whether the **OHIPCRemoteStub** object corresponding to the **OHIPCRemoteProxy** object is dead.| 53 54## Enum Description 55 56### OH_IPC_RequestMode 57 58```C 59enum OH_IPC_RequestMode 60``` 61 62**Description** 63 64Enumerates the IPC request modes. 65 66**Since**: 12 67 68| Enum Item| Description| 69| ------ | ---- | 70| OH_IPC_REQUEST_MODE_SYNC = 0 | Synchronous request.| 71| OH_IPC_REQUEST_MODE_ASYNC = 1 | Asynchronous request.| 72 73## Function Description 74 75### OH_OnRemoteRequestCallback() 76 77```C 78typedef int(*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, void *userData) 79``` 80 81**Description** 82 83Called to process the peer request at the stub. 84 85**System capability**: SystemCapability.Communication.IPC.Core 86 87**Since**: 12 88 89**Parameters** 90 91| Name| Description| 92| -------- | -------- | 93| uint32_t code | Customized communication command word.<br>Value range: [0x01, 0x00ffffff]| 94| const [OHIPCParcel](capi-ohipcparcel.md) *data | Pointer to the requested data object. It cannot be NULL or released in the function.| 95| [OHIPCParcel](capi-ohipcparcel.md) *reply | Pointer to the response data object. It cannot be NULL or released in the function. If this function returns an error, data cannot be written to this parameter.| 96| userDavoid *userDatata | Pointer to the private user data. It can be NULL.| 97 98**Returns** 99 100| Type| Description| 101| ---- | ---- | 102| int | Returns [OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md) if the operation is successful;<br> returns a custom error code in the range [1909001, 1909999] or a system error code otherwise.<br> If the custom error code is out of range, [OH_IPC_ErrorCode#OH_IPC_INVALID_USER_ERROR_CODE](capi-ipc-error-code-h.md) is returned.| 103 104### OH_OnRemoteDestroyCallback() 105 106```C 107typedef void(*OH_OnRemoteDestroyCallback)(void *userData) 108``` 109 110**Description** 111 112Called when an observed object is destroyed. 113 114**System capability**: SystemCapability.Communication.IPC.Core 115 116**Since**: 12 117 118**Parameters** 119 120| Name| Description| 121| ----- | ----- | 122| void *userData | Pointer to the private user data. It can be NULL.| 123 124### OH_IPCRemoteStub_Create() 125 126```C 127OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequestCallback requestCallback, OH_OnRemoteDestroyCallback destroyCallback, void *userData) 128``` 129 130**Description** 131 132Creates an **OHIPCRemoteStub** object. 133 134**System capability**: SystemCapability.Communication.IPC.Core 135 136**Since**: 12 137 138**Parameters** 139 140| Name| Description| 141| ------ | ---- | 142| const char *descriptor | Pointer to the descriptor of the **OHIPCRemoteStub** object to create. It cannot be NULL.| 143| [OH_OnRemoteRequestCallback](#oh_onremoterequestcallback) requestCallback | Callback used to process the data request. It cannot be NULL.| 144| [OH_OnRemoteDestroyCallback](#oh_onremotedestroycallback) destroyCallback | Callback to be invoked when the object is destroyed. It can be NULL.| 145| void *userData | Pointer to the private user data. It can be NULL.| 146 147**Returns** 148 149| Type| Description| 150| ---- | ---- | 151| OHIPCRemoteStub* | Returns the pointer to the **OHIPCRemoteStub** object created if the operation is successful; returns NULL otherwise.| 152 153### OH_IPCRemoteStub_Destroy() 154 155```C 156void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub) 157``` 158 159**Description** 160 161Destroys an **OHIPCRemoteStub** object. 162 163**System capability**: SystemCapability.Communication.IPC.Core 164 165**Since**: 12 166 167**Parameters** 168 169| Name| Description| 170| ------ | ---- | 171| [OHIPCRemoteStub](capi-ohipcparcel-ohipcremotestub.md) *stub | Pointer to the **OHIPCRemoteStub** object to destroy.| 172 173### OH_IPCRemoteProxy_Destroy() 174 175```C 176void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy) 177``` 178 179**Description** 180 181Destroys an **OHIPCRemoteProxy** object. 182 183**System capability**: SystemCapability.Communication.IPC.Core 184 185**Since**: 12 186 187**Parameters** 188 189| Name| Description| 190| ------ | ---- | 191| [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | Pointer to the **OHIPCRemoteProxy** object to destroy.| 192 193### OH_IPCRemoteProxy_SendRequest() 194 195```C 196int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, const OH_IPC_MessageOption *option) 197``` 198 199**Description** 200 201Sends an IPC message. 202 203**System capability**: SystemCapability.Communication.IPC.Core 204 205**Since**: 12 206 207**Parameters** 208 209| Name| Description| 210| ------ | ---- | 211| const [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | Pointer to the **OHIPCRemoteProxy** object. It cannot be NULL.| 212| uint32_t code | Customized IPC command word, in the range [0x01, 0x00ffffff].| 213| const [OHIPCParcel](capi-ohipcparcel.md) *data | Pointer to the requested data object. It cannot be NULL.| 214| [OHIPCParcel](capi-ohipcparcel.md) *reply | Pointer to the response data object. It cannot be NULL in the case of a synchronous request, and can be NULL in the case of an asynchronous request.| 215| const [OH_IPC_MessageOption](capi-ohipcremoteobject-oh-ipc-messageoption.md) *option | Pointer to the message option. It can be NULL, which indicates a synchronous request.| 216 217**Returns** 218 219| Type| Description| 220| ---- | ---- | 221| int | Returns [OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md) if the operation is successful;<br> returns [OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](capi-ipc-error-code-h.md) if invalid parameters are found;<br> returns [OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT](capi-ipc-error-code-h.md) if the remote **OHIPCRemoteStub** object is dead;<br> returns [OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE](capi-ipc-error-code-h.md) if the code is out of range;<br> returns [OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](capi-ipc-error-code-h.md) or a custom error code in other cases.| 222 223### OH_IPCRemoteProxy_GetInterfaceDescriptor() 224 225```C 226int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy *proxy, char **descriptor, int32_t *len, OH_IPC_MemAllocator allocator) 227``` 228 229**Description** 230 231Obtains the interface descriptor from the stub. 232 233**System capability**: SystemCapability.Communication.IPC.Core 234 235**Since**: 12 236 237**Parameters** 238 239| Name| Description| 240| ------ | ---- | 241| [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | Pointer to the **OHIPCRemoteProxy** object. It cannot be NULL.| 242| char **descriptor | Pointer to the address of the memory for holding the interface descriptor. The memory is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. If an error code is returned, you still need to check whether the memory is empty and release the memory. Otherwise, memory leaks may occur.| 243| int32_t *len | Pointer to the length of the data written to the descriptor, including the terminator. It cannot be NULL.| 244| [OH_IPC_MemAllocator](capi-ipc-cparcel-h.md#oh_ipc_memallocator) allocator | Memory allocator specified by the user for allocating memory for **identity**. It cannot be NULL.| 245 246**Returns** 247 248| Type| Description| 249| ---- | ---- | 250| int | Returns [OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md) if the operation is successful;<br> returns [OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](capi-ipc-error-code-h.md) if the parameter is incorrect;<br> returns [OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT](capi-ipc-error-code-h.md) if the remote **OHIPCRemoteStub** object is dead;<br> returns [OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR](capi-ipc-error-code-h.md) if memory allocation fails;<br> returns [OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](capi-ipc-error-code-h.md) or a custom error code if the data in the serialized object fails to be read.| 251 252### OH_OnDeathRecipientCallback() 253 254```C 255typedef void(*OH_OnDeathRecipientCallback)(void *userData) 256``` 257 258**Description** 259 260Defines a callback to be invoked when the remote **OHIPCRemoteStub** object dies unexpectedly. 261 262**System capability**: SystemCapability.Communication.IPC.Core 263 264**Since**: 12 265 266**Parameters** 267 268| Name| Description| 269| ------ | ---- | 270| void *userData | Pointer to the private user data. It can be NULL.| 271 272### OH_OnDeathRecipientDestroyCallback() 273 274```C 275typedef void(*OH_OnDeathRecipientDestroyCallback)(void *userData) 276``` 277 278**Description** 279 280Defines a callback to be invoked when the **OHIPCDeathRecipient** object is destroyed. 281 282**System capability**: SystemCapability.Communication.IPC.Core 283 284**Since**: 12 285 286**Parameters** 287 288| Name| Description| 289| ------ | ---- | 290| void *userData | Pointer to the private user data. It can be NULL.| 291 292### OH_IPCDeathRecipient_Create() 293 294```C 295OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData) 296``` 297 298**Description** 299 300Creates an **OHIPCDeathRecipient** object, which triggers a notification when the **OHIPCRemoteStub** object dies unexpectedly. 301 302**System capability**: SystemCapability.Communication.IPC.Core 303 304**Since**: 12 305 306**Parameters** 307 308| Name| Description| 309| ------ | ---- | 310| [OH_OnDeathRecipientCallback](#oh_ondeathrecipientcallback) deathRecipientCallback | Callback to be invoked when the **OHIPCRemoteStub** object is dead. It cannot be NULL.| 311| [OH_OnDeathRecipientDestroyCallback](#oh_ondeathrecipientdestroycallback) destroyCallback | Callback to be invoked when the object is destroyed. It can be NULL.| 312| void *userData | Pointer to the private user data. It can be NULL.| 313 314**Returns** 315 316| Type| Description| 317| ---- | ---- | 318| OHIPCDeathRecipient* | Returns the pointer to the **OHIPCDeathRecipient** object created if the operation is successful; returns NULL otherwise.| 319 320### OH_IPCDeathRecipient_Destroy() 321 322```C 323void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient) 324``` 325 326**Description** 327 328Destroys an **OHIPCDeathRecipient** object. 329 330**System capability**: SystemCapability.Communication.IPC.Core 331 332**Since**: 12 333 334**Parameters** 335 336| Name| Description| 337| ------ | ---- | 338| [OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md) *recipient | Pointer to the **OHIPCDeathRecipient** object to destroy.| 339 340### OH_IPCRemoteProxy_AddDeathRecipient() 341 342```C 343int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient) 344``` 345 346**Description** 347 348Subscribes to the death of an **OHIPCRemoteStub** object for an **OHIPCRemoteProxy** object. 349 350**System capability**: SystemCapability.Communication.IPC.Core 351 352**Since**: 12 353 354**Parameters** 355 356| Name| Description| 357| ------ | ---- | 358| [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | Pointer to the **OHIPCRemoteProxy** object that subscribes to the death notification. It cannot be NULL.| 359| [OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md) *recipient | Pointer to the object that receives the death notification of the **OHIPCRemoteStub** object. It cannot be NULL.| 360 361**Returns** 362 363| Type| Description| 364| ---- | ---- | 365| int | Returns [OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md) if the operation is successful;<br> returns [OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](capi-ipc-error-code-h.md) if the parameter is incorrect;<br> returns [OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](capi-ipc-error-code-h.md) in other cases.| 366 367### OH_IPCRemoteProxy_RemoveDeathRecipient() 368 369```C 370int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient) 371``` 372 373**Description** 374 375Unsubscribes from the death of the **OHIPCRemoteStub** object for an **OHIPCRemoteProxy** object. 376 377**System capability**: SystemCapability.Communication.IPC.Core 378 379**Since**: 12 380 381**Parameters** 382 383| Name| Description| 384| ------ | ---- | 385| [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | Pointer to the **OHIPCRemoteProxy** object that unsubscribes from the death notification. It cannot be NULL.| 386| [OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md) *recipient | Pointer to the object that receives the death notification of the **OHIPCRemoteStub** object. It cannot be NULL.| 387 388**Returns** 389 390| Type| Description| 391| ---- | ---- | 392| int | Returns [OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md) if the operation is successful;<br> returns [OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](capi-ipc-error-code-h.md) if the parameter is incorrect;<br> returns [OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](capi-ipc-error-code-h.md) in other cases.| 393 394### OH_IPCRemoteProxy_IsRemoteDead() 395 396```C 397int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy) 398``` 399 400**Description** 401 402Checks whether the **OHIPCRemoteStub** object corresponding to the **OHIPCRemoteProxy** object is dead. 403 404**System capability**: SystemCapability.Communication.IPC.Core 405 406**Since**: 12 407 408**Parameters** 409 410| Name| Description| 411| ------ | ---- | 412| const [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | Pointer to the **OHIPCRemoteProxy** object to check. It cannot be NULL.| 413 414**Returns** 415 416| Type| Description| 417| ---- | ---- | 418| int | Returns **1** if the **OHIPCRemoteStub** object is dead or invalid parameters are found; returns **0** otherwise. If invalid parameters are found, the **OHIPCRemoteStub** object does not exist.| 419