Syndication

entry.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2006 Frank Osterfeld <[email protected]>
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
Interface for all format-specific item-like classes, such as RSS2/RDF items, and Atom entries.
Definition: specificitem.h:31
Visitor interface, following the Visitor design pattern.
an Atom entry, equivalent to the "items" in the RSS world.
Definition: entry.h:38
If an entry was copied from another feed, this class contains a description of the source feed.
Definition: atom/source.h:36
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Jun 5 2023 03:55:56 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.