1/******************************************************************************
2 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
3 */
4
5#pragma once
6
7#include <Quotient/jobs/basejob.h>
8
9#include <QtCore/QIODevice>
10#include <QtNetwork/QNetworkReply>
11
12namespace Quotient {
13
14/*! \brief Upload some content to the content repository.
15 *
16 */
17class QUOTIENT_API UploadContentJob : public BaseJob {
18public:
19 /*! \brief Upload some content to the content repository.
20 *
21 * \param content
22 * The content to be uploaded.
23 *
24 * \param filename
25 * The name of the file being uploaded
26 *
27 * \param contentType
28 * The content type of the file being uploaded
29 */
30 explicit UploadContentJob(QIODevice* content, const QString& filename = {},
31 const QString& contentType = {});
32
33 // Result properties
34
35 /// The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to the
36 /// uploaded content.
37 QUrl contentUri() const { return loadFromJson<QUrl>(keyName: "content_uri"_ls); }
38};
39
40/*! \brief Upload content to an `mxc://` URI that was created earlier.
41 *
42 * This endpoint permits uploading content to an `mxc://` URI that was created
43 * earlier via [POST
44 * /_matrix/media/v1/create](/client-server-api/#post_matrixmediav1create).
45 */
46class QUOTIENT_API UploadContentToMXCJob : public BaseJob {
47public:
48 /*! \brief Upload content to an `mxc://` URI that was created earlier.
49 *
50 * \param serverName
51 * The server name from the `mxc://` URI returned by `POST
52 * /_matrix/media/v1/create` (the authoritory component).
53 *
54 * \param mediaId
55 * The media ID from the `mxc://` URI returned by `POST
56 * /_matrix/media/v1/create` (the path component).
57 *
58 * \param content
59 * The content to be uploaded.
60 *
61 * \param filename
62 * The name of the file being uploaded
63 *
64 * \param contentType
65 * The content type of the file being uploaded
66 */
67 explicit UploadContentToMXCJob(const QString& serverName,
68 const QString& mediaId, QIODevice* content,
69 const QString& filename = {},
70 const QString& contentType = {});
71};
72
73/*! \brief Create a new `mxc://` URI without uploading the content.
74 *
75 * Creates a new `mxc://` URI, independently of the content being uploaded. The
76 * content must be provided later via [`PUT
77 * /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid).
78 *
79 * The server may optionally enforce a maximum age for unused IDs,
80 * and delete media IDs when the client doesn't start the upload in time,
81 * or when the upload was interrupted and not resumed in time. The server
82 * should include the maximum POSIX millisecond timestamp to complete the
83 * upload in the `unused_expires_at` field in the response JSON. The
84 * recommended default expiration is 24 hours which should be enough time
85 * to accommodate users on poor connection who find a better connection to
86 * complete the upload.
87 *
88 * As well as limiting the rate of requests to create `mxc://` URIs, the server
89 * should limit the number of concurrent *pending media uploads* a given
90 * user can have. A pending media upload is a created `mxc://` URI where (a)
91 * the media has not yet been uploaded, and (b) has not yet expired (the
92 * `unused_expires_at` timestamp has not yet passed). In both cases, the
93 * server should respond with an HTTP 429 error with an errcode of
94 * `M_LIMIT_EXCEEDED`.
95 */
96class QUOTIENT_API CreateContentJob : public BaseJob {
97public:
98 /// Create a new `mxc://` URI without uploading the content.
99 explicit CreateContentJob();
100
101 /*! \brief Construct a URL without creating a full-fledged job object
102 *
103 * This function can be used when a URL for CreateContentJob
104 * is necessary but the job itself isn't.
105 */
106 static QUrl makeRequestUrl(QUrl baseUrl);
107
108 // Result properties
109
110 /// The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at
111 /// which the content will be available, once it is uploaded.
112 QUrl contentUri() const { return loadFromJson<QUrl>(keyName: "content_uri"_ls); }
113
114 /// The timestamp (in milliseconds since the unix epoch) when the
115 /// generated media id will expire, if media is not uploaded.
116 Omittable<qint64> unusedExpiresAt() const
117 {
118 return loadFromJson<Omittable<qint64>>(keyName: "unused_expires_at"_ls);
119 }
120};
121
122/*! \brief Download content from the content repository.
123 *
124 */
125class QUOTIENT_API GetContentJob : public BaseJob {
126public:
127 /*! \brief Download content from the content repository.
128 *
129 * \param serverName
130 * The server name from the `mxc://` URI (the authoritory component)
131 *
132 * \param mediaId
133 * The media ID from the `mxc://` URI (the path component)
134 *
135 * \param allowRemote
136 * Indicates to the server that it should not attempt to fetch the media
137 * if it is deemed remote. This is to prevent routing loops where the server
138 * contacts itself. Defaults to true if not provided.
139 *
140 * \param timeoutMs
141 * The maximum number of milliseconds that the client is willing to
142 * wait to start receiving data, in the case that the content has not
143 * yet been uploaded. The default value is 20000 (20 seconds). The
144 * content repository can and should impose a maximum value for this
145 * parameter. The content repository may also choose to respond before
146 * the timeout.
147 *
148 * \param allowRedirect
149 * Indicates to the server that it may return a 307 or 308 redirect
150 * response that points at the relevant media content. When not explicitly
151 * set to true the server must return the media content itself.
152 */
153 explicit GetContentJob(const QString& serverName, const QString& mediaId,
154 bool allowRemote = true, qint64 timeoutMs = 20000,
155 bool allowRedirect = false);
156
157 /*! \brief Construct a URL without creating a full-fledged job object
158 *
159 * This function can be used when a URL for GetContentJob
160 * is necessary but the job itself isn't.
161 */
162 static QUrl makeRequestUrl(QUrl baseUrl, const QString& serverName,
163 const QString& mediaId, bool allowRemote = true,
164 qint64 timeoutMs = 20000,
165 bool allowRedirect = false);
166
167 // Result properties
168
169 /// The content type of the file that was previously uploaded.
170 QString contentType() const
171 {
172 return QString::fromUtf8(ba: reply()->rawHeader(headerName: "Content-Type"));
173 }
174
175 /// The name of the file that was previously uploaded, if set.
176 QString contentDisposition() const
177 {
178 return QString::fromUtf8(ba: reply()->rawHeader(headerName: "Content-Disposition"));
179 }
180
181 /// The content that was previously uploaded.
182 QIODevice* data() { return reply(); }
183};
184
185/*! \brief Download content from the content repository overriding the file name
186 *
187 * This will download content from the content repository (same as
188 * the previous endpoint) but replace the target file name with the one
189 * provided by the caller.
190 */
191class QUOTIENT_API GetContentOverrideNameJob : public BaseJob {
192public:
193 /*! \brief Download content from the content repository overriding the file
194 * name
195 *
196 * \param serverName
197 * The server name from the `mxc://` URI (the authoritory component)
198 *
199 * \param mediaId
200 * The media ID from the `mxc://` URI (the path component)
201 *
202 * \param fileName
203 * A filename to give in the `Content-Disposition` header.
204 *
205 * \param allowRemote
206 * Indicates to the server that it should not attempt to fetch the media
207 * if it is deemed remote. This is to prevent routing loops where the server
208 * contacts itself. Defaults to true if not provided.
209 *
210 * \param timeoutMs
211 * The maximum number of milliseconds that the client is willing to
212 * wait to start receiving data, in the case that the content has not
213 * yet been uploaded. The default value is 20000 (20 seconds). The
214 * content repository can and should impose a maximum value for this
215 * parameter. The content repository may also choose to respond before
216 * the timeout.
217 *
218 * \param allowRedirect
219 * Indicates to the server that it may return a 307 or 308 redirect
220 * response that points at the relevant media content. When not explicitly
221 * set to true the server must return the media content itself.
222 */
223 explicit GetContentOverrideNameJob(const QString& serverName,
224 const QString& mediaId,
225 const QString& fileName,
226 bool allowRemote = true,
227 qint64 timeoutMs = 20000,
228 bool allowRedirect = false);
229
230 /*! \brief Construct a URL without creating a full-fledged job object
231 *
232 * This function can be used when a URL for GetContentOverrideNameJob
233 * is necessary but the job itself isn't.
234 */
235 static QUrl makeRequestUrl(QUrl baseUrl, const QString& serverName,
236 const QString& mediaId, const QString& fileName,
237 bool allowRemote = true, qint64 timeoutMs = 20000,
238 bool allowRedirect = false);
239
240 // Result properties
241
242 /// The content type of the file that was previously uploaded.
243 QString contentType() const
244 {
245 return QString::fromUtf8(ba: reply()->rawHeader(headerName: "Content-Type"));
246 }
247
248 /// The `fileName` requested or the name of the file that was previously
249 /// uploaded, if set.
250 QString contentDisposition() const
251 {
252 return QString::fromUtf8(ba: reply()->rawHeader(headerName: "Content-Disposition"));
253 }
254
255 /// The content that was previously uploaded.
256 QIODevice* data() { return reply(); }
257};
258
259/*! \brief Download a thumbnail of content from the content repository
260 *
261 * Download a thumbnail of content from the content repository.
262 * See the [Thumbnails](/client-server-api/#thumbnails) section for more
263 * information.
264 */
265class QUOTIENT_API GetContentThumbnailJob : public BaseJob {
266public:
267 /*! \brief Download a thumbnail of content from the content repository
268 *
269 * \param serverName
270 * The server name from the `mxc://` URI (the authoritory component)
271 *
272 * \param mediaId
273 * The media ID from the `mxc://` URI (the path component)
274 *
275 * \param width
276 * The *desired* width of the thumbnail. The actual thumbnail may be
277 * larger than the size specified.
278 *
279 * \param height
280 * The *desired* height of the thumbnail. The actual thumbnail may be
281 * larger than the size specified.
282 *
283 * \param method
284 * The desired resizing method. See the
285 * [Thumbnails](/client-server-api/#thumbnails) section for more
286 * information.
287 *
288 * \param allowRemote
289 * Indicates to the server that it should not attempt to fetch
290 * the media if it is deemed remote. This is to prevent routing loops
291 * where the server contacts itself. Defaults to true if not provided.
292 *
293 * \param timeoutMs
294 * The maximum number of milliseconds that the client is willing to
295 * wait to start receiving data, in the case that the content has not
296 * yet been uploaded. The default value is 20000 (20 seconds). The
297 * content repository can and should impose a maximum value for this
298 * parameter. The content repository may also choose to respond before
299 * the timeout.
300 *
301 * \param allowRedirect
302 * Indicates to the server that it may return a 307 or 308 redirect
303 * response that points at the relevant media content. When not explicitly
304 * set to true the server must return the media content itself.
305 */
306 explicit GetContentThumbnailJob(const QString& serverName,
307 const QString& mediaId, int width,
308 int height, const QString& method = {},
309 bool allowRemote = true,
310 qint64 timeoutMs = 20000,
311 bool allowRedirect = false);
312
313 /*! \brief Construct a URL without creating a full-fledged job object
314 *
315 * This function can be used when a URL for GetContentThumbnailJob
316 * is necessary but the job itself isn't.
317 */
318 static QUrl makeRequestUrl(QUrl baseUrl, const QString& serverName,
319 const QString& mediaId, int width, int height,
320 const QString& method = {},
321 bool allowRemote = true, qint64 timeoutMs = 20000,
322 bool allowRedirect = false);
323
324 // Result properties
325
326 /// The content type of the thumbnail.
327 QString contentType() const
328 {
329 return QString::fromUtf8(ba: reply()->rawHeader(headerName: "Content-Type"));
330 }
331
332 /// A thumbnail of the requested content.
333 QIODevice* data() { return reply(); }
334};
335
336/*! \brief Get information about a URL for a client
337 *
338 * Get information about a URL for the client. Typically this is called when a
339 * client sees a URL in a message and wants to render a preview for the user.
340 *
341 * **Note:**
342 * Clients should consider avoiding this endpoint for URLs posted in encrypted
343 * rooms. Encrypted rooms often contain more sensitive information the users
344 * do not want to share with the homeserver, and this can mean that the URLs
345 * being shared should also not be shared with the homeserver.
346 */
347class QUOTIENT_API GetUrlPreviewJob : public BaseJob {
348public:
349 /*! \brief Get information about a URL for a client
350 *
351 * \param url
352 * The URL to get a preview of.
353 *
354 * \param ts
355 * The preferred point in time to return a preview for. The server may
356 * return a newer version if it does not have the requested version
357 * available.
358 */
359 explicit GetUrlPreviewJob(const QUrl& url, Omittable<qint64> ts = none);
360
361 /*! \brief Construct a URL without creating a full-fledged job object
362 *
363 * This function can be used when a URL for GetUrlPreviewJob
364 * is necessary but the job itself isn't.
365 */
366 static QUrl makeRequestUrl(QUrl baseUrl, const QUrl& url,
367 Omittable<qint64> ts = none);
368
369 // Result properties
370
371 /// The byte-size of the image. Omitted if there is no image attached.
372 Omittable<qint64> matrixImageSize() const
373 {
374 return loadFromJson<Omittable<qint64>>(keyName: "matrix:image:size"_ls);
375 }
376
377 /// An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to the
378 /// image. Omitted if there is no image.
379 QUrl ogImage() const { return loadFromJson<QUrl>(keyName: "og:image"_ls); }
380};
381
382/*! \brief Get the configuration for the content repository.
383 *
384 * This endpoint allows clients to retrieve the configuration of the content
385 * repository, such as upload limitations.
386 * Clients SHOULD use this as a guide when using content repository endpoints.
387 * All values are intentionally left optional. Clients SHOULD follow
388 * the advice given in the field description when the field is not available.
389 *
390 * **NOTE:** Both clients and server administrators should be aware that proxies
391 * between the client and the server may affect the apparent behaviour of
392 * content repository APIs, for example, proxies may enforce a lower upload size
393 * limit than is advertised by the server on this endpoint.
394 */
395class QUOTIENT_API GetConfigJob : public BaseJob {
396public:
397 /// Get the configuration for the content repository.
398 explicit GetConfigJob();
399
400 /*! \brief Construct a URL without creating a full-fledged job object
401 *
402 * This function can be used when a URL for GetConfigJob
403 * is necessary but the job itself isn't.
404 */
405 static QUrl makeRequestUrl(QUrl baseUrl);
406
407 // Result properties
408
409 /// The maximum size an upload can be in bytes.
410 /// Clients SHOULD use this as a guide when uploading content.
411 /// If not listed or null, the size limit should be treated as unknown.
412 Omittable<qint64> uploadSize() const
413 {
414 return loadFromJson<Omittable<qint64>>(keyName: "m.upload.size"_ls);
415 }
416};
417
418} // namespace Quotient
419