Device插件参考手册 ¶

Title:	Device插件参考手册
Author:	cuipeng@boyaa.com
Version:	3.0.1
Update:	2017-11-15

简介 ¶

Device是客户端引擎V3.x/4.0的Plugin,封装了设备原生的一些功能给lua开发者使用

主要功能包含相机、相册、通讯录、嵌入浏览器、原生对话框、设备信息、网络信息、电源信息等

使用Device插件的同学,请关注我的文章: http://stackoverflow.oa.com/people/崔鹏

使用支持多选功能的相册,请参考:

http://gogit.oa.com/cuipeng/AndroidMediaPicker

http://gogit.oa.com/cuipeng/iOSMediaPicker

使用音频管理模块,请参考:

http://gogit.oa.com/cuipeng/LuaAudioManager

版本策略 ¶

向下兼容

Device插件采用向下兼容的方式开发和升级,也就是说,高版本(后续版本)将继续支持低版本的API

新的功能将在最新的Device插件版本上增加,旧版本的Device插件仅进行bugfix

运行时查看版本方法是:插件启动后会打印版本号,例如:

device version 3.0.0.20161027161568 (编译日期为2016-10-27 16:15:68)

device插件4.0和3.x版本分别对应引擎3.x和4.0版本,不能混用.

支持的引擎版本

Device插件的每个新版本,会标明支持的引擎版本

Device插件支持引擎的最低版本是 Engine Version 3.07.0.20160908100208

CHANGES ¶

Build 4.0.1.20170523 ¶

NativeDevice 增加

NativeDevice.isReady

Build 4.0.1.20170508 ¶

AudioRecorder 增加

AudioRecorder.rawPause

AudioRecorder.rawResume

AudioRecorder.rawIsPause

Device 4.0 支持引擎4.0

iOS 最低支持 iOS8

Build 3.0.1.20170420 ¶

NetworkInfo 增加:

NetworkInfo.getMNO

NetworkInfo.getSSID

PowerInfo 增加:

PowerInfo.setBatteryChangedEvent

增加 DisplayInfo :

DisplayInfo.getInches

增加 isVirtual.lua

bugfix

Build 3.0.1.20170214 ¶

WebView 增加:

WebView.enableLoadingDialog2

增加 javascript 函数: native_close_loading 增加 javascript 函数: native_close_keyboard

Build 3.0.1.20170120 ¶

WebView 增加:

WebView.TOP_LEFT_INNER

WebView.TOP_RIGHT_INNER

PhotoLibrary 增加:

PhotoLibrary.insertImageFile

增加了 AudioRecorder 类

NetworkInfo 增加:

NetworkInfo.getNetworkSubType

Permissions 增加

Permissions.EXTERNAL_STORAGE

Build 3.0.1.20161214 ¶

WebView 增加:

WebView.setBackgroundColor

WebView.loadString

WebView.enableLoadImage

NetworkInfo 增加:

NetworkInfo.isInternetConnected

增加了 GeoLocation 类

Build 3.0.1.20161223 ¶

WebView 增加:

增加 javascript 函数: native_log

DeviceInfo 增加:

DeviceInfo.getStorageSize

DeviceInfo.getStorageAvailable

增加了 MemoryInfo 类

Build 3.0.1.20161229 ¶

WebView 增加:

WebView.EVENT_REFRESH

WebView.enablePullRefresh

安装 ¶

发布地址和文件列表 ¶

http://gogit.oa.com/Engine/device_plugin

win32文件列表

device.dll (插件主库)

libconfig++.dll (读写配置文件用的库)

ByCamera.exe (windows相机程序)

PhotoAlbum.exe (windows相册程序)

location.html (定位功能模拟用的地图页面)

Settings.exe (windows权限管理工具,用户可手动运行)

device.lua (配置文件,配置启动画面/权限模拟平台/通讯录等,源码中包含详细说明)

chrome21.zip (chrome浏览器库,解压至 device.dll 相同目录下,要覆盖2个OpenGL库)

android文件列表

libdevice.so

device.jar

iOS文件列表

libdevice.a

—lua 文件列表

isVirtual.lua

memoryInfo.lua

win32 接入 ¶

将文件列表中所有文件拷贝到引擎程序相同目录下

Device插件使用vs2015 update2(Platform Toolset v140)编译,所以依赖相应的Microsoft Visual C++ 2015 Redistributable库

支持win8/win10

android 接入 ¶

编译环境配置

<uses-sdk android:minSdkVersion="14"
                  android:targetSdkVersion="23"/>
若直接支持 android 6.0 (Device插件支持),可将 targetSdkVersion 的值配置为>=23
<uses-sdk android:minSdkVersion="14"
                  android:targetSdkVersion="23"/>
需要最新版的 android-support-v4.jar

在Activity中初始化:

import com.boyaa.engine.device.Device;

//Activity的派生类需要实现一个interface并加入onRequestPermissionsResult的方法实现
public class Game extends AppActivity implements ActivityCompat.OnRequestPermissionsResultCallback

@Override
protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        //初始化device
        //device内部调用了android的Activity.startActivityForResult方法
        //这里的requestCodeStart是设置device使用>=1000的值.
        //device内部会使用不超过10个requestCode
        int requestCodeStart = 1000;
        int permissionsRequestCodeStart=1000;
        Device.getInstance().init(this,requestCodeStart,permissionsRequestCodeStart);

}

@Override
protected void onResume() {

        //Device resume
        Device.getInstance().onResume();

        super.onResume();
}

