2
* Copyright (C) 2010, 2011 Tuomo Penttinen, all rights reserved.
4
* Author: Tuomo Penttinen <tp@herqq.org>
6
* This file is part of Herqq UPnP (HUPnP) library.
8
* Herqq UPnP is free software: you can redistribute it and/or modify
9
* it under the terms of the GNU Lesser General Public License as published by
10
* the Free Software Foundation, either version 3 of the License, or
11
* (at your option) any later version.
13
* Herqq UPnP is distributed in the hope that it will be useful,
14
* but WITHOUT ANY WARRANTY; without even the implied warranty of
15
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16
* GNU Lesser General Public License for more details.
18
* You should have received a copy of the GNU Lesser General Public License
19
* along with Herqq UPnP. If not, see <http://www.gnu.org/licenses/>.
25
#include <HUpnpCore/HUpnp>
27
#include <QtCore/QObject>
42
* \brief This class is used for sending and receiving SSDP messages defined by the
43
* UPnP Device Architecture specification.
45
* Simple Service Discovery Protocol (SSDP) is an expired IETF Internet draft
46
* on which the UPnP discovery mechanism is built. This class implements only the
47
* SSDP functionality mandated by the UPnP Device Architecture specification.
48
* \brief This class does not implement the SSDP draft in full.
50
* To use this class, you only need to instantiate it and connect to the
51
* exposed signals to receive events when SSDP messages are received. You can also
52
* derive a sub-class and override the various virtual member functions to handle
53
* the received messages.
55
* \headerfile hssdp.h HSsdp
60
* \li this class requires an event loop for listening incoming messages
61
* \li this class has thread-affinity, which mandates that the instances of this
62
* class has to be used in the thread in which they are located at the time.
64
class H_UPNP_CORE_EXPORT HSsdp :
69
H_DECLARE_PRIVATE(HSsdp)
74
* \brief This enumeration specifies the different discovery methods the
75
* HSsdp class can run.
77
enum DiscoveryRequestMethod
80
* This is the default multicast discovery supported both UDA v1.0 and
86
* The unicast discovery specified in UDA v1.1.
93
void unicastMessageReceived();
94
void multicastMessageReceived();
99
HSsdp(const QByteArray& loggingIdentifier, QObject* parent = 0);
104
* This method is called immediately after receiving a discovery request.
106
* Override this method if you want to handle the message. You can also connect
107
* to the discoveryRequestReceived() signal.
109
* \param msg specifies the incoming message.
110
* \param source specifies the source TCP/IP endpoint that sent the
112
* \param requestType specifies the type of the incoming discovery request.
114
* \retval true in case the message was handled successfully and the
115
* discoveryRequestReceived() signal should not be sent.
117
* \retval false in case the message was not handled and the
118
* discoveryRequestReceived() signal should be sent.
120
* \sa discoveryRequestReceived()
122
virtual bool incomingDiscoveryRequest(
123
const HDiscoveryRequest& msg, const HEndpoint& source,
124
DiscoveryRequestMethod requestType);
127
* This method is called immediately after receiving a discovery response.
128
* Override this method if you want to handle message. You can also connect
129
* to the discoveryResponseReceived() signal.
131
* \param msg specifies the incoming message.
132
* \param source specifies the source TCP/IP endpoint that sent the
135
* \retval true in case the message was handled successfully and the
136
* discoveryResponseReceived() signal should not be sent.
138
* \retval false in case the message was not handled and the
139
* discoveryResponseReceived() signal should be sent.
141
* \sa discoveryResponseReceived()
143
virtual bool incomingDiscoveryResponse(
144
const HDiscoveryResponse& msg, const HEndpoint& source);
147
* This method is called immediately after receiving a device available announcement.
148
* Override this method if you want to handle message. You can also connect
149
* to the discoveryRequestReceived() signal.
151
* \param msg specifies the incoming message.
152
* \param source specifies the source TCP/IP endpoint that sent the
155
* \retval true in case the message was handled successfully and the
156
* resourceAvailableReceived() signal should not be sent.
158
* \retval false in case the message was not handled and the
159
* resourceAvailableReceived() signal should be sent.
161
* \sa resourceAvailableReceived()
163
virtual bool incomingDeviceAvailableAnnouncement(
164
const HResourceAvailable& msg, const HEndpoint& source);
167
* This method is called immediately after receiving a device unavailable announcement.
168
* Override this method if you want to handle message. You can also connect
169
* to the resourceUnavailableReceived() signal.
171
* \param msg specifies the incoming message.
172
* \param source specifies the source TCP/IP endpoint that sent the
175
* \retval true in case the message was handled successfully and the
176
* resourceUnavailableReceived() signal should not be sent.
178
* \retval false in case the message was not handled and the
179
* resourceUnavailableReceived() signal should be sent.
181
* \sa resourceUnavailableReceived()
183
virtual bool incomingDeviceUnavailableAnnouncement(
184
const HResourceUnavailable& msg, const HEndpoint& source);
187
* This method is called immediately after receiving a device update announcement.
188
* Override this method if you want to handle message. You can also connect
189
* to the deviceUpdateRecieved() signal.
191
* \param msg specifies the incoming message.
192
* \param source specifies the source TCP/IP endpoint that sent the
195
* \retval true in case the message was handled successfully and the
196
* deviceUpdateRecieved() signal should not be sent.
198
* \retval false in case the message was not handled and the
199
* deviceUpdateRecieved() signal should be sent.
201
* \sa deviceUpdateRecieved()
203
virtual bool incomingDeviceUpdateAnnouncement(
204
const HResourceUpdate& msg, const HEndpoint& source);
209
* \brief Creates a new instance.
211
* \param parent specifies the parent \c QObject.
213
HSsdp(QObject* parent=0);
216
* \brief Destroys the instance.
221
* This enum is used to define a "filter", which specifies which message
222
* types are to be processed when encountered.
224
* \sa filter(), setFilter()
229
* No messages are processed.
234
* Device available messages are processed.
236
DeviceAvailable = 0x01,
239
* Device update messages are processed.
244
* Device unavailable messages are processed.
246
DeviceUnavailable = 0x04,
249
* Discovery request messages are processed.
251
DiscoveryRequest = 0x08,
254
* Discovery response messages are processed.
256
DiscoveryResponse = 0x10,
259
* Discovery response messages are processed.
264
Q_DECLARE_FLAGS(AllowedMessages, AllowedMessage)
267
* \brief Sets the filter of what message types are accepted for processing.
269
* The default is HSsdp::All.
271
* \param allowedMessages defines the message types the instance should
272
* accept for further processing. Other message types will be silently ignored.
276
void setFilter(AllowedMessages allowedMessages);
279
* \brief Returns the message types that are currently accepted for processing.
281
* Default is HSsdp::All.
283
* \return The message types that are currently accepted for processing.
287
AllowedMessages filter() const;
290
* \brief Sets the instance to listen the network for SSDP messages and and attempts to
291
* init the unicast socket of the instance to the address of the first
292
* found network address that is up and that is not loopback. If no such
293
* interface is found the loopback address is used.
295
* \retval true in case the instances was successfully bound to some address.
296
* \retval false in case the instance could not be bound or the instance
299
* \remarks \c %HSsdp has to be bound to receive messages of any type.
304
* \brief Sets the instance to listen the network for SSDP messages and attempts to
305
* init a unicast socket of the instance to the specified address.
307
* \param unicastAddress specifies the address that should be used for
310
* \retval true in case the instance was successfully bound to the
313
* \retval false in case the instance could not be bound or the instance
314
* was already bound to the specified address.
316
* \remarks \c %HSsdp has to be bound to receive messages of any type.
318
bool init(const QHostAddress& unicastAddress);
321
* \brief Indicates if the instance is bound to listen for messages using one
322
* or more network interfaces.
324
* \return \e true in case the instance is bound to listen for messages
325
* using one or more network interfaces.
327
bool isInitialized() const;
330
* \brief Returns the UDP endpoint that is used for unicast communication.
332
* \return The UDP endpoint that is used for unicast communication.
334
HEndpoint unicastEndpoint() const;
337
* Sends the specified device availability announcement.
339
* \param msg specifies the announcement to send.
340
* \param count specifies how many times the announcement is send.
343
* \return The number of messages sent, 0 in case no messages was sent or
344
* -1 in case the provided message is not valid.
346
qint32 announcePresence(const HResourceAvailable& msg, qint32 count = 1);
349
* Sends the specified device availability announcement.
351
* \param msg specifies the announcement to send.
352
* \param count specifies how many times the announcement is send.
355
* \return The number of messages sent, 0 in case no messages was sent or
356
* -1 in case the provided message is not valid.
358
qint32 announcePresence(const HResourceUnavailable& msg, qint32 count = 1);
361
* Sends the specified device update announcement.
363
* \param msg specifies the message to send.
364
* \param count specifies how many times the announcement is send.
367
* \return The number of messages sent, 0 in case no messages was sent or
368
* -1 in case the provided message is not valid.
370
qint32 announceUpdate(const HResourceUpdate& msg, qint32 count = 1);
373
* Sends the specified discovery request.
375
* Sends the specified discovery request to a multicast address
378
* \param msg specifies the announcement to send.
379
* \param count specifies how many times the announcement is send.
382
* \return The number of messages sent, 0 in case no messages was sent or
383
* -1 in case the provided message is not valid.
385
qint32 sendDiscoveryRequest(const HDiscoveryRequest& msg, qint32 count = 1);
388
* Sends the specified discovery request.
390
* Sends the specified discovery request to a specified address. The
391
* address can be an unicast address or a multicast address.
393
* \param msg specifies the announcement to send.
394
* \param destination specifies the target UDP endpoint of the message.
395
* If the port of the specified endpoint is set to zero the message is sent
396
* to the specified host address using the default port 1900.
397
* \param count specifies how many times the announcement is send.
400
* \return The number of messages sent, 0 in case no messages was sent or
401
* -1 in case the provided message or the destination is not valid.
403
qint32 sendDiscoveryRequest(
404
const HDiscoveryRequest& msg, const HEndpoint& destination,
408
* Sends the specified discovery response.
410
* \param msg specifies the announcement to send.
412
* \param destination specifies the target of the response.
413
* If the port of the specified endpoint is set to zero the message is sent
414
* to the specified host address using the default port 1900.
415
* \param count specifies how many times the announcement is send.
418
* \return The number of messages sent, 0 in case no messages was sent or
419
* -1 in case the provided message is not valid.
421
qint32 sendDiscoveryResponse(
422
const HDiscoveryResponse& msg, const HEndpoint& destination,
426
////////////////////////////////////////////////////////////////////////////////
430
* \brief This signal is emitted when a <em>discovery request</em> is received.
432
* \param msg specifies the received <em>discovery request</em> message.
433
* \param source specifies the location where the message came.
434
* \param requestType specifies the type of the incoming discovery request.
436
void discoveryRequestReceived(
437
const Herqq::Upnp::HDiscoveryRequest& msg,
438
const Herqq::Upnp::HEndpoint& source,
439
Herqq::Upnp::HSsdp::DiscoveryRequestMethod requestType);
442
* \brief This signal is emitted when a <em>discovery response</em> is received.
444
* \param msg specifies the received <em>discovery response</em> message.
445
* \param source specifies the location where the message came.
447
void discoveryResponseReceived(
448
const Herqq::Upnp::HDiscoveryResponse& msg,
449
const Herqq::Upnp::HEndpoint& source);
452
* \brief This signal is emitted when a <em>device announcement</em> is received.
454
* \param msg specifies the <em>device announcement</em> message.
455
* \param source specifies the location where the message came.
457
void resourceAvailableReceived(
458
const Herqq::Upnp::HResourceAvailable& msg,
459
const Herqq::Upnp::HEndpoint& source);
462
* \brief This signal is emitted when a <em>device update</em> is received.
464
* \param msg specifies the <em>device update</em> message.
465
* \param source specifies the location where the message came.
467
void deviceUpdateReceived(
468
const Herqq::Upnp::HResourceUpdate& msg,
469
const Herqq::Upnp::HEndpoint& source);
472
* \brief This signal is emitted when a <em>device announcement</em> is received.
474
* \param msg specifies the <em>device announcement</em> message.
475
* \param source specifies the location where the message came.
477
void resourceUnavailableReceived(
478
const Herqq::Upnp::HResourceUnavailable& msg,
479
const Herqq::Upnp::HEndpoint& source);
482
Q_DECLARE_OPERATORS_FOR_FLAGS(HSsdp::AllowedMessages)
487
#endif /* HSSDP_H_ */