blob: 2cd288d662be3107f73bc2e5cfeefa55f87eca5d [file] [log] [blame]
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// 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,
// "Unknown" includes crx's installed from chrome://extensions.
UNKNOWN
};
enum ViewType {
APP_WINDOW,
BACKGROUND_CONTENTS,
COMPONENT,
EXTENSION_BACKGROUND_PAGE,
EXTENSION_DIALOG,
EXTENSION_GUEST,
EXTENSION_POPUP,
TAB_CONTENTS
};
enum ErrorType {
MANIFEST,
RUNTIME
};
enum ErrorLevel {
LOG,
WARN,
ERROR
};
enum ExtensionState {
ENABLED,
DISABLED,
TERMINATED,
BLACKLISTED
};
enum CommandScope {
GLOBAL,
CHROME
};
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;
};
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 ControllerType {
POLICY,
CHILD_CUSTODIAN,
SUPERVISED_USER_CUSTODIAN
};
enum HostAccess {
ON_CLICK,
ON_SPECIFIC_SITES,
ON_ALL_SITES
};
dictionary ControlledInfo {
ControllerType type;
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;
};
dictionary ExtensionInfo {
DOMString? blacklistText;
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;
RuntimeError[] runtimeErrors;
DOMString[] runtimeWarnings;
ExtensionState state;
ExtensionType type;
DOMString updateUrl;
boolean userMayModify;
DOMString version;
ExtensionView[] views;
DOMString webStoreUrl;
};
dictionary ProfileInfo {
boolean appInfoDialogEnabled;
boolean canLoadUnpacked;
boolean inDeveloperMode;
boolean isDeveloperModeControlledByPolicy;
boolean isIncognitoAvailable;
boolean isSupervised;
};
// 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;
};
dictionary ProfileConfigurationUpdate {
boolean? inDeveloperMode;
};
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;
};
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
};
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 the background
// page (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;
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);
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 information of all the extensions and apps installed.
// |includeDisabled| : include disabled items.
// |includeTerminated| : include terminated items.
// |callback| : Called with items info.
[deprecated="Use getExtensionsInfo"] static void getItemsInfo(
boolean includeDisabled,
boolean includeTerminated,
ItemsInfoCallback 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);
// Opens a permissions dialog.
// |extensionId| : The id of the extension to show permissions for.
static void showPermissionsDialog(DOMString extensionId,
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);
[nocompile, deprecated="Use management.setEnabled"]
static void enable(DOMString id,
boolean enabled,
optional VoidCallback callback);
[nocompile, deprecated="Use updateExtensionConfiguration"]
static void allowIncognito(DOMString extensionId,
boolean allow,
optional VoidCallback callback);
[nocompile, deprecated="Use updateExtensionConfiguration"]
static void allowFileAccess(DOMString extensionId,
boolean allow,
optional VoidCallback callback);
[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);
};
};