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

source code of kdnssd/src/publicservice.h