群组

获取群组

SDK 在程序启动时会对本地群信息进行同步,所以只需要调用本地缓存接口获取群就可以了。 SDK 提供了批量获取自己的群接口、以及根据单个群 id 查询的接口。同样 SDK 也提供了远程获取群信息的接口。

本地获取

本地获取所有群组

@protocol QDIMGroupManager <NSObject>


/**
获取所有群组 (本地操作)

@return 返回所有群组
*/
- (nullable NSArray<QDGroup *> *)allMyGroupList;

@end

本地根据群 Id 获取群组

@protocol QDIMGroupManager <NSObject>


/**
根据群组 ID 获取具体的群组信息 (本地操作)

@param groupId 群组 ID
@return 群组信息
*/
- (nullable QDGroup *)groupById:(NSString *)groupId;

@end

由于同步策略只会同步自己所在的群。 对于和用户无关的群,并且获取群的成员信息,需要调用远程接口进行获取

/**
*  获取群信息
*
*  @param groupId    群组ID
*  @param completion 回调
*/
- (void)fetchGroupInfo:(NSString *)groupId completion:(void(^ _Nullable )(QDGroup * _Nullable group, NSArray<QDGroupMember *> * _Nullable userList, NSError * _Nullable error))completion;

创建群组

@protocol QDIMGroupManager <NSObject>

/**
*  创建群组
*
*  @param option     创建群选项
*  @param userList   用户ID列表
*  @param completion 完成后的回调
*/
- (void)createGroup:(QDCreateGroupOption *)option
           userList:(NSArray<NSString *> * _Nullable)userList
         completion:(void (^ _Nullable)(QDGroup * _Nullable group, NSError * _Nullable error))completion;

@end

加入群组

用户可以通过被动接受邀请和主动加入两种方式进入群组。

邀请用户入群

@protocol QDIMGroupManager <NSObject>

/**
邀请用户入群

@param users    用户ID列表
@param groupId  群组ID
@param completion 完成后的回调
*/
- (void)addUsers:(NSArray<NSString *> *)users toGroup:(NSString *)groupId completion:(nullable QDGroupHandler)completion;

@end

请求完成后,被邀请者将直接入群;(QDGroupBeInviteMode 暂时无效)

主动申请入群

@protocol QDIMGroupManager <NSObject>

/**
邀请用户入群

@param users    用户ID列表
@param groupId  群组ID
@param completion 完成后的回调
*/
- (void)addUsers:(NSArray<NSString *> *)users toGroup:(NSString *)groupId completion:(nullable QDGroupHandler)completion;

@end

请求完成后,服务器会下发一条系统消息 QDSystemNotification, type 值为 QDSystemNotificationTypeGroupApply 给群管理员。

管理员可以选择通过或者拒绝申请。

通过群申请


@protocol QDIMGroupManager <NSObject>

/**
*  通过群申请
*
*  @param groupId    群组ID
*  @param userId     申请的用户ID
*  @param completion 完成后的回调
*/
- (void)passApplyToGroup:(NSString *)groupId
                  userId:(NSString *)userId
              completion:(nullable QDGroupHandler)completion;

@end

通过申请后,会自动加入进群组,并在群组中产生一条群通知消息

拒绝申请

@protocol QDIMGroupManager <NSObject>

/**
*  拒绝群申请
*
*  @param groupId      群组ID
*  @param userId       申请的用户ID
*  @param rejectReason 拒绝理由
*  @param completion 完成后的回调
*/
- (void)rejectApplyToGroup:(NSString *)groupId
                    userId:(NSString *)userId
              rejectReason:(nullable NSString *)rejectReason
                completion:(nullable QDGroupHandler)completion;

@end

请求完成后,服务器会下发一条系统消息 QDSystemNotification, type 值为 QDSystemNotificationTypeGroupIviteReject 给申请者。

编辑群组资料

普通成员可以修改自己的群资料,管理员以上权限的群成员可以修改他人群资料以及群组信息。当修改完群组资料后,会收到一条类型为 群组资料变更 (QDGroupNotificationContent) 的群组通知消息,具体可参考 群组通知。

具体包括:

修改群成员昵称

@protocol QDIMGroupManager <NSObject>

