builtin.raw 库模块帮助文档

raw 成员列表 #

raw.byte() #

转换参数@1指定的数值为 byte 类型数值（8位整数）包装对象,
返回对象支持 tonumber tostring 等类型转换函数。

用于调用非声明式原生 API 函数的参数,
默认传值,参数@2为 true 则用于传址参数（传数值的指针）。

用于 COM 函数参数则总是传值, COM 函数也可使用 com.byte 函数

返回对象:rawNumberObject

raw.convertArray(源内存指针,源数组长度,"数据类型") #

将指针指向的内存转换为普通数组,传入空指针返回空值
数据类型参数可省略,默认为"pointer"
类型类型也可以直接传入一个结构体实例对象。
注意该函数不会检测内存溢出错误,调用该函数时必须保证数组长度是正确的值

raw.copy #

复制内存数据

raw.copy(destPinterOrBuffer,srcData,size) #

复制内存数据。

参数 @destPinterOrBuffer 指定复制目标（指针或 buffer 类型参数）。
参数 @srcData 允许使用指针,buffer,字符串,或结构体参数。
此函数不允许其他可自动转换为指针的非指针类型参数。
参数 @size 指定要复制的字节长度。

如果复制源或目标是 buffer，字符串,或结构体等可获取内存长度的类型，可以省略参数 @size 。
如果 aardio 能获取复制源或复制目标的内存长度则复制长度不会超过可用长度。
但如果参数是指针将无法检测内存长度，请自行计算好参数避免溢出。

如果未显式指定复制长度，并且 @srcData 是 buffer，或字符串时，
将复制全部数据与尾部隐藏的\u0000到目标内存，如果复制目标是指针，
那么要保证复制源加上这 2 个字节也不会超过目标内存长度。

raw.copy2 函数支持相同功能，但可以指定更多参数（可指定源内存与目标内存偏移量）

raw.copy2 #

复制内存。
此函数内部调用 raw.copy ，但 raw.copy2 可指定更多参数。

raw.copy2(destPinterOrBuffer,dstOffset,srcData,srcOffset,copySize) #

参数 @destPinterOrBuffer 可指定 buffer 或内存指针。
参数 @dstOffset 指定目标内存偏移量，虽然数组索引自 1 开始，但内存偏移量自 0 开始。
指定非 0 偏移量则将 @destPinterOrBuffer 转为指针传给 raw.copy 函数。
参数 @srcData 可指定字符串、buffer、结构体、指针
如果 @srcData 为结构体则不应指定 @srcOffse 与 @copySize 参数。
参数 @srcOffset 指定复制源内存（指 @srcData ）的偏移量，省略则为 0。
指定非 0 偏移量则将 @srcData 转为指针传给 raw.copy 函数。
参数 @copySize 指定复制长度（字节数）
如果参数 @srcData 是 buffer,字符串、结构体等可确定长度的对象，
且未指定 @srcOffset 参数时可以省略 @copySize 参数。

raw.double() #

转换参数@1指定的数值为 double 类型数值（64位浮点数）包装对象,
返回对象支持 tonumber tostring 等类型转换函数。

用于调用非声明式原生 API 函数的参数,
默认传值,参数@2为 true 则用于传址参数（传数值的指针）。

用于 COM 函数参数则总是传值, COM 函数也可使用 com.double 函数

返回对象:rawNumberObject

raw.dup(源句柄,源进程,目标进程,允许子进程继承) #

返回复制的系统句柄
除参数1之外,其他参数可选
默认仅在当前进程中复制句柄
复制的句柄应使用raw.closehandle释放

raw.equal #

比较内存存储的数据是符相同。

注意 buffer 直接用 == 操作符只能比较地址不能比较内容，
但 aardio 中相同内容的字符串总是指向同一地址，因此字符串可以直接用 == 比较。

raw.equal(data1,data2,size) #

二进制比较 @data1,@data2 存储的数据是否相同。

参数 @data1,@data2 可指定字符串,buffer,结构体,null，指针以及可转为指针的对象。
调用者必须确认指针参数所指向的内存不小于待比较的长度。
对于字符串,buffer,结构体,null 等参数，长度小于待比较长度时返回 false 。
注意 null 与 "" 不相等。
可选用参数 @size 自定义比较长度。
如果 @data1 或 @data2 可以确定长度则 @size 可以省略。
省略 @size 参数并且 @data1,@data2 可以确定长度不相等时直接返回 false 。

如果仅执行文本（不包含空字符 \0）比较应改用更合适的 string.cmp 函数。

raw.execute #

运行外部程序，成功返回 true。
process.execute 函数提供类似的功能，区别可参考函数源码

raw.execute(file,param,operation,showCmd,workDir,hwnd) #

运行外部程序，成功返回 true。
@file 指定要运行的程序路径，其他所有参数可省略，
@param 字符串参数，可选指定启动参数。
@operation 可选用一个字符串指定执行动词，省略则使用默认动词或 "open"。
@showCmd 可选用 SW 前缀常量指定显示选项，默认为 _SW_SHOW。
@workDir 参数可选指定工作目录。
@hwnd 可选指定所有窗口句柄，默认取当前线程活动窗口

raw.explore(path,args,...) #

