iCommAdapter.hpp File Reference

Protocol-agnostic communication adapter interface (contract v4). More...

#include <algorithm>
#include <atomic>
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <variant>
#include <vector>

Go to the source code of this file.

Classes
class	ifw::fnd::defs::PropertyMap
class	ifw::fnd::defs::RegistrationToken
class	ifw::fnd::defs::CancellationToken
class	ifw::fnd::defs::CancellationSource
struct	ifw::fnd::defs::Result
struct	ifw::fnd::defs::RequestOptions
struct	ifw::fnd::defs::DataValue
struct	ifw::fnd::defs::ConnectionOptions
struct	ifw::fnd::defs::ConnectionInfo
struct	ifw::fnd::defs::ConnectionStatus
struct	ifw::fnd::defs::ConnectionStateChange
struct	ifw::fnd::defs::DiscoverRequest
struct	ifw::fnd::defs::DiscoveredEndpoint
struct	ifw::fnd::defs::DiscoverResult
struct	ifw::fnd::defs::BrowseRequest
struct	ifw::fnd::defs::NodeDescriptor
struct	ifw::fnd::defs::BrowseResult
struct	ifw::fnd::defs::ReadItem
struct	ifw::fnd::defs::ReadRequest
struct	ifw::fnd::defs::ReadItemResult
struct	ifw::fnd::defs::ReadResult
struct	ifw::fnd::defs::WriteItem
struct	ifw::fnd::defs::WriteRequest
struct	ifw::fnd::defs::WriteItemResult
struct	ifw::fnd::defs::WriteResult
struct	ifw::fnd::defs::CallArgument
struct	ifw::fnd::defs::CallRequest
struct	ifw::fnd::defs::CallArgumentResult
struct	ifw::fnd::defs::CallResult
struct	ifw::fnd::defs::SubscribeOpts
struct	ifw::fnd::defs::Notification
struct	ifw::fnd::defs::SubscribeItemResult
struct	ifw::fnd::defs::SubscribeResult
struct	ifw::fnd::defs::UnsubscribeItemResult
struct	ifw::fnd::defs::UnsubscribeResult
struct	ifw::fnd::defs::Capabilities
class	ifw::fnd::defs::ICommAdapter

Namespaces
namespace	ifw
namespace	ifw::fnd
	This source file contains definitions of the types and constants to handle data types.
namespace	ifw::fnd::defs

Typedefs
using	ifw::fnd::defs::Address = std::string
using	ifw::fnd::defs::RequestId = std::string
using	ifw::fnd::defs::Value
using	ifw::fnd::defs::ConnectionStateHandler
using	ifw::fnd::defs::SubscriptionHandler = std::function<void(const Notification&)>

Enumerations
enum class	ifw::fnd::defs::Status {   ifw::fnd::defs::Ok , ifw::fnd::defs::Timeout , ifw::fnd::defs::NotConnected , ifw::fnd::defs::AlreadyConnected ,   ifw::fnd::defs::InvalidState , ifw::fnd::defs::BadRequest , ifw::fnd::defs::NotFound , ifw::fnd::defs::AccessDenied ,   ifw::fnd::defs::TypeMismatch , ifw::fnd::defs::Unsupported , ifw::fnd::defs::Cancelled , ifw::fnd::defs::RemoteError ,   ifw::fnd::defs::TransportError , ifw::fnd::defs::InternalError }
enum class	ifw::fnd::defs::ConnectionState {   ifw::fnd::defs::Disconnected , ifw::fnd::defs::Connecting , ifw::fnd::defs::Connected , ifw::fnd::defs::Disconnecting ,   ifw::fnd::defs::Faulted }

Variables
constexpr std::uint32_t	ifw::fnd::defs::kCommAdapterContractVersion = 1

Detailed Description

Protocol-agnostic communication adapter interface (contract v4).

Copyright

SPDX-FileCopyrightText: 2026 European Southern Observatory (ESO) SPDX-License-Identifier: LGPL-3.0-only

Scope: the value-oriented CONTROL plane (read / write / call / browse / subscribe) over arbitrary protocols (OPC UA, Modbus, REST, MQTT, GenICam (control/status), ...). Bulk media streaming (e.g. GenICam image acquisition) is intentionally OUT OF SCOPE and belongs to a peer interface composed alongside this one, not derived from it.

Design rules:

1. A field lives in a core type only if EVERY conceivable adapter can honor it meaningfully. Protocol-specific knobs go in properties or optional fields.
2. The interface grows by ADDITION. After the first adapter ships, new methods MUST carry default implementations (return Unsupported), never pure-virtual, so existing implementers keep compiling. Pre-first-adapter breaking changes are free and acceptable (hence the version bumps).
3. Sync-only for v1; async is a pure ADDITION later (Read + ReadAsync coexist trivially because RequestOptions::cancellation already exists). Document this expectation explicitly so it survives turnover.

THREAD-SAFETY CONTRACT (binding):

• const query methods (Is*, Get*) are callable from any thread at any time.
• Read / Write / Call / Browse / Discover may be called concurrently with each other and with active subscriptions; implementations serialize as needed.
• Configure / Connect / Disconnect must NOT run concurrently with each other or with data operations; the caller owns lifecycle ordering.
• Handlers (subscription + connection-state) run on the adapter's internal thread(s); see each handler's contract below.