原生数据类型（ raw datatype ）

原生类型指的是直接访问和操作原生内存数据的类型系统。

ardio 本身是动态语言，aardio 语言本身的数据类型( datatype ) 与原生数据类型( raw datatype ) 是两套类型系统。aardio 会自动做必要的类型转换，但不要混淆这两种数据类型。举个例子，在原生数据类型中数值有 int,long,double,float …… 一大堆，但是对于 aardio 语言本身的类型系统来说，数值都是双精度浮点数（相当于 double 类型）。

原生接口有关的文档提到的"API 函数"是特指的外部 DLL 文件提供的原生接口函数，例如操作系统 DLL 提供的 "WinAPI" 函数。DLL 文件通常由 C/C++ 等原生编程语言编写。

在 aardio 中使用原生类型主要有两种方式：

• raw 库函数
• 原生原生 API 函数。这个主要是指原生 DLL 接口。
• aardio 定义的结构体。

参考：

• raw库
• aardio 数据类型
• 使用结构体

原生数据类型( raw datatype )

注意原生原生数据类型声明严格区分大小写，数据类型大写表示对类型有更严格的限制条件。

• 数值类型小写表示允许负数，大写表示无符号数据类型(没有负数，仅有正整数)。
  
• 对于支持指针的类型(string,pointer)，小写表示允许 null 值并允许自动转换（例如字符串转换为指针），大写表示不接受 null 实参。
  

使用 aardio『工具 / 转换工具 / API 转换』工具可自动转换 C/C++ 的 API 类型、结构体、函数声明为　aardio 格式。

注意 C/C++/WinAPI 的数据类型名有一些复杂，同一个类型有无数的不同名字，而同一个类型名字可以处理为不同的类型。

aardio 对原生类型做了简化，只要掌握几个基础类型就可以了。

例如句柄类型，有时候作为无符号数，有时候作为有符号数，有时候又作为指针类型处理，实际上你无论是使用指针类型、有符号数值类型、还是无符号数值类型，对于句柄来说内存中的值是相同的，例如 topointer(-1) == topointer(0xFFFFFFFF) 的结果是相等的。 在 aardio 标准库里，一般句柄类型都被处理为指针，只有窗口句柄( HWND )在 aardio 中统一被声明为 addr 类型。

声明的数据类型必须保持绝对正确，使用错误的类型会导致内存读写错误并导致程序崩溃。调用原生 API 函数大部分导致崩溃的错误原因基本都是因为定义了错误的原生数据类型。

原生数组(raw array) #

原生数据类型数组必须写在一个结构体里面。

示例：

var bytes = { 
    byte buffer[256]={1,2,3} 
}

必须在中括号内指定一个有效的数值表示数组长度。 中括号内表示数组长度的只能是一个数值字面量，不能写变量。

如果原生数组不指定数组长度,则表示创建一个变长原生数组， aardio 将会在运行时检测并获取实际的原生数组长度，变长原生数组在运行时的长度不能为 0。

变长原生数组确定长度的方式有两个方法：

• 用数组的 length 属性确定原生数组长度，length 的优先级更高。
• 如果找不到 数组的 length 属性，则用数组实际包含的元素个数确定原生数组长度。

//创建变长数组
var bytes = { 
    byte buffer[] 
}

//根据运行时的数组长度确定原生类型数组长度
bytes.buffer={1,2,3} 

//用 length 属性指定数组长度
bytes.buffer={ length=20 } 

原生数组类型列表：

定义原生数组的要点：

• struct[] 类型数组至少需要显示声明数组中的第一个元素为有效结构体实例。
  
• 大写的 STRING[],POINTER[] 类型数组不允许数组成员为 null 值。
  
• 其他已声明长度的原生数组，数组成员可以包含 null 值或为空数组，但数组本身不能为 null 值。
  
• 未声明长度的变长原生数组必须用 lenght 指定长度或者赋值为非空数组以确定长度，原生数组长度不能为 0。
• BYTE []，byte [] 类型数组可以指向数组，也可以指向字符串。
• WORD []，word [] 类型数组可以指向数组，也可以指向字符串（ 自动转换 UTF-16 编码 ）。

请参考：结构体 - 原生数组

原生输出参数( raw output parameters )

在 aardio 中，如果在原生 API 函数声明的参数类型名以后添加 & 符号，表示这个参数的值允许被外部函数修改并且会返回修改后的值。

如果一个原生 API 函数含输出参数，那么每个输出参数都会按原来的先后顺序附加在返回值后面返回。aardio 遵循纯函数原则，函数的数据只有唯一的入口(参数)，也只有唯一的出口(参数)，所以被修改的输出参数必须显示地从返回值输出。

//加载 DLL 模块
var dll = raw.loadDll("/test.dll");

//声明 API 函数
var apiFunc = dll.api("apifunc", "int(addr hwnd,string text,string &caption,INT uType)" )

//增加返回值以接收 API 输出参数
var ret,caption = apiFunc(hwnd,text,caption,uType);

