File indexing completed on 2024-03-03 04:09:36

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_FEED_H
0009 #define SYNDICATION_FEED_H
0010 
0011 #include <QSharedPointer>
0012 
0013 #include "syndication_export.h"
0014 
0015 class QDomElement;
0016 
0017 template<class T>
0018 class QList;
0019 template<class K, class T>
0020 class QMultiMap;
0021 class QString;
0022 
0023 namespace Syndication
0024 {
0025 //@cond PRIVATE
0026 class SpecificDocument;
0027 typedef QSharedPointer<SpecificDocument> SpecificDocumentPtr;
0028 class Category;
0029 typedef QSharedPointer<Category> CategoryPtr;
0030 class Feed;
0031 typedef QSharedPointer<Feed> FeedPtr;
0032 class Image;
0033 typedef QSharedPointer<Image> ImagePtr;
0034 class Item;
0035 typedef QSharedPointer<Item> ItemPtr;
0036 class Person;
0037 typedef QSharedPointer<Person> PersonPtr;
0038 //@endcond
0039 
0040 /**
0041  * This class represents a feed document ("Channel" in RSS, "Feed" in Atom).
0042  * It contains a ordered list of items (e.g., articles) and a description of the
0043  * feed (title, homepage, etc.). This interface abstracts from format-specific
0044  * details of e.g. Atom::FeedDocument or RSS::Document and provides a
0045  * format-agnostic, unified view on the document.
0046  * This way applications using the syndication library have no need to care
0047  * about the syndication format jungle at all. If necessary, format details and
0048  * specialities can be accessed using the specificDocument() method.
0049  *
0050  * @author Frank Osterfeld
0051  */
0052 class SYNDICATION_EXPORT Feed
0053 {
0054 public:
0055     /**
0056      * destructor
0057      */
0058     virtual ~Feed();
0059 
0060     /**
0061      * returns the format-specific document this abstraction wraps.
0062      * If you want to access format-specific properties, this can be used,
0063      * in combination with a DocumentVisitor.
0064      *
0065      * @return a shared pointer to the wrapped document.
0066      */
0067     virtual SpecificDocumentPtr specificDocument() const = 0;
0068 
0069     /**
0070      * A list of items, in the order they were parsed from the feed source.
0071      * (usually reverse chronological order, see also Item::datePublished()
0072      * for sorting purposes).
0073      *
0074      * @return list of items
0075      */
0076     virtual QList<ItemPtr> items() const = 0;
0077 
0078     /**
0079      * returns a list of categories this feed is associated with.
0080      * See Category for more information.
0081      *
0082      */
0083     virtual QList<CategoryPtr> categories() const = 0;
0084 
0085     /**
0086      * The title of the feed.
0087      *
0088      * This string may contain HTML markup.(Importantly, occurrences of
0089      * the characters &lt;,'\n', '&amp;', '\'' and  '\"' are escaped).
0090      *
0091      * @return the title, or a null string if none is specified
0092      */
0093     virtual QString title() const = 0;
0094 
0095     /**
0096      * returns a link pointing to a website associated with this channel.
0097      * (blog, news site etc.)
0098      *
0099      * @return a WWW link, or a null string if none is specified
0100      */
0101     virtual QString link() const = 0;
0102 
0103     /**
0104      * A description of the feed.
0105      *
0106      * This string may contain HTML markup.(Importantly, occurrences of
0107      * the characters &lt;,'\n', '&amp;', '\'' and  '\"' are escaped).
0108      *
0109      * @return the description as HTML, or a null string if none is
0110      * specified
0111      */
0112     virtual QString description() const = 0;
0113 
0114     /**
0115      * returns an image associated with this item.
0116      *
0117      * @return an image object, or a null image (Not a null pointer!
0118      * I.e., image()->isNull() is @c true)
0119      * if no image is specified in the feed
0120      *
0121      */
0122     virtual ImagePtr image() const = 0;
0123 
0124     /**
0125      * returns an icon associated with this item.
0126      *
0127      * @return an icon object, or a null icon (Not a null pointer!
0128      * I.e., icon()->isNull() is @c true)
0129      * if no image is specified in the feed
0130      *
0131      */
0132     virtual ImagePtr icon() const = 0;
0133 
0134     /**
0135      * returns a list of persons who created the feed content. If there is a
0136      * distinction between authors and contributors (Atom), both are added
0137      * to the list, where authors are added first.
0138      *
0139      * @return list of authors (and possibly other contributing persons)
0140      */
0141     virtual QList<PersonPtr> authors() const = 0;
0142 
0143     /**
0144      * The language used in the feed. This is a global setting, which can
0145      * be overridden by the contained items.
0146      *
0147      * TODO: describe concrete format (language codes)
0148      */
0149     virtual QString language() const = 0;
0150 
0151     /**
0152      * returns copyright information about the feed
0153      */
0154     virtual QString copyright() const = 0;
0155 
0156     /**
0157      * returns a list of feed metadata not covered by this class.
0158      * Can be used e.g. to access format extensions.
0159      *
0160      * The returned map contains key value pairs, where the key
0161      * is the tag name of the element, namespace prefix are resolved
0162      * to the corresponding URIs. The value is the XML element as read
0163      * from the document.
0164      *
0165      * For example, to access the &lt;itunes:subtitle> element, use
0166      * additionalProperties()["http://www.itunes.com/dtds/podcast-1.0.dtdsubtitle"].
0167      *
0168      * Currently this is only
0169      * supported for RSS 0.91..0.94/2.0 and Atom formats, but not for RDF
0170      * (RSS 0.9 and 1.0).
0171      */
0172     virtual QMultiMap<QString, QDomElement> additionalProperties() const = 0;
0173 
0174     /**
0175      * returns a description of the feed for debugging purposes
0176      *
0177      * @return debug string
0178      */
0179     virtual QString debugInfo() const;
0180 };
0181 
0182 } // namespace Syndication
0183 
0184 #endif // SYNDICATION_FEED_H