JMSGGroup Class Reference

Inherits from NSObject
Declared in JMSGGroup.h

Overview

群组

群组表示一组用户, 是群组聊天的聊天对象.

主要包含两类 API: 群组信息维护, 群组成员变更.

Group Info Maintenance 群组信息维护

+ createGroupWithName:desc:memberArray:completionHandler:

创建群组(只能创建私有群)

+ (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

Parameters

groupName

群组名称

groupDesc

群组描述信息

usernameArray

初始成员列表。NSArray 里的类型是 NSString

handler

结果回调。正常返回 resultObject 的类型是 JMSGGroup。

Discussion

向服务器端提交创建群组请求,返回生成后的群组对象. 返回群组对象, 群组ID是App 需要关注的, 是后续各种群组维护的基础.

Declared In

JMSGGroup.h

+ createGroupWithGroupInfo:memberArray:completionHandler:

创建群组(可创建私有群、公开群)

+ (void)createGroupWithGroupInfo:(JMSGGroupInfo *)groupInfo memberArray:(NSArray JMSG_GENERIC ( __kindof NSString *) *JMSG_NULLABLE)usernameArray completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

groupInfo

群信息类,如:群名、群类型等,详细请查看 JMSGGroupInfo

usernameArray

初始成员列表。NSArray 里的类型是 NSString

handler

结果回调。正常返回 resultObject 的类型是 JMSGGroup。

Discussion

向服务器端提交创建群组请求,返回生成后的群组对象. 返回群组对象, 群组ID是App 需要关注的, 是后续各种群组维护的基础.

Declared In

JMSGGroup.h

+ updateGroupInfoWithGroupId:name:desc:completionHandler:

更新群组信息

+ (void)updateGroupInfoWithGroupId:(NSString *)groupId name:(NSString *JMSG_NULLABLE)groupName desc:(NSString *JMSG_NULLABLE)groupDesc completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

groupId

待更新的群组ID

groupName

新名称

groupDesc

新描述

handler

结果回调. 正常返回时, resultObject 为 nil.

Discussion

注意:namedesc 不允许传空字符串

Declared In

JMSGGroup.h

+ updateGroupInfoWithGid:groupInfo:completionHandler:

更新群信息(统一字段上传)

+ (void)updateGroupInfoWithGid:(NSString *)gid groupInfo:(JMSGGroupInfo *)groupInfo completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

gid

群组 id

groupInfo

群信息类,详细请查看 JMSGGroupInfo

handler

结果回调. 正常返回时, resultObject 为 nil.

Discussion

注意:修改群名称和群描述时参数不允许传空字符串,群类型不允许修改

Declared In

JMSGGroup.h

+ updateGroupAvatarWithGroupId:avatarData:avatarFormat:completionHandler:

更新群头像(支持传图片格式)

+ (void)updateGroupAvatarWithGroupId:(NSString *JMSG_NONNULL)groupId avatarData:(NSData *JMSG_NONNULL)avatarData avatarFormat:(NSString *JMSG_NULLABLE)avatarFormat completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

groupId

待更新的群组ID

avatarData

头像数据

avatarFormat

头像格式,可以为空,不包括"."

handler

回调

Discussion

头像格式参数直接填格式名称,不要带点。正确:@“png",错误:@”.png"

Declared In

JMSGGroup.h

+ groupInfoWithGroupId:completionHandler:

获取群组信息

+ (void)groupInfoWithGroupId:(NSString *)groupId completionHandler:(JMSGCompletionHandler)handler

Parameters

groupId

待获取详情的群组ID

handler

结果回调. 正常返回时 resultObject 类型是 JMSGGroup.

Discussion

如果考虑性能损耗, 在群聊时获取群组信息, 可以获取 JMSGConversation -> target 属性.

Declared In

JMSGGroup.h

+ myGroupArray:

获取我的群组列表

+ (void)myGroupArray:(JMSGCompletionHandler)handler

Parameters

handler

结果回调。正常返回时 resultObject 的类型是 NSArray(NSNumber),数组里的成员类型是JMSGGroup的gid

Discussion

该接口总是向服务器端发起请求。

Declared In

JMSGGroup.h

+ shieldList:

获取所有设置群消息屏蔽的群组

+ (void)shieldList:(JMSGCompletionHandler)handler

Parameters

handler

结果回调。回调参数:

  • resultObject 类型为 NSArray,数组里成员的类型为 JMSGGroup
  • error 错误信息

如果 error 为 nil, 表示设置成功 如果 error 不为 nil,表示设置失败

Discussion

从服务器获取,返回所有设置群消息屏蔽的群组。

Declared In

JMSGGroup.h

+ getPublicGroupInfoWithAppKey:start:count:completionHandler:

分页获取 appkey 下所有公开群信息

+ (void)getPublicGroupInfoWithAppKey:(NSString *JMSG_NULLABLE)appkey start:(NSInteger)start count:(NSInteger)count completionHandler:(JMSGCompletionHandler)handler

Parameters

appkey

群组所在的 AppKey,不填则默认为当前应用 AppKey

start

分页获取的下标,第一页从 index = 0 开始

count

每一页的数量,最大值为500

handler

结果回调,NSArrayJMSGGroupInfo

注意:

返回数据中不是 JMSGGroup 类型,而是 JMSGGroupInfo 类型,只能用于展示信息,如果想要调用相关群组 API 接口则需要通过 gid 获取到 JMSGGroup 对象才可以调用

Declared In

JMSGGroup.h

+ applyJoinGroupWithGid:reason:completionHandler:

申请加入群组

+ (void)applyJoinGroupWithGid:(NSString *JMSG_NONNULL)gid reason:(NSString *JMSG_NULLABLE)reason completionHandler:(JMSGCompletionHandler)handler

Parameters

gid

群组 gid

reason

申请原因

handler

结果回调

Discussion

只有公开群需要申请才能加入,私有群不需要申请。

Declared In

JMSGGroup.h

+ processApplyJoinGroupEventID:gid:joinUser:applyUser:isAgree:reason:handler:

管理员审批入群申请

@patam eventId 入取申请事件的 id,详情请查看 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

Parameters

gid

群组 gid

joinUser

入群的用户

applyUser

发起申请的的用户,如果是主动申请入群则和 member 是相同的

isAgree

是否同意申请,YES : 同意, NO: 不同意

reason

拒绝申请的理由,选填

handler

结果回调

Discussion

只有管理员才有权限审批入群申请,SDK 不会保存申请入群事件(JMSGApplyJoinGroupEvent),上层可以自己封装再保存,或则归档直接保存,以便此接口取值调用。

Declared In

JMSGGroup.h

+ processApplyJoinGroupEvents:isAgree:reason:sendInviter:handler:

管理员审批入群申请(批量接口)

@patam events 入取申请事件的 eventId 数组,详情请查看 JMSGApplyJoinGroupEvent

+ (void)processApplyJoinGroupEvents:(NSArray<__kindofNSString*> *)events isAgree:(BOOL)isAgree reason:(NSString *JMSG_NULLABLE)reason sendInviter:(BOOL)isSendInviter handler:(JMSGCompletionHandler)handler

Parameters

isAgree

是否同意申请,YES : 同意, NO: 不同意

reason

拒绝申请的理由,选填

isSendInviter

是否将结果通知给邀请方,默认是 NO

handler

结果回调

Discussion

批量处理接口,event 下包含的所有被邀请者会被一起审批处理。只有管理员才有权限审批入群申请。

Declared In

JMSGGroup.h

+ dissolveGroupWithGid:handler:

解散群组

@patam gid 需要解散的群组 id

+ (void)dissolveGroupWithGid:(NSString *)gid handler:(JMSGCompletionHandler)handler

Parameters

handler

结果回调,error = nil 表示操作成功

Discussion

只有群主才有权限解散群。

Declared In

JMSGGroup.h

Group basic fields 群组基本属性

  gid

群组ID

@property (nonatomic, strong, readonly) NSString *gid

Discussion

该ID由服务器端生成,全局唯一。可以用于服务器端 API。

Declared In

JMSGGroup.h

  name

群组名称

@property (nonatomic, copy, readonly) NSString *name

Discussion

可用于群组聊天的展示名称

Declared In

JMSGGroup.h

  desc

群组描述信息

@property (nonatomic, copy, readonly) NSString *desc

Declared In

JMSGGroup.h

  level

群组等级

@property (nonatomic, strong, readonly) NSNumber *level

Discussion

不同等级的群组,人数上限不同。当前默认等级 4,人数上限 200。客户端不可更改。

Declared In

JMSGGroup.h

  avatar

群组头像(媒体文件ID)

@property (nonatomic, strong, readonly) NSString *avatar

Discussion

此文件ID仅用于内部更新,不支持外部URL。

Declared In

JMSGGroup.h

  flag

群组设置标志位

@property (nonatomic, strong, readonly) NSNumber *flag

Discussion

这是一个内部状态标志,对外展示仅用于调试目的。客户端不可更改。

Declared In

JMSGGroup.h

  groupType

群组类型

@property (nonatomic, assign, readonly) JMSGGroupType groupType

Discussion

目前群组类型有:公开群、私有群。公开群是有权限设置,入群需要群主审核同意方可入群。

Declared In

JMSGGroup.h

  owner

群主(用户的 username)

@property (nonatomic, copy, readonly) NSString *owner

Discussion

有一套确认群主的策略。简单地说,群创建人是群主;如果群主退出,则是第二个加入的人,以此类似。客户端不可更改。

Declared In

JMSGGroup.h

  ownerAppKey

群主的appKey

@property (nonatomic, copy, readonly) NSString *ownerAppKey

Discussion

当有跨应用群成员与群主同名(username相同)时,可结合用这个ownerAppKey来判断群主。

Declared In

JMSGGroup.h

  maxMemberCount

群组人数上限,

@property (nonatomic, strong, readonly) NSString *maxMemberCount

Discussion

表示当前群组人数上限,客户端不可更改。。

Declared In

JMSGGroup.h

  isNoDisturb

该群是否已被设置为免打扰

@property (nonatomic, assign, readonly) BOOL isNoDisturb

Discussion

YES:是 , NO: 否

Declared In

JMSGGroup.h

  isShieldMessage

该群是否已被设置为消息屏蔽

@property (nonatomic, assign, readonly) BOOL isShieldMessage

Discussion

YES:是 , NO: 否

Declared In

JMSGGroup.h

Group members maintenance 群组成员维护

– memberArray

获取群组成员列表(同步接口,建议使用异步接口)

- (NSArray JMSG_GENERIC ( __kindof JMSGUser *) *)memberArray

Return Value

成员列表. NSArray 里成员类型是 JMSGUser.

Discussion

一般在群组详情界面调用此接口,展示群组的所有成员列表。 本接口只是在本地请求成员列表,不会发起服务器端请求。

Declared In

JMSGGroup.h

– memberArrayWithCompletionHandler:

获取群组成员列表(建议使用 [JMSGGroup memberInfoList:] 接口)

@handler 成员列表. NSArray 里成员类型是 JMSGUser.

- (void)memberArrayWithCompletionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Discussion

一般在群组详情界面调用此接口,展示群组的所有成员列表。 本接口只是在本地请求成员列表,不会发起服务器端请求。

Declared In

JMSGGroup.h

– memberInfoList:

获取所有群成员信息列表

@handler 成员列表. 类型为 NSArray,里面元素为 JMSGGroupMemberInfo.

- (void)memberInfoList:(JMSGCompletionHandler JMSG_NULLABLE)handler

Discussion

返回数据中的 JMSGGroupMemberInfo 包含了成员 user 信息、入群时间、群昵称等

Declared In

JMSGGroup.h

– memberInfoWithUsername:appkey:

获取单个群成员信息

- (JMSGGroupMemberInfo *JMSG_NULLABLE)memberInfoWithUsername:(NSString *JMSG_NONNULL)username appkey:(NSString *JMSG_NULLABLE)appkey

Parameters

username

目标用户 username

appkey

目标用户 appkey,不传则默认本应用 appkey

Return Value

群成员信息对象

Discussion

JMSGGroupMemberInfo 包含了成员 user 信息、入群时间、群昵称等

Declared In

JMSGGroup.h

– changeGroupType:handler:

修改群组类型

- (void)changeGroupType:(JMSGGroupType)type handler:(JMSGCompletionHandler)handler

Parameters

type

群类型,公开群、私有群

handler

结果回调。error = nil 表示成功

Discussion

对于已经创建的群组,可以通过此接口来修改群组的类型

Declared In

JMSGGroup.h

– setIsNoDisturb:handler:

设置群组消息免打扰(支持跨应用设置)

- (void)setIsNoDisturb:(BOOL)isNoDisturb handler:(JMSGCompletionHandler)handler

Parameters

isNoDisturb

是否免打扰 YES:是 NO: 否

handler

结果回调。回调参数:

  • resultObject 相应对象
  • error 错误信息

如果 error 为 nil, 表示设置成功 如果 error 不为 nil,表示设置失败

Discussion

针对单个群组设置免打扰 这个接口支持跨应用设置免打扰

Declared In

JMSGGroup.h

– setIsShield:handler:

设置群组消息屏蔽

- (void)setIsShield:(BOOL)isShield handler:(JMSGCompletionHandler)handler

Parameters

isShield

是否群消息屏蔽 YES:是 NO: 否

handler

结果回调。回调参数: error 为 nil, 表示设置成功

Discussion

针对单个群组设置群消息屏蔽

Declared In

JMSGGroup.h

– setGroupNickname:username:appKey:handler:

设置成员群昵称

- (void)setGroupNickname:(NSString *JMSG_NULLABLE)nickname username:(NSString *JMSG_NONNULL)username appKey:(NSString *JMSG_NULLABLE)appKey handler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

nickname

群昵称

username

目标用户的 username

appKey

目标用户的 appKey,若传入空则默认使用本应用appKey

Declared In

JMSGGroup.h

– groupNicknameWithUsername:appKey:

获取成员的群昵称

- (NSString *JMSG_NULLABLE)groupNicknameWithUsername:(NSString *)username appKey:(NSString *JMSG_NULLABLE)appKey

Parameters

username

群成员 username @patam appKey 群成员 appKey,不传则默认是本应用 appkey

Return Value

群昵称

Discussion

还可以通过获取群成员信息 JMSGGroupMemberInfo 来获取群昵称

Declared In

JMSGGroup.h

– setGroupMemberSilence:username:appKey:handler:

群成员禁言设置

- (void)setGroupMemberSilence:(BOOL)isSilence username:(NSString *JMSG_NONNULL)username appKey:(NSString *JMSG_NULLABLE)appKey handler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

isSilence

是否禁言, YES:是 NO: 否

username

带待设置的用户的 appKey,若传入空则默认使用本应用appKey

handler

结果回调

Discussion

注意: 目前 SDK 只支持群主设置群里某个用户禁言

Declared In

JMSGGroup.h

– isSilenceMemberWithUsername:appKey:

判断用户在该群内是否被禁言

- (BOOL)isSilenceMemberWithUsername:(NSString *JMSG_NONNULL)username appKey:(NSString *JMSG_NULLABLE)appKey

Parameters

username

待判断用户的用户名

appKey

待判断用户的appKey,若传入空则默认使用本应用appKey

Declared In

JMSGGroup.h

– groupSilenceMembers

禁言列表

- (NSArray JMSG_GENERIC ( __kindof JMSGUser *) *)groupSilenceMembers

Return Value

禁言的成员列表. NSArray 里成员类型是 JMSGUser

Discussion

仅在获取群成员成功后此接口才有效

Declared In

JMSGGroup.h

– isAdminMemberWithUsername:appKey:

判断用户是否是管理员

- (BOOL)isAdminMemberWithUsername:(NSString *JMSG_NONNULL)username appKey:(NSString *JMSG_NULLABLE)appKey

Parameters

username

待判断用户的用户名

appKey

待判断用户的appKey,若传入空则默认使用本应用appKey

Declared In

JMSGGroup.h

– groupAdminMembers

管理员列表

- (NSArray JMSG_GENERIC ( __kindof JMSGUser *) *)groupAdminMembers

Return Value

管理员列表. NSArray 里成员类型是 JMSGUser

Discussion

注意:返回列表中不包含群主;仅在获取群成员成功后此接口才有效

Declared In

JMSGGroup.h

– transferGroupOwnerWithUsername:appKey:completionHandler:

移交群主

- (void)transferGroupOwnerWithUsername:(NSString *JMSG_NONNULL)username appKey:(NSString *JMSG_NULLABLE)appkey completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

username

新群主用户名

appkey

新群主用户 AppKey,不填则默认为本应用 AppKey

handler

结果回调。error 为 nil 表示成功.

Declared In

JMSGGroup.h

– addGroupAdminWithUsername:appKey:completionHandler:

添加管理员

- (void)addGroupAdminWithUsername:(NSString *JMSG_NONNULL)username appKey:(NSString *JMSG_NULLABLE)appkey completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

username

用户名

appkey

用户 AppKey,不填则默认为本应用 AppKey

handler

结果回调。error 为 nil 表示成功.

Discussion

注意:非 VIP 应用最多设置 15 个管理员,不包括群主本身

Declared In

JMSGGroup.h

– addGroupAdminWithUsernames:appKey:completionHandler:

批量添加管理员

- (void)addGroupAdminWithUsernames:(NSArray<__kindofNSString*> *)usernames appKey:(NSString *JMSG_NULLABLE)appkey completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Declared In

JMSGGroup.h

– deleteGroupAdminWithUsername:appKey:completionHandler:

删除管理员

- (void)deleteGroupAdminWithUsername:(NSString *)username appKey:(NSString *JMSG_NULLABLE)appkey completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

username

用户名

appkey

用户 AppKey,不填则默认为本应用 AppKey

handler

结果回调。error 为 nil 表示成功.

Declared In

JMSGGroup.h

– deleteGroupAdminWithUsernames:appKey:completionHandler:

批量删除管理员

- (void)deleteGroupAdminWithUsernames:(NSArray<__kindofNSString*> *)usernames appKey:(NSString *JMSG_NULLABLE)appkey completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Declared In

JMSGGroup.h

– addMembersWithUsernameArray:completionHandler:

添加群组成员

- (void)addMembersWithUsernameArray:(NSArray JMSG_GENERIC ( __kindof NSString *) *)usernameArray completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

usernameArray

用户名数组。数组里的成员类型是 NSString

handler

结果回调。正常返回时 resultObject 为 nil.

Declared In

JMSGGroup.h

– addMembersWithUsernameArray:appKey:completionHandler:

添加群组跨应用成员

- (void)addMembersWithUsernameArray:(NSArray JMSG_GENERIC ( __kindof NSString *) *)usernameArray appKey:(NSString *)userAppKey completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

usernameArray

用户名数组。数组里的成员类型是 NSString

userAppKey

用户的 AppKey,这批添加的成员必须在同一个 AppKey 下的用户

handler

结果回调。正常返回时 resultObject 为 nil.

Declared In

JMSGGroup.h

– addMembersWithUsernameArray:appKey:reason:completionHandler:

添加群组成员

- (void)addMembersWithUsernameArray:(NSArray JMSG_GENERIC ( __kindof NSString *) *)usernameArray appKey:(NSString *JMSG_NULLABLE)userAppKey reason:(NSString *JMSG_NULLABLE)reason completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

usernameArray

用户名数组。数组里的成员类型是 NSString

userAppKey

用户的 AppKey,这批添加的成员必须在同一个 AppKey 下的用户

reason

邀请原因,可选

handler

结果回调。正常返回时 resultObject 为 nil.

Declared In

JMSGGroup.h

– removeMembersWithUsernameArray:completionHandler:

删除群组成员

- (void)removeMembersWithUsernameArray:(NSArray JMSG_GENERIC ( __kindof NSString *) *)usernameArray completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

usernameArray

用户名数据. 数组里的成员类型是 NSString

handler

结果回调。正常返回时 resultObject 为 nil.

Declared In

JMSGGroup.h

– removeMembersWithUsernameArray:appKey:completionHandler:

删除群组跨应用成员

- (void)removeMembersWithUsernameArray:(NSArray JMSG_GENERIC ( __kindof NSString *) *)usernameArray appKey:(NSString *)userAppKey completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

usernameArray

用户名数据. 数组里的成员类型是 NSString

handler

结果回调。正常返回时 resultObject 为 nil.

Declared In

JMSGGroup.h

– exit:

退出当前群组(当前用户)

- (void)exit:(JMSGCompletionHandler JMSG_NULLABLE)handler

Parameters

handler

结果回调。正常返回时 resultObject 为 nil。

Declared In

JMSGGroup.h

– thumbAvatarData:

获取头像缩略图文件数据

- (void)thumbAvatarData:(JMSGAsyncDataHandler)handler

Parameters

handler

结果回调。回调参数:

  • data 头像数据;
  • objectId 群组 gid;
  • error 不为nil表示出错;

如果 error 为 nil, data 也为 nil, 表示没有头像数据.

Discussion

需要展示缩略图时使用。 如果本地已经有文件,则会返回本地,否则会从服务器上下载。

Declared In

JMSGGroup.h

– thumbAvatarLocalPath

获取头像缩略文件的本地路径

- (NSString *JMSG_NULLABLE)thumbAvatarLocalPath

Return Value

返回本地路,返回值只有在下载完成之后才有意义

Declared In

JMSGGroup.h

– largeAvatarData:

获取头像大图文件数据

- (void)largeAvatarData:(JMSGAsyncDataHandler)handler

Parameters

handler

结果回调。回调参数:

  • data 头像数据;
  • objectId 群组 gid;
  • error 不为nil表示出错;

如果 error 为 nil, data 也为 nil, 表示没有头像数据.

Discussion

需要展示大图图时使用 如果本地已经有文件,则会返回本地,否则会从服务器上下载。

Declared In

JMSGGroup.h

– largeAvatarLocalPath

获取头像大图文件的本地路径

- (NSString *JMSG_NULLABLE)largeAvatarLocalPath

Return Value

返回本地路,返回值只有在下载完成之后才有意义

Declared In

JMSGGroup.h

– memberDisplayName:

获取群成员的展示名

- (NSString *)memberDisplayName:(UInt64)memberUid

Parameters

memberUid

群成员的 uid(即:[JMSGUser uid]

Discussion

展示优先级:群昵称 > 好友备注(user.noteName) > 用户昵称(user.nickname) > 用户名(user.username)

Declared In

JMSGGroup.h

– displayName

获取群组的展示名

- (NSString *)displayName

Discussion

如果 group.name 为空, 则此接口会拼接群组前 5 个成员的展示名返回.

Declared In

JMSGGroup.h