![]() |
dnp3 (C++ API) 1.6.0
|
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 |
Represents a communication channel for a master station.
To communicate with a particular outstation, you need to add an association with MasterChannel::add_association().
|
inlinenoexcept |
Transfer ownership of the underlying C-type to this instance and invalidate the other instance.
| other | Class from which ownership will be transfer to this instance |
| dnp3::MasterChannel::~MasterChannel | ( | ) |
Shutdown a MasterChannel and release all resources.
| 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.
| address | DNP3 data-link address of the remote outstation |
| config | Association configuration |
| read_handler | Interface uses to load measurement data |
| association_handler | Association specific callbacks such as time synchronization |
| association_information | Association information interface |
| ParamException |
| 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.
| id | Association on which to add the poll |
| request | Request to perform |
| period | Period to wait between each poll (in ms) |
| ParamException |
| 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.
| address | DNP3 data-link address of the remote outstation |
| destination | IP address and port of the outstation |
| config | Association configuration |
| read_handler | Interface uses to load measurement data |
| association_handler | Association specific callbacks such as time synchronization |
| association_information | Association information interface |
| ParamException |
| void dnp3::MasterChannel::check_link_status | ( | const AssociationId & | association, |
| std::unique_ptr< LinkStatusCallback > | callback | ||
| ) |
Asynchronously perform a link status check.
| association | Id of the association |
| callback | callback invoked when the operation completes |
| ParamException |
| void dnp3::MasterChannel::close_file | ( | const AssociationId & | association, |
| uint32_t | handle, | ||
| std::unique_ptr< FileOperationCallback > | callback | ||
| ) |
Asynchronously close a file.
| association | Id of the association |
| handle | Handle returned when the file was opened |
| callback | callback invoked when the operation completes |
| ParamException |
| void dnp3::MasterChannel::cold_restart | ( | const AssociationId & | association, |
| std::unique_ptr< RestartTaskCallback > | callback | ||
| ) |
Asynchronously perform a cold restart operation to the association.
| association | Id of the association |
| callback | callback invoked when the operation completes |
| ParamException |
|
static |
Create a master channel on the specified serial port.
The returned master must be gracefully shutdown with MasterChannel::~MasterChannel() when done.
| runtime | Runtime to use to drive asynchronous operations of the master |
| config | Generic configuration for the channel |
| path | Path to the serial device. Generally /dev/tty0 on Linux and COM1 on Windows. |
| serial_params | Serial port settings |
| open_retry_delay | Delay between attempts to open the serial port |
| listener | Listener to receive updates on the status of the serial port |
NULL if an error occurred | ParamException |
|
static |
Create a master channel that connects to the specified TCP endpoint(s)
| runtime | Runtime to use to drive asynchronous operations of the master |
| link_error_mode | Controls how link errors are handled with respect to the TCP session |
| config | Generic configuration for the channel |
| endpoints | List of IP endpoints. |
| connect_strategy | Controls the timing of (re)connection attempts |
| listener | TCP connection listener used to receive updates on the status of the connection |
NULL if an error occurred | ParamException |
|
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
| runtime | Runtime to use to drive asynchronous operations of the master |
| link_error_mode | Controls how link errors are handled with respect to the TCP session |
| config | Generic configuration for the channel |
| endpoints | List of IP endpoints. |
| connect_strategy | Controls the timing of (re)connection attempts |
| connect_options | Options that control the TCP connection process |
| listener | TCP connection listener used to receive updates on the status of the connection |
NULL if an error occurred | ParamException |
|
static |
Create a master channel that connects to the specified TCP endpoint(s) and establish a TLS session with the remote.
| runtime | Runtime to use to drive asynchronous operations of the master |
| link_error_mode | Controls how link errors are handled with respect to the TCP session |
| config | Generic configuration for the channel |
| endpoints | List of IP endpoints. |
| connect_strategy | Controls the timing of (re)connection attempts |
| listener | TCP connection listener used to receive updates on the status of the connection |
| tls_config | TLS client configuration |
NULL if an error occurred | ParamException |
|
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
| runtime | Runtime to use to drive asynchronous operations of the master |
| link_error_mode | Controls how link errors are handled with respect to the TCP session |
| config | Generic configuration for the channel |
| endpoints | List of IP endpoints. |
| connect_strategy | Controls the timing of (re)connection attempts |
| connect_options | Options that control the TCP connection process |
| listener | TCP connection listener used to receive updates on the status of the connection |
| tls_config | TLS client configuration |
NULL if an error occurred | ParamException |
|
static |
Create a UDP master channel on the local endpoint.
The returned master must be gracefully shutdown with MasterChannel::~MasterChannel() when done.
| runtime | Runtime to use to drive asynchronous operations of the master |
| config | Generic configuration for the channel |
| local_endpoint | Local endpoint on which to bind the UDP socket |
| link_read_mode | Determines how the link-layer parser treats frame that span datagrams. Typically set to LinkReadMode::datagram |
| retry_delay | Amount of time to wait after a failed attempt to bind the UDP socket |
NULL if an error occurred | ParamException |
| 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.
| poll_id | Id of the poll |
| ParamException |
| void dnp3::MasterChannel::disable | ( | ) |
stop communications
| ParamException |
| void dnp3::MasterChannel::enable | ( | ) |
start communications
| ParamException |
| DecodeLevel dnp3::MasterChannel::get_decode_level | ( | ) |
| 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.
| association | Id of the association |
| username | User name |
| password | Password |
| callback | callback invoked when the operation completes |
| ParamException |
| 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.
| association | Id of the association |
| file_name | Complete path to the remote file |
| callback | callback invoked when the operation completes |
| ParamException |
| 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.
| association | Id of the association |
| file_name | Complete path to the remote file |
| auth_key | Optional authentication key (0 == None) |
| permissions | Permissions sent in the file open request |
| file_size | File size sent in the request (zero when reading). When writing use the actual file size or 0xFFFFFFFF to indicate the size is unknown |
| file_mode | Mode used to open the file |
| max_block_size | Requested maximum block size |
| callback | callback invoked when the operation completes |
| ParamException |
| void dnp3::MasterChannel::operate | ( | const AssociationId & | association, |
| CommandMode | mode, | ||
| CommandSet & | command, | ||
| std::unique_ptr< CommandTaskCallback > | callback | ||
| ) |
Asynchronously perform a command operation on the association.
| association | Id of the association |
| mode | Operation mode |
| command | Command to send |
| callback | callback invoked when the operation completes |
| ParamException |
| 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.
| association | Association on which to perform the read |
| request | Request to send |
| callback | callback invoked when the operation completes |
| ParamException |
| 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.
| association | Id of the association |
| dir_path | Complete path to the remote directory |
| config | Configuration for the directory read operation |
| callback | callback invoked when the operation completes |
| ParamException |
| 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.
| association | Id of the association |
| dir_path | Complete path to the remote directory |
| config | Configuration for the directory read operation |
| user_name | User name sent to the outstation |
| password | Password sent to the outstation |
| callback | callback invoked when the operation completes |
| ParamException |
| 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.
| association | Id of the association |
| remote_file_path | Path of the remote file |
| config | Configuration for the read operation |
| reader | Interface used to receive file data |
| ParamException |
| 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
| association | Id of the association |
| remote_file_path | Path of the remote file |
| config | Configuration for the read operation |
| reader | Interface used to receive file data |
| user_name | User name sent to the outstation |
| password | Password sent to the outstation |
| ParamException |
| 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.
| association | Association on which to perform the read |
| request | Request to send |
| handler | Custom ReadHandler to send the data to |
| callback | callback invoked when the operation completes |
| ParamException |
| void dnp3::MasterChannel::remove_association | ( | const AssociationId & | id | ) |
Remove an association from the channel.
| id | Id of the association |
| ParamException |
| 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.
| poll_id | Id of the created poll |
| ParamException |
| 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.
| association | Association on which to perform the request |
| function | Function code for the request |
| headers | Headers that will be contained in the request |
| callback | callback invoked when the operation completes |
| ParamException |
| void dnp3::MasterChannel::set_decode_level | ( | const DecodeLevel & | decode_level | ) |
Set the decoding level for the channel.
| decode_level | Decoding level |
| ParamException |
| void dnp3::MasterChannel::synchronize_time | ( | const AssociationId & | association, |
| TimeSyncMode | mode, | ||
| std::unique_ptr< TimeSyncTaskCallback > | callback | ||
| ) |
Asynchronously perform a time sync operation to the association.
| association | Id of the association |
| mode | Time sync mode |
| callback | callback invoked when the operation completes |
| ParamException |
| void dnp3::MasterChannel::warm_restart | ( | const AssociationId & | association, |
| std::unique_ptr< RestartTaskCallback > | callback | ||
| ) |
Asynchronously perform a warm restart operation to the association.
| association | Id of the association |
| callback | callback invoked when the operation completes |
| ParamException |
| 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.
| association | Association on which to perform the WRITE |
| request | Request containing headers of analog input dead-bands (group 34) |
| callback | callback invoked when the operation completes |
| ParamException |
| 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.
| association | Id of the association |
| handle | Handle returned when the file was opened |
| block_number | Sequential block number in the range [0 .. 0x7FFFFFFF]. The top bit is indicates the final block |
| final_block | Indicate that this is the final block |
| block_data | Collection of bytes. This must not be larger than the maximum block size returned by the outstation |
| callback | callback invoked when the operation completes |
| ParamException |