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 | |
12 | namespace Quotient { |
13 | |
14 | /*! \brief Upload some content to the content repository. |
15 | * |
16 | */ |
17 | class QUOTIENT_API UploadContentJob : public BaseJob { |
18 | public: |
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 | */ |
46 | class QUOTIENT_API UploadContentToMXCJob : public BaseJob { |
47 | public: |
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 | */ |
96 | class QUOTIENT_API CreateContentJob : public BaseJob { |
97 | public: |
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 | */ |
125 | class QUOTIENT_API GetContentJob : public BaseJob { |
126 | public: |
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 | */ |
191 | class QUOTIENT_API GetContentOverrideNameJob : public BaseJob { |
192 | public: |
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 | */ |
265 | class QUOTIENT_API GetContentThumbnailJob : public BaseJob { |
266 | public: |
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 | */ |
347 | class QUOTIENT_API GetUrlPreviewJob : public BaseJob { |
348 | public: |
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 | */ |
395 | class QUOTIENT_API GetConfigJob : public BaseJob { |
396 | public: |
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 | |