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_ENTRY_H
9#define SYNDICATION_ATOM_ENTRY_H
10
11#include <syndication/elementwrapper.h>
12#include <syndication/specificitem.h>
13
14#include <QList>
15
16#include <ctime>
17
18class QDomElement;
19class QString;
20
21namespace Syndication
22{
23class SpecificItemVisitor;
24
25namespace Atom
26{
27class Category;
28class Content;
29class Link;
30class Person;
31class Source;
32
33/*!
34 * \class Syndication::Atom::Entry
35 * \inmodule Syndication
36 * \inheaderfile Syndication/Atom/Entry
37 *
38 * \brief An Atom entry, equivalent to the "items" in the RSS world.
39 */
40class SYNDICATION_EXPORT Entry : public ElementWrapper, public SpecificItem
41{
42public:
43 /*!
44 * creates a null entry object
45 */
46 Entry();
47
48 /*!
49 * creates an Entry object wrapping an atom:entry element.
50 *
51 * \a element a DOM element, should be a atom:entry element
52 * (although not enforced), otherwise this object will not parse
53 * anything useful
54 */
55 explicit Entry(const QDomElement &element);
56
57 /*!
58 * Used by visitors for double dispatch. See SpecificVisitor
59 * for more information.
60 *
61 * \a visitor the visitor calling the method
62 */
63 bool accept(SpecificItemVisitor *visitor) override;
64
65 /*!
66 * list of persons who are authors of this entry. (required)
67 *
68 * If the entry itself does not have explicit author description,
69 * its source author description is used. If none of these exist,
70 * the list of authors of the containing feed is used. That list
71 * is set by setFeedAuthors().
72 */
73 Q_REQUIRED_RESULT QList<Person> authors() const;
74
75 /*!
76 * a list of categories this entry is filed to (optional)
77 */
78 Q_REQUIRED_RESULT QList<Category> categories() const;
79
80 /*!
81 * list of persons contributing to this entry (optional)
82 */
83 Q_REQUIRED_RESULT QList<Person> contributors() const;
84
85 /*!
86 * ID of the article. (required)
87 * The ID must be unique inside this feed. The atom spec defines it as a
88 * URI (which is not enforced by this parser)
89 */
90 Q_REQUIRED_RESULT QString id() const;
91
92 /*!
93 * links pointing to associated web sites and other resources.
94 *
95 * Links are optional if the entry provides Content.
96 * Otherwise, it must contain at least one link with
97 * a \c rel value of \c "alternate". (see Link).
98 */
99 Q_REQUIRED_RESULT QList<Link> links() const;
100
101 /*!
102 * copyright information (optional)
103 *
104 * Returns copyright information for the entry (intended for human
105 * readers), or a null string if not specified
106 */
107 Q_REQUIRED_RESULT QString rights() const;
108
109 /*!
110 * source description of the content (optional)
111 *
112 * If the content was copied from another feed, this object contains
113 * information about the source feed.
114 *
115 * Returns source description, or a null object if not
116 * specified
117 */
118 Q_REQUIRED_RESULT Source source() const;
119
120 /*!
121 * The datetime of the publication of this entry (optional).
122 *
123 * Returns the publication date in seconds since epoch
124 */
125 Q_REQUIRED_RESULT time_t published() const;
126
127 /*!
128 * The datetime of the last modification of this entry (required).
129 *
130 * Returns the modification date in seconds since epoch
131 */
132 Q_REQUIRED_RESULT time_t updated() const;
133
134 /*!
135 * a short summary, abstract or excerpt of an entry. (optional)
136 * This is usually more verbose than title() and but does not
137 * contain the whole content as content() does.
138 *
139 * Returns the summary as HTML, or a null string if not specified
140 */
141 Q_REQUIRED_RESULT QString summary() const;
142
143 /*!
144 * title of the entry (required).
145 *
146 * Returns the title as HTML
147 */
148 Q_REQUIRED_RESULT QString title() const;
149
150 /*!
151 * content of the entry (optional)
152 * See Content for details
153 *
154 * Returns entry content, or a null content object if not specified
155 */
156 Q_REQUIRED_RESULT Content content() const;
157
158 /*!
159 * returns all child elements of this entry 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 * Sets the list of the containing feed's authors, which will be used
166 * as a fallback in authors() in case both the entry itself and its
167 * source have no explicit author description.
168 *
169 * \a feedAuthors the list of feed's authors
170 */
171 void setFeedAuthors(const QList<Person> &feedAuthors);
172
173 /*!
174 * returns a description of this entry for debugging purposes
175 *
176 * Returns debug string
177 */
178 Q_REQUIRED_RESULT QString debugInfo() const;
179
180private:
181 QList<Person> m_feedAuthors;
182};
183
184} // namespace Atom
185} // namespace Syndication
186
187#endif // SYNDICATION_ATOM_ENTRY_H
188

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