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 | |
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 <,'\n', '&', '\'' 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 <,'\n', '&', '\'' 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 <,'\n', '&', '\'' 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 () 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 () 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 () 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 () 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 <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 | |