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 26 namespace 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. 31 class 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