dnssd/servicebase.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 DNSSDSERVICEBASE_H
  22 #define DNSSDSERVICEBASE_H
  23
  24 #include <QtCore/QMap>
  25 #include <QtCore/QString>
  26 #include <ksharedptr.h>
  27 #include <dnssd/dnssd_export.h>
  28
  29 namespace DNSSD
  30 {
  31 class ServiceBasePrivate;
  32
  33 /**
  34  * @class ServiceBase servicebase.h DNSSD/ServiceBase
  35  * @short Describes a service
  36  *
  37  * This class is used to describe a service. The service
  38  * can be published by the current application (in which
  39  * case it is probably a PublicService) or by
  40  * another application, either on the current machine or
  41  * a remote machine, in which case it is probably a
  42  * RemoteService returned by ServiceBrowser.
  43  *
  44  * You should not normally need to create a ServiceBase
  45  * object yourself.
  46  *
  47  * @author Jakub Stachowski
  48  *
  49  * @see PublicService
  50  */
  51 class KDNSSD_EXPORT ServiceBase : public QSharedData //krazy:exclude=dpointer (protected)
  52 {
  53 public:
  54         typedef KSharedPtr<ServiceBase> Ptr;
  55
  56         /**
  57          * Creates a ServiceBase object
  58          *
  59          * Note that @p name, @p type and @p domain uniquely identify
  60          * the service in the DNS-SD system, and @p host and @p port
  61          * provide the actual location of the service.
  62          *
  63          * For example, RemoteService populates @p host and @p port
  64          * based on the @p name, @p type and @p domain attributes
  65          * using the DNS-SD resolution system.
  66          *
  67          * @param name   service name
  68          * @param type   service type
  69          * @param domain the DNS-SD domain name for service
  70          * @param host   the host name of the service (a fully-qualified domain name)
  71          * @param port   the port number of the service
  72          */
  73         explicit ServiceBase(const QString& name = QString(),
  74                              const QString& type = QString(),
  75                              const QString& domain = QString(),
  76                              const QString& host = QString(),
  77                              unsigned short port = 0);
  78
  79         virtual  ~ServiceBase();
  80
  81         /**
  82          * The name of the service
  83          */
  84         QString serviceName() const;
  85
  86         /**
  87          * The type of the service
  88          *
  89          * This is always in the format _sometype._udp or _sometype._tcp.
  90          *
  91          * See the <a href="http://www.dns-sd.org">DNS-SD website</a> for
  92          * <a href="http://www.dns-sd.org/ServiceTypes.html">a full list of service types</a>.
  93          */
  94         QString type() const;
  95
  96         /**
  97          * The domain that the service belongs to
  98          *
  99          * It is "local." for link-local services.
 100          */
 101         QString domain() const;
 102
 103         /**
 104          * The hostname of the service
 105          *
 106          * Only valid for local and resolved remote services.
 107          *
 108          * Together with port(), this can be used to actually
 109          * access the service.
 110          *
 111          * @see RemoteService::resolve() and RemoteService::resolveAsync()
 112          */
 113         QString hostName() const;
 114
 115         /**
 116          * The port number of the service
 117          *
 118          * Only valid for local and resolved remote services.
 119          *
 120          * Together with hostName(), this can be used to actually
 121          * access the service.
 122          *
 123          * @see RemoteService::resolve() and RemoteService::resolveAsync()
 124          */
 125         unsigned short port() const;
 126
 127         /**
 128          * Additional text data associated with the service
 129          *
 130          * Only valid for local and resolved remote services.
 131          *
 132          * This is data that provides additional information about the
 133          * service.  For example, it might be used to specify a printer
 134          * queue on the printer server specified by hostName() and port().
 135          *
 136          * You can check for the data that might be associated with a
 137          * particular service on the <a
 138          * href="http://www.dns-sd.org/ServiceTypes.html">service types list</a>.
 139          * If a @c key=value pair is given, this will appear with the @c value
 140          * in a QByteArray indexed by the @c key.  If the data is on its own
 141          * (does not have an @c = in it), it will be used to index an empty
 142          * QByteArray, and can be checked for with QMap::contains().
 143          *
 144          * For example, if you are accessing the _ipp._tcp service, you might
 145          * do something like
 146          * @code
 147          * QString printerModel = "unknown";
 148          * if (service->textData().contains("ty")) {
 149          *     printQueue = QString::fromUtf8(service->textData()["ty"].constData());
 150          * }
 151          * @endcode
 152          * since the TXT data of the IPP service may contain data like
 153          * "ty=Apple LaserWriter Pro 630".  Note that you actually have to be
 154          * a bit more clever than this, since the key should usually be case
 155          * insensitive.
 156          */
 157         QMap<QString,QByteArray> textData() const;
 158
 159         /**
 160          * Compares services based on name, type and domain
 161          *
 162          * This is enough to for unique identification and omitting
 163          * port, host and text data allows to compare resolved and
 164          * unresolved services
 165          *
 166          * @param o the service to compare this service to
 167          * @return @c true if this service represents the same
 168          *         service (from the point of view of DNS-SD) as
 169          *         @p o, @c false otherwise
 170          */
 171         bool operator==(const ServiceBase& o) const;
 172         /**
 173          * Compares services based on name, type and domain
 174          *
 175          * This is enough to for unique identification and omitting
 176          * port, host and text data allows to compare resolved and
 177          * unresolved services
 178          *
 179          * @param o the service to compare this service to
 180          * @return @c false if this service represents the same
 181          *         service (from the point of view of DNS-SD) as
 182          *         @p o, @c true otherwise
 183          */
 184         bool operator!=(const ServiceBase& o) const;
 185
 186 protected:
 187         ServiceBase(ServiceBasePrivate* const d);
 188         virtual void virtual_hook(int, void*);
 189         ServiceBasePrivate* const d;
 190
 191 };
 192
 193 /* Utility functions */
 194
 195 /**
 196  * Check if the domain is link-local
 197  *
 198  * @return @c true if domain is link-local ('local.'), @c false otherwise
 199  */
 200 bool domainIsLocal(const QString& domain);
 201
 202 }
 203
 204 #endif