imtcom::IConnectionStatusProvider

Interface for monitoring network connection status with observable state changes. More...

#include <IConnectionStatusProvider.h>

Inheritance diagram for imtcom::IConnectionStatusProvider:

Public Types
enum	ConnectionStatus { CS_UNKNOWN = 0 , CS_DISCONNECTED , CS_CONNECTED }
	Connection status enumeration. More...

Public Member Functions
virtual ConnectionStatus	GetConnectionStatus () const =0
	Get the current connection status.

Detailed Description

Interface for monitoring network connection status with observable state changes.

The IConnectionStatusProvider defines a contract for components that monitor network connectivity and provide real-time status updates. It extends IChangeable to support reactive programming patterns, allowing clients to observe connection state transitions.

This interface is central to connection health monitoring in ImtCore, supporting various monitoring strategies from simple endpoint checks to comprehensive internet availability detection.

Key Features

Observable Status:

• Extends istd::IChangeable for change notifications
• Clients can react to connection state transitions
• Supports event-driven architectures
• Enables UI updates without polling

Three-State Model:

• CS_UNKNOWN: Initial state or monitoring disabled
• CS_DISCONNECTED: Connection is down or unreachable
• CS_CONNECTED: Connection is established and healthy

Multiple Strategies:

• Async timer-based checks (CAsyncConnectionCheckerComp)
• GraphQL endpoint validation (CSimpleConnectionCheckerComp)
• Internet connectivity detection (CInternetConnectionCheckerComp)

Connection States

CS_UNKNOWN (0)

Meaning: Connection status has not been determined yet.

Typical Scenarios:

• Initial state before first health check
• Monitoring disabled or not started
• Error in status determination logic
• After Reset() call

Recommended Actions:

• Show loading/initializing indicator in UI
• Wait for first status update
• Do not enable connection-dependent features yet

CS_DISCONNECTED (1)

Meaning: Connection is unavailable, unreachable, or failed health check.

Typical Scenarios:

• Network interface down
• Server not responding (timeout)
• DNS resolution failure
• HTTP error response (4xx, 5xx)
• WebSocket connection closed
• GraphQL query failed

Recommended Actions:

• Show "offline" or "disconnected" indicator
• Disable network-dependent UI features
• Queue operations for retry when reconnected
• Implement exponential backoff for reconnection attempts
• Log diagnostic information for troubleshooting

CS_CONNECTED (2)

Meaning: Connection is established and health check succeeded.

Typical Scenarios:

• HTTP endpoint returned 2xx status
• WebSocket connection established
• GraphQL query executed successfully
• Periodic health check passed

Recommended Actions:

• Show "online" or "connected" indicator
• Enable network-dependent features
• Process queued operations
• Reset retry backoff timer

Implementations

CAsyncConnectionCheckerComp

Strategy: Timer-based asynchronous HTTP requests

Features:

• Configurable check interval (e.g., every 30 seconds)
• Timeout support for slow connections
• Retry logic with exponential backoff
• Non-blocking checks via QTimer

Use Cases:

• Periodic health monitoring
• Server availability detection
• Network connectivity validation

Configuration:

• Check interval (milliseconds)
• Request timeout (milliseconds)
• Maximum retry count
• Target URL for health checks

CSimpleConnectionCheckerComp

Strategy: GraphQL client request validation

Features:

• Application-level connectivity check
• Validates full stack (network + auth + GraphQL)
• Uses actual application endpoints
• Tests real communication paths

Use Cases:

• End-to-end application connectivity
• Post-authentication validation
• Service-specific health checks

Benefits:

• Tests actual application protocols
• Detects authentication failures
• Validates complete request pipeline

CInternetConnectionCheckerComp

Strategy: External internet availability detection

Features:

• Checks connectivity to well-known sites (e.g., Google)
• Differentiates between local network and internet issues
• Configurable target URLs
• Timeout and retry support

Use Cases:

• General internet availability detection
• Network diagnostics
• Differentiating local vs. remote issues

Configuration:

• Target URL (default: google.com)
• Check interval
• Timeout settings

Usage Examples

Basic Usage

// Create connection checker
auto checker = icomp::CreateComponent<CAsyncConnectionCheckerComp>();
 
// Configure via component attributes (check interval, timeout, etc.)
// ...
 
// Get current status
auto status = checker->GetConnectionStatus();
switch (status) {
    case IConnectionStatusProvider::CS_CONNECTED:
        qDebug() << "Online";
        break;
    case IConnectionStatusProvider::CS_DISCONNECTED:
        qDebug() << "Offline";
        break;
    case IConnectionStatusProvider::CS_UNKNOWN:
        qDebug() << "Status unknown";
        break;
}

Observing Status Changes

// Subscribe to status changes
QObject::connect(checker.get(), &istd::IChangeable::OnChanged,
    [checker](const istd::IChangeable::ChangeSet& changeSet) {
        auto status = checker->GetConnectionStatus();
        
        if (status == IConnectionStatusProvider::CS_CONNECTED) {
            qDebug() << "Connection restored!";
            // Enable network features, process queued operations
            ProcessQueuedRequests();
        } else if (status == IConnectionStatusProvider::CS_DISCONNECTED) {
            qWarning() << "Connection lost!";
            // Disable network features, show offline indicator
            ShowOfflineIndicator();
        }
    });

