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 |
205 | |