src/chrome/common/extensions/api/debugger.json

   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 [
   6   {
   7     "namespace": "debugger",
   8     "description": "The <code>chrome.debugger</code> API serves as an alternate transport for Chrome's <a href='http://code.google.com/chrome/devtools/docs/remote-debugging.html'>remote debugging protocol</a>. Use <code>chrome.debugger</code> to attach to one or more tabs to instrument network interaction, debug JavaScript, mutate the DOM and CSS, etc. Use the Debuggee <code>tabId</code> to target tabs with sendCommand and route events by <code>tabId</code> from onEvent callbacks.",
   9     "types": [
  10       {
  11         "id": "Debuggee",
  12         "type": "object",
  13         "description": "Debuggee identifier. Either tabId or extensionId must be specified",
  14         "properties": {
  15           "tabId": { "type": "integer", "optional": true, "description": "The id of the tab which you intend to debug." },
  16           "extensionId": { "type": "string", "optional": true, "description": "The id of the extension which you intend to debug. Attaching to an extension background page is only possible when 'enable-silent-debugging' flag is enabled on the target browser." },
  17           "targetId": { "type": "string", "optional": true, "description": "The opaque id of the debug target." }
  18         }
  19       },
  20       {
  21         "id": "TargetInfo",
  22         "type": "object",
  23         "description": "Debug target information",
  24         "properties": {
  25           "type": {
  26             "type": "string",
  27             "description": "Target type.",
  28             "enum" : ["page", "background_page", "worker", "other" ]
  29           },
  30           "id": { "type": "string", "description": "Target id." },
  31           "tabId": { "type": "integer", "optional": true, "description": "The tab id, defined if type == 'page'." },
  32           "extensionId": { "type": "string", "optional": true, "description": "The extension id, defined if type = 'background_page'." },
  33           "attached": { "type": "boolean", "description": "True if debugger is already attached." },
  34           "title": { "type": "string", "description": "Target page title." },
  35           "url": { "type": "string", "description": "Target URL." },
  36           "faviconUrl": { "type": "string", "optional": true, "description": "Target favicon URL." }
  37         }
  38       }
  39     ],
  40     "functions": [
  41       {
  42         "name": "attach",
  43         "type": "function",
  44         "description": "Attaches debugger to the given target.",
  45         "parameters": [
  46           {
  47             "$ref": "Debuggee",
  48             "name": "target",
  49             "description": "Debugging target to which you want to attach."
  50           },
  51           {
  52             "type": "string",
  53             "name": "requiredVersion",
  54             "description": "Required debugging protocol version (\"0.1\"). One can only attach to the debuggee with matching major version and greater or equal minor version. List of the protocol versions can be obtained <a href='http://code.google.com/chrome/devtools/docs/remote-debugging.html'>here</a>."
  55           },
  56           {
  57             "type": "function",
  58             "name": "callback",
  59             "optional": true,
  60             "parameters": [],
  61             "description": "Called once the attach operation succeeds or fails. Callback receives no arguments. If the attach fails, $ref:runtime.lastError will be set to the error message."
  62           }
  63         ]
  64       },
  65       {
  66         "name": "detach",
  67         "type": "function",
  68         "description": "Detaches debugger from the given target.",
  69         "parameters": [
  70           {
  71             "$ref": "Debuggee",
  72             "name": "target",
  73             "description": "Debugging target from which you want to detach."
  74           },
  75           {
  76             "type": "function",
  77             "name": "callback",
  78             "optional": true,
  79             "parameters": [],
  80             "description": "Called once the detach operation succeeds or fails. Callback receives no arguments. If the detach fails, $ref:runtime.lastError will be set to the error message."
  81           }
  82         ]
  83       },
  84       {
  85         "name": "sendCommand",
  86         "type": "function",
  87         "description": "Sends given command to the debugging target.",
  88         "parameters": [
  89           {
  90             "$ref": "Debuggee",
  91             "name": "target",
  92             "description": "Debugging target to which you want to send the command."
  93           },
  94           {
  95             "type": "string",
  96             "name": "method",
  97             "description": "Method name. Should be one of the methods defined by the <a href='http://code.google.com/chrome/devtools/docs/remote-debugging.html'>remote debugging protocol</a>."
  98           },
  99           {
 100             "type": "object",
 101             "name": "commandParams",
 102             "optional": true,
 103             "additionalProperties": { "type": "any" },
 104             "description": "JSON object with request parameters. This object must conform to the remote debugging params scheme for given method."
 105           },
 106           {
 107             "type": "function",
 108             "name": "callback",
 109             "optional": true,
 110             "parameters": [
 111               {
 112                 "type": "object",
 113                 "name": "result",
 114                 "optional": true,
 115                 "additionalProperties": { "type": "any" },
 116                 "description": "JSON object with the response. Structure of the response varies depending on the method and is defined by the remote debugging protocol."
 117               }
 118             ],
 119             "description": "Response body. If an error occurs while posting the message, the callback will be called with no arguments and $ref:runtime.lastError will be set to the error message."
 120           }
 121         ]
 122       },
 123       {
 124         "name": "getTargets",
 125         "type": "function",
 126         "description": "Returns the list of available debug targets.",
 127         "parameters": [
 128           {
 129             "type": "function",
 130             "name": "callback",
 131             "parameters": [
 132               {
 133                 "type": "array",
 134                 "name": "result",
 135                 "items": {"$ref": "TargetInfo"},
 136                 "description": "Array of TargetInfo objects corresponding to the available debug targets."
 137               }
 138             ]
 139           }
 140         ]
 141       }
 142     ],
 143     "events": [
 144       {
 145         "name": "onEvent",
 146         "type": "function",
 147         "description": "Fired whenever debugging target issues instrumentation event.",
 148         "parameters": [
 149           {
 150             "$ref": "Debuggee",
 151             "name": "source",
 152             "description": "The debuggee that generated this event."
 153           },
 154           {
 155             "type": "string",
 156             "name": "method",
 157             "description": "Method name. Should be one of the notifications defined by the <a href='http://code.google.com/chrome/devtools/docs/remote-debugging.html'>remote debugging protocol</a>."
 158           },
 159           {
 160             "type": "object",
 161             "name": "params",
 162             "optional": true,
 163             "additionalProperties": { "type": "any" },
 164             "description": "JSON object with the response. Structure of the response varies depending on the method and is defined by the remote debugging protocol."
 165           }
 166         ]
 167       },
 168       {
 169         "name": "onDetach",
 170         "type": "function",
 171         "description": "Fired when browser terminates debugging session for the tab. This happens when either the tab is being closed or Chrome DevTools is being invoked for the attached tab.",
 172         "parameters": [
 173           {
 174             "$ref": "Debuggee",
 175             "name": "source",
 176             "description": "The debuggee that was detached."
 177           },
 178           {
 179             "type": "string",
 180             "name": "reason",
 181             "description": "Connection termination reason.",
 182             "enum": [ "target_closed", "canceled_by_user", "replaced_with_devtools" ]
 183           }
 184         ]
 185       }
 186     ]
 187   }
 188 ]