Declares the set of APIs for enabling file cache boost.
File to include: <PreviewKit/file_cache_boost.h>
Library: libfile_cache_boost.so
System capability: SystemCapability.PCService.OpenFileBoost
Since: 6.1.0(23)
Related module: Preview
| Name | Description |
|---|---|
| typedef struct CacheKey CacheKey | External declaration of the key-related data structure passed by you. You only need to pass it when the serialization function SerializeFunc and deserialization function DeserializeFunc call WriteFunc and ReadFunc. |
| typedef FileCacheBoost_ErrCode(* ReadFunc) (void *buffer, size_t *bufferLen, struct CacheKey *key) | Function called during DeserializeFunc deserialization to read data from the cache to the buffer. |
| typedef FileCacheBoost_ErrCode(* WriteFunc) (const void *buffer, size_t bufferLen, struct CacheKey *key) | Function called during SerializeFunc serialization to write data to the cache. |
| typedef FileCacheBoost_CbErrCode(* DeserializeFunc) (void **object, ReadFunc readFunc, struct CacheKey *key) | Callback function for the system to perform the deserialization operation. This function is used to deserialize data to original data. Implement it yourself. |
| typedef FileCacheBoost_CbErrCode(* SerializeFunc) (const void *object, WriteFunc writeFunc, struct CacheKey *key) | Callback function for the system to perform the serialization operation. This function is used to serialize complex data. Implement it yourself. |
| Name | Description |
|---|---|
| FILE_CACHE_BOOST_SUCCESS = 0, FILE_CACHE_BOOST_ERROR_INVALID_PARAM = 401, FILE_CACHE_BOOST_ERROR_NOT_SUPPORTED = 801, FILE_CACHE_BOOST_ERROR_NOMEM = 1017220001, FILE_CACHE_BOOST_ERROR_INTERNAL_ERROR = 1017220002, FILE_CACHE_BOOST_ERROR_KEY_NOT_FOUND = 1017220003, FILE_CACHE_BOOST_ERROR_KEY_EXIST = 1017220004, FILE_CACHE_BOOST_ERROR_NOT_DIR = 1017220005, FILE_CACHE_BOOST_ERROR_IO = 1017220006, FILE_CACHE_BOOST_ERROR_IO_CANCELED = 1017220007, FILE_CACHE_BOOST_ERROR_NOT_INITIALIZED = 1017220008, FILE_CACHE_BOOST_ERROR_EXCEED_LIMIT = 1017220009, FILE_CACHE_BOOST_ERROR_IO_CANCEL_FAILED = 1017220010 } | Enumerates the error codes for file cache boost. |
| FILE_CACHE_BOOST_CALLBACK_SUCCESS = 0, FILE_CACHE_BOOST_CALLBACK_FAILURE = 1017221001, FILE_CACHE_BOOST_CALLBACK_IO_CANCELED = 1017221002 } | Enumerates the error codes for the callback functions DeserializeFunc and SerializeFunc. It is used by the app to return the callback function execution result to the system. |
| Name | Description |
|---|---|
| bool HMS_Preview_FileCacheBoost_IsSupported (void) | Checks whether the current device supports file cache boost. It is recommended that you call this API to check whether the current device supports file cache boost before using the file open cache function. After confirming that the device supports this function, you can use other file cache boost APIs, such as HMS_FileCacheBoost_Init. |
| FileCacheBoost_ErrCode HMS_FileCacheBoost_Init (const char *path, size_t pathLen, uint32_t cacheUpperLimitMb, const char *dbName, size_t dbNameLen) | Initializes the cache path, cache capacity upper limit, and database name. The system ensures thread concurrency security control. If multi-process concurrency scenarios need to be supported, it is recommended that each process use a different database file name to ensure access security. |
| FileCacheBoost_ErrCode HMS_FileCacheBoost_AddObjectByKey (const uint8_t *key, size_t keyLen, const uint8_t *data, size_t dataLen, uint32_t weight) | Creates and adds a cache object to the file cache. The system manages cache through keys. You are advised to properly design and manage keys to ensure their uniqueness and accuracy across different contexts. When the cache is no longer needed, you are advised to call HMS_FileCacheBoost_RemoveObjectByKey to delete the cache item, thereby avoiding resource waste. If the cache item is not deleted, the system will delete it based on the system policy when the cache capacity becomes insufficient. If you want to modify the cache content corresponding to a key, you need to call HMS_FileCacheBoost_RemoveObjectByKey to delete the key, and then create and add a new one. |
| FileCacheBoost_ErrCode HMS_FileCacheBoost_GetObjectByKey (const uint8_t *key, size_t keyLen, uint8_t **data, size_t *dataLen) | Queries a cache object based on the specified key. If the cache object exists, its content is loaded from the disk. This function is called for the system to allocate a memory segment for storing cache data and return the memory segment to you as an output parameter. After using the memory, you need to call HMS_FileCacheBoost_FreeObject to explicitly free the memory. |
| void HMS_FileCacheBoost_FreeObject (uint8_t *data) | Frees the memory allocated by calling HMS_FileCacheBoost_GetObjectByKey or HMS_FileCacheBoost_GetSerialObjectByKey. It is recommended that you call this function promptly to free the memory when it is no longer needed, preventing memory leaks. |
| FileCacheBoost_ErrCode HMS_FileCacheBoost_AddSerialObjectByKey (const uint8_t *key, size_t keyLen, SerializeFunc func, const void *object, uint32_t weight) | Creates a cache item for a complex type object. A custom serialization function SerializeFunc is passed to serialize the object so that it can be stored on a disk and later restored. For example, for image data, both its metadata and pixel data must be saved in order to complete the full caching and reading process. Serialization and deserialization consume memory. You need to control the object size to reduce memory pressure. |
| FileCacheBoost_ErrCode HMS_FileCacheBoost_GetSerialObjectByKey (const uint8_t *key, size_t keyLen, DeserializeFunc func, void **object) | Obtains a complex cache object based on the specified key and restores the object to the original data using the input deserialization function DeserializeFunc to obtain the complete object content. This function is called for the system to allocate a memory segment for storing cache data and return the memory segment to you as an output parameter. After using the memory, you need to call HMS_FileCacheBoost_FreeObject to explicitly free the memory. |
| FileCacheBoost_ErrCode HMS_FileCacheBoost_RemoveObjectByKey (const uint8_t *key, size_t keyLen) | Deletes a cache object based on the specified key. |
| FileCacheBoost_ErrCode HMS_FileCacheBoost_CancelOngoingIOByKey (const uint8_t *key, size_t keyLen) | Cancels the ongoing I/O operation of the cache object corresponding to the specified key. When you need to release a data object, call this function to prevent other threads from adding or obtaining cache objects for the data object. If the object is being cached, the operation will be canceled. If caching has already completed, the function performs no action. For example, when a thread attempts to delete a data object, another thread may perform the HMS_FileCacheBoost_AddObjectByKey operation on the data object. In this case, you can call this function to ensure the security of the cache object and avoid data race. |
| FileCacheBoost_ErrCode HMS_FileCacheBoost_ClearAllCache (void) | Clears all cache objects. This function is used to release all cache objects created by HMS_FileCacheBoost_AddObjectByKey and HMS_FileCacheBoost_AddSerialObjectByKey. |