update api

4.ratelAPI.md

@@ -17,7 +17,7 @@ ratelAPI是ratel给开发者提供的编程接口，类似太极一样，ratel
 除开基本xposed功能支持外，ratelAPI支持如下特性：
 
 
-### externalAPI
+## externalAPI
 
 标准的xposedAPI中，会依赖common-lang3，但是在实际导出的API中，common-lang3是被隐藏的。但是实际业务代码实践发现，我们还是需要一个基础的工具库的。
 所以我把common-lang3的依赖export到xposed api中了。另外，除开common-lang3，我还引入了common-io。
@@ -27,11 +27,11 @@ common-lang3 rename到external下。
 代码结构如下：
 ![4_1_api_categore](img/4_1_api_categore.png)
 
-可以看到api中，有``common-lang3``和``common-io``的身影。API对应规则则是，在左右package前面增加external前缀。
+可以看到api中，有``common-lang3``和``common-io``的身影。API对应规则则是，在原package前面增加external前缀。
 
 如：``org.apache.commons.lang3.StringUtils``可以用``external.org.apache.commons.lang3.StringUtils``替代
 
-### rposed
+## rposed
 
 常规xposed检测方案中，可以存在xposed堆栈检测，其实在ratel中，只要没有在callOrigin中有堆栈检测逻辑，xposed也是安全的。
 为了保证任何时候都可以pass xposed堆栈检测，ratel单独抽取了rposedAPI。
@@ -50,69 +50,95 @@ common-lang3 rename到external下。
 
 ratelAPI从1.1.0之后支持RPosed
 
