// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
module updater.mojom;
import "mojo/public/mojom/base/file_path.mojom";
// Struct containing the information required to register an application with
// the updater. Passed from client to server during RegisterApp and Install.
// Next version: 2
[Stable] struct RegistrationRequest {
// Application ID of the app.
string app_id;
// The brand code, a four character code attributing the app’s
// presence to a marketing campaign or similar effort. May be the empty
// string.
string brand_code;
// A file path. Currently applicable to on Mac only: if a valid plist file
// exists at this path, the string value of key "KSBrandID" will override
// the `brand_code` above.
mojo_base.mojom.FilePath brand_path;
// The ap value (e.g. from a tagged metainstaller). May be the empty string.
// This typically indicates channel, though it can carry additional data as
// well.
string ap;
// The version of the app already installed. 0.0.0.0 if the app is not
// already installed.
string version;
// A file path. A file exists at this path if and only if the app is
// still installed. This is used (on Mac, for example) to detect
// whether an app has been uninstalled via deletion. May be the empty
// string; if so, the app is assumed to be installed unconditionally.
mojo_base.mojom.FilePath existence_checker_path;
// The path to a file containing the ap key/value pair. On macOS, a plist
// should be used.
[MinVersion=1] mojo_base.mojom.FilePath? ap_path;
// The name of the key in the file for the ap value.
[MinVersion=1] string? ap_key;
// The path to a file containing the product version key/value. On macOS, a
// plist should be used.
[MinVersion=1] mojo_base.mojom.FilePath? version_path;
// The name of they key in the file for the product version value.
[MinVersion=1] string? version_key;
};
// Struct containing details on the state of an update. It is passed
// periodically from the server to the client via the StateChangeObserver.
[Stable] struct UpdateState {
// Possible states for updating an app. Add new values at the end of
// the definition, and do not mutate the existing values.
[Stable, Extensible]
enum State {
// This value represents the absence of a state. No update request has
// yet been issued. Also used if the remote transmits a state this version
// of the app does not know about.
[Default] kUnknown = 0,
// This update has not been started, but has been requested.
kNotStarted,
// The engine began issuing an update check request.
kCheckingForUpdates,
// An update is available.
kUpdateAvailable,
// The engine began downloading an update.
kDownloading,
// The engine began running installation scripts.
kInstalling,
// The engine found and installed an update for this product. The update
// is complete and the state will not change.
kUpdated,
// The engine checked for updates. This product is already up to date.
// No update has been installed for this product. The update is complete
// and the state will not change.
kNoUpdate,
// The engine encountered an error updating this product. The update has
// halted and the state will not change.
kUpdateError,
};
string app_id;
State state = State.kUnknown;
// The version is initialized only after an update check has completed, and
// an update is available.
string next_version;
int64 downloaded_bytes = -1;
int64 total_bytes = -1;
// A value in the range [0, 100] if the install progress is known, or -1
// if the install progress is not available or it could not be computed.
int8 install_progress = -1;
UpdateService.ErrorCategory error_category =
UpdateService.ErrorCategory.kNone;
int32 error_code = 0;
int32 extra_code1 = 0;
// Results collected from installer result API. See the definition of
// `update_client::CrxInstaller::Result` for the meaning of the members.
string installer_text;
string installer_cmd_line;
};
// Next version: 3
[Stable] struct AppState {
string app_id;
string version;
string ap;
string brand_code;
mojo_base.mojom.FilePath brand_path;
mojo_base.mojom.FilePath ecp;
[MinVersion=1] mojo_base.mojom.FilePath? ap_path;
[MinVersion=1] string? ap_key;
[MinVersion=1] mojo_base.mojom.FilePath? version_path;
[MinVersion=1] string? version_key;
[MinVersion=2] string? cohort;
};
// The UpdateService is the cross-platform core of the updater.
// All functions and callbacks must be called on the same sequence.
[Stable] interface UpdateService {
// Defines the behavior of the update stack for over-installs.
// Typically, same versions updates are not allowed, in which case, the update
// server replies with `update not available'. But there are cases, such as
// re-installing an application again, when the server may respond with an
// update.
[Stable, Extensible]
enum PolicySameVersionUpdate {
// The embedder does not allow over-installs with the same version. In this
// case, the server is expected to return `update not available` when it
// is queried for updates.
[Default] kNotAllowed = 0,
// The embedder is capable of handling updates with the same version, and
// the server may respond with such an update.
kAllowed,
};
[Stable, Extensible]
enum Result {
// Indicates that the service successfully handled the non-blocking function
// invocation. Returning this value provides no indication regarding the
// outcome of the function, such as whether the updates succeeded or not.
kSuccess = 0,
// The function failed because there is an update in progress. Certain
// service functions can be parallelized but not all functions can run
// concurrently.
kUpdateInProgress,
kUpdateCanceled,
// The function failed because of a throttling policy such as load shedding.
kRetryLater,
// This is a generic result indicating that an error occurred in the service
// such as a task failed to post, or allocation of a resource failed.
kServiceFailed,
// An error handling the update check occurred.
kUpdateCheckFailed,
// This value indicates that required metadata associated with the
// application was not available for any reason.
kAppNotFound,
// A function argument was invalid.
kInvalidArgument,
// This server is not the active server.
kInactive,
// IPC connection to the remote process failed for some reason.
kIPCConnectionFailed,
// Failed to run app installer.
kInstallFailed,
// The server received the request and rejected the requestor as
// unauthorized to make it.
kPermissionDenied,
// The remote transmitted a value unknown to this version of the app.
[Default] kUnknown,
};
// Run time errors are organized in specific categories to indicate the
// component where such errors occurred. The category appears as a numeric
// value in the telemetry pings. The values of this enum must be kept Stable.
// Next version: 2
[Stable, Extensible]
enum ErrorCategory {
kNone = 0,
kDownload,
kUnpack,
kInstall,
kService,
kUpdateCheck,
[Default] kUnknown,
[MinVersion=1] kInstaller,
};
// Urgency of the update service invocation.
[Stable, Extensible]
enum Priority {
// The caller has not set a valid priority value.
[Default] kUnknown = 0,
// The user is not waiting for this update.
kBackground,
// The user is not waiting for this update.
kForeground,
};
// Returns the version of the active updater. The version object is invalid
// if an error (including timeout) occurs.
GetVersion@0() => (string version);
// Fetches policies from device management.
FetchPolicies@1() => (int32 result);
// Registers given request to the updater.
RegisterApp@2(RegistrationRequest request) => (int32 result);
// Gets state of all registered apps.
GetAppStates@3() => (array<AppState> app_states);
// Runs periodic tasks such as checking for uninstallation of registered
// applications or doing background updates for registered applications.
RunPeriodicTasks@4() => ();
// Initiates an update check for all registered applications. Receives state
// change notifications through the `state_change_observer`. Responds once
// the operation is complete.
UpdateAll@5() =>
(pending_receiver<StateChangeObserver> observer);
// Updates specified product. This update may be on-demand.
//
// Response:
// The final result from the update engine.
Update@6(
// ID of app to update.
string app_id,
// Index of the server install data.
string install_data_index,
// Priority for processing this update.
Priority priority,
// Whether a same-version update is allowed.
PolicySameVersionUpdate policy_same_version_update,
// Only checks for updates if `do_update_check_only` is `true`.
[MinVersion=1] bool do_update_check_only) =>
(pending_receiver<StateChangeObserver> observer);
// Registers and installs an application from the network.
//
// Response:
// The final result from the update engine.
Install@7(
// Registration data about the app.
RegistrationRequest registration,
// User provided install data.
string client_install_data,
// Index of the server install data. Effective only
// when `client_install_data` is not set.
string install_data_index,
// Priority for processing this update.
Priority priority) =>
(pending_receiver<StateChangeObserver> observer);
// Cancels any ongoing installations of the specified product. This does not
// interrupt any product installers that are currently running, but does
// prevent them from being run if they are not yet downloaded.
//
// Args:
// `app_id`: ID of the product to cancel installs of.
CancelInstalls@8(string app_id);
// Install an app by running its installer.
//
// Result:
// The final result from the update engine.
RunInstaller@9(
// `app_id`: ID of app to install.
string app_id,
// `app_installer`: Offline installer path.
mojo_base.mojom.FilePath installer_path,
// `arguments`: Arguments to run the installer.
string install_args,
// `install_data`: Server install data extracted from the offline manifest.
string install_data,
// `install_settings`: An optional serialized dictionary to customize the
// installation.
string install_settings) =>
(pending_receiver<StateChangeObserver> observer);
// Check for updates to a specified product, but do not apply them.
//
// Response:
// The final result from the update engine.
[MinVersion=2] CheckForUpdate@10(
// ID of app to update.
string app_id,
// Priority for processing this update.
Priority priority,
// Whether a same-version update is allowed.
PolicySameVersionUpdate policy_same_version_update) =>
(pending_receiver<StateChangeObserver> observer);
};
// Callback interface for repeated state change notifications produced by
// methods of the UpdateService interface.
[Stable] interface StateChangeObserver {
// Repeated state change callback.
// state: the new state of this update request.
OnStateChange@0(UpdateState state);
// A callback to be run with the final result of the operation.
OnComplete@1(UpdateService.Result result);
};
Codebase Browser
chromium