Syndication

rss2/document.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2005 Frank Osterfeld <[email protected]>
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 
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 Category;
30 class Cloud;
31 class Document;
32 class Image;
33 class Item;
34 class TextInput;
35 typedef 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  */
43 class SYNDICATION_EXPORT Document : 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 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  * @param 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  * @param 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 
241  Monday = 0, /**< self-explanatory */
242  Tuesday = 1, /**< self-explanatory */
243  Wednesday = 2, /**< self-explanatory */
244  Thursday = 3, /**< self-explanatory */
245  Friday = 4, /**< self-explanatory */
246  Saturday = 5, /**< self-explanatory */
247  Sunday = 6, /**< self-explanatory */
248  };
249 
250  /**
251  * A set of week days where aggregators shouldn't read the channel.
252  *
253  */
254  QSet<DayOfWeek> skipDays() 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 debugInfo() 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 getItemTitleFormatInfo(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 getItemDescriptionFormatInfo(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 Document(const QDomElement &element);
297 
298  class DocumentPrivate;
300 };
301 
302 } // namespace RSS2
303 } // namespace Syndication
304 
305 #endif // SYNDICATION_RSS2_DOCUMENT_H
Cloud information for an RSS channel.
Definition: cloud.h:45
A wrapper for XML elements.
"The purpose of the <textInput> element is something of a mystery.
Visitor interface, following the Visitor design pattern.
Document interface for format-specific feed documents as parsed from a document source (see DocumentS...
document implementation, representing an RSS feed from the 0.91-0.94/2.0 family.
Definition: rss2/document.h:43
DayOfWeek
days of week, used for skip days
An RSS2 image, used to describe feed logos.
Definition: rss2/image.h:23
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue May 17 2022 03:54:41 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.