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