群组管理

          /*!
 * @abstract 创建群组(只能创建私有群)
 *
 * @param groupName 群组名称
 * @param groupDesc 群组描述信息
 * @param usernameArray 初始成员列表。NSArray 里的类型是 NSString
 * @param handler 结果回调。正常返回 resultObject 的类型是 JMSGGroup。
 *
 * @discussion 向服务器端提交创建群组请求，返回生成后的群组对象.
 * 返回群组对象, 群组ID是App 需要关注的, 是后续各种群组维护的基础.
 */
+ (void)createGroupWithName:(NSString * JMSG_NULLABLE )groupName
                       desc:(NSString *JMSG_NULLABLE)groupDesc
                memberArray:(NSArray JMSG_GENERIC(__kindof NSString *) *JMSG_NULLABLE)usernameArray
          completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 创建群组（可创建私有群、公开群）
 *
 * @param groupInfo     群信息类，如：群名、群类型等，详细请查看 JMSGGroupInfo 类
 * @param usernameArray 初始成员列表。NSArray 里的类型是 NSString
 * @param handler       结果回调。正常返回 resultObject 的类型是 JMSGGroup。
 *
 * @discussion 向服务器端提交创建群组请求，返回生成后的群组对象.
 * 返回群组对象, 群组ID是App 需要关注的, 是后续各种群组维护的基础.
 */
+ (void)createGroupWithGroupInfo:(JMSGGroupInfo *)groupInfo
                     memberArray:(NSArray JMSG_GENERIC(__kindof NSString *) *JMSG_NULLABLE)usernameArray
               completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 解散群组
 *
 * @patam gid     需要解散的群组 id
 * @param handler 结果回调,error = nil 表示操作成功
 *
 * @discussion 只有群主才有权限解散群。
 */
+ (void)dissolveGroupWithGid:(NSString *)gid handler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 获取群组信息
 *
 * @param groupId 待获取详情的群组ID
 * @param handler 结果回调. 正常返回时 resultObject 类型是 JMSGGroup.
 *
 * @discussion 如果考虑性能损耗, 在群聊时获取群组信息, 可以获取 JMSGConversation -> target 属性.
 */
+ (void)groupInfoWithGroupId:(NSString *)groupId
           completionHandler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 更新群信息（统一字段上传）
 *
 * @param gid         群组 id
 * @param groupInfo   群信息类，详细请查看 JMSGGroupInfo 类
 * @param handler     结果回调. 正常返回时, resultObject 为 nil.
 *
 * @discussion 注意：修改群名称和群描述时参数不允许传空字符串，群类型不允许修改
 */
+ (void)updateGroupInfoWithGid:(NSString *)gid
                     groupInfo:(JMSGGroupInfo *)groupInfo
             completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 获取头像缩略图文件数据
 *
 * @param handler 结果回调。回调参数:
 *
 * - data     头像数据;
 * - objectId 群组 gid;
 * - error    不为nil表示出错;
 *
 * 如果 error 为 nil, data 也为 nil, 表示没有头像数据.
 *
 * @discussion 需要展示缩略图时使用。
 * 如果本地已经有文件，则会返回本地，否则会从服务器上下载。
 */
- (void)thumbAvatarData:(JMSGAsyncDataHandler)handler;

        

          /*!
 * @abstract 更新群头像（支持传图片格式）
 *
 * @param groupId         待更新的群组ID
 * @param avatarData      头像数据
 * @param avatarFormat    头像格式，可以为空，不包括"."
 * @param handler         回调
 *
 * @discussion 头像格式参数直接填格式名称，不要带点。正确：@"png"，错误：@".png"
 */
+ (void)updateGroupAvatarWithGroupId:(NSString *JMSG_NONNULL)groupId
                          avatarData:(NSData *JMSG_NONNULL)avatarData
                        avatarFormat:(NSString *JMSG_NULLABLE)avatarFormat
                   completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 获取头像缩略文件的本地路径
 *
 * @return 返回本地路，返回值只有在下载完成之后才有意义
 */
- (NSString *JMSG_NULLABLE)thumbAvatarLocalPath;

        

          /*!
 * @abstract 修改群组类型
 *
 * @param type    群类型，公开群、私有群
 * @param handler 结果回调。error = nil 表示成功
 *
 * @discussion 对于已经创建的群组，可以通过此接口来修改群组的类型
 */
