You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdenetwork/krdc/kservicelocator.h

310 lines
12 KiB

/*
* 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