Added in API level 21

NetworkCallback

open class NetworkCallback
kotlin.Any
   ↳ android.net.ConnectivityManager.NetworkCallback

Base class for NetworkRequest callbacks. Used for notifications about network changes. Should be extended by applications wanting notifications. A NetworkCallback is registered by calling requestNetwork(android.net.NetworkRequest,android.net.ConnectivityManager.NetworkCallback), registerNetworkCallback(android.net.NetworkRequest,android.net.ConnectivityManager.NetworkCallback), or registerDefaultNetworkCallback(android.net.ConnectivityManager.NetworkCallback). A NetworkCallback is unregistered by calling unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback). A NetworkCallback should be registered at most once at any time. A NetworkCallback that has been unregistered can be registered again.

Summary

Constants
static Int

Inclusion of this flag means location-sensitive redaction requests keeping location info.
Public constructors

Public methods
open Unit
onAvailable(network: Network)

Called when the framework connects and has declared a new network ready for use.
open Unit
onBlockedStatusChanged(network: Network, blocked: Boolean)

Called when access to the specified network is blocked or unblocked.
open Unit
onCapabilitiesChanged(network: Network, networkCapabilities: NetworkCapabilities)

Called when the network corresponding to this request changes capabilities but still satisfies the requested criteria.
open Unit
onLinkPropertiesChanged(network: Network, linkProperties: LinkProperties)

Called when the network corresponding to this request changes LinkProperties.
open Unit
onLosing(network: Network, maxMsToLive: Int)

Called when the network is about to be lost, typically because there are no outstanding requests left for it.
open Unit
onLost(network: Network)

Called when a network disconnects or otherwise no longer satisfies this request or callback.
open Unit

Called if no network is found within the timeout time specified in requestNetwork(android.net.NetworkRequest,android.net.ConnectivityManager.NetworkCallback,int) call or if the requested network request cannot be fulfilled (whether or not a timeout was specified).

Constants

FLAG_INCLUDE_LOCATION_INFO

Added in API level 31
static val FLAG_INCLUDE_LOCATION_INFO: Int

Inclusion of this flag means location-sensitive redaction requests keeping location info. Some objects like NetworkCapabilities may contain location-sensitive information. Prior to Android 12, this information is always returned to apps holding the appropriate permission, possibly noting that the app has used location.

In Android 12 and above, by default the sent objects do not contain any location information, even if the app holds the necessary permissions, and the system does not take note of location usage by the app. Apps can request that location information is included, in which case the system will check location permission and the location toggle state, and take note of location usage by the app if any such information is returned. Use this flag to include any location sensitive data in NetworkCapabilities sent via onCapabilitiesChanged(android.net.Network,android.net.NetworkCapabilities).

