1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
/******************************************************************************
* THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
*/
#pragma once
#include "jobs/basejob.h"
#include "converters.h"
#include "csapi/definitions/device_keys.h"
#include <QtCore/QHash>
#include <QtCore/QJsonObject>
#include <QtCore/QVariant>
namespace QMatrixClient {
// Operations
/// Upload end-to-end encryption keys.
///
/// Publishes end-to-end encryption keys for the device.
class UploadKeysJob : public BaseJob
{
public:
/*! Upload end-to-end encryption keys.
* \param deviceKeys
* Identity keys for the device. May be absent if no new
* identity keys are required.
* \param oneTimeKeys
* One-time public keys for "pre-key" messages. The names of
* the properties should be in the format
* ``<algorithm>:<key_id>``. The format of the key is determined
* by the key algorithm.
*
* May be absent if no new one-time keys are required.
*/
explicit UploadKeysJob(
const Omittable<DeviceKeys>& deviceKeys = none,
const QHash<QString, QVariant>& oneTimeKeys = {});
~UploadKeysJob() override;
// Result properties
/// For each key algorithm, the number of unclaimed one-time keys
/// of that type currently held on the server for this device.
const QHash<QString, int>& oneTimeKeyCounts() const;
protected:
Status parseJson(const QJsonDocument& data) override;
private:
class Private;
QScopedPointer<Private> d;
};
/// Download device identity keys.
///
/// Returns the current devices and identity keys for the given users.
class QueryKeysJob : public BaseJob
{
public:
// Inner data structures
/// Additional data added to the device key information
/// by intermediate servers, and not covered by the
/// signatures.
struct UnsignedDeviceInfo {
/// The display name which the user set on the device.
QString deviceDisplayName;
};
/// Returns the current devices and identity keys for the given users.
struct DeviceInformation : DeviceKeys {
/// Additional data added to the device key information
/// by intermediate servers, and not covered by the
/// signatures.
Omittable<UnsignedDeviceInfo> unsignedData;
};
// Construction/destruction
/*! Download device identity keys.
* \param deviceKeys
* The keys to be downloaded. A map from user ID, to a list of
* device IDs, or to an empty list to indicate all devices for the
* corresponding user.
* \param timeout
* The time (in milliseconds) to wait when downloading keys from
* remote servers. 10 seconds is the recommended default.
* \param token
* If the client is fetching keys as a result of a device update
* received in a sync request, this should be the 'since' token of that
* sync request, or any later sync token. This allows the server to
* ensure its response contains the keys advertised by the notification
* in that sync.
*/
explicit QueryKeysJob(const QHash<QString, QStringList>& deviceKeys,
Omittable<int> timeout = none,
const QString& token = {});
~QueryKeysJob() override;
// Result properties
/// If any remote homeservers could not be reached, they are
/// recorded here. The names of the properties are the names of
/// the unreachable servers.
///
/// If the homeserver could be reached, but the user or device
/// was unknown, no failure is recorded. Instead, the corresponding
/// user or device is missing from the ``device_keys`` result.
const QHash<QString, QJsonObject>& failures() const;
/// Information on the queried devices. A map from user ID, to a
/// map from device ID to device information. For each device,
/// the information returned will be the same as uploaded via
/// ``/keys/upload``, with the addition of an ``unsigned``
/// property.
const QHash<QString, QHash<QString, DeviceInformation>>&
deviceKeys() const;
protected:
Status parseJson(const QJsonDocument& data) override;
private:
class Private;
QScopedPointer<Private> d;
};
/// Claim one-time encryption keys.
///
/// Claims one-time keys for use in pre-key messages.
class ClaimKeysJob : public BaseJob
{
public:
/*! Claim one-time encryption keys.
* \param oneTimeKeys
* The keys to be claimed. A map from user ID, to a map from
* device ID to algorithm name.
* \param timeout
* The time (in milliseconds) to wait when downloading keys from
* remote servers. 10 seconds is the recommended default.
*/
explicit ClaimKeysJob(
const QHash<QString, QHash<QString, QString>>& oneTimeKeys,
Omittable<int> timeout = none);
~ClaimKeysJob() override;
// Result properties
/// If any remote homeservers could not be reached, they are
/// recorded here. The names of the properties are the names of
/// the unreachable servers.
///
/// If the homeserver could be reached, but the user or device
/// was unknown, no failure is recorded. Instead, the corresponding
/// user or device is missing from the ``one_time_keys`` result.
const QHash<QString, QJsonObject>& failures() const;
/// One-time keys for the queried devices. A map from user ID, to a
/// map from devices to a map from ``<algorithm>:<key_id>`` to the key
/// object.
const QHash<QString, QHash<QString, QVariant>>& oneTimeKeys() const;
protected:
Status parseJson(const QJsonDocument& data) override;
private:
class Private;
QScopedPointer<Private> d;
};
/// Query users with recent device key updates.
///
/// Gets a list of users who have updated their device identity keys since a
/// previous sync token.
///
/// The server should include in the results any users who:
///
/// * currently share a room with the calling user (ie, both users have
/// membership state ``join``); *and*
/// * added new device identity keys or removed an existing device with
/// identity keys, between ``from`` and ``to``.
class GetKeysChangesJob : public BaseJob
{
public:
/*! Query users with recent device key updates.
* \param from
* The desired start point of the list. Should be the ``next_batch``
* field from a response to an earlier call to |/sync|. Users who have
* not uploaded new device identity keys since this point, nor deleted
* existing devices with identity keys since then, will be excluded
* from the results.
* \param to
* The desired end point of the list. Should be the ``next_batch``
* field from a recent call to |/sync| - typically the most recent
* such call. This may be used by the server as a hint to check its
* caches are up to date.
*/
explicit GetKeysChangesJob(const QString& from, const QString& to);
/*! Construct a URL without creating a full-fledged job object
*
* This function can be used when a URL for
* GetKeysChangesJob is necessary but the job
* itself isn't.
*/
static QUrl makeRequestUrl(QUrl baseUrl, const QString& from,
const QString& to);
~GetKeysChangesJob() override;
// Result properties
/// The Matrix User IDs of all users who updated their device
/// identity keys.
const QStringList& changed() const;
/// The Matrix User IDs of all users who may have left all
/// the end-to-end encrypted rooms they previously shared
/// with the user.
const QStringList& left() const;
protected:
Status parseJson(const QJsonDocument& data) override;
private:
class Private;
QScopedPointer<Private> d;
};
} // namespace QMatrixClient
|
