dnp3 (C++ API) 1.6.0
Loading...
Searching...
No Matches
dnp3::MasterChannel Class Reference

Represents a communication channel for a master station. More...

#include <dnp3.hpp>

Public Member Functions

 MasterChannel (MasterChannel &&other) noexcept
 Transfer ownership of the underlying C-type to this instance and invalidate the other instance. More...
 
 ~MasterChannel ()
 Shutdown a MasterChannel and release all resources. More...
 
void enable ()
 start communications More...
 
void disable ()
 stop communications More...
 
AssociationId add_association (uint16_t address, const AssociationConfig &config, std::unique_ptr< ReadHandler > read_handler, std::unique_ptr< AssociationHandler > association_handler, std::unique_ptr< AssociationInformation > association_information)
 Add an association to the channel. More...
 
AssociationId add_udp_association (uint16_t address, const std::string &destination, const AssociationConfig &config, std::unique_ptr< ReadHandler > read_handler, std::unique_ptr< AssociationHandler > association_handler, std::unique_ptr< AssociationInformation > association_information)
 Add a UDP association to the channel. More...
 
void remove_association (const AssociationId &id)
 Remove an association from the channel. More...
 
void set_decode_level (const DecodeLevel &decode_level)
 Set the decoding level for the channel. More...
 
DecodeLevel get_decode_level ()
 Get the decoding level for the channel. More...
 
PollId add_poll (const AssociationId &id, Request &request, std::chrono::steady_clock::duration period)
 Add a periodic poll to an association. More...
 
void remove_poll (const PollId &poll_id)
 Add a periodic poll to an association. More...
 
void demand_poll (const PollId &poll_id)
 Demand the immediate execution of a poll previously created with MasterChannel::add_poll(). More...
 
void read_file (const AssociationId &association, const std::string &remote_file_path, const FileReadConfig &config, std::unique_ptr< FileReader > reader)
 Start an operation to READ a file from the outstation using a FileReader to receive data. More...
 
void read_file_with_auth (const AssociationId &association, const std::string &remote_file_path, const FileReadConfig &config, std::unique_ptr< FileReader > reader, const std::string &user_name, const std::string &password)
 Start an operation to READ a file from the outstation using a FileReader to receive data. More...
 
void read (const AssociationId &association, Request &request, std::unique_ptr< ReadTaskCallback > callback)
 Perform a read on the association. More...
 
void read_with_handler (const AssociationId &association, Request &request, std::unique_ptr< ReadHandler > handler, std::unique_ptr< ReadTaskCallback > callback)
 Perform a read on the association. More...
 
void operate (const AssociationId &association, CommandMode mode, CommandSet &command, std::unique_ptr< CommandTaskCallback > callback)
 Asynchronously perform a command operation on the association. More...
 
void synchronize_time (const AssociationId &association, TimeSyncMode mode, std::unique_ptr< TimeSyncTaskCallback > callback)
 Asynchronously perform a time sync operation to the association. More...
 
void cold_restart (const AssociationId &association, std::unique_ptr< RestartTaskCallback > callback)
 Asynchronously perform a cold restart operation to the association. More...
 
void warm_restart (const AssociationId &association, std::unique_ptr< RestartTaskCallback > callback)
 Asynchronously perform a warm restart operation to the association. More...
 
void write_dead_bands (const AssociationId &association, WriteDeadBandRequest &request, std::unique_ptr< EmptyResponseCallback > callback)
 Perform a WRITE on the association using the supplied collection of dead-band headers. More...
 
void send_and_expect_empty_response (const AssociationId &association, FunctionCode function, Request &headers, std::unique_ptr< EmptyResponseCallback > callback)
 Send the specified request to the association using the supplied function and collection of request headers. More...
 
void get_file_info (const AssociationId &association, const std::string &file_name, std::unique_ptr< FileInfoCallback > callback)
 Asynchronously retrieve information on a particular file. More...
 
void get_file_auth_key (const AssociationId &association, const std::string &username, const std::string &password, std::unique_ptr< FileAuthCallback > callback)
 Obtain a file authentication key. More...
 
