Alchemy:Documentation:Developing with Alchemy:C API
From Adobe Labs
Alchemy C/C++ API
This API is declared in AS3.h found in $ALCHEMY_HOME/avm2_clib/include. In general where const char* is passed and no length is passed, the string is assumed to be NULL-terminated.
Managing ActionScript objects
These functions can be used to create instances of various ActionScript types and manage references to them. You can always create objects directly using the namespace APIs as well.
AS3_Val
This is the type Alchemy uses to represent ActionScript objects. Internals of the structure may change in later release.
void AS3_Acquire(AS3_Val obj)
This method increments the reference count for the ActionScript object. This impacts whether the runtime will collect this object when the GC is run next.
void AS3_Release(AS3_Val obj)
This method decrements the reference count for the ActionScript object. This impacts whether the runtime will collect this object when the GC is run next.
AS3_Val AS3_New(AS3_Val constr, AS3_Val params)
This method will call the ActionScript method constr passing the params value to it. The params value must be an ActionScript object of type Array. It may be empty if there are no parameters needed, but it should not be null. The return value is the newly constructed ActionScript object. To get the constructor method to use, you will need to query the appropriate namespace. See AS3_NSGet for a good example of this.
AS3_Malloced_Str AS3_TypeOf(AS3_Val obj)
Get the ActionScript type for the passed object. The returned string must be free'd.
int AS3_InstanceOf(AS3_Val val, AS3_Val type)
Compares the type of val against the class type passed in.
- val an ActionScript object
- type an ActionScript class retrieved via NSGet
Returns 0 if val is not of type type. Returns non-zero otherwise.
Example:
AS3_Val ArrayClass = AS3_NSGetS(NULL, "Array");
if(!AS3_InstanceOf(AS3_Array(""), ArrayClass))) sztrace("whaaa!");
AS3_Val AS3_NSGet(AS3_Val ns, AS3_Val prop)
This method does a lookup in the runtime for the named property in the specified namespace.
- ns must be an ActionScript String that contains the name of the namespace you want to look in. NULL may be passed here to look in the default runtime namespace (e.g. for things defined by the runtime itself like trace() and Array)
- prop must be an ActionScript String that contains the name of the property you are looking for.
The function returns whatever the runtime has defined as that property, typically a method. If the value is not found, NULL is returned.
Example:
AS3_Val flash_utils_namespace = AS3_String("flash.utils");
AS3_Val ByteArray_property = AS3_String("ByteArray");
AS3_Val ByteArray_class = AS3_NSGetS(flash_utils_namespace, ByteArray_property);
AS3_Val byteArray = AS3_New(ByteArray_class, no_params);
AS3_Release(ByteArray_class);
AS3_Release(ByteArray_property);
AS3_Release(flash_utils_namespace);
AS3_Val AS3_NSGetS(AS3_Val ns, const char *prop)
This method is the same as AS3_NSGet() but uses a const char* instead of an ActionScript String for the property name. The return value is the same.
Example:
AS3_Val flash_utils_namespace = AS3_String("flash.utils");
AS3_Val ByteArray_class = AS3_NSGetS(flash_utils_namespace, "ByteArray");
AS3_Val byteArray = AS3_New(ByteArray_class, no_params);
AS3_Release(ByteArray_class);
AS3_Release(flash_utils_namespace);
Converting C/C++ Values to ActionScript objects
AS3_Val AS3_String(const char* str)
Returns a newly created ActionScript String object whose contents are copied from const char* value passed in. Null-termination is assumed. Must be released with AS3_Release().
AS3_Val AS3_StringN(const char* str, int len)
Returns a newly created ActionScript String object whose contents are copied from first <len> bytes of the const char* value passed in. Must be released with AS3_Release().
AS3_Val AS3_Int(int)
Returns a newly created ActionScript int object that contains the value passed in. Must be released with AS3_Release().
AS3_Val AS3_Ptr(void* ptr)
Returns a newly created ActionScript uint whose value is the offset of this value from the beginning of the ByteArray being used as "ram". Must be released with AS3_Release().
AS3_Val AS3_Number(double d)
Returns a newly created ActionScript Number object that contains the double passed in. Must be released with AS3_Release().
AS3_Val AS3_True()
Returns a newly created ActionScript Boolean object set to true. Must be released with AS3_Release().
AS3_Val AS3_False()
Returns a newly created ActionScript Boolean object set to false. Must be released with AS3_Release().
AS3_Val AS3_Null()
Returns a "null" reference to pass to ActionScript. This does not need to be released.
AS3_Val AS3_Undefined()
Returns an "undefined" reference to pass to ActionScript. This does not need to be released.
AS3_Val AS3_Array(const char *tt, ...)
This method creates an ActionScript Array from a type template and list of parameters. tt is the type template and format looks like "type0, type1, type2". The types supported are:
- IntType -- maps to int
- PtrType -- maps to void*
- DoubleType -- maps to double
- StrType -- maps to char*
- AS3ValType -- maps to AS3_Val
The return value is the new Array containing the values passed. You will need to call AS3_Release() when you are done with it.
Example:
AS3_Val point = AS3_Array("IntType, IntType", x, y);
AS3_Val AS3_Object(const char *tt, ...)
This method creates an ActionScript Object from a type template and list of parameters. tt is the type template and format looks like "name0:type0, name1:type1, name2:type2". The types supported are the same as for AS3_Array().
The return value is the new Object containing the values passed with the name specified. You will need to call AS3_Release() when you are done with it.
Example:
AS3_Val addr = AS3_Array("city:StrType, state:StrType, zip:StrType", "Anytown", "State", "12345");
Converting ActionScript objects to C/C++ Values
AS3_Malloced_Str AS3_StringValue(AS3_Val obj)
Convert the ActionScript object passed to a char*. The returned value must be freed.
int AS3_IntValue(AS3_Val obj)
Convert the ActionScript object passed to an int.
void* AS3_PtrValue(AS3_Val obj)
Convert the ActionScript object passed to a void*.
double AS3_NumberValue(AS3_Val obj)
Convert the ActionScript object passed to a double.
void AS3_ArrayValue(AS3_Val arr, const char *tt, ...)
This function is used to extract values from the ActionScript Array arr according to the tt type template. The format of tt follows that of AS3_Array(). The parameters following tt should all be pointers to variables of the expected type. If the number of type entries in tt exceeds the number of elements in the Array, the additional variables are ignored. If the number of elements in the Array exceeds the number of entries in tt, the additional entries are ignored.
Example:
int arg0 = 0; char* arg1 = NULL; double arg2 = 0.0; AS3_ArrayValue(arr, "IntType, StrType, DoubleType", &arg0, &arg1, &arg2);
void AS3_ObjectValue(AS3_Val arr, const char *tt, ...)
This function is used to extract values from the ActionScript Object obj according to the tt type template. The format of tt follows that of AS3_Object(). The parameters following tt should all be pointers to variables of the expected type. If a named entry in tt does not appear in in the Object, it is ignored. If a named member of the Object does not appear in tt, it is ignored.
Example:
int arg0 = 0; char* arg1 = NULL; double arg2 = 0.0; AS3_ObjectValue(obj, "foo:IntType, bar:StrType, baz:DoubleType", &arg0, &arg1, &arg2);
Assuming the Object obj contained the named elements and the types are correct, all the variables will be initialized from the Object.
Calling ActionScript methods from C/C++
AS3_Val AS3_Get(AS3_Val obj, AS3_Val prop)
This method does a lookup on the object passed for the named property.
- obj must be a valid ActionScript object
- prop must be an ActionScript String that contains the name of the property you are looking for.
The function returns the named property for that object. This will call a "getter" function if present. If the value is not found, NULL is returned.
Example:
AS3_Val length_property = AS3_String("length");
AS3_Val length = AS3_GetS(byteArray, length_property);
AS3_Release(length_property);
AS3_Val AS3_GetS(AS3_Val obj, const char *prop)
This method is the same as AS3_Get() but uses a const char* instead of an ActionScript String for the property name. The return value is the same.
Example:
AS3_Val length = AS3_GetS(byteArray, "length");
AS3_Val AS3_Set(AS3_Val obj, AS3_Val prop, AS3_Val val)
This method does a lookup on the object passed for the named property.
- obj must be a valid ActionScript object
- prop must be an ActionScript String that contains the name of the property you are looking for.
The function sets the named property for that object to the value passed. This will call a "setter" function if present. No value is returned.
Example:
AS3_Val position_property = AS3_String("position");
AS3_Val zero = AS3_Int(0);
AS3_SetS(byteArray, position_property, zero);
AS3_Release(zero);
AS3_Release(position_property);
AS3_Val AS3_SetS(AS3_Val obj, const char *prop, AS3_Val val)
This method is the same as AS3_Set() but uses a const char* instead of an ActionScript String for the property name. No value is returned.
Example:
AS3_Val zero = AS3_Int(0); AS3_SetS(byteArray, "position", zero); AS3_Release(zero);
AS3_Val AS3_Call(AS3_Val func, AS3_Val thiz, AS3_Val params)
Calls the ActionScript function func on the object thiz passing params.
- func is a function reference retrieved from a namespace using NSGet/NSGetS or an object using Get/GetS
- thiz is a valid ActionScript object for this function to act on. Can be AS3_Undefined() for top-level ActionScript methods like trace().
- params is an ActionScript Array containing the parameters to pass to func
Example:
AS3_Val baNS = AS3_String("flash.utils");
AS3_Val baClass = AS3_NSGetS(baNS, "ByteArray");
AS3_Val emptyParams = AS3_Array("");
AS3_Val ba = AS3_New(baClass, emptyParams);
AS3_Val readUTFBytes = AS3_GetS(ba, "readUTFBytes");
AS3_Val lenParams = AS3_Array("IntType", strlen(buf));
AS3_Val str = AS3_Call(readUTFBytes, ba, lenParams);
AS3_Val AS3_CallS(const char *func, AS3_Val thiz, AS3_Val params)
Same as AS3_Call but func is a const char* and required to be a function on the object passed as thiz.
- func is a const char* pointing to the name of the function to call on thiz
- thiz is a valid ActionScript object
- params is an ActionScript Array containing the parameters to pass to func
Example:
...
AS3_Val str = AS3_Call("readUTFBytes", ba, lenParams);
AS3_Val AS3_CallT(AS3_Val func, AS3_Val thiz, const char *tt, ...)
Calls the ActionScript function func on the object thiz passing an ActionScript Array constructed using tt and other parameters.
- func is a const char* pointing to the name of the function to call on thiz
- thiz is a valid ActionScript object
- tt is a type template describing the parameters following it.
In this method, the Array passed to func is constructed from tt and the parameters following.
AS3_Val AS3_CallTS(const char *func, AS3_Val thiz, const char *tt, ...)
Same as AS3_CallT but func is a const char* and required to be a function on the object passed as thiz.
Example:
...
AS3_Val str = AS3_CallTS("readUTFBytes", ba, "IntType", 16);
void *AS3_Shim(AS3_Val func, AS3_Val thiz, const char *rt, const char *tt, int varargs)
Create a C function pointer that thunks to thiz.func(...).
int (*myfunc)(const char *s, double n) = AS3_Shim(someFunc, someThiz, "IntType, StrType, NumberType", false);
The function pointer is PERMANENT!
AS3_Val AS3_Proxy()
Create a Proxy object that delegates callProperty, etc. to the Function vars in the object in the flash_delegate namespace!
i.e., delgates to flash_delegate::callProperty, not public callProperty.
Calling C/C++ methods from ActionScript methods
AS3_ThunkProc
This is the typedef Alchemy uses for C/C++ function callbacks.
typedef AS3_Val (*AS3_ThunkProc)(void *data, AS3_Val params);
AS3_Val AS3_Function(void *data, AS3_ThunkProc proc)
Create a synchronous function callback object, binding the function pointer with the data passed in.
- data can be used to hold state for the function
AS3_Val AS3_FunctionAsync(void *data, AS3_ThunkProc proc)
Create an asynchronous function callback object, binding the function pointer with the data passed in.
- data can be used to hold state for the function
AS3_Val AS3_FunctionT(void *data, void *proc, const char *rt, const char *tt, int varargs)
Create an synchronous function callback object , binding it with the data passed in.
- data can be used to hold state for the function
AS3_Val AS3_FunctionAsyncT(void *data, void *proc, const char *rt, const char *tt, int varargs)
Create an asynchronous function callback object, binding it with the data passed in.
- data can be used to hold state for the function
Miscellaneous
void AS3_LibInit(AS3_Val libData)
This method notifies the runtime that the library has initialized.
- libData should be the ActionScript Object containing your library methods (if any).
This call does not return, so no code should be placed after it. If this is not called from your C program, the runtime will never get the chance to execute any code outside of your C program (like updating the stage). For an example of using this -- see the AS3Lib project from the Alchemy samples.
AS3_Val AS3_Stage()
This method returns the runtime stage object (typically ConSprite). You can then perform actions on it to manipulate the stage.
AS3_Val AS3_Ram()
This method returns the ByteArray that represents all of the RAM for your C program. Since you are using that RAM, be very careful what you do with it!
void flyield()
This method will force the Alchemy state machine to give up it's time slice. Execution will return to the line following this call on the next Alchemy time-slicing timer tick.
void sztrace(char* msg)
This method will print the msg to the log and to the trace window if running in FlexBuilder or to STDOUT if running with swfbridge.
void AS3_Trace(AS3_Val val)
This method will print the value passed to the log and to the trace window if running in FlexBuilder or to STDOUT if running with swfbridge.
int AS3_ByteArray_readBytes(void *dst, AS3_Val src, int len)
Reads len bytes from the ByteArray src at the current position into the buffer pointed to by dst.
int AS3_ByteArray_writeBytes(AS3_Val dst, void *src, int len)
Writes len bytes from the buffer src into the ByteArray dst at the current position.
int AS3_ByteArray_seek(AS3_Val dst, int offs, int whence)
Adjust the position in the ByteArray dst according to "lseek" style rules.