Streaming Messages

This document describes how to use the IMLib SDK to retrieve streaming messages in one-to-one chats and group chats.

tip

This feature is supported starting from version 5.16.1.

Streaming Messages Overview

Streaming messages are triggered by the business server, generated by the RC IM server, and delivered to the client SDK. Upon receiving a streaming message, the client SDK can initiate content retrieval based on business requirements and handle corresponding event callbacks. The sequence diagram is as follows:

The IMLib SDK defines the RCStreamMessage object, which inherits from RCMessageContent. The table below describes key properties of the RCStreamMessage class. For a complete property list, refer to the API documentation.

The RCStreamMessage data structure is as follows:

Property	Type	Description
content	NSString	Streaming message content
type	NSString	Text format of streaming message
isComplete	BOOL	Whether streaming message content generation has completed
completeReason	NSInteger	Reason for abnormal termination of streaming message content (provided by business server)
stopReason	NSInteger	Reason for abnormal termination of streaming message content (provided by RC server, 0 indicates normal termination)
isSync	BOOL	Flag indicating whether client has completed streaming retrieval
referMsg	RCReferenceInfo	Reference message information for streaming message

tip

• The IMLib SDK does not support sending streaming messages, which can only be delivered by the server. After receiving a streaming message, the IMLib SDK passes it to the business layer through the RCIMClientReceiveMessageDelegate callback interface.
• After receiving a streaming message, you need to use the RCCoreClient's requestStreamMessageWithParams:completionHandler: interface to retrieve the complete content.

Receiving Streaming Messages

The IMLib SDK does not support sending streaming messages. Developers must trigger streaming messages through server APIs, and the corresponding recipients will receive them.

Adding Message Listeners

You can set up the message reception delegate using the addReceiveMessageDelegate method after initializing the SDK but before connecting to IM.

[[RCCoreClient sharedCoreClient] addReceiveMessageDelegate:self];

Message Listener Callback

Implement the message reception callback method in your application's delegate.

- (void)onReceived:(RCMessage *)message left:(int)nLeft object:(nullable id)object {
    if ([message.content isKindOfClass:[RCStreamMessage class]]) {
        // TODO
    }
}

Historical Streaming Messages

After receiving streaming messages, the IMLib SDK stores them in the local database. You can query streaming messages when calling Get History Messages related interfaces.

Retrieving Streaming Messages

By default, the content of streaming messages contains only the initial packet. After obtaining a streaming message, developers need to retrieve its complete content using the requestStreamMessageWithParams:completionHandler: interface.

Adding Streaming Message Retrieval Event Delegate

You can add a streaming message retrieval event listener by calling the addStreamMessageRequestEventDelegate: method.

[[RCCoreClient sharedCoreClient] addStreamMessageRequestEventDelegate:self];

The streaming message retrieval process consists of three events: onInit, onDelta, and onComplete, corresponding to the following delegate methods:

/// Streaming message event delegate.
/// - Since: 5.16.0
@protocol RCStreamMessageRequestEventDelegate <NSObject>

@optional

/// Callback when request preparation is complete. Cleans abnormal data if the message was previously abnormally terminated.
- (void)didReceiveInitEventWithMessageUId:(NSString *)messageUId;

/// Callback when incremental data is received for streaming message request.
- (void)didReceiveDeltaEventWithMessage:(RCMessage *)message
                              chunkInfo:(RCStreamMessageChunkInfo *)chunkInfo;

/// Callback when streaming message request reception is complete.
- (void)didReceiveCompleteEventWithMessageUId:(NSString *)messageUId
                                         code:(RCErrorCode)code;

@end

Parameters for didReceiveDeltaEventWithMessage:chunkInfo: are as follows:

Parameter	Type	Description
message	RCMessage	Streaming message
chunkInfo	[RCStreamMessageChunkInfo]	Chunk information of streaming message

Initiating Streaming Message Retrieval

After obtaining a streaming message, you can check the isSync parameter to determine whether synchronization is complete. If NO, you can retrieve the streaming message as needed:

RCStreamMessageRequestParams *params = [[RCStreamMessageRequestParams alloc] init];
params.messageUId = message.messageUId;
[[RCCoreClient sharedCoreClient] requestStreamMessageWithParams:params
                                              completionHandler：^(RCErrorCode code){
    // TODO
}];

tip

• The completionHandler parameter in the request interface handles logical validation and request result callbacks, while the RCStreamMessageRequestEventDelegate event listener handles streaming message event callbacks after the request is initiated.

Streaming Message Summaries

When the server completes streaming message content reception, it notifies the client of the message summary via [Message Extension].

Registering Message Extension Update Listener

Developers can register a message extension update listener by setting messageExpansionDelegate.

[[RCCoreClient sharedCoreClient] setMessageExpansionDelegate:self];

Obtaining Streaming Message Summaries

When you receive a message extension update, you can retrieve the streaming message summary using the summary extension key.

- (void)messageExpansionDidUpdate:(NSDictionary<NSString *, NSString *> *)expansionDic
                          message:(RCMessage *)message {
    if ([message.content isKindOfClass:[RCStreamMessage class]]) {
        NSString *summery = [expansionDic objectForKey:RCStreamMessageExpansionSummeryKey];
        // TODO
    }
}

Obtaining Historical Streaming Message Summaries

When the client receives a message extension update, summary information is automatically stored in the database. You can retrieve historical message summaries by checking the streaming message's isComplete property.

- (void)messageExpansionDidUpdate:(NSDictionary<NSString *, NSString *> *)expansionDic
                          message:(RCMessage *)message {
    if ([message.content isKindOfClass:[RCStreamMessage class]]) {
        RCStreamMessage *streamMessage = (RCStreamMessage *)message.content;
        if (streamMessage.isComplete) {
            NSString *summery = [message.expansionDic objectForKey:RCStreamMessageExpansionSummeryKey];
            // TODO
        }
    }
}