Allow embedder service request handlers to return JSON-RPC errors.

runtime/include/dart_tools_api.h

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 #ifndef INCLUDE_DART_TOOLS_API_H_
 #define INCLUDE_DART_TOOLS_API_H_
 
 #include "include/dart_api.h"
 
 /** \mainpage Dart Tools Embedding API Reference
@@ skipping 734 matching lines @@
  * =======
  */
 
 /**
  * A service request callback function.
  *
  * These callbacks, registered by the embedder, are called when the VM receives
  * a service request it can't handle and the service request command name
  * matches one of the embedder registered handlers.
  *
+ * The return value of the callback indicates whether the response
+ * should be used as a regular result or an error result.
+ * Specifically, if the callback returns true, a regular JSON-RPC
+ * response is built in the following way:
+ *
+ * {
+ *   "jsonrpc": "2.0",
+ *   "result": <json_object>,
+ *   "id": <some sequence id>,
+ * }
+ *
+ * If the callback returns false, a JSON-RPC error is built like this:
+ *
+ * {
+ *   "jsonrpc": "2.0",
+ *   "error": <json_object>,
+ *   "id": <some sequence id>,
+ * }
+ *
  * \param method The rpc method name.
  * \param param_keys Service requests can have key-value pair parameters. The
  *   keys and values are flattened and stored in arrays.
  * \param param_values The values associated with the keys.
  * \param num_params The length of the param_keys and param_values arrays.
  * \param user_data The user_data pointer registered with this handler.
+ * \param result A C string containing a valid JSON object. The returned
+ *   pointer will be freed by the VM by calling free.
  *
- * \return Returns a C string containing a valid JSON object. The returned
- * pointer will be freed by the VM by calling free.
+ * \return True if the result is a regular JSON-RPC response, false if the
+ *   result is a JSON-RPC error.
  */
-typedef const char* (*Dart_ServiceRequestCallback)(
+typedef bool (*Dart_ServiceRequestCallback)(
     const char* method,
     const char** param_keys,
     const char** param_values,
     intptr_t num_params,
-    void* user_data);
+    void* user_data,
+    const char** json_object);
 
 
 /**
  * Register a Dart_ServiceRequestCallback to be called to handle
  * requests for the named rpc on a specific isolate. The callback will
  * be invoked with the current isolate set to the request target.
  *
  * \param method The name of the method that this callback is responsible for.
  * \param callback The callback to invoke.
  * \param user_data The user data passed to the callback.
@@ skipping 258 matching lines @@
  * \param start_recording See Dart_EmbedderTimelineStartRecording.
  * \param stop_recording See Dart_EmbedderTimelineStopRecording.
  *
  * NOTE: To avoid races, this should be called before Dart_Initialize.
  */
 DART_EXPORT void Dart_SetEmbedderTimelineCallbacks(
     Dart_EmbedderTimelineStartRecording start_recording,
     Dart_EmbedderTimelineStopRecording stop_recording);
 
 #endif  // INCLUDE_DART_TOOLS_API_H_