Merge "Add API surface for ConnectivityDiagnostics API."

    field @NonNull public static final android.os.Parcelable.Creator<android.net.CaptivePortal> CREATOR;

  }

  public class ConnectivityDiagnosticsManager {

    method public void registerConnectivityDiagnosticsCallback(@NonNull android.net.NetworkRequest, @NonNull java.util.concurrent.Executor, @NonNull android.net.ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback);

    method public void unregisterConnectivityDiagnosticsCallback(@NonNull android.net.ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback);

    field public static final int DETECTION_METHOD_DNS_EVENTS = 1; // 0x1

    field public static final int DETECTION_METHOD_TCP_METRICS = 2; // 0x2

  }

  public abstract static class ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback {

    ctor public ConnectivityDiagnosticsManager.ConnectivityDiagnosticsCallback();

    method public void onConnectivityReport(@NonNull android.net.ConnectivityDiagnosticsManager.ConnectivityReport);

    method public void onDataStallSuspected(@NonNull android.net.ConnectivityDiagnosticsManager.DataStallReport);

    method public void onNetworkConnectivityReported(@NonNull android.net.Network, boolean);

  }

  public static class ConnectivityDiagnosticsManager.ConnectivityReport {

    ctor public ConnectivityDiagnosticsManager.ConnectivityReport(@NonNull android.net.Network, long, @NonNull android.net.LinkProperties, @NonNull android.net.NetworkCapabilities, @NonNull android.os.PersistableBundle);

    field @NonNull public final android.os.PersistableBundle additionalInfo;

    field @NonNull public final android.net.LinkProperties linkProperties;

    field @NonNull public final android.net.Network network;

    field @NonNull public final android.net.NetworkCapabilities networkCapabilities;

    field public final long reportTimestamp;

  }

  public static class ConnectivityDiagnosticsManager.DataStallReport {

    ctor public ConnectivityDiagnosticsManager.DataStallReport(@NonNull android.net.Network, long, int, @NonNull android.os.PersistableBundle);

    field public final int detectionMethod;

    field @NonNull public final android.net.Network network;

    field public final long reportTimestamp;

    field @NonNull public final android.os.PersistableBundle stallDetails;

  }

  public class ConnectivityManager {

    method public void addDefaultNetworkActiveListener(android.net.ConnectivityManager.OnNetworkActiveListener);

    method public boolean bindProcessToNetwork(@Nullable android.net.Network);

/*

 * Copyright (C) 2019 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package android.net;

import android.annotation.IntDef;

import android.annotation.NonNull;

import android.os.PersistableBundle;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.util.concurrent.Executor;

/**

 * Class that provides utilities for collecting network connectivity diagnostics information.

 * Connectivity information is made available through triggerable diagnostics tools and by listening

 * to System validations. Some diagnostics information may be permissions-restricted.

 *

 * <p>ConnectivityDiagnosticsManager is intended for use by applications offering network

 * connectivity on a user device. These tools will provide several mechanisms for these applications

 * to be alerted to network conditions as well as diagnose potential network issues themselves.

 *

 * <p>The primary responsibilities of this class are to:

 *

 * <ul>

 *   <li>Allow permissioned applications to register and unregister callbacks for network event

 *       notifications

 *   <li>Invoke callbacks for network event notifications, including:

 *       <ul>

 *         <li>Network validations

 *         <li>Data stalls

 *         <li>Connectivity reports from applications

 *       </ul>

 * </ul>

 */

public class ConnectivityDiagnosticsManager {

    public static final int DETECTION_METHOD_DNS_EVENTS = 1;

    public static final int DETECTION_METHOD_TCP_METRICS = 2;

    /** @hide */

    @Retention(RetentionPolicy.SOURCE)

    @IntDef(

            prefix = {"DETECTION_METHOD_"},

            value = {DETECTION_METHOD_DNS_EVENTS, DETECTION_METHOD_TCP_METRICS})

    public @interface DetectionMethod {}

    /** @hide */

    public ConnectivityDiagnosticsManager() {}

    /** Class that includes connectivity information for a specific Network at a specific time. */

    public static class ConnectivityReport {

        /** The Network for which this ConnectivityReport applied */

        @NonNull public final Network network;

        /**

         * The timestamp for the report. The timestamp is taken from {@link

         * System#currentTimeMillis}.

         */

        public final long reportTimestamp;

        /** LinkProperties available on the Network at the reported timestamp */

        @NonNull public final LinkProperties linkProperties;

        /** NetworkCapabilities available on the Network at the reported timestamp */

        @NonNull public final NetworkCapabilities networkCapabilities;

        /** PersistableBundle that may contain additional info about the report */

        @NonNull public final PersistableBundle additionalInfo;

        /**

         * Constructor for ConnectivityReport.

         *

         * <p>Apps should obtain instances through {@link

         * ConnectivityDiagnosticsCallback#onConnectivityReport} instead of instantiating their own

         * instances (unless for testing purposes).

         *

         * @param network The Network for which this ConnectivityReport applies

         * @param reportTimestamp The timestamp for the report

         * @param linkProperties The LinkProperties available on network at reportTimestamp

         * @param networkCapabilities The NetworkCapabilities available on network at

         *     reportTimestamp

         * @param additionalInfo A PersistableBundle that may contain additional info about the

         *     report

         */

        public ConnectivityReport(

                @NonNull Network network,

                long reportTimestamp,

                @NonNull LinkProperties linkProperties,

                @NonNull NetworkCapabilities networkCapabilities,

                @NonNull PersistableBundle additionalInfo) {

            this.network = network;

            this.reportTimestamp = reportTimestamp;

            this.linkProperties = linkProperties;

            this.networkCapabilities = networkCapabilities;

            this.additionalInfo = additionalInfo;

        }

    }

    /** Class that includes information for a suspected data stall on a specific Network */

    public static class DataStallReport {

        /** The Network for which this DataStallReport applied */

        @NonNull public final Network network;

        /**

         * The timestamp for the report. The timestamp is taken from {@link

         * System#currentTimeMillis}.

         */

        public final long reportTimestamp;

        /** The detection method used to identify the suspected data stall */

        @DetectionMethod public final int detectionMethod;

        /** PersistableBundle that may contain additional information on the suspected data stall */

        @NonNull public final PersistableBundle stallDetails;

        /**

         * Constructor for DataStallReport.

         *

         * <p>Apps should obtain instances through {@link

         * ConnectivityDiagnosticsCallback#onDataStallSuspected} instead of instantiating their own

         * instances (unless for testing purposes).

         *

         * @param network The Network for which this DataStallReport applies

         * @param reportTimestamp The timestamp for the report

         * @param detectionMethod The detection method used to identify this data stall

         * @param stallDetails A PersistableBundle that may contain additional info about the report

         */

        public DataStallReport(

                @NonNull Network network,

                long reportTimestamp,

                @DetectionMethod int detectionMethod,

                @NonNull PersistableBundle stallDetails) {

            this.network = network;

            this.reportTimestamp = reportTimestamp;

            this.detectionMethod = detectionMethod;

            this.stallDetails = stallDetails;

        }

    }

    /**

     * Abstract base class for Connectivity Diagnostics callbacks. Used for notifications about

     * network connectivity events. Must be extended by applications wanting notifications.

     */

    public abstract static class ConnectivityDiagnosticsCallback {

        /**

         * Called when the platform completes a data connectivity check. This will also be invoked

         * upon registration with the latest report.

         *

         * <p>The Network specified in the ConnectivityReport may not be active any more when this

         * method is invoked.

         *

         * @param report The ConnectivityReport containing information about a connectivity check

         */

        public void onConnectivityReport(@NonNull ConnectivityReport report) {}

        /**

         * Called when the platform suspects a data stall on some Network.

         *

         * <p>The Network specified in the DataStallReport may not be active any more when this

         * method is invoked.

         *

         * @param report The DataStallReport containing information about the suspected data stall

         */

        public void onDataStallSuspected(@NonNull DataStallReport report) {}

        /**

         * Called when any app reports connectivity to the System.

         *

         * @param network The Network for which connectivity has been reported

         * @param hasConnectivity The connectivity reported to the System

         */

        public void onNetworkConnectivityReported(

                @NonNull Network network, boolean hasConnectivity) {}

    }

    /**

     * Registers a ConnectivityDiagnosticsCallback with the System.

     *

     * <p>Only apps that offer network connectivity to the user are allowed to register callbacks.

     * This includes:

     *

     * <ul>

     *   <li>Carrier apps with active subscriptions

     *   <li>Active VPNs

     *   <li>WiFi Suggesters

     * </ul>

     *

     * <p>Callbacks will be limited to receiving notifications for networks over which apps provide

     * connectivity.

     *

     * <p>If a registering app loses its relevant permissions, any callbacks it registered will

     * silently stop receiving callbacks.

     *

     * <p>Each register() call <b>MUST</b> use a unique ConnectivityDiagnosticsCallback instance. If

     * a single instance is registered with multiple NetworkRequests, an IllegalArgumentException

     * will be thrown.

     *

     * @param request The NetworkRequest that will be used to match with Networks for which

     *     callbacks will be fired

     * @param e The Executor to be used for running the callback method invocations

     * @param callback The ConnectivityDiagnosticsCallback that the caller wants registered with the

     *     System

     * @throws IllegalArgumentException if the same callback instance is registered with multiple

     *     NetworkRequests

     * @throws SecurityException if the caller does not have appropriate permissions to register a

     *     callback

     */

    public void registerConnectivityDiagnosticsCallback(

            @NonNull NetworkRequest request,

            @NonNull Executor e,

            @NonNull ConnectivityDiagnosticsCallback callback) {

        // TODO(b/143187964): implement ConnectivityDiagnostics functionality

        throw new UnsupportedOperationException("registerCallback() not supported yet");

    }

    /**

     * Unregisters a ConnectivityDiagnosticsCallback with the System.

     *

     * <p>If the given callback is not currently registered with the System, this operation will be

     * a no-op.

     *

     * @param callback The ConnectivityDiagnosticsCallback to be unregistered from the System.

     */

    public void unregisterConnectivityDiagnosticsCallback(

            @NonNull ConnectivityDiagnosticsCallback callback) {

        // TODO(b/143187964): implement ConnectivityDiagnostics functionality

        throw new UnsupportedOperationException("registerCallback() not supported yet");

    }

}