void open_file (const AssociationId &association, const std::string &file_name, uint32_t auth_key, const Permissions &permissions, uint32_t file_size, FileMode file_mode, uint16_t max_block_size, std::unique_ptr< FileOpenCallback > callback)
 Asynchronously open a file. More...
 
void write_file_block (const AssociationId &association, uint32_t handle, uint32_t block_number, bool final_block, const std::vector< uint8_t > &block_data, std::unique_ptr< FileOperationCallback > callback)
 Asynchronously write a block of file data to the outstation. More...
 
void close_file (const AssociationId &association, uint32_t handle, std::unique_ptr< FileOperationCallback > callback)
 Asynchronously close a file. More...
 
void read_directory (const AssociationId &association, const std::string &dir_path, const DirReadConfig &config, std::unique_ptr< ReadDirectoryCallback > callback)
 Asynchronously retrieve a directory listing. More...
 
void read_directory_with_auth (const AssociationId &association, const std::string &dir_path, const DirReadConfig &config, const std::string &user_name, const std::string &password, std::unique_ptr< ReadDirectoryCallback > callback)
 Asynchronously retrieve a directory listing by first obtaining an authentication key. More...
 
void check_link_status (const AssociationId &association, std::unique_ptr< LinkStatusCallback > callback)
 Asynchronously perform a link status check. More...
 

Static Public Member Functions

static MasterChannel create_tcp_channel (Runtime &runtime, LinkErrorMode link_error_mode, const MasterChannelConfig &config, EndpointList &endpoints, const ConnectStrategy &connect_strategy, std::unique_ptr< ClientStateListener > listener)
 Create a master channel that connects to the specified TCP endpoint(s) More...
 
static MasterChannel create_tcp_channel_2 (Runtime &runtime, LinkErrorMode link_error_mode, const MasterChannelConfig &config, EndpointList &endpoints, const ConnectStrategy &connect_strategy, ConnectOptions &connect_options, std::unique_ptr< ClientStateListener > listener)
 Create a master channel that connects to the specified TCP endpoint(s) More...
 
static MasterChannel create_tls_channel (Runtime &runtime, LinkErrorMode link_error_mode, const MasterChannelConfig &config, EndpointList &endpoints, const ConnectStrategy &connect_strategy, std::unique_ptr< ClientStateListener > listener, const TlsClientConfig &tls_config)
 Create a master channel that connects to the specified TCP endpoint(s) and establish a TLS session with the remote. More...
 
static MasterChannel create_tls_channel_2 (Runtime &runtime, LinkErrorMode link_error_mode, const MasterChannelConfig &config, EndpointList &endpoints, const ConnectStrategy &connect_strategy, ConnectOptions &connect_options, std::unique_ptr< ClientStateListener > listener, const TlsClientConfig &tls_config)
 Create a master channel that connects to the specified TCP endpoint(s) and establish a TLS session with the remote. More...
 
static MasterChannel create_serial_channel (Runtime &runtime, const MasterChannelConfig &config, const std::string &path, const SerialSettings &serial_params, std::chrono::steady_clock::duration open_retry_delay, std::unique_ptr< PortStateListener > listener)
 Create a master channel on the specified serial port. More...
 
static MasterChannel create_udp_channel (Runtime &runtime, const MasterChannelConfig &config, const std::string &local_endpoint, LinkReadMode link_read_mode, std::chrono::steady_clock::duration retry_delay)
 Create a UDP master channel on the local endpoint. More...
 

Friends

class CppMasterChannelFriend
 

Detailed Description

Represents a communication channel for a master station.

To communicate with a particular outstation, you need to add an association with MasterChannel::add_association().

Warning
The class methods that return a value (e.g. as MasterChannel::add_association()) cannot be called from within a callback.

Constructor & Destructor Documentation

◆ MasterChannel()

dnp3::MasterChannel::MasterChannel ( MasterChannel &&  other)
inlinenoexcept

Transfer ownership of the underlying C-type to this instance and invalidate the other instance.

