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 | |
15 | class QDomElement; |
16 | |
17 | template<class T> |
18 | class QList; |
19 | template<class K, class T> |
20 | class QMultiMap; |
21 | class QString; |
22 | |
23 | namespace Syndication |
24 | { |
25 | //@cond PRIVATE |
26 | class SpecificDocument; |
27 | typedef QSharedPointer<SpecificDocument> SpecificDocumentPtr; |
28 | class Category; |
29 | typedef QSharedPointer<Category> CategoryPtr; |
30 | class Feed; |
31 | typedef QSharedPointer<Feed> FeedPtr; |
32 | class Image; |
33 | typedef QSharedPointer<Image> ImagePtr; |
34 | class Item; |
35 | typedef QSharedPointer<Item> ItemPtr; |
36 | class Person; |
37 | typedef 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 | */ |
52 | class SYNDICATION_EXPORT Feed |
53 | { |
54 | public: |
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 <,'\n', '&', '\'' 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 <,'\n', '&', '\'' 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 <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 | |