Represent a Matrix client. More...

#include <client.hpp>

Classes
struct	InEventLoopTag

Public Types
using	ActionT = ClientAction

using	DepsT = lager::deps< JobInterface &, EventInterface &, SdkModelCursorKey, RandomInterface & >

using	ContextT = Context< ActionT >

using	ContextWithDepsT = Context< ActionT, DepsT >

using	PromiseT = SingleTypePromise< DefaultRetType >

Public Member Functions
	Client (lager::reader< SdkModel > sdk, ContextT ctx, std::nullopt_t)
	Constructor. More...

	Client (lager::reader< SdkModel > sdk, ContextWithDepsT ctx)
	Constructor. More...

	Client (InEventLoopTag, ContextWithDepsT ctx)
	Constructor. More...

	Client (InEventLoopTag, ContextT ctx, DepsT deps)
	Constructor. More...

Client	toEventLoop () const
	Create a Client that is not constructed from a cursor. More...

auto	rooms () const

auto	roomIds () const

auto	roomIdsUnderTag (std::string tagId) const -> lager::reader< immer::map< std::string, double >>

auto	roomIdsByTagId () const -> lager::reader< immer::map< std::string, immer::map< std::string, double >>>
	Get the room ids under all tags. More...

Room	room (std::string id) const
	Get the room with `id` . More...

Room	roomByCursor (lager::reader< std::string > id) const
	Get the room with `id`. More...

PromiseT	passwordLogin (std::string homeserver, std::string username, std::string password, std::string deviceName) const
	Login using the password. More...

PromiseT	tokenLogin (std::string homeserver, std::string username, std::string token, std::string deviceId) const
	Login using `token` and `deviceId`. More...

auto	shouldSync () const -> lager::reader< bool >
	Get the `shouldSync` field of current ClientModel. More...

PromiseT	logout () const
	Stop syncing and then logout current session. More...

PromiseT	autoDiscover (std::string userId) const
	Automatically discover the homeserver for `userId`. More...

PromiseT	createRoom (RoomVisibility v, std::optional< std::string > name={}, std::optional< std::string > alias={}, immer::array< std::string > invite={}, std::optional< bool > isDirect={}, bool allowFederate=true, std::optional< std::string > topic={}, JsonWrap powerLevelContentOverride=json::object(), std::optional< CreateRoomPreset > preset=std::nullopt, immer::array< Event > initialState=immer::array< Event >()) const
	Create a room. More...

PromiseT	joinRoomById (std::string roomId) const
	Join a room by its id. More...

PromiseT	joinRoom (std::string roomId, immer::array< std::string > serverName) const
	Join a room by its id or alias. More...

PromiseT	uploadContent (immer::box< Bytes > content, std::string uploadId, std::optional< std::string > filename=std::nullopt, std::optional< std::string > contentType=std::nullopt) const
	Upload content to the content repository. More...

PromiseT	uploadContent (FileDesc file) const
	Upload content to the content repository. More...

std::string	mxcUriToHttp (std::string mxcUri) const
	Convert a MXC URI to an HTTP(s) URI. More...

PromiseT	downloadContent (std::string mxcUri, std::optional< FileDesc > downloadTo=std::nullopt) const
	Download content from the content repository. More...

PromiseT	downloadThumbnail (std::string mxcUri, int width, int height, std::optional< ThumbnailResizingMethod > method=std::nullopt, std::optional< FileDesc > downloadTo=std::nullopt) const
	Download a thumbnail from the content repository. More...

PromiseT	getProfile (std::string userId) const
	Fetch the profile of a user. More...

PromiseT	setAvatarUrl (std::optional< std::string > avatarUrl) const
	Change the avatar url of the current user. More...

PromiseT	setDisplayName (std::optional< std::string > displayName) const
	Change the display name of the current user. More...

auto	syncing () const

PromiseT	startSyncing () const
	Start syncing if the Client is not syncing. More...

PromiseT	stopSyncing () const
	Stop the indefinite syncing. More...

auto	devicesOfUser (std::string userId) const -> lager::reader< immer::flex_vector< DeviceKeyInfo >>
	Get the info of all devices of user `userId` that supports encryption. More...

PromiseT	setDeviceTrustLevel (std::string userId, std::string deviceId, DeviceTrustLevel trustLevel) const
	Set the trust level of a device. More...

auto	trustLevelNeededToSendKeys () const -> lager::reader< DeviceTrustLevel >
	Get the trust level needed to send keys to a device. More...

