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_DOCUMENT_H |
9 | #define |
10 | |
11 | #include <syndication/elementwrapper.h> |
12 | #include <syndication/specificdocument.h> |
13 | |
14 | #include <ctime> |
15 | |
16 | class QDomDocument; |
17 | class QDomElement; |
18 | class QString; |
19 | |
20 | template<class T> |
21 | class QList; |
22 | template<class T> |
23 | class QSet; |
24 | |
25 | namespace Syndication |
26 | { |
27 | namespace RSS2 |
28 | { |
29 | class ; |
30 | class ; |
31 | class Document; |
32 | class ; |
33 | class ; |
34 | class ; |
35 | typedef QSharedPointer<Document> ; |
36 | |
37 | /** |
38 | * document implementation, representing an RSS feed from the 0.91-0.94/2.0 |
39 | * family. |
40 | * |
41 | * @author Frank Osterfeld |
42 | */ |
43 | class : public Syndication::SpecificDocument, public Syndication::ElementWrapper |
44 | { |
45 | public: |
46 | /** |
47 | * Parses an RSS2 document from an XML document. |
48 | * TODO: More on supported formats etc. |
49 | * |
50 | * @param document The dom document to parse the document from |
51 | * @return the document parsed from XML, or an invalid |
52 | * document if parsing failed. |
53 | */ |
54 | static Document (const QDomDocument &document); |
55 | |
56 | /** |
57 | * Default constructor, creates a null object, for which |
58 | * isNull() is @c true and isValid() is @c false. |
59 | */ |
60 | (); |
61 | |
62 | /** |
63 | * copy constructor |
64 | */ |
65 | (const Document &other); |
66 | |
67 | /** |
68 | * destructor |
69 | */ |
70 | () override; |
71 | |
72 | /** |
73 | * assigns another document. As the d pointer is shared, |
74 | * this is a cheap operation. |
75 | * |
76 | * @param other the document to assign |
77 | */ |
78 | Document &(const Document &other); |
79 | |
80 | /** |
81 | * Used by visitors for double dispatch. See DocumentVisitor |
82 | * for more information. |
83 | * @param visitor the visitor calling the method |
84 | */ |
85 | bool (DocumentVisitor *visitor) override; |
86 | |
87 | /** |
88 | * returns whether this document is valid or not. |
89 | * Invalid documents do not contain any useful |
90 | * information. |
91 | */ |
92 | bool () const override; |
93 | |
94 | /** |
95 | * The title of the channel. |
96 | * |
97 | * @return title TODO: more on escaping/HTML |
98 | */ |
99 | QString () const; |
100 | |
101 | /** |
102 | * The URL to the HTML website corresponding to the channel. |
103 | * |
104 | * @return TODO |
105 | */ |
106 | QString () const; |
107 | |
108 | /** |
109 | * Phrase or sentence describing the channel. |
110 | * |
111 | * @return TODO |
112 | */ |
113 | QString () const; |
114 | |
115 | /** |
116 | * the items contained in this document |
117 | */ |
118 | QList<Item> () const; |
119 | |
120 | /** |
121 | * |
122 | * @return TODO |
123 | */ |
124 | QString () const; |
125 | |
126 | /** |
127 | * |
128 | * Copyright notice for content in the channel. |
129 | * This method returns the content of the @c <copyright> |
130 | * element. If @c <copyright> is not available, the method returns |
131 | * @c <dc:rights> instead, if available. |
132 | * |
133 | * @return copyright information, or a null string if not set |
134 | */ |
135 | QString () const; |
136 | |
137 | /** |
138 | * Email address for person responsible for editorial content. |
139 | * |
140 | * @return editor's email address, or a null string if not set |
141 | */ |
142 | QString () const; |
143 | |
144 | /** |
145 | * Email address for person responsible for technical issues relating |
146 | * to channel. |
147 | * |
148 | * @return web master's email address, or a null string if not |
149 | */ |
150 | QString () const; |
151 | |
152 | /** |
153 | * The publication date for the content in the channel. For example, |
154 | * the New York Times publishes on a daily basis, the publication date |
155 | * flips once every 24 hours. That's when the pubDate of the channel |
156 | * changes. |
157 | * This method returns the content of the @c <pubDate> element. If |
158 | * @c <pubDate> is not available, the method returns |
159 | * @c <dc:date> instead, if available. |
160 | * |
161 | * @return the publication date, or 0 if no date was specified or |
162 | * parsing failed |
163 | */ |
164 | time_t () const; |
165 | |
166 | /** |
167 | * The last time the content of the channel changed. |
168 | * |
169 | * @return the last build date, or 0 if no date was specified or parsing |
170 | * failed |
171 | */ |
172 | time_t () const; |
173 | |
174 | /** |
175 | * Specifies one or more categories that the channel belongs to. |
176 | * |
177 | * @return TODO |
178 | */ |
179 | QList<Category> () const; |
180 | |
181 | /** |
182 | * A string indicating the program used to generate the channel. |
183 | * |
184 | * @return description of the generator program, or a null string if |
185 | * not set |
186 | */ |
187 | QString () const; |
188 | |
189 | /** |
190 | * A URL that points to the documentation for the format used in the |
191 | * RSS file. It's probably a pointer to the RSS specification. |
192 | * It's for people who might stumble across an RSS file on a Web server |
193 | * 25 years from now and wonder what it is. |
194 | * |
195 | * @return URL pointing to the format specification, or a null string if |
196 | * not set |
197 | */ |
198 | QString () const; |
199 | |
200 | /** |
201 | * Allows processes to register with a cloud to be notified of updates |
202 | * to the channel, implementing a lightweight publish-subscribe |
203 | * protocol for RSS feeds. |
204 | * |
205 | * @return cloud information, or a null object if not set |
206 | */ |
207 | Cloud () const; |
208 | |
209 | /** |
210 | * ttl stands for time to live. It's a number of minutes that indicates |
211 | * how long a channel can be cached before refreshing from the source. |
212 | * |
213 | * @return the "time to live" in minutes, or 0 if not set |
214 | */ |
215 | int () const; |
216 | |
217 | /** |
218 | * Specifies a GIF, JPEG or PNG image that can be displayed with the |
219 | * channel. |
220 | * |
221 | * @return the image, or a null object if not set |
222 | */ |
223 | Image () const; |
224 | |
225 | /** |
226 | * Specifies a text input box that can be displayed with the channel. |
227 | * |
228 | * @return the text input, or a null object if not set |
229 | */ |
230 | TextInput () const; |
231 | |
232 | /** |
233 | * Contains a set of hours (from 0 to 23), time in GMT, when the |
234 | * channel is not updated. |
235 | */ |
236 | QSet<int> () const; |
237 | |
238 | /** days of week, used for skip days */ |
239 | enum { |
240 | |
241 | = 0, /**< self-explanatory */ |
242 | = 1, /**< self-explanatory */ |
243 | = 2, /**< self-explanatory */ |
244 | = 3, /**< self-explanatory */ |
245 | = 4, /**< self-explanatory */ |
246 | = 5, /**< self-explanatory */ |
247 | = 6, /**< self-explanatory */ |
248 | }; |
249 | |
250 | /** |
251 | * A set of week days where aggregators shouldn't read the channel. |
252 | * |
253 | */ |
254 | QSet<DayOfWeek> () const; |
255 | |
256 | /** |
257 | * returns all child elements of this document not covered by this class. |
258 | * You can use this to access additional metadata from RSS extensions. |
259 | */ |
260 | QList<QDomElement> unhandledElements() const; |
261 | |
262 | /** |
263 | * Returns a description of the object and its children for |
264 | * debugging purposes. |
265 | * |
266 | * @return debug string |
267 | */ |
268 | QString () const override; |
269 | |
270 | //@cond PRIVATE |
271 | /** |
272 | * @internal |
273 | * checks the format of title elements and returns the results |
274 | * @param isCDATA whether the titles are encapsulated in CDATA |
275 | * @param containsMarkup whether the heuristic found HTML markup in |
276 | * titles |
277 | */ |
278 | void (bool *isCDATA, bool *containsMarkup) const; |
279 | |
280 | /** |
281 | * @internal |
282 | * checks the format of title elements and returns the results |
283 | * @param isCDATA whether the descriptions are encapsulated in CDATA |
284 | * @param containsMarkup whether the heuristic found HTML markup in |
285 | * descriptions |
286 | */ |
287 | void (bool *isCDATA, bool *containsMarkup) const; |
288 | //@endcond |
289 | |
290 | private: |
291 | /** |
292 | * @internal |
293 | * private constructor, used by fromXML() |
294 | * TODO: remove fromXML(), make this one private |
295 | */ |
296 | explicit (const QDomElement &element); |
297 | |
298 | class ; |
299 | QSharedPointer<DocumentPrivate> ; |
300 | }; |
301 | |
302 | } // namespace RSS2 |
303 | } // namespace Syndication |
304 | |
305 | #endif // SYNDICATION_RSS2_DOCUMENT_H |
306 | |