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 | |
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 | */ |
186 | class SYNDICATION_EXPORT EntryDocument : public Syndication::SpecificDocument, public Syndication::ElementWrapper |
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 |
237 | |