Syndication

documentsource.h
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 * 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 */
35class SYNDICATION_EXPORT DocumentSource
36{
37public:
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
118private:
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-2024 The KDE developers.
Generated on Fri May 17 2024 11:56:56 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.