XXTouch OpenAPI 文档

XXTouch

Windows 平台按 Ctrl + F 可以输入文字搜索

Mac 平台按 command + F 可以输入文字搜索

电脑端示例源码

• XXT局域网控制器简易示例[aardio版]-0.0.0.56.zip-32.8kB

• 注：aardio 是一款 Windows 端的快速开发工具

开始之前

• 打开远程服务
  首先，如果是做电脑端，需要从设备端打开远程服务
  具体的步骤是：打开应用 --> 更多 --> 远程服务 --> 打开
  这里有图文：使用手册
• 远程服务的协议 HTTP/1.1
• 远程服务默认端口 46952
• 如果没做特殊说明
  接口文本参数都应该用 UTF-8 编码
  接口文本返回值是 UTF-8 编码的文本
  接口返回的 HTTP 状态码为 200
  没有打开远程服务所有接口统一返回的 HTTP 状态码为 400

文件相关

获取文件列表

• 接口描述

  POST /file_list HTTP/1.1
  {"directory":"/lua/scripts/"}

• 可能的返回

  {
      "code":0,
      "message":"操作成功",
      "data":{
          "list":[
              {
                  "name":"文件名",
                  "change":1446566100,
                  "size":144,
                  "access":1442128726,
                  "gid":20,
                  "blksize":4096,
                  "uid":0,
                  "rdev":0,
                  "blocks":8,
                  "nlink":1,
                  "permissions":"rw-r--r--",
                  "mode":"file",
                  "dev":16777219,
                  "ino":4887321,
                  "modification":1443063784
              },
              {
                  "name":"文件夹名",
                  "change":1464135126,
                  "size":102,
                  "access":1464135114,
                  "gid":20,
                  "blksize":4096,
                  "uid":0,
                  "rdev":0,
                  "blocks":0,
                  "nlink":2,
                  "permissions":"rwxr-xr-x",
                  "mode":"directory",
                  "dev":16777219,
                  "ino":9407305,
                  "modification":1464135126
              },
              ...
          ]
      }
  }

• 电脑端获取脚本列表示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/file_list", json.dumps({
      "directory" : "/lua/scripts/"
  }))
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      if ret['code']==0:
          for finfo in ret['data']['list']:
              if finfo['name']!='.' and finfo['name']!='..':
                  print(finfo['name'])
      else:
          print ret['message']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/
  • 开源脚本模块存放目录为 /var/mobile/Media/1ferver/lua/
  • 脚本存放目录为 /var/mobile/Media/1ferver/lua/scripts/
  • 插件存放目录为 /var/mobile/Media/1ferver/lib/
  • 资源存放目录为 /var/mobile/Media/1ferver/res/
  • 日志存放目录为 /var/mobile/Media/1ferver/log/
  • UI配置存放目录为 /var/mobile/Media/1ferver/uicfg/
  • 文字识别字库存放目录为 /var/mobile/Media/1ferver/tessdata/

选择一个脚本文件

• 接口描述

  POST /select_script_file HTTP/1.1
  {"filename":"文件名"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"操作失败"}

  {"code":4,"message":"无法读取文件"}

  {"code":8,"message":"参数错误"}

• 电脑端选择脚本列表示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/select_script_file", json.dumps({
      "filename" : "123.lua"
  }))
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/lua/scripts/

获取当前已经选择的脚本文件

• 接口描述

  POST /get_selected_script_file HTTP/1.1

• 可能的返回

  {
      "code":0,
      "message":"操作成功",
      "data":{
          "filename":"当前选择的文件名"
      }
  }

• 电脑端选择脚本示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/get_selected_script_file", '')
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
      if ret['code'] == 0:
          print ret['data']['filename']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/lua/scripts/

运行已经选择的脚本

• 接口描述

  POST /launch_script_file HTTP/1.1

• 可能的返回

  {"code":0,"message":"脚本运行开始"}

  {"code":1,"message":"操作失败"}

  {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}

  {"code":3,"message":"已有脚本正在运行中"}

  {"code":4,"message":"无法读取文件"}

  {"code":8,"message":"参数错误"}

  {"code":9,"message":"脚本已损坏"}

  {"code":10,"message":"软件需要更新方能支持使用这个脚本"}

• 电脑端获取已经选择脚本示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/launch_script_file", '')
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

删除一个脚本文件

