You.i Engine
CYIConnectivity Class Reference

Detailed Description

A class used to perform active network connectivity checks.

This class allows for active network connectivity checks to be performed, either on a per-request basis, or on a periodic basis. This differs from the CYINetworkInformationBridge class, which only performs passive checks.

Three 'levels' of network connectivity can be checked:

  1. Connectivity to the local network (CYIConnectivity::Type::LocalNetwork). This is checked through the CYINetworkInformationBridge, and just checks if a network device is configured.
  2. Connectivity to the internet (CYIConnectivity::Type::Internet). This is done by performing an HTTP request to a server on the web.
  3. Connectivity to an application server (CYIConnectivity::Type::ApplicationServer). This is performed optionally if the user has specified an application URL to check. Again, this is done by performing an HTTP request to that URL.

If the reported connectivity is CYIConnectivity::Type::Internet, it also implies that connectivity to the local network is available. Similarly, connectivity to application servers imply connectivity to internet and local network.

The periodic connectivity checks are enabled by the StartPeriodicChecker() function, and are stopped by the StopPeriodicChecker() function.

Whether the periodic checkers are running or not, the user can request a 'one shot' connectivity check using the ProbeState function. When the probe completes, the ProbeCompleted signal is emitted with the connectivity state. The signal will be emitted even if the connectivity state has not changed.

When the connectivity state is detected as having changed (either due to periodic check or due to a manually-requested check), the StateChanged is called with the new connectivity state.

Note
The behaviour of the ProbeState() function changes if the periodic state checks are running. If a check is currently in progress, the result of that check is returned through the ProbeCompleted signal. If a check is not currently in progress, a check will be made immediately and the periodic checks will be delayed.
While a GetState() function is provided, that function does not perform any checks and simply returns the last known connectivity value. Thus, this function will not give accurate information unless the periodic checks are running, or the user has recently called the ProbeState() function.
This class makes use of the CYIHTTPService class, and thus the CYIHTTPService instance must be started for this class to be usable. If the CYIHTTPService instance is not started, this class will always report NO_CONNECTIVITY as the network connectivity.

#include <network/YiConnectivity.h>

Inheritance diagram for CYIConnectivity:

Public Types

enum  Type {
  Type::NoConnectivity = 0x00,
  Type::LocalNetwork = 0x01,
  Type::Internet = 0x02,
  Type::ApplicationServer = 0x04
}
 

Public Member Functions

 CYIConnectivity ()
 
virtual ~CYIConnectivity ()
 
void StartPeriodicChecker ()
 
void StopPeriodicChecker ()
 
bool IsCheckerRunning () const
 
bool IsWaitingOnNetwork () const
 
void ProbeState ()
 
Type GetState () const
 
const CYIUrlGetInternetURL () const
 
const CYIUrlGetApplicationURL () const
 
void SetApplicationURL (const CYIUrl &url)
 
void SetPeriodicCheckInterval (uint64_t intervalMs)
 
void SetNetworkCheckTimeout (uint64_t timeoutMs)
 
- Public Member Functions inherited from CYISignalHandler
 CYISignalHandler ()
 
 CYISignalHandler (const CYISignalHandler &signalHandler)
 
virtual ~CYISignalHandler ()
 
CYISignalHandleroperator= (const CYISignalHandler &signalHandler)
 
void MoveToThread (CYIThread *pThread)
 This function allows the user to override the default thread affinity to any CYIThread that may or may not be running. More...
 
CYIThreadHandle GetThreadAffinity () const
 
void SetThreadAffinity (const CYIThreadHandle &threadAffinity)
 
virtual bool IsConnected () const
 
virtual bool IsConnected (const CYISignalBase &signal) const
 
void Disconnect (CYISignalBase &signal)
 
void DisconnectFromAllSignals ()
 
- Public Member Functions inherited from CYIThread::Listener
 Listener ()
 
virtual ~Listener ()
 
virtual void OnThreadStarted (CYIThread *)
 
virtual void OnThreadTerminated (CYIThread *)
 
virtual void OnThreadFinished (CYIThread *)
 

Public Attributes

