1/******************************************************************************
2 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
3 */
4
5#pragma once
6
7#include <Quotient/events/stateevent.h>
8#include <Quotient/jobs/basejob.h>
9
10namespace Quotient {
11
12/*! \brief Retrieve a portion of a space tree.
13 *
14 * Paginates over the space tree in a depth-first manner to locate child rooms
15 * of a given space.
16 *
17 * Where a child room is unknown to the local server, federation is used to fill
18 * in the details. The servers listed in the `via` array should be contacted to
19 * attempt to fill in missing rooms.
20 *
21 * Only [`m.space.child`](#mspacechild) state events of the room are considered.
22 * Invalid child rooms and parent events are not covered by this endpoint.
23 */
24class QUOTIENT_API GetSpaceHierarchyJob : public BaseJob {
25public:
26 // Inner data structures
27
28 /// Paginates over the space tree in a depth-first manner to locate child
29 /// rooms of a given space.
30 ///
31 /// Where a child room is unknown to the local server, federation is used to
32 /// fill in the details. The servers listed in the `via` array should be
33 /// contacted to attempt to fill in missing rooms.
34 ///
35 /// Only [`m.space.child`](#mspacechild) state events of the room are
36 /// considered. Invalid child rooms and parent events are not covered by
37 /// this endpoint.
38 struct ChildRoomsChunk {
39 /// The number of members joined to the room.
40 int numJoinedMembers;
41 /// The ID of the room.
42 QString roomId;
43 /// Whether the room may be viewed by guest users without joining.
44 bool worldReadable;
45 /// Whether guest users may join the room and participate in it.
46 /// If they can, they will be subject to ordinary power level
47 /// rules like any other user.
48 bool guestCanJoin;
49 /// The [`m.space.child`](#mspacechild) events of the space-room,
50 /// represented as [Stripped State Events](#stripped-state) with an
51 /// added `origin_server_ts` key.
52 ///
53 /// If the room is not a space-room, this should be empty.
54 StateEvents childrenState;
55 /// The canonical alias of the room, if any.
56 QString canonicalAlias{};
57 /// The name of the room, if any.
58 QString name{};
59 /// The topic of the room, if any.
60 QString topic{};
61 /// The URL for the room's avatar, if one is set.
62 QUrl avatarUrl{};
63 /// The room's join rule. When not present, the room is assumed to
64 /// be `public`.
65 QString joinRule{};
66 /// The `type` of room (from
67 /// [`m.room.create`](/client-server-api/#mroomcreate)), if any.
68 QString roomType{};
69 };
70
71 // Construction/destruction
72
73 /*! \brief Retrieve a portion of a space tree.
74 *
75 * \param roomId
76 * The room ID of the space to get a hierarchy for.
77 *
78 * \param suggestedOnly
79 * Optional (default `false`) flag to indicate whether or not the server
80 * should only consider suggested rooms. Suggested rooms are annotated in
81 * their [`m.space.child`](#mspacechild) event contents.
82 *
83 * \param limit
84 * Optional limit for the maximum number of rooms to include per response.
85 * Must be an integer greater than zero.
86 *
87 * Servers should apply a default value, and impose a maximum value to
88 * avoid resource exhaustion.
89 *
90 * \param maxDepth
91 * Optional limit for how far to go into the space. Must be a non-negative
92 * integer.
93 *
94 * When reached, no further child rooms will be returned.
95 *
96 * Servers should apply a default value, and impose a maximum value to
97 * avoid resource exhaustion.
98 *
99 * \param from
100 * A pagination token from a previous result. If specified, `max_depth`
101 * and `suggested_only` cannot be changed from the first request.
102 */
103 explicit GetSpaceHierarchyJob(const QString& roomId,
104 Omittable<bool> suggestedOnly = none,
105 Omittable<int> limit = none,
106 Omittable<int> maxDepth = none,
107 const QString& from = {});
108
109 /*! \brief Construct a URL without creating a full-fledged job object
110 *
111 * This function can be used when a URL for GetSpaceHierarchyJob
112 * is necessary but the job itself isn't.
113 */
114 static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId,
115 Omittable<bool> suggestedOnly = none,
116 Omittable<int> limit = none,
117 Omittable<int> maxDepth = none,
118 const QString& from = {});
119
120 // Result properties
121
122 /// The rooms for the current page, with the current filters.
123 std::vector<ChildRoomsChunk> rooms()
124 {
125 return takeFromJson<std::vector<ChildRoomsChunk>>(key: "rooms"_ls);
126 }
127
128 /// A token to supply to `from` to keep paginating the responses. Not
129 /// present when there are no further results.
130 QString nextBatch() const { return loadFromJson<QString>(keyName: "next_batch"_ls); }
131};
132
133template <>
134struct JsonObjectConverter<GetSpaceHierarchyJob::ChildRoomsChunk> {
135 static void fillFrom(const QJsonObject& jo,
136 GetSpaceHierarchyJob::ChildRoomsChunk& result)
137 {
138 fillFromJson(jv: jo.value(key: "num_joined_members"_ls), pod&: result.numJoinedMembers);
139 fillFromJson(jv: jo.value(key: "room_id"_ls), pod&: result.roomId);
140 fillFromJson(jv: jo.value(key: "world_readable"_ls), pod&: result.worldReadable);
141 fillFromJson(jv: jo.value(key: "guest_can_join"_ls), pod&: result.guestCanJoin);
142 fillFromJson(jv: jo.value(key: "children_state"_ls), pod&: result.childrenState);
143 fillFromJson(jv: jo.value(key: "canonical_alias"_ls), pod&: result.canonicalAlias);
144 fillFromJson(jv: jo.value(key: "name"_ls), pod&: result.name);
145 fillFromJson(jv: jo.value(key: "topic"_ls), pod&: result.topic);
146 fillFromJson(jv: jo.value(key: "avatar_url"_ls), pod&: result.avatarUrl);
147 fillFromJson(jv: jo.value(key: "join_rule"_ls), pod&: result.joinRule);
148 fillFromJson(jv: jo.value(key: "room_type"_ls), pod&: result.roomType);
149 }
150};
151
152} // namespace Quotient
153