File indexing completed on 2024-07-14 03:59:06

0001 /*
0002     This file is part of the syndication library
0003     SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef SYNDICATION_ITEM_H
0009 #define SYNDICATION_ITEM_H
0010 
0011 #include <QSharedPointer>
0012 #include <QString>
0013 
0014 #include "syndication_export.h"
0015 
0016 #include <ctime>
0017 
0018 class QDomElement;
0019 template<class T>
0020 class QList;
0021 template<class K, class T>
0022 class QMultiMap;
0023 
0024 namespace Syndication
0025 {
0026 //@cond PRIVATE
0027 class Category;
0028 typedef QSharedPointer<Category> CategoryPtr;
0029 class Enclosure;
0030 typedef QSharedPointer<Enclosure> EnclosurePtr;
0031 class Item;
0032 typedef QSharedPointer<Item> ItemPtr;
0033 class Person;
0034 typedef QSharedPointer<Person> PersonPtr;
0035 class SpecificItem;
0036 typedef QSharedPointer<SpecificItem> SpecificItemPtr;
0037 //@endcond
0038 
0039 /**
0040  * An item from a news feed.
0041  *
0042  * @author Frank Osterfeld
0043  */
0044 class SYNDICATION_EXPORT Item
0045 {
0046 public:
0047     /**
0048      * destructor
0049      */
0050     virtual ~Item();
0051 
0052     /**
0053      * returns the format-specific item this object abstracts from.
0054      * Use it if you need to access format-specifics that are not covered
0055      * by this abstraction.
0056      *
0057      */
0058     virtual SpecificItemPtr specificItem() const = 0;
0059 
0060     /**
0061      * The title of the item.
0062      *
0063      * This string may contain HTML markup.(Importantly, occurrences of
0064      * the characters &lt;,'\n', '&amp;', '\'' and  '\"' are escaped).
0065      *
0066      * @return the title of the item as HTML, or a null string if not
0067      * specified
0068      */
0069     virtual QString title() const = 0;
0070 
0071     /**
0072      * returns a link to the (web) resource described by this item. In most
0073      * cases, this will be a website containing the full article associated
0074      * with this item.
0075      *
0076      * @return a URL, or a null string if not specified
0077      */
0078     virtual QString link() const = 0;
0079 
0080     /**
0081      * returns the description of the item. The description can either be
0082      * a tag line, a short summary of the item content up to a complete
0083      * article. If content() is non-empty, it
0084      *
0085      * This string may contain HTML markup. (Importantly, occurrences of
0086      * the characters &lt;,'\n', '&amp;', '\'' and  '\"' are escaped).
0087      *
0088      * @return the description as HTML, or a null string if not specified
0089      */
0090     virtual QString description() const = 0;
0091 
0092     /**
0093      * returns the content of the item. If provided, this is the most
0094      * comprehensive text content available for this item. If it is empty,
0095      * use description() (which might also contain complete article
0096      * content).
0097      *
0098      * This string may contain HTML markup. (Importantly, occurrences of
0099      * the characters &lt;,'\n', '&amp;', '\'' and  '\"' are escaped).
0100      *
0101      * @return content string as HTML, or a null string if not set
0102      */
0103     virtual QString content() const = 0;
0104 
0105     /**
0106      * returns the date when the item was initially published.
0107      *
0108      * @return publication date, as seconds since epoch (Jan 1st 1970), or 0
0109      * (epoch) if not set
0110      */
0111     virtual time_t datePublished() const = 0;
0112 
0113     /**
0114      * returns the date when the item was modified the last time. If no such
0115      * date is provided by the feed, this method returns the value of
0116      * datePublished().
0117      *
0118      * @return modification date, as seconds since epoch (Jan 1st 1970)
0119      */
0120     virtual time_t dateUpdated() const = 0;
0121 
0122     /**
0123      * returns an identifier that identifies the item within its
0124      * feed. The ID must be unique within its feed. If no ID is provided
0125      * by the feed source, a hash from title, description and content is
0126      * returned.
0127      * Generated hash IDs start with "hash:".
0128      */
0129     virtual QString id() const = 0;
0130 
0131     /**
0132      * returns a list of persons who created the item content. If there is a
0133      * distinction between authors and contributors (Atom), both are added
0134      * to the list, where authors are added first.
0135      *
0136      * @return list of authors (and possibly other contributing persons)
0137      */
0138     virtual QList<PersonPtr> authors() const = 0;
0139 
0140     /**
0141      * returns the language used in the item's content
0142      *
0143      * @return TODO: tell about language codes and link them
0144      */
0145     virtual QString language() const = 0;
0146 
0147     /**
0148      * returns a list of enclosures describing files available on the net.
0149      * (often used for audio files, so-called "Podcasts").
0150      *
0151      * @return a list of enclosures associated with this item
0152      */
0153     virtual QList<EnclosurePtr> enclosures() const = 0;
0154 
0155     /**
0156      * returns a list of categories this item is filed in.
0157      * See Category for more information on categories.
0158      *
0159      * @return a list of categories
0160      */
0161     virtual QList<CategoryPtr> categories() const = 0;
0162 
0163     /**
0164      * The number of comments posted for this item.
0165      *
0166      * @return the number of comments associated to this item, or -1 if not
0167      * specified
0168      */
0169     virtual int commentsCount() const = 0;
0170 
0171     /**
0172      * Link to an HTML site which contains the comments belonging to
0173      * this item.
0174      *
0175      * @return URL to the comments page, or a null string if not set
0176      */
0177     virtual QString commentsLink() const = 0;
0178 
0179     /**
0180      * URL of feed syndicating comments belonging to this item.
0181      *
0182      * @return comments feed URL, or a null string if not set
0183      */
0184     virtual QString commentsFeed() const = 0;
0185 
0186     /**
0187      * URI that can be used to post comments via an HTTP POST request using
0188      * the Comment API.
0189      * For more details on the Comment API, see
0190      * http://wellformedweb.org/story/9
0191      *
0192      * @return URI for posting comments, or a null string if not set
0193      */
0194     virtual QString commentPostUri() const = 0;
0195 
0196     /**
0197      * returns a list of item metadata not covered by this class.
0198      * Can be used e.g. to access format extensions.
0199      *
0200      * The returned map contains key value pairs, where the key
0201      * is the tag name of the element, namespace prefix are resolved
0202      * to the corresponding URIs. The value is the XML element as read
0203      * from the document.
0204      *
0205      * For example, to access the &lt;itunes:keywords> element, use
0206      * additionalProperties()["http://www.itunes.com/dtds/podcast-1.0.dtdkeywords"].
0207      *
0208      * Currently this is only
0209      * supported for RSS 0.91..0.94/2.0 and Atom formats, but not for RDF
0210      * (RSS 0.9 and 1.0).
0211      */
0212     virtual QMultiMap<QString, QDomElement> additionalProperties() const = 0;
0213 
0214     /**
0215      * returns a description of the item for debugging purposes
0216      *
0217      * @return debug string
0218      */
0219     virtual QString debugInfo() const;
0220 };
0221 
0222 } // namespace Syndication
0223 
0224 #endif // SYNDICATION_ITEM_H