dnssd/servicetypebrowser.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 DNSSDSERVICETYPEBROWSER_H
  22 #define DNSSDSERVICETYPEBROWSER_H
  23
  24 #include <QtCore/QObject>
  25 #include <dnssd/remoteservice.h>
  26
  27 class QStringList;
  28 namespace DNSSD
  29 {
  30 class 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  */
  47 class KDNSSD_EXPORT ServiceTypeBrowser : public QObject
  48 {
  49         Q_OBJECT
  50
  51 public:
  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         KDE_DEPRECATED bool isRunning() const;
  98
  99 Q_SIGNALS:
 100         /**
 101          * Emitted when there are no more services of this type
 102          *
 103          * @warning
 104          * This signal is not reliable: it is possible that it will not be
 105          * emitted even after last service of this type disappeared
 106          *
 107          * @param type the service type
 108          *
 109          * @see serviceTypeAdded() and finished()
 110          */
 111         void serviceTypeRemoved(const QString& type);
 112
 113         /**
 114          * A new type of service has been found
 115          *
 116          * @param type the service type
 117          *
 118          * @see serviceTypeAdded() and finished()
 119          */
 120         void serviceTypeAdded(const QString& type);
 121
 122         /**
 123          * Emitted when the list of published service types has settled
 124          *
 125          * This signal is emitted once after startBrowse() is called
 126          * when the types of all the services that are
 127          * currently published have been reported (even if no services
 128          * are available or the DNS-SD service is not available).
 129          * It is emitted again when a new batch of service types become
 130          * available or disappear.
 131          *
 132          * For example, if a new host is connected to network and
 133          * announces services of several new types,
 134          * they will be reported by several serviceTypeAdded() signals
 135          * and the whole batch will be concluded by finished().
 136          *
 137          * This signal can be used by applications that just want to
 138          * get a list of the currently available service types
 139          * (similar to a directory listing) and do not care about
 140          * adding or removing service types that appear or disappear later.
 141          *
 142          * @see serviceTypeAdded() and serviceTypeRemoved()
 143          */
 144         void finished();
 145
 146 private:
 147         friend class ServiceTypeBrowserPrivate;
 148         ServiceTypeBrowserPrivate* const d;
 149 };
 150
 151 }
 152
 153 #endif