文件位置:GatewayWorker/Lib/Gateway.php
Lib\Gateway类是Gateway/BusinessWorker模型中给客户端发送数据的类。
提供了单发、群发以及关闭客户端连接的接口。
提示:GatewayWorker提供的所有接口都是支持分布式调用的,所以业务代码不需要任何更改,直接就可以分布式部署。
Gateway::sendToAll
void Gateway::sendToAll(string $send_data [, array $client_id_array = null [, array $exclude_client_id = null [, bool $raw = false]]]);
向所有客户端或者client_id_array指定的客户端发送$send_data数据。如果指定的$client_id_array中的client_id不存在则自动丢弃
$send_data=>要发送的数据(字符串类型),此数据会被Gateway所使用协议的encode方法打包后发送给客户端
$client_id_array=>指定向哪些client_id发送,如果不传递该参数,则是向所有在线客户端发送 $send_data 数据
$exclude_client_id=>client_id组成的数组。$exclude_client_id数组中指定的client_id将被排除在外,不会收到本次发的消息
$raw=>是否发送原始数据,也就是绕过gateway协议打包过程,gateway对数据不再做任何处理,直接发给客户端。
如果$raw为true,要求$message为用协议打包好的数据(调用了gateway指定协议的encode方法生成的数据),否则客户端可能无法解析。
此参数一般用于某些特殊情况,例如合并多个数据包为一段buffer,一次性发给客户端,而不是逐条发给客户端,这将有助于降低系统负载。
绝大多数情况此参数用不到,开发者可以忽略。
Gateway::sendToClient
void Gateway::sendToClient(string $client_id, string $send_data);
向客户端client_id发送$send_data数据。如果client_id对应的客户端不存在或者不在线则自动丢弃发送数据
$client_id=>客户端连接的client_id
$send_data=>要发送的数据(字符串类型),此数据会被Gateway所使用协议的encode方法打包后再发送给客户端
发送前先可以用Gateway::isOnline判断下客户端是否在线。
Gateway::sendToCurrentClient
void Gateway::sendToCurrentClient(string $send_data);
作用与Gateway::sendToClient相同,只不过是只能给当前用户发送
注意: 此接口不能用于定时器中,因为定时器执行的时候无法判断当前用户是哪个client_id。如果开发者需要在定时器中给某个客户端发送数据,请使用Gateway::sendToClient。
Gateway::closeClient
void Gateway::closeClient(string $client_id);
断开与client_id对应的客户端的连接
$client_id=>全局唯一标识客户端连接的id
Gateway::closeCurrentClient
void Gateway::closeCurrentClient();
作用与Gateway::closeClient相同,只不过是断开当前客户端的连接
注意: 此接口不能用于定时器中,因为定时器执行的时候无法判断当前用户是哪个client_id
Gateway::isOnline
int Gateway::isOnline(string $client_id);
判断$client_id是否还在线
$client_id=>客户端的client_id
在线返回1,不在线返回0
Gateway::bindUid
void Gateway::bindUid(string $client_id, mixed $uid);
将client_id与uid绑定,以便通过Gateway::sendToUid($uid)发送数据,通过Gateway::isUidOnline($uid)用户是否在线。
uid解释:这里uid泛指用户id或者设备id,用来唯一确定一个客户端用户或者设备。
$client_id=>客户端的client_id
$uid=>uid,可以是数字或者字符串。
注意:
1、uid与client_id是一对多的关系,系统允许一个uid下有多个client_id。
2、但是一个client_id只能绑定一个uid,如果绑定多次uid,则只有最后一次绑定有效。
2、如果业务需要一对一的关系,可以通过Gateway::getClientIdByUid($uid)获得某uid已经绑定的所有client_id,然后调用closeClient($client_id)踢掉之前的client_id。
3、client_id下线(连接断开)时会自动执行解绑,开发者无需调用Gateway::unbindUid解绑。
4、如果某个uid对应的所有client_id都下线了,则调用Gateway::isUidOnline($uid)将返回0,即uid不在线。
5、uid和client_id映射关系存储在Gateway进程内存中。
6、调用Gateway::bindUid($client_id, $uid)的时机一般是在验证连接合法性的时候。例如客户端连上服务端后,发送的第一个数据包应当包含客户端的鉴权信息(例如用户名密码或者可用于鉴权的token),服务端通过鉴权信息确定该连接属于哪个uid,然后调用Gateway::bindUid($client_id, $uid)绑定。
Gateway::isUidOnline
int Gateway::isUidOnline(mixed $uid);
判断$uid是否在线,此方法需要配合Gateway::bindUid($client_uid, $uid)使用。
如果某uid没有通过Gateway::bindUid($client_uid, $uid)进行任何绑定,那么对该uid调用Gateway::isUidOnline($uid)将返回0。
如果某uid绑定的client_id都已经下线,那么对该uid调用Gateway::isUidOnline($uid)将返回0。
如果某uid绑定的client_id有至少有一个在线,那么对该uid调用Gateway::isUidOnline($uid)将返回1。
$uid=>uid,可以是数字或者字符串
uid在线返回1,不在线返回0
Gateway::getClientIdByUid
array Gateway::getClientIdByUid(mixed $uid);
返回一个数组,数组元素为与uid绑定的所有在线的client_id。如果没有在线的client_id则返回一个空数组。
此方法可以判断一个uid是否在线。
注意:返回值为与uid绑定的所有在线的client_id数组。因为已经下线的client_id会自动与uid解绑,所以已经下线的client_id不会出现在返回值中。
返回一个client_id的数组$uid=>uid,可以是数字或者字符串。
getUidByClientId
目前并没有这个接口,开发者可以将uid存储到session中,获取的时候从session获取即可。
如果是获取当前请求所属client_id的session,直接使用$_SESSION变量即可。
如果想获取任意client_id的session,可以通过Gateway::getSession($client_id)获取。
Gateway::unbindUid
void Gateway::unbindUid(string $client_id, mixed $uid);
将client_id与uid解绑。
注意:当client_id下线(连接断开)时会自动与uid解绑,开发者无需在onClose事件调用Gateway::unbindUid。
$uid=>数字或者字符串。$client_id=>客户端的client_id
Gateway::sendToUid
void Gateway::sendToUid(mixed $uid, string $message);
向uid绑定的所有在线client_id发送数据。
注意:默认uid与client_id是一对多的关系,如果当前uid下绑定了多个client_id,则多个client_id对应的客户端都会收到消息,这类似于PC QQ和手机QQ同时在线接收消息。
$message=>要发送的数据(字符串类型),此数据会被Gateway所使用协议的encode方法打包后再发送给客户端$uid=>uid可以是字符串、数字、或者包含uid的数组。如果为数组,则是给数组内所有uid发送数据
发送前先可以用Gateway::getClientIdByUid判断下uid是否有在线的client_id。
Gateway::joinGroup
void Gateway::joinGroup(string $client_id, mixed $group);
将client_id加入某个组,以便通过Gateway::sendToGroup发送数据。
可以通过Gateway::getClientSessionsByGroup($group)获得该组所有在线成员数据。 可以通过Gateway::getClientCountByGroup($group)获得该组所有在线连接数(人数)。
该方法对于分组发送数据例如房间广播非常有用。
注意:
1、同一个client_id可以加入多个分组,以便接收不同组发来的数据。
2、当client_id下线(连接断开)后,该client_id会自动从该分组中删除,开发者无需调用Gateway::leaveGroup。
3、如果对应分组的所有client_id都下线,则对应分组会被自动删除。
4、目前没有提供获得所有分组id接口,所有分组名称可以自行存入数据库中。
$group=>只能是数字或者字符串。$client_id=>客户端的client_id
注意:group不能为空值。例如0,0.0,'0',"0",false,null是非法的group值。
Gateway::leaveGroup
void Gateway::leaveGroup(string $client_id, mixed $group);
将client_id从某个组中删除,不再接收该分组广播(Gateway::sendToGroup)发送的数据。
注意:当client_id下线(连接断开)时,client_id会自动从它所属的各个分组中删除,也就是说无需在onClose回调中调用Gateway::leaveGroup$group=>只能是数字或者字符串。$client_id=>客户端的client_id
Gateway::sendToGroup
void Gateway::sendToGroup(mixed $group, string $message [, array $exclude_client_id = null [, bool $raw = false]]);
向某个分组的所有在线client_id发送数据。
$group=>group可以是字符串、数字、或者数组。如果为数组,则是给数组内所有group发送数据
$message=>要发送的数据(字符串类型),此数据会被Gateway所使用协议的encode方法打包后再发送给客户端
$exclude_client_id=>client_id组成的数组。$exclude_client_id数组中指定的client_id将被排除在外,不会收到本次发的消息
$raw=>是否发送原始数据,也就是绕过gateway协议打包过程,gateway对数据不再做任何处理,直接发给客户端。
如果$raw为true,要求$message为用协议打包好的数据(调用了gateway指定协议的encode方法生成的数据),否则客户端可能无法解析。
此参数一般用于某些特殊情况,例如合并多个数据包为一段buffer,一次性发给客户端,而不是逐条发给客户端,这将有助于降低系统负载。
绝大多数情况此参数用不到,开发者可以忽略。
Gateway::getClientCountByGroup
int Gateway::getClientCountByGroup(mixed $group);
获取某分组当前在线成员数(多少client_id在线)。
$group=>分组名字
返回一个数字
Gateway::getClientSessionsByGroup
array Gateway::getClientSessionsByGroup(mixed $group);
获取某个分组所有在线client_id信息。
返回值为client_id为key,client_id对应的$_SESSION为值的数组。 类似下面的格式
array(
'7f00000108fc00000008' => array(...),
'7f00000108fc00000009' => array(...),
)
Gateway::getAllClientCount
int Gateway::getAllClientCount(void);
获取当前在线连接总数(多少client_id在线)
返回一个数字
Gateway::getAllClientSessions
array Gateway::getAllClientSessions(void);
获取当前所有在线client_id信息。
返回值为client_id为key,client_id对应的$_SESSION为值的数组。 类似下面的格式
array(
'7f00000108fc00000008' => array(...),
'7f00000108fc00000009' => array(...),
)
Gateway::setSession
void Gateway::setSession(string $client_id, array $session);
设置某个client_id对应的session。如果对应client_id已经下线或者不存在,则会被忽略。
注意:不要$_SESSION赋值与Gateway::setSession同时操作同一个$client_id,可能会造成session值与预期效果不符。操作当前用户用$_SESSION['xx']=xxx方式赋值即可,操作其他用户session可以使用Gateway::setSession接口。
$client_id=>客户端的client_id
$session=>要设置的session数组
Gateway::updateSession
void Gateway::updateSession(string $client_id, array $session);
更新某个client_id对应的session。如果对应client_id已经下线或者不存在,则会被忽略。
此函数与Gateway::setSession($client_id, $new_session)的区别是:
1、Gateway::setSession($client_id, $new_session)是整体赋值。
2、Gateway::updateSession($client_id, $update_session)部分更新。
注意:不要$_SESSION赋值与Gateway::setSession同时操作同一个$client_id,可能会造成session值与预期效果不符。操作当前用户用$_SESSION['xx']=xxx方式赋值即可,操作其他用户session可以使用Gateway::setSession接口。
$client_id=>客户端的client_id
$session=>要设置的session数组
Gateway::getSession
mixed Gateway::getSession(string $client_id);
获取某个client_id对应的session。
$client_id=>客户端的client_id
1、如果对应的client_id下线或者不存在,则返回null
2、如果对应的client_id在线但是没有设置过session,则返回array()
3、如果对应的client_id在线并设置了session,则正常返回一个数组
注意:Gateway::onClose回调里无法使用Gateway::getSession来获得当前用户的session数据,但是仍然可以使用$_SESSION变量获得。