事件处理
- 概述
  - 添加监听代理
    - JMessage
- 用户事件
  - 事件类型
  - 监听方法
消息事件
- 特殊的消息事件
  - 事件类型
  - 监听方法
- 普通的消息事件
群组事件
聊天室事件
- 聊天室管理员变更事件通知
  - 事件
  - 监听方法
- 聊天室黑名单变更事件通知
  - 事件
  - 监听方法
好友事件
- 事件
- 监听方法
透传命令事件
- 事件
- 监听方法

事件处理

概述

当 SDK 收到某些后台下发的数据，或者发生了某些需要上层关注的事件时，SDK 会上抛事件对象通知给上层，例如，好友事件、入群申请事件、用户登录状态变更事件等。应用上层需要根据实际情况决定是否需要接收并且处理事件。

添加监听代理

只有添加了代理，并且上层实现代理方法，才能够接收到相关事件，SDK 所有代理的添加都是通过此接口设置：

JMessage

/*!
 * @abstract 增加回调(delegate protocol)监听
 *
 * @param delegate 需要监听的 Delegate Protocol
 * @param conversation 允许为nil
 *
 * - 为 nil, 表示接收所有的通知, 不区分会话.
 * - 不为 nil，表示只接收指定的 conversation 相关的通知.
 *
 * @discussion 默认监听全局 JMessageDelegate 即可.
 *
 * 这个调用可以在任何地方, 任何时候调用, 可以在未进行 SDK
 * 启动 setupJMessage:appKey:channel:apsForProduction:category: 时就被调用.
 *
 * 并且, 如果你有必要接收数据库升级通知 JMSGDBMigrateDelegate,
 * 就应该在 SDK 启动前就调用此方法, 来注册通知接收.
 * 这样, SDK启动过程中发现需要进行数据库升级, 给 App 发送数据库升级通知时,
 * App 才可以收到并进行处理.
 */
+ (void)addDelegate:(id <JMessageDelegate>)delegate withConversation:(JMSGConversation *)conversation;

用户事件

此类事件总体分为：用户信息变更和登录状态变更事件，当前登录用户的登录状态发生变化或者异常时，SDK 会上抛此类型事件，上层通过 JMSGUserDelegate 类里的方法来监听此类事件。

事件类型

typedef NS_ENUM(NSInteger, JMSGLoginStatusChangeEventType) {
  // 用户登录状态变更事件
  /// 事件类型: 登录被踢
  kJMSGEventNotificationLoginKicked = 1,
  /// 事件类型: 非客户端修改密码强制登出事件
  kJMSGEventNotificationServerAlterPassword = 2,
  /// 事件类型：用户登录状态异常事件（需要重新登录）
  kJMSGEventNotificationUserLoginStatusUnexpected = 70,
  /// 事件类型：当前登录用户信息变更通知事件(非客户端修改)
  kJMSGEventNotificationCurrentUserInfoChange = 40,
  /// 事件类型：当前登录用户被删除事件（本地用户信息会被清空）
  kJMSGEventNotificationCurrentUserDeleted = 10001,
  /// 事件类型：当前登录用户被禁用事件（本地用户信息会被清空）
  kJMSGEventNotificationCurrentUserDisabled = 10002,
};

监听方法

/*!
 * @abstract 监听当前用户登录状态变更事件
 *
 * @discussion 可监听：当前登录用户被踢、非客户端修改密码强制登出、登录状态异常、被删除、被禁用、信息变更等事件
 *
 * @since 3.5.0
 */
@optional
- (void)onReceiveUserLoginStatusChangeEvent:(JMSGUserLoginStatusChangeEvent *)event;

消息事件

与消息 JMSGMessage 有关的事件都称之为消息事件，但是消息事件又可分为如下两类：

普通的消息事件：这类事件都是有单独的方法监听，不会入库，SDK 也不会将其主动加入消息记录中。
特殊的消息事件：这是类事件 SDK 会封装为一个消息对象 message 上抛，这些消息事件会入库到消息记录里。这类事件其实就是群会话里的事件，比如：用户加入群组、用户被踢出群组等，

