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 SYNDICATION_RSS2_DOCUMENT_H
10
11#include <syndication/elementwrapper.h>
12#include <syndication/specificdocument.h>
13
14#include <ctime>
15
16class QDomDocument;
17class QDomElement;
18class QString;
19
20template<class T>
21class QList;
22template<class T>
23class QSet;
24
25namespace Syndication
26{
27namespace RSS2
28{
29class Category;
30class Cloud;
31class Document;
32class Image;
33class Item;
34class TextInput;
35typedef QSharedPointer<Document> DocumentPtr;
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 */
43class Document : public Syndication::SpecificDocument, public Syndication::ElementWrapper
44{
45public:
46 /*!
47 * Parses an RSS2 document from an XML document.
48 * TODO: More on supported formats etc.
49 *
50 * \a 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 fromXML(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 Document();
61
62 /*!
63 * copy constructor
64 */
65 Document(const Document &other);
66
67 /*!
68 * destructor
69 */
70 ~Document() override;
71
72 /*!
73 * assigns another document. As the d pointer is shared,
74 * this is a cheap operation.
75 *
76 * \a other the document to assign
77 */
78 Document &operator=(const Document &other);
79
80 /*!
81 * Used by visitors for double dispatch. See DocumentVisitor
82 * for more information.
83 * \a visitor the visitor calling the method
84 */
85 bool accept(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 isValid() const override;
93
94 /*!
95 * The title of the channel.
96 *
97 * @return title TODO: more on escaping/HTML
98 */
99 QString title() const;
100
101 /*!
102 * The URL to the HTML website corresponding to the channel.
103 *
104 * @return TODO
105 */
106 QString link() const;
107
108 /*!
109 * Phrase or sentence describing the channel.
110 *
111 * @return TODO
112 */
113 QString description() const;
114
115 /*!
116 * the items contained in this document
117 */
118 QList<Item> items() const;
119
120 /*!
121 *
122 * @return TODO
123 */
124 QString language() const;
125
126 /*!
127 *
128 * Copyright notice for content in the channel.
129 * This method returns the content of the @c &lt;copyright>
130 * element. If @c &lt;copyright> is not available, the method returns
131 * @c &lt;dc:rights> instead, if available.
132 *
133 * @return copyright information, or a null string if not set
134 */
135 QString copyright() 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 managingEditor() 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 webMaster() 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 &lt;pubDate> element. If
158 * @c &lt;pubDate> is not available, the method returns
159 * @c &lt;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 pubDate() 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 lastBuildDate() const;
173
174 /*!
175 * Specifies one or more categories that the channel belongs to.
176 *
177 * @return TODO
178 */
179 QList<Category> categories() 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 generator() 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 docs() 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 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 ttl() 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 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 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> skipHours() const;
237
238 /*! days of week, used for skip days */
239 enum DayOfWeek {
240 Monday = 0, /*!< self-explanatory */
241 Tuesday = 1, /*!< self-explanatory */
242 Wednesday = 2, /*!< self-explanatory */
243 Thursday = 3, /*!< self-explanatory */
244 Friday = 4, /*!< self-explanatory */
245 Saturday = 5, /*!< self-explanatory */
246 Sunday = 6, /*!< self-explanatory */
247 };
248
249 /*!
250 * A set of week days where aggregators shouldn't read the channel.
251 *
252 */
253 QSet<DayOfWeek> skipDays() const;
254
255 /*!
256 * returns all child elements of this document not covered by this class.
257 * You can use this to access additional metadata from RSS extensions.
258 */
259 QList<QDomElement> unhandledElements() const;
260
261 /*!
262 * Returns a description of the object and its children for
263 * debugging purposes.
264 *
265 * @return debug string
266 */
267 QString debugInfo() const override;
268
269 //@cond PRIVATE
270 /*!
271 * @internal
272 * checks the format of title elements and returns the results
273 * \a isCDATA whether the titles are encapsulated in CDATA
274 * \a containsMarkup whether the heuristic found HTML markup in
275 * titles
276 */
277 void getItemTitleFormatInfo(bool *isCDATA, bool *containsMarkup) const;
278
279 /*!
280 * @internal
281 * checks the format of title elements and returns the results
282 * \a isCDATA whether the descriptions are encapsulated in CDATA
283 * \a containsMarkup whether the heuristic found HTML markup in
284 * descriptions
285 */
286 void getItemDescriptionFormatInfo(bool *isCDATA, bool *containsMarkup) const;
287 //@endcond
288
289private:
290 /*!
291 * @internal
292 * private constructor, used by fromXML()
293 * TODO: remove fromXML(), make this one private
294 */
295 explicit Document(const QDomElement &element);
296
297 class DocumentPrivate;
298 QSharedPointer<DocumentPrivate> d;
299};
300
301} // namespace RSS2
302} // namespace Syndication
303
304#endif // SYNDICATION_RSS2_DOCUMENT_H
305

source code of syndication/src/rss2/document.h