// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// developerPrivate API.
// This is a private API exposing developing and debugging functionalities for
// apps and extensions.
namespace developerPrivate {
// DEPRECATED: Prefer ExtensionType.
enum ItemType {
hosted_app,
packaged_app,
legacy_packaged_app,
extension,
theme
};
// DEPRECATED: Prefer ExtensionView.
dictionary ItemInspectView {
// path to the inspect page.
DOMString path;
// For lazy background pages, the value is -1.
long render_process_id;
// This actually refers to a render frame.
long render_view_id;
boolean incognito;
boolean generatedBackgroundPage;
};
// DEPRECATED: Use OpenDevTools.
dictionary InspectOptions {
DOMString extension_id;
(DOMString or long) render_process_id;
(DOMString or long) render_view_id;
boolean incognito;
};
dictionary InstallWarning {
DOMString message;
};
enum ExtensionType {
HOSTED_APP,
PLATFORM_APP,
LEGACY_PACKAGED_APP,
EXTENSION,
THEME,
SHARED_MODULE
};
enum Location {
FROM_STORE,
UNPACKED,
THIRD_PARTY,
INSTALLED_BY_DEFAULT,
// "Unknown" includes crx's installed from chrome://extensions.
UNKNOWN
};
enum ViewType {
APP_WINDOW,
BACKGROUND_CONTENTS,
COMPONENT,
EXTENSION_BACKGROUND_PAGE,
EXTENSION_GUEST,
EXTENSION_POPUP,
EXTENSION_SERVICE_WORKER_BACKGROUND,
TAB_CONTENTS,
OFFSCREEN_DOCUMENT,
EXTENSION_SIDE_PANEL,
DEVELOPER_TOOLS
};
enum ErrorType {
MANIFEST,
RUNTIME
};
enum ErrorLevel {
LOG,
WARN,
ERROR
};
enum ExtensionState {
ENABLED,
DISABLED,
TERMINATED,
BLOCKLISTED
};
enum CommandScope {
GLOBAL,
CHROME
};
enum SafetyCheckWarningReason {
UNPUBLISHED,
POLICY,
MALWARE,
OFFSTORE,
UNWANTED,
NO_PRIVACY_PRACTICE
};
dictionary AccessModifier {
boolean isEnabled;
boolean isActive;
};
dictionary StackFrame {
long lineNumber;
long columnNumber;
DOMString url;
DOMString functionName;
};
dictionary ManifestError {
ErrorType type;
DOMString extensionId;
boolean fromIncognito;
DOMString source;
DOMString message;
long id;
DOMString manifestKey;
DOMString? manifestSpecific;
};
dictionary RuntimeError {
ErrorType type;
DOMString extensionId;
boolean fromIncognito;
DOMString source;
DOMString message;
long id;
ErrorLevel severity;
DOMString contextUrl;
long occurrences;
long renderViewId;
long renderProcessId;
boolean canInspect;
StackFrame[] stackTrace;
};
dictionary DisableReasons {
boolean suspiciousInstall;
boolean corruptInstall;
boolean updateRequired;
boolean publishedInStoreRequired;
boolean blockedByPolicy;
boolean reloading;
boolean custodianApprovalRequired;
boolean parentDisabledPermissions;
boolean unsupportedManifestVersion;
};
dictionary OptionsPage {
boolean openInTab;
DOMString url;
};
dictionary HomePage {
DOMString url;
boolean specified;
};
dictionary ExtensionView {
DOMString url;
long renderProcessId;
// This actually refers to a render frame.
long renderViewId;
boolean incognito;
boolean isIframe;
ViewType type;
};
enum HostAccess {
ON_CLICK,
ON_SPECIFIC_SITES,
ON_ALL_SITES
};
dictionary SafetyCheckStrings {
DOMString? panelString;
DOMString? detailString;
};
dictionary ControlledInfo {
DOMString text;
};
dictionary Command {
DOMString description;
DOMString keybinding;
DOMString name;
boolean isActive;
CommandScope scope;
boolean isExtensionAction;
};
dictionary DependentExtension {
DOMString id;
DOMString name;
};
dictionary Permission {
DOMString message;
DOMString[] submessages;
};
dictionary SiteControl {
// The host pattern for the site.
DOMString host;
// Whether the pattern has been granted.
boolean granted;
};
dictionary RuntimeHostPermissions {
// True if |hosts| contains an all hosts like pattern.
boolean hasAllHosts;
// The current HostAccess setting for the extension.
HostAccess hostAccess;
// The site controls for all granted and requested patterns.
SiteControl[] hosts;
};
dictionary Permissions {
Permission[] simplePermissions;
// Only populated for extensions that can be affected by the runtime host
// permissions feature.
RuntimeHostPermissions? runtimeHostPermissions;
// True if the extension can access site data through host permissions or
// API permissions such as activeTab.
boolean canAccessSiteData;
};
dictionary ExtensionInfo {
DOMString? blocklistText;
SafetyCheckStrings? safetyCheckText;
Command[] commands;
ControlledInfo? controlledInfo;
DependentExtension[] dependentExtensions;
DOMString description;
DisableReasons disableReasons;
AccessModifier errorCollection;
AccessModifier fileAccess;
HomePage homePage;
DOMString iconUrl;
DOMString id;
AccessModifier incognitoAccess;
DOMString[] installWarnings;
DOMString? launchUrl;
Location location;
DOMString? locationText;
ManifestError[] manifestErrors;
DOMString manifestHomePageUrl;
boolean mustRemainInstalled;
DOMString name;
boolean offlineEnabled;
OptionsPage? optionsPage;
DOMString? path;
Permissions permissions;
DOMString? prettifiedPath;
DOMString? recommendationsUrl;
RuntimeError[] runtimeErrors;
DOMString[] runtimeWarnings;
ExtensionState state;
ExtensionType type;
DOMString updateUrl;
boolean userMayModify;
DOMString version;
ExtensionView[] views;
DOMString webStoreUrl;
boolean showSafeBrowsingAllowlistWarning;
SafetyCheckWarningReason? safetyCheckWarningReason;
boolean showAccessRequestsInToolbar;
boolean? pinnedToToolbar;
boolean isAffectedByMV2Deprecation;
boolean didAcknowledgeMV2DeprecationNotice;
};
dictionary ProfileInfo {
boolean canLoadUnpacked;
boolean inDeveloperMode;
boolean isDeveloperModeControlledByPolicy;
boolean isIncognitoAvailable;
boolean isChildAccount;
boolean isMv2DeprecationNoticeDismissed;
};
// DEPRECATED: Prefer ExtensionInfo.
dictionary ItemInfo {
DOMString id;
DOMString name;
DOMString version;
DOMString description;
boolean may_disable;
boolean enabled;
boolean isApp;
ItemType type;
boolean allow_activity;
boolean allow_file_access;
boolean wants_file_access;
boolean incognito_enabled;
boolean is_unpacked;
boolean allow_reload;
boolean terminated;
boolean allow_incognito;
DOMString icon_url;
// Path of an unpacked extension.
DOMString? path;
// Options settings page for the item.
DOMString? options_url;
DOMString? app_launch_url;
DOMString? homepage_url;
DOMString? update_url;
InstallWarning[] install_warnings;
any[] manifest_errors;
any[] runtime_errors;
boolean offline_enabled;
// All views of the current extension.
ItemInspectView[] views;
};
dictionary GetExtensionsInfoOptions {
boolean? includeDisabled;
boolean? includeTerminated;
};
dictionary ExtensionConfigurationUpdate {
DOMString extensionId;
boolean? fileAccess;
boolean? incognitoAccess;
boolean? errorCollection;
HostAccess? hostAccess;
boolean? showAccessRequestsInToolbar;
SafetyCheckWarningReason? acknowledgeSafetyCheckWarningReason;
boolean? acknowledgeSafetyCheckWarning;
boolean? pinnedToToolbar;
};
dictionary ProfileConfigurationUpdate {
boolean? inDeveloperMode;
boolean? isMv2DeprecationNoticeDismissed;
};
dictionary ExtensionCommandUpdate {
DOMString extensionId;
DOMString commandName;
CommandScope? scope;
DOMString? keybinding;
};
dictionary ReloadOptions {
// If false, an alert dialog will show in the event of a reload error.
// Defaults to false.
boolean? failQuietly;
// If true, populates a LoadError for the response rather than setting
// lastError. Only relevant for unpacked extensions; it will be ignored for
// any other extension.
boolean? populateErrorForUnpacked;
};
dictionary LoadUnpackedOptions {
// If false, an alert dialog will show in the event of a reload error.
// Defaults to false.
boolean? failQuietly;
// If true, populates a LoadError for the response rather than setting
// lastError.
boolean? populateError;
// A unique identifier for retrying a previous failed load. This should be
// the identifier returned in the LoadError. If specified, the path
// associated with the identifier will be loaded, and the file chooser
// will be skipped.
DOMString? retryGuid;
// True if the function should try to load an extension from the drop data
// of the page. notifyDragInstallInProgress() needs to be called prior to
// this being used. This cannot be used with |retryGuid|.
boolean? useDraggedPath;
};
// Describes which set of sites a given url/string is associated with. Note
// that a site can belong to multiple sets at the same time.
enum SiteSet {
// The site is specified by the user to automatically grant access to all
// extensions with matching host permissions. Mutually exclusive with
// USER_RESTRICTED but takes precedence over EXTENSION_SPECIFIED.
USER_PERMITTED,
// The site is specified by the user to disallow all extensions from running
// on it. Mutually exclusive with USER_PERMITTED but takes precedence over
// EXTENSION_SPECIFIED.
USER_RESTRICTED,
// The site is specified by one or more extensions' set of host permissions.
EXTENSION_SPECIFIED
};
dictionary UserSiteSettingsOptions {
// Specifies which set of user specified sites that the host will be added
// to or removed from.
SiteSet siteSet;
// The sites to add/remove.
DOMString[] hosts;
};
dictionary UserSiteSettings {
// The list of origins where the user has allowed all extensions to run on.
DOMString[] permittedSites;
// The list of origins where the user has blocked all extensions from
// running on.
DOMString[] restrictedSites;
};
dictionary SiteInfo {
// The site set that `site` belongs to.
SiteSet siteSet;
// The number of extensions with access to `site`.
// TODO(crbug.com/40227416): A tricky edge case is when one extension
// specifies something like *.foo.com and another specifies foo.com.
// Patterns which match all subdomains should be represented differently.
long numExtensions;
// The site itself. This could either be a user specified site or an
// extension host permission pattern.
DOMString site;
};
dictionary SiteGroup {
// The common effective top level domain plus one (eTLD+1) for all sites in
// `sites`.
DOMString etldPlusOne;
// The number of extensions that can run on at least one site inside `sites`
// for this eTLD+1.
long numExtensions;
// The list of user or extension specified sites that share the same eTLD+1.
SiteInfo[] sites;
};
dictionary MatchingExtensionInfo {
// The id of the matching extension.
DOMString id;
// Describes the extension's access to the queried site from
// getMatchingExtensionsForSite. Note that the meaning is different from the
// original enum:
// - ON_CLICK: The extension requested access to the site but its access is
// withheld.
// - ON_SPECIFIC_SITES: the extension is permitted to run on at least one
// site specified by the queried site but it does not request access to
// all sites or it has its access withheld on at least one site in its
// host permissions.
// - ON_ALL_SITES: the extension is permitted to run on all sites.
HostAccess siteAccess;
// Whether the matching extension requests access to all sites in its
// host permissions.
boolean canRequestAllSites;
};
dictionary ExtensionSiteAccessUpdate {
// The id of the extension to update its site access settings for.
DOMString id;
// Describes the update made to the extension's site access for a given site
// Note that this has a different meaning from the original enum:
// - ON_CLICK: Withholds the extension's access to the given site,
// - ON_SPECIFIC_SITES: Grants the extension access to the intersection of
// (given site, extension's specified host permissions.)
// - ON_ALL_SITES: Grants access to all of the extension's specified host
// permissions.
HostAccess siteAccess;
};
enum PackStatus {
SUCCESS,
ERROR,
WARNING
};
enum FileType {
LOAD,
PEM
};
enum SelectType {
FILE,
FOLDER
};
enum EventType {
INSTALLED,
UNINSTALLED,
LOADED,
UNLOADED,
// New window / view opened.
VIEW_REGISTERED,
// window / view closed.
VIEW_UNREGISTERED,
ERROR_ADDED,
ERRORS_REMOVED,
PREFS_CHANGED,
WARNINGS_CHANGED,
COMMAND_ADDED,
COMMAND_REMOVED,
PERMISSIONS_CHANGED,
SERVICE_WORKER_STARTED,
SERVICE_WORKER_STOPPED,
CONFIGURATION_CHANGED,
PINNED_ACTIONS_CHANGED
};
dictionary PackDirectoryResponse {
// The response message of success or error.
DOMString message;
// Unpacked items's path.
DOMString item_path;
// Permanent key path.
DOMString pem_path;
long override_flags;
PackStatus status;
};
dictionary ProjectInfo {
DOMString name;
};
dictionary EventData {
EventType event_type;
DOMString item_id;
ExtensionInfo? extensionInfo;
};
dictionary ErrorFileSource {
// The region before the "highlight" portion.
// If the region which threw the error was not found, the full contents of
// the file will be in the "beforeHighlight" section.
DOMString beforeHighlight;
// The region of the code which threw the error, and should be highlighted.
DOMString highlight;
// The region after the "highlight" portion.
DOMString afterHighlight;
};
dictionary LoadError {
// The error that occurred when trying to load the extension.
DOMString error;
// The path to the extension.
DOMString path;
// The file source for the error, if it could be retrieved.
ErrorFileSource? source;
// A unique identifier to pass to developerPrivate.loadUnpacked to retry
// loading the extension at the same path.
DOMString retryGuid;
};
dictionary RequestFileSourceProperties {
// The ID of the extension owning the file.
DOMString extensionId;
// The path of the file, relative to the extension; e.g., manifest.json,
// script.js, or main.html.
DOMString pathSuffix;
// The error message which was thrown as a result of the error in the file.
DOMString message;
// The key in the manifest which caused the error (e.g., "permissions").
// (Required for "manifest.json" files)
DOMString? manifestKey;
// The specific portion of the manifest key which caused the error (e.g.,
// "foo" in the "permissions" key). (Optional for "manifest.json" file).
DOMString? manifestSpecific;
// The line number which caused the error (optional for non-manifest files).
long? lineNumber;
};
dictionary RequestFileSourceResponse {
// The region of the code which threw the error, and should be highlighted.
DOMString highlight;
// The region before the "highlight" portion.
// If the region which threw the error was not found, the full contents of
// the file will be in the "beforeHighlight" section.
DOMString beforeHighlight;
// The region after the "highlight" portion.
DOMString afterHighlight;
// A title for the file in the form '<extension name>: <file name>'.
DOMString title;
// The error message.
DOMString message;
};
dictionary OpenDevToolsProperties {
// The ID of the extension. This is only needed if opening its background
// page or its background service worker (where renderViewId and
// renderProcessId are -1).
DOMString? extensionId;
// The ID of the render frame in which the error occurred.
// Despite being called renderViewId, this refers to a render frame.
long renderViewId;
// The ID of the process in which the error occurred.
long renderProcessId;
// Whether or not the background is service worker based.
boolean? isServiceWorker;
boolean? incognito;
// The URL in which the error occurred.
DOMString? url;
// The line to focus the devtools at.
long? lineNumber;
// The column to focus the devtools at.
long? columnNumber;
};
dictionary DeleteExtensionErrorsProperties {
DOMString extensionId;
long[]? errorIds;
ErrorType? type;
};
callback VoidCallback = void ();
callback BooleanCallback = void (boolean result);
callback ExtensionInfosCallback = void (ExtensionInfo[] result);
callback ExtensionInfoCallback = void (ExtensionInfo result);
callback ItemsInfoCallback = void (ItemInfo[] result);
callback ProfileInfoCallback = void (ProfileInfo info);
callback GetProjectsInfoCallback = void (ProjectInfo[] result);
callback PackCallback = void (PackDirectoryResponse response);
callback StringCallback = void (DOMString string);
callback RequestFileSourceCallback =
void (RequestFileSourceResponse response);
callback LoadErrorCallback = void (optional LoadError error);
callback DragInstallInProgressCallback = void (DOMString loadGuid);
callback UserSiteSettingsCallback = void (UserSiteSettings settings);
callback UserAndExtensionSitesByEtldCallback = void (SiteGroup[] siteGroups);
callback GetMatchingExtensionsForSiteCallback =
void (MatchingExtensionInfo[] matchingExtensions);
interface Functions {
// Runs auto update for extensions and apps immediately.
// |callback| : Called after update check completes.
static void autoUpdate(optional VoidCallback callback);
// Returns information of all the extensions and apps installed.
// |options| : Options to restrict the items returned.
// |callback| : Called with extensions info.
static void getExtensionsInfo(
optional GetExtensionsInfoOptions options,
optional ExtensionInfosCallback callback);
// Returns information of a particular extension.
// |id| : The id of the extension.
// |callback| : Called with the result.
static void getExtensionInfo(
DOMString id,
optional ExtensionInfoCallback callback);
// Returns the size of a particular extension on disk (already formatted).
// |id| : The id of the extension.
// |callback| : Called with the result.
static void getExtensionSize(
DOMString id,
StringCallback callback);
// Returns the current profile's configuration.
static void getProfileConfiguration(
ProfileInfoCallback callback);
// Updates the active profile.
// |update| : The parameters for updating the profile's configuration. Any
// properties omitted from |update| will not be changed.
static void updateProfileConfiguration(
ProfileConfigurationUpdate update,
optional VoidCallback callback);
// Reloads a given extension.
// |extensionId| : The id of the extension to reload.
// |options| : Additional configuration parameters.
static void reload(
DOMString extensionId,
optional ReloadOptions options,
optional LoadErrorCallback callback);
// Modifies an extension's current configuration.
// |update| : The parameters for updating the extension's configuration.
// Any properties omitted from |update| will not be changed.
static void updateExtensionConfiguration(
ExtensionConfigurationUpdate update,
optional VoidCallback callback);
// Loads a user-selected unpacked item.
// |options| : Additional configuration parameters.
static void loadUnpacked(
optional LoadUnpackedOptions options,
optional LoadErrorCallback callback);
// Installs the file that was dragged and dropped onto the associated
// page.
static void installDroppedFile(
optional VoidCallback callback);
// Notifies the browser that a user began a drag in order to install an
// extension.
static void notifyDragInstallInProgress();
// Loads an extension / app.
// |directory| : The directory to load the extension from.
static void loadDirectory(
[instanceOf=DirectoryEntry] object directory,
StringCallback callback);
// Open Dialog to browse to an entry.
// |selectType| : Select a file or a folder.
// |fileType| : Required file type. For example, pem type is for private
// key and load type is for an unpacked item.
// |callback| : called with selected item's path.
static void choosePath(
SelectType selectType,
FileType fileType,
StringCallback callback);
// Pack an extension.
// |rootPath| : The path of the extension.
// |privateKeyPath| : The path of the private key, if one is given.
// |flags| : Special flags to apply to the loading process, if any.
// |callback| : called with the success result string.
static void packDirectory(
DOMString path,
optional DOMString privateKeyPath,
optional long flags,
optional PackCallback callback);
// Returns true if the profile is managed.
static void isProfileManaged(BooleanCallback callback);
// Reads and returns the contents of a file related to an extension which
// caused an error.
static void requestFileSource(
RequestFileSourceProperties properties,
RequestFileSourceCallback callback);
// Open the developer tools to focus on a particular error.
static void openDevTools(
OpenDevToolsProperties properties,
optional VoidCallback callback);
// Delete reported extension errors.
// |properties| : The properties specifying the errors to remove.
static void deleteExtensionErrors(
DeleteExtensionErrorsProperties properties,
optional VoidCallback callback);
// Repairs the extension specified.
// |extensionId| : The id of the extension to repair.
static void repairExtension(
DOMString extensionId,
optional VoidCallback callback);
// Shows the options page for the extension specified.
// |extensionId| : The id of the extension to show the options page for.
static void showOptions(
DOMString extensionId,
optional VoidCallback callback);
// Shows the path of the extension specified.
// |extensionId| : The id of the extension to show the path for.
static void showPath(
DOMString extensionId,
optional VoidCallback callback);
// (Un)suspends global shortcut handling.
// |isSuspended| : Whether or not shortcut handling should be suspended.
static void setShortcutHandlingSuspended(
boolean isSuspended,
optional VoidCallback callback);
// Updates an extension command.
// |update| : The parameters for updating the extension command.
static void updateExtensionCommand(
ExtensionCommandUpdate update,
optional VoidCallback callback);
// Adds a new host permission to the extension. The extension will only
// have access to the host if it is within the requested permissions.
// |extensionId|: The id of the extension to modify.
// |host|: The host to add.
static void addHostPermission(
DOMString extensionId,
DOMString host,
optional VoidCallback callback);
// Removes a host permission from the extension. This should only be called
// with a host that the extension has access to.
// |extensionId|: The id of the extension to modify.
// |host|: The host to remove.
static void removeHostPermission(
DOMString extensionId,
DOMString host,
optional VoidCallback callback);
// Returns the user specified site settings (which origins can extensions
// always/never run on) for the current profile.
static void getUserSiteSettings(
UserSiteSettingsCallback callback);
// Adds hosts to the set of user permitted or restricted sites. If any hosts
// are in the other set than what's specified in `options`, then they are
// removed from that set.
static void addUserSpecifiedSites(
UserSiteSettingsOptions options,
optional VoidCallback callback);
// Removes hosts from the specified set of user permitted or restricted
// sites.
static void removeUserSpecifiedSites(
UserSiteSettingsOptions options,
optional VoidCallback callback);
// Returns all hosts specified by user site settings, grouped by each host's
// eTLD+1.
static void getUserAndExtensionSitesByEtld(
UserAndExtensionSitesByEtldCallback callback);
// Returns a list of extensions which have at least one matching site in
// common between its set of host permissions and `site`.
static void getMatchingExtensionsForSite(
DOMString site,
GetMatchingExtensionsForSiteCallback callback);
// Updates the site access settings for multiple extensions for the given
// `site` and calls `callback` once all updates have been finished.
// Each update species an extension id an a new HostAccess setting.
static void updateSiteAccess(
DOMString site,
ExtensionSiteAccessUpdate[] updates,
optional VoidCallback callback);
// Removes multiple installed extensions.
static void removeMultipleExtensions(
DOMString[] extensionIds,
optional VoidCallback callback);
// Dismisses the menu notification for the extensions module in Safety Hub
// if one is active.
static void dismissSafetyHubExtensionsMenuNotification();
// Triggers the dismissal of the mv2 deprecation notice for `extensionId`.
static void dismissMv2DeprecationNoticeForExtension(DOMString extensionId);
[nocompile, deprecated="Use openDevTools"]
static void inspect(InspectOptions options,
optional VoidCallback callback);
};
interface Events {
// Fired when a item state is changed.
static void onItemStateChanged(EventData response);
// Fired when the profile's state has changed.
static void onProfileStateChanged(ProfileInfo info);
// Fired when the lists of sites in the user's site settings have changed.
static void onUserSiteSettingsChanged(UserSiteSettings settings);
};
};
Codebase Browser
chromium