Note
the moved class will now throw an exception if any method is called
Parameters
otherClass from which ownership will be transfer to this instance

◆ ~MasterChannel()

dnp3::MasterChannel::~MasterChannel ( )

Shutdown a MasterChannel and release all resources.

Member Function Documentation

◆ add_association()

AssociationId dnp3::MasterChannel::add_association ( uint16_t  address,
const AssociationConfig config,
std::unique_ptr< ReadHandler read_handler,
std::unique_ptr< AssociationHandler association_handler,
std::unique_ptr< AssociationInformation association_information 
)

Add an association to the channel.

Parameters
addressDNP3 data-link address of the remote outstation
configAssociation configuration
read_handlerInterface uses to load measurement data
association_handlerAssociation specific callbacks such as time synchronization
association_informationAssociation information interface
Returns
Id of the association
Exceptions
ParamException

◆ add_poll()

PollId dnp3::MasterChannel::add_poll ( const AssociationId id,
Request request,
std::chrono::steady_clock::duration  period 
)

Add a periodic poll to an association.

Each result of the poll will be sent to the ReadHandler of the association.

Parameters
idAssociation on which to add the poll
requestRequest to perform
periodPeriod to wait between each poll (in ms)
Returns
Id of the created poll
Exceptions
ParamException

◆ add_udp_association()

AssociationId dnp3::MasterChannel::add_udp_association ( uint16_t  address,
const std::string &  destination,
const AssociationConfig config,
std::unique_ptr< ReadHandler read_handler,
std::unique_ptr< AssociationHandler association_handler,
std::unique_ptr< AssociationInformation association_information 
)

Add a UDP association to the channel.

Parameters
addressDNP3 data-link address of the remote outstation
destinationIP address and port of the outstation
configAssociation configuration
read_handlerInterface uses to load measurement data
association_handlerAssociation specific callbacks such as time synchronization
association_informationAssociation information interface
Returns
Id of the association
Exceptions
ParamException

◆ check_link_status()

void dnp3::MasterChannel::check_link_status ( const AssociationId association,
std::unique_ptr< LinkStatusCallback callback 
)

Asynchronously perform a link status check.

Parameters
associationId of the association
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ close_file()

void dnp3::MasterChannel::close_file ( const AssociationId association,
uint32_t  handle,
std::unique_ptr< FileOperationCallback callback 
)

Asynchronously close a file.

Parameters
associationId of the association
handleHandle returned when the file was opened
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ cold_restart()

void dnp3::MasterChannel::cold_restart ( const AssociationId association,
std::unique_ptr< RestartTaskCallback callback 
)

Asynchronously perform a cold restart operation to the association.

Parameters
associationId of the association
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ create_serial_channel()

static MasterChannel dnp3::MasterChannel::create_serial_channel ( Runtime runtime,
const MasterChannelConfig config,
const std::string &  path,
const SerialSettings serial_params,
std::chrono::steady_clock::duration  open_retry_delay,
std::unique_ptr< PortStateListener listener 
)
static

Create a master channel on the specified serial port.

The returned master must be gracefully shutdown with MasterChannel::~MasterChannel() when done.

Parameters
runtimeRuntime to use to drive asynchronous operations of the master
configGeneric configuration for the channel
pathPath to the serial device. Generally /dev/tty0 on Linux and COM1 on Windows.
serial_paramsSerial port settings
open_retry_delayDelay between attempts to open the serial port
listenerListener to receive updates on the status of the serial port
Returns
Handle to the master created, NULL if an error occurred
Exceptions
ParamException

◆ create_tcp_channel()

static MasterChannel dnp3::MasterChannel::create_tcp_channel ( Runtime runtime,
LinkErrorMode  link_error_mode,
const MasterChannelConfig config,
EndpointList endpoints,
const ConnectStrategy connect_strategy,
std::unique_ptr< ClientStateListener listener 
)
static

Create a master channel that connects to the specified TCP endpoint(s)

