NIMChatManagerProtocol.h

浏览该文件的文档.

//
//  NIMChatManagerProtocol.h
//  NIMLib
//
//  Created by Netease.
//  Copyright (c) 2015 Netease. All rights reserved.
//
 
#import <Foundation/Foundation.h>
 
@class NIMMessage;
@class NIMSession;
@class NIMMessageReceipt;
@class NIMRevokeMessageNotification;
@class NIMTeamMessageReceiptDetail;
@class NIMRevokeMessageOption;
 
NS_ASSUME_NONNULL_BEGIN
 
/**
 *  P2P 发送已读回执 Block
 *
 *  @param error 错误信息,如果成功,error 为 nil
 */
typedef void(^NIMSendMessageReceiptBlock)(NSError * __nullable error);
 
/**
 *  Team 发送已读回执 Block
 *
 *  @param error 错误信息,如果成功,error 为 nil
 *  @param failedReceipts 失败的回执
 */
typedef void(^NIMSendTeamMessageReceiptsBlock)(NSError * __nullable error,NSArray<NIMMessageReceipt *> * __nullable failedReceipts);
 
/**
 *  撤回消息Block
 *
 *  @param error 错误信息,如果成功,error 为 nil
 */
typedef void(^NIMRevokeMessageBlock)(NSError * __nullable error);
 
/**
 *  查询群组消息回执详情Block
 *
 *  @param error      错误,如果成功则error为nil
 *  @param detail     已读回执详情
 */
typedef void(^NIMQueryReceiptDetailBlock)(NSError * __nullable error,NIMTeamMessageReceiptDetail * __nullable detail);
 
 
/**
 *  操作完成回调
 *
 *  @param error      错误,如果成功则error为nil
 */
typedef void(^NIMChatManagerBlock)(NSError * __nullable error);
 
 
/**
 *  聊天委托
 */
@protocol NIMChatManagerDelegate <NSObject>
 
@optional
/**
 *  即将发送消息回调
 *  @discussion 因为发消息之前可能会有个准备过程,所以需要在收到这个回调时才将消息加入到 Datasource 中
 *  @param message 当前发送的消息
 */
- (void)willSendMessage:(NIMMessage *)message;
 
 
/**
 *  上传资源文件成功的回调
 *  @discussion 对于需要上传资源的消息(图片，视频，音频等)，SDK 将在上传资源成功后通过这个接口进行回调，上层可以在收到该回调后进行推送信息的重新配置 (APNS payload)
 *  @param urlString 当前消息资源获得的 url 地址
 *  @param message 当前发送的消息
 */
- (void)uploadAttachmentSuccess:(NSString *)urlString
                     forMessage:(NIMMessage *)message;
 
/**
 *  发送消息进度回调
 *
 *  @param message  当前发送的消息
 *  @param progress 进度
 */
- (void)sendMessage:(NIMMessage *)message
           progress:(float)progress;
 
 
/**
 *  发送消息完成回调
 *
 *  @param message 当前发送的消息
 *  @param error   失败原因,如果发送成功则error为nil
 */
- (void)sendMessage:(NIMMessage *)message
    didCompleteWithError:(nullable NSError *)error;
 
 
/**
 *  收到消息回调
 *
 *  @param messages 消息列表,内部为NIMMessage
 */
- (void)onRecvMessages:(NSArray<NIMMessage *> *)messages;
 
/**
 *  收到消息回执
 *
 *  @param receipts 消息回执数组
 *  @discussion 当上层收到此消息时所有的存储和 model 层业务都已经更新，只需要更新 UI 即可。
 */
- (void)onRecvMessageReceipts:(NSArray<NIMMessageReceipt *> *)receipts;
 
 
/**
 *  收到消息被撤回的通知
 *
 *  @param notification 被撤回的消息信息
 *  @discusssion 云信在收到消息撤回后，会先从本地数据库中找到对应消息并进行删除，之后通知上层消息已删除
 */
- (void)onRecvRevokeMessageNotification:(NIMRevokeMessageNotification *)notification;
 
 
/**
 *  收取消息附件回调
 *  @param message  当前收取的消息
 *  @param progress 进度
 *  @discussion 附件包括:图片,视频的缩略图,语音文件
 */
- (void)fetchMessageAttachment:(NIMMessage *)message
                      progress:(float)progress;
 
 
/**
 *  收取消息附件完成回调
 *
 *  @param message 当前收取的消息
 *  @param error   错误返回,如果收取成功,error为nil
 */
- (void)fetchMessageAttachment:(NIMMessage *)message
          didCompleteWithError:(nullable NSError *)error;
 
@end
 
 
/**
 *  聊天协议
 */
@protocol NIMChatManager <NSObject>
 
