chrome/common/extensions/api/developer_private.idl

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // developerPrivate API.
   6 // This is a private API exposing developing and debugging functionalities for
   7 // apps and extensions.
   8 namespace developerPrivate {
   9
  10   // DEPRECATED: Prefer ExtensionType.
  11   enum ItemType {
  12     hosted_app,
  13     packaged_app,
  14     legacy_packaged_app,
  15     extension,
  16     theme
  17   };
  18
  19   // DEPRECATED: Prefer ExtensionView.
  20   dictionary ItemInspectView {
  21     // path to the inspect page.
  22     DOMString path;
  23
  24     // For lazy background pages, the value is -1.
  25     long render_process_id;
  26     // This actually refers to a render frame.
  27     long render_view_id;
  28
  29     boolean incognito;
  30     boolean generatedBackgroundPage;
  31   };
  32
  33   // DEPRECATED: Use OpenDevTools.
  34   dictionary InspectOptions {
  35     DOMString extension_id;
  36     (DOMString or long) render_process_id;
  37     (DOMString or long) render_view_id;
  38     boolean incognito;
  39   };
  40
  41   dictionary InstallWarning {
  42     DOMString message;
  43   };
  44
  45   enum ExtensionType {
  46     HOSTED_APP,
  47     PLATFORM_APP,
  48     LEGACY_PACKAGED_APP,
  49     EXTENSION,
  50     THEME,
  51     SHARED_MODULE
  52   };
  53
  54   enum Location {
  55     FROM_STORE,
  56     UNPACKED,
  57     THIRD_PARTY,
  58     // "Unknown" includes crx's installed from chrome://extensions.
  59     UNKNOWN
  60   };
  61
  62   enum ViewType {
  63     APP_WINDOW,
  64     BACKGROUND_CONTENTS,
  65     EXTENSION_BACKGROUND_PAGE,
  66     EXTENSION_DIALOG,
  67     EXTENSION_POPUP,
  68     LAUNCHER_PAGE,
  69     PANEL,
  70     TAB_CONTENTS,
  71     VIRTUAL_KEYBOARD
  72   };
  73
  74   enum ErrorType {
  75     MANIFEST,
  76     RUNTIME
  77   };
  78
  79   enum ErrorLevel {
  80     LOG,
  81     WARN,
  82     ERROR
  83   };
  84
  85   enum ExtensionState {
  86     ENABLED,
  87     DISABLED,
  88     TERMINATED
  89   };
  90
  91   enum CommandScope {
  92     GLOBAL,
  93     CHROME
  94   };
  95
  96   dictionary AccessModifier {
  97     boolean isEnabled;
  98     boolean isActive;
  99   };
 100
 101   dictionary StackFrame {
 102     long lineNumber;
 103     long columnNumber;
 104     DOMString url;
 105     DOMString functionName;
 106   };
 107
 108   dictionary ManifestError {
 109     ErrorType type;
 110     DOMString extensionId;
 111     boolean fromIncognito;
 112     DOMString source;
 113     DOMString message;
 114     long id;
 115     DOMString manifestKey;
 116     DOMString? manifestSpecific;
 117   };
 118
 119   dictionary RuntimeError {
 120     ErrorType type;
 121     DOMString extensionId;
 122     boolean fromIncognito;
 123     DOMString source;
 124     DOMString message;
 125     long id;
 126     ErrorLevel severity;
 127     DOMString contextUrl;
 128     long occurrences;
 129     long renderViewId;
 130     long renderProcessId;
 131     boolean canInspect;
 132     StackFrame[] stackTrace;
 133   };
 134
 135   dictionary DisableReasons {
 136     boolean suspiciousInstall;
 137     boolean corruptInstall;
 138     boolean updateRequired;
 139   };
 140
 141   dictionary OptionsPage {
 142     boolean openInTab;
 143     DOMString url;
 144   };
 145
 146   dictionary HomePage {
 147     DOMString url;
 148     boolean specified;
 149   };
 150
 151   dictionary ExtensionView {
 152     DOMString url;
 153     long renderProcessId;
 154     // This actually refers to a render frame.
 155     long renderViewId;
 156     boolean incognito;
 157     ViewType type;
 158   };
 159
 160   enum ControllerType {
 161     POLICY,
 162     CHILD_CUSTODIAN,
 163     SUPERVISED_USER_CUSTODIAN
 164   };
 165
 166   dictionary ControlledInfo {
 167     ControllerType type;
 168     DOMString text;
 169   };
 170
 171   dictionary Command {
 172     DOMString description;
 173     DOMString keybinding;
 174     DOMString name;
 175     boolean isActive;
 176     CommandScope scope;
 177     boolean isExtensionAction;
 178   };
 179
 180   dictionary ExtensionInfo {
 181     boolean actionButtonHidden;
 182     DOMString? blacklistText;
 183     Command[] commands;
 184     ControlledInfo? controlledInfo;
 185     DOMString[] dependentExtensions;
 186     DOMString description;
 187     DisableReasons disableReasons;
 188     AccessModifier errorCollection;
 189     AccessModifier fileAccess;
 190     HomePage homePage;
 191     DOMString iconUrl;
 192     DOMString id;
 193     AccessModifier incognitoAccess;
 194     DOMString[] installWarnings;
 195     DOMString? launchUrl;
 196     Location location;
 197     DOMString? locationText;
 198     ManifestError[] manifestErrors;
 199     boolean mustRemainInstalled;
 200     DOMString name;
 201     boolean offlineEnabled;
 202     OptionsPage? optionsPage;
 203     DOMString? path;
 204     DOMString? prettifiedPath;
 205     AccessModifier runOnAllUrls;
 206     RuntimeError[] runtimeErrors;
 207     DOMString[] runtimeWarnings;
 208     ExtensionState state;
 209     ExtensionType type;
 210     DOMString updateUrl;
 211     boolean userMayModify;
 212     DOMString version;
 213     ExtensionView[] views;
 214   };
 215
 216   dictionary ProfileInfo {
 217     boolean appInfoDialogEnabled;
 218     boolean canLoadUnpacked;
 219     boolean inDeveloperMode;
 220     boolean isIncognitoAvailable;
 221     boolean isSupervised;
 222   };
 223
 224   // DEPRECATED: Prefer ExtensionInfo.
 225   dictionary ItemInfo {
 226     DOMString id;
 227     DOMString name;
 228     DOMString version;
 229     DOMString description;
 230     boolean may_disable;
 231     boolean enabled;
 232     boolean isApp;
 233     ItemType type;
 234     boolean allow_activity;
 235     boolean allow_file_access;
 236     boolean wants_file_access;
 237     boolean incognito_enabled;
 238     boolean is_unpacked;
 239     boolean allow_reload;
 240     boolean terminated;
 241     boolean allow_incognito;
 242     DOMString icon_url;
 243
 244     // Path of an unpacked extension.
 245     DOMString? path;
 246
 247     // Options settings page for the item.
 248     DOMString? options_url;
 249     DOMString? app_launch_url;
 250     DOMString? homepage_url;
 251     DOMString? update_url;
 252     InstallWarning[] install_warnings;
 253     any[] manifest_errors;
 254     any[] runtime_errors;
 255     boolean offline_enabled;
 256
 257     // All views of the current extension.
 258     ItemInspectView[] views;
 259   };
 260
 261   dictionary GetExtensionsInfoOptions {
 262     boolean? includeDisabled;
 263     boolean? includeTerminated;
 264   };
 265
 266   dictionary ExtensionConfigurationUpdate {
 267     DOMString extensionId;
 268     boolean? fileAccess;
 269     boolean? incognitoAccess;
 270     boolean? errorCollection;
 271     boolean? runOnAllUrls;
 272     boolean? showActionButton;
 273   };
 274
 275   dictionary ProfileConfigurationUpdate {
 276     boolean? inDeveloperMode;
 277   };
 278
 279   dictionary ExtensionCommandUpdate {
 280     DOMString extensionId;
 281     DOMString commandName;
 282     CommandScope? scope;
 283     DOMString? keybinding;
 284   };
 285
 286   dictionary ReloadOptions {
 287     // If false, an alert dialog will show in the event of a reload error.
 288     // Defaults to false.
 289     boolean? failQuietly;
 290   };
 291
 292   dictionary LoadUnpackedOptions {
 293     // If false, an alert dialog will show in the event of a reload error.
 294     // Defaults to false.
 295     boolean? failQuietly;
 296   };
 297
 298   enum PackStatus {
 299     SUCCESS,
 300     ERROR,
 301     WARNING
 302   };
 303
 304   enum FileType {
 305     LOAD,
 306     PEM
 307   };
 308
 309   enum SelectType {
 310     FILE,
 311     FOLDER
 312   };
 313
 314   enum EventType {
 315     INSTALLED,
 316     UNINSTALLED,
 317     LOADED,
 318     UNLOADED,
 319     // New window / view opened.
 320     VIEW_REGISTERED,
 321     // window / view closed.
 322     VIEW_UNREGISTERED,
 323     ERROR_ADDED,
 324     ERRORS_REMOVED,
 325     PREFS_CHANGED,
 326     WARNINGS_CHANGED
 327   };
 328
 329   dictionary PackDirectoryResponse {
 330     // The response message of success or error.
 331     DOMString message;
 332
 333     // Unpacked items's path.
 334     DOMString item_path;
 335
 336     // Permanent key path.
 337     DOMString pem_path;
 338
 339     long override_flags;
 340     PackStatus status;
 341   };
 342
 343   dictionary ProjectInfo {
 344     DOMString name;
 345   };
 346
 347   dictionary EventData {
 348     EventType event_type;
 349     DOMString item_id;
 350     ExtensionInfo? extensionInfo;
 351   };
 352
 353   dictionary RequestFileSourceProperties {
 354     // The ID of the extension owning the file.
 355     DOMString extensionId;
 356
 357     // The path of the file, relative to the extension; e.g., manifest.json,
 358     // script.js, or main.html.
 359     DOMString pathSuffix;
 360
 361     // The error message which was thrown as a result of the error in the file.
 362     DOMString message;
 363
 364     // The key in the manifest which caused the error (e.g., "permissions").
 365     // (Required for "manifest.json" files)
 366     DOMString? manifestKey;
 367
 368     // The specific portion of the manifest key which caused the error (e.g.,
 369     // "foo" in the "permissions" key). (Optional for "manifest.json" file).
 370     DOMString? manifestSpecific;
 371
 372     // The line number which caused the error (optional for non-manifest files).
 373     long? lineNumber;
 374   };
 375
 376   dictionary RequestFileSourceResponse {
 377     // The region of the code which threw the error, and should be highlighted.
 378     DOMString highlight;
 379
 380     // The region before the "highlight" portion.
 381     // If the region which threw the error was not found, the full contents of
 382     // the file will be in the "beforeHighlight" section.
 383     DOMString beforeHighlight;
 384
 385     // The region after the "highlight" portion.
 386     DOMString afterHighlight;
 387
 388     // A title for the file in the form '<extension name>: <file name>'.
 389     DOMString title;
 390
 391     // The error message.
 392     DOMString message;
 393   };
 394
 395   dictionary OpenDevToolsProperties {
 396     // The ID of the extension. This is only needed if opening the background
 397     // page (where renderViewId and renderProcessId are -1).
 398     DOMString? extensionId;
 399
 400     // The ID of the render frame in which the error occurred.
 401     // Despite being called renderViewId, this refers to a render frame.
 402     long renderViewId;
 403
 404     // The ID of the process in which the error occurred.
 405     long renderProcessId;
 406
 407     boolean? incognito;
 408
 409     // The URL in which the error occurred.
 410     DOMString? url;
 411
 412     // The line to focus the devtools at.
 413     long? lineNumber;
 414
 415     // The column to focus the devtools at.
 416     long? columnNumber;
 417   };
 418
 419   dictionary DeleteExtensionErrorsProperties {
 420     DOMString extensionId;
 421     long[]? errorIds;
 422     ErrorType? type;
 423   };
 424
 425   callback VoidCallback = void ();
 426   callback BooleanCallback = void (boolean result);
 427   callback ExtensionInfosCallback = void (ExtensionInfo[] result);
 428   callback ExtensionInfoCallback = void (ExtensionInfo result);
 429   callback ItemsInfoCallback = void (ItemInfo[] result);
 430   callback ProfileInfoCallback = void (ProfileInfo info);
 431   callback GetProjectsInfoCallback = void (ProjectInfo[] result);
 432   callback PathCallback = void (DOMString path);
 433   callback PackCallback = void (PackDirectoryResponse response);
 434   callback VoidCallback = void();
 435   callback RequestFileSourceCallback =
 436       void (RequestFileSourceResponse response);
 437
 438   interface Functions {
 439     // Runs auto update for extensions and apps immediately.
 440     // |callback| : Called with the boolean result, true if autoUpdate is
 441     // successful.
 442     static void autoUpdate(optional BooleanCallback callback);
 443
 444     // Returns information of all the extensions and apps installed.
 445     // |options| : Options to restrict the items returned.
 446     // |callback| : Called with extensions info.
 447     static void getExtensionsInfo(optional GetExtensionsInfoOptions options,
 448                                   optional ExtensionInfosCallback callback);
 449
 450     // Returns information of a particular extension.
 451     // |id| : The id of the extension.
 452     // |callback| : Called with the result.
 453     static void getExtensionInfo(DOMString id,
 454                                  optional ExtensionInfoCallback callback);
 455
 456     // Returns information of all the extensions and apps installed.
 457     // |includeDisabled| : include disabled items.
 458     // |includeTerminated| : include terminated items.
 459     // |callback| : Called with items info.
 460     [deprecated="Use getExtensionsInfo"] static void getItemsInfo(
 461         boolean includeDisabled,
 462         boolean includeTerminated,
 463         ItemsInfoCallback callback);
 464
 465     // Returns the current profile's configuration.
 466     static void getProfileConfiguration(ProfileInfoCallback callback);
 467
 468     // Updates the active profile.
 469     // |update| : The parameters for updating the profile's configuration.  Any
 470     //     properties omitted from |update| will not be changed.
 471     static void updateProfileConfiguration(ProfileConfigurationUpdate update,
 472                                            optional VoidCallback callback);
 473
 474     // Opens a permissions dialog.
 475     // |extensionId| : The id of the extension to show permissions for.
 476     static void showPermissionsDialog(DOMString extensionId,
 477                                       optional VoidCallback callback);
 478
 479     // Reloads a given extension.
 480     // |extensionId| : The id of the extension to reload.
 481     // |options| : Additional configuration parameters.
 482     static void reload(DOMString extensionId,
 483                        optional ReloadOptions options,
 484                        optional VoidCallback callback);
 485
 486     // Modifies an extension's current configuration.
 487     // |update| : The parameters for updating the extension's configuration.
 488     //     Any properties omitted from |update| will not be changed.
 489     static void updateExtensionConfiguration(
 490         ExtensionConfigurationUpdate update,
 491         optional VoidCallback callback);
 492
 493     // Loads a user-selected unpacked item.
 494     // |options| : Additional configuration parameters.
 495     static void loadUnpacked(optional LoadUnpackedOptions options,
 496                              optional VoidCallback callback);
 497
 498     // Loads an extension / app.
 499     // |directory| : The directory to load the extension from.
 500     static void loadDirectory(
 501         [instanceOf=DirectoryEntry] object directory,
 502         PathCallback callback);
 503
 504     // Open Dialog to browse to an entry.
 505     // |selectType| : Select a file or a folder.
 506     // |fileType| : Required file type. For example, pem type is for private
 507     // key and load type is for an unpacked item.
 508     // |callback| : called with selected item's path.
 509     static void choosePath(SelectType selectType,
 510                            FileType fileType,
 511                            PathCallback callback);
 512
 513     // Pack an extension.
 514     // |rootPath| : The path of the extension.
 515     // |privateKeyPath| : The path of the private key, if one is given.
 516     // |flags| : Special flags to apply to the loading process, if any.
 517     // |callback| : called with the success result string.
 518     static void packDirectory(DOMString path,
 519                               optional DOMString privateKeyPath,
 520                               optional long flags,
 521                               optional PackCallback callback);
 522
 523     // Returns true if the profile is managed.
 524     static void isProfileManaged(BooleanCallback callback);
 525
 526     // Reads and returns the contents of a file related to an extension which
 527     // caused an error.
 528     static void requestFileSource(RequestFileSourceProperties properties,
 529                                   RequestFileSourceCallback callback);
 530
 531     // Open the developer tools to focus on a particular error.
 532     static void openDevTools(OpenDevToolsProperties properties,
 533                              optional VoidCallback callback);
 534
 535     // Delete reported extension erors.
 536     // |properties| : The properties specifying the errors to remove.
 537     static void deleteExtensionErrors(
 538         DeleteExtensionErrorsProperties properties,
 539         optional VoidCallback callback);
 540
 541     // Repairs the extension specified.
 542     // |extensionId| : The id of the extension to repair.
 543     static void repairExtension(DOMString extensionId,
 544                                 optional VoidCallback callback);
 545
 546     // Shows the options page for the extension specified.
 547     // |extensionId| : The id of the extension to show the options page for.
 548     static void showOptions(DOMString extensionId,
 549                             optional VoidCallback callback);
 550
 551     // Shows the path of the extension specified.
 552     // |extensionId| : The id of the extension to show the path for.
 553     static void showPath(DOMString extensionId, optional VoidCallback callback);
 554
 555     // (Un)suspends global shortcut handling.
 556     // |isSuspended| : Whether or not shortcut handling should be suspended.
 557     static void setShortcutHandlingSuspended(boolean isSuspended,
 558                                              optional VoidCallback callback);
 559
 560     // Updates an extension command.
 561     // |update| : The parameters for updating the extension command.
 562     static void updateExtensionCommand(ExtensionCommandUpdate update,
 563                                        optional VoidCallback callback);
 564
 565     [nocompile, deprecated="Use management.setEnabled"]
 566         static void enable(DOMString id,
 567                            boolean enabled,
 568                            optional VoidCallback callback);
 569     [nocompile, deprecated="Use updateExtensionConfiguration"]
 570         static void allowIncognito(DOMString extensionId,
 571                                    boolean allow,
 572                                    optional VoidCallback callback);
 573     [nocompile, deprecated="Use updateExtensionConfiguration"]
 574         static void allowFileAccess(DOMString extensionId,
 575                                     boolean allow,
 576                                     optional VoidCallback callback);
 577     [nocompile, deprecated="Use openDevTools"]
 578         static void inspect(InspectOptions options,
 579                             optional VoidCallback callback);
 580   };
 581
 582   interface Events {
 583     // Fired when a item state is changed.
 584     static void onItemStateChanged(EventData response);
 585
 586     // Fired when the profile's state has changed.
 587     static void onProfileStateChanged(ProfileInfo info);
 588   };
 589
 590 };