Merge branch 'dev' into device-verification

# Conflicts:
#	autotests/testfilecrypto.cpp
#	lib/connection.cpp
#	lib/connection.h
#	lib/database.cpp
#	lib/database.h
#	lib/e2ee/qolmoutboundsession.cpp
#	lib/e2ee/qolmoutboundsession.h
#	lib/eventitem.h
#	lib/events/encryptedevent.cpp
#	lib/events/encryptedevent.h
#	lib/events/encryptedfile.cpp
#	lib/events/encryptedfile.h
#	lib/events/keyverificationevent.cpp
#	lib/events/keyverificationevent.h
#	lib/events/roomkeyevent.h
#	lib/room.cpp
#	lib/room.h

1 files changed, 37 insertions, 18 deletions

diff --git a/lib/csapi/message_pagination.h b/lib/csapi/message_pagination.h
index 8c18f104..9831ae2d 100644
--- a/lib/csapi/message_pagination.h
+++ b/lib/csapi/message_pagination.h
@@ -25,20 +25,30 @@ public:
      * \param roomId
      *   The room to get events from.
      *
+     * \param dir
+     *   The direction to return events from. If this is set to `f`, events
+     *   will be returned in chronological order starting at `from`. If it
+     *   is set to `b`, events will be returned in *reverse* chronological
+     *   order, again starting at `from`.
+     *
      * \param from
      *   The token to start returning events from. This token can be obtained
-     *   from a `prev_batch` token returned for each room by the sync API,
-     *   or from a `start` or `end` token returned by a previous request
-     *   to this endpoint.
+     *   from a `prev_batch` or `next_batch` token returned by the `/sync`
+     * endpoint, or from an `end` token returned by a previous request to this
+     * endpoint.
      *
-     * \param dir
-     *   The direction to return events from.
+     *   This endpoint can also accept a value returned as a `start` token
+     *   by a previous request to this endpoint, though servers are not
+     *   required to support this. Clients should not rely on the behaviour.
+     *
+     *   If it is not provided, the homeserver shall return a list of messages
+     *   from the first or last (per the value of the `dir` parameter) visible
+     *   event in the room history for the requesting user.
      *
      * \param to
      *   The token to stop returning events at. This token can be obtained from
-     *   a `prev_batch` token returned for each room by the sync endpoint,
-     *   or from a `start` or `end` token returned by a previous request to
-     *   this endpoint.
+     *   a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
+     *   or from an `end` token returned by a previous request to this endpoint.
      *
      * \param limit
      *   The maximum number of events to return. Default: 10.
@@ -46,8 +56,8 @@ public:
      * \param filter
      *   A JSON RoomEventFilter to filter returned events with.
      */
-    explicit GetRoomEventsJob(const QString& roomId, const QString& from,
-                              const QString& dir, const QString& to = {},
+    explicit GetRoomEventsJob(const QString& roomId, const QString& dir,
+                              const QString& from = {}, const QString& to = {},
                               Omittable<int> limit = none,
                               const QString& filter = {});
 
@@ -57,25 +67,34 @@ public:
      * is necessary but the job itself isn't.
      */
     static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId,
-                               const QString& from, const QString& dir,
+                               const QString& dir, const QString& from = {},
                                const QString& to = {},
                                Omittable<int> limit = none,
                                const QString& filter = {});
 
     // Result properties
 
-    /// The token the pagination starts from. If `dir=b` this will be
-    /// the token supplied in `from`.
+    /// A token corresponding to the start of `chunk`. This will be the same as
+    /// the value given in `from`.
     QString begin() const { return loadFromJson<QString>("start"_ls); }
 
-    /// The token the pagination ends at. If `dir=b` this token should
-    /// be used again to request even earlier events.
+    /// A token corresponding to the end of `chunk`. This token can be passed
+    /// back to this endpoint to request further events.
+    ///
+    /// If no further events are available (either because we have
+    /// reached the start of the timeline, or because the user does
+    /// not have permission to see any more events), this property
+    /// is omitted from the response.
     QString end() const { return loadFromJson<QString>("end"_ls); }
 
     /// A list of room events. The order depends on the `dir` parameter.
     /// For `dir=b` events will be in reverse-chronological order,
-    /// for `dir=f` in chronological order, so that events start
-    /// at the `from` point.
+    /// for `dir=f` in chronological order. (The exact definition of
+    /// `chronological` is dependent on the server implementation.)
+    ///
+    /// Note that an empty `chunk` does not *necessarily* imply that no more
+    /// events are available. Clients should continue to paginate until no `end`
+    /// property is returned.
     RoomEvents chunk() { return takeFromJson<RoomEvents>("chunk"_ls); }
 
     /// A list of state events relevant to showing the `chunk`. For example, if
@@ -86,7 +105,7 @@ public:
     /// may remove membership events which would have already been
     /// sent to the client in prior calls to this endpoint, assuming
     /// the membership of those members has not changed.
-    StateEvents state() { return takeFromJson<StateEvents>("state"_ls); }
+    RoomEvents state() { return takeFromJson<RoomEvents>("state"_ls); }
 };
 
 } // namespace Quotient