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