File indexing completed on 2024-12-01 12:41:48

0001 /*
0002     This file is part of the syndication library
0003     SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef SYNDICATION_ATOM_CONTENT_H
0009 #define SYNDICATION_ATOM_CONTENT_H
0010 
0011 #include <syndication/elementwrapper.h>
0012 
0013 #include <QString>
0014 
0015 class QByteArray;
0016 class QDomElement;
0017 
0018 namespace Syndication
0019 {
0020 namespace Atom
0021 {
0022 /**
0023  * The content element either contains or links the content of an entry.
0024  * The content is usually plain text or HTML, but arbitrary XML or binary
0025  * content are also possible. If isContained() is false, the content is
0026  * not contained in the feed source, but linked.
0027  *
0028  * @author Frank Osterfeld
0029  */
0030 class SYNDICATION_EXPORT Content : public ElementWrapper
0031 {
0032 public:
0033     /**
0034      * format of the content.
0035      */
0036     enum Format {
0037         PlainText, /**< the content is plain text (i.e. "<", ">"
0038                     * etc. are text, not
0039                     * markup */
0040         EscapedHTML, /**< the content is escaped HTML, (i.e., "<", ">" etc.
0041                       * are markup) */
0042         XML, /**< the content is embedded XML */
0043         Binary, /**< the content is base64-encoded binary content */
0044     };
0045 
0046     /**
0047      * maps a mimetype to Format enum according to the Atom 1.0
0048      * specification
0049      *
0050      * @param type a valid mimetype, or one of "text", "html", "xhtml"
0051      * @param src content source, see src() for details.
0052      *
0053      */
0054     static Format mapTypeToFormat(const QString &type, const QString &src = QString());
0055 
0056     /**
0057      * creates a null content object.
0058      */
0059     Content();
0060 
0061     /**
0062      * creates a Content object wrapping an atom:content element.
0063      * @param element a DOM element, should be a atom:content element
0064      * (although not enforced), otherwise this object will not parse
0065      * anything useful
0066      */
0067     explicit Content(const QDomElement &element);
0068 
0069     /**
0070      * creates a copy of another Content object
0071      *
0072      * @param other the content object to copy
0073      */
0074     Content(const Content &other);
0075 
0076     /**
0077      * destructor
0078      */
0079     ~Content() override;
0080 
0081     /**
0082      * assigns another content objecct
0083      *
0084      * @param other the Content object to assign
0085      */
0086     Content &operator=(const Content &other);
0087 
0088     /**
0089      * the type of the content. This is either "text" (plain text),
0090      * "html" (escaped HTML), "xhtml" (embedded XHTML) or a mime type
0091      *
0092      * @return the content type. If no type is specified, "text" (the
0093      * default) is returned.
0094      */
0095     Q_REQUIRED_RESULT QString type() const;
0096 
0097     /**
0098      * If src() is set, the content of this entry is not contained in the
0099      * feed source, but available on the net.
0100      * src() then contains a URL (more precise: IRI reference) linking to
0101      * remote content.
0102      * If src is provided, type() should contain a mimetype, instead of "text",
0103      * "html" or "xhtml".
0104      *
0105      * @return  a null string if the content is contained in the feed
0106      * source, or a URL linking to the remote content
0107      */
0108     Q_REQUIRED_RESULT QString src() const;
0109 
0110     /**
0111      * returns the content as string. If the content format is Text, the
0112      * returned string contains the text as HTML.
0113      * If the content is embedded XML, the XML is returned as string.
0114      *
0115      * @return a string representation of the content, or a null string if
0116      * the content is either binary content or not contained but linked
0117      * (see isContained())
0118      */
0119 
0120     Q_REQUIRED_RESULT QString asString() const;
0121 
0122     /**
0123      * returns binary content as byte array.
0124      *
0125      * @return byte array containing the embedded binary data, or
0126      * an empty array if the content is not in binary format
0127      */
0128     Q_REQUIRED_RESULT QByteArray asByteArray() const;
0129 
0130     /**
0131      * returns the content format
0132      */
0133     Q_REQUIRED_RESULT Format format() const;
0134 
0135     /**
0136      * returns whether the content is contained in the feed source,
0137      * or not. If it is not contained, src() provides a URL to the
0138      * content.
0139      */
0140     Q_REQUIRED_RESULT bool isContained() const;
0141 
0142     /**
0143      * returns whether the content is embedded XML.
0144      * Use element() to access the DOM tree, or asString() to get the XML
0145      * as string.
0146      */
0147     Q_REQUIRED_RESULT bool isXML() const;
0148 
0149     /**
0150      * returns whether the content is binary content or not.
0151      * Use asByteArray() to access it.
0152      */
0153     Q_REQUIRED_RESULT bool isBinary() const;
0154 
0155     /**
0156      * returns whether the content is plain text or not.
0157      * Use asString() to access it.
0158      */
0159     Q_REQUIRED_RESULT bool isPlainText() const;
0160 
0161     /**
0162      * returns whether the content is escaped HTML or not
0163      * Use asString() to access it
0164      */
0165     Q_REQUIRED_RESULT bool isEscapedHTML() const;
0166 
0167     /**
0168      * returns a description of the content object
0169      * for debugging purposes
0170      *
0171      * @return debug string
0172      */
0173     Q_REQUIRED_RESULT QString debugInfo() const;
0174 
0175 private:
0176     class ContentPrivate;
0177     QSharedPointer<ContentPrivate> d;
0178 };
0179 
0180 } // namespace Atom
0181 } // namespace Syndication
0182 
0183 #endif // SYNDICATION_ATOM_CONTENT_H