libQuotient
A Qt library for building matrix clients
Loading...
Searching...
No Matches
event.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2016 Kitsune Ral <Kitsune-Ral@users.sf.net>
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
7
8#include <Quotient/converters.h>
9#include <Quotient/function_traits.h>
10
11#include <span>
12
13namespace Quotient {
14// === event_ptr_tt<> and basic type casting facilities ===
15
16template <typename EventT>
18
19// === Standard Matrix key names ===
20
21constexpr inline auto TypeKey = "type"_L1;
22constexpr inline auto ContentKey = "content"_L1;
23constexpr inline auto SenderKey = "sender"_L1;
24constexpr inline auto UnsignedKey = "unsigned"_L1;
25
27
28// === EventMetaType ===
29
30class Event;
31
32template <typename EventT, typename BaseEventT = Event>
33concept EventClass = std::derived_from<EventT, BaseEventT>;
34
35template <EventClass EventT>
36bool is(const Event& e);
37
38//! \brief The base class for event metatypes
39//!
40//! You should not normally have to use this directly, unless you need to devise
41//! a whole new kind of event metatypes.
43public:
44 // The public fields here are const and are not to be changeable anyway.
45 // NOLINTBEGIN(misc-non-private-member-variables-in-classes)
47 const char *const className;
50 // NOLINTEND(misc-non-private-member-variables-in-classes)
51
52 auto derivedTypes() const { return std::span(_derivedTypes); }
53
54 virtual ~AbstractEventMetaType() = default;
55
57 {
58 return lhs.typeInfo == rhs.typeInfo;
59 }
60
61protected:
62 // Allow template specialisations to call into one another
63 template <class EventT>
64 friend class EventMetaType;
65
66 explicit AbstractEventMetaType(const std::type_info &typeInfo, const char *className,
68 event_type_t matrixId = nullptr);
69
70 // The returned value indicates whether a generic object has to be created
71 // on the top level when `event` is empty, instead of returning nullptr
72 virtual bool doLoadFrom(const QJsonObject& fullJson, const QString& type,
73 Event*& event) const = 0;
74
75private:
78};
79
80//! \brief A family of event meta-types to load and match events
81//!
82//! TL;DR for the loadFrom() story:
83//! - for base event types, use QUO_BASE_EVENT and, if you have additional
84//! validation (e.g., JSON has to contain a certain key - see StateEvent
85//! for a real example), define it in the static EventT::isValid() member
86//! function accepting QJsonObject and returning bool.
87//! - for leaf (specific) event types - simply use QUO_EVENT and it will do
88//! everything necessary, including the TypeId definition.
89//! \sa QUO_EVENT, QUO_BASE_EVENT
90template <class EventT>
92 // Above: can't constrain EventT to be EventClass because it's incomplete
93 // at the point of EventMetaType<EventT> instantiation (see QUO_BASE_EVENT and QUO_EVENT)
94public:
96 const char* matrixTypeId = {})
97 // NB: typeid(T&) == typeid(T) but typeid(T&) can be used with an incomplete type
98 // NB2: it would be lovely to "just" use QMetaType::fromType<> instead of QtPrivate API
99 // but QMetaType tries to instantiate constructor wrappers and it's not possible while
100 // the type is incomplete
103 {}
104
105 //! \brief Try to load an event from JSON, with dynamic type resolution
106 //!
107 //! The generic logic defined in this class template and invoked applies to
108 //! all event types defined in the library and boils down to the following:
109 //! 1.
110 //! a. If EventT has TypeId defined (which normally is a case of
111 //! all leaf - specific - event types, via QUO_EVENT macro) and
112 //! \p type doesn't exactly match it, nullptr is immediately returned.
113 //! b. In absence of TypeId, an event type is assumed to be a base;
114 //! its derivedTypes are examined, and this algorithm is applied
115 //! recursively on each.
116 //! 2. Optional validation: if EventT (or, due to the way inheritance works,
117 //! any of its base event types) has a static isValid() predicate and
118 //! the event JSON does not satisfy it, nullptr is immediately returned
119 //! to the upper level or to the loadFrom() caller. This is how existence
120 //! of `state_key` is checked in any type derived from StateEvent.
121 //! 3. If step 1b above returned non-nullptr, immediately return it.
122 //! 4.
123 //! a. If EventT::isValid() or EventT::TypeId (either, or both) exist and
124 //! are satisfied (see steps 1a and 2 above), an object of this type
125 //! is created from the passed JSON and returned. In case of a base
126 //! event type, this will be a generic (aka "unknown") event.
127 //! b. If neither exists, a generic event is only created and returned
128 //! when on the top level (i.e., outside of recursion into
129 //! derivedTypes); lower levels return nullptr instead and the type
130 //! lookup continues. The latter is a case of a derived base event
131 //! metatype (e.g. RoomEvent) called from its base event metatype
132 //! (i.e., Event). If no matching type derived from RoomEvent is found,
133 //! the nested lookup returns nullptr rather than a generic RoomEvent,
134 //! so that other types derived from Event could be examined.
136 const QString& type) const
137 {
138 Event* event = nullptr;
139 const bool goodEnough = doLoadFrom(fullJson, type, event);
140 if (!event && goodEnough)
141 return event_ptr_tt<EventT>{ new EventT(fullJson) };
142 return event_ptr_tt<EventT>{ static_cast<EventT*>(event) };
143 }
144
145private:
146 bool doLoadFrom(const QJsonObject& fullJson, const QString& type,
147 Event*& event) const override
148 {
149 if constexpr (requires { EventT::TypeId; }) {
150 if (EventT::TypeId != type)
151 return false;
152 } else {
153 for (const auto& p : _derivedTypes) {
155 if (event) {
157 return false;
158 }
159 }
160 }
161 if constexpr (requires { EventT::isValid; }) {
162 if (!EventT::isValid(fullJson))
163 return false;
164 } else if constexpr (!requires { EventT::TypeId; })
165 return true; // Create a generic event object if on the top level
166 event = new EventT(fullJson);
167 return false;
168 }
169};
170
171// === Event creation facilities ===
172
173//! \brief Create an event of arbitrary type from its arguments
174//!
175//! This should not be used to load events from JSON - use loadEvent() for that.
176//! \sa loadEvent
177template <EventClass EventT, typename... ArgTs>
178inline event_ptr_tt<EventT> makeEvent(ArgTs&&... args)
179{
180 return std::make_unique<EventT>(std::forward<ArgTs>(args)...);
181}
182
183template <EventClass EventT>
184constexpr const auto& mostSpecificMetaType()
185{
186 if constexpr (requires { EventT::MetaType; })
187 return EventT::MetaType;
188 else
189 return EventT::BaseMetaType;
190}
191
192//! \brief Create an event with proper type from a JSON object
193//!
194//! Use this factory template to detect the type from the JSON object
195//! contents (the detected event type should derive from the template
196//! parameter type) and create an event object of that type.
197template <EventClass EventT>
198inline event_ptr_tt<EventT> loadEvent(const QJsonObject& fullJson)
199{
200 return mostSpecificMetaType<EventT>().loadFrom(
201 fullJson, fullJson[TypeKey].toString());
202}
203
204//! \brief Create an event from a type string and content JSON
205//!
206//! Use this template to resolve the C++ type from the Matrix type string in
207//! \p matrixType and create an event of that type by passing all parameters
208//! to EventT::basicJson().
209template <EventClass EventT>
210inline event_ptr_tt<EventT> loadEvent(const QString& matrixType,
211 const auto&... otherBasicJsonParams)
212{
213 return mostSpecificMetaType<EventT>().loadFrom(
214 EventT::basicJson(matrixType, otherBasicJsonParams...), matrixType);
215}
216
217template <EventClass EventT>
220 // No dump() to avoid any ambiguity on whether a given export to JSON uses
221 // fullJson() or only contentJson()
223 static auto load(const QJsonObject& jo)
224 {
225 return loadEvent<EventT>(jo);
226 }
227};
228
229// === Event ===
230
232public:
234 virtual const AbstractEventMetaType& metaType() const
235 {
236 return BaseMetaType;
237 }
238
240 Event(Event&&) noexcept = default;
241 Event& operator=(Event&&) = delete;
242 virtual ~Event();
243
244 /// Make a minimal correct Matrix event JSON
246 const QJsonObject& content)
247 {
248 return { { TypeKey, matrixType }, { ContentKey, content } };
249 }
250
251 //! \brief Exact Matrix type stored in JSON
253
254 template <EventClass EventT>
255 bool is() const
256 {
257 return Quotient::is<EventT>(*this);
258 }
259
260 //! \brief Apply one of the visitors based on the actual event type
261 //!
262 //! This function uses function_traits template and is() to find the first
263 //! of the passed visitor invocables that can be called with this event
264 //! object, downcasting `*this` in a type-safe way to the most specific type
265 //! accepted by the visitor. Without this function, you can still write
266 //! a stack of, for example,
267 //! `(else) if (const auto* evtPtr = eventCast<...>(baseEvtPtr))`
268 //! blocks but switchType() provides a more concise and isolating syntax:
269 //! there's no `else` or trailing `return/break` to forget, for one.
270 //! The visitors have to all return the same type (possibly void).
271 //! Here's how you might use this function:
272 //! \code
273 //! RoomEventPtr eptr = /* get the event pointer from somewhere */;
274 //! const auto result = eptr->switchOnType(
275 //! [](const RoomMemberEvent& memberEvent) {
276 //! // Do what's needed if eptr points to a RoomMemberEvent
277 //! return 1;
278 //! },
279 //! [](const CallEvent& callEvent) {
280 //! // Do what's needed if eptr points to a CallEvent or any
281 //! // class derived from it
282 //! return 2;
283 //! },
284 //! 3); /* the default value to return if nothing above matched */
285 //! \endcode
286 //! As the example shows, the last parameter can optionally be
287 //! a plain returned value instead of a visitor.
288 template <typename... VisitorTs>
289 auto switchOnType(VisitorTs&&... visitors) const;
290
291 const QJsonObject& fullJson() const { return _json; }
292
293 // According to the CS API spec, every event also has
294 // a "content" object; but since its structure is different for
295 // different types, we're implementing it per-event type.
296
297 // NB: const return types below are meant to catch accidental attempts
298 // to change event JSON (e.g., consider contentJson()["inexistentKey"]).
299
301
302 //! \brief Get a part of the content object, assuming a given type
303 //!
304 //! This retrieves the value under `content.<key>` from the event JSON and
305 //! then converts it to \p T using fromJson().
306 //! \sa contentJson, fromJson
307 template <typename T, typename KeyT>
308 const T contentPart(KeyT&& key) const
309 {
310 return fromJson<T>(contentJson()[std::forward<KeyT>(key)]);
311 }
312
314
315 //! \brief Get a part of the unsigned object, assuming a given type
316 //!
317 //! This retrieves the value under `unsigned.<key>` from the event JSON and
318 //! then converts it to \p T using fromJson().
319 //! \sa unsignedJson, fromJson
320 template <typename T, typename KeyT>
321 const T unsignedPart(KeyT&& key) const
322 {
323 return fromJson<T>(unsignedJson()[std::forward<KeyT>(key)]);
324 }
325
327 {
328 const QDebugStateSaver _dss { dbg };
330 << e.matrixType() << '(' << e.metaType().className << "): ";
331 e.dumpTo(dbg);
332 return dbg;
333 }
334
335protected:
336 friend class EventMetaType<Event>; // To access the below constructor
337
338 explicit Event(const QJsonObject& json);
339
341 virtual void dumpTo(QDebug dbg) const;
342
343private:
345};
347
348template <EventClass EventT>
351
352// === Facilities for event class definitions ===
353
354//! \brief A template base class to derive your event type from
355//!
356//! This simple class template generates commonly used event constructor
357//! signatures and the content() method with the appropriate return type.
358//! The generic version here is only used with non-trivial \p ContentT (if you
359//! don't need to create an event from its content structure, just go and derive
360//! straight from the respective \p EventBaseT instead of using EventTemplate);
361//! specialisations may override that and provide useful semantics even without
362//! \p ContentT (see EventTemplate<CallEvent>, e.g.).
363//!
364//! The template uses CRTP to pick the event type id from the actual class;
365//! it will fail to compile if \p EventT doesn't provide TypeId. It also uses
366//! the base event type's basicJson(); if you need extra keys to be inserted
367//! you may want to bypass this template as writing the code to that effect in
368//! your class will likely be clearer and more concise.
369//! \sa https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern
370//! \sa DEFINE_SIMPLE_EVENT
371template <typename EventT, EventClass BaseEventT, typename ContentT = void>
372class EventTemplate : public BaseEventT {
373 // Above: can't constrain EventT to be EventClass because it's incomplete
374 // by CRTP definition.
375public:
376 static_assert(
377 !std::is_same_v<ContentT, void>,
378 "If you see this, you tried to use EventTemplate with the default"
379 " ContentT type, which is void. This default is only used with explicit"
380 " specialisations (see CallEvent, e.g.). Otherwise, if you don't intend"
381 " to use the content part of EventTemplate then you don't need"
382 " EventTemplate; just use the base event class directly");
383 using content_type = ContentT;
384
385 explicit EventTemplate(const QJsonObject& json)
387 {}
388 explicit EventTemplate(const ContentT& c)
390 {}
391
392 ContentT content() const { return fromJson<ContentT>(this->contentJson()); }
393};
394
395//! \brief Supply event metatype information in base event types
396//!
397//! Use this macro in a public section of your base event class to provide
398//! type identity and enable dynamic loading of generic events of that type.
399//! Do _not_ add this macro if your class is an intermediate wrapper and is not
400//! supposed to be instantiated on its own. Provides BaseMetaType static field
401//! initialised by parameters passed to the macro, and a metaType() override
402//! pointing to that BaseMetaType.
403//! \sa EventMetaType
404#define QUO_BASE_EVENT(CppType_, BaseCppType_, ...)
405 friend class EventMetaType<CppType_>;
406 static inline auto BaseMetaType =
407 EventMetaType<CppType_>(&BaseCppType_::BaseMetaType __VA_OPT__(, ) __VA_ARGS__);
408 static_assert(&CppType_::BaseMetaType == &BaseMetaType,
409 #CppType_ " is wrong here - check for copy-pasta");
410 const AbstractEventMetaType &metaType() const override { return BaseMetaType; }
411 // End of macro
412
413//! \brief Supply event metatype information in (specific) event types
414//!
415//! Use this macro in a public section of your event class to provide type
416//! identity and enable dynamic loading of generic events of that type.
417//! Do _not_ use this macro if your class is an intermediate wrapper and is not
418//! supposed to be instantiated on its own. Provides MetaType static field
419//! initialised as described below; a metaType() override pointing to it; and
420//! the TypeId static field that is equal to MetaType.matrixId.
421//!
422//! The first two macro parameters are used as the first two EventMetaType
423//! constructor parameters; the third EventMetaType parameter is always
424//! BaseMetaType; and additional base types can be passed in extra macro
425//! parameters if you need to include the same event type in more than one
426//! event factory hierarchy (e.g., EncryptedEvent).
427//! \sa EventMetaType
428#define QUO_EVENT(CppType_, MatrixType_)
429 friend class EventMetaType<CppType_>;
430 static inline const auto MetaType = EventMetaType<CppType_>(&BaseMetaType, MatrixType_);
431 static_assert(&CppType_::MetaType == &MetaType,
432 #CppType_ " is wrong here - check for copy-pasta");
433 static inline const auto &TypeId = MetaType.matrixId;
434 const AbstractEventMetaType &metaType() const override { return MetaType; }
435 // End of macro
436
437#define QUO_CONTENT_GETTER_X(PartType_, PartName_, JsonKey_)
438 PartType_ PartName_() const
439 {
440 static const auto PartName_##JsonKey = JsonKey_;
441 return contentPart<PartType_>(PartName_##JsonKey);
442 }
443
444//! \brief Define an inline method obtaining a content part
445//!
446//! This macro adds a const method that extracts a JSON value at the key
447//! <tt>toSnakeCase(PartName_)</tt> (sic) and converts it to the type
448//! \p PartType_. Effectively, the generated method is an equivalent of
449//! \code
450//! contentPart<PartType_>(Quotient::toSnakeCase(#PartName_##_L1));
451//! \endcode
452#define QUO_CONTENT_GETTER(PartType_, PartName_)
453 QUO_CONTENT_GETTER_X(PartType_, PartName_, toSnakeCase(#PartName_##_L1))
454
455/// \brief Define a new event class with a single key-value pair in the content
456///
457/// This macro defines a new event class \p Name_ derived from \p Base_,
458/// with Matrix event type \p TypeId_, providing a getter named \p GetterName_
459/// for a single value of type \p ValueType_ inside the event content.
460/// To retrieve the value the getter uses a JSON key name that corresponds to
461/// its own (getter's) name but written in snake_case. \p GetterName_ must be
462/// in camelCase, no quotes (an identifier, not a literal).
463#define DEFINE_SIMPLE_EVENT(Name_, Base_, TypeId_, ValueType_, GetterName_, JsonKey_)
464 constexpr inline auto Name_##ContentKey = JsonKey_##_L1;
465 class QUOTIENT_API Name_
466 : public ::Quotient::EventTemplate<
467 Name_, Base_, EventContent::SingleKeyValue<ValueType_, Name_##ContentKey>> {
468 public:
469 QUO_EVENT(Name_, TypeId_)
470 using value_type = ValueType_;
471 using EventTemplate::EventTemplate;
472 QUO_CONTENT_GETTER_X(ValueType_, GetterName_, Name_##ContentKey)
473 };
474 // End of macro
475
476// === is<>(), eventCast<>() and switchOnType<>() ===
477
478template <EventClass EventT>
479inline bool is(const Event& e)
480{
481 // Protect against accidental putting QUO_*EVENT to a private section
482 static_assert(requires { &EventT::metaType; },
483 "Event class doesn't have a public metaType() override - "
484 "did you misplace the QUO_*EVENT macro?");
485 if constexpr (requires { EventT::MetaType; }) {
486 return &e.metaType() == &EventT::MetaType;
487 } else {
488 const auto* p = &e.metaType();
489 do {
490 if (p == &EventT::BaseMetaType)
491 return true;
492 } while ((p = p->baseType) != nullptr);
493 return false;
494 }
495}
496
497//! \brief Cast the event pointer down in a type-safe way
498//!
499//! Checks that the event \p eptr points to actually is of the requested type
500//! and returns a (plain) pointer to the event downcast to that type. \p eptr
501//! can be either "dumb" (BaseEventT*) or "smart" (`event_ptr_tt<>`). This
502//! overload doesn't affect the event ownership - if the original pointer owns
503//! the event it must outlive the downcast pointer to keep it from dangling.
504template <EventClass EventT>
505inline auto eventCast(const auto& eptr) -> decltype(static_cast<EventT*>(std::to_address(eptr)))
506{
507 return eptr && is<std::decay_t<EventT>>(*eptr)
508 ? static_cast<EventT*>(std::to_address(eptr))
509 : nullptr;
510}
511
512//! \brief Cast the event pointer down in a type-safe way, with moving
513//!
514//! Checks that the event \p eptr points to actually is of the requested type;
515//! if (and only if) it is, releases the pointer, downcasts it to the requested
516//! event type and returns a new smart pointer wrapping the downcast one.
517//! Unlike the non-moving eventCast() overload, this one only accepts a smart
518//! pointer, and that smart pointer should be an rvalue (either a temporary,
519//! or as a result of std::move()). The ownership, respectively, is transferred
520//! to the new pointer; the original smart pointer is reset to nullptr, as is
521//! normal for `unique_ptr<>::release()`.
522//! \note If \p eptr's event type does not match \p EventT it retains ownership
523//! after calling this overload; if it is a temporary, this normally
524//! leads to the event getting deleted along with the end of
525//! the temporary's lifetime.
526template <EventClass EventT, typename BaseEventT>
527inline auto eventCast(event_ptr_tt<BaseEventT>&& eptr)
528{
529 return eptr && is<std::decay_t<EventT>>(*eptr)
530 ? event_ptr_tt<EventT>(static_cast<EventT*>(eptr.release()))
531 : nullptr;
532}
533
534namespace _impl {
535 template <typename FnT, typename BaseT>
536 concept Invocable_With_Downcast =
537 EventClass<BaseT> && std::derived_from<std::remove_cvref_t<fn_arg_t<FnT>>, BaseT>;
538}
539
540template <EventClass BaseT, typename TailT>
541inline auto switchOnType(const BaseT& event, TailT&& tail)
542{
543 if constexpr (std::is_invocable_v<TailT, BaseT>) {
544 return tail(event);
545 } else if constexpr (_impl::Invocable_With_Downcast<TailT, BaseT>) {
546 using event_type = fn_arg_t<TailT>;
547 if (is<std::decay_t<event_type>>(event))
548 return tail(static_cast<event_type>(event));
549 return std::invoke_result_t<TailT, event_type>(); // Default-constructed
550 } else { // Treat it as a value to return
551 return std::forward<TailT>(tail);
552 }
553}
554
555template <typename FnT1, typename... FnTs>
556inline auto switchOnType(const EventClass auto& event, FnT1&& fn1, FnTs&&... fns)
557{
558 using event_type1 = fn_arg_t<FnT1>;
559 if (is<std::decay_t<event_type1>>(event))
560 return fn1(static_cast<event_type1>(event));
561 return switchOnType(event, std::forward<FnTs>(fns)...);
562}
563
564template <typename... VisitorTs>
565inline auto Event::switchOnType(VisitorTs&&... visitors) const
566{
567 return Quotient::switchOnType(*this,
569}
570
571} // namespace Quotient
572Q_DECLARE_METATYPE(Quotient::Event*)
573Q_DECLARE_METATYPE(const Quotient::Event*)
The base class for event metatypes.
Definition event.h:42
A family of event meta-types to load and match events.
Definition event.h:91
A template base class to derive your event type from.
Definition event.h:372
EventTemplate(const QJsonObject &json)
Definition event.h:385
ContentT content() const
Definition event.h:392
EventTemplate(const ContentT &c)
Definition event.h:388
#define QUO_CONTENT_GETTER_X(PartType_, PartName_, JsonKey_)
Definition event.h:437
#define QUO_EVENT(CppType_, MatrixType_)
Supply event metatype information in (specific) event types.
Definition event.h:428
auto eventCast(event_ptr_tt< BaseEventT > &&eptr)
Cast the event pointer down in a type-safe way, with moving.
Definition event.h:527
constexpr auto ContentKey
Definition event.h:22
event_ptr_tt< EventT > makeEvent(ArgTs &&... args)
Create an event of arbitrary type from its arguments.
Definition event.h:178
auto eventCast(const auto &eptr) -> decltype(static_cast< EventT * >(std::to_address(eptr)))
Cast the event pointer down in a type-safe way.
Definition event.h:505
event_ptr_tt< EventT > loadEvent(const QString &matrixType, const auto &... otherBasicJsonParams)
Create an event from a type string and content JSON.
Definition event.h:210
constexpr auto TypeKey
Definition event.h:21
constexpr const auto & mostSpecificMetaType()
Definition event.h:184
auto switchOnType(const EventClass auto &event, FnT1 &&fn1, FnTs &&... fns)
Definition event.h:556
constexpr auto UnsignedKey
Definition event.h:24
auto switchOnType(const BaseT &event, TailT &&tail)
Definition event.h:541
bool is(const Event &e)
Definition event.h:479
event_ptr_tt< EventT > loadEvent(const QJsonObject &fullJson)
Create an event with proper type from a JSON object.
Definition event.h:198
constexpr auto SenderKey
Definition event.h:23
#define QUOTIENT_API