From b8447ea9fca813aa1d99f579c61cbba301ce3dfd Mon Sep 17 00:00:00 2001 From: y30045598 Date: Tue, 11 Aug 2026 16:31:22 +0800 Subject: [PATCH] =?UTF-8?q?Description:=E4=B8=AD=E6=96=87d.ts=E8=A1=A5?= =?UTF-8?q?=E5=85=85=E4=BF=AE=E6=94=B9=20Feature=20or=20Bugfix:Bugfix=20Bu?= =?UTF-8?q?nary=20Source:No?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: yyh --- IPCKit/ipc_error_code.h | 2 +- zh-cn/IPCKit/ipc_cparcel.h | 225 +++++++++++++++++++++++++++++- zh-cn/IPCKit/ipc_cremote_object.h | 76 +++++++++- zh-cn/IPCKit/ipc_cskeleton.h | 48 ++++++- zh-cn/IPCKit/ipc_error_code.h | 20 +-- 5 files changed, 347 insertions(+), 24 deletions(-) diff --git a/IPCKit/ipc_error_code.h b/IPCKit/ipc_error_code.h index 37945f73a..022e2c9f9 100644 --- a/IPCKit/ipc_error_code.h +++ b/IPCKit/ipc_error_code.h @@ -92,7 +92,7 @@ typedef enum { /** * Maximum value for a custom error code. */ - OH_IPC_USER_ERROR_CODE_MAX = 1909999, + OH_IPC_USER_ERROR_CODE_MAX = 1909999 } OH_IPC_ErrorCode; /** @} */ diff --git a/zh-cn/IPCKit/ipc_cparcel.h b/zh-cn/IPCKit/ipc_cparcel.h index a6ecb9b28..f9b7d650a 100644 --- a/zh-cn/IPCKit/ipc_cparcel.h +++ b/zh-cn/IPCKit/ipc_cparcel.h @@ -42,7 +42,7 @@ extern "C" { #endif /** - * @brief IPC序列化对象，用于在跨进程通信中序列化和反序列化数据。该对象需要通过相关函数创建和销毁，开发者需要遵循对象的生命周期管理规范，正确管理内存资源。 + * @brief IPC序列化结构体，用于在跨进程通信中序列化和反序列化数据。该对象需要通过相关函数创建和销毁，开发者需要遵循对象的生命周期管理规范，正确管理内存资源。 * * @syscap SystemCapability.Communication.IPC.Core * @since 12 @@ -50,7 +50,7 @@ extern "C" { struct OHIPCParcel; /** - * @brief IPC序列化对象，用于在跨进程通信中序列化和反序列化数据。该对象需要通过相关函数创建和销毁，开发者需要遵循对象的生命周期管理规范，正确管理内存资源。 + * @brief IPC序列化结构体，用于在跨进程通信中序列化和反序列化数据。该对象需要通过相关函数创建和销毁，开发者需要遵循对象的生命周期管理规范，正确管理内存资源。 * * @syscap SystemCapability.Communication.IPC.Core * @since 12 @@ -77,7 +77,7 @@ typedef struct OHIPCRemoteProxy OHIPCRemoteProxy; /** * @brief IPC远端服务对象。该结构体用于在服务端表示一个远端服务，作为IPC通信中服务端的服务代理，用于处理客户端的请求并实现跨进程通信。OHIPCRemoteStub是IPC Kit提供的核心结构体， - * 使用OHIPCRemoteStub可以简化IPC服务开发流程，提供统一的请求处理机制，帮助开发者快速实现跨进程通信能力。主要用于： + * 使用OHIPCRemoteStub可以简化IPC服务开发流程，提供统一的请求处理机制，帮助开发者快速实现跨进程通信能力。 * * @syscap SystemCapability.Communication.IPC.Core * @since 12 @@ -86,7 +86,7 @@ struct OHIPCRemoteStub; /** * @brief IPC远端服务对象。该结构体用于在服务端表示一个远端服务，作为IPC通信中服务端的服务代理，用于处理客户端的请求并实现跨进程通信。OHIPCRemoteStub是IPC Kit提供的核心结构体， - * 使用OHIPCRemoteStub可以简化IPC服务开发流程，提供统一的请求处理机制，帮助开发者快速实现跨进程通信能力。主要用于： + * 使用OHIPCRemoteStub可以简化IPC服务开发流程，提供统一的请求处理机制，帮助开发者快速实现跨进程通信能力。 * * @syscap SystemCapability.Communication.IPC.Core * @since 12 @@ -106,6 +106,14 @@ typedef void* (*OH_IPC_MemAllocator)(int32_t len); /** * @brief 创建OHIPCParcel对象，用于IPC通信中的数据序列化。 * + * 调用此函数： + * - 在内存中分配并初始化一个OHIPCParcel对象。 + * - 对象初始状态为空，对象可序列化大小不能超过204800字节。 + * - 返回对象指针用于后续的数据读写操作。 + * - 不支持多线程并发访问同一对象。 + * - 典型使用流程：[OH_IPCParcel_Create]{@link OH_IPCParcel_Create} → + * 数据读写操作 → [OH_IPCParcel_Destroy]{@link oh_ipcparcel_destroy}。 + * * @syscap SystemCapability.Communication.IPC.Core * @return 成功返回OHIPCParcel对象指针；失败返回NULL。 * @since 12 @@ -115,6 +123,18 @@ OHIPCParcel* OH_IPCParcel_Create(void); /** * @brief 销毁OHIPCParcel对象。 * + * 调用此函数： + * - 释放OHIPCParcel对象占用的内存缓冲区。 + * - 清除对象内部的所有数据。释放对象自身的内存。 + * - 传入的指针将变为无效指针，不应再被使用。 + * - 使用前检查：确保没有其他线程正在使用该对象。 + * - 指针置空：销毁后建议将指针置为NULL，避免悬垂指针。 + * - 必须与[OH_IPCParcel_Create]{@link oh_ipcparcel_create}方法配对使用。 + * - 销毁时机：确保已读取完所有需要的数据后再销毁。 + * - 多次销毁：禁止对同一对象多次调用销毁函数。 + * - 只能销毁由[OH_IPCParcel_Create]{@link oh_ipcparcel_create}创建的对象。 + * - 销毁后不能再访问该对象。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel 需要销毁OHIPCParcel对象的指针，不能为空。 * @since 12 @@ -124,6 +144,11 @@ void OH_IPCParcel_Destroy(OHIPCParcel *parcel); /** * @brief 获取OHIPCParcel对象包含的数据的大小。常用于监控数据传输进度、检查是否超过IPC序列化大小限制、调试数据读写过程等场景。 * + * 调用此函数： + * - 计算Parcel对象中已写入数据的总字节数。 + * - 返回已写入数据的总大小值。 + * - 保持读写位置和数据内容不变。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @return 返回Parcel对象已写入数据的累计大小，单位：字节，参数不合法时返回-1。 @@ -134,6 +159,11 @@ int OH_IPCParcel_GetDataSize(const OHIPCParcel *parcel); /** * @brief 获取OHIPCParcel对象可以写入的字节数。常用于检查是否还有空间写入更多数据、防止写入溢出、批量写入前预检查等场景。 * + * 调用此函数： + * - 计算Parcel对象剩余可写入空间的大小。 + * - 返回可写字节数值。 + * - 不改变Parcel对象的读写位置或数据内容。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @return 返回可写字节数大小，单位：字节，参数不合法时返回-1。 @@ -144,6 +174,11 @@ int OH_IPCParcel_GetWritableBytes(const OHIPCParcel *parcel); /** * @brief 获取OHIPCParcel对象还可以读取的字节数。常用于检查还有多少数据可读、循环读取数据、调试数据读取过程等场景。 * + * 调用此函数： + * - 计算Parcel对象中未读取数据的字节数。 + * - 返回可读字节数值。 + * - 不改变Parcel对象的读写位置或数据内容。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @return 返回可读字节数大小，单位：字节，参数不合法时返回-1。 @@ -154,6 +189,10 @@ int OH_IPCParcel_GetReadableBytes(const OHIPCParcel *parcel); /** * @brief 获取OHIPCParcel对象当前读取位置。常用于记录读取位置以便后续恢复、配合RewindReadPosition实现重复读取、调试数据读取进度等场景。 * + * 调用此函数： + * - 返回Parcel对象当前的读取位置值。 + * - 不改变读取位置或数据内容。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @return 返回当前读位置，单位：字节，参数不合法时返回-1。 @@ -164,6 +203,10 @@ int OH_IPCParcel_GetReadPosition(const OHIPCParcel *parcel); /** * @brief 获取OHIPCParcel对象当前写入位置。常用于记录写入位置、配合RewindWritePosition修正写入错误、调试数据写入进度等场景。 * + * 调用此函数： + * - 返回Parcel对象当前的写入位置值。 + * - 不改变写入位置或数据内容。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @return 返回当前写入位置，单位：字节。参数不合法时返回-1。 @@ -174,6 +217,11 @@ int OH_IPCParcel_GetWritePosition(const OHIPCParcel *parcel); /** * @brief 重置OHIPCParcel对象的读取位置到指定位置。常用于需要重复解析数据的场景。 * + * 调用此函数： + * - 读取位置指针移动到newReadPos指定的位置，必须在[0, 当前数据大小]范围内。 + * - 已写入的数据保持不变。 + * - 后续读取操作从新位置开始。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param newReadPos 新的读取位置，范围：[0，当前数据大小]，单位：字节。超出范围时返回OH_IPC_CHECK_PARAM_ERROR错误。 @@ -186,6 +234,12 @@ int OH_IPCParcel_RewindReadPosition(OHIPCParcel *parcel, uint32_t newReadPos); /** * @brief 重置OHIPCParcel对象的写入位置到指定位置。常用于写入数据后发现前序数据错误需要修正、实现数据的分段重写、撤销部分写入操作等场景。 * + * 调用此函数： + * - 写入位置指针移动到newWritePos指定的位置，必须在[0, 当前数据大小]范围内。 + * - 重置位置可能导致部分数据被覆盖或无效，需谨慎使用。 + * - 后续写入操作从新位置开始。 + * - 重置写入位置不影响读取位置。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param newWritePos 新的写入位置，范围：[0, 当前数据大小]，单位：字节。超出范围时返回OH_IPC_CHECK_PARAM_ERROR错误。 @@ -198,6 +252,10 @@ int OH_IPCParcel_RewindWritePosition(OHIPCParcel *parcel, uint32_t newWritePos); /** * @brief 向OHIPCParcel写入一个int8_t值。不支持多线程并发访问同一对象。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadInt8]{@link oh_ipcparcel_readint8}方法配对使用。 + * - 调用顺序：先调用OH_IPCParcel_WriteInt()写入数据，接收端再调用[OH_IPCParcel_ReadInt8]{@link oh_ipcparcel_readint8}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的int8_t数据值，用于IPC通信数据序列化。 @@ -224,6 +282,10 @@ int OH_IPCParcel_ReadInt8(const OHIPCParcel *parcel, int8_t *value); /** * @brief 向OHIPCParcel对象写入int16_t值。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadInt16]{@link oh_ipcparcel_readint16}方法配对使用。 + * - 调用顺序：先调用OH_IPCParcel_WriteInt16()写入数据，接收端再调用[OH_IPCParcel_ReadInt16]{@link oh_ipcparcel_readint16}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的int16_t数据值，用于IPC通信数据序列化。 @@ -250,6 +312,10 @@ int OH_IPCParcel_ReadInt16(const OHIPCParcel *parcel, int16_t *value); /** * @brief 向OHIPCParcel对象写入int32_t值。写入数据受IPC序列化总大小限制，参见{@link OH_IPCParcel_Create}。 * + * - 必须与[OH_IPCParcel_ReadInt32]{@link oh_ipcparcel_readint32}方法配对使用。 + * - 调用顺序：先调用WriteInt()写入数据，接收端再调用[OH_IPCParcel_ReadInt32]{@link oh_ipcparcel_readint32}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的int32_t数据值，用于IPC通信数据序列化。 @@ -276,6 +342,10 @@ int OH_IPCParcel_ReadInt32(const OHIPCParcel *parcel, int32_t *value); /** * @brief 向OHIPCParcel对象写入int64_t值。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadInt64]{@link oh_ipcparcel_readint64}方法配对使用。 + * - 调用顺序：先调用WriteInt()写入数据，接收端再调用[OH_IPCParcel_ReadInt64]{@link oh_ipcparcel_readint64}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的int64_t数据值，用于IPC通信数据序列化。 @@ -302,6 +372,10 @@ int OH_IPCParcel_ReadInt64(const OHIPCParcel *parcel, int64_t *value); /** * @brief 向OHIPCParcel对象写入uint8_t值。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadUint8]{@link oh_ipcparcel_readuint8}方法配对使用。 + * - 调用顺序：先调用WriteUint()写入数据，接收端再调用[OH_IPCParcel_ReadUint8]{@link oh_ipcparcel_readuint8}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的uint8_t数据值，用于IPC通信数据序列化。 * @return 成功返回{@link OH_IPC_ErrorCode#OH_IPC_SUCCESS}； @@ -326,6 +400,10 @@ int OH_IPCParcel_ReadUint8(const OHIPCParcel *parcel, uint8_t *value); /** * @brief 向OHIPCParcel对象写入uint16_t值。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadUint16]{@link oh_ipcparcel_readuint16}方法配对使用。 + * - 调用顺序：先调用WriteUint()写入数据，接收端再调用[OH_IPCParcel_ReadUint16]{@link oh_ipcparcel_readuint16}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的uint16_t数据值，用于IPC通信数据序列化。 * @return 成功返回{@link OH_IPC_ErrorCode#OH_IPC_SUCCESS}； @@ -350,6 +428,10 @@ int OH_IPCParcel_ReadUint16(const OHIPCParcel *parcel, uint16_t *value); /** * @brief 向OHIPCParcel对象写入uint32_t值。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadUint32]{@link oh_ipcparcel_readuint32}方法配对使用。 + * - 调用顺序：先调用WriteUint()写入数据，接收端再调用[OH_IPCParcel_ReadUint32]{@link oh_ipcparcel_readuint32}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的uint32_t数据值，用于IPC通信数据序列化。 * @return 成功返回{@link OH_IPC_ErrorCode#OH_IPC_SUCCESS}； @@ -374,6 +456,10 @@ int OH_IPCParcel_ReadUint32(const OHIPCParcel *parcel, uint32_t *value); /** * @brief 向OHIPCParcel对象写入uint64_t值。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadUint64]{@link oh_ipcparcel_readuint64}方法配对使用。 + * - 调用顺序：先调用WriteUint()写入数据，接收端再调用[OH_IPCParcel_ReadUint64]{@link oh_ipcparcel_readuint64}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的uint64_t数据值，用于IPC通信数据序列化。 * @return 成功返回{@link OH_IPC_ErrorCode#OH_IPC_SUCCESS}； @@ -398,6 +484,10 @@ int OH_IPCParcel_ReadUint64(const OHIPCParcel *parcel, uint64_t *value); /** * @brief 向OHIPCParcel对象写入float值。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadFloat]{@link oh_ipcparcel_readfloat}方法配对使用。 + * - 调用顺序：先调用WriteFloat()写入数据，接收端再调用[OH_IPCParcel_ReadFloat]{@link oh_ipcparcel_readfloat}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的float数据值，用于IPC通信数据序列化。 @@ -424,6 +514,10 @@ int OH_IPCParcel_ReadFloat(const OHIPCParcel *parcel, float *value); /** * @brief 向OHIPCParcel对象写入double值。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * - 必须与[OH_IPCParcel_ReadDouble]{@link oh_ipcparcel_readdouble}方法配对使用。 + * - 调用顺序：先调用WriteDouble()写入数据，接收端再调用[OH_IPCParcel_ReadDouble]{@link oh_ipcparcel_readdouble}读取数据。 + * - 未正确配对：如果未按顺序调用或读取类型不匹配，会导致读取失败或数据错误。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param value 要写入的double数据值，用于IPC通信数据序列化。 @@ -450,6 +544,14 @@ int OH_IPCParcel_ReadDouble(const OHIPCParcel *parcel, double *value); /** * @brief 向OHIPCParcel对象写入字符串，包括字符串结束符。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * 调用此函数： + * - 将字符串内容(包括结束符'\0')写入到OHIPCParcel对象的当前写入位置。 + * - 写入位置自动后移(字符串长度+1)字节。 + * - 字符串数据被序列化存储在Parcel对象中，无需调用者管理。 + * - 写入的字符串长度受IPC序列化大小限制(参见[OH_IPCParcel_Create]{@link OH_IPCParcel_Create}，最大204800字节)。 + * - str参数不能为空，否则会返回参数错误。 + * - 编码说明：字符串应为有效的UTF-8或ASCII编码。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param str 写入字符串，用于IPC通信中的字符串数据传输，不能为空。长度范围[0, 204800]，单位：字节（含结束符，实际长度受parcel已写入数据与结束符开销的动态影响）。写入的字符串长度受IPC序列化大小限制（ @@ -464,6 +566,15 @@ int OH_IPCParcel_WriteString(OHIPCParcel *parcel, const char *str); /** * @brief 从OHIPCParcel对象读取字符串，用户可通过strlen获取字符串长度。 * + * 调用此函数： + * 1. 从当前读取位置读取字符串内容。 + * 2. 返回字符串的内存地址指针。 + * 3. 读取位置自动后移到字符串结束符之后。 + * 4. 返回的字符串内存由Parcel对象管理，无需调用者释放。 + * 5. 字符串有效性与Parcel对象绑定，销毁Parcel后字符串失效。 + * 6. 参数不合法或读取失败时返回NULL，需检查返回值。 + * 7. 可通过strlen获取长度，直接使用返回的指针访问字符串内容。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @return 成功返回读取字符串地址；参数不合法或读取失败时返回NULL。 @@ -474,6 +585,16 @@ const char* OH_IPCParcel_ReadString(const OHIPCParcel *parcel); /** * @brief 向OHIPCParcel对象写入指定长度的内存信息。常用于写入二进制数据、图片数据、自定义结构体、共享内存内容等场景。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * 调用此函数： + * - 将buffer指向的内存数据写入到OHIPCParcel对象的当前写入位置。 + * - 写入位置自动后移len字节。 + * - 内存数据被序列化存储在Parcel对象中。 + * - buffer必须提前分配足够的内存空间，且内存有效。 + * - len取值范围[0, parcel可写字节数]，超出范围会返回错误。 + * - buffer不能为空，否则会返回参数错误。 + * - 写入的数据应在调用期间保持有效，写入完成后无限制。 + * - 写入完成后，buffer内存由调用者自行管理，Parcel内部存储副本。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param buffer 写入内存的起始地址，要写入的数据缓冲区的起始地址，指向需要通过IPC传输的二进制数据，不能为空。缓冲区必须提前分配好足够的内存空间。 @@ -489,6 +610,13 @@ int OH_IPCParcel_WriteBuffer(OHIPCParcel *parcel, const uint8_t *buffer, int32_t /** * @brief 从OHIPCParcel对象读取指定长度内存信息。常用于读取二进制数据、图片数据、自定义结构体、共享内存内容等场景。 * + * 调用此函数： + * - 从当前读取位置读取len字节的内存数据，len取值范围[0, parcel可读字节数]，超出范围会返回NULL。 + * - 返回指向Parcel对象内部存储数据的指针。 + * - 读取位置自动后移len字节。 + * - 返回的内存由Parcel对象管理，无需调用者释放。 + * - 生命周期：数据有效性与Parcel对象绑定，销毁Parcel后数据失效。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param len 读取内存的长度，单位：字节，取值范围[0, parcel当前剩余可读字节数]。超出可读字节数时返回NULL。 @@ -501,6 +629,14 @@ const uint8_t* OH_IPCParcel_ReadBuffer(const OHIPCParcel *parcel, int32_t len); * @brief 向OHIPCParcel对象写入OHIPCRemoteStub对象。常用于跨进程传递服务对象、实现IPC服务端的远程调用、服务对象共享等场景。 * 写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * 调用此函数： + * - 将OHIPCRemoteStub对象的引用信息写入到OHIPCParcel对象中，写入位置自动后移。 + * - Stub对象的引用信息被序列化存储。 + * - 调用顺序：先调用WriteRemoteStub()写入Stub对象，接收端再调用[OH_IPCParcel_ReadRemoteStub]{@link oh_ipcparcel_readremotestub}读取。 + * - 未正确配对：如果未按顺序调用或未配对使用，会导致接收端无法正确获取Stub对象引用，影响IPC通信建立。 + * - 对象有效性：stub不能为空，必须为有效的OHIPCRemoteStub对象指针，否则会返回参数错误。 + * - 引用管理：写入后Stub对象的引用计数增加，需确保Stub对象生命周期足够。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param stub 需要写入的OHIPCRemoteStub对象指针，不能为空。 @@ -514,6 +650,15 @@ int OH_IPCParcel_WriteRemoteStub(OHIPCParcel *parcel, const OHIPCRemoteStub *stu /** * @brief 从OHIPCParcel对象读取OHIPCRemoteStub对象。常用于跨进程接收服务对象、实现IPC服务端的远程调用、服务对象共享等场景。 * + * 调用此函数： + * - 从当前读取位置读取Stub对象的引用信息。 + * - 返回OHIPCRemoteStub对象的指针。 + * - 读取位置自动后移。 + * - 必须与[OH_IPCParcel_WriteRemoteStub]{@link oh_ipcparcel_writeremotestub}方法配对使用。 + * - 返回的Stub对象指针由系统管理，需按IPC规范使用。 + * - 读取失败时返回NULL，需检查返回值。 + * - 通常用于接收服务端传递的Stub对象，用于建立IPC通信。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @return 成功返回OHIPCRemoteStub对象指针；失败返回NULL。 @@ -525,6 +670,16 @@ OHIPCRemoteStub* OH_IPCParcel_ReadRemoteStub(const OHIPCParcel *parcel); * @brief 向OHIPCParcel对象写入OHIPCRemoteProxy对象。常用于跨进程传递代理对象、实现IPC客户端的远程调用、代理对象共享等场景。 * 写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * 调用此函数： + * - 将OHIPCRemoteProxy对象的引用信息写入到OHIPCParcel对象中。 + * - 写入位置自动后移。 + * - Proxy对象的引用信息被序列化存储。 + * - 调用顺序：先调用[OH_IPCParcel_WriteRemoteProxy]{@link oh_ipcparcel_writeremoteproxy}写入Proxy对象， + * 接收端再调用[OH_IPCParcel_ReadRemoteProxy]{@link oh_ipcparcel_readremoteproxy}读取。 + * - 未正确配对：如果未按顺序调用或未配对使用，会导致接收端无法正确获取Proxy对象引用，影响IPC通信建立。 + * - 对象有效性：proxy不能为空，必须为有效的OHIPCRemoteProxy对象指针，否则会返回参数错误。 + * - 引用管理：写入后Proxy对象的引用计数增加，需确保Proxy对象生命周期足够。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param proxy 需要写入的OHIPCRemoteProxy对象指针，不能为空。 @@ -538,6 +693,14 @@ int OH_IPCParcel_WriteRemoteProxy(OHIPCParcel *parcel, const OHIPCRemoteProxy *p /** * @brief 从OHIPCParcel对象读取OHIPCRemoteProxy对象。常用于跨进程接收代理对象、实现IPC客户端的远程调用、代理对象共享等场景。 * + * 调用此函数： + * - 从当前读取位置读取Proxy对象的引用信息。 + * - 返回OHIPCRemoteProxy对象的指针。 + * - 读取位置自动后移。 + * - 必须与[OH_IPCParcel_WriteRemoteProxy]{@link oh_ipcparcel_writeremoteproxy}方法配对使用。 + * - 返回的Proxy对象指针由系统管理，需按IPC规范使用。 + * - 读取失败时返回NULL，需检查返回值。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @return 成功返回OHIPCRemoteProxy对象指针；失败返回NULL。 @@ -548,6 +711,18 @@ OHIPCRemoteProxy* OH_IPCParcel_ReadRemoteProxy(const OHIPCParcel *parcel); /** * @brief 向OHIPCParcel对象写入文件描述符。常用于跨进程传递文件句柄、共享内存文件描述符、管道文件描述符等场景。写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * 调用此函数： + * - 将文件描述符的副本写入到OHIPCParcel对象中。 + * - 写入位置自动后移。 + * - 文件描述符信息被序列化存储，可在IPC通信中传递。 + * - 调用顺序：先调用[OH_IPCParcel_WriteFileDescriptor]{@link oh_ipcparcel_writefiledescriptor}写入文件描述符，接收端再调用 + * [OH_IPCParcel_ReadFileDescriptor]{@link oh_ipcparcel_readfiledescriptor}读取。 + * - 未正确配对：如果未按顺序调用或未配对使用，会导致接收端无法获取正确的文件描述符，影响跨进程文件共享和访问。 + * - 文件描述符有效性：fd必须为有效的非负整数文件描述符。 + * - 资源管理：写入后原文件描述符仍由调用者管理，需自行关闭。 + * - 权限传递：接收端获得的文件描述符具有相同的访问权限。 + * - 系统限制：文件描述符传递受系统限制，某些特殊文件描述符可能无法传递。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param fd 要写入的文件描述符，取值原则：有效的文件描述符，为非负整数。传入负数或无效文件描述符时返回OH_IPC_CHECK_PAARM_ERROR错误。 @@ -561,6 +736,16 @@ int OH_IPCParcel_WriteFileDescriptor(OHIPCParcel *parcel, int32_t fd); /** * @brief 从OHIPCParcel对象读取文件描述符。常用于跨进程接收文件句柄、共享内存文件描述符、管道文件描述符等场景。不支持多线程并发访问同一对象。 * + * 调用此函数： + * - 从当前读取位置读取文件描述符信息。 + * - 返回一个新的有效的文件描述符。 + * - 读取位置自动后移。 + * - 新文件描述符指向与原文件相同的资源，继承原文件描述符的访问权限。 + * - 必须与[OH_IPCParcel_WriteFileDescriptor]{@link oh_ipcparcel_writefiledescriptor}方法配对使用。 + * - 读取到的文件描述符需要由接收方管理，使用完毕后应关闭。 + * - 返回的文件描述符应检查是否有效(非负值)。 + * - 文件描述符的生命周期独立于Parcel对象。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param fd 存储读取文件描述符的指针，不能为空。读取前需确保parcel中已写入有效的文件描述符数据。 @@ -574,6 +759,15 @@ int OH_IPCParcel_ReadFileDescriptor(const OHIPCParcel *parcel, int32_t *fd); /** * @brief OHIPCParcel对象数据拼接。常用于合并多个Parcel的数据、数据包组装、分段写入数据的合并等场景。拼接数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * 调用此函数： + * - 将源Parcel对象(data)中的数据复制并追加到目标Parcel对象(parcel)的当前写入位置。 + * - 写入位置自动后移追加数据的字节数。 + * - 源Parcel对象的读取位置和内容保持不变。 + * - 追加操作会复制源数据到目标Parcel，内存由目标Parcel管理。 + * - 拼接后的数据总大小不能超过IPC序列化限制(参见[OH_IPCParcel_Create]{@link oh_ipcparcel_create})。 + * - parcel和data参数均不能为空，否则会返回参数错误。 + * - 两个参数必须为由[OH_IPCParcel_Create]{@link oh_ipcparcel_create}创建的有效对象。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param data data源OHIPCParcel对象的指针，不能为空。 @@ -588,6 +782,18 @@ int OH_IPCParcel_Append(OHIPCParcel *parcel, const OHIPCParcel *data); * @brief 向OHIPCParcel对象写入接口描述符，用于接口身份校验。常用于IPC通信中的安全验证场景，例如：防止恶意进程发送伪造请求、确保消息发送到正确的服务接口、多接口服务中区分不同的接口调用。不支持多线程并发访问同一对象。 * 写入数据受IPC序列化总大小限制（参见{@link OH_IPCParcel_Create}）。 * + * 调用此函数： + * - 将接口描述符字符串写入到OHIPCParcel对象的当前写入位置。 + * - 写入位置自动后移相应的字节数。 + * - 接口描述符数据被序列化存储在Parcel对象中。 + * - 接口描述符字符串长度不能超过Parcel剩余可写空间。 + * - 调用顺序：客户端先调用[OH_IPCParcel_WriteInterfaceToken]{@link oh_ipcparcel_writeinterfacetoken}写入接口描述符， + * 服务端再调用[OH_IPCParcel_ReadInterfaceToken]{@link oh_ipcparcel_readinterfacetoken}读取并校验。 + * - 如果未按顺序调用或未配对使用，会导致接口身份校验失败，请求可能被拒绝或发送到错误的接口，造成接口混淆。 + * - token参数不能为空，否则会返回参数错误。 + * - 建议在写入其他请求数据前先写入接口描述符。 + * - 接口描述符应为接口的全限定名或唯一标识字符串。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param token 需要写入的接口描述符信息，不能为空。接口描述符通常为接口的全限定名或唯一标识字符串，用于接口身份校验。字符串长度范围[0, parcel剩余可写空间]，单位：字节。 @@ -602,6 +808,17 @@ int OH_IPCParcel_WriteInterfaceToken(OHIPCParcel *parcel, const char *token); /** * @brief 从OHIPCParcel对象读取接口描述符信息，用于接口身份校验。 * + * 调用此函数： + * - 必须与[OH_IPCParcel_WriteInterfaceToken]{@link oh_ipcparcel_writeinterfacetoken}方法配对使用。 + * - 从当前读取位置读取接口描述符字符串。 + * - 通过用户提供的allocator分配内存存储描述符。 + * - 返回描述符地址和长度。 + * - 读取位置自动后移。 + * - token内存由用户提供的allocator分配，使用后必须主动释放。 + * - 即使函数返回失败，也需要检查token是否为空并释放。 + * - 未正确释放token会导致内存泄漏。 + * - 建议在处理请求前先校验接口描述符。 + * * @syscap SystemCapability.Communication.IPC.Core * @param parcel OHIPCParcel对象的指针，不能为空。 * @param token 用于存储接口描述符信息的内存地址，该内存由用户提供的分配器进行内存分配，用户使用完后需要主动释放，不能为空。接口返回失败时，用户依然需要判断该内存是否为空，并主动释放，否则会造成内存泄漏。 diff --git a/zh-cn/IPCKit/ipc_cremote_object.h b/zh-cn/IPCKit/ipc_cremote_object.h index 69148c15b..baf42bd55 100644 --- a/zh-cn/IPCKit/ipc_cremote_object.h +++ b/zh-cn/IPCKit/ipc_cremote_object.h @@ -25,8 +25,8 @@ /** * @file ipc_cremote_object.h * - * @brief 提供远端对象创建、销毁、数据发送、远端对象死亡状态监听等功能的C接口，适用于IPC（Inter-Process Communication，进程间通信）和RPC（Remote Procedure Call，远程过程调用） - * 通信场景。 + * @brief 提供远端对象创建、销毁、数据发送、远端对象死亡状态监听等功能的C接口，适用于IPC（Inter-Process Communication，进程间通信）和 + * RPC（Remote Procedure Call，远程过程调用）通信场景。 * * @library libipc_capi.so * @kit IPCKit @@ -67,6 +67,10 @@ typedef struct OHIPCDeathRecipient OHIPCDeathRecipient; * @brief Stub端用于处理远端数据请求的回调函数。当Proxy端通过{@link OH_IPCRemoteProxy_SendRequest}发送请求时，系统会触发此回调函数。回调函数在Binder线程池中执行， * 需要注意线程安全。回调函数应尽快返回，避免长时间阻塞，否则可能影响其他IPC请求的处理。 * + * - 服务端实现自定义IPC通信协议时，用于接收并处理来自客户端的跨进程请求。 + * - 需要跨进程调用服务端能力时，服务端通过此回调函数处理具体业务逻辑。 + * - 实现RPC服务端能力时，作为消息分发和处理的入口。 + * * @syscap SystemCapability.Communication.IPC.Core * @param code 用户定义的IPC命令字，范围：[0x01, 0x00ffffff]。建议按业务模块分段定义code值，避免不同功能命令冲突。例如：0x01-0x100用于基础功能，0x101-0x200用于扩展功能。 * @param data 请求数据对象指针，不会为空，函数内不允许释放。 @@ -83,6 +87,10 @@ typedef int (*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data /** * @brief 用于监听对象销毁的回调函数。 * + * - 需要在Stub对象销毁时释放相关资源（如内存、文件句柄）。 + * - 需要在对象销毁时通知其他模块进行状态同步。 + * - 需要在对象销毁时清理用户私有数据。 + * * @syscap SystemCapability.Communication.IPC.Core * @param userData 用户私有数据，当需要在回调函数中访问用户自定义数据时传入此参数，不需要访问用户数据时可为NULL。传入NULL时回调函数无法访问用户私有数据。 * @since 12 @@ -92,6 +100,16 @@ typedef void (*OH_OnRemoteDestroyCallback)(void *userData); /** * @brief 创建OHIPCRemoteStub对象，用于Stub端创建服务端对象，处理来自Proxy端的远端数据请求。 * + * - 服务端需要提供跨进程服务能力时，创建Stub对象作为服务端实体。 + * - 实现自定义IPC通信协议的服务端部分 - 构建RPC服务端服务能力。 + * - 创建Stub对象后，通常需要通过OH_IPCRemoteProxy相关接口将Stub对象注册到服务管理器，供Proxy端发现和连接。 + * - requestCallback中应避免耗时操作，以免阻塞IPC通信。 + * - 如需处理耗时任务，可在回调中返回错误码并使用线程池异步处理。 + * - 确保userData的生命周期覆盖Stub对象的生命周期，避免悬空指针。 + * - 调用[OH_IPCRemoteStub_Create()]{@link oh_ipcremotestub_create}创建对象后， + * 必须在使用完毕后调用[OH_IPCRemoteStub_Destroy()]{@link oh_ipcremotestub_destroy}销毁对象释放资源。 + * - 未销毁会导致内存泄漏。 + * * @syscap SystemCapability.Communication.IPC.Core * @param descriptor OHIPCRemoteStub对象描述符，不能为空。字符串长度取值范围：(0, 204800]字节。超出范围时返回NULL。建议使用唯一的标识符字符串， * 如："com.example.myservice"或"MyService"。格式通常为反向域名或简单服务名称，用于标识不同的IPC服务接口。 @@ -107,6 +125,13 @@ OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequ /** * @brief 销毁OHIPCRemoteStub对象。 * + * - 服务端不再需要提供IPC服务时，释放Stub对象。 + * - 服务端退出或模块卸载时，清理IPC资源。 + * - 与[OH_IPCRemoteStub_Create()]{@link oh_ipcremotestub_create}配对使用。 + * - 必须在Stub对象不再被使用时调用。 + * - 销毁后会自动触发destroyCallback回调释放userData。 + * - 销毁后不能再使用该Stub对象进行任何操作。 + * * @syscap SystemCapability.Communication.IPC.Core * @param stub 要销毁的OHIPCRemoteStub对象指针，不能为空。 * @since 12 @@ -116,6 +141,12 @@ void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub); /** * @brief 销毁OHIPCRemoteProxy对象。 * + * - 客户端不再需要调用远端服务时，释放Proxy对象。 + * - 客户端退出或模块卸载时，清理IPC资源。 + * - 必须先调用[OH_IPCRemoteProxy_RemoveDeathRecipient()]{@link oh_ipcremoteproxy_removedeathrecipient}移除所有已添加的死亡监听。 + * - 如果未移除监听就销毁Proxy对象，将导致死亡监听回调异常或内存泄漏。 + * - 销毁后不能再调用该Proxy的任何方法。 + * * @syscap SystemCapability.Communication.IPC.Core * @param proxy 要销毁的OHIPCRemoteProxy对象指针，不能为空。 * @since 12 @@ -139,7 +170,7 @@ typedef enum { } OH_IPC_RequestMode; /** - * @brief Defines the IPC message options. + * @brief IPC消息选项定义，用于配置IPC通信过程中的请求参数。 * * @since 12 */ @@ -166,6 +197,16 @@ typedef struct { /** * @brief IPC消息发送函数，用于Proxy端向远端Stub发送IPC消息请求，支持同步和异步两种通信模式。 * + * - 客户端需要跨进程调用服务端能力时，发送请求并获取响应。 + * - 实现客户端与服务端的IPC通信交互。 + * - 调用远端服务的业务接口。 + * - 同步模式适用于需要等待结果的请求，如查询操作；异步模式适用于无需等待结果的请求，如日志上报。 + * - 同步调用会阻塞当前线程，应避免在UI线程中使用，以免造成卡顿。 + * - 异步调用虽然不阻塞线程，但仍需注意调用频率，避免过度占用IPC通道。 + * - 建议在调用前先使用[OH_IPCRemoteProxy_IsRemoteDead()]{@link oh_ipcremoteproxy_isremotedead}检查远端是否存活。 + * - 调用失败时，建议根据返回的错误码进行相应的重试或错误处理。 + * - 频繁的IPC调用会影响性能，建议合理设计通信协议，减少调用次数。 + * * @syscap SystemCapability.Communication.IPC.Core * @param proxy OHIPCRemoteProxy对象指针，不能为空。 * @param code 用户定义的IPC命令字，范围：[0x01, 0x00ffffff]。超出范围时返回OH_IPC_CODE_OUT_OF_RANGE错误码。 @@ -188,6 +229,8 @@ int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, * @brief 从Stub端获取接口描述符。接口描述符是Stub对象的唯一标识，用于识别远端服务类型、进行服务版本兼容性检查或者验证远端服务是否实现了特定接口。函数通过IPC调用从远端Stub获取描述符字符串， * 并使用用户提供的内存分配器存储结果。 * + * - 返回的描述符字符串内存由用户提供的allocator分配，用户使用完毕后必须主动释放，否则会造成内存泄漏。即使函数调用失败，也需要检查descriptor是否非空并释放。 + * * @syscap SystemCapability.Communication.IPC.Core * @param proxy OHIPCRemoteProxy对象指针，不能为空。 * @param descriptor 用于存储描述符的内存地址，该内存由用户提供的分配器进行内存分配，用户使用完后需要主动释放，不能为空。接口返回失败时，用户依然需要判断该内存是否为空，并主动释放，否则会造成内存泄漏。 @@ -227,6 +270,16 @@ typedef void (*OH_OnDeathRecipientDestroyCallback)(void *userData); * @brief 创建远端OHIPCRemoteStub对象死亡通知对象OHIPCDeathRecipient。用于监听远端Stub对象的死亡状态。常用于客户端需要监听服务端对象的死亡事件、 * 需要实现服务端异常退出的感知机制以及需要在服务端崩溃时进行故障处理或自动重连。 * + * - 死亡回调会在远端Stub对象销毁或进程崩溃时触发，建议在回调中释放相关资源、重置状态、尝试重连。 + * - 死亡回调可能在任意线程执行，需注意线程安全，避免在回调中进行耗时操作。 + * - 建议在回调中不要直接销毁[OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md)对象，应在回调外进行销毁操作。 + * - 多个Proxy可以共用同一个[OHIPCDeathRecipient](capi-ohipcremoteobject-ohipcdeathrecipient.md)对象，但需确保在销毁前从所有Proxy中移除。 + * - 如果Proxy已死亡，添加死亡监听会立即触发回调，需在添加前做好状态检查。 + * - 建议在应用初始化时创建并添加死亡监听，在应用退出时移除并销毁。 + * - 创建后需要通过[OH_IPCRemoteProxy_AddDeathRecipient()]{@link oh_ipcremoteproxy_adddeathrecipient}添加到Proxy对象。 + * - 不再需要监听时，必须先调用[OH_IPCRemoteProxy_RemoveDeathRecipient()]{@link oh_ipcremoteproxy_removedeathrecipient}移除监听。 + * - 移除监听后，必须调用[OH_IPCDeathRecipient_Destroy()]{@link oh_ipcdeathrecipient_destroy}销毁对象。 + * * @syscap SystemCapability.Communication.IPC.Core * @param deathRecipientCallback 远端OHIPCRemoteStub对象死亡通知的回调处理函数，不能为空。 * @param destroyCallback 对象销毁回调处理函数，可以为NULL。为NULL时不监听对象销毁事件。当需要在OHIPCDeathRecipient对象销毁时执行清理操作（如释放userData资源）时传入此参数， @@ -241,6 +294,12 @@ OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback dea /** * @brief 销毁OHIPCDeathRecipient对象。常用于不再需要监听远端对象死亡事件以及客户端退出或模块卸载时，清理死亡监听资源。 * + * - 与[OH_IPCDeathRecipient_Create()]{@link oh_ipcdeathrecipient_create}配对使用。 + * - 必须先调用[OH_IPCRemoteProxy_RemoveDeathRecipient()]{@link oh_ipcremoteproxy_removedeathrecipient}从所有Proxy中移除该监听对象。 + * - 死亡监听对象不再需要时销毁。 + * - 未移除监听直接销毁将导致回调异常或内存泄漏。 + * - 销毁后会自动触发destroyCallback释放userData。 + * * @syscap SystemCapability.Communication.IPC.Core * @param recipient 要销毁的OHIPCDeathRecipient对象指针，不能为空。 * @since 12 @@ -251,6 +310,14 @@ void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient); * @brief 向OHIPCRemoteProxy对象添加死亡监听，用于接收远端OHIPCRemoteStub对象死亡的回调通知。常用于客户端启动后，注册服务端死亡监听以便及时感知服务端异常、 * 需要实现服务端故障检测和自动恢复机制以及需要在服务端不可用时及时释放相关资源或通知用户。 * + * - 未移除监听直接销毁对象可能导致回调异常或内存泄漏。 + * - 先调用[OH_IPCDeathRecipient_Create()]{@link oh_ipcdeathrecipient_create}创建监听对象。 + * - 调用[OH_IPCRemoteProxy_AddDeathRecipient()]{@link oh_ipcremoteproxy_adddeathrecipient}添加监听。 + * - 使用中，监听回调会被触发。 + * - 在销毁Proxy或Recipient前，应先调用[OH_IPCRemoteProxy_RemoveDeathRecipient()]{@link oh_ipcremoteproxy_removedeathrecipient} + * 移除监听。 + * - 调用[OH_IPCDeathRecipient_Destroy()]{@link oh_ipcdeathrecipient_destroy}销毁监听对象。 + * * @syscap SystemCapability.Communication.IPC.Core * @param proxy 需要添加死亡通知的OHIPCRemoteProxy对象指针，不能为空。 * @param recipient 用于接收远程对象死亡通知的死亡对象指针，不能为空。 @@ -264,6 +331,9 @@ int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecip /** * @brief 移除向OHIPCRemoteProxy对象已经添加的死亡监听。常用于不再需要监听远端对象死亡事件时取消注册或切换到其他服务实例时移除旧的死亡监听。 * + * - 如果不再需要该监听对象，应调用[OH_IPCDeathRecipient_Destroy()]{@link oh_ipcdeathrecipient_destroy}销毁。 + * - 未销毁会导致内存泄漏。 + * * @syscap SystemCapability.Communication.IPC.Core * @param proxy 需要移除死亡通知的OHIPCRemoteProxy对象指针，不能为空。 * @param recipient 用于接收远程对象死亡通知的死亡对象指针，不能为空。 diff --git a/zh-cn/IPCKit/ipc_cskeleton.h b/zh-cn/IPCKit/ipc_cskeleton.h index d4fc11702..77ac2912c 100644 --- a/zh-cn/IPCKit/ipc_cskeleton.h +++ b/zh-cn/IPCKit/ipc_cskeleton.h @@ -45,6 +45,12 @@ extern "C" { /** * @brief 当前线程加入IPC工作线程池，使其能够参与处理IPC请求。适用于需要自定义IPC请求处理线程的场景，例如：在需要扩展IPC并发处理能力时手动添加工作线程、在特定业务场景下需要专用线程处理IPC请求以提高响应速度。 + * 调用此方法后，当前线程将被注册为IPC工作线程，参与处理来自其他进程的IPC请求， + * 直到调用[OH_IPCSkeleton_StopWorkThread()]{@link oh_ipcskeleton_stopworkthread}退出线程池。 + * + * - 仅在需要处理IPC请求的场景下调用。 + * - 调用后线程将阻塞等待处理IPC请求。 + * - 建议配合[OH_IPCSkeleton_StopWorkThread()]{@link oh_ipcskeleton_stopworkthread}使用以正确退出线程池。 * * @syscap SystemCapability.Communication.IPC.Core * @since 12 @@ -52,7 +58,11 @@ extern "C" { void OH_IPCSkeleton_JoinWorkThread(void); /** - * @brief 当前线程退出IPC工作线程池，不再参与处理IPC请求。 + * @brief 当前线程退出IPC工作线程池，不再参与处理IPC请求。调用此方法后，当前线程将从IPC工作线程池中移除，不再被分配处理IPC请求的任务，线程可以执行其他操作。 + * + * - 应在不再需要处理IPC请求时调用。 + * - 调用前需确保当前线程已通过[OH_IPCSkeleton_JoinWorkThread()]{@link oh_ipcskeleton_joinworkthread}加入线程池。 + * - 线程退出时应确保所有IPC事务处理完成。 * * @syscap SystemCapability.Communication.IPC.Core * @since 12 @@ -70,7 +80,10 @@ uint64_t OH_IPCSkeleton_GetCallingTokenId(void); /** * @brief 获取IPC调用链中首个调用方的TokenId。该接口需要在IPC上下文中调用，否则返回自身TokenId。适用于多级服务调用中的权限追溯和安全审计场景，例如：在需要追踪原始调用方身份而非中间代理服务的权限审计中、 - * 在跨进程的权限继承验证中确认最原始的权限来源。 + * 在跨进程的权限继承验证中确认最原始的权限来源。返回发起IPC调用的首个客户端的TokenId标识。 + * + * - 仅在多级IPC调用场景中有意义。 + * - 在单级调用场景中，与[OH_IPCSkeleton_GetCallingTokenId()]{@link oh_ipcskeleton_getcallingtokenid}返回值相同。 * * @syscap SystemCapability.Communication.IPC.Core * @return 返回首调者TokenId。 @@ -80,6 +93,9 @@ uint64_t OH_IPCSkeleton_GetFirstTokenId(void); /** * @brief 获取当前进程自身的TokenId标识。适用于进程自我身份验证和权限状态确认场景，例如：在服务启动时校验自身权限状态、在权限检查中确认自身是否具备访问特定资源的权限、在安全审计中标识当前进程身份。 + * 返回当前进程的TokenId，无论是否在IPC上下文中调用。 + * + * - 可在任意上下文中调用，不依赖IPC上下文。 * * @syscap SystemCapability.Communication.IPC.Core * @return 返回自身TokenId。 @@ -110,6 +126,9 @@ uint64_t OH_IPCSkeleton_GetCallingUid(void); /** * @brief 判断当前IPC调用是否为本地调用。 * + * - 需在IPC上下文中调用。 + * - 常用于根据调用类型采取不同处理策略。 + * * @syscap SystemCapability.Communication.IPC.Core * @return 正在进行本地调用，返回1；否则，返回0。 * @since 12 @@ -117,7 +136,14 @@ uint64_t OH_IPCSkeleton_GetCallingUid(void); int OH_IPCSkeleton_IsLocalCalling(void); /** - * @brief 设置IPC工作线程池的最大线程数，控制IPC请求的并发处理能力。 + * @brief 设置IPC工作线程池的最大线程数，控制IPC请求的并发处理能力。调用此方法后，IPC框架将按照设置的最大线程数管理工作线程，当并发IPC请求数超过线程数时，请求将排队等待。 + * + * - 建议在应用启动时调用，避免运行时频繁修改。 + * - 此配置应在调用[OH_IPCSkeleton_JoinWorkThread()]{@link oh_ipcskeleton_joinworkthread}加入工作线程池之前完成，以确保线程池按配置大小工作。 + * - 此配置影响后续加入线程池的线程容量控制。 + * - 若无特殊诉求，不建议用户更改最大线程数。 + * - 线程数过多会增加系统资源消耗，过少可能影响IPC并发处理性能。 + * - 需根据实际业务场景和设备能力合理设置。 * * @syscap SystemCapability.Communication.IPC.Core * @param maxThreadNum 最大工作线程数，单位：个，默认16，范围:[1, 32]。设置该参数可控制IPC并发处理能力，较小的值可节省系统资源，较大的值可提高并发处理效率。 @@ -131,11 +157,16 @@ int OH_IPCSkeleton_SetMaxWorkThreadNum(const int maxThreadNum); /** * @brief 重置调用方身份凭证为自身进程的身份凭证（包括TokenId、UID和PID信息），并返回调用方的凭证信息。适用于需要临时提升权限或以服务进程身份执行操作的场景，例如：在系统服务中需要访问受保护资源时临时切换为服务身份、 - * 在权限代理场景中以服务身份代为执行特权操作。 + * 在权限代理场景中以服务身份代为执行特权操作。调用此方法后，当前IPC上下文的身份凭证将切换为自身进程的凭证，同时返回原始调用方的凭证信息，用于后续恢复。 + * + * - 必须在IPC请求处理上下文中调用。 + * - 返回的凭证信息需要由调用方妥善管理，使用后需释放。 + * - 必须与[OH_IPCSkeleton_SetCallingIdentity()]{@link oh_ipcskeleton_setcallingidentity}配对使用，在操作完成后恢复原始凭证。 + * - 避免长时间保持重置状态，可能影响权限校验。 * * @syscap SystemCapability.Communication.IPC.Core - * @param identity identity 用于存储调用凭证的内存地址，凭证中包含调用方的TokenId、UID和PID等身份信息，可用于后续通过 - * {@link OH_IPCSkeleton_SetCallingIdentity()} 恢复调用方身份。该内存由用户提供的分配器进行内存分配，用户使用完后需要主动释放。必须在IPC请求处理上下文中调用。不能为空。 + * @param identity identity 用于存储调用凭证的内存地址，凭证中包含调用方的TokenId、UID和PID等身份信息， + * 可用于后续通过{@link OH_IPCSkeleton_SetCallingIdentity()}恢复调用方身份。该内存由用户提供的分配器进行内存分配，用户使用完后需要主动释放。必须在IPC请求处理上下文中调用。不能为空。 * @param len len 写入identity的数据长度（字节数），用于告知调用者凭证数据的实际大小，便于后续正确使用和释放内存。必须在IPC请求处理上下文中调用。不能为空。 * @param allocator allocator 用户指定的内存分配器，用于为identity分配内存。通过自定义分配器可控制内存分配策略（如使用共享内存或堆内存）。必须在IPC请求处理上下文中调用。不能为空。 * @return 成功返回{@link OH_IPC_ErrorCode#OH_IPC_SUCCESS}（对应值：0）； @@ -150,6 +181,11 @@ int OH_IPCSkeleton_ResetCallingIdentity(char **identity, int32_t *len, OH_IPC_Me * @brief 恢复调用方凭证信息至IPC上下文中。将IPC上下文的身份凭证恢复为原始调用方的凭证。必须在IPC请求处理上下文中调用。适用于完成临时权限提升操作后恢复正常权限的场景，例如：在服务端完成受保护资源访问后恢复调用方身份、 * 在权限代理操作完成后还原调用方权限状态。 * + * - 调用此方法后，IPC上下文的身份凭证将恢复为之前通过[OH_IPCSkeleton_ResetCallingIdentity()]{@link oh_ipcskeleton_resetcallingidentity} + * 保存的调用方凭证。 + * - 应在完成需要服务端身份的操作后立即调用。 + * - 身份凭证应正确管理，避免凭证泄露。 + * * @syscap SystemCapability.Communication.IPC.Core * @param identity identity 调用方凭证，不能为空。来源于OH_IPCSkeleton_ResetCallingIdentity的返回值。 * 需与OH_IPCSkeleton_ResetCallingIdentity配对使用。 diff --git a/zh-cn/IPCKit/ipc_error_code.h b/zh-cn/IPCKit/ipc_error_code.h index d7d4c8606..7cbe1dcee 100644 --- a/zh-cn/IPCKit/ipc_error_code.h +++ b/zh-cn/IPCKit/ipc_error_code.h @@ -24,7 +24,7 @@ /** * @file ipc_error_code.h * - * @brief 定义IPC错误码定义，用于标识和处理IPC通信过程中可能发生的各类错误。开发者可根据返回的错误码快速定位问题原因，如参数错误、序列化失败、内存分配失败、远端对象死亡等场景，从而采取相应的错误处理措施。 + * @brief 提供IPC错误码定义，用于标识和处理IPC通信过程中可能发生的各类错误。开发者可根据返回的错误码快速定位问题原因，如参数错误、序列化失败、内存分配失败、远端对象死亡等场景，从而采取相应的错误处理措施。 * * @library libipc_capi.so * @kit IPCKit @@ -49,35 +49,35 @@ typedef enum { * 错误码区间起始值。 */ 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, - /** + /** * 命令字超出定义范围[0x01,0x00FFFFFF]。当IPC通信使用的命令字不在有效范围内时返回此错误码。开发者应检查命令字定义是否符合规范要求。 */ OH_IPC_CODE_OUT_OF_RANGE = OH_IPC_ERROR_CODE_BASE + 4, - /** + /** * 远端对象死亡。当IPC通信的对端进程已退出或远端对象已被销毁时返回此错误码。开发者应重新建立连接或使用替代服务。 */ OH_IPC_DEAD_REMOTE_OBJECT = OH_IPC_ERROR_CODE_BASE + 5, - /** + /** * 用户自定义错误码超出范围[1909000, 1909999]。当开发者设置的自定义错误码不在允许范围内时返回此错误码。开发者应确保自定义错误码在有效范围内。 */ OH_IPC_INVALID_USER_ERROR_CODE = OH_IPC_ERROR_CODE_BASE + 6, - /** + /** * IPC内部错误。当IPC系统内部发生未知错误时返回此错误码。开发者可记录日志并联系技术支持或稍后重试。 */ OH_IPC_INNER_ERROR = OH_IPC_ERROR_CODE_BASE + 7, @@ -92,7 +92,7 @@ typedef enum { /** * 用户自定义错误码最大值。 */ - OH_IPC_USER_ERROR_CODE_MAX = 1909999, + OH_IPC_USER_ERROR_CODE_MAX = 1909999 } OH_IPC_ErrorCode; /** @} */