Allow for embedder provided service request handlers

runtime/include/dart_api.h

 /*
  * Copyright (c) 2012, 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_API_H_
 #define INCLUDE_DART_API_H_
 
 /** \mainpage Dart Embedding API Reference
@@ skipping 2447 matching lines @@
  * After obtaining the service isolate the embedder specific glue code can
  * be loaded in and the isolate can be run by the embedder.
  *
  * NOTE: It is not safe to call this from multiple threads concurrently.
  *
  * \return Returns NULL if an error occurred.
  */
 DART_EXPORT Dart_Isolate Dart_GetServiceIsolate(void* callback_data);
 
 
+/**
+ * Returns true if the service is enabled. False otherwise.
+ *
+ *  \return Returns true if service is running.
+ */
+DART_EXPORT bool Dart_IsServiceRunning();
+
+
+/**
+ * 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.
+ *
+ * \param name The service request command name. Always the first entry
+ *   in the arguments array. Will match the name the callback was
+ *   registered with.
+ * \param arguments The service request command arguments. Incoming service
+ *   request paths are split like file system paths and flattened into an array
+ *   (e.g. /foo/bar becomes the array ["foo", "bar"].
+ * \param num_arguments The length of the arguments array.
+ * \param option_keys Service requests can have options key-value pairs. The
+ *   keys and values are flattened and stored in arrays.
+ * \param option_values The values associated with the keys.
+ * \param num_options The length of the option_keys and option_values array.
+ * \param user_data The user_data pointer registered with this handler.
+ *
+ * \return Returns a C string containing a valid JSON object. The returned
+ * pointer will be freed by the VM by calling free.
+ */
+typedef const char* (*Dart_ServiceRequestCallback)(
+    const char* name,
+    const char** arguments,
+    intptr_t num_arguments,
+    const char** option_keys,
+    const char** option_values,
+    intptr_t num_options,
+    void* user_data);
+
+/**
+ * Register a Dart_ServiceRequestCallback to be called to handle requests
+ * with name.
+ *
+ * \param name The name of the command that this callback is responsible for.
+ * \param callback The callback to invoke.
+ * \param user_data The user data passed to the callback.
+ *
+ * NOTE: If multiple callbacks with the same name are registered, only the
+ * last callback registered will be remembered.
+ */
+DART_EXPORT void Dart_RegisterServiceRequestCallback(
+    const char* name,
+    Dart_ServiceRequestCallback callback,
+    void* user_data);

[turnidge, 2014/02/18 21:27:05]

Do we want to be able to regiater top-level (i.e. non-isolate-based) callbacks?

[Cutch, 2014/02/18 22:18:51]

Done here and elsewhere.

+
 #endif  /* INCLUDE_DART_API_H_ */  /* NOLINT */