summaryrefslogtreecommitdiffstats
path: root/librss/document.h
blob: 903598715af21f7457063e33fe7b099ffeebeae5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
/*
 * document.h
 *
 * Copyright (c) 2001, 2002, 2003, 2004 Frerich Raabe <raabe@kde.org>
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. For licensing and distribution details, check the
 * accompanying file 'COPYING'.
 */
#ifndef LIBRSS_DOCUMENT_H
#define LIBRSS_DOCUMENT_H

#include "article.h"
#include "global.h"

class QDateTime;
class QDomDocument;

namespace RSS
{
	class Image;
	class TextInput;
	
	/**
	 * Represents a RSS document and provides all the features and properties
	 * as stored in it. You usually don't need to instantiate this one yourself
	 * but rather use Loader::loadFrom() to produce a Document object.
	 * @see Loader::loadForm()
	 */
	class LIBRSS_EXPORT Document
	{
		public:
			/**
			 * Default constructor.
			 */
			Document();

			/**
			 * Copy constructor.
			 * @param other The Document object to copy.
			 */
			Document(const Document &other);
			
			/**
			 * Constructs a Document from a piece of XML markup.
			 */
			Document(const QDomDocument &doc);
			
			/**
			 * Assignment operator.
			 * @param other The Document object to clone.
			 * @return A reference to the cloned Document object.
			 */
			Document &operator=(const Document &other);
			
			/**
			 * Destructor.
			 */
			~Document();

			/**
			 * @return The version of this document (one of the values of the
			 * enum RSS::Version). This value can be used to determine which
			 * features this RSS document provides.
			 * @see verbVersion()
			 */
			Version version() const;

			/**
			 * Convenience method. Differs from version() only in how the result
			 * is returned.
			 * @return A QString representing the verbose version of the
			 * document.
			 * @see version()
			 */
			QString verbVersion() const;

			/**
			 * RSS 0.90 and upwards
			 * @return The title of the RSS document, or QString::null if no
			 * title was available. This is often the name of the news source
			 * from which the RSS document was retrieved.
			 */
			QString title() const;

			/**
			 * RSS 0.90 and upwards
			 * @return The description of the RSS document, or QString::null
			 * if no description was available. This is usually a short slogan
			 * or description of the news source from which the RSS document
			 * was retrieved.
			 */
			QString description() const;

			/**
			 * RSS 0.90 and upwards
			 * @return A link pointing to some website, or an empty KURL if no
			 * link was available. This URL mostly points to the homepage of
			 * the news site from which the RSS document was retrieved.
			 * Note that the RSS 0.91 Specification dictates that URLs not
			 * starting with "http://" or "ftp://" are considered invalid.
			 */
			const KURL &link() const;

			/**
			 * RSS 0.90 and upwards
			 * @return An Image object as stored in the RSS document, or a
			 * null pointer if there was no image available.
			 * @see Image
			 */
			Image *image();

			/**
			 * A version of the method above, with stricter const-ness.
			 */
			const Image *image() const;

			/**
			 * RSS 0.90 and upwards
			 * @return A TextInput object as stored in the RSS document, or a
			 * null pointer if there was no text input available.
			 * @see TextInput
			 */
			TextInput *textInput();

			/**
			 * A version of the method above, with stricter const-ness.
			 */
			const TextInput *textInput() const;

			/**
			 * RSS 0.90 and upwards
			 * @return A list of Article objects as stored in the RSS document,
			 * or a null pointer if there were no articles available. Every RSS
			 * DTD requires that there is at least one article defined, so a
			 * null pointer indicates an invalid RSS file!
			 * @see Article
			 */
			const Article::List &articles() const;
			
			/**
			 * RSS 0.91 and upwards
			 * @return The language used in the RSS document (for the article
			 * headlines etc.). This was originally introduced to assist with
			 * determining the correct page encoding but acts as a solely
			 * optional information in this library since you don't have to care
			 * about the encoding as Unicode is used in the whole library.
			 * @see RSS::Language
			 */
			Language language() const;

			/**
			 * RSS 0.91 and upwards
			 * @return A copyright of the information contained in the RSS
			 * document, or QString::null if no copyright is available.
			 */
			QString copyright() const;

			/**
			 * RSS 0.91 and upwards
			 * @return The date when the RSS document was published.
			 */
			const QDateTime &pubDate() const;

			/**
			 * RSS 0.91 and upwards.
			 * @return The last time the channel was modified.
			 */
			const QDateTime &lastBuildDate() const;

			/**
			 * RSS 0.91 and upwards
			 * @return A <a href="http://www.w3.org/PICS/#Specs">PICS</a>
			 * rating for this page.
			 */
			QString rating() const;

			/**
			 * RSS 0.91 and upwards
			 * @return This tag should contain either a URL that references a
			 * description of the channel, or a pointer to the documentation
			 * for the format used in the RSS file.
			 */
			const KURL &docs() const;

			/**
			 * RSS 0.91 and upwards
			 * @return The email address of the managing editor of the site,
			 * the person to contact for editorial inquiries. The suggested
			 * format for email addresses in RSS documents is
			 * bull@mancuso.com (Bull Mancuso).
			 * @see webMaster()
			 */
			QString managingEditor() const;

			/**
			 * RSS 0.91 and upwards
			 * @return The email address of the webmaster for the site, the
			 * person to contact if there are technical problems with the
			 * channel, or QString::null if this information isn't available.
			 * @see managingEditor()
			 */
			QString webMaster() const;

			/**
			 * RSS 0.91 and upwards
			 * @return A list of hours indicating the hours in the day, GMT,
			 * when the channel is unlikely to be updated. If this item is
			 * omitted, the channel is assumed to be updated hourly. Each
			 * hour should be an integer value between 0 and 23.
			 * @see skipDays()
			 */
			const HourList &skipHours() const;

			/**
			 * RSS 0.91 and upwards
			 * @return A list of <day>s of the week, in English, indicating
			 * the days of the week when the RSS document will not be updated.
			 * @see skipHours(), DayList, Day
			 */
			const DayList &skipDays() const;

		private:
			struct Private;
			Private *d;
	};
}

#endif // LIBRSS_DOCUMENT_H
// vim: noet:ts=4