Parameters
runtimeRuntime to use to drive asynchronous operations of the master
link_error_modeControls how link errors are handled with respect to the TCP session
configGeneric configuration for the channel
endpointsList of IP endpoints.
connect_strategyControls the timing of (re)connection attempts
listenerTCP connection listener used to receive updates on the status of the connection
Returns
Handle to the master created, NULL if an error occurred
Exceptions
ParamException

◆ create_tcp_channel_2()

static MasterChannel dnp3::MasterChannel::create_tcp_channel_2 ( Runtime runtime,
LinkErrorMode  link_error_mode,
const MasterChannelConfig config,
EndpointList endpoints,
const ConnectStrategy connect_strategy,
ConnectOptions connect_options,
std::unique_ptr< ClientStateListener listener 
)
static

Create a master channel that connects to the specified TCP endpoint(s)

This is just like MasterChannel::create_tcp_channel() but adds the ConnectOptions parameter

Parameters
runtimeRuntime to use to drive asynchronous operations of the master
link_error_modeControls how link errors are handled with respect to the TCP session
configGeneric configuration for the channel
endpointsList of IP endpoints.
connect_strategyControls the timing of (re)connection attempts
connect_optionsOptions that control the TCP connection process
listenerTCP connection listener used to receive updates on the status of the connection
Returns
Handle to the master created, NULL if an error occurred
Exceptions
ParamException

◆ create_tls_channel()

static MasterChannel dnp3::MasterChannel::create_tls_channel ( Runtime runtime,
LinkErrorMode  link_error_mode,
const MasterChannelConfig config,
EndpointList endpoints,
const ConnectStrategy connect_strategy,
std::unique_ptr< ClientStateListener listener,
const TlsClientConfig tls_config 
)
static

Create a master channel that connects to the specified TCP endpoint(s) and establish a TLS session with the remote.

Parameters
runtimeRuntime to use to drive asynchronous operations of the master
link_error_modeControls how link errors are handled with respect to the TCP session
configGeneric configuration for the channel
endpointsList of IP endpoints.
connect_strategyControls the timing of (re)connection attempts
listenerTCP connection listener used to receive updates on the status of the connection
tls_configTLS client configuration
Returns
Handle to the master created, NULL if an error occurred
Exceptions
ParamException

◆ create_tls_channel_2()

static MasterChannel dnp3::MasterChannel::create_tls_channel_2 ( Runtime runtime,
LinkErrorMode  link_error_mode,
const MasterChannelConfig config,
EndpointList endpoints,
const ConnectStrategy connect_strategy,
ConnectOptions connect_options,
std::unique_ptr< ClientStateListener listener,
const TlsClientConfig tls_config 
)
static

Create a master channel that connects to the specified TCP endpoint(s) and establish a TLS session with the remote.

This is just like MasterChannel::create_tls_channel() but adds the ConnectOptions parameter

Parameters
runtimeRuntime to use to drive asynchronous operations of the master
link_error_modeControls how link errors are handled with respect to the TCP session
configGeneric configuration for the channel
endpointsList of IP endpoints.
connect_strategyControls the timing of (re)connection attempts
connect_optionsOptions that control the TCP connection process
listenerTCP connection listener used to receive updates on the status of the connection
tls_configTLS client configuration
Returns
Handle to the master created, NULL if an error occurred
Exceptions
ParamException

◆ create_udp_channel()

static MasterChannel dnp3::MasterChannel::create_udp_channel ( Runtime runtime,
const MasterChannelConfig config,
const std::string &  local_endpoint,
LinkReadMode  link_read_mode,
std::chrono::steady_clock::duration  retry_delay 
)
static

Create a UDP master channel on the local endpoint.

The returned master must be gracefully shutdown with MasterChannel::~MasterChannel() when done.

Parameters
runtimeRuntime to use to drive asynchronous operations of the master
configGeneric configuration for the channel
local_endpointLocal endpoint on which to bind the UDP socket
link_read_modeDetermines how the link-layer parser treats frame that span datagrams. Typically set to LinkReadMode::datagram
retry_delayAmount of time to wait after a failed attempt to bind the UDP socket
Returns
Handle to the master created, NULL if an error occurred
Exceptions
ParamException

