This file is indexed.

/usr/include/dnssd/servicebrowser.h is in kdelibs5-dev 4:4.14.16-0ubuntu3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  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
/* This file is part of the KDE project
 *
 * Copyright (C) 2004 Jakub Stachowski <qbast@go2.pl>
 *
 * 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 DNSSDSERVICEBROWSER_H
#define DNSSDSERVICEBROWSER_H

#include <QtCore/QObject>
#include <QtNetwork/QHostAddress>

#include <dnssd/remoteservice.h>


namespace DNSSD
{
class DomainBrowser;
class ServiceBrowserPrivate;

/**
 * @class ServiceBrowser servicebrowser.h DNSSD/ServiceBrowser
 * @short Browses for network services advertised over DNS-SD
 *
 * This is the central class in the DNSSD library for applications
 * that want to discover services on network.
 *
 * Suppose that you need list of web servers running.  Then you
 * might do something like
 * @code
 * DNSSD::ServiceBrowser* browser = new DNSSD::ServiceBrowser("_http._tcp");
 * connect(browser, SIGNAL(serviceAdded(RemoteService::Ptr)),
 *         this,    SLOT(addService(RemoteService::Ptr)));
 * connect(browser, SIGNAL(serviceRemoved(RemoteService::Ptr)),
 *         this,    SLOT(delService(RemoteService::Ptr)));
 * browser->startBrowse();
 * @endcode
 *
 * In above example addService() will be called for every web server
 * already running and for every web service that subsequently
 * appears on the network and delService() will be called when
 * a server previously advertised is stopped.
 *
 * Because no domain was passed to constructor, the default domain
 * will be searched.  To find other domains to browse for services on,
 * use DomainBrowser.
 *
 * @author Jakub Stachowski
 */
class KDNSSD_EXPORT ServiceBrowser : public QObject
{
	Q_OBJECT

public:
	/**
	 * Availability of DNS-SD services
	 */
	enum State {
		/** the service is available */
		Working,
		/** not available because mDnsd or Avahi daemon is not running */
		Stopped,
		/** not available because KDE was compiled without DNS-SD support */
		Unsupported
	};

	/**
	 * Create a ServiceBrowser for a particular service type
	 *
	 * DomainBrowser can be used to find other domains to browse on.
	 * If no domain is given, the default domain is used.
	 *
	 * The service type is the high-level protocol type, followed by a dot,
	 * followed by the transport protocol type (@c _tcp or @c _udp).
	 * The <a href="http://www.dns-sd.org">DNS-SD website</a> maintains
	 * <a href="http://www.dns-sd.org/ServiceTypes.html">a full list</a>
	 * of service types.
	 *
	 * The @p subtype parameter allows you to do more fine-grained filtering
	 * on the services you are interested in.  So you might request only
	 * FTP servers that allow anonymous access by passing "_ftp._tcp" as the
	 * @p type and "_anon" as the @p subtype.  Subtypes are particularly
	 * important for types like _soap and _upnp, which are far too generic
	 * for most applications.  In these cases, the subtype can be used to
	 * specify the particular SOAP or UPnP protocol they want.
	 *
	 * @warning
	 * Enabling @p autoResolve will increase network usage by resolving
	 * all services, so this feature should be used only when necessary.
	 *
	 * @param type        service types to browse for (example: "_http._tcp")
	 * @param autoResolve discovered services will be resolved before being
	 *                    reported with the serviceAdded() signal
	 * @param domain      a domain to search on instead of the default one
	 * @param subtype     only browse for a specific subtype
	 *
	 * @see startBrowse() and isAvailable()
	 */
	explicit ServiceBrowser(const QString& type,
	                        bool autoResolve = false,
	                        const QString& domain = QString(),
	                        const QString& subtype = QString());

	~ServiceBrowser();

	/**
	 * The currently known services of the specified type
	 *
	 * @returns a list of RemoteService pointers
	 *
	 * @see serviceAdded() and serviceRemoved()
	 */
	QList<RemoteService::Ptr> services() const;

	/**
	 * Starts browsing for services
	 *
	 * Only the first call to this function will have any effect.
	 *
	 * Browsing stops when the ServiceBrowser object is destroyed.
	 *
	 * @warning The serviceAdded() signal may be emitted before this
	 *          function returns.
	 *
	 * @see serviceAdded(), serviceRemoved() and finished()
	 */
	virtual void startBrowse();

