From a02680d9846b395411df71576e8ee665dff60c9f Mon Sep 17 00:00:00 2001
From: Nicolas Werner <nicolas.werner@hotmail.de>
Date: Sun, 3 Jan 2021 18:49:01 +0100
Subject: [PATCH] Add @file documentation to all files
---
Doxyfile | 2 +-
docs/dirs.dox | 29 +++++++++
docs/index.md | 21 ++++++
include/mtx.hpp | 4 ++
include/mtx/common.hpp | 3 +-
include/mtx/errors.hpp | 3 +
include/mtx/events.hpp | 3 +
include/mtx/events/aliases.hpp | 3 +
include/mtx/events/avatar.hpp | 3 +
include/mtx/events/canonical_alias.hpp | 3 +
include/mtx/events/collections.hpp | 7 ++
include/mtx/events/common.hpp | 3 +
include/mtx/events/create.hpp | 5 +-
include/mtx/events/encrypted.hpp | 3 +
include/mtx/events/encryption.hpp | 3 +
include/mtx/events/event_type.hpp | 7 ++
include/mtx/events/guest_access.hpp | 8 ++-
include/mtx/events/history_visibility.hpp | 5 +-
include/mtx/events/join_rules.hpp | 5 +-
include/mtx/events/member.hpp | 5 +-
include/mtx/events/messages/audio.hpp | 3 +
include/mtx/events/messages/emote.hpp | 3 +
include/mtx/events/messages/file.hpp | 3 +
include/mtx/events/messages/image.hpp | 3 +
include/mtx/events/messages/notice.hpp | 3 +
include/mtx/events/messages/text.hpp | 3 +
include/mtx/events/messages/video.hpp | 3 +
include/mtx/events/name.hpp | 3 +
.../events/nheko_extensions/hidden_events.hpp | 4 ++
include/mtx/events/pinned_events.hpp | 5 ++
include/mtx/events/power_levels.hpp | 20 ++++--
include/mtx/events/presence.hpp | 12 +++-
include/mtx/events/reaction.hpp | 3 +
include/mtx/events/redaction.hpp | 3 +
include/mtx/events/tag.hpp | 5 ++
include/mtx/events/tombstone.hpp | 3 +
include/mtx/events/topic.hpp | 3 +
include/mtx/events/voip.hpp | 3 +
include/mtx/identifiers.hpp | 10 ++-
include/mtx/lightweight_error.hpp | 7 ++
include/mtx/pushrules.hpp | 24 +++++++
include/mtx/requests.hpp | 4 ++
include/mtx/responses.hpp | 3 +
include/mtx/responses/common.hpp | 25 ++++++-
include/mtx/responses/create_room.hpp | 5 ++
include/mtx/responses/crypto.hpp | 7 ++
include/mtx/responses/empty.hpp | 3 +
include/mtx/responses/groups.hpp | 9 ++-
include/mtx/responses/login.hpp | 6 ++
include/mtx/responses/media.hpp | 3 +
include/mtx/responses/messages.hpp | 3 +
include/mtx/responses/notifications.hpp | 4 ++
include/mtx/responses/profile.hpp | 3 +
include/mtx/responses/register.hpp | 3 +
include/mtx/responses/sync.hpp | 3 +
include/mtx/responses/turn_server.hpp | 3 +
include/mtx/responses/version.hpp | 3 +
include/mtx/responses/well-known.hpp | 4 ++
include/mtx/secret_storage.hpp | 7 ++
include/mtx/user_interactive.hpp | 58 +++++++++++++++--
include/mtxclient/crypto/client.hpp | 65 ++++++++++++++++++-
include/mtxclient/crypto/objects.hpp | 29 +++++++++
include/mtxclient/crypto/types.hpp | 28 +++++++-
include/mtxclient/crypto/utils.hpp | 21 +++++-
include/mtxclient/http/client.hpp | 3 +
include/mtxclient/http/client_impl.hpp | 14 ++++
include/mtxclient/http/errors.hpp | 3 +
include/mtxclient/http/session.hpp | 5 ++
include/mtxclient/utils.hpp | 4 ++
lib/crypto/client.cpp | 4 --
70 files changed, 547 insertions(+), 36 deletions(-)
create mode 100644 docs/dirs.dox
create mode 100644 docs/index.md
diff --git a/Doxyfile b/Doxyfile
index 954c17c48..cd27491ec 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -844,7 +844,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = ./include/ ./docs/
+INPUT = ./include/ ./docs/ ./README.md
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
diff --git a/docs/dirs.dox b/docs/dirs.dox
new file mode 100644
index 000000000..6aac0a8b7
--- /dev/null
+++ b/docs/dirs.dox
@@ -0,0 +1,29 @@
+/// @dir include
+/// @brief Include directory. Add this to your include path.
+
+/// @dir include/mtxclient
+/// @brief The root directory for all the client callbacks.
+
+/// @dir include/mtxclient/http
+/// @brief Functions to invoke the API over HTTP.
+
+/// @dir include/mtxclient/crypto
+/// @brief Wrappers around the olm library as well as other encryption specific
+/// functionality.
+
+/// @dir include/mtx
+/// @brief The root directory for all the type definitions listed in the
+/// specifications.
+
+/// @dir include/mtx/events
+/// @brief The different event types in the Matrix API.
+
+/// @dir include/mtx/events/messages
+/// @brief The different types, that can be sent as a message event.
+
+/// @dir include/mtx/events/nheko_extensions
+/// @brief Nheko specific event types not part of the official specification.
+
+/// @dir include/mtx/responses
+/// @brief The reponses returned from each request.
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 000000000..0440fb521
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,21 @@
+mtxclient {#mainpage}
+=====================
+
+mtxclient is a library for the [Matrix protocol](https://matrix.org/) used
+primarily in the [Nheko client](https://nheko.im/nheko-reborn/nheko). This
+library is not a full SDK. Rather it is a thin wrapper providing functions and
+data structures to access the [Client-Server
+API](https://matrix.org/docs/spec/client_server/latest). Most of the semantics
+are described there and this library provides similarly named types and function
+to invoke those endpoints.
+
+mtxclient is built on top of
+[Boost.Asio](https://www.boost.org/doc/libs/1_75_0/doc/html/boost_asio.html) and
+[nlohmann/json](https://github.com/nlohmann/json). Many of the data structures
+in this library can be serialized to and deserialized from JSON. Most endpoints
+use a callback to inform the caller, if the request completed and what the
+response was.
+
+## Building
+
+For build instructions please refer to the [README](README.md).
diff --git a/include/mtx.hpp b/include/mtx.hpp
index 4a79c9714..4eb600baa 100644
--- a/include/mtx.hpp
+++ b/include/mtx.hpp
@@ -1,5 +1,9 @@
#pragma once
+/// @file
+/// @brief A header including pretty much all the headers of the library.
+/// Including this will have a significant compile time cost.
+
#include "mtx/identifiers.hpp"
#include "mtx/events.hpp"
diff --git a/include/mtx/common.hpp b/include/mtx/common.hpp
index 31ca50934..70629c427 100644
--- a/include/mtx/common.hpp
+++ b/include/mtx/common.hpp
@@ -10,7 +10,8 @@
#include <string>
#include <vector>
-//! Common types used by the crypto related endpoints.
+/// @file
+/// @brief Common types used by the crypto related endpoints.
namespace mtx {
namespace crypto {
diff --git a/include/mtx/errors.hpp b/include/mtx/errors.hpp
index 1dd8127f2..06e44be79 100644
--- a/include/mtx/errors.hpp
+++ b/include/mtx/errors.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief The error struct returned by the Matrix API.
+
#include "lightweight_error.hpp"
#include "user_interactive.hpp"
diff --git a/include/mtx/events.hpp b/include/mtx/events.hpp
index 36bb8384e..b45b8a758 100644
--- a/include/mtx/events.hpp
+++ b/include/mtx/events.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Basetypes for events. Content is defined elsewhere.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/aliases.hpp b/include/mtx/events/aliases.hpp
index 64a68c4c3..cf07d1792 100644
--- a/include/mtx/events/aliases.hpp
+++ b/include/mtx/events/aliases.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Alias events.
+
#include <string>
#include <vector>
diff --git a/include/mtx/events/avatar.hpp b/include/mtx/events/avatar.hpp
index 1a7c7e1a6..1c7fcdcc3 100644
--- a/include/mtx/events/avatar.hpp
+++ b/include/mtx/events/avatar.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Room avatar events.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/canonical_alias.hpp b/include/mtx/events/canonical_alias.hpp
index ed19abd55..900581189 100644
--- a/include/mtx/events/canonical_alias.hpp
+++ b/include/mtx/events/canonical_alias.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Change the canonical or listed avatars of a room.
+
#include <string>
#if __has_include(<nlohmann/json_fwd.hpp>)
diff --git a/include/mtx/events/collections.hpp b/include/mtx/events/collections.hpp
index 5378f1af3..dcd0bc730 100644
--- a/include/mtx/events/collections.hpp
+++ b/include/mtx/events/collections.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Collections to store multiple events of different types
+
#include <variant>
#include "mtx/events.hpp"
@@ -141,6 +144,7 @@ using TimelineEvents = std::variant<events::StateEvent<states::Aliases>,
events::RoomEvent<msgs::CallAnswer>,
events::RoomEvent<msgs::CallHangUp>>;
+//! A wapper around TimelineEvent, that produces less noisy compiler errors.
struct TimelineEvent
{
TimelineEvents data;
@@ -151,6 +155,7 @@ from_json(const json &obj, TimelineEvent &e);
} // namespace collections
+//! Get the right event type for some type of message content.
template<typename Content>
constexpr inline EventType message_content_to_type = EventType::Unsupported;
@@ -195,6 +200,7 @@ template<>
constexpr inline EventType message_content_to_type<mtx::events::msg::CallHangUp> =
EventType::CallHangUp;
+//! Get the right event type for some type of state event content.
template<typename Content>
constexpr inline EventType state_content_to_type = EventType::Unsupported;
@@ -239,6 +245,7 @@ constexpr inline EventType state_content_to_type<mtx::events::state::Tombstone>
template<>
constexpr inline EventType state_content_to_type<mtx::events::state::Topic> = EventType::RoomTopic;
+//! Get the right event type for some type of device message content.
template<typename Content>
constexpr inline EventType to_device_content_to_type = EventType::Unsupported;
diff --git a/include/mtx/events/common.hpp b/include/mtx/events/common.hpp
index ea6cd4afa..9da0c615a 100644
--- a/include/mtx/events/common.hpp
+++ b/include/mtx/events/common.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Structs used in multiple different event types.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/create.hpp b/include/mtx/events/create.hpp
index 69cf3831f..ff0422bfc 100644
--- a/include/mtx/events/create.hpp
+++ b/include/mtx/events/create.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief The first event in a room.
+
#include <optional>
#if __has_include(<nlohmann/json_fwd.hpp>)
@@ -11,7 +14,7 @@
namespace mtx {
namespace events {
namespace state {
-
+//! The predecessor of this room.
struct PreviousRoom
{
//! Required. The ID of the old room.
diff --git a/include/mtx/events/encrypted.hpp b/include/mtx/events/encrypted.hpp
index c6df76461..246416908 100644
--- a/include/mtx/events/encrypted.hpp
+++ b/include/mtx/events/encrypted.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Various event types used in E2EE.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/encryption.hpp b/include/mtx/events/encryption.hpp
index 42d0c8f13..fbf8b0ee0 100644
--- a/include/mtx/events/encryption.hpp
+++ b/include/mtx/events/encryption.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief The event enabling encryption in a room.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/event_type.hpp b/include/mtx/events/event_type.hpp
index 2a8fd4559..729452583 100644
--- a/include/mtx/events/event_type.hpp
+++ b/include/mtx/events/event_type.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Enumeration of all event types
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -10,6 +13,7 @@
namespace mtx {
namespace events {
+//! The type of an event.
enum class EventType
{
/// m.key.verification.cancel
@@ -100,12 +104,15 @@ enum class EventType
Unsupported,
};
+//! Turn an event into a string
std::string
to_string(EventType type);
+//! Parse a string into an event type.
EventType
getEventType(const std::string &type);
+//! Get the event type of an event.
EventType
getEventType(const nlohmann::json &obj);
}
diff --git a/include/mtx/events/guest_access.hpp b/include/mtx/events/guest_access.hpp
index 2718f8243..0effd617b 100644
--- a/include/mtx/events/guest_access.hpp
+++ b/include/mtx/events/guest_access.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief An event describing, if guest accounts can join a room.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -12,10 +15,11 @@ namespace mtx {
namespace events {
namespace state {
+//! The different access states for a room.
enum class AccessState
{
- CanJoin,
- Forbidden,
+ CanJoin, //! Joining is allowd (for guests)
+ Forbidden, //! Guests can't join.
};
//! Converts @p AccessState to @p std::string for serialization.
diff --git a/include/mtx/events/history_visibility.hpp b/include/mtx/events/history_visibility.hpp
index ddc8cc4a5..897df3f4c 100644
--- a/include/mtx/events/history_visibility.hpp
+++ b/include/mtx/events/history_visibility.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief State event describing the visibility of the history.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -11,7 +14,7 @@
namespace mtx {
namespace events {
namespace state {
-
+//! The different visibilities.
enum class Visibility
{
//! All events while this is the `m.room.history_visibility`
diff --git a/include/mtx/events/join_rules.hpp b/include/mtx/events/join_rules.hpp
index 63473fd28..989b1c038 100644
--- a/include/mtx/events/join_rules.hpp
+++ b/include/mtx/events/join_rules.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Manage the permission of how people can join a room.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -11,7 +14,7 @@
namespace mtx {
namespace events {
namespace state {
-
+//! The different JoinRules
enum class JoinRule
{
//! Anyone can join the room without any prior action.
diff --git a/include/mtx/events/member.hpp b/include/mtx/events/member.hpp
index 25fb66a9b..d5e49950e 100644
--- a/include/mtx/events/member.hpp
+++ b/include/mtx/events/member.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief The state event describing the membership status of a specific member.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -11,7 +14,7 @@
namespace mtx {
namespace events {
namespace state {
-
+//! The different Membership states.
enum class Membership
{
//! The user has joined.
diff --git a/include/mtx/events/messages/audio.hpp b/include/mtx/events/messages/audio.hpp
index 912a3bd9b..0c7207cfb 100644
--- a/include/mtx/events/messages/audio.hpp
+++ b/include/mtx/events/messages/audio.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Audio messages.
+
#include <optional>
#include <string>
diff --git a/include/mtx/events/messages/emote.hpp b/include/mtx/events/messages/emote.hpp
index d86beccc7..5ab5d2a5b 100644
--- a/include/mtx/events/messages/emote.hpp
+++ b/include/mtx/events/messages/emote.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Events describing an emotion or action.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/messages/file.hpp b/include/mtx/events/messages/file.hpp
index 8291615f3..baa794fcc 100644
--- a/include/mtx/events/messages/file.hpp
+++ b/include/mtx/events/messages/file.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief A file sent in a room.
+
#include <optional>
#include <string>
diff --git a/include/mtx/events/messages/image.hpp b/include/mtx/events/messages/image.hpp
index 2f47dc423..8307da28d 100644
--- a/include/mtx/events/messages/image.hpp
+++ b/include/mtx/events/messages/image.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Images sent in a room.
+
#include <optional>
#include <string>
diff --git a/include/mtx/events/messages/notice.hpp b/include/mtx/events/messages/notice.hpp
index 1de8878b2..b222f85e2 100644
--- a/include/mtx/events/messages/notice.hpp
+++ b/include/mtx/events/messages/notice.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief A bot generated message and other notices.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/messages/text.hpp b/include/mtx/events/messages/text.hpp
index ab1d39da3..a64a74977 100644
--- a/include/mtx/events/messages/text.hpp
+++ b/include/mtx/events/messages/text.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief A text message.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/messages/video.hpp b/include/mtx/events/messages/video.hpp
index 8b361c105..1b33bb8d3 100644
--- a/include/mtx/events/messages/video.hpp
+++ b/include/mtx/events/messages/video.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief A video sent in a room.
+
#include <optional>
#include <string>
diff --git a/include/mtx/events/name.hpp b/include/mtx/events/name.hpp
index 4eb4d2243..15c5ba80c 100644
--- a/include/mtx/events/name.hpp
+++ b/include/mtx/events/name.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief The room name state event.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/nheko_extensions/hidden_events.hpp b/include/mtx/events/nheko_extensions/hidden_events.hpp
index 7eb92578a..ba64d70e1 100644
--- a/include/mtx/events/nheko_extensions/hidden_events.hpp
+++ b/include/mtx/events/nheko_extensions/hidden_events.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief A nheko specific event in account data used to hide events across different clients.
+
#include <vector>
#if __has_include(<nlohmann/json_fwd.hpp>)
@@ -13,6 +16,7 @@
namespace mtx {
namespace events {
namespace account_data {
+//! Custom nheko specific event types
namespace nheko_extensions {
//! Custom event to hide certain event types in nheko
struct HiddenEvents
diff --git a/include/mtx/events/pinned_events.hpp b/include/mtx/events/pinned_events.hpp
index c5e64606a..c404a1cbf 100644
--- a/include/mtx/events/pinned_events.hpp
+++ b/include/mtx/events/pinned_events.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Events pinned in a room.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -12,8 +15,10 @@ namespace mtx {
namespace events {
namespace state {
+//! `m.room.pinned_events` state event.
struct PinnedEvents
{
+ //! The ids of the pinned events.
std::vector<std::string> pinned;
};
diff --git a/include/mtx/events/power_levels.hpp b/include/mtx/events/power_levels.hpp
index 375e67032..e4d0ed599 100644
--- a/include/mtx/events/power_levels.hpp
+++ b/include/mtx/events/power_levels.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief The state event governing the different permissions in a room.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -11,21 +14,28 @@
namespace mtx {
namespace events {
namespace state {
+//! The type representing a power level.
using power_level_t = int64_t;
+//! The default level required for events
constexpr power_level_t EventsDefault = 0;
+//! The default level for users.
constexpr power_level_t UsersDefault = 0;
+//! The default level required for state events.
constexpr power_level_t StatesDefault = 50;
+//! The power level usually associated with normal users.
constexpr power_level_t User = 0;
+//! The power level usually associated with moderators.
constexpr power_level_t Moderator = 50;
+//! The power level usually associated with admins.
constexpr power_level_t Admin = 100;
-//! Content for the `m.room.power_levels` state event.
-//
-//! This event specifies the minimum level a user must have in
-//! order to perform a certain action. It also specifies the
-//! levels of each user in the room.
+/// @brief Content for the `m.room.power_levels` state event.
+///
+/// This event specifies the minimum level a user must have in
+/// order to perform a certain action. It also specifies the
+/// levels of each user in the room.
struct PowerLevels
{
//! Returns the power_level for a given event type.
diff --git a/include/mtx/events/presence.hpp b/include/mtx/events/presence.hpp
index 34fbc191d..17674a16f 100644
--- a/include/mtx/events/presence.hpp
+++ b/include/mtx/events/presence.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief An ephemeral event describing the presence of a user.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -11,12 +14,14 @@
#include <string_view>
namespace mtx {
+//! Presence specific types.
namespace presence {
+//! The current presence state.
enum PresenceState
{
- online,
- offline,
- unavailable,
+ online, //!< The user is online.
+ offline, //!< The user is offline.
+ unavailable, //!< The user is online, but currently not available.
};
std::string
@@ -27,6 +32,7 @@ from_string(std::string_view str);
namespace events {
namespace presence {
+//! The `m.presence` ephemeral event.
struct Presence
{
std::string avatar_url; //! The current avatar URL for this user, if any.
diff --git a/include/mtx/events/reaction.hpp b/include/mtx/events/reaction.hpp
index 1ba22a1fc..e8f8106f8 100644
--- a/include/mtx/events/reaction.hpp
+++ b/include/mtx/events/reaction.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief A reaction event used to attach small annotations to events.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/redaction.hpp b/include/mtx/events/redaction.hpp
index 0d4da0ca6..6cda35c3b 100644
--- a/include/mtx/events/redaction.hpp
+++ b/include/mtx/events/redaction.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Events describing redactions and redacted content.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/tag.hpp b/include/mtx/events/tag.hpp
index 1eb78a02f..64f5c444e 100644
--- a/include/mtx/events/tag.hpp
+++ b/include/mtx/events/tag.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Events describing room tags.
+
#include <optional>
#include <string>
@@ -11,7 +14,9 @@
namespace mtx {
namespace events {
+//! Namespace for events in account_data
namespace account_data {
+//! The content of a tag.
struct Tag
{
//! A number in a range [0,1] describing a relative position of the room under
diff --git a/include/mtx/events/tombstone.hpp b/include/mtx/events/tombstone.hpp
index f5d3de25b..84e3185b1 100644
--- a/include/mtx/events/tombstone.hpp
+++ b/include/mtx/events/tombstone.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief An event describing a room upgrade or shutdown.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/topic.hpp b/include/mtx/events/topic.hpp
index 8e4d69921..befa8d7f9 100644
--- a/include/mtx/events/topic.hpp
+++ b/include/mtx/events/topic.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief The state event describing the topic in a room.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/events/voip.hpp b/include/mtx/events/voip.hpp
index 7ed179366..ee9dbe145 100644
--- a/include/mtx/events/voip.hpp
+++ b/include/mtx/events/voip.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Call related events.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/identifiers.hpp b/include/mtx/identifiers.hpp
index b6ef59e57..cf3c2d7c4 100644
--- a/include/mtx/identifiers.hpp
+++ b/include/mtx/identifiers.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Identifiers used in the Matrix API.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -33,6 +36,7 @@ protected:
std::string id_;
};
+//! An event id.
class Event : public ID
{
public:
@@ -44,6 +48,7 @@ private:
std::string sigil = "$";
};
+//! A room id.
class Room : public ID
{
public:
@@ -54,6 +59,7 @@ private:
std::string sigil = "!";
};
+//! A user id.
class User : public ID
{
public:
@@ -110,9 +116,7 @@ void
to_json(nlohmann::json &obj, const User &user);
void
-from_json(const nlohmann::json &obj, Room &room)
-
- ;
+from_json(const nlohmann::json &obj, Room &room);
void
to_json(nlohmann::json &obj, const Room &room);
diff --git a/include/mtx/lightweight_error.hpp b/include/mtx/lightweight_error.hpp
index dc207521a..01da796b1 100644
--- a/include/mtx/lightweight_error.hpp
+++ b/include/mtx/lightweight_error.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Error codes returned by the Matrix API.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -8,8 +11,10 @@
#include <string>
namespace mtx {
+//! Namespace for Matrix errors.
namespace errors {
+//! A Matrix error code.
enum class ErrorCode
{
M_UNRECOGNIZED,
@@ -53,9 +58,11 @@ enum class ErrorCode
M_INVALID_SIGNATURE,
};
+//! Convert an error code into a string.
std::string
to_string(ErrorCode code);
+//! Parse an error code from a string.
ErrorCode
from_string(const std::string &code);
diff --git a/include/mtx/pushrules.hpp b/include/mtx/pushrules.hpp
index f4301d96b..7b1ddfbd5 100644
--- a/include/mtx/pushrules.hpp
+++ b/include/mtx/pushrules.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Pushrules and notification settings.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -11,7 +14,9 @@
#include <vector>
namespace mtx {
+//! Namespace for the pushrules specific endpoints.
namespace pushrules {
+//! A condition to match pushrules on.
struct PushCondition
{
//! Required. The kind of condition to apply. See conditions for more information on the
@@ -40,21 +45,34 @@ to_json(nlohmann::json &obj, const PushCondition &condition);
void
from_json(const nlohmann::json &obj, PushCondition &condition);
+//! Namespace for the different push actions.
namespace actions {
+//! Notify the user.
struct notify
{};
+//! Don't notify the user.
struct dont_notify
{};
+/// @brief This enables notifications for matching events but activates homeserver specific
+/// behaviour to intelligently coalesce multiple events into a single notification.
+///
+/// Not all homeservers may support this. Those that do not support it should treat it as the notify
+/// action.
struct coalesce
{};
+//! Play a sound.
struct set_tweak_sound
{
+ //! The sound to play.
std::string value = "default";
};
+//! Highlight the message.
struct set_tweak_highlight
{
bool value = true;
};
+
+//! A collection for the different actions.
using Action = std::variant<actions::notify,
actions::dont_notify,
actions::coalesce,
@@ -67,6 +85,7 @@ to_json(nlohmann::json &obj, const Action &action);
void
from_json(const nlohmann::json &obj, Action &action);
+//! A list of actions.
struct Actions
{
std::vector<Action> actions;
@@ -78,6 +97,7 @@ void
from_json(const nlohmann::json &obj, Actions &action);
}
+//! A pushrule defining the notification behaviour for a message.
struct PushRule
{
//! Required. Whether this is a default rule, or has been set explicitly.
@@ -102,6 +122,7 @@ to_json(nlohmann::json &obj, const PushRule &condition);
void
from_json(const nlohmann::json &obj, PushRule &condition);
+//! All the pushrules to evaluate for events.
struct Ruleset
{
//! see https://matrix.org/docs/spec/client_server/latest#push-rules
@@ -126,8 +147,10 @@ to_json(nlohmann::json &obj, const Ruleset &condition);
void
from_json(const nlohmann::json &obj, Ruleset &condition);
+//! The global ruleset applied to all events.
struct GlobalRuleset
{
+ //! The actual ruleset.
Ruleset global;
};
@@ -137,6 +160,7 @@ to_json(nlohmann::json &obj, const GlobalRuleset &set);
void
from_json(const nlohmann::json &obj, GlobalRuleset &set);
+//! The response for queries, if a specific ruleset is enabled.
struct Enabled
{
bool enabled = true;
diff --git a/include/mtx/requests.hpp b/include/mtx/requests.hpp
index eba9a85ee..320e9aac4 100644
--- a/include/mtx/requests.hpp
+++ b/include/mtx/requests.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Structs for for requests to the Matrix API.
+
#include <string>
#include <variant>
@@ -14,6 +17,7 @@
using json = nlohmann::json;
namespace mtx {
+//! Namespace for request structs
namespace requests {
//! Whether or not the room will be visible by non members.
diff --git a/include/mtx/responses.hpp b/include/mtx/responses.hpp
index 6f7d55784..ebe6d00f3 100644
--- a/include/mtx/responses.hpp
+++ b/include/mtx/responses.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Collection header for all the different response structs.
+
#include "responses/common.hpp"
#include "responses/create_room.hpp"
diff --git a/include/mtx/responses/common.hpp b/include/mtx/responses/common.hpp
index 574679157..9458b3c1d 100644
--- a/include/mtx/responses/common.hpp
+++ b/include/mtx/responses/common.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Responses used by multiple endpoints.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -12,46 +15,59 @@
#include "mtx/events/collections.hpp"
namespace mtx {
+//! Namespace for the different types of responses.
namespace responses {
-
+//! An event id returned by the API.
struct EventId
{
+ //! The event id.
mtx::identifiers::Event event_id;
};
void
from_json(const nlohmann::json &obj, EventId &response);
+//! A group id returned by the API.
struct GroupId
{
+ //! The group id.
std::string group_id;
};
void
from_json(const nlohmann::json &obj, GroupId &response);
+//! A room id returned by the API.
struct RoomId
{
+ //! The room id.
std::string room_id;
};
void
from_json(const nlohmann::json &obj, RoomId &response);
+//! A filter id returned by the API.
struct FilterId
{
+ //! The filter id.
std::string filter_id;
};
void
from_json(const nlohmann::json &obj, FilterId &response);
+//! Different helper for parsing responses.
namespace utils {
-
+//! Multiple account_data events.
using RoomAccountDataEvents = std::vector<mtx::events::collections::RoomAccountDataEvents>;
+//! Multiple TimelineEvents.
using TimelineEvents = std::vector<mtx::events::collections::TimelineEvents>;
+//! Multiple StateEvents.
using StateEvents = std::vector<mtx::events::collections::StateEvents>;
+//! Multiple StrippedEvents.
using StrippedEvents = std::vector<mtx::events::collections::StrippedEvents>;
+//! Multiple DeviceEvents.
using DeviceEvents = std::vector<mtx::events::collections::DeviceEvents>;
namespace states = mtx::events::state;
@@ -63,21 +79,26 @@ log_error(std::exception &err, const nlohmann::json &event);
void
log_error(std::string err, const nlohmann::json &event);
+//! Parse multiple account_data events.
void
parse_room_account_data_events(const nlohmann::json &events, RoomAccountDataEvents &container);
void
compose_timeline_events(nlohmann::json &events, const TimelineEvents &container);
+//! Parse multiple timeline events.
void
parse_timeline_events(const nlohmann::json &events, TimelineEvents &container);
+//! Parse multiple state events.
void
parse_state_events(const nlohmann::json &events, StateEvents &container);
+//! Parse multiple stripped events.
void
parse_stripped_events(const nlohmann::json &events, StrippedEvents &container);
+//! Parse multiple device events.
void
parse_device_events(const nlohmann::json &events, DeviceEvents &container);
}
diff --git a/include/mtx/responses/create_room.hpp b/include/mtx/responses/create_room.hpp
index e1fe6e10d..91ee521b1 100644
--- a/include/mtx/responses/create_room.hpp
+++ b/include/mtx/responses/create_room.hpp
@@ -1,11 +1,16 @@
#pragma once
+/// @file
+/// @brief Response from creating a room.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
#include <nlohmann/json.hpp>
#endif
+#include <mtx/identifiers.hpp>
+
namespace mtx {
namespace responses {
//! Response from the `POST /_matrix/client/r0/createRoom` endpoint.
diff --git a/include/mtx/responses/crypto.hpp b/include/mtx/responses/crypto.hpp
index 358886bc6..1cf6ce469 100644
--- a/include/mtx/responses/crypto.hpp
+++ b/include/mtx/responses/crypto.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief E2EE related endpoints.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -53,8 +56,10 @@ to_json(nlohmann::json &obj, const QueryKeys &response);
void
from_json(const nlohmann::json &obj, QueryKeys &response);
+//! Request for `POST /_matrix/client/r0/keys/upload`.
struct KeySignaturesUpload
{
+ //! Errors returned during upload.
std::map<std::string, std::map<std::string, mtx::errors::LightweightError>> errors;
};
@@ -89,6 +94,7 @@ struct KeyChanges
void
from_json(const nlohmann::json &obj, KeyChanges &response);
+//! KeysBackup related responses.
namespace backup {
//! Encrypted session data using the m.megolm_backup.v1.curve25519-aes-sha2 algorithm
struct EncryptedSessionData
@@ -177,6 +183,7 @@ from_json(const nlohmann::json &obj, BackupVersion &response);
void
to_json(nlohmann::json &obj, const BackupVersion &response);
+//! The SessionData stored in the KeysBackup.
struct SessionData
{
//! Required. The end-to-end message encryption algorithm that the key is
diff --git a/include/mtx/responses/empty.hpp b/include/mtx/responses/empty.hpp
index cf742761a..dc4ab9e4c 100644
--- a/include/mtx/responses/empty.hpp
+++ b/include/mtx/responses/empty.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Empty responses returned by different endpoints.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/responses/groups.hpp b/include/mtx/responses/groups.hpp
index b7012ac0c..dcd20ebcd 100644
--- a/include/mtx/responses/groups.hpp
+++ b/include/mtx/responses/groups.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Groups related endpoints.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -8,18 +11,22 @@
namespace mtx {
namespace responses {
-
+//! The list of joined groups.
struct JoinedGroups
{
+ //! joined group ids.
std::vector<std::string> groups;
};
void
from_json(const nlohmann::json &obj, JoinedGroups &res);
+//! The profile of a group.
struct GroupProfile
{
+ //! The group name.
std::string name;
+ //! The group avatar.
std::string avatar_url;
};
diff --git a/include/mtx/responses/login.hpp b/include/mtx/responses/login.hpp
index e38f30e9e..ee243eabf 100644
--- a/include/mtx/responses/login.hpp
+++ b/include/mtx/responses/login.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Login related responses.
+
#include <optional>
#include <string>
@@ -37,8 +40,10 @@ struct Login
void
from_json(const nlohmann::json &obj, Login &response);
+//! One supported login flow.
struct LoginFlow
{
+ //! The authentication used for this flow.
mtx::user_interactive::AuthType type;
};
void
@@ -47,6 +52,7 @@ from_json(const nlohmann::json &obj, LoginFlow &response);
//! Response from the `GET /_matrix/client/r0/login` endpoint.
struct LoginFlows
{
+ //! The list of supported flows.
std::vector<LoginFlow> flows;
};
diff --git a/include/mtx/responses/media.hpp b/include/mtx/responses/media.hpp
index c40e7d0f8..acc44695d 100644
--- a/include/mtx/responses/media.hpp
+++ b/include/mtx/responses/media.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Responses returned by the media repo.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/responses/messages.hpp b/include/mtx/responses/messages.hpp
index 1bf7da48e..e5de898fe 100644
--- a/include/mtx/responses/messages.hpp
+++ b/include/mtx/responses/messages.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Reponses from the message pagination API.
+
#include <string>
#if __has_include(<nlohmann/json_fwd.hpp>)
diff --git a/include/mtx/responses/notifications.hpp b/include/mtx/responses/notifications.hpp
index afefcab7c..1f0974b9b 100644
--- a/include/mtx/responses/notifications.hpp
+++ b/include/mtx/responses/notifications.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Notification related endpoints.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -12,6 +15,7 @@
namespace mtx {
namespace responses {
+//! Description for a notification.
struct Notification
{
//! The action to perform when the conditions for this rule are met.
diff --git a/include/mtx/responses/profile.hpp b/include/mtx/responses/profile.hpp
index d1a046b61..a7781f689 100644
--- a/include/mtx/responses/profile.hpp
+++ b/include/mtx/responses/profile.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Responses from the profile API.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/responses/register.hpp b/include/mtx/responses/register.hpp
index 4a1c16546..3ae65b703 100644
--- a/include/mtx/responses/register.hpp
+++ b/include/mtx/responses/register.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Responses from the registration API.
+
#include <string>
#if __has_include(<nlohmann/json_fwd.hpp>)
diff --git a/include/mtx/responses/sync.hpp b/include/mtx/responses/sync.hpp
index 0c1f5fd36..f14591389 100644
--- a/include/mtx/responses/sync.hpp
+++ b/include/mtx/responses/sync.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Response from the /sync API.
+
#include <map>
#include <string>
#include <vector>
diff --git a/include/mtx/responses/turn_server.hpp b/include/mtx/responses/turn_server.hpp
index c8fe10379..5c4fa3d5e 100644
--- a/include/mtx/responses/turn_server.hpp
+++ b/include/mtx/responses/turn_server.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Responses for the turn server used for calls.
+
#include <string>
#include <vector>
diff --git a/include/mtx/responses/version.hpp b/include/mtx/responses/version.hpp
index 28b44f11b..23a2cb09f 100644
--- a/include/mtx/responses/version.hpp
+++ b/include/mtx/responses/version.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Return value of the server and API version query.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtx/responses/well-known.hpp b/include/mtx/responses/well-known.hpp
index 98c246aa6..9e5a64aad 100644
--- a/include/mtx/responses/well-known.hpp
+++ b/include/mtx/responses/well-known.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Response for .well-known lookup.
+
#include <optional>
#if __has_include(<nlohmann/json_fwd.hpp>)
@@ -10,6 +13,7 @@
namespace mtx {
namespace responses {
+//! The info about this server.
struct ServerInformation
{
//! Required. The base URL for client-server connections.
diff --git a/include/mtx/secret_storage.hpp b/include/mtx/secret_storage.hpp
index f6b9ac845..15c0af033 100644
--- a/include/mtx/secret_storage.hpp
+++ b/include/mtx/secret_storage.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Header with SSSS related types.
+
#include <cstdint>
#include <map>
#include <optional>
@@ -26,6 +29,7 @@ constexpr const char cross_signing_user_signing[] = "m.cross_signing.user_signin
constexpr const char cross_signing_master[] = "m.cross_signing.master";
}
+//! A aes-hmac-sha2 encrypted secret.
struct AesHmacSha2EncryptedData
{
std::string iv; //!< Required. The 16-byte initialization vector, encoded as base64.
@@ -39,6 +43,7 @@ to_json(nlohmann::json &obj, const AesHmacSha2EncryptedData &data);
void
from_json(const nlohmann::json &obj, AesHmacSha2EncryptedData &data);
+//! A secret, encrypted with one or more algorithms.
struct Secret
{
/// @brief Required. Map from key ID the encrypted data.
@@ -54,6 +59,7 @@ to_json(nlohmann::json &obj, const Secret &secret);
void
from_json(const nlohmann::json &obj, Secret &secret);
+//! Information about the key derivation from a passphrase.
struct PBKDF2
{
//! Required. Must be m.pbkdf2
@@ -72,6 +78,7 @@ to_json(nlohmann::json &obj, const PBKDF2 &desc);
void
from_json(const nlohmann::json &obj, PBKDF2 &desc);
+//! Description of the key for a secret.
struct AesHmacSha2KeyDescription
{
std::string name; //!< Required. The name of the key.
diff --git a/include/mtx/user_interactive.hpp b/include/mtx/user_interactive.hpp
index 90c36cc6b..90825c4bb 100644
--- a/include/mtx/user_interactive.hpp
+++ b/include/mtx/user_interactive.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Header with types for user interactive authentication
+
#include <string>
#include <string_view>
#include <unordered_map>
@@ -13,61 +16,86 @@
#endif
namespace mtx {
+//! Types and definitions for user interactive authentication.
namespace user_interactive {
+//! The type of the different auth types.
using AuthType = std::string;
+//! The different auth types.
namespace auth_types {
+//! Password based authentication.
constexpr std::string_view password = "m.login.password";
+//! Authentication using a ReCaptcha.
constexpr std::string_view recaptcha = "m.login.recaptcha";
+//! Authentication using oauth2.
constexpr std::string_view oauth2 = "m.login.oauth2";
+//! Authentication via email.
constexpr std::string_view email_identity = "m.login.email.identity";
+//! Authentication using SMS?
constexpr std::string_view msisdn = "m.login.msisdn";
+//! Token based auth.
constexpr std::string_view token = "m.login.token";
+//! Single Sign On.
constexpr std::string_view sso = "m.login.sso"; // needed for /login at least
+//! Placeholder used in alternative auth flows.
constexpr std::string_view dummy = "m.login.dummy";
+//! Authentication by accepting a set of terms like a privacy policy.
constexpr std::string_view terms = "m.login.terms"; // see MSC1692
}
+//! A list of auth types
using Stages = std::vector<AuthType>;
+//! A flow composed of a list of stages
struct Flow
{
+ //! The stages to complete.
Stages stages;
};
void
from_json(const nlohmann::json &obj, Flow &flow);
+
+//! Parameters for oauth2.
struct OAuth2Params
{
+ //! The oauth uri
std::string uri;
};
void
from_json(const nlohmann::json &obj, OAuth2Params ¶ms);
+//! The desciption of one policy in the terms and conditions.
struct PolicyDescription
{
- std::string name; // language specific name
- std::string url; // language specific link
+ std::string name; //!< language specific name
+ std::string url; //!< language specific link
};
void
from_json(const nlohmann::json &obj, PolicyDescription &desc);
+//! A policy in the terms and conditions.
struct Policy
{
+ //! Version of this policy
std::string version;
- // 2 letter language code to policy name and link, fallback to "en"
- // recommended, when language not available.
+ /// @brief 2 letter language code to policy name and link, fallback to "en"
+ /// recommended, when language not available.
std::unordered_map<std::string, PolicyDescription> langToPolicy;
};
void
from_json(const nlohmann::json &obj, Policy &policy);
+//! Parameters for the auth stage requiring you to accept terms and conditions.
struct TermsParams
{
+ //! The different policies by name.
std::unordered_map<std::string, Policy> policies;
};
void
from_json(const nlohmann::json &obj, TermsParams ¶ms);
+//! All the different parameters.
using Params = std::variant<OAuth2Params, TermsParams, std::string>;
+//! The struct returned on requests failing with 401.
struct Unauthorized
{
// completed stages
@@ -85,16 +113,21 @@ struct Unauthorized
void
from_json(const nlohmann::json &obj, Unauthorized &unauthorized);
+//! namespace for the request types in the different auth stages.
namespace auth {
+//! Password stage
struct Password
{
+ //! The password set by the user.
std::string password;
+ //! Types of identifiers.
enum IdType
{
- UserId,
- ThirdPartyId
+ UserId, //!< Use the identifier_user
+ ThirdPartyId //!< use identifier_medium and identifier_address
};
+ //! If a user or third party identifier is used.
IdType identifier_type;
//! for user
@@ -105,12 +138,14 @@ struct Password
std::string identifier_address;
};
+//! ReCaptcha stage.
struct ReCaptcha
{
//! The recaptcha response
std::string response;
};
+//! Token stage.
struct Token
{
//! the obtained token
@@ -119,6 +154,7 @@ struct Token
std::string txn_id;
};
+//! Third party identifier for Email or MSISDN stages
struct ThreePIDCred
{
//! identity server session id
@@ -130,11 +166,15 @@ struct ThreePIDCred
//! access token previously registered with the identity server
std::string id_access_token;
};
+
+//! Email authentication stage.
struct EmailIdentity
{
// The 3rd party ids
std::vector<ThreePIDCred> threepidCreds;
};
+
+//! SMS authentication stage.
struct MSISDN
{
// The 3rd party ids
@@ -144,15 +184,21 @@ struct MSISDN
//! OAuth2, client retries with the session only, so I'm guessing this is empty?
struct OAuth2
{};
+//! Empty struct, when parameters are accepted.
struct Terms
{};
+//! Empty struct to complete SSO.
struct SSO
{};
+//! Empty struct to complete dummy auth.
struct Dummy
{};
+//! Fallback auth.
struct Fallback
{};
}
+
+//! The auth request to complete a stage.
struct Auth
{
//! the session id
diff --git a/include/mtxclient/crypto/client.hpp b/include/mtxclient/crypto/client.hpp
index b6894071a..bd60ee7d8 100644
--- a/include/mtxclient/crypto/client.hpp
+++ b/include/mtxclient/crypto/client.hpp
@@ -1,5 +1,9 @@
#pragma once
+/// @file
+/// @brief Holds most of the crypto functions and errors as well as a Client, which does the Olm
+/// account bookkeeping for you.
+
#include <exception>
#include <memory>
#include <new>
@@ -105,20 +109,36 @@ unpickle(const std::string &pickled, const std::string &key)
return object;
}
+//! Return value from decrypting a group message.
struct GroupPlaintext
{
+ //! The plain text, which was decrypted.
BinaryBuf data;
+ //! The message index used for this message.
uint32_t message_index;
};
//! Helper to generate Short Authentication Strings (SAS)
struct SAS
{
+ //! Create a new SAS object.
SAS();
+ //! Query the public key generated for this object.
std::string public_key();
+ //! Set the key of the other party being verified.
void set_their_key(std::string their_public_key);
+ /// @brief Returns 3 integers ranging from 1000 to 9191, to be used only after
+ /// using `set_their_key`
+ ///
+ /// These are meant to be compared by the users verifying each other.
std::vector<int> generate_bytes_decimal(std::string info);
+ /// @brief Returns 7 integers in the range from 0 to 63, to be used only after using
+ /// `set_their_key`
+ ///
+ /// Map these numpers to one of the 64 emoji from the specification and let the user compare
+ /// them.
std::vector<int> generate_bytes_emoji(std::string info);
+ //! Calculate MACs after verification to verify keys.
std::string calculate_mac(std::string input_data, std::string info);
private:
@@ -147,15 +167,20 @@ class OlmClient : public std::enable_shared_from_this<OlmClient>
{
public:
OlmClient() = default;
+ //! Initialize a crypto client for the specified device of the specified user.
OlmClient(std::string user_id, std::string device_id)
: user_id_(std::move(user_id))
, device_id_(std::move(device_id))
{}
+ //! Base64 encoded string
using Base64String = std::string;
+ //! A signed set of one time keys indexed by `<algorithm>:<key_id>`.
using SignedOneTimeKeys = std::map<std::string, requests::SignedOneTimeKey>;
+ //! Set the id of this device.
void set_device_id(std::string device_id) { device_id_ = std::move(device_id); }
+ //! Set the id of this user.
void set_user_id(std::string user_id) { user_id_ = std::move(user_id); }
//! Sign the given message.
@@ -163,8 +188,11 @@ public:
//! Create a new olm Account. Must be called before any other operation.
void create_new_account();
+ //! Create a new olm utility object.
void create_new_utility() { utility_ = create_olm_object<UtilityObject>(); }
+ /// @brief Restore the olm account from a pickled string encrypted by `key`
+ /// @see load
void restore_account(const std::string &saved_data, const std::string &key);
//! Retrieve the json representation of the identity keys for the given account.
@@ -190,6 +218,7 @@ public:
//! Prepare request for the /keys/upload endpoint by signing identity & one time keys.
mtx::requests::UploadKeys create_upload_keys_request(const OneTimeKeys &keys);
+ //! Prepare an empty /keys/upload request.
mtx::requests::UploadKeys create_upload_keys_request();
//! Decrypt a message using megolm.
@@ -206,17 +235,40 @@ public:
std::size_t msg_type,
const std::string &msg);
- //! Create an outbount megolm session.
+ /// @brief Create an outbound megolm session.
+ /// @sa init_inbound_group_session(const std::string&), import_inbound_group_session()
OutboundGroupSessionPtr init_outbound_group_session();
+ /// @brief Initialize an inbound group session from a shared session key (an m.room_key
+ /// event).
+ /// @sa init_inbound_group_session(), import_inbound_group_session()
InboundGroupSessionPtr init_inbound_group_session(const std::string &session_key);
+ /// @brief Initialize an inbound group session from a forwarded session key (an
+ /// m.forwarded_room_key event).
+ /// @sa init_inbound_group_session(const std::string&), init_inbound_group_session()
InboundGroupSessionPtr import_inbound_group_session(const std::string &session_key);
+
+ /// @brief create an outbound session to encrypt to device messages.
+ /// @param identity_key The curve25519 key of the other party.
+ /// @param one_time_key The claimed one time key of the other party.
OlmSessionPtr create_outbound_session(const std::string &identity_key,
const std::string &one_time_key);
+ /// @brief Creates an inbound session from an inbound message. DON'T USE THIS, use
+ /// create_inbound_session_from() instead.
+ /// @sa create_inbound_session_from()
OlmSessionPtr create_inbound_session(const BinaryBuf &one_time_key_message);
+ /// @brief Creates an inbound session from an inbound message. DON'T USE THIS, use
+ /// create_inbound_session_from() instead.
+ /// @sa create_inbound_session_from()
OlmSessionPtr create_inbound_session(const std::string &one_time_key_message);
+ /// @brief Create an inbound olm session from the other users message and identity key
+ /// @sa create_inbound_session_from(const std::string&, const std::string&),
+ /// create_outbound_session(), create_inbound_session()
OlmSessionPtr create_inbound_session_from(const std::string &their_curve25519,
const BinaryBuf &one_time_key_message);
+ /// @brief Create an inbound olm session from the other users message and identity key
+ /// @sa create_inbound_session_from(const std::string&, const BinaryBuf&),
+ /// create_outbound_session(), create_inbound_session()
OlmSessionPtr create_inbound_session_from(const std::string &their_curve25519,
const std::string &one_time_key_message);
@@ -228,13 +280,18 @@ public:
const std::string &recipient_ed25519_key,
const std::string &recipient_curve25519_key);
+ //! store the account in a pickled string encrypted by `key`
std::string save(const std::string &key);
+ /// @brief Restore the account from a pickled string encrypted by `key`
+ /// @see restore_account
void load(const std::string &data, const std::string &key)
{
account_ = unpickle<AccountObject>(data, key);
}
+ //! Access the olm account directly.
OlmAccount *account() { return account_.get(); }
+ //! Access the olm utility object directly.
OlmUtility *utility() { return utility_.get(); }
//! SAS related stuff
@@ -269,17 +326,23 @@ export_session(OlmInboundGroupSession *s);
InboundGroupSessionPtr
import_session(const std::string &session_key);
+/// Checks if an inbound session matches a pre key message.
+///
+/// Use matches_inbound_session_from() instead.
bool
matches_inbound_session(OlmSession *session, const std::string &one_time_key_message);
+//! Checks if an inbound session matches a pre key message
bool
matches_inbound_session_from(OlmSession *session,
const std::string &id_key,
const std::string &one_time_key_message);
+//! Encrypt the exported sessions according to the export format from the spec.
std::string
encrypt_exported_sessions(const mtx::crypto::ExportedSessionKeys &keys, std::string pass);
+//! Decrypt the exported sessions according to the export format from the spec.
mtx::crypto::ExportedSessionKeys
decrypt_exported_sessions(const std::string &data, std::string pass);
diff --git a/include/mtxclient/crypto/objects.hpp b/include/mtxclient/crypto/objects.hpp
index 9303940df..faf1a22cd 100644
--- a/include/mtxclient/crypto/objects.hpp
+++ b/include/mtxclient/crypto/objects.hpp
@@ -1,5 +1,10 @@
#pragma once
+/// @file
+/// @brief Wrappers around the various Olm types.
+///
+/// The wrappers implement RAII semantics, so you don't need to free stuff manually.
+
#include <memory>
#include <olm/olm.h>
#include <olm/pk.h>
@@ -8,6 +13,19 @@
namespace mtx {
namespace crypto {
+/// @brief Deleter type to pass as a template argument to most smart pointers.
+///
+/// Can be used like so:
+///
+/// ```{.cpp}
+/// std::unique_ptr<OlmAccount, OlmDeleter> olmAccount = new uint8_t[olm_account_size()];
+/// ```
+///
+/// In general the coresponding *Object type should be preffered as a wapper, for example:
+///
+/// ```{.cpp}
+/// SASPtr sas = create_olm_object<SASObject>();
+/// ```
struct OlmDeleter
{
void operator()(OlmAccount *ptr) { delete[](reinterpret_cast<uint8_t *>(ptr)); }
@@ -25,6 +43,7 @@ struct OlmDeleter
void operator()(OlmSAS *ptr) { delete[](reinterpret_cast<uint8_t *>(ptr)); }
};
+//! Olm type for Short Authentication Strings.
struct SASObject
{
using olm_type = OlmSAS;
@@ -32,6 +51,7 @@ struct SASObject
static olm_type *allocate() { return olm_sas(new uint8_t[olm_sas_size()]); }
};
+//! Wrapper for the Olm utility object.
struct UtilityObject
{
using olm_type = OlmUtility;
@@ -39,6 +59,7 @@ struct UtilityObject
static olm_type *allocate() { return olm_utility(new uint8_t[olm_utility_size()]); }
};
+//! Wrapper for the olm object to do Private Key Decryption.
struct PkDecryptionObject
{
using olm_type = OlmPkDecryption;
@@ -49,6 +70,7 @@ struct PkDecryptionObject
}
};
+//! Wrapper for the olm object to do Private Key Signing.
struct PkSigningObject
{
using olm_type = OlmPkSigning;
@@ -56,6 +78,7 @@ struct PkSigningObject
static olm_type *allocate() { return olm_pk_signing(new uint8_t[olm_pk_signing_size()]); }
};
+//! Wrapper for the olm account object.
struct AccountObject
{
using olm_type = OlmAccount;
@@ -86,6 +109,7 @@ struct AccountObject
}
};
+//! Wrapper around olm sessions used for to device encryption.
struct SessionObject
{
using olm_type = OlmSession;
@@ -116,6 +140,8 @@ struct SessionObject
}
};
+//! Wrapper around the olm object for inbound group sessions used to decrypt messages in matrix
+//! rooms.
struct InboundSessionObject
{
using olm_type = OlmInboundGroupSession;
@@ -151,6 +177,8 @@ struct InboundSessionObject
}
};
+//! Wrapper around the outbound olm session object used to encrypt outbound group messages in matrix
+//! rooms.
struct OutboundSessionObject
{
using olm_type = OlmOutboundGroupSession;
@@ -186,6 +214,7 @@ struct OutboundSessionObject
}
};
+//! Allocates an olm object using the mtxclient wrapper type.
template<class T>
std::unique_ptr<typename T::olm_type, OlmDeleter>
create_olm_object()
diff --git a/include/mtxclient/crypto/types.hpp b/include/mtxclient/crypto/types.hpp
index 455b98dfb..b4cdc3cff 100644
--- a/include/mtxclient/crypto/types.hpp
+++ b/include/mtxclient/crypto/types.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Various type definitions for the crypto API.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
@@ -8,40 +11,61 @@
namespace mtx {
namespace crypto {
-
+//! Constant for ed25519 keys
constexpr auto ED25519 = "ed25519";
+//! Constant for curve25519 keys
constexpr auto CURVE25519 = "curve25519";
+//! Constant for signed curve25519 keys
constexpr auto SIGNED_CURVE25519 = "signed_curve25519";
+//! The algorithm used for group messages.
constexpr auto MEGOLM_ALGO = "m.megolm.v1.aes-sha2";
+//! An exported megolm group session
struct ExportedSession
{
- std::map<std::string, std::string> sender_claimed_keys; // currently unused.
+ //! Required. The Ed25519 key of the device which initiated the session originally.
+ std::map<std::string, std::string> sender_claimed_keys; // currently unused.
+ //! Required. Chain of Curve25519 keys through which this session was forwarded, via
+ //! m.forwarded_room_key events.
std::vector<std::string> forwarding_curve25519_key_chain; // currently unused.
+ //! Required. The encryption algorithm that the session uses. Must be m.megolm.v1.aes-sha2.
std::string algorithm = MEGOLM_ALGO;
+ //! Required. The room where the session is used.
std::string room_id;
+ //! Required. The Curve25519 key of the device which initiated the session originally.
std::string sender_key;
+ //! Required. The ID of the session.
std::string session_id;
+ //! Required. The key for the session.
std::string session_key;
};
+//! A list of exported sessions.
struct ExportedSessionKeys
{
+ //! The actual sessions.
std::vector<ExportedSession> sessions;
};
+//! A pair of keys connected to an olm account.
struct IdentityKeys
{
+ //! The identity key.
std::string curve25519;
+ //! The signing key.
std::string ed25519;
};
+//! A list of one time keys.
struct OneTimeKeys
{
+ //! The key id type.
using KeyId = std::string;
+ //! The type for the keys.
using EncodedKey = std::string;
+ //! The one time keys by key id.
std::map<KeyId, EncodedKey> curve25519;
};
diff --git a/include/mtxclient/crypto/utils.hpp b/include/mtxclient/crypto/utils.hpp
index 61573a42c..ffb4c490e 100644
--- a/include/mtxclient/crypto/utils.hpp
+++ b/include/mtxclient/crypto/utils.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Various crypto functions.
+
#include <string>
#include <vector>
@@ -25,7 +28,7 @@ private:
std::string msg_;
};
-//! Data representation used to interact with libolm.
+//! Data representation used to interact with libolm. It's a contiguous buffer of bytes.
using BinaryBuf = std::vector<uint8_t>;
const std::string HEADER_LINE("-----BEGIN MEGOLM SESSION DATA-----");
@@ -35,6 +38,7 @@ const std::string TRAILER_LINE("-----END MEGOLM SESSION DATA-----");
BinaryBuf
create_buffer(std::size_t nbytes);
+//! Convert a string to a binary buffer.
inline BinaryBuf
to_binary_buf(const std::string &str)
{
@@ -42,6 +46,7 @@ to_binary_buf(const std::string &str)
reinterpret_cast<const uint8_t *>(str.data()) + str.size());
}
+//! Convert a binary buffer to a string.
inline std::string
to_string(const BinaryBuf &buf)
{
@@ -55,14 +60,18 @@ PBKDF2_HMAC_SHA_512(const std::string pass,
uint32_t iterations,
uint32_t keylen = 64);
+//! Derive the SSSS decryption key from a passphrase using the parameters stored in account_data.
std::optional<BinaryBuf>
key_from_passphrase(const std::string &password,
const mtx::secret_storage::AesHmacSha2KeyDescription ¶meters);
+//! Derive the SSSS decryption key from a base58 encoded recoverykey using the parameters stored in
+//! account_data.
std::optional<BinaryBuf>
key_from_recoverykey(const std::string &recoverkey,
const mtx::secret_storage::AesHmacSha2KeyDescription ¶meters);
+//! Decrypt a secret from SSSS
std::string
decrypt(const mtx::secret_storage::AesHmacSha2EncryptedData &data,
BinaryBuf decryptionKey,
@@ -89,6 +98,7 @@ CURVE25519_AES_SHA2_Decrypt(std::string base64_ciphertext,
const std::string &ephemeral,
const std::string &mac);
+//! Decrypt a session retrieved from online key backup.
mtx::responses::backup::SessionData
decrypt_session(const mtx::responses::backup::EncryptedSessionData &data,
const BinaryBuf &privateKey);
@@ -96,6 +106,7 @@ decrypt_session(const mtx::responses::backup::EncryptedSessionData &data,
BinaryBuf
HMAC_SHA256(const BinaryBuf hmacKey, const BinaryBuf data);
+//! Sha256 a string.
std::string
sha256(const std::string &data);
@@ -126,27 +137,35 @@ uint32_to_uint8(uint8_t b[4], uint32_t u32);
void
print_binary_buf(const BinaryBuf buf);
+//! Convert base64 to binary
std::string
base642bin(const std::string &b64);
+//! Encode a binary string in base64.
std::string
bin2base64(const std::string &bin);
+//! Decode unpadded base64 to binary.
std::string
base642bin_unpadded(const std::string &b64);
+//! Encode binary in unpadded base64.
std::string
bin2base64_unpadded(const std::string &bin);
+//! Decode urlsafe, unpadded base64 to binary.
std::string
base642bin_urlsafe_unpadded(const std::string &b64);
+//! Encode binary in urlsafe, unpadded base64.
std::string
bin2base64_urlsafe_unpadded(const std::string &bin);
+//! Encode binary in base58.
std::string
bin2base58(const std::string &bin);
+//! Decode base58 to binary.
std::string
base582bin(const std::string &bin);
} // namespace crypto
diff --git a/include/mtxclient/http/client.hpp b/include/mtxclient/http/client.hpp
index 7ca135873..381facfd8 100644
--- a/include/mtxclient/http/client.hpp
+++ b/include/mtxclient/http/client.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Primary header to access the http API.
+
#if __has_include(<nlohmann/json_fwd.hpp>)
#include <nlohmann/json_fwd.hpp>
#else
diff --git a/include/mtxclient/http/client_impl.hpp b/include/mtxclient/http/client_impl.hpp
index 4051880a4..eb2156fca 100644
--- a/include/mtxclient/http/client_impl.hpp
+++ b/include/mtxclient/http/client_impl.hpp
@@ -1,13 +1,24 @@
#pragma once
+/// @file
+/// @brief All the template stuff needed for the http client.
+///
+/// If you implement custom event types, this can be useful, but in general including this header
+/// just adds compile time without any benefits.
+
#include "client.hpp"
#include "mtxclient/utils.hpp" // for random_token, url_encode, des...
#include <nlohmann/json.hpp>
namespace mtx {
+//! A few helpers for the http client.
namespace client {
namespace utils {
+
+/// @brief deserialize a type or string from json.
+///
+/// Used internally to deserialize the response types for the various http methods.
template<class T>
inline T
deserialize(const std::string &data)
@@ -22,6 +33,9 @@ deserialize<std::string>(const std::string &data)
return data;
}
+/// @brief serialize a type or string to json.
+///
+/// Used internally to serialize the request types for the various http methods.
template<class T>
inline std::string
serialize(const T &obj)
diff --git a/include/mtxclient/http/errors.hpp b/include/mtxclient/http/errors.hpp
index aeb9ed2bf..853de39f9 100644
--- a/include/mtxclient/http/errors.hpp
+++ b/include/mtxclient/http/errors.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Error codes returned by the client-server API
+
#include "mtx/errors.hpp"
#include <boost/beast/http/status.hpp>
#include <boost/system/error_code.hpp>
diff --git a/include/mtxclient/http/session.hpp b/include/mtxclient/http/session.hpp
index 928de06b9..0d90362ff 100644
--- a/include/mtxclient/http/session.hpp
+++ b/include/mtxclient/http/session.hpp
@@ -1,5 +1,10 @@
#pragma once
+/// @file
+/// @brief A single http session, which is the context for a single http request.
+///
+/// You usually don't need to include this as session handling is handled by the library for you.
+
#include <boost/asio.hpp>
#include <boost/asio/ssl.hpp>
#include <boost/beast.hpp>
diff --git a/include/mtxclient/utils.hpp b/include/mtxclient/utils.hpp
index ee98310b1..00ddf99bf 100644
--- a/include/mtxclient/utils.hpp
+++ b/include/mtxclient/utils.hpp
@@ -1,5 +1,8 @@
#pragma once
+/// @file
+/// @brief Various utility functions for http requests.
+
#include <boost/iostreams/device/array.hpp>
#include <iosfwd>
#include <map>
@@ -7,6 +10,7 @@
namespace mtx {
namespace client {
+//! Utility namespace.
namespace utils {
//! Representation of Matrix Content (MXC) URIs.
diff --git a/lib/crypto/client.cpp b/lib/crypto/client.cpp
index f75a6e547..b64e7517d 100644
--- a/lib/crypto/client.cpp
+++ b/lib/crypto/client.cpp
@@ -419,7 +419,6 @@ SAS::SAS()
throw olm_exception("create_sas_instance", this->sas.get());
}
-//! returns the public key of the key-pair created
std::string
SAS::public_key()
{
@@ -434,7 +433,6 @@ SAS::public_key()
return to_string(pub_key_buffer);
}
-//! this is for setting the public key of the other user
void
SAS::set_their_key(std::string their_public_key)
{
@@ -447,8 +445,6 @@ SAS::set_their_key(std::string their_public_key)
throw olm_exception("get_public_key", this->sas.get());
}
-//! generates and returns a vector of numbers(int) ranging from 0 to 8191, to be used only after
-//! using `set_their_key`
std::vector<int>
SAS::generate_bytes_decimal(std::string info)
{
--
GitLab