文件打开加速（C/C++）
=============

从5.0.3(15)版本开始，新增文件打开加速功能。提供注册和取消注册接口，应用可以注册一系列回调，文件打开加速服务通过调用回调接口向应用推荐文件进行预加载动作。

从26.0.0版本开始，文件打开加速过程中，新增支持应用扫描文件并同步结果给加速服务，加速服务判断该文件是否具备加速条件。

从26.0.0版本起，新增动态参数配置功能，允许应用根据自身需求定制文件预加载策略（如文件后缀、大小范围）。同时，系统还提供文件打开加速服务可用性查询和文件操作事件上报功能，有助于提升预加载的准确性。

#### 接口说明

具体API说明详见[文件打开加速接口文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/openfileboost_preview)。

**表1** 文件预加载接口介绍（C API）

| 接口名 | 描述 |
| :-- | :-- |
| 
OpenFileBoost\_ErrCode HMS\_OpenFileBoost\_RegisterFilePreload(

HMS\_OpenFileBoost\_QueryAppState queryAppState,

HMS\_OpenFileBoost\_OnFilePreload filePreload,

HMS\_OpenFileBoost\_OnFilePreload cancelFilePreload);

 | 向系统注册文件预加载回调。 |
| typedef OpenFileBoost\_AppState (\*HMS\_OpenFileBoost\_QueryAppState)(void); | 系统查询APP状态的回调函数定义。 |
| typedef OpenFileBoost\_CbErrCode (\*HMS\_OpenFileBoost\_OnFilePreload)(void\* fileInfo); | 系统向应用推荐或取消推荐预加载文件的回调函数定义。 |
| 

OpenFileBoost\_ErrCode HMS\_OpenFileBoost\_GetFdFromPreloadFileInfo(

void\* fileInfo, int32\_t\* fd);

 | 在向应用推荐文件进行预加载或取消预加载的回调上下文中，应用通过调用该接口获取文件描述符信息。 |
| 

OpenFileBoost\_ErrCode HMS\_OpenFileBoost\_GetSandboxPathFromPreloadFileInfo(

void\* fileInfo, char\* sandboxPath, int32\_t pathLen);

 | 在向应用推荐文件进行预加载或取消预加载的回调上下文中，应用通过调用该接口获取文件沙箱路径信息。 |
| OpenFileBoost\_ErrCode HMS\_OpenFileBoost\_UnregisterFilePreload(void); | 取消注册预加载回调。 |
| 

OpenFileBoost\_ErrCode HMS\_OpenFileBoost\_NotifyPreloadHit(

int32\_t fd, char\* sandboxPath, int32\_t pathLen);

 | 当用户打开预加载文件时，应用调用该接口通知系统预加载命中，这将有助于提高预加载文件预测的准确性。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_ScanOptionCreate (FileScanBoost\_ScanOption \*\*outOption) | 创建FileScanBoost\_ScanOption实例。 |
