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

source code of syndication/src/feed.h