Syndication

documentsource.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2005 Frank Osterfeld <[email protected]>
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;
121 };
122 
123 } // namespace Syndication
124 
125 #endif // SYNDICATION_DOCUMENTSOURCE_H
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:51:47 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.