事件处理

概述

当sdk收到某些后台下发的数据,或者发生了某些需要上层关注的事件时,sdk会上抛事件对象通知给上层,例如,在线消息事件会话刷新事件用户下线事件等。
应用上层需要根据实际情况决定是否需要接收并且处理事件。

事件接收类的注册

应用层可以在任意类中注册事件接收,sdk会持有这个类的强引用,上层需要注意在合适的地方解绑事件接收。
如果要实现全局事件监听,或者在应用的整个生命周期内都需要监听事件的话,建议放在application类里,不要放在类似activity、或者fragmemt、service之类的组件中。

  1. JMessageClient.registerEventReceiver(Object receiver);
  2. JMessageClient.registerEventReceiver(Object receiver, int priority);

参数说明

  • Object receiver 消息接收类对象
  • int priority 定义事件接收者接收事件的优先级,默认值为0,优先级越高将越先接收到事件。(优先级只对同一个线程模式中的接收者有效)

事件接收类的解绑

  1. JMessageClient.unRegisterEventReceiver(Object receiver);

参数说明

  • Object receiver 消息接收类对象,对象解绑之后将不再接收到任何event。

事件接收

注册事件接收类之后,需要在消息接收类中实现如下方法来接收对应消息。sdk将根据实现方法的方法名来区分不同的线程模式,常用的线程模式有onEvent(默认线程模式)和onEventMainThread(主线程模式)两种。

可以通过定义不同类型的参数,来接收不同种类的事件。具体事件类型定义见 “事件类型” 一节

子线程模式(默认线程)

  1. public void onEvent(EventEntity event){
  2. //do your own business
  3. }

方法体将在子线程中被调用, 可以用来处理耗时操作。

参数定义

  • EventEntity event 事件对象。( 指代下文的具体事件类型实体类型,具体用法可以参考“示例代码“。)

主线程模式

  1. public void onEventMainThread(EventEntity event){
  2. //do your own business
  3. }

方法体将在主线程中被调用,可以用来刷新UI。 参数定义

  • EventEntity event 事件对象。EventEntity指代的是下文的具体事件类型

用户事件

当前登录用户信息被更新事件实体类 MyInfoUpdatedEvent

方法 类型 说明
getMyInfo() UserInfo 获取更新之后的我的userinfo

用户下线事件UserLogoutEvent
(已过时,请使用LoginStateChangeEvent代替)

方法 类型 说明
getMyInfo() UserInfo 获取当前被登出账号的信息


用户被删除事件UserDeletedEvent
(已过时,请使用LoginStateChangeEvent代替)

方法 类型 说明
getMyInfo() UserInfo 获取当前被删除账号的信息


用户登录状态变更事件LoginStateChangeEvent

方法 类型 说明
getMyInfo() UserInfo 获取当前登录状态改变的账号的信息
getReason() Reason 获取登录状态变更原因。

消息/会话事件

在线消息事件实体类 MessageEvent

方法 类型 说明
getMessage() Message 获取消息对象


离线消息事件实体类 OfflineMessageEvent
Since 2.1.0

方法 类型 说明
getConversation() Conversation 获取收到离线消息的会话对象
getNewMessageList() List 获取收到的离线消息列表,包含了该会话此次离线收到的所有离线消息列表。其中也有可能包含自己发出去的消息。
getOfflineMsgCnt() int 获取此次事件中该会话的离线消息总数。

会话刷新事件实体类 ConversationRefreshEvent

方法 类型 说明
getConversation() Conversation 获取需要被刷新的会话对象
getReason() Reason 获取事件发生的原因,包括消息漫游完成、会话信息更新等

消息被对方撤回通知事件MessageRetractEvent
Since 2.2.0

方法 类型 说明
getConversation() Conversation 获取被撤回消息所属的会话对象
getRetractedMessage() Message 获取被撤回的message对象.
(注意!此时获取到的Message的MessageContent对象已经从撤回前的真正的消息内容变为了PromptContent类型的提示文字)

消息未回执人数变更事件MessageReceiptStatusChangeEvent
Since 2.3.0

方法 类型 说明
getConversation() Conversation 获取未回执数变更的消息所属的会话对象
getMessageReceiptMetas() List<MessageReceiptMeta> 获取未回执数发生变化的消息的MessageReceiptMeta。其中包括了消息的serverMsg Id、当前的未回执人数、以及未回执人数更新的时间

群组事件

