diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/Readme-CN.md b/zh-cn/application-dev/reference/apis-ipc-kit/Readme-CN.md index eb72ae847777c07d7884921796ddaf5490acc1ef..0b2521ff70a3fbc4022119ee49b3b9bcc4c167ce 100644 --- a/zh-cn/application-dev/reference/apis-ipc-kit/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis-ipc-kit/Readme-CN.md @@ -2,5 +2,21 @@ - ArkTS API - [@ohos.rpc (RPC通信)](js-apis-rpc.md) +- C API + - 模块 + - [OHIPCParcel](_o_h_i_p_c_parcel.md) + - [OHIPCRemoteObject](_o_h_i_p_c_remote_object.md) + - [OHIPCSkeleton](_o_h_i_p_c_skeleton.md) + - [OHIPCErrorCode](_o_h_i_p_c_error_code.md) + - [IPCKit](_i_p_c_kit.md) + - 头文件和结构体 + - 头文件 + - [ipc_cparcel.h](ipc__cparcel_8h.md) + - [ipc_cremote_object.h](ipc__cremote__object_8h.md) + - [ipc_cskeleton.h](ipc__cskeleton_8h.md) + - [ipc_error_code.h](ipc__error__code_8h.md) + - [ipc_kit.h](ipc__kit_8h.md) + - 结构体 + - [OH_IPC_MessageOption](_o_h___i_p_c___message_option.md) - 错误码 - [RPC错误码](errorcode-rpc.md) diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/_i_p_c_kit.md b/zh-cn/application-dev/reference/apis-ipc-kit/_i_p_c_kit.md new file mode 100644 index 0000000000000000000000000000000000000000..494a6b22257c2e2fff113ddd698ef28ab3328498 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/_i_p_c_kit.md @@ -0,0 +1,20 @@ +# IPCKit + + +## 概述 + +IPC头文件包含入口，方便开发者引用。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + + +## 汇总 + + +### 文件 + +| 名称 | 描述 | +| -------- | -------- | +| [ipc_kit.h](ipc__kit_8h.md) | IPC头文件包含入口，方便开发者引用。 | diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/_o_h___i_p_c___message_option.md b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h___i_p_c___message_option.md new file mode 100644 index 0000000000000000000000000000000000000000..237545be19b9993ced68e8efc0464baf2e0a6df7 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h___i_p_c___message_option.md @@ -0,0 +1,58 @@ +# OH_IPC_MessageOption + + +## 概述 + +IPC消息选项定义。 + +**起始版本：** 12 + +**相关模块：**[OHIPCRemoteObject](_o_h_i_p_c_remote_object.md) + + +## 汇总 + + +### 成员变量 + +| 名称 | 描述 | +| -------- | -------- | +| [OH_IPC_RequestMode](_o_h_i_p_c_remote_object.md#oh_ipc_requestmode)[mode](#mode) | 消息请求模式。 | +| uint32_t [timeout](#timeout) | RPC预留参数，该参数对IPC无效。 | +| void \* [reserved](#reserved) | 保留参数，必须为空。 | + + +## 结构体成员变量说明 + + +### mode + +``` +OH_IPC_RequestMode OH_IPC_MessageOption::mode +``` + +**描述** + +消息请求模式。 + + +### reserved + +``` +void* OH_IPC_MessageOption::reserved +``` + +**描述** + +保留参数，必须为空。 + + +### timeout + +``` +uint32_t OH_IPC_MessageOption::timeout +``` + +**描述** + +RPC预留参数，该参数对IPC无效。 diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_error_code.md b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_error_code.md new file mode 100644 index 0000000000000000000000000000000000000000..60ad7bc98a6c60d7bb1827ed8724bec8ca702357 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_error_code.md @@ -0,0 +1,59 @@ +# OHIPCErrorCode + + +## 概述 + +提供IPC错误码定义。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + + +## 汇总 + + +### 文件 + +| 名称 | 描述 | +| -------- | -------- | +| [ipc_error_code.h](ipc__error__code_8h.md) | 提供IPC错误码定义。 | + + +### 枚举 + +| 名称 | 描述 | +| -------- | -------- | +| OH_IPC_ErrorCode {
OH_IPC_SUCCESS = 0,
OH_IPC_ERROR_CODE_BASE = 1901000,
OH_IPC_CHECK_PARAM_ERROR = OH_IPC_ERROR_CODE_BASE,
OH_IPC_PARCEL_WRITE_ERROR = OH_IPC_ERROR_CODE_BASE + 1,
OH_IPC_PARCEL_READ_ERROR = OH_IPC_ERROR_CODE_BASE + 2,
OH_IPC_MEM_ALLOCATOR_ERROR = OH_IPC_ERROR_CODE_BASE + 3,
OH_IPC_CODE_OUT_OF_RANGE = OH_IPC_ERROR_CODE_BASE + 4,
OH_IPC_DEAD_REMOTE_OBJECT = OH_IPC_ERROR_CODE_BASE + 5,
OH_IPC_INVALID_USER_ERROR_CODE = OH_IPC_ERROR_CODE_BASE + 6,
OH_IPC_INNER_ERROR = OH_IPC_ERROR_CODE_BASE + 7,
OH_IPC_ERROR_CODE_MAX = OH_IPC_ERROR_CODE_BASE + 1000,
OH_IPC_USER_ERROR_CODE_MIN = 1909000,
OH_IPC_USER_ERROR_CODE_MAX = 1909999
} | IPC错误码定义。 | + + +## 枚举类型说明 + + +### OH_IPC_ErrorCode + +``` +enum OH_IPC_ErrorCode +``` + +**描述** + +IPC错误码定义。 + +**起始版本：** 12 + +| 枚举值 | 描述 | +| -------- | -------- | +| OH_IPC_SUCCESS | 执行成功。 | +| OH_IPC_ERROR_CODE_BASE | 错误码区间起始值。 | +| OH_IPC_CHECK_PARAM_ERROR | 参数错误。 | +| OH_IPC_PARCEL_WRITE_ERROR | 序列化对象写入数据失败。 | +| OH_IPC_PARCEL_READ_ERROR | 序列化对象读取数据失败。 | +| OH_IPC_MEM_ALLOCATOR_ERROR | 内存分配失败。 | +| OH_IPC_CODE_OUT_OF_RANGE | 命令字超出定义范围[0x01,0x00ffffff]。 | +| OH_IPC_DEAD_REMOTE_OBJECT | 远端对象死亡。 | +| OH_IPC_INVALID_USER_ERROR_CODE | 用户自定义错误码超出范围[1900001, 1999999]。 | +| OH_IPC_INNER_ERROR | IPC内部错误。 | +| OH_IPC_ERROR_CODE_MAX | 错误码区间最大值。 | +| OH_IPC_USER_ERROR_CODE_MIN | 用户自定义错误码最小值。 | +| OH_IPC_USER_ERROR_CODE_MAX | 用户自定义错误码最大值。 | diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_parcel.md b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_parcel.md new file mode 100644 index 0000000000000000000000000000000000000000..a77d7a2a94bad5c962a063f0415d972ef3eefa4b --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_parcel.md @@ -0,0 +1,1053 @@ +# OHIPCParcel + + +## 概述 + +提供IPC序列化/反序列化C接口。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + + +## 汇总 + + +### 文件 + +| 名称 | 描述 | +| -------- | -------- | +| [ipc_cparcel.h](ipc__cparcel_8h.md) | 提供IPC序列化/反序列化C接口。 | + + +### 类型定义 + +| 名称 | 描述 | +| -------- | -------- | +| typedef void \*(\* [OH_IPC_MemAllocator](#oh_ipc_memallocator)) (int32_t len) | 内存分配函数类型。 | + + +### 函数 + +| 名称 | 描述 | +| -------- | -------- | +| OHIPCParcel \* [OH_IPCParcel_Create](#oh_ipcparcel_create) (void) | 创建OHIPCParcel对象，对象可序列化大小不能超过204800字节。 | +| void [OH_IPCParcel_Destroy](#oh_ipcparcel_destroy) (OHIPCParcel \*parcel) | 销毁OHIPCParcel对象. | +| int [OH_IPCParcel_GetDataSize](#oh_ipcparcel_getdatasize) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象包含的数据的大小。 | +| int [OH_IPCParcel_GetWritableBytes](#oh_ipcparcel_getwritablebytes) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象可以写入的字节数。 | +| int [OH_IPCParcel_GetReadableBytes](#oh_ipcparcel_getreadablebytes) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象还可以读取的字节数。 | +| int [OH_IPCParcel_GetReadPosition](#oh_ipcparcel_getreadposition) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象当前读取位置。 | +| int [OH_IPCParcel_GetWritePosition](#oh_ipcparcel_getwriteposition) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象当前写入位置。 | +| int [OH_IPCParcel_RewindReadPosition](#oh_ipcparcel_rewindreadposition) (OHIPCParcel \*parcel, uint32_t newReadPos) | 重置OHIPCParcel对象读取位置。 | +| int [OH_IPCParcel_RewindWritePosition](#oh_ipcparcel_rewindwriteposition) (OHIPCParcel \*parcel, uint32_t newWritePos) | 重置OHIPCParcel对象写入位置。 | +| int [OH_IPCParcel_WriteInt8](#oh_ipcparcel_writeint8) (OHIPCParcel \*parcel, int8_t value) | 向OHIPCParcel对象写入int8_t值。 | +| int [OH_IPCParcel_ReadInt8](#oh_ipcparcel_readint8) (const OHIPCParcel \*parcel, int8_t \*value) | 从OHIPCParcel对象读取int8_t值。 | +| int [OH_IPCParcel_WriteInt16](#oh_ipcparcel_writeint16) (OHIPCParcel \*parcel, int16_t value) | 向OHIPCParcel对象写入int16_t值。 | +| int [OH_IPCParcel_ReadInt16](#oh_ipcparcel_readint16) (const OHIPCParcel \*parcel, int16_t \*value) | 从OHIPCParcel对象读取int16_t值。 | +| int [OH_IPCParcel_WriteInt32](#oh_ipcparcel_writeint32) (OHIPCParcel \*parcel, int32_t value) | 向OHIPCParcel对象写入int32_t值。 | +| int [OH_IPCParcel_ReadInt32](#oh_ipcparcel_readint32) (const OHIPCParcel \*parcel, int32_t \*value) | 从OHIPCParcel对象读取int32_t值。 | +| int [OH_IPCParcel_WriteInt64](#oh_ipcparcel_writeint64) (OHIPCParcel \*parcel, int64_t value) | 向OHIPCParcel对象写入int64_t值。 | +| int [OH_IPCParcel_ReadInt64](#oh_ipcparcel_readint64) (const OHIPCParcel \*parcel, int64_t \*value) | 从OHIPCParcel对象读取int64_t值。 | +| int [OH_IPCParcel_WriteFloat](#oh_ipcparcel_writefloat) (OHIPCParcel \*parcel, float value) | 向OHIPCParcel对象写入float值。 | +| int [OH_IPCParcel_ReadFloat](#oh_ipcparcel_readfloat) (const OHIPCParcel \*parcel, float \*value) | 从OHIPCParcel对象读取float值。 | +| int [OH_IPCParcel_WriteDouble](#oh_ipcparcel_writedouble) (OHIPCParcel \*parcel, double value) | 向OHIPCParcel对象写入double值。 | +| int [OH_IPCParcel_ReadDouble](#oh_ipcparcel_readdouble) (const OHIPCParcel \*parcel, double \*value) | 从OHIPCParcel对象读取double值。 | +| int [OH_IPCParcel_WriteString](#oh_ipcparcel_writestring) (OHIPCParcel \*parcel, const char \*str) | 向OHIPCParcel对象写入字符串，包含字符串结束符。 | +| const char \* [OH_IPCParcel_ReadString](#oh_ipcparcel_readstring) (const OHIPCParcel \*parcel) | 从OHIPCParcel对象读取字符串，用户可通过strlen获取字符串长度。 | +| int [OH_IPCParcel_WriteBuffer](#oh_ipcparcel_writebuffer) (OHIPCParcel \*parcel, const uint8_t \*buffer, int32_t len) | 向OHIPCParcel对象写入指定长度的内存信息。 | +| const uint8_t \* [OH_IPCParcel_ReadBuffer](#oh_ipcparcel_readbuffer) (const OHIPCParcel \*parcel, int32_t len) | 从OHIPCParcel对象读取指定长度内存信息。 | +| int [OH_IPCParcel_WriteRemoteStub](#oh_ipcparcel_writeremotestub) (OHIPCParcel \*parcel, const OHIPCRemoteStub \*stub) | 向OHIPCParcel对象写入OHIPCRemoteStub对象。 | +| OHIPCRemoteStub \* [OH_IPCParcel_ReadRemoteStub](#oh_ipcparcel_readremotestub) (const OHIPCParcel \*parcel) | 从OHIPCParcel对象读取OHIPCRemoteStub对象。 | +| int [OH_IPCParcel_WriteRemoteProxy](#oh_ipcparcel_writeremoteproxy) (OHIPCParcel \*parcel, const OHIPCRemoteProxy \*proxy) | 向OHIPCParcel对象写入OHIPCRemoteProxy对象。 | +| OHIPCRemoteProxy \* [OH_IPCParcel_ReadRemoteProxy](#oh_ipcparcel_readremoteproxy) (const OHIPCParcel \*parcel) | 从OHIPCParcel对象读取OHIPCRemoteProxy对象。 | +| int [OH_IPCParcel_WriteFileDescriptor](#oh_ipcparcel_writefiledescriptor) (OHIPCParcel \*parcel, int32_t fd) | 向OHIPCParcel对象写入文件描述符。 | +| int [OH_IPCParcel_ReadFileDescriptor](#oh_ipcparcel_readfiledescriptor) (const OHIPCParcel \*parcel, int32_t \*fd) | 从OHIPCParcel对象读取文件描述符。 | +| int [OH_IPCParcel_Append](#oh_ipcparcel_append) (OHIPCParcel \*parcel, const OHIPCParcel \*data) | OHIPCParcel对象数据拼接。 | +| int [OH_IPCParcel_WriteInterfaceToken](#oh_ipcparcel_writeinterfacetoken) (OHIPCParcel \*parcel, const char \*token) | 向OHIPCParcel对象写入接口描述符，用于接口身份校验。 | +| int [OH_IPCParcel_ReadInterfaceToken](#oh_ipcparcel_readinterfacetoken) (const OHIPCParcel \*parcel, char \*\*token, int32_t \*len, [OH_IPC_MemAllocator](#oh_ipc_memallocator) allocator) | 从OHIPCParcel对象读取接口描述符信息，用于接口身份校验。 | + + +## 类型定义说明 + + +### OH_IPC_MemAllocator + +``` +typedef void*(* OH_IPC_MemAllocator) (int32_t len) +``` + +**描述** + +内存分配函数类型。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| len | 分配内存长度。 | + +**返回：** + +成功返回分配的内存地址；失败返回NULL。 + + +## 函数说明 + + +### OH_IPCParcel_Append() + +``` +int OH_IPCParcel_Append (OHIPCParcel * parcel, const OHIPCParcel * data ) +``` + +**描述** + +OHIPCParcel对象数据拼接。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | 拼接目标OHIPCParcel对象的指针，不能为空。 | +| data | 源OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +拼接失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_Create() + +``` +OHIPCParcel* OH_IPCParcel_Create (void ) +``` + +**描述** + +创建OHIPCParcel对象，对象可序列化大小不能超过204800字节。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**返回：** + +成功返回OHIPCParcel对象指针；失败返回NULL。 + + +### OH_IPCParcel_Destroy() + +``` +void OH_IPCParcel_Destroy (OHIPCParcel * parcel) +``` + +**描述** + +销毁OHIPCParcel对象. + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | 需要销毁OHIPCParcel对象的指针。 | + + +### OH_IPCParcel_GetDataSize() + +``` +int OH_IPCParcel_GetDataSize (const OHIPCParcel * parcel) +``` + +**描述** + +获取OHIPCParcel对象包含的数据的大小。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +返回数据大小，参数不合法时返回-1。 + + +### OH_IPCParcel_GetReadableBytes() + +``` +int OH_IPCParcel_GetReadableBytes (const OHIPCParcel * parcel) +``` + +**描述** + +获取OHIPCParcel对象还可以读取的字节数。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +返回可读字节数大小，参数不合法时返回-1。 + + +### OH_IPCParcel_GetReadPosition() + +``` +int OH_IPCParcel_GetReadPosition (const OHIPCParcel * parcel) +``` + +**描述** + +获取OHIPCParcel对象当前读取位置。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +返回当前读位置，参数不合法时返回-1 + + +### OH_IPCParcel_GetWritableBytes() + +``` +int OH_IPCParcel_GetWritableBytes (const OHIPCParcel * parcel) +``` + +**描述** + +获取OHIPCParcel对象可以写入的字节数。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +返回可写字节数大小，参数不合法时返回-1。 + + +### OH_IPCParcel_GetWritePosition() + +``` +int OH_IPCParcel_GetWritePosition (const OHIPCParcel * parcel) +``` + +**描述** + +获取OHIPCParcel对象当前写入位置。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +返回当前写入位置，参数不合法时返回-1。 + + +### OH_IPCParcel_ReadBuffer() + +``` +const uint8_t* OH_IPCParcel_ReadBuffer (const OHIPCParcel * parcel, int32_t len ) +``` + +**描述** + +从OHIPCParcel对象读取指定长度内存信息。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| len | 读取内存的长度。 | + +**返回：** + +成功返回读取到的内存地址；参数不合法或len超过parcel可读长度时返回NULL。 + + +### OH_IPCParcel_ReadDouble() + +``` +int OH_IPCParcel_ReadDouble (const OHIPCParcel * parcel, double * value ) +``` + +**描述** + +从OHIPCParcel对象读取double值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 存储读取数据的指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +读取失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_ReadFileDescriptor() + +``` +int OH_IPCParcel_ReadFileDescriptor (const OHIPCParcel * parcel, int32_t * fd ) +``` + +**描述** + +从OHIPCParcel对象读取文件描述符。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| fd | 存储读取文件描述符的指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +读取失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_ReadFloat() + +``` +int OH_IPCParcel_ReadFloat (const OHIPCParcel * parcel, float * value ) +``` + +**描述** + +从OHIPCParcel对象读取float值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 存储读取数据的指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +读取失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_ReadInt16() + +``` +int OH_IPCParcel_ReadInt16 (const OHIPCParcel * parcel, int16_t * value ) +``` + +**描述** + +从OHIPCParcel对象读取int16_t值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 存储读取数据的指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +读取失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_ReadInt32() + +``` +int OH_IPCParcel_ReadInt32 (const OHIPCParcel * parcel, int32_t * value ) +``` + +**描述** + +从OHIPCParcel对象读取int32_t值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 存储读取数据的指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +读取失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_ReadInt64() + +``` +int OH_IPCParcel_ReadInt64 (const OHIPCParcel * parcel, int64_t * value ) +``` + +**描述** + +从OHIPCParcel对象读取int64_t值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 存储读取数据的指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +读取失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_ReadInt8() + +``` +int OH_IPCParcel_ReadInt8 (const OHIPCParcel * parcel, int8_t * value ) +``` + +**描述** + +从OHIPCParcel对象读取int8_t值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 存储读取数据的指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +读取失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_ReadInterfaceToken() + +``` +int OH_IPCParcel_ReadInterfaceToken (const OHIPCParcel * parcel, char ** token, int32_t * len, OH_IPC_MemAllocator allocator ) +``` + +**描述** + +从OHIPCParcel对象读取接口描述符信息，用于接口身份校验。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| token | 用于存储接口描述符信息的内存地址，该内存由用户提供的分配器进行内存分配，用户使用完后需要主动释放，不能为空。 接口返回失败时，用户依然需要判断该内存是否为空，并主动释放，否则会造成内存泄漏。 | +| len | 存储读取接口描述符的长度，包含结束符，不能为空。 | +| allocator | 用户指定的用来分配token的内存分配器，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +读取失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_ReadRemoteProxy() + +``` +OHIPCRemoteProxy* OH_IPCParcel_ReadRemoteProxy (const OHIPCParcel * parcel) +``` + +**描述** + +从OHIPCParcel对象读取OHIPCRemoteProxy对象。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +成功返回OHIPCRemoteProxy对象指针；失败返回NULL。 + + +### OH_IPCParcel_ReadRemoteStub() + +``` +OHIPCRemoteStub* OH_IPCParcel_ReadRemoteStub (const OHIPCParcel * parcel) +``` + +**描述** + +从OHIPCParcel对象读取OHIPCRemoteStub对象。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +成功返回OHIPCRemoteStub对象指针；失败返回NULL。 + + +### OH_IPCParcel_ReadString() + +``` +const char* OH_IPCParcel_ReadString (const OHIPCParcel * parcel) +``` + +**描述** + +从OHIPCParcel对象读取字符串，用户可通过strlen获取字符串长度。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | + +**返回：** + +成功返回读取字符串地址；参数不合法或读取失败时返回NULL。 + + +### OH_IPCParcel_RewindReadPosition() + +``` +int OH_IPCParcel_RewindReadPosition (OHIPCParcel * parcel, uint32_t newReadPos ) +``` + +**描述** + +重置OHIPCParcel对象读取位置。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| newReadPos | 新的读取位置，范围:[0, 当前数据大小]。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_RewindWritePosition() + +``` +int OH_IPCParcel_RewindWritePosition (OHIPCParcel * parcel, uint32_t newWritePos ) +``` + +**描述** + +重置OHIPCParcel对象写入位置。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| newWritePos | 新的写入位置，范围:[0, 当前数据大小]。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteBuffer() + +``` +int OH_IPCParcel_WriteBuffer (OHIPCParcel * parcel, const uint8_t * buffer, int32_t len ) +``` + +**描述** + +向OHIPCParcel对象写入指定长度的内存信息。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| buffer | 写入内存信息地址。 | +| len | 写入信息长度。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteDouble() + +``` +int OH_IPCParcel_WriteDouble (OHIPCParcel * parcel, double value ) +``` + +**描述** + +向OHIPCParcel对象写入double值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 要写入的值。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteFileDescriptor() + +``` +int OH_IPCParcel_WriteFileDescriptor (OHIPCParcel * parcel, int32_t fd ) +``` + +**描述** + +向OHIPCParcel对象写入文件描述符。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| fd | 要写入的文件描述符。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteFloat() + +``` +int OH_IPCParcel_WriteFloat (OHIPCParcel * parcel, float value ) +``` + +**描述** + +向OHIPCParcel对象写入float值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 要写入的值。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteInt16() + +``` +int OH_IPCParcel_WriteInt16 (OHIPCParcel * parcel, int16_t value ) +``` + +**描述** + +向OHIPCParcel对象写入int16_t值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 要写入的值。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteInt32() + +``` +int OH_IPCParcel_WriteInt32 (OHIPCParcel * parcel, int32_t value ) +``` + +**描述** + +向OHIPCParcel对象写入int32_t值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 要写入的值。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteInt64() + +``` +int OH_IPCParcel_WriteInt64 (OHIPCParcel * parcel, int64_t value ) +``` + +**描述** + +向OHIPCParcel对象写入int64_t值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 要写入的值。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteInt8() + +``` +int OH_IPCParcel_WriteInt8 (OHIPCParcel * parcel, int8_t value ) +``` + +**描述** + +向OHIPCParcel对象写入int8_t值。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| value | 要写入的值。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteInterfaceToken() + +``` +int OH_IPCParcel_WriteInterfaceToken (OHIPCParcel * parcel, const char * token ) +``` + +**描述** + +向OHIPCParcel对象写入接口描述符，用于接口身份校验。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| token | 需要写入的接口描述符信息，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteRemoteProxy() + +``` +int OH_IPCParcel_WriteRemoteProxy (OHIPCParcel * parcel, const OHIPCRemoteProxy * proxy ) +``` + +**描述** + +向OHIPCParcel对象写入OHIPCRemoteProxy对象。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| proxy | 需要写入的OHIPCRemoteProxy对象指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteRemoteStub() + +``` +int OH_IPCParcel_WriteRemoteStub (OHIPCParcel * parcel, const OHIPCRemoteStub * stub ) +``` + +**描述** + +向OHIPCParcel对象写入OHIPCRemoteStub对象。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| stub | 需要写入的OHIPCRemoteStub对象指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCParcel_WriteString() + +``` +int OH_IPCParcel_WriteString (OHIPCParcel * parcel, const char * str ) +``` + +**描述** + +向OHIPCParcel对象写入字符串，包含字符串结束符。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| parcel | OHIPCParcel对象的指针，不能为空。 | +| str | 写入字符串，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +写入失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md)。 diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_remote_object.md b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_remote_object.md new file mode 100644 index 0000000000000000000000000000000000000000..a31c8ec77dc49c2ca6c8e687c1ac2f9fb7d50c24 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_remote_object.md @@ -0,0 +1,458 @@ +# OHIPCRemoteObject + + +## 概述 + +提供远端对象创建、销毁、数据发送、远端对象死亡状态监听等功能C接口。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + + +## 汇总 + + +### 文件 + +| 名称 | 描述 | +| -------- | -------- | +| [ipc_cremote_object.h](ipc__cremote__object_8h.md) | 提供远端对象创建、销毁、数据发送、远端对象死亡状态监听等功能C接口。 | + + +### 结构体 + +| 名称 | 描述 | +| -------- | -------- | +| struct  [OH_IPC_MessageOption](_o_h___i_p_c___message_option.md) | IPC消息选项定义。 | + + +### 类型定义 + +| 名称 | 描述 | +| -------- | -------- | +| typedef int(\* [OH_OnRemoteRequestCallback](#oh_onremoterequestcallback)) (uint32_t code, const OHIPCParcel \*data, OHIPCParcel \*reply, void \*userData) | Stub端用于处理远端数据请求的回调函数。 | +| typedef void(\* [OH_OnRemoteDestroyCallback](#oh_onremotedestroycallback)) (void \*userData) | Stub端用于监听对象销毁的回调函数。 | +| typedef void(\* [OH_OnDeathRecipientCallback](#oh_ondeathrecipientcallback)) (void \*userData) | 远端OHIPCRemoteStub对象死亡通知的回调函数类型。 | +| typedef void(\* [OH_OnDeathRecipientDestroyCallback](#oh_ondeathrecipientdestroycallback)) (void \*userData) | OHIPCDeathRecipient对象销毁回调函数类型。 | + + +### 枚举 + +| 名称 | 描述 | +| -------- | -------- | +| [OH_IPC_RequestMode](#oh_ipc_requestmode) { OH_IPC_REQUEST_MODE_SYNC = 0, OH_IPC_REQUEST_MODE_ASYNC = 1 } | IPC请求模式定义 | + + +### 函数 + +| 名称 | 描述 | +| -------- | -------- | +| OHIPCRemoteStub \* [OH_IPCRemoteStub_Create](#oh_ipcremotestub_create) (const char \*descriptor, [OH_OnRemoteRequestCallback](#oh_onremoterequestcallback) requestCallback, [OH_OnRemoteDestroyCallback](#oh_onremotedestroycallback) destroyCallback, void \*userData) | 创建OHIPCRemoteStub对象。 | +| void [OH_IPCRemoteStub_Destroy](#oh_ipcremotestub_destroy) (OHIPCRemoteStub \*stub) | 销毁OHIPCRemoteStub对象。 | +| void [OH_IPCRemoteProxy_Destroy](#oh_ipcremoteproxy_destroy) (OHIPCRemoteProxy \*proxy) | 销毁OHIPCRemoteProxy对象。 | +| int [OH_IPCRemoteProxy_SendRequest](#oh_ipcremoteproxy_sendrequest) (const OHIPCRemoteProxy \*proxy, uint32_t code, const OHIPCParcel \*data, OHIPCParcel \*reply, const [OH_IPC_MessageOption](_o_h___i_p_c___message_option.md) \*option) | IPC消息发送函数。 | +| int [OH_IPCRemoteProxy_GetInterfaceDescriptor](#oh_ipcremoteproxy_getinterfacedescriptor) (OHIPCRemoteProxy \*proxy, char \*\*descriptor, int32_t \*len, [OH_IPC_MemAllocator](_o_h_i_p_c_parcel.md#oh_ipc_memallocator) allocator) | 从Stub端获取接口描述符。 | +| OHIPCDeathRecipient \* [OH_IPCDeathRecipient_Create](#oh_ipcdeathrecipient_create) ([OH_OnDeathRecipientCallback](#oh_ondeathrecipientcallback) deathRecipientCallback, [OH_OnDeathRecipientDestroyCallback](#oh_ondeathrecipientdestroycallback) destroyCallback, void \*userData) | 创建远端OHIPCRemoteStub对象死亡通知对象OHIPCDeathRecipient。 | +| void [OH_IPCDeathRecipient_Destroy](#oh_ipcdeathrecipient_destroy) (OHIPCDeathRecipient \*recipient) | 销毁OHIPCDeathRecipient对象。 | +| int [OH_IPCRemoteProxy_AddDeathRecipient](#oh_ipcremoteproxy_adddeathrecipient) (OHIPCRemoteProxy \*proxy, OHIPCDeathRecipient \*recipient) | 向OHIPCRemoteProxy对象添加死亡监听，用于接收远端OHIPCRemoteStub对象死亡的回调通知。 | +| int [OH_IPCRemoteProxy_RemoveDeathRecipient](#oh_ipcremoteproxy_removedeathrecipient) (OHIPCRemoteProxy \*proxy, OHIPCDeathRecipient \*recipient) | 移除向OHIPCRemoteProxy对象已经添加的死亡监听。 | +| int [OH_IPCRemoteProxy_IsRemoteDead](#oh_ipcremoteproxy_isremotedead) (const OHIPCRemoteProxy \*proxy) | 判断OHIPCRemoteProxy对象对应的远端OHIPCRemoteStub对象是否死亡。 | + + +## 类型定义说明 + + +### OH_OnDeathRecipientCallback + +``` +typedef void(* OH_OnDeathRecipientCallback) (void *userData) +``` + +**描述** + +远端OHIPCRemoteStub对象死亡通知的回调函数类型。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| userData | 用户私有数据指针，可以为空。 | + + +### OH_OnDeathRecipientDestroyCallback + +``` +typedef void(* OH_OnDeathRecipientDestroyCallback) (void *userData) +``` + +**描述** + +OHIPCDeathRecipient对象销毁回调函数类型。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| userData | 用户私有数据指针，可以为空。 | + + +### OH_OnRemoteDestroyCallback + +``` +typedef void(* OH_OnRemoteDestroyCallback) (void *userData) +``` + +**描述** + +Stub端用于监听对象销毁的回调函数。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| userData | 用户私有数据，可以为空。 | + + +### OH_OnRemoteRequestCallback + +``` +typedef int(* OH_OnRemoteRequestCallback) (uint32_t code, const OHIPCParcel *data, OHIPCParcel *reply, void *userData) +``` + +**描述** + +Stub端用于处理远端数据请求的回调函数。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| code | 用户自定义通讯命令字，范围:[0x01, 0x00ffffff]。 | +| data | 请求数据对象指针，不会为空，函数内不允许释放。 | +| reply | 回应数据对象指针，不会为空，函数内不允许释放。如果函数返回错误，该值不允许写入数据。 | +| userData | 用户私有数据，可以为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +否则返回用户自定义错误码或系统错误码，自定义错误码范围:[1909001, 1909999]； + +如果用户自定义错误码超出范围，将返回[OH_IPC_ErrorCode#OH_IPC_INVALID_USER_ERROR_CODE](_o_h_i_p_c_error_code.md)。 + + +## 枚举类型说明 + + +### OH_IPC_RequestMode + +``` +enum OH_IPC_RequestMode +``` + +**描述** + +IPC请求模式定义 + +**起始版本：** 12 + +| 枚举值 | 描述 | +| -------- | -------- | +| OH_IPC_REQUEST_MODE_SYNC | 同步请求模式。 | +| OH_IPC_REQUEST_MODE_ASYNC | 异步请求模式。 | + + +## 函数说明 + + +### OH_IPCDeathRecipient_Create() + +``` +OHIPCDeathRecipient* OH_IPCDeathRecipient_Create (OH_OnDeathRecipientCallback deathRecipientCallback, OH_OnDeathRecipientDestroyCallback destroyCallback, void * userData ) +``` + +**描述** + +创建远端OHIPCRemoteStub对象死亡通知对象OHIPCDeathRecipient。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| deathRecipientCallback | 远端OHIPCRemoteStub对象死亡通知的回调处理函数，不能为空。 | +| destroyCallback | 对象销毁回调处理函数，可以为空。 | +| userData | 用户私有数据指针，可以为空。 | + +**返回：** + +成功返回OHIPCDeathRecipient对象指针;否则返回NULL。 + + +### OH_IPCDeathRecipient_Destroy() + +``` +void OH_IPCDeathRecipient_Destroy (OHIPCDeathRecipient * recipient) +``` + +**描述** + +销毁OHIPCDeathRecipient对象。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| recipient | 要销毁的OHIPCDeathRecipient对象指针。 | + + +### OH_IPCRemoteProxy_AddDeathRecipient() + +``` +int OH_IPCRemoteProxy_AddDeathRecipient (OHIPCRemoteProxy * proxy, OHIPCDeathRecipient * recipient ) +``` + +**描述** + +向OHIPCRemoteProxy对象添加死亡监听，用于接收远端OHIPCRemoteStub对象死亡的回调通知。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| proxy | 需要添加死亡通知的OHIPCRemoteProxy对象指针，不能为空。 | +| recipient | 用于接收远程对象死亡通知的死亡对象指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +其它[OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCRemoteProxy_Destroy() + +``` +void OH_IPCRemoteProxy_Destroy (OHIPCRemoteProxy * proxy) +``` + +**描述** + +销毁OHIPCRemoteProxy对象。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| proxy | 要销毁的OHIPCRemoteProxy对象指针。 | + + +### OH_IPCRemoteProxy_GetInterfaceDescriptor() + +``` +int OH_IPCRemoteProxy_GetInterfaceDescriptor (OHIPCRemoteProxy * proxy, char ** descriptor, int32_t * len, OH_IPC_MemAllocator allocator ) +``` + +**描述** + +从Stub端获取接口描述符。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| proxy | OHIPCRemoteProxy对象指针，不能为空。 | +| descriptor | 用于存储描述符的内存地址，该内存由用户提供的分配器进行内存分配，用户使用完后需要主动释放，不能为空。 接口返回失败时，用户依然需要判断该内存是否为空，并主动释放，否则会造成内存泄漏。 | +| len | 写入descriptor的数据长度，包含结束符，不能为空。 | +| allocator | 用户指定的用来分配descriptor的内存分配器，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +远端OHIPCRemoteStub对象死亡返回[OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT](_o_h_i_p_c_error_code.md)； + +内存分配失败返回[OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR](_o_h_i_p_c_error_code.md)； + +序列化读失败返回[OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCRemoteProxy_IsRemoteDead() + +``` +int OH_IPCRemoteProxy_IsRemoteDead (const OHIPCRemoteProxy * proxy) +``` + +**描述** + +判断OHIPCRemoteProxy对象对应的远端OHIPCRemoteStub对象是否死亡。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| proxy | 需要判断远端是否死亡的OHIPCRemoteProxy对象指针，不能为空。 | + +**返回：** + +远端OHIPCRemoteStub对象死亡返回1; 否则，返回0。参数非法时，说明其远端OHIPCRemoteStub对象不存在，返回1。 + + +### OH_IPCRemoteProxy_RemoveDeathRecipient() + +``` +int OH_IPCRemoteProxy_RemoveDeathRecipient (OHIPCRemoteProxy * proxy, OHIPCDeathRecipient * recipient ) +``` + +**描述** + +移除向OHIPCRemoteProxy对象已经添加的死亡监听。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| proxy | 需要移除死亡通知的OHIPCRemoteProxy对象指针，不能为空。 | +| recipient | 用于接收远程对象死亡通知的死亡对象指针，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +其它[OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCRemoteProxy_SendRequest() + +``` +int OH_IPCRemoteProxy_SendRequest (const OHIPCRemoteProxy * proxy, uint32_t code, const OHIPCParcel * data, OHIPCParcel * reply, const OH_IPC_MessageOption * option ) +``` + +**描述** + +IPC消息发送函数。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| proxy | OHIPCRemoteProxy对象指针，不能为空。 | +| code | 用户定义的IPC命令字，范围:[0x01,0x00ffffff]。 | +| data | 请求数据对象指针，不能为空。 | +| reply | 回应数据对象指针，同步请求时，不能为空；异步请求时，可以为空。 | +| option | 消息选项指针，可以为空，为空时按同步处理。 | + +**返回：** + +发送成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数不合法时返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +远端OHIPCRemoteStub对象死亡返回[OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT](_o_h_i_p_c_error_code.md)； + +code超出范围返回[OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE](_o_h_i_p_c_error_code.md)； + +其它返回[OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](_o_h_i_p_c_error_code.md)或用户自定义错误码。 + + +### OH_IPCRemoteStub_Create() + +``` +OHIPCRemoteStub* OH_IPCRemoteStub_Create (const char * descriptor, OH_OnRemoteRequestCallback requestCallback, OH_OnRemoteDestroyCallback destroyCallback, void * userData ) +``` + +**描述** + +创建OHIPCRemoteStub对象。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| descriptor | OHIPCRemoteStub对象描述符，不能为空。 | +| requestCallback | 数据请求处理函数，不能为空。 | +| destroyCallback | 对象销毁回调函数，可以为空。 | +| userData | 用户私有数据，可以为空。 | + +**返回：** + +成功返回OHIPCRemoteStub对象指针，否则返回NULL。 + + +### OH_IPCRemoteStub_Destroy() + +``` +void OH_IPCRemoteStub_Destroy (OHIPCRemoteStub * stub) +``` + +**描述** + +销毁OHIPCRemoteStub对象。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| stub | 要销毁的OHIPCRemoteStub对象指针。 | diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_skeleton.md b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_skeleton.md new file mode 100644 index 0000000000000000000000000000000000000000..33d5991fbe4e773d1d166632569442be88c0eb0b --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/_o_h_i_p_c_skeleton.md @@ -0,0 +1,295 @@ +# OHIPCSkeleton + + +## 概述 + +提供IPC框架tokenId、凭据、PID/UID、线程池配置等功能C接口。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + + +## 汇总 + + +### 文件 + +| 名称 | 描述 | +| -------- | -------- | +| [ipc_cskeleton.h](ipc__cskeleton_8h.md) | 提供IPC框架tokenId、凭据、PID/UID、线程池配置等功能C接口。 | + + +### 函数 + +| 名称 | 描述 | +| -------- | -------- | +| void [OH_IPCSkeleton_JoinWorkThread](#oh_ipcskeleton_joinworkthread) (void) | 当前线程加入IPC工作线程池。 | +| void [OH_IPCSkeleton_StopWorkThread](#oh_ipcskeleton_stopworkthread) (void) | 当前线程退出IPC工作线程池。 | +| uint64_t [OH_IPCSkeleton_GetCallingTokenId](#oh_ipcskeleton_getcallingtokenid) (void) | 获取调用方TokenId.该接口需要在IPC上下文中调用，否则返回自身TokenId。 | +| uint64_t [OH_IPCSkeleton_GetFirstTokenId](#oh_ipcskeleton_getfirsttokenid) (void) | 获取首调者TokenId。 | +| uint64_t [OH_IPCSkeleton_GetSelfTokenId](#oh_ipcskeleton_getselftokenid) (void) | 获取自身TokenId。 | +| uint64_t [OH_IPCSkeleton_GetCallingPid](#oh_ipcskeleton_getcallingpid) (void) | 获取调用方进程ID.该接口需要在IPC上下文中调用，否则返当前进程ID。 | +| uint64_t [OH_IPCSkeleton_GetCallingUid](#oh_ipcskeleton_getcallinguid) (void) | 获取调用方用户ID.该接口需要在IPC上下文中调用，否则返当前用户ID。 | +| int [OH_IPCSkeleton_IsLocalCalling](#oh_ipcskeleton_islocalcalling) (void) | 判断是否正在进行本地调用。 | +| int [OH_IPCSkeleton_SetMaxWorkThreadNum](#oh_ipcskeleton_setmaxworkthreadnum) (const int maxThreadNum) | 设置最大工作线程数。 | +| int [OH_IPCSkeleton_ResetCallingIdentity](#oh_ipcskeleton_resetcallingidentity) (char \*\*identity, int32_t \*len, [OH_IPC_MemAllocator](_o_h_i_p_c_parcel.md#oh_ipc_memallocator) allocator) | 重置调用方身份凭证为自身进程的身份凭证（包括tokenid、UID和PID信息），并返回调用方的凭证信息。 该信息主要用于OH_IPCSkeleton_SetCallingIdentity接口调用。 | +| int [OH_IPCSkeleton_SetCallingIdentity](#oh_ipcskeleton_setcallingidentity) (const char \*identity) | 恢复调用方凭证信息至IPC上下文中。 | +| int [OH_IPCSkeleton_IsHandlingTransaction](#oh_ipcskeleton_ishandlingtransaction) (void) | 是否正在处理IPC请求。 | + + +## 函数说明 + + +### OH_IPCSkeleton_GetCallingPid() + +``` +uint64_t OH_IPCSkeleton_GetCallingPid (void ) +``` + +**描述** + +获取调用方进程ID.该接口需要在IPC上下文中调用，否则返当前进程ID。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**返回：** + +返回调用方进程ID。 + + +### OH_IPCSkeleton_GetCallingTokenId() + +``` +uint64_t OH_IPCSkeleton_GetCallingTokenId (void ) +``` + +**描述** + +获取调用方TokenId.该接口需要在IPC上下文中调用，否则返回自身TokenId。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**返回：** + +返回调用方TokenId。 + + +### OH_IPCSkeleton_GetCallingUid() + +``` +uint64_t OH_IPCSkeleton_GetCallingUid (void ) +``` + +**描述** + +获取调用方用户ID.该接口需要在IPC上下文中调用，否则返当前用户ID。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**返回：** + +返回调用方用户ID。 + + +### OH_IPCSkeleton_GetFirstTokenId() + +``` +uint64_t OH_IPCSkeleton_GetFirstTokenId (void ) +``` + +**描述** + +获取首调者TokenId。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**返回：** + +返回首调者TokenId。 + + +### OH_IPCSkeleton_GetSelfTokenId() + +``` +uint64_t OH_IPCSkeleton_GetSelfTokenId (void ) +``` + +**描述** + +获取自身TokenId。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**返回：** + +返回自身TokenId。 + + +### OH_IPCSkeleton_IsHandlingTransaction() + +``` +int OH_IPCSkeleton_IsHandlingTransaction (void ) +``` + +**描述** + +是否正在处理IPC请求。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**返回：** + +正在处理IPC请求，返回1；否则，返回0。 + + +### OH_IPCSkeleton_IsLocalCalling() + +``` +int OH_IPCSkeleton_IsLocalCalling (void ) +``` + +**描述** + +判断是否正在进行本地调用。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**返回：** + +正在进行本地调用，返回1；否则，返回0。 + + +### OH_IPCSkeleton_JoinWorkThread() + +``` +void OH_IPCSkeleton_JoinWorkThread (void ) +``` + +**描述** + +当前线程加入IPC工作线程池。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + + +### OH_IPCSkeleton_ResetCallingIdentity() + +``` +int OH_IPCSkeleton_ResetCallingIdentity (char ** identity, int32_t * len, OH_IPC_MemAllocator allocator ) +``` + +**描述** + +重置调用方身份凭证为自身进程的身份凭证（包括tokenid、UID和PID信息），并返回调用方的凭证信息。 该信息主要用于OH_IPCSkeleton_SetCallingIdentity接口调用。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| identity | 用于存储调凭证的内存地址，该内存由用户提供的分配器进行内存分配，用户使用完后需要主动释放，不能为空。 | +| len | 写入identity的数据长度，不能为空。 | +| allocator | 用户指定的用来分配identity的内存分配器，不能为空。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +内存分配失败返回[OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR](_o_h_i_p_c_error_code.md)； + +其它情况返回[OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCSkeleton_SetCallingIdentity() + +``` +int OH_IPCSkeleton_SetCallingIdentity (const char * identity) +``` + +**描述** + +恢复调用方凭证信息至IPC上下文中。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| identity | 调用方凭证，不能为空。来源于OH_IPCSkeleton_ResetCallingIdentity的返回值。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +其它情况返回[OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCSkeleton_SetMaxWorkThreadNum() + +``` +int OH_IPCSkeleton_SetMaxWorkThreadNum (const int maxThreadNum) +``` + +**描述** + +设置最大工作线程数。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| maxThreadNum | 最大工作线程数，默认16，范围[1, 32]。 | + +**返回：** + +成功返回[OH_IPC_ErrorCode#OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md)； + +参数错误返回[OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md)； + +其它情况返回[OH_IPC_ErrorCode#OH_IPC_INNER_ERROR](_o_h_i_p_c_error_code.md)。 + + +### OH_IPCSkeleton_StopWorkThread() + +``` +void OH_IPCSkeleton_StopWorkThread (void ) +``` + +**描述** + +当前线程退出IPC工作线程池。 + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cparcel_8h.md b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cparcel_8h.md new file mode 100644 index 0000000000000000000000000000000000000000..6d1506069fc71f955294ba9fdcd62647e0188099 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cparcel_8h.md @@ -0,0 +1,64 @@ +# ipc_cparcel.h + + +## 概述 + +提供IPC序列化/反序列化C接口。 + +**库：** libipc_capi.so + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**相关模块：**[OHIPCParcel](_o_h_i_p_c_parcel.md) + + +## 汇总 + + +### 类型定义 + +| 名称 | 描述 | +| -------- | -------- | +| typedef void \*(\* [OH_IPC_MemAllocator](_o_h_i_p_c_parcel.md#oh_ipc_memallocator)) (int32_t len) | 内存分配函数类型。 | + + +### 函数 + +| 名称 | 描述 | +| -------- | -------- | +| OHIPCParcel \* [OH_IPCParcel_Create](_o_h_i_p_c_parcel.md#oh_ipcparcel_create) (void) | 创建OHIPCParcel对象，对象可序列化大小不能超过204800字节。 | +| void [OH_IPCParcel_Destroy](_o_h_i_p_c_parcel.md#oh_ipcparcel_destroy) (OHIPCParcel \*parcel) | 销毁OHIPCParcel对象. | +| int [OH_IPCParcel_GetDataSize](_o_h_i_p_c_parcel.md#oh_ipcparcel_getdatasize) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象包含的数据的大小。 | +| int [OH_IPCParcel_GetWritableBytes](_o_h_i_p_c_parcel.md#oh_ipcparcel_getwritablebytes) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象可以写入的字节数。 | +| int [OH_IPCParcel_GetReadableBytes](_o_h_i_p_c_parcel.md#oh_ipcparcel_getreadablebytes) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象还可以读取的字节数。 | +| int [OH_IPCParcel_GetReadPosition](_o_h_i_p_c_parcel.md#oh_ipcparcel_getreadposition) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象当前读取位置。 | +| int [OH_IPCParcel_GetWritePosition](_o_h_i_p_c_parcel.md#oh_ipcparcel_getwriteposition) (const OHIPCParcel \*parcel) | 获取OHIPCParcel对象当前写入位置。 | +| int [OH_IPCParcel_RewindReadPosition](_o_h_i_p_c_parcel.md#oh_ipcparcel_rewindreadposition) (OHIPCParcel \*parcel, uint32_t newReadPos) | 重置OHIPCParcel对象读取位置。 | +| int [OH_IPCParcel_RewindWritePosition](_o_h_i_p_c_parcel.md#oh_ipcparcel_rewindwriteposition) (OHIPCParcel \*parcel, uint32_t newWritePos) | 重置OHIPCParcel对象写入位置。 | +| int [OH_IPCParcel_WriteInt8](_o_h_i_p_c_parcel.md#oh_ipcparcel_writeint8) (OHIPCParcel \*parcel, int8_t value) | 向OHIPCParcel对象写入int8_t值。 | +| int [OH_IPCParcel_ReadInt8](_o_h_i_p_c_parcel.md#oh_ipcparcel_readint8) (const OHIPCParcel \*parcel, int8_t \*value) | 从OHIPCParcel对象读取int8_t值。 | +| int [OH_IPCParcel_WriteInt16](_o_h_i_p_c_parcel.md#oh_ipcparcel_writeint16) (OHIPCParcel \*parcel, int16_t value) | 向OHIPCParcel对象写入int16_t值。 | +| int [OH_IPCParcel_ReadInt16](_o_h_i_p_c_parcel.md#oh_ipcparcel_readint16) (const OHIPCParcel \*parcel, int16_t \*value) | 从OHIPCParcel对象读取int16_t值。 | +| int [OH_IPCParcel_WriteInt32](_o_h_i_p_c_parcel.md#oh_ipcparcel_writeint32) (OHIPCParcel \*parcel, int32_t value) | 向OHIPCParcel对象写入int32_t值。 | +| int [OH_IPCParcel_ReadInt32](_o_h_i_p_c_parcel.md#oh_ipcparcel_readint32) (const OHIPCParcel \*parcel, int32_t \*value) | 从OHIPCParcel对象读取int32_t值。 | +| int [OH_IPCParcel_WriteInt64](_o_h_i_p_c_parcel.md#oh_ipcparcel_writeint64) (OHIPCParcel \*parcel, int64_t value) | 向OHIPCParcel对象写入int64_t值。 | +| int [OH_IPCParcel_ReadInt64](_o_h_i_p_c_parcel.md#oh_ipcparcel_readint64) (const OHIPCParcel \*parcel, int64_t \*value) | 从OHIPCParcel对象读取int64_t值。 | +| int [OH_IPCParcel_WriteFloat](_o_h_i_p_c_parcel.md#oh_ipcparcel_writefloat) (OHIPCParcel \*parcel, float value) | 向OHIPCParcel对象写入float值。 | +| int [OH_IPCParcel_ReadFloat](_o_h_i_p_c_parcel.md#oh_ipcparcel_readfloat) (const OHIPCParcel \*parcel, float \*value) | 从OHIPCParcel对象读取float值。 | +| int [OH_IPCParcel_WriteDouble](_o_h_i_p_c_parcel.md#oh_ipcparcel_writedouble) (OHIPCParcel \*parcel, double value) | 向OHIPCParcel对象写入double值。 | +| int [OH_IPCParcel_ReadDouble](_o_h_i_p_c_parcel.md#oh_ipcparcel_readdouble) (const OHIPCParcel \*parcel, double \*value) | 从OHIPCParcel对象读取double值。 | +| int [OH_IPCParcel_WriteString](_o_h_i_p_c_parcel.md#oh_ipcparcel_writestring) (OHIPCParcel \*parcel, const char \*str) | 向OHIPCParcel对象写入字符串，包含字符串结束符。 | +| const char \* [OH_IPCParcel_ReadString](_o_h_i_p_c_parcel.md#oh_ipcparcel_readstring) (const OHIPCParcel \*parcel) | 从OHIPCParcel对象读取字符串，用户可通过strlen获取字符串长度。 | +| int [OH_IPCParcel_WriteBuffer](_o_h_i_p_c_parcel.md#oh_ipcparcel_writebuffer) (OHIPCParcel \*parcel, const uint8_t \*buffer, int32_t len) | 向OHIPCParcel对象写入指定长度的内存信息。 | +| const uint8_t \* [OH_IPCParcel_ReadBuffer](_o_h_i_p_c_parcel.md#oh_ipcparcel_readbuffer) (const OHIPCParcel \*parcel, int32_t len) | 从OHIPCParcel对象读取指定长度内存信息。 | +| int [OH_IPCParcel_WriteRemoteStub](_o_h_i_p_c_parcel.md#oh_ipcparcel_writeremotestub) (OHIPCParcel \*parcel, const OHIPCRemoteStub \*stub) | 向OHIPCParcel对象写入OHIPCRemoteStub对象。 | +| OHIPCRemoteStub \* [OH_IPCParcel_ReadRemoteStub](_o_h_i_p_c_parcel.md#oh_ipcparcel_readremotestub) (const OHIPCParcel \*parcel) | 从OHIPCParcel对象读取OHIPCRemoteStub对象。 | +| int [OH_IPCParcel_WriteRemoteProxy](_o_h_i_p_c_parcel.md#oh_ipcparcel_writeremoteproxy) (OHIPCParcel \*parcel, const OHIPCRemoteProxy \*proxy) | 向OHIPCParcel对象写入OHIPCRemoteProxy对象。 | +| OHIPCRemoteProxy \* [OH_IPCParcel_ReadRemoteProxy](_o_h_i_p_c_parcel.md#oh_ipcparcel_readremoteproxy) (const OHIPCParcel \*parcel) | 从OHIPCParcel对象读取OHIPCRemoteProxy对象。 | +| int [OH_IPCParcel_WriteFileDescriptor](_o_h_i_p_c_parcel.md#oh_ipcparcel_writefiledescriptor) (OHIPCParcel \*parcel, int32_t fd) | 向OHIPCParcel对象写入文件描述符。 | +| int [OH_IPCParcel_ReadFileDescriptor](_o_h_i_p_c_parcel.md#oh_ipcparcel_readfiledescriptor) (const OHIPCParcel \*parcel, int32_t \*fd) | 从OHIPCParcel对象读取文件描述符。 | +| int [OH_IPCParcel_Append](_o_h_i_p_c_parcel.md#oh_ipcparcel_append) (OHIPCParcel \*parcel, const OHIPCParcel \*data) | OHIPCParcel对象数据拼接。 | +| int [OH_IPCParcel_WriteInterfaceToken](_o_h_i_p_c_parcel.md#oh_ipcparcel_writeinterfacetoken) (OHIPCParcel \*parcel, const char \*token) | 向OHIPCParcel对象写入接口描述符，用于接口身份校验。 | +| int [OH_IPCParcel_ReadInterfaceToken](_o_h_i_p_c_parcel.md#oh_ipcparcel_readinterfacetoken) (const OHIPCParcel \*parcel, char \*\*token, int32_t \*len, [OH_IPC_MemAllocator](_o_h_i_p_c_parcel.md#oh_ipc_memallocator) allocator) | 从OHIPCParcel对象读取接口描述符信息，用于接口身份校验。 | diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cremote__object_8h.md b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cremote__object_8h.md new file mode 100644 index 0000000000000000000000000000000000000000..0bef77e73b44d3d1d45b5e6fb3b05f67534caa41 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cremote__object_8h.md @@ -0,0 +1,57 @@ +# ipc_cremote_object.h + + +## 概述 + +提供远端对象创建、销毁、数据发送、远端对象死亡状态监听等功能C接口。 + +**库：** libipc_capi.so + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**相关模块：**[OHIPCRemoteObject](_o_h_i_p_c_remote_object.md) + + +## 汇总 + + +### 结构体 + +| 名称 | 描述 | +| -------- | -------- | +| struct  [OH_IPC_MessageOption](_o_h___i_p_c___message_option.md) | IPC消息选项定义。 | + + +### 类型定义 + +| 名称 | 描述 | +| -------- | -------- | +| typedef int(\* [OH_OnRemoteRequestCallback](_o_h_i_p_c_remote_object.md#oh_onremoterequestcallback)) (uint32_t code, const OHIPCParcel \*data, OHIPCParcel \*reply, void \*userData) | Stub端用于处理远端数据请求的回调函数。 | +| typedef void(\* [OH_OnRemoteDestroyCallback](_o_h_i_p_c_remote_object.md#oh_onremotedestroycallback)) (void \*userData) | Stub端用于监听对象销毁的回调函数。 | +| typedef void(\* [OH_OnDeathRecipientCallback](_o_h_i_p_c_remote_object.md#oh_ondeathrecipientcallback)) (void \*userData) | 远端OHIPCRemoteStub对象死亡通知的回调函数类型。 | +| typedef void(\* [OH_OnDeathRecipientDestroyCallback](_o_h_i_p_c_remote_object.md#oh_ondeathrecipientdestroycallback)) (void \*userData) | OHIPCDeathRecipient对象销毁回调函数类型。 | + + +### 枚举 + +| 名称 | 描述 | +| -------- | -------- | +| OH_IPC_RequestMode {
[OH_IPC_REQUEST_MODE_SYNC](_o_h_i_p_c_remote_object.md) = 0,
[OH_IPC_REQUEST_MODE_ASYNC](_o_h_i_p_c_remote_object.md) = 1
} | IPC请求模式定义。 | + + +### 函数 + +| 名称 | 描述 | +| -------- | -------- | +| OHIPCRemoteStub \* [OH_IPCRemoteStub_Create](_o_h_i_p_c_remote_object.md#oh_ipcremotestub_create) (const char \*descriptor, [OH_OnRemoteRequestCallback](_o_h_i_p_c_remote_object.md#oh_onremoterequestcallback) requestCallback, [OH_OnRemoteDestroyCallback](_o_h_i_p_c_remote_object.md#oh_onremotedestroycallback) destroyCallback, void \*userData) | 创建OHIPCRemoteStub对象。 | +| void [OH_IPCRemoteStub_Destroy](_o_h_i_p_c_remote_object.md#oh_ipcremotestub_destroy) (OHIPCRemoteStub \*stub) | 销毁OHIPCRemoteStub对象。 | +| void [OH_IPCRemoteProxy_Destroy](_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy) (OHIPCRemoteProxy \*proxy) | 销毁OHIPCRemoteProxy对象。 | +| int [OH_IPCRemoteProxy_SendRequest](_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_sendrequest) (const OHIPCRemoteProxy \*proxy, uint32_t code, const OHIPCParcel \*data, OHIPCParcel \*reply, const [OH_IPC_MessageOption](_o_h___i_p_c___message_option.md) \*option) | IPC消息发送函数。 | +| int [OH_IPCRemoteProxy_GetInterfaceDescriptor](_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_getinterfacedescriptor) (OHIPCRemoteProxy \*proxy, char \*\*descriptor, int32_t \*len, [OH_IPC_MemAllocator](_o_h_i_p_c_parcel.md#oh_ipc_memallocator) allocator) | 从Stub端获取接口描述符。 | +| OHIPCDeathRecipient \* [OH_IPCDeathRecipient_Create](_o_h_i_p_c_remote_object.md#oh_ipcdeathrecipient_create) ([OH_OnDeathRecipientCallback](_o_h_i_p_c_remote_object.md#oh_ondeathrecipientcallback) deathRecipientCallback, [OH_OnDeathRecipientDestroyCallback](_o_h_i_p_c_remote_object.md#oh_ondeathrecipientdestroycallback) destroyCallback, void \*userData) | 创建远端OHIPCRemoteStub对象死亡通知对象OHIPCDeathRecipient。 | +| void [OH_IPCDeathRecipient_Destroy](_o_h_i_p_c_remote_object.md#oh_ipcdeathrecipient_destroy) (OHIPCDeathRecipient \*recipient) | 销毁OHIPCDeathRecipient对象。 | +| int [OH_IPCRemoteProxy_AddDeathRecipient](_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_adddeathrecipient) (OHIPCRemoteProxy \*proxy, OHIPCDeathRecipient \*recipient) | 向OHIPCRemoteProxy对象添加死亡监听，用于接收远端OHIPCRemoteStub对象死亡的回调通知。 | +| int [OH_IPCRemoteProxy_RemoveDeathRecipient](_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_removedeathrecipient) (OHIPCRemoteProxy \*proxy, OHIPCDeathRecipient \*recipient) | 移除向OHIPCRemoteProxy对象已经添加的死亡监听。 | +| int [OH_IPCRemoteProxy_IsRemoteDead](_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_isremotedead) (const OHIPCRemoteProxy \*proxy) | 判断OHIPCRemoteProxy对象对应的远端OHIPCRemoteStub对象是否死亡。 | diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cskeleton_8h.md b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cskeleton_8h.md new file mode 100644 index 0000000000000000000000000000000000000000..52db6b17580b0d7b7aa6f69586cab55558339776 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__cskeleton_8h.md @@ -0,0 +1,35 @@ +# ipc_cskeleton.h + + +## 概述 + +提供IPC框架tokenId、凭据、PID/UID、线程池配置等功能C接口。 + +**库：** libipc_capi.so + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**相关模块：**[OHIPCSkeleton](_o_h_i_p_c_skeleton.md) + + +## 汇总 + + +### 函数 + +| 名称 | 描述 | +| -------- | -------- | +| void [OH_IPCSkeleton_JoinWorkThread](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_joinworkthread) (void) | 当前线程加入IPC工作线程池。 | +| void [OH_IPCSkeleton_StopWorkThread](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_stopworkthread) (void) | 当前线程退出IPC工作线程池。 | +| uint64_t [OH_IPCSkeleton_GetCallingTokenId](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_getcallingtokenid) (void) | 获取调用方TokenId.该接口需要在IPC上下文中调用，否则返回自身TokenId。 | +| uint64_t [OH_IPCSkeleton_GetFirstTokenId](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_getfirsttokenid) (void) | 获取首调者TokenId。 | +| uint64_t [OH_IPCSkeleton_GetSelfTokenId](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_getselftokenid) (void) | 获取自身TokenId。 | +| uint64_t [OH_IPCSkeleton_GetCallingPid](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_getcallingpid) (void) | 获取调用方进程ID.该接口需要在IPC上下文中调用，否则返当前进程ID。 | +| uint64_t [OH_IPCSkeleton_GetCallingUid](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_getcallinguid) (void) | 获取调用方用户ID.该接口需要在IPC上下文中调用，否则返当前用户ID。 | +| int [OH_IPCSkeleton_IsLocalCalling](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_islocalcalling) (void) | 判断是否正在进行本地调用。 | +| int [OH_IPCSkeleton_SetMaxWorkThreadNum](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_setmaxworkthreadnum) (const int maxThreadNum) | 设置最大工作线程数。 | +| int [OH_IPCSkeleton_ResetCallingIdentity](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_resetcallingidentity) (char \*\*identity, int32_t \*len, [OH_IPC_MemAllocator](_o_h_i_p_c_parcel.md#oh_ipc_memallocator) allocator) | 重置调用方身份凭证为自身进程的身份凭证（包括tokenid、UID和PID信息），并返回调用方的凭证信息。 该信息主要用于OH_IPCSkeleton_SetCallingIdentity接口调用。 | +| int [OH_IPCSkeleton_SetCallingIdentity](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_setcallingidentity) (const char \*identity) | 恢复调用方凭证信息至IPC上下文中。 | +| int [OH_IPCSkeleton_IsHandlingTransaction](_o_h_i_p_c_skeleton.md#oh_ipcskeleton_ishandlingtransaction) (void) | 是否正在处理IPC请求。 | diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/ipc__error__code_8h.md b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__error__code_8h.md new file mode 100644 index 0000000000000000000000000000000000000000..81a6a882e1edd1b3e78346779583e41bff03edea --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__error__code_8h.md @@ -0,0 +1,24 @@ +# ipc_error_code.h + + +## 概述 + +提供IPC错误码定义。 + +**库：** libipc_capi.so + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**相关模块：**[OHIPCErrorCode](_o_h_i_p_c_error_code.md) + + +## 汇总 + + +### 枚举 + +| 名称 | 描述 | +| -------- | -------- | +| [OH_IPC_ErrorCode](_o_h_i_p_c_error_code.md#oh_ipc_errorcode) {
[OH_IPC_SUCCESS](_o_h_i_p_c_error_code.md) = 0,
[OH_IPC_ERROR_CODE_BASE](_o_h_i_p_c_error_code.md) = 1901000,
[OH_IPC_CHECK_PARAM_ERROR](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE,
[OH_IPC_PARCEL_WRITE_ERROR](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE + 1,
[OH_IPC_PARCEL_READ_ERROR](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE + 2,
[OH_IPC_MEM_ALLOCATOR_ERROR](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE + 3,
[OH_IPC_CODE_OUT_OF_RANGE](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE + 4,
[OH_IPC_DEAD_REMOTE_OBJECT](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE + 5,
[OH_IPC_INVALID_USER_ERROR_CODE](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE + 6,
[OH_IPC_INNER_ERROR](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE + 7,
[OH_IPC_ERROR_CODE_MAX](_o_h_i_p_c_error_code.md) = OH_IPC_ERROR_CODE_BASE + 1000,
[OH_IPC_USER_ERROR_CODE_MIN](_o_h_i_p_c_error_code.md) = 1909000,
[OH_IPC_USER_ERROR_CODE_MAX](_o_h_i_p_c_error_code.md) = 1909999
} | IPC错误码定义。 | diff --git a/zh-cn/application-dev/reference/apis-ipc-kit/ipc__kit_8h.md b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__kit_8h.md new file mode 100644 index 0000000000000000000000000000000000000000..b12754de7ddb8a4e5f6554db55226e5ead7f94a3 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-ipc-kit/ipc__kit_8h.md @@ -0,0 +1,14 @@ +# ipc_kit.h + + +## 概述 + +IPC头文件包含入口，方便开发者引用。 + +**库：** libipc_capi.so + +**系统能力：** SystemCapability.Communication.IPC.Core + +**起始版本：** 12 + +**相关模块：**[IPCKit](_i_p_c_kit.md)