会话与消息

          /*!
 * @abstract 创建单聊会话
 *
 * @param username 单聊对象 username
 * @param handler 结果回调。正常返回时 resultObject 类型为 JMSGConversation。
 *
 * @discussion 如果会话已经存在，则直接返回。如果不存在则创建。
 * 创建会话时如果发现该 username 的信息本地还没有，则需要从服务器上拉取。
 * 服务器端如果找不到该 username，或者某种原因查找失败，则创建会话失败。
 */
+ (void)createSingleConversationWithUsername:(NSString *)username
                           completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 创建群聊会话
 *
 * @param groupId 群聊群组ID。由创建群组时返回。
 * @param handler 结果回调。正常返回时 resultObject 类型为 JMSGConversation。
 *
 * @discussion 如果会话已经存在，则直接返回。如果不存在则创建。
 * 创建会话时如果发现该 groupId 的信息本地还没有，则需要从服务器端上拉取。
 * 如果从服务器上获取 groupId 的信息不存在或者失败，则创建会话失败。
 */
+ (void)createGroupConversationWithGroupId:(NSString *)groupId
                         completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 获取单聊会话
 *
 * @param username 单聊对象 username
 * @param appKey   应用appKey
 *
 * @discussion 如果会话还不存在，则返回 nil
 */
+ (JMSGConversation * JMSG_NULLABLE)singleConversationWithUsername:(NSString *)username
                                                            appKey:(NSString *)userAppKey;

        

          /*!
 * @abstract 获取群聊会话
 *
 * @param groupId 群聊群组ID。此 ID 由创建群组时返回的。
 *
 * @discussion 如果会话还不存在，则返回 nil
 */
+ (JMSGConversation * JMSG_NULLABLE)groupConversationWithGroupId:(NSString *)groupId;

        

          /*!
 * @abstract 返回 conversation 列表（异步,已排序）
 *
 * @param handler 结果回调。正常返回时 resultObject 的类型为 NSArray，数组里成员的类型为 JMSGConversation
 *
 * @discussion 当前是返回所有的 conversation 列表，不包括聊天室会话，默认是已经排序。
 */
+ (void)allConversations:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 删除单聊会话
 *
 * @param username 单聊用户名
 *
 * @discussion 除了删除会话本身，还会删除该会话下所有的聊天消息。
 */
+ (BOOL)deleteSingleConversationWithUsername:(NSString *)username;

/*!
 * @abstract 删除跨应用单聊会话
 */
+ (BOOL)deleteSingleConversationWithUsername:(NSString *)username
                                      appKey:(NSString *)userAppKey;

        

          /*!
 * @abstract 删除群聊会话
 *
 * @param groupId 群聊群组ID
 *
 * @discussion 除了删除会话本身，还会删除该会话下所有的聊天消息。
 */
+ (BOOL)deleteGroupConversationWithGroupId:(NSString *)groupId;

        

          /*!
 * @abstract 获取当前所有会话的未读消息的总数
 *
 * @discussion 获取所有会话未读消息总数，开启免打扰的会话未读数不会加入计数
 */
+ (NSNumber *)getAllUnreadCount;

        

          /*!
 * @abstract 未读数
 * @discussion 有新消息来时, SDK 会对未读数自动加 1
 */
@property(nonatomic, strong, readonly) NSNumber * JMSG_NULLABLE unreadCount;

        

          /*!
 * @abstract 清除会话未读数
 *
 * @discussion 把未读数设置为 0
 */
- (void)clearUnreadCount;

        

           /*!
 * @abstract 异步获取会话头像
 *
 * @param handler 结果回调。回调参数:
 *
 * - data 头像数据;
 * - objectId 为 targetId_conversationType 的组合, 用下划线隔开.
 *   其中 targetId 单聊时为 username_targetAppKey,
 *                 群聊时为 groupId
 * - error 不为nil表示出错;
 *
 * 如果 error 为 ni, data 也为 nil, 表示没有数据.
 *
 * @discussion 会话的头像来自于聊天对象, 单聊就是用户的头像.
 * 建议在会话列表时, 使用此接口来显示会话的头像, 而不要使用 target 属性里的用户头像.
 */
