Syndication

atom/document.h
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;
32//@cond PRIVATE
33typedef QSharedPointer<EntryDocument> EntryDocumentPtr;
34typedef 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 */
43class SYNDICATION_EXPORT FeedDocument : public Syndication::SpecificDocument, public ElementWrapper
44{
45public:
46 /**
47 * default constructor, creates a null feed, which
48 * is invalid.
49 * @see isValid()
50 */
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 */
186class SYNDICATION_EXPORT EntryDocument : public Syndication::SpecificDocument, public Syndication::ElementWrapper
187{
188public:
189 /**
190 * default constructor, creates a null document, which is invalid.
191 * @see isValid()
192 */
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
An Atom 1.0 Entry Document, containing a single Atom entry outside of the context of a feed.
an Atom entry, equivalent to the "items" in the RSS world.
Definition entry.h:39
An Atom 1.0 Feed Document, containing metadata describing the feed and a number of entries.
Description of the agent used to generate the feed.
Definition generator.h:26
Visitor interface, following the Visitor design pattern.
Document interface for format-specific feed documents as parsed from a document source (see DocumentS...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 21 2024 11:56:25 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.