diff options
Diffstat (limited to 'src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt')
| -rw-r--r-- | src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt new file mode 100644 index 0000000000..3a5d0f0e91 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt @@ -0,0 +1,89 @@ +/** @page components_transportmanager_internal_design_transport_adapters Device Adapters + * + * TransportManager communicates with actual devices via device adapters. + * + * @section components_transportmanager_internal_design_transport_adapters_common Common logic + * + * Logic common to all device adapters is implemented in class NsSmartDeviceLink::NsTransportManager::CTransportAdapter. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_devices_map Devices map + * + * Devices map is a map of device handle to internal device structure NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SDevice. + * Devices map is stored in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDevices. Any access to this map must be performed + * with NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDevicesMutex locked. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connections_map Connections map + * + * Connections map is a map of connection handle to internal connection structure NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection. + * Connections map is stored in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mConnections. Any access to this map must be performed + * with NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mConnectionsMutex locked. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_main_thread Device adapter main thread + * + * Device adapter main thread is started in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::run(). + * Specific device adapter must implement virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mainThread() + * and implement its specific main thread logic there. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connection_thread Device adapter connection thread + * + * Device adapter connection thread is started in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::startConnection(). + * Specific device adapter must implement virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::connectionThread() + * and implement its specific connection thread logic there. When connection is established and socket file descriptor is set + * in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mConnectionSocket specific device adapter may call + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::handleCommunication() to handle all communication through this socket + * until connection is terminated. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_threads_termination Termination of device adapter threads + * + * Specific device adapter implementation must call in its destructor NsSmartDeviceLink::NsTransportManager::CTransportAdapter::waitForThreadsTermination() + * to wait for termination of all threads (main thread and connection threads). Device adapter threads must be terminated before specific + * device adapter class is destructed, so it can't be called in the destructor of base class and must be called explicitly from the inherited + * class's destructor. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_device_scan Requesting scan for new devices + * + * Device scan is requested by setting flag NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDeviceScanRequested + * and signaling conditional variable NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDeviceScanRequestedCond, which may be monitored + * by specific device adapter if it supports device scanning. Specific device adaptere may call for this purpose + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::waitForDeviceScanRequest() which will wait on this conditional variable + * until it's signaled or specified timeout expires. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connecting_devices Connecting devices + * + * Device connection is initiated with a call to NsSmartDeviceLink::NsTransportManager::CTransportAdapter::connectDevice(). + * This method calls virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::createConnectionsListForDevice() + * which may be implemented by specific device adapter to create a list of connections that must be established for the device. + * For each connection created by device adapter it calls NsSmartDeviceLink::NsTransportManager::CTransportAdapter::startConnection() + * which adds connection to connections map and starts connection thread. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_disconnecting_devices Disconnecting devices + * + * Device disconnection is initiated with a call to NsSmartDeviceLink::NsTransportManager::CTransportAdapter::disconnectDevice(). + * This method finds all connections in connections map that corresponds to specified device and calls + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::stopConnection() for each of them. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_handling_communication Handling communication + * + * All frames requested to be sent via NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() are stored in + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mFramesToSend. Pipe + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mNotificationPipeFds is used by + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() to notify connection thread that data is available + * to be sent. NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() writes one byte to the write end of this pipe. + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::handleCommunication() uses poll() to wait for + * incoming data using connection socket file descriptor and outgoing data using file descriptor of the read end of this pipe. + * When either of them become available for reading or some error occurs (e.g. socket gets disconnected) connection thread + * wakes up and handles this event. Notification pipe is also used to notify connection thread that connection has to be + * terminated using NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mTerminateFlag. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_update_client_device_list Updating client device list. + * + * Specific device adapter may call NsSmartDeviceLink::NsTransportManager::CTransportAdapter::updateClientDeviceList() when its internal + * knowledge about available devices is updated to notify device adapter client (TransportManager) about this update. + * + * @section components_transportmanager_internal_design_transport_adapters_common_specific Specific device adapters + * + * Current TransportManager implementation contains following device adapters: + * + * - @subpage components_transportmanager_internal_design_transport_adapters_bluetooth_adapter "Bluetooth Adapter" + * - @subpage components_transportmanager_internal_design_transport_adapters_tcp_adapter "TCP Adapter" + */ |