1#pragma once
2
3/// @file
4/// @brief Space related events to make child and parent relations
5
6#include <optional>
7
8#if __has_include(<nlohmann/json_fwd.hpp>)
9#include <nlohmann/json_fwd.hpp>
10#else
11#include <nlohmann/json.hpp>
12#endif
13
14namespace mtx {
15namespace events {
16namespace state {
17//! Namespace for space related state events.
18namespace space {
19/// @brief Event to point at a parent space from a room or space
20///
21/// To avoid abuse where a room admin falsely claims that a room is part of a space that it
22/// should not be, clients could ignore such m.space.parent events unless either (a) there
23/// is a corresponding m.space.child event in the claimed parent, or (b) the sender of the
24/// m.space.child event has a sufficient power-level to send such an m.space.child event in
25/// the parent. (It is not necessarily required that that user currently be a member of the
26/// parent room - only the m.room.power_levels event is inspected.)
27struct Parent
28{
29 /// @brief Servers to join the parent space via.
30 ///
31 /// Needs to contain at least one server.
32 std::optional<std::vector<std::string>> via;
33 /// @brief Determines whether this is the main parent for the space.
34 ///
35 /// When a user joins a room with a canonical parent, clients may switch to view the room in
36 /// the context of that space, peeking into it in order to find other rooms and group them
37 /// together. In practice, well behaved rooms should only have one canonical parent, but
38 /// given this is not enforced: if multiple are present the client should select the one
39 /// with the lowest room ID, as determined via a lexicographic ordering of the Unicode
40 /// code-points.
41 bool canonical = false;
42
43 friend void from_json(const nlohmann::json &obj, Parent &child);
44 friend void to_json(nlohmann::json &obj, const Parent &child);
45};
46
47/// @brief Event to point at a child room or space from a parent space
48///
49/// The admins of a space can advertise rooms and subspaces for their space by setting m.space.child
50/// state events. The state_key is the ID of a child room or space, and the content must contain a
51/// via key which gives a list of candidate servers that can be used to join the room.
52struct Child
53{
54 /// @brief Servers to join the child room/space via.
55 ///
56 /// Needs to contain at least one server.
57 std::optional<std::vector<std::string>> via;
58 /// @brief A string which is used to provide a default ordering of siblings in the room
59 /// list.
60 ///
61 /// Rooms are sorted based on a lexicographic ordering of the Unicode codepoints of the
62 /// characters in order values. Rooms with no order come last, in ascending numeric order of
63 /// the origin_server_ts of their m.room.create events, or ascending lexicographic order of
64 /// their room_ids in case of equal origin_server_ts. orders which are not strings, or do
65 /// not consist solely of ascii characters in the range \x20 (space) to \x7E (~), or consist
66 /// of more than 50 characters, are forbidden and the field should be ignored if received.
67 std::optional<std::string> order;
68
69 //! Optional (default false) flag to denote whether the child is “suggested” or of interest to
70 //! members of the space. This is primarily intended as a rendering hint for clients to display
71 //! the room differently, such as eagerly rendering them in the room list.
72 bool suggested = false;
73
74 friend void from_json(const nlohmann::json &obj, Child &child);
75 friend void to_json(nlohmann::json &obj, const Child &child);
76};
77}
78}
79}
80}
81