1/*
2 This file is part of the syndication library
3 SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef SYNDICATION_GLOBAL_H
9#define SYNDICATION_GLOBAL_H
10
11#include "feed.h"
12
13#include "syndication_export.h"
14
15#include <QString>
16
17/*!
18 * \namespace Syndication
19 * \inmodule Syndication
20 * \inheaderfile Syndication/Global
21 */
22namespace Syndication
23{
24class DocumentSource;
25template<class T>
26class ParserCollection;
27
28/*!
29 * The default ParserCollection instance parsing
30 * a DocumentSource into a Feed object.
31 *
32 * Use this to parse a local file or a otherwise
33 * manually created DocumentSource object.
34 *
35 * To retrieve a feed from the web, use Loader instead.
36 *
37 * Example code:
38 *
39 * \code
40 * ...
41 * QFile someFile(somePath);
42 * ...
43 * DocumentSource src(someFile.readAll());
44 * someFile.close();
45 *
46 * FeedPtr feed = parserCollection()->parse(src);
47 *
48 * if (feed)
49 * {
50 * QString title = feed->title();
51 * QList<ItemPtr> items = feed->items();
52 * ...
53 * }
54 * \endcode
55 */
56SYNDICATION_EXPORT
57ParserCollection<Feed> *parserCollection();
58
59/*!
60 * parses a document from a source and returns a new Feed object
61 * wrapping the feed content.
62 *
63 * Shortcut for parserCollection()->parse().
64 *
65 * See ParserCollection::parse() for more details.
66 *
67 * \a src the document source to parse
68 *
69 * \a formatHint an optional hint which format to test first
70 */
71SYNDICATION_EXPORT
72FeedPtr parse(const DocumentSource &src, const QString &formatHint = QString());
73
74/*!
75 * error code indicating fetching or parsing errors
76 *
77 * \value Success No error occurred, feed was fetched and parsed successfully
78 * \value Aborted File downloading/parsing was aborted by the user
79 * \value Timeout File download timed out
80 * \value UnknownHost The hostname couldn't get resolved to an IP address
81 * \value FileNotFound The host was contacted successfully, but reported a 404 error
82 * \value OtherRetrieverError Retriever error not covered by the error codes above. This is returned if a custom DataRetriever was used. See the
83 * retriever-specific status byte for more information on the occurred error.
84 * \value InvalidXml The XML is invalid. This is returned if no parser accepts the source and the DOM document can't be parsed. It is not returned if the source
85 * is not valid XML but a (non-XML) parser accepts it.
86 * \value XmlNotAccepted The source is valid XML, but no parser accepted it.
87 * \value InvalidFormat The source was accepted by a parser, but the actual parsing failed. As our parser implementations currently do not validate the source
88 * ("parse what you can get"), this code will be rarely seen.
89 */
90enum ErrorCode {
91 Success = 0,
92 Aborted = 1,
93 Timeout = 2,
94 UnknownHost = 3,
95 FileNotFound = 4,
96 OtherRetrieverError = 5,
97 InvalidXml = 6,
98 XmlNotAccepted = 7,
99 InvalidFormat = 8,
100};
101
102} // namespace Syndication
103
104#endif // SYNDICATION_GLOBAL_H
105

source code of syndication/src/global.h