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, 309 insertions, 0 deletions

diff --git a/krdc/kservicelocator.h b/krdc/kservicelocator.h
new file mode 100644
index 00000000..1177000f
--- /dev/null
+++ b/krdc/kservicelocator.h
@@ -0,0 +1,309 @@
+/*
+ *  Interface to find SLP services.
+ *  Copyright (C) 2002 Tim Jansen <tim@tjansen.de>
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Library General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
+ *
+ *  This library 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.  See the GNU
+ *  Library General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Library General Public License
+ *  along with this library; see the file COPYING.LIB.  If not, write to
+ *  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ *  Boston, MA 02111-1307, USA.
+ */
+
+#ifndef __KSERVICELOCATOR_H
+#define __KSERVICELOCATOR_H
+
+#include <qobject.h>
+#include <qmap.h>
+#include <qstringlist.h>
+
+class KServiceLocatorPrivate;
+
+/**
+ * KServiceLocator allows you to search the network for service types, 
+ * services and their attributes using SLP.
+ * Note that most find methods can work in a synchronous and a asynchronous 
+ * mode. In synchronous mode the find method emits a number of signals and
+ * returns. In asynchronous mode the method returns as soon as possible and 
+ * will emit the signals either during or after the find method. You can have 
+ * only one find search at a given time.
+ *
+ * @version $Id$
+ * @author Tim Jansen, tim@tjansen.de 
+ */
+class KServiceLocator : public QObject {
+  Q_OBJECT
+ private:
+        friend class KServiceLocatorPrivate;
+        KServiceLocatorPrivate *d;
+
+ public:
+	/**
+	 * Creates a new KServiceLocator.
+	 * @param lang the language to search in, or QString::null for the 
+	 *             default language
+	 * @param async true to create the service locator in asynchronous
+	 *                   mode, false otherwise
+	 */
+        KServiceLocator(const QString &lang = QString::null, 
+			bool async = true);
+
+	virtual ~KServiceLocator();
+	
+
+	/**
+	 * Parses a list of attributes that has been encoded in a string, as
+	 * returned by foundServiceAttributes() and foundAttributes().
+	 * The format of the encoded attributes is "(name=value), (name=value)".
+	 * Note that some attributes contain lists that must be parsed using 
+	 * parseCommaList(), and that all values must be decoded using 
+	 * decodeAttributeValue().
+	 * @param attributes a list of encoded attributes
+	 * @param attributeMap the attributes will be added to this map
+	 */
+	static void parseAttributeList(const QString &attributes, 
+				       QMap<QString,QString> &attributeMap);
+
+	/**
+	 * Decodes the value of an attribute (removes the escape codes). This
+	 * is neccessary even when you parsed an attribute list.
+	 * This function requires the presence of the SLP library, otherwise it
+	 * will return the original value.
+	 * @param value the attribute value to decode
+	 * @return the decoded value. If @p value was QString::null or decoding
+	 *         failed, QString::null will be returned
+	 */
+	static QString decodeAttributeValue(const QString &value);
+
+	/**
+	 * Parses a comma-separated string of lists, as returned by many signals.
+	 * @param list the comma-separated list
+	 * @return the items as a QStringList
+	 */
+	static QStringList parseCommaList(const QString &list);
+
+	/**
+	 * Creates a comma-separated string of lists, as required by many functions.
+	 * @param map the items of this list will be converted
+	 * @return the comma-separated list
+	 */
+	static QString createCommaList(const QStringList &values);
+
+	/**
+	 * Escapes a string for use as part of a filter, as described in
+	 * RFC 2254. This will replace all occurrences of special 
+	 * characters like paranthesis, backslash and "*", so you can use 
+	 * the converted string as part of the query. Never escape the whole 
+	 * query because then even the neccessary paranthesis characters 
+	 * will be escaped.
+	 * @param str the string to escape 
+	 * @return the escaped string
+	 */
+	static QString escapeFilter(const QString &str);
+
+	/**
+	 * Returns true if service location is generally possible.
+	 * It will fail if SLP libraries are not installed.
+	 * @return true if service location seems to be possible
+	 */
+	bool available();
+
+	/**
+	 * Use this constant for findServiceTypes()'s namingAuthority argument
+	 * to get only services from the default (IANA) naming authority.
+	 */
+	static const QString DEFAULT_AUTHORITY;
+
+	/**
+	 * Use this constant for findServiceTypes()'s namingAuthority argument
+	 * to get all services,
+	 */
+	static const QString ALL_AUTHORITIES;
+
+	/**
+	 * Finds all service types in the given scope with the given naming 
+	 * authority. This function emits the signal foundServiceTypes()
+	 * each time it discovered one or more service types. When the last 
+	 * service type has been found lastServiceTypeSignal() will be emitted. 
+	 * When KServiceLocator is in synchronous mode the function will not be
+	 * returned before lastServiceTypeSignal() has been emitted, in 
+	 * asynchronous mode lastServiceTypeSignal() can be emitted later. If 
+	 * you call this function while another asynchronous operation is 
+	 * running it will fail.
+	 * 
+	 * @param namingAuthority the naming authorities of the service 
+	 *                        types to be found. If DEFAULT_AUTHORITY
+	 *                        only IANA service types will be returned,
+	 *                        if it is ALL_AUTHORITIES or the
+	 *                        argument has been omitted all service types
+	 *                        will be returned.
+	 * @param scopelist a comma-separated list of all scopes that will 
+	 *                  be searched, or QString:null to search in all 
+	 *                  scopes
+	 * @return true if the operation was successful
+	 */
+	bool findServiceTypes(const QString &namingAuthority = QString::null,
+			      const QString &scopelist = QString::null);
+
+	/**
+	 * Finds all services in the given scope with the given service type.
+	 * Examples for service types are "service:ftp" to find all ftp servers
+	 * or "service:remotedesktop:" to find all remote desktop services.
+	 * You can also specify a filter to match services depending their 
+	 * attributes. The filter uses the LDAP Search Filter syntax as 
+	 * described in RFC 2254, "String Representation of LDAP Search 
+	 * Filters".
+	 * The function emits the signal foundService() each time it 
+	 * discovered a service types. When the last service has been found 
+	 * lastServiceSignal() will be emitted. When KServiceLocator is in 
+	 * synchronous mode the function will not be returned before 
+	 * lastServiceSignal() has been emitted, in asynchronous mode 
+	 * lastServiceSignal() can be emitted later. If you call this function 
+	 * while another asynchronous operation is running it will fail.
+	 * 
+	 * @param srvtype the type of the service to search.
+	 * @param filter a filter in LDAP Search Filter syntax, as described
+	 *               in RFC 2254.
+	 * @param scopelist a comma-separated list of all scopes that will 
+	 *                  be searched, or QString:null to search in all 
+	 *                  scopes
+	 * @return true if the operation was successful
+	 */
+	bool findServices(const QString &srvtype, 
+			  const QString &filter = QString::null, 
+			  const QString &scopelist = QString::null);
+
+	/**
+	 * Finds the attributes of the service with the given URL.
+	 * The function emits the signal foundAttributes() if the service
+	 * has been found, followed by lastAttributesSignal(). When 
+	 * KServiceLocator is  in synchronous mode the function will not be 
+	 * returned before lastAttributesSignal() has been emitted, in 
+	 * asynchronous mode lastAttributesSignal() can be emitted later. If 
+	 * you call this function while another asynchronous operation is 
+	 * running it will fail.
+	 * 
+	 * @param serviceURL the URL of the service to search
+	 * @param attributeIds a comma-separated list of attributes to 
+	 *                     retrieve, or QString::null to retrieve all
+	 *                     attributes
+	 * @return true if the operation was successful
+	 */
+	bool findAttributes(const QString &serviceUrl,
+			    const QString &attributeIds = QString::null);
+
+	/**
+	 * Finds all scopes that can be searched. Always finds at least
+	 * one scope (the default scope).
+	 * The function emits the signal foundScopes() if the service
+	 * has been found. When KServiceLocator is in synchronous mode 
+	 * the function will not be returned before foundScopes() has been 
+	 * emitted, in asynchronous mode it can be emitted later. If 
+	 * you call this function while another asynchronous operation is 
+	 * running it will fail.
+	 *
+	 * @return true if the operation was successful
+	 */
+	bool findScopes();
+
+	/**
+	 * If there is a asynchronous operation running, it will aborted.
+	 * It is not guaranteed that you dont receive any signals after 
+	 * calling abortOperation. You will always get a lastSignal call
+	 * even after aborting.
+	 */
+	void abortOperation();
+
+
+ signals:
+	/**
+	 * Called by findServiceTypes() each time one or more service
+	 * types have been discovered.
+	 * @param serviceTypes a comma-separated list of service types
+	 */
+	void foundServiceTypes(QString serviceTypes);
+
+	/**
+	 * Called by findServices() each time a service has been 
+	 * found.
+	 * @param serviceUrl the service url
+	 * @param lifetime the lifetime of the service in seconds
+	 */
+	void foundService(QString serviceUrl, 
+			  int lifetime);
+
+	/**
+	 * Called by findAttributes() when the service's attributes
+	 * have been found.
+	 * @param serviceUrl the service url
+	 * @param attributes an attribute map (see parseAttributeList() and
+	 *                   decodeAttributeValue())
+	 */
+	void foundAttributes(QString serviceUrl, 
+			     QString attributes);
+
+	/**
+	 * Called by findScopes() when the scopes have been discovered.
+	 * @param scopeList a list of valid scopes, empty if an error 
+	 *                  occurred
+	 */
+	void foundScopes(QStringList scopeList);
+
+	
+	/**
+	 * Emitted when a service type discovery operation finished. If 
+	 * you are in async  mode it is guaranteed that the operation is 
+	 * finished when you  receive the signal, so you can start a new 
+	 * one. In synced mode the operation is still running, so you 
+	 * must wait until the find function returns.
+	 * @param success true if all items have been found, false when 
+	 *                an error occurred during the operation
+	 */
+	void lastServiceTypeSignal(bool success);
+
+	/**
+	 * Emitted when a service discovery operation finished. If you are 
+	 * in async  mode it is guaranteed that the operation is finished 
+	 * when you receive the signal, so you can start a new one. In 
+	 * synced mode the operation is still running, so you must wait 
+	 * until the find function returns.
+	 * @param success true if all items have been found, false when 
+	 *                an error occurred during the operation
+	 */
+	void lastServiceSignal(bool success);
+
+	/**
+	 * Emitted when a attributes reqyest operation finished. If you are 
+	 * in async mode it is guaranteed that the operation is finished 
+	 * when you receive the signal, so you can start a new one. In synced 
+	 * mode the operation is still running, so you must wait until the
+	 * find function returns.
+	 * @param success true if all items have been found, false when 
+	 *                an error occurred during the operation
+	 */
+	void lastAttributesSignal(bool success);
+
+ protected:
+	virtual void customEvent(QCustomEvent *);
+
+ private:
+	void emitFoundServiceTypes(QString serviceTypes);
+	void emitFoundService(QString serviceUrl,
+			      int lifetime);
+	void emitFoundAttributes(QString serviceUrl,
+				 QString attributes);
+	void emitFoundScopes(QStringList scopeList);
+	void emitLastServiceTypeSignal(bool success);
+	void emitLastServiceSignal(bool success);
+	void emitLastAttributesSignal(bool success);
+};
+
+#endif