1//
2// Copyright (C) 2012 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_PAYLOAD_STATE_INTERFACE_H_
18#define UPDATE_ENGINE_PAYLOAD_STATE_INTERFACE_H_
19
20#include <string>
21
22#include "update_engine/common/action_processor.h"
23#include "update_engine/common/constants.h"
24#include "update_engine/omaha_response.h"
25
26namespace chromeos_update_engine {
27
28// Describes the methods that need to be implemented by the PayloadState class.
29// This interface has been carved out to support mocking of the PayloadState
30// object.
31class PayloadStateInterface {
32 public:
33  virtual ~PayloadStateInterface() = default;
34
35  // Sets the internal payload state based on the given Omaha response. This
36  // response could be the same or different from the one for which we've stored
37  // the internal state. If it's different, then this method resets all the
38  // internal state corresponding to the old response. Since the Omaha response
39  // has a lot of fields that are not related to payload state, it uses only
40  // a subset of the fields in the Omaha response to compare equality.
41  virtual void SetResponse(const OmahaResponse& response) = 0;
42
43  // This method should be called whenever we have completed downloading all
44  // the bytes of a payload and have verified that its size and hash match the
45  // expected values. We use this notificaiton to increment the payload attempt
46  // number so that the throttle the next attempt to download the same payload
47  // (in case there's an error in subsequent steps such as post-install)
48  // appropriately.
49  virtual void DownloadComplete() = 0;
50
51  // This method should be called whenever we receive new bytes from the
52  // network for the current payload. We use this notification to reset the
53  // failure count for a given URL since receipt of some bytes means we are
54  // able to make forward progress with the current URL.
55  virtual void DownloadProgress(size_t count) = 0;
56
57  // This method should be called every time we resume an update attempt.
58  virtual void UpdateResumed() = 0;
59
60  // This method should be called every time we begin a new update. This method
61  // should not be called when we resume an update from the previously
62  // downloaded point. This is used to reset the metrics for each new update.
63  virtual void UpdateRestarted() = 0;
64
65  // This method should be called once after an update attempt succeeds. This
66  // is when the relevant UMA metrics that are tracked on a per-update-basis
67  // are uploaded to the UMA server.
68  virtual void UpdateSucceeded() = 0;
69
70  // This method should be called whenever an update attempt fails with the
71  // given error code. We use this notification to update the payload state
72  // depending on the type of the error that happened.
73  virtual void UpdateFailed(ErrorCode error) = 0;
74
75  // This method should be called whenever a succeeded update is canceled, and
76  // thus can only be called after UpdateSucceeded(). This is currently used
77  // only for manual testing using the update_engine_client.
78  virtual void ResetUpdateStatus() = 0;
79
80  // This method should be called every time we initiate a Rollback.
81  virtual void Rollback() = 0;
82
83  // Sets the expectations to boot into the new version in the next reboot.
84  // This function is called every time a new update is marked as ready by
85  // UpdateSuccess(). |target_version_uid| is an unique identifier of the
86  // applied payload. It can be any string, as long as the same string is used
87  // for the same payload.
88  virtual void ExpectRebootInNewVersion(
89      const std::string& target_version_uid) = 0;
90
91  // Sets whether P2P is being used to download the update payload. This
92  // is used to keep track of download sources being used and should be called
93  // before the transfer begins.
94  virtual void SetUsingP2PForDownloading(bool value) = 0;
95
96  // Sets whether P2P is being used for sharing the update payloads.
97  virtual void SetUsingP2PForSharing(bool value) = 0;
98
99  // Returns true if we should backoff the current download attempt.
100  // False otherwise.
101  virtual bool ShouldBackoffDownload() = 0;
102
103  // Returns the currently stored response "signature". The signature  is a
104  // subset of fields that are of interest to the PayloadState behavior.
105  virtual std::string GetResponseSignature() = 0;
106
107  // Returns the payload attempt number.
108  virtual int GetPayloadAttemptNumber() = 0;
109
110  // Returns the payload attempt number of the attempted full payload. Returns
111  // 0 for delta payloads.
112  virtual int GetFullPayloadAttemptNumber() = 0;
113
114  // Returns the current URL. Returns an empty string if there's no valid URL.
115  virtual std::string GetCurrentUrl() = 0;
116
117  // Returns the current URL's failure count.
118  virtual uint32_t GetUrlFailureCount() = 0;
119
120  // Returns the total number of times a new URL has been switched to
121  // for the current response.
122  virtual uint32_t GetUrlSwitchCount() = 0;
123
124  // Returns the total number of different responses seen since the
125  // last successful update.
126  virtual int GetNumResponsesSeen() = 0;
127
128  // Returns the expiry time for the current backoff period.
129  virtual base::Time GetBackoffExpiryTime() = 0;
130
131  // Returns the elapsed time used for this update, including time
132  // where the device is powered off and sleeping. If the
133  // update has not completed, returns the time spent so far.
134  virtual base::TimeDelta GetUpdateDuration() = 0;
135
136  // Returns the time used for this update not including time when
137  // the device is powered off or sleeping. If the update has not
138  // completed, returns the time spent so far.
139  virtual base::TimeDelta GetUpdateDurationUptime() = 0;
140
141  // Returns the number of bytes that have been downloaded for each source for
142  // each new update attempt. If we resume an update, we'll continue from the
143  // previous value, but if we get a new response or if the previous attempt
144  // failed, we'll reset this to 0 to start afresh.
145  virtual uint64_t GetCurrentBytesDownloaded(DownloadSource source) = 0;
146
147  // Returns the total number of bytes that have been downloaded for each
148  // source since the the last successful update. This is used to compute the
149  // overhead we incur.
150  virtual uint64_t GetTotalBytesDownloaded(DownloadSource source) = 0;
151
152  // Returns the reboot count for this update attempt.
153  virtual uint32_t GetNumReboots() = 0;
154
155  // Called at update_engine startup to do various house-keeping.
156  virtual void UpdateEngineStarted() = 0;
157
158  // Returns the version from before a rollback if our last update was a
159  // rollback.
160  virtual std::string GetRollbackVersion() = 0;
161
162  // Returns the value of number of attempts we've attempted to
163  // download the payload via p2p.
164  virtual int GetP2PNumAttempts() = 0;
165
166  // Returns the value of timestamp of the first time we've attempted
167  // to download the payload via p2p.
168  virtual base::Time GetP2PFirstAttemptTimestamp() = 0;
169
170  // Should be called every time we decide to use p2p for an update
171  // attempt. This is used to increase the p2p attempt counter and
172  // set the timestamp for first attempt.
173  virtual void P2PNewAttempt() = 0;
174
175  // Returns |true| if we are allowed to continue using p2p for
176  // downloading and |false| otherwise. This is done by recording
177  // and examining how many attempts have been done already as well
178  // as when the first attempt was.
179  virtual bool P2PAttemptAllowed() = 0;
180
181  // Gets the values previously set with SetUsingP2PForDownloading() and
182  // SetUsingP2PForSharing().
183  virtual bool GetUsingP2PForDownloading() const = 0;
184  virtual bool GetUsingP2PForSharing() const = 0;
185
186  // Returns the current (persisted) scattering wallclock-based wait period.
187  virtual base::TimeDelta GetScatteringWaitPeriod() = 0;
188
189  // Sets and persists the scattering wallclock-based wait period.
190  virtual void SetScatteringWaitPeriod(base::TimeDelta wait_period) = 0;
191
192  // Sets/gets the P2P download URL, if one is to be used.
193  virtual void SetP2PUrl(const std::string& url) = 0;
194  virtual std::string GetP2PUrl() const = 0;
195  virtual ErrorCode GetAttemptErrorCode() const = 0;
196};
197
198}  // namespace chromeos_update_engine
199
200#endif  // UPDATE_ENGINE_PAYLOAD_STATE_INTERFACE_H_
201