特殊的消息事件

称之为“特殊”，是因为写类型的事件 SDK 会封装成 JMSGMessage 对象后上抛给上层，而其他类型的消息则是通过 JMSGNotificationEvent 对象上抛的。

事件类型

typedef NS_ENUM(NSInteger, JMSGEventNotificationType) {
  // 消息事件
  /// 事件类型: 群组被创建
  kJMSGEventNotificationCreateGroup = 8,
  /// 事件类型: 退出群组
  kJMSGEventNotificationExitGroup = 9,
  /// 事件类型: 群组添加新成员
  kJMSGEventNotificationAddGroupMembers = 10,
  /// 事件类型: 群组成员被踢出
  kJMSGEventNotificationRemoveGroupMembers = 11,
  /// 事件类型: 群信息更新
  kJMSGEventNotificationUpdateGroupInfo = 12,
  /// 事件类型: 群禁言通知事件
  kJMSGEventNotificationGroupMemberSilence = 65,
  /// 事件类型: 管理员角色变更通知事件
  kJMSGEventNotificationGroupAdminChange = 80,
  /// 事件类型: 群主变更通知事件
  kJMSGEventNotificationGroupOwnerChange = 82,
  /// 事件类型: 群类型变更通知事件
  kJMSGEventNotificationGroupTypeChange = 83,
  /// 事件类型: 解散群组
  kJMSGEventNotificationDissolveGroup = 11001,
  /// 事件类型: 群组成员上限变更
  kJMSGEventNotificationGroupMaxMemberCountChange = 11002,
};

监听方法

这类特殊的消息事件的监听分为：在线、离线、漫游。

在线监听方法

/*!
 * @abstract 接收消息(服务器端下发的)回调
 *
 * @param message 接收到下发的消息
 * @param error 不为 nil 表示接收消息出错
 *
 * @discussion 应检查 error 是否为空来判断有没有出错. 如果未出错, 则成功.
 * 留意的是, 这里的 error 不包含媒体消息下载文件错误. 这类错误有单独的回调 onReceiveMessageDownloadFailed:
 *
 * 收到的消息里, 也包含服务器端下发的各类消息事件, 比如有人被加入了群聊. 这类消息事件处理为特殊的 JMSGMessage 类型.
 *
 * 事件类的消息, 基于 JMSGMessage 类里的 contentType 属性来做判断,
 * contentType = kJMSGContentTypeEventNotification.
 */
@optional
- (void)onReceiveMessage:(JMSGMessage *)message error:(NSError *)error;

离线监听方法

/*!
 * @abstract 同步离线消息、离线事件通知
 *
 * @param conversation    同步离线消息的会话
 * @param offlineMessages 离线消息、离线事件数组
 *
 * @discussion 注意：
 *
 * SDK 会将消息下发分为在线下发和离线下发两种情况,
 * 其中用户在离线状态(包括用户登出或者网络断开)期间所收到的消息我们称之为离线消息.
 *
 * 当用户上线收到这部分离线消息后,这里的处理与之前版本不同的是:
 *
 * 3.1.0 版本之前: SDK 会和在线时收到的消息一样,每收到一条消息都会上抛一个在线消息 JMSGMessage 来通知上层.
 *
 * 3.1.0 版本之后: SDK 会以会话为单位，不管该会话有多少离线消息，SDK同步完成后每个会话只上抛一次.
 *
 * 3.2.1 版本之后: SDK 会以会话为单位，不管该会话有多少离线事件，SDK同步完成后每个会话只上抛一次
 *
 * 注意：一个会话最多触发两次这个代理，即：离线消息和离线事件各一次,这样会大大减轻上层在收到消息刷新 UI 的压力.
 *
 * 上层通过此代理方法监听离线消息同步的会话,详见官方文档.
 *
 */
@optional
- (void)onSyncOfflineMessageConversation:(JMSGConversation *)conversation
                         offlineMessages:(NSArray JMSG_GENERIC(__kindof JMSGMessage *)*)offlineMessages;

