微信Mars使用说明

Mars组件结构

github源码地址为https://github.com/Tencent/mars#mars_cn

使用前准备

将源码下载到本地，编译位于源码文件夹下的/mars/libraries/build_apple.py

python build_apple.py

编译成功得到

把 mars.framework 作为依赖加入到项目中，把和 mars.framework 同目录的后缀名为 rewriteme 的文件名删掉".rewriteme"和头文件一起加入到项目中,另外工程还需要导入的文件有:

在Mars源码文件夹下iOSDemo工程里还有需要导入的文件，包括:

使用

xlog组件

xlog组件为日志记录组件，使用时需要在main函数里初始化：

NSString* logPath = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0] stringByAppendingString:@"/log"];

// set do not backup for logpath
const char* attrName = "com.apple.MobileBackup";
u_int8_t attrValue = 1;
setxattr([logPath UTF8String], attrName, &attrValue, sizeof(attrValue), 0, 0);

// init xlog
#if DEBUG
xlogger_SetLevel(kLevelDebug);
appender_set_console_log(true);
#else
xlogger_SetLevel(kLevelInfo);
appender_set_console_log(false);
#endif
appender_open(kAppednerAsync, [logPath UTF8String], "Test");

在 applicationWillTerminate 函数中反初始化：

appender_close();

需要注意：

保存 log 的目录请使用单独的目录，不要存放任何其他文件防止被 xlog 自动清理功能误删。
请把 log 目录设上不备份的标识。
debug 版本下建议把控制台日志打开，日志级别设为 Debug, release 版本建议把控制台日志关闭，日志级别使用 Info.

stn组件

在 didFinishLaunchingWithOptions 函数中或者使用网络之前进行初始化：

[NetworkService sharedInstance].delegate = [[NetworkEvent alloc] init];
[[NetworkService sharedInstance] setCallBack];
[[NetworkService sharedInstance] createMars];
[[NetworkService sharedInstance] setClientVersion:200];
[[NetworkService sharedInstance] setLongLinkAddress:@"www.marsopen.cn" port:8081];
[[NetworkService sharedInstance] setShortLinkPort:8080];
[[NetworkService sharedInstance] reportEvent_OnForeground:YES];
[[NetworkService sharedInstance] makesureLongLinkConnect];
    
[[NetworkStatus sharedInstance] Start:[NetworkService sharedInstance]];

在程序退出时或需要释放 stn 时调用：

[[NetworkService sharedInstance] destroyMars];

当发生前后台切换时调用：

[[NetworkService sharedInstance] reportEvent_OnForeground:NO];
[[NetworkService sharedInstance] reportEvent_OnForeground:YES];

程序进入后台时选择NO，程序将要回到前台时选择YES。

消息发送

发送消息需要具体controller遵循代理UINotifyDelegate:

-(NSData*)requestSendData

该函数为将要发送的数据打包，demo中使用的数据格式为ProtocolBuffer，我们可以使用json数据格式。

-(int)onPostDecode:(NSData*)responseData

该函数为发送消息后接收到的服务器返回的消息数据解包。

-(int)onTaskEnd:(uint32_t)tid errType:(uint32_t)errtype errCode:(uint32_t)errcode

该函数为请求任务结束的回调，用于捕捉处理错误信息。

消息接收

接收消息需要具体controller遵循代理PushNotifyDelegate:

-(void)notifyPushMessage:(NSData*)pushData withCmdId:(int)cmdId

该函数为接收消息回调，解包数据后更新UI。

与服务端配合

首先来看官方的两个问题和答案：

如果我已经有现有服务器端了，客户端想使用 Mars，需要服务器做什么工作？

如果你已经深入了解了 Mars，感觉自己适合使用 Mars的，需要先理解长短连协议和加解包的区别。不论之前使用的哪种方式，长短连的协议是必须有的，你需要参照自定义扩展把长短连协议和服务器端对齐，至于加解包逻辑是在 Req2Buf 和 Buf2Resp 回调中做的，给上实现就可以了。关于长短连协议的理解和 req2Buf buf2Resp 的理解可以看一个例子：就像你用 HTTP 发一个 json 数据 HTTP 就类似 Mars 的长短连协议， json 的组装和解析就是 req2Buf 和 buf2Resp 来做的

如果我已经有现有服务器端了，客户端想使用 Mars，客户端需要注意什么？

longlink_packer.cc中的自定义需要注意。心跳包的cmdid一定要和服务器的对应上，否则可能发生心跳包超时导致长连断开。longlink_complexconnect_need_verify的含义是如果设为 true 经过心跳包验证的连接才认为是成功的连接。如果你的长连接建立连接后第一个包必须是验证包，该函数的返回值一定要设为false。长连的鉴权是会回调GetLonglinkIdentifyCheckBuffer这个函数，实现即可，记得处理回包：OnLonglinkIdentifyResponse,需要区分开长连接的鉴权和用户的登陆。长连的鉴权只是用来表示这个长连接是某个人的，不要用来做登陆功能。强调：需要注意，mars长连的请求包和回包的对应关系的条件是seq一样，所以服务器对请求的回应要保证seq一样，或者可以自己在longlink_taskmanger.cc里修改(不推荐)。

因此与服务端配合需要对齐长短连协议以及数据的加解包格式，后者在UINotifyDelegate、PushNotifyDelegate的回调中实现，而长短连协议的自定义在以下几个函数中实现：

void longlink_pack(uint32_t _cmdid, uint32_t _seq, const void* _raw, size_t _raw_len, AutoBuffer& _packed);
int  longlink_unpack(const AutoBuffer& _packed, uint32_t& _cmdid, uint32_t& _seq, size_t& _package_len, AutoBuffer& _body);
void shortlink_pack(const std::string& _url, const std::map<std::string, std::string>& _headers, const AutoBuffer& _body, AutoBuffer& _out_buff);

微信Mars使用说明