Syndication

item.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2006 Frank Osterfeld <[email protected]>
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 
18 class QDomElement;
19 template<class T>
20 class QList;
21 template<class K, class T>
22 class QMultiMap;
23 
24 namespace Syndication
25 {
26 //@cond PRIVATE
27 class Category;
28 typedef QSharedPointer<Category> CategoryPtr;
29 class Enclosure;
30 typedef QSharedPointer<Enclosure> EnclosurePtr;
31 class Item;
32 typedef QSharedPointer<Item> ItemPtr;
33 class Person;
34 typedef QSharedPointer<Person> PersonPtr;
35 class SpecificItem;
36 typedef QSharedPointer<SpecificItem> SpecificItemPtr;
37 //@endcond
38 
39 /**
40  * An item from a news feed.
41  *
42  * @author Frank Osterfeld
43  */
44 class SYNDICATION_EXPORT Item
45 {
46 public:
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
Definition: feed.h:20
An item from a news feed.
Definition: item.h:44
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:51:47 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.