ipc_cremote_object.h

Overview

Provides C APIs for creating and destroying a remote object, transferring data, and observing the dead status of a remote object.

File to include: <IPCKit/ipc_cremote_object.h>

Library: libipc_capi.so

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Related module: OHIPCRemoteObject

Summary

Structs

Name	typedef Keyword	Description
OH_IPC_MessageOption	-	Defines an IPC message.
OHIPCDeathRecipient	OHIPCDeathRecipient	Defines an object that receives death notifications.

Enums

Name	typedef Keyword	Description
OH_IPC_RequestMode	OH_IPC_RequestMode	Enumerates the IPC request modes.

Function

Name	typedef Keyword	Description
typedef int (OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel data, OHIPCParcel reply, void userData)	OH_OnRemoteRequestCallback	Called to process the peer request at the stub.
typedef void (OH_OnRemoteDestroyCallback)(void userData)	OH_OnRemoteDestroyCallback	Called when an observed object is destroyed.
OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char descriptor, OH_OnRemoteRequestCallback requestCallback, OH_OnRemoteDestroyCallback destroyCallback, void userData)	-	Creates an OHIPCRemoteStub object.
void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub)	-	Destroys an OHIPCRemoteStub object.
void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy)	-	Destroys an OHIPCRemoteProxy object.
int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy proxy, uint32_t code, const OHIPCParcel data, OHIPCParcel reply, const OH_IPC_MessageOption option)	-	Sends an IPC message.
int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy proxy, char descriptor, int32_t len, OH_IPC_MemAllocator allocator)	-	Obtains the interface descriptor from the stub.
typedef void (OH_OnDeathRecipientCallback)(void userData)	OH_OnDeathRecipientCallback	Defines a callback to be invoked when the remote OHIPCRemoteStub object dies unexpectedly.
typedef void (OH_OnDeathRecipientDestroyCallback)(void userData)	OH_OnDeathRecipientDestroyCallback	Defines a callback to be invoked when the OHIPCDeathRecipient object is destroyed.
OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData)	-	Creates an OHIPCDeathRecipient object.
void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient)	-	Destroys an OHIPCDeathRecipient object.
int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy proxy, OHIPCDeathRecipient recipient)	-	Subscribes to the death of an OHIPCRemoteStub object for an OHIPCRemoteProxy object.
int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy proxy, OHIPCDeathRecipient recipient)	-	Unsubscribes from the death of the OHIPCRemoteStub object for an OHIPCRemoteProxy object.
int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy)	-	Checks whether the OHIPCRemoteStub object corresponding to the OHIPCRemoteProxy object is dead.

Enum Description

OH_IPC_RequestMode

enum OH_IPC_RequestMode

Description

Enumerates the IPC request modes.

Since: 12

Enum Item	Description
OH_IPC_REQUEST_MODE_SYNC = 0	Synchronous request.
OH_IPC_REQUEST_MODE_ASYNC = 1	Asynchronous request.

Function Description

OH_OnRemoteRequestCallback()

typedef int(*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, void *userData)

Description

Called to process the peer request at the stub.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
uint32_t code	Customized communication command word. Value range: [0x01, 0x00ffffff]
const OHIPCParcel *data	Pointer to the requested data object. It cannot be NULL or released in the function.
OHIPCParcel *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.
void *userData	Pointer to the private user data. It can be NULL.

Returns

Type	Description
int	Returns OH_IPC_ErrorCode#OH_IPC_SUCCESS if the operation is successful. Returns a custom error code in the range [1909001, 1909999] or a system error code otherwise. If the custom error code is out of range, OH_IPC_ErrorCode#OH_IPC_INVALID_USER_ERROR_CODE is returned.

OH_OnRemoteDestroyCallback()

typedef void(*OH_OnRemoteDestroyCallback)(void *userData)

Description

Called when an observed object is destroyed.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
void *userData	Pointer to the private user data. It can be NULL.

OH_IPCRemoteStub_Create()

OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequestCallback requestCallback, OH_OnRemoteDestroyCallback destroyCallback, void *userData)

Description

Creates an OHIPCRemoteStub object.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
const char *descriptor	Pointer to the descriptor of the OHIPCRemoteStub object to create. It cannot be NULL.
OH_OnRemoteRequestCallback requestCallback	Callback used to process the data request. It cannot be NULL.
OH_OnRemoteDestroyCallback destroyCallback	Callback to be invoked when the object is destroyed. It can be NULL.
void *userData	Pointer to the private user data. It can be NULL.

Returns

Type	Description
OHIPCRemoteStub*	Returns the pointer to the OHIPCRemoteStub object created if the operation is successful; returns NULL otherwise.

OH_IPCRemoteStub_Destroy()

void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub)

Description

Destroys an OHIPCRemoteStub object.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
OHIPCRemoteStub *stub	Pointer to the OHIPCRemoteStub object to destroy.

OH_IPCRemoteProxy_Destroy()

void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy)

Description

Destroys an OHIPCRemoteProxy object.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
OHIPCRemoteProxy *proxy	Pointer to the OHIPCRemoteProxy object to destroy.

OH_IPCRemoteProxy_SendRequest()

int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, const OH_IPC_MessageOption *option)

Description

Sends an IPC message.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
const OHIPCRemoteProxy *proxy	Pointer to the OHIPCRemoteProxy object. It cannot be NULL.
uint32_t code	Customized IPC command word, in the range [0x01, 0x00ffffff].
const OHIPCParcel *data	Pointer to the requested data object. It cannot be NULL.
OHIPCParcel *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.
const OH_IPC_MessageOption *option	Pointer to the message option. It can be NULL, which indicates a synchronous request.