/**
 *  发送消息
 *
 *  @param message 消息
 *  @param session 接受方
 *  @param error   错误 如果在准备发送消息阶段发生错误,这个error会被填充相应的信息
 *
 *  @return 是否调用成功,这里返回的 result 只是表示当前这个函数调用是否成功,需要后续的回调才能够判断消息是否已经发送至服务器
 */
- (BOOL)sendMessage:(NIMMessage *)message
          toSession:(NIMSession *)session
              error:(NSError * __nullable *)error;
 
 
/**
 *  异步发送消息
 *
 *  @param message 消息
 *  @param session 接收方
 *  @param completion 发送完成后的回调，这里的回调完成只表示当前这个函数调用完成，需要后续的回调才能判断消息是否已经发送至服务器
 */
- (void)sendMessage:(NIMMessage *)message
          toSession:(NIMSession *)session
         completion:(__nullable NIMChatManagerBlock)completion;
 
 
/**
 *  取消正在发送的消息
 *
 *  @param message 目标消息
 *  @return 是否调用成功
 */
- (BOOL)cancelSendingMessage:(NIMMessage *)message;
 
 
/**
 *  重发消息
 *
 *  @param message 重发消息
 *  @param error   错误 如果在准备发送消息阶段发生错误,这个error会被填充相应的信息
 *
 *  @return 是否调用成功,这里返回的 result 只是表示当前这个函数调用是否成功,需要后续的回调才能够判断消息是否已经发送至服务器
 */
- (BOOL)resendMessage:(NIMMessage *)message
                error:(NSError * __nullable *)error;
 
 
/**
 *  生成转发消息
 *  得到转发消息后，开发者需要自己再调用sendForwardMessage:toSession:error: 进行发送, 和 直接调用forwardMessage:toSession:error:效果一样，但是这样可以得到转发消息的进度方法回调和是否转发成功方法回调
 *
 *  @param message 要转发的消息
 *  @param error   错误 如果在准备发送消息阶段发生错误,这个error会被填充相应的信息
 *
 *  @return 生成的需要转发的消息
 */
- (NIMMessage *)makeForwardMessageFromMessage:(NIMMessage *)message
                                        error:(NSError *__autoreleasing  _Nullable * _Nullable)error;
 
/**
 *  发送生成的转发消息
 *
 *  @param message 转发消息
 *  @param session 接受方
 *  @param error   错误 如果在准备发送消息阶段发生错误,这个error会被填充相应的信息
 *
 *  @return 是否调用成功,这里返回的 result 只是表示当前这个函数调用是否成功,需要后续的回调才能够判断消息是否已经发送至服务器
 */
- (BOOL)sendForwardMessage:(NIMMessage *)message
          toSession:(NIMSession *)session
              error:(NSError * __nullable *)error;
 
/**
 *  转发消息
 *
 *  @param message 消息
 *  @param session 接收方
 *  @param error   错误 如果在准备发送消息阶段发生错误,这个error会被填充相应的信息
 *
 *  @return 是否调用成功,这里返回的 result 只是表示当前这个函数调用是否成功,需要后续的回调才能够判断消息是否已经发送至服务器
 */
- (BOOL)forwardMessage:(NIMMessage *)message
             toSession:(NIMSession *)session
                 error:(NSError * __nullable *)error;
 
 
/**
 *  发送已读回执 (P2P)
 *
 *  @param receipt    已读回执
 *  @param completion 完成回调
 *  @discussion 此接口仅适用于 P2P 消息，群消息已读回执使用 sendTeamMessageReceipts:completion 如果已有比当前已读回执时间戳更大的已读回执已确认，则接口返回成功。
 */
- (void)sendMessageReceipt:(NIMMessageReceipt *)receipt
                completion:(nullable NIMSendMessageReceiptBlock)completion;
 
 
/**
 *  发送已读回执 (Team 批量接口)
 *
 *  @param receipts   已读回执 receipts count 最多不超过50个
 *  @param completion 完成回调
 *  @discussion 此接口仅适用于 Team 消息。
 */
- (void)sendTeamMessageReceipts:(NSArray<NIMMessageReceipt *> *)receipts
                     completion:(nullable NIMSendTeamMessageReceiptsBlock)completion;
 
 
/**
 *  刷新群组消息已读、未读数量
 *
 *  @param messages      要查询的消息集合
 *  @discussion          消息已读变化后，会通过 NIMChatManager 的代理 onRecvMessageReceipts: 回调给上层
 *                       刷新的消息必须为群组消息
 */
- (void)refreshTeamMessageReceipts:(NSArray<NIMMessage *> *)messages;
 
 
/**
 *  查询群组消息回执详情
 *
 *  @param message       要查询的消息
 *  @param completion    完成后的回调
 *  @discussion          详情包括已读人数的 id 列表和未读人数的 id 列表
 *                       查询详情对象不会跟着回执人数变化而变化，如果要获取最新的详情，必须再次调用此接口
 *
 */
