Merge libv1.

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 1437 matching lines @@
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_StringToCString(Dart_Handle str,
                                              const char** cstr);
 
 /**
  * Gets a UTF-8 encoded representation of a String.
  *
  * \param str A string.
- * \param utf8_array An array allocated by the caller, used to return
- *   the array of UTF-8 encoded characters.
- * \param length Used to pass in the length of the provided array.
- *   Used to return the length of the array which was actually used.
+ * \param utf8_array Returns the String represented as UTF-8 code
+ *   units.  This UTF-8 array is scope allocated and is only valid
+ *   until the next call to Dart_ExitScope.
+ * \param length Used to return the length of the array which was
+ *   actually used.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_StringToUTF8(Dart_Handle str,
-                                          uint8_t* utf8_array,
+                                          uint8_t** utf8_array,
                                           intptr_t* length);
 
 /**
  * Gets the UTF-16 encoded representation of a string.
  *
  * \param str A string.
  * \param utf16_array An array allocated by the caller, used to return
  *   the array of UTF-16 encoded characters.
  * \param length Used to pass in the length of the provided array.
  *   Used to return the length of the array which was actually used.
@@ skipping 1252 matching lines @@
  *
  * \param object An object.
  * \param peer A value to store in the peer field.
  *
  * \return Returns an error if 'object' is a subtype of Null, num, or
  *   bool.
  */
 DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
 
 #endif  // INCLUDE_DART_API_H_