Alchemy(C/C++)API

1.1-ActionScript 对象管理：

这些功能可以用来创建不同的ActionScript类型的实例，并管理对它们的引用。您可以随时创建对象的命名空间API以及直接使用。

1.1.1 AS3_Val：

AS3值对象。

1.1.2 void AS3_Acquire(AS3_Val obj)：

这种方法的ActionScript对象的引用计数加1。

1.1.3 void AS3_Release(AS3_Val obj)：

这种方法的ActionScript对象的引用计数减1。

static void ggInit()
{
	AS3_Val flash_utils_namespace = AS3_String("flash.utils");
	ByteArray_class = AS3_NSGetS(flash_utils_namespace, "ByteArray");
	getTimer_method = AS3_NSGetS(flash_utils_namespace, "getTimer");
	AS3_Release(flash_utils_namespace);
}

1.1.4 AS3_Val AS3_New(AS3_Val constr, AS3_Val params)：

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

AS3_Val no_params = NULL;
AS3_Val ByteArray_class = NULL;

static void ggInit()
{
	no_params = AS3_Array("");
	AS3_Val flash_utils_namespace = AS3_String("flash.utils");
	ByteArray_class = AS3_NSGetS(flash_utils_namespace, "ByteArray");
	AS3_Release(flash_utils_namespace);
}

static AS3_Val newByteArrayFromMalloc(void *data, unsigned int size)
{
	AS3_Val byteArray = AS3_New(ByteArray_class, no_params);
	AS3_ByteArray_writeBytes(byteArray, data, size);
	return byteArray;
}

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。

AS3_Val ArrayClass = AS3_NSGetS(NULL, "Array");
if(!AS3_InstanceOf(AS3_Array(""), ArrayClass))) sztrace("whaaa!");

1.1.7 AS3_Val AS3_NSGet(AS3_Val ns, AS3_Val prop)：

运行时通过ns（AS3_String，例如"flash.utils"）和prop（AS3_String，例如"ByteArray"）查找类。

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);

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

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

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);

---

1.2-C / C + +转换为ActionScript对象

1.2.1 AS3_Val AS3_String(const char* str)：

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

AS3_Val ByteArray_class = NULL;
static void ggInit()
{
	AS3_Val flash_utils_namespace = AS3_String("flash.utils");
	ByteArray_class = AS3_NSGetS(flash_utils_namespace, "ByteArray");
	AS3_Release(flash_utils_namespace);
}

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)：

int转AS3的int，需要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释放。

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

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

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

AS3_Val addr = AS3_Array("city:StrType, state:StrType, zip:StrType", "Anytown", "State", "12345");

---

1.3-ActionScript对象转换为C / C + +的值

1.3.1 AS3_Malloced_Str AS3_StringValue(AS3_Val obj)：

String转char[]（malloc，需要释放）。

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。

AS3_Val num = AS3_Call(mathRandom, NULL, no_params);
      double e = AS3_NumberValue(num);

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)

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的分解。

int arg0 = 0;
char* arg1 = NULL;
double arg2 = 0.0;
AS3_ObjectValue(obj, "foo:IntType, bar:StrType, baz:DoubleType", &arg0, &arg1, &arg2);

---

1.4-从C / C + +中调用ActionScript方法

1.4.1 AS3_Val AS3_Get(AS3_Val obj, AS3_Val prop)：

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

AS3_Val length_property = AS3_String("length");
AS3_Val length = AS3_GetS(byteArray, length_property);
AS3_Release(length_property);

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

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

AS3_Val length = AS3_GetS(byteArray, "length");

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

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

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);

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

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

AS3_Val zero = AS3_Int(0);
AS3_SetS(byteArray, "position", zero);
AS3_Release(zero);

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))）作为参数。

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);

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

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

...
AS3_Val str = AS3_Call("readUTFBytes", ba, lenParams);

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。

...
AS3_Val str = AS3_CallTS("readUTFBytes", ba, "IntType", 16);

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);

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-从ActionScript方法中调用C / C + +方法

1.5.1 AS3_ThunkProc

 用typedef定义回调函数的一般形式。typedef AS3_Val (*AS3_ThunkProc)(void *data, AS3_Val params);

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的用法。

---

注解：

1、malloc

原型：extern void *malloc(unsigned int num_bytes);

头文件：在TC2.0中可以用malloc.h或 alloc.h (注意：alloc.h 与 malloc.h 的内容是完全一致的)，而在Visual C++6.0中可以用malloc.h或者stdlib.h。

功能：分配长度为num_bytes字节的内存块

返回值：如果分配成功则返回指向被分配内存的指针(此存储区中的初始值不确定)，否则返回空指针NULL。当内存不再使用时，应使用free()函数将内存块释放函数返回的指针一定要适当对齐，使其可以用于任何数据对象。

说明：关于该函数的原型，在旧的版本中malloc返回的是char型指针，新的ANSIC标准规定，该函数返回为void型指针，因此必要时要进行类型转换。

名称解释：malloc的全称是memory allocation，中文叫动态内存分配，当无法知道内存具体位置的时候，想要绑定真正的内存空间，就需要用到动态的分配内存。