定时任务

Cube App SDK 提供了基本的定时能力，支持设备定时和群组定时，设备可以是 Wi-Fi 设备、蓝牙 Mesh 子设备、Zigbee 子设备的。并封装了针对设备功能（DP）的定时器信息的增删改查接口。App 通过定时接口设置好定时器信息后，云模组会自动根据定时要求进行预订的操作。

功能说明

• 封装类：

  类	说明
  IThingCommonTimer	定时封装类

• 以下多个接口用到了 taskName 参数，具体可理解为一个分组，一个分组可以有多个定时器。每个定时属于或不属于一个分组，分组仅用于展示。例如：

  • 一个开关可能有多个功能，可以根据每个设备功能设置一个定时分组。

  • 每个分组可以添加多个定时器，用于控制这个设备功能各个时段的开启或关闭。

    每个定时任务下可以包含多个定时器。如下图所示：

    

版本说明

为了解决老接口存在的问题，本文描述的定时任务接口是从 3.18.0 SDK 版本新增的。

• 新版定时接口在 ThingHomeSdk.getTimerInstance() 中
• 旧版定时接口在 ThingHomeSdk.getTimerManagerInstance() 中

与旧版接口相比，新版接口有以下几点更新：

• 新增或更新定时器接口，可以设置定时器开关状态
• 提供批量修改定时器状态接口
• 修复旧版关闭定时分组失效问题
• 提供分组定时删除功能

增加定时任务

为设备或群组新增一个定时器，到指定的任务（task）下。每个设备或群组定时的上限为 30 个。

接口说明

void addTimer(ThingTimerBuilder builder, final IResultCallback callback);

参数说明

ThingTimerBuilder 及 IResultCallback 说明

参数	说明
taskName	定时分组名称
devId	设备 ID 或群组 ID
loops	循环次数，格式为 0000000，每一位数字的取值可以是 0：关闭 1：开启 从左至右依次表示周日、周一、周二、周三、周四、周五、周六。如每个周一循环该任务，则取值为 0100000。0000000 表示只执行一次，1111111 表示每天执行。
actions	设备功能（dps）的操作任务的 JSON 格式表达方式，格式为 {"dps":{}, "time":""}，其中 Raw 类型的 DP 需要转换格式，转换方式为：new String(Base64.encodeBase64(HexUtil.hexStringToBytes(dps)))
status	初始化定时器开关状态： 0：关闭 1：开启
appPush	是否支持定时执行结果推送
aliasName	设置定时备注名
TimerDeviceTypeEnum	枚举，定时类型： DEVICE：设备定时 GROUP：设备群组定时
callback	回调，返回成功或失败的结果，不能为 null

示例代码

ThingTimerBuilder builder = new ThingTimerBuilder.Builder()
        .taskName(mTaskName)
        .devId("efw9990wedsew")
        .deviceType(TimerDeviceTypeEnum.DEVICE)
        .actions(dps)
        .loops("1100011")
        .aliasName("Test")
        .status(1)
        .appPush(true)
        .build();
ThingHomeSdk.getTimerInstance().addTimer(builder, new IResultCallback() {
    @Override
    public void onSuccess() {
            }

    @Override
    public void onError(String errorCode, String errorMsg) {

    }
});

批量修改普通定时状态或删除定时器

接口说明

void updateTimerStatus(String devId, TimerDeviceTypeEnum deviceTimerTypeEnum, List<String> ids, TimerUpdateEnum timerUpdateEnum, final IResultCallback callback);

参数说明

参数	说明
devId	设备 ID 或群组 ID
TimerDeviceTypeEnum	枚举，定时类型： DEVICE：设备定时 GROUP：设备群组定时
ids	定时器 ID 列表
TimerUpdateEnum	枚举，操作类型： OPEN：开启定时器 CLOSE：关闭定时器 DELETE：删除定时器
callback	回调，主要包括发送成功或失败的回调，不能为 null

示例代码

List<String> list = new ArrayList<>();
list.add("111");
ThingHomeSdk.getTimerInstance().updateTimerStatus(mDevId, TimerDeviceTypeEnum.DEVICE, list, TimerUpdateEnum.DELETE, new IResultCallback() {
    @Override
    public void onError(String code, String error) {

    }

    @Override
    public void onSuccess() {

    }
});

修改定时任务的定时信息

接口说明

更新设备或群组下某个任务的定时器信息。

void updateTimer(ThingTimerBuilder builder, final IResultCallback callback);

参数说明

ThingTimerBuilder 及 IResultCallback 说明

