/*
    KMime, the KDE Internet mail/usenet news message library.
    SPDX-FileCopyrightText: 2001 the KMime authors.
    See file AUTHORS for details
    SPDX-FileCopyrightText: 2006 Volker Krause <vkrause@kde.org>
    SPDX-FileCopyrightText: 2009 Constantin Berzan <exit3219@gmail.com>

    SPDX-License-Identifier: LGPL-2.0-or-later
*/

#pragma once

#include "kmime_export.h"
#include "contentindex.h"
#include "util.h"
#include "headers.h"

#include <QByteArray>
#include <QList>
#include <QMetaType>

#include <memory>
#include <span>

namespace KMime
{

/*!
 * Controls whether to create a header that does not exist.
 *
 * \value DontCreate Do not create header
 * \value Create Create header
 *
 * \since 26.04
 */
enum CreatePolicy {
    DontCreate,
    Create,
};

namespace Internal {

template <typename T>
class OwningConstPtrSpan : public std::span<const T *const> {
public:
    explicit inline OwningConstPtrSpan(const QList<T*> &list)
      : std::span<const T *const>(static_cast<const T* const*>(list.constData()), list.size())
      , m_list(list)
    {}
private:
    QList<T*> m_list;
};
}

class ContentPrivate;
class Message;

/*!
  \class KMime::Content
  \inmodule KMime
  \inheaderfile KMime/Content

  \brief A class that encapsulates MIME encoded Content.

  A Content object holds two representations of a content:
  \list
  \li the string representation: This is the content encoded as a string ready
    for transport.  Accessible through the encodedContent() method.
  \li the broken-down representation: This is the tree of objects (headers,
    sub-Contents and (if present) the encapsulated message) that this Content is made of.
    Accessible through methods like header(), contents() and bodyAsMessage().
  \endlist

  The parse() function updates the broken-down representation of the Content
  from its string representation.  Calling it is necessary to access the
  headers, sub-Contents or the encapsulated message of this Content.

  The assemble() function updates the string representation of the Content
  from its broken-down representation.  Calling it is necessary for
  encodedContent() to reflect any changes made to the broken-down representation of the Content.

  There are two basic types of a Content:
  \list
  \li A leaf Content: This is a content that is neither a multipart content nor an encapsulated
                    message. Because of this, it will not have any children, it has no sub-contents
                    and is therefore a leaf content.
                    Only leaf contents have a body that is not empty, i.e. functions that operate
                    on the body, such as body(), size() and decodedBody(), will work only on
                    leaf contents.
  \li A non-leaf Content: This is a content that itself doesn't have any body, but that does have
                        sub-contents.
                        This is the case for contents that are of mimetype multipart/ or of mimetype
                        message/rfc822. In case of a multipart content, contents() will return the
                        multipart child contents. In case of an encapsulated message, the message
                        can be accessed with bodyAsMessage(), and contents() will have one entry
                        that is the message as well.
                        On a non-leaf content, body() will have an empty return value and other
                        functions working on the body will not work.
                        A call to parse() is required before the child multipart contents or the
                        encapsulated message is created.
  \endlist
*/
class KMIME_EXPORT Content
{
public:
  /*!
    Creates an empty Content object.
    \since 4.3
  */
  explicit Content();

  virtual ~Content();

  /*!
    Returns \c true if this Content object is not empty.
  */
  [[nodiscard]] bool hasContent() const;

  /*!
    Sets the Content to the given raw data, containing the Content head and
    body separated by two linefeeds.

    This method operates on the string representation of the Content. Call
    parse() if you want to access individual headers, sub-Contents or the
    encapsulated message.

    \note The passed data must not contain any CRLF sequences, only LF.
          Use CRLFtoLF for conversion before passing in the data.

    \a s is a QByteArray containing the raw Content data.
  */
  void setContent(const QByteArray &s);

