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