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

source code of kdnssd/src/publicservice.h