	/**
	 * Checks availability of DNS-SD services
	 *
	 * Although this method is part of ServiceBrowser, none of the classes
	 * in this library will be able to perform their intended function
	 * if this method does not return Working.
	 *
	 * If this method does not return Working, it is still safe to call
	 * any of the methods in this library.  However, no services will be
	 * found or published and no domains will be found.
	 *
	 * If you use this function to report an error to the user, below
	 * is a suggestion on how to word the errors when publishing a
	 * service.  The first line of each error message can also be
	 * used for reporting errors when browsing for services.
	 *
	 * @code
	 * switch(DNSSD::ServiceBrowser::isAvailable()) {
	 * case DNSSD::ServiceBrowser::Working:
	 *     return "";
	 * case DNSSD::ServiceBrowser::Stopped:
	 *     return i18n("<p>The Zeroconf daemon is not running. See the Service"
	 *                 " Discovery Handbook for more information.<br/>"
	 *                 "Other users will not see the services provided by this
	 *                 " system when browsing the network via zeroconf, but "
	 *                 " normal access will still work.</p>");
	 * case DNSSD::ServiceBrowser::Unsupported:
	 *     return i18n("<p>Zeroconf support is not available in this version of KDE."
	 *                 " See the Service Discovery Handbook for more information.<br/>"
	 *                 "Other users will not see the services provided by this
	 *                 " application when browsing the network via zeroconf, but "
	 *                 " normal access will still work.</p>");
	 * default:
	 *     return i18n("<p>Unknown error with Zeroconf.<br/>"
	 *                 "Other users will not see the services provided by this
	 *                 " application when browsing the network via zeroconf, but "
	 *                 " normal access will still work.</p>");
	 * }
	 * @endcode
	 *
	 */
	static State isAvailable();

	/**
	 * Whether discovered services are resolved before being reported
	 *
	 * @return the value of the @p autoResolve parameter passed to the constructor
	 *
	 * @since 4.1
	 */
	bool isAutoResolving() const;

	/**
	 * Resolves an mDNS hostname into an IP address
	 *
	 * This function is very rarely useful, since a properly configured
	 * system is able to resolve an mDNS-based host name using the system
	 * resolver (ie: you can just pass the mDNS hostname to KIO or other
	 * library).
	 *
	 * @param hostname the hostname to be resolved
	 * @return a QHostAddress containing the IP address, or QHostAddress() if
	 *         resolution failed
	 * @since 4.2
	 */
	static QHostAddress resolveHostName(const QString& hostname);

	/**
	 * The mDNS hostname of the local machine
	 *
	 * Usually this will return the same as QHostInfo::localHostName(),
	 * but it may be changed to something different
	 * in the Avahi configuration file (if using the Avahi backend).
	 *
	 * @return the hostname, or an empty string on failure
	 * @since 4.2
	 */
	static QString getLocalHostName();

Q_SIGNALS:
	/**
	 * Emitted when new service is discovered
	 *
	 * If isAutoResolving() returns @c true, this will not be emitted
	 * until the service has been resolved.
	 *
	 * @param service a RemoteService object describing the service
	 *
	 * @see serviceRemoved() and finished()
	 */
	void serviceAdded(DNSSD::RemoteService::Ptr service);

	/**
	 * Emitted when a service is no longer published over DNS-SD
	 *
	 * The RemoteService object is removed from the services() list
	 * and deleted immediately after this signal returns.
	 *
	 * @warning
	 * Do @b not use a delayed connection with this signal
	 *
	 * @param service a RemoteService object describing the service
	 *
	 * @see serviceAdded() and finished()
	 */
	void serviceRemoved(DNSSD::RemoteService::Ptr service);

	/**
	 * Emitted when the list of published services has settled
	 *
	 * This signal is emitted once after startBrowse() is called
	 * when all the services of the requested type that are
	 * currently published have been reported (even if none
	 * are available or the DNS-SD service is not available).
	 * It is emitted again when a new batch of services become
	 * available or disappear.
	 *
	 * For example, if a new host is connected to network and
	 * announces some services watched for by this ServiceBrowser,
	 * they will be reported by one or more serviceAdded() signals
	 * and the whole batch will be concluded by finished().
	 *
	 * This signal can be used by applications that just want to
	 * get a list of the currently available services
	 * (similar to a directory listing) and do not care about
	 * adding or removing services that appear or disappear later.
	 *
	 * @warning
	 * There is no guarantee any RemoteService
	 * pointers received by serviceAdded() will be valid
	 * by the time this signal is emitted, so you should either
	 * do all your work involving them in the slot receiving
	 * the serviceAdded() signal, or you should listen to
	 * serviceRemoved() as well.
	 *
	 * @see serviceAdded() and serviceRemoved()
	 */
	void finished();

protected:
	virtual void virtual_hook(int, void*);

private:
	friend class ServiceBrowserPrivate;
	ServiceBrowserPrivate* const d;

};

}

#endif