1/*
2 This file is part of the KDE project
3
4 SPDX-FileCopyrightText: 2004 Jakub Stachowski <qbast@go2.pl>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KDNSSDDOMAINBROWSER_H
10#define KDNSSDDOMAINBROWSER_H
11
12#include "remoteservice.h"
13#include <QObject>
14#include <QtContainerFwd>
15#include <memory>
16
17namespace KDNSSD
18{
19class DomainBrowserPrivate;
20
21/*!
22 * \class KDNSSD::DomainBrowser
23 * \inmodule KDNSSD
24 * \inheaderfile KDNSSD/DomainBrowser
25 *
26 * \brief Browses recommended domains for browsing or publishing to.
27 *
28 * Usage of this class is very simple. If you are interested in
29 * browsing for services, simple do:
30 * \code
31 * KDNSSD::DomainBrowser *browser =
32 * new KDNSSD::DomainBrowser(KDNSSD::DomainBrowser::Browsing, this);
33 * connect(browser, SIGNAL(domainAdded(QString)),
34 * this, SLOT(browsingDomainAdded(QString));
35 * connect(browser, SIGNAL(domainRemoved(QString)),
36 * this, SLOT(browsingDomainRemove(QString));
37 * browser->startBrowse();
38 * \endcode
39 *
40 * If you are interested in domains where you can register services,
41 * usage is identical except that you should pass
42 * KDNSSD::DomainBrowser::Publishing to the constructor.
43 */
44class KDNSSD_EXPORT DomainBrowser : public QObject
45{
46 Q_OBJECT
47public:
48 /*!
49 * \enum KDNSSD::DomainBrowser::DomainType
50 * \brief A type of domain recommendation.
51 * \value Browsing Domains recommended for browsing for services on (using ServiceBrowser).
52 * \value Publishing Domains recommended for publishing to (using PublicService).
53 */
54 enum DomainType {
55 Browsing,
56 Publishing,
57 };
58 /*!
59 * Standard constructor
60 *
61 * The global DNS-SD configuration (for example, the global Avahi
62 * configuration for the Avahi backend) will be used.
63 *
64 * \a type is the type of domain to search for
65 *
66 * \a parent is the parent object (see QObject documentation)
67 *
68 * \sa startBrowse() and ServiceBrowser::isAvailable()
69 */
70 explicit DomainBrowser(DomainType type, QObject *parent = nullptr);
71
72 ~DomainBrowser() override;
73
74 /*!
75 * The current known list of domains of the requested DomainType.
76 *
77 * Returns a list of currently known domain names
78 */
79 QStringList domains() const;
80
81 /*!
82 * Starts browsing.
83 *
84 * \note Only the first call to this function will have any effect.
85 *
86 * Browsing stops when the DomainBrowser object is destroyed.
87 *
88 * \warning The domainAdded() signal may be emitted before this
89 * function returns.
90 *
91 * \sa domainAdded() and domainRemoved()
92 */
93 void startBrowse();
94
95 /*!
96 * Whether the browsing has been started.
97 *
98 * Returns \c true if startBrowse() has been called, \c false otherwise
99 */
100 bool isRunning() const;
101
102Q_SIGNALS:
103 /*!
104 * A domain has disappeared from the browsed list.
105 *
106 * Emitted when domain has been removed from browsing list
107 * or the publishing list (depending on which list was
108 * requested in the constructor).
109 *
110 * \a domain is the name of the domain
111 *
112 * \sa domainAdded()
113 */
114 void domainRemoved(const QString &domain);
115
116 /*!
117 * A new domain has been discovered.
118 *
119 * If the requested DomainType is Browsing, this will
120 * also be emitted for the domains specified in the
121 * global configuration.
122 *
123 * \a domain is the name of the domain
124 *
125 * \sa domainRemoved()
126 */
127 void domainAdded(const QString &domain);
128
129private:
130 friend class DomainBrowserPrivate;
131 std::unique_ptr<DomainBrowserPrivate> const d;
132 Q_DECLARE_PRIVATE_D(d, DomainBrowser)
133};
134
135}
136
137#endif
138

source code of kdnssd/src/domainbrowser.h