File indexing completed on 2024-07-14 14:39:59

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_ENTRY_H
0009 #define SYNDICATION_ATOM_ENTRY_H
0010 
0011 #include <syndication/elementwrapper.h>
0012 #include <syndication/specificitem.h>
0013 
0014 #include <QList>
0015 
0016 #include <ctime>
0017 
0018 class QDomElement;
0019 class QString;
0020 
0021 namespace Syndication
0022 {
0023 class SpecificItemVisitor;
0024 
0025 namespace Atom
0026 {
0027 class Category;
0028 class Content;
0029 class Link;
0030 class Person;
0031 class Source;
0032 
0033 /**
0034  * an Atom entry, equivalent to the "items" in the RSS world.
0035  *
0036  * @author Frank Osterfeld
0037  */
0038 class SYNDICATION_EXPORT Entry : public ElementWrapper, public SpecificItem
0039 {
0040 public:
0041     /**
0042      * creates a null entry object
0043      */
0044     Entry();
0045 
0046     /**
0047      * creates an Entry object wrapping an atom:entry element.
0048      * @param element a DOM element, should be a atom:entry element
0049      * (although not enforced), otherwise this object will not parse
0050      * anything useful
0051      */
0052     explicit Entry(const QDomElement &element);
0053 
0054     /**
0055      * Used by visitors for double dispatch. See SpecificVisitor
0056      * for more information.
0057      * @param visitor the visitor calling the method
0058      */
0059 
0060     bool accept(SpecificItemVisitor *visitor) override;
0061 
0062     /**
0063      * list of persons who are authors of this entry. (required)
0064      *
0065      * If the entry itself does not have explicit author description,
0066      * its source author description is used. If none of these exist,
0067      * the list of authors of the containing feed is used. That list
0068      * is set by setFeedAuthors().
0069      */
0070     Q_REQUIRED_RESULT QList<Person> authors() const;
0071 
0072     /**
0073      * a list of categories this entry is filed to (optional)
0074      */
0075     Q_REQUIRED_RESULT QList<Category> categories() const;
0076 
0077     /**
0078      * list of persons contributing to this entry (optional)
0079      */
0080     Q_REQUIRED_RESULT QList<Person> contributors() const;
0081 
0082     /**
0083      * ID of the article. (required)
0084      * The ID must be unique inside this feed. The atom spec defines it as a
0085      * URI (which is not enforced by this parser)
0086      */
0087     Q_REQUIRED_RESULT QString id() const;
0088 
0089     /**
0090      * links pointing to associated web sites and other resources.
0091      *
0092      * Links are optional if the entry provides Content.
0093      * Otherwise, it must contain at least one link with
0094      * a @c rel value of @c "alternate". (see Link).
0095      */
0096     Q_REQUIRED_RESULT QList<Link> links() const;
0097 
0098     /**
0099      * copyright information (optional)
0100      *
0101      * @return copyright information for the entry (intended for human
0102      * readers), or a null string if not specified
0103      */
0104     Q_REQUIRED_RESULT QString rights() const;
0105 
0106     /**
0107      * source description of the content (optional)
0108      *
0109      * If the content was copied from another feed, this object contains
0110      * information about the source feed.
0111      *
0112      * @return source description, or a null object if not
0113      * specified
0114      */
0115     Q_REQUIRED_RESULT Source source() const;
0116 
0117     /**
0118      * The datetime of the publication of this entry (optional).
0119      *
0120      * @return the publication date in seconds since epoch
0121      */
0122     Q_REQUIRED_RESULT time_t published() const;
0123 
0124     /**
0125      * The datetime of the last modification of this entry (required).
0126      *
0127      * @return the modification date in seconds since epoch
0128      */
0129     Q_REQUIRED_RESULT time_t updated() const;
0130 
0131     /**
0132      * a short summary, abstract or excerpt of an entry. (optional)
0133      * This is usually more verbose than title() and but does not
0134      * contain the whole content as content() does.
0135      *
0136      * @return the summary as HTML, or a null string if not specified
0137      */
0138     Q_REQUIRED_RESULT QString summary() const;
0139 
0140     /**
0141      * title of the entry (required).
0142      *
0143      * @return the title as HTML
0144      */
0145     Q_REQUIRED_RESULT QString title() const;
0146 
0147     /**
0148      * content of the entry (optional)
0149      * See @ref Content for details
0150      *
0151      * @return entry content, or a null content object if not specified
0152      */
0153     Q_REQUIRED_RESULT Content content() const;
0154 
0155     /**
0156      * returns all child elements of this entry not covered by this class.
0157      * This can be used to access additional metadata from Atom extensions.
0158      */
0159     Q_REQUIRED_RESULT QList<QDomElement> unhandledElements() const;
0160 
0161     /**
0162      * Sets the list of the containing feed's authors, which will be used
0163      * as a fallback in authors() in case both the entry itself and its
0164      * source have no explicit author description.
0165      * @param feedAuthors the list of feed's authors
0166      */
0167     void setFeedAuthors(const QList<Person> &feedAuthors);
0168 
0169     /**
0170      * returns a description of this entry for debugging purposes
0171      *
0172      * @return debug string
0173      */
0174     Q_REQUIRED_RESULT QString debugInfo() const;
0175 
0176 private:
0177     QList<Person> m_feedAuthors;
0178 };
0179 
0180 } // namespace Atom
0181 } // namespace Syndication
0182 
0183 #endif // SYNDICATION_ATOM_ENTRY_H