These include:

  • Some transport info instances (retrieved via NetworkCapabilities#getTransportInfo()) like android.net.wifi.WifiInfo contain location sensitive information.
  • OwnerUid (retrieved via NetworkCapabilities#getOwnerUid() is location sensitive for wifi suggestor apps (i.e using WifiNetworkSuggestion).

    • Note:

  • Retrieving this location sensitive information (subject to app's location permissions) will be noted by system.
  • Without this flag any NetworkCapabilities provided via the callback does not include location sensitive information.
    • Value: 1

    Public constructors

    NetworkCallback

    Added in API level 21
    NetworkCallback()

    NetworkCallback

    Added in API level 31
    NetworkCallback(flags: Int)
    Parameters
    flags Int: Value is either 0 or a combination of android.net.ConnectivityManager.NetworkCallback.FLAG_NONE, and android.net.ConnectivityManager.NetworkCallback#FLAG_INCLUDE_LOCATION_INFO

    Public methods

    onAvailable

    Added in API level 21
    open fun onAvailable(network: Network): Unit

    Called when the framework connects and has declared a new network ready for use.

    For callbacks registered with #registerNetworkCallback, multiple networks may be available at the same time, and onAvailable will be called for each of these as they appear.

    For callbacks registered with #requestNetwork and #registerDefaultNetworkCallback, this means the network passed as an argument is the new best network for this request and is now tracked by this callback ; this callback will no longer receive method calls about other networks that may have been passed to this method previously. The previously-best network may have disconnected, or it may still be around and the newly-best network may simply be better.

    Starting with android.os.Build.VERSION_CODES#O, this will always immediately be followed by a call to onCapabilitiesChanged(android.net.Network,android.net.NetworkCapabilities) then by a call to onLinkPropertiesChanged(android.net.Network,android.net.LinkProperties), and a call to onBlockedStatusChanged(android.net.Network,boolean).

    Do NOT call getNetworkCapabilities(android.net.Network) or getLinkProperties(android.net.Network) or other synchronous ConnectivityManager methods in this callback as this is prone to race conditions (there is no guarantee the objects returned by these methods will be current). Instead, wait for a call to onCapabilitiesChanged(android.net.Network,android.net.NetworkCapabilities) and onLinkPropertiesChanged(android.net.Network,android.net.LinkProperties) whose arguments are guaranteed to be well-ordered with respect to other callbacks.

    Parameters
    network Network: The Network of the satisfying network. This value cannot be null.

    onBlockedStatusChanged

    Added in API level 29
    open fun onBlockedStatusChanged(
        network: Network, 
        blocked: Boolean
    ): Unit

    Called when access to the specified network is blocked or unblocked.

    Do NOT call getNetworkCapabilities(android.net.Network) or getLinkProperties(android.net.Network) or other synchronous ConnectivityManager methods in this callback as this is prone to race conditions : calling these methods while in a callback may return an outdated or even a null object.

    Parameters
    network Network: The Network whose blocked status has changed. This value cannot be null.
    blocked Boolean: The blocked status of this Network.

    onCapabilitiesChanged

    Added in API level 21
    open fun onCapabilitiesChanged(
        network: Network, 
        networkCapabilities: NetworkCapabilities
    ): Unit

    Called when the network corresponding to this request changes capabilities but still satisfies the requested criteria.

    Starting with android.os.Build.VERSION_CODES#O this method is guaranteed to be called immediately after onAvailable.

    Do NOT call getLinkProperties(android.net.Network) or other synchronous ConnectivityManager methods in this callback as this is prone to race conditions : calling these methods while in a callback may return an outdated or even a null object.

    Parameters
    network Network: The Network whose capabilities have changed. This value cannot be null.
    networkCapabilities NetworkCapabilities: The new NetworkCapabilities for this network. This value cannot be null.

    onLinkPropertiesChanged

    Added in API level 21
    open fun onLinkPropertiesChanged(
        network: Network, 
        linkProperties: LinkProperties
    ): Unit

    Called when the network corresponding to this request changes LinkProperties.

    Starting with android.os.Build.VERSION_CODES#O this method is guaranteed to be called immediately after onAvailable.

    Do NOT call getNetworkCapabilities(android.net.Network) or other synchronous ConnectivityManager methods in this callback as this is prone to race conditions : calling these methods while in a callback may return an outdated or even a null object.

    Parameters
    network Network: The Network whose link properties have changed. This value cannot be null.
    linkProperties LinkProperties: The new LinkProperties for this network. This value cannot be null.

    onLosing

    Added in API level 21
    open fun onLosing(
        network: Network, 
        maxMsToLive: Int
    ): Unit

    Called when the network is about to be lost, typically because there are no outstanding requests left for it. This may be paired with a NetworkCallback#onAvailable call with the new replacement network for graceful handover. This method is not guaranteed to be called before NetworkCallback#onLost is called, for example in case a network is suddenly disconnected.

    Do NOT call getNetworkCapabilities(android.net.Network) or getLinkProperties(android.net.Network) or other synchronous ConnectivityManager methods in this callback as this is prone to race conditions ; calling these methods while in a callback may return an outdated or even a null object.

    Parameters
    network Network: The Network that is about to be lost. This value cannot be null.
    maxMsToLive Int: The time in milliseconds the system intends to keep the network connected for graceful handover; note that the network may still suffer a hard loss at any time.

    onLost

    Added in API level 21
    open fun onLost(network: Network): Unit

    Called when a network disconnects or otherwise no longer satisfies this request or callback.

    If the callback was registered with requestNetwork() or registerDefaultNetworkCallback(), it will only be invoked against the last network returned by onAvailable() when that network is lost and no other network satisfies the criteria of the request.

    If the callback was registered with registerNetworkCallback() it will be called for each network which no longer satisfies the criteria of the callback.

    Do NOT call getNetworkCapabilities(android.net.Network) or getLinkProperties(android.net.Network) or other synchronous ConnectivityManager methods in this callback as this is prone to race conditions ; calling these methods while in a callback may return an outdated or even a null object.

    Parameters
    network Network: The Network lost. This value cannot be null.

    onUnavailable

    Added in API level 26
    open fun onUnavailable(): Unit

    Called if no network is found within the timeout time specified in requestNetwork(android.net.NetworkRequest,android.net.ConnectivityManager.NetworkCallback,int) call or if the requested network request cannot be fulfilled (whether or not a timeout was specified). When this callback is invoked the associated NetworkRequest will have already been removed and released, as if unregisterNetworkCallback(android.net.ConnectivityManager.NetworkCallback) had been called.