mtx::http::Client class

#include <include/mtxclient/http/client.hpp>

Public functions

void alt_svc_cache_path(const std::string& path)

Set a path to cache alternate service lookups like the http/3 ports of a server.

void close(bool force = false)

Wait for the client to close.

void verify_certificates(bool enabled = true)

Enable or disable certificate verification. On by default.

void set_user(const mtx::identifiers::User& user)

Set the homeserver domain name.

void set_device_id(const std::string& device_id)

Set the device ID.

void set_server(const std::string& server)

Set the homeserver domain name.

auto server() -> std::string

Retrieve the homeserver domain name.

auto server_url() -> std::string

Retrieve the full server url including protocol and ports.

void set_port(uint16_t port)

Set the homeserver port.

auto port() -> uint16_t

Retrieve the homeserver port.

void set_access_token(const std::string& token)

Add an access token.

auto access_token() const -> std::string

Retrieve the access token.

void set_next_batch_token(const std::string& token)

Update the next batch token.

auto next_batch_token() const -> std::string

Retrieve the current next batch token.

auto user_id() const -> mtx::identifiers::User

Retrieve the user_id.

auto device_id() const -> std::string

Retrieve the device_id.

auto generate_txn_id() -> std::string

Generate a new transaction id.

void shutdown()

Abort all active pending requests.

void clear()

Remove all saved configuration.

void login(const std::string& username, const std::string& password, Callback<mtx::responses::Login> cb)

Perfom login.

void get_login(Callback<mtx::responses::LoginFlows> cb)

Get the supported login flows.

auto login_sso_redirect(std::string redirectUrl, const std::string& idp = "") -> std::string

Get url to navigate to for sso login flow, optionally preselecting an identity provider Open this in a browser.

void well_known(Callback<mtx::responses::WellKnown> cb)

Lookup real server to connect to. Call set_server with the returned homeserver url after this.

void register_username_available(const std::string& username, Callback<mtx::responses::Available> cb)

Check for username availability.

void registration(const std::string& user, const std::string& pass, UIAHandler uia_handler, Callback<mtx::responses::Register> cb, const std::string& initial_device_display_name = "")

Register with an UIA handler so you don't need to repeat the request manually.

void registration(Callback<mtx::responses::Register> cb)

Send a dummy registration request to query the auth flows.

void registration_token_validity(const std::string token, Callback<mtx::responses::RegistrationTokenValidity> cb)

Check the validity of a registration token.

void register_email_request_token(const requests::RequestEmailToken& r, Callback<mtx::responses::RequestToken> cb)

Validate an unused email address.

void verify_email_request_token(const requests::RequestEmailToken& r, Callback<mtx::responses::RequestToken> cb)

Validate a used email address.

void register_phone_request_token(const requests::RequestMSISDNToken& r, Callback<mtx::responses::RequestToken> cb)

Validate an unused phone number.

void verify_phone_request_token(const requests::RequestMSISDNToken& r, Callback<mtx::responses::RequestToken> cb)

Validate a used phone number.

void validate_submit_token(const std::string& url, const requests::IdentitySubmitToken& r, Callback<mtx::responses::Success>)

Validate ownership of an email address/phone number.

void notifications(uint64_t limit, const std::string& from, const std::string& only, Callback<mtx::responses::Notifications> cb)

Paginate through the list of events that the user has been, or would have been notified about.

void get_pushrules(Callback<pushrules::GlobalRuleset> cb)

Retrieve all push rulesets for this user.

void get_pushrules(const std::string& scope, const std::string& kind, const std::string& ruleId, Callback<pushrules::PushRule> cb)

Retrieve a single specified push rule.

void delete_pushrules(const std::string& scope, const std::string& kind, const std::string& ruleId, ErrCallback cb)

This endpoint removes the push rule defined in the path.

void put_pushrules(const std::string& scope, const std::string& kind, const std::string& ruleId, const pushrules::PushRule& rule, ErrCallback cb, const std::string& before = "", const std::string& after = "")

This endpoint allows the creation, modification and deletion of pushers for this user ID.

void get_pushrules_enabled(const std::string& scope, const std::string& kind, const std::string& ruleId, Callback<pushrules::Enabled> cb)

