| // 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; |
| |
| /// Information about the state of the update system. |
| [Discoverable, FragileBase] |
| protocol Info { |
| /// Retrieve the currently active update channel. |
| /// |
| /// - response `channel` the currently active update channel. |
| GetChannel() -> (string:128 channel); |
| }; |
| |
| /// Control the target update channel, this is the channel we will use on the next update check. |
| [Discoverable] |
| protocol ChannelControl { |
| compose Info; |
| |
| /// Set a new desired target channel. This tells the updater to attempt to |
| /// check for updates using a new channel. This is tentative, and won't be |
| /// persisted unless an update check on that channel is successful. |
| /// |
| /// A response is generated when the new target channel has been verified as |
| /// valid. |
| /// |
| /// + request `channel` the new target channel name (name used by the updater) |
| SetTarget(string:128 channel) -> (); |
| |
| /// Get the current tentative target channel for updates. |
| /// This returns the channel that the update client is using to perform update |
| /// checks. It's always one of: |
| /// - the current channel |
| /// - the default channel |
| /// - a new target that's different, but hasn't been OTA'd from yet. |
| /// |
| /// - response `channel` the current target channel. |
| GetTarget() -> (string:128 channel); |
| }; |
| |
| [Discoverable] |
| protocol Manager { |
| /// Immediately check for an update. |
| /// `options`: Did a user initiate this request? (`USER_INITIATED`) This changes |
| /// some parameters about aggressiveness of retries and throttling. |
| /// `monitor`: An interface on which to receive the status events for this update check. |
| /// It's only valid for a single update check, after that it won't receive any |
| /// more events. |
| /// |
| /// -> Was the update check successfully started (state machine in a proper state |
| /// to do so). |
| CheckNow(Options options, request<Monitor>? monitor) |
| -> (CheckStartedResult result); |
| |
| /// Get the current state of the Manager (is an update available, is it currently |
| /// checking for an update, etc). |
| GetState() -> (State state); |
| |
| /// Get all status events, for all update checks (interactive and background). |
| AddMonitor(request<Monitor> monitor); |
| }; |
| |
| /// Receiver of updates for either an individual update check, or to continuously |
| /// receive updates for all checks. |
| protocol Monitor { |
| /// Receive the current state as it changes. |
| -> OnState(State state); |
| |
| // TODO: support progress reporting. |
| }; |
| |
| /// Configuration options for an update attempt (this is common with the Fuchsia |
| /// OTA Interface v2) |
| table Options { |
| /// What initiated this update attempt. |
| 1: Initiator initiator; |
| }; |
| |
| /// Who or what initiated the update check. |
| enum Initiator { |
| /// The update check was initiated by an interactive user, or the user is |
| /// otherwise blocked and waiting for the result of this update check. |
| USER = 0; |
| |
| /// The update check was initiated by a service, in the background. |
| SERVICE = 1; |
| }; |
| |
| /// ``` |
| /// The various states that the manager can be in. |
| /// |
| /// +----------------------+ |
| /// --->| IDLE |<--------------------------------+ |
| /// | +----------------------+ | |
| /// | | +----------------------+ | |
| /// | |<--------------| UPDATE_AVAILABLE | | |
| /// | | +----------------------+ | |
| /// | v ^ | |
| /// | +----------------------+ | | |
| /// |<--| CHECKING_FOR_UPDATES |-----------------+ | |
| /// | +----------------------+ | | |
| /// | v | | |
| /// | +----------------------+ | | |
| /// | | PERFORMING_UPDATE |---------------->| | |
| /// | +----------------------+ | | |
| /// | v | | |
| /// | +----------------------+ | | |
| /// | | WAITING_FOR_REBOOT |---------------->| | |
| /// | +----------------------+ | | |
| /// | v v | |
| /// | +----------------------+ +----------------------+ | |
| /// +---| FINALIZING_UPDATE |---->| ENCOUNTERED_ERROR |----+ |
| /// +----------------------+ +----------------------+ |
| /// |
| /// ``` |
| enum ManagerState { |
| /// The Manager is currently idle (in between updates). |
| /// |
| /// Next states: |
| /// * `CHECKING_FOR_UPDATES` |
| IDLE = 0; |
| /// The Manager is currently checking for an update. |
| /// |
| /// Next states: |
| /// * `IDLE` update is not available |
| /// * `UPDATE_AVAILABLE` update is available but not allowed by policy |
| /// * `PERFORMING_UPDATE` update is available and allowed by policy |
| /// * `ENCOUNTERED_ERROR` on error |
| CHECKING_FOR_UPDATES = 1; |
| /// The Manager has found an available update but is not allowed to update |
| /// due to policy. |
| /// |
| /// Next states: |
| /// * `CHECKING_FOR_UPDATES` when CheckNow() is called or a background update starts |
| UPDATE_AVAILABLE = 2; |
| /// The Manager has started the available update. |
| /// |
| /// Next states: |
| /// * `WAITING_FOR_REBOOT` on success |
| /// * `ENCOUNTERED_ERROR` on error |
| PERFORMING_UPDATE = 3; |
| /// The update has been performed, and the device is waiting to be rebooted. |
| /// |
| /// Next states: |
| /// * `FINALIZING_UPDATE` after device reboot |
| /// * `ENCOUNTERED_ERROR` on error |
| WAITING_FOR_REBOOT = 4; |
| /// The update is being finalized after reboot. |
| /// |
| /// Next states: |
| /// * `IDLE` on success |
| /// * `ENCOUNTERED_ERROR` on error |
| FINALIZING_UPDATE = 5; |
| /// The Manager is reporting to Omaha that an error has occurred during the |
| /// update. |
| /// |
| /// Next states: |
| /// * `IDLE` |
| ENCOUNTERED_ERROR = 6; |
| }; |
| |
| enum CheckStartedResult { |
| /// The update check has been started. |
| STARTED = 0; |
| /// The update check was not started, as an update is already in progress, `monitor` is |
| /// attached to that update and will immediately get a OnState() call on current state. |
| IN_PROGRESS = 1; |
| /// The update check was not started, because too many requests to check have |
| /// been made in a short period of time. |
| THROTTLED = 2; |
| }; |
| |
| table State { |
| /// The current state of the Manager. Always present. |
| 1: ManagerState state; |
| |
| /// The version available from Omaha. Will be present in `UPDATE_AVAILABLE` or starting |
| /// from `PERFORMING_UPDATE`. |
| 2: string version_available; |
| }; |