Merge "Basic javadoc for android.os.UpdateEngine." (cbafc8d6) · Commits · e / os / android_frameworks_base

core/java/android/os/UpdateEngine.java

+76 −1

Original line number	Diff line number	Diff line
		@@ -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 {

core/java/android/os/UpdateEngineCallback.java

+12 −1

Original line number	Diff line number	Diff line
		@@ -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);
		}