fetchNext method
- MessageFetchListener? listener,
- dynamic onSuccess(
- List<
BaseMessage> message
- List<
- dynamic onError(
- CometChatException excep
Returns a list of BaseMessage object fetched after putting the filters.
Android Reference: MessagesRequest.fetchNext()
Migration Note: Migrated from platform channels to native Dart.
Uses MessageRepository for backend communication.
Fetches newer messages (append direction).
Offline (opt-in, additive): pass listener for the two-phase read —
onCachedMessages (instant local page, may be empty) → onServerMessages
(authoritative) / onError.
B2 (backward-compatibility.md §3): the cache phase now fires on
fetchNext too, uniform with Android (which delivers it in both
directions). It serves the newest locally-cached window as an instant
first paint; the authoritative server page (cursor-based) always follows
and corrects it. Legacy callers (no listener) are unaffected.
Implementation
Future<List<BaseMessage>> fetchNext({
MessageFetchListener? listener,
Function(List<BaseMessage> message)? onSuccess,
Function(CometChatException excep)? onError,
}) async {
// Phase 1 — cache. Listener-only, fires before any network call (rule 2).
// Mirrors [fetchPrevious]; the server phase below is authoritative.
var cacheDelivered = false;
// The timeline cache page delivered, kept for the cache-edge resume.
List<BaseMessage>? timelineCachePage;
if (listener != null) {
try {
if (_isPinnedList || _isSavedList) {
// A feature list's `fetchNext` walks AGAINST the list's order, so the
// store cannot answer it: the window is a newest-first slice, and the
// page being asked for is on the other side of it. The two-phase
// contract still fires, with an empty page, and the server page that
// follows is delivered WITHOUT writing a store (BEH-FLAG-07).
cacheDelivered = true;
listener.onCachedMessages(const []);
} else {
final page = await _timelineCachePage(forward: true);
if (page != null) {
cacheDelivered = true;
timelineCachePage = page.messages;
listener.onCachedMessages(page.messages);
}
}
} catch (_) {
// A cache-phase failure is non-fatal; the server phase still runs.
}
}
try {
// 1. Validate request parameters
// **Android Reference:** MessagesRequest.fetchNext() → validateMessageRequest()
final validationError = _validateMessageRequest();
if (validationError != null) {
if (onError != null) onError(validationError);
return [];
}
// 2. Check ERROR_FILTERS_MISSING — fetchNext requires at least one cursor
// **Android Reference:** if (messageId == -1 && timestamp == -1 && updatedAfter == -1)
final int? updatedAfterLong = updatedAfter != null
? updatedAfter!.millisecondsSinceEpoch ~/ 1000
: null;
if (_messageId == null &&
_timestamp == null &&
updatedAfterLong == null) {
final error = CometChatException(
'ERR_FILTERS_MISSING',
'At least one of messageId, timestamp, or updatedAfter must be set for fetchNext',
'At least one of messageId, timestamp, or updatedAfter must be set for fetchNext',
);
if (onError != null) onError(error);
return [];
}
// 3. Check updatesOnly without updatedAfter
// **Android Reference:** if (updatesOnly && updatedAfter == -1)
if ((updatesOnly ?? false) && updatedAfterLong == null) {
final error = CometChatException(
'ERR_UPDATESONLY_WITHOUT_UPDATEDAFTER',
'updatedAfter must be set when updatesOnly is true',
'updatedAfter must be set when updatesOnly is true',
);
if (onError != null) onError(error);
return [];
}
// 4. Check hasNext flag — return empty list if no more messages
// **Android Reference:** MessagesRequest.fetchNext() hasNext check
// With offline on, a two-phase read past the end still asks the server
// (BEH-READ-05, R105): see [_readsPastTheEnd].
if (!_hasNext && !_readsPastTheEnd(listener)) {
if (onSuccess != null) onSuccess([]);
return [];
}
// 5. Check limit does not exceed MAX_LIMIT
// **Android Reference:** Each fetch method checks limit <= MAX_LIMIT
if ((limit ?? 0) > (maxLimit ?? 100)) {
final error = CometChatException(
'ERR_LIMIT_EXCEEDED',
'Limit cannot exceed $maxLimit',
'Limit cannot exceed $maxLimit',
);
if (onError != null) onError(error);
return [];
}
// 6. Check inProgress flag — return error if already fetching
// **Android Reference:** returns ERROR_REQUEST_IN_PROGRESS to onError
if (_inProgress) {
final error = CometChatException(
'ERR_REQUEST_IN_PROGRESS',
'A fetch request is already in progress',
'A fetch request is already in progress',
);
if (onError != null) onError(error);
return [];
}
// Set inProgress flag before fetch
// **Android Reference:** MessagesRequest.fetchNext() line: inProgress = true
_inProgress = true;
// 1. Get SDK instance
final sdk = SdkRegistry.getInstance();
debugPrint(
"fetchNext - Starting with cursor: messageId=$_messageId, timestamp=$_timestamp",
);
debugPrint(
"fetchNext - uid=$uid, guid=$guid, parentMessageId=$parentMessageId",
);
// 2. Get updatedAfter as Unix timestamp (already computed above)
int? updateAfterLong = updatedAfterLong;
// A feature list's `fetchNext` asks for the page BEFORE the window, which
// is against the list's own order, so it sends no feature cursor: the
// `pinnedAt`/`id` pair names a position in a newest-first ranking and
// means nothing to an `affix=append` page (BEH-PIN-02).
const int? featurePinnedAtCursor = null;
const String? featureIdCursor = null;
// Captured as the request goes out: a page answered after this session
// ended is never written (BEH-SYNC-06).
final issuedIn = OfflineRuntime.instance.readSession;
// 3. Call repository based on parentMessageId/uid/guid
// **Android Reference:** MessagesRequest.fetchNext() routing:
// parentMessageId first, then uid/guid, then fallback
late final MessagesResult result;
if (parentMessageId != null && parentMessageId != 0) {
// Threaded messages — checked FIRST per Android SDK
result = await sdk.messages.getThreadedMessages(
parentMessageId.toString(),
limit: limit ?? 30,
affix: 'append', // fetchNext = append (newer messages)
timestamp: _timestamp,
messageId: _messageId?.toString(),
unread: unread,
hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
searchKeyword: searchKeyword,
updatedAfter: updateAfterLong,
updatesOnly: updatesOnly,
categories: categories,
types: types,
hideDeleted: hideDeleted,
tags: tags,
withTags: withTags,
interactionGoalCompleted: interactionGoalCompletedOnly,
mentionsWithTagInfo: _mentionsWithTagInfo,
mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
hasAttachments: hasAttachments,
hasLinks: hasLinks,
hasMentions: hasMentions,
hasReactions: hasReactions,
mentionedUids: mentionedUids,
attachmentTypes: attachmentTypes,
withParent: withParent,
hideQuotedMessages: hideQuotedMessages,
pinned: pinned,
saved: saved,
pinnedAtCursor: featurePinnedAtCursor,
featureIdCursor: featureIdCursor,
);
} else if (uid != null &&
uid!.isNotEmpty &&
guid != null &&
guid!.isNotEmpty) {
// User messages in a specific group
// **Android Reference:** fetchMessagesForUserInGroup()
result = await sdk.messages.getUserMessages(
uid!,
limit: limit ?? 30,
affix: 'append',
timestamp: _timestamp,
messageId: _messageId?.toString(),
unread: unread,
hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
searchKeyword: searchKeyword,
updatedAfter: updateAfterLong,
updatesOnly: updatesOnly,
categories: categories,
types: types,
hideReplies: hideReplies,
hideDeleted: hideDeleted,
tags: tags,
withTags: withTags,
interactionGoalCompleted: interactionGoalCompletedOnly,
mentionsWithTagInfo: _mentionsWithTagInfo,
mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
hasAttachments: hasAttachments,
hasLinks: hasLinks,
hasMentions: hasMentions,
hasReactions: hasReactions,
mentionedUids: mentionedUids,
attachmentTypes: attachmentTypes,
hideQuotedMessages: hideQuotedMessages,
pinned: pinned,
saved: saved,
pinnedAtCursor: featurePinnedAtCursor,
featureIdCursor: featureIdCursor,
);
} else if (uid != null && uid!.isNotEmpty) {
// User messages
result = await sdk.messages.getUserMessages(
uid!,
limit: limit ?? 30,
affix: 'append', // fetchNext = append (newer messages)
timestamp: _timestamp,
messageId: _messageId?.toString(),
unread: unread,
hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
searchKeyword: searchKeyword,
updatedAfter: updateAfterLong,
updatesOnly: updatesOnly,
categories: categories,
types: types,
hideReplies: hideReplies,
hideDeleted: hideDeleted,
tags: tags,
withTags: withTags,
interactionGoalCompleted: interactionGoalCompletedOnly,
mentionsWithTagInfo: _mentionsWithTagInfo,
mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
hasAttachments: hasAttachments,
hasLinks: hasLinks,
hasMentions: hasMentions,
hasReactions: hasReactions,
mentionedUids: mentionedUids,
attachmentTypes: attachmentTypes,
hideQuotedMessages: hideQuotedMessages,
pinned: pinned,
saved: saved,
pinnedAtCursor: featurePinnedAtCursor,
featureIdCursor: featureIdCursor,
);
} else if (guid != null && guid!.isNotEmpty) {
// Group messages
result = await sdk.messages.getGroupMessages(
guid!,
limit: limit ?? 30,
affix: 'append', // fetchNext = append (newer messages)
timestamp: _timestamp,
messageId: _messageId?.toString(),
unread: unread,
hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
searchKeyword: searchKeyword,
updatedAfter: updateAfterLong,
updatesOnly: updatesOnly,
categories: categories,
types: types,
hideReplies: hideReplies,
hideDeleted: hideDeleted,
tags: tags,
withTags: withTags,
interactionGoalCompleted: interactionGoalCompletedOnly,
mentionsWithTagInfo: _mentionsWithTagInfo,
mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
hasAttachments: hasAttachments,
hasLinks: hasLinks,
hasMentions: hasMentions,
hasReactions: hasReactions,
mentionedUids: mentionedUids,
attachmentTypes: attachmentTypes,
hideQuotedMessages: hideQuotedMessages,
pinned: pinned,
saved: saved,
pinnedAtCursor: featurePinnedAtCursor,
featureIdCursor: featureIdCursor,
);
} else {
// All messages
result = await sdk.messages.getMessages(
limit: limit ?? 30,
timestamp: _timestamp,
messageId: _messageId?.toString(),
affix: 'append', // fetchNext = append (newer messages)
unread: unread,
hideMessagesFromBlockedUsers: hideMessagesFromBlockedUsers,
searchKeyword: searchKeyword,
updatedAfter: updateAfterLong,
updatesOnly: updatesOnly,
categories: categories,
types: types,
hideReplies: hideReplies,
hideDeleted: hideDeleted,
tags: tags,
withTags: withTags,
interactionGoalCompleted: interactionGoalCompletedOnly,
mentionsWithTagInfo: _mentionsWithTagInfo,
mentionsWithBlockedInfo: _mentionsWithBlockedInfo,
hasAttachments: hasAttachments,
hasLinks: hasLinks,
hasMentions: hasMentions,
hasReactions: hasReactions,
mentionedUids: mentionedUids,
attachmentTypes: attachmentTypes,
hideQuotedMessages: hideQuotedMessages,
pinned: pinned,
saved: saved,
pinnedAtCursor: featurePinnedAtCursor,
featureIdCursor: featureIdCursor,
);
}
// 4. Update pagination cursor for next fetch
// For append (fetchNext), we update to the MAX messageId/timestamp
// Reference: Android SDK updateMessageIdAndTimestamp() method
_updatePaginationCursor(result.messages, isAppend: true);
debugPrint(
"fetchNext - Updated cursor: messageId=$_messageId, timestamp=$_timestamp",
);
// 5. Update pagination state from response
// **Android Reference:** MessagesRequest.fetchNext() pagination state update
_updatePaginationState(result);
// 6. Update hasNext/hasPrevious flags based on page comparison
// **Android Reference:** if (affix==APPEND && currentPage==totalPages) { hasNext=false; hasPrevious=true; }
if (_currentPage != -1 &&
_totalPages != -1 &&
_currentPage == _totalPages) {
_hasNext = false;
_hasPrevious = true;
}
// Also set hasNext=false if no messages returned (safety net)
if (result.messages.isEmpty) {
_hasNext = false;
}
// 7. Reset inProgress flag after successful fetch
// **Android Reference:** MessagesRequest.fetchNext() line: inProgress = false
_inProgress = false;
// A feature list's `fetchNext` page is DELIVERED but never written: it
// walked against the list's order, so it proves nothing about where the
// window begins or ends (BEH-FLAG-07). `_persistToCache` and
// `_healOmittedGhosts` are already no-ops for it (T3), and the store is
// deliberately left alone here too.
// Offline: warm the cache with this server page (no-op when disabled).
await _persistToCache(result.messages, issuedIn);
// Then heal read-time forceDelete ghosts by omission (no-op when disabled
// or under a content filter). Runs only here, on a genuine parsed 200.
await _healOmittedGhosts(result.messages, issuedIn);
// 8. Call callbacks (listener wins — never both).
if (listener != null) {
listener.onServerMessages(result.messages);
} else if (onSuccess != null) {
onSuccess(result.messages);
}
return result.messages;
} on sdk_errors.SdkException catch (sdkEx) {
// Reset inProgress flag on error
_inProgress = false;
// Convert SdkException to CometChatException
final cometChatEx = CometChatException(
sdkEx.code,
sdkEx.details ?? sdkEx.message,
sdkEx.message,
);
_resumeServerAtCacheEdge(timelineCachePage, isAppend: true);
_deliverFetchError(cometChatEx, listener, onError, cacheDelivered);
} catch (e) {
// Reset inProgress flag on error
_inProgress = false;
debugPrint("Error: $e");
// Handle unexpected errors
final cometChatEx = CometChatException(
ErrorCode.errorUnhandledException,
e.toString(),
e.toString(),
);
_resumeServerAtCacheEdge(timelineCachePage, isAppend: true);
_deliverFetchError(cometChatEx, listener, onError, cacheDelivered);
}
return [];
}