1 /*
2  * Copyright (c) 2023-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_SESSION_RESTORE_ASYNC_H
17 #define OHOS_FILEMGMT_BACKUP_B_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 BSessionRestoreAsync : public std::enable_shared_from_this<BSessionRestoreAsync> {
33 public:
34     struct Callbacks {
35         std::function<void(const BFileInfo &, 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         std::function<void(const std::string, const std::string)> onProcess; // 上报备份恢复过程中的进度和异常
43     };
44 
45     struct AppendBundleInfo {
46         UniqueFd remoteCap;                       // 已打开的保存远端设备能力的Json文件
47         std::vector<BundleName> bundlesToRestore; // 需要恢复的应用名称列表
48         RestoreTypeEnum restoreType; // 待恢复类型(例如升级服务数据迁移就绪无需进行数据传输)
49         int32_t userId;              // 用户ID
50     };
51 
52 public:
53     /**
54      * @brief 获取一个用于控制恢复流程的会话
55      *
56      * @param callbacks 注册的回调函数
57      * @return std::unique_ptr<BRestoreSession> 指向BRestoreSession的智能指针。失败时为空指针
58      */
59     static std::shared_ptr<BSessionRestoreAsync> Init(Callbacks callbacks);
60 
61     /**
62      * @brief 通知备份服务文件内容已就绪
63      *
64      * @param fileInfo 文件描述信息
65      * @return ErrCode 规范错误码
66      * @see GetFileHandle
67      */
68     ErrCode PublishFile(BFileInfo fileInfo);
69 
70     /**
71      * @brief 请求恢复流程所需的真实文件
72      *
73      * @param bundleName 应用名称
74      * @param fileName   文件名称
75      */
76     ErrCode GetFileHandle(const std::string &bundleName, const std::string &fileName);
77 
78     /**
79      * @brief 用于追加待恢复应用
80      *
81      * @param remoteCap 已打开的保存远端设备能力的Json文件。可使用GetLocalCapabilities方法获取
82      * @param bundlesToRestore 待恢复的应用清单
83      * @param detailInfos bundle对应的单双映射的json串
84      * @param userId 用户ID
85      * @return ErrCode 规范错误码
86      */
87     ErrCode AppendBundles(UniqueFd remoteCap,
88                           std::vector<BundleName> bundlesToRestore,
89                           std::vector<std::string> detailInfos,
90                           RestoreTypeEnum restoreType = RestoreTypeEnum::RESTORE_DATA_WAIT_SEND,
91                           int32_t userId = DEFAULT_INVAL_VALUE);
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:
BSessionRestoreAsync(Callbacks callbacks)113     explicit BSessionRestoreAsync(Callbacks callbacks) : callbacks_(callbacks) {};
114     ~BSessionRestoreAsync();
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_SESSION_RESTORE_ASYNC_H