Syndication

atom/document.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2006 Frank Osterfeld <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef SYNDICATION_ATOM_DOCUMENT_H
9 #define SYNDICATION_ATOM_DOCUMENT_H
10 
11 #include <syndication/elementwrapper.h>
12 #include <syndication/specificdocument.h>
13 
14 #include <ctime>
15 
16 template<class T>
17 class QList;
18 
19 namespace Syndication
20 {
21 class DocumentVisitor;
22 
23 namespace Atom
24 {
25 class Category;
26 class Entry;
27 class EntryDocument;
28 class FeedDocument;
29 class Generator;
30 class Link;
31 class Person;
32 //@cond PRIVATE
33 typedef QSharedPointer<EntryDocument> EntryDocumentPtr;
34 typedef QSharedPointer<FeedDocument> FeedDocumentPtr;
35 //@endcond
36 
37 /**
38  * An Atom 1.0 Feed Document, containing metadata describing the
39  * feed and a number of entries.
40  *
41  * @author Frank Osterfeld
42  */
43 class SYNDICATION_EXPORT FeedDocument : public Syndication::SpecificDocument, public ElementWrapper
44 {
45 public:
46  /**
47  * default constructor, creates a null feed, which
48  * is invalid.
49  * @see isValid()
50  */
51  FeedDocument();
52 
53  /**
54  * creates a FeedDocument wrapping an atom:feed element.
55  * @param element a DOM element, should be a atom:feed document
56  * (although not enforced), otherwise this object will not parse
57  * anything useful
58  */
59  explicit FeedDocument(const QDomElement &element);
60 
61  /**
62  * Used by visitors for double dispatch. See DocumentVisitor
63  * for more information.
64  * @param visitor the visitor calling the method
65  */
66  bool accept(DocumentVisitor *visitor) override;
67 
68  /**
69  * a list of persons who are the authors of this feed.
70  * According to the Atom 1.0 spec, a feed must have an
71  * author unless all entries in it have one.
72  */
73  Q_REQUIRED_RESULT QList<Person> authors() const;
74 
75  /**
76  * a list of persons who contribute to this feed. (optional)
77  */
78  Q_REQUIRED_RESULT QList<Person> contributors() const;
79 
80  /**
81  * a list of categories this feed is assigned to (optional)
82  */
83  Q_REQUIRED_RESULT QList<Category> categories() const;
84 
85  /**
86  * URL of an image serving as a feed icon (optional)
87  *
88  * @return icon URL, or a null string if not specified in the feed.
89  */
90  Q_REQUIRED_RESULT QString icon() const;
91 
92  /**
93  * URL of an image serving as a feed logo (optional)
94  *
95  * @return image URL, or a null string if not specified in the feed.
96  */
97  Q_REQUIRED_RESULT QString logo() const;
98 
99  /**
100  * a string that unambiguously identifies the feed (required)
101  *
102  * @return the ID of the feed. As defined in the Atom spec it must be
103  * a valid URI (which is neither checked nor enforced by this parser)
104  *
105  */
106  Q_REQUIRED_RESULT QString id() const;
107 
108  /**
109  * copyright information (optional)
110  *
111  * @return copyright information for the feed (intended for human
112  * readers), or a null string if not specified
113  */
114  Q_REQUIRED_RESULT QString rights() const;
115 
116  /**
117  * feed title (required).
118  *
119  * @return title string as HTML.
120  */
121  Q_REQUIRED_RESULT QString title() const;
122 
123  /**
124  * description or subtitle of the feed (optional).
125  *
126  * @return subtitle string as HTML, or a null string
127  * if not specified in the feed.
128  */
129  Q_REQUIRED_RESULT QString subtitle() const;
130 
131  /**
132  * description of the agent used to generate the feed. See
133  * Generator for more information (optional).
134  *
135  * @return description of the generator, or a null Generator object
136  * if not specified in the feed.
137  */
138  Q_REQUIRED_RESULT Generator generator() const;
139 
140  /**
141  * The datetime of the last modification of the feed content.
142  *
143  * @return the modification date in seconds since epoch
144  */
145  Q_REQUIRED_RESULT time_t updated() const;
146 
147  /**
148  * a list of links. See Link for more information on
149  * link types.
150  */
151  Q_REQUIRED_RESULT QList<Link> links() const;
152 
153  /**
154  * a list of the entries (items) in this feed.
155  */
156  Q_REQUIRED_RESULT QList<Entry> entries() const;
157 
158  /**
159  * returns all child elements of this feed not covered by this class.
160  * This can be used to access additional metadata from Atom extensions.
161  */
162  Q_REQUIRED_RESULT QList<QDomElement> unhandledElements() const;
163 
164  /**
165  * returns a description of this feed document for debugging
166  * purposes.
167  *
168  * @return debug string
169  */
170  Q_REQUIRED_RESULT QString debugInfo() const override;
171 
172  /**
173  * returns whether this document is valid or not.
174  * Invalid documents do not contain any useful
175  * information.
176  */
177  Q_REQUIRED_RESULT bool isValid() const override;
178 };
179 
180 /**
181  * An Atom 1.0 Entry Document, containing a single Atom entry outside
182  * of the context of a feed.
183  *
184  * @author Frank Osterfeld
185  */
187 {
188 public:
189  /**
190  * default constructor, creates a null document, which is invalid.
191  * @see isValid()
192  */
193  EntryDocument();
194 
195  /**
196  * creates an Atom Entry Document wrapping an atom:entry element.
197  * @param element a DOM element, should be a atom:entry element
198  * (although not enforced), otherwise this object will not parse
199  * anything useful
200  */
201  explicit EntryDocument(const QDomElement &element);
202 
203  /**
204  * Used by visitors for double dispatch. See DocumentVisitor
205  * for more information.
206  * @param visitor the visitor calling the method
207  */
208  bool accept(DocumentVisitor *visitor) override;
209 
210  /**
211  * returns the single entry described in the source.
212  *
213  * @return the entry
214  */
215  Q_REQUIRED_RESULT Entry entry() const;
216 
217  /**
218  * returns a description of this entry document for debugging
219  * purposes.
220  *
221  * @return debug string
222  */
223  Q_REQUIRED_RESULT QString debugInfo() const override;
224 
225  /**
226  * returns whether this document is valid or not.
227  * Invalid documents do not contain any useful
228  * information.
229  */
230  Q_REQUIRED_RESULT bool isValid() const override;
231 };
232 
233 } // namespace Atom
234 } // namespace Syndication
235 
236 #endif // SYNDICATION_ATOM_DOCUMENT_H
Description of the agent used to generate the feed.
Definition: generator.h:25
A wrapper for XML elements.
An Atom 1.0 Feed Document, containing metadata describing the feed and a number of entries...
Definition: atom/document.h:43
an Atom entry, equivalent to the "items" in the RSS world.
Definition: entry.h:38
Visitor interface, following the Visitor design pattern.
Document interface for format-specific feed documents as parsed from a document source (see DocumentS...
An Atom 1.0 Entry Document, containing a single Atom entry outside of the context of a feed...
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Jan 20 2022 22:54:56 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.