Mars iOS / OS X 接口详细说明

优质

小牛编辑

130浏览

2023-12-01

接口说明(用作查询用，不建议在用 Mars 之前通读。部分接口是函数指针，本文档简写成函数)

Xlog

appender.h

void appender_open(const 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;
};

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

mode_ : 文件写入模式，分异步和同步，变量定义见 appender.h 里 kAppednerXX， Release版本一定要用 kAppednerAsync， Debug 版本两个都可以，但是使用 kAppednerSync 可能会有卡顿。

cachedir : 缓存目录，当 \logdir 不可写时候会写进这个目录，可选项，不选用请给 ""， Apple 系平台建议给 ""。

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

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

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

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

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

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

appender_close();

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

void appender_flush();
void appender_flush_sync();

当日志写入模式为异步时，调用接口会把内存中的日志写入到文件。appender_flush_sync 为同步 flush，flush 结束后才会返回。 appender_flush 为异步 flush，不等待 flush 结束就返回。

void appender_set_console_log(bool _is_open);

是否会把日志打印到控制台中，默认不打印。

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

xloggerbase.h

void xlogger_SetLevel(TLogLevel _level);

设置日志级别，变量见 xloggerbase.h 里 TLogLevel 的枚举值， Debug版本推荐 kLevelDebug， Release 版本推荐 kLevelInfo。

xlogger.h

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

xverbose/xinfo/xdebug/xwran/xerror/xfatal/xassert...

写日志时调用的接口。

STN

base_logic.h

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

void OnCreate();

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

void OnDestroy();

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

void OnNetworkChange();

网络切换时调用。

void OnForeground(bool _isforeground);

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

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

void OnSingalCrash(int _sig);
void OnExceptionCrash();

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

_sig : 触发 Crash 的信号量。

stn.h

uint32_t       taskid; // 任务唯一标识，会自动生成。
uint32_t       cmdid;   // 长连的 cgi 命令号，用于标识长连请求的 cgi。长连必填项，相当于短连的 cgi。
int32_t        channel_select; // 任务走长连还是短连，或者两个都可以，可选值见 kChannelXXX
std::string    cgi;       // 短连的 URI，短连必填项。

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

bool        network_status_sensitive;  // true 没网络的情况下任务会直接返回失败，不会尝试去走网络，false 即使没网络，也会尝试建立连接。默认为 false。
int32_t     channel_strategy; // channel_select 为 kChannelBoth 情况下，该值为 kChannelNormalStrategy 长连存在则走长连，该值为 kChannelFastStrategy，即使长连存在，但是长连接队列里有别的任务的时候，会优先走短连接。默认值为 kChannelNormalStrategy
int32_t     priority;  // 任务的优先级，可选值见 kTaskPriorityXXX。

int32_t     retry_count;  // 任务重试次数，设为-1，如果任务失败，会走 Mars 的重试逻。辑，设置大于等于0的数，会以此为准，默认值-1。
int32_t     server_process_cost;  //该 Task 等待SVR处理的最长时间,也即预计的SVR处理耗时。
int32_t     total_timetout;  // 该 Task 总的超时时间，设置小于等于零的值，会走 Mars 的超时逻辑，否则以此值为准，默认值为0。

void*       user_context;  // 用户变量，可填任何值，Mars 不会更改该变量。
std::string report_arg;  // 统计上报所用，可忽略。

std::vector<std::string> shortlink_host_list; //短连所用 host 或者 ip，如果是走短连的任务，必填项。

stn_logic.h

void SetCallback(Callback* const callback);

设置 STN 的回调接口。

virtual bool MakesureAuthed(const std::string& _host) = 0;

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

host : 忽略此字段即可

virtual std::vector<std::string> OnNewDns(const std::string& host);

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

return : IP 列表，可返回 null。

virtual void OnPush(uint64_t _channel_id, uint32_t _cmdid, uint32_t _taskid, const AutoBuffer& _body, const AutoBuffer& _extend) = 0;

收到 SVR PUSH 下来的消息。

_channel_id : 通道 id, 可忽略
_cmdid : push 下来的消息的命令号。
_taskid : 任务 id, 暂时忽略 _body : push 下来的数据。
_extend : 扩展字段，暂时忽略

