dashel.h
Go to the documentation of this file.
/*
Dashel
A cross-platform DAta Stream Helper Encapsulation Library
Copyright (C) 2007 -- 2017:
Stephane Magnenat <stephane at magnenat dot net>
(http://stephane.magnenat.net)
Mobots group - Laboratory of Robotics Systems, EPFL, Lausanne
(http://mobots.epfl.ch)
Sebastian Gerlach
Kenzan Technologies
(http://www.kenzantech.com)
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the names of "Mobots", "Laboratory of Robotics Systems", "EPFL",
"Kenzan Technologies" nor the names of the contributors may be used to
endorse or promote products derived from this software without specific
prior written permission.
THIS SOFTWARE IS PROVIDED BY COPYRIGHT HOLDERS ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef __Dashel_H
#define __Dashel_H
#include <string>
#include <set>
#include <map>
#include <vector>
#include <deque>
#include <stdexcept>
namespace Dashel
{
class Stream;
#define DASHEL_VERSION "1.3.3"
#define DASHEL_VERSION_INT 10301
class DashelException: public std::runtime_error
{
public:
typedef enum {
Unknown,
SyncError,
InvalidTarget,
InvalidOperation,
ConnectionLost,
IOError,
ConnectionFailed,
EnumerationError,
PreviousIncomingDataNotRead
} Source;
Source source;
int sysError;
Stream *stream;
public:
DashelException(Source s, int se, const char *reason, Stream* stream = NULL);
protected:
static std::string sourceToString(Source s);
};
class SerialPortEnumerator
{
public:
static std::map<int, std::pair<std::string, std::string> > getPorts();
};
class IPV4Address
{
public:
unsigned address;
unsigned short port;
public:
IPV4Address(unsigned addr = 0, unsigned short prt = 0);
IPV4Address(const std::string& name, unsigned short port);
bool operator==(const IPV4Address& o) const;
bool operator<(const IPV4Address& o) const;
std::string format(const bool resolveName = true) const;
std::string hostname() const;
//bool isValid() const;
};
class ParameterSet
{
private:
std::map<std::string, std::string> values;
std::vector<std::string> params;
public:
void add(const char *line);
void addParam(const char *param, const char *value = NULL, bool atStart = false);
bool isSet(const char *key) const;
template<typename T> T get(const char *key) const;
const std::string& get(const char *key) const;
std::string getString() const;
void erase(const char *key);
};
class Stream
{
private:
bool failedFlag;
std::string failReason;
protected:
ParameterSet target;
std::string protocolName;
protected:
friend class Hub;
explicit Stream(const std::string& protocolName) : failedFlag(false), protocolName(protocolName) {}
virtual ~Stream() { /* intentionally blank */ }
public:
void fail(DashelException::Source s, int se, const char* reason);
bool failed() const { return failedFlag; }
const std::string &getFailReason() const { return failReason; }
const std::string &getProtocolName() const { return protocolName; }
std::string getTargetName() const { return protocolName + ":" + target.getString(); }
const std::string &getTargetParameter(const char *param) const { return target.get(param); }
const ParameterSet getTarget() const { return target; }
virtual void write(const void *data, const size_t size) = 0;
template<typename T> void write(T v)
{
write(&v, sizeof(T));
}
virtual void flush() = 0;
virtual void read(void *data, size_t size) = 0;
template<typename T> T read()
{
T v;
read(&v, sizeof(T));
return v;
}
};
class PacketStream: virtual public Stream
{
public:
explicit PacketStream(const std::string& protocolName) : Stream(protocolName) { }
virtual void send(const IPV4Address& dest) = 0;
virtual void receive(IPV4Address& source) = 0;
};
class Hub
{
public:
typedef std::set<Stream*> StreamsSet;
private:
void *hTerminate;
void *streamsLock;
StreamsSet streams;
protected:
StreamsSet dataStreams;
public:
const bool resolveIncomingNames;
public:
explicit Hub(const bool resolveIncomingNames = true);
virtual ~Hub();
Stream* connect(const std::string &target);
void closeStream(Stream* stream);
void run();
bool step(const int timeout = 0);
void stop();
void lock();
void unlock();
protected:
virtual void connectionCreated(Stream * stream) { /* hook for use by derived classes */ }
virtual void incomingData(Stream * stream) { /* hook for use by derived classes */ }
virtual void connectionClosed(Stream * stream, bool abnormal) { /* hook for use by derived classes */ }
};
struct StreamTypeRegistry
{
typedef Stream* (*CreatorFunc)(const std::string& target, const Hub& hub);
StreamTypeRegistry();
void reg(const std::string& proto, const CreatorFunc func);
Stream* create(const std::string& proto, const std::string& target, const Hub& hub) const;
std::string list() const;
protected:
typedef std::map<std::string, CreatorFunc> CreatorMap;
CreatorMap creators;
};
template<typename C>
Stream* createInstance(const std::string& target, const Hub& hub)
{
return new C(target);
}
template<typename C>
Stream* createInstanceWithHub(const std::string& target, const Hub& hub)
{
return new C(target, hub);
}
extern StreamTypeRegistry streamTypeRegistry;
}
#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.