Danny Tuppeny
74bd539d4d
This adds additional "Editor" service method definitions as used by the new DTD sidebar. I moved the Editor service definitions into a new file (because they're now quite large and dtd_common_services seems better as an intro and list of the common specified services). I also split the existing info about `navigateToCode` into a more terse definition (in the new file) and a general example. I also updated the error example as I believe it was incorrectly wrapped in `result`. Change-Id: I6136eb550cce0dab86d535db02f9f06ee42892e0 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/378141 Reviewed-by: Kenzie Davisson <kenzieschmoll@google.com> Reviewed-by: Ben Konyi <bkonyi@google.com> Reviewed-by: Helin Shiah <helinx@google.com> Commit-Queue: Ben Konyi <bkonyi@google.com>
3.3 KiB
Common Services
These are service methods and events that may be registered to DTD by multiple client types (e.g. multiple IDEs support navigating to a location in code). Other clients can then rely on service methods having a common interface despite being implemented by different client types. For example, DevTools should be able to request navigation to code using the same service method regardless of whether VS Code or IntelliJ registered it.
Notes:
- Though multiple client types may register these methods, a single instance of DTD will accept only one client registering as a particular service. (DTD will throw an error if a second client tries to register as the same service.)
- These methods are not implemented in DTD. Rather, we want any new clients registering methods for a common purpose to follow a shared interface.
- These methods may not be registered at all to DTD, depending on what other tools are connected. Clients hoping to use these methods should use the
Servicestream to monitor whether these services are available.
Service Definitions
- Editor Service Services provided by an editor or IDE for tools to interact with code, devices and debug sessions.
Registering a service method with DTD
DTD uses JSON-RPC for communication. Methods can be registered by calling the registerService method documented in the DTD Protocol.
Example
{
"jsonrpc": "2.0",
"method": "registerService",
"params": {
"service": "Editor",
"method": "navigateToCode",
"capabilities": {
"supportedSchemes": ["file", "dart-macro+file"],
}
},
"id": "0"
}
Calling a service method over DTD
Calling a service method involves a JSON-RPC request to a method name that
combines the service and method name, for example "Editor.navigateToCode".
Example
{
"jsonrpc": "2.0",
"method": "Editor.navigateToCode",
"params": {
"file": "file:///path/to/file.dart",
"line": 1,
"column": 2,
},
"id": "0"
}
Responses
The response will contain a result that has a type indicating the type of
returned data or Success if a successful request has no return value. Errors
will be indicated as JSON-RPC errors with a code and message.
Examples
Success
If a request is successful but has no specific return value, a Success result
is returned.
{
"jsonrpc": "2.0",
"result": {"type": "Success"},
"id": "0"
}
Error
If an error occurs, there will be no result but instead an error.
{
"jsonrpc": "2.0",
"error": {
"code": 144,
"message": "File scheme is not supported",
"data": {
"details": "File URI `malformed-file:///file.dart` is not valid.",
"request": {
"id": "0",
"jsonrpc": "2.0",
"method": "Editor.navigateToCode",
"params": {
"file": "malformed-file:///file.dart",
"line": 1,
"column": 2,
}
}
}
}
"id": "0"
}
Common Error Codes
Below are some common error codes that may be used by all common services. Individual services may document their own error codes.
| Error code | Description |
|---|---|
| 144 | The URI's scheme is not recognized. |