Alchemy文档:开发Alchemy 、C API（as3与C交互转换）

1 Alchemy C/C++ API

1.1 Managing ActionScript objects:管理ActionScript对象

1.1.1 AS3_Val:AS3值对象

1.1.2 void AS3_Acquire(AS3_Val obj):增加obj的引用计数

1.1.3 void AS3_Release(AS3_Val obj):减小obj的引用计数

1.1.4 AS3_Val AS3_New(AS3_Val constr, AS3_Val params):

把constr构造函数（用AS3_NSGet获取）应用到非null（可以是空的）的Array型变量params上。

1.1.5 AS3_Malloced_Str AS3_TypeOf(AS3_Val obj):

获取obj的类型的malloc字符串（返回值需要free）

1.1.6 int AS3_InstanceOf(AS3_Val val, AS3_Val type):

判断val是否属于type（用NSGet获取）类型，如果是返回非0，否返回0。

1.1.7 AS3_Val AS3_NSGet(AS3_Val ns, AS3_Val prop):

运行时通过ns（AS3_String，例如"flash.utils"）

和prop（AS3_String，例如"ByteArray"）查找类。

1.1.8 AS3_Val AS3_NSGetS(AS3_Val ns, const char *prop):

同AS3_NSGet，只不过prop是C风格常数值，不需要AS3_Release。

1.2 Converting C/C++ Values to ActionScript objects

C/C++到AS的值转换。

1.2.1 AS3_Val AS3_String(const char* str):

const char[]（C风格）转String，需要AS3_Release释放。

1.2.2 AS3_Val AS3_StringN(const char* str, int len):

void *转String，需要AS3_Release释放。

1.2.3 AS3_Val AS3_Int(int):

int转AS3的int，需要AS3_Release释放。

1.2.4 AS3_Val AS3_Ptr(void* ptr):

void *转ByteArray（用uint读写），需要AS3_Release释放。

1.2.5 AS3_Val AS3_Number(double d):

double转Number，需要AS3_Release释放。

1.2.6 AS3_Val AS3_True():

获取true，需要AS3_Release释放。

1.2.7 AS3_Val AS3_False():

获取false，需要AS3_Release释放。

1.2.8 AS3_Val AS3_Null():

获取null，无需释放。

1.2.9 AS3_Val AS3_Undefined()

获取undefined，无需释放。

1.2.10 AS3_Val AS3_Array(const char *tt, ...):

printf风格的Array构造式，例如：

AS3_Val point = AS3_Array("IntType, IntType", x, y);

支持"IntType"(int)，"PtrType"(void*)，

"DoubleType"(double)，"StrType"(char *)，

"AS3ValType"(AS3_Val)。

需要AS3_Release释放。

1.2.11 AS3_Val AS3_Object(const char *tt, ...)

同上，但是构造Object对象，需要AS3_Release释放。

1.3 Converting ActionScript objects to C/C++ Values

AS3到C/C++的值转换

1.3.1 AS3_Malloced_Str AS3_StringValue(AS3_Val obj)

String转char[]（malloc，需要free）

1.3.2 int AS3_IntValue(AS3_Val obj)

AS3的int转int。

1.3.3 void* AS3_PtrValue(AS3_Val obj)

Object转void *。

1.3.4 double AS3_NumberValue(AS3_Val obj)

Number转double。

1.3.5 void AS3_ArrayValue(AS3_Val arr, const char *tt, ...)

scanf风格的Array分解。例如：

int arg0 = 0;

char* arg1 = NULL;

double arg2 = 0.0;

AS3_ArrayValue(arr, "IntType, StrType, DoubleType", &arg0, &arg1, &arg2)

1.3.6 void AS3_ObjectValue(AS3_Val arr, const char *tt, ...)

同上，但是对Object的分解

1.4 Calling ActionScript methods from C/C++

从C/C++中调用AS3方法

1.4.1 AS3_Val AS3_Get(AS3_Val obj, AS3_Val prop)

对obj执行prop（例如AS3_String("length")）的属性读取，

1.4.2 AS3_Val AS3_GetS(AS3_Val obj, const char *prop)

同AS3_Get，不过prop是C风格常数字符串，不需要AS3_Release。

1.4.3 AS3_Val AS3_Set(AS3_Val obj, AS3_Val prop, AS3_Val val)

对obj的prop执行属性设置，值为val。

1.4.4 AS3_Val AS3_SetS(AS3_Val obj, const char *prop, AS3_Val val)

同AS3_Set，不过prop是C风格常数字符串，不需要AS3_Release。

1.4.5 AS3_Val AS3_Call(AS3_Val func, AS3_Val thiz, AS3_Val params)

对thiz（如果是AS3_Undefined()则为顶级调用）

执行func（可以是NSGet/NSGetS的名字空间(常规函数)或Get/GetS的对象(闭包)）

函数调用，传入Array型的params（例如AS3_Array("IntType", strlen(buf))）作为参数。

1.4.6 AS3_Val AS3_CallS(const char *func, AS3_Val thiz, AS3_Val params)

同AS3_Call，不过func是C风格常数字符串，不需要AS3_Release。

1.4.7 AS3_Val AS3_CallT(AS3_Val func, AS3_Val thiz, const char *tt, ...)

同AS3_Call，不过params换成变长参数tt。

1.4.8 AS3_Val AS3_CallTS(const char *func, AS3_Val thiz, const char *tt, ...)