漫游监听方法

漫游消息事件则是通过如下方法监听，此方法只会通知上层是某个会话有漫游消息事件，而不会上抛具体的消息事件列表，需上层调用接口从本地获取。

/*!
 * @abstract 同步漫游消息通知
 *
 * @param conversation 同步漫游消息的会话
 *
 * @discussion 注意：
 *
 * 当 SDK 触发此函数时，说明该会话有同步下漫游消息，并且已经存储到本地数据库中，
 * 上层可通过 JMSGConversation 类中的获取message的方法刷新UI.
 *
 * @since 3.1.0
 */
@optional
- (void)onSyncRoamingMessageConversation:(JMSGConversation *)conversation;

普通的消息事件

消息撤回事件

由消息发送方发起调用，在一定时间内，SDK 可以撤回会话中某条消息，一旦消息撤回成功，用户会收到 SDK 上抛的一个 JMSGMessageRetractEvent 事件，上层通过下面的代理来监听。

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
conversation	JMSGConversation	消息撤回所属会话
retractMessage	JMSGMessage	撤回之后的消息

监听方法

/*!
 * @abstract 监听消息撤回事件
 *
 * @param retractEvent 下发的通知事件，事件类型请查看 JMSGMessageRetractEvent 类
 *
 * @since 3.2.0
 */
@optional
- (void)onReceiveMessageRetractEvent:(JMSGMessageRetractEvent *)retractEvent;

消息回执事件

对于消息接收方，可以将一条消息标记为已读，标记成功后，这条消息的已读状态会记录在本地，SDK 还将主动上抛一个 JMSGMessageReceiptStatusChangeEvent 通知事件

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
conversation	JMSGConversation	消息所属会话
messages	NSArray(JMSGMessage)	已读回执变更的消息列表

监听方法

/*!
 * @abstract 监听消息回执状态变更事件
 *
 * @param receiptEvent 下发的通知事件，事件类型请查看 JMSGMessageReceiptStatusChangeEvent 类
 *
 * @discussion 上层可以通过 receiptEvent 获取相应信息
 *
 * @since 3.3.0
 */
@optional
- (void)onReceiveMessageReceiptStatusChangeEvent:(JMSGMessageReceiptStatusChangeEvent *)receiptEvent;

群组事件

这里说的群组事件是指需要单独方法来监听的群事件，与消息事件是有区别的。此类事件上层通过 JMSGGroupDelegate 类里的代理方法来监听。

群信息变更通知事件

群信息变更后，后台下发的通知给到SDK，SDK 会主动更新群信息，然后再出发上抛并触发代理方法，上层通过实现该代理可监听群信息变更通知。

监听方法

/*!
 * @abstract 群组信息 (GroupInfo) 变更通知
 *
 * @param group 变更后的群组对象
 *
 * @discussion 如果想要获取通知, 需要先注册回调. 具体请参考 JMessageDelegate 里的说明.
 */
@optional
- (void)onGroupInfoChanged:(JMSGGroup *)group;

申请入群通知事件

该事件通知只适用于公开群，并且只有群主和管理员会收到此事件，事件内的具体参数请查看 JMSGApplyJoinGroupEvent

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
eventID	NSString	事件的 id
groupID	NSString	群 gid
isInitiativeApply	BOOL	YES：主动申请加入，NO：被邀请加入
sendApplyUser	JMSGUser	发起申请的 user
joinGroupUsers	NSArray(JMSGUser)	被邀请入群的 user 数组
reason	NSString	原因

监听方法

/*!
 * @abstract 监听申请入群通知
 *
 * @param event 申请入群事件
 *
 * @discussion 只有群主和管理员能收到此事件；申请入群事件相关参数请查看 JMSGApplyJoinGroupEvent 类，在群主审批此事件时需要传递事件的相关参数
 *
 * @since 3.4.0
 */
@optional
- (void)onReceiveApplyJoinGroupApprovalEvent:(JMSGApplyJoinGroupEvent *)event;

管理员拒绝入群申请通知事件