virtual bool Req2Buf(uint32_t _taskid, void* const _user_context, AutoBuffer& outbuffer, AutoBuffer& extend, int& error_code, const int channel_select, const std::string& host) = 0;

要求上层对 Task 组包。

_taskid : 任务 id。

_user_context : 和 Task.user_context 值相同。

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

extend : 扩展字段，暂时忽略

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

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

host : 忽略此字段即可

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

virtual int Buf2Resp(int32_t taskid, void* const user_context, const AutoBuffer& inbuffer, int& error_code, const int channel_select) = 0;

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

taskid : 任务 id。

user_context : 和 Task. user_context 值相同。

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

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

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

return : 值见 stn.h 中 kTaskFailHandleXXX，解包成功返回kTaskFailHandleNormal，session 超时返回kTaskFailHandleSessionTimeout，解包失败并不再重试该任务返回kTaskFailHandleTaskEnd，其他错误返回kTaskFailHandleDefault。

virtual int  OnTaskEnd(uint32_t _taskid, void* const _user_context, int _error_type, int _error_code) = 0;

_taskid : 任务 id。

_user_context : 和 Task.userContext 值相同。

_error_type : Buf2Resp 的返回值

_error_code : 值和 Buf2Resp 的 error_code 相同

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

virtual void ReportConnectStatus(int _status, int _longlink_status) = 0;

Mars 的网络状态

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

enum NetStatus {
    kNetworkUnkown = -1,
    kNetworkUnavailable = 0,
    kGateWayFailed = 1,
    kServerFailed = 2,
    kConnecting = 3,
    kConnected = 4,
    kServerDown = 5
};

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

virtual int  GetLonglinkIdentifyCheckBuffer(AutoBuffer& _identify_buffer, AutoBuffer& _buffer_hash, int32_t& _cmdid) = 0;

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

_identify_buffer : 校验包数据内容。

_buffer_hash : 校验包的 hash。

_cmdid : 数据校验的 cmd id。

return : kCheckNow(需要校验), kCheckNext(不校验), kCheckNever(下一次再询问)。

virtual bool OnLonglinkIdentifyResponse(const AutoBuffer& _response_buffer, const AutoBuffer& _identify_buffer_hash) = 0;

校验包的回包。

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

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

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

virtual void RequestSync() = 0;

请求上层发起 sync 请求。

virtual bool IsLogoned() = 0;

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

virtual void ReportFlow(int32_t wifi_recv, int32_t wifi_send, int32_t mobile_recv, int32_t mobile_send) = 0;
virtual void TrafficData(ssize_t _send, ssize_t _recv);

流量统计接口，两个接口功能类似。

void SetLonglinkSvrAddr(const std::string& host, const std::vector<uint16_t> ports, const std::string& debugip);
void SetLonglinkSvrAddr(const std::string& host, const std::vector<uint16_t> ports);

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

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

ports : 长连接端口。

debugip : 长连接 debug IP

void SetShortlinkSvrAddr(const uint16_t port, const std::string& debugip);

设置短连的端口信息。

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

debugip : 短连接所用 debug IP。

void SetBackupIPs(const std::string& host, const std::vector<std::string>& iplist);

设置 backup IP。

host : 需要设置的域名

iplist : back IP。

void SetDebugIP(const std::string& host, const std::string& ip);

设置 Debug IP。

host : 需要设置的域名。

ip : 与 host 相对应的 debug IP。

void StartTask(const Task& task);

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

void StopTask(int32_t taskid);

停止一个正在做的任务。

bool HasTask(int32_t taskid);

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

void RedoTasks();

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

void ClearTasks();

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

void Reset();

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

void MakesureLonglinkConnected();

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

void SetSignallingStrategy(long period, long keeptime);

信令保活策略设置。

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

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

void KeepSignalling();

开始信令保活。

void StopSignalling();

停止信令保活。

bool LongLinkIsConnected();

长连接是否已经连接上。

app_logic.h

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

void SetCallback(Callback* const callback);

设置 callback。

virtual std::string GetAppFilePath() = 0;

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

virtual AccountInfo GetAccountInfo() = 0;

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

virtual unsigned int GetClientVersion() = 0;

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

virtual DeviceInfo GetDeviceInfo() = 0;

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

SDT

sdt_logic.h

void SetCallBack(Callback* const callback);

设置 SDT 检测的回调接口。

void SetHttpNetcheckCGI(std::string cgi);

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