summaryrefslogtreecommitdiffstats
path: root/librss/loader.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitbcb704366cb5e333a626c18c308c7e0448a8e69f (patch)
treef0d6ab7d78ecdd9207cf46536376b44b91a1ca71 /librss/loader.h
downloadtdenetwork-bcb704366cb5e333a626c18c308c7e0448a8e69f.tar.gz
tdenetwork-bcb704366cb5e333a626c18c308c7e0448a8e69f.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'librss/loader.h')
-rw-r--r--librss/loader.h322
1 files changed, 322 insertions, 0 deletions
diff --git a/librss/loader.h b/librss/loader.h
new file mode 100644
index 00000000..5f0c1447
--- /dev/null
+++ b/librss/loader.h
@@ -0,0 +1,322 @@
+/*
+ * loader.h
+ *
+ * Copyright (c) 2001, 2002, 2003, 2004 Frerich Raabe <raabe@kde.org>
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. For licensing and distribution details, check the
+ * accompanying file 'COPYING'.
+ */
+#ifndef LIBRSS_LOADER_H
+#define LIBRSS_LOADER_H
+
+#include "global.h"
+
+class KURL;
+
+#include <qobject.h>
+
+namespace KIO
+{
+ class Job;
+}
+class KProcess;
+
+namespace RSS
+{
+ class Document;
+
+ /**
+ * Abstract baseclass for all data retriever classes. Subclass this to add
+ * a new retrieval algorithm which can then be plugged into the RSS loader.
+ * @see Loader, FileRetriever, OutputRetriever
+ */
+ class DataRetriever : public QObject
+ {
+ Q_OBJECT
+ public:
+ /**
+ * Default constructor.
+ */
+ DataRetriever();
+
+ /**
+ * Destructor.
+ */
+ virtual ~DataRetriever();
+
+ /**
+ * Retrieve data from the given URL. This method is supposed to get
+ * reimplemented by subclasses. It will be called by the Loader
+ * class in case it needs to retrieve the data.
+ * @see Loader::loadFrom()
+ */
+ virtual void retrieveData(const KURL &url) = 0;
+
+ /**
+ * @return An error code which might give a more precise information
+ * about what went wrong in case the 'success' flag returned with
+ * the dataRetrieved() signal was 'false'. Note that the meaning of
+ * the returned integer depends on the actual data retriever.
+ */
+ virtual int errorCode() const = 0;
+
+ signals:
+ /**
+ * Emit this signal to tell the Loader class that the retrieval
+ * process was finished.
+ * @param data Should contain the retrieved data and will get
+ * parsed by the Loader class.
+ * @param success Indicates whether there were any problems during
+ * the retrieval process. Pass 'true' to indicate that everything
+ * went seamlessy, 'false' to tell the Loader that something went
+ * wrong and that the data parameter might contain no or invalid
+ * data.
+ */
+ void dataRetrieved(const QByteArray &data, bool success);
+
+ private:
+ DataRetriever(const DataRetriever &other);
+ DataRetriever &operator=(const DataRetriever &other);
+ };
+
+ /**
+ * Implements a file retriever, to be used with Loader::loadFrom().
+ * @see DataRetriever, Loader::loadFrom()
+ */
+ class LIBRSS_EXPORT FileRetriever : public DataRetriever
+ {
+ Q_OBJECT
+ public:
+ /**
+ * Default constructor.
+ */
+ FileRetriever();
+
+ /**
+ * Destructor.
+ */
+ virtual ~FileRetriever();
+
+ /**
+ * Downloads the file referenced by the given URL and passes it's
+ * contents on to the Loader.
+ * @param url An URL referencing a file which is assumed to
+ * reference valid XML.
+ * @see Loader::loadFrom()
+ */
+ virtual void retrieveData(const KURL &url);
+
+ /**
+ * @return The error code for the last process of retrieving data.
+ * The returned numbers correspond directly to the error codes
+ * <a href="http://developer.kde.org/documentation/library/cvs-api/classref/kio/KIO.html#Error">as
+ * defined by KIO</a>.
+ */
+ virtual int errorCode() const;
+
+ signals:
+ /**
+ * Signals a permanent redirection. The redirection itself is
+ * handled internally, so you don't need to call Loader::loadFrom()
+ * with the new URL. This signal is useful in case you want to
+ * notify the user, or adjust a database entry.
+ * @see Loader::loadFrom()
+ */
+ void permanentRedirection(const KURL &url);
+
+ private slots:
+ void slotData(KIO::Job *job, const QByteArray &data);
+ void slotResult(KIO::Job *job);
+ void slotPermanentRedirection(KIO::Job *job, const KURL &fromUrl,
+ const KURL &toUrl);
+
+ private:
+ FileRetriever(const FileRetriever &other);
+ FileRetriever &operator=(const FileRetriever &other);
+
+ struct Private;
+ Private *d;
+ };
+
+ /**
+ * Implements a data retriever which executes a program and stores returned
+ * by the program on stdout. To be used with Loader::loadFrom().
+ * @see DataRetriever, Loader::loadFrom()
+ */
+ class OutputRetriever : public DataRetriever
+ {
+ Q_OBJECT
+ public:
+ /**
+ * Default constructor.
+ */
+ OutputRetriever();
+
+ /**
+ * Destructor.
+ */
+ virtual ~OutputRetriever();
+
+ /**
+ * Executes the program referenced by the given URL and retrieves
+ * the data which the program prints to stdout.
+ * @param url An URL which is supposed to reference an executable
+ * file.
+ * @see Loader::loadFrom()
+ */
+ virtual void retrieveData(const KURL &url);
+
+ /**
+ * @return The error code for the last process of retrieving data.
+ * 0 is returned in case there was no error, otherwise an error
+ * code which depends on the particular program which was run is
+ * returned.
+ */
+ virtual int errorCode() const;
+
+ private slots:
+ void slotOutput(KProcess *process, char *data, int length);
+ void slotExited(KProcess *process);
+
+ private:
+ OutputRetriever(const OutputRetriever &other);
+ OutputRetriever &operator=(const OutputRetriever &other);
+
+ struct Private;
+ Private *d;
+ };
+
+ /**
+ * This class is the preferred way of loading RSS files. Usage is very
+ * straightforward:
+ *
+ * \code
+ * Loader *loader = Loader::create();
+ * connect(loader, SIGNAL(loadingComplete(Loader *, Document, Status)),
+ * this, SLOT(slotLoadingComplete(Loader *, Document, Status)));
+ * loader->loadFrom("http://www.blah.org/foobar.rdf", new FileRetriever);
+ * \endcode
+ *
+ * This creates a Loader object, connects it's loadingComplete() signal to
+ * your custom slot and then makes it load the file
+ * 'http://www.blah.org/foobar.rdf' using the FileRetriever. You could've
+ * done something like this as well:
+ *
+ * \code
+ * // create the Loader, connect it's signal...
+ * loader->loadFrom("/home/myself/some-script.py", new OutputRetriever);
+ * \endcode
+ *
+ * That'd make the Loader use another algorithm for retrieving the RSS data;
+ * 'OutputRetriever' will make it execute the script
+ * '/home/myself/some-script.py' and assume whatever that script prints to
+ * stdout is RSS markup. This is e.g. handy for conversion scripts, which
+ * download a HTML file and convert it's contents into RSS markup.
+ *
+ * No matter what kind of retrieval algorithm you employ, your
+ * 'slotLoadingComplete' method might look like this:
+ *
+ * \code
+ * void MyClass::slotLoadingComplete(Loader *loader, Document doc, Status status)
+ * {
+ * // Note that Loader::~Loader() is private, so you cannot delete Loader instances.
+ * // You don't need to do that anyway since Loader instances delete themselves.
+ *
+ * if (status != RSS::Success)
+ * return;
+ *
+ * QString title = doc.title();
+ * // do whatever you want with the information.
+ * }
+ * \endcode
+ *
+ * \note You have to create a copy of the passed Document instance in
+ * case you want/need to use it after the slot attached to the
+ * loadingComplete signal goes out of scope. This is e.g. the case if you
+ * intend to call getPixmap() on Document::image()!
+ */
+ class LIBRSS_EXPORT Loader : public QObject
+ {
+ Q_OBJECT
+ friend class someClassWhichDoesNotExist;
+ public:
+ /**
+ * Constructs a Loader instance. This is pretty much what the
+ * default constructor would do, except that it ensures that all
+ * Loader instances have been allocated on the heap (this is
+ * required so that Loader's can delete themselves safely after they
+ * emitted the loadingComplete() signal.).
+ * @return A pointer to a new Loader instance.
+ */
+ static Loader *create();
+
+ /**
+ * Convenience method. Does the same as the above method except that
+ * it also does the job of connecting the loadingComplete() signal
+ * to the given slot for you.
+ * @param object A QObject which features the specified slot
+ * @param slot Which slot to connect to.
+ */
+ static Loader *create(QObject *object, const char *slot);
+
+ /**
+ * Loads the RSS file referenced by the given URL using the
+ * specified retrieval algorithm. Make sure that you connected
+ * to the loadingComplete() signal before calling this method so
+ * that you're guaranteed to get notified when the loading finished.
+ * \note A Loader object cannot load from multiple URLs simultaneously;
+ * consequently, subsequent calls to loadFrom will be discarded
+ * silently, only the first loadFrom request will be executed.
+ * @param url An URL referencing the input file.
+ * @param retriever A subclass of DataRetriever which implements a
+ * specialized retrieval behaviour. Note that the ownership of the
+ * retriever is transferred to the Loader, i.e. the Loader will
+ * delete it when it doesn't need it anymore.
+ * @see DataRetriever, Loader::loadingComplete()
+ */
+ void loadFrom(const KURL &url, DataRetriever *retriever);
+
+ /**
+ * Retrieves the error code of the last loading process (if any),
+ * as reported by the employed data retrever.
+ */
+ int errorCode() const;
+
+ signals:
+ /**
+ * This signal gets emitted when the loading process triggered by
+ * calling loadFrom() finished.
+ * @param loader A pointer pointing to the loader object which
+ * emitted this signal; this is handy in case you connect multiple
+ * loaders to a single slot.
+ * @param doc In case status is Success, this parameter holds the
+ * parsed RSS file. In case it's RetrieveError, you should query
+ * loader->errorCode() for the actual error code.
+ * Note that you have to create a copy of the passed Document
+ * instance in case you want/need to use it after the slot attached
+ * to the loadingComplete signal goes out of scope. This is e.g.
+ * the case if you intend to call getPixmap() on Document::image()!
+ * @param status A status byte telling whether there were any problems
+ * while retrieving or parsing the data.
+ * @see Document, Status
+ */
+ void loadingComplete(Loader *loader, Document doc, Status status);
+
+ private slots:
+ void slotRetrieverDone(const QByteArray &data, bool success);
+
+ private:
+ Loader();
+ Loader(const Loader &other);
+ Loader &operator=(const Loader &other);
+ ~Loader();
+
+ struct Private;
+ Private *d;
+ };
+}
+
+#endif // LIBRSS_LOADER_H
+// vim: noet:ts=4