| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.update.installer; |
| |
| using fuchsia.pkg; |
| |
| alias AttemptId = string:36; // 36 == strlen("01234567-89ab-cdef-0123-456789abcdef") |
| |
| /// Updates the system. |
| /// |
| /// This protocol is intended to be consumed by a component capable of |
| /// discovering when to update and what version of the system to install. |
| @discoverable |
| closed protocol Installer { |
| /// Get the status of the last update attempt. If this device hasn't |
| /// attempted an update since the last factory reset, every field in the |
| /// result will be absent. |
| /// |
| /// - response `info` the status of the last update attempt, if available. |
| strict GetLastUpdateResult() -> (struct { |
| info UpdateResult; |
| }); |
| |
| /// Get the status of the given update attempt, if it exists. If this device |
| /// hasn't attempted an update with the given `attempt_id` or forgotten about |
| /// that attempt, every field in the result will be absent. |
| /// |
| /// + request `attempt_id` UUID identifying the requested update attempt. |
| /// - response `info` the status of the last update attempt, if available. |
| strict GetUpdateResult(struct { |
| attempt_id AttemptId; |
| }) -> (struct { |
| info UpdateResult; |
| }); |
| |
| /// Start an update if one is not running, or attach to a pending update |
| /// attempt if one is running and |
| /// [`Options.allow_attach_to_existing_attempt`] is true. If an update |
| /// attempt is started or attached to, provide status updates through |
| /// `monitor`. |
| /// |
| /// + request `url` The fuchsia-pkg URL of the update package to update to. |
| /// + request `options` Configuration options for this update attempt. |
| /// Ignored or merged with the existing `options` if an update attempt |
| /// is already in progress. |
| /// + request `monitor` A protocol on which to receive progress updates. |
| /// + request `reboot_controller` An optional protocol to control the timing |
| /// of the reboot into the update system. If not provided, the update |
| /// attempt will initiate the reboot as soon as it is ready. |
| /// |
| /// - response `attempt_id` UUID identifying this update attempt. For |
| /// updates that require a reboot, components may use this identifier to |
| /// disambiguate the completion of this update attempt from new update |
| /// attempts that start post-reboot. |
| strict StartUpdate(resource struct { |
| url fuchsia.pkg.PackageUrl; |
| options Options; |
| monitor client_end:Monitor; |
| reboot_controller server_end:<RebootController, optional>; |
| }) -> (struct { |
| attempt_id AttemptId; |
| }) error UpdateNotStartedReason; |
| |
| /// Attempt to monitor a specific update attempt, if it exists. This request |
| /// will not start an update if one is not already running. |
| /// |
| /// + request `attempt_id` UUID identifying the requested update attempt. If |
| /// not given, monitor any active update attempt. |
| /// + request `monitor` A protocol on which to receive progress updates. |
| /// |
| /// - response `attached` Whether or not the provided monitor was attached |
| /// to an in-progress update attempt. If false, monitor will be closed |
| /// by the server. |
| strict MonitorUpdate(resource struct { |
| attempt_id AttemptId:optional; |
| monitor client_end:Monitor; |
| }) -> (struct { |
| attached bool; |
| }); |
| |
| /// Suspend a specific update attempt, if it exists. |
| /// |
| /// + request `attempt_id` UUID identifying the requested update attempt. If |
| /// not given, suspend any active update attempt. |
| strict SuspendUpdate(struct { |
| attempt_id AttemptId:optional; |
| }) -> () error SuspendError; |
| |
| /// Resume a specific update attempt, if it exists. |
| /// |
| /// + request `attempt_id` UUID identifying the requested update attempt. If |
| /// not given, resume any active update attempt. |
| strict ResumeUpdate(struct { |
| attempt_id AttemptId:optional; |
| }) -> () error ResumeError; |
| |
| /// Cancel a specific update attempt, if it exists. |
| /// |
| /// + request `attempt_id` UUID identifying the requested update attempt. If |
| /// not given, cancel any active update attempt. |
| strict CancelUpdate(struct { |
| attempt_id AttemptId:optional; |
| }) -> () error CancelError; |
| }; |
| |
| /// Controls the timing of the reboot into the updated system. |
| /// |
| /// If the client end of a [`RebootController`] is closed without calling |
| /// [`RebootController.Detach()`], the update attempt will fall back to the |
| /// default behavior of rebooting as soon as it is ready. |
| closed protocol RebootController { |
| /// Informs the update attempt that it may reboot when ready, unblocking a |
| /// pending reboot if it is already ready to reboot. |
| /// |
| /// If a controller is dropped without sending this request or |
| /// [`RebootController.Detach`], the update attempt reclaims control of the |
| /// timing of the reboot, behaving as if the update attempt was not given a |
| /// [`RebootController`] at all. |
| strict Unblock(); |
| |
| /// Informs the update attempt that it should wait to reboot indefinitely, |
| /// even if this [`RebootController`] connection is dropped. |
| strict Detach(); |
| }; |
| |
| /// Metadata about a prior update attempt. |
| type UpdateResult = table { |
| /// Unique identifier for this specific update attempt. Always present. |
| 1: attempt_id AttemptId; |
| |
| /// fuchsia-pkg:// url for the update package associated with this update |
| /// attempt. Always present. |
| 2: url fuchsia.pkg.PackageUrl; |
| |
| /// Configuration options for this update attempt. Always present. |
| 3: options Options; |
| |
| /// Terminal state of this update attempt. Always present if the update |
| /// failed. None if the update succeeded. |
| 4: state State; |
| }; |
| |
| /// Configuration options for an update attempt. |
| type Options = table { |
| /// What initiated this update attempt. Required. |
| 1: initiator Initiator; |
| |
| /// If an update is already in progress, it's acceptable to instead attach a |
| /// Monitor to that in-progress update instead of failing this request to |
| /// install the update. Setting this option to true may convert situations |
| /// that would have resulted in the ALREADY_IN_PROGRESS to be treated as |
| /// non-error cases. A controller, if provided, will be ignored if the |
| /// running update attempt already has a controller. |
| 2: allow_attach_to_existing_attempt bool; |
| |
| /// Determines if the installer should update the recovery partition if an |
| /// update is available. Defaults to true. |
| 3: should_write_recovery bool; |
| }; |
| |
| /// Who or what initiated the update installation. |
| type Initiator = strict enum { |
| /// The install was initiated by an interactive user, or the user is |
| /// otherwise blocked and waiting for the result of this update. |
| USER = 0; |
| |
| /// The install was initiated by a service, in the background. |
| SERVICE = 1; |
| }; |
| |
| /// The set of values that are returned by an request to start an update. |
| type UpdateNotStartedReason = strict enum { |
| /// There was already another update attempt in progress when this request was |
| /// made. A new update attempt will not be started. |
| ALREADY_IN_PROGRESS = 1; |
| }; |
| |
| /// Why suspend failed. |
| type SuspendError = strict enum { |
| /// There is no update attempt in progress. |
| NO_UPDATE_IN_PROGRESS = 1; |
| /// The current update attempt has reached its suspend limit. |
| SUSPEND_LIMIT_EXCEEDED = 2; |
| /// The given attempt id does not match the current update attempt. |
| ATTEMPT_ID_MISMATCH = 3; |
| }; |
| |
| /// Why resume failed. |
| type ResumeError = strict enum { |
| /// There is no update attempt in progress. |
| NO_UPDATE_IN_PROGRESS = 1; |
| /// The given attempt id does not match the current update attempt. |
| ATTEMPT_ID_MISMATCH = 2; |
| }; |
| |
| /// Why cancel failed. |
| type CancelError = strict enum { |
| /// There is no update attempt in progress. |
| NO_UPDATE_IN_PROGRESS = 1; |
| /// The update attempt has past the point that can be canceled. |
| UPDATE_CANNOT_BE_CANCELED = 2; |
| /// The given attempt id does not match the current update attempt. |
| ATTEMPT_ID_MISMATCH = 3; |
| /// The number of cancel requests has exceeded the limit. |
| CANCEL_LIMIT_EXCEEDED = 4; |
| }; |