- (void)avatarData:(JMSGAsyncDataHandler)handler;

        

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

        

              JMSGTextContent  *content = [[JMSGTextContent alloc] initWithText:@"text"];

        

              message = [JMSGMessage createSingleMessageWithContent:content username:@"username"];

        

          /*!
 * @abstract 基于文本初始化内容对象
 *
 * @param text 纯文本内容
 *
 * @discussion 这是预设的创建文本类型内容的方法
 */
- (instancetype)initWithText:(NSString *)text;

        

          /*!
 * @abstract 初始化消息图片内容
 *
 * @param data 图片数据
 *
 * @discussion 这是预设的初始化方法. 创建一个图片内容对象, 必须要传入图片数据.
 *
 * 对于图片消息, 一般来说创建此图片内容的数据, 是对拍照原图经过裁减处理的, 否则发图片消息太大.
 * 这里传入的图片数据, SDK视为大图. 方法 largeImageDataWithProgress:completionHandler 下载到的,
 * 就是这个概念上的图片数据.
 */
- (nullable instancetype)initWithImageData:(NSData * JMSG_NONNULL)data;

        

          /*!
 * @abstract 初始化语音内容
 *
 * @param data 该语音内容的数据. 不允许为 nil, 并且内容长度应大于 0, 否则失败
 * @param duration 该语音内容的持续时长. 单位是秒. 不允许为 nil, 并且应大于 0.
 *
 * @discussion 这是预设的初始化方法, 创建一条语音内容, 必然传入语音数据, 以及时长.
 */
- (instancetype)initWithVoiceData:(NSData *)data
                    voiceDuration:(NSNumber *)duration;

        

          /*!
 * @abstract 初始化视频消息内容
 *
 * @param data      该视频内容的数据
 * @param thumbData 缩略图，建议：缩略图上层要控制大小，避免上传过大图片
 * @param duration  该视频内容的持续时长，长度应大于 0
 *
 * @discussion 建议：缩略图上层要控制大小，避免上传过大图片.
 */
- (instancetype)initWithVideoData:(NSData *)data
                        thumbData:(NSData *JMSG_NULLABLE)thumbData
                         duration:(NSNumber *)duration;

        

          /**
 *  初始化地理位置消息内容
 *
 *  @param latitude  纬度
 *  @param longitude 经度
 *  @param scale     缩放比例
 *  @param address   详细地址信息
 *
 *  @return 地理位置消息内容
 */
- (instancetype)initWithLatitude:(NSNumber *)latitude
                       longitude:(NSNumber *)longitude
                           scale:(NSNumber *)scale
                        address:(NSString *)address;

        

          /**
 *  初始化文件内容
 *
 *  @param data     文件数据
 *  @param fileName 文件名
 *
 */
- (instancetype)initWithFileData:(NSData *)data
                        fileName:(NSString *)fileName;

        

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

        

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

        

          /*!
 * @abstract 创建消息对象
 *
 * @param content 消息的内容对象。当前直接的内容对象有:
 * JMSGTextContent, JMSGImageContent, JMSGVoiceContent, JMSGCustomContent
 *
 * @return 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: 方法。
 */
- (JMSGMessage * JMSG_NULLABLE)createMessageWithContent:(JMSGAbstractContent *)content;

        

          [JMessage addDelegate: withConversation: ]

        

          /*!
 * @abstract 发送消息结果返回回调
 *
 * @param message 原发出的消息对象
 * @param error 不为nil表示发送消息出错
 *
 * @discussion 应检查 error 是否为空来判断是否出错. 如果未出错, 则成功.
 */
@optional
- (void)onSendMessageResponse:(JMSGMessage *)message error:(NSError *)error;

        

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

        

          /*!
 * @abstract 发送消息（附带可选功能，如：控制离线消息存储、自定义通知栏内容、消息已读回执等）
 *
 * @param message           通过消息创建类接口，创建好的消息对象
 * @param optionalContent   可选功能，具体请查看 JMSGOptionalContent 类
 *
 * @discussion 可选功能里可以设置离线消息存储、自定义通知栏内容、消息已读回执等，具体请查看 JMSGOptionalContent 类。
 *
 */
- (void)sendMessage:(JMSGMessage *)message optionalContent:(JMSGOptionalContent *)optionalContent;

        

          JMSGOptionalContent *option = [[JMSGOptionalContent alloc] init];
