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