Line data Source code
1 :
2 : /* Copyright (c) 2012-2014, Stefan Eilemann <eile@eyescale.ch>
3 : *
4 : * This file is part of Lunchbox <https://github.com/Eyescale/Lunchbox>
5 : *
6 : * This library is free software; you can redistribute it and/or modify it under
7 : * the terms of the GNU Lesser General Public License version 2.1 as published
8 : * by the Free Software Foundation.
9 : *
10 : * This library is distributed in the hope that it will be useful, but WITHOUT
11 : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 : * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
13 : * details.
14 : *
15 : * You should have received a copy of the GNU Lesser General Public License
16 : * along with this library; if not, write to the Free Software Foundation, Inc.,
17 : * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 : */
19 :
20 : #ifndef LUNCHBOX_SERVUS_H
21 : #define LUNCHBOX_SERVUS_H
22 :
23 : #include <lunchbox/api.h>
24 : #include <lunchbox/result.h> // nested base class
25 : #include <lunchbox/types.h>
26 : #include <boost/noncopyable.hpp>
27 : #include <map>
28 :
29 : namespace lunchbox
30 : {
31 : namespace detail { class Servus; }
32 :
33 : /**
34 : * Simple wrapper for ZeroConf key/value pairs.
35 : *
36 : * The servus class allows simple announcement and discovery of key/value pairs
37 : * using ZeroConf networking. The same instance can be used to announce and/or
38 : * to browse a ZeroConf service. If the Lunchbox library is compiled without
39 : * zeroconf support (@sa isAvailable()), this class does not do anything useful.
40 : *
41 : * Example: @include tests/servus.cpp
42 : */
43 : class Servus : public boost::noncopyable
44 : {
45 : public:
46 : enum Interface
47 : {
48 : IF_ALL = 0, //!< use all interfaces
49 : // (uint32_t) -1 == kDNSServiceInterfaceIndexLocalOnly
50 : IF_LOCAL = (unsigned)(-1) //!< only local interfaces
51 : };
52 :
53 : /**
54 : * The ZeroConf operation result code.
55 : *
56 : * The result code is either one of kDNSServiceErr_ or one of static
57 : * constants defined by this class
58 : */
59 : class Result : public lunchbox::Result
60 : {
61 : public:
62 12 : explicit Result( const int32_t code ) : lunchbox::Result( code ){}
63 12 : virtual ~Result(){}
64 : LUNCHBOX_API std::string getString() const override;
65 :
66 : /** operation did not complete. */
67 : static const int32_t PENDING = -1;
68 : /** Lunchbox compiled without ZeroConf support. */
69 : static const int32_t NOT_SUPPORTED = -2;
70 : /** Error during polling for event. */
71 : static const int32_t POLL_ERROR = -3;
72 : };
73 :
74 : /** @return true if a usable implementation is available. @version 1.9.2 */
75 : LUNCHBOX_API static bool isAvailable();
76 :
77 : /**
78 : * Create a new service handle.
79 : *
80 : * @param name the service descriptor, e.g., "_hwsd._tcp"
81 : * @version 0.9
82 : */
83 : LUNCHBOX_API explicit Servus( const std::string& name );
84 :
85 : /** Destruct this service. */
86 : LUNCHBOX_API virtual ~Servus();
87 :
88 : /**
89 : * Set a key/value pair to be announced.
90 : *
91 : * Keys should be at most eight characters, and values are truncated to 255
92 : * characters. The total length of all keys and values cannot exceed 65535
93 : * characters. Setting a value on an announced service causes an update
94 : * which needs some time to propagate after this function returns, that is,
95 : * calling discover() immediately afterwards will very likely not contain
96 : * the new key/value pair.
97 : *
98 : * @version 0.9
99 : */
100 : LUNCHBOX_API void set( const std::string& key, const std::string& value );
101 :
102 : /** @return all (to be) announced keys. @version 1.5.1 */
103 : LUNCHBOX_API Strings getKeys() const;
104 :
105 : /** @return the value to the given (to be) announced key. @version 1.5.1 */
106 : LUNCHBOX_API const std::string& get( const std::string& key ) const;
107 :
108 : /**
109 : * Start announcing the registered key/value pairs.
110 : *
111 : * @param port the service IP port in host byte order.
112 : * @param instance a host-unique instance name, hostname is used if empty.
113 : * @return the success status of the operation.
114 : * @version 0.9
115 : */
116 : LUNCHBOX_API Result announce( const unsigned short port,
117 : const std::string& instance );
118 :
119 : /** Stop announcing the registered key/value pairs. @version 0.9 */
120 : LUNCHBOX_API void withdraw();
121 :
122 : /** @return true if the local data is announced. @version 0.9 */
123 : LUNCHBOX_API bool isAnnounced() const;
124 :
125 : /**
126 : * Discover all announced key/value pairs.
127 : *
128 : * @param addr the scope of the discovery
129 : * @param browseTime the browse time, in milliseconds, to wait for new
130 : * records.
131 : * @return all instance names found during discovery.
132 : * @version 0.9
133 : * @sa beginBrowsing(), browse(), endBrowsing()
134 : */
135 : LUNCHBOX_API Strings discover( const Interface addr,
136 : const unsigned browseTime );
137 :
138 : /**
139 : * Begin the discovery of announced key/value pairs.
140 : *
141 : * @param addr the scope of the discovery
142 : * @return the success status of the operation.
143 : * @version 1.9.2
144 : */
145 : LUNCHBOX_API Result beginBrowsing( const lunchbox::Servus::Interface addr );
146 :
147 : /**
148 : * Browse and process discovered key/value pairs.
149 : *
150 : * @param timeout The time to spend browsing.
151 : * @return the success status of the operation.
152 : * @version 1.9.2
153 : */
154 : LUNCHBOX_API Result browse( int32_t timeout = -1 );
155 :
156 : /** Stop a discovery process and return all results. @version 1.9.2 */
157 : LUNCHBOX_API void endBrowsing();
158 :
159 : /** @return true if the local data is browsing. @version 1.9.2 */
160 : LUNCHBOX_API bool isBrowsing() const;
161 :
162 : /** @return all instances found during the last discovery. @version 0.9 */
163 : LUNCHBOX_API Strings getInstances() const;
164 :
165 : /** @return all keys discovered on the given instance. @version 0.9 */
166 : LUNCHBOX_API Strings getKeys( const std::string& instance ) const;
167 :
168 : /** @return true if the given key was discovered. @version 0.9 */
169 : LUNCHBOX_API bool containsKey( const std::string& instance,
170 : const std::string& key ) const;
171 :
172 : /** @return the value of the given key and instance. @version 0.9 */
173 : LUNCHBOX_API const std::string& get( const std::string& instance,
174 : const std::string& key ) const;
175 :
176 : /** @internal */
177 : typedef std::map< std::string, std::map< std::string, std::string > > Data;
178 :
179 : /** @internal */
180 : LUNCHBOX_API void getData( Data& data );
181 :
182 : private:
183 : detail::Servus* const _impl;
184 : friend LUNCHBOX_API std::ostream& operator << ( std::ostream&,
185 : const Servus& );
186 : };
187 :
188 : /** Output the servus instance in human-readable format. @version 1.5.1 */
189 : LUNCHBOX_API std::ostream& operator << ( std::ostream&, const Servus& );
190 :
191 : /** Output the servus interface in human-readable format. @version 1.9.2 */
192 : LUNCHBOX_API std::ostream& operator << (std::ostream&,const Servus::Interface&);
193 : }
194 :
195 : #endif // LUNCHBOX_SERVUS_H
|
