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

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