Retrieve a single specified push rule.

void put_pushrules_enabled(const std::string& scope, const std::string& kind, const std::string& ruleId, bool enabled, ErrCallback cb)

This endpoint allows clients to enable or disable the specified push rule.

void get_pushrules_actions(const std::string& scope, const std::string& kind, const std::string& ruleId, Callback<pushrules::actions::Actions> cb)

This endpoint get the actions for the specified push rule.

void put_pushrules_actions(const std::string& scope, const std::string& kind, const std::string& ruleId, const pushrules::actions::Actions& actions, ErrCallback cb)

This endpoint allows clients to change the actions of a push rule. This can be used to change the actions of builtin rules.

void logout(Callback<mtx::responses::Logout> cb)

Perform logout.

void set_avatar_url(const std::string& avatar_url, ErrCallback cb)

Change avatar.

void set_displayname(const std::string& displayname, ErrCallback cb)

Change displayname.

void get_profile(const std::string& user_id, Callback<mtx::responses::Profile> cb)

Get user profile.

void get_avatar_url(const std::string& user_id, Callback<mtx::responses::AvatarUrl> cb)

Get user avatar URL.

void get_tags(const std::string& room_id, Callback<mtx::events::account_data::Tags> cb)

List the tags set by a user on a room.

void put_tag(const std::string& room_id, const std::string& tag_name, const mtx::events::account_data::Tag& tag, ErrCallback cb)

Add a tag to the room.

void delete_tag(const std::string& room_id, const std::string& tag_name, ErrCallback cb)

Remove a tag from the room.

void create_room(const mtx::requests::CreateRoom& room_options, Callback<mtx::responses::CreateRoom> cb)

Create a room with the given options.

void join_room(const std::string& room, Callback<mtx::responses::RoomId> cb)

Join a room by an alias or a room_id.

void join_room(const std::string& room, const std::vector<std::string>& via, Callback<mtx::responses::RoomId> cb, const std::string& reason = "")

Join a room by an alias or a room_id. via are other servers, that may know about this room.

void leave_room(const std::string& room_id, Callback<mtx::responses::Empty> cb, const std::string& reason = "")

Leave a room by its room_id.

void knock_room(const std::string& room_id, const std::vector<std::string>& via, Callback<mtx::responses::RoomId> cb, const std::string& reason = "")

Knock on a room.

void invite_user(const std::string& room_id, const std::string& user_id, Callback<mtx::responses::RoomInvite> cb, const std::string& reason = "")

Invite a user to a room.

void kick_user(const std::string& room_id, const std::string& user_id, Callback<mtx::responses::Empty> cb, const std::string& reason = "")

Kick a user from a room.

void ban_user(const std::string& room_id, const std::string& user_id, Callback<mtx::responses::Empty> cb, const std::string& reason = "")

Ban a user from a room.

void unban_user(const std::string& room_id, const std::string& user_id, Callback<mtx::responses::Empty> cb, const std::string& reason = "")

Unban a user from a room.

void sync(const SyncOpts& opts, Callback<mtx::responses::Sync> cb)

Perform sync.

void members(const std::string& room_id, Callback<mtx::responses::Members> cb, const std::string& at = "", std::optional<mtx::events::state::Membership> membership = {}, std::optional<mtx::events::state::Membership> not_membership = {})

List members in a room.

void messages(const MessagesOpts& opts, Callback<mtx::responses::Messages> cb)

Paginate through room messages.

void versions(Callback<mtx::responses::Versions> cb)

Get the supported versions from the server.

void capabilities(Callback<mtx::responses::capabilities::Capabilities> cb)

Get the supported capabilities from the server.

void read_event(const std::string& room_id, const std::string& event_id, ErrCallback cb, bool hidden = false)

Mark an event as read.

void redact_event(const std::string& room_id, const std::string& event_id, Callback<mtx::responses::EventId> cb, const std::string& reason = "")

Redact an event from a room.

void report_event(const std::string& room_id, const std::string& event_id, const std::string& reason, const int score)

Report an event to the server adminstrator.

void upload_filter(const nlohmann::json& j, Callback<mtx::responses::FilterId> cb)

Upload a filter.