• 接口描述

  POST /remove_script_file HTTP/1.1
  {"filename":"文件名"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":4,"message":"无法读取文件"}

  {"code":8,"message":"参数错误"}

• 说明
  
  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/lua/scripts/

新建一个脚本文件

• 接口描述

  POST /new_script_file HTTP/1.1
  {"filename":"文件名", "data":"文件内容"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":4,"message":"无法写入文件"}、{"code":11,"message":"文件或目录已存在"}

  {"code":8,"message":"参数错误"}

• 电脑端新建一个脚本文件示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json, base64
  luaf = open('r:/123.lua', 'r') # 脚本文件路径
  luatext = luaf.read()
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/new_script_file", json.dumps({
      "filename":"123.lua",
      "data":base64.b64encode(luatext)
  }))
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/lua/scripts/
  • 如果脚本是二进制数据比如加密的脚本，则需要将脚本内容使用 base64 算法编码

写入内容到脚本文件

• 接口描述

  POST /write_script_file HTTP/1.1
  {"filename":"文件名", "data":"文件内容"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":4,"message":"无法写入文件"}

  {"code":8,"message":"参数错误"}

• 电脑端写入内容到脚本文件示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json, base64
  luaf = open('r:/123.lua', 'r') # 脚本文件路径
  luatext = luaf.read()
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/write_script_file", json.dumps({
      "filename":"123.lua",
      "data":base64.b64encode(luatext)
  }))
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/lua/scripts/
  • 如果脚本是二进制数据比如加密的脚本，则需要将脚本内容使用 base64 算法编码
  • 如果文件不存在，则会创建文件

新建一个目录

• 接口描述

  POST /mkdir HTTP/1.1
  {"directory":"目录名"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"操作失败","detail":详细的错误信息}

  {"code":8,"message":"参数错误"}

• 说明
  
  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/

删除一个目录

• 接口描述

  POST /rmdir HTTP/1.1
  {"directory":"目录名"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":8,"message":"参数错误"}

• 说明
  
  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/
  • 这个函数无条件删除目录，不会管目录是不是空的

读取脚本文件

• 接口描述

  POST /read_script_file HTTP/1.1
  {"filename":"文件名"}

• 可能的返回

  {"code":0,"message":"操作成功","data":"脚本内容"}

  {"code":4,"message":"无法读取文件"}、{"code":4,"message":"加密脚本无法编辑"}

  {"code":8,"message":"参数错误"}

• 电脑端从设备读取脚本文件示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json, base64
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/read_script_file", json.dumps({
      "filename":"123.lua"
  }))
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
      if ret['code'] == 0:
          print ret['data']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/lua/scripts/

重命名一个文件或目录（RAW）

• 接口描述

  POST /rename_file HTTP/1.1
  {"filename":"文件名","newfilename":"新文件名"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"操作失败","detail":具体的错误信息}

  {"code":4,"message":"文件或目录不存在"}

  {"code":11,"message":"文件或目录已存在"}

  {"code":8,"message":"参数错误"}

• 说明
  
  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/

删除一个文件或空目录（RAW）

• 接口描述

  POST /remove_file HTTP/1.1
  {"filename":"文件名"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"操作失败","detail":具体的错误信息}

  {"code":4,"message":"文件或目录不存在"}

  {"code":8,"message":"参数错误"}

• 说明
  
  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/

读取一个文件（RAW）

• 接口描述

  POST /read_file HTTP/1.1
  {"filename":"文件名"}

• 可能的返回

  {"code":0,"message":"操作成功","data":"文件内容的 base64 编码字符串"}

  {"code":4,"message":"无法读取文件"}

  {"code":8,"message":"参数错误"}

• 电脑端从设备读取脚本文件示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json, base64
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/read_file", json.dumps({
      "filename":"lua/scripts/123.lua"
  }))
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
      if ret['code'] == 0:
          print base64.b64decode(ret['data'])
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/

写入一个文件（RAW）

• 接口描述

  POST /write_file HTTP/1.1
  {"filename":"文件名","data":"内容的 base64 编码字符串"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":4,"message":"无法写入文件"}

• 电脑端写入内容到脚本文件示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json, base64
  luaf = open('r:/123.lua', 'r') # 脚本文件路径
  luatext = luaf.read()
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/write_file", json.dumps({
      "filename":"lua/scripts/123.lua",
      "data":base64.b64encode(luatext)
  }))
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/

跳转下载一个文件

