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 | |
31 | class QByteArray; |
32 | class QDomDocument; |
33 | |
34 | namespace 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 | */ |
50 | class 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 | |