◆ demand_poll()

void dnp3::MasterChannel::demand_poll ( const PollId poll_id)

Demand the immediate execution of a poll previously created with MasterChannel::add_poll().

This method returns immediately. The result will be sent to the registered ReadHandler.

This method resets the internal timer of the poll.

Parameters
poll_idId of the poll
Exceptions
ParamException

◆ disable()

void dnp3::MasterChannel::disable ( )

stop communications

Exceptions
ParamException

◆ enable()

void dnp3::MasterChannel::enable ( )

start communications

Exceptions
ParamException

◆ get_decode_level()

DecodeLevel dnp3::MasterChannel::get_decode_level ( )

Get the decoding level for the channel.

Returns
Decode level
Exceptions
ParamException

◆ get_file_auth_key()

void dnp3::MasterChannel::get_file_auth_key ( const AssociationId association,
const std::string &  username,
const std::string &  password,
std::unique_ptr< FileAuthCallback callback 
)

Obtain a file authentication key.

Parameters
associationId of the association
usernameUser name
passwordPassword
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ get_file_info()

void dnp3::MasterChannel::get_file_info ( const AssociationId association,
const std::string &  file_name,
std::unique_ptr< FileInfoCallback callback 
)

Asynchronously retrieve information on a particular file.

Parameters
associationId of the association
file_nameComplete path to the remote file
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ open_file()

void dnp3::MasterChannel::open_file ( const AssociationId association,
const std::string &  file_name,
uint32_t  auth_key,
const Permissions permissions,
uint32_t  file_size,
FileMode  file_mode,
uint16_t  max_block_size,
std::unique_ptr< FileOpenCallback callback 
)

Asynchronously open a file.

Parameters
associationId of the association
file_nameComplete path to the remote file
auth_keyOptional authentication key (0 == None)
permissionsPermissions sent in the file open request
file_sizeFile size sent in the request (zero when reading). When writing use the actual file size or 0xFFFFFFFF to indicate the size is unknown
file_modeMode used to open the file
max_block_sizeRequested maximum block size
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ operate()

void dnp3::MasterChannel::operate ( const AssociationId association,
CommandMode  mode,
CommandSet command,
std::unique_ptr< CommandTaskCallback callback 
)

Asynchronously perform a command operation on the association.

Parameters
associationId of the association
modeOperation mode
commandCommand to send
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ read()

void dnp3::MasterChannel::read ( const AssociationId association,
Request request,
std::unique_ptr< ReadTaskCallback callback 
)

Perform a read on the association.

The callback will be called once the read is completely received, but the actual values will be sent to the ReadHandler of the association.

Parameters
associationAssociation on which to perform the read
requestRequest to send
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ read_directory()

void dnp3::MasterChannel::read_directory ( const AssociationId association,
const std::string &  dir_path,
const DirReadConfig config,
std::unique_ptr< ReadDirectoryCallback callback 
)

Asynchronously retrieve a directory listing.

Parameters
associationId of the association
dir_pathComplete path to the remote directory
configConfiguration for the directory read operation
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ read_directory_with_auth()

void dnp3::MasterChannel::read_directory_with_auth ( const AssociationId association,
const std::string &  dir_path,
const DirReadConfig config,
const std::string &  user_name,
const std::string &  password,
std::unique_ptr< ReadDirectoryCallback callback 
)

Asynchronously retrieve a directory listing by first obtaining an authentication key.

Parameters
associationId of the association
dir_pathComplete path to the remote directory
configConfiguration for the directory read operation
user_nameUser name sent to the outstation
passwordPassword sent to the outstation
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ read_file()

void dnp3::MasterChannel::read_file ( const AssociationId association,
const std::string &  remote_file_path,
const FileReadConfig config,
std::unique_ptr< FileReader reader 
)

Start an operation to READ a file from the outstation using a FileReader to receive data.

Parameters
associationId of the association
remote_file_pathPath of the remote file
configConfiguration for the read operation
readerInterface used to receive file data
Exceptions
ParamException

◆ read_file_with_auth()