群成员变化相关事件
群组成员变化相关事件因为sdk需要入库,所以sdk会将相关事件以消息事件的方式上抛,用户可以将群组中产生的成员变化事件理解成一条特殊的消息,其消息类型为eventNotification,例如:

  1. //用户在线期间,如果群组中发生了成员变化事件,sdk也会通过上抛MessageEvent的方式来通知上层
  2. public void onEvent(MessageEvent event) {
  3. Message msg = event.getMessage();
  4. //获取消息类型,如text voice image eventNotification等。
  5. switch (msg.getContentType()) {
  6. //处理事件提醒消息,此处message的contentType类型为eventNotification。
  7. case eventNotification:
  8. //获取事件发生的群的群信息
  9. GroupInfo groupInfo = (GroupInfo) msg.getTargetInfo();
  10. //获取事件具体的内容对象
  11. EventNotificationContent eventNotificationContent = (EventNotificationContent)msg.getContent();
  12. //获取事件具体类型
  13. switch (eventNotificationContent.getEventNotificationType()){
  14. case group_member_added:
  15. //群成员加群事件
  16. break;
  17. case group_member_removed:
  18. //群成员被踢事件
  19. break;
  20. case group_member_exit:
  21. //群成员退群事件
  22. break;
  23. case group_info_updated://since 2.2.1
  24. //群信息变更事件
  25. break;
  26. ...
  27. }
  28. break;
  29. }
  30. }
  31. //用户离线期间,如果群组中发生了成员变化事件,sdk也会通过上抛OfflineMessageEvent
  32. //的方式来通知上层,处理方式类似上面的MessageEvent
  33. public void onEvent(OfflineMessageEvent event) {
  34. List<Message> msgs = event.getOfflineMessageList();
  35. for (Message msg:msgs) {
  36. //...
  37. }
  38. }

群成员审批事件GroupApprovalEvent
Since 2.4.0

方法 类型 说明
getType() Type 获取群成员审批通知事件类型,主动申请入群是Type.apply_join_group,邀请入群是Type.invited_into_group
getFromUserInfo() UserInfo 获取群成员审批事件发起方UserInfo,主动申请入群时是申请人UserInfo,邀请入群时是邀请人UserInfo
getApprovalUserInfoList() List<UserInfo> 获取需要审批入群的用户UserInfo
getApprovalUserCount() int 获取需要审批入群的用户的人数
getReason() String 获取事件发生的理由,主动申请入群时是申请理由(可为null),邀请入群时是null
acceptGroupApproval() void 入群审批同意,需要指定usernameappKey
refuseGroupApproval() void 入群审批拒绝,需要指定usernameappKeyreason(可为null)

群成员审批拒绝事件GroupApprovalRefuseEvent
Since 2.4.0

方法 类型 说明
getFromUserInfo() UserInfo 获取事件发起方userInfo,在本事件中为群主信息
getToUserInfoList() List<UserInfo> 获取事件对象用户信息列表,在本事件中为被拒绝入群的用户UserInfo列表
getReason() String 获取事件发生的理由, 在本事件中为群主审批拒绝的理由
getGid() long 返回实际群组Gid

已审批事件通知GroupApprovedNotificationEvent
Since 2.5.0

方法 类型 说明
getApprovalEventID() long 获取对应的入群审批事件ID
getApprovalResult() boolean 获取入群审批结果
getGroupID() long 获取入群审批事件对应的群组ID
getOperator() UserInfo 获取该次入群审批的操作者用户信息
getApprovedUserInfoList() List<UserInfo> 获取已被审批过的用户信息,这些用户的入群审批已经被审批

群成员昵称修改事件GroupMemNicknameChangedEvent
Since 2.7.0

方法 类型 说明
getGroupID() long 获取群组id
getChangeEntities() List<ChangeEntity> 获取昵称修改事件列表,按照时间升序排列

群公告变更事件GroupAnnouncementChangedEvent
Since 2.8.0

方法 类型 说明
getGroupID() long 获取群组id
getChangeEntities() List<ChangeEntity> 获取公告变更事件列表,按照时间升序排列

群黑名单变更事件GroupBlackListChangedEvent
Since 2.8.0

方法 类型 说明
getGroupID() long 获取群组id
getChangeEntities() List<ChangeEntity> 获取黑名单变更事件列表,按照时间升序排列

聊天室事件

聊天室消息事件ChatRoomMessageEvent
Since 2.4.0 聊天室消息因为sdk不会入库,所以没有走正常的消息事件,而是单独的聊天室消息事件。注意和消息事件做区分

方法 类型 说明
getMessages() List<Message> 获取聊天室消息事件中包含的消息列表

聊天室通知事件ChatRoomNotificationEvent
Since 2.8.0

方法 类型 说明
getEventID() long 获取事件ID
getRoomID() long 获取事件对应聊天室的房间ID
getType() Type 获取事件类型
getOperator(GetUserInfoCallback callback) void 获取事件操作者用户信息
getTargetUserInfoList(GetUserInfoListCallback callback) void 获取目标用户信息列表
getCtime() long 取事件发生时间,单位-毫秒

好友事件

好友相关事件通知实体类ContactNotifyEvent
Since 1.4.0


方法 类型 说明
getType() Type 获取好友通知事件的具体类型。
getReason() String 获取事件发生的理由,该字段由对方发起请求时所填。
getFromUsername() String 获取事件发起者用户的username
getfromUserAppKey() String 获取事件发起者用户所属应用的appKey

命令透传事件

命令透传事件实体类CommandNotificationEvent
Since 2.3.0


方法 类型 说明
getSenderUserInfo() UserInfo 获取命令透传消息发送者的UserInfo
getType() Type 获取命令透传消息对象的类型,单聊是Type.single,群聊则是Type.group,如果是自己已登录设备间的命令透传则是Type.self
getTargetInfo() Objcet 获取命令透传消息发送对象的Info。若对象是单聊用户则是UserInfo,对象是群组则是GroupInfo,使用时强制转型
getMsg() String 获取命令透传消息的实际内容

