2012-01-30 08:29:31 +00:00
|
|
|
// Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file
|
2011-10-05 05:20:07 +00:00
|
|
|
// 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_
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/** \mainpage Dart Embedding API Reference
|
|
|
|
*
|
|
|
|
* Dart is a class-based programming language for creating structured
|
|
|
|
* web applications. This reference describes the Dart embedding api,
|
|
|
|
* which is used to embed the Dart Virtual Machine within an
|
|
|
|
* application.
|
|
|
|
*
|
|
|
|
* This reference is generated from the header include/dart_api.h.
|
|
|
|
*/
|
|
|
|
|
2011-10-05 05:20:07 +00:00
|
|
|
#ifdef __cplusplus
|
|
|
|
#define DART_EXTERN_C extern "C"
|
|
|
|
#else
|
|
|
|
#define DART_EXTERN_C
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#if defined(__CYGWIN__)
|
|
|
|
#error Tool chain and platform not supported.
|
|
|
|
#elif defined(_WIN32)
|
|
|
|
typedef signed __int8 int8_t;
|
|
|
|
typedef signed __int16 int16_t;
|
|
|
|
typedef signed __int32 int32_t;
|
|
|
|
typedef signed __int64 int64_t;
|
|
|
|
typedef unsigned __int8 uint8_t;
|
|
|
|
typedef unsigned __int16 uint16_t;
|
|
|
|
typedef unsigned __int32 uint32_t;
|
|
|
|
typedef unsigned __int64 uint64_t;
|
|
|
|
#if defined(DART_SHARED_LIB)
|
|
|
|
#define DART_EXPORT DART_EXTERN_C __declspec(dllexport)
|
|
|
|
#else
|
|
|
|
#define DART_EXPORT DART_EXTERN_C
|
|
|
|
#endif
|
|
|
|
#else
|
2012-08-06 10:50:38 +00:00
|
|
|
// __STDC_FORMAT_MACROS has to be defined before including <inttypes.h> to
|
|
|
|
// enable platform independent printf format specifiers.
|
|
|
|
#ifndef __STDC_FORMAT_MACROS
|
|
|
|
#define __STDC_FORMAT_MACROS
|
|
|
|
#endif
|
2011-10-05 05:20:07 +00:00
|
|
|
#include <inttypes.h>
|
2012-05-15 20:03:05 +00:00
|
|
|
#include <stdbool.h>
|
2011-10-05 05:20:07 +00:00
|
|
|
#if __GNUC__ >= 4
|
|
|
|
#if defined(DART_SHARED_LIB)
|
|
|
|
#define DART_EXPORT DART_EXTERN_C __attribute__ ((visibility("default")))
|
|
|
|
#else
|
|
|
|
#define DART_EXPORT DART_EXTERN_C
|
|
|
|
#endif
|
|
|
|
#else
|
|
|
|
#error Tool chain not supported.
|
|
|
|
#endif
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#include <assert.h>
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Handles ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* An object reference managed by the Dart VM garbage collector.
|
|
|
|
*
|
|
|
|
* Because the garbage collector may move objects, it is unsafe to
|
|
|
|
* refer to objects directly. Instead, we refer to objects through
|
|
|
|
* handles, which are known to the garbage collector and updated
|
|
|
|
* automatically when the object is moved. Handles should be passed
|
|
|
|
* by value (except in cases like out-parameters) and should never be
|
|
|
|
* allocated on the heap.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* Most functions in the Dart Embedding API return a handle. When a
|
|
|
|
* function completes normally, this will be a valid handle to an
|
|
|
|
* object in the Dart VM heap. This handle may represent the result of
|
|
|
|
* the operation or it may be a special valid handle used merely to
|
|
|
|
* indicate successful completion. Note that a valid handle may in
|
|
|
|
* some cases refer to the null object.
|
|
|
|
*
|
2012-06-12 21:07:49 +00:00
|
|
|
* --- Error handles ---
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* When a function encounters a problem that prevents it from
|
|
|
|
* completing normally, it returns an error handle (See Dart_IsError).
|
|
|
|
* An error handle has an associated error message that gives more
|
|
|
|
* details about the problem (See Dart_GetError).
|
|
|
|
*
|
2012-06-12 21:07:49 +00:00
|
|
|
* There are four kinds of error handles that can be produced,
|
|
|
|
* depending on what goes wrong:
|
|
|
|
*
|
|
|
|
* - Api error handles are produced when an api function is misused.
|
|
|
|
* This happens when a Dart embedding api function is called with
|
|
|
|
* invalid arguments or in an invalid context.
|
|
|
|
*
|
|
|
|
* - Unhandled exception error handles are produced when, during the
|
|
|
|
* execution of Dart code, an exception is thrown but not caught.
|
|
|
|
* Prototypically this would occur during a call to Dart_Invoke, but
|
|
|
|
* it can occur in any function which triggers the execution of Dart
|
|
|
|
* code (for example, Dart_ToString).
|
|
|
|
*
|
|
|
|
* An unhandled exception error provides access to an exception and
|
|
|
|
* stacktrace via the functions Dart_ErrorGetException and
|
|
|
|
* Dart_ErrorGetStacktrace.
|
|
|
|
*
|
|
|
|
* - Compilation error handles are produced when, during the execution
|
|
|
|
* of Dart code, a compile-time error occurs. As above, this can
|
|
|
|
* occur in any function which triggers the execution of Dart code.
|
|
|
|
*
|
|
|
|
* - Fatal error handles are produced when the system wants to shut
|
|
|
|
* down the current isolate.
|
|
|
|
*
|
|
|
|
* --- Propagating errors ---
|
|
|
|
*
|
|
|
|
* When an error handle is returned from the top level invocation of
|
|
|
|
* Dart code in a program, the embedder must handle the error as they
|
|
|
|
* see fit. Often, the embedder will print the error message produced
|
|
|
|
* by Dart_Error and exit the program.
|
|
|
|
*
|
|
|
|
* When an error is returned while in the body of a native function,
|
|
|
|
* it can be propagated by calling Dart_PropagateError. Errors should
|
|
|
|
* be propagated unless there is a specific reason not to. If an
|
|
|
|
* error is not propagated then it is ignored. For example, if an
|
|
|
|
* unhandled exception error is ignored, that effectively "catches"
|
|
|
|
* the unhandled exception. Fatal errors must always be propagated.
|
|
|
|
*
|
|
|
|
* Note that a call to Dart_PropagateError never returns. Instead it
|
|
|
|
* transfers control non-locally using a setjmp-like mechanism. This
|
|
|
|
* can be inconvenient if you have resources that you need to clean up
|
|
|
|
* before propagating the error. When an error is propagated, any
|
|
|
|
* current scopes created by Dart_EnterScope will be exited.
|
|
|
|
*
|
|
|
|
* To deal with this inconvenience, we often return error handles
|
|
|
|
* rather than propagating them from helper functions. Consider the
|
|
|
|
* following contrived example:
|
|
|
|
*
|
|
|
|
* 1 Dart_Handle isLongStringHelper(Dart_Handle arg) {
|
|
|
|
* 2 intptr_t* length = 0;
|
|
|
|
* 3 result = Dart_StringLength(arg, &length);
|
|
|
|
* 4 if (Dart_IsError(result)) {
|
|
|
|
* 5 return result
|
|
|
|
* 6 }
|
|
|
|
* 7 return Dart_NewBoolean(length > 100);
|
|
|
|
* 8 }
|
|
|
|
* 9
|
|
|
|
* 10 void NativeFunction_isLongString(Dart_NativeArguments args) {
|
|
|
|
* 11 Dart_EnterScope();
|
|
|
|
* 12 AllocateMyResource();
|
|
|
|
* 13 Dart_Handle arg = Dart_GetNativeArgument(args, 0);
|
|
|
|
* 14 Dart_Handle result = isLongStringHelper(arg);
|
|
|
|
* 15 if (Dart_IsError(result)) {
|
|
|
|
* 16 FreeMyResource();
|
|
|
|
* 17 Dart_PropagateError(result);
|
|
|
|
* 18 abort(); // will not reach here
|
|
|
|
* 19 }
|
|
|
|
* 20 Dart_SetReturnValue(result);
|
|
|
|
* 21 FreeMyResource();
|
|
|
|
* 22 Dart_ExitScope();
|
|
|
|
* 23 }
|
|
|
|
*
|
|
|
|
* In this example, we have a native function which calls a helper
|
|
|
|
* function to do its work. On line 5, the helper function could call
|
|
|
|
* Dart_PropagateError, but that would not give the native function a
|
|
|
|
* chance to call FreeMyResource(), causing a leak. Instead, the
|
|
|
|
* helper function returns the error handle to the caller, giving the
|
|
|
|
* caller a chance to clean up before propagating the error handle.
|
|
|
|
*
|
|
|
|
* --- Local and persistent handles ---
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Local handles are allocated within the current scope (see
|
|
|
|
* Dart_EnterScope) and go away when the current scope exits. Unless
|
2011-11-11 19:31:04 +00:00
|
|
|
* otherwise indicated, callers should assume that all functions in
|
|
|
|
* the Dart embedding api return local handles.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Persistent handles are allocated within the current isolate. They
|
2011-11-11 19:31:04 +00:00
|
|
|
* 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).
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-12-01 18:18:06 +00:00
|
|
|
typedef struct _Dart_Handle* Dart_Handle;
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2012-02-11 04:34:44 +00:00
|
|
|
typedef void (*Dart_WeakPersistentHandleFinalizer)(Dart_Handle handle,
|
|
|
|
void* peer);
|
2011-12-20 01:44:53 +00:00
|
|
|
typedef void (*Dart_PeerFinalizer)(void* peer);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-11-11 19:31:04 +00:00
|
|
|
* Is this an error handle?
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
2011-12-21 17:50:38 +00:00
|
|
|
DART_EXPORT bool Dart_IsError(Dart_Handle handle);
|
2011-10-31 20:18:07 +00:00
|
|
|
|
2012-06-12 21:07:49 +00:00
|
|
|
/**
|
|
|
|
* Is this an api error handle?
|
|
|
|
*
|
|
|
|
* Api error handles are produced when an api function is misused.
|
|
|
|
* This happens when a Dart embedding api function is called with
|
|
|
|
* invalid arguments or in an invalid context.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsApiError(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this an unhandled exception error handle?
|
|
|
|
*
|
|
|
|
* Unhandled exception error handles are produced when, during the
|
|
|
|
* execution of Dart code, an exception is thrown but not caught.
|
|
|
|
* This can occur in any function which triggers the execution of Dart
|
|
|
|
* code.
|
|
|
|
*
|
|
|
|
* See Dart_ErrorGetException and Dart_ErrorGetStacktrace.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsUnhandledExceptionError(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this a compilation error handle?
|
|
|
|
*
|
|
|
|
* Compilation error handles are produced when, during the execution
|
|
|
|
* of Dart code, a compile-time error occurs. This can occur in any
|
|
|
|
* function which triggers the execution of Dart code.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsCompilationError(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this a fatal error handle?
|
|
|
|
*
|
|
|
|
* Fatal error handles are produced when the system wants to shut down
|
|
|
|
* the current isolate.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsFatalError(Dart_Handle handle);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-11-11 19:31:04 +00:00
|
|
|
* Gets the error message from an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
|
|
|
* \return A C string containing an error message if the handle is
|
2011-11-11 19:31:04 +00:00
|
|
|
* error. An empty C string ("") if the handle is valid. This C
|
2011-11-01 18:11:36 +00:00
|
|
|
* String is scope allocated and is only valid until the next call
|
|
|
|
* to Dart_ExitScope.
|
|
|
|
*/
|
2011-12-21 17:50:38 +00:00
|
|
|
DART_EXPORT const char* Dart_GetError(Dart_Handle handle);
|
2011-10-31 20:18:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-11-11 19:31:04 +00:00
|
|
|
* Is this an error handle for an unhandled exception?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_ErrorHasException(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the exception Object from an unhandled exception error handle.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ErrorGetException(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the stack trace Object from an unhandled exception error handle.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ErrorGetStacktrace(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
2012-06-12 21:07:49 +00:00
|
|
|
* Produces an api error handle with the provided error message.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
2012-06-12 21:07:49 +00:00
|
|
|
* \param format A printf style format specifier used to construct the
|
|
|
|
* error message.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-06-12 21:07:49 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewApiError(const char* format, ...);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Produces a new unhandled exception error handle.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
|
|
|
* \param exception An instance of a Dart object to be thrown.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_NewUnhandledExceptionError(Dart_Handle exception);
|
|
|
|
|
|
|
|
// Deprecated.
|
|
|
|
// TODO(turnidge): Remove all uses and delete.
|
2011-11-08 00:12:59 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_Error(const char* format, ...);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
2012-02-02 19:05:06 +00:00
|
|
|
/**
|
|
|
|
* Propagates an error.
|
|
|
|
*
|
2012-06-12 21:07:49 +00:00
|
|
|
* If the provided handle is an unhandled exception error, this
|
2012-08-07 18:01:46 +00:00
|
|
|
* function will cause the unhandled exception to be rethrown. This
|
|
|
|
* will proceeed in the standard way, walking up Dart frames until an
|
|
|
|
* appropriate 'catch' block is found, executing 'finally' blocks,
|
|
|
|
* etc.
|
2012-02-02 19:05:06 +00:00
|
|
|
*
|
2012-06-12 21:07:49 +00:00
|
|
|
* If the error is not an unhandled exception error, we will unwind
|
2012-08-07 18:01:46 +00:00
|
|
|
* the stack to the next C frame. Intervening Dart frames will be
|
|
|
|
* discarded; specifically, 'finally' blocks will not execute. This
|
|
|
|
* is the standard way that compilation errors (and the like) are
|
|
|
|
* handled by the Dart runtime.
|
2012-02-02 19:05:06 +00:00
|
|
|
*
|
2012-06-12 21:07:49 +00:00
|
|
|
* In either case, when an error is propagated any current scopes
|
|
|
|
* created by Dart_EnterScope will be exited.
|
2012-02-02 19:05:06 +00:00
|
|
|
*
|
2012-06-12 21:07:49 +00:00
|
|
|
* See the additonal discussion under "Propagating Errors" at the
|
|
|
|
* beginning of this file.
|
|
|
|
*
|
|
|
|
* \param An error handle (See Dart_IsError)
|
2012-02-02 19:05:06 +00:00
|
|
|
*
|
|
|
|
* \return On success, this function does not return. On failure, an
|
|
|
|
* error handle is returned.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_PropagateError(Dart_Handle handle);
|
2012-06-12 21:07:49 +00:00
|
|
|
// TODO(turnidge): Should this really return an error handle?
|
|
|
|
// Consider just terminating.
|
2012-02-02 19:05:06 +00:00
|
|
|
|
2011-11-11 19:31:04 +00:00
|
|
|
// Internal routine used for reporting error handles.
|
|
|
|
DART_EXPORT void _Dart_ReportErrorHandle(const char* file,
|
|
|
|
int line,
|
|
|
|
const char* handle_string,
|
|
|
|
const char* error);
|
|
|
|
|
|
|
|
// TODO(turnidge): Move DART_CHECK_VALID to some sort of dart_utils
|
|
|
|
// header instead of this header.
|
|
|
|
/**
|
|
|
|
* Aborts the process if 'handle' is an error handle.
|
|
|
|
*
|
|
|
|
* Provided for convenience.
|
|
|
|
*/
|
|
|
|
#define DART_CHECK_VALID(handle) \
|
|
|
|
if (Dart_IsError((handle))) { \
|
|
|
|
_Dart_ReportErrorHandle(__FILE__, __LINE__, \
|
|
|
|
#handle, Dart_GetError(handle)); \
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2011-11-08 19:18:22 +00:00
|
|
|
/**
|
|
|
|
* Converts an object to a string.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* May generate an unhandled exception error.
|
2011-11-08 19:18:22 +00:00
|
|
|
*
|
2012-09-13 17:47:25 +00:00
|
|
|
* \return The converted string if no error occurs during
|
2011-11-11 19:31:04 +00:00
|
|
|
* the conversion. If an error does occur, an error handle is
|
|
|
|
* returned.
|
2011-11-08 19:18:22 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ToString(Dart_Handle object);
|
|
|
|
|
|
|
|
/**
|
2012-05-15 18:34:58 +00:00
|
|
|
* Checks to see if two handles refer to identically equal objects.
|
2011-11-08 19:18:22 +00:00
|
|
|
*
|
2012-05-15 18:34:58 +00:00
|
|
|
* This is equivalent to using the triple-equals (===) operator.
|
2011-11-08 19:18:22 +00:00
|
|
|
*
|
|
|
|
* \param obj1 An object to be compared.
|
|
|
|
* \param obj2 An object to be compared.
|
|
|
|
*
|
2012-05-15 18:34:58 +00:00
|
|
|
* \return True if the objects are identically equal. False otherwise.
|
2011-11-08 19:18:22 +00:00
|
|
|
*/
|
2012-05-15 18:34:58 +00:00
|
|
|
DART_EXPORT bool Dart_IdentityEquals(Dart_Handle obj1, Dart_Handle obj2);
|
2011-11-08 19:18:22 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Allocates a persistent handle for an object.
|
|
|
|
*
|
|
|
|
* This handle has the lifetime of the current isolate unless it is
|
|
|
|
* explicitly deallocated by calling Dart_DeletePersistentHandle.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_NewPersistentHandle(Dart_Handle object);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Deallocates a persistent handle.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT void Dart_DeletePersistentHandle(Dart_Handle object);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-12-20 01:44:53 +00:00
|
|
|
* Allocates a weak persistent handle for an object.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-12-20 01:44:53 +00:00
|
|
|
* This handle has the lifetime of the current isolate unless it is
|
|
|
|
* explicitly deallocated by calling Dart_DeletePersistentHandle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
2012-03-13 23:41:59 +00:00
|
|
|
*
|
|
|
|
* \param object An object.
|
|
|
|
* \param peer A pointer to a native object or NULL. This value is
|
|
|
|
* provided to callback when it is invoked.
|
|
|
|
* \param callback A function pointer that will be invoked sometime
|
|
|
|
* after the object is garbage collected.
|
|
|
|
*
|
|
|
|
* \return Success if the weak persistent handle was
|
|
|
|
* created. Otherwise, returns an error.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-12-20 01:44:53 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewWeakPersistentHandle(
|
|
|
|
Dart_Handle object,
|
|
|
|
void* peer,
|
2012-02-11 04:34:44 +00:00
|
|
|
Dart_WeakPersistentHandleFinalizer callback);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2011-12-20 01:44:53 +00:00
|
|
|
* Is this object a weak persistent handle?
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
2011-12-20 01:44:53 +00:00
|
|
|
DART_EXPORT bool Dart_IsWeakPersistentHandle(Dart_Handle object);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
2012-03-13 23:41:59 +00:00
|
|
|
/**
|
|
|
|
* Allocates a prologue weak persistent handle for an object.
|
|
|
|
*
|
|
|
|
* Prologue weak persistent handles are similar to weak persistent
|
|
|
|
* handles but exhibit different behavior during garbage collections
|
|
|
|
* that invoke the prologue and epilogue callbacks. While weak
|
|
|
|
* persistent handles always weakly reference their referents,
|
|
|
|
* prologue weak persistent handles weakly reference their referents
|
|
|
|
* only during a garbage collection that invokes the prologue and
|
|
|
|
* epilogue callbacks. During all other garbage collections, prologue
|
|
|
|
* weak persistent handles strongly reference their referents.
|
|
|
|
*
|
|
|
|
* This handle has the lifetime of the current isolate unless it is
|
|
|
|
* explicitly deallocated by calling Dart_DeletePersistentHandle.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
|
|
|
* \param object An object.
|
|
|
|
* \param peer A pointer to a native object or NULL. This value is
|
|
|
|
* provided to callback when it is invoked.
|
|
|
|
* \param callback A function pointer that will be invoked sometime
|
|
|
|
* after the object is garbage collected.
|
|
|
|
*
|
|
|
|
* \return Success if the prologue weak persistent handle was created.
|
|
|
|
* Otherwise, returns an error.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_NewPrologueWeakPersistentHandle(
|
|
|
|
Dart_Handle object,
|
|
|
|
void* peer,
|
|
|
|
Dart_WeakPersistentHandleFinalizer callback);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this object a prologue weak persistent handle?
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsPrologueWeakPersistentHandle(Dart_Handle object);
|
2012-03-03 02:30:20 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Constructs a set of weak references from the Cartesian product of
|
|
|
|
* the objects in the key set and the objects in values set.
|
|
|
|
*
|
|
|
|
* \param keys A set of object references. These references will be
|
|
|
|
* considered weak by the garbage collector.
|
|
|
|
* \param num_keys the number of objects in the keys set.
|
|
|
|
* \param values A set of object references. These references will be
|
|
|
|
* considered weak by garbage collector unless any object reference
|
|
|
|
* in 'keys' is found to be strong.
|
|
|
|
* \param num_values the size of the values set
|
|
|
|
*
|
|
|
|
* \return Success if the weak reference set could be created.
|
|
|
|
* Otherwise, returns an error handle.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_NewWeakReferenceSet(Dart_Handle* keys,
|
|
|
|
intptr_t num_keys,
|
|
|
|
Dart_Handle* values,
|
|
|
|
intptr_t num_values);
|
|
|
|
|
2012-06-14 00:08:07 +00:00
|
|
|
// --- Garbage Collection Callbacks ---
|
2012-03-07 19:38:51 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Callbacks signal the beginning and end of a garbage collection.
|
|
|
|
*
|
|
|
|
* These signals are intended to be used by the embedder to manage the
|
|
|
|
* lifetime of native objects with a managed object peer.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A callback invoked at the beginning of a garbage collection.
|
|
|
|
*/
|
|
|
|
typedef void (*Dart_GcPrologueCallback)();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A callback invoked at the end of a garbage collection.
|
|
|
|
*/
|
|
|
|
typedef void (*Dart_GcEpilogueCallback)();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Adds a garbage collection prologue callback.
|
|
|
|
*
|
|
|
|
* \param callback A function pointer to a prologue callback function.
|
|
|
|
* This function must not have been previously added as a prologue
|
|
|
|
* callback.
|
|
|
|
*
|
|
|
|
* \return Success if the callback was added. Otherwise, returns an
|
|
|
|
* error handle.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_AddGcPrologueCallback(
|
|
|
|
Dart_GcPrologueCallback callback);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Removes a garbage collection prologue callback.
|
|
|
|
*
|
|
|
|
* \param callback A function pointer to a prologue callback function.
|
|
|
|
* This function must have been added as a prologue callback.
|
|
|
|
*
|
|
|
|
* \return Success if the callback was removed. Otherwise, returns an
|
|
|
|
* error handle.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_RemoveGcPrologueCallback(
|
|
|
|
Dart_GcPrologueCallback callback);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Adds a garbage collection epilogue callback.
|
|
|
|
*
|
|
|
|
* \param callback A function pointer to an epilogue callback
|
|
|
|
* function. This function must not have been previously added as
|
|
|
|
* an epilogue callback.
|
|
|
|
*
|
|
|
|
* \return Success if the callback was added. Otherwise, returns an
|
|
|
|
* error handle.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_AddGcEpilogueCallback(
|
|
|
|
Dart_GcEpilogueCallback callback);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Removes a garbage collection epilogue callback.
|
|
|
|
*
|
|
|
|
* \param callback A function pointer to an epilogue callback
|
|
|
|
* function. This function must have been added as an epilogue
|
|
|
|
* callback.
|
|
|
|
*
|
|
|
|
* \return Success if the callback was removed. Otherwise, returns an
|
|
|
|
* error handle.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_RemoveGcEpilogueCallback(
|
|
|
|
Dart_GcEpilogueCallback callback);
|
2012-03-03 02:30:20 +00:00
|
|
|
|
2012-06-14 00:08:07 +00:00
|
|
|
// --- Heap Profiler ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A callback invoked by the heap profiler during profiling to write
|
|
|
|
* data.
|
|
|
|
*/
|
|
|
|
typedef void (*Dart_HeapProfileWriteCallback)(const void* data,
|
|
|
|
intptr_t length,
|
|
|
|
void* stream);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Generates a heap profile.
|
|
|
|
*
|
|
|
|
* \param callback A function pointer that will be repeatedly invoked
|
|
|
|
* with heap profile data.
|
|
|
|
* \param stream A pointer that will be passed to the callback. This
|
|
|
|
* is a convenient way to provide an open stream to the callback.
|
|
|
|
*
|
|
|
|
* \return Success if the heap profile is successful.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_HeapProfile(Dart_HeapProfileWriteCallback callback,
|
|
|
|
void* stream);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Initialization and Globals ---
|
|
|
|
|
2012-10-11 07:17:09 +00:00
|
|
|
/**
|
|
|
|
* Gets the version string for the Dart VM.
|
|
|
|
*
|
|
|
|
* The version of the Dart VM can be accessed without initializing the VM.
|
|
|
|
*
|
|
|
|
* \return The version string for the embedded Dart VM.
|
|
|
|
*/
|
|
|
|
DART_EXPORT const char* Dart_VersionString();
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-12-01 00:30:25 +00:00
|
|
|
* An isolate creation and initialization callback function.
|
|
|
|
*
|
2012-05-23 18:32:51 +00:00
|
|
|
* This callback, provided by the embedder, is called when the vm
|
|
|
|
* needs to create an isolate. The callback should create an isolate
|
|
|
|
* by calling Dart_CreateIsolate and load any scripts required for
|
|
|
|
* execution.
|
|
|
|
*
|
|
|
|
* When the function returns false, it is the responsibility of this
|
|
|
|
* function to ensure that Dart_ShutdownIsolate has been called if
|
|
|
|
* required (for example, if the isolate was created successfully by
|
|
|
|
* Dart_CreateIsolate() but the root library fails to load
|
|
|
|
* successfully, then the function should call Dart_ShutdownIsolate
|
|
|
|
* before returning).
|
|
|
|
*
|
|
|
|
* When the function returns false, the function should set *error to
|
|
|
|
* a malloc-allocated buffer containing a useful error message. The
|
|
|
|
* caller of this function (the vm) will make sure that the buffer is
|
|
|
|
* freed.
|
|
|
|
*
|
|
|
|
* \param script_uri The uri of the script to load. This uri has been
|
|
|
|
* canonicalized by the library tag handler from the parent isolate.
|
|
|
|
* The callback is responsible for loading this script by a call to
|
|
|
|
* Dart_LoadScript or Dart_LoadScriptFromSnapshot.
|
|
|
|
* \param main The name of the main entry point this isolate will
|
|
|
|
* eventually run. This is provided for advisory purposes only to
|
|
|
|
* improve debugging messages. The main function is not invoked by
|
|
|
|
* this function.
|
|
|
|
* \param callback_data The callback data which was passed to the
|
|
|
|
* parent isolate when it was created by calling Dart_CreateIsolate().
|
2011-12-01 00:30:25 +00:00
|
|
|
* \param error A structure into which the embedder can place a
|
|
|
|
* C string containing an error message in the case of failures.
|
|
|
|
*
|
2012-05-23 18:32:51 +00:00
|
|
|
* \return The embedder returns false if the creation and
|
|
|
|
* initialization was not successful and true if successful.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-05-23 18:32:51 +00:00
|
|
|
typedef bool (*Dart_IsolateCreateCallback)(const char* script_uri,
|
|
|
|
const char* main,
|
2012-01-18 21:46:27 +00:00
|
|
|
void* callback_data,
|
|
|
|
char** error);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
2011-12-16 18:41:20 +00:00
|
|
|
/**
|
|
|
|
* An isolate interrupt callback function.
|
|
|
|
*
|
|
|
|
* This callback, provided by the embedder, is called when an isolate
|
|
|
|
* is interrupted as a result of a call to Dart_InterruptIsolate().
|
|
|
|
* When the callback is called, Dart_CurrentIsolate can be used to
|
|
|
|
* figure out which isolate is being interrupted.
|
|
|
|
*
|
|
|
|
* \return The embedder returns true if the isolate should continue
|
|
|
|
* execution. If the embedder returns false, the isolate will be
|
|
|
|
* unwound (currently unimplemented).
|
|
|
|
*/
|
|
|
|
typedef bool (*Dart_IsolateInterruptCallback)();
|
|
|
|
// TODO(turnidge): Define and implement unwinding.
|
|
|
|
|
2012-06-28 18:15:17 +00:00
|
|
|
/**
|
|
|
|
* An isolate shutdown callback function.
|
|
|
|
*
|
|
|
|
* This callback, provided by the embedder, is called after the vm
|
|
|
|
* shuts down an isolate. Since the isolate has been shut down, it is
|
|
|
|
* not safe to enter the isolate or use it to run any Dart code.
|
|
|
|
*
|
|
|
|
* This function should be used to dispose of native resources that
|
|
|
|
* are allocated to an isolate in order to avoid leaks.
|
|
|
|
*
|
|
|
|
* \param callback_data The same callback data which was passed to the
|
|
|
|
* isolate when it was created.
|
|
|
|
*
|
|
|
|
*/
|
|
|
|
typedef void (*Dart_IsolateShutdownCallback)(void* callback_data);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-12-01 11:59:35 +00:00
|
|
|
* Initializes the VM.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-12-16 18:41:20 +00:00
|
|
|
* \param create A function to be called during isolate creation.
|
2011-12-01 00:30:25 +00:00
|
|
|
* See Dart_IsolateCreateCallback.
|
2011-12-16 18:41:20 +00:00
|
|
|
* \param interrupt A function to be called when an isolate is interrupted.
|
|
|
|
* See Dart_IsolateInterruptCallback.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \return True if initialization is successful.
|
|
|
|
*/
|
2011-12-16 18:41:20 +00:00
|
|
|
DART_EXPORT bool Dart_Initialize(Dart_IsolateCreateCallback create,
|
2012-06-28 18:15:17 +00:00
|
|
|
Dart_IsolateInterruptCallback interrupt,
|
|
|
|
Dart_IsolateShutdownCallback shutdown);
|
2011-12-01 11:59:35 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets command line flags. Should be called before Dart_Initialize.
|
|
|
|
*
|
|
|
|
* \param argc The length of the arguments array.
|
|
|
|
* \param argv An array of arguments.
|
|
|
|
*
|
|
|
|
* \return True if VM flags set successfully.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_SetVMFlags(int argc, const char** argv);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Returns true if the named VM flag is set.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name);
|
|
|
|
|
|
|
|
// --- Isolates ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* An isolate is the unit of concurrency in Dart. Each isolate has
|
|
|
|
* its own memory and thread of control. No state is shared between
|
|
|
|
* isolates. Instead, isolates communicate by message passing.
|
|
|
|
*
|
|
|
|
* Each thread keeps track of its current isolate, which is the
|
|
|
|
* isolate which is ready to execute on the current thread. The
|
|
|
|
* current isolate may be NULL, in which case no isolate is ready to
|
|
|
|
* execute. Most of the Dart apis require there to be a current
|
2011-11-11 19:31:04 +00:00
|
|
|
* isolate in order to function without error. The current isolate is
|
2011-11-01 18:11:36 +00:00
|
|
|
* set by any call to Dart_CreateIsolate or Dart_EnterIsolate.
|
|
|
|
*/
|
2011-12-01 18:18:06 +00:00
|
|
|
typedef struct _Dart_Isolate* Dart_Isolate;
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2011-12-01 18:18:06 +00:00
|
|
|
* Creates a new isolate. The new isolate becomes the current isolate.
|
|
|
|
*
|
|
|
|
* A snapshot can be used to restore the VM quickly to a saved state
|
|
|
|
* and is useful for fast startup. If snapshot data is provided, the
|
|
|
|
* isolate will be started using that snapshot data.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Requires there to be no current isolate.
|
|
|
|
*
|
2012-05-23 18:32:51 +00:00
|
|
|
* \param script_uri The name of the script this isolate will load.
|
|
|
|
* Provided only for advisory purposes to improve debugging messages.
|
|
|
|
* \param main The name of the main entry point this isolate will run.
|
|
|
|
* Provided only for advisory purposes to improve debugging messages.
|
2011-11-01 18:11:36 +00:00
|
|
|
* \param snapshot A buffer containing a VM snapshot or NULL if no
|
|
|
|
* snapshot is provided.
|
2012-05-23 18:32:51 +00:00
|
|
|
* \param callback_data Embedder data. This data will be passed to
|
|
|
|
* the Dart_IsolateCreateCallback when new isolates are spawned from
|
|
|
|
* this parent isolate.
|
|
|
|
* \param error DOCUMENT
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \return The new isolate is returned. May be NULL if an error
|
|
|
|
* occurs duing isolate initialization.
|
|
|
|
*/
|
2012-05-23 18:32:51 +00:00
|
|
|
DART_EXPORT Dart_Isolate Dart_CreateIsolate(const char* script_uri,
|
|
|
|
const char* main,
|
2012-01-18 21:46:27 +00:00
|
|
|
const uint8_t* snapshot,
|
2011-12-01 00:30:25 +00:00
|
|
|
void* callback_data,
|
|
|
|
char** error);
|
2011-11-01 18:11:36 +00:00
|
|
|
// TODO(turnidge): Document behavior when there is already a current
|
|
|
|
// isolate.
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Shuts down the current isolate. After this call, the current
|
|
|
|
* isolate is NULL.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT void Dart_ShutdownIsolate();
|
2011-11-01 18:11:36 +00:00
|
|
|
// TODO(turnidge): Document behavior when there is no current isolate.
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Returns the current isolate. Will return NULL if there is no
|
|
|
|
* current isolate.
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT Dart_Isolate Dart_CurrentIsolate();
|
2011-11-01 18:11:36 +00:00
|
|
|
|
2012-06-28 21:28:12 +00:00
|
|
|
/**
|
|
|
|
* Returns the callback data which was passed to the isolate when it
|
|
|
|
* was created.
|
|
|
|
*/
|
|
|
|
DART_EXPORT void* Dart_CurrentIsolateData();
|
|
|
|
|
2012-05-30 17:07:19 +00:00
|
|
|
/**
|
|
|
|
* Returns the debugging name for the current isolate.
|
|
|
|
*
|
|
|
|
* This name is unique to each isolate and should only be used to make
|
|
|
|
* debugging messages more comprehensible.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_DebugName();
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Enters an isolate. After calling this function,
|
|
|
|
* the current isolate will be set to the provided isolate.
|
|
|
|
*
|
|
|
|
* Requires there to be no current isolate.
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
|
2011-11-01 18:11:36 +00:00
|
|
|
// TODO(turnidge): Describe what happens if two threads attempt to
|
2011-11-11 19:31:04 +00:00
|
|
|
// enter the same isolate simultaneously. Check for this in the code.
|
2011-11-01 18:11:36 +00:00
|
|
|
// Describe whether isolates are allowed to migrate.
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Exits an isolate. After this call, Dart_CurrentIsolate will
|
|
|
|
* return NULL.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT void Dart_ExitIsolate();
|
2011-11-01 18:11:36 +00:00
|
|
|
// TODO(turnidge): We don't want users of the api to be able to exit a
|
2011-11-11 19:31:04 +00:00
|
|
|
// "pure" dart isolate. Implement and document.
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-12-06 00:34:49 +00:00
|
|
|
* Creates a full snapshot of the current isolate heap.
|
|
|
|
*
|
|
|
|
* A full snapshot is a compact representation of the dart heap state and
|
|
|
|
* can be used for fast initialization of an isolate. A Snapshot of the heap
|
|
|
|
* can only be created before any dart code has executed.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
|
|
|
* \param buffer Returns a pointer to a buffer containing the
|
|
|
|
* snapshot. This buffer is scope allocated and is only valid
|
|
|
|
* until the next call to Dart_ExitScope.
|
|
|
|
* \param size Returns the size of the buffer.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_CreateSnapshot(uint8_t** buffer,
|
|
|
|
intptr_t* size);
|
|
|
|
|
|
|
|
/**
|
2011-12-20 02:04:24 +00:00
|
|
|
* Creates a snapshot of the application script loaded in the isolate.
|
2011-12-06 00:34:49 +00:00
|
|
|
*
|
|
|
|
* A script snapshot can be used for implementing fast startup of applications
|
|
|
|
* (skips the script tokenizing and parsing process). A Snapshot of the script
|
|
|
|
* can only be created before any dart code has executed.
|
|
|
|
*
|
2011-12-20 02:04:24 +00:00
|
|
|
* Requires there to be a current isolate which already has loaded script.
|
2011-12-06 00:34:49 +00:00
|
|
|
*
|
|
|
|
* \param buffer Returns a pointer to a buffer containing
|
|
|
|
* the snapshot. This buffer is scope allocated and is only valid
|
|
|
|
* until the next call to Dart_ExitScope.
|
|
|
|
* \param size Returns the size of the buffer.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-12-20 02:04:24 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_CreateScriptSnapshot(uint8_t** buffer,
|
2011-12-06 00:34:49 +00:00
|
|
|
intptr_t* size);
|
|
|
|
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-12-16 18:41:20 +00:00
|
|
|
/**
|
|
|
|
* Schedules an interrupt for the specified isolate.
|
|
|
|
*
|
|
|
|
* Note that the interrupt does not occur immediately. In fact, if
|
|
|
|
* 'isolate' does not execute any further Dart code, then the
|
|
|
|
* interrupt will not occur at all. If and when the isolate is
|
|
|
|
* interrupted, the isolate interrupt callback will be invoked with
|
|
|
|
* 'isolate' as the current isolate (see
|
|
|
|
* Dart_IsolateInterruptCallback).
|
|
|
|
*
|
|
|
|
* \param isolate The isolate to be interrupted.
|
|
|
|
*/
|
|
|
|
DART_EXPORT void Dart_InterruptIsolate(Dart_Isolate isolate);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Messages and Ports ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A port is used to send or receive inter-isolate messages
|
|
|
|
*/
|
|
|
|
typedef int64_t Dart_Port;
|
|
|
|
|
2012-02-01 18:53:40 +00:00
|
|
|
/**
|
2012-08-01 18:47:33 +00:00
|
|
|
* ILLEGAL_PORT is a port number guaranteed never to be associated with a valid
|
|
|
|
* port.
|
2012-02-01 18:53:40 +00:00
|
|
|
*/
|
2012-08-01 18:47:33 +00:00
|
|
|
#define ILLEGAL_PORT ((Dart_Port) 0)
|
2012-02-01 18:53:40 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2012-01-24 19:31:01 +00:00
|
|
|
* A message notification callback.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2012-01-24 19:31:01 +00:00
|
|
|
* This callback allows the embedder to provide an alternate wakeup
|
|
|
|
* mechanism for the delivery of inter-isolate messages. It is the
|
|
|
|
* responsibility of the embedder to call Dart_HandleMessage to
|
|
|
|
* process the message.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-01-24 19:31:01 +00:00
|
|
|
typedef void (*Dart_MessageNotifyCallback)(Dart_Isolate dest_isolate);
|
2011-10-18 17:54:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2012-01-24 19:31:01 +00:00
|
|
|
* Allows embedders to provide an alternative wakeup mechanism for the
|
|
|
|
* delivery of inter-isolate messages. This setting only applies to
|
|
|
|
* the current isolate.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* Most embedders will only call this function once, before isolate
|
|
|
|
* execution begins. If this function is called after isolate
|
|
|
|
* execution begins, the embedder is responsible for threading issues.
|
|
|
|
*/
|
2012-01-24 19:31:01 +00:00
|
|
|
DART_EXPORT void Dart_SetMessageNotifyCallback(
|
|
|
|
Dart_MessageNotifyCallback message_notify_callback);
|
2011-11-01 18:11:36 +00:00
|
|
|
// TODO(turnidge): Consider moving this to isolate creation so that it
|
|
|
|
// is impossible to mess up.
|
2011-10-18 17:54:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2012-01-24 19:31:01 +00:00
|
|
|
* Handles the next pending message for the current isolate.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-01-24 19:31:01 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_HandleMessage();
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Processes any incoming messages for the current isolate.
|
|
|
|
*
|
|
|
|
* This function may only be used when the embedder has not provided
|
|
|
|
* an alternate message delivery mechanism with
|
|
|
|
* Dart_SetMessageCallbacks. It is provided for convenience.
|
|
|
|
*
|
|
|
|
* This function waits for incoming messages for the current
|
|
|
|
* isolate. As new messages arrive, they are handled using
|
|
|
|
* Dart_HandleMessage. The routine exits when all ports to the
|
|
|
|
* current isolate are closed.
|
2011-12-14 18:27:58 +00:00
|
|
|
*
|
|
|
|
* \return A valid handle if the run loop exited successfully. If an
|
|
|
|
* exception or other error occurs while processing messages, an
|
|
|
|
* error handle is returned.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_RunLoop();
|
|
|
|
// TODO(turnidge): Should this be removed from the public api?
|
|
|
|
|
2011-11-29 21:55:13 +00:00
|
|
|
/**
|
|
|
|
* Gets the main port id for the current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Port Dart_GetMainPortId();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Does the current isolate have live ReceivePorts?
|
|
|
|
*
|
|
|
|
* A ReceivePort is live when it has not been closed.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_HasLivePorts();
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Posts a message for some isolate. The message is a serialized
|
|
|
|
* object.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
|
|
|
* \param port The destination port.
|
|
|
|
* \param object An object from the current isolate.
|
|
|
|
*
|
|
|
|
* \return True if the message was posted.
|
|
|
|
*/
|
2011-11-29 21:55:13 +00:00
|
|
|
DART_EXPORT bool Dart_Post(Dart_Port port_id, Dart_Handle object);
|
|
|
|
|
2012-02-09 08:47:19 +00:00
|
|
|
// --- Message sending/receiving from native code ----
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A Dart_CObject is used for representing Dart objects as native C
|
|
|
|
* data outside the Dart heap. These objects are totally detached from
|
|
|
|
* the Dart heap. Only a subset of the Dart objects have a
|
|
|
|
* representation as a Dart_CObject.
|
2012-11-14 13:01:57 +00:00
|
|
|
*
|
|
|
|
* The string encoding in the 'value.as_string' is UTF-8.
|
2012-02-09 08:47:19 +00:00
|
|
|
*/
|
2012-05-15 20:03:05 +00:00
|
|
|
typedef struct _Dart_CObject {
|
2012-02-09 08:47:19 +00:00
|
|
|
enum Type {
|
|
|
|
kNull = 0,
|
|
|
|
kBool,
|
|
|
|
kInt32,
|
2012-02-09 10:21:38 +00:00
|
|
|
kInt64,
|
2012-02-09 14:09:03 +00:00
|
|
|
kBigint,
|
2012-02-09 08:47:19 +00:00
|
|
|
kDouble,
|
|
|
|
kString,
|
|
|
|
kArray,
|
2012-05-04 23:16:09 +00:00
|
|
|
kUint8Array,
|
2012-07-02 07:22:32 +00:00
|
|
|
kExternalUint8Array,
|
2012-05-15 10:40:44 +00:00
|
|
|
kUnsupported,
|
2012-02-09 08:47:19 +00:00
|
|
|
kNumberOfTypes
|
2012-05-15 20:03:05 +00:00
|
|
|
} type;
|
2012-02-09 08:47:19 +00:00
|
|
|
union {
|
|
|
|
bool as_bool;
|
|
|
|
int32_t as_int32;
|
2012-02-09 10:21:38 +00:00
|
|
|
int64_t as_int64;
|
2012-02-09 08:47:19 +00:00
|
|
|
double as_double;
|
|
|
|
char* as_string;
|
2012-02-09 14:09:03 +00:00
|
|
|
char* as_bigint;
|
2012-02-09 08:47:19 +00:00
|
|
|
struct {
|
|
|
|
int length;
|
2012-05-15 20:03:05 +00:00
|
|
|
struct _Dart_CObject** values;
|
2012-02-09 08:47:19 +00:00
|
|
|
} as_array;
|
2012-02-09 09:34:31 +00:00
|
|
|
struct {
|
|
|
|
int length;
|
|
|
|
uint8_t* values;
|
|
|
|
} as_byte_array;
|
2012-07-02 07:22:32 +00:00
|
|
|
struct {
|
|
|
|
int length;
|
|
|
|
uint8_t* data;
|
|
|
|
void* peer;
|
|
|
|
Dart_PeerFinalizer callback;
|
|
|
|
} as_external_byte_array;
|
2012-02-09 08:47:19 +00:00
|
|
|
} value;
|
2012-05-15 20:03:05 +00:00
|
|
|
} Dart_CObject;
|
2012-02-09 08:47:19 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Posts a message on some port. The message will contain the
|
|
|
|
* Dart_CObject object graph rooted in 'message'.
|
|
|
|
*
|
|
|
|
* While the message is being sent the state of the graph of
|
|
|
|
* Dart_CObject structures rooted in 'message' should not be accessed,
|
|
|
|
* as the message generation will make temporary modifications to the
|
|
|
|
* data. When the message has been sent the graph will be fully
|
|
|
|
* 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);
|
|
|
|
|
2012-02-01 18:53:40 +00:00
|
|
|
/**
|
|
|
|
* A native message handler.
|
|
|
|
*
|
|
|
|
* This handler is associated with a native port by calling
|
|
|
|
* Dart_NewNativePort.
|
2012-02-09 08:47:19 +00:00
|
|
|
*
|
|
|
|
* The message received is decoded into the message structure. The
|
|
|
|
* lifetime of the message data is controlled by the caller. All the
|
|
|
|
* data references from the message are allocated by the caller and
|
|
|
|
* will be reclaimed when returning to it.
|
2012-02-01 18:53:40 +00:00
|
|
|
*/
|
2012-02-09 10:21:38 +00:00
|
|
|
|
2012-02-01 18:53:40 +00:00
|
|
|
typedef void (*Dart_NativeMessageHandler)(Dart_Port dest_port_id,
|
|
|
|
Dart_Port reply_port_id,
|
2012-02-09 08:47:19 +00:00
|
|
|
Dart_CObject* message);
|
2012-02-01 18:53:40 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Creates a new native port. When messages are received on this
|
|
|
|
* native port, then they will be dispatched to the provided native
|
|
|
|
* message handler.
|
|
|
|
*
|
|
|
|
* \param name The name of this port in debugging messages.
|
|
|
|
* \param handler The C handler to run when messages arrive on the port.
|
|
|
|
* \param handle_concurrently Is it okay to process requests on this
|
|
|
|
* native port concurrently?
|
|
|
|
*
|
|
|
|
* \return If successful, returns the port id for the native port. In
|
2012-08-01 18:47:33 +00:00
|
|
|
* case of error, returns ILLEGAL_PORT.
|
2012-02-01 18:53:40 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Port Dart_NewNativePort(const char* name,
|
|
|
|
Dart_NativeMessageHandler handler,
|
|
|
|
bool handle_concurrently);
|
|
|
|
// TODO(turnidge): Currently handle_concurrently is ignored.
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Closes the native port with the given id.
|
|
|
|
*
|
|
|
|
* The port must have been allocated by a call to Dart_NewNativePort.
|
|
|
|
*
|
|
|
|
* \param native_port_id The id of the native port to close.
|
|
|
|
*
|
|
|
|
* \return Returns true if the port was closed successfully.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_CloseNativePort(Dart_Port native_port_id);
|
|
|
|
|
2011-11-29 21:55:13 +00:00
|
|
|
/**
|
|
|
|
* Returns a new SendPort with the provided port id.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_NewSendPort(Dart_Port port_id);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the ReceivePort for the provided port id, creating it if necessary.
|
|
|
|
*
|
|
|
|
* Note that there is at most one ReceivePort for a given port id.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_GetReceivePort(Dart_Port port_id);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
// --- Scopes ----
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Enters a new scope.
|
|
|
|
*
|
|
|
|
* All new local handles will be created in this scope. Additionally,
|
|
|
|
* some functions may return "scope allocated" memory which is only
|
|
|
|
* valid within this scope.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT void Dart_EnterScope();
|
2011-10-18 17:54:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Exits a scope.
|
|
|
|
*
|
|
|
|
* The previous scope (if any) becomes the current scope.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*/
|
|
|
|
DART_EXPORT void Dart_ExitScope();
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2012-02-17 07:43:24 +00:00
|
|
|
/**
|
|
|
|
* The Dart VM uses "zone allocation" for temporary structures. Zones
|
|
|
|
* support very fast allocation of small chunks of memory. The chunks
|
|
|
|
* cannot be deallocated individually, but instead zones support
|
|
|
|
* deallocating all chunks in one fast operation.
|
|
|
|
*
|
|
|
|
* This function makes it possible for the embedder to allocate
|
|
|
|
* temporary data in the VMs zone allocator.
|
|
|
|
*
|
|
|
|
* Zone allocation is possible:
|
|
|
|
* 1. when inside a scope where local handles can be allocated
|
|
|
|
* 2. when processing a message from a native port in a native port
|
|
|
|
* handler
|
|
|
|
*
|
|
|
|
* All the memory allocated this way will be reclaimed either on the
|
|
|
|
* next call to Dart_ExitScope or when the native port handler exits.
|
|
|
|
*
|
|
|
|
* \param size Size of the memory to allocate.
|
|
|
|
*
|
|
|
|
* \return A pointer to the allocated memory. NULL if allocation
|
|
|
|
* failed. Failure might due to is no current VM zone.
|
|
|
|
*/
|
|
|
|
DART_EXPORT uint8_t* Dart_ScopeAllocate(intptr_t size);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Objects ----
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-05 00:09:36 +00:00
|
|
|
/**
|
|
|
|
* Returns the null object.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
|
|
|
* \return A handle to the null object.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_Null();
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Is this object null?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsNull(Dart_Handle object);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-11-08 19:18:22 +00:00
|
|
|
* Checks if the two objects are equal.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* The result of the comparison is returned through the 'equal'
|
|
|
|
* parameter. The return value itself is used to indicate success or
|
|
|
|
* failure, not equality.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
2011-11-01 18:11:36 +00:00
|
|
|
* \param obj1 An object to be compared.
|
|
|
|
* \param obj2 An object to be compared.
|
|
|
|
* \param equal Returns the result of the equality comparison.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the comparison.
|
|
|
|
*/
|
2011-11-08 19:18:22 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_ObjectEquals(Dart_Handle obj1,
|
|
|
|
Dart_Handle obj2,
|
|
|
|
bool* equal);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this object an instance of some type?
|
|
|
|
*
|
2012-06-12 21:07:49 +00:00
|
|
|
* The result of the test is returned through the 'instanceof' parameter.
|
2011-11-01 18:11:36 +00:00
|
|
|
* The return value itself is used to indicate success or failure.
|
|
|
|
*
|
|
|
|
* \param object An object.
|
|
|
|
* \param type A type.
|
|
|
|
* \param instanceof Return true if 'object' is an instance of type 'type'.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-11-08 19:18:22 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_ObjectIsType(Dart_Handle object,
|
2011-11-01 18:11:36 +00:00
|
|
|
Dart_Handle type,
|
|
|
|
bool* instanceof);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2012-06-12 21:07:49 +00:00
|
|
|
// --- Instances ----
|
|
|
|
// For the purposes of the embedding api, not all objects returned are
|
|
|
|
// Dart language objects. Within the api, we use the term 'Instance'
|
|
|
|
// to indicate handles which refer to true Dart language objects.
|
|
|
|
//
|
|
|
|
// TODO(turnidge): Reorganize the "Object" section above, pulling down
|
|
|
|
// any functions that more properly belong here.
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Does this handle refer to some Dart language object?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsInstance(Dart_Handle object);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the class for some Dart language object.
|
|
|
|
*
|
|
|
|
* \param instance Some Dart object.
|
|
|
|
*
|
|
|
|
* \return If no error occurs, the class is returned. Otherwise an
|
|
|
|
* error handle is returned.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_InstanceGetClass(Dart_Handle instance);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Numbers ----
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Is this object a Number?
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT bool Dart_IsNumber(Dart_Handle object);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Integers ----
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Is this object an Integer?
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT bool Dart_IsInteger(Dart_Handle object);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Does this Integer fit into a 64-bit signed integer?
|
|
|
|
*
|
|
|
|
* \param integer An integer.
|
|
|
|
* \param fits Returns true if the integer fits into a 64-bit signed integer.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_IntegerFitsIntoInt64(Dart_Handle integer,
|
|
|
|
bool* fits);
|
|
|
|
|
2011-12-09 17:25:44 +00:00
|
|
|
/**
|
|
|
|
* Does this Integer fit into a 64-bit unsigned integer?
|
|
|
|
*
|
|
|
|
* \param integer An integer.
|
|
|
|
* \param fits Returns true if the integer fits into a 64-bit unsigned integer.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_IntegerFitsIntoUint64(Dart_Handle integer,
|
|
|
|
bool* fits);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Returns an Integer with the provided value.
|
|
|
|
*
|
|
|
|
* \param value The value of the integer.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The Integer object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewInteger(int64_t value);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns an Integer with the provided value.
|
|
|
|
*
|
|
|
|
* \param value The value of the integer represented as a C string
|
|
|
|
* containing a hexadecimal number.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The Integer object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewIntegerFromHexCString(const char* value);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the value of an Integer.
|
|
|
|
*
|
|
|
|
* The integer must fit into a 64-bit signed integer, otherwise an error occurs.
|
|
|
|
*
|
|
|
|
* \param integer An Integer.
|
|
|
|
* \param value Returns the value of the Integer.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-12-09 17:25:44 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_IntegerToInt64(Dart_Handle integer,
|
|
|
|
int64_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the value of an Integer.
|
|
|
|
*
|
|
|
|
* The integer must fit into a 64-bit unsigned integer, otherwise an
|
|
|
|
* error occurs.
|
|
|
|
*
|
|
|
|
* \param integer An Integer.
|
|
|
|
* \param value Returns the value of the Integer.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_IntegerToUint64(Dart_Handle integer,
|
|
|
|
uint64_t* value);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the value of an integer as a hexadecimal C string.
|
|
|
|
*
|
|
|
|
* \param integer An Integer.
|
|
|
|
* \param value Returns the value of the Integer as a hexadecimal C
|
|
|
|
* string. This C string is scope allocated and is only valid until
|
|
|
|
* the next call to Dart_ExitScope.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-12-09 17:25:44 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_IntegerToHexCString(Dart_Handle integer,
|
|
|
|
const char** value);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Booleans ----
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-05 00:09:36 +00:00
|
|
|
/**
|
|
|
|
* Returns the True object.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
|
|
|
* \return A handle to the True object.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_True();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the False object.
|
|
|
|
*
|
|
|
|
* Requires there to be a current isolate.
|
|
|
|
*
|
|
|
|
* \return A handle to the False object.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_False();
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Is this object a Boolean?
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT bool Dart_IsBoolean(Dart_Handle object);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns a Boolean with the provided value.
|
|
|
|
*
|
|
|
|
* \param value true or false.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The Boolean object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewBoolean(bool value);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the value of a Boolean
|
|
|
|
*
|
2011-12-08 23:50:40 +00:00
|
|
|
* \param boolean_obj A Boolean
|
2011-11-01 18:11:36 +00:00
|
|
|
* \param value Returns the value of the Boolean.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-12-08 23:50:40 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_BooleanValue(Dart_Handle boolean_obj, bool* value);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Doubles ---
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Is this object a Double?
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT bool Dart_IsDouble(Dart_Handle object);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns a Double with the provided value.
|
|
|
|
*
|
|
|
|
* \param value A double.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The Double object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewDouble(double value);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the value of a Double
|
|
|
|
*
|
2011-12-08 23:50:40 +00:00
|
|
|
* \param double_obj A Double
|
2011-11-01 18:11:36 +00:00
|
|
|
* \param value Returns the value of the Double.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-12-08 23:50:40 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_DoubleValue(Dart_Handle double_obj, double* value);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Strings ---
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Is this object a String?
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT bool Dart_IsString(Dart_Handle object);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2012-11-16 00:13:18 +00:00
|
|
|
* Is this object a Latin-1 (ISO-8859-1) String?
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-11-16 00:13:18 +00:00
|
|
|
DART_EXPORT bool Dart_IsStringLatin1(Dart_Handle object);
|
2012-10-31 17:56:46 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Gets the length of a String.
|
|
|
|
*
|
|
|
|
* \param str A String.
|
|
|
|
* \param length Returns the length of the String.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_StringLength(Dart_Handle str, intptr_t* length);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns a String built from the provided C string
|
2012-10-31 17:56:46 +00:00
|
|
|
* (There is an implicit assumption that the C string passed in contains
|
|
|
|
* UTF-8 encoded characters and '\0' is considered as a termination
|
|
|
|
* character).
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \param value A C String
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The String object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-10-31 17:56:46 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewStringFromCString(const char* str);
|
2012-05-30 17:07:19 +00:00
|
|
|
// TODO(turnidge): Document what happens when we run out of memory
|
|
|
|
// during this call.
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2012-10-31 17:56:46 +00:00
|
|
|
* Returns a String built from an array of UTF-8 encoded characters.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param utf8_array An array of UTF-8 encoded characters.
|
2011-11-01 18:11:36 +00:00
|
|
|
* \param length The length of the codepoints array.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The String object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-10-31 17:56:46 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewStringFromUTF8(const uint8_t* utf8_array,
|
|
|
|
intptr_t length);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2012-10-31 17:56:46 +00:00
|
|
|
* Returns a String built from an array of UTF-16 encoded characters.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param utf16_array An array of UTF-16 encoded characters.
|
2011-11-01 18:11:36 +00:00
|
|
|
* \param length The length of the codepoints array.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The String object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-10-31 17:56:46 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewStringFromUTF16(const uint16_t* utf16_array,
|
|
|
|
intptr_t length);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2012-10-31 17:56:46 +00:00
|
|
|
* Returns a String built from an array of UTF-32 encoded characters.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param utf32_array An array of UTF-32 encoded characters.
|
2011-11-01 18:11:36 +00:00
|
|
|
* \param length The length of the codepoints array.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The String object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-11-21 00:30:27 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewStringFromUTF32(const int32_t* utf32_array,
|
2012-10-31 17:56:46 +00:00
|
|
|
intptr_t length);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-12-05 17:55:01 +00:00
|
|
|
/**
|
|
|
|
* Is this object an external String?
|
|
|
|
*
|
|
|
|
* An external String is a String which references a fixed array of
|
|
|
|
* codepoints which is external to the Dart heap.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsExternalString(Dart_Handle object);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Retrieves the peer pointer associated with an external String.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ExternalStringGetPeer(Dart_Handle object,
|
|
|
|
void** peer);
|
|
|
|
|
|
|
|
/**
|
2012-10-31 17:56:46 +00:00
|
|
|
* Returns a String which references an external array of UTF-8 encoded
|
|
|
|
* characters.
|
2011-12-05 17:55:01 +00:00
|
|
|
*
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param utf8_array An array of UTF-8 encoded characters. This must not move.
|
|
|
|
* \param length The length of the characters array.
|
2011-12-05 17:55:01 +00:00
|
|
|
* \param peer An external pointer to associate with this string.
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param cback A callback to be called when this string is finalized.
|
2011-12-05 17:55:01 +00:00
|
|
|
*
|
|
|
|
* \return The String object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
|
|
|
*/
|
2012-10-31 17:56:46 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewExternalUTF8String(const uint8_t* utf8_array,
|
|
|
|
intptr_t length,
|
|
|
|
void* peer,
|
|
|
|
Dart_PeerFinalizer cback);
|
2011-11-19 00:33:23 +00:00
|
|
|
|
2011-12-05 17:55:01 +00:00
|
|
|
/**
|
2012-10-31 17:56:46 +00:00
|
|
|
* Returns a String which references an external array of UTF-16 encoded
|
|
|
|
* characters.
|
2011-12-05 17:55:01 +00:00
|
|
|
*
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param utf16_array An array of UTF-16 encoded characters. This must not move.
|
|
|
|
* \param length The length of the characters array.
|
2011-12-05 17:55:01 +00:00
|
|
|
* \param peer An external pointer to associate with this string.
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param cback A callback to be called when this string is finalized.
|
2011-12-05 17:55:01 +00:00
|
|
|
*
|
|
|
|
* \return The String object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
|
|
|
*/
|
2012-10-31 17:56:46 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewExternalUTF16String(const uint16_t* utf16_array,
|
|
|
|
intptr_t length,
|
|
|
|
void* peer,
|
|
|
|
Dart_PeerFinalizer cback);
|
2011-11-19 00:33:23 +00:00
|
|
|
|
2011-12-05 17:55:01 +00:00
|
|
|
/**
|
2012-10-31 17:56:46 +00:00
|
|
|
* Gets the C string representation of a String.
|
|
|
|
* (It is a sequence of UTF-8 encoded values with a '\0' termination.)
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \param str A string.
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param cstr Returns the String represented as a C string.
|
|
|
|
* This C string is scope allocated and is only valid until
|
|
|
|
* the next call to Dart_ExitScope.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2012-10-31 17:56:46 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_StringToCString(Dart_Handle str,
|
|
|
|
const char** cstr);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2012-10-31 17:56:46 +00:00
|
|
|
* Gets a UTF-8 encoded representation of a String.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \param str A string.
|
2012-11-06 19:07:43 +00:00
|
|
|
* \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.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2012-10-31 17:56:46 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_StringToUTF8(Dart_Handle str,
|
2012-11-06 19:07:43 +00:00
|
|
|
uint8_t** utf8_array,
|
2012-10-31 17:56:46 +00:00
|
|
|
intptr_t* length);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2012-10-31 17:56:46 +00:00
|
|
|
* Gets the UTF-16 encoded representation of a string.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \param str A string.
|
2012-10-31 17:56:46 +00:00
|
|
|
* \param utf16_array An array allocated by the caller, used to return
|
|
|
|
* the array of UTF-16 encoded characters.
|
2011-11-01 18:11:36 +00:00
|
|
|
* \param length Used to pass in the length of the provided array.
|
|
|
|
* Used to return the length of the array which was actually used.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2012-10-31 17:56:46 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_StringToUTF16(Dart_Handle str,
|
|
|
|
uint16_t* utf16_array,
|
2012-05-02 22:40:48 +00:00
|
|
|
intptr_t* length);
|
|
|
|
|
2012-11-15 21:37:26 +00:00
|
|
|
/**
|
|
|
|
* Gets the storage size in bytes of a String.
|
|
|
|
*
|
|
|
|
* \param str A String.
|
|
|
|
* \param length Returns the storage size in bytes of the String.
|
|
|
|
* This is the size in bytes needed to store the String.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_StringStorageSize(Dart_Handle str, intptr_t* size);
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Converts a String into an ExternalString.
|
|
|
|
* The original object is morphed into an external string object.
|
|
|
|
*
|
|
|
|
* \param array External space into which the string data will be
|
|
|
|
* copied into. This must not move.
|
|
|
|
* \param length The size in bytes of the provided external space (array).
|
|
|
|
* \param peer An external pointer to associate with this string.
|
|
|
|
* \param cback A callback to be called when this string is finalized.
|
|
|
|
*
|
|
|
|
* \return the converted ExternalString object if no error occurs.
|
|
|
|
* Otherwise returns an error handle.
|
|
|
|
*
|
|
|
|
* For example:
|
|
|
|
* intptr_t size;
|
|
|
|
* Dart_Handle result;
|
|
|
|
* result = DartStringStorageSize(str, &size);
|
|
|
|
* void* data = malloc(size);
|
|
|
|
* result = Dart_MakeExternalString(str, data, size, NULL, NULL);
|
|
|
|
*
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_MakeExternalString(Dart_Handle str,
|
|
|
|
void* array,
|
|
|
|
intptr_t length,
|
|
|
|
void* peer,
|
|
|
|
Dart_PeerFinalizer cback);
|
|
|
|
|
2012-10-31 17:56:46 +00:00
|
|
|
|
2011-11-04 12:25:53 +00:00
|
|
|
// --- Lists ---
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2011-11-04 12:25:53 +00:00
|
|
|
* Is this object a List?
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-11-04 12:25:53 +00:00
|
|
|
DART_EXPORT bool Dart_IsList(Dart_Handle object);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2011-11-04 12:25:53 +00:00
|
|
|
* Returns a List of the desired length.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-11-04 12:25:53 +00:00
|
|
|
* \param length The length of the list.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return The List object if no error occurs. Otherwise returns
|
|
|
|
* an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-11-04 12:25:53 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_NewList(intptr_t length);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2011-11-04 12:25:53 +00:00
|
|
|
* Gets the length of a List.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
2011-11-04 12:25:53 +00:00
|
|
|
* \param list A List.
|
|
|
|
* \param length Returns the length of the List.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-11-04 12:25:53 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_ListLength(Dart_Handle list, intptr_t* length);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2011-11-04 12:25:53 +00:00
|
|
|
* Gets the Object at some index of a List.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* If the index is out of bounds, an error occurs.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
2011-11-04 12:25:53 +00:00
|
|
|
* \param list A List.
|
|
|
|
* \param index A valid index into the List.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-11-04 12:25:53 +00:00
|
|
|
* \return The Object in the List at the specified index if no errors
|
2011-11-11 19:31:04 +00:00
|
|
|
* occurs. Otherwise returns an error handle.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2011-11-04 12:25:53 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_ListGetAt(Dart_Handle list,
|
|
|
|
intptr_t index);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2011-11-04 12:25:53 +00:00
|
|
|
* Sets the Object at some index of a List.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* If the index is out of bounds, an error occurs.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
2011-11-04 12:25:53 +00:00
|
|
|
* \param array A List.
|
|
|
|
* \param index A valid index into the List.
|
|
|
|
* \param value The Object to put in the List.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-11-04 12:25:53 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_ListSetAt(Dart_Handle list,
|
|
|
|
intptr_t index,
|
|
|
|
Dart_Handle value);
|
|
|
|
|
2011-11-11 19:31:04 +00:00
|
|
|
/**
|
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*/
|
2011-11-04 12:25:53 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_ListGetAsBytes(Dart_Handle list,
|
|
|
|
intptr_t offset,
|
|
|
|
uint8_t* native_array,
|
|
|
|
intptr_t length);
|
|
|
|
|
2011-11-11 19:31:04 +00:00
|
|
|
/**
|
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*/
|
2011-11-04 12:25:53 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_ListSetAsBytes(Dart_Handle list,
|
|
|
|
intptr_t offset,
|
|
|
|
uint8_t* native_array,
|
|
|
|
intptr_t length);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2012-01-26 02:42:08 +00:00
|
|
|
// --- Byte Arrays ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this object a ByteArray?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsByteArray(Dart_Handle object);
|
|
|
|
|
2012-11-01 07:53:33 +00:00
|
|
|
/**
|
|
|
|
* Is this object an external ByteArray?
|
|
|
|
*
|
|
|
|
* An external ByteArray is a ByteArray which references a fixed array of
|
|
|
|
* bytes which is external to the Dart heap.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsByteArrayExternal(Dart_Handle object);
|
|
|
|
|
2012-02-11 04:34:44 +00:00
|
|
|
/**
|
|
|
|
* 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.
|
2012-02-15 02:51:11 +00:00
|
|
|
* \param peer An external pointer to associate with this byte array.
|
2012-02-11 04:34:44 +00:00
|
|
|
*
|
|
|
|
* \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);
|
|
|
|
|
2012-11-01 07:53:33 +00:00
|
|
|
/**
|
|
|
|
* Retrieves the data pointer associated with an external ByteArray.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ExternalByteArrayGetData(Dart_Handle object,
|
|
|
|
void** data);
|
|
|
|
|
2012-02-11 04:34:44 +00:00
|
|
|
/**
|
|
|
|
* Retrieves the peer pointer associated with an external ByteArray.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ExternalByteArrayGetPeer(Dart_Handle object,
|
|
|
|
void** peer);
|
|
|
|
|
2012-02-15 02:51:11 +00:00
|
|
|
/**
|
|
|
|
* Gets an int8_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the int8_t.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetInt8At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
int8_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets an int8_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The int8_t to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetInt8At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
int8_t value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets a uint8_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the uint8_t.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetUint8At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
uint8_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets a uint8_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The uint8_t to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetUint8At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
uint8_t value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets an int16_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the int16_t.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetInt16At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
int16_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets an int16_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The int16_t to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetInt16At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
int16_t value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets a uint16_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the uint16_t.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetUint16At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
uint16_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets a uint16_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The uint16_t to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetUint16At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
uint16_t value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets an int32_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the int32_t.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetInt32At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
int32_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets an int32_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The int32_t to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetInt32At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
int32_t value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets a uint32_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the uint32_t.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetUint32At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
uint32_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets a uint32_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The uint32_t to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetUint32At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
uint32_t value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets an int64_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the int64_t.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetInt64At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
int64_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets an int64_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The int64_t to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetInt64At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
int64_t value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets a uint64_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the uint64_t.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetUint64At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
uint64_t* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets a uint64_t at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The uint64_t to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetUint64At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
uint64_t value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets a float at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the float.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetFloat32At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
float* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets a float at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The float to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetFloat32At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
float value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets a double from some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the List.
|
|
|
|
* \param value Returns the value of the double.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArrayGetFloat64At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
double* value);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets a double at some byte offset in a ByteArray.
|
|
|
|
*
|
|
|
|
* If the byte offset is out of bounds, an error occurs.
|
|
|
|
*
|
|
|
|
* \param array A ByteArray.
|
|
|
|
* \param offset A valid byte offset into the ByteArray.
|
|
|
|
* \param value The double to put into the ByteArray.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ByteArraySetFloat64At(Dart_Handle array,
|
|
|
|
intptr_t offset,
|
|
|
|
double value);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Closures ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this object a Closure?
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT bool Dart_IsClosure(Dart_Handle object);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
2012-07-24 17:59:12 +00:00
|
|
|
/**
|
|
|
|
* Retrieves the function of a closure.
|
|
|
|
*
|
2012-09-13 17:47:25 +00:00
|
|
|
* \return A handle to the function of the closure, or an error handle if the
|
2012-07-24 17:59:12 +00:00
|
|
|
* argument is not a closure.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ClosureFunction(Dart_Handle closure);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Invokes a Closure with the given arguments.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
2011-11-01 18:11:36 +00:00
|
|
|
* \return If no error occurs during execution, then the result of
|
2011-11-11 19:31:04 +00:00
|
|
|
* invoking the closure is returned. If an error occurs during
|
|
|
|
* execution, then an error handle is returned.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_InvokeClosure(Dart_Handle closure,
|
|
|
|
int number_of_arguments,
|
|
|
|
Dart_Handle* arguments);
|
|
|
|
|
2012-06-12 21:07:49 +00:00
|
|
|
// --- Classes and Interfaces ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this a class handle?
|
|
|
|
*
|
|
|
|
* Most parts of the dart embedding api do not distinguish between
|
|
|
|
* classes and interfaces. For example, Dart_GetClass can return a
|
|
|
|
* class or an interface and Dart_New can instantiate a class or an
|
|
|
|
* interface. The exceptions are Dart_IsClass and Dart_IsInterface,
|
|
|
|
* which can be used to distinguish whether a handle refers to a class
|
|
|
|
* or an interface.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsClass(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this an interface handle?
|
|
|
|
*
|
|
|
|
* Most parts of the dart embedding api do not distinguish between
|
|
|
|
* classes and interfaces. For example, Dart_GetClass can return a
|
|
|
|
* class or an interface and Dart_New can instantiate a class or an
|
|
|
|
* interface. The exceptions are Dart_IsClass and Dart_IsInterface,
|
|
|
|
* which can be used to distinguish whether a handle refers to a class
|
|
|
|
* or an interface.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsInterface(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the class name for the provided class or interface.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ClassName(Dart_Handle clazz);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the library for the provided class or interface.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ClassGetLibrary(Dart_Handle clazz);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the default factory class for the provided class or
|
|
|
|
* interface.
|
|
|
|
*
|
|
|
|
* Only interfaces may have default fadctory classes. If the class or
|
|
|
|
* interface has no default factory class, this function returns
|
|
|
|
* Dart_Null().
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ClassGetDefault(Dart_Handle clazz);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the number of interfaces directly implemented by some class
|
|
|
|
* or interface.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Finish documentation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ClassGetInterfaceCount(Dart_Handle clazz,
|
|
|
|
intptr_t* count);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the interface at some index in the list of interfaces some
|
|
|
|
* class or inteface.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Finish documentation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ClassGetInterfaceAt(Dart_Handle clazz,
|
|
|
|
intptr_t index);
|
|
|
|
|
2012-09-13 17:47:25 +00:00
|
|
|
/**
|
|
|
|
* Is this class defined by a typedef?
|
|
|
|
*
|
|
|
|
* Typedef definitions from the main program are represented as a
|
|
|
|
* special kind of class handle. See Dart_ClassGetTypedefReferent.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Finish documentation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_ClassIsTypedef(Dart_Handle clazz);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns a handle to the type to which a typedef refers.
|
|
|
|
*
|
|
|
|
* It is an error to call this function on a handle for which
|
|
|
|
* Dart_ClassIsTypedef is not true.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Finish documentation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ClassGetTypedefReferent(Dart_Handle clazz);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Does this class represent the type of a function?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_ClassIsFunctionType(Dart_Handle clazz);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns a function handle representing the signature associated
|
|
|
|
* with a function type.
|
|
|
|
*
|
|
|
|
* The return value is a function handle (See Dart_IsFunction, etc.).
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Finish documentation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ClassGetFunctionTypeSignature(Dart_Handle clazz);
|
|
|
|
|
2012-07-09 23:57:08 +00:00
|
|
|
// --- Function and Variable Declarations ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns a list of the names of all functions or methods declared in
|
|
|
|
* a library or class.
|
|
|
|
*
|
|
|
|
* \param target A library or class.
|
|
|
|
*
|
|
|
|
* \return If no error occurs, a list of strings is returned.
|
2012-09-13 17:47:25 +00:00
|
|
|
* Otherwise an error handle is returned.
|
2012-07-09 23:57:08 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_GetFunctionNames(Dart_Handle target);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Looks up a function or method declaration by name from a library or
|
|
|
|
* class.
|
|
|
|
*
|
|
|
|
* \param target The library or class containing the function.
|
|
|
|
* \param function_name The name of the function.
|
|
|
|
*
|
|
|
|
* \return If an error is encountered, returns an error handle.
|
|
|
|
* Otherwise returns a function handle if the function is found of
|
|
|
|
* Dart_Null() if the function is not found.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_LookupFunction(Dart_Handle target,
|
|
|
|
Dart_Handle function_name);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this a function or method declaration handle?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsFunction(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the name for the provided function or method.
|
|
|
|
*
|
|
|
|
* \return A valid string handle if no error occurs during the
|
2012-09-13 17:47:25 +00:00
|
|
|
* operation.
|
2012-07-09 23:57:08 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionName(Dart_Handle function);
|
2012-07-31 22:47:52 +00:00
|
|
|
|
|
|
|
/**
|
2012-09-13 17:47:25 +00:00
|
|
|
* Returns a handle to the owner of a function.
|
|
|
|
*
|
|
|
|
* The owner of an instance method or a static method is its defining
|
|
|
|
* class. The owner of a top-level function is its defining
|
|
|
|
* library. The owner of the function of a non-implicit closure is the
|
|
|
|
* function of the method or closure that defines the non-implicit
|
2012-08-03 22:56:21 +00:00
|
|
|
* closure.
|
2012-07-31 22:47:52 +00:00
|
|
|
*
|
2012-09-13 17:47:25 +00:00
|
|
|
* \return A valid handle to the owner of the function, or an error
|
|
|
|
* handle if the argument is not a valid handle to a function.
|
2012-07-31 22:47:52 +00:00
|
|
|
*/
|
2012-08-03 22:56:21 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionOwner(Dart_Handle function);
|
2012-07-09 23:57:08 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Determines whether a function handle refers to an abstract method.
|
|
|
|
*
|
|
|
|
* \param function A handle to a function or method declaration.
|
|
|
|
* \param is_static Returns whether the handle refers to an abstract method.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionIsAbstract(Dart_Handle function,
|
|
|
|
bool* is_abstract);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Determines whether a function handle referes to a static function
|
|
|
|
* of method.
|
|
|
|
*
|
|
|
|
* For the purposes of the embedding API, a top-level function is
|
|
|
|
* implicitly declared static.
|
|
|
|
*
|
|
|
|
* \param function A handle to a function or method declaration.
|
|
|
|
* \param is_static Returns whether the function or method is declared static.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionIsStatic(Dart_Handle function,
|
|
|
|
bool* is_static);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Determines whether a function handle referes to a constructor.
|
|
|
|
*
|
|
|
|
* \param function A handle to a function or method declaration.
|
|
|
|
* \param is_static Returns whether the function or method is a constructor.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionIsConstructor(Dart_Handle function,
|
|
|
|
bool* is_constructor);
|
|
|
|
// TODO(turnidge): Document behavior for factory constructors too.
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Determines whether a function or method is a getter.
|
|
|
|
*
|
|
|
|
* \param function A handle to a function or method declaration.
|
|
|
|
* \param is_static Returns whether the function or method is a getter.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionIsGetter(Dart_Handle function,
|
|
|
|
bool* is_getter);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Determines whether a function or method is a setter.
|
|
|
|
*
|
|
|
|
* \param function A handle to a function or method declaration.
|
|
|
|
* \param is_static Returns whether the function or method is a setter.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionIsSetter(Dart_Handle function,
|
|
|
|
bool* is_setter);
|
|
|
|
|
2012-09-13 17:47:25 +00:00
|
|
|
/**
|
|
|
|
* Returns the return type of a function.
|
|
|
|
*
|
|
|
|
* \return A valid handle to a type or an error handle if the argument
|
|
|
|
* is not valid.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionReturnType(Dart_Handle function);
|
|
|
|
|
2012-07-16 22:05:16 +00:00
|
|
|
/**
|
|
|
|
* Determines the number of required and optional parameters.
|
|
|
|
*
|
|
|
|
* \param function A handle to a function or method declaration.
|
|
|
|
* \param fixed_param_count Returns the number of required parameters.
|
|
|
|
* \param opt_param_count Returns the number of optional parameters.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionParameterCounts(
|
|
|
|
Dart_Handle function,
|
|
|
|
int64_t* fixed_param_count,
|
|
|
|
int64_t* opt_param_count);
|
|
|
|
|
2012-09-13 17:47:25 +00:00
|
|
|
/**
|
|
|
|
* Returns a handle to the type of a function parameter.
|
|
|
|
*
|
|
|
|
* \return A valid handle to a type or an error handle if the argument
|
|
|
|
* is not valid.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_FunctionParameterType(Dart_Handle function,
|
|
|
|
int parameter_index);
|
|
|
|
|
2012-07-09 23:57:08 +00:00
|
|
|
/**
|
|
|
|
* Returns a list of the names of all variables declared in a library
|
|
|
|
* or class.
|
|
|
|
*
|
|
|
|
* \param target A library or class.
|
|
|
|
*
|
|
|
|
* \return If no error occurs, a list of strings is returned.
|
2012-09-13 17:47:25 +00:00
|
|
|
* Otherwise an error handle is returned.
|
2012-07-09 23:57:08 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_GetVariableNames(Dart_Handle target);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Looks up a variable declaration by name from a library or class.
|
|
|
|
*
|
2012-09-13 17:47:25 +00:00
|
|
|
* \param target The library or class containing the variable.
|
2012-07-09 23:57:08 +00:00
|
|
|
* \param variable_name The name of the variable.
|
|
|
|
*
|
|
|
|
* \return If an error is encountered, returns an error handle.
|
|
|
|
* Otherwise returns a variable handle if the variable is found or
|
|
|
|
* Dart_Null() if the variable is not found.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_LookupVariable(Dart_Handle target,
|
|
|
|
Dart_Handle variable_name);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this a variable declaration handle?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsVariable(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the name for the provided variable.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_VariableName(Dart_Handle variable);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Determines whether a variable is declared static.
|
|
|
|
*
|
|
|
|
* For the purposes of the embedding API, a top-level variable is
|
|
|
|
* implicitly declared static.
|
|
|
|
*
|
|
|
|
* \param variable A handle to a variable declaration.
|
|
|
|
* \param is_static Returns whether the variable is declared static.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_VariableIsStatic(Dart_Handle variable,
|
|
|
|
bool* is_static);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Determines whether a variable is declared final.
|
|
|
|
*
|
|
|
|
* \param variable A handle to a variable declaration.
|
|
|
|
* \param is_final Returns whether the variable is declared final.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_VariableIsFinal(Dart_Handle variable,
|
|
|
|
bool* is_final);
|
|
|
|
|
2012-09-13 17:47:25 +00:00
|
|
|
/**
|
|
|
|
* Returns the type of a variable.
|
|
|
|
*
|
|
|
|
* \return A valid handle to a type of or an error handle if the
|
|
|
|
* argument is not valid.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_VariableType(Dart_Handle function);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns a list of the names of all type variables declared in a class.
|
|
|
|
*
|
|
|
|
* The type variables list preserves the original declaration order.
|
|
|
|
*
|
|
|
|
* \param clazz A class.
|
|
|
|
*
|
|
|
|
* \return If no error occurs, a list of strings is returned.
|
|
|
|
* Otherwise an error handle is returned.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_GetTypeVariableNames(Dart_Handle clazz);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Looks up a type variable declaration by name from a class.
|
|
|
|
*
|
|
|
|
* \param clazz The class containing the type variable.
|
|
|
|
* \param variable_name The name of the type variable.
|
|
|
|
*
|
|
|
|
* \return If an error is encountered, returns an error handle.
|
|
|
|
* Otherwise returns a type variable handle if the type variable is
|
|
|
|
* found or Dart_Null() if the type variable is not found.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_LookupTypeVariable(Dart_Handle clazz,
|
|
|
|
Dart_Handle type_variable_name);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Is this a type variable handle?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsTypeVariable(Dart_Handle handle);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the name for the provided type variable.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_TypeVariableName(Dart_Handle type_variable);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the owner of a function.
|
|
|
|
*
|
|
|
|
* The owner of a type variable is its defining class.
|
|
|
|
*
|
|
|
|
* \return A valid handle to the owner of the type variable, or an error
|
|
|
|
* handle if the argument is not a valid handle to a type variable.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_TypeVariableOwner(Dart_Handle type_variable);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the upper bound of a type variable.
|
|
|
|
*
|
|
|
|
* The upper bound of a type variable is ...
|
|
|
|
*
|
|
|
|
* \return A valid handle to a type, or an error handle if the
|
|
|
|
* argument is not a valid handle.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_TypeVariableUpperBound(Dart_Handle type_variable);
|
|
|
|
// TODO(turnidge): Finish documentation.
|
|
|
|
|
2012-04-23 17:36:05 +00:00
|
|
|
// --- Constructors, Methods, and Fields ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Invokes a constructor, creating a new object.
|
|
|
|
*
|
|
|
|
* This function allows hidden constructors (constructors with leading
|
|
|
|
* underscores) to be called.
|
|
|
|
*
|
|
|
|
* \param clazz A class or an interface.
|
|
|
|
* \param constructor_name The name of the constructor to invoke. Use
|
|
|
|
* Dart_Null() to invoke the unnamed constructor. This name should
|
|
|
|
* not include the name of the class.
|
|
|
|
* \param number_of_arguments Size of the arguments array.
|
|
|
|
* \param arguments An array of arguments to the constructor.
|
|
|
|
*
|
|
|
|
* \return If the constructor is called and completes successfully,
|
|
|
|
* then the new object. If an error occurs during execution, then an
|
|
|
|
* error handle is returned.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_New(Dart_Handle clazz,
|
|
|
|
Dart_Handle constructor_name,
|
|
|
|
int number_of_arguments,
|
|
|
|
Dart_Handle* arguments);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
2012-03-13 19:49:48 +00:00
|
|
|
* Invokes a method or function.
|
|
|
|
*
|
|
|
|
* The 'target' parameter may be an object, class, or library. If
|
|
|
|
* 'target' is an object, then this function will invoke an instance
|
|
|
|
* method. If 'target' is a class, then this function will invoke a
|
|
|
|
* static method. If 'target' is a library, then this function will
|
|
|
|
* invoke a top-level function from that library.
|
|
|
|
*
|
|
|
|
* This function ignores visibility (leading underscores in names).
|
|
|
|
*
|
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
|
|
|
* \param target An object, class, or library.
|
|
|
|
* \param name The name of the function or method to invoke.
|
|
|
|
* \param number_of_arguments Size of the arguments array.
|
|
|
|
* \param arguments An array of arguments to the function.
|
|
|
|
*
|
|
|
|
* \return If the function or method is called and completes
|
|
|
|
* successfully, then the return value is returned. If an error
|
|
|
|
* occurs during execution, then an error handle is returned.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_Invoke(Dart_Handle target,
|
|
|
|
Dart_Handle name,
|
|
|
|
int number_of_arguments,
|
|
|
|
Dart_Handle* arguments);
|
2012-05-30 17:07:19 +00:00
|
|
|
// TODO(turnidge): Document how to invoke operators.
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2012-03-07 21:15:58 +00:00
|
|
|
* Gets the value of a field.
|
|
|
|
*
|
2012-03-13 19:49:48 +00:00
|
|
|
* The 'container' parameter may be an object, class, or library. If
|
|
|
|
* 'container' is an object, then this function will access an
|
|
|
|
* instance field. If 'container' is a class, then this function will
|
|
|
|
* access a static field. If 'container' is a library, then this
|
|
|
|
* function will access a top-level variable.
|
2012-03-07 21:15:58 +00:00
|
|
|
*
|
|
|
|
* This function ignores field visibility (leading underscores in names).
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
2012-03-07 21:15:58 +00:00
|
|
|
* \param container An object, class, or library.
|
2012-03-13 19:49:48 +00:00
|
|
|
* \param name A field name.
|
2012-03-07 21:15:58 +00:00
|
|
|
*
|
2011-11-01 18:11:36 +00:00
|
|
|
* \return If no error occurs, then the value of the field is
|
2011-11-11 19:31:04 +00:00
|
|
|
* returned. Otherwise an error handle is returned.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-03-07 21:15:58 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_GetField(Dart_Handle container,
|
|
|
|
Dart_Handle name);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets the value of a field.
|
|
|
|
*
|
|
|
|
* The 'container' parameter may actually be an object, class, or
|
|
|
|
* library. If 'container' is an object, then this function will
|
|
|
|
* access an instance field. If 'container' is a class, then this
|
|
|
|
* function will access a static field. If 'container' is a library,
|
|
|
|
* then this function will access a top-level variable.
|
|
|
|
*
|
|
|
|
* This function ignores field visibility (leading underscores in names).
|
|
|
|
*
|
|
|
|
* May generate an unhandled exception error.
|
|
|
|
*
|
|
|
|
* \param container An object, class, or library.
|
2012-03-13 19:49:48 +00:00
|
|
|
* \param name A field name.
|
|
|
|
* \param value The new field value.
|
2012-03-07 21:15:58 +00:00
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_SetField(Dart_Handle container,
|
|
|
|
Dart_Handle name,
|
|
|
|
Dart_Handle value);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Creates a native wrapper class.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Document.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_CreateNativeWrapperClass(Dart_Handle library,
|
|
|
|
Dart_Handle class_name,
|
|
|
|
int field_count);
|
|
|
|
|
2012-05-30 17:07:19 +00:00
|
|
|
/**
|
|
|
|
* Gets the number of native instance fields in an object.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_GetNativeInstanceFieldCount(Dart_Handle obj,
|
|
|
|
int* count);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Gets the value of a native field.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Document.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_GetNativeInstanceField(Dart_Handle obj,
|
|
|
|
int index,
|
|
|
|
intptr_t* value);
|
|
|
|
/**
|
|
|
|
* Sets the value of a native field.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Document.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_SetNativeInstanceField(Dart_Handle obj,
|
|
|
|
int index,
|
|
|
|
intptr_t value);
|
|
|
|
|
|
|
|
// --- Exceptions ----
|
2012-06-12 21:07:49 +00:00
|
|
|
// TODO(turnidge): Remove these functions from the api and replace all
|
|
|
|
// uses with Dart_NewUnhandledExceptionError.
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Throws an exception.
|
|
|
|
*
|
2012-08-07 18:01:46 +00:00
|
|
|
* This function causes a Dart language exception to be thrown. This
|
|
|
|
* will proceeed in the standard way, walking up Dart frames until an
|
|
|
|
* appropriate 'catch' block is found, executing 'finally' blocks,
|
|
|
|
* etc.
|
|
|
|
*
|
|
|
|
* If successful, this function does not return. Note that this means
|
2011-11-01 18:11:36 +00:00
|
|
|
* that the destructors of any stack-allocated C++ objects will not be
|
2011-11-11 19:31:04 +00:00
|
|
|
* called. If there are no Dart frames on the stack, an error occurs.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return An error handle if the exception was not thrown.
|
2011-11-01 18:11:36 +00:00
|
|
|
* Otherwise the function does not return.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_ThrowException(Dart_Handle exception);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Rethrows an exception.
|
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* Rethrows an exception, unwinding all dart frames on the stack. If
|
|
|
|
* successful, this function does not return. Note that this means
|
2011-11-01 18:11:36 +00:00
|
|
|
* that the destructors of any stack-allocated C++ objects will not be
|
2011-11-11 19:31:04 +00:00
|
|
|
* called. If there are no Dart frames on the stack, an error occurs.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2011-11-11 19:31:04 +00:00
|
|
|
* \return An error handle if the exception was not thrown.
|
2011-11-01 18:11:36 +00:00
|
|
|
* Otherwise the function does not return.
|
|
|
|
*/
|
2011-11-08 19:18:22 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_RethrowException(Dart_Handle exception,
|
2011-11-01 18:11:36 +00:00
|
|
|
Dart_Handle stacktrace);
|
|
|
|
|
|
|
|
// --- Native functions ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* The arguments to a native function.
|
|
|
|
*
|
|
|
|
* This object is passed to a native function to represent its
|
|
|
|
* arguments and return value. It allows access to the arguments to a
|
|
|
|
* native function by index. It also allows the return value of a
|
|
|
|
* native function to be set.
|
|
|
|
*/
|
2011-12-01 18:18:06 +00:00
|
|
|
typedef struct _Dart_NativeArguments* Dart_NativeArguments;
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the native argument at some index.
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_GetNativeArgument(Dart_NativeArguments args,
|
|
|
|
int index);
|
2011-11-01 18:11:36 +00:00
|
|
|
// TODO(turnidge): Specify the behavior of an out-of-bounds access.
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Gets the number of native arguments.
|
|
|
|
*/
|
2011-10-24 23:44:29 +00:00
|
|
|
DART_EXPORT int Dart_GetNativeArgumentCount(Dart_NativeArguments args);
|
2011-11-01 18:11:36 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets the return value for a native function.
|
|
|
|
*/
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT void Dart_SetReturnValue(Dart_NativeArguments args,
|
|
|
|
Dart_Handle retval);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* A native function.
|
|
|
|
*/
|
|
|
|
typedef void (*Dart_NativeFunction)(Dart_NativeArguments arguments);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Native entry resolution callback.
|
|
|
|
*
|
|
|
|
* For libraries and scripts which have native functions, the embedder
|
|
|
|
* can provide a native entry resolver. This callback is used to map a
|
|
|
|
* name/arity to a Dart_NativeFunction. If no function is found, the
|
|
|
|
* callback should return NULL.
|
|
|
|
*
|
|
|
|
* See Dart_SetNativeResolver.
|
|
|
|
*/
|
|
|
|
typedef Dart_NativeFunction (*Dart_NativeEntryResolver)(Dart_Handle name,
|
|
|
|
int num_of_arguments);
|
|
|
|
// TODO(turnidge): Consider renaming to NativeFunctionResolver or
|
|
|
|
// NativeResolver.
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Scripts and Libraries ---
|
|
|
|
// TODO(turnidge): Finish documenting this section.
|
|
|
|
|
|
|
|
typedef enum {
|
|
|
|
kLibraryTag = 0,
|
|
|
|
kImportTag,
|
|
|
|
kSourceTag,
|
2012-03-07 16:03:01 +00:00
|
|
|
kCanonicalizeUrl
|
2011-11-01 18:11:36 +00:00
|
|
|
} Dart_LibraryTag;
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-21 19:09:51 +00:00
|
|
|
// TODO(turnidge): Document.
|
2011-11-01 18:11:36 +00:00
|
|
|
typedef Dart_Handle (*Dart_LibraryTagHandler)(Dart_LibraryTag tag,
|
|
|
|
Dart_Handle library,
|
2012-05-23 18:32:51 +00:00
|
|
|
Dart_Handle url);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2012-05-10 19:17:37 +00:00
|
|
|
/**
|
2012-05-23 18:32:51 +00:00
|
|
|
* Sets library tag handler for the current isolate. This handler is
|
|
|
|
* used to handle the various tags encountered while loading libraries
|
|
|
|
* or scripts in the isolate.
|
2012-05-10 19:17:37 +00:00
|
|
|
*
|
|
|
|
* \param handler Handler code to be used for handling the various tags
|
|
|
|
* encountered while loading libraries or scripts in the isolate.
|
|
|
|
*
|
|
|
|
* \return If no error occurs, the handler is set for the isolate.
|
|
|
|
* Otherwise an error handle is returned.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Document.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_SetLibraryTagHandler(
|
|
|
|
Dart_LibraryTagHandler handler);
|
|
|
|
|
2012-05-23 18:32:51 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Loads the root script for the current isolate.
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Document.
|
|
|
|
*/
|
2011-10-26 20:38:41 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_LoadScript(Dart_Handle url,
|
2012-05-23 18:32:51 +00:00
|
|
|
Dart_Handle source);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-12-06 00:34:49 +00:00
|
|
|
/**
|
|
|
|
* Loads the root script for current isolate from a snapshot.
|
|
|
|
*
|
|
|
|
* \param buffer A buffer which contains a snapshot of the script.
|
|
|
|
*
|
|
|
|
* \return If no error occurs, the Library object corresponding to the root
|
|
|
|
* script is returned. Otherwise an error handle is returned.
|
2012-05-23 18:32:51 +00:00
|
|
|
*/
|
2011-12-06 00:34:49 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_LoadScriptFromSnapshot(const uint8_t* buffer);
|
|
|
|
|
2012-05-23 18:32:51 +00:00
|
|
|
/**
|
|
|
|
* Gets the library for the root script for the current isolate.
|
|
|
|
*
|
2012-05-30 17:07:19 +00:00
|
|
|
* If the root script has not yet been set for the current isolate,
|
|
|
|
* this function returns Dart_Null(). This function never returns an
|
|
|
|
* error handle.
|
|
|
|
*
|
|
|
|
* \return Returns the root Library for the current isolate or Dart_Null().
|
2012-05-23 18:32:51 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_RootLibrary();
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Forces all loaded classes and functions to be compiled eagerly in
|
|
|
|
* the current isolate..
|
|
|
|
*
|
|
|
|
* TODO(turnidge): Document.
|
|
|
|
*/
|
2011-10-26 20:38:41 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_CompileAll();
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Is this object a Library?
|
|
|
|
*/
|
|
|
|
DART_EXPORT bool Dart_IsLibrary(Dart_Handle object);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
2012-05-23 21:54:00 +00:00
|
|
|
* Lookup a class or interface by name from a Library.
|
2011-11-01 18:11:36 +00:00
|
|
|
*
|
2012-05-23 21:54:00 +00:00
|
|
|
* \param library The library containing the class or interface.
|
|
|
|
* \param class_name The name of the class or interface.
|
|
|
|
*
|
|
|
|
* \return If no error occurs, the class or interface is
|
|
|
|
* returned. Otherwise an error handle is returned.
|
2011-11-01 18:11:36 +00:00
|
|
|
*/
|
2012-05-23 21:54:00 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library,
|
|
|
|
Dart_Handle class_name);
|
2012-03-08 23:06:44 +00:00
|
|
|
// TODO(turnidge): Consider returning Dart_Null() when the class is
|
|
|
|
// not found to distinguish that from a true error case.
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2012-05-30 17:07:19 +00:00
|
|
|
/**
|
|
|
|
* Returns the name of a library as declared in the #library directive.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_LibraryName(Dart_Handle library);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the url from which a library was loaded.
|
|
|
|
*/
|
2011-11-21 19:09:51 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library);
|
|
|
|
|
2012-06-12 21:07:49 +00:00
|
|
|
/**
|
|
|
|
* Returns a list of the names of all classes and interfaces declared
|
|
|
|
* in a library.
|
|
|
|
*
|
|
|
|
* \return If no error occurs, a list of strings is returned.
|
2012-09-13 17:47:25 +00:00
|
|
|
* Otherwise an error handle is returned.
|
2012-06-12 21:07:49 +00:00
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_LibraryGetClassNames(Dart_Handle library);
|
|
|
|
|
2011-11-22 19:42:38 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url);
|
2012-03-08 23:06:44 +00:00
|
|
|
// TODO(turnidge): Consider returning Dart_Null() when the library is
|
|
|
|
// not found to distinguish that from a true error case.
|
2011-11-22 19:42:38 +00:00
|
|
|
|
2011-11-21 19:09:51 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_LoadLibrary(Dart_Handle url,
|
2012-05-23 18:32:51 +00:00
|
|
|
Dart_Handle source);
|
2011-11-21 19:09:51 +00:00
|
|
|
|
2012-08-29 08:35:43 +00:00
|
|
|
/**
|
|
|
|
* Imports a library into another library, optionally with a prefix.
|
|
|
|
* If no prefix is required, an empty string or Dart_Null() can be
|
|
|
|
* supplied.
|
|
|
|
*
|
|
|
|
* \param library The library into which to import another library.
|
|
|
|
* \param import The library to import.
|
|
|
|
* \param prefix The prefix under which to import.
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-11-01 18:11:36 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_LibraryImportLibrary(Dart_Handle library,
|
2012-08-29 08:35:43 +00:00
|
|
|
Dart_Handle import,
|
|
|
|
Dart_Handle prefix);
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2012-07-12 19:21:08 +00:00
|
|
|
/**
|
|
|
|
* Loads a source string into a library.
|
|
|
|
*
|
|
|
|
* \param library A library
|
|
|
|
* \param url A url identifying the origin of the source
|
|
|
|
* \param source A string of Dart source
|
|
|
|
*
|
|
|
|
* \return A valid handle if no error occurs during the operation.
|
|
|
|
*/
|
2011-11-01 18:11:36 +00:00
|
|
|
DART_EXPORT Dart_Handle Dart_LoadSource(Dart_Handle library,
|
|
|
|
Dart_Handle url,
|
|
|
|
Dart_Handle source);
|
2011-11-21 19:09:51 +00:00
|
|
|
// TODO(turnidge): Rename to Dart_LibraryLoadSource?
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2012-10-26 08:00:05 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Loads a patch source string into a library.
|
|
|
|
*
|
|
|
|
* \param library A library
|
|
|
|
* \param url A url identifying the origin of the patch source
|
|
|
|
* \param source A string of Dart patch source
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_LoadPatch(Dart_Handle library,
|
|
|
|
Dart_Handle url,
|
|
|
|
Dart_Handle patch_source);
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
/**
|
|
|
|
* Sets the callback used to resolve native functions for a library.
|
|
|
|
*
|
|
|
|
* \param library A library.
|
|
|
|
* \param resolver A native entry resolver.
|
|
|
|
*
|
|
|
|
* \return A valid handle if the native resolver was set successfully.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_SetNativeResolver(
|
|
|
|
Dart_Handle library,
|
|
|
|
Dart_NativeEntryResolver resolver);
|
2011-11-21 19:09:51 +00:00
|
|
|
// TODO(turnidge): Rename to Dart_LibrarySetNativeResolver?
|
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// --- Profiling support ----
|
2011-10-05 05:20:07 +00:00
|
|
|
|
2011-11-01 18:11:36 +00:00
|
|
|
// External pprof support for gathering and dumping symbolic
|
|
|
|
// information that can be used for better profile reports for
|
|
|
|
// dynamically generated code.
|
2011-10-05 05:20:07 +00:00
|
|
|
DART_EXPORT void Dart_InitPprofSupport();
|
|
|
|
DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
|
|
|
|
|
2012-07-26 00:21:25 +00:00
|
|
|
typedef void (*Dart_FileWriterFunction)(const char* buffer, int64_t num_bytes);
|
|
|
|
|
|
|
|
// Support for generating symbol maps for use by the Linux perf tool.
|
|
|
|
DART_EXPORT void Dart_InitPerfEventsSupport(Dart_FileWriterFunction function);
|
|
|
|
|
2012-09-18 21:15:46 +00:00
|
|
|
// --- Peers ---
|
|
|
|
|
|
|
|
/**
|
|
|
|
* The peer field is a lazily allocated field intendend for storage of
|
|
|
|
* an uncommonly used values. Most instances types can have a peer
|
|
|
|
* field allocated. The exceptions are subtypes of Null, num, and
|
|
|
|
* bool.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the value of peer field of 'object' in 'peer'.
|
|
|
|
*
|
|
|
|
* \param object An object.
|
|
|
|
* \param peer An out parameter that returns the value of the peer
|
|
|
|
* field.
|
|
|
|
*
|
|
|
|
* \return Returns an error if 'object' is a subtype of Null, num, or
|
|
|
|
* bool.
|
|
|
|
*/
|
|
|
|
DART_EXPORT Dart_Handle Dart_GetPeer(Dart_Handle object, void** peer);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets the value of the peer field of 'object' to the value of
|
|
|
|
* 'peer'.
|
|
|
|
*
|
|
|
|
* \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);
|
|
|
|
|
2011-10-05 05:20:07 +00:00
|
|
|
#endif // INCLUDE_DART_API_H_
|