PromiseT	setTrustLevelNeededToSendKeys (DeviceTrustLevel trustLevel) const
	Set the trust level needed to send keys to a device. More...

auto	directRoomMap () const -> lager::reader< immer::map< std::string, std::string >>
	Get the map from direct messaging room ids to user ids. More...

auto	accountData () const -> lager::reader< immer::map< std::string, Event >>
	Get the account data that is not associated with any room. More...

PromiseT	setAccountData (Event accountDataEvent) const
	Set the account data that is not associated with any room. More...

NotificationHandler	notificationHandler () const
	Get a notification handler that works on this Client. More...

template<class Archive >
void	serializeTo (Archive &ar) const
	Serialize the model to a Boost.Serialization archive. More...

Detailed Description

Represent a Matrix client.

If the Client is constructed from a cursor originated from a root whose event loop is on thread A, then we say that the Client belongs to thread A. If the Client is not constructed from a cursor, then we say that the Client belongs to the thread where the event loop of the context runs.

All methods in this class that take a cursor only take a cursor on the same thread as the Client. All methods in this class that return a cursor will return a cursor on the same thread as the Client.

All methods in this class must be run on the same thread as the the Client. If the Client is not constructed from a cursor, copy-constructing another Client from this is safe from any thread. If the Client is constructed from a cursor, copy-constructing another Client is safe only from the same thread as this Client.

Error handling

A lot of functions in Client and Room are asynchronous actions. These actions return the result via a Promise. If an API request has failed, the Promise p will satisfy the following:

!p.success()
p.dataStr("error") will contain the error message from the response.
p.dataStr("errorCode") will contain the matrix error code, if available, or the HTTP status code otherwise.

What information is resolved if the API request has succeeded is defined by individual functions.

Member Typedef Documentation

◆ ActionT

using Kazv::Client::ActionT = ClientAction

◆ ContextT

using Kazv::Client::ContextT = Context<ActionT>

◆ ContextWithDepsT

using Kazv::Client::ContextWithDepsT = Context<ActionT, DepsT>

◆ DepsT

using Kazv::Client::DepsT = lager::deps<JobInterface &, EventInterface &, SdkModelCursorKey, RandomInterface & >

◆ PromiseT

using Kazv::Client::PromiseT = SingleTypePromise<DefaultRetType>

Constructor & Destructor Documentation

◆ Client() [1/4]

Kazv::Client::Client	(	lager::reader< SdkModel >	sdk,
		ContextT	ctx,
		std::nullopt_t
	)

Constructor.

Construct the client. Without Deps support.

Warning: You should not use this directly. Use Sdk::client() instead.

◆ Client() [2/4]

Kazv::Client::Client	(	lager::reader< SdkModel >	sdk,
		ContextWithDepsT	ctx
	)

Constructor.

Construct the client, with Deps support.

This enables startSyncing() to work properly.

Warning: You should not use this directly. Use Sdk::client() instead.

◆ Client() [3/4]

Kazv::Client::Client	(	InEventLoopTag	,
		ContextWithDepsT	ctx
	)

Constructor.

Construct the client, with Deps support.

The constructed Client belongs to the thread of event loop.

Warning: You should not use this directly. Use Sdk::client() instead.

◆ Client() [4/4]

Kazv::Client::Client	(	InEventLoopTag	,
		ContextT	ctx,
		DepsT	deps
	)

Constructor.

Construct the client, with Deps support.

The constructed Client belongs to the thread of event loop.

Warning: You should not use this directly. Use Sdk::client() instead.

Member Function Documentation

◆ accountData()

auto Kazv::Client::accountData ( ) const -> lager::reader<immer::map<std::string, Event>>

Get the account data that is not associated with any room.

Returns: A lager::reader of a map from the type to the account data event.

◆ autoDiscover()

auto Kazv::Client::autoDiscover ( std::string userId ) const

Automatically discover the homeserver for userId.

If the operation succeeds, r.dataStr("homeserverUrl") will contain the url suitable to pass to tokenLogin() and passwordLogin().

