1 | /* |
2 | * This file is part of the syndication library |
3 | * |
4 | * Copyright (C) 2006 Frank Osterfeld <osterfeld@kde.org> |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Library General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Library General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Library General Public License |
17 | * along with this library; see the file COPYING.LIB. If not, write to |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | * |
21 | */ |
22 | #ifndef SYNDICATION_GLOBAL_H |
23 | #define SYNDICATION_GLOBAL_H |
24 | |
25 | #include <syndication/feed.h> |
26 | |
27 | #include "ksyndication_export.h" |
28 | |
29 | #include <QtCore/QString> |
30 | |
31 | #define SYNDICATION_VERSION "0.1" |
32 | |
33 | namespace Syndication { |
34 | |
35 | class DocumentSource; |
36 | template <class T> class ParserCollection; |
37 | |
38 | /** |
39 | * |
40 | * The default ParserCollection instance parsing |
41 | * a DocumentSource into a Feed object. |
42 | * |
43 | * Use this to parse a local file or a otherwise |
44 | * manually created DocumentSource object. |
45 | |
46 | * To retrieve a feed from the web, use Loader instead. |
47 | * |
48 | * Example code: |
49 | * |
50 | * @code |
51 | * ... |
52 | * QFile someFile(somePath); |
53 | * ... |
54 | * DocumentSource src(someFile.readAll()); |
55 | * someFile.close(); |
56 | * |
57 | * FeedPtr feed = parserCollection()->parse(src); |
58 | * |
59 | * if (feed) |
60 | * { |
61 | * QString title = feed->title(); |
62 | * QList<ItemPtr> items = feed->items(); |
63 | * ... |
64 | * } |
65 | * @endcode |
66 | */ |
67 | SYNDICATION_EXPORT |
68 | ParserCollection<Feed>* parserCollection(); |
69 | |
70 | /** |
71 | * parses a document from a source and returns a new Feed object |
72 | * wrapping the feed content. |
73 | * Shortcut for parserCollection()->parse(). |
74 | * See ParserCollection::parse() for more details. |
75 | * |
76 | * @param src the document source to parse |
77 | * @param formatHint an optional hint which format to test first |
78 | */ |
79 | SYNDICATION_EXPORT |
80 | FeedPtr parse(const DocumentSource& src, const QString& formatHint=QString()); |
81 | |
82 | /** |
83 | * error code indicating fetching or parsing errors |
84 | */ |
85 | enum ErrorCode |
86 | { |
87 | Success = 0, /**< No error occurred, feed was fetched and parsed |
88 | * successfully |
89 | */ |
90 | Aborted = 1, /**< file downloading/parsing was aborted by the user */ |
91 | Timeout = 2, /**< file download timed out */ |
92 | |
93 | UnknownHost = 3, /**< The hostname couldn't get resolved to an IP address */ |
94 | |
95 | FileNotFound = 4, /**< the host was contacted successfully, but reported a |
96 | * 404 error |
97 | */ |
98 | OtherRetrieverError = 5, /**< retriever error not covered by the error codes |
99 | * above. This is returned if a custom |
100 | * DataRetriever was used. See the |
101 | * retriever-specific status byte for more |
102 | * information on the occurred error. */ |
103 | InvalidXml = 6, /**< The XML is invalid. This is returned if no parser |
104 | * accepts the source and the DOM document can't be parsed. |
105 | * It is not returned if the source is not valid XML but a |
106 | * (non-XML) parser accepts it. |
107 | */ |
108 | XmlNotAccepted = 7, /**< The source is valid XML, but no parser accepted |
109 | * it. |
110 | */ |
111 | InvalidFormat = 8 /**< the source was accepted by a parser, but the actual |
112 | * parsing failed. As our parser implementations |
113 | * currently do not validate the source ("parse what you |
114 | * can get"), this code will be rarely seen. |
115 | */ |
116 | }; |
117 | |
118 | |
119 | } // namespace Syndication |
120 | |
121 | #endif // SYNDICATION_GLOBAL_H |
122 | |