Retry Logic with Exponential Backoff

class ConnectionManager {
public:
    ConnectionManager(IConnectionStatusProvider* checker) 
        : m_checker(checker), m_retryDelay(1000) {
        connect(checker, &IChangeable::OnChanged, 
                this, &ConnectionManager::OnStatusChanged);
    }
    
private:
    void OnStatusChanged() {
        auto status = m_checker->GetConnectionStatus();
        
        if (status == IConnectionStatusProvider::CS_CONNECTED) {
            m_retryDelay = 1000;  // Reset backoff
            qDebug() << "Connected successfully";
        } else if (status == IConnectionStatusProvider::CS_DISCONNECTED) {
            // Schedule retry with exponential backoff
            QTimer::singleShot(m_retryDelay, this, &ConnectionManager::AttemptReconnect);
            m_retryDelay = qMin(m_retryDelay * 2, 60000);  // Max 60 seconds
            qWarning() << "Disconnected, retry in" << m_retryDelay << "ms";
        }
    }
    
    void AttemptReconnect() {
        // Trigger reconnection logic
    }
    
    IConnectionStatusProvider* m_checker;
    int m_retryDelay;
};

UI Status Indicator

// QML example with model update binder
class ConnectionStatusModel : public QObject {
    Q_OBJECT
    Q_PROPERTY(QString statusText READ statusText NOTIFY statusChanged)
    Q_PROPERTY(QColor statusColor READ statusColor NOTIFY statusChanged)
    
public:
    ConnectionStatusModel(IConnectionStatusProvider* provider)
        : m_observer(this, &ConnectionStatusModel::OnStatusChanged) {
        m_observer.Observe(provider);
    }
    
signals:
    void statusChanged();
    
private:
    void OnStatusChanged(const IChangeable::ChangeSet&,
                        const IConnectionStatusProvider* provider) {
        m_status = provider->GetConnectionStatus();
        emit statusChanged();
    }
    
    QString statusText() const {
        switch (m_status) {
            case CS_CONNECTED: return "Online";
            case CS_DISCONNECTED: return "Offline";
            default: return "Unknown";
        }
    }
    
    QColor statusColor() const {
        switch (m_status) {
            case CS_CONNECTED: return QColor(Qt::green);
            case CS_DISCONNECTED: return QColor(Qt::red);
            default: return QColor(Qt::gray);
        }
    }
    
    ConnectionStatus m_status = CS_UNKNOWN;
    TModelUpdateBinder<IConnectionStatusProvider, ConnectionStatusModel> m_observer;
};

Best Practices

Check Intervals:

• Balance responsiveness vs. resource usage
• Typical range: 10-60 seconds
• More frequent for critical connections (5-10 seconds)
• Less frequent for background monitoring (60+ seconds)

Timeout Configuration:

• Set reasonable timeouts (5-10 seconds typical)
• Avoid very short timeouts (< 1 second) - may cause false negatives
• Avoid very long timeouts (> 30 seconds) - delays status updates

Retry Logic:

• Always implement exponential backoff
• Set maximum retry delay (e.g., 60 seconds)
• Reset backoff on successful connection
• Consider jitter to avoid thundering herd

Observable Pattern:

• Always use IChangeable notifications, not polling
• Unsubscribe from observers when no longer needed
• Handle both CS_CONNECTED and CS_DISCONNECTED transitions
• Account for CS_UNKNOWN initial state in UI

Error Handling:

• Log connection failures with diagnostic details
• Differentiate between transient and persistent failures
• Provide user feedback for prolonged disconnection
• Consider implementing connection quality metrics (not just binary on/off)

See also

CAsyncConnectionCheckerComp, CSimpleConnectionCheckerComp, CInternetConnectionCheckerComp

istd::IChangeable, imtbase::TModelUpdateBinder

Definition at line 320 of file IConnectionStatusProvider.h.

Member Enumeration Documentation

ConnectionStatus

enum imtcom::IConnectionStatusProvider::ConnectionStatus

Connection status enumeration.

Represents the current state of network connectivity as determined by the monitoring implementation.

See also

GetConnectionStatus()

Enumerator
CS_UNKNOWN	Connection status unknown or not yet determined.
CS_DISCONNECTED	Connection is unavailable or failed health check.
CS_CONNECTED	Connection is established and healthy.

Definition at line 332 of file IConnectionStatusProvider.h.

Member Function Documentation

GetConnectionStatus()

virtual ConnectionStatus imtcom::IConnectionStatusProvider::GetConnectionStatus ( ) const

pure virtual

Get the current connection status.

Returns the current state of the connection as determined by the most recent health check or monitoring activity.

This method is typically very lightweight and suitable for frequent calls, as it returns cached status rather than performing an actual connectivity test.

Returns

Current connection status (CS_UNKNOWN, CS_DISCONNECTED, or CS_CONNECTED).

See also

ConnectionStatus

Example:

auto status = statusProvider->GetConnectionStatus();
if (status == IConnectionStatusProvider::CS_CONNECTED) {
    // Safe to perform network operations
    SendNetworkRequest();
} else {
    // Connection unavailable, queue operation or show error
    QueueForLater();
}

Note

Status changes trigger IChangeable::OnChanged notifications. Subscribe to these signals rather than polling GetConnectionStatus() for reactive updates.