librss/document.h

   1 /*
   2  * document.h
   3  *
   4  * Copyright (c) 2001, 2002, 2003, 2004 Frerich Raabe <raabe@kde.org>
   5  *
   6  * This program is distributed in the hope that it will be useful, but WITHOUT
   7  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
   8  * FOR A PARTICULAR PURPOSE. For licensing and distribution details, check the
   9  * accompanying file 'COPYING'.
  10  */
  11 #ifndef LIBRSS_DOCUMENT_H
  12 #define LIBRSS_DOCUMENT_H
  13
  14 #include "article.h"
  15 #include "global.h"
  16
  17 class QDateTime;
  18 class QDomDocument;
  19
  20 namespace RSS
  21 {
  22         class Image;
  23         class TextInput;
  24
  25         /**
  26          * Represents a RSS document and provides all the features and properties
  27          * as stored in it. You usually don't need to instantiate this one yourself
  28          * but rather use Loader::loadFrom() to produce a Document object.
  29          * @see Loader::loadForm()
  30          */
  31         class LIBRSS_EXPORT Document
  32         {
  33                 public:
  34                         /**
  35                          * Default constructor.
  36                          */
  37                         Document();
  38
  39                         /**
  40                          * Copy constructor.
  41                          * @param other The Document object to copy.
  42                          */
  43                         Document(const Document &other);
  44
  45                         /**
  46                          * Constructs a Document from a piece of XML markup.
  47                          */
  48                         Document(const QDomDocument &doc);
  49
  50                         /**
  51                          * Assignment operator.
  52                          * @param other The Document object to clone.
  53                          * @return A reference to the cloned Document object.
  54                          */
  55                         Document &operator=(const Document &other);
  56
  57                         /**
  58                          * Destructor.
  59                          */
  60                         ~Document();
  61
  62                         /**
  63                          * @return The version of this document (one of the values of the
  64                          * enum RSS::Version). This value can be used to determine which
  65                          * features this RSS document provides.
  66                          * @see verbVersion()
  67                          */
  68                         Version version() const;
  69
  70                         /**
  71                          * Convenience method. Differs from version() only in how the result
  72                          * is returned.
  73                          * @return A QString representing the verbose version of the
  74                          * document.
  75                          * @see version()
  76                          */
  77                         QString verbVersion() const;
  78
  79                         /**
  80                          * RSS 0.90 and upwards
  81                          * @return The title of the RSS document, or QString::null if no
  82                          * title was available. This is often the name of the news source
  83                          * from which the RSS document was retrieved.
  84                          */
  85                         QString title() const;
  86
  87                         /**
  88                          * RSS 0.90 and upwards
  89                          * @return The description of the RSS document, or QString::null
  90                          * if no description was available. This is usually a short slogan
  91                          * or description of the news source from which the RSS document
  92                          * was retrieved.
  93                          */
  94                         QString description() const;
  95
  96                         /**
  97                          * RSS 0.90 and upwards
  98                          * @return A link pointing to some website, or an empty KURL if no
  99                          * link was available. This URL mostly points to the homepage of
 100                          * the news site from which the RSS document was retrieved.
 101                          * Note that the RSS 0.91 Specification dictates that URLs not
 102                          * starting with "http://" or "ftp://" are considered invalid.
 103                          */
 104                         const KURL &link() const;
 105
 106                         /**
 107                          * RSS 0.90 and upwards
 108                          * @return An Image object as stored in the RSS document, or a
 109                          * null pointer if there was no image available.
 110                          * @see Image
 111                          */
 112                         Image *image();
 113
 114                         /**
 115                          * A version of the method above, with stricter const-ness.
 116                          */
 117                         const Image *image() const;
 118
 119                         /**
 120                          * RSS 0.90 and upwards
 121                          * @return A TextInput object as stored in the RSS document, or a
 122                          * null pointer if there was no text input available.
 123                          * @see TextInput
 124                          */
 125                         TextInput *textInput();
 126
 127                         /**
 128                          * A version of the method above, with stricter const-ness.
 129                          */
 130                         const TextInput *textInput() const;
 131
 132                         /**
 133                          * RSS 0.90 and upwards
 134                          * @return A list of Article objects as stored in the RSS document,
 135                          * or a null pointer if there were no articles available. Every RSS
 136                          * DTD requires that there is at least one article defined, so a
 137                          * null pointer indicates an invalid RSS file!
 138                          * @see Article
 139                          */
 140                         const Article::List &articles() const;
 141
 142                         /**
 143                          * RSS 0.91 and upwards
 144                          * @return The language used in the RSS document (for the article
 145                          * headlines etc.). This was originally introduced to assist with
 146                          * determining the correct page encoding but acts as a solely
 147                          * optional information in this library since you don't have to care
 148                          * about the encoding as Unicode is used in the whole library.
 149                          * @see RSS::Language
 150                          */
 151                         Language language() const;
 152
 153                         /**
 154                          * RSS 0.91 and upwards
 155                          * @return A copyright of the information contained in the RSS
 156                          * document, or QString::null if no copyright is available.
 157                          */
 158                         QString copyright() const;
 159
 160                         /**
 161                          * RSS 0.91 and upwards
 162                          * @return The date when the RSS document was published.
 163                          */
 164                         const QDateTime &pubDate() const;
 165
 166                         /**
 167                          * RSS 0.91 and upwards.
 168                          * @return The last time the channel was modified.
 169                          */
 170                         const QDateTime &lastBuildDate() const;
 171
 172                         /**
 173                          * RSS 0.91 and upwards
 174                          * @return A <a href="http://www.w3.org/PICS/#Specs">PICS</a>
 175                          * rating for this page.
 176                          */
 177                         QString rating() const;
 178
 179                         /**
 180                          * RSS 0.91 and upwards
 181                          * @return This tag should contain either a URL that references a
 182                          * description of the channel, or a pointer to the documentation
 183                          * for the format used in the RSS file.
 184                          */
 185                         const KURL &docs() const;
 186
 187                         /**
 188                          * RSS 0.91 and upwards
 189                          * @return The email address of the managing editor of the site,
 190                          * the person to contact for editorial inquiries. The suggested
 191                          * format for email addresses in RSS documents is
 192                          * bull@mancuso.com (Bull Mancuso).
 193                          * @see webMaster()
 194                          */
 195                         QString managingEditor() const;
 196
 197                         /**
 198                          * RSS 0.91 and upwards
 199                          * @return The email address of the webmaster for the site, the
 200                          * person to contact if there are technical problems with the
 201                          * channel, or QString::null if this information isn't available.
 202                          * @see managingEditor()
 203                          */
 204                         QString webMaster() const;
 205
 206                         /**
 207                          * RSS 0.91 and upwards
 208                          * @return A list of hours indicating the hours in the day, GMT,
 209                          * when the channel is unlikely to be updated. If this item is
 210                          * omitted, the channel is assumed to be updated hourly. Each
 211                          * hour should be an integer value between 0 and 23.
 212                          * @see skipDays()
 213                          */
 214                         const HourList &skipHours() const;
 215
 216                         /**
 217                          * RSS 0.91 and upwards
 218                          * @return A list of <day>s of the week, in English, indicating
 219                          * the days of the week when the RSS document will not be updated.
 220                          * @see skipHours(), DayList, Day
 221                          */
 222                         const DayList &skipDays() const;
 223
 224                 private:
 225                         struct Private;
 226                         Private *d;
 227         };
 228 }
 229
 230 #endif // LIBRSS_DOCUMENT_H
 231 // vim: noet:ts=4