-接口一览
+## RatelToolKit
+
+ratelToolKit是ratel提供的API的入口，他的全称限定名称为：``com.virjar.ratel.api.RatelToolKit``。RatelToolKit的各种成员变量在API引用中都是null，
+实际上在runtime里面会被ratel framework初始化，所以可以大胆的访问RatelToolKit里面的成员对象。成员解释如下：
+
+### RatelToolKit.sContext
+全局的一个context，context是调用Android系统功能的重要对象。有这个对象之后，无需手动通过拦截attach的方式获取context,其实在ActivityThread里面随时可以捞取Context，自己捞也可以。
+RatelFramework在运行过程中，已经进行了context的构造。另外考虑很多Xposed插件通过attachContext的方式作为模块逻辑起点，这个在某些xposedLike framework中可能存在一些不兼容问题。在ratel中则无须考虑这个问题，我们单独为这个功能做了兼容。
+
+### RatelToolKit.ratelConfig
+ratel框架的配置信息，代表了ratel编码、打包、运行过程产生的一些特定flag,这些flag会影响ratel framework的生命周期，一般情况下用户不需要关心这个接口，排除未来某些特定的framework hack场景。
+
+### RatelToolKit.ioRelocator
+这是一个读写重定向的接口，通过他可以改变整个经常的读写访问逻辑，主要用在设备指纹对抗方面，一般情况下，用户不必关心这个功能，除非你在ratel上面有非常深度的功能定制。需要注意的是，ioRelocator只能在ratelFramework启动完成之前调用，也就是``de.robv.android.xposed.IXposedHookLoadPackage#handleLoadPackage``之中，这涉及到ratel framework生命周期问题，详见"ratel framework lifecycle" TODO
+
+### RatelToolKit.processName
+当前进程名称
+
+### RatelToolKit.packageName
+当成packageName
+
+### RatelToolKit.ratelVersionName
+ratel engine版本号
+### RatelToolKit.ratelVersionCode
+ratel engine版本号，数字格式
+### RatelToolKit.whiteSdcardDirPath
+存储卡白名单地址，这个功能在虚拟化环境中使用，虚拟化环境下，sdcard将会被隔离，导致无法往sdcard写入数据。但是如果ratel模块期望通过sdcard和其他app交换数据，那么需要通过一个sdcard白名单进行放行。该路径规则为：  ``/sdcard/ratel_white_dir/packageName/``
+
+### RatelToolKit.virtualEnv
+
+这是ratel系统的虚拟化环境功能支持，在这个模块中，设备指纹和文件读写都会被隔离，如此实现一键新机或者一机多号。我们还提供API接口和虚拟化环境进行通信，以便对虚拟化环境做更深度的定制。
+
+#### VirtualEnvModel
+VirtualEnvModel代表ratel框架支持的集中虚拟化设备模式``com.virjar.ratel.api.VirtualEnv.VirtualEnvModel``，分别为：
+1. DISABLE：未启用虚拟环境
+2. START_UP：每次启动app切换设备数据
+3. INSTALL：app重新安装的时候切换设备数据，适合登录态+不会编程控制
+4. MULTI：多用户模式，这个模式比较特殊，将会放大用户。通过时间分割的方式实现多用户
+5. MANUAL：通过ratel api来控制设备信息切换，灵活的根据业务逻辑控制。比如发现设备被拉黑，主动控制设备切换
+
+一机多号功能基于MULTI实现，如果希望app每次打开都是新设备，那么可以制定模式为：START_UP
+
+#### com.virjar.ratel.api.VirtualEnv#getVirtualEnvModel
+查询当前设备虚拟环境，结果为枚举。包含系统ratel定义的几种模式
+
+#### com.virjar.ratel.api.VirtualEnv#switchEnv
+这个接口非常重要，通过这个接口实现设备切换，当然这个接口调用的前提是当前虚拟化模式为``MULTI``，switchEnv需要传入一个字符串作为参数，该参数代表设备id，如果userId不存在，那么重新创建。如果userId为控，那么ratel自动创建一个。userId需要满足JavaIdentify规则（数字、字母、下划线），不满足规则的字符将会被抹除。另外注意，本API只有在main进程中执行有效，所有环境操作只能由主进程执行，如果设备数据切换成功，那么将会导致app主动停止。需要被其他框架重新守护打开。
+如下代码，通过sdcard的一个文件控制当前设备
 ```
-package com.virjar.ratel.api;
-
-import android.annotation.SuppressLint;
-import android.content.Context;
-
-public class RatelToolKit {
-    /**
-     * 1。 以下对象，是暴露给调用方的额外API，可以通过他们操作ratel提供的额外功能（除开xposed本身功能之外）
-     */
-    //全局的一个context，context是调用Android系统功能的重要对象。有这个对象之后，无需手动通过拦截attach的方式获取context
-    @SuppressLint("StaticFieldLeak")
-    public static Context sContext = null;
-
-    /**
-     * ratel框架的配置信息，代表了ratel编码、打包、运行过程产生的一些特定flag
-     */
-    public static RatelConfig ratelConfig = null;
-
-    /**
-     * ratel支持对文件进行重定向
-     */
-    public static IORelocator ioRelocator = null;
-
-    /**
-     * 当前进程名称
-     */
-    public static String processName = null;
-
-    /**
-     * 当成packageName
-     */
-    public static String packageName = null;
-
-
-    /**
-     * 虚拟化环境功能支持
-     */
-    public static VirtualEnv virtualEnv = null;
-
-    /**
-     * 虚拟化环境下，sdcard将会被隔离，导致无法往sdcard写入数据。但是如果ratel模块期望通过sdcard和其他app交换数据，那么需要通过一个sdcard白名单进行放行
-     */
-    public static String whiteSdcardDirPath = null;
-    /**
-     * @hidden
-     */
-    public static RatalStartUpCallback ratalStartUpCallback = null;
-
-    public static void setOnRatelStartUpCallback(RatalStartUpCallback ratelStartUpCallback) {
-        RatelToolKit.ratalStartUpCallback = ratelStartUpCallback;
+    private static void switchUserBySdcardFile() {
+        String nowUser = RatelToolKit.virtualEnv.nowUser();
+
+        File file = new File(new File(RatelToolKit.whiteSdcardDirPath), "userId.txt");
+        if (file.exists()) {
+            try {
+                String userIdFromSdcard = FileUtils.readFileToString(file, StandardCharsets.UTF_8);
+                if (!StringUtils.equals(nowUser, userIdFromSdcard)) {
+                    RatelToolKit.virtualEnv.switchEnv(userIdFromSdcard);
+                }
+            } catch (IOException e) {
+                Log.i(tag, "failed to read id ctr file", e);
+            }
+        } else {
+            Log.i(tag, "multi user id control file not exist: " + file);
+        }
     }
+```
+如下代码，硬编码切换设备
+```
+private static void switchTo18782164555() {
+        RatelToolKit.virtualEnv.switchEnv("18782164555");
+    }
+```
 
+#### com.virjar.ratel.api.VirtualEnv#nowUser
+ 当前用户生效的用户，仅在MULTI模式下有效在，当前生效用户代表虚拟化设备ID
 
-    /**
-     * 2。 以下以下对象，是用户层不需要关心的。我也不会做解释
-     */
-    public static HookProvider usedHookProvider;
+#### com.virjar.ratel.api.VirtualEnv#removeUser
+删除某个用户。用户需要存在，并且不能删除nowUser
 
-    public static String TAG = null;
+#### com.virjar.ratel.api.VirtualEnv#availableUserSet
+系统可用的user集合，仅在multi模式下有效
 
+#### com.virjar.ratel.api.VirtualEnv#keepEnvForManualModel
+manual 模式下，需要手动控制是否切换设备，如果设置设备切换状态为true。那么设备信息永远不会切换。除非将标记从新设置为false。 keep标记默认为false
 
-}
+#### com.virjar.ratel.api.VirtualEnv#rawFingerData
+获取原始的可以作为唯一设备的指纹数据，虚拟化之后，我们拿到的imei之类的数据会变成假的。这是获取真实数据的一个后门。
 
-```
\ No newline at end of file
+### FingerPrintModel
+设备指纹填充接口，通过这个即可灌入模拟的设备数据，这个API接口使用蛮简单，就不多解释了。
+不过需要注意的是，自ratelAPI 1.2.1之后才支持这个功能