• 接口描述

  GET /download_file?filename=[UTF8-URIEncoded 文件的路径]

• 可能的返回
  200

  [文件二进制内容]

  400

  {"code":4,"message":"文件或目录不存在"}

• 说明
  
  • 这个接口在 1.1.2-6 版以上方可使用
  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/
  • 该接口支持绝对路径，路径第一个字符是 / 则判定为绝对路径

状态相关

对明文脚本内容进行语法检测

• 接口描述

  POST /check_syntax HTTP/1.1
  明文脚本内容

• 可能的返回

  {"code":0,"message":"语法检测已通过"}

  {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}

获得脚本运行状态

• 接口描述

  POST /is_running HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"} // 代表没有脚本在运行也没有在录制

  {"code":3,"message":"已经有脚本正在运行中"}

  {"code":9,"message":"当前正在录制"}

获得前台应用画面旋转方向

• 接口描述

  POST /device_front_orien HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功","data":{"orien":0~4}} // 0 为 home 在下; 1 为 home 在右; 2 为 home 在左; 3 为 home 在上; 4 未知

设置相关

获取录制设置

• 接口描述

  POST /get_record_conf HTTP/1.1

• 可能的返回

  {
      "code":0,
      "message":"操作成功",
      "data":{
          "record_volume_up":true|false,  // 录制是否也包括音量上键
          "record_volume_down":true|false // 录制是否也包括音量下键
      }
  }

录制设置开关

• 接口描述

  设置录制包含音量加键

  POST /set_record_volume_up_on HTTP/1.1

  设置录制不包含音量加键

  POST /set_record_volume_up_off HTTP/1.1

  设置录制包含音量减键

  POST /set_record_volume_down_on HTTP/1.1

  设置录制不包含音量减键

  POST /set_record_volume_down_off HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

获取音量键事件设置

• 接口描述

  POST /get_volume_action_conf HTTP/1.1

• 可能的返回

  {
      "code":0,
      "message":"操作成功",
      "data":{
          "hold_volume_up":"0"|"1"|"2", // 0 代表 “脚本启/停（有弹窗）”、1 代表 “脚本启/停”、2 代表 “无动作”；下同
          "hold_volume_down":"0"|"1"|"2",
          "click_volume_up":"0"|"1"|"2",
          "click_volume_down":"0"|"1"|"2",
          "activator_installed":true|false, // 是否安装了 Activator，如果安装了 Activator 则这里设置不生效
      }
  }

音量键事件设置开关

• 接口描述

  设置长按音量加键的动作

  POST /set_hold_volume_up_action HTTP/1.1
  0|1|2

  设置长按音量减键的动作

  POST /set_hold_volume_down_action HTTP/1.1
  0|1|2

  设置按一下音量加键的动作

  POST /set_click_volume_up_action HTTP/1.1
  0|1|2

  设置按一下音量减键的动作

  POST /set_click_volume_down_action HTTP/1.1
  0|1|2

• 可能的返回

  {"code":0,"message":"操作成功"}

获取开机启动设置

• 接口描述

  POST /get_startup_conf HTTP/1.1

• 可能的返回

  {
      "code":0,
      "message":"操作成功",
      "data":{
          "startup_run":true|false,          // true - 已启用开机启动；false - 未启用开机启动
          "startup_script":"开机启动的脚本名"
      }
  }

  {"code":5,"message":"配置文件有误"}

开机启动设置开关

• 接口描述

  启用开机启动

  POST /set_startup_run_on HTTP/1.1

  禁用开机启动

  POST /set_startup_run_off HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"脚本运行的过程中无法做出该操作"}

选择开机启动脚本

• 接口描述

  POST /select_startup_script_file HTTP/1.1
  {"filename":"文件名"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"脚本运行的过程中无法做出该操作"}

获得用户偏好配置

• 接口描述

  POST /get_user_conf HTTP/1.1

• 可能的返回

  {
      "code":0,
      "message":"操作成功",
      "data":{
          "no_nosim_alert":true|false,     // “无 SIM 卡” 弹窗设置，true 为不弹，默认 false
          "no_low_power_alert":true|false, // “低电量” 弹窗设置，true 为不弹，默认 false
          "no_idle":true|false,
          // 失眠模式，true 为不休眠，默认 false （该设置只在远程开启的情况下生效）
          "script_on_daemon":true|false,
          // 守护模式，true 为服务非正常死亡复活会启动最后正在运行的脚本，默认 false
          "script_end_hint":true|false,    // 脚本停止提示文字开关，true 为提示，默认为 false
      }
  }