使用资源管理器（Explorer.exe）打开文件或目录。
第一个参数 @path 指定文件路径，可为空值（ null ）。
注意 Explorer.exe 不解析标准的命令行参数转义符，这一点与其他程序不同。
如参数 @path 尾部有双反斜杠\\则为无效路径并打开默认目录（打开我的文档，XP系统报错）。
如参数 @path 指定为 ","或"file:" 则打开“此电脑（This PC）”。
如参数 @path 使用shell:::前缀则可以指定特殊路径的 CLSID。

可用第二个参数 @args 或更多参数指定 Explorer.exe 命令行选项，
例如指定 "/select" 在资源管理器选择指定路径。
注意 "/n" 等选项在新系统中是无意义的，Explorer 将总是打开新窗口。

raw.float() #

转换参数@1指定的数值为 float 类型数值（32位浮点数）包装对象,
返回对象支持 tonumber tostring 等类型转换函数。

用于调用非声明式原生 API 函数的参数,
默认传值,参数@2为 true 则用于传址参数（传数值的指针）。

用于 COM 函数参数则总是传值, COM 函数也可使用 com.float 函数

返回对象:rawNumberObject

raw.int() #

转换参数@1指定的数值为 int 类型数值（32位整数）包装对象,
返回对象支持 tonumber tostring 等类型转换函数。

用于调用非声明式原生 API 函数的参数,
默认传值,参数@2为 true 则用于传址参数（传数值的指针）。

用于 COM 函数参数则总是传值, COM 函数也可使用 com.int 函数

返回对象:rawNumberObject

raw.join(字节串数组,分隔字符串,起始索引,结束索引) #

拼接参数 @1 指定的字符串或 buffer 数组，返回 buffer 对象。

参数 @1不可包含除字符串, buffer, null 之外其他类型的值，忽略 null 值元素。
包含 buffer 的数组只能用 raw.join 拼接，不可使用 string.join 拼接。
参数 @2 可选指定一个分隔字符串。
起始索引与结束索引为可选参数，可传入负数表示自数组尾部倒计数

如果拼接后字节长度为 0，此函数返回 null。
起始索引与结束索引可用负数表示倒计数，索引溢出则自动设为最接近的有效索引。
如果转换后的起始索引大于结束索引此函数返回 null。

raw.len(buffer、字符串或结构体) #

返回参数 @1 指定的字符串、buffer 或结构体的字节长度。
传入其他类型参数返回 null 值。

raw.long() #

转换参数@1指定的数值为 long 类型数值（64位整数）包装对象,
返回对象支持 tonumber tostring 等类型转换函数。

用于调用非声明式原生 API 函数的参数,
默认传值,参数@2为 true 则用于传址参数（传数值的指针）。

用于 COM 函数参数则总是传值, COM 函数也可使用 com.long 函数

返回对象:rawNumberObject

raw.main #

进程主模块,默认调用约定为stdcall
与raw.module("stdcall")返回的值相同,
可用于将当前进程中的函数指针转换为aardio函数

返回对象:dllModuleObject

raw.mixin(指针,结构体对象,任意个混入表...) #

如果未指定参数 @3 此函数将参数 @2 指定的结构体复制到参数 @1 指定的内存，
然后返回结构体。

否则将参数 @1 指定的内存数据先复制到参数 @2 指定的结构体。
然后将后续的所有表参数（仅包含需要修改的字段）调用 table.assign 函数混入到结构体中。
然后再将被填充的结构体复制到参数 @1 指定的内存。

例如代码 raw.minxin(ptr,{int x;int y},{y=123}) 只会修改内存中的 y 字段。
而 raw.minxin(ptr,{int x;int y}) 则会将 x,y 字段都清零。

raw.module("调用约定") #

指定约定并返回进程主模块,
省略参数时调用约定默认为stdcall,
可用于将当前进程中的函数指针转换为aardio函数,

raw.module() #

返回对象:dllModuleObject

raw.serializeDupHandle("类名",句柄) #

复制进程内有效句柄并序列化对象
只能用于_serialize元方法，且必须kernelCall参数为真
序列化类构造函数必须支持指针参数1为指针类型句柄,参数2为true的参数
并负责在析构函数中调用 raw.closehandle 释放该句柄

raw.sizeof #

计算原生类型大小。

raw.sizeof( ) #

返回结构体、原生类型、动态指针内存长度。
参数 @1 可指定结构体、或包含原生类型名称的字符串。

参数 @1 如果是指针，则必须是通过 raw.realloc 函数创建的动态指针,
传入动态指针，返回 2 个值，分别为存储数据长度、分配内存总长度。
传入其他来源指针，因缺少动态指针头信息会导致崩溃。
参数 @1 传入 null 值返回 0。
无参数时会报错抛出异常。

raw.slice #

截取字节串并返回新的 buffer 对象。

raw.slice(buffferOrPtr,startIndex,endIndex,size) #

参数 @buffferOrPtr 可指定 buffer,字符串或指针。
参数 @startIndex 指定截取开始位置，参数 @endIndex 指定最后一个截取字节的位置。
省略 @startIndex 则默认为 1,省略 @endIndex 则默认为 @size
如果 @startIndex,endIndex 为负数则表示自尾部倒计数，-1 表示最后一个字节。
如果转换后 @startIndex 小于 1 则设为 1，@endIndex 大于 size 则设为 size。
如果 @startIndex 大于 1，@endIndex 则返回 null 值。
参数 @size 指定字节串长度，如果参数 @1 指定字符串或 buffer 则可省略 size 参数。