File indexing completed on 2024-04-14 03:50:39

 /*
   This file is part of the kcalcore library.
 
   SPDX-FileCopyrightText: 2002 Michael Brade <brade@kde.org>
 
   SPDX-License-Identifier: LGPL-2.0-or-later
 */
 /**
   @file
   This file is part of the API for handling calendar data and
   defines the Attachment class.
 
   @author Michael Brade \<brade@kde.org\>
 */
 
 #ifndef KCALCORE_ATTACHMENT_H
 #define KCALCORE_ATTACHMENT_H
 
 #include "kcalendarcore_export.h"
 
 #include <QHash>
 #include <QMetaType>
 #include <QSharedDataPointer>
 #include <QString>
 
 namespace KCalendarCore
 {
 /**
   @brief
   Represents information related to an attachment for a Calendar Incidence.
 
   This is not an email message attachment.
 
   Calendar Incidence attachments consist of:
   - A <a href="https://en.wikipedia.org/wiki/Uniform_Resource_Identifier">
     Uniform Resource Identifier (URI)</a>
     or a
     <a href="https://en.wikipedia.org/wiki/Base64#MIME">base64 encoded</a>
     binary blob.
   - A <a href="https://en.wikipedia.org/wiki/MIME">
     Multipurpose Internet Mail Extensions (MIME)</a> type.
 
   This class is used to associate files (local or remote) or other resources
   with a Calendar Incidence.
 */
 class KCALENDARCORE_EXPORT Attachment
 {
     Q_GADGET
     Q_PROPERTY(bool isEmpty READ isEmpty)
     Q_PROPERTY(QString uri READ uri WRITE setUri)
     Q_PROPERTY(bool isUri READ isUri)
     Q_PROPERTY(bool isBinary READ isBinary)
     Q_PROPERTY(int size READ size)
     Q_PROPERTY(QString mimeType READ mimeType WRITE setMimeType)
     Q_PROPERTY(bool showInline READ showInline WRITE setShowInline)
     Q_PROPERTY(QString label READ label WRITE setLabel)
     Q_PROPERTY(bool isLocal READ isLocal WRITE setLocal)
 
 public:
     /**
       List of attachments.
     */
     typedef QList<Attachment> List;
 
     /**
       Constructs an empty attachment.
     */
     explicit Attachment();
 
     /**
       Constructs an attachment consisting of a @p uri and a @p mime type.
 
       @param uri is the @acronym URI referred to by this attachment.
       @param mime is the (optional) @acronym MIME type of the @p uri
     */
     explicit Attachment(const QString &uri, const QString &mime = QString());
 
     /**
       Constructs an attachment consisting of a binary blob of data
       and a @p mime type.
 
       @param base64 is the binary data in base64 format for the attachment.
       @param mime is the (optional) @acronym MIME type of the attachment
     */
     explicit Attachment(const QByteArray &base64, const QString &mime = QString());
 
     /**
       Constructs an attachment by copying another attachment.
 
       @param attachment is the attachment to be copied.
     */
     Attachment(const Attachment &attachment);
 
     /**
       Destroys the attachment.
     */
     ~Attachment();
 
     /**
        Returns whether this is an empty or default constructed object.
     */
     bool isEmpty() const;
 
     /**
       Sets the @acronym URI for this attachment to @p uri.
 
       @param uri is the @acronym URI to use for the attachment.
 
       @see uri(), isUri()
     */
     void setUri(const QString &uri);
 
     /**
       Returns the @acronym URI of the attachment.
 
       @see setUri(), isUri()
     */
     Q_REQUIRED_RESULT QString uri() const;
 
     /**
       Returns true if the attachment has a @acronym URI; false otherwise.
 
       @see uri(), setUri(I), isBinary()
     */
     Q_REQUIRED_RESULT bool isUri() const;
 
     /**
       Returns true if the attachment has a binary blob; false otherwise.
 
       @see isUri()
     */
     Q_REQUIRED_RESULT bool isBinary() const;
 
     /**
       Sets the base64 encoded binary blob data of the attachment.
 
       @param base64 contains the base64 encoded binary data.
 
       @see data(), decodedData()
     */
     void setData(const QByteArray &base64);
 
     /**
       Returns a pointer to a QByteArray containing the base64 encoded
       binary data of the attachment.
 
       @see setData(), setDecodedData()
     */
     Q_REQUIRED_RESULT QByteArray data() const;
 
     /**
       Sets the decoded attachment data.
 
       @param data is the decoded base64 binary data.
 
       @see decodedData(), data()
     */
     void setDecodedData(const QByteArray &data);
 
     /**
       Returns a QByteArray containing the decoded base64 binary data of the
       attachment.
 
       @see setDecodedData(), setData()
     */
     Q_REQUIRED_RESULT QByteArray decodedData() const;
 
     /**
       Returns the size of the attachment, in bytes.
       If the attachment is binary (i.e, there is no @acronym URI associated
       with the attachment) then a value of 0 is returned.
     */
     uint size() const;
 
     /**
       Sets the @acronym MIME-type of the attachment to @p mime.
 
       @param mime is the string to use for the attachment @acronym MIME-type.
 
       @see mimeType()
     */
     void setMimeType(const QString &mime);
 
     /**
       Returns the @acronym MIME-type of the attachment.
 
       @see setMimeType()
     */
     Q_REQUIRED_RESULT QString mimeType() const;
 
     /**
       Sets the attachment "show in-line" option, which is derived from
       the Calendar Incidence @b X-CONTENT-DISPOSITION parameter.
 
       @param showinline is the flag to set (true) or unset (false)
       for the attachment "show in-line" option.
 
       @see showInline()
     */
     void setShowInline(bool showinline);
 
     /**
       Returns the attachment "show in-line" flag.
 
       @see setShowInline()
     */
     Q_REQUIRED_RESULT bool showInline() const;
 
     /**
       Sets the attachment label to @p label, which is derived from
       the Calendar Incidence @b X-LABEL parameter.
 
       @param label is the string to use for the attachment label.
 
       @see label()
     */
     void setLabel(const QString &label);
 
     /**
       Returns the attachment label string.
     */
     Q_REQUIRED_RESULT QString label() const;
 
     /**
       Sets the attachment "local" option, which is derived from the
       Calendar Incidence @b X-KONTACT-TYPE parameter.
 
       @param local is the flag to set (true) or unset (false) for the
       attachment "local" option.
 
       @see local()
     */
     void setLocal(bool local);
 
     /**
       Returns the attachment "local" flag.
     */
     Q_REQUIRED_RESULT bool isLocal() const;
 
     /**
       Assignment operator.
       @param attachment is the attachment to assign.
     */
     Attachment &operator=(const Attachment &attachment);
 
     /**
       Compare this with @p attachment for equality.
       @param attachment is the attachment to compare.
       @return true if the attachments are equal; false otherwise.
      */
     bool operator==(const Attachment &attachment) const;
 
     /**
       Compare this with @p attachment for inequality.
       @param attachment is the attachment to compare.
       @return true if the attachments are /not/ equal; false otherwise.
      */
     bool operator!=(const Attachment &attachment) const;
 
 private:
     //@cond PRIVATE
     class Private;
     QSharedDataPointer<Private> d;
     //@endcond
 
     friend KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalendarCore::Attachment &);
     friend KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &s, KCalendarCore::Attachment &);
 };
 
 /**
  * Attachment serializer.
  *
  * @since 4.12
  */
 KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalendarCore::Attachment &);
 
 /**
  * Attachment deserializer.
  *
  * @since 4.12
  */
 KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &in, KCalendarCore::Attachment &);
 
 }
 
 //@cond PRIVATE
 Q_DECLARE_TYPEINFO(KCalendarCore::Attachment, Q_RELOCATABLE_TYPE);
 Q_DECLARE_METATYPE(KCalendarCore::Attachment)
 //@endcond
 
 #endif