| void HMS\_Preview\_FileScanBoost\_ScanOptionDestroy (FileScanBoost\_ScanOption \*option) | 销毁FileScanBoost\_ScanOption实例。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_ScanOptionAddSupportFile (FileScanBoost\_ScanOption \*option, const char \*suffix, uint32\_t suffixLen) | 向扫描选项添加支持的文件类型。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_ScanResultCreate (FileScanBoost\_ScanResult \*\*outResult) | 创建FileScanBoost\_ScanResult实例。 |
| void HMS\_Preview\_FileScanBoost\_ScanResultDestroy (FileScanBoost\_ScanResult \*result) | 销毁FileScanBoost\_ScanResult实例。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_ScanResultSetState (FileScanBoost\_ScanResult \*result, FileScanBoost\_ScanState state) | 在结果中设置扫描状态。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_ScanResultSetMaxAtomicTime (FileScanBoost\_ScanResult \*result, int64\_t maxAtomicTime) | 在结果中设置最大原子时间。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_ScanResultSetMemSize (FileScanBoost\_ScanResult \*result, int64\_t memSize) | 在结果中设置内存大小。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_RegisterFileScan (HMS\_Preview\_FileScanBoost\_OnFileScan fileScanCb, FileScanBoost\_ScanOption \*option) | 使用扩展名过滤方式注册多文件类型的回调函数。 在上一次注册结果注销之前，请勿重复注册。 重复注册将返回错误码FILE\_SCAN\_BOOST\_ERROR\_ALREADY\_REGISTERED， 且仅首次注册的信息生效。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_UnregisterFileScan (void) | 移除已注册的文件扫描回调函数。 |
| FileScanBoost\_ErrCode HMS\_Preview\_FileScanBoost\_ReportScanResult (const char \*path, uint32\_t pathLen, FileScanBoost\_ScanResult \*result) | 报告文件扫描操作的完成结果。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_SupportFileCreate (const char \*suffix, uint32\_t suffixLen, uint64\_t lowerLimitKb, uint64\_t upperLimitKb, OpenFileBoost\_SupportFile \*\*outSupportFile) | 创建OpenFileBoost\_SupportFile。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_SupportFileDestroy (OpenFileBoost\_SupportFile \*supportFile) | 销毁OpenFileBoost\_SupportFile。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_OptionsCreate (OpenFileBoost\_Options \*\*outOptions) | 创建一个空的OpenFileBoost\_Options。 使用HMS\_Preview\_OpenFileBoost\_OptionsAddSupportFile添加文件。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_OptionsAddSupportFile (OpenFileBoost\_Options \*options, const OpenFileBoost\_SupportFile \*supportFile) | 向OpenFileBoost\_Options添加支持预加载的文件类型。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_OptionsDestroy (OpenFileBoost\_Options \*options) | 销毁OpenFileBoost\_Options。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_RegisterFilePreloadWithOption (HMS\_OpenFileBoost\_QueryAppState queryAppState, HMS\_OpenFileBoost\_OnFilePreload filePreload, HMS\_OpenFileBoost\_OnFilePreload cancelFilePreload, OpenFileBoost\_Options \*options) | 注册预加载回调，允许应用传入支持预加载的文件信息。 |
| bool HMS\_Preview\_OpenFileBoost\_IsEnabled (void) | 查询应用加速特性是否使能。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_FileOperationInfoCreate (const char \*path, uint32\_t pathLen, const char \*operation, uint32\_t operationLen, OpenFileBoost\_FileOperationInfo \*\*outFileOperationInfo) | 创建OpenFileBoost\_FileOperationInfo。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_FileOperationInfoDestroy (OpenFileBoost\_FileOperationInfo \*fileOperationInfo) | 销毁OpenFileBoost\_FileOperationInfo。 |
| OpenFileBoost\_ErrCode HMS\_Preview\_OpenFileBoost\_NotifyFileOperation (OpenFileBoost\_FileOperationInfo \*fileOperationInfo) | 当用户对文件进行操作时，app调用该接口通知系统文件操作类型，这将有助于提高预加载文件预测的准确性。 |

#### 开发准备