@Override
protected void onPause() {

        //Device pause
        Device.getInstance().onPause();

        super.onPause();
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {

        //Device onActivityResult
        if ( Device.getInstance().onActivityResult(requestCode, resultCode, data))
        {
                return;
        }

        super.onActivityResult(requestCode, resultCode, data);
}

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {

        //Device onRequestPermissionsResult
        if ( Device.getInstance().onRequestPermissionsResult(requestCode, permissions, grantResults))
        {
                return;
        }
}

配置权限

如果没有用到Device插件对应的功能,就无需配置对应的权限.

读写 external storage

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

相机

<uses-permission android:name="android.permission.CAMERA" />

通讯录

<uses-permission android:name="android.permission.READ_CONTACTS" />

访问设备(震动、屏幕亮度控制等)

<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

网络信息

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

录音

<uses-permission android:name="android.permission.RECORD_AUDIO" />

电源信息

<uses-permission android:name="android.permission.BATTERY_STATS"/>

获取设备名称:DeviceInfo.getName()

<uses-permission android:name="android.permission.BLUETOOTH" />

定位(GPS)

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS 接入 ¶

Xcode环境相关

device工程在Xcode中的Deployment Target设置为7.0 ( Device插件最低支持 iOS 7.0 )

Objective-C Automatic Reference Counting 设置为 YES

Other Linker Flags增加一条: -ObjC (可以去掉了)

需要链接下面所有的库(请注意 optional ):

libdevice.a required

AddressBook.framework required

Contacts.framework optional

Photos.framework optional

UIKit.framework optional

WebKit.framework optional

SystemConfiguration.framework required

CoreMotion.framework required

AVFoundation.framework optional

CoreLocation.framework optional

CoreTelephony.framework optional

Hide status bar

如果需要支持iOS平台NetworkInfo.getNetworkTypeName/getNetworkSubType接口的话,XCode设置中不要选中这项； 在 Build 3.0.1.20170420之后的版本,不再需要 Hide status bar
配置权限
如果没有用到Device插件对应的功能,就无需配置对应的权限.

在Info.plist中增加如下内容:

相机:NSCameraUsageDescription

相册:NSPhotoLibraryUsageDescription

通讯录:NSContactsUsageDescription

录音:NSMicrophoneUsageDescription

定位(GPS):NSLocationWhenInUseUsageDescription

打开电话和短信:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>tel</string>
<string>sms</string>
</array>
打开IOS[定位服务]的系统设置界面:

xcode设置:[info]->[URL Types] 中添加一项,并将[URL Schemes]中填入”prefs”(不包含引号).
源码相关
在UIApplicationDelegate父类中增加如下函数,用来支持iPhone/iPod竖屏拍照
- (NSUInteger)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(UIWindow *)window {
        return UIInterfaceOrientationMaskAll;
}
@end

配置插件 ¶

Win32平台需要在Resource/plugin配置文件中增加一行配置:device

Android平台需要在assets/plugin配置文件中增加一行配置:device

iOS平台需要使用如下接口来初始化插件
extern "C" int device_plugin_proc(EPluginMsgType eMsgType,void* param1,void* param2);
addPlugin(device_plugin_proc);

示例代码 ¶

相机 ¶

--此为拍摄完成后回调的lua函数
onCameraEvent = function(flag,imageFile)
        if NativeDevice.Camera.OPEN_SUCCESS == flag then
                --拍摄成功, imageFile是图片文件名
        end

        if NativeDevice.Camera.OPEN_CANCEL == flag then
                --用户Cancel了拍摄
        end

        if NativeDevice.Camera.OPEN_ERROR == flag then
                --错误
        end

        if NativeDevice.Camera.OPEN_NO_PERMISSION == flag then
                --没有权限或用户禁止了权限
        end

end

function openCamera()

        local outputPath = ...
        --设置拍摄图片的存放路径
        NativeDevice.Camera.setImagePath(outputPath);

        --设置拍摄图片为PNG格式
        NativeDevice.Camera.setImageFormat(NativeDevice.Camera.IMAGE_PNG);

        --设置拍摄图片的长度、宽度,单位为像素
        NativeDevice.Camera.setImageSize(400,300);

        --选择缺省的相机
        NativeDevice.Camera.select(NativeDevice.Camera.DEFAULT_CAMERA);

        --拍摄完成后允许编辑
        NativeDevice.Camera.enableEdit(true);

        --打开相机,设置拍摄完成后回调的lua函数
        NativeDevice.Camera.open(onCameraEvent);

end

相机权限 ¶

local Permissions = NativeDevice.Permissions;

--查询相机权限,以便于分别处理
local status = Permissions.getStatus(Permissions.CAMERA);

--如果是受限状态(比如儿童模式),则返回
if status == Permissions.STATUS_RESTRICTED then
        return;
end

--如果是允许状态,则打开相机
if status == Permissions.STATUS_GRANTED then
        openCamera();
        return;
end

--用户授权的回调函数
function onUserGranted(granted)
        if granted then
                openCamera();
        end
end

--如果是未确定状态,则请求相机权限(会打开系统对话框)
if status == Permissions.STATUS_NOT_DETERMINED then
        Permissions.request(Permissions.CAMERA,onUserGranted);
end

--如果是拒绝状态,则向用户解释原因,请求用户再次授权
if status == Permissions.STATUS_DENIED then
        local param = {
                reason="斗地主拍照功能需要使用您的相机,在使用相机之前需要您授权同意,请点击[下一步]进入授权界面",
                ok_title="下一步",
                cancel_title="取消"};

        Permissions.requestReason(Permissions.CAMERA,param,onUserGranted);
end

相册 ¶

--此为浏览并选择图片完成后回调的lua函数
onPhotoLibEvent = function(flag,imageFile)

        if NativeDevice.PhotoLibrary.PICK_SUCCESS == flag then
                --成功, imageFile是图片文件名
        end

        if NativeDevice.PhotoLibrary.PICK_CANCEL == flag then
                --用户Cancel了
        end

        if NativeDevice.PhotoLibrary.PICK_ERROR == flag then
                --错误
        end

        if NativeDevice.PhotoLibrary.PICK_NO_PERMISSION == flag then
                --没有权限或用户禁止了权限
        end

end

local path = ...
--设置图片的存放路径
NativeDevice.PhotoLibrary.setImagePath(path);

--设置图片保存为PNG格式
NativeDevice.PhotoLibrary.setImageFormat(NativeDevice.PhotoLibrary.IMAGE_PNG);

--设置图片的长度、宽度,单位为像素
NativeDevice.PhotoLibrary.setImageSize(400,300);

--设置用户选择完成后允许编辑
NativeDevice.PhotoLibrary.enableEdit(true);

--浏览图片,设置浏览完成后回调的lua函数
NativeDevice.PhotoLibrary.pick(onPhotoLibEvent);

通讯录 ¶

--读取通讯录数目
local count = NativeDevice.Contacts.getCount();

--从第0条开始读取,读20条
local defaultSort = 0;
local contacts = NativeDevice.Contacts.read(0,20,defaultSort);
--返回contacts是一个lua table,格式如下:

--contacts[1] = {id="7033",name="赵丽颖",phone_numbers = {home="0755-88886666",mobile="13988886666"}}
--contacts[2] = {id="7034",name="李易峰",phone_numbers = {"46446","+86 18633443344"}}
--...
--contacts[5] = {id="7028",name="杨紫",phone_numbers = {workNumber="010-88310571"}}

WebView ¶

--java script调用lua的回调函数
onWeb1JsEvent = function(stringData)
        --
end

--webview事件
onWeb1Event = function(cmd)

        if cmd == NativeDevice.WebView.EVENT_LOAD_SUCCESS then
                --加载网页成功
        end

        if cmd == NativeDevice.WebView.EVENT_LOAD_FAILED then
                --加载网页失败
        end

        if cmd == NativeDevice.WebView.EVENT_QUIT then
                --用户点击了网页上的close按钮(如果有的话)
        end

end

--创建一个WebView对象,设置屏幕坐标,单位为像素
web1 = NativeDevice.WebView(0,0,400,300);

--设置webview事件回调的lua函数
web1:setEvent(onWeb1Event);

--设置java script调用lua的回调函数
web1:setJsCallback(onWeb1JsEvent);

local imgPath = sys_get_string("storage_app_images");
--在webview窗口右上角添加一个close按钮,设置按钮图片,按钮大小,单位为像素
web1:enableCloseButton(NativeDevice.WebView.TOP_RIGHT,imgPath.."close.png",32,32);

--设置webview在加载网页时显示一个loading动画,设置动画图片,动画窗口大小,单位为像素,动画窗口显示的文字
web1:enableLoadingDialog(imgPath.."load1.png",loadingSize,loadingSize,"加载&Loading...");

--设置webview显示水平和垂直滚动条
web1:enableScrollBar(true,true);

--设置webview禁止缓存
web1:enableCache(false);

--设置webview浏览时禁止回退和前进
web1:enableBackOrForward(false);

--打开webview窗口,并且加载指定网址
web1:loadUrl("www.boyaa.com");

原生对话框 ¶

--创建一个AlertDialog对象
local dlg = NativeDevice.AlertDialog();

--设置标题
dlg:setTitle("title");

--设置内容
dlg:setMessage("message content");

--添加一个close按钮
dlg:enableButton(NativeDevice.AlertDialog.BUTTON_IDX_0,"close");

--显示AlertDialog,设置用户点击按钮的lua回调函数为nil
dlg:show(nil);

API参考 ¶

前言 ¶

Device插件的所有接口,都在NativeDevice表(lua表)下;下面文档中会省略NativeDevice表

以下所有未特别说明的接口,都支持三个平台：win32、android、iOS

以下所有未特别说明的接口,都只能在lua主线程(渲染线程)中调用

以下所有未特别说明的接口,都是同步接口

以下所有未特别说明的接口,不用考虑调用接口的耗时

基本 ¶

API列表
NativeDevice.print(str)
功能说明 打印日志

str 类型为 string

返回值 无
NativeDevice.isReady()
功能说明 检查NativeDevice是否初始化完成. 因为NativeDevice会在原生线程中初始化, lua主线程中需要检查初始化是否完成, 然后再访问其接口.

返回值 类型为 boolean

支持版本 4.0以上

Permissions(权限)¶

简介

提供相机、相册、通讯录、访问手机信息、录音的权限管理
API列表
Permissions.getStatus(type)
功能说明 查询某类权限的状态,权限的状态有4种: 未确定,授权,拒绝,限制授权

type 查询的类型,取值为:

Permissions.CAMERA

Permissions.PHOTO_LIBRARY

Permissions.CONTACTS

Permissions.PHONE_STATE

Permissions.RECORD_AUDIO

Permissions.GEO_LOCATION

Permissions.EXTERNAL_STORAGE

返回值 返回权限的状态, 取值为:

Permissions.STATUS_NOT_DETERMINED

Permissions.STATUS_GRANTED

Permissions.STATUS_DENIED

Permissions.STATUS_RESTRICTED
Permissions.request(type,function)
功能说明 请求某类权限. 如果某类权限为 Permissions.STATUS_NOT_DETERMINED 状态,调用此接口可以打开系统对话框,让用户进行授权.

type 请求的类型,取值为:

Permissions.CAMERA

Permissions.PHOTO_LIBRARY

Permissions.CONTACTS

Permissions.PHONE_STATE

Permissions.RECORD_AUDIO

Permissions.GEO_LOCATION

Permissions.EXTERNAL_STORAGE

function 函数声明为:
onUserGrant=function(granted)
        --granted 取值为 true/false, true以为用户同意授权
end
function 不允许为 nil

返回值 无
Permissions.requestReason(type,param,function)
功能说明 当用户拒绝( Permissions.STATUS_DENIED )了某类权限后,调用此接口创建对话框向用户解释申请某类权限的原因,如果用户同意则可再次进行授权.

type 请求的类型,取值为:

Permissions.CAMERA

Permissions.PHOTO_LIBRARY

Permissions.CONTACTS

Permissions.PHONE_STATE

Permissions.RECORD_AUDIO

Permissions.GEO_LOCATION

Permissions.EXTERNAL_STORAGE

function 函数声明为:
onUserGrant=function(granted)
        --granted 取值为 true/false, true以为用户同意授权
end
function 不允许为 nil

param 对话框的参数, 类型为 lua table, 如下:
param = {
        reason="拍照功能需要使用您的相机,在使用相机之前需要您授权同意,请点击[下一步]进入授权界面", --向用户解释原因
        ok_title="下一步", --用户同意按钮的标题
        cancel_title="取消" --用户不同意按钮的标题
        };
返回值 无

win32提供了对以上权限接口的完整模拟,介绍如下: 在 Settings.exe 中可以修改权限；在 device.lua 中可以选择win32模拟哪类设备的权限,支持:

iOS

android 4.x原生

android 4.x 定制或root版

android 6.0

device.lua中配置示例如下:
permissions = {
        options = {"ios","android_4","android_root","android_6"},
        camera = "ios", --win32模拟iOS相机权限
        photo_library="android_6", --win32模拟 android 6.0 相册权限
        contacts="android_root", --win32模拟 android 4.x 华为 通讯录权限
        phone_state="android_4", --win32模拟 android 4.x 原生版权限
        record_audio="android_4",
        geo_location="android_6",
}

Camera(相机)¶

简介

调用系统相机,完成一般的拍照功能
API列表
Camera.setImagePath(path)
功能说明 设置拍摄图片的存放路径,缺省值为空

path 类型为 string ,拍照图片文件保存路径

返回值 无
Camera.setImageFormat(format)
功能说明 设置拍摄图片的格式,缺省值为png格式

format 图片格式,取值为:

Camera.IMAGE_PNG

Camera.IMAGE_JPG

返回值 无
Camera.setQuality(quality)
功能说明 设置拍摄图片后保存图片质量,仅对jpg格式有效

quality 图片质量,取值为0-100,缺省值为80

返回值 无
Camera.setImageSize(width,height)
功能说明 设置拍摄图片的长度、宽度,单位为像素,缺省值为0,0

width 类型为 number ,宽度,>=0

height 类型为 number ,宽度,>=0,如果 width height 其中一个为0,则为0的值会自动按原图的长宽比计算

返回值 无
Camera.enableEdit(enable)
功能说明 设置拍摄完成后允许编辑,缺省为 true

enable 类型为 boolean

返回值 无
Camera.select(type)
功能说明 选择摄像机

type 相机类型,取值为:

Camera.DEFAULT_CAMERA

Camera.FRONT_CAMERA

缺省为 Camera.DEFAULT_CAMERA

返回值 无

支持平台 Camera.FRONT_CAMERA 仅支持iOS平台
Camera.open(function)
功能说明 启动相机进行拍照

function 函数声明为:
onCameraEvent=function(flag,fileName)
        --flag取值为:
        --Camera.OPEN_SUCCESS 拍摄成功
        --Camera.OPEN_CANCEL 拍摄时用户取消
        --Camera.OPEN_ERROR 拍摄时未知错误
        --Camera.OPEN_NO_PERMISSION 没有权限

        --fileName取值:当flag为Camera.OPEN_SUCCESS时,fileName为图片名,例如:13198118.png

end
function 不允许为 nil

返回值 无

此为异步接口

平台差异 android平台不同厂家（三星、华为、小米、360等）调用此接口会有差异, 未授权时华为mate7(android 4.x) 上 onCameraEvent 不会被调用. 未授权时360(android 6.0)上事件结果是 Camera.OPEN_CANCEL .

权限 Permissions.CAMERA

PhotoLibrary(相册)¶

简介

打开系统缺省图片浏览器,选择一张图片
API列表
PhotoLibrary.setImagePath(path)
功能说明 设置选中图片的存放路径,缺省值为空

path 类型为 string ,选中图片文件保存路径

返回值 无
PhotoLibrary.setImageFormat(format)
功能说明 设置选中图片的保存格式,缺省值为png格式

format 图片格式,取值为:

PhotoLibrary.IMAGE_PNG

PhotoLibrary.IMAGE_JPG

返回值 无
PhotoLibrary.setQuality(quality)
功能说明 设置选中图片后保存图片的质量,仅对jpg格式有效

quality 图片质量,取值为0-100,缺省值为80

返回值 无
PhotoLibrary.setImageSize(width,height)
功能说明 设置选中图片保存的长度、宽度,单位为像素,缺省值为0,0

width 类型为 number ,宽度,>=0

height 类型为 number ,宽度,>=0,如果 width height 其中一个为0,则为0的值会自动按原始图片的长宽比计算

返回值 无
PhotoLibrary.enableEdit(enable)
功能说明 设置选中后允许编辑,缺省为 true

enable 类型为 boolean

返回值 无
PhotoLibrary.pick(function)
功能说明 打开系统缺省图片浏览器进行选择

function 函数声明为:
onPhotoLibraryEvent=function(flag,fileName)
        --flag取值为:
        --PhotoLibrary.PICK_SUCCESS 选择成功
        --PhotoLibrary.PICK_CANCEL 选择时用户取消
        --PhotoLibrary.PICK_ERROR 选择时未知错误
        --PhotoLibrary.PICK_NO_PERMISSION 没有权限

        --fileName取值:当flag为PhotoLibrary.PICK_SUCCESS,fileName为图片名,例如:13198118.png

end
function 不允许为 nil

返回值 无

此为异步接口

平台差异 android平台不支持 PhotoLibrary.PICK_NO_PERMISSION 参数,但用户拒绝权限时, onPhotoLibraryEvent 不会被调用

权限 Permissions.PHOTO_LIBRARY
PhotoLibrary.insertImageFile(path)
功能说明 将指定图片文件放入相册

path 类型为 string ,图片文件的完整路径

返回值 返回 boolean 如果文件不存在则返回 false

此为异步接口 调用此接口返回 true 后不能立即删除文件,因为执行图片文件拷贝的线程还未执行完成.

权限 Permissions.EXTERNAL_STORAGE

Contacts(通讯录)¶

简介

通讯录的读取

win32平台可以在 device.lua 中配置
API列表
contacts.getCount()
功能说明 读取通讯录中记录的数目

返回值 类型为 number ,返回数目

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几十毫秒,iOS平台调用此接口耗时在几十毫秒

权限 Permissions.CONTACTS
contacts.read(start,num,sortType)
功能说明 读取通讯录中的记录

start 类型为 number ,从第start条开始读取, -1意为倒数第1条

num 类型为 number ,最多读取num条

sortType 固定取值为 contacts.SORT_DEFAULT ,保留值

返回值 类型为 table 或 nil ,例如:
--contacts[1] = {id="7033",name="赵丽颖",timestamp=1474193836631.000,phone_numbers = {home="0755-88886666",mobile="13988886666"}}
--contacts[2] = {id="7034",name="李易峰",timestamp=1474193836631.000,phone_numbers = {"46446","+86 18633443344"}}
--...
--contacts[5] = {id="7028",name="杨紫",timestamp=1474193836631.000,phone_numbers = {workNumber="010-88310571"}}

--说明1:phone_numbers是一个lua table; 其中的电话号码是从手机中读出并且未做任何处理的.
--说明2:timestamp是此条记录的最后修改时间
线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几十至几百毫秒,iOS平台调用此接口耗时在几十至几百毫秒

权限 Permissions.CONTACTS
contacts.search(key)
功能说明 按关键字搜索通讯录中的记录

key 类型为 string ,搜索关键字,例如 “张” “139”

返回值 同 contacts.read

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几十至几百毫秒,iOS平台调用此接口耗时在几十至几百毫秒

权限 Permissions.CONTACTS

Uri ¶

简介

提供Uri(统一资源标识符Uniform Resource Identifier)的相关接口
API列表
Uri.stringEscape(str,spaceToPlus,normalizeBreaks);
功能说明 url编码

str 类型为 string 输入的字符串

spaceToPlus 类型为 boolean 是否将空格转为+

normalizeBreaks 类型为 boolean 是否将CR和LF转为CR-LF

返回值 类型为 string ,编码后的字符串
Uri.stringUnescape(str,plusToSpace);
功能说明 url解码

str 类型为 string 输入的字符串

plusToSpace 类型为 boolean 是否将+转为空格

返回值 类型为 string ,解码后的字符串

GeoLocation(定位)¶

简介

提供定位相关功能
API列表
GeoLocation.isEnable(type)
功能说明 检查 type 功能是否可用

type 取值 GeoLocation.GPS 或 GeoLocation.NETWORK, 一般手机均支持2种定位, 一种是卫星定位, 一种是网络(cell或wifi等)定位. 该接口的一种用途是:如果需要GPS定位,可以预先检查一下是否可用. 如果要定位到城市,那么用网络定位可能更快.

返回值 类型为 boolean

权限 Permissions.GEO_LOCATION
GeoLocation.showSettings()
功能说明 打开定位服务的系统设置对话框,可以让用户更快捷的启动系统的定位服务.

返回值 无
GeoLocation.setEvent(accuracy, minTime, minDistance,function);
功能说明 启动定位, 位置信息会源源不断的发往 function ,每次调用此接口,都会先清除上一次的调用和参数设置.

accuracy 定位精度, 取值如下. 定位精度要求越高,越耗电,精度要求越高,首次定位速度越慢.建议选择业务所需的合理精度. 定位精度仅是一个参考值,定位结果的精度可能与其有出入.
GeoLocation.ACCURACY_FOR_NAVIGATION 用于导航的精度
GeoLocation.ACCURACY_BEST  最好的精度
GeoLocation.ACCURACY_TEN_METERS  10米左右的精度
GeoLocation.ACCURACY_HUNDRED_METERS  100米左右的精度
GeoLocation.ACCURACY_KM  公里级的精度
GeoLocation.ACCURACY_THREE_KMS  三公里的精度
minTime 定位的最小时间间隔.单位为 毫秒 , 系统将会按照这个最小间隔来定位. 时间间隔越小,越耗电.

minDistance 距离变化的最小值, 当位置发生变化之后,与上一次位置的距离大于该值时,才回调 function ,仅作为一个参考值.

function 系统调用此函数来传递定位结果, 函数声明为:
function onLocation (location)
--[[
        location是一个table,定义如下
        location = {
                status = GeoLocation.STATUS_XXX, --返回定位结果的当前状态和信息,下文有定义
                gps = true, --定位的结果是否来源于gps,取值 true or false
                longitude = 经度,
                latitude = 纬度,
                altitude = 海拔,米
                accuracy = 精度,米
                timestamp = 时间戳,毫秒
        }
]]
end
status 取值如下:
GeoLocation.STATUS_AVAILABLE_WITH_DATA  定位设备可用,当前location结果中包含经纬度等定位数据
GeoLocation.STATUS_AVAILABLE            定位设备可用,
GeoLocation.STATUS_TEMPORARILY_UNAVAILABLE  定位设备临时不可用,可以继续使用.
GeoLocation.STATUS_OUT_OF_SERVICE           无GPS信号(不在服务区) ,可以继续使用.
GeoLocation.STATUS_ENABLE                   定位被启用(比如:手机中的位置服务被用户启用)
GeoLocation.STATUS_DISABLE                  定位被禁用或或其他原因无法使用.无法继续使用.

对于可以继续使用的状态, location 数据还会继续收到.
function 取值为 nil 则会终止定位.

返回值 无

支持平台 win32平台通过地图来模拟定位,需要开发人员手动在地图上多次选择位置.

权限 Permissions.GEO_LOCATION
GeoLocation.setSingleEvent(accuracy, function);
功能说明 定位1次, 位置信息(或错误信息)会发往 function ,连续调用多次本接口, 每次调用都会回调 function ,除了导航等功能以外,大多业务需求仅需1次定位, 更省电,速度可能更快.

accuracy 定位精度, 同 setEvent 的参数``accuracy``

function 为 nil 则调用无效, 其余使用同 setEvent``的参数 ``function

返回值 无

支持平台 win32平台通过地图来模拟定位,需要开发人员手动在地图上选择1次位置.

权限 Permissions.GEO_LOCATION

WebView(嵌入浏览器)¶

简介
嵌入浏览器:

支持设置浏览器窗口大小;支持lua和javascript互相调用;支持在浏览器窗口的顶部添加一个原生的关闭按钮

tips 引擎画面、原生WebView、html5界面:

引擎画面本身是一个原生窗口,WebView也是一个原生窗口,WebView叠加到引擎窗口之上,所以WebView会遮挡住引擎绘制的所有内容.

对于html5内容,就完全在WebView窗口之内.

此外,WebView支持在自己的顶部添加一个原生的按钮,这个按钮的位置可以超出WebView一半,如果是透明的图片,引擎画面会透过来,也可以是不超出WebView的区域,如下图:

基于这些特性,使用WebView有一些技巧: 对于非全屏的WebView,可以使用WebView提供的顶部关闭按钮.对于全屏WebView,既可以用上面这种关闭按钮,也可以用html5来实现顶部的返回或关闭按钮.不过如果用html5来实现关闭按钮的话,有可能html加载失败,此时按钮就无法显示了.

tips

引擎WebView和Html5/JS交互的分享： http://stackoverflow.oa.com/article/13

tips

视频格式支持：iOS支持H264, android 2.3+ 支持H264/WebM. 可用如下网站测试: http://www.quirksmode.org/html5/tests/video.html

tips 请注意WebView接口调用的限制:

比如WebView对象的 enableCloseButton 和 enableLoadingDialog 一旦被调用,该对象就不能取消关闭按钮或Loading对话框了。

tips IOS8以上(WKWebView)的差异:

IOS8以上,WebView的背景色会变为透明,请H5开发同学强制设置背景色.

IOS8以上,网页会显示的比较小,请在H5页面中控制页面显示大小,例如添加如下代码:
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" >
tips win32平台支持IE9/IE10/IE11/chrome21,您可以在 device.lua 中配置当前要使用哪一种浏览器

tips 存在这样的问题:

用户点击网页中的编辑框时,如果编辑框太靠近下方,弹出的软键盘可能会遮挡编辑框.这将导致用户无法看到输入的内容.这个问题是系统原因造成,建议H5开发同学在布局的时候考虑这种情况.

https://code.google.com/p/android/issues/detail?id=5497

有一种解决方法是：当用户点击网页中的编辑框时,创建一个原生的编辑框,让用户在这个编辑框中输入.但这种方法需要先关闭再弹出软键盘,很卡,体验不好,所以没有采用此种方法.
API列表
WebView(x,y,width,height)
功能说明 创建WebView对象

x,y,width,height 类型为 number ,屏幕坐标

返回值 WebView对象,是一个lua引用,在该引用被释放时,WebView对象也被销毁.
WebView.setRect(x,y,width,height)
功能说明 设置屏幕坐标,可以在WebView创建前后来设置WebView的位置和大小

x,y,width,height 类型为 number ,屏幕坐标

返回值 无
WebView.setBackgroundColor(r,g,b)
功能说明 设置背景色. 缺省为透明. 此处设置网页加载完成之前的背景色,加载完成之后的背景色由网页自行设定. 在 loadUrl 或 loadFile 调用之前,调用本接口有效

r,g,b 类型为 number , 分别是红色、绿色、蓝色分量,取值 [ 0.0, 1.0 ]

返回值 无

支持平台 不支持win32平台.
WebView.loadUrl(stringUrl)
功能说明 加载一个网址,调用此接口后,WebView才在引擎画面上显示.可以对同一个WebView对象多次调用此接口加载不同url

stringUrl 类型为 string ,网址,例如 www.boyaa.com

返回值 无

此为异步接口

tips iOS9+版本限制打开http网址,可参考 NSAppTransportSecurity 相关说明
WebView.loadFile(basePath,fileName)
功能说明 加载一个本地网页文件,调用此接口后,WebView才在引擎画面上显示.可以对同一个WebView对象多次调用此接口加载不同内容

basePath 类型为 string ,一般取值为 sys_get_string("storage_inner_root") 代表与引擎的scripts image目录是同级目录

fileName 类型为 string ,网页文件名

返回值 无

此为异步接口

备注 如果网页中包含图片或js脚本,图片和js请用相对路径；iOS平台要求图片和js必须位于当前网页的相同或子目录下.

android平台可以加载apk中的网页文件,WebView内部首先会检查basePath+fileName组成的绝对路径的网页文件是否存在,如果不存在,就会忽略basePath并尝试加载apk中assets下的fileName文件. 比如要加载assets/html/help.html文件,需要将fileName写为html/help.html.
WebView.loadString(htmlString,baseUrl,encoding)
功能说明 加载一个字符串,调用此接口后,WebView才在引擎画面上显示.可以对同一个WebView对象多次调用此接口加载不同内容

htmlString 类型为 string

baseUrl 类型为 string ,网页中相对路径的baseUrl,可以为”“

encoding 类型为 number ,固定为 WebView.ENCODING_UTF8

返回值 无

此为异步接口

支持平台 baseUrl 参数在win32平台无效
WebView.enableLoadImage(type)
功能说明 设置仅在WIFI网络时下载图片,缺省不是.

type 类型为 number ,取值为 WebView.WIFI 或者 WebView.ALL

返回值 无

支持平台 不支持win32平台,不支持iOS平台
WebView:close()
功能说明 关闭WebView窗口.在WebView显示之后,调用本接口有效

返回值 无

此为异步接口
WebView:setEvent(function)
功能说明 设置WebView的事件响应接口.在 loadUrl 或 loadFile 调用之前,调用本接口有效

function 函数声明为:
onLoadEvent=function(cmd)
        --cmd取值为:
        --WebView.EVENT_LOAD_SUCCESS 网页加载成功
        --WebView.EVENT_LOAD_FAILED 网页加载失败
        --WebView.EVENT_CLOSE 用户点击WebView自带的关闭按钮或javascript调用native_close
        --WebView.EVENT_REFRESH 下拉更新事件,可在这个事件里重新加载网页
end
function 取值为 nil 则会设置事件响应函数为空

返回值 无

支持平台 WebView.EVENT_REFRESH 不支持win32平台
WebView:setJsCallback(function)
功能说明 设置WebView的响应javascript调用的回调函数.在 loadUrl 或 loadFile 调用之前,调用本接口有效

function 函数声明为:
onJsCall=function(stringData)
        --stringData是javascript传递的字符串
end
function 取值为 nil 则会设置事件响应函数为空

返回值 无
WebView:callJs(funcName,stringData)
功能说明 调用javascript函数

funcName 类型为 string ,javascript的函数名,是一个网页最顶层的全局javascript函数

stringData 类型为 string ,传递给javascript函数的字符串参数

javascript的例子
<script type="text/javascript">
function webview_data_init(stringDataFromLua)
{
        window.alert(stringDataFromLua);
}
</script>

//WebView内置了4个javascript接口,javascript开发者可以使用这4个接口,声明如下:
function native_call(stringData);
function native_close();
function native_log(stringData);
function native_close_loading();

//调用native_call(stringData)后,lua中onJsCall函数会响应
//调用native_close(),lua中会响应onLoadEvent(WebView.EVENT_CLOSE)
//调用native_log(stringData),可以将stringData输出到lua日志相同的地方
//调用native_close_loading(),会关闭loading动画界面
lua的例子
myWeb:callJs("webview_data_init","json_data_from_http");
返回值 无

lua和javascript互相调用均为异步接口
WebView:enableCloseButton(pos,imagePath,width,height)
功能说明 在WebView顶部添加一个原生关闭按钮,在第一次 loadUrl 或 loadFile 调用之前,调用本接口有效.一旦调用过此接口,可以再次调用来修改参数,但无法禁用原生按钮.

pos 添加按钮的位置,取值为预定的值: WebView.TOP_LEFT WebView.TOP_LEFT_INNER 是在左上角添加, WebView.TOP_RIGHT WebView.TOP_RIGHT_INNER 是在右上角添加

imagePath 类型为 string ,是图片(支持png和jpg)的完整路径,该图片将被加载并显示为关闭按钮

width 类型为 number ,图片显示的宽度,单位为像素

height 类型为 number ,图片显示的高度,单位为像素

返回值 无
WebView:enableLoadingDialog(imagePath,width,height,loadingText)
功能说明 允许WebView在网页加载期间显示一个loading动画界面.在第一次 loadUrl 或 loadFile 调用之前,调用本接口有效.一旦调用过此接口,可以再次调用来修改参数,但无法不显示loading动画.

imagePath 类型为 string ,是图片(支持png和jpg)的完整路径,该图片将被加载并显示为动画

width 类型为 number ,图片显示的宽度,单位为像素

height 类型为 number ,图片显示的高度,单位为像素

loadingText 类型为 string ,loading动画的文字提示,允许为”“

返回值 无
WebView:enableLoadingDialog2(imagePath,width,height,loadingText,closeTimeout)
功能说明 在 enableLoadingDialog 基础上增加了 closeTimeout 参数, 允许延时关闭loading动画界面

closeTimeout 类型为 number ,延时时长, 单位为毫秒

返回值 无
WebView:enableScrollBar(hScroll,vScroll)
功能说明 设置WebView是否显示水平滚动条和垂直滚动条,缺省仅显示垂直滚动条.在 loadUrl 或 loadFile 调用之前,调用本接口有效

hScroll 类型为 boolean ,是否显示水平滚动条

vScroll 类型为 boolean ,是否显示垂直滚动条

返回值 无

支持平台 win32(IE)平台上水平和垂直滚动条无法单独控制可见性,只能全部显示或全部隐藏.win32(chrome21)不支持滚动条的可见性控制(H5可以). IOS设置任一滚动条不显示,则水平和垂直滚动条都不显示.
WebView:enablePullRefresh(titleUp,titleDown,imagePathUp,imagePathDown,imageWidth,imageHeight,subTitle)
功能说明 允许用户下拉网页后刷新网页,例如:
local imgPath = sys_get_string("storage_app_images");
local imageUp = imgPath.."common/arrow_up.png";
local imageDown = imgPath.."common/arrow_down.png";
web1:enablePullRefresh("下拉中...","松开刷新",imageUp,imageDown,64,64,"最后更新时间12:00:00");
--响应 WebView.EVENT_REFRESH 事件
返回值 无

支持平台 不支持win32平台
WebView:enableCache(enable)
功能说明 设置WebView是否优先使用缓存的网页(未过期的情况下),缺省是不缓存,在 loadUrl 或 loadFile 调用之前,调用本接口有效

enable 类型为 boolean ,是否使用缓存

返回值 无

支持平台 IOS不支持Cache
WebView:enableBackKey(enable)
功能说明 设置android返回键是否令到WebView回退,缺省是 false .在 loadUrl 或 loadFile 调用之前,调用本接口有效

enable 类型为 boolean

返回值 无
WebView:enableBackOrForward(enable)
功能说明 设置WebView是否允许回退、前进;只有允许之后,android的Back才可能回退,网页中(javascript)调用回退、前进功能才有效,缺省是 false .在 loadUrl 或 loadFile 调用之前,调用本接口有效

enable 类型为 boolean ,是否支持回退、前进

返回值 无
WebView:setVisible(visible)
功能说明 设置WebView可见性,缺省是可见,注意:设置引擎节点与设置WebView的可见性,是不同步的.在 loadUrl 或 loadFile 调用之后,调用本接口有效

visible 类型为 boolean ,是否可见

返回值 无

此为异步接口

AlertDialog(原生对话框)¶

简介

原生弹出框,非阻塞

android使用android.app.AlertDialog实现

iOS使用UIAlertView和UIAlertController实现

win32使用modeless dialog实现
API列表
AlertDialog()
功能说明 创建AlertDialog对象

返回值 返回AlertDialog对象,是一个lua引用,在该引用被释放时,AlertDialog对象也被销毁.
AlertDialog:setTitle(title)
功能说明 设置标题,缺省为”“

title 类型为 string ,标题

返回值 无
AlertDialog:setMessage(msg)
功能说明 设置显示内容,缺省为”“

msg 类型为 string ,内容

返回值 无
AlertDialog:enableButton(idx,buttonText)
功能说明 启用内置的按钮,缺省包含一个按钮,按钮文字是”close”,最多支持2个按钮.

idx 预定义的按钮id,取值为:

AlertDialog.BUTTON_IDX_0

AlertDialog.BUTTON_IDX_1

buttonText 类型为 string ,按钮上的文字

返回值 无
AlertDialog:show(function)
功能说明 显示对话框,非阻塞调用,创建并同时弹出多个AlertDialog是允许的

function 函数声明为:
onAlertDialogClose=function(idx)
        --idx为用户点击的按钮id,取值为:
        --AlertDialog.BUTTON_IDX_0
        --AlertDialog.BUTTON_IDX_1

end
function 可以为 nil

返回值 无

此为异步接口

Toast(小提示)¶

简介

在引擎画面最前端显示一个提示框,超时后会自动消失(销毁)

参考android的Toast实现
API列表
Toast.show(msg,pos,duration)
功能说明 显示一个提示,非阻塞调用

msg 类型为 string ,提示内容

pos 显示的位置,预定义的位置值, 取值为:

Toast.TOP 垂直方向上位于屏幕上方,水平居中;

Toast.CENTER 垂直方向上位于屏幕中间,水平居中;

Toast.BOTTOM 垂直方向上位于屏幕下方,水平居中

duration 显示的持续时长,预定义的值,取值为：

Toast.DURATION_SHORT 短时间(2秒);

Toast.DURATION_LONG 长时间(3.5秒)

返回值 无

此为异步接口

DeviceInfo(设备信息)¶

简介

获取设备信息的接口
API列表
DeviceInfo.getPlatform()
功能说明 获取平台类型

返回值 类型为 string ,目前返回值包括 android ios win32

线程支持 支持在任意线程中调用
DeviceInfo.getVersion()
功能说明 返回OS版本号

返回值 类型为 string , android平台返回的是android.os.Build.$VERSION.RELEASE,例如返回”4.2.2”; iOS平台返回的是[[UIDevice currentDevice] systemVersion],例如返回”9.3.2”; win32平台返回的是Win8.1 Win10等

线程支持 支持在任意线程中调用
DeviceInfo.getAppInfo(type);
功能说明 获取本应用的信息

type 支持的信息类型,取值为:

DeviceInfo.PACKAGE_NAME_OR_BUNDLE_ID 返回android的 package name 或iOS平台的 CFBundleIdentifier

DeviceInfo.VERSION_CODE_OR_BUNDLE_VERSION 返回android的 versionCode 或iOS平台的 CFBundleVersion

DeviceInfo.VERSION_NAME_OR_BUNDLE_SHORT_VERSION_STRING 返回android的 versionName 或iOS平台的 CFBundleShortVersionString

返回值 类型为 string , win32平台可以在 device.lua 中配置

线程支持 支持在任意线程中调用
DeviceInfo.getUserAgent()
功能说明 获取浏览器user-agent

返回值 类型为 string , win32平台可以在 device.lua 中配置

线程支持 支持在任意线程中调用

性能说明 首次调用此接口耗时往往在几十到几百毫秒
DeviceInfo.getUUID()
功能说明 返回一个通用唯一识别码 (Universally Unique Identifier)

返回值 类型为 string , android平台返回的是UUID.randomUUID(),每次调用此接口,都会重新生成一个值; iOS平台返回的是一个CFUUIDCreate生成的UUID,每次调用此接口,都会重新生成一个值; win32平台返回的是CoCreateGuid生成的GUID,每次调用此接口,都会重新生成一个值

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒以上
DeviceInfo.getSerial()
功能说明 获取设备序列号(唯一标识)

返回值 类型为 string , android平台返回的是android.os.Build$SERIAL,例如:某手机返回的是”M9N7N15929003218”; win32平台返回主板的序列号

支持平台 不支持iOS平台

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒
DeviceInfo.isVirtual()
功能说明 是否在模拟器上运行

返回值 类型为 boolean

线程支持 支持在任意线程中调用

支持平台 不支持 android TV, win32平台可以在 device.lua 中配置
DeviceInfo.isTablet()
功能说明 是否是平板

返回值 类型为 boolean

线程支持 支持在任意线程中调用

支持平台 不支持 android TV, win32平台可以在 device.lua 中配置
DeviceInfo.getName()
功能说明 获取设备用户名称(iOS->设置->通用->关于本机->名称, android是获取蓝牙的名称)

返回值 类型为 string , win32平台可以在 device.lua 中配置

线程支持 支持在任意线程中调用
DeviceInfo.getModel()
功能说明 获取设备型号

返回值 类型为 string , android平台返回的是android.os.Build$MODEL,例如:华为Mate7手机返回的是”HUAWEI MT7-TL10”; iOS平台返回的是 iPhone 6 Plus iPad Air 2 iPad Pro 12.9-inch 等等, win32平台返回的是电脑型号

线程支持 支持在任意线程中调用
DeviceInfo.getBrand()
功能说明 获取品牌名

返回值 类型为 string , win32平台可以在 device.lua 中配置

线程支持 支持在任意线程中调用
DeviceInfo.getManufacturer()
功能说明 返回制造商名称

返回值 类型为 string , android平台返回的是android.os.Build$MANUFACTURER,例如:华为手机返回的是”HUAWEI”; iOS平台返回的是”Apple”

线程支持 支持在任意线程中调用
DeviceInfo.getLocale()
功能说明 获取当前设置区域的语言

返回值 类型为 string , win32平台可以在 device.lua 中配置

线程支持 支持在任意线程中调用
DeviceInfo.getCountry()
功能说明 获取当前设置的国家或地区

返回值 类型为 string , win32平台可以在 device.lua 中配置

线程支持 支持在任意线程中调用
DeviceInfo.getTimeZone()
功能说明 获取当前时区

返回值 类型为 string , win32平台可以在 device.lua 中配置

线程支持 支持在任意线程中调用
DeviceInfo.getStorageSize(type)
功能说明 获取总的存储空间大小,对于win32来说,是获取磁盘分区的大小,对于iOS来说,是获取机身存储的大小.

type 类型为 number ,取值为 DeviceInfo.INTERNAL 或者 DeviceInfo.EXTERNAL ,对于win32和iOS来说,传这两个参数获取的结果是一样的,对于Android来说, DeviceInfo.INTERNAL 是获取机身存储的大小. 对于 DeviceInfo.EXTERNAL 如果使用sd卡作为主外部存储,则获取的是sd卡的大小,否则是获取机身存储大小.如果使用引擎3.x向 storage_outer_root 写文件前要判断存储空间是否够用,就要用 DeviceInfo.EXTERNAL .

返回值 类型为 number ,单位为字节

线程支持 支持在任意线程中调用
DeviceInfo.getStorageAvailable(type)
功能说明 获取可用存储空间大小

type 类型为 number ,取值为 DeviceInfo.INTERNAL 或者 DeviceInfo.EXTERNAL

返回值 类型为 number ,单位为字节

线程支持 支持在任意线程中调用

MemoryInfo(内存信息)¶

简介

获取内存信息的接口

API列表

MemoryInfo.getMemoryInfo()

功能说明 实时获取内存信息

返回值 类型为 table , android 返回值为

mem_info = {
        totalMem = 0,
        availMem = 0,
        threshold = 0,

        runtime={
                maxMemory = 0,
                totalMemory = 0,
                freeMemory = 0}

        debug = {
                totalPss = 0,
                totalPrivateDirty = 0,
                totalSharedDirty = 0,
                dalvikPss = 0,
                dalvikPrivateDirty = 0,
                dalvikSharedDirty = 0,
                nativePss = 0,
                nativePrivateDirty = 0,
                nativeSharedDirty = 0,
                otherPss = 0,
                otherPrivateDirty = 0,
                otherSharedDirty = 0}}

详情请参考:http://stackoverflow.oa.com/question/69

iOS 返回值为

mem_info = {
        physicalMemory = 0,
        wire_count = 0,
        active_count = 0,
        inactive_count = 0,
        free_count = 0,
        resident_size = 0}

详情请参考:http://stackoverflow.oa.com/article/20

win32 返回值为

mem_info = {
        totalPhys = 7984279552, --RAM大小,8G
        availPhys = 2914562048, --操作系统中剩余的RAM 接近3G
        workingSetSize = 44417024 --当前进程已经使用的RAM 44M左右, 因为windows平台大量存在独立显存的显卡,此值不包含贴图.
        }

线程支持 支持在任意线程中调用

NativeDevice(设备相关功能)¶

简介

提供了震动、铃声、设置屏幕亮度等接口 直接由NativeDevice提供
API列表
NativeDevice.Vibrate(ms)
功能说明 设备震动

ms 类型为 number ,震动的时长,单位为毫秒,取值为0意为停止震动

返回值 无

支持平台 iPhone/iPod不支持 ms 参数;iPad不支持此接口;部分android pad不支持此接口
NativeDevice.Beep()
功能说明 铃声

返回值 无

支持平台 iOS不支持此接口;部分android pad不支持此接口
NativeDevice.setScreenBrightness(level)
功能说明 设置屏幕亮度

level 类型为 number ,level取值0.0~1.0,1.0屏幕最亮

返回值 无

平台差异 android平台上,设置亮度之后,不影响其他程序的屏幕亮度,重启游戏失效; iOS平台上,设置亮度后,不影响其他程序的屏幕亮度,重启游戏失效; windows平台上,设置亮度后,会改变整个屏幕亮度,影响到所有程序,重启电脑失效

已知问题 iOS平台在游戏切换到后台之后,如果玩家在系统设置或其他App中设置了亮度,下次游戏切换到后台之后,并不能恢复原样；
NativeDevice.keepScreenOn(enable)
功能说明 设置屏幕常亮并且不锁屏,缺省为NO

enable 类型为 bool

返回值 无
NativeDevice.openUrl(url)
功能说明 用操作系统缺省浏览器打开一个网址

url 类型为 string url地址

返回值 无
NativeDevice.openDialer(phoneNumber)
功能说明 打开系统的电话拨号界面

phoneNumber 类型为 string 电话号码

返回值 无

平台差异 win32平台为模拟界面
NativeDevice.openSms(phoneNumber,content)
功能说明 打开系统的短信发送界面

phoneNumber 类型为 string 电话号码

content 类型为 string 短信内容

返回值 无

平台差异 iOS平台不支持 content 参数; win32平台为模拟界面

NetworkInfo(网络)¶

简介

获取网络类型,监控网络连接和断开的系统事件
API列表
NetworkInfo.getNetworkType()
功能说明 获取联网类型

返回值 返回值为预定义的值,取值为:

NetworkInfo.TYPE_MOBILE 移动网络;

NetworkInfo.TYPE_WIFI WIFI;

NetworkInfo.TYPE_ETHERNET 以太网;

NetworkInfo.TYPE_UNKNOWN 未知

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时小于几毫秒

权限 Permissions.PHONE_STATE
NetworkInfo.getNetworkSubType()
功能说明 获取联网类型和子类型

返回值 返回值为预定义的值,取值为:

NetworkInfo.TYPE_2G NetworkInfo.TYPE_3G NetworkInfo.TYPE_4G 移动网络;

NetworkInfo.TYPE_WIFI WIFI;

NetworkInfo.TYPE_ETHERNET 以太网;

NetworkInfo.TYPE_UNKNOWN 未知

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时小于几毫秒

权限 Permissions.PHONE_STATE
NetworkInfo.getNetworkTypeName()
功能说明 获取联网类型的名称

返回值 类型为 string

支持平台 如果需要支持iOS平台的话,XCode设置中不要选中 “Hide status bar”

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时小于几毫秒

权限 Permissions.PHONE_STATE
NetworkInfo.getSSID()
功能说明 获取WIFI的名称,如果没有WIFI权限或未连接,则返回字符串长度为0

返回值 类型为 string

支持平台 不支持win32

线程支持 支持在任意线程中调用

权限 Permissions.PHONE_STATE
NetworkInfo.getMNO()
功能说明 获取 mobile network operator 的名称,也就是运营商的名称. 可能返回字符串长度为0

返回值 类型为 string

支持平台 不支持win32

线程支持 支持在任意线程中调用

权限 Permissions.PHONE_STATE
NetworkInfo.isNetworkConnected()
功能说明 检查是否联网

返回值 类型为 boolean

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时小于几毫秒

权限 Permissions.PHONE_STATE
NetworkInfo.isInternetConnected(ipOrHost,port,timeout)
功能说明 检查是否能连接到指定服务器

ipOrHost 类型为 string 服务器ip地址或域名,例如 "www.boyaa.com" 或 "183.61.180.186" .支持 IPV6

port 类型为 number 端口号

timeout 类型为 number 连接的超时时间,单位为毫秒. 如果 ipOrHost 为域名的话, 此参数仅包含连接的超时时间, 不包括域名解析的超时时间. 所以推荐用 IP 地址.

返回值 类型为 boolean ,连接成功返回 true

线程支持 支持在任意线程中调用

性能说明 此接口为同步接口,耗时从几毫秒到几十秒,建议在ThreadPool线程中使用.
NetworkInfo.setNetworkConnectivityEvent(function)
功能说明 启用网络断开、连接的监控功能

function 函数声明为:
onNetworkConnected=function(conn,subType)
        --conn取值为true/false
        --type取值为 network sub type

        --备注1:
        --conn和subType的值,是操作系统层在网络连通/断开时的值
        --isNetworkConnected()/getNetworkSubType()获取的是当前的值.
        --应用层收到事件是有延迟的,所以,以上两者有可能不同.

        --备注2:
        --android手机wifi断开,然后4G连接,事件序列如下:
        -- onNetworkConnected ( false, TYPE_WIFI )
        -- onNetworkConnected ( true, TYPE_4G )

        --iPhone wifi断开,然后4G连接,事件序列如下:
        -- onNetworkConnected ( true, TYPE_4G )

        --iPod wifi断开,事件序列如下:
        -- onNetworkConnected ( false, TYPE_UNKNOWN )

        --备注3:
        --事件可能会重复发送,所以,可以通过与上一次的值的比较,来决定后续的动作.
        --监控网络发生变化的一般流程:
        --第一步:调用isNetworkConnected()/getNetworkSubType()获取当前的值conn1,subType1;
        --第二步:调用 setNetworkConnectivityEvent 启用网络监控
        --第三步:在 onNetworkConnected 事件中,将conn1,subType1与conn,subType对比.

end
function 为 nil 意为停止(关闭)网络断开、连接的监控功能

返回值 无

平台差异 不支持win32

权限 Permissions.PHONE_STATE

PowerInfo(电力)¶

简介

获取电池电量,判断是否插电,低电警告等
API列表
PowerInfo.getBatteryValue()
功能说明 获取电池电量

返回值 类型为 number ,调用成功的取值范围为[0.0~1.0],接近1.0为满电,失败为其他值.

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时在几毫秒
PowerInfo.isCharging()
功能说明 检查是否正在充电

返回值 类型为 boolean

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时在几毫秒
PowerInfo.isPlug()
功能说明 检查是否连接插电设备

返回值 类型为 boolean

线程支持 支持在任意线程中调用

性能说明 Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时在几毫秒
PowerInfo.setChargingEvent(function)
功能说明 启用充电通知

function 函数声明为:
onCharging=function(charging)
        --charging取值为true/false
end
function 为 nil 意为停止(关闭)充电通知

返回值 无
PowerInfo.setLowPowerEvent(function)
功能说明 启用连接插电设备通知

function 函数声明为:
onLowPower=function(lowpower)
        --lowpower取值为true/false
end
function 为 nil 意为停止(关闭)插电设备通知

返回值 无
PowerInfo.setBatteryChangedEvent(function)
功能说明 启用电池电量信息监控

function 函数声明为:
onBatteryChanged=function(level)
        --level取值同 getBatteryValue 的返回值
end
function 为 nil 意为停止(关闭)通知

返回值 无

Sensor(传感器)¶

简介

传感器,提供加速计底层接口,提供摇晃检测、计步器等高级接口
API列表
Sensor.catchAccelerometer(function, hz)
功能说明 获取加速计数据,调用此接口后,加速计数据会源源不断通过function函数输出给lua,供lua代码处理,当程序切换到后台时加速计会暂停

function 函数声明为:
onAccelerometerDataEvent=function(x,y,z,timestamp)
        --x,y,z是double类型,3个方向的加速度
        --目前存在一个问题是:android和iOS设备的向上的方向是相反的
        --timestamp是double类型,时间戳,单位是秒,但精度达到了微秒,取毫秒值则是timestamp*1000,微秒值是timestamp*1000*1000
end
function 取值为 nil 则会设置失败

hz 类型为 number 正整数,每秒种抓取加速计值的次数(大约的值,经过测试,不太精确),参数名hz是赫兹的缩写.还可以使用下面一些预置的常量:

Sensor.UPDATE_UI 值为15

Sensor.UPDATE_GAME 值为50

Sensor.UPDATE_FASTEST 值为100

当然也允许设置为1000000以上的值,用于采集数据,不过这样比较耗电.

返回值 无

线程支持 阻塞函数,仅支持lua子线程中调用

支持平台 不支持win32,调用接口无效
Sensor.releaseAccelerometer()
功能说明 释放加速计

返回值 无

线程支持 阻塞函数,仅支持lua子线程中调用,包括调用 Sensor.catchAccelerometer 的线程

支持平台 不支持win32,调用接口无效
Sensor.setShakeEvent(function, param)
功能说明 启用手机摇晃检测.每次当手机达到摇晃标准时,都回调 function 一次

function 函数声明为:
onShakeEvent=function()

end
function 取值为 nil 则会取消摇晃检测

param 摇晃检测的参数, 类型为 lua table, 如果设为 nil 则取如下缺省值
param = {
        samplePerSecond = 50, --每秒钟从加速计(指硬件)取值的次数
        acceleration = 1.4, --重力加速度G的倍数,只有大于此值的加速计值,才会参与摇晃判定的运算
        minInterval = 0.25, --执行摇晃判定的最小时间间隔,单位是秒
        maxInterval = 0.5, --执行摇晃判定的最大时间间隔,单位是秒
        samplePercent = 0.75 --采样的百分比,建议维持使用缺省值
        }
返回值 无

支持平台 不支持win32,调用接口无效
Sensor.hasStepCounter()
功能说明 检测系统是否支持计步器

返回值 boolean ,有计步器则为 true

支持平台 不支持win32,调用接口返回 false 另外,pad设备一般没有计步器
Sensor.setStepCounterEvent(function)
功能说明 启用系统计步器

function 函数声明为:
onStepCounterEvent=function(num)
        --num是自启用计步器起的步数, num的值具有不确定性

end
function 取值为 nil 则会取消系统计步器

返回值 无

支持平台 不支持win32,调用接口无效

Clipboard(剪贴板)¶

简介

提供复制、粘贴等功能,可以与其他程序共享数据
API列表
Clipboard.setString(str)
功能说明 向剪贴板里写入字符串,相当于copy

str 类型为 string

返回值 无
Clipboard.getString()
功能说明 从剪贴板里获取字符串,相当于paste

返回值 返回类型为 string

PopupLogger(弹出式日志窗口)¶

简介

当手机脱离了台式机时,若想要看到一些信息,可以将日志输出到这里.
API列表
PopupLogger.show(enable)
功能说明 显示或隐藏日志窗口

enable 类型为 boolean

返回值 无

线程支持 支持在任意线程中调用
PopupLogger.clear()
功能说明 清空日志窗口中的日志内容

返回值 无

线程支持 支持在任意线程中调用
PopupLogger.logi( msg );
PopupLogger.logw( msg );
PopupLogger.logd( msg );
PopupLogger.loge( msg );
功能说明 用不同的颜色写日志

msg 类型为 string 日志内容

返回值 无

线程支持 支持在任意线程中调用

支持平台 win32平台不支持多种颜色

AudioRecorder(录音)¶

简介

提供实时流式录音功能.

详细说明请参考: http://stackoverflow.oa.com/article/26
API列表
AudioRecorder.getSupportFormat()
功能说明 获取当前设备支持的录音格式

返回值 类型为 array ,数组中包含多个 table ,每个的格式如下:
params[1] = { sampleRate=44100, channels=1,bitsPerSample=16,minBufferSize=1024 };

sampleRate是采样频率,单位是赫兹;channels是声道数;bitsPerSample是位数;minBufferSize是最小缓冲区大小,单位为字节;
支持8位/16位采样,采样值是8位/16位带符号整数.
线程支持 支持在任意线程中调用

权限 Permissions.RECORD_AUDIO
AudioRecorder.rawStart(param)
功能说明 用指定数据格式,开始录音

param 类型为 table 是用getSupportFormat函数取得,其中只有minBufferSize允许修改,且只能乘以2的N次方

返回值 类型为 boolean ,成功为 true

线程支持 支持在任意线程中调用

权限 Permissions.RECORD_AUDIO
AudioRecorder.rawPause()
功能说明 暂停

返回值 无

线程支持 支持在任意线程中调用

支持版本 4.0以上

权限 Permissions.RECORD_AUDIO
AudioRecorder.rawIsPause();
功能说明 返回是否处于暂停状态

返回值 类型为 boolean

线程支持 支持在任意线程中调用

支持版本 4.0以上

权限 Permissions.RECORD_AUDIO
AudioRecorder.rawResume()
功能说明 恢复

返回值 无

线程支持 支持在任意线程中调用

支持版本 4.0以上

权限 Permissions.RECORD_AUDIO
AudioRecorder.rawRead()
功能说明 同步读取录音数据,会读取minBufferSize大小的数据流并返回,也可能返回 nil 或长度小于minBufferSize. rawRead返回的是录音设备提供的未经处理的数据流,应用层需要考虑消除噪音、回响等.如果在rawStart时设置的minBufferSize过大,那么系统录音设备会录制很久才能填满minBufferSize,会导致rawRead阻塞很久,流式语音就会产生较大延迟.如果CPU处理不及时,也会导致延迟.

返回值 类型为 binary

线程支持 支持在任意线程中调用

权限 Permissions.RECORD_AUDIO
AudioRecorder.rawStop()
功能说明 停止录音

返回值 无

线程支持 支持在任意线程中调用

权限 Permissions.RECORD_AUDIO
AudioRecorder.rawIsStop()
功能说明 返回是否处于停止状态

返回值 类型为 boolean

线程支持 支持在任意线程中调用

权限 Permissions.RECORD_AUDIO