  /*!
   * Parses the Content.
   *
   * This means the broken-down object representation of the Content is
   * updated from the string representation of the Content.
   *
   * Call this if you want to access or change headers, sub-Contents or the
   * encapsulated message.
   *
   * Note Calling parse() twice will not work for multipart contents or for
   * contents of which the body is an encapsulated message. The reason is that
   * the first parse() will delete the body, so there is no body to work on for
   * the second call of parse().
   *
   * \note Calling this will reset the message returned by bodyAsMessage(), as
   *       the message is re-parsed as well.
   *       Also, all old sub-contents will be deleted, so any old Content
   * pointer will become invalid.
   */
  void parse();

  /*!
    Returns whether this Content is frozen.

    A frozen content is immutable, i.e. calling assemble() will never modify
    its head or body, and encodedContent() will return the same data before
    and after parsing.

    \since 4.4.
    \sa setFrozen().
  */
  [[nodiscard]] bool isFrozen() const;

  /*!
    Freezes this Content if \a frozen is \c true; otherwise unfreezes it.

    \a frozen freeze content if \c true, otherwise unfreeze
    \since 4.4
    \sa isFrozen().
  */
  void setFrozen(bool frozen = true);

  /*!
    Generates the MIME content.

    This means the string representation of this Content is updated from the
    broken-down object representation.
    Call this if you have made changes to the content, and want
    encodedContent() to reflect those changes.

    Note assemble() has no effect if the Content isFrozen().  You may want
    to freeze, for instance, signed sub-Contents, to make sure they are kept
    unmodified.

    Note If this content is an encapsulated message, i.e. bodyIsMessage()
    returns true, then calling assemble() will also assemble the message
    returned by bodyAsMessage().

    \warning assemble() may change the order of the headers, and other
    details such as where folding occurs.  This may break things like
    signature verification, so you should *ONLY* call assemble() when you
    have actually modified the content.
  */
  virtual void assemble();

  /*!
    Clears the content, deleting all headers and sub-Contents.
  */
  void clear();

  /*!
    Returns the Content header raw data.

    \sa setHead().
  */
  [[nodiscard]] QByteArray head() const;

  /*!
    Sets the Content header raw data.

    This method operates on the string representation of the Content. Call
    parse() if you want to access individual headers.

    \a head is a QByteArray containing the header data.

    \sa head().
  */
  void setHead(const QByteArray &head);

  /*!
   * Returns all headers.
   * \since 5.7
   */
  [[nodiscard]] QList<Headers::Base *> headers();
  [[nodiscard]] inline auto headers() const -> auto
  {
      return Internal::OwningConstPtrSpan<Headers::Base>(const_cast<Content*>(this)->headers());
  }

  /*!
    Returns the first header of type \a type, if it exists.

    Otherwise returns \nullptr. Note that the returned header may be empty.

    \a type the header type to find

    \since 4.2
  */
  [[nodiscard]] Headers::Base *headerByType(QByteArrayView type) const;

  /*!
    Returns the first header of type T, if it exists.

    If the header does not exist and \a create is \c Create, creates an empty header
    and returns it. Otherwise returns \nullptr. Ownership of the header remains with
    the Content object, the created header is automatically added to that.

    Note that the returned header may be empty.

    \a create Whether to create the header if it does not exist.

    \since 4.4 (took a bool before 26.04)
  */
  template <typename T> T *header(CreatePolicy create = Create);
  /*!
    Returns the first header of type \c T.

    Can be \nullptr if such a header doesn't exist.
    \since 24.08
  */
  template <typename T> [[nodiscard]] const std::remove_cv_t<T> *header() const;

  /*!
    Returns all \a type headers in the Content.

    Take care that this result is not cached, so could be slow.

    \a type the header type to find

    \since 4.2
  */
  [[nodiscard]] QList<Headers::Base *> headersByType(QByteArrayView type) const;

