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
33namespace Syndication {
34
35class DocumentSource;
36template <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 */
67SYNDICATION_EXPORT
68ParserCollection<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 */
79SYNDICATION_EXPORT
80FeedPtr parse(const DocumentSource& src, const QString& formatHint=QString());
81
82/**
83 * error code indicating fetching or parsing errors
84 */
85enum 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