usermetadata.h

/*
    SPDX-FileCopyrightText: 2014 Vishesh Handa <me@vhanda.in>
 
    SPDX-License-Identifier: LGPL-2.1-or-later
*/
 
#ifndef KFILEMETADATA_USERMETADATA_H
#define KFILEMETADATA_USERMETADATA_H
 
#include "kfilemetadata_export.h"
#include <QStringList>
#include <QUrl>
 
#include <memory>
 
namespace KFileMetaData {
 
class UserMetaDataPrivate;
 
/**
 * \class UserMetaData usermetadata.h <KFileMetaData/UserMetaData>
 *
 * \brief The UserMetaData class can be used to read and set user meta data of files.
 */
class KFILEMETADATA_EXPORT UserMetaData
{
public:
    UserMetaData(const QString &filePath);
    UserMetaData(const UserMetaData &rhs);
    virtual ~UserMetaData();
 
    enum Error {
        /// i.e Success
        NoError = 0,
        /// An error that's not currently handled specifically @since 6.2
        UnknownError,
        /// Underlying filesystem does not provide extended attributes features @since 6.2
        NotSupported,
        /// There is insufficient space remaining to store the extended attribute. @since 6.2
        NoSpace,
        /// Process doesn't have write permission to the file or the file is marked append-only @since 6.2
        MissingPermission,
        /// The value size exceeds the maximum size allowed per-value (64 kB for Linux VFS) @since 6.2
        ValueTooBig,
        /// The attribute name is too long (255 bytes for Linux VFS)  @since 6.2
        NameToolong,
    };
 
    /**
     * @see Attributes
     */
    enum Attribute : uint32_t {
        None                 = 0x0,
        Any                  = None,
        Tags                 = 0x1,
        Rating               = 0x2,
        Comment              = 0x4,
        OriginUrl            = 0x8,
        OriginEmailSubject   = 0x10,
        OriginEmailSender    = 0x20,
        OriginEmailMessageId = 0x40,
        Other                = 0xffffff80,
        All                  = 0xffffffff,
    };
    /**
     * Stores a combination of #Attribute values.
     */
    Q_DECLARE_FLAGS(Attributes, Attribute)
 
    const UserMetaData& operator =(const UserMetaData& rhs);
 
    QString filePath() const;
    bool isSupported() const;
 
    Error setTags(const QStringList& tags);
    QStringList tags() const;
 
    int rating() const;
    Error setRating(int rating);
 
    QString userComment() const;
    Error setUserComment(const QString& userComment);
 
    QUrl originUrl() const;
    Error setOriginUrl(const QUrl &originUrl);
 
    QString originEmailSubject() const;
    Error setOriginEmailSubject(const QString &originEmailSubject);
 
    QString originEmailSender() const;
    Error setOriginEmailSender(const QString &originEmailSender);
 
    QString originEmailMessageId() const;
    Error setOriginEmailMessageId(const QString &originEmailMessageId);
 
#if KFILEMETADATA_ENABLE_DEPRECATED_SINCE(6, 2)
    /// @deprecated since 6.2
    QString attribute(const QString &name);
#endif
    /// @since 6.2
    QString attribute(const QString &name) const;
 
    Error setAttribute(const QString &name, const QString &value);
 
#if KFILEMETADATA_ENABLE_DEPRECATED_SINCE(6, 2)
    /// @deprecated since 6.2
    bool hasAttribute(const QString &name);
#endif
    /// @since 6.2
    bool hasAttribute(const QString &name) const;
 
    /**
      * Query list of available attributes
      *
      * Checks for the availability of the given \p attributes. May return
      * a superset of the input value when the file has attributes set
      * beyond the requested ones.
      *
      * If the input attribute mask is Attribute::Any, either Attribute::None
      * (the file has no user attributes) or Attribute::All (the file has at
      * least one attribute set) is returned.
      *
      * \since 5.60
      */
    Attributes queryAttributes(Attributes attributes = Attribute::Any) const;
 
private:
    const std::unique_ptr<UserMetaDataPrivate> d;
};
 
Q_DECLARE_OPERATORS_FOR_FLAGS(UserMetaData::Attributes)
}
 
#endif // KFILEMETADATA_USERMETADATA_H