- (void)changeGroupType:(JMSGGroupType)type handler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 获取所有群成员信息列表
 *
 * @handler 成员列表. 类型为 NSArray，里面元素为 JMSGGroupMemberInfo.
 *
 * @discussion 返回数据中的 JMSGGroupMemberInfo 包含了成员 user 信息、入群时间、群昵称等
 */
- (void)memberInfoList:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 添加群组成员
 *
 * @param usernameArray 用户名数组。数组里的成员类型是 NSString
 * @param userAppKey    用户的 AppKey，这批添加的成员必须在同一个 AppKey 下的用户
 * @param reason        邀请原因，可选
 *
 * @param handler 结果回调。正常返回时 resultObject 为 nil.
 */
- (void)addMembersWithUsernameArray:(NSArray JMSG_GENERIC(__kindof NSString *) *)usernameArray
                             appKey:(NSString *JMSG_NULLABLE)userAppKey
                             reason:(NSString *JMSG_NULLABLE)reason
                  completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 删除群组成员
 *
 * @param usernameArray 用户名数据. 数组里的成员类型是 NSString
 * @param handler 结果回调。正常返回时 resultObject 为 nil.
 */
- (void)removeMembersWithUsernameArray:(NSArray JMSG_GENERIC(__kindof NSString *) *)usernameArray
                     completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 移交群主
 *
 * @param username 新群主用户名
 * @param appkey   新群主用户 AppKey，不填则默认为本应用 AppKey
 * @param handler 结果回调。error 为 nil 表示成功.
 */
- (void)transferGroupOwnerWithUsername:(NSString *JMSG_NONNULL)username
                                appKey:(NSString *JMSG_NULLABLE)appkey
                     completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 设置成员群昵称
 *
 * @param nickname 群昵称
 * @param username 目标用户的 username
 * @param appKey   目标用户的 appKey,若传入空则默认使用本应用appKey
 */
- (void)setGroupNickname:(NSString *JMSG_NULLABLE)nickname
                username:(NSString *JMSG_NONNULL)username
                  appKey:(NSString *JMSG_NULLABLE)appKey
                 handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 管理员列表
 *
 * @return 管理员列表. NSArray 里成员类型是 JMSGUser
 *
 * @discussion 注意：返回列表中不包含群主；仅在获取群成员成功后此接口才有效
 */
- (NSArray JMSG_GENERIC(__kindof JMSGUser *)*)groupAdminMembers;

        

          /*!
 * @abstract 添加管理员
 *
 * @param usernames 用户名列表
 * @param appkey   用户 AppKey，不填则默认为本应用 AppKey
 * @param handler 结果回调。error 为 nil 表示成功.
 *
 * @discussion 注意：非 VIP 应用最多设置 15 个管理员，不包括群主本身
 */
- (void)addGroupAdminWithUsernames:(NSArray <__kindof NSString *>*)usernames
                            appKey:(NSString *JMSG_NULLABLE)appkey
                 completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 删除管理员
 *
 * @param usernames 用户名 列表
 * @param appkey   用户 AppKey，不填则默认为本应用 AppKey
 * @param handler 结果回调。error 为 nil 表示成功.
 */
- (void)deleteGroupAdminWithUsernames:(NSArray <__kindof NSString *>*)usernames
                               appKey:(NSString *JMSG_NULLABLE)appkey
                    completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 设置群组消息屏蔽
 *
 * @param isShield 是否群消息屏蔽 YES:是 NO: 否
 * @param handler 结果回调。回调参数： error 为 nil, 表示设置成功
 *
 * @discussion 针对单个群组设置群消息屏蔽
 */
- (void)setIsShield:(BOOL)isShield handler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 该群是否已被设置为消息屏蔽
 *
 * @discussion YES:是 , NO: 否
 */
@property(nonatomic, assign, readonly) BOOL isShieldMessage;

        

          /*!
 * @abstract 获取所有设置群消息屏蔽的群组
 *
 * @param handler 结果回调。回调参数：
 *
 * - resultObject 类型为 NSArray，数组里成员的类型为 JMSGGroup
 * - error 错误信息
 *
 * 如果 error 为 nil, 表示设置成功
 * 如果 error 不为 nil,表示设置失败
 *
 * @discussion 从服务器获取，返回所有设置群消息屏蔽的群组。
 */
