summaryrefslogtreecommitdiffstats
path: root/krdc/kservicelocator.h
blob: db247177a9aeb3a88a2b0a662e303bf9716cbcab (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
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., 51 Franklin Street, Fifth Floor,
 *  Boston, MA 02110-1301, 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