If there is no well-known file (i.e. server responds with 404), r.dataStr("homeserverUrl") will contain the domain part of the user id (https://example.org for @foo:example.org).

Parameters

userId The full user id. E.g. @foo:example.org.

Returns: A Promise that resolves when the auto-discovery finishes.

◆ createRoom()

auto Kazv::Client::createRoom	(	RoomVisibility	v,
		std::optional< std::string >	name = `{}`,
		std::optional< std::string >	alias = `{}`,
		immer::array< std::string >	invite = `{}`,
		std::optional< bool >	isDirect = `{}`,
		bool	allowFederate = `true`,
		std::optional< std::string >	topic = `{}`,
		JsonWrap	powerLevelContentOverride = `json::object()`,
		std::optional< CreateRoomPreset >	preset = `std::nullopt`,
		immer::array< Event >	initialState = `immer::array<Event>()`
	)		const

Create a room.

Parameters

v	The visibility of the room.
name	The name of the room.
alias	The alias of the room.
invite	User ids to invite to this room.
isDirect	Whether this room is a direct chat.
allowFederate	Whether to allow users from other homeservers to join this room.
topic	The topic of the room.
powerLevelContentOverride	The content of the m.room.power_levels state event to override the default.
preset	The preset to create the room with.

Returns: A Promise that resolves when the room is created, or when there is an error.

◆ devicesOfUser()

auto Kazv::Client::devicesOfUser ( std::string userId ) const -> lager::reader<immer::flex_vector<DeviceKeyInfo>>

Get the info of all devices of user userId that supports encryption.

Parameters

userId The id of the user to get the devices of.

Returns: a lager::reader of a RangeT of DeviceKeyInfo representing the devices of that user.

◆ directRoomMap()

auto Kazv::Client::directRoomMap ( ) const -> lager::reader<immer::map<std::string, std::string>>

Get the map from direct messaging room ids to user ids.

Returns: a lager::reader of such mapping.

◆ downloadContent()

auto Kazv::Client::downloadContent	(	std::string	mxcUri,
		std::optional< FileDesc >	downloadTo = `std::nullopt`
	)		const

Download content from the content repository.

After the returned Promise resolves successfully, if downloadTo is provided, the content will be available in that file; if it is not provided, r.dataStr("content") will contain the content of the downloaded file.

Parameters

mxcUri	The MXC URI of the content.
downloadTo	The file to write the content to. Must not be an in-memory file.

Returns: A Promise that is resolved after the content is downloaded, or when there is an error.

◆ downloadThumbnail()

auto Kazv::Client::downloadThumbnail	(	std::string	mxcUri,
		int	width,
		int	height,
		std::optional< ThumbnailResizingMethod >	method = `std::nullopt`,
		std::optional< FileDesc >	downloadTo = `std::nullopt`
	)		const

Download a thumbnail from the content repository.

After the returned Promise resolves successfully, if downloadTo is provided, the content will be available in that file; if it is not provided, r.dataStr("content") will contain the content of the downloaded file.

Parameters

mxcUri	The MXC URI of the content.
width,height	The dimension wanted for the thumbnail
method	The method to generate the thumbnail. Either `Crop` or `Scale`.
downloadTo	The file to write the content to. Must not be an in-memory file.

Returns: A Promise that is resolved after the thumbnail is downloaded, or when there is an error.

◆ getProfile()

auto Kazv::Client::getProfile ( std::string userId ) const

Fetch the profile of a user.

Parameters

userId The id of the user to fetch.

Returns: A Promise that resolves when the fetch is completed. If successful, r.dataStr("avatarUrl") will contain the avatar url of that user, and r.dataStr("displayName") will contain the display name of that user.

◆ joinRoom()

auto Kazv::Client::joinRoom	(	std::string	roomId,
		immer::array< std::string >	serverName
	)		const

Join a room by its id or alias.

Parameters

roomId	The id or alias of the room to join.
serverName	A list of servers to use when joining the room. This corresponds to the `via` parameter in a matrix.to url.

Returns: A Promise that resolves when the room is joined, or when there is an error.

◆ joinRoomById()

auto Kazv::Client::joinRoomById ( std::string roomId ) const

Join a room by its id.

Parameters

roomId The id of the room to join.

Returns: A Promise that resolves when the room is joined, or when there is an error.

◆ logout()

auto Kazv::Client::logout ( ) const

Stop syncing and then logout current session.

Meanwhile, clear the current token and set loggedIn to false.

Returns: A promise that resolves when the syncing is stopped.

◆ mxcUriToHttp()

std::string Kazv::Client::mxcUriToHttp ( std::string mxcUri ) const

inline

Convert a MXC URI to an HTTP(s) URI.

The converted URI will be using the homeserver of this Client.

Parameters

mxcUri The MXC URI to convert.

Returns: The HTTP(s) URI that has the content indicated by mxcUri.

◆ notificationHandler()

NotificationHandler Kazv::Client::notificationHandler ( ) const

Get a notification handler that works on this Client.

Returns: A notification handler that works on this Client.

◆ passwordLogin()

auto Kazv::Client::passwordLogin	(	std::string	homeserver,
		std::string	username,
		std::string	password,
		std::string	deviceName
	)		const

Login using the password.

This will create a new session on the homeserver.

If the returned Promise resolves successfully, this will call startSyncing().

Parameters

homeserver	The base url of the homeserver. E.g. `https://tusooa.xyz`.
username	The username. This can be the full user id or just the local part. E.g. `tusooa`, `@tusooa:tusooa.xyz`.
password	The password.
deviceName	Optionally, a custom device name. If empty, `libkazv` will be used.

Returns: A Promise that resolves when logging in successfully, or when there is an error.

◆ room()

Room Kazv::Client::room ( std::string id ) const

Get the room with id .

This is equivalent to roomByCursor(lager::make_constant(id)).

Parameters

id	The room id.

Returns: A Room representing the room with id.

◆ roomByCursor()

Room Kazv::Client::roomByCursor ( lager::reader< std::string > id ) const

Get the room with id.

The Room returned will change as the content in id changes.

For example, you can have the Room that is always the first alphabetically in all rooms by:

auto someProcessing =
    zug::map([=](auto ids) {
        std::sort(ids.begin(), ids.end(), [=](auto id1, auto id2) {
            using namespace Kazv::CursorOp;
            return (+client.room(id1).name()) < (+client.room(id2).name());
        });
        return ids;
    });
auto room =
    client.roomByCursor(
        client.roomIds().xform(someProcessing)[0]);

Parameters

id	A lager::reader<std::string> containing the room id.

Returns: A Room representing the room with id.

◆ roomIds()

auto Kazv::Client::roomIds ( ) const

inline

◆ roomIdsByTagId()

auto Kazv::Client::roomIdsByTagId ( ) const -> lager::reader<immer::map<std::string, immer::map<std::string, double>>>

Get the room ids under all tags.

Returns: A lager::reader containing the map from tag id to a map from room id to order. Rooms without a tag will be under the tag id of the empty string.

◆ roomIdsUnderTag()

auto Kazv::Client::roomIdsUnderTag ( std::string tagId ) const -> lager::reader<immer::map<std::string, double>>

◆ rooms()

auto Kazv::Client::rooms ( ) const

inline

◆ serializeTo()

template<class Archive >

void Kazv::Client::serializeTo ( Archive & ar ) const

inline

Serialize the model to a Boost.Serialization archive.

Parameters

ar	A Boost.Serialization output archive.

This function can be used to save the model. For loading, you should use the makeSdk function. For example:

 {c++}
client.serializeTo(outputAr);
 
SdkModel m;
inputAr >> m;
auto newSdk = makeSdk(m, ...);

◆ setAccountData()

auto Kazv::Client::setAccountData ( Event accountDataEvent ) const

Set the account data that is not associated with any room.

Returns: A Promise that resolves when the account data has been set, or when there is an error.

◆ setAvatarUrl()

auto Kazv::Client::setAvatarUrl ( std::optional< std::string > avatarUrl ) const

Change the avatar url of the current user.

Parameters

avatarUrl The url of the new avatar. Should be an MXC URI. If it is std::nullopt, remove the user avatar.

Returns: A Promise that resolves when the request is completed.

◆ setDeviceTrustLevel()

auto Kazv::Client::setDeviceTrustLevel	(	std::string	userId,
		std::string	deviceId,
		DeviceTrustLevel	trustLevel
	)		const

Set the trust level of a device.

Parameters

userId	The id of the user to whom the device belongs.
deviceId	The id of the device.

Returns: a Promise that resolves when the setting is changed.

◆ setDisplayName()

auto Kazv::Client::setDisplayName ( std::optional< std::string > displayName ) const

Change the display name of the current user.

Parameters

displayName The new display name. If it is std::nullopt, remove the user avatar.

Returns: A Promise that resolves when the request is completed.

◆ setTrustLevelNeededToSendKeys()

auto Kazv::Client::setTrustLevelNeededToSendKeys ( DeviceTrustLevel trustLevel ) const

Set the trust level needed to send keys to a device.

Parameters

trustLevel The trust level threshold.

Returns: a Promise that resolves when the setting is changed.

◆ shouldSync()

auto Kazv::Client::shouldSync ( ) const -> lager::reader<bool>

Get the shouldSync field of current ClientModel.

Returns: A lager::reader of bool of the shouldSync field of the ClientModel

◆ startSyncing()

auto Kazv::Client::startSyncing ( ) const

Start syncing if the Client is not syncing.

Syncing will continue indefinitely, if the preparation of the sync (posting filters and uploading identity keys, if needed) is successful, or until stopSyncing() is called.

Returns: A Promise that resolves when the Client is syncing (more exactly, when syncing() contains true), or when there is an error in the preparation of the sync.

◆ stopSyncing()

auto Kazv::Client::stopSyncing ( ) const

Stop the indefinite syncing.

After this, no more syncing actions will be dispatched.

Returns: A Promise that resolves when syncing is stopped.

◆ syncing()

auto Kazv::Client::syncing ( ) const

inline

◆ toEventLoop()

Client Kazv::Client::toEventLoop ( ) const

Create a Client that is not constructed from a cursor.

The returned Client belongs to the thread of event loop.

This function is thread-safe if every thread calls it using different objects.

Returns: A Client not constructed from a cursor.

◆ tokenLogin()

auto Kazv::Client::tokenLogin	(	std::string	homeserver,
		std::string	username,
		std::string	token,
		std::string	deviceId
	)		const

Login using token and deviceId.

This will not make a request. Library users should make sure the information is correct and the token and the device id are valid.

If the returned Promise resolves successfully, this will call startSyncing().

Parameters

homeserver	The base url of the homeserver. E.g. `https://tusooa.xyz`.
username	The full user id. E.g. `@tusooa:tusooa.xyz`.
token	The access token.
deviceId	The device id that is paired with `token`.

Returns: A Promise that resolves when the account information is filled in.

◆ trustLevelNeededToSendKeys()

auto Kazv::Client::trustLevelNeededToSendKeys ( ) const -> lager::reader<DeviceTrustLevel>

Get the trust level needed to send keys to a device.

Returns: a lager::reader of the trust level threshold.

◆ uploadContent() [1/2]

auto Kazv::Client::uploadContent ( FileDesc file ) const

Upload content to the content repository.

Parameters

file	The file to upload.

Returns: A Promise that resolves when the upload is successful, or when there is an error. If it successfully resolves to r, r.dataStr("mxcUri") will be the MXC URI of the uploaded content.

◆ uploadContent() [2/2]

auto Kazv::Client::uploadContent	(	immer::box< Bytes >	content,
		std::string	uploadId,
		std::optional< std::string >	filename = `std::nullopt`,
		std::optional< std::string >	contentType = `std::nullopt`
	)		const

Upload content to the content repository.

Parameters

content	The content to upload.
uploadId
filename	The name of the file.
contentType	The content type of the file.

Returns: A Promise that resolves when the upload is successful, or when there is an error. If it successfully resolves to r, r.dataStr("mxcUri") will be the MXC URI of the uploaded content.

The documentation for this class was generated from the following files:

src/client/client.hpp
src/client/client.cpp

Classes

Public Types

Public Member Functions

Detailed Description

Error handling

Member Typedef Documentation

◆ ActionT

◆ ContextT

◆ ContextWithDepsT

◆ DepsT

◆ PromiseT

Constructor & Destructor Documentation

◆ Client() [1/4]

◆ Client() [2/4]

◆ Client() [3/4]

◆ Client() [4/4]

Member Function Documentation

◆ accountData()

◆ autoDiscover()

◆ createRoom()

◆ devicesOfUser()

◆ directRoomMap()

◆ downloadContent()

◆ downloadThumbnail()

◆ getProfile()

◆ joinRoom()

◆ joinRoomById()

◆ logout()

◆ mxcUriToHttp()

◆ notificationHandler()

◆ passwordLogin()

◆ room()

◆ roomByCursor()

◆ roomIds()

◆ roomIdsByTagId()

◆ roomIdsUnderTag()

◆ rooms()

◆ serializeTo()

◆ setAccountData()

◆ setAvatarUrl()

◆ setDeviceTrustLevel()

◆ setDisplayName()

◆ setTrustLevelNeededToSendKeys()

◆ shouldSync()

◆ startSyncing()

◆ stopSyncing()

◆ syncing()

◆ toEventLoop()

◆ tokenLogin()

◆ trustLevelNeededToSendKeys()

◆ uploadContent() [1/2]

◆ uploadContent() [2/2]