1 | /* |
2 | This file is part of the syndication library |
3 | SPDX-FileCopyrightText: 2005 Frank Osterfeld <osterfeld@kde.org> |
4 | |
5 | SPDX-License-Identifier: LGPL-2.0-or-later |
6 | */ |
7 | |
8 | #ifndef SYNDICATION_DOCUMENTSOURCE_H |
9 | #define SYNDICATION_DOCUMENTSOURCE_H |
10 | |
11 | #include <QSharedPointer> |
12 | #include <QString> |
13 | |
14 | #include "syndication_export.h" |
15 | |
16 | class QByteArray; |
17 | class QDomDocument; |
18 | |
19 | namespace Syndication |
20 | { |
21 | /** |
22 | * Represents the source of a syndication document, as read from the |
23 | * downloaded file. |
24 | * |
25 | * It provides a (cached) DOM representation of the document, but keeps |
26 | * the raw data available (for (rarely used) non-XML formats like Okay! |
27 | * News). |
28 | * |
29 | * This way the document can be passed to all available parsers (to find the |
30 | * right one for the source), regardless whether they parse XML formats or |
31 | * non-XML formats, without having every parser to do the XML parsing again. |
32 | * |
33 | * @author Frank Osterfeld |
34 | */ |
35 | class SYNDICATION_EXPORT DocumentSource |
36 | { |
37 | public: |
38 | /** |
39 | * Creates an empty document source. The raw representation is empty and |
40 | * the DOM representation will be invalid. |
41 | */ |
42 | DocumentSource(); |
43 | |
44 | /** |
45 | * Creates a DocumentSource object from a raw byte array |
46 | * |
47 | * @param source the raw source (of the downloaded feed file usually) |
48 | * @param url the URL/path the source was read from |
49 | */ |
50 | DocumentSource(const QByteArray &source, const QString &url); |
51 | |
52 | /** |
53 | * Copy constructor. The d pointer is shared, so this is a cheap |
54 | * operation. |
55 | * |
56 | * @param other DocumentSource to copy |
57 | */ |
58 | DocumentSource(const DocumentSource &other); |
59 | |
60 | /** |
61 | * destructor |
62 | */ |
63 | ~DocumentSource(); |
64 | |
65 | /** |
66 | * Assignment operator. The d pointer is shared, so this is a cheap |
67 | * operation. |
68 | * |
69 | * @param other DocumentSource to assign to this instance |
70 | * @return reference to this instance |
71 | */ |
72 | DocumentSource &operator=(const DocumentSource &other); |
73 | |
74 | /** |
75 | * Returns the feed source as byte array. |
76 | * |
77 | * @return the feed source as raw byte array. |
78 | */ |
79 | Q_REQUIRED_RESULT QByteArray asByteArray() const; |
80 | |
81 | /** |
82 | * returns the size the source array in bytes. |
83 | * |
84 | * @return the size of the byte array in bytes. |
85 | * See also QByteArray::size() |
86 | */ |
87 | Q_REQUIRED_RESULT unsigned int size() const; |
88 | |
89 | /** |
90 | * calculates a hash value for the source array. |
91 | * This can be used to decide whether the feed has changed since |
92 | * the last fetch. If the hash hasn't changed since the last fetch, |
93 | * the feed wasn't modified with high probability. |
94 | * |
95 | * @return the hash calculated from the source, 0 if the |
96 | * source is empty |
97 | */ |
98 | Q_REQUIRED_RESULT unsigned int hash() const; |
99 | |
100 | /** |
101 | * Returns the feed source as DOM document. |
102 | * The document is parsed only on the first call of this method |
103 | * and then cached. |
104 | * |
105 | * If the feed source cannot be parsed successfully then the |
106 | * returned DOM node will be null (eg. asDomDocument().isNull() |
107 | * will return true) |
108 | * |
109 | * @return XML representation parsed from the raw source |
110 | */ |
111 | Q_REQUIRED_RESULT QDomDocument asDomDocument() const; |
112 | |
113 | /** |
114 | * returns the URL the document source was loaded from |
115 | */ |
116 | Q_REQUIRED_RESULT QString url() const; |
117 | |
118 | private: |
119 | class DocumentSourcePrivate; |
120 | QSharedPointer<DocumentSourcePrivate> d; |
121 | }; |
122 | |
123 | } // namespace Syndication |
124 | |
125 | #endif // SYNDICATION_DOCUMENTSOURCE_H |
126 | |