  /*!
    Sets the specified header to this Content.

    Any previous header of the same type is removed.

    If you need multiple headers of the same type, use appendHeader() or
    prependHeader().

    \a h The header to set.

    \sa appendHeader()
    \sa removeHeader()
    \since 4.4 (took a raw pointer before 26.04)
  */
  void setHeader(std::unique_ptr<Headers::Base> &&h);

  /*!
    Appends the specified header to the headers of this Content.

    \a h The header to append.

    \since 4.4 (took a raw pointer before 26.04)
  */
  void appendHeader(std::unique_ptr<Headers::Base> &&h);

  /*!
    Searches for the first header of type \a type, and deletes it, removing
    it from this Content.

    \a type The type of the header to look for.

    Returns \c true if a header was found and removed.
  */
  bool removeHeader(QByteArrayView type);

  /*!
    Searches for the first header of type \c T, and deletes it, removing
    it from this Content.

    \c T The type of the header to look for.

    Returns \c true if a header was found and removed.
  */
  template <typename T> bool removeHeader();

  // TODO probably provide hasHeader<T>() too.
  /*!
    Returns true if this Content has a header of type \a type.
  */
  [[nodiscard]] bool hasHeader(QByteArrayView type) const;

  /*!
    Returns the Content-Type header.

    \a create Whether to create the header if it doesn't exist yet.
  */
  Headers::ContentType *contentType(CreatePolicy create = Create);
  /*!
    Returns the Content-Type header.

    Can be \nullptr if the header doesn't exist.
    \since 24.08
  */
  [[nodiscard]] const Headers::ContentType *contentType() const;

  /*!
    Returns the Content-Transfer-Encoding header.

    Ownership of the header remains with the Content object,
    the created header is automatically added to that.

    \a create Whether to create the header if it doesn't exist yet.
  */
  Headers::ContentTransferEncoding *contentTransferEncoding(CreatePolicy create = Create);
  /*!
    Returns the Content-Transfer-Encoding header.

    Can be \nullptr if the header doesn't exist.
    \since 24.08
  */
  [[nodiscard]] const Headers::ContentTransferEncoding *contentTransferEncoding() const;

  /*!
    Returns the Content-Disposition header.

    Ownership of the header remains with the Content object,
    the created header is automatically added to that.

    \a create Whether to create the header if it doesn't exist yet.
  */
  Headers::ContentDisposition *contentDisposition(CreatePolicy create = Create);
  /*!
    Returns the Content-Disposition header.

    Can be \nullptr if the header doesn't exist.
    \since 24.08
  */
  [[nodiscard]] const Headers::ContentDisposition *contentDisposition() const;

  /*!
    Returns the Content-Description header.

    Ownership of the header remains with the Content object,
    the created header is automatically added to that.

    \a create Whether to create the header if it doesn't exist yet.
  */
  Headers::ContentDescription *contentDescription(CreatePolicy create = Create);
  /*!
    Returns the Content-Description header.

    Can be \nullptr if the header doesn't exist.
    \since 24.08
  */
  [[nodiscard]] const Headers::ContentDescription *contentDescription() const;

  /*!
    Returns the Content-Location header.

    Ownership of the header remains with the Content object,
    the created header is automatically added to that.

    \a create Whether to create the header if it doesn't exist yet.
    \since 4.2
  */
  Headers::ContentLocation *contentLocation(CreatePolicy create = Create);
  /*!
    Returns the Content-Location header.

    Can be \nullptr if the header doesn't exist.
    \since 24.08
  */
  [[nodiscard]] const Headers::ContentLocation *contentLocation() const;

  /*!
    Returns the Content-ID header.

    Ownership of the header remains with the Content object,
    the created header is automatically added to that.

    \a create Whether to create the header if it doesn't exist yet.
    \since 4.4
  */
  Headers::ContentID *contentID(CreatePolicy create = Create);
  /*!
    Returns the Content-ID header.

    Can be \nullptr if the header doesn't exist.
    \since 24.08
  */
  [[nodiscard]] const Headers::ContentID *contentID() const;

