dashel  1.3.3
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 {
165  } Source;
166 
168  Source source;
170  int sysError;
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 
192  {
193  public:
195 
201  static std::map<int, std::pair<std::string, std::string> > getPorts();
202  };
203 
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 
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:
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 
537  {
539  typedef Stream* (*CreatorFunc)(const std::string& target, const Hub& hub);
540 
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 
576 }
577 
578 #endif
A data stream, that can be later send data as at UDP packet or read data from an UDP packet...
Definition: dashel.h:396
Some I/O error.
Definition: dashel.h:161
Stream(const std::string &protocolName)
Constructor.
Definition: dashel.h:293
const ParameterSet getTarget() const
Returns the target description.
Definition: dashel.h:335
const std::string & getTargetParameter(const char *param) const
Returns the value of a parameter extracted from the target.
Definition: dashel.h:330
virtual void connectionClosed(Stream *stream, bool abnormal)
Called when target closes connection.
Definition: dashel.h:532
The central place where to create, destroy, and synchronize streams.
Definition: dashel.h:422
bool failed() const
Query failed state of stream.
Definition: dashel.h:309
virtual void incomingData(Stream *stream)
Called when data is available for reading on the stream.
Definition: dashel.h:519
The target string was bad.
Definition: dashel.h:158
const bool resolveIncomingNames
Whether Dashel should try to resolve the peer&#39;s hostname of incoming TCP connections.
Definition: dashel.h:437
A IP version 4 address.
Definition: dashel.h:205
static std::string sourceToString(Source s)
Return a string description of the source error.
Parameter set.
Definition: dashel.h:238
void write(T v)
Write a variable of basic type to the stream.
Definition: dashel.h:352
A data stream, with low-level (not-endian safe) read/write functions.
Definition: dashel.h:274
Source source
The exception cause.
Definition: dashel.h:168
The connection was lost.
Definition: dashel.h:160
ParameterSet target
The target description.
Definition: dashel.h:284
Serial port enumerator class.
Definition: dashel.h:191
CreatorMap creators
streams that can be created
Definition: dashel.h:557
The one size fits all exception for streams.
Definition: dashel.h:151
StreamTypeRegistry streamTypeRegistry
The registry of all known stream types.
Dashel, a cross-platform stream abstraction library.
Definition: dashel.h:138
The operation is not valid on this stream.
Definition: dashel.h:159
DashelException(Source s, int se, const char *reason, Stream *stream=NULL)
Construct an stream exception with everything.
The incoming data was not read by the Hub subclass.
Definition: dashel.h:164
unsigned address
IP host address. Stored in local byte order.
Definition: dashel.h:208
T read()
Read a variable of basic type from the stream.
Definition: dashel.h:379
Well, hopefully never used.
Definition: dashel.h:156
unsigned short port
IP port. Stored in local byte order.
Definition: dashel.h:209
StreamsSet dataStreams
All our streams that transfer data (in opposition to streams that just listen for data)...
Definition: dashel.h:434
const std::string & getFailReason() const
Returns the reason the stream has failed.
Definition: dashel.h:314
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
Some synchronisation error.
Definition: dashel.h:157
std::set< Stream * > StreamsSet
A list of streams.
Definition: dashel.h:426
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
virtual ~Stream()
Virtual destructor, to ensure calls to destructors of sub-classes.
Definition: dashel.h:296
int sysError
The reason as an OS error code.
Definition: dashel.h:170
T get(const char *key) const
Get a parameter value.
const std::string & getProtocolName() const
Returns the protocol name of the stream.
Definition: dashel.h:317
virtual void connectionCreated(Stream *stream)
Called when any data connection is created.
Definition: dashel.h:507
std::map< std::string, CreatorFunc > CreatorMap
a map of stream type names to constructors and arguments
Definition: dashel.h:555
Registry of constructors to a stream, to add new stream types dynamically.
Definition: dashel.h:536
Some serial enumeration error.
Definition: dashel.h:163
std::string getTargetName() const
Returns the name of the target.
Definition: dashel.h:324
Stream * stream
The stream that caused the exception to be thrown.
Definition: dashel.h:172
Source
The different exception causes.
Definition: dashel.h:155
PacketStream(const std::string &protocolName)
Constructor.
Definition: dashel.h:400
std::string protocolName
The protocol name.
Definition: dashel.h:286
The connection could not be established.
Definition: dashel.h:162
std::string getString() const
Get the parameters as string.