OLD | NEW |
1 # Dart VM Service Protocol 3.0 | 1 # Dart VM Service Protocol 3.0 |
2 | 2 |
3 > Please post feedback to the [observatory-discuss group][discuss-list] | 3 > Please post feedback to the [observatory-discuss group][discuss-list] |
4 | 4 |
5 This document describes of _version 3.0_ of the Dart VM Service Protocol. This | 5 This document describes of _version 3.0_ of the Dart VM Service Protocol. This |
6 protocol is used to communicate with a running Dart Virtual Machine. | 6 protocol is used to communicate with a running Dart Virtual Machine. |
7 | 7 |
8 To use the Service Protocol, start the VM with the *--observe* flag. | 8 To use the Service Protocol, start the VM with the *--observe* flag. |
9 The VM will start a webserver which services protocol requests via WebSocket. | 9 The VM will start a webserver which services protocol requests via WebSocket. |
10 It is possible to make HTTP (non-WebSocket) requests, | 10 It is possible to make HTTP (non-WebSocket) requests, |
11 but this does not allow access to VM _events_ and is not documented | 11 but this does not allow access to VM _events_ and is not documented |
12 here. | 12 here. |
13 | 13 |
14 The Service Protocol uses [JSON-RPC 2.0][]. | 14 The Service Protocol uses [JSON-RPC 2.0][]. |
15 | 15 |
16 [JSON-RPC 2.0]: http://www.jsonrpc.org/specification | 16 [JSON-RPC 2.0]: http://www.jsonrpc.org/specification |
17 | 17 |
18 **Table of Contents** | 18 **Table of Contents** |
19 | 19 |
20 - [RPCs, Requests, and Responses](#rpcs-requests-and-responses) | 20 - [RPCs, Requests, and Responses](#rpcs-requests-and-responses) |
21 - [Events](#events) | 21 - [Events](#events) |
22 - [Types](#types) | 22 - [Types](#types) |
23 - [IDs and Names](#ids-and-names) | 23 - [IDs and Names](#ids-and-names) |
24 - [Versioning](#versioning) | 24 - [Versioning](#versioning) |
25 - [Private RPCs, Types, and Properties](#private-rpcs-types-and-properties) | 25 - [Private RPCs, Types, and Properties](#private-rpcs-types-and-properties) |
26 - [Public RPCs](#public-rpcs) | 26 - [Public RPCs](#public-rpcs) |
27 - [addBreakpoint](#addbreakpoint) | 27 - [addBreakpoint](#addbreakpoint) |
| 28 - [addBreakpointWithScriptUri](#addbreakpointwithscripturi) |
28 - [addBreakpointAtEntry](#addbreakpointatentry) | 29 - [addBreakpointAtEntry](#addbreakpointatentry) |
29 - [evaluate](#evaluate) | 30 - [evaluate](#evaluate) |
30 - [evaluateInFrame](#evaluateinframe) | 31 - [evaluateInFrame](#evaluateinframe) |
31 - [getFlagList](#getflaglist) | 32 - [getFlagList](#getflaglist) |
32 - [getIsolate](#getisolate) | 33 - [getIsolate](#getisolate) |
33 - [getObject](#getobject) | 34 - [getObject](#getobject) |
34 - [getStack](#getstack) | 35 - [getStack](#getstack) |
35 - [getVersion](#getversion) | 36 - [getVersion](#getversion) |
36 - [getVM](#getvm) | 37 - [getVM](#getvm) |
37 - [pause](#pause) | 38 - [pause](#pause) |
(...skipping 327 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
365 ReturnType methodName(parameterType parameterName [optional) | 366 ReturnType methodName(parameterType parameterName [optional) |
366 ``` | 367 ``` |
367 | 368 |
368 A description of the return types and parameter types is provided | 369 A description of the return types and parameter types is provided |
369 in the section on [public types](#public-types). | 370 in the section on [public types](#public-types). |
370 | 371 |
371 ### addBreakpoint | 372 ### addBreakpoint |
372 | 373 |
373 ``` | 374 ``` |
374 Breakpoint addBreakpoint(string isolateId, | 375 Breakpoint addBreakpoint(string isolateId, |
375 string scriptId [optional], | 376 string scriptId, |
376 string scriptUri [optional], | |
377 int line, | 377 int line, |
378 int column [optional]) | 378 int column [optional]) |
379 ``` | 379 ``` |
380 | 380 |
381 The _addBreakpoint_ RPC is used to add a breakpoint at a specific line | 381 The _addBreakpoint_ RPC is used to add a breakpoint at a specific line |
382 of some script. | 382 of some script. |
383 | 383 |
384 The _scriptId_ or _scriptUri_ parameter is used to specify the target | 384 The _scriptId_ parameter is used to specify the target script. |
385 script. One of these two parameters must always be provided. | |
386 | 385 |
387 The _line_ parameter is used to specify the target line for the | 386 The _line_ parameter is used to specify the target line for the |
388 breakpoint. If there are multiple possible breakpoints on the target | 387 breakpoint. If there are multiple possible breakpoints on the target |
| 388 line, then the VM will place the breakpoint at the location which |
| 389 would execute soonest. If it is not possible to set a breakpoint at |
| 390 the target line, the breakpoint will be added at the next possible |
| 391 breakpoint location within the same function. |
| 392 |
| 393 The _column_ parameter may be optionally specified. This is useful |
| 394 for targeting a specific breakpoint on a line with multiple possible |
| 395 breakpoints. |
| 396 |
| 397 If no breakpoint is possible at that line, the _102_ (Cannot add |
| 398 breakpoint) error code is returned. |
| 399 |
| 400 Note that breakpoints are added and removed on a per-isolate basis. |
| 401 |
| 402 See [Breakpoint](#breakpoint). |
| 403 |
| 404 ### addBreakpointWithScriptUri |
| 405 |
| 406 ``` |
| 407 Breakpoint addBreakpointWithScriptUri(string isolateId, |
| 408 string scriptUri, |
| 409 int line, |
| 410 int column [optional]) |
| 411 ``` |
| 412 |
| 413 The _addBreakpoint_ RPC is used to add a breakpoint at a specific line |
| 414 of some script. This RPC is useful when a script has not yet been |
| 415 assigned an id, for example, if a script is in a deferred library |
| 416 which has not yet been loaded. |
| 417 |
| 418 The _scriptUri_ parameter is used to specify the target script. |
| 419 |
| 420 The _line_ parameter is used to specify the target line for the |
| 421 breakpoint. If there are multiple possible breakpoints on the target |
389 line, then the VM will place the breakpoint at the location which | 422 line, then the VM will place the breakpoint at the location which |
390 would execute soonest. If it is not possible to set a breakpoint at | 423 would execute soonest. If it is not possible to set a breakpoint at |
391 the target line, the breakpoint will be added at the next possible | 424 the target line, the breakpoint will be added at the next possible |
392 breakpoint location within the same function. | 425 breakpoint location within the same function. |
393 | 426 |
394 The _column_ parameter may be optionally specified. This is useful | 427 The _column_ parameter may be optionally specified. This is useful |
395 for targeting a specific breakpoint on a line with multiple possible | 428 for targeting a specific breakpoint on a line with multiple possible |
396 breakpoints. | 429 breakpoints. |
397 | 430 |
398 If no breakpoint is possible at that line, the _102_ (Cannot add | 431 If no breakpoint is possible at that line, the _102_ (Cannot add |
(...skipping 1249 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1648 // The number of live ports for this isolate. | 1681 // The number of live ports for this isolate. |
1649 int livePorts; | 1682 int livePorts; |
1650 | 1683 |
1651 // Will this isolate pause when exiting? | 1684 // Will this isolate pause when exiting? |
1652 bool pauseOnExit; | 1685 bool pauseOnExit; |
1653 | 1686 |
1654 // The last pause event delivered to the isolate. If the isolate is | 1687 // The last pause event delivered to the isolate. If the isolate is |
1655 // running, this will be a resume event. | 1688 // running, this will be a resume event. |
1656 Event pauseEvent; | 1689 Event pauseEvent; |
1657 | 1690 |
1658 // The entry function for this isolate. | |
1659 // | |
1660 // Guaranteed to be initialized when the IsolateRunnable event fires. | |
1661 @Function entry [optional]; | |
1662 | |
1663 // The root library for this isolate. | 1691 // The root library for this isolate. |
1664 // | 1692 // |
1665 // Guaranteed to be initialized when the IsolateRunnable event fires. | 1693 // Guaranteed to be initialized when the IsolateRunnable event fires. |
1666 @Library rootLib [optional]; | 1694 @Library rootLib [optional]; |
1667 | 1695 |
1668 // A list of all libraries for this isolate. | 1696 // A list of all libraries for this isolate. |
1669 // | 1697 // |
1670 // Guaranteed to be initialized when the IsolateRunnable event fires. | 1698 // Guaranteed to be initialized when the IsolateRunnable event fires. |
1671 @Library[] libraries; | 1699 @Library[] libraries; |
1672 | 1700 |
(...skipping 437 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2110 | 2138 |
2111 // A list of isolates running in the VM. | 2139 // A list of isolates running in the VM. |
2112 @Isolate[] isolates; | 2140 @Isolate[] isolates; |
2113 } | 2141 } |
2114 ``` | 2142 ``` |
2115 | 2143 |
2116 ## Revision History | 2144 ## Revision History |
2117 | 2145 |
2118 version | comments | 2146 version | comments |
2119 ------- | -------- | 2147 ------- | -------- |
2120 1.0 draft 1 | initial revision | 2148 1.0 | initial revision |
2121 1.1 | Describe protocol version 2.0. | 2149 2.0 | Describe protocol version 2.0. |
2122 1.2 | Describe protocol version 3.0. Added UnresolvedSourceLocation. Added Sen
tinel return to getIsolate. | 2150 3.0 | Describe protocol version 3.0. Added UnresolvedSourceLocation. Added Sen
tinel return to getIsolate. Add AddedBreakpointWithScriptUri. Removed Isolate.
entry. |
2123 | 2151 |
2124 | 2152 |
2125 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observato
ry-discuss | 2153 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observato
ry-discuss |
OLD | NEW |