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

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