File indexing completed on 2024-02-25 04:06:36

0001 /*
0002     This file is part of the syndication library
0003     SPDX-FileCopyrightText: 2005 Frank Osterfeld <osterfeld@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef SYNDICATION_RSS2_DOCUMENT_H
0009 #define SYNDICATION_RSS2_DOCUMENT_H
0010 
0011 #include <syndication/elementwrapper.h>
0012 #include <syndication/specificdocument.h>
0013 
0014 #include <ctime>
0015 
0016 class QDomDocument;
0017 class QDomElement;
0018 class QString;
0019 
0020 template<class T>
0021 class QList;
0022 template<class T>
0023 class QSet;
0024 
0025 namespace Syndication
0026 {
0027 namespace RSS2
0028 {
0029 class Category;
0030 class Cloud;
0031 class Document;
0032 class Image;
0033 class Item;
0034 class TextInput;
0035 typedef QSharedPointer<Document> DocumentPtr;
0036 
0037 /**
0038  * document implementation, representing an RSS feed from the 0.91-0.94/2.0
0039  * family.
0040  *
0041  * @author Frank Osterfeld
0042  */
0043 class Document : public Syndication::SpecificDocument, public Syndication::ElementWrapper
0044 {
0045 public:
0046     /**
0047      * Parses an RSS2 document from an XML document.
0048      * TODO: More on supported formats etc.
0049      *
0050      * @param document The dom document to parse the document from
0051      * @return the document parsed from XML, or an invalid
0052      * document if parsing failed.
0053      */
0054     static Document fromXML(const QDomDocument &document);
0055 
0056     /**
0057      * Default constructor, creates a null object, for which
0058      * isNull() is @c true and  isValid() is @c false.
0059      */
0060     Document();
0061 
0062     /**
0063      * copy constructor
0064      */
0065     Document(const Document &other);
0066 
0067     /**
0068      * destructor
0069      */
0070     ~Document() override;
0071 
0072     /**
0073      * assigns another document. As the d pointer is shared,
0074      * this is a cheap operation.
0075      *
0076      * @param other the document to assign
0077      */
0078     Document &operator=(const Document &other);
0079 
0080     /**
0081      * Used by visitors for double dispatch. See DocumentVisitor
0082      * for more information.
0083      * @param visitor the visitor calling the method
0084      */
0085     bool accept(DocumentVisitor *visitor) override;
0086 
0087     /**
0088      * returns whether this document is valid or not.
0089      * Invalid documents do not contain any useful
0090      * information.
0091      */
0092     bool isValid() const override;
0093 
0094     /**
0095      * The title of the channel.
0096      *
0097      * @return title TODO: more on escaping/HTML
0098      */
0099     QString title() const;
0100 
0101     /**
0102      * The URL to the HTML website corresponding to the channel.
0103      *
0104      * @return TODO
0105      */
0106     QString link() const;
0107 
0108     /**
0109      * Phrase or sentence describing the channel.
0110      *
0111      * @return TODO
0112      */
0113     QString description() const;
0114 
0115     /**
0116      * the items contained in this document
0117      */
0118     QList<Item> items() const;
0119 
0120     /**
0121      *
0122      * @return TODO
0123      */
0124     QString language() const;
0125 
0126     /**
0127      *
0128      * Copyright notice for content in the channel.
0129      * This method returns the content of the @c &lt;copyright>
0130      * element. If @c &lt;copyright> is not available, the method returns
0131      * @c &lt;dc:rights> instead, if available.
0132      *
0133      * @return copyright information, or a null string if not set
0134      */
0135     QString copyright() const;
0136 
0137     /**
0138      * Email address for person responsible for editorial content.
0139      *
0140      * @return editor's email address, or a null string if not set
0141      */
0142     QString managingEditor() const;
0143 
0144     /**
0145      * Email address for person responsible for technical issues relating
0146      * to channel.
0147      *
0148      * @return web master's email address, or a null string if not
0149      */
0150     QString webMaster() const;
0151 
0152     /**
0153      * The publication date for the content in the channel. For example,
0154      * the New York Times publishes on a daily basis, the publication date
0155      * flips once every 24 hours. That's when the pubDate of the channel
0156      * changes.
0157      * This method returns the content of the @c &lt;pubDate> element. If
0158      * @c &lt;pubDate> is not available, the method returns
0159      * @c &lt;dc:date> instead, if available.
0160      *
0161      * @return the publication date, or 0 if no date was specified or
0162      * parsing failed
0163      */
0164     time_t pubDate() const;
0165 
0166     /**
0167      * The last time the content of the channel changed.
0168      *
0169      * @return the last build date, or 0 if no date was specified or parsing
0170      * failed
0171      */
0172     time_t lastBuildDate() const;
0173 
0174     /**
0175      * Specifies one or more categories that the channel belongs to.
0176      *
0177      * @return TODO
0178      */
0179     QList<Category> categories() const;
0180 
0181     /**
0182      * A string indicating the program used to generate the channel.
0183      *
0184      * @return description of the generator program, or a null string if
0185      * not set
0186      */
0187     QString generator() const;
0188 
0189     /**
0190      * A URL that points to the documentation for the format used in the
0191      * RSS file. It's probably a pointer to the RSS specification.
0192      * It's for people who might stumble across an RSS file on a Web server
0193      * 25 years from now and wonder what it is.
0194      *
0195      * @return URL pointing to the format specification, or a null string if
0196      * not set
0197      */
0198     QString docs() const;
0199 
0200     /**
0201      * Allows processes to register with a cloud to be notified of updates
0202      * to the channel, implementing a lightweight publish-subscribe
0203      * protocol for RSS feeds.
0204      *
0205      * @return cloud information, or a null object if not set
0206      */
0207     Cloud cloud() const;
0208 
0209     /**
0210      * ttl stands for time to live. It's a number of minutes that indicates
0211      * how long a channel can be cached before refreshing from the source.
0212      *
0213      * @return the "time to live" in minutes, or 0 if not set
0214      */
0215     int ttl() const;
0216 
0217     /**
0218      * Specifies a GIF, JPEG or PNG image that can be displayed with the
0219      * channel.
0220      *
0221      * @return the image, or a null object if not set
0222      */
0223     Image image() const;
0224 
0225     /**
0226      * Specifies a text input box that can be displayed with the channel.
0227      *
0228      * @return the text input, or a null object if not set
0229      */
0230     TextInput textInput() const;
0231 
0232     /**
0233      * Contains a set of hours (from 0 to 23), time in GMT, when the
0234      * channel is not updated.
0235      */
0236     QSet<int> skipHours() const;
0237 
0238     /** days of week, used for skip days */
0239     enum DayOfWeek {
0240 
0241         Monday = 0, /**< self-explanatory */
0242         Tuesday = 1, /**< self-explanatory */
0243         Wednesday = 2, /**< self-explanatory */
0244         Thursday = 3, /**< self-explanatory */
0245         Friday = 4, /**< self-explanatory */
0246         Saturday = 5, /**< self-explanatory */
0247         Sunday = 6, /**< self-explanatory */
0248     };
0249 
0250     /**
0251      * A set of week days where aggregators shouldn't read the channel.
0252      *
0253      */
0254     QSet<DayOfWeek> skipDays() const;
0255 
0256     /**
0257      * returns all child elements of this document not covered by this class.
0258      * You can use this to access additional metadata from RSS extensions.
0259      */
0260     QList<QDomElement> unhandledElements() const;
0261 
0262     /**
0263      * Returns a description of the object and its children for
0264      * debugging purposes.
0265      *
0266      * @return debug string
0267      */
0268     QString debugInfo() const override;
0269 
0270     //@cond PRIVATE
0271     /**
0272      * @internal
0273      * checks the format of title elements and returns the results
0274      * @param isCDATA whether the titles are encapsulated in CDATA
0275      * @param containsMarkup whether the heuristic found HTML markup in
0276      * titles
0277      */
0278     void getItemTitleFormatInfo(bool *isCDATA, bool *containsMarkup) const;
0279 
0280     /**
0281      * @internal
0282      * checks the format of title elements and returns the results
0283      * @param isCDATA whether the descriptions are encapsulated in CDATA
0284      * @param containsMarkup whether the heuristic found HTML markup in
0285      * descriptions
0286      */
0287     void getItemDescriptionFormatInfo(bool *isCDATA, bool *containsMarkup) const;
0288     //@endcond
0289 
0290 private:
0291     /**
0292      * @internal
0293      * private constructor, used by fromXML()
0294      * TODO: remove fromXML(), make this one private
0295      */
0296     explicit Document(const QDomElement &element);
0297 
0298     class DocumentPrivate;
0299     QSharedPointer<DocumentPrivate> d;
0300 };
0301 
0302 } // namespace RSS2
0303 } // namespace Syndication
0304 
0305 #endif // SYNDICATION_RSS2_DOCUMENT_H