ConnectivityDiagnosticsManager
public
class
ConnectivityDiagnosticsManager
extends Object
java.lang.Object | |
↳ | android.net.ConnectivityDiagnosticsManager |
Class that provides utilities for collecting network connectivity diagnostics information. Connectivity information is made available through triggerable diagnostics tools and by listening to System validations. Some diagnostics information may be permissions-restricted.
ConnectivityDiagnosticsManager is intended for use by applications offering network connectivity on a user device. These tools will provide several mechanisms for these applications to be alerted to network conditions as well as diagnose potential network issues themselves.
The primary responsibilities of this class are to:
- Allow permissioned applications to register and unregister callbacks for network event notifications
- Invoke callbacks for network event notifications, including:
- Network validations
- Data stalls
- Connectivity reports from applications
Summary
Nested classes | |
---|---|
class |
ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback
Abstract base class for Connectivity Diagnostics callbacks. |
class |
ConnectivityDiagnosticsManager.ConnectivityReport
Class that includes connectivity information for a specific Network at a specific time. |
class |
ConnectivityDiagnosticsManager.DataStallReport
Class that includes information for a suspected data stall on a specific Network |
Public methods | |
---|---|
void
|
registerConnectivityDiagnosticsCallback(NetworkRequest request, Executor e, ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback callback)
Registers a ConnectivityDiagnosticsCallback with the System. |
void
|
unregisterConnectivityDiagnosticsCallback(ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback callback)
Unregisters a ConnectivityDiagnosticsCallback with the System. |
Inherited methods | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Public methods
registerConnectivityDiagnosticsCallback
public void registerConnectivityDiagnosticsCallback (NetworkRequest request, Executor e, ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback callback)
Registers a ConnectivityDiagnosticsCallback with the System.
Only apps that offer network connectivity to the user should be registering callbacks. These are the only apps whose callbacks will be invoked by the system. Apps considered to meet these conditions include:
- Carrier apps with active subscriptions
- Active VPNs
- WiFi Suggesters
Callbacks registered by apps not meeting the above criteria will not be invoked.
If a registering app loses its relevant permissions, any callbacks it registered will silently stop receiving callbacks. Note that registering apps must also have location permissions to receive callbacks as some Networks may be location-bound (such as WiFi networks).
Each register() call MUST use a ConnectivityDiagnosticsCallback instance that is not currently registered. If a ConnectivityDiagnosticsCallback instance is registered with multiple NetworkRequests, an IllegalArgumentException will be thrown.
To avoid performance issues due to apps leaking callbacks, the system will limit the
number of outstanding requests to 100 per app (identified by their UID), shared with
callbacks in ConnectivityManager
. Registering a callback with this method will count
toward this limit. If this limit is exceeded, an exception will be thrown. To avoid hitting
this issue and to conserve resources, make sure to unregister the callbacks with
unregisterConnectivityDiagnosticsCallback(ConnectivityDiagnosticsCallback)
.
Parameters | |
---|---|
request |
NetworkRequest : The NetworkRequest that will be used to match with Networks for which
callbacks will be fired
This value cannot be null . |
e |
Executor : The Executor to be used for running the callback method invocations
This value cannot be null . |
callback |
ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback : The ConnectivityDiagnosticsCallback that the caller wants registered with the
System
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if the same callback instance is registered with multiple NetworkRequests |
RuntimeException |
if the app already has too many callbacks registered. |
unregisterConnectivityDiagnosticsCallback
public void unregisterConnectivityDiagnosticsCallback (ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback callback)
Unregisters a ConnectivityDiagnosticsCallback with the System.
If the given callback is not currently registered with the System, this operation will be a no-op.
Parameters | |
---|---|
callback |
ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback : The ConnectivityDiagnosticsCallback to be unregistered from the System.
This value cannot be null . |