dashel: dashel/dashel.h Source File

dashel 1.3.3

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

dashel.h
Go to the documentation of this file.
1 /*
2 Dashel
3 A cross-platform DAta Stream Helper Encapsulation Library
4 Copyright (C) 2007 -- 2017:
5
6 Stephane Magnenat <stephane at magnenat dot net>
7 (http://stephane.magnenat.net)
8 Mobots group - Laboratory of Robotics Systems, EPFL, Lausanne
9 (http://mobots.epfl.ch)
10
11 Sebastian Gerlach
12 Kenzan Technologies
13 (http://www.kenzantech.com)
14
15 All rights reserved.
16
17 Redistribution and use in source and binary forms, with or without
18 modification, are permitted provided that the following conditions are met:
19 * Redistributions of source code must retain the above copyright
20 notice, this list of conditions and the following disclaimer.
21 * Redistributions in binary form must reproduce the above copyright
22 notice, this list of conditions and the following disclaimer in the
23 documentation and/or other materials provided with the distribution.
24 * Neither the names of "Mobots", "Laboratory of Robotics Systems", "EPFL",
25 "Kenzan Technologies" nor the names of the contributors may be used to
26 endorse or promote products derived from this software without specific
27 prior written permission.
28
29 THIS SOFTWARE IS PROVIDED BY COPYRIGHT HOLDERS ``AS IS'' AND ANY
30 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
31 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
32 DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS BE LIABLE FOR ANY
33 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
35 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
36 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
38 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 */
40
41 #ifndef __Dashel_H
42 #define __Dashel_H
43
44 #include <string>
45 #include <set>
46 #include <map>
47 #include <vector>
48 #include <deque>
49 #include <stdexcept>
50
137 namespace Dashel
139 {
140 class Stream;
141
143 #define DASHEL_VERSION "1.3.3"
144 #define DASHEL_VERSION_INT 10301
146
148
151 class DashelException: public std::runtime_error
152 {
153 public:
155 typedef enum {
156 Unknown,
157 SyncError,
158 InvalidTarget,
159 InvalidOperation,
160 ConnectionLost,
161 IOError,
162 ConnectionFailed,
163 EnumerationError,
164 PreviousIncomingDataNotRead
165 } Source;
166
168 Source source;
170 int sysError;
172 Stream *stream;
173
174 public:
176
181 DashelException(Source s, int se, const char *reason, Stream* stream = NULL);
182
183 protected:
185 static std::string sourceToString(Source s);
186 };
187
189
191 class SerialPortEnumerator
192 {
193 public:
195
201 static std::map<int, std::pair<std::string, std::string> > getPorts();
202 };
203
205 class IPV4Address
206 {
207 public:
208 unsigned address;
209 unsigned short port;
210
211 public:
213 IPV4Address(unsigned addr = 0, unsigned short prt = 0);
214
216 IPV4Address(const std::string& name, unsigned short port);
217
219 bool operator==(const IPV4Address& o) const;
220
222 bool operator<(const IPV4Address& o) const;
223
225
228 std::string format(const bool resolveName = true) const;
229
231 std::string hostname() const;
232
234 //bool isValid() const;
235 };
236
238 class ParameterSet
239 {
240 private:
241 std::map<std::string, std::string> values;
242 std::vector<std::string> params;
243
244 public:
246 void add(const char *line);
247
249
254 void addParam(const char *param, const char *value = NULL, bool atStart = false);
255
257 bool isSet(const char *key) const;
258
261 template<typename T> T get(const char *key) const;
262
264 const std::string& get(const char *key) const;
265
267 std::string getString() const;
268
270 void erase(const char *key);
271 };
272
274 class Stream
275 {
276 private:
278 bool failedFlag;
280 std::string failReason;
281
282 protected:
284 ParameterSet target;
286 std::string protocolName;
287
288 protected:
289
290 friend class Hub;
291
293 explicit Stream(const std::string& protocolName) : failedFlag(false), protocolName(protocolName) {}
294
296 virtual ~Stream() { /* intentionally blank */ }
297
298 public:
300
304 void fail(DashelException::Source s, int se, const char* reason);
305
307
309 bool failed() const { return failedFlag; }
310
312
314 const std::string &getFailReason() const { return failReason; }
315
317 const std::string &getProtocolName() const { return protocolName; }
318
320
324 std::string getTargetName() const { return protocolName + ":" + target.getString(); }
325
327
330 const std::string &getTargetParameter(const char *param) const { return target.get(param); }
331
333
335 const ParameterSet getTarget() const { return target; }
336
338
346 virtual void write(const void *data, const size_t size) = 0;
347
349
352 template<typename T> void write(T v)
353 {
354 write(&v, sizeof(T));
355 }
356
358
362 virtual void flush() = 0;
363
365
372 virtual void read(void *data, size_t size) = 0;
373
375
379 template<typename T> T read()
380 {
381 T v;
382 read(&v, sizeof(T));
383 return v;
384 }
385 };
386
388
396 class PacketStream: virtual public Stream
397 {
398 public:
400 explicit PacketStream(const std::string& protocolName) : Stream(protocolName) { }
401
403
406 virtual void send(const IPV4Address& dest) = 0;
407
409
414 virtual void receive(IPV4Address& source) = 0;
415 };
416
422 class Hub
423 {
424 public:
426 typedef std::set<Stream*> StreamsSet;
427
428 private:
429 void *hTerminate;
430 void *streamsLock;
431 StreamsSet streams;
432
433 protected:
434 StreamsSet dataStreams;
435
436 public:
437 const bool resolveIncomingNames;
438
439 public:
443 explicit Hub(const bool resolveIncomingNames = true);
444
446 virtual ~Hub();
447
458 Stream* connect(const std::string &target);
459
469 void closeStream(Stream* stream);
470
473 void run();
474
482 bool step(const int timeout = 0);
483
485 void stop();
486
489 void lock();
490
493 void unlock();
494
495 protected:
496
507 virtual void connectionCreated(Stream * stream) { /* hook for use by derived classes */ }
508
519 virtual void incomingData(Stream * stream) { /* hook for use by derived classes */ }
520
532 virtual void connectionClosed(Stream * stream, bool abnormal) { /* hook for use by derived classes */ }
533 };
534
536 struct StreamTypeRegistry
537 {
539 typedef Stream* (*CreatorFunc)(const std::string& target, const Hub& hub);
540
542 StreamTypeRegistry();
543
545 void reg(const std::string& proto, const CreatorFunc func);
546
548 Stream* create(const std::string& proto, const std::string& target, const Hub& hub) const;
549
551 std::string list() const;
552
553 protected:
555 typedef std::map<std::string, CreatorFunc> CreatorMap;
557 CreatorMap creators;
558 };
559
561 template<typename C>
562 Stream* createInstance(const std::string& target, const Hub& hub)
563 {
564 return new C(target);
565 }
566
568 template<typename C>
569 Stream* createInstanceWithHub(const std::string& target, const Hub& hub)
570 {
571 return new C(target, hub);
572 }
573
575 extern StreamTypeRegistry streamTypeRegistry;
576 }
577
578 #endif
Dashel::PacketStream
A data stream, that can be later send data as at UDP packet or read data from an UDP packet...
Definition: dashel.h:396
Dashel::DashelException::IOError
Some I/O error.
Definition: dashel.h:161
Dashel::Stream::Stream
Stream(const std::string &protocolName)
Constructor.
Definition: dashel.h:293
Dashel::Stream::getTarget
const ParameterSet getTarget() const
Returns the target description.
Definition: dashel.h:335
Dashel::Stream::getTargetParameter
const std::string & getTargetParameter(const char *param) const
Returns the value of a parameter extracted from the target.
Definition: dashel.h:330
Dashel::Hub::connectionClosed
virtual void connectionClosed(Stream *stream, bool abnormal)
Called when target closes connection.
Definition: dashel.h:532
Dashel::Hub
The central place where to create, destroy, and synchronize streams.
Definition: dashel.h:422
Dashel::Stream::failed
bool failed() const
Query failed state of stream.
Definition: dashel.h:309
Dashel::Hub::incomingData
virtual void incomingData(Stream *stream)
Called when data is available for reading on the stream.
Definition: dashel.h:519
Dashel::DashelException::InvalidTarget
The target string was bad.
Definition: dashel.h:158
Dashel::Hub::resolveIncomingNames
const bool resolveIncomingNames
Whether Dashel should try to resolve the peer&#39;s hostname of incoming TCP connections.
Definition: dashel.h:437
Dashel::IPV4Address
A IP version 4 address.
Definition: dashel.h:205
Dashel::DashelException::sourceToString
static std::string sourceToString(Source s)
Return a string description of the source error.
Dashel::ParameterSet
Parameter set.
Definition: dashel.h:238
Dashel::Stream::write
void write(T v)
Write a variable of basic type to the stream.
Definition: dashel.h:352
Dashel::Stream
A data stream, with low-level (not-endian safe) read/write functions.
Definition: dashel.h:274
Dashel::DashelException::source
Source source
The exception cause.
Definition: dashel.h:168
Dashel::DashelException::ConnectionLost
The connection was lost.
Definition: dashel.h:160
Dashel::Stream::target
ParameterSet target
The target description.
Definition: dashel.h:284
Dashel::SerialPortEnumerator
Serial port enumerator class.
Definition: dashel.h:191
Dashel::StreamTypeRegistry::creators
CreatorMap creators
streams that can be created
Definition: dashel.h:557
Dashel::DashelException
The one size fits all exception for streams.
Definition: dashel.h:151
Dashel::streamTypeRegistry
StreamTypeRegistry streamTypeRegistry
The registry of all known stream types.
Dashel
Dashel, a cross-platform stream abstraction library.
Definition: dashel.h:138
Dashel::DashelException::InvalidOperation
The operation is not valid on this stream.
Definition: dashel.h:159
Dashel::DashelException::DashelException
DashelException(Source s, int se, const char *reason, Stream *stream=NULL)
Construct an stream exception with everything.
Dashel::DashelException::PreviousIncomingDataNotRead
The incoming data was not read by the Hub subclass.
Definition: dashel.h:164
Dashel::IPV4Address::address
unsigned address
IP host address. Stored in local byte order.
Definition: dashel.h:208
Dashel::Stream::read
T read()
Read a variable of basic type from the stream.
Definition: dashel.h:379
Dashel::DashelException::Unknown
Well, hopefully never used.
Definition: dashel.h:156
Dashel::IPV4Address::port
unsigned short port
IP port. Stored in local byte order.
Definition: dashel.h:209
Dashel::Hub::dataStreams
StreamsSet dataStreams
All our streams that transfer data (in opposition to streams that just listen for data)...
Definition: dashel.h:434
Dashel::Stream::getFailReason
const std::string & getFailReason() const
Returns the reason the stream has failed.
Definition: dashel.h:314
Dashel::createInstanceWithHub
Stream * createInstanceWithHub(const std::string &target, const Hub &hub)
Create an instance of stream type C, passing target to its constructor.
Definition: dashel.h:569
Dashel::DashelException::SyncError
Some synchronisation error.
Definition: dashel.h:157
Dashel::Hub::StreamsSet
std::set< Stream * > StreamsSet
A list of streams.
Definition: dashel.h:426
Dashel::createInstance
Stream * createInstance(const std::string &target, const Hub &hub)
Create an instance of stream type C, passing target to its constructor.
Definition: dashel.h:562
Dashel::Stream::~Stream
virtual ~Stream()
Virtual destructor, to ensure calls to destructors of sub-classes.
Definition: dashel.h:296
Dashel::DashelException::sysError
int sysError
The reason as an OS error code.
Definition: dashel.h:170
Dashel::ParameterSet::get
T get(const char *key) const
Get a parameter value.
Dashel::Stream::getProtocolName
const std::string & getProtocolName() const
Returns the protocol name of the stream.
Definition: dashel.h:317
Dashel::Hub::connectionCreated
virtual void connectionCreated(Stream *stream)
Called when any data connection is created.
Definition: dashel.h:507
Dashel::StreamTypeRegistry::CreatorMap
std::map< std::string, CreatorFunc > CreatorMap
a map of stream type names to constructors and arguments
Definition: dashel.h:555
Dashel::StreamTypeRegistry
Registry of constructors to a stream, to add new stream types dynamically.
Definition: dashel.h:536
Dashel::DashelException::EnumerationError
Some serial enumeration error.
Definition: dashel.h:163
Dashel::Stream::getTargetName
std::string getTargetName() const
Returns the name of the target.
Definition: dashel.h:324
Dashel::DashelException::stream
Stream * stream
The stream that caused the exception to be thrown.
Definition: dashel.h:172
Dashel::DashelException::Source
Source
The different exception causes.
Definition: dashel.h:155
Dashel::PacketStream::PacketStream
PacketStream(const std::string &protocolName)
Constructor.
Definition: dashel.h:400
Dashel::Stream::protocolName
std::string protocolName
The protocol name.
Definition: dashel.h:286
Dashel::DashelException::ConnectionFailed
The connection could not be established.
Definition: dashel.h:162
Dashel::ParameterSet::getString
std::string getString() const
Get the parameters as string.