libkazv
Kazv::Client Class Reference

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...
 
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) 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

◆ ContextT

◆ ContextWithDepsT

◆ DepsT

◆ PromiseT

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
userIdThe 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 
) const

Create a room.

Parameters
vThe visibility of the room.
nameThe name of the room.
aliasThe alias of the room.
inviteUser ids to invite to this room.
isDirectWhether this room is a direct chat.
allowFederateWhether to allow users from other homeservers to join this room.
topicThe topic of the room.
powerLevelContentOverrideThe content of the m.room.power_levels state event to override the default.
presetThe 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
userIdThe 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
mxcUriThe MXC URI of the content.
downloadToThe 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
mxcUriThe MXC URI of the content.
width,heightThe dimension wanted for the thumbnail
methodThe method to generate the thumbnail. Either Crop or Scale.
downloadToThe 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
userIdThe 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
roomIdThe id or alias of the room to join.
serverNameA 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
roomIdThe id of the room to join.
Returns
A Promise that resolves when the room is joined, or when there is an error.

◆ 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
mxcUriThe 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
homeserverThe base url of the homeserver. E.g. https://tusooa.xyz.
usernameThe username. This can be the full user id or just the local part. E.g. tusooa, @tusooa:tusooa.xyz.
passwordThe password.
deviceNameOptionally, 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
idThe 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
idA 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
arA 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
avatarUrlThe 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
userIdThe id of the user to whom the device belongs.
deviceIdThe 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
displayNameThe 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
trustLevelThe trust level threshold.
Returns
a Promise that resolves when the setting is changed.

◆ 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
homeserverThe base url of the homeserver. E.g. https://tusooa.xyz.
usernameThe full user id. E.g. @tusooa:tusooa.xyz.
tokenThe access token.
deviceIdThe 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
fileThe 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
contentThe content to upload.
uploadId
filenameThe name of the file.
contentTypeThe 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:
Kazv::makeSdk
auto makeSdk(SdkModel sdk, JobInterface &jobHandler, EventInterface &eventEmitter, EventLoop &&eventLoop, Xform &&xform, Enhancers &&...enhancers) -> Sdk< EventLoop, Xform, Enhancers... >
Create an sdk with the provided model.
Definition: sdk.hpp:200
Kazv::Client::room
Room room(std::string id) const
Get the room with id .
Definition: client.cpp:65