  /*!
    Returns the size of the Content body after encoding.

    (If the encoding is quoted-printable, this is only an approximate size.)

    This will return 0 for multipart contents or for encapsulated messages.
  */
  [[nodiscard]] qsizetype size() const;

  /*!
    Returns the size of this Content and all sub-Contents.
  */
  [[nodiscard]] qsizetype storageSize() const;

  /*!
    Returns the Content body raw data.

    Note that this will be empty for multipart contents or for encapsulated
    messages, after parse() has been called.

    \sa setBody().
  */
  [[nodiscard]] QByteArray body() const;

  /*!
    Sets the Content decoded body raw data.

    This method operates on the string representation of the Content. Call
    parse() if you want to access individual sub-Contents or the encapsulated
    message.

    \a body is a QByteArray containing the body data.

    Note \a body is assumed to be decoded as far as the content transfer encoding
    is concerned.

    \sa setEncodedBody()
  */
  void setBody(const QByteArray &body);

  /*!
    Sets the Content body raw data encoded according to the content transfer encoding.

    This method operates on the string representation of the Content. Call
    parse() if you want to access individual sub-Contents or the encapsulated
    message.

    \a body is a QByteArray containing the body data.

    Note \a body is assumed to be encoded as far as the content transfer encoding
    is concerned.

    \since 24.08

    \sa setBody()
  */
  void setEncodedBody(const QByteArray &body);

  /*!
    Returns the MIME preamble.

    \since 4.9
   */
  [[nodiscard]] QByteArray preamble() const;

  /*!
    Sets the MIME preamble.

    \a preamble a QByteArray containing what will be used as the
    MIME preamble.

    \since 4.9
   */
  void setPreamble(const QByteArray &preamble);

  /*!
    Returns the MIME epilogue.

    Returns a QByteArray containing the MIME epilogue.

    \since 4.9
   */
  [[nodiscard]] QByteArray epilogue() const;

  /*!
    Sets the MIME epilogue.

    \a epilogue a QByteArray containing what will be used as the
    MIME epilogue.

    \since 4.9
   */
  void setEpilogue(const QByteArray &epilogue);

  /*!
    Returns a QByteArray containing the encoded Content, including the
    Content header and all sub-Contents.

    If you make changes to the broken-down representation of the message, be
    sure to first call assemble() before calling encodedContent(), otherwise
    the result will not be up-to-date.

    If this content is an encapsulated message, i.e. bodyIsMessage() returns
    true, then encodedContent() will use the message returned by bodyAsMessage()
    as the body of the result, calling encodedContent() on the message.

    \a newline whether to use CRLF for linefeeds, or LF (default is LF).
  */
  [[nodiscard]] QByteArray encodedContent(NewlineType newline = NewlineType::LF) const;

  /*!
   * Like encodedContent(), with the difference that only the body will be
   * returned, i.e. the headers are excluded.
   *
   * \since 4.6
   */
  [[nodiscard]] QByteArray encodedBody() const;

  /*!
   * Returns the decoded Content body.
   *
   * Note that this will be empty for multipart contents or for encapsulated
   * messages, after parse() has been called.
   * \since 25.12 (previously decodedContent())
   */
  [[nodiscard]] QByteArray decodedBody() const;

  /*! Options for Content::decodedText().
   *  \since 24.12
   *  \value NoTrim Do not trim text content
   *  \value TrimNewlines Trim trailing newlines
   *  \value TrimSpaces Trim any trailing whitespaces
   */
  enum DecodedTextTrimOption {
    NoTrim,
    TrimNewlines,
    TrimSpaces,
  };