/**
*  更新成员群昵称
*
*  @param userId  群成员ID
*  @param newNick 新的群成员昵称
*  @param groupId 群组ID
*  @param completion 完成后的回调
*/
- (void)updateUserNick:(NSString *)userId
               newNick:(NSString *)newNick
               inGroup:(NSString *)groupId
            completion:(nullable QDGroupHandler)completion;

@end

修改群名称


@protocol QDIMGroupManager <NSObject>

/**
*  更新群组名称
*
*  @param groupName 群组名称
*  @param groupId   群组ID
*  @param completion 完成后的回调
*/
- (void)updateGroupName:(NSString *)groupName
                groupId:(NSString *)groupId
             completion:(nullable QDGroupHandler)completion;

@end

修改群头像

@protocol QDIMGroupManager <NSObject>

/**
*  更新群头像
*
*  @param avatarUrl   群头像的url地址
*  @param groupId     群组Id
*  @param completion  完成后的回调
*/
- (void)updateGroupAvatar:(NSString *)avatarUrl
                  groupId:(NSString *)groupId
               completion:(nullable QDGroupHandler)completion;

@end

修改群介绍

@protocol QDIMGroupManager <NSObject>

/**
*  更新群介绍
*
*  @param intro   群介绍
*  @param groupId 群组ID
*  @param completion 完成后的回调
*/
- (void)updateGroupIntro:(NSString *)intro
                 groupId:(NSString *)groupId
              completion:(nullable QDGroupHandler)completion;

@end

新增群公告

@protocol QDIMGroupManager <NSObject>

/**
*  新增群公告
*
*  @param announcement 群公告
*  @param groupId      群组ID
*  @param completion   完成后的回调
*/
- (void)addGroupAnnouncement:(NSString *)announcement
                     groupId:(NSString *)groupId
                  completion:(void (^ _Nullable )(QDGroupAnnouncement  * _Nullable announcement, NSError  * _Nullable error))completion;

@end

删除群公告

@protocol QDIMGroupManager <NSObject>

/**
*  删除群组公告
*
*  @param announcementId 群公告ID
*  @param groupId        群组ID
*  @param completion     完成后的回调
*/
- (void)deleteGroupAnnouncement:(NSString *)announcementId
                        groupId:(NSString *)groupId
                     completion:(nullable QDGroupHandler)completion;

@end

修改群验证方式

@protocol QDIMGroupManager <NSObject>

/**
*  更新群组验证方式
*
*  @param joinMode   验证方式
*  @param groupId    群组ID
*  @param completion 完成后的回调
*/
- (void)updateGroupJoinMode:(QDGroupJoinMode)joinMode
                    groupId:(NSString *)groupId
                 completion:(nullable QDGroupHandler)completion;

@end

修改被邀请人验证方式

@protocol QDIMGroupManager <NSObject>

/**
*  更新群组被邀请人验证方式
*
*  @param beInviteMode 邀请方式
*  @param groupId      群组ID
*  @param completion   完成后的回调
*/
- (void)updateGroupBeInviteMode:(QDGroupBeInviteMode)beInviteMode
                        groupId:(NSString *)groupId
                     completion:(nullable QDGroupHandler)completion;

@end

修改谁可以邀请其他人入群

@protocol QDIMGroupManager <NSObject>

/**
*  更新群组邀请他人方式
*
*  @param inviteMode 邀请方式
*  @param groupId    群组ID
*  @param completion 完成后的回调
*/
- (void)updateGroupInviteMode:(QDGroupInviteMode)inviteMode
                      groupId:(NSString *)groupId
                   completion:(nullable QDGroupHandler)completion;

@end

管理群组权限

群主可以对群进行权限管理,权限管理包括:

添加管理员

@protocol QDIMGroupManager <NSObject>

/**
*  添加管理员
*
*  @param groupId    群组ID
*  @param users      需要添加为管理员的用户ID列表
*  @param completion 完成后的回调
*/
- (void)addManagersToGroup:(NSString *)groupId 
                     users:(NSArray<NSString *> *)users
                completion:(nullable QDGroupHandler)completion;

@end

移除管理员

@protocol QDIMGroupManager <NSObject>

