File indexing completed on 2024-04-14 03:58:29

0001 /*
0002     This file is part of the syndication library
0003     SPDX-FileCopyrightText: 2005 Frank Osterfeld <osterfeld@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef SYNDICATION_DOCUMENTSOURCE_H
0009 #define SYNDICATION_DOCUMENTSOURCE_H
0010 
0011 #include <QSharedPointer>
0012 #include <QString>
0013 
0014 #include "syndication_export.h"
0015 
0016 class QByteArray;
0017 class QDomDocument;
0018 
0019 namespace Syndication
0020 {
0021 /**
0022  * Represents the source of a syndication document, as read from the
0023  * downloaded file.
0024  *
0025  * It provides a (cached) DOM representation of the document, but keeps
0026  * the raw data available (for (rarely used) non-XML formats like Okay!
0027  * News).
0028  *
0029  * This way the document can be passed to all available parsers (to find the
0030  * right one for the source), regardless whether they parse XML formats or
0031  * non-XML formats, without having every parser to do the XML parsing again.
0032  *
0033  * @author Frank Osterfeld
0034  */
0035 class SYNDICATION_EXPORT DocumentSource
0036 {
0037 public:
0038     /**
0039      * Creates an empty document source. The raw representation is empty and
0040      * the DOM representation will be invalid.
0041      */
0042     DocumentSource();
0043 
0044     /**
0045      * Creates a DocumentSource object from a raw byte array
0046      *
0047      * @param source the raw source (of the downloaded feed file usually)
0048      * @param url the URL/path the source was read from
0049      */
0050     DocumentSource(const QByteArray &source, const QString &url);
0051 
0052     /**
0053      * Copy constructor. The d pointer is shared, so this is a cheap
0054      * operation.
0055      *
0056      * @param other DocumentSource to copy
0057      */
0058     DocumentSource(const DocumentSource &other);
0059 
0060     /**
0061      * destructor
0062      */
0063     ~DocumentSource();
0064 
0065     /**
0066      * Assignment operator. The d pointer is shared, so this is a cheap
0067      * operation.
0068      *
0069      * @param other DocumentSource to assign to this instance
0070      * @return reference to this instance
0071      */
0072     DocumentSource &operator=(const DocumentSource &other);
0073 
0074     /**
0075      * Returns the feed source as byte array.
0076      *
0077      * @return the feed source as raw byte array.
0078      */
0079     Q_REQUIRED_RESULT QByteArray asByteArray() const;
0080 
0081     /**
0082      * returns the size the source array in bytes.
0083      *
0084      * @return the size of the byte array in bytes.
0085      * See also QByteArray::size()
0086      */
0087     Q_REQUIRED_RESULT unsigned int size() const;
0088 
0089     /**
0090      * calculates a hash value for the source array.
0091      * This can be used to decide whether the feed has changed since
0092      * the last fetch. If the hash hasn't changed since the last fetch,
0093      * the feed wasn't modified with high probability.
0094      *
0095      * @return the hash calculated from the source, 0 if the
0096      * source is empty
0097      */
0098     Q_REQUIRED_RESULT unsigned int hash() const;
0099 
0100     /**
0101      * Returns the feed source as DOM document.
0102      * The document is parsed only on the first call of this method
0103      * and then cached.
0104      *
0105      * If the feed source cannot be parsed successfully then the
0106      * returned DOM node will be null (eg. asDomDocument().isNull()
0107      * will return true)
0108      *
0109      * @return XML representation parsed from the raw source
0110      */
0111     Q_REQUIRED_RESULT QDomDocument asDomDocument() const;
0112 
0113     /**
0114      * returns the URL the document source was loaded from
0115      */
0116     Q_REQUIRED_RESULT QString url() const;
0117 
0118 private:
0119     class DocumentSourcePrivate;
0120     QSharedPointer<DocumentSourcePrivate> d;
0121 };
0122 
0123 } // namespace Syndication
0124 
0125 #endif // SYNDICATION_DOCUMENTSOURCE_H