CYISignal< TypeStateChanged
 
CYISignal< TypeProbeCompleted
 

Member Enumeration Documentation

◆ Type

enum CYIConnectivity::Type
strong

An enum representing the various possible network connectivity states.

Enumerator
NoConnectivity 

No network connectivity is available.

LocalNetwork 

Connectivity to the local network is available.

Internet 

Connectivity to the internet is available. Implies that connectivity to the local network is available.

ApplicationServer 

Connectivity to the application servers is available. Implies that connectivity to the local network and internet is available.

Constructor & Destructor Documentation

◆ CYIConnectivity()

CYIConnectivity::CYIConnectivity ( )

◆ ~CYIConnectivity()

virtual CYIConnectivity::~CYIConnectivity ( )
virtual

Member Function Documentation

◆ GetApplicationURL()

const CYIUrl& CYIConnectivity::GetApplicationURL ( ) const

Returns the URL which is used to perform checks for connectivity to the application server.

See also
SetApplicationURL

◆ GetInternetURL()

const CYIUrl& CYIConnectivity::GetInternetURL ( ) const

Returns the URL which is used to perform checks for connectivity to the internet.

◆ GetState()

Type CYIConnectivity::GetState ( ) const

Returns the current connectivity state.

Warning
This function does not perform any connectivity checks! It only returns the value of the last known connectivity state.
See also
ProbeState()
StartPeriodicChecker()

◆ IsCheckerRunning()

bool CYIConnectivity::IsCheckerRunning ( ) const

Returns true if the periodic checks for connectivity are active.

◆ IsWaitingOnNetwork()

bool CYIConnectivity::IsWaitingOnNetwork ( ) const

Returns true if a network connectivity check is currently in progress. Both periodic connectivity checks and state probes can cause this function to return true.

Note
This function is mostly used for debugging purposes.

◆ ProbeState()

void CYIConnectivity::ProbeState ( )

Requests that a network connectivity check be performed. Once the check has been performed, the ProbeComplete signal is emitted with the connectivity state.

◆ SetApplicationURL()

void CYIConnectivity::SetApplicationURL ( const CYIUrl url)

Sets the URL to be used for performing application server connectivity checks. If a blank URL is provided, no application server checks are performed. By default, no application server checks are performed.

◆ SetNetworkCheckTimeout()

void CYIConnectivity::SetNetworkCheckTimeout ( uint64_t  timeoutMs)

Sets how long HTTP requests are allowed to run before timing out.

Note
If this value is larger than the periodic check interval, then all checks performed by the periodic checks will report NO_CONNECTIVITY.

◆ SetPeriodicCheckInterval()

void CYIConnectivity::SetPeriodicCheckInterval ( uint64_t  intervalMs)

Sets the frequency at which periodic network connectivity checks are made. For example, calling this function with a value of 5000 will result in periodic checks being performed every 5 seconds.

◆ StartPeriodicChecker()

void CYIConnectivity::StartPeriodicChecker ( )

Starts performing periodic checks for connectivity. This will result in 1-2 HTTP requests being performed every 5 seconds (by default). Has no effect if periodic checks are already running.

When the network connectivity state is detected as having changed, the StateChanged signal is emitted with the new connectivity state.

The check interval can be configured using the SetPeriodicCheckInterval function.

◆ StopPeriodicChecker()

void CYIConnectivity::StopPeriodicChecker ( )

Stops performing periodic checks for connectivity. Has no effect if periodic checks are not currently running.

Note
Normally, outstanding network check requests are cancelled by a call to this function. However, if the user has requested a state probe then the existing network check request will be allowed to complete.

Member Data Documentation

◆ ProbeCompleted

CYISignal<Type> CYIConnectivity::ProbeCompleted

A signal emitted when a state probe requested by the user (through the ProbeState() function) has completed. This signal is emitted even if the probe revealed no change in the network connectivity state.

◆ StateChanged

CYISignal<Type> CYIConnectivity::StateChanged

A signal emitted when a network connectivity change is detected (either through periodic checks or through a user-triggered state probe).


The documentation for this class was generated from the following file: