1# ipc_cremote_object.h 2<!--Kit: IPC Kit--> 3<!--Subsystem: Communication--> 4<!--Owner: @xdx19211@luodonghui0157--> 5<!--Designer: @zhaopeng_gitee--> 6<!--Tester: @maxiaorong--> 7<!--Adviser: @zhang_yixin13--> 8 9## 概述 10 11提供远端对象创建、销毁、数据发送、远端对象死亡状态监听等功能C接口。 12 13**库：** libipc_capi.so 14 15**系统能力：** SystemCapability.Communication.IPC.Core 16 17**起始版本：** 12 18 19**相关模块：** [OHIPCRemoteObject](capi-ohipcremoteobject.md) 20 21## 汇总 22 23### 结构体 24 25| 名称 | typedef关键字 | 描述 | 26| ---- | ------------- | ---- | 27| [OH_IPC_MessageOption](capi-ohipcremoteobject-oh-ipc-messageoption.md) | - | IPC消息选项定义。 | 28| [OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md) | OHIPCDeathRecipient | 死亡通知对象。 | 29 30### 枚举 31 32| 名称 | typedef关键字 | 描述 | 33| ---- | ------------- | ---- | 34| [OH_IPC_RequestMode](#oh_ipc_requestmode) | OH_IPC_RequestMode | IPC请求模式定义。 | 35 36### 函数 37 38| 名称 | typedef关键字 | 描述 | 39| ---- | ------------- | ---- | 40| [typedef int (\*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, void *userData)](#oh_onremoterequestcallback) | OH_OnRemoteRequestCallback | Stub端用于处理远端数据请求的回调函数。 | 41| [typedef void (\*OH_OnRemoteDestroyCallback)(void *userData)](#oh_onremotedestroycallback) | OH_OnRemoteDestroyCallback | 用于监听对象销毁的回调函数。 | 42| [OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequestCallback requestCallback, OH_OnRemoteDestroyCallbac destroyCallback, void *userData)](#oh_ipcremotestub_create) | - | 创建OHIPCRemoteStub对象。 | 43| [void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub)](#oh_ipcremotestub_destroy) | - | 销毁OHIPCRemoteStub对象。 | 44| [void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy)](#oh_ipcremoteproxy_destroy) | - | 销毁OHIPCRemoteProxy对象。 | 45| [int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, const OH_IPC_MessageOption *option)](#oh_ipcremoteproxy_sendrequest) | - | IPC消息发送函数。 | 46| [int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy *proxy, char **descriptor, int32_t *len, OH_IPC_MemAllocator allocator)](#oh_ipcremoteproxy_getinterfacedescriptor) | - | 从Stub端获取接口描述符。 | 47| [typedef void (\*OH_OnDeathRecipientCallback)(void *userData)](#oh_ondeathrecipientcallback) | OH_OnDeathRecipientCallback | 远端OHIPCRemoteStub对象死亡通知的回调函数类型。 | 48| [typedef void (\*OH_OnDeathRecipientDestroyCallback)(void *userData)](#oh_ondeathrecipientdestroycallback) | OH_OnDeathRecipientDestroyCallback | OH_OnDeathRecipient对象销毁回调函数类型。 | 49| [OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData)](#oh_ipcdeathrecipient_create) | - | 创建OHIPCDeathRecipient对象。 | 50| [void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient)](#oh_ipcdeathrecipient_destroy) | - | 销毁OHIPCDeathRecipient对象。 | 51| [int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient)](#oh_ipcremoteproxy_adddeathrecipient) | - | 向OHIPCRemoteProxy对象添加死亡监听，用于接收远端OHIPCRemoteStub对象死亡的回调通知。 | 52| [int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient)](#oh_ipcremoteproxy_removedeathrecipient) | - | 移除向OHIPCRemoteProxy对象已经添加的死亡监听。 | 53| [int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy)](#oh_ipcremoteproxy_isremotedead)| - | 判断OHIPCRemoteProxy对象对应的远端OHIPCRemoteStub对象是否死亡。 | 54 55## 枚举类型说明 56 57### OH_IPC_RequestMode 58 59```C 60enum OH_IPC_RequestMode 61``` 62 63**描述：** 64 65IPC请求模式定义。 66 67**起始版本：** 12 68 69| 枚举项 | 描述 | 70| ------ | ---- | 71| OH_IPC_REQUEST_MODE_SYNC = 0 | 同步请求模式。 | 72| OH_IPC_REQUEST_MODE_ASYNC = 1 | 异步请求模式。 | 73 74## 函数说明 75 76### OH_OnRemoteRequestCallback() 77 78```C 79typedef int(*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, void *userData) 80``` 81 82**描述：** 83 84Stub端用于处理远端数据请求的回调函数。 85 86**系统能力：** SystemCapability.Communication.IPC.Core 87 88**起始版本：** 12 89 90**参数:** 91 92| 参数项 | 描述 | 93| -------- | -------- | 94| uint32_t code | code 用户自定义通讯命令字，范围：[0x01, 0x00ffffff]。 | 95| const [OHIPCParcel](capi-ohipcparcel.md) *data | data 请求数据对象指针，不会为空，函数内不允许释放。 | 96| [OHIPCParcel](capi-ohipcparcel.md) *reply | reply 回应数据对象指针，不会为空，函数内不允许释放。如果函数返回错误，该值不允许写入数据。 | 97| void *userData | userData 用户私有数据，可以为空。 | 98 99**返回：** 100 101| 类型 | 说明 | 102| ---- | ---- | 103| int | 成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 否则返回用户自定义错误码或系统错误码，自定义错误码范围：[1909001, 1909999]；<br> 如果用户自定义错误码超出范围，将返回[OH_IPC_ErrorCode#OH_IPC_INVALID_USER_ERROR_CODE](capi-ipc-error-code-h.md#oh_ipc_errorcode)。 | 104 105### OH_OnRemoteDestroyCallback() 106 107```C 108typedef void(*OH_OnRemoteDestroyCallback)(void *userData) 109``` 110 111**描述：** 112 113用于监听对象销毁的回调函数。 114 115**系统能力：** SystemCapability.Communication.IPC.Core 116 117**起始版本：** 12 118 119**参数:** 120 121| 参数项 | 描述 | 122| ----- | ----- | 123| void *userData | userData 用户私有数据，可以为空。 | 124 125### OH_IPCRemoteStub_Create() 126 127```C 128OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequestCallback requestCallback, OH_OnRemoteDestroyCallback destroyCallback, void *userData) 129``` 130 131**描述：** 132 133创建OHIPCRemoteStub对象。 134 135**系统能力：** SystemCapability.Communication.IPC.Core 136 137**起始版本：** 12 138 139**参数:** 140 141| 参数项 | 描述 | 142| ------ | ---- | 143| const char *descriptor | descriptor OHIPCRemoteStub对象描述符，不能为空。 | 144| [OH_OnRemoteRequestCallback](#oh_onremoterequestcallback) requestCallback | requestCallback 数据请求处理函数，不能为空。 | 145| [OH_OnRemoteDestroyCallback](#oh_onremotedestroycallback) destroyCallback | destroyCallback对象销毁回调函数，可以为空。 | 146| void *userData | userData用户私有数据，可以为空。 | 147 148**返回：** 149 150| 类型 | 说明| 151| ---- | ---- | 152| OHIPCRemoteStub* | 成功返回OHIPCRemoteStub对象指针，否则返回NULL。 | 153 154### OH_IPCRemoteStub_Destroy() 155 156```C 157void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub) 158``` 159 160**描述：** 161 162销毁OHIPCRemoteStub对象。 163 164**系统能力：** SystemCapability.Communication.IPC.Core 165 166**起始版本：** 12 167 168**参数:** 169 170| 参数项 | 描述 | 171| ------ | ---- | 172| [OHIPCRemoteStub](capi-ohipcparcel-ohipcremotestub.md) *stub | stub 要销毁的OHIPCRemoteStub对象指针。 | 173 174### OH_IPCRemoteProxy_Destroy() 175 176```C 177void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy) 178``` 179 180**描述：** 181 182销毁OHIPCRemoteProxy对象。 183 184**系统能力：** SystemCapability.Communication.IPC.Core 185 186**起始版本：** 12 187 188**参数:** 189 190| 参数项 | 描述 | 191| ------ | ---- | 192| [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | proxy 要销毁的OHIPCRemoteProxy对象指针。 | 193 194### OH_IPCRemoteProxy_SendRequest() 195 196```C 197int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, const OH_IPC_MessageOption *option) 198``` 199 200**描述：** 201 202IPC消息发送函数。 203 204**系统能力：** SystemCapability.Communication.IPC.Core 205 206**起始版本：** 12 207 208**参数:** 209 210| 参数项 | 描述 | 211| ------ | ---- | 212| const [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | proxy OHIPCRemoteProxy对象指针，不能为空。 | 213| uint32_t code | code 用户定义的IPC命令字，范围：[0x01, 0x00ffffff]。 | 214| const [OHIPCParcel](capi-ohipcparcel.md) *data | data 请求数据对象指针，不能为空。 | 215| [OHIPCParcel](capi-ohipcparcel.md) *reply | reply 回应数据对象指针，同步请求时，不能为空；异步请求时，可以为空。 | 216| const [OH_IPC_MessageOption](capi-ohipcremoteobject-oh-ipc-messageoption.md) *option | option消息选项指针，可以为空，为空时按同步处理。 | 217 218**返回：** 219 220| 类型 | 说明 | 221| ---- | ---- | 222| int | 发送成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 远端OHIPCRemoteStub对象死亡返回[OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> code超出范围返回[OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 其它返回[OH_IPC_ErrorCode#OH_IPC_INNER_ERRORT](capi-ipc-error-code-h.md#oh_ipc_errorcode)或用户自定义错误码。 | 223 224### OH_IPCRemoteProxy_GetInterfaceDescriptor() 225 226```C 227int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy *proxy, char **descriptor, int32_t *len, OH_IPC_MemAllocator allocator) 228``` 229 230**描述：** 231 232从Stub端获取接口描述符。 233 234**系统能力：** SystemCapability.Communication.IPC.Core 235 236**起始版本：** 12 237 238**参数:** 239 240| 参数项 | 描述 | 241| ------ | ---- | 242| [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | proxy OHIPCRemoteProxy对象指针，不能为空。 | 243| char **descriptor | descriptor 用于存储描述符的内存地址，该内存由用户提供的分配器进行内存分配，用户使用完后需要主动释放，不能为空。 接口返回失败时，用户依然需要判断该内存是否为空，并主动释放，否则会造成内存泄漏。 | 244| int32_t *len | len 写入descriptor的数据长度，包含结束符，不能为空。 | 245| [OH_IPC_MemAllocator](capi-ipc-cparcel-h.md#oh_ipc_memallocator) allocator | allocator 用户指定的用来分配descriptor的内存分配器，不能为空。 | 246 247**返回：** 248 249| 类型 | 说明 | 250| ---- | ---- | 251| int | 发送成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 远端OHIPCRemoteStub对象死亡返回[OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 内存分配失败返回[OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 序列化读失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](capi-ipc-error-code-h.md#oh_ipc_errorcode)或用户自定义错误码。 | 252 253### OH_OnDeathRecipientCallback() 254 255```C 256typedef void(*OH_OnDeathRecipientCallback)(void *userData) 257``` 258 259**描述：** 260 261远端OHIPCRemoteStub对象死亡通知的回调函数类型。 262 263**系统能力：** SystemCapability.Communication.IPC.Core 264 265**起始版本：** 12 266 267**参数:** 268 269| 参数项 | 描述 | 270| ------ | ---- | 271| void *userData | userData 用户私有数据指针，可以为空。 | 272 273### OH_OnDeathRecipientDestroyCallback() 274 275```C 276typedef void(*OH_OnDeathRecipientDestroyCallback)(void *userData) 277``` 278 279**描述：** 280 281OHIPCDeathRecipient对象销毁回调函数类型。 282 283**系统能力：** SystemCapability.Communication.IPC.Core 284 285**起始版本：** 12 286 287**参数:** 288 289| 参数项 | 描述 | 290| ------ | ---- | 291| void *userData | userData 用户私有数据指针，可以为空。 | 292 293### OH_IPCDeathRecipient_Create() 294 295```C 296OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData) 297``` 298 299**描述：** 300 301创建远端OHIPCRemoteStub对象死亡通知对象OHIPCDeathRecipient。 302 303**系统能力：** SystemCapability.Communication.IPC.Core 304 305**起始版本：** 12 306 307**参数:** 308 309| 参数项 | 描述 | 310| ------ | ---- | 311| [OH_OnDeathRecipientCallback](#oh_ondeathrecipientcallback) deathRecipientCallback | deathRecipientCallback 远端OHIPCRemoteStub对象死亡通知的回调处理函数，不能为空。 | 312| [OH_OnDeathRecipientDestroyCallback](#oh_ondeathrecipientdestroycallback) destroyCallback | destroyCallback 对象销毁回调处理函数，可以为空。 | 313| void *userData | userData 用户私有数据指针，可以为空。 | 314 315**返回：** 316 317| 类型 | 说明 | 318| ---- | ---- | 319| OHIPCDeathRecipient* | 成功返回OHIPCDeathRecipient对象指针；否则返回NULL。| 320 321### OH_IPCDeathRecipient_Destroy() 322 323```C 324void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient) 325``` 326 327**描述：** 328 329销毁OHIPCDeathRecipient对象。 330 331**系统能力：** SystemCapability.Communication.IPC.Core 332 333**起始版本：** 12 334 335**参数:** 336 337| 参数项 | 描述 | 338| ------ | ---- | 339| [OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md) *recipient | recipient 要销毁的OHIPCDeathRecipient对象指针。 | 340 341### OH_IPCRemoteProxy_AddDeathRecipient() 342 343```C 344int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient) 345``` 346 347**描述：** 348 349向OHIPCRemoteProxy对象添加死亡监听，用于接收远端OHIPCRemoteStub对象死亡的回调通知。 350 351**系统能力：** SystemCapability.Communication.IPC.Core 352 353**起始版本：** 12 354 355**参数:** 356 357| 参数项 | 描述 | 358| ------ | ---- | 359| [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | proxy 需要添加死亡通知的OHIPCRemoteProxy对象指针，不能为空。 | 360| [OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md) *recipient | recipient 用于接收远程对象死亡通知的死亡对象指针，不能为空。 | 361 362**返回：** 363 364| 类型 | 说明 | 365| ---- | ---- | 366| int | 成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 其它返回[OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](capi-ipc-error-code-h.md#oh_ipc_errorcode)。 | 367 368### OH_IPCRemoteProxy_RemoveDeathRecipient() 369 370```C 371int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient) 372``` 373 374**描述：** 375 376移除向OHIPCRemoteProxy对象已经添加的死亡监听。 377 378**系统能力：** SystemCapability.Communication.IPC.Core 379 380**起始版本：** 12 381 382**参数:** 383 384| 参数项 | 描述 | 385| ------ | ---- | 386| [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | proxy 需要移除死亡通知的OHIPCRemoteProxy对象指针，不能为空。 | 387| [OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md) *recipient | recipient用于接收远程对象死亡通知的死亡对象指针，不能为空。 | 388 389**返回：** 390 391| 类型 | 说明 | 392| ---- | ---- | 393| int | 成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](capi-ipc-error-code-h.md#oh_ipc_errorcode)；<br> 其它返回[OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](capi-ipc-error-code-h.md#oh_ipc_errorcode)。 | 394 395### OH_IPCRemoteProxy_IsRemoteDead() 396 397```C 398int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy) 399``` 400 401**描述：** 402 403判断OHIPCRemoteProxy对象对应的远端OHIPCRemoteStub对象是否死亡。 404 405**系统能力：** SystemCapability.Communication.IPC.Core 406 407**起始版本：** 12 408 409**参数:** 410 411| 参数项 | 描述 | 412| ------ | ---- | 413| const [OHIPCRemoteProxy](capi-ohipcparcel-ohipcremoteproxy.md) *proxy | proxy 需要判断远端是否死亡的OHIPCRemoteProxy对象指针，不能为空。 | 414 415**返回：** 416 417| 类型 | 说明 | 418| ---- | ---- | 419| int | 远端OHIPCRemoteStub对象死亡返回1；否则，返回0。参数非法时，说明其远端OHIPCRemoteStub对象不存在，返回1。 | 420