chromium/chrome/updater/constants.h

// Copyright 2019 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CHROME_UPDATER_CONSTANTS_H_
#define CHROME_UPDATER_CONSTANTS_H_

#include "base/time/time.h"
#include "build/build_config.h"
#include "components/update_client/update_client_errors.h"

namespace updater {

// Key for storing the installer version in the install settings dictionary.
inline constexpr char kInstallerVersion[] = …;

// The updater specific app ID. Defined in the .cc file so that the updater
// branding constants don't leak in this public header.
extern const char kUpdaterAppId[];

// The app ID used to qualify the updater. Defined in the .cc file so that the
// updater branding constants don't leak in this public header.
extern const char kQualificationAppId[];

// The name of the updater program image.
#if BUILDFLAG(IS_WIN)
inline constexpr char kExecutableName[] = "updater.exe";
#else
inline constexpr char kExecutableName[] = …;
#endif

// A suffix appended to the updater executable name before any file extension.
extern const char kExecutableSuffix[];

// "0.0.0.0". Historically, a null version has been used to indicate a
// new install.
inline constexpr char kNullVersion[] = …;

// Command line switches.
//
// If a command line switch is marked as `backward-compatibility`, it
// means the switch name cannot be changed, and the parser must be able to
// handle command line in the DOS style '/<switch> <optional_value>'. This is to
// make sure the new updater understands the hand-off requests from the legacy
// updaters.

// This switch starts the COM server. This switch is invoked by the COM runtime
// when CoCreate is called on one of several CLSIDs that the server supports.
// We expect to use the COM server for the following scenarios:
// * The Server for the UI when installing User applications, and as a fallback
//   if the Service fails when installing Machine applications.
// * The On-Demand COM Server when running for User, and as a fallback if the
//   Service fails.
// * COM Server for launching processes at Medium Integrity, i.e., de-elevating.
// * The On-Demand COM Server when the client requests read-only interfaces
//   (say, Policy queries) at Medium Integrity.
// * A COM broker when running modes such as On-Demand for Machine. A COM broker
//   is something that acts as an intermediary, allowing creating one of several
//   possible COM objects that can service a particular COM request, ranging
//   from Privileged Services that can offer full functionality for a particular
//   set of interfaces, to Medium Integrity processes that can offer limited
//   (say, read-only) functionality for that same set of interfaces.
inline constexpr char kServerSwitch[] = …;

// This switch specifies the XPC service the server registers to listen to.
inline constexpr char kServerServiceSwitch[] = …;

// Valid values for the kServerServiceSwitch.
inline constexpr char kServerUpdateServiceInternalSwitchValue[] = …;
inline constexpr char kServerUpdateServiceSwitchValue[] = …;

// This switch starts the Windows service. This switch is invoked by the SCM
// either as a part of system startup (`SERVICE_AUTO_START`) or when `CoCreate`
// is called on one of several CLSIDs that the server supports.
inline constexpr char kWindowsServiceSwitch[] = …;

// This switch indicates that the Windows service is in the COM server mode.
// This switch is passed to `ServiceMain` by the SCM when CoCreate is called on
// one of several CLSIDs that the server supports. We expect to use the COM
// service for the following scenarios:
// * The Server for the UI when installing Machine applications.
// * The On-Demand COM Server for Machine applications.
// * COM Server for launching processes at System Integrity, i.e., an Elevator.
inline constexpr char kComServiceSwitch[] = …;

// Crash the program for testing purposes.
inline constexpr char kCrashMeSwitch[] = …;

// Runs as the Crashpad handler.
inline constexpr char kCrashHandlerSwitch[] = …;

// Updates the updater.
inline constexpr char kUpdateSwitch[] = …;

// Run as a network worker.
inline constexpr char kNetWorkerSwitch[] = …;

// Installs the updater. Takes an optional argument for the meta installer tag.
// The tag is a string of arguments, separated by a delimiter (in this case, the
// delimiter is `&`). The tag is typically embedded in the program image of the
// metainstaller, but for testing purposes, the tag could be passed directly as
// a command line argument. The tag is currently encoded as an ASCII string.
inline constexpr char kInstallSwitch[] = …;

inline constexpr char kEulaRequiredSwitch[] = …;

// Specifies that this is an OEM install in audit mode.
inline constexpr char kOemSwitch[] = …;

// The --installerdata=file.dat switch is passed to an installer if an
// installdataindex is specified in the tag or if installerdata is passed in via
// --appargs. The corresponding installerdata is written to file.dat with an
// UTF8 encoding as well as a UTF8 BOM.
inline constexpr char kInstallerDataSwitch[] = …;

// Uninstalls the updater.
inline constexpr char kUninstallSwitch[] = …;

// Uninstalls this version of the updater.
inline constexpr char kUninstallSelfSwitch[] = …;

// Uninstalls the updater if no apps are managed by it.
inline constexpr char kUninstallIfUnusedSwitch[] = …;

// Kicks off the update service. This switch is typically used for by a
// scheduled to invoke the updater periodically.
inline constexpr char kWakeSwitch[] = …;

// Kicks off the update service for all versions.
inline constexpr char kWakeAllSwitch[] = …;

// The updater needs to operate in the system context.
inline constexpr char kSystemSwitch[] = …;

// Runs in test mode. Currently, it exits right away.
inline constexpr char kTestSwitch[] = …;

// Run in recovery mode.
inline constexpr char kRecoverSwitch[] = …;

// The version of the program triggering recovery.
inline constexpr char kBrowserVersionSwitch[] = …;

// The session ID of the Omaha session triggering recovery.
inline constexpr char kSessionIdSwitch[] = …;  // backward-compatibility.

// The app ID of the program triggering recovery.
inline constexpr char kAppGuidSwitch[] = …;

// Causes crashpad handler to start a second instance to monitor the first
// instance for exceptions.
inline constexpr char kMonitorSelfSwitch[] = …;

// Additional arguments passed to the --monitor-self instance.
inline constexpr char kMonitorSelfSwitchArgument[] = …;

// The handle of an event to signal when the initialization of the main process
// is complete.
inline constexpr char kInitDoneNotifierSwitch[] = …;

// Enables logging.
inline constexpr char kEnableLoggingSwitch[] = …;

// Specifies the logging module filter and its value. Note that some call sites
// may still use different values for the logging module filter.
inline constexpr char kLoggingModuleSwitch[] = …;
inline constexpr char kLoggingModuleSwitchValue[] = …"*/components/winhttp/*=1,"
#endif
    "*/components/update_client/*=2,*/chrome/updater/*=2";

// Specifies the application that the Updater needs to install.
inline constexpr char kAppIdSwitch[] = …;

// Specifies the version of the application that the updater needs to register.
inline constexpr char kAppVersionSwitch[] = …;

// Specifies that the Updater should perform some minimal checks to verify that
// it is operational/healthy. This is for backward compatibility with Omaha 3.
// Omaha 3 runs "GoogleUpdate.exe /healthcheck" and expects an exit code of
// HRESULT SUCCESS, i.e., S_OK, in which case it will hand off the installation
// to Omaha 4.
inline constexpr char kHealthCheckSwitch[] = …;

// Specifies the enterprise request argument. On Windows, the request may
// be from legacy updaters which pass the argument in the format of
// `/enterprise`. Manual argument parsing is needed for that scenario.
inline constexpr char kEnterpriseSwitch[] = …;  // backward-compatibility.

// Specifies that no UI should be shown.
inline constexpr char kSilentSwitch[] = …;  // backward-compatibility.

// The "alwayslaunchcmd" switch specifies that launch commands are to be run
// unconditionally, even for silent modes.
inline constexpr char kAlwaysLaunchCmdSwitch[] = …;

// Specifies the handoff request argument. On Windows, the request may
// be from legacy updaters which pass the argument in the format of
// `/handoff <install-args-details>`. Manual argument parsing is needed for that
// scenario.
inline constexpr char kHandoffSwitch[] = …;  // backward-compatibility.

// Specifies the full path to the offline install resources. The folder
// contains offline installer and the manifest file.
inline constexpr char kOfflineDirSwitch[] = …;  // backward-compatibility.

// Specifies extra app args. The switch must be in the following format:
//     --appargs="appguid=<appid>&installerdata=<URL-encoded-installer-data>"
// On Windows, the request may be from legacy updaters which pass the argument
// in the format of `/appargs <value>`. Manual argument parsing is needed for
// that scenario.
inline constexpr char kAppArgsSwitch[] = …;  // backward-compatibility.

// The "expect-elevated" switch indicates that updater setup should be running
// elevated (at high integrity). This switch is needed to avoid running into a
// loop trying (but failing repeatedly) to elevate updater setup when attempting
// to install on a standard user account with UAC disabled.
inline constexpr char kCmdLineExpectElevated[] = …;

// The "expect-de-elevated" switch indicates that updater setup should be
// running de-elevated (at medium integrity). This switch is needed to avoid
// running into a loop trying (but failing repeatedly) to de-elevate updater
// setup when attempting to install as a standard user account with UAC enabled.
inline constexpr char kCmdLineExpectDeElevated[] = …;

// The "prefers-user" switch indicates that updater setup could not elevate, and
// is now trying to install the app per-user.
inline constexpr char kCmdLinePrefersUser[] = …;

// Environment variables. Defined in the .cc file so that the updater branding
// constants don't leak in this public header.
extern const char kUsageStatsEnabled[];
extern const char kUsageStatsEnabledValueEnabled[];

// File system paths.
//
// The directory name where CRX apps get installed. This is provided for demo
// purposes, since products installed by this updater will be installed in
// their specific locations.
inline constexpr char kAppsDir[] = …;

// The name of the uninstall script which is invoked by the --uninstall switch.
inline constexpr char kUninstallScript[] = …;

// Developer override keys.
inline constexpr char kDevOverrideKeyUrl[] = …;
inline constexpr char kDevOverrideKeyCrashUploadUrl[] = …;
inline constexpr char kDevOverrideKeyDeviceManagementUrl[] = …;
inline constexpr char kDevOverrideKeyAppLogoUrl[] = …;
inline constexpr char kDevOverrideKeyUseCUP[] = …;
inline constexpr char kDevOverrideKeyInitialDelay[] = …;
inline constexpr char kDevOverrideKeyServerKeepAliveSeconds[] = …;
inline constexpr char kDevOverrideKeyCrxVerifierFormat[] = …;
inline constexpr char kDevOverrideKeyGroupPolicies[] = …;
inline constexpr char kDevOverrideKeyOverinstallTimeout[] = …;
inline constexpr char kDevOverrideKeyIdleCheckPeriodSeconds[] = …;
inline constexpr char kDevOverrideKeyManagedDevice[] = …;
inline constexpr char kDevOverrideKeyEnableDiffUpdates[] = …;

// Timing constants.
// How long to wait for an application installer (such as chrome_installer.exe)
// to complete.
inline constexpr base::TimeDelta kWaitForAppInstaller = …;

// How long to wait for the common setup lock for
// AppInstall/AppUninstall/AppUpdate.
inline constexpr base::TimeDelta kWaitForSetupLock = …;

// The default last check period is 4.5 hours.
inline constexpr base::TimeDelta kDefaultLastCheckPeriod = …;

#if BUILDFLAG(IS_WIN)
// How often the installer progress from registry is sampled. This value may
// be changed to provide a smoother progress experience (crbug.com/1067475).
inline constexpr int kWaitForInstallerProgressSec = 1;
#elif BUILDFLAG(IS_MAC)
// How long to wait for launchd changes to be reported by launchctl.
inline constexpr int kWaitForLaunchctlUpdateSec = 5;
#endif  // BUILDFLAG(IS_MAC)

#if BUILDFLAG(IS_MAC)
// The user defaults suite name. Defined in the .cc file so that the updater
// branding constants don't leak in this public header.
extern const char kUserDefaultsSuiteName[];
#endif  // BUILDFLAG(IS_MAC)

// Install Errors.
//
// Specific errors for the updater that are passed through `update_client` are
// reported in such a way that their range does not conflict with the range of
// generic errors defined by the metainstaller, the `update_client` module, or
// Windows.
#if BUILDFLAG(IS_WIN)
inline constexpr int kCustomInstallErrorBase =
    static_cast<int>(update_client::InstallError::CUSTOM_ERROR_BASE) + 74000;
#else
inline constexpr int kCustomInstallErrorBase = …;
#endif

// Running the application installer failed.
inline constexpr int kErrorApplicationInstallerFailed = …;

// The errors below are reported in the `extra_code1` in the
// `CrxInstaller::Result` structure, with the `error` reported as
// `GOOPDATEINSTALL_E_FILENAME_INVALID`. `GOOPDATEINSTALL_E_FILENAME_INVALID` is
// used to avoid overlaps of the specific error codes below with Windows error
// codes.

// The install params are missing. This usually means that the update
// response does not include the name of the installer and its command line
// arguments.
inline constexpr int kErrorMissingInstallParams = …;

// The file extension for the installer is not supported. For instance, on
// Windows, only `.exe` and `.msi` extensions are supported.
inline constexpr int kErrorInvalidFileExtension = …;

// The app command failed to launch. This code is reported in the `extra_code1`
// in the ping, along with the actual error code that caused that launch failure
// in `error`.
inline constexpr int kErrorAppCommandLaunchFailed = …;

// The app command timed out. This code is reported in the `extra_code1` in the
// ping, along with the error code `HRESULT_FROM_WIN32(ERROR_TIMEOUT)` in
// `error`.
inline constexpr int kErrorAppCommandTimedOut = …;

// Specific error codes for the updater are reported in such a way that their
// range does not conflict with the range of generic errors defined by the
// metainstaller, the `update_client` module, or Windows.
#if BUILDFLAG(IS_WIN)
inline constexpr int kUpdaterErrorBase = 75000;
#else
inline constexpr int kUpdaterErrorBase = …;
#endif

// Error codes.
//
// The server process may exit with any of these exit codes.
inline constexpr int kErrorOk = …;

// The server could not acquire the lock needed to run.
inline constexpr int kErrorFailedToLockPrefsMutex = …;

// The server candidate failed to promote itself to active.
inline constexpr int kErrorFailedToSwap = …;

inline constexpr int kErrorRegistrationFailed = …;
inline constexpr int kErrorPermissionDenied = …;
inline constexpr int kErrorWaitFailedUninstall = …;
inline constexpr int kErrorWaitFailedInstall = …;
inline constexpr int kErrorPathServiceFailed = …;
inline constexpr int kErrorComInitializationFailed = …;
inline constexpr int kErrorUnknownCommandLine = …;
inline constexpr int kErrorNoVersionedDirectory = …;
inline constexpr int kErrorNoBaseDirectory = …;
inline constexpr int kErrorPathTooLong = …;
inline constexpr int kErrorProcessLaunchFailed = …;

// Failed to copy the updater's bundle.
inline constexpr int kErrorFailedToCopyBundle = …;

// Failed to delete the updater's install folder.
inline constexpr int kErrorFailedToDeleteFolder = …;

// Failed to delete the updater's data folder.
inline constexpr int kErrorFailedToDeleteDataFolder = …;

// Failed to get versioned updater folder path.
inline constexpr int kErrorFailedToGetVersionedInstallDirectory = …;

// Failed to get the install directory.
inline constexpr int kErrorFailedToGetInstallDir = …;

// Failed to remove the active(unversioned) update service job from Launchd.
inline constexpr int kErrorFailedToRemoveActiveUpdateServiceJobFromLaunchd = …;

// Failed to remove versioned update service job from Launchd.
inline constexpr int kErrorFailedToRemoveCandidateUpdateServiceJobFromLaunchd = …;

// Failed to remove versioned update service internal job from Launchd.
inline constexpr int kErrorFailedToRemoveUpdateServiceInternalJobFromLaunchd = …;

// Failed to remove versioned wake job from Launchd.
inline constexpr int kErrorFailedToRemoveWakeJobFromLaunchd = …;

// Failed to create the active(unversioned) update service Launchd plist.
inline constexpr int kErrorFailedToCreateUpdateServiceLaunchdJobPlist = …;

// Failed to create the versioned update service Launchd plist.
inline constexpr int kErrorFailedToCreateVersionedUpdateServiceLaunchdJobPlist = …;

// Failed to create the versioned update service internal Launchd plist.
inline constexpr int kErrorFailedToCreateUpdateServiceInternalLaunchdJobPlist = …;

// Failed to create the versioned wake Launchd plist.
inline constexpr int kErrorFailedToCreateWakeLaunchdJobPlist = …;

// Failed to start the active(unversioned) update service job.
inline constexpr int kErrorFailedToStartLaunchdActiveServiceJob = …;

// Failed to start the versioned update service job.
inline constexpr int kErrorFailedToStartLaunchdVersionedServiceJob = …;

// Failed to start the update service internal job.
inline constexpr int kErrorFailedToStartLaunchdUpdateServiceInternalJob = …;

// Failed to start the wake job.
inline constexpr int kErrorFailedToStartLaunchdWakeJob = …;

// Timed out while awaiting launchctl to become aware of the update service
// internal job.
inline constexpr int kErrorFailedAwaitingLaunchdUpdateServiceInternalJob = …;

// DM registration failure with mandatory enrollment.
inline constexpr int kErrorDMRegistrationFailed = …;

inline constexpr int kErrorFailedToInstallLegacyUpdater = …;

// A Mojo remote was unexpectedly disconnected.
inline constexpr int kErrorIpcDisconnect = …;

// Failed to copy the updater binary.
inline constexpr int kErrorFailedToCopyBinary = …;

// Failed to delete a socket file.
inline constexpr int kErrorFailedToDeleteSocket = …;

// Failed to create a symlink to the current version.
inline constexpr int kErrorFailedToLinkCurrent = …;

// Failed to rename the current symlink during activation.
inline constexpr int kErrorFailedToRenameCurrent = …;

// Failed to install one or more Systemd units.
inline constexpr int kErrorFailedToInstallSystemdUnit = …;

// Failed to remove one or more Systemd units during uninstallation.
inline constexpr int kErrorFailedToRemoveSystemdUnit = …;

// Running as the wrong user for the provided UpdaterScope.
inline constexpr int kErrorWrongUser = …;

// Failed to get the setup files.
inline constexpr int kErrorFailedToGetSetupFiles = …;

// Failed to run install list.
inline constexpr int kErrorFailedToRunInstallList = …;

// The server was running but had no tasks to do.
inline constexpr int kErrorIdle = …;

// The call was rejected because the user needs to accept the EULA / Terms of
// service.
inline constexpr int kErrorEulaRequired = …;

// The current operating system is not supported.
inline constexpr int kErrorUnsupportedOperatingSystem = …;

inline constexpr int kErrorTagParsing = …;

// Metainstaller errors.
inline constexpr int kErrorCreatingTempDir = …;
inline constexpr int kErrorUnpackingResource = …;
inline constexpr int kErrorInitializingBackupDir = …;

// Launcher errors.
inline constexpr int kErrorGettingUpdaterPath = …;
inline constexpr int kErrorStattingPath = …;
inline constexpr int kErrorLaunchingProcess = …;
inline constexpr int kErrorPathOwnershipMismatch = …;

// A setup process could not acquire the lock needed to run.
inline constexpr int kErrorFailedToLockSetupMutex = …;

// Cannot establish a Mojo connection.
inline constexpr int kErrorMojoConnectionFailure = …;

// Mojo server rejected the request.
inline constexpr int kErrorMojoRequestRejected = …;

// Cannot find the console user, for example when the user is not logged on.
inline constexpr int kErrorNoConsoleUser = …;

// Failed to fetch enterprise policies.
inline constexpr int kErrorPolicyFetchFailed = …;

// Policy Management constants.
// The maximum value allowed for policy AutoUpdateCheckPeriodMinutes.
inline constexpr int kMaxAutoUpdateCheckPeriodMinutes = …;

// The maximum value allowed for policy UpdatesSuppressedDurationMin.
inline constexpr int kMaxUpdatesSuppressedDurationMinutes = …;

inline constexpr char kProxyModeDirect[] = …;
inline constexpr char kProxyModeAutoDetect[] = …;
inline constexpr char kProxyModePacScript[] = …;
inline constexpr char kProxyModeFixedServers[] = …;
inline constexpr char kProxyModeSystem[] = …;

inline constexpr char kDownloadPreferenceCacheable[] = …;

// UTF8 byte order mark (BOM) used to prefix the contents of the installerdata
// file.
inline constexpr char kUTF8BOM[] = …;

inline constexpr int kPolicyNotSet = …;
inline constexpr int kPolicyDisabled = …;
inline constexpr int kPolicyEnabled = …;
inline constexpr int kPolicyEnabledMachineOnly = …;
inline constexpr int kPolicyManualUpdatesOnly = …;
inline constexpr int kPolicyAutomaticUpdatesOnly = …;
inline constexpr int kPolicyForceInstallMachine = …;
inline constexpr int kPolicyForceInstallUser = …;

inline constexpr bool kInstallPolicyDefault = …;
inline constexpr bool kUpdatePolicyDefault = …;

// Policy manager `source()` constants.
inline constexpr char kSourceGroupPolicyManager[] = …;
inline constexpr char kSourceDMPolicyManager[] = …;
inline constexpr char kSourceManagedPreferencePolicyManager[] = …;
inline constexpr char kSourceDefaultValuesPolicyManager[] = …;
inline constexpr char kSourceDictValuesPolicyManager[] = …;

// Serializes updater installs. Defined in the .cc file so that the updater
// branding constants don't leak in this public header.
extern const char kSetupMutex[];

inline constexpr int kUninstallPingReasonUninstalled = …;
inline constexpr int kUninstallPingReasonUserNotAnOwner = …;
inline constexpr int kUninstallPingReasonNoAppsRemain = …;
inline constexpr int kUninstallPingReasonNeverHadApps = …;

// The file downloaded to a temporary location could not be moved.
inline constexpr int kErrorFailedToMoveDownloadedFile = …;

// Error occurred during file writing.
inline constexpr int kErrorFailedToWriteFile = …;

inline constexpr base::TimeDelta kInitialDelay = …;
inline constexpr base::TimeDelta kServerKeepAliveTime = …;

// The maximum number of server starts before the updater uninstalls itself
// while waiting for the first app registration.
inline constexpr int kMaxServerStartsBeforeFirstReg = …;

// Number of tries when an installer returns `ERROR_INSTALL_ALREADY_RUNNING`.
inline constexpr int kNumAlreadyRunningMaxTries = …;

// Initial delay between retries when an installer returns
// `ERROR_INSTALL_ALREADY_RUNNING`.
inline constexpr base::TimeDelta kAlreadyRunningRetryInitialDelay = …;

// These are GoogleUpdate error codes, which must be retained by this
// implementation in order to be backward compatible with the existing update
// client code in Chrome.
inline constexpr int GOOPDATE_E_APP_INSTALL_DISABLED_BY_POLICY = …;
inline constexpr int GOOPDATE_E_APP_UPDATE_DISABLED_BY_POLICY = …;
inline constexpr int GOOPDATE_E_APP_UPDATE_DISABLED_BY_POLICY_MANUAL = …;
inline constexpr int GOOPDATEINSTALL_E_FILENAME_INVALID = …;
inline constexpr int GOOPDATEINSTALL_E_INSTALLER_FAILED_START = …;
inline constexpr int GOOPDATEINSTALL_E_INSTALLER_FAILED = …;
inline constexpr int GOOPDATEINSTALL_E_INSTALLER_TIMED_OUT = …;
inline constexpr int GOOPDATEINSTALL_E_INSTALL_ALREADY_RUNNING = …;

// Install Sources.
inline constexpr char kInstallSourceTaggedMetainstaller[] = …;
inline constexpr char kInstallSourceOffline[] = …;
inline constexpr char kInstallSourcePolicy[] = …;
inline constexpr char kInstallSourceOnDemand[] = …;

}  // namespace updater

#endif  // CHROME_UPDATER_CONSTANTS_H_