File indexing completed on 2024-07-14 03:59:01

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_DOCUMENT_H
0009 #define SYNDICATION_ATOM_DOCUMENT_H
0010 
0011 #include <syndication/elementwrapper.h>
0012 #include <syndication/specificdocument.h>
0013 
0014 #include <ctime>
0015 
0016 template<class T>
0017 class QList;
0018 
0019 namespace Syndication
0020 {
0021 class DocumentVisitor;
0022 
0023 namespace Atom
0024 {
0025 class Category;
0026 class Entry;
0027 class EntryDocument;
0028 class FeedDocument;
0029 class Generator;
0030 class Link;
0031 class Person;
0032 //@cond PRIVATE
0033 typedef QSharedPointer<EntryDocument> EntryDocumentPtr;
0034 typedef QSharedPointer<FeedDocument> FeedDocumentPtr;
0035 //@endcond
0036 
0037 /**
0038  * An Atom 1.0 Feed Document, containing metadata describing the
0039  * feed and a number of entries.
0040  *
0041  * @author Frank Osterfeld
0042  */
0043 class SYNDICATION_EXPORT FeedDocument : public Syndication::SpecificDocument, public ElementWrapper
0044 {
0045 public:
0046     /**
0047      * default constructor, creates a null feed, which
0048      * is invalid.
0049      * @see isValid()
0050      */
0051     FeedDocument();
0052 
0053     /**
0054      * creates a FeedDocument wrapping an atom:feed element.
0055      * @param element a DOM element, should be a atom:feed document
0056      * (although not enforced), otherwise this object will not parse
0057      * anything useful
0058      */
0059     explicit FeedDocument(const QDomElement &element);
0060 
0061     /**
0062      * Used by visitors for double dispatch. See DocumentVisitor
0063      * for more information.
0064      * @param visitor the visitor calling the method
0065      */
0066     bool accept(DocumentVisitor *visitor) override;
0067 
0068     /**
0069      * a list of persons who are the authors of this feed.
0070      * According to the Atom 1.0 spec, a feed must have an
0071      * author unless all entries in it have one.
0072      */
0073     Q_REQUIRED_RESULT QList<Person> authors() const;
0074 
0075     /**
0076      * a list of persons who contribute to this feed. (optional)
0077      */
0078     Q_REQUIRED_RESULT QList<Person> contributors() const;
0079 
0080     /**
0081      * a list of categories this feed is assigned to (optional)
0082      */
0083     Q_REQUIRED_RESULT QList<Category> categories() const;
0084 
0085     /**
0086      * URL of an image serving as a feed icon (optional)
0087      *
0088      * @return icon URL, or a null string if not specified in the feed.
0089      */
0090     Q_REQUIRED_RESULT QString icon() const;
0091 
0092     /**
0093      * URL of an image serving as a feed logo (optional)
0094      *
0095      * @return image URL, or a null string if not specified in the feed.
0096      */
0097     Q_REQUIRED_RESULT QString logo() const;
0098 
0099     /**
0100      * a string that unambiguously identifies the feed (required)
0101      *
0102      * @return the ID of the feed. As defined in the Atom spec it must be
0103      * a valid URI (which is neither checked nor enforced by this parser)
0104      *
0105      */
0106     Q_REQUIRED_RESULT QString id() const;
0107 
0108     /**
0109      * copyright information (optional)
0110      *
0111      * @return copyright information for the feed (intended for human
0112      * readers), or a null string if not specified
0113      */
0114     Q_REQUIRED_RESULT QString rights() const;
0115 
0116     /**
0117      * feed title (required).
0118      *
0119      * @return title string as HTML.
0120      */
0121     Q_REQUIRED_RESULT QString title() const;
0122 
0123     /**
0124      * description or subtitle of the feed (optional).
0125      *
0126      * @return subtitle string as HTML, or a null string
0127      * if not specified in the feed.
0128      */
0129     Q_REQUIRED_RESULT QString subtitle() const;
0130 
0131     /**
0132      * description of the agent used to generate the feed. See
0133      * Generator for more information (optional).
0134      *
0135      * @return description of the generator, or a null Generator object
0136      * if not specified in the feed.
0137      */
0138     Q_REQUIRED_RESULT Generator generator() const;
0139 
0140     /**
0141      * The datetime of the last modification of the feed content.
0142      *
0143      * @return the modification date in seconds since epoch
0144      */
0145     Q_REQUIRED_RESULT time_t updated() const;
0146 
0147     /**
0148      * a list of links. See Link for more information on
0149      * link types.
0150      */
0151     Q_REQUIRED_RESULT QList<Link> links() const;
0152 
0153     /**
0154      * a list of the entries (items) in this feed.
0155      */
0156     Q_REQUIRED_RESULT QList<Entry> entries() const;
0157 
0158     /**
0159      * returns all child elements of this feed not covered by this class.
0160      * This can be used to access additional metadata from Atom extensions.
0161      */
0162     Q_REQUIRED_RESULT QList<QDomElement> unhandledElements() const;
0163 
0164     /**
0165      * returns a description of this feed document for debugging
0166      * purposes.
0167      *
0168      * @return debug string
0169      */
0170     Q_REQUIRED_RESULT QString debugInfo() const override;
0171 
0172     /**
0173      * returns whether this document is valid or not.
0174      * Invalid documents do not contain any useful
0175      * information.
0176      */
0177     Q_REQUIRED_RESULT bool isValid() const override;
0178 };
0179 
0180 /**
0181  * An Atom 1.0 Entry Document, containing a single Atom entry outside
0182  * of the context of a feed.
0183  *
0184  * @author Frank Osterfeld
0185  */
0186 class SYNDICATION_EXPORT EntryDocument : public Syndication::SpecificDocument, public Syndication::ElementWrapper
0187 {
0188 public:
0189     /**
0190      * default constructor, creates a null document, which is invalid.
0191      * @see isValid()
0192      */
0193     EntryDocument();
0194 
0195     /**
0196      * creates an Atom Entry Document wrapping an atom:entry element.
0197      * @param element a DOM element, should be a atom:entry element
0198      * (although not enforced), otherwise this object will not parse
0199      * anything useful
0200      */
0201     explicit EntryDocument(const QDomElement &element);
0202 
0203     /**
0204      * Used by visitors for double dispatch. See DocumentVisitor
0205      * for more information.
0206      * @param visitor the visitor calling the method
0207      */
0208     bool accept(DocumentVisitor *visitor) override;
0209 
0210     /**
0211      * returns the single entry described in the source.
0212      *
0213      * @return the entry
0214      */
0215     Q_REQUIRED_RESULT Entry entry() const;
0216 
0217     /**
0218      * returns a description of this entry document for debugging
0219      * purposes.
0220      *
0221      * @return debug string
0222      */
0223     Q_REQUIRED_RESULT QString debugInfo() const override;
0224 
0225     /**
0226      * returns whether this document is valid or not.
0227      * Invalid documents do not contain any useful
0228      * information.
0229      */
0230     Q_REQUIRED_RESULT bool isValid() const override;
0231 };
0232 
0233 } // namespace Atom
0234 } // namespace Syndication
0235 
0236 #endif // SYNDICATION_ATOM_DOCUMENT_H