• 说明
  
  • no_idle、script_on_daemon 字段在 1.0.3-3 以上版本方可使用
  • script_end_hint 字段在 1.0.5-1 以上版本方可使用

设置用户偏好配置

• 接口描述

  POST /set_user_conf HTTP/1.1
  {
      "no_nosim_alert":true|false,     // “无 SIM 卡” 弹窗设置，true 为不弹，默认 false
      "no_low_power_alert":true|false, // “低电量” 弹窗设置，true 为不弹，默认 false
      "no_idle":true|false,
      // 失眠模式，true 为不休眠，默认 false （该设置只在远程开启的情况下生效）
      "script_on_daemon":true|false,
      // 守护模式，true 为服务非正常死亡复活会启动最后正在运行的脚本，默认 false，无法在脚本运行的过程中打开此开关
      "script_end_hint":true|false,    // 脚本停止提示文字开关，true 为提示，默认为 false
  }

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"脚本运行的过程中无法做出该操作"}

  {"code":8,"message":"参数错误"}

• 说明

  • 这个接口在 1.0.3-3 版以上方可使用
  • script_end_hint 字段在 1.0.5-1 以上版本方可使用

禁弹出 “无 SIM 卡” 弹窗开关

• 接口描述

  禁止 “无 SIM 卡” 弹窗弹出

  POST /set_no_nosim_alert_on HTTP/1.1

  不禁止 “无 SIM 卡” 弹窗弹出

  POST /set_no_nosim_alert_off HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

• 说明
  
  • 在 1.0.4-1 版以上支持 iOS9

禁弹出 “低电量” 弹窗开关

• 接口描述

  禁止 “低电量” 弹窗弹出

  POST /set_no_low_power_alert_on HTTP/1.1

  不禁止 “低电量” 弹窗弹出

  POST /set_no_low_power_alert_off HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

禁弹出 “使用推送通知来连接 iTunes” 弹窗开关

• 接口描述

  禁止 “使用推送通知来连接 iTunes” 弹窗弹出

  POST /set_no_need_pushid_alert_on HTTP/1.1

  不禁止 “使用推送通知来连接 iTunes” 弹窗弹出

  POST /set_no_need_pushid_alert_off HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

设置设备名

• 接口描述

  POST /set_device_name HTTP/1.1
  {"name":"设备名"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":8,"message":"参数错误"}

设置设备的屏幕背光度

• 接口描述

  POST /set_brightness HTTP/1.1
  {"level":范围0.0~1.0}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":8,"message":"参数错误"}

• 说明
  
  • 这个接口在 1.0.2-1 版以上方可使用

设置设备全局音量

• 接口描述

  POST /set_volume HTTP/1.1
  {"level":范围0.0~1.0}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":8,"message":"参数错误"}

• 说明
  
  • 这个接口在 1.0.2-1 版以上方可使用

系统相关

获取设备已安装应用程序信息

• 接口描述

  POST /applist HTTP/1.1
  {"no_icon": true|false}

• 可能的返回

  {
      "code":0,
      "message":"操作成功",
      "data":[
          {
              "bid":"com.xxx.xxx.1",
              "name":"应用本地化名字",
              "bundle_path":"应用包路径",
              "data_path":"应用数据路径",
              "icon":"应用程序图标数据（base64 编码）"
          },
          {
              "bid":"com.xxx.xxx.2",
              "name":"应用本地化名字",
              "bundle_path":"应用包路径",
              "data_path":"应用数据路径",
              "icon":"应用程序图标数据（base64 编码）"
          },
          ...
      ]
  }

  {"code":8,"message":"参数错误"}

• 说明

  • no_icon 参数可选，在 1.1.3-1 版以上方可使用，用于获取除 icon 数据以外所有的信息

获取设备信息

• 接口描述

  POST /deviceinfo HTTP/1.1

• 可能的返回

  {
      "code":0,
      "message":"操作成功",
      "data":{
          "devsn":"XXXXXXXXXXXX",                                // 设备序列号
          "zeversion":"0.0.1.733",                               // 服务程序版本
          "sysversion":"7.1.2",                                  // 系统版本
          "devname":"蛤蛤蛤蛤",                                  // 设备名
          "devmac":"10:11:12:13:14:15",                          // 设备 MAC 地址
          "deviceid":"1234567890123456789012345678901234567890", // 设备 UDID
          "devtype":"iPhone5,3",                                 // 设备类型
          "wifi_ip":"192.168.1.100",                             // WIFI IP 地址
          "ipaddr":"127.0.0.1",                                  // 当前访问的本机地址
          "port":46952                                           // 端口
      }
  }

锁定屏幕

• 接口描述

  POST /lock_screen HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

解锁屏幕

• 接口描述

  POST /unlock_screen HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

重启服务

• 接口描述

  POST /restart HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

注销设备

• 接口描述

  POST /respring HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

重启设备

• 接口描述

  POST /reboot2 HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

关机

• 接口描述

  POST /halt HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

清理 UI 缓存

• 接口描述

  POST /uicache HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

清理 GPS 伪装信息

• 接口描述

  POST /clear_gps HTTP/1.1
  {"bid": "com.xxx.xxx"}

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":8,"message":"参数错误"}

• 说明

  • bid 参数可选，在 1.1.3-1 版以上方可使用，用于清除指定应用的 GPS 伪装信息

全清设备

• 接口描述

  POST /clear_all HTTP/1.1

• 可能的返回

  {"code":0,"message":"清理已经完成"}

清理应用程序存档

• 接口描述

  POST /clear_app_data HTTP/1.1
  {"bid":"应用包名"}

• 可能的返回

  {"code":0,"message":"清理已经完成"}

  {"code":1,"message":"操作失败"}

  {"code":8,"message":"参数错误"}

  {"code":11,"message":"这个应用程序的存档不能清理"}

• 说明

  • 这个接口在 1.0.3-2 版以上方可使用

导入一张照片到系统相册

• 接口描述

  POST /image_to_album HTTP/1.1
  [图像数据]

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"操作失败"}

