java.lang.Object | |
↳ | android.net.ConnectivityManager |
Class that answers queries about the state of network connectivity. It also
notifies applications when network connectivity changes. Get an instance
of this class by calling
Context.getSystemService(Context.CONNECTIVITY_SERVICE)
.
The primary responsibilities of this class are to:
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
ConnectivityManager.NetworkCallback | Base class for NetworkRequest callbacks. | ||||||||||
ConnectivityManager.OnNetworkActiveListener | Callback for use with registerDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener)
to find out when the system default network has gone in to a high power state. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | ACTION_BACKGROUND_DATA_SETTING_CHANGED |
This constant was deprecated
in API level 16.
As of 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.
|
|||||||||
String | CONNECTIVITY_ACTION | A change in network connectivity has occurred. | |||||||||
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.
|
|||||||||
String | EXTRA_EXTRA_INFO | The lookup key for a string that provides optionally supplied extra information about the network state. | |||||||||
String | EXTRA_IS_FAILOVER | 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. | |||||||||
String | EXTRA_NETWORK_INFO |
This constant was deprecated
in API level 14.
Since NetworkInfo can vary based on UID, applications
should always obtain network information through
getActiveNetworkInfo() or
getAllNetworkInfo() . |
|||||||||
String | EXTRA_NETWORK_TYPE | Network type which triggered a CONNECTIVITY_ACTION broadcast. |
|||||||||
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 | The lookup key for a NetworkInfo object. |
|||||||||
String | EXTRA_REASON | The lookup key for a string that indicates why an attempt to connect to a network failed. | |||||||||
int | TYPE_BLUETOOTH | The Bluetooth data connection. | |||||||||
int | TYPE_DUMMY | Dummy data connection. | |||||||||
int | TYPE_ETHERNET | The Ethernet data connection. | |||||||||
int | TYPE_MOBILE | The Mobile data connection. | |||||||||
int | TYPE_MOBILE_DUN | A DUN-specific Mobile data connection. | |||||||||
int | TYPE_MOBILE_HIPRI | A High Priority Mobile data connection. | |||||||||
int | TYPE_MOBILE_MMS | An MMS-specific Mobile data connection. | |||||||||
int | TYPE_MOBILE_SUPL | A SUPL-specific Mobile data connection. | |||||||||
int | TYPE_WIFI | The WIFI data connection. | |||||||||
int | TYPE_WIMAX | The WiMAX data connection. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns details about the currently active default data network.
| |||||||||||
Returns connection status information about all network
types supported by the device.
| |||||||||||
This method was deprecated
in API level 14.
As of
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. | |||||||||||
Get the
LinkProperties for the given Network . | |||||||||||
Get the
NetworkCapabilities for the given Network . | |||||||||||
Returns connection status information about a particular
network type.
| |||||||||||
This method is deprecated.
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.
| |||||||||||
Returns the
Network currently bound to this process via
setProcessDefaultNetwork(Network) , or null if no Network is explicitly bound. | |||||||||||
Returns if the currently active data network is metered.
| |||||||||||
Return whether the data network is currently active.
| |||||||||||
Tests if a given integer represents a valid network type.
| |||||||||||
Start listening to reports when the system's default data network is active, meaning it is
a good time to perform network traffic.
| |||||||||||
Registers to receive notifications about all networks which satisfy the given
NetworkRequest . | |||||||||||
Report a problem network to the framework.
| |||||||||||
Request a network to satisfy a set of
NetworkCapabilities . | |||||||||||
This method is deprecated.
Deprecated in favor of the
requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) ,
setProcessDefaultNetwork(Network) and getSocketFactory() api.
| |||||||||||
This method is deprecated.
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.
| |||||||||||
Binds the current process to
network . | |||||||||||
This method is deprecated.
Deprecated in favor of the cleaner
requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) api.
| |||||||||||
This method is deprecated.
Deprecated in favor of the cleaner
requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) api.
| |||||||||||
Remove network active listener previously registered with
registerDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener) . | |||||||||||
Unregisters callbacks about and possibly releases networks originating from
requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback) and registerNetworkCallback(NetworkRequest, ConnectivityManager.NetworkCallback) calls. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
This constant was deprecated
in API level 16.
As of 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
.
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.
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 totrue
if there are no connected networks at all.
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.
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 getStringExtra(String)
.
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 getBooleanExtra(String, boolean)
.
This constant was deprecated
in API level 14.
Since NetworkInfo
can vary based on UID, applications
should always obtain network information through
getActiveNetworkInfo()
or
getAllNetworkInfo()
.
The lookup key for a NetworkInfo
object. Retrieve with
getParcelableExtra(String)
.
Network type which triggered a CONNECTIVITY_ACTION
broadcast.
Can be used with getNetworkInfo(int)
to get NetworkInfo
state based on the calling application.
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 getBooleanExtra(String, boolean)
.
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
getParcelableExtra(String)
.
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 getStringExtra(String)
.
The Bluetooth data connection. When active, all data traffic will use this network type's interface by default (it has a default route).
Dummy data connection. This should not be used on shipping devices.
The Ethernet data connection. When active, all data traffic will use this network type's interface by default (it has a default route).
The Mobile data connection. When active, all data traffic will use this network type's interface by default (it has a default route)
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.
A High Priority Mobile data connection. This network type uses the
same network interface as TYPE_MOBILE
but the routing setup
is different. Only requesting processes will have access to the
Mobile DNS servers and only IP's explicitly requested via requestRouteToHost(int, int)
will route over this interface if no default route exists.
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.
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.
The WIFI data connection. When active, all data traffic will use this network type's interface by default (it has a default route).
The WiMAX data connection. When active, all data traffic will use this network type's interface by default (it has a default route).
Returns details about the currently active default data network. When
connected, this network is the default route for outgoing connections.
You should always check isConnected()
before initiating
network traffic. This may return null
when there is no default
network.
NetworkInfo
object for the current default network
or null
if no network default network is currently active
This method requires the call to hold the permission
ACCESS_NETWORK_STATE
.
Returns connection status information about all network types supported by the device.
NetworkInfo
objects. Check each
getType()
for which type each applies.
This method requires the call to hold the permission
ACCESS_NETWORK_STATE
.
This method was deprecated
in API level 14.
As of 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
.
Get the LinkProperties
for the given Network
. This
will return null
if the network is unknown.
network | The Network object identifying the network in question. |
---|
LinkProperties
for the network, or null
.
Get the NetworkCapabilities
for the given Network
. This
will return null
if the network is unknown.
network | The Network object identifying the network in question. |
---|
NetworkCapabilities
for the network, or null
.
Returns connection status information about a particular network type.
networkType | integer specifying which networkType in which you're interested. |
---|
NetworkInfo
object for the requested
network type or null
if the type is not
supported by the device.
This method requires the call to hold the permission
ACCESS_NETWORK_STATE
.
This method is deprecated.
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.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Returns the Network
currently bound to this process via
setProcessDefaultNetwork(Network)
, or null
if no Network
is explicitly bound.
Network
to which this process is bound, or null
.
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.
true
if large transfers should be avoided, otherwise
false
.
This method requires the call to hold the permission
ACCESS_NETWORK_STATE
.
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.
Tests if a given integer represents a valid network type.
networkType | the type to be tested |
---|
true
if the type is valid, else false
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
setProcessDefaultNetwork(Network)
this function will not
reflect the process's default, but the system default.
l | The listener to be told when the network is active. |
---|
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(ConnectivityManager.NetworkCallback)
is called
request | NetworkRequest describing this request. |
---|---|
networkCallback | The ConnectivityManager.NetworkCallback that the system will call as suitable
networks change state.
|
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.
network | The Network the application was attempting to use
or null to indicate the current default network.
|
---|
Request a network to satisfy a set of NetworkCapabilities
.
This NetworkRequest
will live until released via
unregisterNetworkCallback(ConnectivityManager.NetworkCallback)
or the calling application exits.
Status of the request can be followed by listening to the various
callbacks described in ConnectivityManager.NetworkCallback
. The Network
can be used to direct traffic to the network.
request | NetworkRequest describing this request. |
---|---|
networkCallback | The ConnectivityManager.NetworkCallback to be utilized for this
request. Note the callback must not be shared - they
uniquely specify this request.
|
This method is deprecated.
Deprecated in favor of the requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)
,
setProcessDefaultNetwork(Network)
and getSocketFactory()
api.
Ensure that a network route exists to deliver traffic to the specified host via the specified network interface. An attempt to add a route that already exists is ignored, but treated as successful.
This method requires the caller to hold the permission
CHANGE_NETWORK_STATE
.
networkType | the type of the network over which traffic to the specified host is to be routed |
---|---|
hostAddress | the IP address of the host to which the route is desired |
true
on success, false
on failure
This method is deprecated.
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.
preference | the network type to prefer over all others. It is unspecified what happens to the old preferred network in the overall ordering. |
---|
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
.
network | The Network to bind the current process to, or null to clear
the current binding. |
---|
true
on success, false
if the Network
is no longer valid.
This method is deprecated.
Deprecated in favor of the cleaner requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)
api.
Tells the underlying networking system that the caller wants to
begin using the named feature. The interpretation of feature
is completely up to each networking implementation.
This method requires the caller to hold the permission
CHANGE_NETWORK_STATE
.
networkType | specifies which network the request pertains to |
---|---|
feature | the name of the feature to be used |
-1
always indicates failure.
This method is deprecated.
Deprecated in favor of the cleaner requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)
api.
Tells the underlying networking system that the caller is finished
using the named feature. The interpretation of feature
is completely up to each networking implementation.
This method requires the caller to hold the permission
CHANGE_NETWORK_STATE
.
networkType | specifies which network the request pertains to |
---|---|
feature | the name of the feature that is no longer needed |
-1
always indicates failure.Remove network active listener previously registered with
registerDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener)
.
l | Previously registered listener. |
---|
Unregisters callbacks about and possibly releases networks originating from
requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)
and registerNetworkCallback(NetworkRequest, ConnectivityManager.NetworkCallback)
calls. If the
given NetworkCallback
had previosuly been used with #requestNetwork
,
any networks that had been connected to only to satisfy that request will be
disconnected.
networkCallback | The ConnectivityManager.NetworkCallback used when making the request.
|
---|