- (void)queryMessageReceiptDetail:(NIMMessage *)message
                       completion:(NIMQueryReceiptDetailBlock)completion;
/**
 * 查询群组消息指定用户的回执详情
 *
 * @param message 待查询的消息
 * @param accountSet 指定的用户的账号组成的NSSet
 * @return 该消息的已读、未读账号列表
 */
- (void)queryMessageReceiptDetail:(NIMMessage *)message
                     accountSet:(NSSet *)accountSet
                       completion:(NIMQueryReceiptDetailBlock)completion;
 
/**
* 从本地数据库查询单条群组消息已读、未读账号列表
* 注意！！！：这里获取的数据通常比离线前的列表信息更陈旧
*
* @param message 待查询的消息
* @return 该消息的已读、未读账号列表
*/
- (nullable NIMTeamMessageReceiptDetail *)localMessageReceiptDetail:(NIMMessage *)message;
 
/**
* 从本地数据库查询单条群组消息在指定用户中的已读、未读账号列表（同步接口）
* 注意！！！：这里获取的数据通常比离线前的列表信息更陈旧
*
* @param message 待查询的消息
* @param accountSet 指定的用户的账号组成的NSSet
* @return 该消息的已读、未读账号列表
*/
- (nullable NIMTeamMessageReceiptDetail *)localMessageReceiptDetail:(NIMMessage *)message
                                                       accountSet:(NSSet *)accountSet;
 
/**
 *  撤回消息,不含推送信息
 *
 *  @param message    需要被撤回的消息
 *  @param completion 完成回调
 *  @discussion 消息计入未读数
 */
- (void)revokeMessage:(NIMMessage *)message
           completion:(nullable NIMRevokeMessageBlock)completion;
 
/**
 *  撤回消息
 *
 *  @param message        需要被撤回的消息
 *  @param apnsContent    云信推送内容,长度限制500字
 *  @param apnsPayload    云信推送payload信息,长度限制 2K
 *  @param should         是否计入未读数
 *  @param completion     完成回调
 */
- (void)revokeMessage:(NIMMessage *)message
          apnsContent:(nullable NSString *)apnsContent
          apnsPayload:(nullable NSDictionary *)apnsPayload
      shouldBeCounted:(BOOL)should
           completion:(nullable NIMRevokeMessageBlock)completion;
 
/**
*  撤回消息
*
*  @param message    需要被撤回的消息
*  @param option     撤回的配置选项
*  @param completion 完成回调
*  @discussion 消息计入未读数
*/
- (void)revokeMessage:(NIMMessage *)message
               option:(NIMRevokeMessageOption *)option
           completion:(nullable NIMRevokeMessageBlock)completion;
 
 
/**
 *  收取消息附件
 *
 *  @param message 需要收取附件的消息
 *  @param error   错误
 *
 *  @return 是否调用成功
 *  @discussion 附件包括：图片消息的图片缩略图，视频消息的视频缩略图，音频消息的音频文件，文件消息的文件以及自定义消息中的自定义文件
 *              个人和群组消息 SDK 会在收到该消息时自动调用本接口，自动下载除 "文件消息的文件" 外的所有附件内容
 *
 */
- (BOOL)fetchMessageAttachment:(NIMMessage *)message
                         error:(NSError * __nullable *)error;
 
 
 
/**
 *  取消收取消息附件
 *
 *  @param message 需要取消收取附件的消息
 *
 *  @discussion 附件包括：图片消息的图片缩略图，视频消息的视频缩略图，音频消息的音频文件，文件消息的文件以及自定义消息中的自定义文件
 *              个人和群组消息。SDK 不会触发任何下载回调
 */
- (void)cancelFetchingMessageAttachment:(NIMMessage *)message;
 
/**
 *  消息是否正在传输 (发送/接受附件)
 *
 *  @param message 消息
 *
 *  @return 是否正在传输
 */
- (BOOL)messageInTransport:(NIMMessage *)message;
 
/** 
 *  传输消息的进度 (发送/接受附件)
 *
 *  @param message 消息
 *
 *  @return 正在传输的消息进度,如果消息不在传输,则返回0
 */
- (float)messageTransportProgress:(NIMMessage *)message;
 
/**
 *  添加聊天委托
 *
 *  @param delegate 聊天委托
 */
- (void)addDelegate:(id<NIMChatManagerDelegate>)delegate;
 
/**
 *  移除聊天委托
 *
 *  @param delegate 聊天委托
 */
- (void)removeDelegate:(id<NIMChatManagerDelegate>)delegate;
@end
 
NS_ASSUME_NONNULL_END