/**
*  移除管理员
*
*  @param groupId    群组ID
*  @param users      需要移除管理员的用户ID列表
*  @param completion 完成后的回调
*/
- (void)removeManagersFromGroup:(NSString *)groupId
                          users:(NSArray<NSString *> *)users
                     completion:(nullable QDGroupHandler)completion;

@end

转让群

@protocol QDIMGroupManager <NSObject>

/**
*  转移群主
*
*  @param groupId    群组ID
*  @param newOwnerId 新群主ID
*  @param completion 完成后的回调
*/
- (void)transferOwnerWithGroup:(NSString *)groupId 
                    newOwnerId:(NSString *)newOwnerId
                    completion:(nullable QDGroupHandler)completion;

@end

群组成员

群组成员信息不同于用户资料,主要是和群组关联的信息。同一个用户在不同群组中自己的群成员信息也不一样。群成员信息包括群昵称,是否禁言,群成员类型等等。

@interface QDGroupMember : NSObject

/**
*  群ID
*/
@property (nullable, nonatomic, copy, readonly)  NSString *groupId;

/**
*  群成员ID
*/
@property (nullable, nonatomic, copy, readonly)  NSString *userId;

/**
用户名
*/
@property (nullable, nonatomic, copy)            NSString *name;

/**
*  群昵称
*/
@property (nullable, nonatomic, copy)            NSString *nickname;

/**
*  群成员类型
*/
@property (nonatomic, assign)                    QDGroupMemberType type;

/**
*  被禁言
*/
@property (nonatomic, assign, readonly)          BOOL isMuted;


@end

对于群成员, SDK 不保证有本地数据,需要调用 - (void)fetchGroupInfo:completion: 。对于同步或主动远程获取过的群成员,SDK会把数据缓存在本地。

当本地缓存群成员资料发生变动时,会通过 QDGroupManagerDelegate 的回调通知上层,详见群组委托

获取群信息,群成员

/**
*  获取群信息
*
*  @param groupId    群组ID
*  @param completion 回调
*/
- (void)fetchGroupInfo:(NSString *)groupId
            completion:(void(^ _Nullable )(QDGroup * _Nullable group, NSArray<QDGroupMember *> * _Nullable userList, NSError * _Nullable error))completion;

用户退群

@protocol QDIMGroupManager <NSObject>

/**
*  退出群组
*
*  @param groupID 群组ID
*  @param completion 回调
*/
- (void)quitGroup:(NSString *)groupID completion:(nullable QDGroupHandler)completion;

@end

踢出用户

@protocol QDIMGroupManager <NSObject>

/**
*  从群组内移除成员
*
*  @param users  用户ID列表
*  @param groupId 群组ID
*  @param completion 完成后的回调
*/
- (void)kickUsers:(NSArray<NSString *> *)users
        fromGroup:(NSString *)groupId
       completion:(nullable QDGroupHandler)completion;

@end

解散群

/**
*  解散群组
*
*  @param groupID 群组ID
*  @param completion 回调
*/
- (void)dismissGroup:(NSString *)groupID completion:(nullable QDGroupHandler)completion;

群解散后,所有群用户关于此群会话会被保留,但是不能能够在此群会话里收发消息。

群组委托

群用户信息更新,退群,入群等操作,会触发 SDK 的群委托事件:

@protocol QDGroupManagerDelegate <NSObject>

/**
*  群组增加回调
*
*  @param group 添加的群组
*/
- (void)onGroupAdded:(QDGroup *)group;

/**
*  群组更新回调
*
*  @param group 更新的群组
*/
- (void)onGroupUpdated:(QDGroup *)group;

/**
*  群组移除回调
*
*  @param group 被移除的群组
*/
- (void)onGroupRemoved:(QDGroup *)group;

/**
*  群组成员变动回调,包括数量增减以及成员属性变动
*
*  @param group 变动的群组
*/
- (void)onGroupMemeberChanged:(QDGroup *)group;


@end

群组通知

群组通知是一种消息类型 ( QDMessageTypeNotify ) ,用户在创建群或者进入群成功之后,任何关于群的变动,服务器都会下发一条群通知消息。群通知消息和其他消息一样,可从 QDIMChatManager 提供的消息查询接口中获取。

