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 |
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 ; |
29 | class ; |
30 | class ; |
31 | |
32 | /** |
33 | * An Item, representing an entry in an RSS feed. |
34 | * |
35 | * @author Frank Osterfeld |
36 | */ |
37 | class : public ElementWrapper, public Syndication::SpecificItem |
38 | { |
39 | public: |
40 | /** |
41 | * Default constructor, creates a null object, for which isNull() is |
42 | * @c true. |
43 | */ |
44 | explicit (QSharedPointer<Document> doc = QSharedPointer<Document>()); |
45 | |
46 | /** |
47 | * Creates an Item object wrapping an @c <item> XML element. |
48 | * |
49 | * @param element The @c <item> element to wrap |
50 | * @param doc the document this item is part of |
51 | */ |
52 | explicit (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 | (const Item &other); |
61 | |
62 | /** |
63 | * destructor |
64 | */ |
65 | () 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 &(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 (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 () 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 () 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 <br/> is used for newlines, "&", "<", ">" are escaped) |
106 | * summarizing the item. A null string if no description was specified. |
107 | */ |
108 | QString () 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 | * <br/> is used for newlines, "&", "<", ">" are escaped) |
118 | * If no content is specified, a null string is returned. |
119 | */ |
120 | QString () 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> () 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 () 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 <author> element. If |
143 | * @c <author> is not available, the method returns |
144 | * @c <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 () 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> () 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 () 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 () 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 <pubDate> element. If @c |
188 | * <pubDate> is not available, the method returns |
189 | * @c <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 () 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 () 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 () 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 () 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 () 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 () const; |
245 | |
246 | /** |
247 | * @internal |
248 | * returns the title content in unmodified form (no |
249 | * plaintext/HTML conversions etc.) |
250 | */ |
251 | QString () const; |
252 | //@endcond |
253 | |
254 | private: |
255 | class ; |
256 | QSharedPointer<ItemPrivate> ; |
257 | }; |
258 | |
259 | } // namespace RSS2 |
260 | } // namespace Syndication |
261 | |
262 | #endif // SYNDICATION_RSS2_ITEM_H |
263 | |