1 /* 2 SPDX-FileCopyrightText: 2012 Andrius da Costa Ribas <andriusmao@gmail.com> 3 4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 5 */ 6 7 #pragma once 8 9 #include "object.h" 10 #include "types.h" 11 #include "change.h" 12 13 #include <QString> 14 #include <QStringList> 15 #include <QUrl> 16 #include <QVariantMap> 17 #include <QImage> 18 19 #include <QDateTime> 20 21 namespace KGAPI2 22 { 23 24 namespace Drive 25 { 26 27 /** 28 * @brief File contains metadata for a file. 29 * Getters and setters' documentation is based on Google Drive's API v2 reference 30 * @see <a href="https://developers.google.com/drive/v2/reference/files">Files</a> 31 * 32 * @since 2.0 33 * @author Andrius da Costa Ribas <andriusmao@gmail.com> 34 * @author Daniel Vrátil <dvratil@redhat.com> 35 */ 36 class KGAPIDRIVE_EXPORT File: public KGAPI2::Object 37 { 38 private: 39 class Private; 40 41 public: 42 /** 43 * @brief DriveFile::Labels holds the structure used for labels property. 44 */ 45 class Labels 46 { 47 public: 48 explicit Labels(); 49 explicit Labels(const Labels &other); 50 virtual ~Labels(); 51 bool operator==(const Labels &other) const; 52 bool operator!=(const Labels &other) const { return !operator==(other); } 53 54 /** 55 * @brief Returns whether this file is starred by the user. 56 */ 57 bool starred() const; 58 59 /** 60 * @brief Sets whether this file is starred by the user. 61 * 62 * @param starred 63 */ 64 void setStarred(bool starred); 65 66 /** 67 * @brief Returns whether this file has the 'hidden' label set. 68 * @deprecated The 'hidden' label has been deprecated in the v2 api and removed in the v3 one. 69 * You can just ignore it. 70 */ 71 #ifndef KGAPIDRIVE_NO_DEPRECATED 72 KGAPIDRIVE_DEPRECATED bool hidden() const; 73 #endif 74 75 /** 76 * @brief Sets whether this file has the 'hidden' label set. 77 * @deprecated The 'hidden' label has been deprecated in the v2 api and removed in the v3 one. 78 */ 79 #ifndef KGAPIDRIVE_NO_DEPRECATED 80 KGAPIDRIVE_DEPRECATED void setHidden(bool hidden); 81 #endif 82 83 /** 84 * @brief Returns whether this file has been trashed. 85 */ 86 bool trashed() const; 87 88 /** 89 * @brief Sets whether this file has been trashed. 90 * 91 * @param trashed 92 */ 93 void setTrashed(bool trashed); 94 95 /** 96 * @brief Returns whether viewers are prevented from downloading this file. 97 */ 98 bool restricted() const; 99 100 /** 101 * @brief Sets whether viewers are prevented from downloading this file. 102 * 103 * @param restricted 104 */ 105 void setRestricted(bool restricted); 106 107 /** 108 * @brief Returns whether this file has been viewed by this user. 109 */ 110 bool viewed() const; 111 112 /** 113 * @brief Sets whether this file has been viewed by this user. 114 * 115 * @param viewed 116 */ 117 void setViewed(bool viewed); 118 119 private: 120 class Private; 121 Private *const d; 122 friend class Private; 123 friend class File::Private; 124 }; 125 126 using LabelsPtr = QSharedPointer<Labels>; 127 using LabelsList = QList<LabelsPtr>; 128 129 /** 130 * @brief DriveFile::IndexableText holds the structure used for indexableText property. 131 */ 132 class IndexableText 133 { 134 public: 135 explicit IndexableText(const IndexableText &other); 136 virtual ~IndexableText(); 137 bool operator==(const IndexableText &other) const; 138 bool operator!=(const IndexableText &other) const { return !operator==(other); } 139 140 /** 141 * @brief Returns the text to be indexed for this file. 142 */ 143 QString text() const; 144 145 /** 146 * @brief Sets the text to be indexed for this file. 147 * 148 * @param text 149 */ 150 void setText(const QString &text); 151 152 private: 153 explicit IndexableText(); 154 155 class Private; 156 Private *const d; 157 friend class Private; 158 friend class File::Private; 159 }; 160 161 using IndexableTextPtr = QSharedPointer<IndexableText>; 162 163 /** 164 * @brief DriveFile::ImageMediaMetadata holds the structure used for 165 * imageMediaMetadata property. 166 */ 167 class ImageMediaMetadata 168 { 169 public: 170 /** 171 * @brief DriveFile::ImageMediaMetadata::Location holds the structure used 172 * for imageMediaMetadata.location property. 173 */ 174 class Location 175 { 176 public: 177 explicit Location(const Location &other); 178 virtual ~Location(); 179 bool operator==(const Location &other) const; 180 bool operator!=(const Location &other) const { return !operator==(other); } 181 182 /** 183 * @brief Returns the latitude stored in the image. 184 */ 185 qreal latitude() const; 186 187 /** 188 * @brief Returns the longitude stored in the image. 189 */ 190 qreal longitude() const; 191 192 /** 193 * @brief Returns the altitude stored in the image. 194 */ 195 qreal altitude() const; 196 197 private: 198 explicit Location(); 199 200 class Private; 201 Private *const d; 202 friend class Private; 203 friend class ImageMediaMetadata; 204 }; 205 206 using LocationPtr = QSharedPointer<Location>; 207 208 explicit ImageMediaMetadata(const ImageMediaMetadata &other); 209 virtual ~ImageMediaMetadata(); 210 bool operator==(const ImageMediaMetadata &other) const; 211 bool operator!=(const ImageMediaMetadata &other) const { return !operator==(other); } 212 213 /** 214 * @brief Returns the width of the image in pixels. 215 */ 216 int width() const; 217 218 /** 219 * @brief Returns the height of the image in pixels. 220 */ 221 int height() const; 222 223 /** 224 * @brief Returns the rotation in clockwise degrees from the image's original orientation. 225 */ 226 int rotation() const; 227 228 /** 229 * @brief Returns the geographic location information stored in the image. 230 */ 231 LocationPtr location() const; 232 233 QString date() const; 234 235 QString cameraMake() const; 236 237 QString cameraModel() const; 238 239 float exposureTime() const; 240 241 float aperture() const; 242 243 bool flashUsed() const; 244 245 float focalLength() const; 246 247 int isoSpeed() const; 248 249 QString meteringMode() const; 250 251 QString sensor() const; 252 253 QString exposureMode() const; 254 255 QString colorSpace() const; 256 257 QString whiteBalance() const; 258 259 float exposureBias() const; 260 261 float maxApertureValue() const; 262 263 int subjectDistance() const; 264 265 QString lens() const; 266 267 private: 268 explicit ImageMediaMetadata(const QVariantMap &jsonMap); 269 270 class Private; 271 Private *const d; 272 friend class Private; 273 friend class File::Private; 274 }; 275 276 using ImageMediaMetadataPtr = QSharedPointer<ImageMediaMetadata>; 277 278 class Thumbnail 279 { 280 public: 281 explicit Thumbnail(const Thumbnail &other); 282 virtual ~Thumbnail(); 283 bool operator==(const Thumbnail &other) const; 284 bool operator!=(const Thumbnail &other) const { return !operator==(other); } 285 286 QImage image() const; 287 288 QString mimeType() const; 289 290 private: 291 explicit Thumbnail(const QVariantMap &jsonMap); 292 293 class Private; 294 Private * const d; 295 friend class Private; 296 friend class File::Private; 297 }; 298 299 using ThumbnailPtr = QSharedPointer<Thumbnail>; 300 301 /** 302 * @brief JSON serialization options. 303 * @since 5.3.1 304 */ 305 enum SerializationOption { 306 NoOptions = 0, ///< No option set. 307 ExcludeCreationDate = 1 ///< Exclude 'createdDate' entry. This is necessary when renaming URLs. 308 }; 309 Q_DECLARE_FLAGS(SerializationOptions, SerializationOption) 310 311 explicit File(); 312 explicit File(const File &other); 313 ~File() override; 314 bool operator==(const File &other) const; 315 bool operator!=(const File &other) const { return !operator==(other); } 316 317 /** 318 * @brief Returns mimetype of folders 319 */ 320 static QString folderMimeType(); 321 322 /** 323 * @brief Returns the id of the file. 324 */ 325 QString id() const; 326 327 /** 328 * @brief Returns a link back to this file. 329 */ 330 QUrl selfLink() const; 331 332 /** 333 * @brief Returns the title of this file. 334 * 335 * Used to identify file or folder name. 336 */ 337 QString title() const; 338 339 /** 340 * @brief Sets the title of this file. 341 * 342 * Used to identify file or folder name. 343 * 344 * @param title 345 */ 346 void setTitle(const QString &title); 347 348 /** 349 * @brief Returns the MIME type of the file. 350 */ 351 QString mimeType() const; 352 353 /** 354 * @brief Sets the MIME type of the file. 355 * 356 * @param mimeType 357 */ 358 void setMimeType(const QString &mimeType); 359 360 /** 361 * @brief Returns a short description of the file. 362 */ 363 QString description() const; 364 365 /** 366 * @brief Sets a short description of the file. 367 * 368 * @param description 369 */ 370 void setDescription(const QString &description); 371 372 /** 373 * @brief Returns a group of labels for the file. 374 */ 375 File::LabelsPtr labels() const; 376 377 /** 378 * @brief Sets a group of labels for the file. 379 * 380 * @param labels 381 */ 382 void setLabels(const LabelsPtr &labels); 383 384 /** 385 * @brief Returns the create time for this file. 386 */ 387 QDateTime createdDate() const; 388 389 /** 390 * @brief Returns the last time this file was modified by anyone. 391 * 392 * This is only mutable on update when the setModifiedDate parameter is set. 393 */ 394 QDateTime modifiedDate() const; 395 396 /** 397 * @brief Sets the last time this file was modified by anyone. 398 * 399 * This is only mutable on update when the setModifiedDate parameter is set. 400 * 401 * @param modifiedDate 402 */ 403 void setModifiedDate(const QDateTime &modifiedDate); 404 405 /** 406 * @brief Returns the last time this file was modified by the currently 407 * authenticated user. 408 */ 409 QDateTime modifiedByMeDate() const; 410 411 /** 412 * @brief Returns a short lived download URL for the file. 413 * 414 * This is only populated for files with content stored in Drive. 415 */ 416 QUrl downloadUrl() const; 417 418 /** 419 * @brief Returns the indexable text attributes for the file. 420 * 421 * This property can only be written, and is not returned by files.get 422 */ 423 File::IndexableTextPtr& indexableText(); 424 425 /** 426 * @brief Returns the permissions for the authenticated user on this file. 427 */ 428 PermissionPtr userPermission() const; 429 430 /** 431 * @brief Returns the file extension used when downloading this file. 432 * 433 * This field is read only. To set the extension, include it on title when creating the file. 434 * This is populated only for files with content stored in Drive. 435 */ 436 QString fileExtension() const; 437 438 /** 439 * @brief Returns an MD5 checksum for the content of this file. 440 * 441 * This is populated only for files with content stored in Drive. 442 */ 443 QString md5Checksum() const; 444 445 /** 446 * @brief Returns the size of the file in bytes. 447 * 448 * This is populated only for files with content stored in Drive. 449 */ 450 qlonglong fileSize() const; 451 452 /** 453 * @brief Returns a link for opening the file in using a relevant 454 * Google editor or viewer. 455 */ 456 QUrl alternateLink() const; 457 458 /** 459 * @brief Returns a link for embedding the file. 460 */ 461 QUrl embedLink() const; 462 463 /** 464 * @brief Returns the version of the file; 465 */ 466 qlonglong version() const; 467 468 /** 469 * @brief Returns the time at which this file was shared with the user. 470 */ 471 QDateTime sharedWithMeDate() const; 472 473 /** 474 * @brief Returns the collection of parent folders which contain this file. 475 * 476 * Setting this field will put the file in all of the provided folders. 477 * On insert, if no folders are provided, the file will be placed in the 478 * default root folder. 479 */ 480 ParentReferencesList parents() const; 481 482 /** 483 * @brief Sets the collection of parent folders which contain this file. 484 * 485 * Setting this field will put the file in all of the provided folders. 486 * On insert, if no folders are provided, the file will be placed in the 487 * default root folder. 488 * 489 * @param parents 490 */ 491 void setParents(const ParentReferencesList &parents); 492 493 /** 494 * @brief Returns the links for exporting Google Docs to specific formats. 495 * 496 * This is a map from the export format to URL. 497 */ 498 QMap < QString /* format */, QUrl /* url */ > exportLinks() const; 499 500 /** 501 * @brief Returns the original filename if the file was uploaded manually, 502 * or the original title if the file was inserted through the API. 503 * 504 * Note that renames of the title will not change the original filename. 505 * This will only be populated on files with content stored in Drive. 506 */ 507 QString originalFileName() const; 508 509 /** 510 * @brief Returns the number of quota bytes used by this file. 511 */ 512 qlonglong quotaBytesUsed() const; 513 514 /** 515 * @brief Return the name(s) of the owner(s) of this file. 516 */ 517 QStringList ownerNames() const; 518 519 /** 520 * @brief Returns the name of the last user to modify this file. 521 * 522 * This will only be populated if a user has edited this file. 523 */ 524 QString lastModifyingUserName() const; 525 526 /** 527 * @brief Returns whether the file can be edited by the current user. 528 */ 529 bool editable() const; 530 531 /** 532 * @brief Returns whether writers can share the document with other users. 533 */ 534 bool writersCanShare() const; 535 536 /** 537 * @brief Returns a link to the file's thumbnail. 538 */ 539 QUrl thumbnailLink() const; 540 541 /** 542 * @brief Returns the last time this file was viewed by the user. 543 */ 544 QDateTime lastViewedByMeDate() const; 545 546 /** 547 * @brief Sets the last time this file was viewed by the user. 548 * 549 * @param lastViewedByMeDate 550 */ 551 void setLastViewedByMeDate(const QDateTime &lastViewedByMeDate); 552 553 /** 554 * @brief Returns a link for downloading the content of the file in a browser 555 * using cookie based authentication. 556 * 557 * In cases where the content is shared publicly, the content can be 558 * downloaded without any credentials. 559 */ 560 QUrl webContentLink() const; 561 562 /** 563 * @brief Returns whether this file has been explicitly trashed, as opposed 564 * to recursively trashed. 565 * 566 * This will only be populated if the file is trashed. 567 */ 568 bool explicitlyTrashed() const; 569 570 /** 571 * @brief Returns metadata about image media. 572 * 573 * This will only be present for image types, and its contents will depend 574 * on what can be parsed from the image content. 575 */ 576 File::ImageMediaMetadataPtr imageMediaMetadata() const; 577 578 /** 579 * @brief Returns thumbnail for the file. 580 */ 581 ThumbnailPtr thumbnail() const; 582 583 QUrl webViewLink() const; 584 585 QUrl iconLink() const; 586 587 bool shared() const; 588 589 UsersList owners() const; 590 591 UserPtr lastModifyingUser() const; 592 593 bool isFolder() const; 594 595 struct Fields { 596 static const QString Items; 597 static const QString SelfLink; 598 static const QString Etag; 599 static const QString Kind; 600 static const QString NextLink; 601 static const QString NextPageToken; 602 static const QString Id; 603 static const QString Title; 604 static const QString MimeType; 605 static const QString Description; 606 static const QString Labels; 607 static const QString CreatedDate; 608 static const QString ModifiedDate; 609 static const QString ModifiedByMeDate; 610 static const QString DownloadUrl; 611 static const QString IndexableText; 612 static const QString UserPermission; 613 static const QString FileExtension; 614 static const QString Md5Checksum; 615 static const QString FileSize; 616 static const QString AlternateLink; 617 static const QString EmbedLink; 618 static const QString SharedWithMeDate; 619 static const QString Parents; 620 static const QString ExportLinks; 621 static const QString OriginalFilename; 622 static const QString OwnerNames; 623 static const QString LastModifiedByMeDate; 624 static const QString Editable; 625 static const QString WritersCanShare; 626 static const QString ThumbnailLink; 627 static const QString LastViewedByMeDate; 628 static const QString WebContentLink; 629 static const QString ExplicitlyTrashed; 630 static const QString ImageMediaMetadata; 631 static const QString Thumbnail; 632 static const QString WebViewLink; 633 static const QString IconLink; 634 static const QString Shared; 635 static const QString Owners; 636 static const QString LastModifyingUser; 637 static const QString AppDataContents; 638 static const QString OpenWithLinks; 639 static const QString DefaultOpenWithLink; 640 static const QString HeadRevisionId; 641 static const QString Copyable; 642 static const QString Properties; 643 static const QString MarkedViewedByMeDate; 644 static const QString Version; 645 static const QString SharingUser; 646 static const QString Permissions; 647 }; 648 649 static FilePtr fromJSON(const QByteArray &jsonData); 650 static FilesList fromJSONFeed(const QByteArray &jsonData, FeedData &feedData); 651 static QByteArray toJSON(const FilePtr &file, SerializationOptions options = NoOptions); 652 653 static FilePtr fromJSON(const QVariantMap &jsonData); 654 655 private: 656 Private * const d; 657 friend class Private; 658 friend class Change::Private; 659 friend class ParentReference; 660 friend class Permission; 661 }; 662 663 } /* namespace Drive */ 664 665 } /* namespace KGAPI2 */ 666 667 Q_DECLARE_OPERATORS_FOR_FLAGS(KGAPI2::Drive::File::SerializationOptions) 668 669