JMSGConversation Class Reference
Inherits from | NSObject |
---|---|
Declared in | JMSGConversation.h |
Overview
会话
会话是整个 IM 的核心. 所有的消息行为都是基于"会话"的.
会话由会话类型, 会话对象组成. 比如: 与某username的单聊, 某个groupId的群聊.
几乎所有的消息行为, 都是由本类 JMSGConversation 提供的. 而聊天对象的信息, 则通过 [target] 来直接访问到.
JMSGMessage 上提供了部分消息相关 API, 是快捷方式的概念, 其背后还是依赖于会话的. 提供这个快捷方式的目的在于: 某些聊天场景简单的应用, 可能不必去理解"会话"这个概念, 只是简单地收发消息即可.
本类主要提供两类 API: 会话类, 消息类.
设计提示: 考虑到会话列表性能问题, SDK 把一些会话信息冗余到了会话数据库表里, 从而只需要读取一张表. 设计上准备, 在会话列表时, 不要访问会话对象的 target 对象. 只是进入一个会话(聊天界面)时, 才会访问 target 对象.
Conversation Operations 会话相关操作
+ singleConversationWithUsername:
获取单聊会话
+ (JMSGConversation *JMSG_NULLABLE)singleConversationWithUsername:(NSString *)username
Parameters
username |
单聊对象 username |
---|
Discussion
如果会话还不存在,则返回 nil
Declared In
JMSGConversation.h
+ singleConversationWithUsername:appKey:
获取跨应用单聊会话
+ (JMSGConversation *JMSG_NULLABLE)singleConversationWithUsername:(NSString *)username appKey:(NSString *)userAppKey
Declared In
JMSGConversation.h
+ groupConversationWithGroupId:
获取群聊会话
+ (JMSGConversation *JMSG_NULLABLE)groupConversationWithGroupId:(NSString *)groupId
Parameters
groupId |
群聊群组ID。此 ID 由创建群组时返回的。 |
---|
Discussion
如果会话还不存在,则返回 nil
Declared In
JMSGConversation.h
+ chatRoomConversationWithRoomId:
获取聊天室会话
+ (JMSGConversation *JMSG_NULLABLE)chatRoomConversationWithRoomId:(NSString *)roomId
Parameters
roomId |
聊天室 ID |
---|
Discussion
如果会话还不存在,则返回 nil
Declared In
JMSGConversation.h
+ createSingleConversationWithUsername:completionHandler:
创建单聊会话
+ (void)createSingleConversationWithUsername:(NSString *)username completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler
Parameters
username |
单聊对象 username |
---|---|
handler |
结果回调。正常返回时 resultObject 类型为 JMSGConversation。 |
Discussion
如果会话已经存在,则直接返回。如果不存在则创建。 创建会话时如果发现该 username 的信息本地还没有,则需要从服务器上拉取。 服务器端如果找不到该 username,或者某种原因查找失败,则创建会话失败。
Declared In
JMSGConversation.h
+ createSingleConversationWithUsername:appKey:completionHandler:
创建跨应用单聊会话
+ (void)createSingleConversationWithUsername:(NSString *)username appKey:(NSString *)userAppKey completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler
Declared In
JMSGConversation.h
+ createGroupConversationWithGroupId:completionHandler:
创建群聊会话
+ (void)createGroupConversationWithGroupId:(NSString *)groupId completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler
Parameters
groupId |
群聊群组ID。由创建群组时返回。 |
---|---|
handler |
结果回调。正常返回时 resultObject 类型为 JMSGConversation。 |
Discussion
如果会话已经存在,则直接返回。如果不存在则创建。 创建会话时如果发现该 groupId 的信息本地还没有,则需要从服务器端上拉取。 如果从服务器上获取 groupId 的信息不存在或者失败,则创建会话失败。
Declared In
JMSGConversation.h
+ createChatRoomConversationWithRoomId:completionHandler:
创建聊天室会话
+ (void)createChatRoomConversationWithRoomId:(NSString *)roomId completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler
Parameters
roomId |
聊天室 ID。 |
---|---|
handler |
结果回调。正常返回时 resultObject 类型为 JMSGConversation。 |
Discussion
如果会话已经存在,则直接返回。如果不存在则创建。 创建会话时如果发现该 roomId 的信息本地还没有,则需要从服务器端上拉取。 如果从服务器上获取 roomId 的信息不存在或者失败,则创建会话失败。
Declared In
JMSGConversation.h
+ deleteSingleConversationWithUsername:
删除单聊会话
+ (BOOL)deleteSingleConversationWithUsername:(NSString *)username
Parameters
username |
单聊用户名 |
---|
Discussion
除了删除会话本身,还会删除该会话下所有的聊天消息。
Declared In
JMSGConversation.h
+ deleteSingleConversationWithUsername:appKey:
删除跨应用单聊会话
+ (BOOL)deleteSingleConversationWithUsername:(NSString *)username appKey:(NSString *)userAppKey
Declared In
JMSGConversation.h
+ deleteGroupConversationWithGroupId:
删除群聊会话
+ (BOOL)deleteGroupConversationWithGroupId:(NSString *)groupId
Parameters
groupId |
群聊群组ID |
---|
Discussion
除了删除会话本身,还会删除该会话下所有的聊天消息。
Declared In
JMSGConversation.h
+ deleteChatRoomConversationWithRoomId:
删除聊天室会话
+ (BOOL)deleteChatRoomConversationWithRoomId:(NSString *)roomId
Parameters
roomId |
聊天室 ID |
---|
Discussion
除了删除会话本身,还会删除该会话下所有的聊天消息。
Declared In
JMSGConversation.h
+ allConversations:
返回 conversation 列表(异步,已排序)
+ (void)allConversations:(JMSGCompletionHandler)handler
Parameters
handler |
结果回调。正常返回时 resultObject 的类型为 NSArray,数组里成员的类型为 JMSGConversation |
---|
Discussion
当前是返回所有的 conversation 列表,不包括聊天室会话,默认是已经排序。
Declared In
JMSGConversation.h
+ allUnsortedConversations:
返回 conversation 列表(异步,没有排序)
+ (void)allUnsortedConversations:(JMSGCompletionHandler)handler
Parameters
handler |
结果回调。正常返回时 resultObject 的类型为 NSArray,数组里成员的类型为 JMSGConversation |
---|
Discussion
返回所有的 conversation 列表,不包括聊天室会话,返回是没有排序的列表。
Declared In
JMSGConversation.h
+ allChatRoomConversation:
返回聊天室 conversation 列表(异步,已排序)
+ (void)allChatRoomConversation:(JMSGCompletionHandler)handler
Parameters
handler |
结果回调。正常返回时 resultObject 的类型为 NSArray,数组里成员的类型为 JMSGConversation |
---|
Discussion
当前是返回所有的chatroom conversation 列表,不包括单聊和群聊会话,默认是已经排序。
Declared In
JMSGConversation.h
+ getAllUnreadCount
获取当前所有会话的未读消息的总数
+ (NSNumber *)getAllUnreadCount
Discussion
获取所有会话未读消息总数,开启免打扰的会话未读数不会加入计数
Declared In
JMSGConversation.h
Conversation Basic Properties 会话基本属性:用于会话列表
latestMessage
最后一条消息
@property (nonatomic, strong, readonly) JMSGMessage *latestMessage
Declared In
JMSGConversation.h
latestMsgTime
会话最近一条消息的创建时间
@property (nonatomic, strong, readonly) NSNumber *latestMsgTime
Discussion
可用于会话排序,单位为毫秒
Declared In
JMSGConversation.h
unreadCount
未读数
@property (nonatomic, strong, readonly) NSNumber *unreadCount
Discussion
有新消息来时, SDK 会对未读数自动加 1
Declared In
JMSGConversation.h
Conversation Extend Properties 会话扩展属性:用于聊天
conversationType
会话类型 - 单聊,群聊,聊天室
@property (nonatomic, assign, readonly) JMSGConversationType conversationType
Discussion
详细定义见 JMSGConversationType
Declared In
JMSGConversation.h
target
聊天对象
@property (nonatomic, strong, readonly) id target
Discussion
需要根据会话类型转型。单聊时转型为 JMSGUser,群聊时转型为 JMSGGroup,聊天时转型为 JMSGChatRoom
注意: 在会话列表上, 请不要使用此属性, 否则有性能问题. 只在进入聊天界面(单个会话) 时使用此属性.
进入会话(聊天界面)后, 访问会话对象的各种信息, 包括群聊的群组成员, 都应使用此属性, 而没有必要再通过接口查询 UserInfo / GroupInfo / ChatRoomInfo.
Declared In
JMSGConversation.h
targetAppKey
会话目标用户所在的 appKey
@property (nonatomic, strong, readonly) NSString *targetAppKey
Discussion
这是为了跨应用聊天而新增的一个字段. 如果此字段为空, 则表示为默认的主应用.
单聊会话时, 如果单聊对象用户不属于主应用, 则此字段会有值.
Declared In
JMSGConversation.h
Message Operations 消息相关操作
– messageWithMessageId:
获取某条消息
- (JMSGMessage *JMSG_NULLABLE)messageWithMessageId:(NSString *)msgId
Parameters
msgId |
本地消息ID |
---|
Discussion
这个接口在正常场景下不需要单独使用到. 获取消息一般应使用 [JSMGConversation messageArrayFromNewestWithOffset::]
注意: 这里的 msgId 概念同 [JMSGMessage msgId], 是本地生成的消息ID, 而非 [JMSGMessage serverMessageId]
Declared In
JMSGConversation.h
– messageArrayFromNewestWithOffset:limit:
同步分页获取最新的消息
- (NSArray JMSG_GENERIC ( __kindof JMSGMessage *) *)messageArrayFromNewestWithOffset:(NSNumber *JMSG_NULLABLE)offset limit:(NSNumber *JMSG_NULLABLE)limit
Parameters
offset |
开始的位置。nil 表示从最初开始。 |
---|---|
limit |
获取的数量。nil 表示不限。 |
Return Value
返回消息列表(数组)。数组成员的类型是 JMSGMessage*
Discussion
排序规则是:最新
参数举例:
- offset = nil, limit = nil,表示获取全部。相当于 allMessages。
- offset = nil, limit = 100,表示从最新开始取 100 条记录。
- offset = 100, limit = nil,表示从最新第 100 条开始,获取余下所有记录。
Declared In
JMSGConversation.h
– allMessages:
异步获取所有消息记录
- (void)allMessages:(JMSGCompletionHandler)handler
Parameters
handler |
结果回调。正常返回时 resultObject 类型为 NSArray,数据成员类型为 JMSGMessage。 |
---|
Discussion
排序规则:最新
Declared In
JMSGConversation.h
– deleteMessageWithMessageId:
删除一条消息
- (BOOL)deleteMessageWithMessageId:(NSString *)msgId
Parameters
msgId |
本地消息ID |
---|
Discussion
注意:如果被删除消息是多媒体消息,也会将本地缓存的多媒体文件删除
Declared In
JMSGConversation.h
– deleteAllMessages
删除全部消息
- (BOOL)deleteAllMessages
Discussion
清空当前会话的所有消息,并清空当前会话的所有本地文件缓存。
Declared In
JMSGConversation.h
– createMessageWithContent:
创建消息对象
- (JMSGMessage *JMSG_NULLABLE)createMessageWithContent:(JMSGAbstractContent *)content
Parameters
content |
消息的内容对象。当前直接的内容对象有: JMSGTextContent, JMSGImageContent, JMSGVoiceContent, JMSGCustomContent |
---|
Return Value
JMSGMessage对象。该对象里包含了 content。
Discussion
这是推荐的创建新的消息拿到 JMSGMessage 对象接口。
此接口创建消息后, SDK 会进行落地, 包括: 消息保存数据库, 媒体文件保存到文件系统. 这意味着, 这个创建后的消息对象, App 可以用来放到 UI 上展示.
新创建的消息对象, 其消息状态 status 为: kJMSGMessageStatusSendDraft
调用此接口前需要先创建消息内容,以作为 content 参数传入。举例:
NSData *imageData = … // 可能来自拍照或者相册
JMSGImageContent *imageContent = [[JMSGImageContent alloc] initWithImageData:imageData];
另外更快捷的作法是,不通过此接口创建 JMSGMessage 而是直接调用具体的发送接口,如 sendSingleTextMessage.
通过此接口先创建 JMSGMessage 的好处是,可以对 JMSGMessage 做更多的定制控制,比如加附加字段。举例:
[imageContent addExtraValue:@"extra_value" forKey:@"extra_key"]
注意:如果创建消息的内容是图片,并且图片可能比较大,则建议不要使用这个同步接口, 改用 createMessageAsyncWithImageContent:completionHandler: 方法。
Declared In
JMSGConversation.h
– createMessageAsyncWithImageContent:completionHandler:
创建消息对象(图片,异步)
注意:此方法已过期,请使用 createMessageAsyncWithMediaContent: 方法
- (void)createMessageAsyncWithImageContent:(JMSGImageContent *)content completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler
Declared In
JMSGConversation.h
– createMessageAsyncWithMediaContent:completionHandler:
创建消息对象(多媒体消息,异步)
- (void)createMessageAsyncWithMediaContent:(JMSGMediaAbstractContent *)content completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler
Parameters
content |
准备好的多媒体内容,如:图片、语音、文件等 |
---|---|
handler |
结果回调. 正常返回时 resultObject 类型为 JMSGMessage. |
Discussion
注意:对于多媒体消息,因为 SDK 要做缩图有一定的性能损耗,图片文件很大时存储落地也会较慢。 所以创建图片消息,建议使用这个异步接口。
Declared In
JMSGConversation.h
– sendMessage:
发送消息(已经创建好对象的)
- (void)sendMessage:(JMSGMessage *)message
Parameters
message |
通过消息创建类接口,创建好的消息对象 |
---|
Discussion
发送消息的多个接口,都未在方法上直接提供回调。你应通过 JMSGMessageDelegate中的onReceiveMessage: error:方法来注册消息发送结果
Declared In
JMSGConversation.h
– sendMessage:optionalContent:
发送消息(附带可选功能,如:控制离线消息存储、自定义通知栏内容、消息已读回执等)
- (void)sendMessage:(JMSGMessage *)message optionalContent:(JMSGOptionalContent *)optionalContent
Parameters
message |
通过消息创建类接口,创建好的消息对象 |
---|---|
optionalContent |
可选功能,具体请查看 JMSGOptionalContent 类 |
Discussion
可选功能里可以设置离线消息存储、自定义通知栏内容、消息已读回执等,具体请查看 JMSGOptionalContent 类。
Declared In
JMSGConversation.h
– sendMessage:at_list:
发送@人消息(已经创建好对象的)
- (void)sendMessage:(JMSGMessage *)message at_list:(NSArray<__kindofJMSGUser*> *)userList
Parameters
message |
通过消息创建类接口,创建好的消息对象 |
---|---|
userList |
@对象的数组 |
Discussion
发送消息的多个接口,都未在方法上直接提供回调。你应通过 JMSGMessageDelegate中的onReceiveMessage: error:方法来注册消息发送结果
Declared In
JMSGConversation.h
– sendAtAllMessage:
发送@所有人消息(已经创建好对象的)
- (void)sendAtAllMessage:(JMSGMessage *)message
Parameters
message |
通过消息创建类接口,创建好的消息对象 |
---|
Discussion
发送消息的多个接口,都未在方法上直接提供回调。你应通过 JMSGMessageDelegate中的onReceiveMessage: error:方法来注册消息发送结果
Declared In
JMSGConversation.h
– sendTextMessage:
发送文本消息
- (void)sendTextMessage:(NSString *)text
Parameters
text |
文本消息内容 |
---|
Discussion
快捷发消息接口。如果发送文本消息不需要附加 extra,则使用此接口更方便。
Declared In
JMSGConversation.h
– sendImageMessage:
发送图片消息
- (void)sendImageMessage:(NSData *)imageData
Parameters
imageData |
图片消息数据 |
---|
Discussion
快捷发送消息接口。如果发送图片消息不需要附加 extra,则使用此接口更方便。
Declared In
JMSGConversation.h
– sendVoiceMessage:duration:
发送语音消息
- (void)sendVoiceMessage:(NSData *)voiceData duration:(NSNumber *)duration
Parameters
voiceData |
语音消息数据 |
---|---|
duration |
语音消息时长(秒). 长度必须大于 0. |
Discussion
快捷发送消息接口。如果发送语音消息不需要附加 extra,则使用此接口更方便。
Declared In
JMSGConversation.h
– sendVideoMessage:thumbData:videoFormat:duration:
发送视频消息
- (void)sendVideoMessage:(NSData *)videoData thumbData:(NSData *JMSG_NULLABLE)thumbData videoFormat:(NSString *JMSG_NULLABLE)videoFormat duration:(NSNumber *)duration
Parameters
videoData |
视频消息数据 |
---|---|
thumbData |
视频封面图片 |
videoFormat |
视频格式,如:mp4、mov |
duration |
视频消息时长(秒). 长度必须大于 0. |
Discussion
快捷发送消息接口。如果发送语音消息不需要附加 extra,则使用此接口更方便。
Declared In
JMSGConversation.h
– sendFileMessage:fileName:
发送文件消息
- (void)sendFileMessage:(NSData *)fileData fileName:(NSString *)fileName
Parameters
fileData |
文件消息数据 |
---|---|
fileName |
文件名 |
Discussion
快捷发送消息接口。如果发送文件消息不需要附加 extra,则使用此接口更方便。
Declared In
JMSGConversation.h
– sendLocationMessage:longitude:scale:address:
发送地理位置消息
- (void)sendLocationMessage:(NSNumber *)latitude longitude:(NSNumber *)longitude scale:(NSNumber *)scale address:(NSString *)address
Parameters
latitude |
纬度 |
---|---|
longitude |
经度 |
scale |
缩放比例 |
address |
详细地址 |
Discussion
快捷发送消息接口。如果发送文件消息不需要附加 extra,则使用此接口更方便。
Declared In
JMSGConversation.h
– retractMessage:completionHandler:
消息撤回
- (void)retractMessage:(JMSGMessage *)message completionHandler:(JMSGCompletionHandler)handler
Parameters
message |
需要撤回的消息 |
---|---|
handler |
结果回调
|
Discussion
注意:SDK可撤回3分钟内的消息
Declared In
JMSGConversation.h
– sendTransparentMessage:completionHandler:
消息透传
- (void)sendTransparentMessage:(NSString *JMSG_NONNULL)transparentText completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler
Parameters
transparentText |
用户自定义透传内容,仅限 NSString 类型 |
---|---|
handler |
回调,error=nil 表示成功 |
Discussion
注意:
消息透传功能,消息不会进入到后台的离线存储中去,仅当对方用户当前在线时才会成功送达,可以快速响应,方便开发者拓展自定义行为;
可用来快速实现一些在线场景下的辅助功能 :输入状态提示、位置信息提示、开发者自定义等。
透传命令到达是,接收方通过 [JMSGEventDelegate onReceiveMessageTransparentEvent:] 方法监听
Declared In
JMSGConversation.h
– avatarData:
异步获取会话头像
- (void)avatarData:(JMSGAsyncDataHandler)handler
Parameters
handler |
结果回调。回调参数:
如果 error 为 ni, data 也为 nil, 表示没有数据. |
---|
Discussion
会话的头像来自于聊天对象, 单聊就是用户的头像. 建议在会话列表时, 使用此接口来显示会话的头像, 而不要使用 target 属性里的用户头像.
Declared In
JMSGConversation.h
– avatarLocalPath
获取会话头像的本地路径
- (NSString *JMSG_NULLABLE)avatarLocalPath
Return Value
返回本地路,返回值只有在下载完成之后才有意义
Declared In
JMSGConversation.h
Conversation State Maintenance 会话状态维护
– clearUnreadCount
清除会话未读数
- (void)clearUnreadCount
Discussion
把未读数设置为 0
Declared In
JMSGConversation.h
– latestMessageContentText
获取最后一条消息的内容文本
- (NSString *)latestMessageContentText
Discussion
通常用来展示在会话列表的第 2 行. 如果是图片消息,通常是文本 [图片] 之类. CustomContent 可以定制这个文本.
Declared In
JMSGConversation.h
– getConversationExtras
获取会话所有扩展字段
- (NSDictionary *JMSG_NULLABLE)getConversationExtras
Return Value
返回所有值,NSDictionary 类型
Discussion
与 [- (void)setExtraValue:forKey:] 配套使用,可用于对会话属性的扩展
Declared In
JMSGConversation.h
– getExtraValueForKey:
获取单个扩展字段
- (NSString *JMSG_NULLABLE)getExtraValueForKey:(NSString *JMSG_NONNULL)key
Return Value
返回 key 对应值,NSString 类型
Discussion
与 [- (void)setExtraValue:forKey:] 配套使用,可用于对会话属性的扩展
Declared In
JMSGConversation.h
– setExtraValue:forKey:
增加或更新扩展字段,可扩展会话属性,比如:会话置顶、标识特殊会话等
- (void)setExtraValue:(NSString *JMSG_NULLABLE)value forKey:(NSString *JMSG_NONNULL)key
Parameters
value |
新增键值对的值. String 类型. |
---|---|
key |
新增键值对的键 |
Discussion
如果 value = nil,则删除 extras 中 key 对应的值
Declared In
JMSGConversation.h
– isMessageForThisConversation:
判断消息是否属于这个 Conversation
- (BOOL)isMessageForThisConversation:(JMSGMessage *)message
Parameters
message |
待判断的消息对象 |
---|
Discussion
当前在聊天界面时,接收到消息通知,需要通过这个接口判断该消息是否属于当前这个会话,从而做不同的动作
如果注册消息接收事件时,只注册接收当前会话的消息,则不需要用此接口判断.
Declared In
JMSGConversation.h
– refreshTargetInfoFromServer:
从服务器端刷新会话信息
- (void)refreshTargetInfoFromServer:(JMSGCompletionHandler)handler
Parameters
handler |
结果回调。返回正常时 resultObject 为当前 conversation 对象. |
---|
Discussion
会话信息的 title/avatar 信息, 单聊来自于 UserInfo,对于群聊来自于 GroupInfo。 建议在进入聊天界面时,调用此接口,来更新会话属性。 典型的情况是, 此接口返回时, 刷新单聊界面顶部的会话标题. (有可能聊天对方昵称改变了, 或者群组名称改变了, 聊天标题需要刷新)
此接口供暂时使用。JMessage 整体的 Sync 机制生效后,将不需要客户端主动去刷新信息。
Declared In
JMSGConversation.h