+ (void)shieldList:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 创建@人的群聊消息
 *
 * @param content 消息内容对象
 * @param groupId 群聊ID
 * @param at_list @对象的数组
 *
 * #### 注意：
 *
 * 1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存；
 *
 * 2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:]
 */
+ (JMSGMessage *)createGroupMessageWithContent:(JMSGAbstractContent *)content
                                       groupId:(NSString *)groupId
                                       at_list:(NSArray<__kindof JMSGUser *> *)at_list;

        

          /*!
 * @abstract 创建@所有人的群聊消息
 *
 * @param content 消息内容对象
 * @param groupId 群聊ID
 *
 * #### 注意：
 *
 * 1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存；
 *
 * 2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:]
 */
+ (JMSGMessage *)createGroupAtAllMessageWithContent:(JMSGAbstractContent *)content
                                            groupId:(NSString *)groupId;

        

          /*!
 * @abstract 是否是@自己的消息（只针对群消息，单聊消息无@功能）
 */
- (BOOL)isAtMe;

        

          /*!
 * @abstract 是否是@所有人的消息（只针对群消息，单聊消息无@功能）
 */
- (BOOL)isAtAll;

        

          /*!
 * @abstract 获取消息体中所有@对象（只针对群消息，单聊消息无@功能）
 *
 * @param handler 结果回调。回调参数：
 *
 * - resultObject 类型为 NSArray，数组里成员的类型为 JMSGUser
 * 注意：如果该消息为@所有人消息时，resultObject 返回nil，可以通过 isAtAll 接口来判断是否是@所有人的消息
 * - error 错误信息
 *
 * 如果 error 为 nil, 表示获取成功
 * 如果 error 不为 nil,表示获取失败
 *
 * @discussion 从服务器获取，返回消息的所有@对象。
 */
- (void)getAt_List:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 发送@人消息（已经创建好对象的）
 *
 * @param message 通过消息创建类接口，创建好的消息对象
 * @param userList @对象的数组
 *
 * @discussion 发送消息的多个接口，都未在方法上直接提供回调。你应通过 JMSGMessageDelegate中的onReceiveMessage: error:方法来注册消息发送结果
 */
- (void)sendMessage:(JMSGMessage *)message at_list:(NSArray<__kindof JMSGUser *> *)userList;

        

          /*!
 * @abstract 发送@所有人消息（已经创建好对象的）
 *
 * @param message 通过消息创建类接口，创建好的消息对象
 *
 * @discussion 发送消息的多个接口，都未在方法上直接提供回调。你应通过 JMSGMessageDelegate中的onReceiveMessage: error:方法来注册消息发送结果
 */
- (void)sendAtAllMessage:(JMSGMessage *)message;

        

          /*!
 * @abstract 申请加入群组
 *
 * @param gid     群组 gid
 * @param reason   申请原因
 * @param handler 结果回调
 *
 * @discussion 只有公开群需要申请才能加入，私有群不需要申请。
 */
+ (void)applyJoinGroupWithGid:(NSString *JMSG_NONNULL)gid
                       reason:(NSString *JMSG_NULLABLE)reason
            completionHandler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 管理员审批入群申请
 *
 * @patam eventId     入取申请事件的 id，详情请查看 JMSGApplyJoinGroupEvent 类
 * @param gid         群组 gid
 * @param joinUser    入群的用户
 * @param applyUser   发起申请的的用户，如果是主动申请入群则和 member 是相同的
 * @param isAgree     是否同意申请，YES : 同意， NO: 不同意
 * @param reason      拒绝申请的理由，选填
 * @param handler     结果回调
 *
 * @discussion 只有管理员才有权限审批入群申请，SDK 不会保存申请入群事件(JMSGApplyJoinGroupEvent)，上层可以自己封装再保存，或则归档直接保存，以便此接口取值调用。
 */
