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 ( LOCAL_NETWORK ). This is checked through the CYINetworkInformationBridge, and just checks if a network device is configured.
2. Connectivity to the internet ( INTERNET ). This is done by performing an HTTP request to a server on the web.
3. Connectivity to an application server ( APPLICATION_SERVER ). 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 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 {   NO_CONNECTIVITY = 0x00,   LOCAL_NETWORK = 0x01,   INTERNET = 0x02,   APPLICATION_SERVER = 0x04 }

Public Member Functions
	CYIConnectivity ()
virtual	~CYIConnectivity ()
void	StartPeriodicChecker ()
void	StopPeriodicChecker ()
bool	IsCheckerRunning () const
bool	IsWaitingOnNetwork () const
void	ProbeState ()
TYPE	GetState () const
void	SetApplicationURL (const CYIUrl &url)
void	SetPeriodicCheckInterval (uint64_t uIntervalMs)
void	SetNetworkCheckTimeout (uint64_t uTimeoutMs)
Public Member Functions inherited from CYISignalHandler
	CYISignalHandler ()
	CYISignalHandler (const CYISignalHandler &rSignalHandler)
virtual	~CYISignalHandler ()
CYISignalHandler &	operator= (const CYISignalHandler &rSignalHandler)
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 &rThreadAffinity)
virtual bool	IsConnected () const
virtual bool	IsConnected (const CYISignalBase &rSignal) const
void	Disconnect (CYISignalBase &rSignal)
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 Member Functions inherited from CYIScriptableObject
	CYIScriptableObject ()
	CYIScriptableObject (const CYIScriptableObject &other)
CYIScriptableObject &	operator= (const CYIScriptableObject &other)
virtual	~CYIScriptableObject ()
CYIBindingImplementation *	GetBindingImplementation () const
void	SetBindingImplementation (CYIBindingImplementation *pBindingImplementation)
virtual const CYIRuntimeTypeInfo *	GetRuntimeTypeInfoForScriptObject () const

Public Attributes
CYISignal< TYPE >	StateChanged
CYISignal< TYPE >	ProbeCompleted

Member Enumeration Documentation

enum CYIConnectivity::TYPE

An enum representing the various possible network connectivity states.

Enumerator
NO_CONNECTIVITY	No network connectivity is available.
LOCAL_NETWORK	Connectivity to the local network is available.
INTERNET	Connectivity to the internet is available. Implies that connectivity to the local network is available.
APPLICATION_SERVER	Connectivity to the application servers is available. Implies that connectivity to the local network and internet is available.

Constructor & Destructor Documentation

CYIConnectivity::CYIConnectivity

(

)

virtual CYIConnectivity::~CYIConnectivity ( )

virtual

Member Function Documentation

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()

bool CYIConnectivity::IsCheckerRunning

(

)

const

Returns true if the periodic checks for connectivity are active.

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.

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.

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.

void CYIConnectivity::SetNetworkCheckTimeout

(

uint64_t

uTimeoutMs

)

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.

void CYIConnectivity::SetPeriodicCheckInterval

(

uint64_t

uIntervalMs

)

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.

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.

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

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.

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:

• network/YiConnectivity.h