diff --git a/zh-cn/native_sdk/memory/purgeable_memory.h b/zh-cn/native_sdk/memory/purgeable_memory.h new file mode 100644 index 0000000000000000000000000000000000000000..1209f3cf130dc19e1755157dbd7f415400b52ba9 --- /dev/null +++ b/zh-cn/native_sdk/memory/purgeable_memory.h @@ -0,0 +1,178 @@ +/* + * Copyright (c) 2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 1.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-1.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup memory + * @{ + * + * @brief 提供内存管理能力。 + * + * @Syscap SystemCapability.CommonLibrary.PurgeableMemory + * @since 10 + * @version 1.0 + */ + +/** + * @file purgeable_memory.h + * + * @brief 声明从native层管理可丢弃内存的方法。 + * + * @since 10 + * @version 1.0 + */ + +#ifndef INTERFACES_KITS_NATIVE_INCLUDE_PURGEABLE_MEMORY_H_ +#define INTERFACES_KITS_NATIVE_INCLUDE_PURGEABLE_MEMORY_H_ +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义native层OH_PurgeableMemory对象。 + * + * @since 10 + * @version 1.0 + */ +struct OH_PurgeableMemory; + +/** + * @brief 用于定义OH_PurgeableMemory数据类型名称。 + * + * @since 10 + * @version 1.0 + */ +typedef struct OH_PurgeableMemory OH_PurgeableMemory; + +/** + * @brief: 用于重建可丢弃内存PurgeableMemory数据的方法。 + * + * @param void * 指向PurgeableMemory内容的内存地址。 + * @param size_t 重建内容的大小。 + * @param void * 重建参数。 + * @return: 操作成功则返回成功;如果操作失败,则返回失败。 + * @since 10 + * @version 1.0 + */ +typedef bool (*OH_PurgeableMemory_ModifyFunc)(void *, size_t, void *); + +/** + * @brief: 创建PurgeableMemory对象。 + * + * @param size PurgeableMemory对象大小。 + * @param func 关于重建方法的函数指针,用于恢复被回收的PurgeableMemory内存数据。 + * @param funcPara 用于重建的参数。 + * @return 返回PurgeableMemory对象。 + * @since 10 + * @version 1.0 + */ +OH_PurgeableMemory *OH_PurgeableMemory_Create( + size_t size, OH_PurgeableMemory_ModifyFunc func, void *funcPara); + +/** + * @brief 销毁PurgeableMemory对象。 + * + * @param purgObj 需要销毁的PurgeableMemory对象。 + * @return 操作成功则返回成功;如果操作失败,则返回失败。如果purgObj为空则返回失败; + * 如果返回成功,purgObj会置空避免Use-After-Free。 + * @since 10 + * @version 1.0 + */ +bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory *purgObj); + +/** + * @brief 开始读取PurgeableMemory对象。检查PurgeableMemory是否被回收, + * 若被回收则调用重建方法进行重建 + * + * @param purgObj 待读取的PurgeableMemory对象。 + * @return 如果PurgeableMemory内存数据准备好则返回成功; + * 如果PurgeableMemory内存数据已被回收且重建失败则返回失败。 + * @since 10 + * @version 1.0 + */ +bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory *purgObj); + +/** + * @brief 结束读取PurgeableMemory对象。表示系统可回收该PurgeableMemory对象内存数据。 + * + * @param purgObj: 结束读取的PurgeableMemory对象。 + * @since 10 + * @version 1.0 + */ +void OH_PurgeableMemory_EndRead(OH_PurgeableMemory *purgObj); + +/** + * @brief 开始修改PurgeableMemory对象。检查PurgeableMemory是否被回收, + * 若被回收则调用重建方法进行重建 + * + * @param purgObj 待修改的PurgeableMemory对象。 + * @return: 如果PurgeableMemory内存数据准备好则返回成功; + * 如果PurgeableMemory内存数据已被回收且重建失败则返回失败。 + * @since 10 + * @version 1.0 + */ +bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory *purgObj); + +/** + * @brief 结束修改PurgeableMemory对象。表示系统可回收该PurgeableMemory对象内存数据。 + * + * @param purgObj 结束修改的PurgeableMemory对象。 + * @since 10 + * @version 1.0 + */ +void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory *purgObj); + +/** + * @brief 获取PurgeableMemory对象内存数据。 + * + * @param 待读取内存数据的PurgeableMemory对象。 + * @return 返回PurgeableMemory对象内存地址。 + * @since 10 + * @version 1.0 + */ +void *OH_PurgeableMemory_GetContent(OH_PurgeableMemory *purgObj); + +/** + * @brief 获取PurgeableMemory对象内存数据大小。 + * + * @param 待读取内存数据的PurgeableMemory对象。 + * @return 返回PurgeableMemory对象内存数据大小。 + * @since 10 + * @version 1.0 + */ +size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory *purgObj); + +/** + * @brief 添加PurgeableMemory对象的修改方法。 + * + * @param purgObj 待添加修改方法的PurgeableMemory对象。 + * @param func 关于数据修改方法的函数指针,用于PurgeableMemory内存数据重建后进一步修改。 + * @param funcPara 修改方法的参数。 + * @return 如果添加成功则返回成功,否则返回失败。 + * + * @since 10 + * @version 1.0 + */ +bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory *purgObj, + OH_PurgeableMemory_ModifyFunc func, void *funcPara); + +#ifdef __cplusplus +}; +#endif + +/** @} */ +#endif /* OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEMORY_H */ \ No newline at end of file