1/*
2 This file is part of the syndication library
3 SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef SYNDICATION_FEED_H
9#define SYNDICATION_FEED_H
10
11#include <QSharedPointer>
12
13#include "syndication_export.h"
14
15class QDomElement;
16
17template<class T>
18class QList;
19template<class K, class T>
20class QMultiMap;
21class QString;
22
23namespace Syndication
24{
25class SpecificDocument;
26typedef QSharedPointer<SpecificDocument> SpecificDocumentPtr;
27class Category;
28typedef QSharedPointer<Category> CategoryPtr;
29class Feed;
30typedef QSharedPointer<Feed> FeedPtr;
31class Image;
32typedef QSharedPointer<Image> ImagePtr;
33class Item;
34typedef QSharedPointer<Item> ItemPtr;
35class Person;
36typedef QSharedPointer<Person> PersonPtr;
37
38/*!
39 * \class Syndication::Feed
40 * \inmodule Syndication
41 * \inheaderfile Syndication/Feed
42 *
43 * \brief This class represents a feed document ("Channel" in RSS, "Feed" in Atom).
44 *
45 * It contains a ordered list of items (e.g., articles) and a description of the
46 * feed (title, homepage, etc.). This interface abstracts from format-specific
47 * details of e.g. Atom::FeedDocument or RSS::Document and provides a
48 * format-agnostic, unified view on the document.
49 *
50 * This way applications using the syndication library have no need to care
51 * about the syndication format jungle at all. If necessary, format details and
52 * specialities can be accessed using the specificDocument() method.
53 */
54class SYNDICATION_EXPORT Feed
55{
56public:
57 virtual ~Feed();
58
59 /*!
60 * Returns the format-specific document this abstraction wraps.
61 *
62 * If you want to access format-specific properties, this can be used,
63 * in combination with a DocumentVisitor.
64 */
65 virtual SpecificDocumentPtr specificDocument() const = 0;
66
67 /*!
68 * A list of items, in the order they were parsed from the feed source.
69 * (usually reverse chronological order, see also Item::datePublished()
70 * for sorting purposes).
71 */
72 virtual QList<ItemPtr> items() const = 0;
73
74 /*!
75 * Returns a list of categories this feed is associated with.
76 * See Category for more information.
77 */
78 virtual QList<CategoryPtr> categories() const = 0;
79
80 /*!
81 * The title of the feed.
82 *
83 * This string may contain HTML markup.(Importantly, occurrences of
84 * the characters '<', '\n', '&', '\'' and '\"' are escaped).
85 *
86 * Returns the title, or a null string if none is specified
87 */
88 virtual QString title() const = 0;
89
90 /*!
91 * returns a link pointing to a website associated with this channel.
92 * (blog, news site etc.)
93 */
94 virtual QString link() const = 0;
95
96 /*!
97 * A description of the feed.
98 *
99 * This string may contain HTML markup.(Importantly, occurrences of
100 * the characters '<', '\n', '&', '\'' and '\"' are escaped).
101 */
102 virtual QString description() const = 0;
103
104 /*!
105 * Returns an image associated with this item, or a null image (Not a null pointer!
106 * I.e., image()->isNull() is \c true)
107 * if no image is specified in the feed
108 */
109 virtual ImagePtr image() const = 0;
110
111 /*!
112 * returns an icon associated with this item.
113 *
114 * Returns an icon object, or a null icon (Not a null pointer!
115 * I.e., icon()->isNull() is \c true)
116 * if no image is specified in the feed
117 *
118 */
119 virtual ImagePtr icon() const = 0;
120
121 /*!
122 * returns a list of persons who created the feed content. If there is a
123 * distinction between authors and contributors (Atom), both are added
124 * to the list, where authors are added first.
125 */
126 virtual QList<PersonPtr> authors() const = 0;
127
128 /*!
129 * The language used in the feed. This is a global setting, which can
130 * be overridden by the contained items.
131 *
132 * TODO: describe concrete format (language codes)
133 */
134 virtual QString language() const = 0;
135
136 /*!
137 * returns copyright information about the feed
138 */
139 virtual QString copyright() const = 0;
140
141 /*!
142 * returns a list of feed metadata not covered by this class.
143 * Can be used e.g. to access format extensions.
144 *
145 * The returned map contains key value pairs, where the key
146 * is the tag name of the element, namespace prefix are resolved
147 * to the corresponding URIs. The value is the XML element as read
148 * from the document.
149 *
150 * For example, to access the <itunes:subtitle> element, use
151 * additionalProperties()["http://www.itunes.com/dtds/podcast-1.0.dtdsubtitle"].
152 *
153 * Currently this is only
154 * supported for RSS 0.91..0.94/2.0 and Atom formats, but not for RDF
155 * (RSS 0.9 and 1.0).
156 */
157 virtual QMultiMap<QString, QDomElement> additionalProperties() const = 0;
158
159 /*!
160 * returns a description of the feed for debugging purposes
161 */
162 virtual QString debugInfo() const;
163};
164
165} // namespace Syndication
166
167#endif // SYNDICATION_FEED_H
168

source code of syndication/src/feed.h