参数	说明
taskName	定时分组名称
devId	设备 ID 或群组 ID
loops	循环次数，格式为 0000000，每一位数字的取值可以是 0：关闭 1：开启 从左至右依次表示周日、周一、周二、周三、周四、周五、周六。如每个周一循环该任务，则取值为 0100000。0000000 表示只执行一次，1111111 表示每天执行。
actions	设备功能（dps）的操作任务的 JSON 格式表达方式，格式为 {"dps":{}, "time":""}，其中 Raw 类型的 DP 需要转换格式，转换方式为：new String(Base64.encodeBase64(HexUtil.hexStringToBytes(dps)))
status	初始化定时器开关状态： 0：关闭 1：开启
appPush	是否支持定时执行结果推送
aliasName	设置定时备注名
TimerDeviceTypeEnum	枚举，定时类型： DEVICE：设备定时 GROUP：设备群组定时
callback	回调，返回成功或失败的结果，不能为 null

示例代码

ThingTimerBuilder builder = new ThingTimerBuilder.Builder()
    .timerId("1204923")
    .devId(groupId+"")
    .deviceType(TimerDeviceTypeEnum.GROUP)
    .actions(dps)
    .loops("0000000")
    .aliasName("test")
    .status(1)
    .appPush(true)
    .build();
ThingHomeSdk.getTimerInstance().updateTimer(builder, new IResultCallback() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(String errorCode, String errorMsg) {

    }
});

查询定时任务下所有定时任务

接口说明

查询设备或群组下某个任务的定时器。

void getTimerList(String taskName, String devId, TimerDeviceTypeEnum deviceTimerTypeEnum, final IThingDataCallback<TimerTask> callback);

参数说明

参数	说明
taskname	定时分组，可选，如果为空表示查询普通定时器列表
devId	设备 ID 或群组 ID
TimerDeviceTypeEnum	枚举，定时类型： DEVICE：设备定时 GROUP：设备群组定时
callback	回调，主要包括发送成功或失败的回调，不能为 null

回调参数 TimerTask 说明

参数	说明
TimerTaskStatus	定时器开关状态及名称
ArrayList	单个定时器列表
category	定时分组信息

示例代码

ThingHomeSdk.getTimerInstance().getTimerList(null, mGwId, TimerDeviceTypeEnum.DEVICE, new IThingDataCallback<TimerTask>() {
    @Override
    public void onSuccess(TimerTask timerTask){

    }

    @Override
    public void onError(String errorCode, String errorMessage){

    }
});

查询设备或群组下的定时任务

接口说明

查询设备或群组下所有的定时器，根据任务分类。

void getAllTimerList(String devId, TimerDeviceTypeEnum deviceTimerTypeEnum, final IThingDataCallback<List<TimerTask>> callback);

参数说明

参数	说明
devId	设备 ID 或群组 ID
TimerDeviceTypeEnum	枚举，定时类型： DEVICE：设备定时 GROUP：设备群组定时
callback	回调，主要包括发送成功或失败的回调，不能为 null

回调参数 TimerTask 说明

参数	说明
TimerTaskStatus	定时器开关状态及名称
ArrayList	单个定时器列表
category	定时分组信息

示例代码

ThingHomeSdk.getTimerInstance().getAllTimerList(mGwId, TimerDeviceTypeEnum.DEVICE, new IThingDataCallback<List<TimerTask>>() {
    @Override
    public void onSuccess(List<TimerTask> timerTaskList){

    }

    @Override
    public void onError(String errorCode, String errorMessage){

    }
});

修改分类下所有定时任务状态或删除定时器

接口说明

void updateCategoryTimerStatus(String taskName, String devId, TimerDeviceTypeEnum deviceTimerTypeEnum, TimerUpdateEnum timerUpdateEnum, IResultCallback callback);

参数说明

参数	说明
taskname	定时分组
devId	设备 ID 或群组 ID
TimerDeviceTypeEnum	枚举，定时类型： DEVICE：设备定时 GROUP：设备群组定时
TimerUpdateEnum	枚举，操作类型： OPEN：开启定时器 CLOSE：关闭定时器 DELETE：删除定时器
callback	回调，主要包括发送成功或失败的回调，不能为 null

示例代码

ThingHomeSdk.getTimerInstance().updateCategoryTimerStatus("test" ,"90sdjoi3dedj33", TimerDeviceTypeEnum.DEVICE, TimerUpdateEnum.CLOSE,new IResultCallback() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(String errorCode, String errorMsg) {

    }
});