请特别注意：struct 与 struct & 类型在 API 参数里传递的都是相同的结构体指针，目标 API 参数收到的值是一样的。struct & 并不是二级指针。 区别是指定为 struct类型时 aardio 会丢弃外部 API 对结构体的修改（速度更快），而指定为 struct &类型时外部 API 对结构体的修改会被同步到 table 对象。无论是不是接收了新的返回值，struct &类型的参数都具有副作用，这一点与其他类型是完全不同的。

但其他数值类型以及 bool、pointer、POINTER 类型如果加上 & 则是传址（指针），否则是传值，目标 API 函数收到的值是完全不一样的。例如 API 形参定义为 int，那么你传递实参数值 123 时，API 函数接收到的是 123 这个数值。
如果 API 形参定义为 int &，那么你同样传递参数值 123 时，API收到的是指向 123 的地址，是另外一个数值。

我们要特别注意，纯 aardio 对象与原生数据类型对象在内存里的结构是完全不同的。所以我们并不能将 aardio 里的对象的指针传给外部 API 函数。当我们在调用 API 时对于 int & 这样的原生数据类型的输出参数，aardio 是在调用时临时分配了一块内存，在调用 API 函数结束后会立即释放该内存。所以在外部 API 中不得保存这样的内存指针，如果要传给外部 API 函数稳定不变的指针，则需要使用 raw.buffer , raw.realloc 分配原生内存。

aardio 结构体传给外部 API 函数时，同样会分配临时的内存指针，在 API 调用结束后立即释放。如果要传稳定不变的指针，则需要将结构体转换为 buffer 类型，或者使用 raw.struct 创建结构体。

在 API 函数中使用字符串

aardio 中的 string 数据类型是传址的，多个相同内容的字符串变量内部指向相同的内存数据。 而字符串内存数据是只读的，修改字符串总是会导致 aardio 创建新的字符串，而不是改变原字符串的内存数据。

