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
28namespace DNSSD
29{
30class 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
59class KDNSSD_EXPORT PublicService : public QObject, public ServiceBase
60{
61 Q_OBJECT
62
63public:
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
216Q_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
226private:
227 friend class PublicServicePrivate;
228
229protected:
230 virtual void virtual_hook(int, void*);
231};
232
233
234}
235
236#endif
237