1 | /* This file is part of the KDE project |
2 | * |
3 | * Copyright (C) 2004, 2005 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 DNSSDPUBLICSERVICE_H |
22 | #define DNSSDPUBLICSERVICE_H |
23 | |
24 | #include <QtCore/QObject> |
25 | #include <dnssd/servicebase.h> |
26 | #include <QtCore/QStringList> |
27 | |
28 | namespace DNSSD |
29 | { |
30 | class PublicServicePrivate; |
31 | |
32 | /** |
33 | * @class PublicService publicservice.h DNSSD/PublicService |
34 | * @short Represents a service to be published |
35 | * |
36 | * This class allows you to publish the existence of a network |
37 | * service provided by your application. |
38 | * |
39 | * If you are providing a web server and want to advertise it |
40 | * on the local network, you might do |
41 | * @code |
42 | * DNSSD::PublicService *service = new DNSSD::PublicService("My files", "_http._tcp", 80); |
43 | * bool isOK = service->publish(); |
44 | * @endcode |
45 | * |
46 | * In this example publish() is synchronous: it will not return |
47 | * until publishing is complete. This is usually not too long |
48 | * but it can freeze an application's GUI for a moment. |
49 | * To publish asynchronously instead, do: |
50 | * @code |
51 | * DNSSD::PublicService *service = new DNSSD::PublicService("My files", "_http._tcp", 80); |
52 | * connect(service, SIGNAL(published(bool)), this, SLOT(wasPublished(bool))); |
53 | * service->publishAsync(); |
54 | * @endcode |
55 | * |
56 | * @author Jakub Stachowski |
57 | */ |
58 | |
59 | class KDNSSD_EXPORT PublicService : public QObject, public ServiceBase |
60 | { |
61 | Q_OBJECT |
62 | |
63 | public: |
64 | /** |
65 | * Creates a service description that can be published |
66 | * |
67 | * If no @p name is given, the computer name is used instead. If there |
68 | * is already a service with the same name, type and domain a number will |
69 | * be appended to the name to make it unique. |
70 | * |
71 | * If no @p domain is specified, the service is published on the link-local |
72 | * domain (.local). |
73 | * |
74 | * The subtypes can be used to specify server attributes, such |
75 | * as "_anon" for anonymous FTP servers, or can specify a specific protocol |
76 | * (such as a web service interface) on top of a generic protocol like SOAP. |
77 | * |
78 | * There is |
79 | * <a href="http://www.dns-sd.org/ServiceTypes.html">a comprehensive list |
80 | * of possible types</a> available, but you are largely on your own for |
81 | * subtypes. |
82 | * |
83 | * @param name a service name to use instead of the computer name |
84 | * @param type service type, in the form _sometype._udp or _sometype._tcp |
85 | * @param port port number, or 0 to "reserve" the service name |
86 | * @param domain the domain to publish the service on (see DomainBrowser) |
87 | * @param subtypes optional list of subtypes, each with a leading underscore |
88 | * |
89 | * @see ServiceBrowser::ServiceBrowser() |
90 | */ |
91 | explicit PublicService(const QString& name = QString(), |
92 | const QString& type = QString(), |
93 | unsigned int port = 0, |
94 | const QString& domain = QString(), |
95 | const QStringList& subtypes = QStringList()); |
96 | |
97 | ~PublicService(); |
98 | |
99 | /** |
100 | * Stops publishing or aborts an incomplete publish request. |
101 | * |
102 | * Useful when you want to disable the service for some time. |
103 | * |
104 | * Note that if you stop providing a service (without exiting the |
105 | * application), you should stop publishing it. |
106 | */ |
107 | void stop(); |
108 | |
109 | /** |
110 | * Publish the service synchronously |
111 | * |
112 | * The method will not return (and hence the application interface will |
113 | * freeze, since KDElibs code should be executed in the main thread) |
114 | * until either the service is published or publishing fails. |
115 | * |
116 | * published(bool) is emitted before this method returns. |
117 | * |
118 | * @return @c true if the service was successfully published, @c false otherwise |
119 | */ |
120 | bool publish(); |
121 | |
122 | /** |
123 | * Whether the service is currently published |
124 | * |
125 | * @return @c true if the service is being published to the domain, |
126 | * @c false otherwise |
127 | */ |
128 | bool isPublished() const; |
129 | |
130 | /** |
131 | * Publish the service asynchronously |
132 | * |
133 | * Returns immediately and emits published(bool) when completed. |
134 | * Note that published(bool) may be emitted before this method |
135 | * returns when an error is detected immediately. |
136 | */ |
137 | void publishAsync(); |
138 | |
139 | /** |
140 | * Sets new text properties |
141 | * |
142 | * If the service is already published, it will be re-announced with |
143 | * the new data. |
144 | * |
145 | * @param textData the new text properties for the service |
146 | * |
147 | * @see ServiceBase::textData() |
148 | */ |
149 | void setTextData(const QMap<QString,QByteArray>& textData); |
150 | |
151 | /** |
152 | * Sets the name of the service |
153 | * |
154 | * If the service is already published, it will be re-announced with |
155 | * the new name. |
156 | * |
157 | * @param serviceName the new name of the service |
158 | */ |
159 | void setServiceName(const QString &serviceName); |
160 | |
161 | /** |
162 | * Sets the service type |
163 | * |
164 | * If the service is already published, it will be re-announced with |
165 | * the new type. |
166 | * |
167 | * @param type the new type of the service |
168 | * |
169 | * See PublicService() for details on the format of @p type |
170 | */ |
171 | void setType(const QString& type); |
172 | |
173 | /** |
174 | * Sets the subtypetypes of the service |
175 | * |
176 | * If the service is already published, it will be re-announced with |
177 | * the new subtypes. |
178 | * |
179 | * The existing list of substypes is replaced, so an empty list will |
180 | * cause all existing subtypes to be removed. |
181 | * |
182 | * @param subtypes the new list of subtypes |
183 | */ |
184 | void setSubTypes(const QStringList& subtypes); |
185 | |
186 | /** |
187 | * Sets the port |
188 | * |
189 | * If the service is already published, it will be re-announced with |
190 | * the new port. |
191 | * |
192 | * @param port the port of the service, or 0 to simply "reserve" the name |
193 | */ |
194 | void setPort(unsigned short port); |
195 | |
196 | /** |
197 | * Sets the domain where the service is published |
198 | * |
199 | * "local." means link-local, ie: the IP subnet on the LAN containing |
200 | * this computer. |
201 | * |
202 | * If service is already published, it will be removed from the current |
203 | * domain and published on @p domain instead. |
204 | * |
205 | * @param domain the new domain to publish the service on |
206 | */ |
207 | void setDomain(const QString& domain); |
208 | |
209 | /** |
210 | * The subtypes of service. |
211 | * |
212 | * @see setSubTypes() |
213 | */ |
214 | QStringList subtypes() const; |
215 | |
216 | Q_SIGNALS: |
217 | /** |
218 | * Emitted when publishing is complete |
219 | * |
220 | * It will also emitted when an already-published service is |
221 | * republished after a property of the service (such as the |
222 | * name or port) is changed. |
223 | */ |
224 | void published(bool successful); |
225 | |
226 | private: |
227 | friend class PublicServicePrivate; |
228 | |
229 | protected: |
230 | virtual void virtual_hook(int, void*); |
231 | }; |
232 | |
233 | |
234 | } |
235 | |
236 | #endif |
237 | |