登录
目录
当前位置： 首页 > 文档资料 > Mars WIKI 中文文档 >

Mars Android 接口详细说明

优质
小牛编辑
134浏览
2023-12-01

接口说明(用作查询用，不建议在用 Mars 之前通读)

Xlog

Xlog.java
public static native void appenderOpen(Xlog.XLogConfig config);

struct XLogConfig{
    TAppenderMode mode_ = kAppednerAsync;
    std::string logdir_;
    std::string nameprefix_;
    std::string pub_key_;
    TCompressMode compress_mode_ = kZlib;
    int compress_level_ = 0;
    std::string cachedir_;
    int cache_days_ = 0;
};

初始化日志需要调用的接口。

level: 日志级别，变量见 Xlog.java 里 LEVEL_XX， Debug版本推荐 LEVEL_DEBUG， Release 版本推荐 LEVEL_INFO。

mode : 文件写入模式，分异步和同步，变量定义见 Xlog.java 里 AppednerModeXX， Release版本一定要用 AppednerModeAsync， Debug 版本两个都可以，但是使用 AppednerModeSync 可能会有卡顿。

cacheDir : 缓存目录，当 logDir 不可写时候会写进这个目录，可选项，不选用请给 ""， 如若要给，建议给应用的 /data/data/packname/files/log 目录。

logDir : 日志写入目录，请给单独的目录，除了日志文件不要把其他文件放入该目录，不然可能会被日志的自动清理功能清理掉。

nameprefix : 日志文件名的前缀，例如该值为TEST，生成的文件名为：TEST_20170102.xlog。

cacheDays : 一般情况下填0即可。非0表示会在 _cachedir 目录下存放几天的日志。

pubkey : 加密所用的 pub_key，具体可参考 Xlog 加密指引。

compressmode : 压缩模式，有 Zlib 和 Zstd 两种，默认使用Zlib。

compresslevel : 压缩级别，使用 Zstd 需要设置压缩级别，为1-9，数字越大，压缩率越高。

public static native void setConsoleLogOpen(boolean isOpen);

是否会把日志打印到 logcat 中， 默认不打印。

isOpen : true 为打印，false为不打印。

Log.java

该文件包含打印日志最常调用的接口。

public static void setLogImp(LogImp imp)

设置 Log 的具体实现，这里必须调用 Log.setLogImp(new Xlog()); 日志才会写到 Xlog 中。

public static void appenderFlush(boolean isSync)

当日志写入模式为异步时，调用该接口会把内存中的日志写入到文件。

isSync : true 为同步 flush，flush 结束后才会返回。 false 为异步 flush，不等待 flush 结束就返回。

public static void appenderClose()

关闭日志，在程序退出时调用。

public static void f/e/w/i/d(final String tag, final String msg)

写日志时调用的接口。

STN

BaseEvent.java

该文件主要包含基础事件改变时需要调用的接口。

public static native void onCreate();

初始化 Mars，一般在程序启动时或者使用 Mars 之前调用。

public static native void onDestroy();

释放 Mars，一般在程序退出时或者不再使用 Mars 之前调用。

public static native void onNetworkChange();

网络切换时调用，默认 BaseEvent 中已经监听相关事件，无需再调用。

public static native void onForeground(final boolean forground);

程序前后台改变时调用，必须调用，否则可能会出现网络连接频率没那么快的问题。

forground : true 为前台， false 为后台。

public static native void onSingalCrash(int sig);
public static native void onExceptionCrash();

因为有异常或 Crash 程序将要退出时调用，二选一，调用了两个中的一个后无需再调用onDestroy

sig : 触发 Crash 的信号量。

Mars.java
public static void init(Context _context, Handler _handler)

程序初始化时必须调用，必须在 onCreate 之前调用。

_context : 程序的 context， Mars 回调时使用。

_handler : Mars 回调时使用的 handler。

public static void onCreate(boolean isFirstStartup)

和BaseEvent.onCreate() 相同功能，不要和BaseEvent.onCreate()重复调用。

isFirstStartup : 是否首次进行 Mars create， 目前此变量无意义。

 public static void onDestroy()

和BaseEvent.onDestroy()相同功能，不要和BaseEvent.onDestroy() 重复调用。

StnLogic.java
Task
public int taskID;  // 任务唯一标识，会自动生成。
public int channelSelect;   // 任务走长连还是短连，或者两个都可以，可选值见 EShort。ELong EBoth
public int cmdID; // 长连的 cgi 命令号，用于标识长连请求的 cgi。长连必填项，相当于短连的 cgi。
public String cgi;    // 短连的 URI，短连必填项。
public ArrayList<String> shortLinkHostList;    //短连所用 host 或者 ip，如果是走短连的任务，必填项。

