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_ITEM_H
9#define SYNDICATION_ITEM_H
10
11#include <QSharedPointer>
12#include <QString>
13
14#include "syndication_export.h"
15
16#include <ctime>
17
18class QDomElement;
19template<class T>
20class QList;
21template<class K, class T>
22class QMultiMap;
23
24namespace Syndication
25{
26class Category;
27typedef QSharedPointer<Category> CategoryPtr;
28class Enclosure;
29typedef QSharedPointer<Enclosure> EnclosurePtr;
30class Item;
31typedef QSharedPointer<Item> ItemPtr;
32class Person;
33typedef QSharedPointer<Person> PersonPtr;
34class SpecificItem;
35typedef QSharedPointer<SpecificItem> SpecificItemPtr;
36
37/*!
38 * \class Syndication::Item
39 * \inmodule Syndication
40 * \inheaderfile Syndication/Item
41 *
42 * \brief An item from a news feed.
43 */
44class SYNDICATION_EXPORT Item
45{
46public:
47 virtual ~Item();
48
49 /*!
50 * Returns the format-specific item this object abstracts from.
51 *
52 * Use it if you need to access format-specifics that are not covered
53 * by this abstraction.
54 */
55 virtual SpecificItemPtr specificItem() const = 0;
56
57 /*!
58 * The title of the item.
59 *
60 * This string may contain HTML markup.(Importantly, occurrences of
61 * the characters '<', '\n', '&', '\'' and '\"' are escaped).
62 *
63 * Returns the title of the item as HTML, or a null string if not
64 * specified
65 */
66 virtual QString title() const = 0;
67
68 /*!
69 * returns a link to the (web) resource described by this item. In most
70 * cases, this will be a website containing the full article associated
71 * with this item.
72 */
73 virtual QString link() const = 0;
74
75 /*!
76 * returns the description of the item.
77 *
78 * The description can either be
79 * a tag line, a short summary of the item content up to a complete
80 * article. If content() is non-empty, it
81 *
82 * This string may contain HTML markup. (Importantly, occurrences of
83 * the characters '<', '\n', '&', '\'' and '\"' are escaped).
84 *
85 * Returns the description as HTML, or a null string if not specified
86 */
87 virtual QString description() const = 0;
88
89 /*!
90 * returns the content of the item. If provided, this is the most
91 * comprehensive text content available for this item. If it is empty,
92 * use description() (which might also contain complete article
93 * content).
94 *
95 * This string may contain HTML markup. (Importantly, occurrences of
96 * the characters '<', '\n', '&', '\'' and '\"' are escaped).
97 *
98 * Returns content string as HTML, or a null string if not set
99 */
100 virtual QString content() const = 0;
101
102 /*!
103 * returns the date when the item was initially published,
104 * as seconds since epoch (Jan 1st 1970), or 0
105 * (epoch) if not set
106 */
107 virtual time_t datePublished() const = 0;
108
109 /*!
110 * returns the date when the item was modified the last time. If no such
111 * date is provided by the feed, this method returns the value of
112 * datePublished().
113 *
114 * Returns modification date, as seconds since epoch (Jan 1st 1970)
115 */
116 virtual time_t dateUpdated() const = 0;
117
118 /*!
119 * returns an identifier that identifies the item within its
120 * feed. The ID must be unique within its feed. If no ID is provided
121 * by the feed source, a hash from title, description and content is
122 * returned.
123 *
124 * Generated hash IDs start with "hash:".
125 */
126 virtual QString id() const = 0;
127
128 /*!
129 * returns a list of persons who created the item content. If there is a
130 * distinction between authors and contributors (Atom), both are added
131 * to the list, where authors are added first.
132 */
133 virtual QList<PersonPtr> authors() const = 0;
134
135 /*!
136 * returns the language used in the item's content
137 *
138 * TODO: tell about language codes and link them
139 */
140 virtual QString language() const = 0;
141
142 /*!
143 * returns a list of enclosures describing files available on the net.
144 * (often used for audio files, so-called "Podcasts").
145 */
146 virtual QList<EnclosurePtr> enclosures() const = 0;
147
148 /*!
149 * returns a list of categories this item is filed in.
150 * See Category for more information on categories.
151 */
152 virtual QList<CategoryPtr> categories() const = 0;
153
154 /*!
155 * Returns the number of comments associated to this item, or -1 if not
156 * specified
157 */
158 virtual int commentsCount() const = 0;
159
160 /*!
161 * Link to an HTML site which contains the comments belonging to
162 * this item.
163 */
164 virtual QString commentsLink() const = 0;
165
166 /*!
167 * URL of feed syndicating comments belonging to this item.
168 */
169 virtual QString commentsFeed() const = 0;
170
171 /*!
172 * URI that can be used to post comments via an HTTP POST request using
173 * the Comment API.
174 *
175 * For more details on the Comment API, see
176 * http://wellformedweb.org/story/9
177 *
178 * Returns URI for posting comments, or a null string if not set
179 */
180 virtual QString commentPostUri() const = 0;
181
182 /*!
183 * returns a list of item metadata not covered by this class.
184 * Can be used e.g. to access format extensions.
185 *
186 * The returned map contains key value pairs, where the key
187 * is the tag name of the element, namespace prefix are resolved
188 * to the corresponding URIs. The value is the XML element as read
189 * from the document.
190 *
191 * For example, to access the <itunes:keywords> element, use
192 * additionalProperties()["http://www.itunes.com/dtds/podcast-1.0.dtdkeywords"].
193 *
194 * Currently this is only
195 * supported for RSS 0.91..0.94/2.0 and Atom formats, but not for RDF
196 * (RSS 0.9 and 1.0).
197 */
198 virtual QMultiMap<QString, QDomElement> additionalProperties() const = 0;
199
200 /*!
201 * returns a description of the item for debugging purposes
202 */
203 virtual QString debugInfo() const;
204};
205
206} // namespace Syndication
207
208#endif // SYNDICATION_ITEM_H
209

source code of syndication/src/item.h