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
29namespace DNSSD
30{
31class 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 */
51class KDNSSD_EXPORT ServiceBase : public QSharedData //krazy:exclude=dpointer (protected)
52{
53public:
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
186protected:
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 */
200bool domainIsLocal(const QString& domain);
201
202}
203
204#endif
205