//optional
public boolean sendOnly; // true 为不需要等待回包，false 为需要等待回包。默认值为 false
public boolean needAuthed;    // true 为需要登陆态才能发送的任务，false 为任何状态下都可以发送的任务，默认值为 true。
public boolean limitFlow; // true 在手机网络情况下会走流量限制，false 不会。默认值为 true。大数据包请置为 false。
public boolean limitFrequency; // true 会走频率限制，false 不会。默认值为 true。 频繁发送相同包内容的 Task 请置为 false。

public int channelStrategy;     // channelSelect 为 EBoth 情况下，该值为 ENORMAL 长连存在则走长连，该值为 EFAST，即使长连存在，但是长连接队列里有别的任务的时候，会优先走短连接。默认值为 ENORMAL
public boolean networkStatusSensitive;    // true 没网络的情况下任务会直接返回失败，不会尝试去走网络，false 即使没网络，也会尝试建立连接。默认为 false。
public int priority;    // 任务的优先级，可选值见 ETASK_PRIORITY_XX。
public int retryCount = -1;    // 任务重试次数，设为-1，如果任务失败，会走 Mars 的重试逻。辑，设置大于等于0的数，会以此为准，默认值-1。
public int serverProcessCost;   //该 Task 等待SVR处理的最长时间,也即预计的SVR处理耗时。
public int totalTimeout;        // 该 Task 总的超时时间，设置小于等于零的值，会走 Mars 的超时逻辑，否则以此值为准，默认值为0。
public Object userContext;      // 用户变量，可填任何值，Mars 不会更改该变量。
public String reportArg;    // 统计上报所用，可忽略。

public static void setCallBack(ICallBack _callBack)

设置 STN 的回调接口。

boolean makesureAuthed(String host);

当 Task.needAuthed = true 时，会回调该接口询问是否是登陆态，如若是返回 true，如若不是返回 false，并触发上层做登陆的相关逻辑。 注意：该接口会短时间内重复被调用，不要频繁触发登陆逻辑，建议加上登陆请求之间的间隔。

host : 忽略此字段即可

String[] onNewDns(final String host);

要求上层做域名解析.上层可以实现自己的 DNS解析,或者自己实现的域名/IP映射。

return : IP 列表，可返回 null。

void onPush(final int cmdid, final byte[] data);

收到 SVR PUSH 下来的消息。

cmdid : push 下来的消息的命令号。

data : push 下来的数据。

boolean req2Buf(final int taskID, Object userContext, ByteArrayOutputStream reqBuffer, int[] errCode, int channelSelect, String host);

要求上层对 Task 组包

taskID : 任务 id。

userContext : 和 Task.userContext 值相同。

reqBuffer : 返回的组包好的数据。

errCode : 返回的组包的错误码，Mars 用作打日志，不会根据该值做相关逻辑。

channelSelect : 该 Task 所用的长连还是短连。

host : 忽略此字段即可

return : true 组包成功，false 组包失败。

int buf2Resp(final int taskID, Object userContext, final byte[] respBuffer, int[] errCode, int channelSelect);

要求上层对服务器的回包进行解包

taskID : 任务 id。

userContext : 和 Task.userContext 值相同。

respBuffer : 服务器返回的数据，待解的数据包。

errCode : 返回的解包的错误码，Mars 用作打日志，不会根据该值做相关逻辑。

channelSelect : 该 Task 所用的长连还是短连。

return : 值见 RESP_FAIL_XXX，解包成功返回RES_FAIL_HANDLE_NORMAL，session 超时返回RESP_FAIL_HANDLE_SESSION_TIMEOUT，解包失败并不再重试该任务返回RESP_FAIL_HANDLE_TASK_END，其他错误返回RESP_FAIL_HANDLE_DEFAULT。

int onTaskEnd(final int taskID, Object userContext, final int errType, final int errCode);

taskID : 任务 id。

userContext : 和 Task.userContext 值相同。

errType : buf2Resp 的返回值

errCode : 值和 buf2Resp 的 errCode 相同

return : 返回该 Task 的错误码，用作统计上报。

void reportConnectInfo(int status, int longlinkstatus);

Mars 的网络状态

status : 综合长短连下的网络状态，值见：

public static final int NETWORK_UNKNOWN = -1;
public static final int NETWORK_UNAVAILABLE = 0;
public static final int GATEWAY_FAILED = 1;
public static final int SERVER_FAILED = 2;
public static final int CONNECTTING = 3;
public static final int CONNECTED = 4;
public static final int SERVER_DOWN = 5;

