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 DNSSDDOMAINBROWSER_H
22#define DNSSDDOMAINBROWSER_H
23
24#include <QtCore/QObject>
25#include <dnssd/remoteservice.h>
26
27class QStringList;
28namespace DNSSD
29{
30class DomainBrowserPrivate;
31
32/**
33 * @class DomainBrowser domainbrowser.h DNSSD/DomainBrowser
34 * @short Browses recommended domains for browsing or publishing to.
35 *
36 * Usage of this class is very simple. If you are interested in
37 * browsing for services, simple do
38 * @code
39 * DNSSD::DomainBrowser *browser =
40 * new DNSSD::DomainBrowser(DNSSD::DomainBrowser::Browsing, this);
41 * connect(browser, SIGNAL(domainAdded(QString)),
42 * this, SLOT(browsingDomainAdded(QString));
43 * connect(browser, SIGNAL(domainRemoved(QString)),
44 * this, SLOT(browsingDomainRemove(QString));
45 * browser->startBrowse();
46 * @endcode
47 *
48 * If you are interested in domains where you can register services,
49 * usage is identical except that you should pass
50 * <tt>DNSSD::DomainBrowser::Registering</tt> to the constructor.
51 *
52 * @author Jakub Stachowski
53 */
54class KDNSSD_EXPORT DomainBrowser : public QObject
55{
56 Q_OBJECT
57public:
58 /**
59 * A type of domain recommendation
60 */
61 enum DomainType
62 {
63 /** Domains recommended for browsing for services on (using ServiceBrowser) */
64 Browsing,
65 /** Domains recommended for publishing to (using PublicService) */
66 Publishing
67 };
68 /**
69 * Standard constructor
70 *
71 * The global DNS-SD configuration (for example, the global Avahi
72 * configuration for the Avahi backend) will be used.
73 *
74 * @param type the type of domain to search for
75 * @param parent parent object (see QObject documentation)
76 *
77 * @see startBrowse() and ServiceBrowser::isAvailable()
78 */
79 explicit DomainBrowser(DomainType type, QObject* parent = 0);
80
81 ~DomainBrowser();
82
83 /**
84 * The current known list of domains of the requested DomainType
85 *
86 * @return a list of currently known domain names
87 */
88 QStringList domains() const;
89
90 /**
91 * Starts browsing
92 *
93 * Only the first call to this function will have any effect.
94 *
95 * Browsing stops when the DomainBrowser object is destroyed.
96 *
97 * @warning The domainAdded() signal may be emitted before this
98 * function returns.
99 *
100 * @see domainAdded() and domainRemoved()
101 */
102 void startBrowse();
103
104 /**
105 * Whether the browsing has been started
106 *
107 * @return @c true if startBrowse() has been called, @c false otherwise
108 */
109 bool isRunning() const;
110
111Q_SIGNALS:
112 /**
113 * A domain has disappeared from the browsed list
114 *
115 * Emitted when domain has been removed from browsing list
116 * or the publishing list (depending on which list was
117 * requested in the constructor).
118 *
119 * @param domain the name of the domain
120 *
121 * @see domainAdded()
122 */
123 void domainRemoved(const QString& domain);
124
125 /**
126 * A new domain has been discovered
127 *
128 * If the requested DomainType is Browsing, this will
129 * also be emitted for the domains specified in the
130 * global configuration.
131 *
132 * @param domain the name of the domain
133 *
134 * @see domainRemoved()
135 */
136 void domainAdded(const QString& domain);
137
138private:
139 friend class DomainBrowserPrivate;
140 DomainBrowserPrivate* const d;
141};
142
143}
144
145#endif
146