1/******************************************************************************
2 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
3 */
4
5#pragma once
6
7#include <Quotient/events/roomevent.h>
8#include <Quotient/jobs/basejob.h>
9
10namespace Quotient {
11
12/*! \brief Get a list of events for this room
13 *
14 * This API returns a list of message and state events for a room. It uses
15 * pagination query parameters to paginate history in the room.
16 *
17 * *Note*: This endpoint supports lazy-loading of room member events. See
18 * [Lazy-loading room members](/client-server-api/#lazy-loading-room-members)
19 * for more information.
20 */
21class QUOTIENT_API GetRoomEventsJob : public BaseJob {
22public:
23 /*! \brief Get a list of events for this room
24 *
25 * \param roomId
26 * The room to get events from.
27 *
28 * \param dir
29 * The direction to return events from. If this is set to `f`, events
30 * will be returned in chronological order starting at `from`. If it
31 * is set to `b`, events will be returned in *reverse* chronological
32 * order, again starting at `from`.
33 *
34 * \param from
35 * The token to start returning events from. This token can be obtained
36 * from a `prev_batch` or `next_batch` token returned by the `/sync`
37 * endpoint, or from an `end` token returned by a previous request to this
38 * endpoint.
39 *
40 * This endpoint can also accept a value returned as a `start` token
41 * by a previous request to this endpoint, though servers are not
42 * required to support this. Clients should not rely on the behaviour.
43 *
44 * If it is not provided, the homeserver shall return a list of messages
45 * from the first or last (per the value of the `dir` parameter) visible
46 * event in the room history for the requesting user.
47 *
48 * \param to
49 * The token to stop returning events at. This token can be obtained from
50 * a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
51 * or from an `end` token returned by a previous request to this endpoint.
52 *
53 * \param limit
54 * The maximum number of events to return. Default: 10.
55 *
56 * \param filter
57 * A JSON RoomEventFilter to filter returned events with.
58 */
59 explicit GetRoomEventsJob(const QString& roomId, const QString& dir,
60 const QString& from = {}, const QString& to = {},
61 Omittable<int> limit = none,
62 const QString& filter = {});
63
64 /*! \brief Construct a URL without creating a full-fledged job object
65 *
66 * This function can be used when a URL for GetRoomEventsJob
67 * is necessary but the job itself isn't.
68 */
69 static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId,
70 const QString& dir, const QString& from = {},
71 const QString& to = {},
72 Omittable<int> limit = none,
73 const QString& filter = {});
74
75 // Result properties
76
77 /// A token corresponding to the start of `chunk`. This will be the same as
78 /// the value given in `from`.
79 QString begin() const { return loadFromJson<QString>(keyName: "start"_ls); }
80
81 /// A token corresponding to the end of `chunk`. This token can be passed
82 /// back to this endpoint to request further events.
83 ///
84 /// If no further events are available (either because we have
85 /// reached the start of the timeline, or because the user does
86 /// not have permission to see any more events), this property
87 /// is omitted from the response.
88 QString end() const { return loadFromJson<QString>(keyName: "end"_ls); }
89
90 /// A list of room events. The order depends on the `dir` parameter.
91 /// For `dir=b` events will be in reverse-chronological order,
92 /// for `dir=f` in chronological order. (The exact definition of
93 /// `chronological` is dependent on the server implementation.)
94 ///
95 /// Note that an empty `chunk` does not *necessarily* imply that no more
96 /// events are available. Clients should continue to paginate until no `end`
97 /// property is returned.
98 RoomEvents chunk() { return takeFromJson<RoomEvents>(key: "chunk"_ls); }
99
100 /// A list of state events relevant to showing the `chunk`. For example, if
101 /// `lazy_load_members` is enabled in the filter then this may contain
102 /// the membership events for the senders of events in the `chunk`.
103 ///
104 /// Unless `include_redundant_members` is `true`, the server
105 /// may remove membership events which would have already been
106 /// sent to the client in prior calls to this endpoint, assuming
107 /// the membership of those members has not changed.
108 RoomEvents state() { return takeFromJson<RoomEvents>(key: "state"_ls); }
109};
110
111} // namespace Quotient
112