option.noSaveOffline = YES;//不保存离线消息
option.noSaveNotification = YES;//不在状态栏显示消息
option.needReadReceipt = YES;//否需要对方发送已读回执
option.messageCount = 1;//设置消息发送时的未读数，默认为 1

JMSGCustomNotification *custion = [[JMSGCustomNotification alloc] init];
custion.enabled = YES;//是否启用自定义通知栏
custion.title = @"title";//自定义消息通知栏的标题
custion.alert = @"alert";//自定义消息通知栏的内容
custion.atPrefix = @"atPrefix";//被@目标的通知内容前缀

option.customNotification = custion;

JMSGTextContent *textContent = [[JMSGTextContent alloc] initWithText:@"text"];
JMSGMessage *message = [self.conversation createMessageWithContent:textContent];
[self.conversation sendMessage:message optionalContent:option]

        

          /*!
 * @abstract 取消正在发送的消息
 *
 * @discussion 在消息发送结果监听 [JMSGMessageDelegate onSendMessageResponse:error:] 里会返回对应的错误信息和错误码。
 *
 * @since 3.8.1
 */
- (void)cancelSendingMessage;

        

          /*!
 * @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;

        

          /*!
 * @abstract 接收消息媒体文件下载失败的回调
 *
 * @param message 下载出错的消息
 *
 * @discussion 因为对于接收消息, 最主要需要特别做处理的就是媒体文件下载, 所以单列出来. 一定要处理.
 *
 * 通过的做法是: 如果是图片, 则 App 展示一张特别的表明未下载成功的图, 用户点击再次发起下载. 如果是语音,
 * 则不必特别处理, 还是原来的图标展示. 用户点击时, SDK 发现语音文件在本地没有, 会再次发起下载.
 */
@optional
- (void)onReceiveMessageDownloadFailed:(JMSGMessage *)message;

        

          /*!
 * @abstract 取消正在下载的多媒体文件
 *
 * @discussion 对于正在下载的多媒体源文件，可以调用此接口取消下载，现只能取消下载：大图、文件、视频等；下载接口的回调里会返回对应的错误码和错误信息。
 *
 * @since 3.8.1
 */
- (void)cancelDownloadOriginMedia;

        

          /*!
 * @abstract 消息撤回
 *
 * @param message 需要撤回的消息
 * @param handler 结果回调
 *
 * - resultObject 撤回后的消息
 * - error        错误信息
 *
 * @discussion 注意：SDK可撤回3分钟内的消息
 */
+ (void)retractMessage:(JMSGMessage *)message completionHandler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 消息撤回
 *
 * @param message 需要撤回的消息
 * @param handler 结果回调
 *
 * - resultObject 撤回后的消息
 * - error        错误信息
 *
 * @discussion 注意：SDK可撤回3分钟内的消息
 */
- (void)retractMessage:(JMSGMessage *)message completionHandler:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 消息转发
 *
 * @param message         需要转发的消息
 * @param target          目标 target，只能为 JMSGUser 或 JMSGGroup
 * @param optionalContent 可选功能，具体请查看 JMSGOptionalContent 类
 *
 * @discussion 注意：只能转发消息状态为 SendSucceed 和 ReceiveSucceed 的消息。
 */
+ (void)forwardMessage:(JMSGMessage *)message
                target:(id)target
       optionalContent:(JMSGOptionalContent *JMSG_NULLABLE)optionalContent;

        

          @interface JMSGOptionalContent : NSObject
/*!
 * @abstract 设置这条消息的发送是否需要对方发送已读回执，NO，默认值
 */
@property(nonatomic, assign) BOOL needReadReceipt;
@end

        

          /*!
 * @abstract 消息未读人数
 *
 * @discussion 只针对消息发送方有效
 *
 * 注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有意义。
 */
- (NSInteger)getMessageUnreadCount;

        

          /*!
 * @abstract 已读未读用户列表
 *
 * @param handler 结果回调。回调参数:
 *
 * - unreadUsers  未读用户列表
 * - readsUsers   读用户列表
 * - error        不为nil表示出错
 *
 * @discussion 只针对消息发送方有效
 *
 * 注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有意义。
 */
