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

source code of syndication/src/item.h