$socket 连接
$socket可以让服务器主动推送数据给客户端,实现多个在线用户之间及时传递消息
open(onExp, option) 打开连接
onExp:事件回调表达式可包含如下选项onConnect
:连接上服务器后执行的表达式onReconnect
:连接断开后会自动重连,重连成功后执行的表达式onData
: 收到消息后执行的表达式onError
: 发生错误后执行的表达式
option:有若干选项。channels
:频道数组,指定希望接受到哪些频道的消息。autoResend
:重连后是否自动重发断连期间未能发送的消息。allowMultiLogin
:是否允许多端登录,即在多个浏览器登录的同一个用户能接受到相同的消息saveToDB
:把消息保存到数据库,这样即使离线用户也可以通过$socket.hist(channel)查看历史消息onOnline
:是否响应用户上线消息,有用户上线时将收到{ "type": "onOnline", "x": user_id }
onOffline
:是否响应用户下线消息,有用户下线时将收到{ "type": "onOffline", "x": user_id }
send(to, type, x) 发送消息
可以发给某人(当to是用户_id时)或广播给某个频道里的所有人(当to是channel时)。用type
指定消息类型,以便onData表达式据此分类处理。x
可以是任意格式的消息详情。
此API是异步函数,不等待发送结果就执行下一表达式(因此无$r),发送结果转而由onData接收,格式如下:
{
d: Number, // 发送时间,即new Date().getTime()
from: User, // 发送人ID
to: User/String, // 接收人ID或频道名
type: String, // 即上面的type
x: Any // 即上面的x
}
typezchannel
是特殊类型,用在已打开连接要订阅新频道时,比如加入新群聊,在新群发消息前先订阅一下$socket.send(群_id, "zchannel")才能收到此群的消息。如果不想再收到此群消息则可通过$socket.send(群_id, "zchannel", -1)退订。
heartbeat() 心跳
为了保持长时间的连接,客户端和服务器每隔30秒就会同步一次心跳,此函数可用来获取最近一次心跳的时间。
当date() - $socket.heartbeat() - 30000
为正数时说明暂时断开了连接,无法同步心跳。
onlines(channels) 在线用户
用数组channels指定哪些频道,返回 { 频道: [用户ID] }
hist(channel) 历史消息
如果open()的时把saveToDB选项设为true则可通过此API获取历史消息。
如果有参数channel则获取指定频道中的消息数组,格式为[ { _id: String, channel: String, arr: [], more: [] } ]
无参数时是获取单独发给该用户的消息数组,格式为[ { _id: String, peer: [], arr: [], more: [] } ]
arr
是消息列表,格式同onData。more
是更多历史消息,每项格式:[ _id, from, to ]
,其中_id
可以用more(_id)
来获取更多的50个消息,from
和to
是此更多消息的头尾消息的时间。
more(_id) 更多历史消息
delete(_id) 删除历史消息
_id
是hist()返回的_id。
pull(_id, from, d) 删除指定消息
_id
是hist()返回的_id,from
和d
是待删除消息的发送者和发送时间。
modify(_id, from, d, x) 修改指定消息
_id
是hist()返回的_id,from
和d
是待修改消息的发送者和发送时间,x
是新的文本内容。