该事件通知只适用于公开群，只有申请方和被申请方会收到此事件，相关参数和返回值请详看 JMSGGroupAdminRejectApplicationEvent

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
groupID	NSString	群 gid
rejectReason	NSString	拒绝原因
groupManager	JMSGUser	操作的管理员

监听方法

/*!
 * @abstract 监听管理员拒绝入群申请通知
 *
 * @param event 拒绝入群申请事件
 *
 * @discussion 只有申请方和被申请方会收到此事件；拒绝的相关描述和原因请查看 JMSGGroupAdminRejectApplicationEvent 类
 *
 * @since 3.4.0
 */
@optional
- (void)onReceiveGroupAdminRejectApplicationEvent:(JMSGGroupAdminRejectApplicationEvent *)event;

管理员审批通知事件

该事件通知只适用于公开群，只有管理员才会收到该事件,当管理员同意或拒绝了某个入群申请事件时，其他管理员就会收到该事件，相关属性请查看 JMSGGroupAdminApprovalEvent 类

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
isAgreeApply	BOOL	管理员是否同意申请，YES：同意，NO：拒绝
applyEventID	NSString	申请入群事件的事件 id
groupID	NSString	群 gid
groupAdmin	JMSGUser	操作的管理员
users	NSArray(JMSGUser)	申请或被邀请加入群的用户，即：实际入群的用户

监听方法

/*!
 * @abstract 监听管理员审批通知
 *
 * @param event 管理员审批事件
 *
 * @discussion 只有管理员才会收到该事件；当管理员同意或拒绝了某个入群申请事件时，其他管理员就会收到该事件，相关属性请查看 JMSGGroupAdminApprovalEvent 类
 *
 * @since 3.5.0
 */
@optional
- (void)onReceiveGroupAdminApprovalEvent:(JMSGGroupAdminApprovalEvent *)event;

群成员群昵称变更通知事件

该事件适用于任何类型的群组，当群内某个成员改变了在群里的群昵称，SDK 会上抛该事件，如果是离线修改，SDK 会把同一个群内的所有修改昵称的事件一起上抛，事件具体相关属性请查看 JMSGGroupNicknameChangeEvent 类

事件

属性	类型	说明
group	JMSGGroup	群组
fromMemberInfo	JMSGGroupMemberInfo	修改昵称的群成员
toMemberInfo	JMSGGroupMemberInfo	被修改昵称的群成员
ctime	UInt64	事件时间

监听方法

/*!
 * @abstract 群成员群昵称变更通知
 *
 * @param events 群成员昵称变更事件列表
 *
 * @discussion 如果是离线事件，SDK 会将所有的修改记录加入数组上抛。事件具体相关属性请查看 JMSGGroupNicknameChangeEvent 类
 *
 * @since 3.7.0
 */
@optional
- (void)onReceiveGroupNicknameChangeEvents:(NSArray<__kindof JMSGGroupNicknameChangeEvent*>*)events;

群公告变更通知事件

该事件适用于任何类型群组，群公告最多100条，发布公告、置顶公告、删除公告都会有事件下发，下发的 JMSGGroupAnnouncementEvent 属性并不是全部都有值，比如：删除公告事件里只有公告 id 是有值的。

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
announcement	JMSGGroupAnnouncement	群公告
fromUser	JMSGUser	事件操作者
group	JMSGGroup	群组
ctime	UInt64	事件时间

监听方法

/*!
 * @abstract 群公告变更通知
 *
 * @param event 群公告事件列表
 *
 * @discussion 事件具体相关属性请查看 JMSGGroupAnnouncementEvent 类
 *
 * @since 3.8.0
 */
@optional
- (void)onReceiveGroupAnnouncementEvents:(NSArray<__kindof JMSGGroupAnnouncementEvent*>*)events;

群组黑名单变更通知事件

该事件适用于任何类型群组，黑名单上限100个，超出将无法设置成功，被拉入黑名单用户会被主动踢出群组，且无法再次加入。事件具体相关属性请查看 JMSGGroupBlacklistChangeEvent 类

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
group	JMSGGroup	群组
fromUser	JMSGUser	事件操作者
targetList	NSArray(JMSGUser)	被加入/被删除群组黑名单的用户列表