- (void)messageReadDetailHandler:(void(^)(NSArray *JMSG_NULLABLE readUsers, NSArray *JMSG_NULLABLE unreadUsers, NSError *JMSG_NULLABLE error))handler;

        

          /*!
 * @abstract 设置为已读
 *
 * @param handler 回调
 *
 * - resultObject 返回对应的 message，不过成功失败都会返回 message 对象
 * - error        不为 nil 表示操作失败
 *
 * @discussion 注意: 只针对消息接收方有效
 *
 * 这是一个异步接口;
 *
 * 1、接收方：设置消息为已读状态后，isHaveRead 属性也会被设置为 YES，
 *
 * 2、发送方：会收到消息已读状态变更事件，SDK 会更新消息的未读人数。
 *
 * 注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有效。
 */
- (void)setMessageHaveRead:(JMSGCompletionHandler)handler;

        

          JMSGMessageReceiptStatusChangeEvent

        

          /*!
 * @abstract 异步获取所有消息记录
 *
 * @param handler 结果回调。正常返回时 resultObject 类型为 NSArray，数据成员类型为 JMSGMessage。
 *
 * @discussion 排序规则：最新
 */
- (void)allMessages:(JMSGCompletionHandler)handler;

        

          /*!
 * @abstract 获取某条消息
 *
 * @param msgId 本地消息ID
 *
 * @discussion 这个接口在正常场景下不需要单独使用到. 获取消息一般应使用 [JSMGConversation messageArrayFromNewestWithOffset::]
 *
 * 注意: 这里的 msgId 概念同 [JMSGMessage msgId], 是本地生成的消息ID, 而非 [JMSGMessage serverMessageId]
 */
- (JMSGMessage * JMSG_NULLABLE)messageWithMessageId:(NSString *)msgId;

        

          /*!
 * @abstract 同步分页获取最新的消息
 *
 * @param offset 开始的位置。nil 表示从最初开始。
 * @param limit 获取的数量。nil 表示不限。
 *
 * @return 返回消息列表（数组）。数组成员的类型是 JMSGMessage*
 *
 * @discussion 排序规则是：最新
 *
 * 参数举例：
 *
 * - offset = nil, limit = nil，表示获取全部。相当于 allMessages。
 * - offset = nil, limit = 100，表示从最新开始取 100 条记录。
 * - offset = 100, limit = nil，表示从最新第 100 条开始，获取余下所有记录。
 */
- (NSArray JMSG_GENERIC(__kindof JMSGMessage *) *)messageArrayFromNewestWithOffset:(NSNumber *JMSG_NULLABLE)offset limit:(NSNumber *JMSG_NULLABLE)limit;

        

          /*!
 * @abstract 消息透传
 *
 * @param transparentText 用户自定义透传内容，仅限 NSString 类型
 * @param handler 回调，error=nil 表示成功
 *
 * @discussion 注意：
 *
 *  1. 消息透传功能，消息不会进入到后台的离线存储中去，仅当对方用户当前在线时才会成功送达，可以快速响应，方便开发者拓展自定义行为；
 *
 *  2. 可用来快速实现一些在线场景下的辅助功能 ：输入状态提示、位置信息提示、开发者自定义等。
 *
 *  3. 透传命令到达是，接收方通过 [JMSGEventDelegate onReceiveMessageTransparentEvent:] 方法监听
 */
- (void)sendTransparentMessage:(NSString *JMSG_NONNULL)transparentText
             completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

        

          /*!
 * @abstract 发送透传消息给自己在线的其他设备
 *
 * @param message   发送的内容
 * @param platform  设备类型
 * @param handler   回调
 *
 * @discussion 注意：
 *
 *  1. 消息透传功能，消息不会进入到后台的离线存储中去，仅当对方用户当前在线时才会成功送达，SDK 不会将此类消息内容存储；
 *
 *  2. 透传命令到达是，接收方通过 [JMSGEventDelegate onReceiveMessageTransparentEvent:] 方法监听。
 *
 * @since 3.5.0
 */
+ (void)sendCrossDeviceTransMessage:(NSString *)message
                           platform:(JMSGPlatformType)platform
                            handler:(JMSGCompletionHandler)handler;