群组通知解析步骤:

  • 解析 QDMessage 中的 messageObject 字段,强类型转换为 QDNotificationObject。
  • 解析 QDNotificationObject 中的 content 字段,得到父类 QDNotificationContent。
  • 根据 QDNotificationContent 中的 notificationType 字段,将父类 QDNotificationContent 强类型转化为 QDGroupNotificationContent。群组通知的具体类型可以通过 QDGroupNotificationContent 的 operationType 解析。

SDK 在收到群通知之后,会对本地缓存的群信息做出对应的修改,然后触发与修改相对应的委托事件回调。

群通知是接收型的消息,开发者不应该自己手动去创建和发送群通知消息。

@interface QDGroupNotificationContent : QDNotificationContent

/**
群组Id
*/
@property (nonatomic, copy, readonly)     NSString *groupId;

/**
群组名称
*/
@property (nonatomic, copy, readonly)     NSString *groupName;

/**
操作类型
*/
@property (nonatomic, assign, readonly)   QDGroupOperationType  operationType;

/**
操作发起者ID
*/
@property (nullable, nonatomic, copy, readonly) NSString    *sourceID;

/**
被操作者ID列表
*/
@property (nullable, nonatomic, copy, readonly) NSArray<NSString *> *targetIDs;

/**
群通知扩展信息
*/
@property (nullable, nonatomic, readonly)       NSDictionary *notifyExt;

/**
额外信息
@discussion 禁言时  attachment  为  QDMuteGroupMemberAttachment
*/
@property (nullable,nonatomic,strong,readonly)   id attachment;


@end

/**
禁言通知的额外信息
*/
@interface QDMuteGroupMemberAttachment : NSObject

/**
是否被禁言
@discussion YES 为禁言,NO 为 解除禁言
*/
@property (nonatomic, assign, readonly)  BOOL  flag;

@end

/**
群公告通知的额外信息
*/
@interface QDGroupAnnouncementAttachment : NSObject

/**
群公告内容
*/
@property (nonatomic, copy, readonly)  NSString  *content;

@end

群消息推送设置

@protocol QDIMGroupManager <NSObject>

/**
*  更新群组的通知状态
*
*  @param notify     是否接收消息通知
*  @param groupId    群组Id
*  @param completion 完成后的回调
*/
- (void)updateNotifyState:(BOOL)notify 
                 forGroup:(NSString *)groupId
               completion:(QDGroupHandler)completion;

@end

查询接口

@protocol QDIMGroupManager <NSObject>

/**
*  是否需要消息通知
*
*  @param  groupId 群组Id
*  @return 是否需要消息通知
*/
- (BOOL)notifyForNewMsg:(NSString *)groupId;

@end

群禁言

禁言群成员

@protocol QDIMGroupManager <NSObject>

/**
*  群成员禁言
*
*  @param mute       是否禁言
*  @param userId     用户ID
*  @param groupId    群组ID
*  @param completion 完成后的回调
*/
- (void)updateMuteState:(BOOL)mute 
userId:(NSString *)userId
inGroup:(NSString *)groupId
completion:(nullable QDGroupHandler)completion;

@end

禁言用户后,服务器会下发一条提示该用户被禁言的群组通知消息。

禁言群体普通成员

@protocol QDIMGroupManager <NSObject>

/**
*  禁言群全体普通成员
*
*  @param mute       是否禁言
*  @param groupId    群组ID
*  @param completion 完成后的回调
*/
- (void)updateMuteState:(BOOL)mute inGroup:(NSString *)groupId completion:(nullable QDGroupHandler)completion;

@end

该接口用于操作对于整个群的普通成员的禁言、解禁,只有群主、管理员有这个权限。

查询禁言用户列表

@protocol QDIMGroupManager <NSObject>

/**
*  获取群内被禁言的成员列表
*
*  @param teamId     群组ID
*  @param completion 完成后的回调
*/
- (void)fetchGroupMutedMembers:(NSString *)teamId
                    completion:(void (^ __nullable)(NSError * __nullable error, NSArray<QDGroupMember *> * __nullable members))completion;


/**
*  获取群禁言列表
*
*  @param groupId 群组ID
*  @return 群禁言成员列表
*/
- (NSArray<QDGroupMember *> *)groupMutesInGroup:(NSString *)groupId;

@end

查询群的全体禁言状态

此状态定义在 QDGroup 中,属性 isMute