OpenCurves  0.9
RealTimeCommSpec Class Reference

Specifies a real time communication specification, messaging and buffer setup. More...

#include <realtimecommspec.h>

Public Member Functions

 RealTimeCommSpec ()
 Create an empty comm-spec.
 
 ~RealTimeCommSpec ()
 Destroy the comm-spec. Only deletes the wrapped classes (no disconnect).
 
void setConnection (RealTimeConnection *connection)
 Set the connection details, deleting and replacing any existing connection. More...
 
RealTimeConnectionconnection () const
 Access the connection. More...
 
void setConnectMessage (RTMessage *msg)
 Set the connection message, deleting and replacing any existing connection message. More...
 
const RTMessageconnectMessage () const
 Access the current connection message. More...
 
void setDisconnectMessage (RTMessage *msg)
 Set the disconnect message, deleting and replacing any existing disconnect message. More...
 
const RTMessagedisconnectMessage () const
 Access the current disconnect message. More...
 
void setIncomingMessage (RTMessage *msg)
 Set details of the expected incoming messages deleting and replacing any such existing specification. More...
 
RTMessageincomingMessage () const
 Access the current disconnect message. More...
 
void setBufferSize (unsigned size)
 Set the requested plot buffer size for incoming data. More...
 
unsigned bufferSize () const
 Access the requested buffer size for incoming sample data buffering. More...
 
void setTimeColumn (unsigned columnNumber)
 Set the expected time column number. More...
 
unsigned timeColumn () const
 Access the time column. More...
 
void setTimeScale (double scale)
 Sets the time scaling value. More...
 
double timeScale () const
 Access the time scale value. More...
 
void disconnect ()
 Send disconnect message and disconnect the connection. More...
 

Detailed Description

Specifies a real time communication specification, messaging and buffer setup.

The specification collates the RealTimeConnection and the RTMessage definitions to use with the connection. It also includes expected timing details for the incoming data series.

The messaging may include three messages:

  • A specification for the incoming messages (required).
  • A message to send on establishing a connection (optional).
  • A message to send just prior to disconnecting (optional).

The comm-spec may represent either a binary or text-based connection, but this depends entirely on the RTMessage objects belonging to the comm-spec. The two primary implementations are RTBinaryMessage and RTStringMessage.

This object only serves to collate these messages and the connection, but does not manage the messaging, except that as a convenience, the disconnect() function sends the disconnectMessage() and calls disconnect on the connection.

The code managing the connection communications is responsible for sending the connectMessage() message and processing incoming data using incommingMessage().

Member Function Documentation

unsigned RealTimeCommSpec::bufferSize ( ) const
inline

Access the requested buffer size for incoming sample data buffering.

Returns
The requested buffer size in data sample elements.
RealTimeConnection * RealTimeCommSpec::connection ( ) const
inline

Access the connection.

Must not be null for a valid and complete comm-spec.

Returns
The connection implementation.
const RTMessage * RealTimeCommSpec::connectMessage ( ) const
inline

Access the current connection message.

May be null.

Returns
The connection message, or null when no such message is required.
void RealTimeCommSpec::disconnect ( )

Send disconnect message and disconnect the connection.

This is a convenience function for managing disconnection. Before disconnecting, this function sends the disconnectMessage() if a valid message has been associated with the comm-spec. The RealTimeConnection::disconnect() message is then called.

The function does nothing if there is no connection or if RealTimeConnection::isConnected() returns false.

const RTMessage * RealTimeCommSpec::disconnectMessage ( ) const
inline

Access the current disconnect message.

May be null.

Returns
The disconnect message, or null when no such message is required.
RTMessage * RealTimeCommSpec::incomingMessage ( ) const
inline

Access the current disconnect message.

Must not be null for a valid and complete comm-spec.

Returns
The incoming data message, or null if not set yet.
void RealTimeCommSpec::setBufferSize ( unsigned  size)
inline

Set the requested plot buffer size for incoming data.

This controls the number of samples to store before discarding the oldest sample.

The comm-spec only holds this information and does not apply it. It is used by @ PlotInstance objects to manage a ring buffer of this size.

Parameters
sizeThe requested buffer size in data samples.
void RealTimeCommSpec::setConnection ( RealTimeConnection connection)

Set the connection details, deleting and replacing any existing connection.

Parameters
connectionThe new connection
void RealTimeCommSpec::setConnectMessage ( RTMessage msg)

Set the connection message, deleting and replacing any existing connection message.

The connection message must be sent on establishing a connection. For example, this may be used to request data streaming begin over the connection.

Parameters
msgThe new connection message.
void RealTimeCommSpec::setDisconnectMessage ( RTMessage msg)

Set the disconnect message, deleting and replacing any existing disconnect message.

The connection message must be sent priori to disconnecting. For example, this may be used to request data streaming begin over the connection. The disconnect() function may be used as a convenience.

Parameters
msgThe new disconnect message.
void RealTimeCommSpec::setIncomingMessage ( RTMessage msg)

Set details of the expected incoming messages deleting and replacing any such existing specification.

The incoming message handles incoming data, converting incoming data to time series values. See implementations of RTMessage for details.

Parameters
msgThe new incoming data message.
void RealTimeCommSpec::setTimeColumn ( unsigned  columnNumber)
inline

Set the expected time column number.

This identifies the time column for incoming data. It is a one-based index with a zero value indicating there is no time column.

Parameters
columnNumberThe one-based index for the time column.
void RealTimeCommSpec::setTimeScale ( double  scale)
inline

Sets the time scaling value.

All values in the time column are multiplied by this scale before publishing the actual time value. For example, this may be used to convert from a microsecond timestamp to seconds by setting the value to 1e-6.

Parameters
scaleThe time scaling multiplier. Must not be zero.
unsigned RealTimeCommSpec::timeColumn ( ) const
inline

Access the time column.

Returns
The one-based index of the time column, or zero for no time column.
double RealTimeCommSpec::timeScale ( ) const
inline

Access the time scale value.

See also
setTimeScale()
Returns
The time scaling multiplier.

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