longlinkstatus : 长连接的状态，值的范围和status相同。

int getLongLinkIdentifyCheckBuffer(ByteArrayOutputStream identifyReqBuf, ByteArrayOutputStream hashCodeBuffer, int[] reqCmdID);

要求上层生成长链接数据校验包,在长链接连接上之后使用,用于验证客户端身份和同步消息。

identifyReqBuf : 校验包数据内容。

hashCodeBuffer : 校验包的 hash。

reqCmdID : 数据校验的 cmd id，是用户自定义的值，需要上层设置,该数组长度为1，填reqCmdID。

return : ECHECK_NOW(需要校验), ECHECK_NEVER(不校验), ECHECK_NEXT(下一次再询问)。

 boolean onLongLinkIdentifyResp(final byte[] buffer, final byte[] hashCodeBuffer);

校验包的回包。

buffer : SVR 回复的连接校验包。

hashCodeBuffer : Client 请求的连接校验包的 hash 值。

return : 成功返回 true，失败返回 false。

void requestDoSync();

请求上层发起 sync 请求。

boolean isLogoned();

询问上层是否是登录态，即使不是登录态，也无需触发登陆逻辑。

String[] requestNetCheckShortLinkHosts();

返回用作网络检测的短连域名。

void reportTaskProfile(String taskString);

Task 的各项指标值。具体见TaskProfile.java

public static native void setLonglinkSvrAddr(final String host, final int[] ports, final String debugIP);
public static        void setLonglinkSvrAddr(final String host, final int[] ports) {setLonglinkSvrAddr(host, ports, null);}

设置长连的 host 和端口信息。

host : 长连接域名，可为 IP。

ports : 长连接端口。

debugIP : 长连接 debug IP

public static native void setShortlinkSvrAddr(final int port, final String debugIP);
public static        void setShortlinkSvrAddr(final int port) {setShortlinkSvrAddr(port, null);}

port : 短连接所用端口，建议 80。

debugIP : 短连接所用 debug IP。

public static native void setBackupIPs(final String host, final String[] ips);

设置 backup IP。

host : 需要设置的域名

ips : back IP。

public static native void setDebugIP(final String host, final String ip);

设置 Debug IP。

host : 需要设置的域名。

ip : 与 host 相对应的 debug IP。

public static native void startTask(final Task task);

新起一个任务。放到 Mars 中就立即返回。

public static native void stopTask(final int taskID);

停止一个正在做的任务。

public static native boolean hasTask(final int taskID);

询问 Mars 中是否已经有该 taskID 的任务。

public static native void redoTask();

重做所有长短连任务. 注意这个接口会重连长链接。

public static native void clearTask();

停止并清除所有未完成任务。

public static native void reset();

停止并清除所有未完成任务并重新初始化 STN。

public static native void makesureLongLinkConnected();

检测长链接状态。如果没有连接上，则会尝试重连。

public static native void setSignallingStrategy(long period, long keepTime);

信令保活策略设置。

period : 信令保活间隔,默认5 s。

keepTime : 信令保活时间,默认20 s。

public static native void keepSignalling();

开始信令保活。

public static native void stopSignalling();

停止信令保活。

public static native void setClientVersion(int clientVersion);

设置客户端版本，放入长连私有协议头部。

AppLogic.java

和应用有关的一些基本信息回调接口。

public static void setCallBack(ICallBack _callback)

设置 callback。

String getAppFilePath();

STN 会将配置文件进行存储，如连网IPPort策略、心跳策略等，此类信息将会被存储在客户端上层指定的目录下

AccountInfo getAccountInfo();

STN 会根据客户端是否有账号信息进行网络连接策略的动态调整，当用户没有账号信息时，网络会将连接的频率降低等，所以需要获取用户的帐号信息

int getClientVersion();

客户端版本号能够帮助 STN 清晰区分存储的网络策略配置文件。

DeviceInfo getDeviceType();

客户端通过获取设备类型，加入到不同的上报统计回调中，供客户端进行数据分析。

SDT

SdtLogic.java
public static void setCallBack(ICallBack _callBack)

设置 SDT 检测的回调接口。

public static native void setHttpNetcheckCGI(String requestURI);

设置一个 HTTP 连通状态探测的 URI。

private static void reportSignalDetectResults(String resultsJson)

返回 SDT 检测结果的 json 字符串。

免责声明： 以上内容版权归原作者所有，如有侵犯您的原创版权请告知，我们将尽快删除相关内容。感谢每一位辛勤著写的作者，感谢每一位的分享。
@小牛知识库 xnip.cn