From aa028f0a60ed571ae607028fffa3e2c4e6b93b93 Mon Sep 17 00:00:00 2001 From: Tao Bao Date: Fri, 8 Mar 2019 13:37:57 -0800 Subject: [PATCH] Add Javadoc for UpdateEngine constants. Fixes: 123597185 Test: N/A Change-Id: Iab3a43b2e65687b14424e86bc532180138c97ef0 --- core/java/android/os/UpdateEngine.java | 136 +++++++++++++++++++++++-- 1 file changed, 130 insertions(+), 6 deletions(-) diff --git a/core/java/android/os/UpdateEngine.java b/core/java/android/os/UpdateEngine.java index 1df3dad9530b9..5cf3b970c00cf 100644 --- a/core/java/android/os/UpdateEngine.java +++ b/core/java/android/os/UpdateEngine.java @@ -39,8 +39,9 @@ import android.os.RemoteException; * * The APIs defined in this class and UpdateEngineCallback class must be in * sync with the ones in - * system/update_engine/binder_bindings/android/os/IUpdateEngine.aidl and - * system/update_engine/binder_bindings/android/os/IUpdateEngineCallback.aidl. + * {@code system/update_engine/binder_bindings/android/os/IUpdateEngine.aidl} + * and + * {@code system/update_engine/binder_bindings/android/os/IUpdateEngineCallback.aidl}. * * {@hide} */ @@ -51,39 +52,150 @@ public class UpdateEngine { private static final String UPDATE_ENGINE_SERVICE = "android.os.UpdateEngineService"; /** - * Error code from the update engine. Values must agree with the ones in - * system/update_engine/common/error_code.h. + * Error codes from update engine upon finishing a call to + * {@link applyPayload}. Values will be passed via the callback function + * {@link UpdateEngineCallback#onPayloadApplicationComplete}. Values must + * agree with the ones in {@code system/update_engine/common/error_code.h}. */ public static final class ErrorCodeConstants { + /** + * Error code: a request finished successfully. + */ public static final int SUCCESS = 0; + /** + * Error code: a request failed due to a generic error. + */ public static final int ERROR = 1; + /** + * Error code: an update failed to apply due to filesystem copier + * error. + */ public static final int FILESYSTEM_COPIER_ERROR = 4; + /** + * Error code: an update failed to apply due to an error in running + * post-install hooks. + */ public static final int POST_INSTALL_RUNNER_ERROR = 5; + /** + * Error code: an update failed to apply due to a mismatching payload. + * + *

For example, the given payload uses a feature that's not + * supported by the current update engine. + */ public static final int PAYLOAD_MISMATCHED_TYPE_ERROR = 6; + /** + * Error code: an update failed to apply due to an error in opening + * devices. + */ public static final int INSTALL_DEVICE_OPEN_ERROR = 7; + /** + * Error code: an update failed to apply due to an error in opening + * kernel device. + */ public static final int KERNEL_DEVICE_OPEN_ERROR = 8; + /** + * Error code: an update failed to apply due to an error in fetching + * the payload. + * + *

For example, this could be a result of bad network connection + * when streaming an update. + */ public static final int DOWNLOAD_TRANSFER_ERROR = 9; + /** + * Error code: an update failed to apply due to a mismatch in payload + * hash. + * + *

Update engine does sanity checks for the given payload and its + * metadata. + */ public static final int PAYLOAD_HASH_MISMATCH_ERROR = 10; + + /** + * Error code: an update failed to apply due to a mismatch in payload + * size. + */ public static final int PAYLOAD_SIZE_MISMATCH_ERROR = 11; + + /** + * Error code: an update failed to apply due to failing to verify + * payload signatures. + */ public static final int DOWNLOAD_PAYLOAD_VERIFICATION_ERROR = 12; + + /** + * Error code: an update failed to apply due to a downgrade in payload + * timestamp. + * + *

The timestamp of a build is encoded into the payload, which will + * be enforced during install to prevent downgrading a device. + */ public static final int PAYLOAD_TIMESTAMP_ERROR = 51; + + /** + * Error code: an update has been applied successfully but the new slot + * hasn't been set to active. + * + *

It indicates a successful finish of calling {@link #applyPayload} with + * {@code SWITCH_SLOT_ON_REBOOT=0}. See {@link #applyPayload}. + */ public static final int UPDATED_BUT_NOT_ACTIVE = 52; } /** - * Update status code from the update engine. Values must agree with the - * ones in system/update_engine/client_library/include/update_engine/update_status.h. + * Status codes for update engine. Values must agree with the ones in + * {@code system/update_engine/client_library/include/update_engine/update_status.h}. */ public static final class UpdateStatusConstants { + /** + * Update status code: update engine is in idle state. + */ public static final int IDLE = 0; + + /** + * Update status code: update engine is checking for update. + */ public static final int CHECKING_FOR_UPDATE = 1; + + /** + * Update status code: an update is available. + */ public static final int UPDATE_AVAILABLE = 2; + + /** + * Update status code: update engine is downloading an update. + */ public static final int DOWNLOADING = 3; + + /** + * Update status code: update engine is verifying an update. + */ public static final int VERIFYING = 4; + + /** + * Update status code: update engine is finalizing an update. + */ public static final int FINALIZING = 5; + + /** + * Update status code: an update has been applied and is pending for + * reboot. + */ public static final int UPDATED_NEED_REBOOT = 6; + + /** + * Update status code: update engine is reporting an error event. + */ public static final int REPORTING_ERROR_EVENT = 7; + + /** + * Update status code: update engine is attempting to rollback an + * update. + */ public static final int ATTEMPTING_ROLLBACK = 8; + + /** + * Update status code: update engine is in disabled state. + */ public static final int DISABLED = 9; } @@ -178,6 +290,18 @@ public class UpdateEngine { * "METADATA_SIZE=70604" * }; * + * + *

The callback functions registered via {@code #bind} will be called + * during and at the end of the payload application. + * + *

By default the newly updated slot will be set active upon + * successfully finishing an update. Device will attempt to boot into the + * new slot on next reboot. This behavior can be customized by specifying + * {@code SWITCH_SLOT_ON_REBOOT=0} in {@code headerKeyValuePairs}, which + * allows the caller to later determine a good time to boot into the new + * slot. Calling {@code applyPayload} again with the same payload but with + * {@code SWITCH_SLOT_ON_REBOOT=1} will do the minimal work to set the new + * slot active, after verifying its integrity. */ public void applyPayload(String url, long offset, long size, String[] headerKeyValuePairs) { try {