diff options
| -rw-r--r-- | core/java/android/os/UpdateEngine.java | 77 | ||||
| -rw-r--r-- | core/java/android/os/UpdateEngineCallback.java | 13 |
2 files changed, 88 insertions, 2 deletions
diff --git a/core/java/android/os/UpdateEngine.java b/core/java/android/os/UpdateEngine.java index bf03cce947e2..8549cff1faad 100644 --- a/core/java/android/os/UpdateEngine.java +++ b/core/java/android/os/UpdateEngine.java @@ -26,7 +26,18 @@ import android.util.Log; /** * UpdateEngine handles calls to the update engine which takes care of A/B OTA * updates. It wraps up the update engine Binder APIs and exposes them as - * SystemApis, which will be called by system apps like GmsCore. + * SystemApis, which will be called by the system app responsible for OTAs. + * On a Google device, this will be GmsCore. + * + * The minimal flow is: + * <ol> + * <li>Create a new UpdateEngine instance. + * <li>Call {@link #bind}, optionally providing callbacks. + * <li>Call {@link #applyPayload}. + * </ol> + * + * In addition, methods are provided to {@link #cancel} or + * {@link #suspend}/{@link #resume} application of an update. * * The APIs defined in this class and UpdateEngineCallback class must be in * sync with the ones in @@ -80,12 +91,20 @@ public class UpdateEngine { private IUpdateEngine mUpdateEngine; + /** + * Creates a new instance. + */ @SystemApi public UpdateEngine() { mUpdateEngine = IUpdateEngine.Stub.asInterface( ServiceManager.getService(UPDATE_ENGINE_SERVICE)); } + /** + * Prepares this instance for use. The callback will be notified on any + * status change, and when the update completes. A handler can be supplied + * to control which thread runs the callback, or null. + */ @SystemApi public boolean bind(final UpdateEngineCallback callback, final Handler handler) { IUpdateEngineCallback updateEngineCallback = new IUpdateEngineCallback.Stub() { @@ -125,11 +144,42 @@ public class UpdateEngine { } } + /** + * Equivalent to {@code bind(callback, null)}. + */ @SystemApi public boolean bind(final UpdateEngineCallback callback) { return bind(callback, null); } + /** + * Applies the payload found at the given {@code url}. For non-streaming + * updates, the URL can be a local file using the {@code file://} scheme. + * + * <p>The {@code offset} and {@code size} parameters specify the location + * of the payload within the file represented by the URL. This is useful + * if the downloadable package at the URL contains more than just the + * update_engine payload (such as extra metadata). This is true for + * Google's OTA system, where the URL points to a zip file in which the + * payload is stored uncompressed within the zip file alongside other + * data. + * + * <p>The {@code headerKeyValuePairs} parameter is used to pass metadata + * to update_engine. In Google's implementation, this is stored as + * {@code payload_properties.txt} in the zip file. It's generated by the + * script {@code system/update_engine/scripts/brillo_update_payload}. + * The complete list of keys and their documentation is in + * {@code system/update_engine/common/constants.cc}, but an example + * might be: + * <pre> + * String[] pairs = { + * "FILE_HASH=lURPCIkIAjtMOyB/EjQcl8zDzqtD6Ta3tJef6G/+z2k=", + * "FILE_SIZE=871903868", + * "METADATA_HASH=tBvj43QOB0Jn++JojcpVdbRLz0qdAuL+uTkSy7hokaw=", + * "METADATA_SIZE=70604" + * }; + * </pre> + */ @SystemApi public void applyPayload(String url, long offset, long size, String[] headerKeyValuePairs) { try { @@ -139,6 +189,15 @@ public class UpdateEngine { } } + /** + * Permanently cancels an in-progress update. + * + * <p>See {@link #resetStatus} to undo a finshed update (only available + * before the updated system has been rebooted). + * + * <p>See {@link #suspend} for a way to temporarily stop an in-progress + * update with the ability to resume it later. + */ @SystemApi public void cancel() { try { @@ -148,6 +207,10 @@ public class UpdateEngine { } } + /** + * Suspends an in-progress update. This can be undone by calling + * {@link #resume}. + */ @SystemApi public void suspend() { try { @@ -157,6 +220,9 @@ public class UpdateEngine { } } + /** + * Resumes a suspended update. + */ @SystemApi public void resume() { try { @@ -166,6 +232,15 @@ public class UpdateEngine { } } + /** + * Resets the bootable flag on the non-current partition and all internal + * update_engine state. This can be used after an unwanted payload has been + * successfully applied and the device has not yet been rebooted to signal + * that we no longer want to boot into that updated system. After this call + * completes, update_engine will no longer report + * {@code UPDATED_NEED_REBOOT}, so your callback can remove any outstanding + * notification that rebooting into the new system is possible. + */ @SystemApi public void resetStatus() { try { diff --git a/core/java/android/os/UpdateEngineCallback.java b/core/java/android/os/UpdateEngineCallback.java index b3b856fcf142..afff60abb22b 100644 --- a/core/java/android/os/UpdateEngineCallback.java +++ b/core/java/android/os/UpdateEngineCallback.java @@ -19,7 +19,8 @@ package android.os; import android.annotation.SystemApi; /** - * Callback function for UpdateEngine. + * Callback function for UpdateEngine. Used to keep the caller up to date + * with progress, so the UI (if any) can be updated. * * The APIs defined in this class and UpdateEngine class must be in sync with * the ones in @@ -31,9 +32,19 @@ import android.annotation.SystemApi; @SystemApi public abstract class UpdateEngineCallback { + /** + * Invoked when anything changes. The value of {@code status} will + * be one of the values from {@link UpdateEngine.UpdateStatusConstants}, + * and {@code percent} will be valid [TODO: in which cases?]. + */ @SystemApi public abstract void onStatusUpdate(int status, float percent); + /** + * Invoked when the payload has been applied, whether successfully or + * unsuccessfully. The value of {@code errorCode} will be one of the + * values from {@link UpdateEngine.ErrorCodeConstants}. + */ @SystemApi public abstract void onPayloadApplicationComplete(int errorCode); } |