• 电脑端导入图片到设备相册示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import httplib, json
  imgf = open('r:/1.png', 'rb') # 图片文件路径
  imgdata = imgf.read()
  conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
  conn.request("POST", "/image_to_album", imgdata)
  response = conn.getresponse()
  if response.status == 200:
      ret = json.loads(response.read())
      print ret['message']
  else:
      print response.status, response.reason
      print response.read()
  conn.close()

• 说明

  • 这个接口在 1.0.6-1 版以上方可使用
  • 支持的数据格式有 PNG、JPG

更新自己

• 接口描述

  POST /update_deb HTTP/1.1
  [deb 数据]

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"操作失败"}

• 说明
  
  • 这个接口不会返回安装结果
  • 返回操作成功只是上传成功了而已，安装是异步进行的
  • 这个接口或许还可以安装其它deb，不过不做保证

打开远程访问

• 接口描述

  POST /open_remote_access HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":1,"message":"操作失败"}

• 说明

  • 这个 API 只有设备本机可以调用

关闭远程访问

• 接口描述

  POST /close_remote_access HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

获取远程服务开启状态

• 接口描述

POST /is_remote_access_opened HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功","data":{"opened":true|false}}

• 说明

  • 这个 API 只有设备本机可以调用

加密脚本相关

加密一个设备上的脚本文件

• 接口描述

  POST /encript_file HTTP/1.1
  {
      "no_strip": true|false,             // 是否保留调试信息，默认 false，也就是不保留调试信息
      "in_file": "lua/scripts/xxx.lua",   // 输入文件名，可以为绝对路径
      "out_file": "lua/scripts/xxx.xxt",  // 输出文件名，可以为绝对路径
  }

• 可能的返回

  {"code":0,"message":"操作成功"}

  {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}

  {"code":4,"message":"文件或目录不存在"} // 输入文件无法被读取

  {"code":4,"message":"无法写入文件"}

  {"code":8,"message":"参数错误"}

  {"code":13,"message":"另外一项加密正在进行..."}

• 说明
  
  • 这个接口在 1.1.2-6 版以上方可使用
  • 该接口文件操作的根目录为 /var/mobile/Media/1ferver/

加密一段明文脚本

• 接口描述

  POST /encript HTTP/1.1
  args: {"no_strip":true|false}
  [脚本内容]

• 可能的返回

  • 成功返回状态码 200 并附带内容：

    [加密好的脚本内容]

  • 失败返回状态码 400 并附带内容：

    {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}

    {"code":13,"message":"另外一项加密正在进行..."}