  /*!
    Returns the decoded text. Additional to decodedBody(), this also
    applies charset decoding. If this is not a text Content, decodedText()
    returns an empty QString.

    \a trimOption Control how to trim trailing white spaces.
    The last trailing new line of the decoded text is always removed.

    \since 24.12
  */
  [[nodiscard]] QString decodedText(DecodedTextTrimOption trimOption = NoTrim) const;

  /*!
    Sets the Content body to the given string using charset of the content type.

    If the charset can not be found, the system charset is taken and the content
    type header is changed to that charset. The charset of the content type
    header should be set to a charset that can encode the given string before
    calling this method.

    This method does not set the content transfer encoding automatically, it
    needs to be set to a suitable value that can encode the given string before
    calling this method.

    This method only makes sense for single-part contents, do not try to pass a
    multipart body or an encapsulated message here, that wouldn't work.

    \a s Unicode-encoded string.
  */
  void fromUnicodeString(const QString &s);

  /*!
    Returns the first Content with mimetype text/.
  */
  [[nodiscard]] Content *textContent();
  /*!
    Returns the first Content with MIME type text/.

    Const overload of the above, the returned Content cannot be modified.
    \since 24.08
  */
  [[nodiscard]] const Content *textContent() const;

  /*!
   * Returns all attachments below this node, recursively.
   *
   * This does not include crypto parts, nodes of alternative or related
   * multipart nodes, or the primary body part (see textContent()).
   * \sa KMime::isAttachment(), KMime::hasAttachment()
   */
  [[nodiscard]] QList<Content *> attachments();
  [[nodiscard]] inline auto attachments() const -> auto {
      return Internal::OwningConstPtrSpan<Content>(const_cast<Content*>(this)->attachments());
  }

  /*!
   * For multipart contents, this will return a list of all multipart child
   * contents.
   *
   * For contents that are of mimetype message/rfc822, this will
   * return a list with one entry, and that entry is the encapsulated message,
   * as it would be returned by bodyAsMessage().
   */
  [[nodiscard]] QList<Content *> contents();
  [[nodiscard]] inline auto contents() const -> auto {
      return Internal::OwningConstPtrSpan<Content>(const_cast<Content*>(this)->contents());
  }

  /*!
    Appends a new sub-Content. If the sub-Content is already part of another
    Content object, it is removed from there and its parent is updated.

    \a content The new sub-Content.
    \sa prependContent()
    \sa takeContent()
    \since 6.0 (took a raw pointer until 26.04)
  */
  void appendContent(std::unique_ptr<KMime::Content> &&content);

  /*!
    Prepends a new sub-Content. If the sub-Content is already part of another
    Content object, it is removed from there and its parent is updated.

    \a content The new sub-Content.
    \sa appendContent()
    \sa takeContent()
    \since 6.0 (took a raw pointer until 26.04)
  */
  void prependContent(std::unique_ptr<KMime::Content> &&content);

  /*!
    Removes the given sub-Content and, if that actually was a sub-content
    returns that.

    \a content The Content to remove. It is not deleted, ownership goes
    back to the caller.

    \sa appendContent()
    \sa prependContent()
    \sa clearContents()
    \since 6.0 (returned a raw pointer until 26.04)
  */
  std::unique_ptr<Content> takeContent(Content *content);

  /*!
    Changes the encoding of this Content to \a e.  If the Content is binary,
    this actually re-encodes the data to use the new encoding.

    \a e The new encoding to use.
  */
  void changeEncoding(Headers::contentEncoding e);

  /*!
    Returns the Content specified by the given index.

    If the index does not point to a Content, \nullptr is returned.

    If the index is invalid (empty), this Content is returned.

    \a index The Content index.
  */
  [[nodiscard]] Content *content(const ContentIndex &index) const;

  /*!
    Returns the ContentIndex for the given Content, or an invalid index
    if the Content is not found within the hierarchy.

    \a content the Content object to search.
  */
  [[nodiscard]] ContentIndex indexForContent(const Content *content) const;

