1/*
2 This file is part of the syndication library
3 SPDX-FileCopyrightText: 2005 Frank Osterfeld <osterfeld@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef SYNDICATION_RSS2_ITEM_H
9#define SYNDICATION_RSS2_ITEM_H
10
11#include <syndication/elementwrapper.h>
12#include <syndication/rss2/document.h>
13#include <syndication/specificitem.h>
14
15#include <ctime>
16
17class QDomElement;
18class QString;
19template<class T>
20class QList;
21
22namespace Syndication
23{
24class SpecificItemVisitor;
25
26namespace RSS2
27{
28class Category;
29class Enclosure;
30class Source;
31
32/*!
33 * An Item, representing an entry in an RSS feed.
34 *
35 * @author Frank Osterfeld
36 */
37class Item : public ElementWrapper, public Syndication::SpecificItem
38{
39public:
40 /*!
41 * Default constructor, creates a null object, for which isNull() is
42 * @c true.
43 */
44 explicit Item(QSharedPointer<Document> doc = QSharedPointer<Document>());
45
46 /*!
47 * Creates an Item object wrapping an @c &lt;item> XML element.
48 *
49 * \a element The @c &lt;item> element to wrap
50 * \a doc the document this item is part of
51 */
52 explicit Item(const QDomElement &element, QSharedPointer<Document> doc = QSharedPointer<Document>());
53
54 /*!
55 * creates a copy of an item. As the d pointer is shared,
56 * this is a cheap operation.
57 *
58 * \a other the item to copy
59 */
60 Item(const Item &other);
61
62 /*!
63 * destructor
64 */
65 ~Item() override;
66
67 /*!
68 * assigns another item. As the d pointer is shared,
69 * this is a cheap operation.
70 *
71 * \a other the item to assign
72 */
73 Item &operator=(const Item &other);
74
75 /*!
76 * Used by visitors for double dispatch. See SpecificItemVisitor
77 * for more information.
78 * \a visitor the visitor calling the method
79 */
80 bool accept(SpecificItemVisitor *visitor) override;
81
82 /*!
83 * The title of the item.
84 *
85 * @return The title in plain text. Note that e.g. characters like <,
86 * >, & are not escaped!
87 * (TODO: this might change, check what makes more sense)
88 */
89 QString title() const;
90
91 /*!
92 * The URL of the item. This usually links to the web representation
93 * of the item, e.g. the full news article.
94 *
95 * @return an URL, or a null string if not set
96 */
97 QString link() const;
98
99 /*!
100 * The item synopsis. This might contain a short summary of the
101 * item, but also the full content. If content() is set, that usually
102 * contains the full content instead.
103 *
104 * @return a string in HTML format (whitespace is irrelevant,
105 * @c &lt;br/> is used for newlines, "&", "&lt;", "&gt;" are escaped)
106 * summarizing the item. A null string if no description was specified.
107 */
108 QString description() const;
109
110 /*!
111 * Returns the actual content of the item. In RSS2, this can be stored
112 * in various elements, e.g. in content:encoded, xhtml:body or
113 * xhtml:div. If this is not set, description() might also contain the
114 * content of the item.
115 *
116 * @return the content in HTML format (whitespace is irrelevant,
117 * &lt;br/> is used for newlines, "&", "&lt;", "&gt;" are escaped)
118 * If no content is specified, a null string is returned.
119 */
120 QString content() const;
121
122 /*!
123 * Set of categories this item is included in.
124 *
125 * @return a list of categories, possibly empty.
126 */
127 QList<Category> categories() const;
128
129 /*!
130 * URL of a page for comments relating to the item.
131 *
132 * @return an URL to the comments, or a null string if not set
133 */
134 QString comments() const;
135
136 /*!
137 * The email address of the author of this item. For newspapers and
138 * magazines syndicating via RSS, the author is the person who wrote
139 * the article that this item describes. For collaborative weblogs, the
140 * author of the item might be different from the managing editor or
141 * webmaster.
142 * This method returns the content of the @c &lt;author> element. If
143 * @c &lt;author> is not available, the method returns
144 * @c &lt;dc:creator> instead, if available.
145 *
146 * @return an email address of the author, or a null string if not
147 * specified
148 */
149 QString author() const;
150
151 /*!
152 * Descriptions of media objects that are attached to the item.
153 * Note that the RSS2 spec is a bit unclear about whether an item can
154 * have multiple enclosures or not. Originally it was not intended, but
155 * in reality, some tools out there specify multiple enclosures.
156 * So most of the time, this list be either empty or contains a
157 * single item, but don't take that for granted
158 */
159 QList<Enclosure> enclosures() const;
160
161 /*!
162 * "guid stands for globally unique identifier. It's a string that
163 * uniquely identifies the item. When present, an aggregator may choose
164 * to use this string to determine if an item is new.
165 * There are no rules for the syntax of a guid. Aggregators must view
166 * them as a string. It's up to the source of the feed to establish the
167 * uniqueness of the string."
168 *
169 * @return a guid string, or a null string if none specified in the
170 * feed
171 */
172 QString guid() const;
173
174 /*!
175 * If @c true, it can be assumed that the guid is a permalink to the
176 * item, that is, a url that can be opened in a Web browser, that
177 * points to the full item.
178 *
179 * @return @c true if the guid is a permalink and can be interpreted as
180 * URL
181 */
182 bool guidIsPermaLink() const;
183
184 /*!
185 * Indicates when the item was published. If it's a date in the future,
186 * you may choose to not display the item until that date.
187 * This returns the content of the @c &lt;pubDate> element. If @c
188 * &lt;pubDate> is not available, the method returns
189 * @c &lt;dc:date> instead, if available.
190 *
191 * @return the publication date, or 0 if no date was specified or
192 * parsing failed
193 */
194 time_t pubDate() const;
195
196 /*!
197 * expiration date, specifying a date when the item is not longer
198 * available.
199 * Only available in RSS 0.93.
200 *
201 * @return the expiration date, or 0 if no date was specified or
202 * parsing failed
203 */
204 time_t expirationDate() const;
205
206 /*!
207 * A Platform for Internet Content Selection (PICS) rating tag.
208 * More information on the format of the rating tag can be found here:
209 * http://www.w3.org/PICS/
210 *
211 * @return PICS rating information, or a null string if not specified
212 */
213 QString rating() const;
214
215 /*!
216 * The RSS channel that the item came from. See Source class for more
217 * information.
218 *
219 * @return a Source object, or a null object (see Source.isNull()) if
220 * not set.
221 */
222 Source source() const;
223
224 /*!
225 * returns all child elements of this item not covered by this class.
226 * You can use this to access additional metadata from RSS extensions.
227 */
228 QList<QDomElement> unhandledElements() const;
229
230 /*!
231 * Returns a description of the object and its children for debugging
232 * purposes.
233 *
234 * @return debug string
235 */
236 QString debugInfo() const;
237
238 //@cond PRIVATE
239 /*!
240 * @internal
241 * returns the description content in unmodified form (no
242 * plaintext/HTML conversions etc.)
243 */
244 QString originalDescription() const;
245
246 /*!
247 * @internal
248 * returns the title content in unmodified form (no
249 * plaintext/HTML conversions etc.)
250 */
251 QString originalTitle() const;
252 //@endcond
253
254private:
255 class ItemPrivate;
256 QSharedPointer<ItemPrivate> d;
257};
258
259} // namespace RSS2
260} // namespace Syndication
261
262#endif // SYNDICATION_RSS2_ITEM_H
263

source code of syndication/src/rss2/item.h