• 说明
  
  • 这个接口在 1.1.2-6 版以上方可使用
  • args 参数说明：
    
    • no_strip 当这个参数为 true 的时候，则保留调试信息加密（也就是报错会有行信息）。默认为 false

加密一段明文脚本并返回下载 URI

• 接口描述

  POST /encript HTTP/1.1
  args: {"no_strip":true|false,"filename":"UTF8-URIEncoded 文件名"}
  [脚本内容]

• 可能的返回

  • 成功返回状态码 200 并附带内容：

    {
        "code":0,
        "message":"操作成功",
        "download_uri":"/download_encript", // 可以通过跳转到这个 URI 来下载加密好的文件
    }

  • 失败返回状态码 400 并附带内容：

    {"code":2,"message":"操作失败"}

    {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}

    {"code":13,"message":"另外一项加密正在进行..."}

• 说明

  • 这个接口在 1.1.2-6 版以上方可使用
  • args 参数说明：
    
    • no_strip 当这个参数为 true 的时候，则保留调试信息加密（也就是报错会有行信息）。默认为 false
    • filename 返回的 URI 跳转之后供下载的文件名，注意要 URIEncode 处理

授权相关

绑定一个授权码

• 接口描述

  POST /bind_code HTTP/1.1
  XXXXXXXXXXXXXXXX

• 可能的返回

  {"code":0,"message":"充值成功，新增授权时间 XX 天 XX 小时 XX 分钟"}       // 表示绑定成功

  {"code":1,"message":"操作失败"} // 连接服务器失败

  {"code":-1,"message":...}       // 其它任何非 0 值原因都用 message 描述

获得当前设备的授权信息

• 接口描述

  POST /device_auth_info HTTP/1.1

• 可能的返回

  {
      "code":0,
      "message":"ok",
      "data":{
          "nowDate":现在的时间戳,
          "expireDate":过期的时间戳 // 过期时间 - 现在时间 小于等于 0 的话，也是过期
      }
  }

  {"code":1,"message":"操作失败"}   // 连接服务器失败

  {"code":-1,"message":...}         // 其它任何非 0 值原因都用 message 描述

控制相关

UDP 扫描局域网的设备

• 首先需要在电脑上打开一个 UDP 收消息的端口

• 然后发送如下 UDP 广播内容到局域网的 46953 端口

  {"ip":"电脑端的ip地址","port":收消息的端口}

• 设备收到这个广播后会做出如下回复到电脑的收消息端口

  {
      "ip":"192.168.31.99",
      "port":"46952",
      "devname":"设备名",
      "deviceid":"123456789012345678901234567890123456790", // 设备 UDID
      "devsn":"XXXXXXXXXXXX",                               // 设备序列号
      "devmac":"02:03:04:05:06:07",                         // 设备 WiFi MAC 地址
      "devtype":"iPhone8,1",                                // 设备型号
      "zeversion":"0.0.1.738",                              // 服务版本
      "sysversion":"9.0.2"                                  // 系统版本
  }

• 电脑端 UDP 扫描局域网设备示例（适用于 Python 2.7.x）：

  # -*- coding: utf-8 -*-
  import socket, json  
  local_ip = '192.168.31.13' # 电脑端地址
  local_port = 31500
  local = (local_ip, local_port)
  remote = ("255.255.255.255", 46953)
  s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
  s.bind(local)
  s.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
  s.sendto(json.dumps({"ip":local_ip, "port": local_port}), remote)
  while True:
      data, addr = s.recvfrom(2048)
      if not data:
          print "client has exist"
          break
      print "received:", data, "from", addr
  s.close()

