Preview Kit provides apps with convenient and fast file preview services, including file open boost and file cache boost.
The file open boost function allows apps to load files in advance, shortening the file opening time and providing users with a smooth experience.
The file cache boost function allows apps to cache decoded data to disks through the cache service. In this way, the cache data can be directly obtained later, eliminating the need for decoding and improving the file opening and browsing performance.
For details, please refer to File Open Boost Development Guide and File Cache Boost Development Guide.
Since: 5.0.3(15)
| Name | Description |
|---|---|
| open_file_boost.h | Declares the set of APIs for enabling file open boost. |
| file_cache_boost.h | Declares the APIs used for file cache boost to optimize performance in scenarios such as file opening and browsing. |
| preview_kit.h | Declares all header files contained in Preview Kit. |
| Name | Description |
|---|---|
| MAX_BUFFER_LENGTH 1024 | The sandbox path can contain a maximum of 1,024 characters. |
| Name | Description |
|---|---|
| typedef OpenFileBoost_AppState(* HMS_OpenFileBoost_QueryAppState) (void) | Function called before HMS_OpenFileBoost_OnFilePreload is called to recommend files. This function is used to query whether the app is suitable for file recommendation. For example, if the app is in the foreground focus or in certain special states and is not suitable for preloading files, the app returns a specific enumerated value to reject preloading. |
| typedef OpenFileBoost_CbErrCode(* HMS_OpenFileBoost_OnFilePreload) (void *fileInfo) | Function through which the system predicts the files that may be opened by the user and notifies the app. In some scenarios, for example, the available memory of the system is insufficient or other files are more likely to be opened by the user, the system instructs the app to cancel the preloading of some files. |
| 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(* 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. |
| 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 struct FileScanBoost_ScanOption FileScanBoost_ScanOption | Opaque type of the file scanning option configuration. |
| typedef struct FileScanBoost_ScanResult FileScanBoost_ScanResult | Opaque type of the file scanning result. |
| typedef FileScanBoost_CbErrCode(* HMS_Preview_FileScanBoost_OnFileScan) (int32_t fd, const char *path, uint32_t pathLen) | Type of the pointer to the function of the file scanning callback notification. The system calls this callback to send a scanning task. This callback method is asynchronous with the scanning task execution. Your app should return the callback result immediately after receiving the scanning task, without blocking the callback. In addition, the final result after the scanning task is complete should be reported using HMS_Preview_FileScanBoost_ReportScanResult. |
| typedef struct OpenFileBoost_SupportFile OpenFileBoost_SupportFile | Information about the files that can be preloaded by the app, which is used to describe a group of file features that meet the preloading conditions. You can use HMS_Preview_OpenFileBoost_SupportFileCreate to create this struct and configure the types of files that can be preloaded by the system. |
| typedef struct OpenFileBoost_Options OpenFileBoost_Options | Information about the files that can be preloaded and the number of file types. It is used to register a batch of file types that can be preloaded with the system. |
| typedef struct OpenFileBoost_FileOperationInfo OpenFileBoost_FileOperationInfo | File operation information sent by the app to the system. You can pass the file path and the file operation information. The operation information includes but is not limited to: open, close, import, export, tab_hidden, tab_visible, save, create, upload, download, share, print, save_as, and play. You can use the HMS_Preview_OpenFileBoost_FileOperationInfoCreate function to create this struct. |
| Name | Description |
|---|---|
| OPEN_FILE_BOOST_SUCCESS = 0, OPEN_FILE_BOOST_PERMISSION_NOT_GRANTED = 201, OPEN_FILE_BOOST_INVALID_PARAM = 401, OPEN_FILE_BOOST_CAPABILITY_NOT_SUPPORTED = 801, OPEN_FILE_BOOST_INTERNAL_ERROR = 1017200001, OPEN_FILE_BOOST_INSUFFICIENT_BUFFER = 1017200002, OPEN_FILE_BOOST_SERVICE_UNAVAILABLE = 1017200003, OPEN_FILE_BOOST_NO_MEMORY = 1017200004 } | Enumerates the error codes for file open boost. |
| OPEN_FILE_BOOST_CALLBACK_SUCCESS = 0, OPEN_FILE_BOOST_CALLBACK_FAILURE = 1017210000 } | Enumerates the error codes for the callback function HMS_OpenFileBoost_OnFilePreload. It is used by the app to return the callback function execution result to the system. |
| OPEN_FILE_BOOST_APP_STATE_ALLOW_PRELOAD = 0, OPEN_FILE_BOOST_APP_STATE_REJECT_PRELOAD = 1, OPEN_FILE_BOOST_APP_STATE_FOREVER_REJECT_PRELOAD = 2, OPEN_FILE_BOOST_APP_STATE_EXCEL_TRANSACTION = 3 } | Enumerates the app statuses, indicating that the app allows, rejects, or permanently rejects the file preloading recommended by the system. |
| 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. |
| FILE_SCAN_BOOST_SUCCESS = 0, FILE_SCAN_BOOST_ERROR_PERMISSION_NOT_GRANTED = 201, FILE_SCAN_BOOST_ERROR_INVALID_PARAM = 401, FILE_SCAN_BOOST_ERROR_CAPABILITY_NOT_SUPPORTED = 801, FILE_SCAN_BOOST_ERROR_INTERNAL = 1017230001, FILE_SCAN_BOOST_ERROR_NOT_REGISTERED = 1017230002, FILE_SCAN_BOOST_ERROR_ALREADY_REGISTERED = 1017230003, FILE_SCAN_BOOST_ERROR_SERVICE_UNAVAILABLE = 1017230004, FILE_SCAN_BOOST_ERROR_FORMAT_NOT_SUPPORTED = 1017230005 } | Enumerates all error codes returned by the file scanning boost function. |
| FILE_SCAN_BOOST_CALLBACK_SUCCESS = 0, FILE_SCAN_BOOST_CALLBACK_ERROR_INTERNAL = 1017240001, FILE_SCAN_BOOST_CALLBACK_ERROR_FORMAT_NOT_SUPPORTED = 1017240002 } | Enumerates specific error codes for file scanning callbacks. |
| FILE_SCAN_BOOST_SCAN_STATE_SUCCESS = 0, FILE_SCAN_BOOST_SCAN_STATE_PROCESS_ERROR = 1, FILE_SCAN_BOOST_SCAN_STATE_FILE_ERROR = 2 } | Enumerates the scanning statuses after file scanning. |
| Name | Description |
|---|---|
| bool HMS_Preview_FileBoost_IsSupported (void) | Checks whether the current device supports file open boost. You are advised to use this API to check whether the device supports file open boost. After confirming that the device supports this function, you can use other file open boost APIs, such as HMS_OpenFileBoost_RegisterFilePreload and HMS_Preview_FileScanBoost_RegisterFileScan. |
| OpenFileBoost_ErrCode HMS_OpenFileBoost_GetFdFromPreloadFileInfo (void *fileInfo, int32_t *fd) | Obtains the file descriptor information. |
| OpenFileBoost_ErrCode HMS_OpenFileBoost_GetSandboxPathFromPreloadFileInfo (void *fileInfo, char *sandboxPath, int32_t pathLen) | Obtains the sandbox path information. |
| OpenFileBoost_ErrCode HMS_OpenFileBoost_RegisterFilePreload (HMS_OpenFileBoost_QueryAppState queryAppState, HMS_OpenFileBoost_OnFilePreload filePreload, HMS_OpenFileBoost_OnFilePreload cancelFilePreload) | Called to register a file preloading callback with the system. When predicting the file that the user may open, the system first calls queryAppState to query whether the preloading file can be recommended. If the app returns a message indicating that the recommendation is allowed through queryAppState, the system calls filePreload to recommend a file for the app to preload. In some specific cases, for example, the available memory of the system is insufficient, other files are more likely to be opened by the user, or other conditions that are not suitable for the file to remain in the preloading state occur, the system calls cancelFilePreload to cancel the preloading of some files. |
| OpenFileBoost_ErrCode HMS_OpenFileBoost_UnregisterFilePreload (void) | Unregisters the preloading callback. |
| OpenFileBoost_ErrCode HMS_OpenFileBoost_NotifyPreloadHit (int32_t fd, char *sandboxPath, int32_t pathLen) | Called to notify the system of the preloading hit when a user opens a preloaded file. This helps improve the prediction accuracy of file preloading. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanOptionCreate (FileScanBoost_ScanOption **outOption) | Creates a FileScanBoost_ScanOption instance. |
| void HMS_Preview_FileScanBoost_ScanOptionDestroy (FileScanBoost_ScanOption *option) | Destroys a FileScanBoost_ScanOption instance. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanOptionAddSupportFile (FileScanBoost_ScanOption *option, const char *suffix, uint32_t suffixLen) | Adds file types supported by an app to the scanning option. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanResultCreate (FileScanBoost_ScanResult **outResult) | Creates a FileScanBoost_ScanResult instance. |
| void HMS_Preview_FileScanBoost_ScanResultDestroy (FileScanBoost_ScanResult *result) | Destroys a FileScanBoost_ScanResult instance. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanResultSetState (FileScanBoost_ScanResult *result, FileScanBoost_ScanState state) | Sets the scanning status in the result. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanResultSetMaxAtomicTime (FileScanBoost_ScanResult *result, int64_t maxAtomicTime) | Sets the maximum atomic time in the result. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanResultSetMemSize (FileScanBoost_ScanResult *result, int64_t memSize) | Sets the memory size in the result. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_RegisterFileScan (HMS_Preview_FileScanBoost_OnFileScan fileScanCb, FileScanBoost_ScanOption *option) | Registers a callback for multiple file types using extension-based filtering. Do not re-register before the previous registration is deregistered. Duplicate registrations will return the error code FILESCANBOOST_ERROR_ALREADY_REGISTERED, and only the information from the initial registration will take effect. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_UnregisterFileScan (void) | Unregisters the registered file scanning callback. |
| FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ReportScanResult (const char *path, uint32_t pathLen, FileScanBoost_ScanResult *result) | Reports the file scanning result. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_SupportFileCreate (const char *suffix, uint32_t suffixLen, uint64_t lowerLimitKb, uint64_t upperLimitKb, OpenFileBoost_SupportFile **outSupportFile) | Creates OpenFileBoost_SupportFile. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_SupportFileDestroy (OpenFileBoost_SupportFile *supportFile) | Destroys OpenFileBoost_SupportFile. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_OptionsCreate (OpenFileBoost_Options **outOptions) | Creates an empty OpenFileBoost_Options. Use HMS_Preview_OpenFileBoost_OptionsAddSupportFile to add a file. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_OptionsAddSupportFile (OpenFileBoost_Options *options, const OpenFileBoost_SupportFile *supportFile) | Adds a list of file types that support preloading to OpenFileBoost_Options. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_OptionsDestroy (OpenFileBoost_Options *options) | Destroys OpenFileBoost_Options. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_RegisterFilePreloadWithOption (HMS_OpenFileBoost_QueryAppState queryAppState, HMS_OpenFileBoost_OnFilePreload filePreload, HMS_OpenFileBoost_OnFilePreload cancelFilePreload, OpenFileBoost_Options *options) | Registers a preload callback, which allows an app to pass file information that supports preloading. |
| bool HMS_Preview_OpenFileBoost_IsEnabled (void) | Checks whether the file open boost function is available for the app. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_FileOperationInfoCreate (const char *path, uint32_t pathLen, const char *operation, uint32_t operationLen, OpenFileBoost_FileOperationInfo **outFileOperationInfo) | Creates OpenFileBoost_FileOperationInfo. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_FileOperationInfoDestroy (OpenFileBoost_FileOperationInfo *fileOperationInfo) | Destroys OpenFileBoost_FileOperationInfo. |
| OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_NotifyFileOperation (OpenFileBoost_FileOperationInfo *fileOperationInfo) | Called to notify the system of the file operation type when a user performs an operation on a file. This helps improve the prediction accuracy of file preloading. |
| bool HMS_Preview_FileCacheBoost_IsSupported (void) | Checks whether the current device supports file cache boost. You are advised to use this API to check whether the device supports file cache boost. 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. Cache path: You pass a relative path, and the cache is stored in the app sandbox directory. Cache capacity upper limit: When the system detects that the total cache capacity exceeds the configured upper limit, it will manage the capacity based on the cache eviction policy and delete the corresponding cache to free up space. |
| 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. This function caches data to the file cache system based on the specified unique identifier (key) for fast access in the future. 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. If the function returns FILE_CACHE_BOOST_SUCCESS, you can immediately release the data object. If the function returns FILE_CACHE_BOOST_ERROR_IO_CANCEL_FAILED, no key is being executed and needs to be canceled. In this case, you need to ensure that the action corresponding to the key has been completed or does not need to be executed before releasing the data object. 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. |
#define MAX_BUFFER_LENGTH 1024
Description
Maximum length of the sandbox path.
Since: 5.0.3(15)
typedef OpenFileBoost_CbErrCode(*HMS_OpenFileBoost_OnFilePreload) (void *fileInfo)
Description
Function called when the system recommends or cancels the recommendation of a preloaded file to an app. Function through which the system predicts the files that may be opened by the user and notifies the app. In some scenarios, for example, the available memory of the system is insufficient or other files are more likely to be opened by the user, the system instructs the app to cancel the preloading of some files.
Since: 5.0.3(15)
Parameters:
| Name | Description |
|---|---|
| fileInfo | Preloads file information. The app can call HMS_OpenFileBoost_GetFdFromPreloadFileInfo to obtain the corresponding file descriptor information, and then call HMS_OpenFileBoost_GetSandboxPathFromPreloadFileInfo to obtain the corresponding sandbox path information. The app must synchronously parse the preloaded file in the current callback context so that the system can evaluate the resource consumption of the preloaded file. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_CbErrCode | Function execution result. If the execution is successful, OPEN_FILE_BOOST_CALLBACK_SUCCESS is returned. If the execution fails, OPEN_FILE_BOOST_CALLBACK_FAILURE is returned. |
typedef OpenFileBoost_AppState(*HMS_OpenFileBoost_QueryAppState) (void)
Description
Function called when the system queries the app status. This function calls back the app before calling the HMS_OpenFileBoost_OnFilePreload recommendation file. This function is used to query whether the app is suitable for file recommendation. For example, if the app is in the foreground focus or in certain special states and is not suitable for preloading files, the app returns a specific enumerated value to reject preloading.
Since: 5.0.3(15)
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_AppState | Returns OPEN_FILE_BOOST_APP_STATE_ALLOW_PRELOAD if the app allows file recommendation. Then the system calls HMS_OpenFileBoost_OnFilePreload to preload the recommendation file. Returns OPEN_FILE_BOOST_APP_STATE_REJECT_PRELOAD if the app rejects the recommendation. Returns OPEN_FILE_BOOST_APP_STATE_FOREVER_REJECT_PRELOAD if the app does not want to receive recommendations during the current registration. Then the app needs to call HMS_OpenFileBoost_UnregisterFilePreload as soon as possible to cancel the registration. |
typedef struct FileScanBoost_ScanOption FileScanBoost_ScanOption
Description
Opaque type of the file scanning option configuration.
Since: 26.0.0
typedef struct FileScanBoost_ScanResult FileScanBoost_ScanResult
Description
Opaque type of the file scanning result.
Since: 26.0.0
typedef FileScanBoost_CbErrCode(* HMS_Preview_FileScanBoost_OnFileScan) (int32_t fd, const char *path, uint32_t pathLen)
Description
Type of the pointer to the function of the file scanning callback notification. The system calls this callback to send a scanning task. This callback method is asynchronous with the scanning task execution. Your app should return the callback result immediately after receiving the scanning task, without blocking the callback. In addition, the final result after the scanning task is complete should be reported using HMS_Preview_FileScanBoost_ReportScanResult.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| fd | File descriptor of the file to be scanned. |
| path | File path. |
| pathLen | Length of the file path. For the maximum path length, it is set to PATH_MAX. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_CbErrCode | Callback error code. The app accepts the scan task or returns an error. FILE_SCAN_BOOST_CALLBACK_SUCCESS indicates that the scan task is accepted. Otherwise, the scan task is not accepted. |
typedef struct OpenFileBoost_FileOperationInfo OpenFileBoost_FileOperationInfo
Description
File operation information sent by the app to the system. You can pass the file path and the file operation information. The operation information includes but is not limited to:
| Operation | String |
|---|---|
| Open | "open" |
| Close | "close" |
| Import/Load | "import" |
| Export | "export" |
| Hide the tab | "tab_hidden" |
| Make the tab visible | "tab_visible" |
| Save | "save" |
| Create | "create" |
| Cloud upload | "upload" |
| Cloud download | "download" |
| Share | "share" |
| "print" | |
| Save as | "save_as" |
| Play | "play" |
Since: 26.0.0
typedef struct OpenFileBoost_Options OpenFileBoost_Options
Description
Information about the files that can be preloaded and the number of file types. It is used to register a batch of file types that can be preloaded with the system.
Since: 26.0.0
typedef struct OpenFileBoost_SupportFile OpenFileBoost_SupportFile
Description
Information about the files that can be preloaded by the app, which is used to describe a group of file features that meet the preloading conditions. You can use HMS_Preview_OpenFileBoost_SupportFileCreate to create this struct and configure the types of files that can be preloaded by the system.
Since: 26.0.0
typedef struct CacheKey CacheKey
Description
External declaration of the input key-related data structure when the serialization function SerializeFunc and deserialization function DeserializeFunc call WriteFunc and ReadFunc.
Since: 6.1.0(23)
typedef FileCacheBoost_CbErrCode(*SerializeFunc) (const void *object, WriteFunc writeFunc, struct CacheKey *key)
Description
Serialization function, which defines the callback API for serialization. This function is used to serialize complex data. Implement it yourself.
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| object | Object to be serialized. |
| writeFunc | Callback function for writing serialized data to the cache. For details about the parameter type, please refer to WriteFunc. |
| key | Key of the serialized object. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_CbErrCode | Function execution result. If the function is executed successfully, FILE_CACHE_BOOST_CALLBACK_SUCCESS is returned. If the function fails to be executed, FILE_CACHE_BOOST_CALLBACK_FAILURE is returned. For other errors, please refer to FileCacheBoost_CbErrCode. |
typedef FileCacheBoost_ErrCode(*WriteFunc) (const void *buffer, size_t bufferLen, struct CacheKey *key)
Description
Function called during SerializeFunc serialization to write data to the cache.
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| buffer | Data to be written. |
| bufferLen | Length of the data to be written. |
| key | Key of the object to be written to the cache. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_CACHE_BOOST_SUCCESS is returned. If the task of writing an object to the cache cannot be executed because the memory of the data object is released, FILE_CACHE_BOOST_ERROR_IO_CANCELED is returned. For other errors, please refer to FileCacheBoost_ErrCode. |
typedef FileCacheBoost_CbErrCode(*DeserializeFunc) (void **object, ReadFunc readFunc, struct CacheKey *key)
Description
Deserialization function, which defines the callback API for deserialization. This function is used to deserialize data to original data. Implement it yourself.
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| object | Data generated after deserialization. |
| readFunc | Callback function for reading serialized data from the cache. For details about the parameter type, please refer to ReadFunc. |
| key | Key of the object to be deserialized. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_CbErrCode | Function execution result. If the function is executed successfully, FILE_CACHE_BOOST_CALLBACK_SUCCESS is returned. If the function fails to be executed, FILE_CACHE_BOOST_CALLBACK_FAILURE is returned. For other errors, please refer to FileCacheBoost_CbErrCode. |
typedef FileCacheBoost_ErrCode(*ReadFunc) (void *buffer, size_t *bufferLen, struct CacheKey *key)
Description
Function called during DeserializeFunc deserialization to read data from the cache to the buffer.
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| buffer | Buffer for storing the read data. |
| bufferLen | As an input parameter, it indicates the expected length of the data to be read. As an output parameter, it indicates the actual length of the data that has been read. |
| key | Cache object that is being read. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_CACHE_BOOST_SUCCESS is returned. If the task of reading an object from the cache cannot be executed because the memory of the data object is released, FILE_CACHE_BOOST_ERROR_IO_CANCELED is returned. For other errors, please refer to FileCacheBoost_ErrCode. |
enum OpenFileBoost_AppState
Description
Enumerates the app statuses, indicating whether the app allows the system to recommend preloaded files.
Since: 5.0.3(15)
| Enumerated Value | Description |
|---|---|
| OPEN_FILE_BOOST_APP_STATE_ALLOW_PRELOAD = 0 | The app allows the file preloading recommended by the system. |
| OPEN_FILE_BOOST_APP_STATE_REJECT_PRELOAD = 1 | The app rejects the file preloading recommended by the system. |
| OPEN_FILE_BOOST_APP_STATE_FOREVER_REJECT_PRELOAD = 2 | The app permanently rejects the file preloading recommended by the system during this registration. |
| OPEN_FILE_BOOST_APP_STATE_EXCEL_TRANSACTION = 3 | The app is executing an exclusive task related to Excel files. Since: 26.0.0 |
enum OpenFileBoost_CbErrCode
Description
Enumerates the error codes for the callback function HMS_OpenFileBoost_OnFilePreload. It is used by the app to return the callback function execution result to the system.
Since: 5.0.3(15)
| Enumerated Value | Description |
|---|---|
| OPEN_FILE_BOOST_CALLBACK_SUCCESS = 0 | The callback function is successfully executed. |
| OPEN_FILE_BOOST_CALLBACK_FAILURE = 1017210000 | The callback function fails to be executed. |
enum OpenFileBoost_ErrCode
Description
Enumerates the error codes for file open boost.
Since: 5.0.3(15)
| Enumerated Value | Description |
|---|---|
| OPEN_FILE_BOOST_SUCCESS = 0 | Success. |
| OPEN_FILE_BOOST_PERMISSION_NOT_GRANTED = 201 | Permission not granted. |
| OPEN_FILE_BOOST_INVALID_PARAM = 401 | Invalid input parameter. |
| OPEN_FILE_BOOST_CAPABILITY_NOT_SUPPORTED = 801 | The device does not support the API. Since: 26.0.0 |
| OPEN_FILE_BOOST_INTERNAL_ERROR = 1017200001 | Internal error. |
| OPEN_FILE_BOOST_INSUFFICIENT_BUFFER = 1017200002 | Insufficient buffer. |
| OPEN_FILE_BOOST_SERVICE_UNAVAILABLE = 1017200003 | Service unavailable. |
| OPEN_FILE_BOOST_NO_MEMORY = 1017200004 | Insufficient memory. |
enum FileScanBoost_CbErrCode
Description
Enumerates specific error codes for file scanning callbacks.
Since: 26.0.0
| Enumerated Value | Description |
|---|---|
| FILE_SCAN_BOOST_CALLBACK_SUCCESS = 0 | Successful callback. |
| FILE_SCAN_BOOST_CALLBACK_ERROR_INTERNAL = 1017240001 | Internal callback error. |
| FILE_SCAN_BOOST_CALLBACK_ERROR_FORMAT_NOT_SUPPORTED = 1017240002 | File type not supported. |
enum FileScanBoost_ErrCode
Description
Enumerates all error codes returned by the file scanning boost function.
Since: 26.0.0
| Enumerated Value | Description |
|---|---|
| FILE_SCAN_BOOST_SUCCESS = 0 | Operation successful. |
| FILE_SCAN_BOOST_ERROR_PERMISSION_NOT_GRANTED = 201 | The file preloading permission is not granted. |
| FILE_SCAN_BOOST_ERROR_INVALID_PARAM = 401 | The provided parameters are invalid. |
| FILE_SCAN_BOOST_ERROR_CAPABILITY_NOT_SUPPORTED = 801 | The device does not support the API. |
| FILE_SCAN_BOOST_ERROR_INTERNAL = 1017230001 | Internal system error. |
| FILE_SCAN_BOOST_ERROR_NOT_REGISTERED = 1017230002 | The scanning capability callback is not registered. |
| FILE_SCAN_BOOST_ERROR_ALREADY_REGISTERED = 1017230003 | The scanning capability callback has been registered. |
| FILE_SCAN_BOOST_ERROR_SERVICE_UNAVAILABLE = 1017230004 | Service unavailable. |
| FILE_SCAN_BOOST_ERROR_FORMAT_NOT_SUPPORTED = 1017230005 | The file format is not supported. |
enum FileScanBoost_ScanState
Description
Enumerates the scanning statuses after file scanning, including successful completion, scanning process error, and file scanning error.
Since: 26.0.0
| Enumerated Value | Description |
|---|---|
| FILE_SCAN_BOOST_SCAN_STATE_SUCCESS = 0 | Scanning successful. |
| FILE_SCAN_BOOST_SCAN_STATE_PROCESS_ERROR = 1 | An error occurred during scanning. |
| FILE_SCAN_BOOST_SCAN_STATE_FILE_ERROR = 2 | The file cannot be preloaded. |
enum FileCacheBoost_CbErrCode
Description
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.
Since: 6.1.0(23)
| Enumerated Value | Description |
|---|---|
| FILE_CACHE_BOOST_CALLBACK_SUCCESS = 0 | The callback function is successfully executed. |
| FILE_CACHE_BOOST_CALLBACK_FAILURE = 1017221001 | The callback function fails to be executed. |
| FILE_CACHE_BOOST_CALLBACK_IO_CANCELED = 1017221002 | I/O cancellation error. |
enum FileCacheBoost_ErrCode
Description
Enumerates the error codes for file cache boost.
Since: 6.1.0(23)
| Enumerated Value | Description |
|---|---|
| FILE_CACHE_BOOST_SUCCESS = 0 | Success. |
| FILE_CACHE_BOOST_ERROR_INVALID_PARAM = 401 | Invalid input parameter. |
| FILE_CACHE_BOOST_ERROR_NOT_SUPPORTED = 801 | The device does not support the API. |
| FILE_CACHE_BOOST_ERROR_NOMEM = 1017220001 | Insufficient memory. |
| FILE_CACHE_BOOST_ERROR_INTERNAL_ERROR = 1017220002 | Internal error. |
| FILE_CACHE_BOOST_ERROR_KEY_NOT_FOUND = 1017220003 | The cache key does not exist. |
| FILE_CACHE_BOOST_ERROR_KEY_EXIST = 1017220004 | The cache key already exists. |
| FILE_CACHE_BOOST_ERROR_NOT_DIR = 1017220005 | Path initialization error. |
| FILE_CACHE_BOOST_ERROR_IO = 1017220006 | I/O read/write error. |
| FILE_CACHE_BOOST_ERROR_IO_CANCELED = 1017220007 | I/O canceled. |
| FILE_CACHE_BOOST_ERROR_NOT_INITIALIZED = 1017220008 | Not initialized. |
| FILE_CACHE_BOOST_ERROR_EXCEED_LIMIT = 1017220009 | The size of a single cache exceeds the upper limit. |
| FILE_CACHE_BOOST_ERROR_IO_CANCEL_FAILED = 1017220010 | I/O cancellation failed. |
bool HMS_Preview_FileBoost_IsSupported (void)
Description
Checks whether the current device supports file open boost. You are advised to use this API to check whether the device supports file open boost. After confirming that the device supports this function, you can use other file open boost APIs, such as HMS_OpenFileBoost_RegisterFilePreload and HMS_Preview_FileScanBoost_RegisterFileScan.
Since: 26.0.0
Returns:
If the current device supports file open boost, true is returned. Otherwise, false is returned.
OpenFileBoost_ErrCode HMS_OpenFileBoost_GetFdFromPreloadFileInfo (void * fileInfo, int32_t * fd)
Description
Obtains the file descriptor information. For details about the example, please refer to File Open Boost (C/C++).
Since: 5.0.3(15)
Parameters:
| Name | Description |
|---|---|
| fileInfo | Information about the preloaded file recommended by the system to the app. |
| fd | File descriptor information of the preloaded file. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the execution is successful, OPEN_FILE_BOOST_SUCCESS is returned. If the execution fails, the corresponding error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_OpenFileBoost_GetSandboxPathFromPreloadFileInfo (void * fileInfo, char * sandboxPath, int32_t pathLen)
Description
Obtains the sandbox path information. For details about the example, please refer to File Open Boost (C/C++).
Since: 5.0.3(15)
Parameters:
| Name | Description |
|---|---|
| fileInfo | Information about the preloaded file recommended by the system to the app. |
| sandboxPath | Information about the sandbox path of the preloaded file. The app should pass a pointer to a valid memory region, into which the system fills the sandbox path information. |
| pathLen | Length of the memory area used to fill in the sandbox path. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the execution is successful, OPEN_FILE_BOOST_SUCCESS is returned. If the input memory buffer is too small, the system returns OPEN_FILE_BOOST_INSUFFICIENT_BUFFER. For details about other errors, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_OpenFileBoost_NotifyPreloadHit (int32_t fd, char * sandboxPath, int32_t pathLen)
Description
Called to notify the system of the preloading hit when a user opens a preloaded file. This helps improve the prediction accuracy of file preloading. For details about the example, please refer to File Open Boost (C/C++).
Since: 5.0.3(15)
Parameters:
| Name | Description |
|---|---|
| fd | File descriptor information of the hit file. |
| sandboxPath | Sandbox path of the hit file. |
| pathLen | Length of the sandbox path. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the execution is successful, OPEN_FILE_BOOST_SUCCESS is returned. If the execution fails, the corresponding error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_OpenFileBoost_RegisterFilePreload (HMS_OpenFileBoost_QueryAppState queryAppState, HMS_OpenFileBoost_OnFilePreload filePreload, HMS_OpenFileBoost_OnFilePreload cancelFilePreload)
Description
Called to register a file preloading callback with the system.
When predicting the file that the user may open, the system first calls queryAppState to query whether the preloading file can be recommended. If the app returns a message indicating that the recommendation is allowed through queryAppState, the system calls filePreload to recommend a file for the app to preload.
In some specific cases, for example, the available memory of the system is insufficient, other files are more likely to be opened by the user, or other conditions that are not suitable for the file to remain in the preloading state occur, the system calls cancelFilePreload to cancel the preloading of some files. For details about the example, please refer to File Open Boost (C/C++).
Since: 5.0.3(15)
Parameters:
| Name | Description |
|---|---|
| queryAppState | Callback used for querying the app status. Before the preloading notification is sent, the callback function is called to query whether the preloading file can be recommended. |
| filePreload | Callback used for file preloading. The system predicts the files that may be opened by users and notifies the caller through this callback function. |
| cancelFilePreload | Callback used for canceling file preloading. For example, when the available system memory is insufficient, the system notifies the caller of canceling file preloading. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the execution is successful, OPEN_FILE_BOOST_SUCCESS is returned. If the execution fails, the corresponding error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_OpenFileBoost_UnregisterFilePreload (void)
Description
Unregisters the preloading callback. For details about the example, please refer to File Open Boost (C/C++).
Since: 5.0.3(15)
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the execution is successful, OPEN_FILE_BOOST_SUCCESS is returned. If the execution fails, the corresponding error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_RegisterFileScan (HMS_Preview_FileScanBoost_OnFileScan fileScanCb, FileScanBoost_ScanOption *option)
Description
Registers a callback for multiple file types using extension-based filtering. Do not re-register before the previous registration is deregistered. Duplicate registrations will return the error code FILESCANBOOST_ERROR_ALREADY_REGISTERED, and only the information from the initial registration will take effect. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| fileScanCb | Callback to register. |
| option | Pointer to the instance of the scan options that support the file type. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ReportScanResult (const char *path, uint32_t pathLen, FileScanBoost_ScanResult *result)
Description
Reports the file scanning result after the scanning is complete. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| path | Path of the file to be scanned. |
| pathLen | Length of the file path. For the maximum path length, it is set to PATH_MAX. |
| result | Pointer to the instance of the scanning result that contains the status and metrics. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanOptionAddSupportFile (FileScanBoost_ScanOption *option, const char *suffix, uint32_t suffixLen)
Description
Adds supported file types to the scanning option parameters of the scanning API registration. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| option | Pointer to the scanning option instance. |
| suffix | File name extension, for example, XLSX. |
| suffixLen | Length of the file name extension. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanOptionCreate (FileScanBoost_ScanOption **outOption)
Description
Creates a FileScanBoost_ScanOption instance. After using the instance, the app must call HMS_Preview_FileScanBoost_ScanOptionDestroy to free the instance. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| outOption | Pointer to the created option instance. For details, please refer to FileScanBoost_ScanOption. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
void HMS_Preview_FileScanBoost_ScanOptionDestroy (FileScanBoost_ScanOption *option)
Description
Destroys a FileScanBoost_ScanOption instance. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| option | Pointer to the option instance to be destroyed. For details, please refer to FileScanBoost_ScanOption. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanResultCreate (FileScanBoost_ScanResult **outResult)
Description
Creates a FileScanBoost_ScanResult instance. After using the instance, the app must call HMS_Preview_FileScanBoost_ScanResultDestroy to free the instance. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| outResult | Pointer to the created result instance. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
void HMS_Preview_FileScanBoost_ScanResultDestroy (FileScanBoost_ScanResult *result)
Description
Destroys a FileScanBoost_ScanResult instance. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| result | Pointer to the result instance to be destroyed. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanResultSetMaxAtomicTime (FileScanBoost_ScanResult *result, int64_t maxAtomicTime)
Description
Sets the maximum atomic time in the file scanning result. The unit is ms. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| result | Pointer to the scanning result instance. |
| maxAtomicTime | Maximum atomic time for scanning the file, in milliseconds. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanResultSetMemSize (FileScanBoost_ScanResult *result, int64_t memSize)
Description
Sets the memory size in the file scanning result. The unit is MB. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| result | Pointer to the scanning result instance. |
| memSize | Memory consumed by scanning the file, in MB. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_ScanResultSetState (FileScanBoost_ScanResult *result, FileScanBoost_ScanState state)
Description
Sets the scanning status in the result. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| result | Pointer to the scanning result instance. |
| state | Scanning completion status. For details about the scanning status, please refer to FileScanBoost_ScanState. |
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
FileScanBoost_ErrCode HMS_Preview_FileScanBoost_UnregisterFileScan (void)
Description
Unregisters the registered file scanning callback. After file scanning is deregistered, all scanning tasks of the app that have not reported scanning results become invalid. In addition, before initiating deregistration, the app needs to clear unfinished scanning tasks. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Returns:
| Type | Description |
|---|---|
| FileScanBoost_ErrCode | Function execution result. If the function is executed successfully, FILE_SCAN_BOOST_SUCCESS is returned. If the function fails to be executed, an error code is returned. For details, please refer to FileScanBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_FileOperationInfoCreate (const char *path, uint32_t pathLen, const char *operation, uint32_t operationLen, OpenFileBoost_FileOperationInfo **outFileOperationInfo)
Description
Creates OpenFileBoost_FileOperationInfo. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| path | File path. |
| pathLen | Length of the file path. For the maximum length, it is set to PATH_MAX. |
| operation | File operation information. |
| operationLen | Length of the file operation information. For the maximum length, it is set to NAME_MAX. |
| outFileOperationInfo | Pointer used to receive the created OpenFileBoost_FileOperationInfo. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_FileOperationInfoDestroy (OpenFileBoost_FileOperationInfo *fileOperationInfo)
Description
Destroys OpenFileBoost_FileOperationInfo. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| fileOperationInfo | Pointer to OpenFileBoost_FileOperationInfo to be destroyed. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
bool HMS_Preview_OpenFileBoost_IsEnabled (void)
Description
Checks whether the file open boost function is available for the app. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Returns:
| Type | Description |
|---|---|
| bool | If the boost feature is available, true is returned. Otherwise, false is returned. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_NotifyFileOperation (OpenFileBoost_FileOperationInfo *fileOperationInfo)
Description
Called to notify the system of the file operation type when a user performs an operation on a file. This helps improve the prediction accuracy of file preloading.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| fileOperationInfo | File operation information sent by the app to the system. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_OptionsAddSupportFile (OpenFileBoost_Options *options, const OpenFileBoost_SupportFile *supportFile)
Description
Adds a list of file types that support preloading to OpenFileBoost_Options. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| options | Pointer to OpenFileBoost_Options. |
| supportFile | Pointer to OpenFileBoost_SupportFile to be added. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_OptionsCreate (OpenFileBoost_Options **outOptions)
Description
Creates an empty OpenFileBoost_Options and uses HMS_Preview_OpenFileBoost_OptionsAddSupportFile to add supported file types. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| outOptions | Pointer used to receive the created OpenFileBoost_Options. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_OptionsDestroy (OpenFileBoost_Options *options)
Description
Destroys OpenFileBoost_Options. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| options | Pointer to OpenFileBoost_Options to be destroyed. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_RegisterFilePreloadWithOption (HMS_OpenFileBoost_QueryAppState queryAppState, HMS_OpenFileBoost_OnFilePreload filePreload, HMS_OpenFileBoost_OnFilePreload cancelFilePreload, OpenFileBoost_Options *options)
Description
Registers a preload callback, which allows an app to pass file information that supports preloading. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| queryAppState | Callback used for querying the app status. Before the preloading notification is sent, the callback function is called to query whether the preloading file can be recommended. |
| filePreload | Callback used for file preloading. The system predicts the files that may be opened by users and notifies the app through this callback function. |
| cancelFilePreload | Callback used for canceling file preloading. For example, when the available system memory is insufficient, the system notifies the caller of canceling file preloading. |
| options | File configuration options supported for preloading, which are used to define the types of files that can be preloaded. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_SupportFileCreate (const char *suffix, uint32_t suffixLen, uint64_t lowerLimitKb, uint64_t upperLimitKb, OpenFileBoost_SupportFile **outSupportFile)
Description
Creates OpenFileBoost_SupportFile. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| suffix | File name extension. |
| suffixLen | Length of the file name extension. |
| lowerLimitKb | Minimum file size (in KB). |
| upperLimitKb | Maximum file size (in KB). |
| outSupportFile | Pointer used to receive the created OpenFileBoost_SupportFile. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
OpenFileBoost_ErrCode HMS_Preview_OpenFileBoost_SupportFileDestroy (OpenFileBoost_SupportFile *supportFile)
Description
Destroys OpenFileBoost_SupportFile. For details about the example, please refer to File Open Boost (C/C++).
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| supportFile | Pointer to OpenFileBoost_SupportFile to be destroyed. |
Returns:
| Type | Description |
|---|---|
| OpenFileBoost_ErrCode | Function execution result. If the function is executed successfully, OPEN_FILE_BOOST_SUCCESS is returned. If the function fails to be executed, a specific error code is returned. For details, please refer to OpenFileBoost_ErrCode. |
bool HMS_Preview_FileCacheBoost_IsSupported (void)
Description
Checks whether the current device supports file cache boost. You are advised to use this API to check whether the device supports file cache boost. After confirming that the device supports this function, you can use other file cache boost APIs, such as HMS_FileCacheBoost_Init.
Since: 26.0.0
Returns:
If the current device supports file cache boost, true is returned. Otherwise, false is returned.
FileCacheBoost_ErrCode HMS_FileCacheBoost_Init (const char * path, size_t pathLen, uint32_t cacheUpperLimitMb, const char * dbName, size_t dbNameLen)
Description
Initializes the cache path, cache capacity upper limit, and database name. This function is used to configure the path for storing cached files and the maximum cache capacity. When the system detects that the total cache capacity exceeds the configured upper limit, it will manage the capacity based on the cache eviction policy and delete the corresponding cache to free up space. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| path | Path for storing cached files. You only need to pass a relative path. The system will create a complete path. The passed path must be valid. |
| pathLen | Buffer length of the cache path. |
| cacheUpperLimitMb | Maximum cache capacity, in MB. If the cache usage exceeds the upper limit, the system will activate the cache eviction policy. If the cache capacity set by the user is greater than the default upper limit preset by the system, the system uses the default upper limit as the cache capacity upper limit. |
| dbName | Database file name, which is used for caching metadata management. 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. |
| dbNameLen | Buffer length of the database name. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. FILE_CACHE_BOOST_SUCCESS: The execution is successful. FILE_CACHE_BOOST_ERROR_NOT_DIR: The input path is invalid and cannot be created. FILE_CACHE_BOOST_ERROR_INVALID_PARAM: The input parameter is invalid. For other errors, please refer to FileCacheBoost_ErrCode. |
FileCacheBoost_ErrCode HMS_FileCacheBoost_AddObjectByKey (const uint8_t * key, size_t keyLen, const uint8_t * data, size_t dataLen, uint32_t weight)
Description
Creates and adds a cache object to the file cache. This function caches data to the file cache system based on the specified unique identifier (key) for fast access in the future.
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. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| key | Unique ID of a cache object. This value can typically be generated from a file's feature value, such as the SHA-256 or MD4 hash of an image. If the image content remains unchanged, the corresponding cache can be obtained upon a subsequent image opening. When the image content changes, the key must be updated accordingly, and the original cache content becomes invalid. |
| keyLen | Buffer length of the key. |
| data | Data to be cached. |
| dataLen | Buffer length of the cache data. |
| weight | Weight of a cache object, which reflects its importance or priority. If you want a cache object to be retained with a higher priority, you should assign it a higher weight. The value ranges from 0 to 10000. If the input value exceeds 10000, the system will set it to 10000. For example, you can pass the data decoding duration as the weight. When the cache space reaches its upper limit, the system will calculate the cache eviction sequence based on the weight. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. FILE_CACHE_BOOST_SUCCESS: The execution is successful. FILE_CACHE_BOOST_ERROR_KEY_EXIST: The key already exists. FILE_CACHE_BOOST_ERROR_IO: An I/O read/write error occurs. FILE_CACHE_BOOST_ERROR_IO_CANCELED: The task for obtaining the cache object cannot be executed because the memory cache of the data object is released. FILE_CACHE_BOOST_ERROR_NOT_INITIALIZED: Not initialized. FILE_CACHE_BOOST_ERROR_EXCEED_LIMIT: The size of the added cache exceeds the upper limit. FILE_CACHE_BOOST_ERROR_INVALID_PARAM: The input parameter is invalid. For other errors, please refer to FileCacheBoost_ErrCode. |
FileCacheBoost_ErrCode HMS_FileCacheBoost_GetObjectByKey (const uint8_t * key, size_t keyLen, uint8_t ** data, size_t * dataLen )
Description
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. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| key | Key of the cache object. |
| keyLen | Buffer length of the key. |
| data | Output parameter, which indicates the content of the cache object. Ensure that the input parameter is not empty. |
| dataLen | Length of the cache object content. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. FILE_CACHE_BOOST_SUCCESS: The execution is successful. FILE_CACHE_BOOST_ERROR_KEY_NOT_FOUND: The key does not exist. FILE_CACHE_BOOST_ERROR_IO: An I/O read/write error occurs. FILE_CACHE_BOOST_ERROR_NOT_INITIALIZED: Not initialized. FILE_CACHE_BOOST_ERROR_IO_CANCELED: The task for obtaining the cache object cannot be executed because the memory cache of the data object is released. FILE_CACHE_BOOST_ERROR_INVALID_PARAM: The input parameter is invalid. For other errors, please refer to FileCacheBoost_ErrCode. |
void HMS_FileCacheBoost_FreeObject (uint8_t * data)
Description
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. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| data | Memory data to be released. |
FileCacheBoost_ErrCode HMS_FileCacheBoost_AddSerialObjectByKey (const uint8_t * key, size_t keyLen, SerializeFunc func, const void * object, uint32_t weight )
Description
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. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| key | Key of the cache object. |
| keyLen | Length of the key. |
| func | Serialization function implemented by you to serialize complex data. |
| object | Complex type object to be cached. |
| weight | Weight of a cache object, which reflects its importance or priority. The value ranges from 0 to 10000. If the input value exceeds 10000, the system will set it to 10000. For example, you can pass the data decoding duration as the weight. When the cache space reaches its upper limit, the system will calculate the cache eviction sequence based on the weight. If you want a cache object to be retained with a higher priority, you should assign it a higher weight. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. FILE_CACHE_BOOST_SUCCESS: The execution is successful. FILE_CACHE_BOOST_ERROR_KEY_EXIST: The key already exists. FILE_CACHE_BOOST_ERROR_IO: An I/O read/write error occurs. FILE_CACHE_BOOST_ERROR_IO_CANCELED: The task for obtaining the cache object cannot be executed because the memory cache of the data object is released. FILE_CACHE_BOOST_ERROR_NOT_INITIALIZED: Not initialized. FILE_CACHE_BOOST_ERROR_EXCEED_LIMIT: The size of the added cache exceeds the upper limit. FILE_CACHE_BOOST_ERROR_INVALID_PARAM: The input parameter is invalid. For other errors, please refer to FileCacheBoost_ErrCode. |
FileCacheBoost_ErrCode HMS_FileCacheBoost_GetSerialObjectByKey (const uint8_t * key, size_t keyLen, DeserializeFunc func, void ** object )
Description
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. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| key | Key of the cache object. |
| keyLen | Buffer length of the key. |
| func | Deserialization function implemented by you to restore serialized data to the original object. |
| object | Output parameter, which indicates the content of the cache object. Ensure that the input parameter is not empty. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. FILE_CACHE_BOOST_SUCCESS: The execution is successful. FILE_CACHE_BOOST_ERROR_KEY_NOT_FOUND: The key does not exist. FILE_CACHE_BOOST_ERROR_IO: An I/O read/write error occurs. FILE_CACHE_BOOST_ERROR_NOT_INITIALIZED: Not initialized. FILE_CACHE_BOOST_ERROR_IO_CANCELED: The task for obtaining the cache object cannot be executed because the memory cache of the data object is released. FILE_CACHE_BOOST_ERROR_INVALID_PARAM: The input parameter is invalid. For other errors, please refer to FileCacheBoost_ErrCode. |
FileCacheBoost_ErrCode HMS_FileCacheBoost_CancelOngoingIOByKey (const uint8_t * key, size_t keyLen )
Description
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.
If the function returns FILE_CACHE_BOOST_SUCCESS, you can immediately release the data object. If the function returns FILE_CACHE_BOOST_ERROR_IO_CANCEL_FAILED, no key is being executed and needs to be canceled. In this case, you need to ensure that the action corresponding to the key has been completed or does not need to be executed before releasing the data object.
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. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| key | Key of the cache object. |
| keyLen | Buffer length of the key. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. FILE_CACHE_BOOST_SUCCESS: The cache is complete and the I/O cancellation is successful. You can immediately release the data object. FILE_CACHE_BOOST_ERROR_IO_CANCEL_FAILED: The I/O cancellation fails, indicating that no key is being executed and needs to be canceled. You need to ensure that the action corresponding to the key has been completed or does not need to be executed before releasing the data object. FILE_CACHE_BOOST_ERROR_INVALID_PARAM: The input parameter is invalid. For other errors, please refer to FileCacheBoost_ErrCode. |
FileCacheBoost_ErrCode HMS_FileCacheBoost_RemoveObjectByKey (const uint8_t * key, size_t keyLen )
Description
Deletes a cache object based on the specified key. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Parameters:
| Name | Description |
|---|---|
| key | Key of the cache object. |
| keyLen | Buffer length of the key. |
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. FILE_CACHE_BOOST_SUCCESS: The execution is successful. FILE_CACHE_BOOST_ERROR_KEY_NOT_FOUND: The key does not exist. FILE_CACHE_BOOST_ERROR_NOT_INITIALIZED: Not initialized. FILE_CACHE_BOOST_ERROR_INVALID_PARAM: The input parameter is invalid. For other errors, please refer to FileCacheBoost_ErrCode. |
FileCacheBoost_ErrCode HMS_FileCacheBoost_ClearAllCache (void )
Description
Clears all cache objects. This function is used to release all cache objects created by HMS_FileCacheBoost_AddObjectByKey and HMS_FileCacheBoost_AddSerialObjectByKey. For details about the example, please refer to File Cache Boost (C/C++).
Since: 6.1.0(23)
Returns:
| Type | Description |
|---|---|
| FileCacheBoost_ErrCode | Function execution result. FILE_CACHE_BOOST_SUCCESS: The execution is successful. FILE_CACHE_BOOST_ERROR_NOT_INITIALIZED: Not initialized. For other errors, please refer to FileCacheBoost_ErrCode. |