流式消息
本文主要描述了如何使用 IMLib SDK 向单聊会话、群聊会话中拉取流式消息。
此功能从 5.16.1 版本开始支持。
流式消息简介
流式消息由业务服务器触发,融云 IM 服务器生成并下发消息到客户端 SDK。客户端 SDK 接收到流式消息后,可根据业务需求发起消息拉取,并处理相应的事件回调。以下是时序图:
IMLib SDK 定义 RCStreamMessage 对象,继承于 RCMessageContent。下表描述 RCStreamMessage 类的关键属性,完整的属性列表可参考 API 文档。
RCStreamMessage 的数据结构如下:
属性名 | 类型 | 描述 |
---|---|---|
content | NSString | 流式消息内容。 |
type | NSString | 流式消息的文本格式。 |
isComplete | BOOL | 流式消息内容是否结束生成。 |
completeReason | NSInteger | 流式消息内容是异常结束的原因,为业务服务器下发。 |
stopReason | NSInteger | 流式消息内容是异常结束的原因,为融云服务器下发,0 为正常结束。 |
isSync | BOOL | 客户端是否完成流拉取标识。 |
referMsg | RCReferenceInfo | 流式消息引用的消息信息。 |
- 流式消息不支持 SDK 发送,只能由服务器下发,SDK 接收到流式消息后,通过
RCIMClientReceiveMessageDelegate
的回调接口,传递给业务层使用。 - 在接收流式消息后,需要通过
RCCoreClient
的requestStreamMessageWithParams:completionHandler:
接口拉取完整内容。
接收流式消息
SDK 不支持发送流式消息,开发者需要通过服务器接口触发流式消息,对应的接收者会收到流式消息。
添加消息监听
应用程序可以通过 addReceiveMessageDelegate
方法设置消息接收代理。
[[RCCoreClient sharedCoreClient] addReceiveMessageDelegate:self];
消息监听回调
应用程序实现代理中的消息接收回调方法。
- (void)onReceived:(RCMessage *)message left:(int)nLeft object:(nullable id)object {
if ([message.content isKindOfClass:[RCStreamMessage class]]) {
// TODO
}
}
历史流式消息
SDK 接收到流式消息之后,会存到本地数据库。开发者在调用 获取历史消息 相关接口时,可以查询到流式消息。
拉取流式消息
流式消息的 content
默认是首包传入的内容,开发者在获取到流式消息之后,需要拉取流式消息的全部内容。可以通过 requestStreamMessageWithParams:completionHandler:
接口,拉取完整的消息内容。
添加流式消息拉取事件代理
开发者可以调用 addStreamMessageRequestEventDelegate:
方法,添加流式消息拉取事件监听。
[[RCCoreClient sharedCoreClient] addStreamMessageRequestEventDelegate:self];
流式消息的拉取过程分为 onInit
、onDelta
和 onComplete
三个事件,分别对应代理的以下方法:
/// 流式消息事件代理。
/// - Since: 5.16.0
@protocol RCStreamMessageRequestEventDelegate <NSObject>
@optional
/// 请求准备完成回调,如果该消息之前是异常中止的,会清理异常数据。
- (void)didReceiveInitEventWithMessageUId:(NSString *)messageUId;
/// 收到流式消息请求增量数据的回调。
- (void)didReceiveDeltaEventWithMessage:(RCMessage *)message
chunkInfo:(RCStreamMessageChunkInfo *)chunkInfo;
/// 收到流式消息请求接收完成的回调。
- (void)didReceiveCompleteEventWithMessageUId:(NSString *)messageUId
code:(RCErrorCode)code;
@end
其中 didReceiveDeltaEventWithMessage:chunkInfo:
的参数如下:
参数 | 类型 | 说明 |
---|---|---|
message | RCMessage | 流式消息。 |
chunkInfo | [RCStreamMessageChunkInfo] | 流式消息的分段信息。 |
发起拉取流式消息请求
开发者在获取到流式消息后,可以通过 isSync
参数判断流式消息是否已经同步完成。如果为 NO,开发者可以按需拉取流式消息。
RCStreamMessageRequestParams *params = [[RCStreamMessageRequestParams alloc] init];
params.messageUId = message.messageUId;
[[RCCoreClient sharedCoreClient] requestStreamMessageWithParams:params
completionHandler:^(RCErrorCode code){
// TODO
}];
- 请求接口中的
completionHandler
参数是处理逻辑校验和发起请求的结果回调,事件监听RCStreamMessageRequestEventDelegate
是在请求发出之后流式消息事件的回调。
流式消息摘要
当服务器接收完毕流式消息内容后,会通过消息扩展的方式,通知客户端消息的摘要。