File indexing completed on 2024-03-03 04:09:36

0001 /*
0002     This file is part of the syndication library
0003     SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef SYNDICATION_GLOBAL_H
0009 #define SYNDICATION_GLOBAL_H
0010 
0011 #include "feed.h"
0012 
0013 #include "syndication_export.h"
0014 
0015 #include <QString>
0016 
0017 namespace Syndication
0018 {
0019 class DocumentSource;
0020 template<class T>
0021 class ParserCollection;
0022 
0023 /**
0024  *
0025  * The default ParserCollection instance parsing
0026  * a DocumentSource into a Feed object.
0027  *
0028  * Use this to parse a local file or a otherwise
0029  * manually created DocumentSource object.
0030 
0031 * To retrieve a feed from the web, use Loader instead.
0032  *
0033  * Example code:
0034  *
0035  * @code
0036  * ...
0037  * QFile someFile(somePath);
0038  * ...
0039  * DocumentSource src(someFile.readAll());
0040  * someFile.close();
0041  *
0042  * FeedPtr feed = parserCollection()->parse(src);
0043  *
0044  * if (feed)
0045  * {
0046  *     QString title = feed->title();
0047  *     QList<ItemPtr> items = feed->items();
0048  *     ...
0049  * }
0050  * @endcode
0051  */
0052 SYNDICATION_EXPORT
0053 ParserCollection<Feed> *parserCollection();
0054 
0055 /**
0056  * parses a document from a source and returns a new Feed object
0057  * wrapping the feed content.
0058  * Shortcut for parserCollection()->parse().
0059  * See ParserCollection::parse() for more details.
0060  *
0061  * @param src the document source to parse
0062  * @param formatHint an optional hint which format to test first
0063  */
0064 SYNDICATION_EXPORT
0065 FeedPtr parse(const DocumentSource &src, const QString &formatHint = QString());
0066 
0067 /**
0068  * error code indicating fetching or parsing errors
0069  */
0070 enum ErrorCode {
0071     Success = 0, /**< No error occurred, feed was fetched and parsed
0072                   * successfully
0073                   */
0074     Aborted = 1, /**< file downloading/parsing was aborted by the user */
0075     Timeout = 2, /**< file download timed out */
0076 
0077     UnknownHost = 3, /**< The hostname couldn't get resolved to an IP address */
0078 
0079     FileNotFound = 4, /**< the host was contacted successfully, but reported a
0080                        * 404 error
0081                        */
0082     OtherRetrieverError = 5, /**< retriever error not covered by the error codes
0083                               * above. This is returned if a custom
0084                               * DataRetriever was used. See the
0085                               * retriever-specific status byte for more
0086                               * information on the occurred error. */
0087     InvalidXml = 6, /**< The XML is invalid. This is returned if no parser
0088                      * accepts the source and the DOM document can't be parsed.
0089                      * It is not returned if the source is not valid XML but a
0090                      * (non-XML) parser accepts it.
0091                      */
0092     XmlNotAccepted = 7, /**< The source is valid XML, but no parser accepted
0093                          * it.
0094                          */
0095     InvalidFormat = 8, /**< the source was accepted by a parser, but the actual
0096                         * parsing failed. As our parser implementations
0097                         * currently do not validate the source ("parse what you
0098                         * can get"), this code will be rarely seen.
0099                         */
0100 };
0101 
0102 } // namespace Syndication
0103 
0104 #endif // SYNDICATION_GLOBAL_H