diff options
Diffstat (limited to 'lib/csapi/message_pagination.h')
| -rw-r--r-- | lib/csapi/message_pagination.h | 55 |
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 |