ConnectivityManager
public
class
ConnectivityManager
extends Object
java.lang.Object | |
↳ | android.net.ConnectivityManager |
Class that answers queries about the state of network connectivity. It also notifies applications when network connectivity changes.
The primary responsibilities of this class are to:
- Monitor network connections (Wi-Fi, GPRS, UMTS, etc.)
- Send broadcast intents when network connectivity changes
- Attempt to "fail over" to another network when connectivity to a network is lost
- Provide an API that allows applications to query the coarse-grained or fine-grained state of the available networks
- Provide an API that allows applications to request and select networks for their data traffic
Summary
Nested classes | |
---|---|
class |
ConnectivityManager.NetworkCallback
Base class for |
interface |
ConnectivityManager.OnNetworkActiveListener
Callback for use with |
Constants | |
---|---|
String |
ACTION_BACKGROUND_DATA_SETTING_CHANGED
This constant was deprecated
in API level 16.
As of |
String |
ACTION_CAPTIVE_PORTAL_SIGN_IN
The device has connected to a network that has presented a captive portal, which is blocking Internet connectivity. |
String |
ACTION_RESTRICT_BACKGROUND_CHANGED
A change in the background metered network activity restriction has occurred. |
String |
CONNECTIVITY_ACTION
This constant was deprecated
in API level 28.
apps should use the more versatile |
int |
DEFAULT_NETWORK_PREFERENCE
This constant was deprecated
in API level 18.
Since we support so many more networks now, the single
network default network preference can't really express
the hierarchy. Instead, the default is defined by the
networkAttributes in config.xml. You can determine
the current value by calling |
String |
EXTRA_CAPTIVE_PORTAL
The lookup key for a |
String |
EXTRA_CAPTIVE_PORTAL_URL
Key for passing a URL to the captive portal login activity. |
String |
EXTRA_EXTRA_INFO
This constant was deprecated
in API level 29.
See |
String |
EXTRA_IS_FAILOVER
This constant was deprecated
in API level 29.
See |
String |
EXTRA_NETWORK
The lookup key for a |
String |
EXTRA_NETWORK_INFO
This constant was deprecated
in API level 15.
The |
String |
EXTRA_NETWORK_REQUEST
The lookup key for a |
String |
EXTRA_NETWORK_TYPE
This constant was deprecated
in API level 29.
The network type is not rich enough to represent the characteristics
of modern networks. Please use |
String |
EXTRA_NO_CONNECTIVITY
The lookup key for a boolean that indicates whether there is a complete lack of connectivity, i.e., no network is available. |
String |
EXTRA_OTHER_NETWORK_INFO
This constant was deprecated
in API level 29.
See |
String |
EXTRA_REASON
The lookup key for a string that indicates why an attempt to connect to a network failed. |
int |
MULTIPATH_PREFERENCE_HANDOVER
It is acceptable to briefly use multipath data to provide seamless connectivity for time-sensitive user-facing operations when the system default network is temporarily unresponsive. |
int |
MULTIPATH_PREFERENCE_PERFORMANCE
It is acceptable to use metered data to improve network latency and performance. |
int |
MULTIPATH_PREFERENCE_RELIABILITY
It is acceptable to use small amounts of multipath data on an ongoing basis to provide a backup channel for traffic that is primarily going over another network. |
int |
RESTRICT_BACKGROUND_STATUS_DISABLED
Device is not restricting metered network activity while application is running on background. |
int |
RESTRICT_BACKGROUND_STATUS_ENABLED
Device is restricting metered network activity while application is running on background. |
int |
RESTRICT_BACKGROUND_STATUS_WHITELISTED
Device is restricting metered network activity while application is running on background, but application is allowed to bypass it. |
int |
TYPE_BLUETOOTH
This constant was deprecated
in API level 28.
Applications should instead use |
int |
TYPE_DUMMY
This constant was deprecated in API level 28. This is not used any more. |
int |
TYPE_ETHERNET
This constant was deprecated
in API level 28.
Applications should instead use |
int |
TYPE_MOBILE
This constant was deprecated
in API level 28.
Applications should instead use |
int |
TYPE_MOBILE_DUN
This constant was deprecated
in API level 28.
Applications should instead use |
int |
TYPE_MOBILE_HIPRI
This constant was deprecated
in API level 23.
Applications should instead use |
int |
TYPE_MOBILE_MMS
This constant was deprecated
in API level 23.
Applications should instead use |
int |
TYPE_MOBILE_SUPL
This constant was deprecated
in API level 23.
Applications should instead use |
int |
TYPE_VPN
This constant was deprecated
in API level 28.
Applications should use |
int |
TYPE_WIFI
This constant was deprecated
in API level 28.
Applications should instead use |
int |
TYPE_WIMAX
This constant was deprecated
in API level 28.
Applications should instead use |
Public methods | |
---|---|
void
|
addDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener l)
Start listening to reports when the system's default data network is active, meaning it is a good time to perform network traffic. |
boolean
|
bindProcessToNetwork(Network network)
Binds the current process to |
SocketKeepalive
|
createSocketKeepalive(Network network, IpSecManager.UdpEncapsulationSocket socket, InetAddress source, InetAddress destination, Executor executor, SocketKeepalive.Callback callback)
Request that keepalives be started on a IPsec NAT-T socket. |
Network
|
getActiveNetwork()
Returns a |
NetworkInfo
|
getActiveNetworkInfo()
This method was deprecated
in API level 29.
See |
NetworkInfo[]
|
getAllNetworkInfo()
This method was deprecated
in API level 23.
This method does not support multiple connected networks
of the same type. Use |
Network[]
|
getAllNetworks()
This method was deprecated
in API level 31.
This method does not provide any notification of network state changes, forcing
apps to call it repeatedly. This is inefficient and prone to race conditions.
Apps should use methods such as
|
boolean
|
getBackgroundDataSetting()
This method was deprecated
in API level 15.
As of |
Network
|
getBoundNetworkForProcess()
Returns the |
int
|
getConnectionOwnerUid(int protocol, InetSocketAddress local, InetSocketAddress remote)
Returns the |
ProxyInfo
|
getDefaultProxy()
Get the current default HTTP proxy settings. |
LinkProperties
|
getLinkProperties(Network network)
Get the |
int
|
getMultipathPreference(Network network)
Provides a hint to the calling application on whether it is desirable to use the
multinetwork APIs (e.g., |
NetworkCapabilities
|
getNetworkCapabilities(Network network)
Get the |
NetworkInfo
|
getNetworkInfo(int networkType)
This method was deprecated
in API level 23.
This method does not support multiple connected networks
of the same type. Use |
NetworkInfo
|
getNetworkInfo(Network network)
This method was deprecated
in API level 29.
See |
int
|
getNetworkPreference()
This method was deprecated in API level 21. Functionality has been removed as it no longer makes sense, with many more than two networks - we'd need an array to express preference. Instead we use dynamic network properties of the networks to describe their precedence. |
byte[]
|
getNetworkWatchlistConfigHash()
The network watchlist is a list of domains and IP addresses that are associated with potentially harmful apps. |
static
Network
|
getProcessDefaultNetwork()
This method was deprecated
in API level 23.
Using this function can lead to other functions throwing
|
int
|
getRestrictBackgroundStatus()
Determines if the calling application is subject to metered network restrictions while running on background. |
boolean
|
isActiveNetworkMetered()
Returns if the currently active data network is metered. |
boolean
|
isDefaultNetworkActive()
Return whether the data network is currently active. |
static
boolean
|
isNetworkTypeValid(int networkType)
This method was deprecated in API level 23. All APIs accepting a network type are deprecated. There should be no need to validate a network type. |
void
|
registerBestMatchingNetworkCallback(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, Handler handler)
Registers to receive notifications about the best matching network which satisfy the given
|
void
|
registerDefaultNetworkCallback(ConnectivityManager.NetworkCallback networkCallback)
Registers to receive notifications about changes in the application's default network. |
void
|
registerDefaultNetworkCallback(ConnectivityManager.NetworkCallback networkCallback, Handler handler)
Registers to receive notifications about changes in the application's default network. |
void
|
registerNetworkCallback(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)
Registers to receive notifications about all networks which satisfy the given
|
void
|
registerNetworkCallback(NetworkRequest request, PendingIntent operation)
Registers a PendingIntent to be sent when a network is available which satisfies the given
|
void
|
registerNetworkCallback(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, Handler handler)
Registers to receive notifications about all networks which satisfy the given
|
void
|
releaseNetworkRequest(PendingIntent operation)
Removes a request made via
This method has the same behavior as
|
void
|
removeDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener l)
Remove network active listener previously registered with
|
void
|
reportBadNetwork(Network network)
This method was deprecated
in API level 23.
Use |
void
|
reportNetworkConnectivity(Network network, boolean hasConnectivity)
Report to the framework whether a network has working connectivity. |
boolean
|
requestBandwidthUpdate(Network network)
Requests bandwidth update for a given |
void
|
requestNetwork(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)
Request a network to satisfy a set of |
void
|
requestNetwork(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, int timeoutMs)
Request a network to satisfy a set of |
void
|
requestNetwork(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, Handler handler)
Request a network to satisfy a set of |
void
|
requestNetwork(NetworkRequest request, PendingIntent operation)
Request a network to satisfy a set of |
void
|
requestNetwork(NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, Handler handler, int timeoutMs)
Request a network to satisfy a set of |
void
|
setNetworkPreference(int preference)
This method was deprecated in API level 21. Functionality has been removed as it no longer makes sense, with many more than two networks - we'd need an array to express preference. Instead we use dynamic network properties of the networks to describe their precedence. |
static
boolean
|
setProcessDefaultNetwork(Network network)
This method was deprecated
in API level 23.
This function can throw |
void
|
unregisterNetworkCallback(ConnectivityManager.NetworkCallback networkCallback)
Unregisters a |
void
|
unregisterNetworkCallback(PendingIntent operation)
Unregisters a callback previously registered via
|
Inherited methods | |
---|---|
Constants
ACTION_BACKGROUND_DATA_SETTING_CHANGED
public static final String ACTION_BACKGROUND_DATA_SETTING_CHANGED
This constant was deprecated
in API level 16.
As of VERSION_CODES#ICE_CREAM_SANDWICH
, availability
of background data depends on several combined factors, and
this broadcast is no longer sent. Instead, when background
data is unavailable, getActiveNetworkInfo()
will now
appear disconnected. During first boot after a platform
upgrade, this broadcast will be sent once if
getBackgroundDataSetting()
was false
before
the upgrade.
Broadcast Action: The setting for background data usage has changed
values. Use getBackgroundDataSetting()
to get the current value.
If an application uses the network in the background, it should listen
for this broadcast and stop using the background data if the value is
false
.
Constant Value: "android.net.conn.BACKGROUND_DATA_SETTING_CHANGED"
ACTION_CAPTIVE_PORTAL_SIGN_IN
public static final String ACTION_CAPTIVE_PORTAL_SIGN_IN
The device has connected to a network that has presented a captive
portal, which is blocking Internet connectivity. The user was presented
with a notification that network sign in is required,
and the user invoked the notification's action indicating they
desire to sign in to the network. Apps handling this activity should
facilitate signing in to the network. This action includes a
Network
typed extra called EXTRA_NETWORK
that represents
the network presenting the captive portal; all communication with the
captive portal must be done using this Network
object.
CaptivePortal
extra named
EXTRA_CAPTIVE_PORTAL
that can be used to indicate different
outcomes of the captive portal sign in to the system:
- When the app handling this action believes the user has signed in to
the network and the captive portal has been dismissed, the app should
call
CaptivePortal#reportCaptivePortalDismissed
so the system can reevaluate the network. If reevaluation finds the network no longer subject to a captive portal, the network may become the default active data network. - When the app handling this action believes the user explicitly wants
to ignore the captive portal and the network, the app should call
CaptivePortal#ignoreNetwork
.
Constant Value: "android.net.conn.CAPTIVE_PORTAL"
ACTION_RESTRICT_BACKGROUND_CHANGED
public static final String ACTION_RESTRICT_BACKGROUND_CHANGED
A change in the background metered network activity restriction has occurred.
Applications should call getRestrictBackgroundStatus()
to check if the restriction
applies to them.
This is only sent to registered receivers, not manifest receivers.
Constant Value: "android.net.conn.RESTRICT_BACKGROUND_CHANGED"
CONNECTIVITY_ACTION
public static final String CONNECTIVITY_ACTION
This constant was deprecated
in API level 28.
apps should use the more versatile requestNetwork(NetworkRequest, PendingIntent)
,
registerNetworkCallback(NetworkRequest, PendingIntent)
or registerDefaultNetworkCallback(NetworkCallback)
functions instead for faster and more detailed updates about the network
changes they care about.
A change in network connectivity has occurred. A default connection has either been established or lost. The NetworkInfo for the affected network is sent as an extra; it should be consulted to see what kind of connectivity event occurred.
Apps targeting Android 7.0 (API level 24) and higher do not receive this broadcast if they declare the broadcast receiver in their manifest. Apps will still receive broadcasts if they register theirBroadcastReceiver
with
Context.registerReceiver()
and that context is still valid.
If this is a connection that was the result of failing over from a
disconnected network, then the FAILOVER_CONNECTION boolean extra is
set to true.
For a loss of connectivity, if the connectivity manager is attempting
to connect (or has already connected) to another network, the
NetworkInfo for the new network is also passed as an extra. This lets
any receivers of the broadcast know that they should not necessarily
tell the user that no data traffic will be possible. Instead, the
receiver should expect another broadcast soon, indicating either that
the failover attempt succeeded (and so there is still overall data
connectivity), or that the failover attempt failed, meaning that all
connectivity has been lost.
For a disconnect event, the boolean extra EXTRA_NO_CONNECTIVITY
is set to true
if there are no connected networks at all.
Note that this broadcast is deprecated and generally tries to implement backwards
compatibility with older versions of Android. As such, it may not reflect new
capabilities of the system, like multiple networks being connected at the same
time, the details of newer technology, or changes in tethering state.
Constant Value: "android.net.conn.CONNECTIVITY_CHANGE"
DEFAULT_NETWORK_PREFERENCE
public static final int DEFAULT_NETWORK_PREFERENCE
This constant was deprecated
in API level 18.
Since we support so many more networks now, the single
network default network preference can't really express
the hierarchy. Instead, the default is defined by the
networkAttributes in config.xml. You can determine
the current value by calling getNetworkPreference()
from an App.
If you want to set the default network preference,you can directly change the networkAttributes array in framework's config.xml.
Constant Value: 1 (0x00000001)
EXTRA_CAPTIVE_PORTAL
public static final String EXTRA_CAPTIVE_PORTAL
The lookup key for a CaptivePortal
object included with the
ACTION_CAPTIVE_PORTAL_SIGN_IN
intent. The CaptivePortal
object can be used to either indicate to the system that the captive
portal has been dismissed or that the user does not want to pursue
signing in to captive portal. Retrieve it with
Intent.getParcelableExtra(String)
.
Constant Value: "android.net.extra.CAPTIVE_PORTAL"
EXTRA_CAPTIVE_PORTAL_URL
public static final String EXTRA_CAPTIVE_PORTAL_URL
Key for passing a URL to the captive portal login activity.
Constant Value: "android.net.extra.CAPTIVE_PORTAL_URL"
EXTRA_EXTRA_INFO
public static final String EXTRA_EXTRA_INFO
This constant was deprecated
in API level 29.
See NetworkInfo#getExtraInfo()
.
The lookup key for a string that provides optionally supplied
extra information about the network state. The information
may be passed up from the lower networking layers, and its
meaning may be specific to a particular network type. Retrieve
it with Intent.getStringExtra(String)
.
Constant Value: "extraInfo"
EXTRA_IS_FAILOVER
public static final String EXTRA_IS_FAILOVER
This constant was deprecated
in API level 29.
See NetworkInfo
.
The lookup key for a boolean that indicates whether a connect event
is for a network to which the connectivity manager was failing over
following a disconnect on another network.
Retrieve it with Intent.getBooleanExtra(String, boolean)
.
Constant Value: "isFailover"
EXTRA_NETWORK
public static final String EXTRA_NETWORK
The lookup key for a Network
object included with the intent after
successfully finding a network for the applications request. Retrieve it with
Intent.getParcelableExtra(String)
.
Note that if you intend to invoke Network#openConnection(java.net.URL)
then you must get a ConnectivityManager instance before doing so.
Constant Value: "android.net.extra.NETWORK"
EXTRA_NETWORK_INFO
public static final String EXTRA_NETWORK_INFO
This constant was deprecated
in API level 15.
The NetworkInfo
object is deprecated, as many of its properties
can't accurately represent modern network characteristics.
Please obtain information about networks from the NetworkCapabilities
or LinkProperties
objects instead.
The lookup key for a NetworkInfo
object. Retrieve with
Intent.getParcelableExtra(String)
.
Constant Value: "networkInfo"
EXTRA_NETWORK_REQUEST
public static final String EXTRA_NETWORK_REQUEST
The lookup key for a NetworkRequest
object included with the intent after
successfully finding a network for the applications request. Retrieve it with
Intent.getParcelableExtra(String)
.
Constant Value: "android.net.extra.NETWORK_REQUEST"
EXTRA_NETWORK_TYPE
public static final String EXTRA_NETWORK_TYPE
This constant was deprecated
in API level 29.
The network type is not rich enough to represent the characteristics
of modern networks. Please use NetworkCapabilities
instead,
in particular the transports.
Network type which triggered a CONNECTIVITY_ACTION
broadcast.
See also:
Constant Value: "networkType"
EXTRA_NO_CONNECTIVITY
public static final String EXTRA_NO_CONNECTIVITY
The lookup key for a boolean that indicates whether there is a
complete lack of connectivity, i.e., no network is available.
Retrieve it with Intent.getBooleanExtra(String, boolean)
.
Constant Value: "noConnectivity"
EXTRA_OTHER_NETWORK_INFO
public static final String EXTRA_OTHER_NETWORK_INFO
This constant was deprecated
in API level 29.
See NetworkInfo
.
The lookup key for a NetworkInfo
object. This is supplied when
there is another network that it may be possible to connect to. Retrieve with
Intent.getParcelableExtra(String)
.
Constant Value: "otherNetwork"
EXTRA_REASON
public static final String EXTRA_REASON
The lookup key for a string that indicates why an attempt to connect
to a network failed. The string has no particular structure. It is
intended to be used in notifications presented to users. Retrieve
it with Intent.getStringExtra(String)
.
Constant Value: "reason"
MULTIPATH_PREFERENCE_HANDOVER
public static final int MULTIPATH_PREFERENCE_HANDOVER
It is acceptable to briefly use multipath data to provide seamless connectivity for time-sensitive user-facing operations when the system default network is temporarily unresponsive. The amount of data should be limited (less than one megabyte for every call to this method), and the operation should be infrequent to ensure that data usage is limited. An example of such an operation might be a time-sensitive foreground activity, such as a voice command, that the user is performing while walking out of range of a Wi-Fi network.
Constant Value: 1 (0x00000001)
MULTIPATH_PREFERENCE_PERFORMANCE
public static final int MULTIPATH_PREFERENCE_PERFORMANCE
It is acceptable to use metered data to improve network latency and performance.
Constant Value: 4 (0x00000004)
MULTIPATH_PREFERENCE_RELIABILITY
public static final int MULTIPATH_PREFERENCE_RELIABILITY
It is acceptable to use small amounts of multipath data on an ongoing basis to provide a backup channel for traffic that is primarily going over another network. An example might be maintaining backup connections to peers or servers for the purpose of fast fallback if the default network is temporarily unresponsive or disconnects. The traffic on backup paths should be negligible compared to the traffic on the main path.
Constant Value: 2 (0x00000002)
RESTRICT_BACKGROUND_STATUS_DISABLED
public static final int RESTRICT_BACKGROUND_STATUS_DISABLED
Device is not restricting metered network activity while application is running on background.
Constant Value: 1 (0x00000001)
RESTRICT_BACKGROUND_STATUS_ENABLED
public static final int RESTRICT_BACKGROUND_STATUS_ENABLED
Device is restricting metered network activity while application is running on background.
In this state, application should not try to use the network while running on background, because it would be denied.
Constant Value: 3 (0x00000003)
RESTRICT_BACKGROUND_STATUS_WHITELISTED
public static final int RESTRICT_BACKGROUND_STATUS_WHITELISTED
Device is restricting metered network activity while application is running on background, but application is allowed to bypass it.
In this state, application should take action to mitigate metered network access. For example, a music streaming application should switch to a low-bandwidth bitrate.
Constant Value: 2 (0x00000002)
TYPE_BLUETOOTH
public static final int TYPE_BLUETOOTH
This constant was deprecated
in API level 28.
Applications should instead use NetworkCapabilities#hasTransport
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request an
appropriate network. See NetworkCapabilities
for supported transports.
A Bluetooth data connection.
Constant Value: 7 (0x00000007)
TYPE_DUMMY
public static final int TYPE_DUMMY
This constant was deprecated
in API level 28.
This is not used any more.
Fake data connection. This should not be used on shipping devices.
Constant Value: 8 (0x00000008)
TYPE_ETHERNET
public static final int TYPE_ETHERNET
This constant was deprecated
in API level 28.
Applications should instead use NetworkCapabilities#hasTransport
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request an
appropriate network. See NetworkCapabilities
for supported transports.
An Ethernet data connection.
Constant Value: 9 (0x00000009)
TYPE_MOBILE
public static final int TYPE_MOBILE
This constant was deprecated
in API level 28.
Applications should instead use NetworkCapabilities#hasTransport
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request an
appropriate network. See NetworkCapabilities
for supported transports.
A Mobile data connection. Devices may support more than one.
Constant Value: 0 (0x00000000)
TYPE_MOBILE_DUN
public static final int TYPE_MOBILE_DUN
This constant was deprecated
in API level 28.
Applications should instead use NetworkCapabilities#hasCapability
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request a network that
provides the NetworkCapabilities#NET_CAPABILITY_DUN
capability.
A DUN-specific Mobile data connection. This network type may use the
same network interface as TYPE_MOBILE
or it may use a different
one. This is sometimes by the system when setting up an upstream connection
for tethering so that the carrier is aware of DUN traffic.
Constant Value: 4 (0x00000004)
TYPE_MOBILE_HIPRI
public static final int TYPE_MOBILE_HIPRI
This constant was deprecated
in API level 23.
Applications should instead use NetworkCapabilities#hasTransport
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request an
appropriate network. See NetworkCapabilities
for supported transports.
A High Priority Mobile data connection. This network type uses the
same network interface as TYPE_MOBILE
but the routing setup
is different.
Constant Value: 5 (0x00000005)
TYPE_MOBILE_MMS
public static final int TYPE_MOBILE_MMS
This constant was deprecated
in API level 23.
Applications should instead use NetworkCapabilities#hasCapability
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request a network that
provides the NetworkCapabilities#NET_CAPABILITY_MMS
capability.
An MMS-specific Mobile data connection. This network type may use the
same network interface as TYPE_MOBILE
or it may use a different
one. This is used by applications needing to talk to the carrier's
Multimedia Messaging Service servers.
Constant Value: 2 (0x00000002)
TYPE_MOBILE_SUPL
public static final int TYPE_MOBILE_SUPL
This constant was deprecated
in API level 23.
Applications should instead use NetworkCapabilities#hasCapability
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request a network that
provides the NetworkCapabilities#NET_CAPABILITY_SUPL
capability.
A SUPL-specific Mobile data connection. This network type may use the
same network interface as TYPE_MOBILE
or it may use a different
one. This is used by applications needing to talk to the carrier's
Secure User Plane Location servers for help locating the device.
Constant Value: 3 (0x00000003)
TYPE_VPN
public static final int TYPE_VPN
This constant was deprecated
in API level 28.
Applications should use NetworkCapabilities#TRANSPORT_VPN
instead.
A virtual network using one or more native bearers. It may or may not be providing security services.
Constant Value: 17 (0x00000011)
TYPE_WIFI
public static final int TYPE_WIFI
This constant was deprecated
in API level 28.
Applications should instead use NetworkCapabilities#hasTransport
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request an
appropriate network. See NetworkCapabilities
for supported transports.
A WIFI data connection. Devices may support more than one.
Constant Value: 1 (0x00000001)
TYPE_WIMAX
public static final int TYPE_WIMAX
This constant was deprecated
in API level 28.
Applications should instead use NetworkCapabilities#hasTransport
or
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to request an
appropriate network. See NetworkCapabilities
for supported transports.
A WiMAX data connection.
Constant Value: 6 (0x00000006)
Public methods
addDefaultNetworkActiveListener
public void addDefaultNetworkActiveListener (ConnectivityManager.OnNetworkActiveListener l)
Start listening to reports when the system's default data network is active, meaning it is
a good time to perform network traffic. Use isDefaultNetworkActive()
to determine the current state of the system's default network after registering the
listener.
If the process default network has been set with
ConnectivityManager#bindProcessToNetwork
this function will not
reflect the process's default, but the system default.
Parameters | |
---|---|
l |
ConnectivityManager.OnNetworkActiveListener : The listener to be told when the network is active. |
bindProcessToNetwork
public boolean bindProcessToNetwork (Network network)
Binds the current process to network
. All Sockets created in the future
(and not explicitly bound via a bound SocketFactory from
Network.getSocketFactory()
) will be bound to
network
. All host name resolutions will be limited to network
as well.
Note that if network
ever disconnects, all Sockets created in this way will cease to
work and all host name resolutions will fail. This is by design so an application doesn't
accidentally use Sockets it thinks are still bound to a particular Network
.
To clear binding pass null
for network
. Using individually bound
Sockets created by Network.getSocketFactory().createSocket() and
performing network-specific host name resolutions via
Network.getAllByName
is preferred to calling
bindProcessToNetwork
.
Parameters | |
---|---|
network |
Network : The Network to bind the current process to, or null to clear
the current binding. |
Returns | |
---|---|
boolean |
true on success, false if the Network is no longer valid. |
createSocketKeepalive
public SocketKeepalive createSocketKeepalive (Network network, IpSecManager.UdpEncapsulationSocket socket, InetAddress source, InetAddress destination, Executor executor, SocketKeepalive.Callback callback)
Request that keepalives be started on a IPsec NAT-T socket.
Parameters | |
---|---|
network |
Network : The Network the socket is on.
This value cannot be null . |
socket |
IpSecManager.UdpEncapsulationSocket : The socket that needs to be kept alive.
This value cannot be null . |
source |
InetAddress : The source address of the UdpEncapsulationSocket .
This value cannot be null . |
destination |
InetAddress : The destination address of the UdpEncapsulationSocket .
This value cannot be null . |
executor |
Executor : The executor on which callback will be invoked. The provided Executor
must run callback sequentially, otherwise the order of callbacks cannot be
guaranteed.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
SocketKeepalive.Callback : A SocketKeepalive.Callback . Used for notifications about keepalive
changes. Must be extended by applications that use this API.
This value cannot be null . |
Returns | |
---|---|
SocketKeepalive |
A SocketKeepalive object that can be used to control the keepalive on the
given socket.
This value cannot be null . |
getActiveNetwork
public Network getActiveNetwork ()
Returns a Network
object corresponding to the currently active
default data network. In the event that the current active default data
network disconnects, the returned Network
object will no longer
be usable. This will return null
when there is no default
network, or when the default network is blocked.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Returns | |
---|---|
Network |
a Network object for the current default network or
null if no default network is currently active or if
the default network is blocked for the caller |
getActiveNetworkInfo
public NetworkInfo getActiveNetworkInfo ()
This method was deprecated
in API level 29.
See NetworkInfo
.
Returns details about the currently active default data network. When
connected, this network is the default route for outgoing connections.
You should always check NetworkInfo#isConnected()
before initiating
network traffic. This may return null
when there is no default
network.
Note that if the default network is a VPN, this method will return the
NetworkInfo for one of its underlying networks instead, or null if the
VPN agent did not specify any. Apps interested in learning about VPNs
should use getNetworkInfo(android.net.Network)
instead.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Returns | |
---|---|
NetworkInfo |
a NetworkInfo object for the current default network
or null if no default network is currently active |
getAllNetworkInfo
public NetworkInfo[] getAllNetworkInfo ()
This method was deprecated
in API level 23.
This method does not support multiple connected networks
of the same type. Use getAllNetworks()
and
getNetworkInfo(android.net.Network)
instead.
Returns connection status information about all network types supported by the device.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Returns | |
---|---|
NetworkInfo[] |
an array of NetworkInfo objects. Check each
NetworkInfo#getType for which type each applies.
This value cannot be null . |
getAllNetworks
public Network[] getAllNetworks ()
This method was deprecated
in API level 31.
This method does not provide any notification of network state changes, forcing
apps to call it repeatedly. This is inefficient and prone to race conditions.
Apps should use methods such as
registerNetworkCallback(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
instead.
Apps that desire to obtain information about networks that do not apply to them
can use NetworkRequest.Builder#setIncludeOtherUidNetworks
.
Returns an array of all Network
currently tracked by the framework.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Returns | |
---|---|
Network[] |
an array of Network objects.
This value cannot be null . |
getBackgroundDataSetting
public boolean getBackgroundDataSetting ()
This method was deprecated
in API level 15.
As of VERSION_CODES#ICE_CREAM_SANDWICH
, availability of
background data depends on several combined factors, and this method will
always return true
. Instead, when background data is unavailable,
getActiveNetworkInfo()
will now appear disconnected.
Returns the value of the setting for background data usage. If false, applications should not use the network if the application is not in the foreground. Developers should respect this setting, and check the value of this before performing any background data operations.
All applications that have background services that use the network
should listen to ACTION_BACKGROUND_DATA_SETTING_CHANGED
.
Returns | |
---|---|
boolean |
Whether background data usage is allowed. |
getBoundNetworkForProcess
public Network getBoundNetworkForProcess ()
Returns the Network
currently bound to this process via
bindProcessToNetwork(Network)
, or null
if no Network
is explicitly bound.
Returns | |
---|---|
Network |
Network to which this process is bound, or null . |
getConnectionOwnerUid
public int getConnectionOwnerUid (int protocol, InetSocketAddress local, InetSocketAddress remote)
Returns the uid
of the owner of a network connection.
Parameters | |
---|---|
protocol |
int : The protocol of the connection. Only IPPROTO_TCP and IPPROTO_UDP currently supported. |
local |
InetSocketAddress : The local InetSocketAddress of a connection.
This value cannot be null . |
remote |
InetSocketAddress : The remote InetSocketAddress of a connection.
This value cannot be null . |
Returns | |
---|---|
int |
uid if the connection is found and the app has permission to observe it
(e.g., if it is associated with the calling VPN app's VpnService tunnel) or Process.INVALID_UID if the connection is not found. |
Throws | |
---|---|
SecurityException |
if the caller is not the active VpnService for the current user. |
IllegalArgumentException |
if an unsupported protocol is requested. |
getDefaultProxy
public ProxyInfo getDefaultProxy ()
Get the current default HTTP proxy settings. If a global proxy is set it will be returned,
otherwise if this process is bound to a Network
using
bindProcessToNetwork(Network)
then that Network
's proxy is returned, otherwise
the default network's proxy is returned.
Returns | |
---|---|
ProxyInfo |
the ProxyInfo for the current HTTP proxy, or null if no
HTTP proxy is active. |
getLinkProperties
public LinkProperties getLinkProperties (Network network)
Get the LinkProperties
for the given Network
. This
will return null
if the network is unknown.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
network |
Network : The Network object identifying the network in question.
This value may be null . |
Returns | |
---|---|
LinkProperties |
The LinkProperties for the network, or null . |
getMultipathPreference
public int getMultipathPreference (Network network)
Provides a hint to the calling application on whether it is desirable to use the
multinetwork APIs (e.g., Network#openConnection
, Network#bindSocket
, etc.)
for multipath data transfer on this network when it is not the system default network.
Applications desiring to use multipath network protocols should call this method before
each such operation.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
network |
Network : The network on which the application desires to use multipath data.
If null , this method will return a preference that will generally
apply to metered networks. |
Returns | |
---|---|
int |
a bitwise OR of zero or more of the MULTIPATH_PREFERENCE_* constants.
Value is either 0 or a combination of MULTIPATH_PREFERENCE_HANDOVER , MULTIPATH_PREFERENCE_RELIABILITY , and MULTIPATH_PREFERENCE_PERFORMANCE |
getNetworkCapabilities
public NetworkCapabilities getNetworkCapabilities (Network network)
Get the NetworkCapabilities
for the given Network
, or null.
This will remove any location sensitive data in the returned NetworkCapabilities
.
Some TransportInfo
instances like WifiInfo
contain location
sensitive information. To retrieve this location sensitive information (subject to
the caller's location permissions), use a NetworkCallback
with the
NetworkCallback#FLAG_INCLUDE_LOCATION_INFO
flag instead.
This method returns null
if the network is unknown or if the |network| argument
is null.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
network |
Network : The Network object identifying the network in question.
This value may be null . |
Returns | |
---|---|
NetworkCapabilities |
The NetworkCapabilities for the network, or null . |
getNetworkInfo
public NetworkInfo getNetworkInfo (int networkType)
This method was deprecated
in API level 23.
This method does not support multiple connected networks
of the same type. Use getAllNetworks()
and
getNetworkInfo(android.net.Network)
instead.
Returns connection status information about a particular network type.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
networkType |
int : integer specifying which networkType in
which you're interested. |
Returns | |
---|---|
NetworkInfo |
a NetworkInfo object for the requested
network type or null if the type is not
supported by the device. If networkType is
TYPE_VPN and a VPN is active for the calling app,
then this method will try to return one of the
underlying networks for the VPN or null if the
VPN agent didn't specify any. |
getNetworkInfo
public NetworkInfo getNetworkInfo (Network network)
This method was deprecated
in API level 29.
See NetworkInfo
.
Returns connection status information about a particular Network.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
network |
Network : Network specifying which network
in which you're interested.
This value may be null . |
Returns | |
---|---|
NetworkInfo |
a NetworkInfo object for the requested
network or null if the Network
is not valid. |
getNetworkPreference
public int getNetworkPreference ()
This method was deprecated
in API level 21.
Functionality has been removed as it no longer makes sense,
with many more than two networks - we'd need an array to express
preference. Instead we use dynamic network properties of
the networks to describe their precedence.
Retrieves the current preferred network type.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Returns | |
---|---|
int |
an integer representing the preferred network type |
getNetworkWatchlistConfigHash
public byte[] getNetworkWatchlistConfigHash ()
The network watchlist is a list of domains and IP addresses that are associated with potentially harmful apps. This method returns the SHA-256 of the watchlist config file currently used by the system for validation purposes.
Returns | |
---|---|
byte[] |
Hash of network watchlist config file. Null if config does not exist.
This value may be null . |
getProcessDefaultNetwork
public static Network getProcessDefaultNetwork ()
This method was deprecated
in API level 23.
Using this function can lead to other functions throwing
IllegalStateException
. Use getBoundNetworkForProcess()
instead.
getBoundNetworkForProcess
is a direct replacement.
Returns the Network
currently bound to this process via
bindProcessToNetwork(Network)
, or null
if no Network
is explicitly bound.
Returns | |
---|---|
Network |
Network to which this process is bound, or null . |
getRestrictBackgroundStatus
public int getRestrictBackgroundStatus ()
Determines if the calling application is subject to metered network restrictions while running on background.
isActiveNetworkMetered
public boolean isActiveNetworkMetered ()
Returns if the currently active data network is metered. A network is
classified as metered when the user is sensitive to heavy data usage on
that connection due to monetary costs, data limitations or
battery/performance issues. You should check this before doing large
data transfers, and warn the user or delay the operation until another
network is available.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Returns | |
---|---|
boolean |
true if large transfers should be avoided, otherwise
false . |
isDefaultNetworkActive
public boolean isDefaultNetworkActive ()
Return whether the data network is currently active. An active network means that it is currently in a high power state for performing data transmission. On some types of networks, it may be expensive to move and stay in such a state, so it is more power efficient to batch network traffic together when the radio is already in this state. This method tells you whether right now is currently a good time to initiate network traffic, as the network is already active.
Returns | |
---|---|
boolean |
isNetworkTypeValid
public static boolean isNetworkTypeValid (int networkType)
This method was deprecated
in API level 23.
All APIs accepting a network type are deprecated. There should be no need to
validate a network type.
Tests if a given integer represents a valid network type.
Parameters | |
---|---|
networkType |
int : the type to be tested |
Returns | |
---|---|
boolean |
true if the type is valid, else false |
registerBestMatchingNetworkCallback
public void registerBestMatchingNetworkCallback (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, Handler handler)
Registers to receive notifications about the best matching network which satisfy the given
NetworkRequest
. The callbacks will continue to be called until
either the application exits or unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
is
called.
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
registerNetworkCallback(NetworkRequest, PendingIntent)
and its variants and requestNetwork(NetworkRequest, PendingIntent)
as well as
ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback
.
Requesting a network 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
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
.
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback that the system will call as suitable
networks change state.
This value cannot be null . |
handler |
Handler : Handler to specify the thread upon which the callback will be invoked.
This value cannot be null . |
Throws | |
---|---|
RuntimeException |
if the app already has too many callbacks registered. |
registerDefaultNetworkCallback
public void registerDefaultNetworkCallback (ConnectivityManager.NetworkCallback networkCallback)
Registers to receive notifications about changes in the application's default network. This
may be a physical network or a virtual network, such as a VPN that applies to the
application. The callbacks will continue to be called until either the application exits or
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
is called.
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
all variants of this method, of requestNetwork(NetworkRequest, PendingIntent)
as well as
ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback
.
Requesting a network 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
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback that the system will call as the
application's default network changes.
The callback is invoked on the default internal Handler.
This value cannot be null . |
Throws | |
---|---|
RuntimeException |
if the app already has too many callbacks registered. |
registerDefaultNetworkCallback
public void registerDefaultNetworkCallback (ConnectivityManager.NetworkCallback networkCallback, Handler handler)
Registers to receive notifications about changes in the application's default network. This
may be a physical network or a virtual network, such as a VPN that applies to the
application. The callbacks will continue to be called until either the application exits or
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
is called.
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
all variants of this method, of requestNetwork(NetworkRequest, PendingIntent)
as well as
ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback
.
Requesting a network 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
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback that the system will call as the
application's default network changes.
This value cannot be null . |
handler |
Handler : Handler to specify the thread upon which the callback will be invoked.
This value cannot be null . |
Throws | |
---|---|
RuntimeException |
if the app already has too many callbacks registered. |
registerNetworkCallback
public void registerNetworkCallback (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)
Registers to receive notifications about all networks which satisfy the given
NetworkRequest
. The callbacks will continue to be called until
either the application exits or unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
is
called.
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
all variants of this method, of requestNetwork(NetworkRequest, PendingIntent)
as well as
ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback
.
Requesting a network 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
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback that the system will call as suitable
networks change state.
The callback is invoked on the default internal Handler.
This value cannot be null . |
Throws | |
---|---|
RuntimeException |
if the app already has too many callbacks registered. |
registerNetworkCallback
public void registerNetworkCallback (NetworkRequest request, PendingIntent operation)
Registers a PendingIntent to be sent when a network is available which satisfies the given
NetworkRequest
.
This function behaves identically to the version that takes a NetworkCallback, but instead
of NetworkCallback
a PendingIntent
is used. This means
the request may outlive the calling application and get called back when a suitable
network is found.
The operation is an Intent broadcast that goes to a broadcast receiver that
you registered with Context#registerReceiver
or through the
<receiver> tag in an AndroidManifest.xml file
The operation Intent is delivered with two extras, a Network
typed
extra called EXTRA_NETWORK
and a NetworkRequest
typed extra called EXTRA_NETWORK_REQUEST
containing
the original requests parameters.
If there is already a request for this Intent registered (with the equality of
two Intents defined by Intent#filterEquals
), then it will be removed and
replaced by this one, effectively releasing the previous NetworkRequest
.
The request may be released normally by calling
unregisterNetworkCallback(android.app.PendingIntent)
.
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
all variants of this method, of requestNetwork(NetworkRequest, PendingIntent)
as well as
ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback
.
Requesting a network 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 unregisterNetworkCallback(android.app.PendingIntent)
or releaseNetworkRequest(android.app.PendingIntent)
.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
operation |
PendingIntent : Action to perform when the network is available (corresponds
to the NetworkCallback#onAvailable call. Typically
comes from PendingIntent#getBroadcast . Cannot be null. |
Throws | |
---|---|
RuntimeException |
if the app already has too many callbacks registered. |
registerNetworkCallback
public void registerNetworkCallback (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, Handler handler)
Registers to receive notifications about all networks which satisfy the given
NetworkRequest
. The callbacks will continue to be called until
either the application exits or unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
is
called.
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
all variants of this method, of requestNetwork(NetworkRequest, PendingIntent)
as well as
ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback
.
Requesting a network 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
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
.
Requires Manifest.permission.ACCESS_NETWORK_STATE
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback that the system will call as suitable
networks change state.
This value cannot be null . |
handler |
Handler : Handler to specify the thread upon which the callback will be invoked.
This value cannot be null . |
Throws | |
---|---|
RuntimeException |
if the app already has too many callbacks registered. |
releaseNetworkRequest
public void releaseNetworkRequest (PendingIntent operation)
Removes a request made via requestNetwork(android.net.NetworkRequest, android.app.PendingIntent)
This method has the same behavior as
unregisterNetworkCallback(android.app.PendingIntent)
with respect to
releasing network resources and disconnecting.
Parameters | |
---|---|
operation |
PendingIntent : A PendingIntent equal (as defined by Intent#filterEquals ) to the
PendingIntent passed to
requestNetwork(android.net.NetworkRequest, android.app.PendingIntent) with the
corresponding NetworkRequest you'd like to remove. Cannot be null. |
removeDefaultNetworkActiveListener
public void removeDefaultNetworkActiveListener (ConnectivityManager.OnNetworkActiveListener l)
Remove network active listener previously registered with
addDefaultNetworkActiveListener(OnNetworkActiveListener)
.
Parameters | |
---|---|
l |
ConnectivityManager.OnNetworkActiveListener : Previously registered listener.
This value cannot be null . |
reportBadNetwork
public void reportBadNetwork (Network network)
This method was deprecated
in API level 23.
Use reportNetworkConnectivity(Network, boolean)
which allows reporting both
working and non-working connectivity.
Report a problem network to the framework. This provides a hint to the system that there might be connectivity problems on this network and may cause the framework to re-evaluate network connectivity and/or switch to another network.
Parameters | |
---|---|
network |
Network : The Network the application was attempting to use
or null to indicate the current default network. |
reportNetworkConnectivity
public void reportNetworkConnectivity (Network network, boolean hasConnectivity)
Report to the framework whether a network has working connectivity. This provides a hint to the system that a particular network is providing working connectivity or not. In response the framework may re-evaluate the network's connectivity and might take further action thereafter.
Parameters | |
---|---|
network |
Network : The Network the application was attempting to use
or null to indicate the current default network. |
hasConnectivity |
boolean : true if the application was able to successfully access the
Internet using network or false if not. |
requestBandwidthUpdate
public boolean requestBandwidthUpdate (Network network)
Requests bandwidth update for a given Network
and returns whether the update request
is accepted by ConnectivityService. Once accepted, ConnectivityService will poll underlying
network connection for updated bandwidth information. The caller will be notified via
ConnectivityManager.NetworkCallback
if there is an update. Notice that this
method assumes that the caller has previously called
registerNetworkCallback(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
to listen for network
changes.
Parameters | |
---|---|
network |
Network : Network specifying which network you're interested.
This value cannot be null . |
Returns | |
---|---|
boolean |
true on success, false if the Network is no longer valid. |
requestNetwork
public void requestNetwork (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)
Request a network to satisfy a set of NetworkCapabilities
.
This method will attempt to find the best network that matches the passed
NetworkRequest
, and to bring up one that does if none currently satisfies the
criteria. The platform will evaluate which network is the best at its own discretion.
Throughput, latency, cost per byte, policy, user preference and other considerations
may be factored in the decision of what is considered the best network.
As long as this request is outstanding, the platform will try to maintain the best network
matching this request, while always attempting to match the request to a better network if
possible. If a better match is found, the platform will switch this request to the now-best
network and inform the app of the newly best network by invoking
NetworkCallback#onAvailable(Network)
on the provided callback. Note that the platform
will not try to maintain any other network than the best one currently matching the request:
a network not matching any network request may be disconnected at any time.
For example, an application could use this method to obtain a connected cellular network
even if the device currently has a data connection over Ethernet. This may cause the cellular
radio to consume additional power. Or, an application could inform the system that it wants
a network supporting sending MMSes and have the system let it know about the currently best
MMS-supporting network through the provided NetworkCallback
.
The status of the request can be followed by listening to the various callbacks described
in NetworkCallback
. The Network
object passed to the callback methods can be
used to direct traffic to the network (although accessing some networks may be subject to
holding specific permissions). Callers will learn about the specific characteristics of the
network through
NetworkCallback#onCapabilitiesChanged(Network, NetworkCapabilities)
and
NetworkCallback#onLinkPropertiesChanged(Network, LinkProperties)
. The methods of the
provided NetworkCallback
will only be invoked due to changes in the best network
matching the request at any given time; therefore when a better network matching the request
becomes available, the NetworkCallback#onAvailable(Network)
method is called
with the new network after which no further updates are given about the previously-best
network, unless it becomes the best again at some later time. All callbacks are invoked
in order on the same thread, which by default is a thread created by the framework running
in the app.
See requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, android.os.Handler)
to change where the
callbacks are invoked.
ThisNetworkRequest
will live until released via
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
or the calling application exits, at
which point the system may let go of the network at any time.
A version of this method which takes a timeout is
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, int)
, that an app can use to only
wait for a limited amount of time for the network to become unavailable.
It is presently unsupported to request a network with mutable
NetworkCapabilities
such as
NetworkCapabilities#NET_CAPABILITY_VALIDATED
or
NetworkCapabilities#NET_CAPABILITY_CAPTIVE_PORTAL
as these NetworkCapabilities
represent states that a particular
network may never attain, and whether a network will attain these states
is unknown prior to bringing up the network so the framework does not
know how to go about satisfying a request with these capabilities.
This method requires the caller to hold either the
Manifest.permission.CHANGE_NETWORK_STATE
permission
or the ability to modify system settings as determined by
Settings.System.canWrite(Context)
.
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
all variants of this method, of registerNetworkCallback(NetworkRequest, PendingIntent)
as well as
ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback
.
Requesting a network 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
unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
.
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback to be utilized for this request. Note
the callback must not be shared - it uniquely specifies this request.
The callback is invoked on the default internal Handler.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if request contains invalid network capabilities. |
SecurityException |
if missing the appropriate permissions. |
RuntimeException |
if the app already has too many callbacks registered. |
requestNetwork
public void requestNetwork (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, int timeoutMs)
Request a network to satisfy a set of NetworkCapabilities
, limited
by a timeout.
This function behaves identically to the non-timed-out version
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
, but if a suitable network
is not found within the given time (in milliseconds) the
NetworkCallback#onUnavailable()
callback is called. The request can still be
released normally by calling unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback)
but does
not have to be released if timed-out (it is automatically released). Unregistering a
request that timed out is not an error.
Do not use this method to poll for the existence of specific networks (e.g. with a small
timeout) - registerNetworkCallback(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
is provided
for that purpose. Calling this method will attempt to bring up the requested network.
This method has the same permission requirements as
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
, is subject to the same limitations,
and throws the same exceptions in the same conditions.
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback to be utilized for this request. Note
the callback must not be shared - it uniquely specifies this request.
This value cannot be null . |
timeoutMs |
int : The time in milliseconds to attempt looking for a suitable network
before NetworkCallback#onUnavailable() is called. The timeout must
be a positive value (i.e. >0). |
requestNetwork
public void requestNetwork (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, Handler handler)
Request a network to satisfy a set of NetworkCapabilities
.
This method behaves identically to requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
but runs all the callbacks on the passed Handler.
This method has the same permission requirements as
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
, is subject to the same limitations,
and throws the same exceptions in the same conditions.
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback to be utilized for this request. Note
the callback must not be shared - it uniquely specifies this request.
This value cannot be null . |
handler |
Handler : Handler to specify the thread upon which the callback will be invoked.
This value cannot be null . |
requestNetwork
public void requestNetwork (NetworkRequest request, PendingIntent operation)
Request a network to satisfy a set of NetworkCapabilities
.
This function behaves identically to the version that takes a NetworkCallback, but instead
of NetworkCallback
a PendingIntent
is used. This means
the request may outlive the calling application and get called back when a suitable
network is found.
The operation is an Intent broadcast that goes to a broadcast receiver that
you registered with Context#registerReceiver
or through the
<receiver> tag in an AndroidManifest.xml file
The operation Intent is delivered with two extras, a Network
typed
extra called EXTRA_NETWORK
and a NetworkRequest
typed extra called EXTRA_NETWORK_REQUEST
containing
the original requests parameters. It is important to create a new,
NetworkCallback
based request before completing the processing of the
Intent to reserve the network or it will be released shortly after the Intent
is processed.
If there is already a request for this Intent registered (with the equality of
two Intents defined by Intent#filterEquals
), then it will be removed and
replaced by this one, effectively releasing the previous NetworkRequest
.
The request may be released normally by calling
releaseNetworkRequest(android.app.PendingIntent)
.
It is presently unsupported to request a network with either
NetworkCapabilities#NET_CAPABILITY_VALIDATED
or
NetworkCapabilities#NET_CAPABILITY_CAPTIVE_PORTAL
as these NetworkCapabilities
represent states that a particular
network may never attain, and whether a network will attain these states
is unknown prior to bringing up the network so the framework does not
know how to go about satisfying a request with these capabilities.
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
all variants of this method, of registerNetworkCallback(NetworkRequest, PendingIntent)
as well as
ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback
.
Requesting a network 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 unregisterNetworkCallback(android.app.PendingIntent)
or releaseNetworkRequest(android.app.PendingIntent)
.
This method requires the caller to hold either the
Manifest.permission.CHANGE_NETWORK_STATE
permission
or the ability to modify system settings as determined by
Settings.System.canWrite(Context)
.
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
operation |
PendingIntent : Action to perform when the network is available (corresponds
to the NetworkCallback#onAvailable call. Typically
comes from PendingIntent#getBroadcast . Cannot be null. |
Throws | |
---|---|
IllegalArgumentException |
if request contains invalid network capabilities. |
SecurityException |
if missing the appropriate permissions. |
RuntimeException |
if the app already has too many callbacks registered. |
requestNetwork
public void requestNetwork (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback, Handler handler, int timeoutMs)
Request a network to satisfy a set of NetworkCapabilities
, limited
by a timeout.
This method behaves identically to
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback, int)
but runs all the callbacks
on the passed Handler.
This method has the same permission requirements as
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
, is subject to the same limitations,
and throws the same exceptions in the same conditions.
Parameters | |
---|---|
request |
NetworkRequest : NetworkRequest describing this request.
This value cannot be null . |
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback to be utilized for this request. Note
the callback must not be shared - it uniquely specifies this request.
This value cannot be null . |
handler |
Handler : Handler to specify the thread upon which the callback will be invoked.
This value cannot be null . |
timeoutMs |
int : The time in milliseconds to attempt looking for a suitable network
before NetworkCallback#onUnavailable is called. |
setNetworkPreference
public void setNetworkPreference (int preference)
This method was deprecated
in API level 21.
Functionality has been removed as it no longer makes sense,
with many more than two networks - we'd need an array to express
preference. Instead we use dynamic network properties of
the networks to describe their precedence.
Specifies the preferred network type. When the device has more than one type available the preferred network type will be used.
Parameters | |
---|---|
preference |
int : the network type to prefer over all others. It is
unspecified what happens to the old preferred network in the
overall ordering. |
setProcessDefaultNetwork
public static boolean setProcessDefaultNetwork (Network network)
This method was deprecated
in API level 23.
This function can throw IllegalStateException
. Use
bindProcessToNetwork(Network)
instead. bindProcessToNetwork
is a direct replacement.
Binds the current process to network
. All Sockets created in the future
(and not explicitly bound via a bound SocketFactory from
Network.getSocketFactory()
) will be bound to
network
. All host name resolutions will be limited to network
as well.
Note that if network
ever disconnects, all Sockets created in this way will cease to
work and all host name resolutions will fail. This is by design so an application doesn't
accidentally use Sockets it thinks are still bound to a particular Network
.
To clear binding pass null
for network
. Using individually bound
Sockets created by Network.getSocketFactory().createSocket() and
performing network-specific host name resolutions via
Network.getAllByName
is preferred to calling
setProcessDefaultNetwork
.
Parameters | |
---|---|
network |
Network : The Network to bind the current process to, or null to clear
the current binding. |
Returns | |
---|---|
boolean |
true on success, false if the Network is no longer valid. |
unregisterNetworkCallback
public void unregisterNetworkCallback (ConnectivityManager.NetworkCallback networkCallback)
Unregisters a NetworkCallback
and possibly releases networks originating from
requestNetwork(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
and
registerNetworkCallback(android.net.NetworkRequest, android.net.ConnectivityManager.NetworkCallback)
calls.
If the given NetworkCallback
had previously been used with #requestNetwork
,
any networks that the device brought up only to satisfy that request will be disconnected.
Notifications that would have triggered that NetworkCallback
will immediately stop
triggering it as soon as this call returns.
Parameters | |
---|---|
networkCallback |
ConnectivityManager.NetworkCallback : The NetworkCallback used when making the request.
This value cannot be null . |
unregisterNetworkCallback
public void unregisterNetworkCallback (PendingIntent operation)
Unregisters a callback previously registered via
registerNetworkCallback(android.net.NetworkRequest, android.app.PendingIntent)
.
Parameters | |
---|---|
operation |
PendingIntent : A PendingIntent equal (as defined by Intent#filterEquals ) to the
PendingIntent passed to
registerNetworkCallback(android.net.NetworkRequest, android.app.PendingIntent) .
Cannot be null. |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-06-18 UTC.