aardio 文档

免声明直接调用原生 API 函数

aardio 免声明直接调用原生 API 函数示例： 

::User32.MessageBox(0,"测试","标题",0)

aardio 建议使用免声明的方式调用 API 函数，直接调用 API 更方便也更节省资源(除非有特殊的数据类型必须通过声明 API 来指定)。而且也可以更灵活地调整调用参数。

一、免声明调用 - 传参规则

  1. 在加载 DLL 时可指定调用约定，支持 cdecl 调用约定的不定个数参数。

  2. null、boolean(true,false),string、buffer、pointer,math.size64(64位长整数) 等数据类型一律直接传参，null 参数不可省略。

  3. aardio 数值一律处理为 32 位 int 整型。

    如果 API 函数的要求的参数类型是等于或小于 32 位的整型（包括枚举、bool、BOOL类型），都可以直接传入 aardio 数值作为参数。

    示例：

    例如C语言API声明为：
    void setNumber( short n )

    在 aardio 里如下调用就可以：
    dll.setNumber( 123 )

  4. 64 位整数可以 math.size64 对象表示。或者用两个数值参数表示一个64位整数值参数，其中第一个参数表示低32位数值，第二个参数表示高 32 位数值（一般可以直接写 0 ）。

  5. 任何 API 函数的数值类型的指针（输出参数）都可以使用结构体表示。

    例如 C 语言 API 声明为： void getNumber( short *n )

    在 aardio 里如下调用就可以：

    var n = {word value}  
dll.getNumber( n )

    也可以使用 raw.word(number,true) 创建上面的结构体。

  6. API 函数中的原生数组指针类型，通过 aardio 结构体传原生数组。

    例如 C 语言中的 int data[4] 在 aardio 中写为 { int data[4] } 。字节数组指针也可以使用 aardio 中的 buffer 对象。

  7. 如果调用参数是未定义任何原生类型的 aardio 表对象。

  8. 所有 aardio 结构体一律处理为输出参数并在 aardio 返回值中返回，其他类型只能作为输入参数。注意在 aardio 中，任何结构体在 API 调用中传递的都是结构体指针（传址）。

    在未声明直接调用 API 时，所有结构体都会忽略 _topointer 元方法 - 这与调用已声明 API 函数的规则不同。

    在调用声明的 API 函数时。一个定义了_topointer 元方法的结构体参数如何传参将取决了对应的参数类型声明。如果参数要求结构体类型则会传递结构体指针，如果参数要求传递指针，则会传递 _topointer 元方法返回的指针。

  9. 因为没有参数类型声明，调用代码有责任事先检查并保证参数类型正确，传入错误的参数可能导致程序异常。

二、免声明调用 - 返回值规则

  1. 免声明直接调用 API的 返回值默认为 int 类型。如果原 API 返回的是 32 位无符号整数，那么只要简单的将返回值 >>> 0 就可以得到原来的无符号数值了。

  2. 可以使用 API 尾标 改变返回值为其他类型。

三、使用 API 尾标 #

API 尾标指的是 API 函数名尾部独立大写的特定字符。使用尾标可以修改默认的 API 调用规则。

免声明调用 API 支持的尾标列表：

尾标 'W'，'A' 的特殊规则：

示例：

::User32.MessageBoxB(0,"消息","标题",0)

对于上面的代码，aardio 会执行下面的步骤：

四、免声明调用 API 如何使用字符串 #

  1. 字符串一般直接转换为字符串指针，buffer 类型字节数组也可以作为字符串指针使用，如果 API 需要向字符串指向的内存中写入数据，那么必须使用 raw.buffer() 函数创建定长的字节数组。普通的 aardio 字符串指向的内存是禁止写入的（ aardio 中修改普通字符串会返回新的字符串对象，而不是在原内存修改数据）。

  2. 对于非 UTF-16 API 字符串直接输入原始的数据（对于文本就是 UTF-8 编码），对于声明为 Unicode 版本的 API，字符串会被自动转换为 Unicode(UTF-16)，但 buffer 类型的参数仍然会以二进制方式使用原始数据与 API 交互（不会做文本编码转换）

  3. 一些 API 在接收字符串、字节数组等参数时，通常下一个参数需要指定内存长度。请特别注意 aardio 中用 # 操作符取字符串、buffer 的长度时，返回的都是字节长度。一些 API 可能需要你传入字符个数（而不是字节数）。 注意 Unicod（ UTF-16 ） 版本的 API 里一个字符为两个字节，而 UTF-8 则为多字节编码。对于一个 UTF8 字符串应当事用 string.len() 函数得到真正的字符长度, 而 Unicode（ UTF-16 ） 字符串则用 # 取到字节长度后除以 2 即可得到字符数了（ 就现实情况来说基本都是如此处理 ）。

其他说明

Markdown 格式