同AS3_CallS，不过params换成变长参数tt。

1.4.9 void *AS3_Shim(AS3_Val func, AS3_Val thiz, const char *rt, const char *tt, int varargs)

获取永久的函数指针，但实际上没有调用它（就像AS3的闭包）。例如：

int (*myfunc)(const char *s, double n) =?

AS3_Shim(someFunc, someThiz, "IntType, StrType, NumberType", false);

1.4.10 AS3_Val AS3_Proxy()

创建AS3的Proxy对象，以代理flash_delegate名字空间下的函数

例如flash_delegate::callProperty而非public::callProperty

（注：这里怀疑是用来针对Proxy派生类对象的属性和方法访问，

因为用flash_delegate限定而非public限定，所以需要单独处理）

1.5 Calling C/C++ methods from ActionScript methods

从AS3中调用C/C++方法

1.5.1 AS3_ThunkProc

用typedef定义回调函数的一般形式。

typedef AS3_Val (*AS3_ThunkProc)(void *data, AS3_Val params);

1.5.2 AS3_Val AS3_Function(void *data, AS3_ThunkProc proc)

注册同步回调函数proc，data是用户数据，作为第一参数传给proc的第一参数。

1.5.3 AS3_Val AS3_FunctionAsync(void *data, AS3_ThunkProc proc)

注册异步回调函数proc，data是用户数据，作为第一参数传给proc的第一参数。

1.5.4 AS3_Val AS3_FunctionT(void *data, void *proc, const char *rt, const char *tt, int varargs):

同AS3_Function，不过proc的参数表是不规则的（不同于AS3_ThunkProc）

1.5.5 AS3_Val AS3_FunctionAsyncT(void *data, void *proc, const char *rt, const char *tt, int varargs):

同AS3_FunctionAsync，不过proc的参数表是不规则的（不同于AS3_ThunkProc）

1.6 Miscellaneous

杂项

1.6.1 void AS3_LibInit(AS3_Val libData)

初始化用户定义的libData库对象，永不返回的函数。

1.6.2 AS3_Val AS3_Stage()

获取运行时舞台对象（例如ConSprite），然后操作它。

1.6.3 AS3_Val AS3_Ram()

获取存放C程序中使用的所有RAM的ByteArray变量。

 

1.6.4 void flyield()

放弃当前时间分片，在下次时间分片时返回以继续下面的语句。

1.6.5 void sztrace(char* msg)

用FlexBuilder的话相当于trace()，用swfbridge的话则相当于STDOUT输出。

1.6.6 void AS3_Trace(AS3_Val val)

同sztrace，不过参数是需要AS3_Release的String值

1.6.7 int AS3_ByteArray_readBytes(void *dst, AS3_Val src, int len)

从ByteArray型的src中读取len长度的字节到dst中

1.6.8 int AS3_ByteArray_writeBytes(AS3_Val dst, void *src, int len)

把len字节长度的src写入ByteArray型的dst中。

1.6.9 int AS3_ByteArray_seek(AS3_Val dst, int offs, int whence)

调整ByteArray型dst的游标位置，类似lseek的用法。

-----------------------------

Alchemy:Documentation:Developing with Alchemy:AS3 API

1 Manipulating the Alchemy state machine

操作Alchemy状态机

1.1 CLibInit

CLibInit用于暴露C代码给AS3使用。

init():*:?

初始化，返回导出C函数（一般名称和C函数是相同的）的对象。

setSprite(sprite:Sprite):void:?

设置一个Sprite对象给Alchemy，Alchemy会创建一个TextField然后把STDOUT, STDERR输出内容输出到这个文本域上。

也用于STDIN。

putEnv(key:String, value:String:?

设置环境变量，供C代码的getenv()读取

supplyFile(path:String, data:ByteArray):?

提供文件系统。以避免运行时由于安全限制而无法访问的情况。

gstate：

全局变量，保存Alchemy的状态机。

1.2 GLEByteArrayProvider

这个类允许直接访问C库的RAM（如同操作ByteArray型变量）

get:?

返回当前的领域内存，不存在的话开辟数字低位在前（little endian）的新RAM。

1.3 MemUser

直接操作C库的RAM，以addr偏移的形式访问（如同C代码一样）。

读取RAM：

_mr32(addr:int):int: 32位整型

_mru16(addr:int):int: 16位无符号整型

_mrs16(addr:int):int: 16位有符号整型

_mru8(addr:int):int: 8位无符号整型

_mrs8(addr:int):int: 16位有符号整型

_mrf(addr:int):Number: 浮点型

_mrd(addr:int):Number: 双精度

写入RAM：

_mw32(addr:int, val:int):void: 32位整型

_mw16(addr:int, val:int):void: 16位整型

_mw8(addr:int, val:int):void: 8位整型

_mwf(addr:int, val:Number):void: 浮点型

_mwd(addr:int, val:Number):void: 双精型

2 Calling Functions Exported from C

在AS3中调用C导出函数

在flash工程加入swc库

导入名字空间

import cmodule.<your_lib_name>;

创建CLibInit实例

调用init()

例如：

import cmodule.example.CLibInit;

const libInitializer:CLibInit = new CLibInit();

const lib:Object = libInitializer.init();

lib.myExportedFunc("param1", 1234);

文档中没提到的其它非用户导出函数最好不要调用。