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_ITEM_H |
24 | #define SYNDICATION_ITEM_H |
25 | |
26 | #include <QtCore/QString> |
27 | #include <boost/shared_ptr.hpp> |
28 | |
29 | #include "ksyndication_export.h" |
30 | |
31 | #include <ctime> |
32 | |
33 | class QDomElement; |
34 | template <class T> class QList; |
35 | template <class K, class T> class QMultiMap; |
36 | |
37 | namespace Syndication { |
38 | |
39 | //@cond PRIVATE |
40 | class Category; |
41 | typedef boost::shared_ptr<Category> CategoryPtr; |
42 | class Enclosure; |
43 | typedef boost::shared_ptr<Enclosure> EnclosurePtr; |
44 | class Item; |
45 | typedef boost::shared_ptr<Item> ItemPtr; |
46 | class Person; |
47 | typedef boost::shared_ptr<Person> PersonPtr; |
48 | class SpecificItem; |
49 | typedef boost::shared_ptr<SpecificItem> SpecificItemPtr; |
50 | //@endcond |
51 | |
52 | /** |
53 | * An item from a news feed. |
54 | * |
55 | * @author Frank Osterfeld |
56 | */ |
57 | class SYNDICATION_EXPORT Item |
58 | { |
59 | public: |
60 | |
61 | /** |
62 | * destructor |
63 | */ |
64 | virtual ~Item(); |
65 | |
66 | |
67 | /** |
68 | * returns the format-specific item this object abstracts from. |
69 | * Use it if you need to access format-specifics that are not covered |
70 | * by this abstraction. |
71 | * |
72 | */ |
73 | virtual SpecificItemPtr specificItem() const = 0; |
74 | |
75 | /** |
76 | * The title of the item. |
77 | * |
78 | * This string may contain HTML markup.(Importantly, occurrences of |
79 | * the characters <,'\n', '&', '\'' and '\"' are escaped). |
80 | * |
81 | * @return the title of the item as HTML, or a null string if not |
82 | * specified |
83 | */ |
84 | virtual QString title() const = 0; |
85 | |
86 | /** |
87 | * returns a link to the (web) resource described by this item. In most |
88 | * cases, this will be a website containing the full article associated |
89 | * with this item. |
90 | * |
91 | * @return a URL, or a null string if not specified |
92 | */ |
93 | virtual QString link() const = 0; |
94 | |
95 | /** |
96 | * returns the description of the item. The description can either be |
97 | * a tag line, a short summary of the item content up to a complete |
98 | * article. If content() is non-empty, it |
99 | * |
100 | * This string may contain HTML markup. (Importantly, occurrences of |
101 | * the characters <,'\n', '&', '\'' and '\"' are escaped). |
102 | * |
103 | * @return the description as HTML, or a null string if not specified |
104 | */ |
105 | virtual QString description() const = 0; |
106 | |
107 | /** |
108 | * returns the content of the item. If provided, this is the most |
109 | * comprehensive text content available for this item. If it is empty, |
110 | * use description() (which might also contain complete article |
111 | * content). |
112 | * |
113 | * This string may contain HTML markup. (Importantly, occurrences of |
114 | * the characters <,'\n', '&', '\'' and '\"' are escaped). |
115 | * |
116 | * @return content string as HTML, or a null string if not set |
117 | */ |
118 | virtual QString content() const = 0; |
119 | |
120 | /** |
121 | * returns the date when the item was initially published. |
122 | * |
123 | * @return publication date, as seconds since epoch (Jan 1st 1970), or 0 |
124 | * (epoch) if not set |
125 | */ |
126 | virtual time_t datePublished() const = 0; |
127 | |
128 | /** |
129 | * returns the date when the item was modified the last time. If no such |
130 | * date is provided by the feed, this method returns the value of |
131 | * datePublished(). |
132 | * |
133 | * @return modification date, as seconds since epoch (Jan 1st 1970) |
134 | */ |
135 | virtual time_t dateUpdated() const = 0; |
136 | |
137 | /** |
138 | * returns an identifier that identifies the item within its |
139 | * feed. The ID must be unique within its feed. If no ID is provided |
140 | * by the feed source, a hash from title, description and content is |
141 | * returned. |
142 | * Generated hash IDs start with "hash:". |
143 | */ |
144 | virtual QString id() const = 0; |
145 | |
146 | /** |
147 | * returns a list of persons who created the item content. If there is a |
148 | * distinction between authors and contributors (Atom), both are added |
149 | * to the list, where authors are added first. |
150 | * |
151 | * @return list of authors (and possibly other contributing persons) |
152 | */ |
153 | virtual QList<PersonPtr> authors() const = 0; |
154 | |
155 | /** |
156 | * returns the language used in the item's content |
157 | * |
158 | * @return TODO: tell about language codes and link them |
159 | */ |
160 | virtual QString language() const = 0; |
161 | |
162 | /** |
163 | * returns a list of enclosures describing files available on the net. |
164 | * (often used for audio files, so-called "Podcasts"). |
165 | * |
166 | * @return a list of enclosures associated with this item |
167 | */ |
168 | virtual QList<EnclosurePtr> enclosures() const = 0; |
169 | |
170 | /** |
171 | * returns a list of categories this item is filed in. |
172 | * See Category for more information on categories. |
173 | * |
174 | * @return a list of categories |
175 | */ |
176 | virtual QList<CategoryPtr> categories() const = 0; |
177 | |
178 | /** |
179 | * The number of comments posted for this item. |
180 | * |
181 | * @return the number of comments associated to this item, or -1 if not |
182 | * specified |
183 | */ |
184 | virtual int () const = 0; |
185 | |
186 | /** |
187 | * Link to an HTML site which contains the comments belonging to |
188 | * this item. |
189 | * |
190 | * @return URL to the comments page, or a null string if not set |
191 | */ |
192 | virtual QString () const = 0; |
193 | |
194 | /** |
195 | * URL of feed syndicating comments belonging to this item. |
196 | * |
197 | * @return comments feed URL, or a null string if not set |
198 | */ |
199 | virtual QString () const = 0; |
200 | |
201 | /** |
202 | * URI that can be used to post comments via an HTTP POST request using |
203 | * the Comment API. |
204 | * For more details on the Comment API, see |
205 | * http://wellformedweb.org/story/9 |
206 | * |
207 | * @return URI for posting comments, or a null string if not set |
208 | */ |
209 | virtual QString () const = 0; |
210 | |
211 | /** |
212 | * returns a list of item metadata not covered by this class. |
213 | * Can be used e.g. to access format extensions. |
214 | * |
215 | * The returned map contains key value pairs, where the key |
216 | * is the tag name of the element, namespace prefix are resolved |
217 | * to the corresponding URIs. The value is the XML element as read |
218 | * from the document. |
219 | * |
220 | * For example, to access the <itunes:keywords> element, use |
221 | * additionalProperties()["http://www.itunes.com/dtds/podcast-1.0.dtdkeywords"]. |
222 | * |
223 | * Currently this is only |
224 | * supported for RSS 0.91..0.94/2.0 and Atom formats, but not for RDF |
225 | * (RSS 0.9 and 1.0). |
226 | */ |
227 | virtual QMultiMap<QString, QDomElement> additionalProperties() const = 0; |
228 | |
229 | /** |
230 | * returns a description of the item for debugging purposes |
231 | * |
232 | * @return debug string |
233 | */ |
234 | virtual QString debugInfo() const; |
235 | }; |
236 | |
237 | } // namespace Syndication |
238 | |
239 | #endif // SYNDICATION_ITEM_H |
240 | |