需要先通过[Syscap](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/syscap#使用caniuse判断syscap是否可调用)查询您的目标设备是否支持SystemCapability.PCService.OpenFileBoost系统能力，当前仅在PC/2in1设备上支持该能力。

#### 开发步骤

1.  申请文件打开加速服务的对应权限，在module.json5文件中添加文件预加载权限。注意ohos.permission.PRELOAD\_FILE为受限权限，具体可参考[申请使用受限权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/declare-permissions-in-acl) 。
    
    "requestPermissions":\[
      {
        "name": "ohos.permission.PRELOAD\_FILE"
      }
    \]
    
2.  添加对应的头文件。
    
    #include "PreviewKit/open\_file\_boost.h"
    
3.  编写CMakeLists.txt，新增对文件打开加速功能的依赖。
    
    target\_link\_libraries(entry PUBLIC
        libopen\_file\_boost.so
    )
    
4.  注册文件预加载回调，注册后系统在条件符合时调用回调向应用推荐文件。
    
    OpenFileBoost\_ErrCode ret = HMS\_OpenFileBoost\_RegisterFilePreload(AppQueryAppStateCb,
        AppOnFilePreload, AppCancelFilePreload);
    if (ret != OPEN\_FILE\_BOOST\_SUCCESS){
        // 注册失败，用户可自定义错误处理
    }
    
5.  注册文件预加载回调，应用可传入支持预加载的文件信息，注册后系统在条件符合时调用回调向应用推荐文件。
    
    OpenFileBoost\_SupportFile\* supportFiles\[2\] = {nullptr};
    
    // 创建文件类型
    OpenFileBoost\_ErrCode ret = HMS\_Preview\_OpenFileBoost\_SupportFileCreate(".pptx", 5, 20 \* 1024,
        2 \* 1024 \* 1024, &supportFiles\[0\]);
    if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
    // 应用可自定义错误处理
    }
    
    ret = HMS\_Preview\_OpenFileBoost\_SupportFileCreate(".docx", 5, 5 \* 1024, 2 \* 1024 \* 1024, &supportFiles\[1\]);
    if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
    // 销毁之前的创建
        HMS\_Preview\_OpenFileBoost\_SupportFileDestroy(supportFiles\[0\]);
    }
    
    // 创建选项
    OpenFileBoost\_Options\* options = nullptr;
    ret = HMS\_Preview\_OpenFileBoost\_OptionsCreate(&options);
    if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
    
    }
    
    // 添加文件类型到选项
    ret = HMS\_Preview\_OpenFileBoost\_OptionsAddSupportFile(options, supportFiles\[0\]);
    if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
    
    }
    
    // 注册文件预加载回调，同时应用传递自己支持的文件后缀类型和文件大小上下限
    ret = HMS\_Preview\_OpenFileBoost\_RegisterFilePreloadWithOption(AppQueryAppStateCb,
            AppOnFilePreload, AppCancelFilePreload, options);
    if (ret != OPEN\_FILE\_BOOST\_SUCCESS){
        // 注册失败，应用可自定义错误处理
    }
    
6.  应用在当前回调上下文中同步解析预加载文件，或同步阻塞等待解析完毕后再返回，以便系统评估本次预加载文件的资源消耗。
    
    // 查询应用当前状态的回调函数，系统在向应用推荐文件前会先调用状态查询回调函数向应用查询当前是否适合推荐
    OpenFileBoost\_AppState AppQueryAppStateCb(void)
    {
        // 如果当前状态允许进行文件预加载则返回OPEN\_FILE\_BOOST\_APP\_STATE\_ALLOW\_PRELOAD，这里的CanPreload函数为代码示例，表示应用根据实际业务判断是否允许预加载
        if (CanPreload()) {
            return OPEN\_FILE\_BOOST\_APP\_STATE\_ALLOW\_PRELOAD;
        } else {
            return OPEN\_FILE\_BOOST\_APP\_STATE\_REJECT\_PRELOAD;
        }
    }
    
    // 文件预加载回调
    OpenFileBoost\_CbErrCode AppOnFilePreload(void\* fileInfo)
    {
        int32\_t fileDescriptor = 0;
        // 指针fileInfo仅在当前回调上下文有效，在回调中调用HMS\_OpenFileBoost\_GetFdFromPreloadFileInfo获取文件描述符
        OpenFileBoost\_ErrCode ret = HMS\_OpenFileBoost\_GetFdFromPreloadFileInfo(fileInfo, &fileDescriptor);
        if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
            return OPEN\_FILE\_BOOST\_CALLBACK\_FAILURE;
        }
        char sandboxPath\[MAX\_BUFFER\_LENGTH\] = {0};
        // 指针fileInfo仅在当前回调上下文有效，在回调中调用HMS\_OpenFileBoost\_GetSandboxPathFromPreloadFileInfo获取文件路径
        ret = HMS\_OpenFileBoost\_GetSandboxPathFromPreloadFileInfo(fileInfo, sandboxPath, MAX\_BUFFER\_LENGTH);
        if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
            return OPEN\_FILE\_BOOST\_CALLBACK\_FAILURE;
        }
        // 用户可保存文件描述符和文件路径，方便后续通知取消预加载时对文件取消预加载
        // 用户自定义具体的文件预加载逻辑
        return OPEN\_FILE\_BOOST\_CALLBACK\_SUCCESS;
    }
    
    // 取消预加载回调
    OpenFileBoost\_CbErrCode AppCancelFilePreload(void\* fileInfo)
    {
        // 同样的方法获取文件描述符和沙箱路径
        int32\_t fileDescriptor = 0;
        OpenFileBoost\_ErrCode ret = HMS\_OpenFileBoost\_GetFdFromPreloadFileInfo(fileInfo, &fileDescriptor);
        if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
            return OPEN\_FILE\_BOOST\_CALLBACK\_FAILURE;
        }
        char sandboxPath\[MAX\_BUFFER\_LENGTH\] = {0};
        ret = HMS\_OpenFileBoost\_GetSandboxPathFromPreloadFileInfo(fileInfo, sandboxPath, MAX\_BUFFER\_LENGTH);
        if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
            return OPEN\_FILE\_BOOST\_CALLBACK\_FAILURE;
        }
        // 用户自定义具体的取消文件预加载逻辑
        return OPEN\_FILE\_BOOST\_CALLBACK\_SUCCESS;
    }
    
