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. Get an instance
of this class by calling
Context.getSystemService(Context.CONNECTIVITY_SERVICE)
.
The primary responsibilities of this class are to:
Nested classes | |
---|---|
class |
ConnectivityManager.NetworkCallback
Base class for NetworkRequest callbacks. |
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
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 |
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
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
The lookup key for a |
String |
EXTRA_NETWORK_INFO
This constant was deprecated
in API level 14.
Since |
String |
EXTRA_NETWORK_REQUEST
The lookup key for a |
String |
EXTRA_NETWORK_TYPE
Network type which triggered a |
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 |
String |
EXTRA_REASON
The lookup key for a string that indicates why an attempt to connect to a network failed. |
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
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
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
A virtual network using one or more native bearers. |
int |
TYPE_WIFI
The WIFI data connection. |
int |
TYPE_WIMAX
The WiMAX data connection. |
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 |
Network
|
getActiveNetwork()
Returns a |
NetworkInfo
|
getActiveNetworkInfo()
Returns details about the currently active default data network. |
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()
Returns an array of all |
boolean
|
getBackgroundDataSetting()
This method was deprecated
in API level 14.
As of |
Network
|
getBoundNetworkForProcess()
Returns the |
ProxyInfo
|
getDefaultProxy()
Get the current default HTTP proxy settings. |
LinkProperties
|
getLinkProperties(Network network)
Get the |
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)
Returns connection status information about a particular Network. |
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. |
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
|
registerDefaultNetworkCallback(ConnectivityManager.NetworkCallback networkCallback)
Registers to receive notifications about changes in the system 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
|
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, PendingIntent operation)
Request a network to satisfy a set of |
boolean
|
requestRouteToHost(int networkType, int hostAddress)
This method was deprecated
in API level 21.
Deprecated in favor of the
|
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 |
int
|
startUsingNetworkFeature(int networkType, String feature)
This method was deprecated
in API level 21.
Deprecated in favor of the cleaner
|
int
|
stopUsingNetworkFeature(int networkType, String feature)
This method was deprecated
in API level 21.
Deprecated in favor of the cleaner
|
void
|
unregisterNetworkCallback(ConnectivityManager.NetworkCallback networkCallback)
Unregisters callbacks about and possibly releases networks originating from
|
void
|
unregisterNetworkCallback(PendingIntent operation)
Unregisters a callback previously registered via
|
Inherited methods | |
---|---|
From
class
java.lang.Object
|
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.
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"
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:
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. ignoreNetwork()
. Constant Value: "android.net.conn.CAPTIVE_PORTAL"
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"
String CONNECTIVITY_ACTION
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.
Constant Value: "android.net.conn.CONNECTIVITY_CHANGE"
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)
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
getParcelableExtra(String)
.
Constant Value: "android.net.extra.CAPTIVE_PORTAL"
String EXTRA_CAPTIVE_PORTAL_URL
Key for passing a URL to the captive portal login activity.
Constant Value: "android.net.extra.CAPTIVE_PORTAL_URL"
String EXTRA_EXTRA_INFO
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)
.
Constant Value: "extraInfo"
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.
Retrieve it with getBooleanExtra(String, boolean)
.
Constant Value: "isFailover"
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
getParcelableExtra(String)
.
Note that if you intend to invoke openConnection(java.net.URL)
then you must get a ConnectivityManager instance before doing so.
Constant Value: "android.net.extra.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()
.
The lookup key for a NetworkInfo
object. Retrieve with
getParcelableExtra(String)
.
See also:
Constant Value: "networkInfo"
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
getParcelableExtra(String)
.
Constant Value: "android.net.extra.NETWORK_REQUEST"
String EXTRA_NETWORK_TYPE
Network type which triggered a CONNECTIVITY_ACTION
broadcast.
See also:
Constant Value: "networkType"
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 getBooleanExtra(String, boolean)
.
Constant Value: "noConnectivity"
String EXTRA_OTHER_NETWORK_INFO
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)
.
Constant Value: "otherNetwork"
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 getStringExtra(String)
.
Constant Value: "reason"
int RESTRICT_BACKGROUND_STATUS_DISABLED
Device is not restricting metered network activity while application is running on background.
Constant Value: 1 (0x00000001)
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)
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)
int TYPE_BLUETOOTH
The Bluetooth data connection. When active, all data traffic will use this network type's interface by default (it has a default route).
Constant Value: 7 (0x00000007)
int TYPE_DUMMY
Dummy data connection. This should not be used on shipping devices.
Constant Value: 8 (0x00000008)
int TYPE_ETHERNET
The Ethernet data connection. When active, all data traffic will use this network type's interface by default (it has a default route).
Constant Value: 9 (0x00000009)
int TYPE_MOBILE
The Mobile data connection. When active, all data traffic will use this network type's interface by default (it has a default route)
Constant Value: 0 (0x00000000)
int TYPE_MOBILE_DUN
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)
int TYPE_MOBILE_HIPRI
This constant was deprecated
in API level 23.
Applications should instead use
requestNetwork(NetworkRequest, NetworkCallback)
to request a network that
uses the TRANSPORT_CELLULAR
transport.
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)
int TYPE_MOBILE_MMS
This constant was deprecated
in API level 23.
Applications should instead use
requestNetwork(NetworkRequest, NetworkCallback)
to request a network that
provides the 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)
int TYPE_MOBILE_SUPL
This constant was deprecated
in API level 23.
Applications should instead use
requestNetwork(NetworkRequest, NetworkCallback)
to request a network that
provides the 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)
int TYPE_VPN
A virtual network using one or more native bearers. It may or may not be providing security services.
Constant Value: 17 (0x00000011)
int TYPE_WIFI
The WIFI data connection. When active, all data traffic will use this network type's interface by default (it has a default route).
Constant Value: 1 (0x00000001)
int TYPE_WIMAX
The WiMAX data connection. When active, all data traffic will use this network type's interface by default (it has a default route).
Constant Value: 6 (0x00000006)
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
bindProcessToNetwork(Network)
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.
|
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.
|
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.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Returns | |
---|---|
Network |
a Network object for the current default network or
null if no default network is currently active
|
NetworkInfo getActiveNetworkInfo ()
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.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Returns | |
---|---|
NetworkInfo |
a NetworkInfo object for the current default network
or null if no default network is currently active
|
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.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Returns | |
---|---|
NetworkInfo[] |
an array of NetworkInfo objects. Check each
getType() for which type each applies. |
Network[] getAllNetworks ()
Returns an array of all Network
currently tracked by the
framework.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Returns | |
---|---|
Network[] |
an array of Network objects.
|
boolean getBackgroundDataSetting ()
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
.
Returns | |
---|---|
boolean |
Whether background data usage is allowed. |
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 .
|
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.
|
LinkProperties getLinkProperties (Network network)
Get the LinkProperties
for the given Network
. This
will return null
if the network is unknown.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Parameters | |
---|---|
network |
Network :
The Network object identifying the network in question. |
Returns | |
---|---|
LinkProperties |
The LinkProperties for the network, or null .
|
NetworkCapabilities getNetworkCapabilities (Network network)
Get the NetworkCapabilities
for the given Network
. This
will return null
if the network is unknown.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Parameters | |
---|---|
network |
Network :
The Network object identifying the network in question. |
Returns | |
---|---|
NetworkCapabilities |
The NetworkCapabilities for the network, or null .
|
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.
This method requires the caller to hold the 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. |
NetworkInfo getNetworkInfo (Network network)
Returns connection status information about a particular Network.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Parameters | |
---|---|
network |
Network :
Network specifying which network
in which you're interested. |
Returns | |
---|---|
NetworkInfo |
a NetworkInfo object for the requested
network or null if the Network
is not valid.
|
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.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Returns | |
---|---|
int |
an integer representing the preferred network type |
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 . |
int getRestrictBackgroundStatus ()
Determines if the calling application is subject to metered network restrictions while running on background.
Returns | |
---|---|
int |
RESTRICT_BACKGROUND_STATUS_DISABLED ,
RESTRICT_BACKGROUND_STATUS_ENABLED ,
or RESTRICT_BACKGROUND_STATUS_WHITELISTED
|
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.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Returns | |
---|---|
boolean |
true if large transfers should be avoided, otherwise
false .
|
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 |
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 |
a boolean. true if the type is valid, else false |
void registerDefaultNetworkCallback (ConnectivityManager.NetworkCallback networkCallback)
Registers to receive notifications about changes in the system default network. The callbacks
will continue to be called until either the application exits or
unregisterNetworkCallback(NetworkCallback)
is called.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Parameters | |
---|---|
networkCallback |
ConnectivityManager.NetworkCallback :
The ConnectivityManager.NetworkCallback that the system will call as the
system default network changes.
|
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 link #unregisterNetworkCallback(NetworkCallback)} is called.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Parameters | |
---|---|
request |
NetworkRequest :
NetworkRequest describing this request. |
networkCallback |
ConnectivityManager.NetworkCallback :
The ConnectivityManager.NetworkCallback that the system will call as suitable
networks change state.
|
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 ConnectivityManager.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 registerReceiver(BroadcastReceiver, IntentFilter)
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 filterEquals(Intent)
), 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)
.
This method requires the caller to hold the permission
ACCESS_NETWORK_STATE
.
Parameters | |
---|---|
request |
NetworkRequest :
NetworkRequest describing this request. |
operation |
PendingIntent :
Action to perform when the network is available (corresponds
to the onAvailable(Network) call. Typically
comes from getBroadcast(Context, int, Intent, int) . Cannot be null.
|
void releaseNetworkRequest (PendingIntent operation)
Removes a request made via requestNetwork(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 filterEquals(Intent) ) to the
PendingIntent passed to
requestNetwork(NetworkRequest, android.app.PendingIntent) with the
corresponding NetworkRequest you'd like to remove. Cannot be null.
|
void removeDefaultNetworkActiveListener (ConnectivityManager.OnNetworkActiveListener l)
Remove network active listener previously registered with
addDefaultNetworkActiveListener(ConnectivityManager.OnNetworkActiveListener)
.
Parameters | |
---|---|
l |
ConnectivityManager.OnNetworkActiveListener :
Previously registered listener.
|
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. |
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.
|
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(NetworkRequest, NetworkCallback)
to listen for network
changes.
Parameters | |
---|---|
network |
Network :
Network specifying which network you're interested. |
Returns | |
---|---|
boolean |
true on success, false if the Network is no longer valid.
|
void requestNetwork (NetworkRequest request, ConnectivityManager.NetworkCallback networkCallback)
Request a network to satisfy a set of NetworkCapabilities
.
This NetworkRequest
will live until released via
unregisterNetworkCallback(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.
It is presently unsupported to request a network with mutable
NetworkCapabilities
such as
NET_CAPABILITY_VALIDATED
or
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 satisfing a request with these capabilities.
This method requires the caller to hold either the
CHANGE_NETWORK_STATE
permission
or the ability to modify system settings as determined by
canWrite(Context)
.
Parameters | |
---|---|
request |
NetworkRequest :
NetworkRequest describing this request. |
networkCallback |
ConnectivityManager.NetworkCallback :
The ConnectivityManager.NetworkCallback to be utilized for this
request. Note the callback must not be shared - they
uniquely specify this request. |
Throws | |
---|---|
IllegalArgumentException |
if request specifies any mutable
NetworkCapabilities .
|
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 ConnectivityManager.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 registerReceiver(BroadcastReceiver, IntentFilter)
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,
ConnectivityManager.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 filterEquals(Intent)
), 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
NET_CAPABILITY_VALIDATED
or
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 satisfing a request with these capabilities.
This method requires the caller to hold either the
CHANGE_NETWORK_STATE
permission
or the ability to modify system settings as determined by
canWrite(Context)
.
Parameters | |
---|---|
request |
NetworkRequest :
NetworkRequest describing this request. |
operation |
PendingIntent :
Action to perform when the network is available (corresponds
to the onAvailable(Network) call. Typically
comes from getBroadcast(Context, int, Intent, int) . Cannot be null. |
Throws | |
---|---|
IllegalArgumentException |
if request contains either
NET_CAPABILITY_VALIDATED or
NET_CAPABILITY_CAPTIVE_PORTAL .
|
boolean requestRouteToHost (int networkType, int hostAddress)
This method was deprecated
in API level 21.
Deprecated in favor of the
requestNetwork(NetworkRequest, NetworkCallback)
,
bindProcessToNetwork(Network)
and getSocketFactory()
API.
In M
, and above, this method is unsupported and will
throw UnsupportedOperationException
if called.
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 either the
CHANGE_NETWORK_STATE
permission
or the ability to modify system settings as determined by
canWrite(Context)
.
Parameters | |
---|---|
networkType |
int :
the type of the network over which traffic to the specified
host is to be routed |
hostAddress |
int :
the IP address of the host to which the route is desired |
Returns | |
---|---|
boolean |
true on success, false on failure |
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. |
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. |
int startUsingNetworkFeature (int networkType, String feature)
This method was deprecated
in API level 21.
Deprecated in favor of the cleaner
requestNetwork(NetworkRequest, NetworkCallback)
API.
In M
, and above, this method is unsupported and will
throw UnsupportedOperationException
if called.
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 either the
CHANGE_NETWORK_STATE
permission
or the ability to modify system settings as determined by
canWrite(Context)
.
Parameters | |
---|---|
networkType |
int :
specifies which network the request pertains to |
feature |
String :
the name of the feature to be used |
Returns | |
---|---|
int |
an integer value representing the outcome of the request.
The interpretation of this value is specific to each networking
implementation+feature combination, except that the value -1
always indicates failure. |
int stopUsingNetworkFeature (int networkType, String feature)
This method was deprecated
in API level 21.
Deprecated in favor of the cleaner
unregisterNetworkCallback(NetworkCallback)
API.
In M
, and above, this method is unsupported and will
throw UnsupportedOperationException
if called.
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 either the
CHANGE_NETWORK_STATE
permission
or the ability to modify system settings as determined by
canWrite(Context)
.
Parameters | |
---|---|
networkType |
int :
specifies which network the request pertains to |
feature |
String :
the name of the feature that is no longer needed |
Returns | |
---|---|
int |
an integer value representing the outcome of the request.
The interpretation of this value is specific to each networking
implementation+feature combination, except that the value -1
always indicates failure. |
void unregisterNetworkCallback (ConnectivityManager.NetworkCallback networkCallback)
Unregisters callbacks about and possibly releases networks originating from
requestNetwork(NetworkRequest, NetworkCallback)
and
registerNetworkCallback(NetworkRequest, NetworkCallback)
calls.
If the given NetworkCallback
had previously been used with
#requestNetwork
, any networks that had been connected to only to satisfy that request
will be disconnected.
Parameters | |
---|---|
networkCallback |
ConnectivityManager.NetworkCallback :
The ConnectivityManager.NetworkCallback used when making the request.
|
void unregisterNetworkCallback (PendingIntent operation)
Unregisters a callback previously registered via
registerNetworkCallback(NetworkRequest, android.app.PendingIntent)
.
Parameters | |
---|---|
operation |
PendingIntent :
A PendingIntent equal (as defined by filterEquals(Intent) ) to the
PendingIntent passed to
registerNetworkCallback(NetworkRequest, android.app.PendingIntent) .
Cannot be null.
|