NetworkCallback

FLAG_INCLUDE_LOCATION_INFO

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:

Note:

Value: 1

NetworkCallback

NetworkCallback()

NetworkCallback

NetworkCallback(flags: Int)

onAvailable

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.

onBlockedStatusChanged

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.

onCapabilitiesChanged

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.

onLinkPropertiesChanged

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.

onLosing

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.

onLost

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.

onUnavailable

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.