1/******************************************************************************
2 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
3 */
4
5#pragma once
6
7#include <Quotient/jobs/basejob.h>
8
9namespace Quotient {
10
11/*! \brief Get the closest event ID to the given timestamp
12 *
13 * Get the ID of the event closest to the given timestamp, in the
14 * direction specified by the `dir` parameter.
15 *
16 * If the server does not have all of the room history and does not have
17 * an event suitably close to the requested timestamp, it can use the
18 * corresponding [federation
19 * endpoint](/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid)
20 * to ask other servers for a suitable event.
21 *
22 * After calling this endpoint, clients can call
23 * [`/rooms/{roomId}/context/{eventId}`](#get_matrixclientv3roomsroomidcontexteventid)
24 * to obtain a pagination token to retrieve the events around the returned
25 * event.
26 *
27 * The event returned by this endpoint could be an event that the client
28 * cannot render, and so may need to paginate in order to locate an event
29 * that it can display, which may end up being outside of the client's
30 * suitable range. Clients can employ different strategies to display
31 * something reasonable to the user. For example, the client could try
32 * paginating in one direction for a while, while looking at the
33 * timestamps of the events that it is paginating through, and if it
34 * exceeds a certain difference from the target timestamp, it can try
35 * paginating in the opposite direction. The client could also simply
36 * paginate in one direction and inform the user that the closest event
37 * found in that direction is outside of the expected range.
38 */
39class QUOTIENT_API GetEventByTimestampJob : public BaseJob {
40public:
41 /*! \brief Get the closest event ID to the given timestamp
42 *
43 * \param roomId
44 * The ID of the room to search
45 *
46 * \param ts
47 * The timestamp to search from, as given in milliseconds
48 * since the Unix epoch.
49 *
50 * \param dir
51 * The direction in which to search. `f` for forwards, `b` for backwards.
52 */
53 explicit GetEventByTimestampJob(const QString& roomId, int ts,
54 const QString& dir);
55
56 /*! \brief Construct a URL without creating a full-fledged job object
57 *
58 * This function can be used when a URL for GetEventByTimestampJob
59 * is necessary but the job itself isn't.
60 */
61 static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId, int ts,
62 const QString& dir);
63
64 // Result properties
65
66 /// The ID of the event found
67 QString eventId() const { return loadFromJson<QString>(keyName: "event_id"_ls); }
68
69 /// The event's timestamp, in milliseconds since the Unix epoch.
70 /// This makes it easy to do a quick comparison to see if the
71 /// `event_id` fetched is too far out of range to be useful for your
72 /// use case.
73 int originServerTimestamp() const
74 {
75 return loadFromJson<int>(keyName: "origin_server_ts"_ls);
76 }
77};
78
79} // namespace Quotient
80