tunnel component & update vehicle abstraction example (#8)

sdv_services/uds_unix_tunnel/CMakeLists.txt

@@ -0,0 +1,33 @@
+#*******************************************************************************
+# Copyright (c) 2025-2026 ZF Friedrichshafen AG
+#
+# This program and the accompanying materials are made available under the 
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0 
+#*******************************************************************************
+
+if(UNIX)
+# Define project
+project(uds_unix_tunnel VERSION 1.0 LANGUAGES CXX)
+
+# Define target
+add_library(uds_unix_tunnel STATIC
+    channel_mgnt.cpp
+    connection.cpp
+    )
+
+target_link_libraries(uds_unix_tunnel rt ${CMAKE_DL_LIBS} ${CMAKE_THREAD_LIBS_INIT})
+
+target_include_directories(uds_unix_tunnel PRIVATE ./include/)
+set_target_properties(uds_unix_tunnel PROPERTIES PREFIX "")
+set_target_properties(uds_unix_tunnel PROPERTIES SUFFIX ".sdv")
+
+# Build dependencies
+add_dependencies(uds_unix_tunnel CompileCoreIDL)
+
+# Appending the service in the service list
+set(SDV_Service_List ${SDV_Service_List} uds_unix_tunnel PARENT_SCOPE)
+
+endif()

sdv_services/uds_unix_tunnel/channel_mgnt.cpp

@@ -0,0 +1,178 @@
+#if defined(__unix__)
+
+#include "channel_mgnt.h"
+#include "connection.h"   // CUnixTunnelConnection
+#include "../sdv_services/uds_unix_sockets/connection.h" // CUnixSocketConnection
+
+#include <support/toml.h>
+
+#include <sstream>
+#include <map>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <sys/un.h>
+#include <unistd.h>
+
+namespace
+{
+
+/**
+ * @brief Parses a semicolon-separated list of key=value pairs into a map.
+ *
+ * Example input: "proto=tunnel;role=server;path=/tmp/tunnel.sock;"
+ * Example output: { {"proto","tunnel"}, {"role","server"}, {"path","/tmp/tunnel.sock"} }
+ *
+ * @param s The input string to parse.
+ * @return Map of key-value pairs.
+ */
+static std::map<std::string, std::string> ParseKV(const std::string& s)
+{
+    std::map<std::string, std::string> kv;
+    std::stringstream ss(s);
+    std::string item;
+    while (std::getline(ss, item, ';'))
+    {
+        auto pos = item.find('=');
+        if (pos != std::string::npos)
+            kv[item.substr(0, pos)] = item.substr(pos + 1);
+    }
+    return kv;
+}
+
+
+/**
+ * @brief Clamps an AF_UNIX pathname to the maximum allowed size for sockaddr_un::sun_path.
+ *
+ * @param p The path to clamp.
+ * @return The clamped path string.
+ */
+static std::string ClampSunPath(const std::string& p)
+{
+    constexpr size_t MaxLen = sizeof(sockaddr_un::sun_path);
+    return (p.size() < MaxLen) ? p : p.substr(0, MaxLen - 1);
+}
+
+} // anonymous namespace
+
+std::string CUnixTunnelChannelMgnt::MakeUserRuntimeDir()
+{
+    std::ostringstream oss;
+    oss << "/run/user/" << ::getuid();
+
+    struct stat st{};
+    if (::stat(oss.str().c_str(), &st) == 0)
+    {
+        std::string path = oss.str() + "/sdv";
+        ::mkdir(path.c_str(), 0770);
+        return path;
+    }
+
+    ::mkdir("/tmp/sdv", 0770);
+    return "/tmp/sdv";
+}
+
+bool CUnixTunnelChannelMgnt::OnInitialize()
+{
+    return true;
+}
+
+void CUnixTunnelChannelMgnt::OnShutdown()
+{
+    // Actual cleanup is handled by destructors of CUnixTunnelConnection
+    // and CUnixSocketConnection (shared_ptr).
+}
+
+sdv::ipc::SChannelEndpoint CUnixTunnelChannelMgnt::CreateEndpoint(
+    const sdv::u8string& ssChannelConfig)
+{
+    sdv::ipc::SChannelEndpoint endpoint{};
+
+    const std::string baseDir = MakeUserRuntimeDir();
+    std::string name = "TUNNEL_" + std::to_string(::getpid());
+    std::string path = baseDir + "/" + name + ".sock";
+
+    // Parse optional TOML config for custom name/path
+    if (!ssChannelConfig.empty())
+    {
+        sdv::toml::CTOMLParser cfg(ssChannelConfig.c_str());
+        auto nameNode = cfg.GetDirect("IpcChannel.Name");
+        if (nameNode.GetType() == sdv::toml::ENodeType::node_string)
+            name = static_cast<std::string>(nameNode.GetValue());
+
+        auto pathNode = cfg.GetDirect("IpcChannel.Path");
+        if (pathNode.GetType() == sdv::toml::ENodeType::node_string)
+            path = static_cast<std::string>(pathNode.GetValue());
+        else
+            path = baseDir + "/" + name + ".sock";
+    }
+
+    path = ClampSunPath(path);
+
+    // Create underlying UDS server transport
+    auto udsServer = std::make_shared<CUnixSocketConnection>(
+        -1,
+        /*acceptConnectionRequired*/ true,
+        path);
+
+    // Create tunnel wrapper on top of UDS
+    auto tunnelServer = std::make_shared<CUnixTunnelConnection>(
+        udsServer,
+        /*channelId*/ 0u);
+
+    m_ServerTunnels.push_back(tunnelServer);
+
+    endpoint.pConnection = static_cast<sdv::IInterfaceAccess*>(tunnelServer.get());
+    endpoint.ssConnectString = "proto=tunnel;role=server;path=" + path + ";";
+
+    return endpoint;
+}
+
+sdv::IInterfaceAccess* CUnixTunnelChannelMgnt::Access(
+    const sdv::u8string& ssConnectString)
+{
+    const auto kv = ParseKV(static_cast<std::string>(ssConnectString));
+
+    // Only handle proto=tunnel
+    if (!kv.count("proto") || kv.at("proto") != "tunnel")
+    {
+        return nullptr;
+    }
+
+    const bool isServer =
+        (kv.count("role") && kv.at("role") == "server");
+
+    const std::string path =
+        kv.count("path")
+        ? kv.at("path")
+        : (MakeUserRuntimeDir() + "/TUNNEL_auto.sock");
+
+    if (isServer)
+    {
+        // For simplicity, create a new server tunnel instance for each Access().
+        // The SDV framework is expected to call Access(serverCS) only once in normal cases.
+        auto udsServer = std::make_shared<CUnixSocketConnection>(
+            -1,
+            /*acceptConnectionRequired*/ true,
+            path);
+
+        auto tunnelServer = std::make_shared<CUnixTunnelConnection>(
+            udsServer,
+            /*channelId*/ 0u);
+
+        m_ServerTunnels.push_back(tunnelServer);
+        return static_cast<sdv::IInterfaceAccess*>(tunnelServer.get());
+    }
+
+    // Client: allocate raw pointer (expected to be managed by SDV framework via IObjectDestroy)
+    auto udsClient = std::make_shared<CUnixSocketConnection>(
+        -1,
+        /*acceptConnectionRequired*/ false,
+        path);
+
+    auto* tunnelClient =
+        new CUnixTunnelConnection(udsClient, /*channelId*/ 0u);
+
+    return static_cast<sdv::IInterfaceAccess*>(tunnelClient);
+}
+
+#endif // defined(__unix__)

sdv_services/uds_unix_tunnel/channel_mgnt.h

@@ -0,0 +1,140 @@
+/********************************************************************************
+* Copyright (c) 2025-2026 ZF Friedrichshafen AG
+*
+* This program and the accompanying materials are made available under the
+* terms of the Apache License Version 2.0 which is available at
+* https://www.apache.org/licenses/LICENSE-2.0
+*
+* SPDX-License-Identifier: Apache-2.0
+*
+* Contributors:
+*   Denisa Ros - initial API and implementation
+********************************************************************************/
+#if defined(__unix__)
+#ifndef UNIX_TUNNEL_CHANNEL_MGNT_H
+#define UNIX_TUNNEL_CHANNEL_MGNT_H
+
+#include <support/component_impl.h>
+#include <interfaces/ipc.h>
+#include "../sdv_services/uds_unix_sockets/channel_mgnt.h"   // existing UDS transport
+
+class CUnixTunnelConnection;
+/**
+ * @brief Initialize WinSock on Windows (idempotent).
+ *
+ * This helper ensures WSAStartup() is called only once in the process.
+ * On non-Windows platforms, this is a no-op and always returns success.
+ *
+ * @return 0 on success, otherwise a WinSock error code (Windows only).
+ */
+inline int StartUpWinSock()
+{
+#ifdef _WIN32
+    static bool isInitialized = false;
+    if (isInitialized)
+    {
+        return 0;
+    }
+
+    WSADATA wsaData {};
+    const int error = WSAStartup(MAKEWORD(2, 2), &wsaData);
+    if (error != 0)
+    {
+        SDV_LOG_ERROR("WSAStartup failed with error: ", std::to_string(error));
+    }
+    else
+    {
+        SDV_LOG_INFO("WSAStartup initialized");
+        isInitialized = true;
+    }
+    return error;
+#else
+    // Non-Windows: nothing to do. Return success for symmetry
+    return 0;
+#endif
+}
+/**
+ * @class CUnixTunnelChannelMgnt
+ * @brief IPC channel management class for Unix Domain Socket tunnel communication.
+ *
+ * This manager exposes the "tunnel" IPC type, similar to UDS, with channel multiplexing planned.
+ * It provides creation and access to tunnel endpoints, manages server-side tunnel lifetimes,
+ * and integrates with the SDV object/component framework.
+ */
+class CUnixTunnelChannelMgnt :
+    public sdv::CSdvObject,
+    public sdv::ipc::ICreateEndpoint,
+    public sdv::ipc::IChannelAccess
+{
+public:
+    // Interface map
+    BEGIN_SDV_INTERFACE_MAP()
+        SDV_INTERFACE_ENTRY(sdv::ipc::IChannelAccess)
+        SDV_INTERFACE_ENTRY(sdv::ipc::ICreateEndpoint)
+    END_SDV_INTERFACE_MAP()
+
+    // Object declarations
+    DECLARE_OBJECT_CLASS_TYPE(sdv::EObjectType::system_object)
+    DECLARE_OBJECT_CLASS_NAME("UnixTunnelChannelControl")
+    DECLARE_OBJECT_CLASS_ALIAS("TunnelChannelControl")
+    DECLARE_DEFAULT_OBJECT_NAME("TunnelChannelControl")
+    DECLARE_OBJECT_SINGLETON()
+
+    /**
+     * @brief Destructor for CUnixTunnelChannelMgnt.
+     */
+    virtual ~CUnixTunnelChannelMgnt() = default;
+
+    /**
+     * @brief Initialization event, called after object configuration was loaded. Overload of sdv::CSdvObject::OnInitialize.
+     * @return Returns 'true' when the initialization was successful, 'false' when not.
+     */
+    virtual bool OnInitialize() override;
+
+    /**
+     * @brief Shutdown the object. Overload of sdv::CSdvObject::OnShutdown.
+     */
+    virtual void OnShutdown() override;
+
+    /**
+     * @brief Creates a tunnel endpoint (server side) and returns endpoint info.
+     *
+     * Optionally uses a TOML config string for custom endpoint parameters.
+     *
+     * @param ssChannelConfig Optional config string (TOML).
+     * @return The channel endpoint structure.
+     */
+    sdv::ipc::SChannelEndpoint CreateEndpoint(const sdv::u8string& ssChannelConfig) override;
+
+    /**
+     * @brief Creates or accesses a connection object from the channel connect string.
+     *
+     * Parses the connect string and returns a pointer to the appropriate connection access interface.
+     *
+     * @param ssConnectString The channel connect string.
+     * @return Pointer to connection access interface.
+     */
+    sdv::IInterfaceAccess* Access(const sdv::u8string& ssConnectString) override;
+
+private:
+    /**
+     * @brief Helper: chooses runtime dir (/run/user/<uid>/sdv) or fallback (/tmp/sdv).
+     *
+     * Used for determining the directory path for runtime sockets.
+     *
+     * @return Directory path for runtime sockets.
+     */
+    static std::string MakeUserRuntimeDir();
+
+    /**
+     * @brief Keeps server-side tunnel connections alive for the lifetime of the manager.
+     *
+     * This ensures that server tunnel objects are not destroyed while the manager is active.
+     */
+    std::vector<std::shared_ptr<CUnixTunnelConnection>> m_ServerTunnels;
+};
+
+DEFINE_SDV_OBJECT(CUnixTunnelChannelMgnt)
+
+#endif // UNIX_TUNNEL_CHANNEL_MGNT_H
+#endif // defined(__unix__)

sdv_services/uds_unix_tunnel/connection.cpp

@@ -0,0 +1,230 @@
+/********************************************************************************
+* Copyright (c) 2025-2026 ZF Friedrichshafen AG
+*
+* This program and the accompanying materials are made available under the
+* terms of the Apache License Version 2.0 which is available at
+* https://www.apache.org/licenses/LICENSE-2.0
+*
+* SPDX-License-Identifier: Apache-2.0
+*
+* Contributors:
+*   Denisa Ros - initial API and implementation
+********************************************************************************/
+#if defined(__unix__)
+#include "connection.h"
+
+
+/**
+ * @brief Constructs a tunnel connection wrapper on top of an existing UDS transport.
+ * @param transport Shared pointer to the underlying UDS transport.
+ * @param channelId Logical channel ID for this tunnel instance.
+ */
+CUnixTunnelConnection::CUnixTunnelConnection(
+    std::shared_ptr<CUnixSocketConnection> transport,
+    uint16_t channelId)
+    : m_Transport(std::move(transport))
+    , m_ChannelId(channelId)
+{
+    // No additional initialization required; acts as a thin wrapper.
+}
+
+
+/**
+ * @brief Prepends a tunnel header and forwards the data to the underlying transport.
+ * @param seqData Sequence of message buffers to send (may be modified).
+ * @return true if data was sent successfully, false otherwise.
+ */
+bool CUnixTunnelConnection::SendData(/*inout*/ sdv::sequence<sdv::pointer<uint8_t>>& seqData)
+{
+    if (!m_Transport)
+    {
+        return false;
+    }
+
+    // Build tunnel header buffer
+    sdv::pointer<uint8_t> hdrBuf;
+    hdrBuf.resize(sizeof(STunnelHeader));
+
+    STunnelHeader hdr{};
+    hdr.uiChannelId = m_ChannelId;  // Logical channel for this connection
+    hdr.uiFlags     = 0;            // Reserved for future use
+
+    // Copy header structure into the first buffer (little-endian host layout)
+    std::memcpy(hdrBuf.get(), &hdr, sizeof(STunnelHeader));
+
+    // Compose new sequence: [header] + original payload chunks
+    sdv::sequence<sdv::pointer<uint8_t>> seqWithHdr;
+    seqWithHdr.push_back(hdrBuf);
+    for (auto& chunk : seqData)
+    {
+        seqWithHdr.push_back(chunk);
+    }
+
+    return m_Transport->SendData(seqWithHdr);
+}
+
+
+/**
+ * @brief Starts asynchronous connect and registers upper-layer callbacks.
+ * @param pReceiver Pointer to callback interface for data and state notifications.
+ * @return true if connect started, false otherwise.
+ */
+bool CUnixTunnelConnection::AsyncConnect(/*in*/ sdv::IInterfaceAccess* pReceiver)
+{
+    if (!m_Transport)
+    {
+        return false;
+    }
+
+    // Store upper-layer callbacks (safe for null)
+    {
+        std::lock_guard<std::mutex> lock(m_CallbackMtx);
+        sdv::TInterfaceAccessPtr acc(pReceiver);
+        m_pUpperReceiver = acc.GetInterface<sdv::ipc::IDataReceiveCallback>();
+        m_pUpperEvent    = acc.GetInterface<sdv::ipc::IConnectEventCallback>();
+    }
+
+    // Register this tunnel as the data/event receiver in the UDS transport.
+    // Do NOT pass pReceiver to UDS, only to our upper fields!
+    return m_Transport->AsyncConnect(this);
+}
+
+bool CUnixTunnelConnection::WaitForConnection(/*in*/ uint32_t uiWaitMs)
+{
+    if (!m_Transport)
+    {
+        return false;
+    }
+    return m_Transport->WaitForConnection(uiWaitMs);
+}
+
+void CUnixTunnelConnection::CancelWait()
+{
+    if (!m_Transport)
+    {
+        return;
+    }
+    m_Transport->CancelWait();
+}
+
+void CUnixTunnelConnection::Disconnect()
+{
+    if (!m_Transport)
+    {
+        return;
+    }
+    m_Transport->Disconnect();
+
+    // Clear upper-layer callbacks (thread-safe)
+    std::lock_guard<std::mutex> lock(m_CallbackMtx);
+    m_pUpperReceiver = nullptr;
+    m_pUpperEvent    = nullptr;
+}
+
+uint64_t CUnixTunnelConnection::RegisterStateEventCallback(/*in*/ sdv::IInterfaceAccess* pEventCallback)
+{
+    if (!m_Transport)
+    {
+        return 0ULL;
+    }
+
+    // Directly forward to the underlying transport. This allows external
+    // components to receive connect-state changes without the tunnel
+    // having to implement IConnectEventCallback itself
+    return m_Transport->RegisterStateEventCallback(pEventCallback);
+}
+
+void CUnixTunnelConnection::UnregisterStateEventCallback(/*in*/ uint64_t uiCookie)
+{
+    if (!m_Transport || uiCookie == 0ULL)
+    {
+        return;
+    }
+    m_Transport->UnregisterStateEventCallback(uiCookie);
+}
+
+sdv::ipc::EConnectState CUnixTunnelConnection::GetConnectState() const
+{
+    if (!m_Transport)
+    {
+        // Reasonable default if transport is missing
+        return sdv::ipc::EConnectState::uninitialized;
+    }
+    return m_Transport->GetConnectState();
+}
+
+void CUnixTunnelConnection::DestroyObject()
+{
+    // Disconnect underlying transport and clear callbacks.
+    Disconnect();
+
+    std::lock_guard<std::mutex> lock(m_CallbackMtx);
+    m_Transport.reset();
+}
+
+void CUnixTunnelConnection::ReceiveData(/*inout*/ sdv::sequence<sdv::pointer<uint8_t>>& seqData)
+{
+#ifdef DEBUG_TUNNEL_RECEIVE
+    // Optional debug: count every call and print buffer size.
+    static std::atomic<uint64_t> s_counter{0};
+    auto id = ++s_counter;
+    std::cerr << "[Tunnel] ReceiveData call #" << id
+              << ", seqData.size=" << seqData.size() << std::endl;
+#endif
+
+    if (seqData.empty())
+    {
+        return;
+    }
+
+    // Extract and validate tunnel header, then remove it
+    const auto& hdrChunk = seqData[0];
+    if (hdrChunk.size() < sizeof(STunnelHeader))
+    {
+        return;
+    }
+
+    STunnelHeader hdr{};
+    std::memcpy(&hdr, hdrChunk.get(), sizeof(STunnelHeader));
+
+    seqData.erase(seqData.begin());  // remove header chunk
+
+    // Forward rest of data to upper-layer receiver (set by AsyncConnect)
+    sdv::ipc::IDataReceiveCallback* upper = nullptr;
+    {
+        std::lock_guard<std::mutex> lock(m_CallbackMtx);
+        upper = m_pUpperReceiver;
+    }
+
+    if (upper)
+    {
+        upper->ReceiveData(seqData);
+    }
+}
+
+void CUnixTunnelConnection::SetChannelId(uint16_t channelId)
+{
+    m_ChannelId = channelId;
+}
+
+void CUnixTunnelConnection::SetConnectState(sdv::ipc::EConnectState state)
+{
+    sdv::ipc::IConnectEventCallback* upper = nullptr;
+    {
+        std::lock_guard<std::mutex> lock(m_CallbackMtx);
+        upper = m_pUpperEvent;
+    }
+
+    if (upper)
+    {
+        try
+        {
+            upper->SetConnectState(state);
+        }
+        catch (...)
+        {
+            // Never let user callback crash the transport.
+        }
+    }
+}
+#endif // defined(__unix__)

sdv_services/uds_unix_tunnel/connection.h

@@ -0,0 +1,191 @@
+/********************************************************************************
+* Copyright (c) 2025-2026 ZF Friedrichshafen AG
+*
+* This program and the accompanying materials are made available under the
+* terms of the Apache License Version 2.0 which is available at
+* https://www.apache.org/licenses/LICENSE-2.0
+*
+* SPDX-License-Identifier: Apache-2.0
+*
+* Contributors:
+*   Denisa Ros - initial API and implementation
+********************************************************************************/
+#if defined(__unix__)
+#ifndef UNIX_SOCKET_TUNNEL_CONNECTION_H
+#define UNIX_SOCKET_TUNNEL_CONNECTION_H
+
+#include <interfaces/ipc.h>
+#include <support/component_impl.h>
+#include <support/interface_ptr.h>
+
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <memory>
+#include <thread>
+#include <vector>
+#include <unordered_map>
+
+#include "../sdv_services/uds_unix_sockets/connection.h"   // existing UDS transport
+
+/**
+ * @class CUnixTunnelConnection
+ * @brief Logical tunnel connection on top of a shared Unix Domain Socket (UDS) transport.
+ *
+ * This class wraps an existing CUnixSocketConnection (physical tunnel port) and provides
+ * optional tunneling capabilities such as a prepended tunnel header (channelId, flags).
+ * It is designed to enable demultiplexing of incoming payloads per logical channel in future versions.
+ *
+ * Currently, this acts as a simple pass-through wrapper. Tunnel header parsing and multi-channel
+ * routing are planned as future improvements (see TODOs in implementation).
+ */
+class CUnixTunnelConnection :
+    public sdv::IInterfaceAccess,
+    public sdv::IObjectDestroy,
+    public sdv::ipc::IDataSend,
+    public sdv::ipc::IConnect,
+    public sdv::ipc::IDataReceiveCallback,
+    public sdv::ipc::IConnectEventCallback
+{
+public:
+    /**
+     * @struct STunnelHeader
+     * @brief Small header prepended to each tunneled SDV message.
+     *
+     * Used for logical channel identification and control flags. This enables future support for
+     * multiplexing and advanced features (QoS, direction, etc.).
+     */
+    struct STunnelHeader
+    {
+        uint16_t uiChannelId;  ///< Logical channel ID (e.g., IPC_x / REMOTE_IPC_x)
+        uint16_t uiFlags;      ///< Reserved for future use (QoS, direction, etc.)
+    };
+
+    /**
+     * @brief Constructs a tunnel connection wrapper.
+     * @param transport Shared pointer to the underlying UDS transport (physical tunnel port).
+     * @param channelId Default logical channel ID for this object view (may be ignored if full demux is implemented later).
+     */
+    explicit CUnixTunnelConnection(
+        std::shared_ptr<CUnixSocketConnection> transport,
+        uint16_t channelId);
+
+    /**
+     * @brief Destructor. Cleans up resources if needed.
+     */
+    virtual ~CUnixTunnelConnection() = default;
+
+    BEGIN_SDV_INTERFACE_MAP()
+        SDV_INTERFACE_ENTRY(sdv::ipc::IDataSend)
+        SDV_INTERFACE_ENTRY(sdv::ipc::IConnect)
+        SDV_INTERFACE_ENTRY(sdv::ipc::IDataReceiveCallback)
+        SDV_INTERFACE_ENTRY(sdv::ipc::IConnectEventCallback)
+        SDV_INTERFACE_ENTRY(sdv::IObjectDestroy)
+    END_SDV_INTERFACE_MAP()
+
+    // ---------- IDataSend ----------
+    /**
+     * @brief Sends a sequence of buffers via the tunnel.
+     *
+     * Prepends a STunnelHeader to the outgoing message buffers and forwards them to the underlying UDS transport.
+     * In the current implementation, the channel header is always present but not yet used for multiplexing.
+     *
+     * @param seqData Sequence of message buffers (may be modified by callee).
+     * @return true on successful send, false otherwise.
+     */
+    bool SendData(/*inout*/ sdv::sequence<sdv::pointer<uint8_t>>& seqData) override;
+
+    // ---------- IConnect ----------
+    /**
+     * @brief Starts asynchronous connect on the underlying transport and registers this object as receiver.
+     * @param pReceiver Pointer to callback interface for data and state notifications.
+     * @return true if connect started, false otherwise.
+     */
+    bool AsyncConnect(/*in*/ sdv::IInterfaceAccess* pReceiver) override;
+
+    /**
+     * @brief Waits until the underlying transport becomes 'connected'.
+     *
+     * Forwards to CUnixSocketConnection::WaitForConnection.
+     * @param uiWaitMs Timeout in milliseconds to wait.
+     * @return true if connection established, false on timeout or error.
+     */
+    bool WaitForConnection(/*in*/ uint32_t uiWaitMs) override;
+
+    /**
+     * @brief Cancels any pending connect or wait operation.
+     * Delegated to the underlying transport, if needed.
+     */
+    void CancelWait() override;
+
+    /**
+     * @brief Disconnects the tunnel and underlying transport.
+     */
+    void Disconnect() override;
+
+    /**
+     * @brief Registers a state event callback (forwards to transport).
+     * @param pEventCallback Pointer to event callback interface.
+     * @return Registration cookie (nonzero) or 0 on failure.
+     */
+    uint64_t RegisterStateEventCallback(/*in*/ sdv::IInterfaceAccess* pEventCallback) override;
+
+    /**
+     * @brief Unregisters a previously registered state event callback.
+     * @param uiCookie Registration cookie returned by RegisterStateEventCallback.
+     */
+    void UnregisterStateEventCallback(/*in*/ uint64_t uiCookie) override;
+
+    /**
+     * @brief Gets the current state from the underlying transport.
+     * @return The current connection state.
+     */
+    sdv::ipc::EConnectState GetConnectState() const override;
+
+    // ---------- IObjectDestroy ----------
+    /**
+     * @brief Releases and cleans up all resources associated with this object.
+     */
+    void DestroyObject() override;
+
+    // ---------- IDataReceiveCallback ----------
+    /**
+     * @brief Receives data from the underlying UDS transport.
+     *
+     * Expects the first chunk of seqData to be a STunnelHeader, strips and processes it,
+     * and delivers the remaining payload to the upper-layer receiver registered via AsyncConnect.
+     *
+     * @param seqData Sequence of received message buffers (header chunk is removed by this call).
+     */
+    void ReceiveData(/*inout*/ sdv::sequence<sdv::pointer<uint8_t>>& seqData) override;
+
+    // ---------- IConnectEventCallback ----------
+    /**
+     * @brief Forwards state changes from the underlying UDS transport to the upper layer.
+     * @param state New connection state.
+     */
+    void SetConnectState(sdv::ipc::EConnectState state) override;
+
+    /**
+     * @brief Assigns a logical channel ID for this connection.
+     * Optional helper; you may extend with more routing metadata for advanced tunnel use-cases.
+     * @param channelId The logical channel ID to set.
+     */
+    void SetChannelId(uint16_t channelId);
+
+    /**
+     * @brief Get the logical channel ID for this connection
+     * @return The channel ID
+     */
+    uint16_t GetChannelId() const noexcept { return m_ChannelId; }
+
+private:
+    std::shared_ptr<CUnixSocketConnection> m_Transport;             ///< shared physical tunnel port
+    uint16_t m_ChannelId {0};                                       ///< default logical channel id
+    sdv::ipc::IDataReceiveCallback* m_pUpperReceiver {nullptr};     ///< Callback to upper layer (data receive)
+    sdv::ipc::IConnectEventCallback* m_pUpperEvent {nullptr};       ///< Callback to upper layer (state event)
+    mutable std::mutex m_CallbackMtx;                               ///< Mutex to guard callback access
+};
+
+#endif // UNIX_SOCKET_TUNNEL_CONNECTION_H
+#endif // defined(__unix__)