• 电脑端 UDP 扫描局域网设备示例（适用于 Node.js）：

  var http = require('http');         //HTTP服务
  var dgram = require('dgram');       //UDP模块
  var server_Port = 31500;            //服务端口
  var client_Port = 31501;            //发信端口
  var device_List = {};               //设备列表
  //创建收信服务
  var server_Socket = dgram.createSocket('udp4');
  server_Socket.on('message', function(msg, rinfo){
      console.log('收到消息：%s', msg);
      var device_Info = JSON.parse(msg)
      //过滤重复
      if(device_Info.deviceid){
          device_List[device_Info.deviceid] = device_Info;
      }
  });
  server_Socket.bind(server_Port);
  //创建发信服务
  var client_Socket = dgram.createSocket('udp4');
  client_Socket.bind(client_Port);
  var search = function(){
      var server_List = new Array();
      var os = require('os');
      var ifaces = os.networkInterfaces();
      for (var dev in ifaces) {
          var alias = 0;
          ifaces[dev].forEach(function(details){
              if (details.family=='IPv4') {
                  server_List.push(details.address);
                  ++alias;
              }
          });
      };
      for(var address in server_List) {
          var ip_ar = server_List[address].split(".");
          var send2ip = ip_ar[0] + "." + ip_ar[1] + "." + ip_ar[2] + ".255";
          var client_Socket = dgram.createSocket('udp4');
          var msg = JSON.stringify({ip: server_List[address], port: server_Port});
          client_Socket.send(msg, 0, msg.length, 46953, send2ip);
      };
  }
  http.createServer(function (request, response) {
      response.writeHead(200, {'Content-Type': 'application/json'});
      search()
      response.end(
          JSON.stringify(device_List)
      );
  }).listen(22222);
  search()
  console.log('Web服务地址：http://127.0.0.1:22222/');

远程启动脚本接口 (/spawn)

• 接口描述

  POST /spawn HTTP/1.1
  spawn_args: {"脚本启动参数":...}
  [脚本正文]

• 可能的返回

  {"code":1,"message":"操作失败"}

  {"code":2,"message":"脚本有语法错误","detail":"具体的错误信息"}

  {"code":3,"message":"已经有脚本正在运行中"}

  {"code":233,"message":"什么情况？"}

• 说明

  • [脚本启动参数] 是一个不包含换行符的可打印字符串
  • [脚本正文] 是脚本内容，可以是文本也可以是加密的二进制数据
  • 脚本端可以通过 proc_get 或是 proc_take 获取脚本启动参数
  • 脚本将不会作为文件存到设备上，只是会运行
  • 上一条的例外，设备启用 脚本守护模式 的情况下，设备会缓存与设备相关的脚本数据

• 示例

  • 例如可以构造如下请求发送到设备
    

    POST /spawn HTTP/1.1
    spawn_args: {"server_ip":"192.168.31.13","port":55555}
    Content-Length: 123
    local args = proc_get("spawn_args")
    args = json.decode(args)
    sys.alert("帐号服务器的 IP 为："..args.server_ip.."\n端口为："..args.port)

  • 例子的 Python 语言实现（适用于 Python 2.7.x）：
    

    # -*- coding: utf-8 -*-
    import httplib, json
    spawn_args = {
        "server_ip": "192.168.31.13", # 电脑端 IP 地址
        "port": 55555,                # 电脑端端口
    }
    data = r'''
    local args = proc_get("spawn_args")
    args = json.decode(args)
    sys.alert("帐号服务器的 IP 为："..args.server_ip.."\n端口为："..args.port)
    '''
    headers = {
        "Content-type": "text/lua",
        "spawn_args": json.dumps(spawn_args),
    }
    conn = httplib.HTTPConnection("192.168.31.72:46952") # 设备端地址及端口
    conn.request("POST", "/spawn", data, headers)
    response = conn.getresponse()
    print response.status, response.reason
    data = response.read()
    print data
    conn.close()

停止脚本接口 (/recycle)

• 接口描述

  POST /recycle HTTP/1.1

• 可能的返回

  {"code":0,"message":"脚本即将停止"}

• 说明

  • 这个接口返回之时不保证脚本已完全停止，可以通过 /is_running 接口检测

暂停脚本接口 (/pause_script)

• 接口描述

  POST /pause_script HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

• 说明

  • 会在任何可能让出或等待的时候中断脚本，强烈建议不要使用此 API
  • 重复调用不会有任何多余效果
  • 该 API 会在按音量键弹出选择的时候调用，如要使用注意避开冲突

继续脚本接口 (/resume_script)

• 接口描述

  POST /resume_script HTTP/1.1

• 可能的返回

  {"code":0,"message":"操作成功"}

• 说明

  • 使用暂停脚本后可以用此 API 恢复被暂停的脚本，强烈建议不要使用此 API
  • 重复调用不会有任何多余效果
  • 该 API 会在按音量键弹出选择被按取消的时候调用，如要使用注意避开冲突

远程截图接口 (/snapshot)

• 接口描述

  GET /snapshot?ext=[扩展名]&compress=[压缩率]&orient=[旋转方向]&zoom=[缩放比例]&left=[左]&top=[上]&right=[右]&bottom=[下] HTTP/1.1

