Syndication

rss2/item.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2005 Frank Osterfeld <[email protected]>
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 
17 class QDomElement;
18 class QString;
19 template<class T>
20 class QList;
21 
22 namespace Syndication
23 {
24 class SpecificItemVisitor;
25 
26 namespace RSS2
27 {
28 class Category;
29 class Enclosure;
30 class Source;
31 
32 /**
33  * An Item, representing an entry in an RSS feed.
34  *
35  * @author Frank Osterfeld
36  */
37 class SYNDICATION_EXPORT Item : public ElementWrapper, public Syndication::SpecificItem
38 {
39 public:
40  /**
41  * Default constructor, creates a null object, for which isNull() is
42  * @c true.
43  */
45 
46  /**
47  * Creates an Item object wrapping an @c &lt;item> XML element.
48  *
49  * @param element The @c &lt;item> element to wrap
50  * @param 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  * @param 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  * @param 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  * @param 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 
254 private:
255  class ItemPrivate;
257 };
258 
259 } // namespace RSS2
260 } // namespace Syndication
261 
262 #endif // SYNDICATION_RSS2_ITEM_H
Interface for all format-specific item-like classes, such as RSS2/RDF items, and Atom entries.
Definition: specificitem.h:31
KIOCORE_EXPORT CopyJob * link(const QList< QUrl > &src, const QUrl &destDir, JobFlags flags=DefaultFlags)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:57:11 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.