Dashel::Hub Class Reference

The central place where to create, destroy, and synchronize streams. More...

`#include <dashel.h>`

## Public Types

typedef std::set< Stream * > | StreamsSet
| A list of streams.

## Public Member Functions

| Hub (const bool resolveIncomingNames=true)
| Constructor. More...
virtual | ~Hub ()
| Destructor, closes all connections.
Stream * | connect (const std::string &target)
| Listens for incoming connections on a target. More...
void | closeStream (Stream *stream)
| Close a stream, remove it from the Hub, and delete it. More...
void | run ()
| Runs and returns only when an external event requests the application to stop.
bool | step (const int timeout=0)
| Waits for data from the transfers streams or connections from the listening streams. More...
void | stop ()
| Stops running, subclasses or external code may call this function, that is the only thread-safe function of the Hub.
void | lock ()
| Block any hub processing so another thread can access the streams safely.
void | unlock ()
| Release the lock aquired by lock().

## Public Attributes

const bool | resolveIncomingNames
| Whether Dashel should try to resolve the peer's hostname of incoming TCP connections.

## Protected Member Functions

virtual void | connectionCreated (Stream *stream)
| Called when any data connection is created. More...
virtual void | incomingData (Stream *stream)
| Called when data is available for reading on the stream. More...
virtual void | connectionClosed (Stream *stream, bool abnormal)
| Called when target closes connection. More...

## Protected Attributes

StreamsSet | dataStreams
| All our streams that transfer data (in opposition to streams that just listen for data).

## Detailed Description

The central place where to create, destroy, and synchronize streams.

To create a client connection, users of the library have to subclass Hub and implement connectionCreated(), incomingData(), and connectionClosed().

## Constructor & Destructor Documentation

Dashel::Hub::Hub | ( | const bool | resolveIncomingNames = `true` | ) |

explicit

Constructor.

Parameters

  resolveIncomingNames | if true, try to resolve the peer's hostname of incoming TCP connections

## Member Function Documentation

void Dashel::Hub::closeStream | ( | Stream * | stream | ) |

Close a stream, remove it from the Hub, and delete it.

If the stream is not present in the Hub, it is deleted nevertheless. Note that connectionClosed() is not called by closeStream() and that you must not call closeStream() from inside connectionCreated(), connectionClosed() or incomingData().

Parameters

  stream | stream to remove

Stream* Dashel::Hub::connect | ( | const std::string & | target | ) |

Listens for incoming connections on a target.

Some targets, such as a serial ports and files may directly generate a new connection; others, such as network interfaces, will only generate news connections when a peer connects. May throw a ConnectionError exception if the target does not exists or is not ready.

Parameters

  target | destination to listen connections from (see Section Targets naming)

Returns
  the stream we are connected to; if connect was not possible, an exception was throw.

virtual void Dashel::Hub::connectionClosed | ( | Stream * | stream,
|  | bool | abnormal
| ) |  |

inline protected virtual

Called when target closes connection.

The only valid method to call on the stream is getTargetName(), input/output operations are forbidden. You must not call closeStream(stream) from within this method for the same stream as the one passed as parameter. Subclass can implement this method. Called with the stream lock held.

Parameters

  stream | stream to the target.
  abnormal | whether the connection was closed during step (abnormal == false) or when an operation was performed (abnormal == true)

virtual void Dashel::Hub::connectionCreated | ( | Stream * | stream | ) |

inline protected virtual

Called when any data connection is created.

It is not called when a listening connection (eg tcpin:) is created. If the stream is closed during this method, an exception occurs: the caller is responsible to handle it. The stream is already inserted in the stream list when this function is called. Subclass can implement this method. Called with the stream lock held.

Parameters

  stream | stream to the target

virtual void Dashel::Hub::incomingData | ( | Stream * | stream | ) |

inline protected virtual

Called when data is available for reading on the stream.

If the stream is closed during this method, an exception occurs: Hub stops the execution of this method and calls connectionClosed(); objects dynamically allocated must thus be handled with auto_ptr. If step() is used, subclass must implement this method and call read at least once. Called with the stream lock held.

Parameters

  stream | stream to the target

bool Dashel::Hub::step | ( | const int | timeout = `0` | ) |

Waits for data from the transfers streams or connections from the listening streams.

Read all available data.

Parameters

  timeout | if -1, waits until data arrive. If 0, do not wait, just poll for activity. If positive, waits at maximum timeout ms.

Returns
  false if stop() was called or the application was requested to terminate, true otherwise.

The documentation for this class was generated from the following file:

- dashel/dashel.h