通知栏点击事件

通知栏点击事件实体类NotificationClickEvent

方法 类型 说明
getMessage() Message 获取点击的通知所对应的消息对象

示例代码

接收消息事件

  1. class MessageEventReceiver extends Activity {
  2. @Override
  3. protected void onCreate() {
  4. super.onCreate(savedInstanceState);
  5. //这里只是为了展示注册事件接受者接口的用法,实际上开发者可以在任意类中注册事件接收者
  6. //,而不仅仅在Activity中。 下同
  7. JMessageClient.registerEventReceiver(this);
  8. }
  9. @Override
  10. protected void onDestroy() {
  11. JMessageClient.unRegisterEventReceiver(this);
  12. super.onDestroy();
  13. }
  14. //用户在线期间收到的消息都会以MessageEvent的方式上抛
  15. public void onEvent(MessageEvent event) {
  16. Message msg = event.getMessage();
  17. switch (msg.getContentType()) {
  18. case text:
  19. //处理文字消息
  20. TextContent textContent = (TextContent) msg.getContent();
  21. textContent.getText();
  22. break;
  23. case image:
  24. //处理图片消息
  25. ImageContent imageContent = (ImageContent) msg.getContent();
  26. imageContent.getLocalPath();//图片本地地址
  27. imageContent.getLocalThumbnailPath();//图片对应缩略图的本地地址
  28. break;
  29. case voice:
  30. //处理语音消息
  31. VoiceContent voiceContent = (VoiceContent) msg.getContent();
  32. voiceContent.getLocalPath();//语音文件本地地址
  33. voiceContent.getDuration();//语音文件时长
  34. break;
  35. case custom:
  36. //处理自定义消息
  37. CustomContent customContent = (CustomContent) msg.getContent();
  38. customContent.getNumberValue("custom_num"); //获取自定义的值
  39. customContent.getBooleanValue("custom_boolean");
  40. customContent.getStringValue("custom_string");
  41. break;
  42. case eventNotification:
  43. //处理事件提醒消息
  44. EventNotificationContent eventNotificationContent = (EventNotificationContent)msg.getContent();
  45. switch (eventNotificationContent.getEventNotificationType()){
  46. case group_member_added:
  47. //群成员加群事件
  48. break;
  49. case group_member_removed:
  50. //群成员被踢事件
  51. break;
  52. case group_member_exit:
  53. //群成员退群事件
  54. break;
  55. case group_info_updated://since 2.2.1
  56. //群信息变更事件
  57. break;
  58. }
  59. break;
  60. case unknown:
  61. // 处理未知消息,未知消息的Content为PromptContent 默认提示文本为“当前版本不支持此类型消息,请更新sdk版本”,上层可选择不处理
  62. PromptContent promptContent = (PromptContent) msg.getContent();
  63. promptContent.getPromptType();//未知消息的type是unknown_msg_type
  64. promptContent.getPromptText();//提示文本,“当前版本不支持此类型消息,请更新sdk版本”
  65. break;
  66. }
  67. }
  68. //用户离线期间收到的消息会以OfflineMessageEvent的方式上抛,处理方式类似上面的
  69. //MessageEvent
  70. public void onEvent(OfflineMessageEvent event) {
  71. List<Message> msgs = event.getOfflineMessageList();
  72. for (Message msg:msgs) {
  73. //...
  74. }
  75. }
  76. }

接收通知栏点击事件

  1. class NotificationClickEvent extends Activity{
  2. @Override
  3. protected void onCreate() {
  4. super.onCreate(savedInstanceState);
  5. JMessageClient.registerEventReceiver(this);
  6. }
  7. @Override
  8. protected void onDestroy() {
  9. JMessageClient.unRegisterEventReceiver(this);
  10. super.onDestroy();
  11. }
  12. public void onEvent(NotificationClickEvent event){
  13. Intent notificationIntent = new Intent(mContext, ChatActivity.class);
  14. mContext.startActivity(notificationIntent);//自定义跳转到指定页面
  15. }
  16. }

用户登录状态变更事件

  1. class UserLogoutEventReceiver extends Activity{
  2. @Override
  3. protected void onCreate() {
  4. super.onCreate(savedInstanceState);
  5. JMessageClient.registerEventReceiver(this);
  6. }
  7. @Override
  8. protected void onDestroy() {
  9. JMessageClient.unRegisterEventReceiver(this);
  10. super.onDestroy();``
  11. }
  12. public void onEvent(LoginStateChangeEvent event){
  13. LoginStateChangeEvent.Reason reason = event.getReason();//获取变更的原因
  14. UserInfo myInfo = event.getMyInfo();//获取当前被登出账号的信息
  15. switch (reason) {
  16. case user_password_change:
  17. //用户密码在服务器端被修改
  18. break;
  19. case user_logout:
  20. //用户换设备登录
  21. break;
  22. case user_deleted:
  23. //用户被删除
  24. break;
  25. }
  26. }
  27. }