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 DNSSDREMOTESERVICE_H
22#define DNSSDREMOTESERVICE_H
23
24#include <QtCore/QObject>
25#include <QtCore/QMetaType>
26#include <dnssd/servicebase.h>
27
28namespace DNSSD
29{
30class RemoteServicePrivate;
31
32/**
33 * @class RemoteService remoteservice.h DNSSD/RemoteService
34 * @short Describes a service published over DNS-SD,
35 * typically on a remote machine
36 *
37 * This class allows delayed or asynchronous resolution of
38 * services. As the name suggests, the service is normally
39 * on a remote machine, but the service could just as easily
40 * be published on the local machine.
41 *
42 * RemoteService instances are normally provided by ServiceBrowser,
43 * but can be used to resolve any service if you know the name, type
44 * and domain for it.
45 *
46 * @author Jakub Stachowski
47 *
48 * @see ServiceBrowser
49 */
50class KDNSSD_EXPORT RemoteService : public QObject, public ServiceBase
51{
52 Q_OBJECT
53
54public:
55 typedef KSharedPtr<RemoteService> Ptr;
56
57 /**
58 * Creates an unresolved RemoteService representing the service with
59 * the given name, type and domain
60 *
61 * @param name the name of the service
62 * @param type the type of the service (see ServiceBrowser::ServiceBrowser())
63 * @param domain the domain of the service
64 *
65 * @see ServiceBrowser::isAvailable()
66 */
67 RemoteService(const QString& name, const QString& type, const QString& domain);
68
69 virtual ~RemoteService();
70
71 /**
72 * Resolves the host name and port of service asynchronously
73 *
74 * The host name is not resolved into an IP address - use KResolver
75 * for that.
76 *
77 * The resolved(bool) signal will be emitted when the
78 * resolution is complete, or when it fails.
79 *
80 * Note that resolved(bool) may be emitted before this function
81 * returns in case of immediate failure.
82 *
83 * RemoteService will keep monitoring the service for
84 * changes in hostname and port, and re-emit resolved(bool)
85 * when either changes.
86 *
87 * @see resolve(), hostName(), port()
88 */
89 void resolveAsync();
90
91 /**
92 * Resolves the host name and port of service synchronously
93 *
94 * The host name is not resolved into an IP address - use KResolver
95 * for that.
96 *
97 * resolved(bool) is emitted before this function is returned.
98 *
99 * resolve() will not cause RemoteService to monitor for changes
100 * in the hostname or port of the service.
101 *
102 * @return @c true if successful, @c false on failure
103 *
104 * @see resolveAsync(), hostName(), port()
105 */
106 bool resolve();
107
108 /**
109 * Whether the service has been successfully resolved
110 *
111 * @return @c true if hostName() and port() will return
112 * valid values, @c false otherwise
113 */
114 bool isResolved() const;
115
116Q_SIGNALS:
117 /**
118 * Emitted when resolving is complete
119 *
120 * If operating in asynchronous mode this signal can be
121 * emitted several times (when the hostName or port of
122 * the service changes).
123 *
124 * @param successful @c true if the hostName and port were
125 * successfully resolved, @c false otherwise
126 */
127 void resolved(bool successful);
128
129protected:
130 virtual void virtual_hook(int id, void *data);
131private:
132 friend class RemoteServicePrivate;
133
134};
135
136}
137
138Q_DECLARE_METATYPE(DNSSD::RemoteService::Ptr)
139
140#endif
141