1 /*
2  * Copyright (c) 2024 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef OHOS_FILEMGMT_BACKUP_B_INCREMENTAL_SESSION_RESTORE_ASYNC_H
17 #define OHOS_FILEMGMT_BACKUP_B_INCREMENTAL_SESSION_RESTORE_ASYNC_H
18 
19 #include <functional>
20 #include <memory>
21 #include <mutex>
22 #include <queue>
23 #include <vector>
24 
25 #include "b_file_info.h"
26 #include "errors.h"
27 #include "i_service.h"
28 #include "svc_death_recipient.h"
29 #include "unique_fd.h"
30 
31 namespace OHOS::FileManagement::Backup {
32 class BIncrementalSessionRestoreAsync : public std::enable_shared_from_this<BIncrementalSessionRestoreAsync> {
33 public:
34     struct Callbacks {
35         std::function<void(const BFileInfo &, UniqueFd, UniqueFd, ErrCode)> onFileReady; // 当备份服务有文件待发送时执行的回调
36         std::function<void(ErrCode, const BundleName)> onBundleStarted; // 当启动某个应用的恢复流程结束时执行的回调函数
37         std::function<void(ErrCode, const BundleName)>
38             onBundleFinished; // 当某个应用的恢复流程结束或意外中止时执行的回调函数
39         std::function<void(ErrCode)> onAllBundlesFinished; // 当整个恢复流程结束或意外中止时执行的回调函数
40         std::function<void(const std::string, const std::string)> onResultReport; // 某个应用恢复流程中自定义错误信息的上报的回调函数
41         std::function<void()> onBackupServiceDied;         // 当备份服务意外死亡时执行的回调函数
42     };
43 
44     struct AppendBundleInfo {
45         UniqueFd remoteCap;                       // 已打开的保存远端设备能力的Json文件
46         std::vector<BundleName> bundlesToRestore; // 需要恢复的应用名称列表
47         RestoreTypeEnum restoreType; // 待恢复类型(例如升级服务数据迁移就绪无需进行数据传输)
48         int32_t userId;              // 用户ID
49     };
50 
51 public:
52     /**
53      * @brief 获取一个用于控制恢复流程的会话
54      *
55      * @param callbacks 注册的回调函数
56      * @return std::unique_ptr<BRestoreSession> 指向BRestoreSession的智能指针。失败时为空指针
57      */
58     static std::shared_ptr<BIncrementalSessionRestoreAsync> Init(Callbacks callbacks);
59 
60     /**
61      * @brief 通知备份服务文件内容已就绪
62      *
63      * @param fileInfo 文件描述信息
64      * @return ErrCode 规范错误码
65      * @see GetFileHandle
66      */
67     ErrCode PublishFile(BFileInfo fileInfo);
68 
69     /**
70      * @brief 请求恢复流程所需的真实文件
71      *
72      * @param bundleName 应用名称
73      * @param fileName   文件名称
74      */
75     ErrCode GetFileHandle(const std::string &bundleName, const std::string &fileName);
76 
77     /**
78      * @brief 用于追加待恢复应用
79      *
80      * @param remoteCap 已打开的保存远端设备能力的Json文件。可使用GetLocalCapabilities方法获取
81      * @param bundlesToRestore 待恢复的应用清单
82      * @param detailInfos bundle的单双映射关系json串
83      * @param userId 用户ID
84      * @return ErrCode 规范错误码
85      */
86     ErrCode AppendBundles(UniqueFd remoteCap,
87                           std::vector<BundleName> bundlesToRestore,
88                           std::vector<std::string> detailInfos,
89                           RestoreTypeEnum restoreType = RestoreTypeEnum::RESTORE_DATA_WAIT_SEND,
90                           int32_t userId = DEFAULT_INVAL_VALUE);
91 
92     /**
93      * @brief 用于追加待恢复应用
94      *
95      * @param remoteCap 已打开的保存远端设备能力的Json文件。可使用GetLocalCapabilities方法获取
96      * @param bundlesToRestore 待恢复的应用清单
97      * @param userId 用户ID
98      * @return ErrCode 规范错误码
99      */
100     ErrCode AppendBundles(UniqueFd remoteCap,
101                           std::vector<BundleName> bundlesToRestore,
102                           RestoreTypeEnum restoreType = RestoreTypeEnum::RESTORE_DATA_WAIT_SEND,
103                           int32_t userId = DEFAULT_INVAL_VALUE);
104 
105     /**
106      * @brief 用于结束服务
107      *
108      * @return ErrCode 规范错误码
109      */
110     ErrCode Release();
111 
112 public:
BIncrementalSessionRestoreAsync(Callbacks callbacks)113     explicit BIncrementalSessionRestoreAsync(Callbacks callbacks) : callbacks_(callbacks) {};
114     ~BIncrementalSessionRestoreAsync();
115 
116 private:
117     /** @brief 注册备份服务意外死亡时执行的回调函数 */
118     void OnBackupServiceDied();
119 
120     /**
121      * @brief 注册备份服务意外死亡时执行的回调函数
122      *
123      * @param functor 回调函数
124      */
125     void RegisterBackupServiceDied(std::function<void()> functor);
126 
127 private:
128     sptr<SvcDeathRecipient> deathRecipient_;
129     Callbacks callbacks_;
130     std::atomic<bool> isAppend_ {false};
131     std::mutex mutex_;
132     std::queue<AppendBundleInfo> workList_;
133 };
134 } // namespace OHOS::FileManagement::Backup
135 
136 #endif // OHOS_FILEMGMT_BACKUP_B_INCREMENTAL_SESSION_RESTORE_ASYNC_H