void dnp3::MasterChannel::read_file_with_auth ( const AssociationId association,
const std::string &  remote_file_path,
const FileReadConfig config,
std::unique_ptr< FileReader reader,
const std::string &  user_name,
const std::string &  password 
)

Start an operation to READ a file from the outstation using a FileReader to receive data.

This variant first requests an authentication key from the outstation using the supplied credentials

Parameters
associationId of the association
remote_file_pathPath of the remote file
configConfiguration for the read operation
readerInterface used to receive file data
user_nameUser name sent to the outstation
passwordPassword sent to the outstation
Exceptions
ParamException

◆ read_with_handler()

void dnp3::MasterChannel::read_with_handler ( const AssociationId association,
Request request,
std::unique_ptr< ReadHandler handler,
std::unique_ptr< ReadTaskCallback callback 
)

Perform a read on the association.

The callback will be called once the read is completely received, but the actual values will be sent to the ReadHandler passed as a parameter.

Parameters
associationAssociation on which to perform the read
requestRequest to send
handlerCustom ReadHandler to send the data to
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ remove_association()

void dnp3::MasterChannel::remove_association ( const AssociationId id)

Remove an association from the channel.

Parameters
idId of the association
Exceptions
ParamException

◆ remove_poll()

void dnp3::MasterChannel::remove_poll ( const PollId poll_id)

Add a periodic poll to an association.

Each result of the poll will be sent to the ReadHandler of the association.

Parameters
poll_idId of the created poll
Exceptions
ParamException

◆ send_and_expect_empty_response()

void dnp3::MasterChannel::send_and_expect_empty_response ( const AssociationId association,
FunctionCode  function,
Request headers,
std::unique_ptr< EmptyResponseCallback callback 
)

Send the specified request to the association using the supplied function and collection of request headers.

This is useful for constructing various types of WRITE and FREEZE operations where an empty response is expected from the outstation, and the only indication of success are bits in IIN.2.

The request will fail if 1) The response contains object headers or 2) One of the error bits in IIN.2 is set.

Parameters
associationAssociation on which to perform the request
functionFunction code for the request
headersHeaders that will be contained in the request
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ set_decode_level()

void dnp3::MasterChannel::set_decode_level ( const DecodeLevel decode_level)

Set the decoding level for the channel.

Parameters
decode_levelDecoding level
Exceptions
ParamException

◆ synchronize_time()

void dnp3::MasterChannel::synchronize_time ( const AssociationId association,
TimeSyncMode  mode,
std::unique_ptr< TimeSyncTaskCallback callback 
)

Asynchronously perform a time sync operation to the association.

Parameters
associationId of the association
modeTime sync mode
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ warm_restart()

void dnp3::MasterChannel::warm_restart ( const AssociationId association,
std::unique_ptr< RestartTaskCallback callback 
)

Asynchronously perform a warm restart operation to the association.

Parameters
associationId of the association
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ write_dead_bands()

void dnp3::MasterChannel::write_dead_bands ( const AssociationId association,
WriteDeadBandRequest request,
std::unique_ptr< EmptyResponseCallback callback 
)

Perform a WRITE on the association using the supplied collection of dead-band headers.

Parameters
associationAssociation on which to perform the WRITE
requestRequest containing headers of analog input dead-bands (group 34)
callbackcallback invoked when the operation completes
Exceptions
ParamException

◆ write_file_block()

void dnp3::MasterChannel::write_file_block ( const AssociationId association,
uint32_t  handle,
uint32_t  block_number,
bool  final_block,
const std::vector< uint8_t > &  block_data,
std::unique_ptr< FileOperationCallback callback 
)

Asynchronously write a block of file data to the outstation.

Parameters
associationId of the association
handleHandle returned when the file was opened
block_numberSequential block number in the range [0 .. 0x7FFFFFFF]. The top bit is indicates the final block
final_blockIndicate that this is the final block
block_dataCollection of bytes. This must not be larger than the maximum block size returned by the outstation
callbackcallback invoked when the operation completes
Exceptions
ParamException

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