summaryrefslogtreecommitdiffstats
path: root/krdc/kservicelocator.h
diff options
context:
space:
mode:
Diffstat (limited to 'krdc/kservicelocator.h')
-rw-r--r--krdc/kservicelocator.h309
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