void upload(const std::string& data, const std::string& content_type, const std::string& filename, Callback<mtx::responses::ContentURI> cb)

Upload data to the content repository.

void download(const std::string& mxc_url, std::function<void(const std::string&data, const std::string&content_type, const std::string&original_filename, RequestErr err)> cb)

Retrieve data from the content repository.

void get_thumbnail(const ThumbOpts& opts, Callback<std::string> cb, bool try_download = true)

Retrieve a thumbnail from the given mxc url. If the thumbnail isn't found and try_download is true it will try to use the /download endpoint to retrieve the media.

void start_typing(const std::string& room_id, uint64_t timeout, ErrCallback cb)

Send typing notifications to the room.

void stop_typing(const std::string& room_id, ErrCallback cb)

Remove typing notifications from the room.

void presence_status(const std::string& user_id, Callback<mtx::events::presence::Presence> cb)

Get presence of a user.

void put_presence_status(mtx::presence::PresenceState state, std::optional<std::string> status_msg, ErrCallback cb)

Set presence of the user.

void get_event(const std::string& room_id, const std::string& event_id, Callback<mtx::events::collections::TimelineEvents> cb)

Get a single event.

void get_state(const std::string& room_id, Callback<mtx::responses::StateEvents> payload)

Retrieve the whole state of a room.

template<class Payload>

void get_state_event(const std::string& room_id, const std::string& type, const std::string& state_key, Callback<Payload> payload)

Retrieve a single state event.

template<class Payload>

void get_state_event(const std::string& room_id, const std::string& state_key, Callback<Payload> cb)

Retrieve a single state event.

template<class Payload>

void put_room_account_data(const std::string& room_id, const std::string& type, const Payload& payload, ErrCallback cb)

Store a room account_data event.

template<class Payload>

void put_room_account_data(const std::string& room_id, const Payload& payload, ErrCallback cb)

Store a room account_data event.

template<class Payload>

void put_account_data(const std::string& type, const Payload& payload, ErrCallback cb)

Store an account_data event.

template<class Payload>

void put_account_data(const Payload& payload, ErrCallback cb)

Store an account_data event.

template<class Payload>

void get_room_account_data(const std::string& room_id, const std::string& type, Callback<Payload> payload)

Retrieve a room account_data event.

template<class Payload>

void get_room_account_data(const std::string& room_id, Callback<Payload> cb)

Retrieve a room account_data event.

template<class Payload>

void get_account_data(const std::string& type, Callback<Payload> payload)

Retrieve an account_data event.

template<class Payload>

void get_account_data(Callback<Payload> cb)

Retrieve an account_data event.

template<class Payload>

void send_room_message(const std::string& room_id, const Payload& payload, Callback<mtx::responses::EventId> cb)

Send a room message with auto-generated transaction id.

template<class Payload>

void send_room_message(const std::string& room_id, const std::string& txn_id, const Payload& payload, Callback<mtx::responses::EventId> cb)

Send a room message by providing transaction id.

void send_state_event(const std::string& room_id, const std::string& event_type, const std::string& state_key, const nlohmann::json& payload, Callback<mtx::responses::EventId> callback)

Send a state event by providing the state key.

template<class Payload>

void send_state_event(const std::string& room_id, const Payload& payload, Callback<mtx::responses::EventId> cb)

Send a state event with an empty state key.

void send_to_device(const std::string& event_type, const std::string& txid, const nlohmann::json& body, ErrCallback cb)

Send send-to-device events to a set of client devices with a specified transaction id.

void send_to_device(const std::string& event_type, const nlohmann::json& body, ErrCallback cb)

Send send-to-device events to a set of client devices with a generated transaction id.

template<typename EventContent>

void send_to_device(const std::string& txid, const std::map<mtx::identifiers::User, std::map<std::string, EventContent>>& messages, ErrCallback callback)

Send send-to-device events to a set of client devices with a specified transaction id.

void resolve_room_alias(const std::string& alias, Callback<mtx::responses::RoomId> cb)

Resolve the specified roomalias to a roomid.

void add_room_alias(const std::string& alias, const std::string& roomid, ErrCallback cb)

Add an alias to a room.

void delete_room_alias(const std::string& alias, ErrCallback cb)

