Syndication

feed.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2006 Frank Osterfeld <[email protected]>
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 &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
This class represents a feed document ("Channel" in RSS, "Feed" in Atom).
Definition: feed.h:52
Definition: feed.h:20
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Jan 27 2022 22:54:56 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.