• 可能的返回

  • 图片数据

• 说明

  • [扩展名] 可以是 png 或是 jpg
  • [压缩率] 范围 0~1，如果压缩率小于 1 则自动用 jpg 格式
  • [旋转方向] 范围 0~3；0 - 竖屏 home 在下；1 - 横屏 home 在右；2 - 横屏 home 在左；3 - 竖屏 home 在上
  • [缩放比例] 范围 0~3；默认 1；1.0.7-1 版以上有效
  • [左]、[上]、[右]、[下] 用于设定一个截图区域；区域无效则为全屏；1.0.7-1 版以上有效

设置进程词典条目的值 (/proc_put)

• 接口描述

  POST /proc_put HTTP/1.1
  {"key":"[键]","value":"[值]"}

• 可能的返回

  {"code":0,"message":"操作成功","key":"[键]","old_value":"[旧值]","value":"[新值]"}

  {"code":1,"message":"操作失败"}

• 说明

  • 存储一个以 [键] 为键，值为 [值] 的条目到设备正在运行的 XXTouch 服务进程中
  • [键] 用于提取值
  • [值] 一个字符串

• 示例代码
  例如可以构造如下请求发送到设备

  POST /proc_put HTTP/1.1
  Content-Length: 45
  {"key":"havonz","value":"苏泽是个好人"}

  然后设备的脚本中如果有如下代码

  sys.alert(proc_get("havonz"))

查看进程词典条目的值 (/proc_get)

• 接口描述

  POST /proc_get HTTP/1.1
  {"key":"[键]"}

• 可能的返回

  {"code":0,"key":"[键]","value":"[值]"}

  {"code":1,"message":"操作失败"}

• 说明

  • 查看一个设备正在运行的 XXTouch 服务进程中以 [键] 为键的条目的值
  • 当设备正在运行的 XXTouch 服务进程中以 [键] 为键的条目没有值的时候，返回失败

• 示例代码
  例如当设备的脚本中执行如下代码

  proc_put("taozi", "桃子是个好人")

  然后构造如下请求发送到设备

  POST /proc_get HTTP/1.1
  Content-Length: 15
  {"key":"taozi"}

  则会返回的数据如下

  {"code":0,"key":"taozi","value":"桃子是个好人"}

推入条目到进程词典队列 (/proc_queue_push)

• 接口描述

  POST /proc_queue_push HTTP/1.1
  {"key":"[键]","value":"[值]"}

• 可能的返回

  {"code":0,"message":"操作成功","size":词典队列中的现存的条目数}

• 说明

  • 压入一个以 [值] 为值的条目到键为 [键] 进程词典队列中
  • [键] 标识队列，用于从队列中提取值
  • [值] 一个字符串

从进程词典队列弹出条目 (/proc_queue_pop)

• 接口描述

  POST /proc_queue_pop HTTP/1.1
  {"key":"[键]"}

• 可能的返回

  {"code":0,"message":"操作成功","key":"[键]","value":"[值]"}

• 说明

  • 从进程词典队列中弹出一个值，如果队列为空，则会取出空字符串
  • [键] 标识队列，用于从队列中提取值

弹出进程词典队列所有条目 (/proc_queue_clear)

• 接口描述

  POST /proc_queue_clear HTTP/1.1
  {"key":"[键]"}

• 可能的返回

  {"code":0,"message":"操作成功","key":"[键]","values":["条目1", "条目2", ...]}

• 说明

  • 从进程词典队列弹出所有值
  • [键] 标识队列，用于从队列中提取值

扫一扫协议

授权码充值 (bind_code)

• 协议文本描述

  {
      "event":"bind_code",
      "code":"XXXXXXXXXXXXXXXX"
  }

• 说明

  • 将授权码以上述格式编码成二维码，XXTouch 的扫一扫就能识别并使用授权码

下载脚本 (down_script)

• 协议文本描述

  {
      "event":"down_script",
      "path":"需要保存的文件名.lua",
      "url":"下载地址"
  }

• 说明

  • 该协议在 1.0.0-1 版以上有效
  • 将合法的下载地址以上述格式编码成二维码，XXTouch 的扫一扫就能下载文件到脚本目录
  • 下载超时时间为 5 秒，应尽可能避免下载大型文件或是从极慢的服务器进行下载

• 示例二维码