Returns

Type	Description
int	Returns OH_IPC_ErrorCode#OH_IPC_SUCCESS if the message is sent successfully. Returns OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR if invalid parameters are found. Returns OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT if the remote OHIPCRemoteStub object dies. Returns OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE if the code is out of range. Returns OH_IPC_ErrorCode#OH_IPC_INNER_ERROR or a custom error code in other cases.

Type

Description

int

Returns OH_IPC_ErrorCode#OH_IPC_SUCCESS if the message is sent successfully.
Returns OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR if invalid parameters are found.
Returns OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT if the remote OHIPCRemoteStub object dies.
Returns OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE if the code is out of range.
Returns OH_IPC_ErrorCode#OH_IPC_INNER_ERROR or a custom error code in other cases.

OH_IPCRemoteProxy_GetInterfaceDescriptor()

int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy *proxy, char **descriptor, int32_t *len, OH_IPC_MemAllocator allocator)

Description

Obtains the interface descriptor from the stub.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
OHIPCRemoteProxy *proxy	Pointer to the OHIPCRemoteProxy object. It cannot be NULL.
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.
int32_t *len	Pointer to the length of the data written to the descriptor, including the terminator. It cannot be NULL.
OH_IPC_MemAllocator allocator	Memory allocator specified by the user for allocating memory for identity. It cannot be NULL.

Returns

Type	Description
int	Returns OH_IPC_ErrorCode#OH_IPC_SUCCESS if the message is sent successfully. Returns OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR if the parameters are incorrect. Returns OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT if the remote OHIPCRemoteStub object dies. Returns OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR if the memory allocation fails. Returns OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR or a custom error code if the data in the serialized object fails to be read.

Type

Description

int

Returns OH_IPC_ErrorCode#OH_IPC_SUCCESS if the message is sent successfully.
Returns OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR if the parameters are incorrect.
Returns OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT if the remote OHIPCRemoteStub object dies.
Returns OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR if the memory allocation fails.
Returns OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR or a custom error code if the data in the serialized object fails to be read.

OH_OnDeathRecipientCallback()

typedef void (*OH_OnDeathRecipientCallback)(void *userData)

Description

Defines a callback to be invoked when the remote OHIPCRemoteStub object dies unexpectedly.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
void *userData	Pointer to the private user data. It can be NULL.

OH_OnDeathRecipientDestroyCallback()

typedef void (*OH_OnDeathRecipientDestroyCallback)(void *userData)

Description

Defines a callback to be invoked when the OHIPCDeathRecipient object is destroyed.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
void *userData	Pointer to the private user data. It can be NULL.

OH_IPCDeathRecipient_Create()

OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData)

Description

Creates an OHIPCDeathRecipient object, which triggers a notification when the OHIPCRemoteStub object dies unexpectedly.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
OH_OnDeathRecipientCallback deathRecipientCallback	Callback to be invoked when the OHIPCRemoteStub object is dead. It cannot be NULL.
OH_OnDeathRecipientDestroyCallback destroyCallback	Callback to be invoked when the object is destroyed. It can be NULL.
void *userData	Pointer to the private user data. It can be NULL.

Returns

Type	Description
OHIPCDeathRecipient*	Returns the pointer to the OHIPCDeathRecipient object created if the operation is successful; returns NULL otherwise.

OH_IPCDeathRecipient_Destroy()

void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient)

Description

Destroys an OHIPCDeathRecipient object.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
OHIPCDeathRecipient *recipient	Pointer to the OHIPCDeathRecipient object to destroy.

OH_IPCRemoteProxy_AddDeathRecipient()

int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient)

Description

Subscribes to the death of an OHIPCRemoteStub object for an OHIPCRemoteProxy object.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
OHIPCRemoteProxy *proxy	Pointer to the OHIPCRemoteProxy object that subscribes to the death notification. It cannot be NULL.
OHIPCDeathRecipient *recipient	Pointer to the object that receives the death notification of the OHIPCRemoteStub object. It cannot be NULL.

Returns

Type	Description
int	Returns OH_IPC_ErrorCode#OH_IPC_SUCCESS if the operation is successful. Returns OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR if the parameters are incorrect. Returns OH_IPC_ErrorCode#OH_IPC_INNER_ERROR in other cases.

OH_IPCRemoteProxy_RemoveDeathRecipient()

int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient)

Description

Unsubscribes from the death of the OHIPCRemoteStub object for an OHIPCRemoteProxy object.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
OHIPCRemoteProxy *proxy	Pointer to the OHIPCRemoteProxy object that unsubscribes from the death notification. It cannot be NULL.
OHIPCDeathRecipient *recipient	Pointer to the object that receives the death notification of the OHIPCRemoteStub object. It cannot be NULL.

Returns

Type	Description
int	Returns OH_IPC_ErrorCode#OH_IPC_SUCCESS if the operation is successful. Returns OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR if the parameters are incorrect. Returns OH_IPC_ErrorCode#OH_IPC_INNER_ERROR in other cases.

OH_IPCRemoteProxy_IsRemoteDead()

int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy)

Description

Checks whether the OHIPCRemoteStub object corresponding to the OHIPCRemoteProxy object is dead.

System capability: SystemCapability.Communication.IPC.Core

Since: 12

Parameters

Name	Description
const OHIPCRemoteProxy *proxy	Pointer to the OHIPCRemoteProxy object to check. It cannot be NULL.

Returns

Type	Description
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.