+ (void)processApplyJoinGroupEventID:(NSString *JMSG_NONNULL)eventId
                                 gid:(NSString *JMSG_NONNULL)gid
                            joinUser:(JMSGUser *JMSG_NONNULL)joinUser
                           applyUser:(JMSGUser *JMSG_NONNULL)applyUser
                             isAgree:(BOOL)isAgree
                              reason:(NSString *JMSG_NULLABLE)reason
                             handler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 设置群成员禁言（可设置禁言时间）
 *
 * @param silenceTime 禁言时间戳，单位：毫秒，必须不小于5分钟，不大于1年
 * @param usernames   用户的 username 数组，一次最多500人
 * @param appKey      用户的 appKey，若传入空则默认使用本应用appKey，同一次设置的 usernames 必须在同一个 AppKey 下
 * @param handler     结果回调，error = nil 时，表示成功
 *
 * @discussion 只有群主和管理员可设置；设置成功的话上层会收到相应下发事件。
 *
 * @since 3.8.1
 */
- (void)addGroupSilenceWithTime:(SInt64)silenceTime
                      usernames:(NSArray *JMSG_NONNULL)usernames
                         appKey:(NSString *JMSG_NULLABLE)appkey
                        handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 取消群成员禁言
 *
 * @param usernames  用户的 username 数组，一次最多500人
 * @param appKey     用户的 appKey，若传入空则默认使用本应用appKey，同一次设置的 usernames 必须在同一个 AppKey 下
 * @param handler   结果回调，error = nil 时，表示成功
 *
 * @discussion 只有群主和管理员可设置；取消成功的话上层会收到相应下发事件。
 *
 * @since 3.8.1
 */
- (void)deleteGroupSilenceWithUsernames:(NSArray *JMSG_NONNULL)usernames
                                appKey:(NSString *JMSG_NULLABLE)appkey
                               handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 禁言列表
 *
 * @param handler 结果回调，resultObject 是 NSArray 类型，元素是 JMSGMemberSilenceInfo
 *
 * @discussion 返回的 JMSGMemberSilenceInfo 对象有 user 信息，通过 [JMSGGroup memberInfoWithUsername:appkey:] 可再次获取到 JMSGGroupMemberInfo 信息
 *
 * @since 3.8.1
 */
- (void)getGroupMemberSilenceList:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 获取禁言状态
 *
 * @param username 用户名
 * @param appKey   用户所在应用 AppKey，不填这默认本应用
 * @param handler  结果回调，resultObject 是 JMSGMemberSilenceInfo 类型；
 *                 若 error == nil && resultObject != nil,该成员已被禁言；
 *                 若 error == nil && resultObject == nil,该成员未被禁言；
 *                 若 error != nil ,请求失败。
 *
 * @discussion 返回的 JMSGMemberSilenceInfo 对象有 user 信息，通过 [JMSGGroup memberInfoWithUsername:appkey:] 可再次获取到 JMSGGroupMemberInfo 信息
 *
 * @since 3.8.1
 */
- (void)getGroupMemberSilenceWithUsername:(NSString *JMSG_NONNULL)username
                                   appKey:(NSString *JMSG_NULLABLE)appKey
                                  handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 发布群公告
 *
 * @param announcement 公告内容，大小必须在 1KB 以内
 * @param sendMessage 发布成功后是否需要发一条消息通知群成员，默认：YES
 * @param handler 结果回调。resultObject 为 JMSGGroupAnnouncement对象， error 为 nil 表示成功.
 *
 * @discussion
 * #### 注意：
 *
 * 如果 sendMessage = NO，则 SDK 不会自动发送消息，上层可以在回调或者收到事件后，自己发送消息；
 * 如果 sendMessage = YES，则在发布公告成功后 SDK 会自动在群里发布一条文本消息，文本内容就是公告内容，另外消息的 extras 里会附带公告的相关数据，上层可根据此数据将 message 对应到相应的公告， extras 里的 key-value 如下，
 *
 *    ```
 *    key(String)       = "jmessage_group_announcement"
 *    value(JsonString) = {
 *                        "id" : 公告 id,
 *                        "text" : 公告内容 text,
 *                        "publisher_uid" : 发布者 uid,
 *                        "ctime" : 公告发布时间,
 *                        "isTop" : 是否置顶,
 *                        "topTime" : 置顶时间,
 *                        "gid" : 群 gid
 *                      }
 *    ```
 * 群公告最多100条，发布公告后会有对应事件下发，上层通过 [JMSGGroupDelegate onReceiveGroupAnnouncementEvents:] 监听
 *
 * @since 3.8.0
 */
