dnssd/domainbrowser.h

   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
  27 class QStringList;
  28 namespace DNSSD
  29 {
  30 class 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  */
  54 class KDNSSD_EXPORT DomainBrowser : public QObject
  55 {
  56         Q_OBJECT
  57 public:
  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
 111 Q_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
 138 private:
 139         friend class DomainBrowserPrivate;
 140         DomainBrowserPrivate* const d;
 141 };
 142
 143 }
 144
 145 #endif