mobileIM
概述
mobileIM 封装了MobileIMSDK，MobileIMSDK是一套专为移动端开发的原创即时通讯框架：
- 超轻量级、高度提炼，lib包50KB以内；
- 完全基于UDP协议实现；
- 客户端支持iOS、Android、标准Java平台；
- 服务端提供Mina版和Netty版，方便研究和学习 new；
- 可与姊妹工程 MobileIMSDK-Web 无缝互通实现网页端聊天或推送等；
- 可应用于跨设备、跨网络的聊天APP、企业OA、消息推送等各种场景。
initMobile
初始化，android调用其他接口前需要先调用此接口，退出后再登陆前需要先调用此接口
initMobile({params})
params
appKey:
- 类型：字符串类型
- 描述：AppKey字符串
serverIp:
- 类型：字符串类型
- 描述：全局设置：服务端IP或域名。如需设置本参数，请在登陆前调用，否则将不起效。
serverPort:
- 类型：数字类型
- 描述：全局设置：服务端IP或域名。如需设置本参数，请在登陆前调用，否则将不起效。
mode:
- 类型：数字类型
- 描述：框架预设的敏感度模式，重要说明：客户端本模式的设定必须要与服务端的模式设制保持一致否则可能因参数的不一致而导致IM算法的不匹配，进而出现不可预知的问题。
- 取值范围：
- 0：KeepAlive心跳问隔为3秒，10秒后未收到服务端心跳反馈即认为连接已断开（相当于连续3 个心跳间隔后仍未收到服务端反馈）
- 1：KeepAlive心跳问隔为10秒，21秒后未收到服务端心跳反馈即认为连接已断开（相当于连续2 个心跳间隔后仍未收到服务端反馈）
- 2：KeepAlive心跳问隔为30秒，61秒后未收到服务端心跳反馈即认为连接已断开（相当于连续2 个心跳间隔后仍未收到服务端反馈）
- 3：KeepAlive心跳问隔为60秒，121秒后未收到服务端心跳反馈即认为连接已断开（相当于连续2 个心跳间隔后仍未收到服务端反馈）
- 4：KeepAlive心跳问隔为120秒，241秒后未收到服务端心跳反馈即认为连接已断开（相当于连续2 个心跳间隔后仍未收到服务端反馈）
示例代码
var mobileIM = api.require('mobileIM');
mobileIM.initMobile({
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
login
登陆
login({params}, callback(ret))
params
userId:
- 类型：字符串类型
- 描述：提交到服务端的准一id，保证唯一就可以通信，可能是登陆用户名、也可能是任意不重复的id等，具体意义由业务层决定
token:
- 类型：字符串类型
- 描述：提交到服务端用于身份鉴别和合法性检查的token，它可能是登陆密码，也可能是通过前置单点登陆接口拿到的token等，具体意义由业务层决定
extra:
- 类型：字符串类型
- 描述：（可选项）额外信息字符串。本字段目前为保留字段，供上层应用自行放置需要的内容
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
code:0 //数字类型；结果，0表示成功，否则返回的是错误码
}
示例代码
var mobileIM= api.require('mobileIM');
mobileIM.login({
},function(ret){
console.log(JSON.stringify(ret))
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
loginOut
退出登陆
loginOut(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
code:0 //数字类型；结果，0表示成功，否则返回的是错误码
}
示例代码
var mobileIM= api.require('mobileIM');
mobileIM.loginOut(function(ret){
console.log(JSON.stringify(ret))
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
sendKeepAlive
发送Keep Alive心跳包（仅iOS支持）
sendKeepAlive(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
code:0 //数字类型；结果，0表示成功，否则返回的是错误码
}
示例代码
var mobileIM= api.require('mobileIM');
mobileIM.sendKeepAlive(function(ret){
console.log(JSON.stringify(ret))
});
可用性
iOS系统
可提供的1.0.0及更高版本
sendCommonData
发送通用数据方法
sendCommonData({params}, callback(ret))
params
content:
- 类型：字符串类型
- 描述：要发送的数据内容
toUserId:
- 类型：字符串类型
- 描述：要发送到的目标用户id
qos:
- 类型：布尔类型
- 描述：（可选项）是否需要QoS机制支持（仅iOS支持，android固定为true）
- 默认：fasle
fp:
- 类型：字符串类型
- 描述：（可选项）QoS机制中要用到的指纹码（即消息包唯一id），genFingerPrint接口获取
typeu:
- 类型：数字类型
- 描述：（可选项）应用层专用字段——用于应用层存放聊天、推送等场景下的消息类型，不需要设置时请填-1即可）
- 默认：-1
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
code:0 //数字类型；结果，0表示成功，否则返回的是错误码
}
示例代码
var mobileIM= api.require('mobileIM');
mobileIM.sendCommonData({
},function(ret){
console.log(JSON.stringify(ret))
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
genFingerPrint
获取指纹特征码，目前使用的UUID基本能保证全局唯一，但它有36位长（加上分隔符32+4），目前为了保持框架的算法可读性暂时不进行优化，以后可考虑使用2进制方式或者Protobuffer实现(仅iOS支持)
genFingerPrint(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
fingerPrint:0 //数字类型；指纹特征码，指纹特征码实际上就是系统的当时时间戳
}
示例代码
var mobileIM= api.require('mobileIM');
mobileIM.genFingerPrint(function(ret){
console.log(JSON.stringify(ret))
});
可用性
iOS系统
可提供的1.0.0及更高版本
addAccountListener
账号事件的监听
addAccountListener(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
eventType: 'onLogin', //字符串类型；监听的事件类型，取值范围如下：
//onLogin：登陆结果（仅iOS支持，android在login接口返回）
//onLinkClose：与服务端的通信断开，该消息只有在客户端连接服务器成功之后网络异常中断之时触发。导致与与服务端的通信断开的原因有（但不限于）：无线网络信号不稳定、WiFi与2G/3G/4G等同开情况下的网络切换、手机系统的省电策略等
loginCode:0, //数字类型；服务端反馈的登录结果：0 表示登陆成功，否则为服务端自定义的出错代码（按照约定通常为>=1025的数）（仅iOS支持，android在login接口返回）
linkCloseCode:0 //数字类型；本回调参数表示表示连接断开的原因，目前错误码没有太多意义，仅作保留字段，目前通常为-1
}
示例代码
var mobileIM = api.require('mobileIM');
mobileIM.addAccountListener(function(ret) {
console.log(JSON.stringify(ret))
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
addMessageListener
消息事件的监听
addMessageListener(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
eventType: '', //字符串类型；监听的事件类型，取值范围如下：
//onTransBuffer：收到普通消息
//onError：服务端反馈的出错信息
//messagesLost：消息未送达
//messagesBeReceived：消息已被对方收到，目前，判定消息被对方收到是有两种可能，1：对方确实是在线并且实时收到了，2：对方不在线或者服务端转发过程中出错了，由服务端进行离线存储成功后的反馈（此种情况严格来讲不能算是“已被收到”，但对于应用层来说，离线存储了的消息。原则上就是已送达了的消息：因为用户下次登陆时肯定能通过HTTP协议取到）
code:0, //数字类型；错误码
msg:'', //字符串类型；错误信息
fingerPrintOfProtocal:'',//字符串类型；当该消息需要QoS支持时本回调参数为该消息的特征指纹码，否则为空
dwUserid:'', //字符串类型；消息的发送者id（RainbowCore框架中规定发送者id=“0”即表示是由服务端主动发过的，否则表示的是其它客户端发过来的消息）
dataContent:'', //字符串类型；消息内容
theFingerPrint:'', 字符串类型；已被收到的消息的指纹特征码（唯一ID），应用层可据此ID来找到原先已发生的消息并可在UI是将其标记为”已送达“或”已读“以便提升用户体验
typeu:0, //数字类型；应用层专用字段——用于应用层存放聊天、推送等场景下的消息类型，此值为-1时表示未定义。MobileIMSDK_X框架中，本字段为保留字段，不参与框架的核心算法，专留用应用层自行定义和使用
messages:[{ //json数组，消息内容
bridge:true, //布尔类型；是否来自跨服务器的消息，true表示是、否则不是。本字段是为跨服务器或集群准备的。
type:0, //数字类型；协议类型，本字段为框架专用字段，本字段的使用涉及IM核心层算法的表现，如无必要请避免应用层使用此字段。补充：理论上应用层不参与本字段的定义，可将其视为透明，如需定义应用层的消息类型，请使用 {@link typeu} 字段并配合dataContent一起使用
dataContent:'',//字符串类型；协议数据内容，本字段用于MobileIMSDK_X框架中时，可能会存放一些指令内容。当本字段用于应用层时，由用户自行定义和使用其内容
from:'', //字符串类型；消息发出方的id，为“-1”表示未设定、为“0”表示来自Server
to:'', //字符串类型；消息接收方的id，为“-1”表示未设定、为“0”表示发给Server
fp:'', //字符串类型；用于QoS消息包的质量保证时作为消息的指纹特征码（理论上全局唯一）
QoS:true, //布尔类型；是否需要进行QoS质量保证
typeu:'' //字符串类型；应用层专用字段——用于应用层存放聊天、推送等场景下的消息类型，此值为-1时表示未定义。MobileIMSDK_X框架中，本字段为保留字段，不参与框架的核心算法，专留用应用层自行定义和使用
}]
}
示例代码
var mobileIM = api.require('mobileIM');
mobileIM.addMessageListener(function(ret) {
console.log(JSON.stringify(ret))
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
错误码常量表
- 0：一切正常
- 1：客户端尚未登陆
- 2：未知错误
- 3：数据发送失败
- 4：无效的 {@link Protocal}对象
- 201：与服务端的连接已断开
- 202：与服务端的网络连接失败
- 203：客户端SDK尚未初始化
- 204：本地网络不可用（未打开）
- 205：要连接的服务端网络参数未设置
- 301：客户端尚未登陆，请重新登陆
协议类型
- 0：由客户端发出 - 协议类型：客户端登陆
- 1：由客户端发出 - 协议类型：心跳包
- 2：由客户端发出 - 协议类型：发送通用数据
- 3：由客户端发出 - 协议类型：客户端退出登陆
- 4：由客户端发出 - 协议类型：QoS保证机制中的消息应答包（目前只支持客户端间的QoS机制）
- 5：由客户端发出 - 协议类型：C2S时的回显指令（此指令目前仅用于测试时）
- 51：由服务端发出 - 协议类型：响应客户端的登陆
- 52：由服务端发出 - 协议类型：响应客户端的心跳包
- 53：由服务端发出 - 协议类型：反馈给客户端的错误信息
- 54：由服务端发出 - 协议类型：反馈回显指令给客户端