监听方法

/*!
 * @abstract 群组黑名单变更通知
 *
 * @param event 群组黑名单事件列表
 *
 * @discussion 事件具体相关属性请查看 JMSGGroupBlacklistChangeEvent 类
 *
 * @since 3.8.0
 */
- (void)onReceiveGroupBlacklistChangeEvents:(NSArray<__kindof JMSGGroupBlacklistChangeEvent*>*)events;

聊天室事件

聊天室管理员变更事件通知

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
chatRoom	JMSGChatRoom	聊天室
fromUser	JMSGUser	事件操作者
targetList	NSArray(JMSGUser)	被添加/被删除聊天室管理员的用户列表

监听方法

/*!
 * @abstract 聊天室管理员变更通知
 *
 * @param event 管理员事件列表
 *
 * @discussion 事件具体相关属性请查看 JMSGChatRoomAdminChangeEvent 类
 *
 * @since 3.8.0
 */
- (void)onReceiveChatRoomAdminChangeEvents:(NSArray<__kindof JMSGChatRoomAdminChangeEvent*>*)events;

聊天室黑名单变更事件通知

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
chatRoom	JMSGChatRoom	聊天室
fromUser	JMSGUser	事件操作者
targetList	NSArray(JMSGUser)	被添加/被删除聊天室黑名单的用户列表

监听方法

/*!
 * @abstract 聊天室黑名单变更通知
 *
 * @param event 黑名单事件列表
 *
 * @discussion 事件具体相关属性请查看 JMSGChatRoomBlacklisChangetEvent 类
 *
 * @since 3.8.0
 */
- (void)onReceiveChatRoomBlacklistChangeEvents:(NSArray<__kindof JMSGChatRoomBlacklisChangetEvent*>*)events;

好友事件

可监听：加好友、删除好友、好友更新等事件，具体相关属性请查看 JMSGFriendNotificationEvent

注意：好友相关事件 SDK 并没有做本地化存储，上层想要做记录这些事件，则需要上层自己实现存储。

事件

属性/方法	类型/返回值	说明
eventType	JMSGEventNotificationType	事件类型
eventID	NSString	事件的 id
getReason	NSString	获取事件发生的理由
getFromUsername	NSString	事件发送者的username
getFromUser	JMSGUser	获取事件发送者user

监听方法

/*!
 * @abstract 监听好友相关事件
 *
 * @discussion 可监听：加好友、删除好友、好友更新等事件
 *
 * @since 3.5.0
 */
@optional
- (void)onReceiveFriendNotificationEvent:(JMSGFriendNotificationEvent *)event;

透传命令事件

命令透传发送后台不会为其离线保存，只会在对方用户在线的前提下将命令推送给对方。
SDK 收到命令之后也不会本地保存，不发送通知栏通知，整体快速响应。
透传命令分为会话间透传、设备间透传
开发者可以通过命令透传拓展一些在线场景下的辅助功能，如：实现输入状态提示、控制其他端下线等。事件相关属性请查看 JMSGMessageTransparentEvent 类

事件

属性	类型	说明
eventType	JMSGEventNotificationType	事件类型
transMessageType	JMSGTransMessageType	消息透传的类型,单聊、群聊、设备间透传消息
sendUser	JMSGUser	透传消息的发送者
target	id	透传消息的目标对象，JMSGUser、JMSGGroup
transparentText	NSString	透传消息内容
conversation	JMSGConversation	透传消息所属会话

监听方法

/*!
 * @abstract 监听消息透传事件
 *
 * @param transparentEvent 下发的通知事件，事件类型请查看 JMSGMessageTransparentEvent 类
 *
 * @discussion 消息透传的类型：单聊、群聊、设备间透传消息
 *
 * @since 3.3.0
 */
@optional
- (void)onReceiveMessageTransparentEvent:(JMSGMessageTransparentEvent *)transparentEvent;