  /*!
    Returns true if this is the top-level node in the MIME tree.

    The top-level node is always a Message or NewsArticle.

    However, a node can be a Message
    without being a top-level node when it is an encapsulated message.
  */
  [[nodiscard]] bool isTopLevel() const;

  /*!
   * Sets a new parent to the Content and add to its contents list.
   *
   * If it already had a parent, it is removed from the old parents contents list.
   *
   * \a parent the new parent
   * \since 4.3
   */
  void setParent(Content *parent);

  /*!
   * Returns the parent content object, or 0 if the content doesn't have a
   * parent.
   * \since 4.3
   */
  [[nodiscard]] Content *parent();
  [[nodiscard]] const Content *parent() const;

  /*!
   * Returns the toplevel content object, 0 if there is no such object.
   * \since 4.3
   */
  [[nodiscard]] Content *topLevel();
  [[nodiscard]] const Content *topLevel() const;


  /*!
   * Returns the index of this Content based on the topLevel() object.
   * \since 4.3
   */
  [[nodiscard]] ContentIndex index() const;

  // AK_REVIEW: move to MessageViewer/ObjectTreeParser
  /*!
   * Returns true if this content is an encapsulated message, i.e. if it has the
   * mimetype message/rfc822.
   *
   * \since 4.5
   */
  [[nodiscard]] bool bodyIsMessage() const;

  /*!
   * If this content is an encapsulated message, in which case bodyIsMessage()
   * will return true, the message represented by the body of this content will
   * be returned.
   *
   * The returned message is already fully parsed. Calling this
   * method is the aquivalent of calling contents().first() and casting the
   * result to a KMime::Message*. bodyAsMessage() has the advantage that it will
   * return a shared pointer that will not be destroyed when the container
   * message is destroyed or re-parsed.
   *
   * The message that is returned here is created when calling parse(), so make
   * sure to call parse() first. Since each parse() creates a new message
   * object, a different message object will be returned each time you call
   * parse().
   *
   * If you make changes to the returned message, you need to call assemble() on
   * this content or on the message if you want that encodedContent() reflects
   * these changes. This also means that calling assemble() on this content will
   * assemble the returned message.
   *
   * \since 4.5
   */
  [[nodiscard]] std::shared_ptr<Message> bodyAsMessage();
  [[nodiscard]] inline std::shared_ptr<const Message> bodyAsMessage() const
  {
      return const_cast<Content*>(this)->bodyAsMessage();
  }

  /*!
   * Create a copy of this content object.
   *
   * This is recursive, ie. all child content objects are also cloned.
   * Prefer this over serializing and deserializing conetent as this is
   * is more efficient due to making use of copy-on-write.
   *
   * \since 26.04
   */
  [[nodiscard]] virtual std::unique_ptr<Content> clone() const;
protected:
    std::unique_ptr<ContentPrivate> d_ptr;

private:
    Q_DECLARE_PRIVATE(Content)
    Q_DISABLE_COPY(Content)
};

template <typename T> T *Content::header(CreatePolicy create)
{

    if (auto h = headerByType(T::staticType()); h) {
        // Make sure the header is actually of the right type.
        Q_ASSERT(dynamic_cast<T *>(h));
        return static_cast<T *>(h);
    }
    if (create == Create) {
        auto hptr = std::make_unique<T>();
        auto h = hptr.get();
        appendHeader(std::move(hptr)); // we already know the header doesn't exist yet
        return h;
    }
    return nullptr;
}

template <typename T> const std::remove_cv_t<T> *Content::header() const
{
    Headers::Base *h = headerByType(T::staticType());
    if (h) {
        // Make sure the header is actually of the right type.
        Q_ASSERT(dynamic_cast<T *>(h));
    }
    return static_cast<T *>(h);
}

template <typename T> bool Content::removeHeader()
{
    return removeHeader(T::staticType());
}

} // namespace KMime

Q_DECLARE_METATYPE(KMime::Content*)

