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
33class QDomElement;
34template <class T> class QList;
35template <class K, class T> class QMultiMap;
36
37namespace Syndication {
38
39//@cond PRIVATE
40class Category;
41typedef boost::shared_ptr<Category> CategoryPtr;
42class Enclosure;
43typedef boost::shared_ptr<Enclosure> EnclosurePtr;
44class Item;
45typedef boost::shared_ptr<Item> ItemPtr;
46class Person;
47typedef boost::shared_ptr<Person> PersonPtr;
48class SpecificItem;
49typedef boost::shared_ptr<SpecificItem> SpecificItemPtr;
50//@endcond
51
52/**
53 * An item from a news feed.
54 *
55 * @author Frank Osterfeld
56 */
57class 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 &lt;,'\n', '&amp;', '\'' 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 &lt;,'\n', '&amp;', '\'' 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 &lt;,'\n', '&amp;', '\'' 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 commentsCount() 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 commentsLink() 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 commentsFeed() 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 commentPostUri() 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 &lt;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