fuchsia.update

PROTOCOLS

Manager

Defined in fuchsia.update/update.fidl

The Manager protocol is used by a client that wishes to either check for an update, or follow the status of ongoing updates.

The Manager provides a mechanism for checking for updates via the [fuchisa.update2/Manager.CheckNow] message.

CheckNow

Immediately check for an update, and optionally track the state and progress of that update check.

  • request options: Options for how this request should be performed. E.g. What kind of entity initiated this request? E.g. Is monitoring an existing update check that is already in process an acceptable alternative?

  • request monitor: An interface on which to receive the status events for this update check. The monitor is only valid for this single update check, after that it will not receive any more notifications and will be closed.

  • error If an update check cannot be started, an error will be returned. The Monitor, if provided, will not receive any notifications.

Request

NameType
options CheckOptions
monitor Monitor?

Response

NameType
result Manager_CheckNow_Result

Monitor

Defined in fuchsia.update/update.fidl

This is a protocol that clients which wish to receive of updates for an individual update check should implement. This will not receive the events for more than one update check attempt.

OnState

This method is used to receive the current state as it changes. This receive all state changes, skipping none. However, message delivery is throttled by the rate at which the implementation acknowledges the messages.

The throttled delivery doesn't impact the underlying state of the Manager. It does not wait for any acknowledgements before it moves on to the next state in its state machine. The Manager will simply queue up the states for the Monitor implementor to receive.

During the installing_update state, the Manager implementation may, at its discretion, collapse redundant information like the fraction completed, in the event that the Monitor implementor is not acknowledging the OnState() messages in a timely manner.

'state': The new state from the Manager.

-> The implementor is ready to receive the next State from the Manager.

Request

NameType
state State

Response

NameType

STRUCTS

Manager_CheckNow_Response

Defined in fuchsia.update/update.fidl

NameTypeDescriptionDefault

ENUMS

Initiator

Type: uint32

Defined in fuchsia.update/update.fidl

Who or what initiated the update check.

NameValueDescription
USER 1

The update check was initiated by an interactive user, or the user is otherwise blocked and waiting for the result of this update check. This SHOULD only be used when there is a UI element or flow that a user has interacted with which has initiated this update check.

SERVICE 2

The update check was initiated by a service, not a user-facing aspect of the system.

CheckNotStartedReason

Type: uint32

Defined in fuchsia.update/update.fidl

This is the set of values that are returned by an request to immediately check for an update.

NameValueDescription
INTERNAL 1

There was an internal error in starting the update check. The client is not expected to be able to do something meaningful about this error, except to try again later (after an appropriate delay and back-off in the event of multiple errors.

INVALID_OPTIONS 2

If there are required options (or option values in conflict), provided via the CheckOptions table to CheckNow, this error will be returned.

ALREADY_IN_PROGRESS 3

There was already another update check in progress when this request was made. A new update check will not be started.

THROTTLED 4

The update check was not started, because too many requests to check for updates have been made by clients in a short period of time.

NOTE: Clients MUST NOT attempt to cause background update checks to happen at a more frequent rate than the fuchsia.update.Manager will do them.

If a client attempts to abuse this, it will be throttled.

TABLES

CheckOptions

Defined in fuchsia.update/update.fidl

These are configuration options for an update check.

OrdinalNameTypeDescription
1 initiator Initiator

Who or what initiated this update attempt. This is taken as input to Policy, and may influence how the update check is performed.

This is a required field.

2 allow_attaching_to_existing_update_check bool

If an update check is already in progress, it's acceptable to instead attach a Monitor to that in-progress update instead of failing this request to check for updates. This may convert situations that would have resulted in the ALREADY_IN_PROGRESS to be treated as non-error cases.

CheckingForUpdatesData

Defined in fuchsia.update/update.fidl

This is the set of data associated with checking_for_updates. (currently none)

OrdinalNameTypeDescription

ErrorCheckingForUpdateData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the error_checking_for_update state. (currently none)

OrdinalNameTypeDescription

NoUpdateAvailableData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the no_update_available state. (currently none)

OrdinalNameTypeDescription

InstallationDeferredData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the installation_deferred_by_policy state.

OrdinalNameTypeDescription
1 update UpdateInfo

InstallingData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the states involved with installing an update:

  • installing_update
  • waiting_for_reboot
OrdinalNameTypeDescription
1 update UpdateInfo
2 installation_progress InstallationProgress

InstallationErrorData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the installation_error state. (currently none)

OrdinalNameTypeDescription
1 update UpdateInfo
2 installation_progress InstallationProgress

UpdateInfo

Defined in fuchsia.update/update.fidl

This describes the update that is available to be installed.

OrdinalNameTypeDescription
1 version_available string[128]

A string that describes the version that is available. This may be either a semantic version (A.B.C.D) or an opaque hash. Clients MUST not attempt to inspect this value, it is for display purposes only.

2 download_size uint64

The total number of bytes that may be downloaded to apply this update.

InstallationProgress

Defined in fuchsia.update/update.fidl

This describes the progress installing the update that has been made so far.

OrdinalNameTypeDescription
1 fraction_completed float32

The fraction [0-1.0f] of the installation that has been completed.

UNIONS

Manager_CheckNow_Result

Defined in fuchsia.update/update.fidl

NameTypeDescription
response Manager_CheckNow_Response
err CheckNotStartedReason

State

Defined in fuchsia.update/update.fidl

The set of states that a Monitor can receive as part of an update check are
as follows.  There are a number of terminal states for a single update
check.  They are the ones on the right-hand side of the diagram (and have no
arrows leading out of them).

    +----------------------+     +---------------------------------+
    | checking_for_updates |---->|    error_checking_for_update    |
    +----------------------+     +---------------------------------+
               |
               |                 +---------------------------------+
               +---------------->|       no_update_available       |
               |                 +---------------------------------+
               |
               |                 +---------------------------------+
               +---------------->| installation_deferred_by_policy |
               |                 +---------------------------------+
               v
    +----------------------+     +---------------------------------+
    |  installing_update   |---->|       installation_error        |
    +----------------------+     +---------------------------------+
               |
               |                 +---------------------------------+
               +---------------->|       waiting_for_reboot        |
                                 +---------------------------------+

NameTypeDescription
checking_for_updates CheckingForUpdatesData

The Manager is currently checking for an update.

Next states:

  • installing_update update is available and allowed by policy
  • error_checking_for_update on error
  • update_deferred_by_policy update is available but deferred by policy
error_checking_for_update ErrorCheckingForUpdateData

The Manager encountered an error while checking for the existence of a a new update.

This is a terminal state

no_update_available NoUpdateAvailableData

There is not update available at this time.

This is a terminal state

installation_deferred_by_policy InstallationDeferredData

The Manager has found an available update but is not acting on it at this time due to policy restrictions.

This is a terminal state

installing_update InstallingData

The Manager is installing the available update.

Next states:

  • waiting_for_reboot on success
  • installation_error on error
waiting_for_reboot InstallingData

The update has been installed, and the device is waiting to be rebooted.

Next states:

  • (none, the device reboots)

This is a terminal state

installation_error InstallationErrorData

The Manager encountered an update in the installation of the update.

This is a terminal state

CONSTANTS

NameValueTypeDescription
MAX_VERSION_STRING_SIZE 128 uint32

This is the maximum length of a version string that will be returned by the protocol