getEventByTimestamp method

Future<GetEventByTimestampResponse> getEventByTimestamp(String roomId, int ts, Direction dir)

Get the ID of the event closest to the given timestamp, in the direction specified by the dir parameter.

If the server does not have all of the room history and does not have an event suitably close to the requested timestamp, it can use the corresponding federation endpoint to ask other servers for a suitable event.

After calling this endpoint, clients can call /rooms/{roomId}/context/{eventId} to obtain a pagination token to retrieve the events around the returned event.

The event returned by this endpoint could be an event that the client cannot render, and so may need to paginate in order to locate an event that it can display, which may end up being outside of the client's suitable range. Clients can employ different strategies to display something reasonable to the user. For example, the client could try paginating in one direction for a while, while looking at the timestamps of the events that it is paginating through, and if it exceeds a certain difference from the target timestamp, it can try paginating in the opposite direction. The client could also simply paginate in one direction and inform the user that the closest event found in that direction is outside of the expected range.

roomId The ID of the room to search

ts The timestamp to search from, as given in milliseconds since the Unix epoch.

dir The direction in which to search. f for forwards, b for backwards.

Implementation

Future<GetEventByTimestampResponse> getEventByTimestamp(
    String roomId, int ts, Direction dir) async {
  final requestUri = Uri(
      path:
          '_matrix/client/v1/rooms/${Uri.encodeComponent(roomId)}/timestamp_to_event',
      queryParameters: {
        'ts': ts.toString(),
        'dir': dir.name,
      });
  final request = Request('GET', baseUri!.resolveUri(requestUri));
  request.headers['authorization'] = 'Bearer ${bearerToken!}';
  final response = await httpClient.send(request);
  final responseBody = await response.stream.toBytes();
  if (response.statusCode != 200) unexpectedResponse(response, responseBody);
  final responseString = utf8.decode(responseBody);
  final json = jsonDecode(responseString);
  return GetEventByTimestampResponse.fromJson(json as Map<String, Object?>);
}