1/* This file is part of the KDE project
2 *
3 * Copyright (C) 2004 Jakub Stachowski <qbast@go2.pl>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public License
16 * along with this library; see the file COPYING.LIB. If not, write to
17 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 */
20
21#ifndef DNSSDSERVICETYPEBROWSER_H
22#define DNSSDSERVICETYPEBROWSER_H
23
24#include <QtCore/QObject>
25#include <dnssd/remoteservice.h>
26
27class QStringList;
28namespace DNSSD
29{
30class ServiceTypeBrowserPrivate;
31
32/**
33 * @class ServiceBrowser servicebrowser.h DNSSD/ServiceBrowser
34 * @short Browses the service types being published on a domain
35 *
36 * This class is mostly useful for generic utilities for
37 * browsing all the published services on a local network.
38 * Applications that wish to find out about available services
39 * of a particular type (such as web servers) should use
40 * ServiceBrowser.
41 *
42 * ServiceTypeBrowser provides a list of all the service types
43 * published by at least one service on a given domain.
44 *
45 * @author Jakub Stachowski
46 */
47class KDNSSD_EXPORT ServiceTypeBrowser : public QObject
48{
49 Q_OBJECT
50
51public:
52 /**
53 * Create a ServiceTypeBrowser for a domain
54 *
55 * The link-local domain (the LAN subnet for this computer) will
56 * be used if no @p domain is given. DomainBrowser can be used
57 * to get a list of browsing domains.
58 *
59 * Note that WAN domains may not support service type browsing.
60 *
61 * @param domain a browsing domain to search
62 * @param parent the parent object (see QObject documentation)
63 *
64 * @see startBrowse() and ServiceBrowser::isAvailable()
65 */
66 explicit ServiceTypeBrowser(const QString& domain = QString(),
67 QObject* parent = 0);
68
69 ~ServiceTypeBrowser();
70
71 /**
72 * All the service types currently being published
73 *
74 * @return a list of service types, in the form _type._tcp or _type._udp
75 */
76 QStringList serviceTypes() const;
77
78 /**
79 * Starts browsing
80 *
81 * Only the first call to this function will have any effect.
82 *
83 * Browsing stops when the ServiceBrowser object is destroyed.
84 *
85 * @warning The serviceTypeAdded() signal may be emitted before this
86 * function returns.
87 *
88 * @see serviceTypeAdded(), serviceTypeRemoved() and finished()
89 */
90 void startBrowse();
91
92 /**
93 * @deprecated
94 * This method is unnecessary, since it is safe to call startBrowse()
95 * multiple times.
96 */
97#ifndef KDE_NO_DEPRECATED
98 KDE_DEPRECATED bool isRunning() const;
99#endif
100
101Q_SIGNALS:
102 /**
103 * Emitted when there are no more services of this type
104 *
105 * @warning
106 * This signal is not reliable: it is possible that it will not be
107 * emitted even after last service of this type disappeared
108 *
109 * @param type the service type
110 *
111 * @see serviceTypeAdded() and finished()
112 */
113 void serviceTypeRemoved(const QString& type);
114
115 /**
116 * A new type of service has been found
117 *
118 * @param type the service type
119 *
120 * @see serviceTypeAdded() and finished()
121 */
122 void serviceTypeAdded(const QString& type);
123
124 /**
125 * Emitted when the list of published service types has settled
126 *
127 * This signal is emitted once after startBrowse() is called
128 * when the types of all the services that are
129 * currently published have been reported (even if no services
130 * are available or the DNS-SD service is not available).
131 * It is emitted again when a new batch of service types become
132 * available or disappear.
133 *
134 * For example, if a new host is connected to network and
135 * announces services of several new types,
136 * they will be reported by several serviceTypeAdded() signals
137 * and the whole batch will be concluded by finished().
138 *
139 * This signal can be used by applications that just want to
140 * get a list of the currently available service types
141 * (similar to a directory listing) and do not care about
142 * adding or removing service types that appear or disappear later.
143 *
144 * @see serviceTypeAdded() and serviceTypeRemoved()
145 */
146 void finished();
147
148private:
149 friend class ServiceTypeBrowserPrivate;
150 ServiceTypeBrowserPrivate* const d;
151};
152
153}
154
155#endif
156