Delete an alias from a room.

void list_room_aliases(const std::string& room_id, Callback<mtx::responses::Aliases> cb)

List the local aliases on the users server.

void get_room_visibility(const std::string& room_id, Callback<mtx::responses::PublicRoomVisibility> cb)

Gets the visibility of a given room on the server's public room directory.

void put_room_visibility(const std::string& room_id, const mtx::requests::PublicRoomVisibility& req, ErrCallback cb)

Sets the visibility of a given room in the server's public room directory.

void get_public_rooms(Callback<mtx::responses::PublicRooms> cb, const std::string& server = "", size_t limit = 0, const std::string& since = "")

Lists the public rooms on the server. This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first.

void post_public_rooms(const mtx::requests::PublicRooms& req, Callback<mtx::responses::PublicRooms> cb, const std::string& server = "")

Lists the public rooms on the server, with optional filter. POST Request.

void get_hierarchy(const std::string& room_id, Callback<mtx::responses::HierarchyRooms> cb, const std::string& from = "", size_t limit = 0, size_t max_depth = 0, bool suggested_only = false)

Paginates over the space tree in a depth-first manner to locate child rooms of a given space.

void get_summary(const std::string& room_id, Callback<mtx::responses::PublicRoomsChunk> cb, std::vector<std::string> vias = {})

summarize a room

void query_devices(Callback<mtx::responses::QueryDevices> cb)

List devices.

void get_device(const std::string& device_id, Callback<mtx::responses::Device> cb)

Gets information on a single device, by device id.

void set_device_name(const std::string& device_id, const std::string& display_name, ErrCallback callback)

Updates the display name of the given device id.

void delete_device(const std::string& device_id, UIAHandler uia_handler, ErrCallback cb)

Delete device.

void delete_devices(const std::vector<std::string>& device_ids, UIAHandler uia_handler, ErrCallback cb)

Delete devices.

void enable_encryption(const std::string& room, Callback<mtx::responses::EventId> cb)

Enable encryption in a room by sending a m.room.encryption state event.

void upload_keys(const mtx::requests::UploadKeys& req, Callback<mtx::responses::UploadKeys> cb)

Upload identity keys & one time keys.

void keys_signatures_upload(const mtx::requests::KeySignaturesUpload& req, Callback<mtx::responses::KeySignaturesUpload> cb)

Upload signatures for cross-signing keys.

void device_signing_upload(const mtx::requests::DeviceSigningUpload&, UIAHandler uia_handler, ErrCallback cb)

Upload cross signing keys.

void query_keys(const mtx::requests::QueryKeys& req, Callback<mtx::responses::QueryKeys> cb)

Returns the current devices and identity keys for the given users.

void claim_keys(const mtx::requests::ClaimKeys& req, Callback<mtx::responses::ClaimKeys> cb)

Claims one-time keys for use in pre-key messages.

void key_changes(const std::string& from, const std::string& to, Callback<mtx::responses::KeyChanges> cb)

Gets a list of users who have updated their device identity keys since a previous sync token.

void secret_storage_secret(std::string_view secret_id, Callback<mtx::secret_storage::Secret> cb)

Retrieve a specific secret.

void secret_storage_key(std::string_view key_id, Callback<mtx::secret_storage::AesHmacSha2KeyDescription> cb)

Retrieve information about a key.

void upload_secret_storage_secret(std::string_view secret_id, const mtx::secret_storage::Secret& secret, ErrCallback cb)

Upload a specific secret.

void upload_secret_storage_key(std::string_view key_id, const mtx::secret_storage::AesHmacSha2KeyDescription& desc, ErrCallback cb)

Upload information about a key.

void set_secret_storage_default_key(std::string_view key_id, ErrCallback cb)

Set the default key for the secret storage.

void get_turn_server(Callback<mtx::responses::TurnServer> cb)

Gets any TURN server URIs and authentication credentials.

void set_pusher(const mtx::requests::SetPusher& req, Callback<mtx::responses::Empty> cb)

Sets, updates, or deletes a pusher.

void search_user_directory(const std::string& search_term, Callback<mtx::responses::Users> callback, int limit = -1)

Searches the user directory.

Function documentation