Connects to an instrument profile URL and reads instrument profiles with support of streaming live updates. More...

#include <InstrumentProfileConnection.hpp>

Inheritance diagram for dxfcpp::InstrumentProfileConnection:

Public Types
enum class	State : std::int32_t { NOT_CONNECTED , CONNECTING , CONNECTED , COMPLETED , CLOSED }
	Instrument profile connection state. More...

using	Ptr = std::shared_ptr<InstrumentProfileConnection>
	The alias to a type of shared pointer to the InstrumentProfileConnection object.

using	Unique = std::unique_ptr<InstrumentProfileConnection>
	The alias to a type of unique pointer to the InstrumentProfileConnection object.

Public Types inherited from dxfcpp::SharedEntity
using	Ptr = std::shared_ptr<SharedEntity>
	The alias to a type of shared pointer to the SharedEntity object.

Public Member Functions
std::string	getAddress () const noexcept
	Returns the address of this instrument profile connection.

std::int64_t	getUpdatePeriod () const noexcept
	Returns update period in milliseconds.

std::chrono::milliseconds	getUpdatePeriodAsDuration () const noexcept
	Returns update period in milliseconds as chrono::duration It is period of an update check when the instrument profiles source does not support live updates and/or when connection is dropped.

void	setUpdatePeriod (std::int64_t updatePeriod) const noexcept
	Changes the update period in milliseconds.

void	setUpdatePeriod (std::chrono::milliseconds updatePeriod) const noexcept
	Changes the update period in milliseconds as chrono::duration.

State	getState () const noexcept
	Returns state of this instrument profile connections.

std::int64_t	getLastModified () const noexcept
	Returns last modification time (in milliseconds) of instrument profiles or zero if it is unknown.

void	start () const noexcept
	Starts this instrument profile connection.

void	close () const noexcept
	Closes this instrument profile connection.

template<typename StateChangeListener >
std::size_t	addStateChangeListener (StateChangeListener &&listener) noexcept
	Adds listener that is notified about changes in state property.

void	removeStateChangeListener (std::size_t listenerId) noexcept
	Removes listener that is notified about changes in state property.

auto &	onStateChange () noexcept
	Returns the onStateChange handler that can be used to add or remove listeners.

bool	waitUntilCompleted (std::int64_t timeout) const noexcept
	Synchronously waits for full first snapshot read with the specified timeout.

bool	waitUntilCompleted (std::chrono::milliseconds timeout) const noexcept
	Synchronously waits for full first snapshot read with the specified timeout.

Public Member Functions inherited from dxfcpp::SharedEntity
template<typename T >
bool	is () const noexcept
	Checks that pointer to the current type could be converted to type T* In other words: whether type T belongs to the type hierarchy in which the current type resides.

template<typename T >
std::shared_ptr< T >	sharedAs () noexcept
	Returns a pointer to the current object wrapped in a smart pointer to type T.

template<typename T >
std::shared_ptr< T >	sharedAs () const noexcept
	Returns a pointer to the current object wrapped in a smart pointer to type T.

virtual std::string	toString () const noexcept
	Returns a string representation of the current object.

Public Member Functions inherited from dxfcpp::Entity
virtual	~Entity () noexcept=default
	The default virtual d-tor.

Static Public Member Functions
static Ptr	createConnection (const std::string &address, InstrumentProfileCollector::Ptr collector) noexcept
	Creates instrument profile connection with a specified address and collector.

Detailed Description

Connects to an instrument profile URL and reads instrument profiles with support of streaming live updates.

Please see Instrument Profile Format documentation for complete description.

Member Enumeration Documentation

◆ State

enum class dxfcpp::InstrumentProfileConnection::State : std::int32_t

strong

Instrument profile connection state.

Enumerator
NOT_CONNECTED	Instrument profile connection is not started yet. start was not invoked yet.
CONNECTING	Connection is being established.
CONNECTED	Connection was established.
COMPLETED	Initial instrument profiles snapshot was fully read (this state is set only once).
CLOSED	Instrument profile connection was closed.

Member Function Documentation

◆ addStateChangeListener()

template<typename StateChangeListener >

std::size_t dxfcpp::InstrumentProfileConnection::addStateChangeListener ( StateChangeListener && listener )

inlinenoexcept

Adds listener that is notified about changes in state property.

Installed listener can be removed by id with InstrumentProfileConnection::removeStateChangeListener method or by call InstrumentProfileConnection::onStateChange() -= id;

Template Parameters

StateChangeListener The listener type. It can be any callable with signature: void(State, State)

Parameters

listener The listener to add

Returns: the listener id

◆ close()

void dxfcpp::InstrumentProfileConnection::close ( ) const

noexcept

Closes this instrument profile connection.

This connection's state immediately changes to CLOSED and the background update procedures are terminated.

◆ createConnection()

InstrumentProfileConnection::Ptr dxfcpp::InstrumentProfileConnection::createConnection	(	const std::string &	address,
		InstrumentProfileCollector::Ptr	collector )