1. 获取原生 API 输出的字符串

   对于外部API函数：

   如果一个字符串有可能被外部函数所改变，并且需要返回修改后的新字符串，那么在API函数参数中应将其声明为 string & 以通知 aardio 字符串的内存可能被修改，而在结构体中应声明为 BYTE[] 数组。在结构体中的 BYTE[] 是一个字节数组，仍然可以使用字符串进行赋值。例如：

   //字段 b , b2 的内存数据是相同的
   class struct{
       BYTE b[3] = {'a'#;'b'#;'c'#};
       BYTE b2[3] = "abc";//BYTE 数组仍然可以使用字符串进行赋值
   }
   

2. 获取原生 API 输出的 UTF-16 字符串

   对于可能被外部函数所改变 Unicocde( UTF-16 ) 字符串，可将类型声明 ustring 变更为 ustring & 以通知 aardio 字符串的内存可能被修改。而在结构体中应声明为 WORD[] 数组。在结构体中的 WORD[] 是一个宽字节数组，仍然可以使用字符串进行赋值。例如：

   class struct{
       WORD b[3] = {'a'#;'b'#;'c'#};
       WORD b2[3] = "abc"; 
   }
   

   对于 WORD[] 类型如果值是一个 table 数组则 aardio 总是将该字段处理为数值数组。如果值为空，或者值是一个字符串，aardio 则总是将该字段作为一个 UTF16 编码的 Unicode 文本字符串处理，在调用 API、以及作为输出结构体参数时 aardio 会自动做 UTF16 到 UTF8 的双向自动转换（ 读取或获取 aardio 字符串是 UTF-8, 写入内存或传入原生 API 则自动转为 UTF-16 编码字符串)，此字符串总是会处理为文本字符串，（字符串内容不含'\u0000'，遇 '\u0000' 结束）

3. 使用 buffer 分配的内存获取 API 输出的字符串

   在 API 中字符串实际上是一个内存指针，因此 API 函数中的字符串参数同样可以声明为指针类型。

   使用 raw.buffer 创建的 buffer 对象 - 在API函数中该类型等价于一个C语言中的 char * 指针，该指针指向可修改的内存，在 API 函数返回以后，可以再用 raw.tostring() 将 buffer 指针转换为普通字符串。

   实际上不传换也可以用，在 aardio 中大多数字符串函数可以直接支持将 buffer 类型的字节数组作为字符串参数直接使用。

   注意：buffer 对象用于普通 API 函数的pointer类型的输入参数，或普通结构体pointer类型成员指针。buffer 接收的是指针指向的数据而不是接收指针本身。对于声明为 声明为 pointer & 类型的参数，应当用 null 值或者 pointer 类型的指针值去接收新的指针。

4. 结构体中的字符串类型

   在结构体中声明为 string 类型，作为输出参数使用时，这时候接收的就是一个字符串的地址，例如将 {string pStr}作为 API 参数，结构体指针就是字符串的指针。这里有一个比较奇怪的问题，在 WinAPI 中有一些结构体的字符串指针字段在某些情况下会将字符串指针赋值为一个小于 0xFFFF 的原子值、ID 等数值，aardio 对这种情况做了分别处理，对于结构体中的 string 类型 - 如果 API 返回的是一个字符串指针则获取指针并转换为字符串，对于小于 0xFFFF 或者为 -1 的值， aardio 会将其转换为指针类型的值。

5. 接收字符串指针

   要注意将 API 参数类型声明为 string &,ustring & 接收字符串，或者在结构体中声明为BYTE[]或者 WORD[] 接收字符串，或者创建 buffer 对象接收字符串，这几种不同形式的本质都相同的，也就是分配一块内存让原生 API 可以写入数据。

   如果我们要接收的不是字符串的数据，而是字符串的指针本身。那么用 string &,ustring & 是不行的。

   实际上在调用原生 API 时，遇到这个需求的可能性很小。对于静态语言，把字符串指针单独传给调用者，谁负责释放是很麻烦的一件事。一般写 API 函数的人不会没事自己给自己找麻烦。

   通过原生 API 函数接收字符串指针分为两种情况：

   • 在函数返回值中返回，这又分为两种情况：
     • 如果不需要调用者释放，我们可以声明 API 类型为 string() 就可以了，aardio 拿到指针然后自动转换为字符串，转换为 aardio 字符串以后就不会再使用外部指针，所以外部 API 怎么释放都没不会影响到 aardio 代码。
     • 如果需要调用者释放内存，我们可以声明 API 类型为 pointer() 就可以了，拿到指针以后，调用 raw.tostring 或者 raw.str 转换为 aardio 字符串，Unicode（UTF16）字符串则调用 string.fromUtf16 转换为 UTF-8 字符串，纯二进制也可以考虑转换为 buffer。然后就是调用外部 API 释放该指针就行了。

   • 在函数的输出参数中返回，这有两种方法可以获取：

     • 声明为 pointer & 类型，参数不用传值（因为指针支持 null 值），然后在增加到返回值列表的输出参数中得到指针。跟上面一样，调用 raw.tostring 或者 raw.str 转换为 aardio 字符串。然后看对方的要求是不是要调用什么函数释放获取到的指针。

     • 将参数声明为 struct & 类型，然后传 {string pStr} 得到字符串。示例：

       var getString = dll.api( "GetString","void(struct &ppStr)" );  
       var str = getString( {string value} ); 
       

   要注意区别 string &，ustring & 接收的是数据而不是指针，我们大多时候需要接收的是数据，需要接收字符串指针的情况较为少见。

在原生 API 函数中使用指针

在 aardio 中 API 函数会严格的检测数据类型，不允许直接用数值作为 API 函数 pointer 类型指针实参。

pointer & 类型的输出参数必须使用 pointer 类型的实参、或 null 值接收新的指针值。

pointer 类型输入参数中可以以使用 string、pointer 类型的实参、也可以使用 buffer 对象。如果 aardio 对象声明了 _topointer 元方法，并通过 _topointer 元方法返回一个 pointer 指针或数值，则可以作为指针实参使用。 _topointer 元方法可以指向返回指针或内存地址的函数，也可以直接设置一个指针或内存地址值（数值）。

aardio 字符串的指针是常量指针，外部 API 函数不应当修改 aardio 字符串指针指向的内存。 而 raw.buffer 分配的内存是可修改的，当使用 raw.buffer 分配的指针作为参数时，该参数在 API 函数参数中应当声明为pointer类型而不应当声明为pointer&类型，因为 buffer 用收接收指针指向的数据而不是接收指针本身。

对于原生 API 的输入参数，API 函数的 poinetr 类型与 string 类型的实参都可以使用 aardio 中的 pointer,string,buffer,null 类型的值。如果使用大写的 STRING 或 POINTER 类型，则不能在实参中使用 null 值。

转换数据类型

可使用 raw.convert 函数转换结构体。

函数原型：

raw.convert(inPointerOrStringOrBufferOrStruct,outStruct,offset=0 ) 

将源数据转换为目标结构体数据，偏移量 @offset 是可选参数,默认为 0。

函数的作用是将参数 @inPointerOrStringOrBufferOrStruct 转换为 @outStruct 类型。

参数 @inPointerOrStringOrBufferOrStruct 可以是结构体(struct)、pointer、string、buffer 类型的对象。

第二个参数 @outStruct 必须是结构体(struct)。

下面看一个简单的示例：

import console; 

var struct = raw.convert({
    int value = -1;
},{
    INT value;
})

console.log( struct.value );
console.pause(true);

实际上我们用 -1 >>> 0 也可以代替上面的代码。

一般这种原生类型转换多在我们声明 API 或结构体类型的时候就自动完成了。在 aardio 中需要做这些转换的情况较为少见。如果是简单的有符号转无符号，用 >>> 0 就可以实现。参考：无符号右移

Markdown 格式