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

source code of syndication/src/documentsource.h