staticnoexcept

Creates instrument profile connection with a specified address and collector.

Address may be just "<host>:<port>" of server, URL, or a file path. The "[update=<period>]" clause can be optionally added at the end of the address to specify an update period via an address string. Default update period is 1 minute.

Connection needs to be started to begin an actual operation.

Parameters

address	The address.
collector	The instrument profile collector to push updates into.

Returns: new instrument profile connection.

◆ getAddress()

std::string dxfcpp::InstrumentProfileConnection::getAddress ( ) const

noexcept

Returns the address of this instrument profile connection.

It does not include additional options specified as part of the address.

Returns: The address of this instrument profile connection.

◆ getLastModified()

std::int64_t dxfcpp::InstrumentProfileConnection::getLastModified ( ) const

noexcept

Returns last modification time (in milliseconds) of instrument profiles or zero if it is unknown.

Note, that while the time is represented in milliseconds, the actual granularity of time here is a second.

Returns: The last modification time (in milliseconds) of instrument profiles or zero if it is unknown.

◆ getState()

InstrumentProfileConnection::State dxfcpp::InstrumentProfileConnection::getState ( ) const

noexcept

Returns state of this instrument profile connections.

Returns: The state of this instrument profile connections.

◆ getUpdatePeriod()

std::int64_t dxfcpp::InstrumentProfileConnection::getUpdatePeriod ( ) const

noexcept

Returns update period in milliseconds.

It is period of an update check when the instrument profiles source does not support live updates and/or when connection is dropped. Default update period is 1 minute, unless overridden in an address string.

Returns: The update period in milliseconds.

◆ getUpdatePeriodAsDuration()

std::chrono::milliseconds dxfcpp::InstrumentProfileConnection::getUpdatePeriodAsDuration ( ) const

inlinenoexcept

Returns update period in milliseconds as chrono::duration It is period of an update check when the instrument profiles source does not support live updates and/or when connection is dropped.

Default update period is 1 minute, unless overridden in an address string.

Returns: The update period in milliseconds as chrono::duration.

◆ onStateChange()

auto & dxfcpp::InstrumentProfileConnection::onStateChange ( )

inlinenoexcept

Returns the onStateChange handler that can be used to add or remove listeners.

Returns: onStateChange handler with void(State, State) signature

◆ removeStateChangeListener()

void dxfcpp::InstrumentProfileConnection::removeStateChangeListener ( std::size_t listenerId )

inlinenoexcept

Removes listener that is notified about changes in state property.

It removes the listener that was previously installed with InstrumentProfileConnection::addStateChangeListener method.

Parameters

listenerId The listener id to remove

◆ setUpdatePeriod() [1/2]

void dxfcpp::InstrumentProfileConnection::setUpdatePeriod ( std::chrono::milliseconds updatePeriod ) const

inlinenoexcept

Changes the update period in milliseconds as chrono::duration.

Parameters

updatePeriod The update period in milliseconds as chrono::duration.

See also: InstrumentProfileConnection::getUpdatePeriod()

◆ setUpdatePeriod() [2/2]

void dxfcpp::InstrumentProfileConnection::setUpdatePeriod ( std::int64_t updatePeriod ) const

noexcept

Changes the update period in milliseconds.

Parameters

updatePeriod The update period in milliseconds.

See also: InstrumentProfileConnection::getUpdatePeriod()

◆ start()

void dxfcpp::InstrumentProfileConnection::start ( ) const

noexcept

Starts this instrument profile connection.

This connection's state immediately changes to CONNECTING and the actual connection establishment proceeds in the background.

◆ waitUntilCompleted() [1/2]

bool dxfcpp::InstrumentProfileConnection::waitUntilCompleted ( std::chrono::milliseconds timeout ) const

inlinenoexcept

Synchronously waits for full first snapshot read with the specified timeout.

Parameters

timeout The maximum time to wait

Returns: true if COMPLETED state was reached and false if the waiting time elapsed before snapshot was fully read.

◆ waitUntilCompleted() [2/2]

bool dxfcpp::InstrumentProfileConnection::waitUntilCompleted ( std::int64_t timeout ) const

noexcept

Synchronously waits for full first snapshot read with the specified timeout.

Parameters

timeout The maximum time (in millis) to wait

Returns: true if COMPLETED state was reached and false if the waiting time elapsed before snapshot was fully read.

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ State

Member Function Documentation

◆ addStateChangeListener()

◆ close()

◆ createConnection()

◆ getAddress()

◆ getLastModified()

◆ getState()

◆ getUpdatePeriod()

◆ getUpdatePeriodAsDuration()

◆ onStateChange()

◆ removeStateChangeListener()

◆ setUpdatePeriod() [1/2]

◆ setUpdatePeriod() [2/2]

◆ start()

◆ waitUntilCompleted() [1/2]

◆ waitUntilCompleted() [2/2]