1/*
2 * This file is part of the syndication library
3 *
4 * Copyright (C) 2005 Frank Osterfeld <osterfeld@kde.org>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public License
17 * along with this library; see the file COPYING.LIB. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 *
21 */
22
23#ifndef SYNDICATION_DOCUMENTSOURCE_H
24#define SYNDICATION_DOCUMENTSOURCE_H
25
26#include <QtCore/QString>
27#include <boost/shared_ptr.hpp>
28
29#include "ksyndication_export.h"
30
31class QByteArray;
32class QDomDocument;
33
34namespace Syndication {
35
36/**
37 * Represents the source of a syndication document, as read from the
38 * downloaded file.
39 *
40 * It provides a (cached) DOM representation of the document, but keeps
41 * the raw data available (for (rarely used) non-XML formats like Okay!
42 * News).
43 *
44 * This way the document can be passed to all available parsers (to find the
45 * right one for the source), regardless whether they parse XML formats or
46 * non-XML formats, without having every parser to do the XML parsing again.
47 *
48 * @author Frank Osterfeld
49 */
50class SYNDICATION_EXPORT DocumentSource
51{
52 public:
53
54 /**
55 * Creates an empty document source. The raw representation is empty and
56 * the DOM representation will be invalid.
57 */
58 DocumentSource();
59
60 /**
61 * Creates a DocumentSource object from a raw byte array
62 *
63 * @param source the raw source (of the downloaded feed file usually)
64 * @param url the URL/path the source was read from
65 */
66 DocumentSource(const QByteArray& source, const QString& url);
67
68 /**
69 * Copy constructor. The d pointer is shared, so this is a cheap
70 * operation.
71 *
72 * @param other DocumentSource to copy
73 */
74 DocumentSource(const DocumentSource& other);
75
76 /**
77 * destructor
78 */
79 ~DocumentSource();
80
81 /**
82 * Assignment operator. The d pointer is shared, so this is a cheap
83 * operation.
84 *
85 * @param other DocumentSource to assign to this instance
86 * @return reference to this instance
87 */
88 DocumentSource& operator=(const DocumentSource& other);
89
90 /**
91 * Returns the feed source as byte array.
92 *
93 * @return the feed source as raw byte array.
94 */
95 QByteArray asByteArray() const;
96
97 /**
98 * returns the size the source array in bytes.
99 *
100 * @return the size of the byte array in bytes.
101 * See also QByteArray::size()
102 */
103 unsigned int size() const;
104
105 /**
106 * calculates a hash value for the source array.
107 * This can be used to decide whether the feed has changed since
108 * the last fetch. If the hash hasn't changed since the last fetch,
109 * the feed wasn't modified with high probability.
110 *
111 * @return the hash calculated from the source, 0 if the
112 * source is empty
113 */
114 unsigned int hash() const;
115
116 /**
117 * Returns the feed source as DOM document.
118 * The document is parsed only on the first call of this method
119 * and then cached.
120 *
121 * If the feed source cannot be parsed successfully then the
122 * returned DOM node will be null (eg. asDomDocument().isNull()
123 * will return true)
124 *
125 * @return XML representation parsed from the raw source
126 */
127 QDomDocument asDomDocument() const;
128
129 /**
130 * returns the URL the document source was loaded from
131 */
132 QString url() const;
133
134 private:
135
136 class DocumentSourcePrivate;
137 boost::shared_ptr<DocumentSourcePrivate> d;
138};
139
140} // namespace Syndication
141
142#endif // SYNDICATION_DOCUMENTSOURCE_H
143