7.  如果用户打开了已经预加载的文件，应用需要调用HMS\_OpenFileBoost\_NotifyPreloadHit通知系统，系统会更改文件的预加载状态。
    
    // 传入用户打开的已经预加载的文件描述符、文件路径和长度
    OpenFileBoost\_ErrCode ret = HMS\_OpenFileBoost\_NotifyPreloadHit(fileDescriptor, sandboxPath, pathLen);
    if (ret != OPEN\_FILE\_BOOST\_SUCCESS){
        // 通知失败，用户可自定义错误处理
    }
    
8.  应用不再需要收到回调，或者在退出流程中时，调用取消预加载接口。
    
    OpenFileBoost\_ErrCode ret = HMS\_OpenFileBoost\_UnregisterFilePreload();
    if (ret != OPEN\_FILE\_BOOST\_SUCCESS){
        // 取消注册失败，用户可自定义错误处理
    }
    
9.  应用向系统查询加速开关特性是否可用。
    
    bool switchInfo = HMS\_Preview\_OpenFileBoost\_IsEnabled();
    if (switchInfo) {
        // 加速特性可用，应用可处理加速相关业务逻辑
    } else {
        // 加速特性不可用，应用可处理自身相关业务逻辑
    }
    
10.  应用向系统传递用户对文件的操作信息。
     
     const char\* filePath = "/data/storage/el2/base/files/text.docx";
     const char\* operationType = "open";
     // 创建文件操作信息
     OpenFileBoost\_FileOperationInfo\* fileOpInfo = nullptr;
     
     OpenFileBoost\_ErrCode ret = HMS\_Preview\_OpenFileBoost\_FileOperationInfoCreate(
         filePath, static\_cast<uint32\_t>(strlen(filePath)),
         operationType, static\_cast<uint32\_t>(strlen(operationType)),
         &fileOpInfo);
     
     if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
         // 创建失败，应用可自定义错误处理
     }
     
     ret = HMS\_Preview\_OpenFileBoost\_NotifyFileOperation(fileOpInfo);
     if (ret != OPEN\_FILE\_BOOST\_SUCCESS) {
         // 传递失败，应用可自定义错误处理
     }
     
