Line data Source code
1 :
2 : /* Copyright (c) 2012-2013, 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
37 : * pairs using ZeroConf networking. The same instance can be used to announce
38 : * and/or to browse a ZeroConf service. If the Lunchbox library is compiled
39 : * without zeroconf support (LUNCHBOX_USE_DNSSD is not set), this class does not
40 : * do anything useful.
41 : *
42 : * Example: @include tests/servus.cpp
43 : */
44 : class Servus : public boost::noncopyable
45 : {
46 : public:
47 : enum Interface
48 : {
49 : IF_ALL = 0, //!< use all interfaces
50 : // (uint32_t) -1 == kDNSServiceInterfaceIndexLocalOnly
51 : IF_LOCAL = (unsigned)(-1) //!< only local interfaces
52 : };
53 :
54 : /**
55 : * The ZeroConf operation result code.
56 : *
57 : * The result code is either one of kDNSServiceErr_ or one of static
58 : * constants defined by this class
59 : */
60 6 : class Result : public lunchbox::Result
61 : {
62 : public:
63 10 : explicit Result( const int32_t code ) : lunchbox::Result( code ){}
64 16 : virtual ~Result(){}
65 : LUNCHBOX_API std::string getString() const override;
66 :
67 : /** operation did not complete. */
68 : static const int32_t PENDING = -1;
69 : /** Lunchbox compiled without ZeroConf support. */
70 : static const int32_t NOT_SUPPORTED = -2;
71 : };
72 :
73 : /**
74 : * Create a new service handle.
75 : *
76 : * @param name the service descriptor, e.g., "_gpu-sd._tcp"
77 : * @version 0.9
78 : */
79 : LUNCHBOX_API explicit Servus( const std::string& name );
80 :
81 : /** Destruct this service. */
82 : LUNCHBOX_API virtual ~Servus();
83 :
84 : /**
85 : * Set a key/value pair to be announced.
86 : *
87 : * Keys should be at most eight characters, and values are truncated to 255
88 : * characters. The total length of all keys and values cannot exceed 65535
89 : * characters. Setting a value on an announced service causes an update
90 : * which needs some time to propagate after this function returns, that is,
91 : * calling discover() immediately afterwards will very likely not contain
92 : * the new key/value pair.
93 : *
94 : * @version 0.9
95 : */
96 : LUNCHBOX_API void set( const std::string& key, const std::string& value );
97 :
98 : /** @return all (to be) announced keys. @version 1.5.1 */
99 : LUNCHBOX_API Strings getKeys() const;
100 :
101 : /** @return the value to the given (to be) announced key. @version 1.5.1 */
102 : LUNCHBOX_API const std::string& get( const std::string& key ) const;
103 :
104 : /**
105 : * Start announcing the registered key/value pairs.
106 : *
107 : * @param port the service IP port in host byte order.
108 : * @param instance a host-unique instance name, hostname is used if empty.
109 : * @return the success status of the operation.
110 : * @version 0.9
111 : */
112 : LUNCHBOX_API Result announce( const unsigned short port,
113 : const std::string& instance );
114 :
115 : /** Stop announcing the registered key/value pairs. @version 0.9 */
116 : LUNCHBOX_API void withdraw();
117 :
118 : /** @return true if the local data is announced. @version 0.9 */
119 : LUNCHBOX_API bool isAnnounced() const;
120 :
121 : /**
122 : * Discover all announced key/value pairs.
123 : *
124 : * @param addr the scope of the discovery
125 : * @param browseTime the browse time, in milliseconds, to wait for new
126 : * records.
127 : * @return all instance names found during discovery.
128 : * @version 0.9
129 : */
130 : LUNCHBOX_API Strings discover( const Interface addr,
131 : const unsigned browseTime );
132 :
133 : /** @return all instances found during the last discovery. @version 0.9 */
134 : LUNCHBOX_API Strings getInstances() const;
135 :
136 : /** @return all keys discovered on the given instance. @version 0.9 */
137 : LUNCHBOX_API Strings getKeys( const std::string& instance ) const;
138 :
139 : /** @return true if the given key was discovered. @version 0.9 */
140 : LUNCHBOX_API bool containsKey( const std::string& instance,
141 : const std::string& key ) const;
142 :
143 : /** @return the value of the given key and instance. @version 0.9 */
144 : LUNCHBOX_API const std::string& get( const std::string& instance,
145 : const std::string& key ) const;
146 :
147 : /** @internal */
148 : typedef std::map< std::string, std::map< std::string, std::string > > Data;
149 :
150 : /** @internal */
151 : LUNCHBOX_API void getData( Data& data );
152 :
153 : private:
154 : detail::Servus* const impl_;
155 : };
156 :
157 : /** Output the servus instance in human-readable format. @version 1.5.1 */
158 : LUNCHBOX_API std::ostream& operator << ( std::ostream&, const Servus& );
159 : }
160 :
161 : #endif // LUNCHBOX_SERVUS_H
|
