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 | |
10 | namespace 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 | */ |
24 | class QUOTIENT_API GetSpaceHierarchyJob : public BaseJob { |
25 | public: |
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 | |
133 | template <> |
134 | struct 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 | |