11.  注册文件扫描回调，确保系统在扫描文件时可以调用回调向应用通知扫描任务。
     
     // 创建扫描选项，添加应用支持的文件类型
     FileScanBoost\_ScanOption\* scanOption = nullptr;
     FileScanBoost\_ErrCode res = HMS\_Preview\_FileScanBoost\_ScanOptionCreate(&scanOption);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 应用可自定义错误处理
     }
     
     res = HMS\_Preview\_FileScanBoost\_ScanOptionAddSupportFile(scanOption, "xlsx", 4);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 应用可自定义错误处理
     }
     
     res = HMS\_Preview\_FileScanBoost\_ScanOptionAddSupportFile(scanOption, "xls", 3);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 应用可自定义错误处理
     }
     
     // 注册文件扫描回调
     res = HMS\_Preview\_FileScanBoost\_RegisterFileScan(AppOnFileScan, scanOption);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 注册失败，应用可自定义错误处理
     }
     
     // 扫描完成需销毁扫描选项
     HMS\_Preview\_FileScanBoost\_ScanOptionDestroy(scanOption);
     
     // 文件扫描回调函数，系统调用此回调发送扫描任务
     // 应用应在当前回调上下文中同步完成文件解析或同步阻塞等待解析完毕后再返回
     FileScanBoost\_CbErrCode AppOnFileScan(int32\_t fd, const char\* path, uint32\_t pathLen)
     {
         // 应用可在回调中实现具体文件解析逻辑
         // 返回FILE\_SCAN\_BOOST\_CALLBACK\_SUCCESS表示接受扫描任务
         // 返回其他值表示拒绝
         return FILE\_SCAN\_BOOST\_CALLBACK\_SUCCESS;
     }
     
12.  应用向系统传递扫描结果，确保文件扫描完成后，系统能收到文件扫描结果。
     
     const char\* filePath = "/data/storage/el2/base/files/text.xlsx";
     // 创建扫描结果
     FileScanBoost\_ScanResult\* scanResult = nullptr;
     res = HMS\_Preview\_FileScanBoost\_ScanResultCreate(&scanResult);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 应用可自定义错误处理
     }
     
     // 设置扫描状态为成功
     res = HMS\_Preview\_FileScanBoost\_ScanResultSetState(scanResult, FILE\_SCAN\_BOOST\_SCAN\_STATE\_SUCCESS);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 应用可自定义错误处理
     }
     
     // 设置最大原子耗时（单位：ms）
     res = HMS\_Preview\_FileScanBoost\_ScanResultSetMaxAtomicTime(scanResult, 1500);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 应用可自定义错误处理
     }
     
     // 设置内存占用（单位：MB）
     res = HMS\_Preview\_FileScanBoost\_ScanResultSetMemSize(scanResult, 3);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 应用可自定义错误处理
     }
     
     // 向系统报告扫描结果
     res = HMS\_Preview\_FileScanBoost\_ReportScanResult(
         filePath, static\_cast<uint32\_t>(strlen(filePath)), scanResult);
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 报告失败，应用可自定义错误处理
     }
     
     // 扫描完成需销毁扫描结果
     HMS\_Preview\_FileScanBoost\_ScanResultDestroy(scanResult);
     
     // 报告扫描失败的示例
     FileScanBoost\_ScanResult\* errorResult = nullptr;
     res = HMS\_Preview\_FileScanBoost\_ScanResultCreate(&errorResult);
     if (res == FILE\_SCAN\_BOOST\_SUCCESS) {
         // 设置扫描状态为处理错误
         HMS\_Preview\_FileScanBoost\_ScanResultSetState(errorResult, FILE\_SCAN\_BOOST\_SCAN\_STATE\_PROCESS\_ERROR);
         HMS\_Preview\_FileScanBoost\_ScanResultSetMaxAtomicTime(errorResult, 0);
         HMS\_Preview\_FileScanBoost\_ScanResultSetMemSize(errorResult, 0);
         
         // 报告扫描错误结果
         res = HMS\_Preview\_FileScanBoost\_ReportScanResult(
             filePath, static\_cast<uint32\_t>(strlen(filePath)), errorResult);
         if (ret == FILE\_SCAN\_BOOST\_SUCCESS) {
             // 报告成功
         }
         
         HMS\_Preview\_FileScanBoost\_ScanResultDestroy(errorResult);
     }
     
13.  应用注销文件扫描回调，确保应用将不再接收扫描任务通知。
     
     res = HMS\_Preview\_FileScanBoost\_UnregisterFileScan();
     if (res != FILE\_SCAN\_BOOST\_SUCCESS) {
         // 注销失败，应用可自定义错误处理
     }