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