1 //
2 // Copyright (C) 2016 The Android Open Source Project
3 //
4 // Licensed under the Apache License, Version 2.0 (the "License");
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 //      http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16 
17 #ifndef UPDATE_ENGINE_SERVICE_DELEGATE_ANDROID_INTERFACE_H_
18 #define UPDATE_ENGINE_SERVICE_DELEGATE_ANDROID_INTERFACE_H_
19 
20 #include <inttypes.h>
21 
22 #include <memory>
23 #include <string>
24 #include <vector>
25 
26 #include <brillo/errors/error.h>
27 
28 namespace chromeos_update_engine {
29 
30 // See ServiceDelegateAndroidInterface.CleanupSuccessfulUpdate
31 // Wraps a IUpdateEngineCallback binder object used specifically for
32 // CleanupSuccessfulUpdate.
33 class CleanupSuccessfulUpdateCallbackInterface {
34  public:
35   virtual ~CleanupSuccessfulUpdateCallbackInterface() {}
36   virtual void OnCleanupProgressUpdate(double progress) = 0;
37   virtual void OnCleanupComplete(int32_t error_code) = 0;
38   // Call RegisterForDeathNotifications on the internal binder object.
39   virtual void RegisterForDeathNotifications(base::Closure unbind) = 0;
40 };
41 
42 // This class defines the interface exposed by the Android version of the
43 // daemon service. This interface only includes the method calls that such
44 // daemon exposes. For asynchronous events initiated by a class implementing
45 // this interface see the ServiceObserverInterface class.
46 class ServiceDelegateAndroidInterface {
47  public:
48   virtual ~ServiceDelegateAndroidInterface() = default;
49 
50   // Start an update attempt to download an apply the provided |payload_url| if
51   // no other update is running. The extra |key_value_pair_headers| will be
52   // included when fetching the payload. Returns whether the update was started
53   // successfully, which means that no other update was running and the passed
54   // parameters were correct, but not necessarily that the update finished
55   // correctly.
56   virtual bool ApplyPayload(
57       const std::string& payload_url,
58       int64_t payload_offset,
59       int64_t payload_size,
60       const std::vector<std::string>& key_value_pair_headers,
61       brillo::ErrorPtr* error) = 0;
62 
63   virtual bool ApplyPayload(
64       int fd,
65       int64_t payload_offset,
66       int64_t payload_size,
67       const std::vector<std::string>& key_value_pair_headers,
68       brillo::ErrorPtr* error) = 0;
69 
70   // Suspend an ongoing update. Returns true if there was an update ongoing and
71   // it was suspended. In case of failure, it returns false and sets |error|
72   // accordingly.
73   virtual bool SuspendUpdate(brillo::ErrorPtr* error) = 0;
74 
75   // Resumes an update suspended with SuspendUpdate(). The update can't be
76   // suspended after it finished and this method will fail in that case.
77   // Returns whether the resume operation was successful, which only implies
78   // that there was a suspended update. In case of error, returns false and sets
79   // |error| accordingly.
80   virtual bool ResumeUpdate(brillo::ErrorPtr* error) = 0;
81 
82   // Cancel the ongoing update. The update could be running or suspended, but it
83   // can't be canceled after it was done. In case of error, returns false and
84   // sets |error| accordingly.
85   virtual bool CancelUpdate(brillo::ErrorPtr* error) = 0;
86 
87   // Reset the already applied update back to an idle state. This method can
88   // only be called when no update attempt is going on, and it will reset the
89   // status back to idle, deleting the currently applied update if any. In case
90   // of error, returns false and sets |error| accordingly.
91   virtual bool ResetStatus(brillo::ErrorPtr* error) = 0;
92 
93   // Verifies whether a payload (delegated by the payload metadata) can be
94   // applied to the current device. Returns whether the payload is applicable.
95   // In case of error, returns false and sets |error| accordingly.
96   virtual bool VerifyPayloadApplicable(const std::string& metadata_filename,
97                                        brillo::ErrorPtr* error) = 0;
98 
99   // Allocates space for a payload.
100   // Returns 0 if space is successfully preallocated.
101   // Return non-zero if not enough space is not available; returned value is
102   // the total space required (in bytes) to be free on the device for this
103   // update to be applied, and |error| is unset.
104   // In case of error, returns 0, and sets |error| accordingly.
105   //
106   // This function may block for several minutes in the worst case.
107   virtual uint64_t AllocateSpaceForPayload(
108       const std::string& metadata_filename,
109       const std::vector<std::string>& key_value_pair_headers,
110       brillo::ErrorPtr* error) = 0;
111 
112   // Wait for merge to complete, then clean up merge after an update has been
113   // successful.
114   //
115   // This function returns immediately. Progress updates are provided in
116   // |callback|.
117   virtual void CleanupSuccessfulUpdate(
118       std::unique_ptr<CleanupSuccessfulUpdateCallbackInterface> callback,
119       brillo::ErrorPtr* error) = 0;
120 
121  protected:
122   ServiceDelegateAndroidInterface() = default;
123 };
124 
125 }  // namespace chromeos_update_engine
126 
127 #endif  // UPDATE_ENGINE_SERVICE_DELEGATE_ANDROID_INTERFACE_H_
128