Add external byte array API and finalize external strings and byte arrays.

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
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 77 matching lines @@
  * otherwise indicated, callers should assume that all functions in
  * the Dart embedding api return local handles.
  *
  * Persistent handles are allocated within the current isolate. They
  * can be used to store objects across scopes. Persistent handles have
  * the lifetime of the current isolate unless they are explicitly
  * deallocated (see Dart_DeletePersistentHandle).
  */
 typedef struct _Dart_Handle* Dart_Handle;
 
-typedef void (*Dart_PeerFinalizer)(void* peer);
+typedef void (*Dart_PeerFinalizer)(Dart_Handle handle, void* peer);
 
 /**
  * Is this an error handle?
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT bool Dart_IsError(Dart_Handle handle);
 
 /**
  * Gets the error message from an error handle.
@@ skipping 995 matching lines @@
 /**
  * May generate an unhandled exception error.
  */
 DART_EXPORT Dart_Handle Dart_ListSetAsBytes(Dart_Handle list,
                                             intptr_t offset,
                                             uint8_t* native_array,
                                             intptr_t length);
 
 // --- Byte Arrays ---
 
-DART_EXPORT Dart_Handle Dart_NewByteArray(intptr_t length);
-
 /**
  * Is this object a ByteArray?
  */
 DART_EXPORT bool Dart_IsByteArray(Dart_Handle object);
 
+/**
+ * Returns a ByteArray of the desired length.
+ *
+ * \param length The length of the array.
+ *
+ * \return The ByteArray object if no error occurs. Otherwise returns
+ *   an error handle.
+ */
+DART_EXPORT Dart_Handle Dart_NewByteArray(intptr_t length);
+
+/**
+ * Returns a ByteArray which references an external array of 8-bit bytes.
+ *
+ * \param value An array of 8-bit bytes. This array must not move.
+ * \param length The length of the array.
+ *
+ * \return The ByteArray object if no error occurs. Otherwise returns
+ *   an error handle.
+ */
+DART_EXPORT Dart_Handle Dart_NewExternalByteArray(uint8_t* data,
+                                                  intptr_t length,
+                                                  void* peer,
+                                                  Dart_PeerFinalizer callback);
+
+/**
+ * Retrieves the peer pointer associated with an external ByteArray.
+ */
+DART_EXPORT Dart_Handle Dart_ExternalByteArrayGetPeer(Dart_Handle object,
+                                                      void** peer);
+
 // --- Closures ---
 
 /**
  * Is this object a Closure?
  */
 DART_EXPORT bool Dart_IsClosure(Dart_Handle object);
 
 /**
  * Invokes a Closure with the given arguments.
  *
@@ skipping 325 matching lines @@
  * restored.
  *
  * \param port_id The destination port.
  * \param message The message to send.
  *
  * \return True if the message was posted.
  */
 DART_EXPORT bool Dart_PostCObject(Dart_Port port_id, Dart_CObject* message);
 
 #endif  // INCLUDE_DART_API_H_