File indexing completed on 2024-04-28 07:50:19

 /*
     This file is part of the syndication library
     SPDX-FileCopyrightText: 2005 Frank Osterfeld <osterfeld@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef SYNDICATION_RSS2_ITEM_H
 #define SYNDICATION_RSS2_ITEM_H
 
 #include <syndication/elementwrapper.h>
 #include <syndication/rss2/document.h>
 #include <syndication/specificitem.h>
 
 #include <ctime>
 
 class QDomElement;
 class QString;
 template<class T>
 class QList;
 
 namespace Syndication
 {
 class SpecificItemVisitor;
 
 namespace RSS2
 {
 class Category;
 class Enclosure;
 class Source;
 
 /**
  * An Item, representing an entry in an RSS feed.
  *
  * @author Frank Osterfeld
  */
 class Item : public ElementWrapper, public Syndication::SpecificItem
 {
 public:
     /**
      * Default constructor, creates a null object, for which isNull() is
      * @c true.
      */
     explicit Item(QSharedPointer<Document> doc = QSharedPointer<Document>());
 
     /**
      * Creates an Item object wrapping an @c &lt;item> XML element.
      *
      * @param element The @c &lt;item> element to wrap
      * @param doc the document this item is part of
      */
     explicit Item(const QDomElement &element, QSharedPointer<Document> doc = QSharedPointer<Document>());
 
     /**
      * creates a copy of an item. As the d pointer is shared,
      * this is a cheap operation.
      *
      * @param other the item to copy
      */
     Item(const Item &other);
 
     /**
      * destructor
      */
     ~Item() override;
 
     /**
      * assigns another item. As the d pointer is shared,
      * this is a cheap operation.
      *
      * @param other the item to assign
      */
     Item &operator=(const Item &other);
 
     /**
      * Used by visitors for double dispatch. See SpecificItemVisitor
      * for more information.
      * @param visitor the visitor calling the method
      */
     bool accept(SpecificItemVisitor *visitor) override;
 
     /**
      * The title of the item.
      *
      * @return The title in plain text. Note that e.g. characters like <,
      * >, & are not escaped!
      * (TODO: this might change, check what makes more sense)
      */
     QString title() const;
 
     /**
      * The URL of the item. This usually links to the web representation
      * of the item, e.g. the full news article.
      *
      * @return an URL, or a null string if not set
      */
     QString link() const;
 
     /**
      * The item synopsis. This might contain a short summary of the
      * item, but also the full content. If content() is set, that usually
      * contains the full content instead.
      *
      * @return a string in HTML format (whitespace is irrelevant,
      * @c &lt;br/> is used for newlines, "&", "&lt;", "&gt;" are escaped)
      * summarizing the item. A null string if no description was specified.
      */
     QString description() const;
 
     /**
      * Returns the actual content of the item. In RSS2, this can be stored
      * in various elements, e.g. in content:encoded, xhtml:body or
      * xhtml:div. If this is not set, description() might also contain the
      * content of the item.
      *
      * @return the content in HTML format (whitespace is irrelevant,
      * &lt;br/> is used for newlines, "&", "&lt;", "&gt;" are escaped)
      * If no content is specified, a null string is returned.
      */
     QString content() const;
 
     /**
      * Set of categories this item is included in.
      *
      * @return a list of categories, possibly empty.
      */
     QList<Category> categories() const;
 
     /**
      * URL of a page for comments relating to the item.
      *
      * @return an URL to the comments, or a null string if not set
      */
     QString comments() const;
 
     /**
      * The email address of the author of this item. For newspapers and
      * magazines syndicating via RSS, the author is the person who wrote
      * the article that this item describes. For collaborative weblogs, the
      * author of the item might be different from the managing editor or
      * webmaster.
      * This method returns the content of the @c &lt;author> element. If
      * @c &lt;author> is not available, the method returns
      * @c &lt;dc:creator> instead, if available.
      *
      * @return an email address of the author, or a null string if not
      * specified
      */
     QString author() const;
 
     /**
      * Descriptions of media objects that are attached to the item.
      * Note that the RSS2 spec is a bit unclear about whether an item can
      * have multiple enclosures or not. Originally it was not intended, but
      * in reality, some tools out there specify multiple enclosures.
      * So most of the time, this list be either empty or contains a
      * single item, but don't take that for granted
      */
     QList<Enclosure> enclosures() const;
 
     /**
      * "guid stands for globally unique identifier. It's a string that
      * uniquely identifies the item. When present, an aggregator may choose
      * to use this string to determine if an item is new.
      * There are no rules for the syntax of a guid. Aggregators must view
      * them as a string. It's up to the source of the feed to establish the
      * uniqueness of the string."
      *
      * @return a guid string, or a null string if none specified in the
      * feed
      */
     QString guid() const;
 
     /**
      * If @c true, it can be assumed that the guid is a permalink to the
      * item, that is, a url that can be opened in a Web browser, that
      * points to the full item.
      *
      * @return @c true if the guid is a permalink and can be interpreted as
      * URL
      */
     bool guidIsPermaLink() const;
 
     /**
      * Indicates when the item was published. If it's a date in the future,
      * you may choose to not display the item until that date.
      * This returns the content of the @c &lt;pubDate> element. If @c
      * &lt;pubDate> is not available, the method returns
      * @c &lt;dc:date> instead, if available.
      *
      * @return the publication date, or 0 if no date was specified or
      * parsing failed
      */
     time_t pubDate() const;
 
     /**
      * expiration date, specifying a date when the item is not longer
      * available.
      * Only available in RSS 0.93.
      *
      * @return the expiration date, or 0 if no date was specified or
      * parsing failed
      */
     time_t expirationDate() const;
 
     /**
      * A Platform for Internet Content Selection (PICS) rating tag.
      * More information on the format of the rating tag can be found here:
      * http://www.w3.org/PICS/
      *
      * @return PICS rating information, or a null string if not specified
      */
     QString rating() const;
 
     /**
      * The RSS channel that the item came from. See Source class for more
      * information.
      *
      * @return a Source object, or a null object (see Source.isNull()) if
      * not set.
      */
     Source source() const;
 
     /**
      * returns all child elements of this item not covered by this class.
      * You can use this to access additional metadata from RSS extensions.
      */
     QList<QDomElement> unhandledElements() const;
 
     /**
      * Returns a description of the object and its children for debugging
      * purposes.
      *
      * @return debug string
      */
     QString debugInfo() const;
 
     //@cond PRIVATE
     /**
      * @internal
      * returns the description content in unmodified form (no
      * plaintext/HTML conversions etc.)
      */
     QString originalDescription() const;
 
     /**
      * @internal
      * returns the title content in unmodified form (no
      * plaintext/HTML conversions etc.)
      */
     QString originalTitle() const;
     //@endcond
 
 private:
     class ItemPrivate;
     QSharedPointer<ItemPrivate> d;
 };
 
 } // namespace RSS2
 } // namespace Syndication
 
 #endif // SYNDICATION_RSS2_ITEM_H