Connection

class Connection : public std::enable_shared_from_this<Connection>

connection model for connections via client component to remote servers

Public Functions

~Connection()

Close and destroy a connection to a remote server.

std::string getConnectionString() const

Getter for connectionString to remote server

Returns:

ip:port string

std::string getIP() const

Getter for ip of remote server

Returns:

ip string

std::uint_fast16_t getPort() const

Getter for port of remote server

Returns:

port number

ConnectionState getState() const

Getter for connection state

Returns:

connection state enum

void setOriginatorAddress(std::uint_fast8_t address)

Setter for originatorAddress: who is the originator of a client message.

Parameters:

address – originator address of a client message

std::uint_fast8_t getOriginatorAddress() const

Getter for originatorAddress: who is the originator of a client message.

Returns:

originator address of a client message

std::shared_ptr<Client> getClient() const

getter for client

client object reference

Returns:

shared pointer to the owning client instance, optional

void connect()

Open a created connection to remote server.

void disconnect()

Close a created connection to remote server.

Returns:

information on operation success

bool isOpen() const

Test if connection to remote server is open.

Returns:

information on open state

bool isMuted() const

Test if connection to remote server is muted.

Returns:

information on muted state

bool mute()

Mute an open connection to remote server - disable messages from server to client.

Returns:

information on operation success

bool unmute()

Unmute an open connection to remote server - enabled messages from server to client.

Returns:

information on operation success

void setMuted(bool value)

Setter for muted state.

Parameters:

value – value of new muted state (true = muted, false = unmuted)

void setOpen()

Setter for open state: Mark connection as open.

void setClosed()

Setter for open state: Mark connection as closed, start reconnect state.

void prepareCommandSuccess(const std::string &cmdId, CommandProcessState state)

add command id to awaiting command result map

Parameters:

  • cmdId – unique command id

  • state – command process state

Throws:

std::runtime_error – if cmdId already in use

void cancelCommandSuccess(const std::string &cmdId)

mark a command success as failed to fail fast

Parameters:

cmdId – unique command id

bool awaitCommandSuccess(const std::string &cmdId)

Wait for command confirmation and success information, release outgoing message LOCK for this command and get information on last commands success.

Parameters:

cmdId – unique command id

Returns:

information on last command success

void setCommandSuccess(std::shared_ptr<Message::IncomingMessage> message)

Set success state of last command.

Parameters:

message – incoming message

bool hasStations() const

Test if Stations exists at this NetworkStation.

Returns:

information on availability of child Station objects

Object::StationVector getStations() const

Get a list of all Stations.

Returns:

vector with object stationer

std::shared_ptr<Object::Station> getStation(std::uint_fast16_t commonAddress) const

Get a Station that exists at this NetworkStation and is identified via information object address.

Returns:

Stationer to Station or nullptr

bool hasStation(std::uint_fast16_t commonAddress) const

Checks whether a remote Station with the given common address exists on this client Connection.

Parameters:

commonAddress – The common address (CA) used to identify the Station.

Returns:

True if a Station with the specified common address exists, otherwise false.

std::shared_ptr<Object::Station> addStation(std::uint_fast16_t commonAddress)

Adds a new remote Station to this client Connection.

Parameters:

commonAddress – The common address (CA) that uniquely identifies the new Station.

Returns:

A shared pointer to the newly added Station.

bool removeStation(std::uint_fast16_t commonAddress)

Removes an existing remote Station from this client Connection.

Parameters:

commonAddress – The common address (CA) of the Station to be removed.

Returns:

True if the Station was successfully removed, otherwise false.

CS104_APCIParameters getParameters() const

Get a reference to the protocol parameters to be able to read and update these.

void setOnReceiveRawCallback(py::object &callable)

set python callback that will be executed on incoming message

Throws:

std::invalid_argument – if callable signature does not match

void onReceiveRaw(unsigned char *msg, unsigned char msgSize)

Execute configured callback handlers on receiving raw messages.

Parameters:

  • msg – Pointer to the raw message data.

  • msgSize – Size of the raw message data in bytes.

void setOnSendRawCallback(py::object &callable)

set python callback that will be executed on outgoing message

Throws:

std::invalid_argument – if callable signature does not match

void onSendRaw(unsigned char *msg, unsigned char msgSize)

Execute configured callback handlers on sending raw messages.

Parameters:

  • msg – Pointer to the raw message data to be sent.

  • msgSize – Size of the raw message in bytes.

void setOnStateChangeCallback(py::object &callable)

set python callback that will be executed on connection state changes

Throws:

std::invalid_argument – if callable signature does not match

void setOnUnexpectedMessageCallback(py::object &callable)

set python callback that will be executed on unexpected incoming messages

Throws:

std::invalid_argument – if callable signature does not match

void onUnexpectedMessage(std::shared_ptr<Message::IncomingMessage> message, UnexpectedMessageCause cause)

Execute configured callback handlers on receiving unexpected messages from a client.

Parameters:

  • connection – The master connection from which the unexpected message was received.

  • message – A shared pointer to the incoming message that triggered the unexpected event.

  • cause – The reason why the message was classified as unexpected (e.g., unknown type ID or invalid cause-of-transmission).