- (void)publishGroupAnnouncement:(NSString *JMSG_NONNULL)announcement
                     sendMessage:(BOOL)sendMessage
                         handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 获取群公告列表
 *
 * @param handler 结果回调。resultObject 是 NSArray 类型，元素是 JMSGGroupAnnouncement
 *
 * @since 3.8.0
 */
- (void)groupAnnouncementList:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 删除群公告
 *
 * @param announcementID 公告id
 * @param handler 结果回调。error 为 nil 表示成功.
 *
 * @discussion 删除公告后会有对应事件下发，上层通过 [JMSGGroupDelegate onReceiveGroupAnnouncementEvents:] 监听
 * @since 3.8.0
 */
- (void)deleteGroupAnnouncement:(NSString *JMSG_NONNULL)announcementID
                        handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 置顶/取消置顶 群公告
 *
 * @param isTop 置顶参数，YES:置顶，NO:取消置顶
 * @param ID    公告 id
 * @param handler 结果回调。error 为 nil 表示成功.
 *
 * @discussion 置顶公告后会有对应事件下发，上层通过 [JMSGGroupDelegate onReceiveGroupAnnouncementEvents:] 监听
 * @since 3.8.0
 */
- (void)setGroupAnnouncementTop:(BOOL)isTop
                 announcementID:(NSString *JMSG_NONNULL)ID
                        handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 群黑名单列表
 *
 * @handler 结果回调. resultObject 是 NSArray 类型，元素是 JMSGUser
 *
 * @since 3.8.0
 */
- (void)groupBlacklistHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 添加群黑名单
 *
 * @param usernames 用户名列表
 * @param appkey   用户 appKey，usernames 中的所有用户必须在同一个 AppKey 下，不填则默认为本应用 appKey
 * @param handler 结果回调。error 为 nil 表示成功.
 *
 * @discussion 黑名单上限100个，超出将无法设置成功，被拉入黑名单用户会被主动踢出群组，且无法再次加入.
 * @since 3.8.0
 */
- (void)addGroupBlacklistWithUsernames:(NSArray <__kindof NSString *>*)usernames
                                appKey:(NSString *JMSG_NULLABLE)appKey
                               handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 删除群黑名单
 *
 * @param usernames 用户名列表
 * @param appkey   用户 appKey，usernames 中的所有用户必须在同一个 AppKey 下，不填则默认为本应用 appKey
 * @param handler 结果回调。error 为 nil 表示成功.
 *
 * @since 3.8.0
 */
- (void)deleteGroupBlacklistWithUsernames:(NSArray <__kindof NSString *>*)usernames
                                   appKey:(NSString *JMSG_NULLABLE)appKey
                                  handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 该群是否已被设置为免打扰
 *
 * @discussion YES:是 , NO: 否
 */
@property(nonatomic, assign, readonly) BOOL isNoDisturb;

        

          /*!
 * @abstract 设置群组消息免打扰（支持跨应用设置）
 *
 * @param isNoDisturb 是否免打扰 YES:是 NO: 否
 * @param handler 结果回调。回调参数：
 *
 * - resultObject 相应对象
 * - error 错误信息
 *
 * 如果 error 为 nil, 表示设置成功
 * 如果 error 不为 nil,表示设置失败
 *
 * @discussion 针对单个群组设置免打扰
 * 这个接口支持跨应用设置免打扰
 */
- (void)setIsNoDisturb:(BOOL)isNoDisturb handler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 用户免打扰列表
 *
 * @param handler 结果回调。回调参数：
 *
 * - resultObject 类型为 NSArray，数组里成员的类型为 JMSGUser、JMSGGroup
 * - error 错误信息
 *
 * 如果 error 为 nil, 表示设置成功
 * 如果 error 不为 nil,表示设置失败
 *
 * @discussion 从服务器获取，返回用户的免打扰列表。
 * 建议开发者在 SDK 完全启动之后，再调用此接口获取数据
 */
+ (void)noDisturbList:(JMSGCompletionHandler)handler;