std::optional<std::chrono::system_clock::time_point> getConnectedAt() const

getter for connectedAt

Returns:

the time point the currently active connection was established, optional

std::optional<std::chrono::system_clock::time_point> getDisconnectedAt() const

getter for disconnectedAt

Returns:

the time point the last connection was disconnected, if currently not connected, optional

bool interrogation(std::uint_fast16_t commonAddress, CS101_CauseOfTransmission cause = CS101_COT_ACTIVATION, CS101_QualifierOfInterrogation qualifier = QOI_STATION, bool wait_for_response = true)

send interrogation command

Parameters:

  • commonAddress –

  • cause –

  • qualifier –

  • wait_for_response –

Throws:

std::invalid_argument – if qualifier is invalid

Returns:

success information

bool counterInterrogation(std::uint_fast16_t commonAddress, CS101_CauseOfTransmission cause = CS101_COT_ACTIVATION, CS101_QualifierOfCounterInterrogation qualifier = CS101_QualifierOfCounterInterrogation::GENERAL, CS101_FreezeOfCounterInterrogation freeze = CS101_FreezeOfCounterInterrogation::READ, bool wait_for_response = true)

send counter interrogation command

Parameters:

  • commonAddress – station address

  • cause – transmission reason

  • qualifier – targeted counters

  • freeze – counter behaviour

  • wait_for_response – blocking or non-blocking

Throws:

std::invalid_argument – if qualifier is invalid

Returns:

success information

bool clockSync(std::uint_fast16_t commonAddress, bool wait_for_response = true)

send clock synchronization command

Parameters:

  • commonAddress – station address

  • wait_for_response – blocking or non-blocking

Returns:

success information

bool test(std::uint_fast16_t commonAddress, bool with_time = true, bool wait_for_response = true)

send test command

Parameters:

  • commonAddress – station address

  • with_time – include a timestamp in the test command

  • wait_for_response – blocking or non-blocking

Returns:

success information

bool transmit(std::shared_ptr<Object::DataPoint> point, CS101_CauseOfTransmission cause)

transmit a command to a remote server

Parameters:

  • point – control point

  • cause – reason for transmission

Throws:

std::invalid_argument – if point type is not supported for this operation

Returns:

if operation was successful

bool command(std::shared_ptr<Message::OutgoingMessage> message, bool wait_for_response = true, CommandProcessState state = COMMAND_AWAIT_CON)

add command id to awaiting command result map

Parameters:

  • message – outgoing message

  • wait_for_response – blocking or non-blocking

  • state – command process state

Returns:

if command preparation was successfully (no collision with active sequence)

bool read(std::shared_ptr<Object::DataPoint> point, bool wait_for_response = true)

send a point read command to remote server

Parameters:

  • point – monitoring point

  • wait_for_response – blocking or non-blocking

Throws:

std::invalid_argument – if point type is not supported for this operation

Returns:

if operation was successful

inline std::string toString() const

Returns a string representation of the Connection object, including its state, IP address, port, number of stations, and memory address.

Returns:

A formatted string describing the current state of the Connection.

Public Static Functions

static inline std::shared_ptr<Connection> create(std::shared_ptr<Client> client, const std::string &ip, const uint_fast16_t port = IEC_60870_5_104_DEFAULT_PORT, const uint_fast16_t command_timeout_ms = 100, const ConnectionInit init = INIT_ALL, std::shared_ptr<Remote::TransportSecurity> transport_security = nullptr, const uint_fast8_t originator_address = 0)

Create a new (still closed) connection to a remote server identified via ip and port.

Parameters:

  • client – client instance reference

  • ip – ip address or hostname of remote server

  • port – port address of remote server

  • command_timeout_ms – default timeout for command confirmation

  • init – connection initialization procedure

  • transport_security – communication encryption instance reference

  • originator_address – client identification address

Throws:

std::invalid_argument – if ip or port invalid

Returns:

owning pointer of new Connection instance

static void rawMessageHandler(void *parameter, uint_fast8_t *msg, int msgSize, bool sent)

Callback for logging incoming and outgoing byteStreams.

Warning

DEBUG FUNCTION, IN ORDER TO ACTIVE THIS CALLBACK REMOVE COMMENT WRAPPER IN Connect(connectionState)

Parameters:

  • parameter – reference to custom bound connection data

  • msg – pointer to first character of message

  • msgSize – character count of message

  • sent – direction of message

static void connectionHandler(void *parameter, CS104_Connection connection, CS104_ConnectionEvent event)

Callback to handle connection state changes.

Parameters:

  • parameter – reference to custom bound connection data

  • connection – internal CS104_Connection connection object reference

  • event – state change event (opened,closed,muted,unmuted identified via constants)

static bool asduHandler(void *parameter, int address, CS101_ASDU asdu)

Callback to handle incomming reports from remote servers.

Parameters:

  • parameter – reference to custom bound connection data

  • address – NOT USED IN CS104 - relict from CS101

  • asdu – incoming message formatted as ASDU object

Returns: