1 files changed, 65 insertions, 4 deletions

diff --git a/core/java/android/net/ConnectivityServiceProtocol.java b/core/java/android/net/ConnectivityServiceProtocol.java
index 34ba645..c670166 100644
--- a/core/java/android/net/ConnectivityServiceProtocol.java
+++ b/core/java/android/net/ConnectivityServiceProtocol.java
@@ -23,15 +23,41 @@ import static com.android.internal.util.Protocol.BASE_CONNECTIVITY_SERVICE;
  * @hide
  */
 public class ConnectivityServiceProtocol {
-    private ConnectivityServiceProtocol() {}
 
     private static final int BASE = BASE_CONNECTIVITY_SERVICE;
 
+    private ConnectivityServiceProtocol() {}
+
+    /**
+     * This is a contract between ConnectivityService and various bearers.
+     * A NetworkFactory is an abstract entity that creates NetworkAgent objects.
+     * The bearers register with ConnectivityService using
+     * ConnectivityManager.registerNetworkFactory, where they pass in a Messenger
+     * to be used to deliver the following Messages.
+     */
     public static class NetworkFactoryProtocol {
         private NetworkFactoryProtocol() {}
         /**
-         * Pass a network request to the transport
+         * Pass a network request to the bearer.  If the bearer believes it can
+         * satisfy the request it should connect to the network and create a
+         * NetworkAgent.  Once the NetworkAgent is fully functional it will
+         * register itself with ConnectivityService using registerNetworkAgent.
+         * If the bearer cannot immediately satisfy the request (no network,
+         * user disabled the radio, lower-scored network) it should remember
+         * any NetworkRequests it may be able to satisfy in the future.  It may
+         * disregard any that it will never be able to service, for example
+         * those requiring a different bearer.
          * msg.obj = NetworkRequest
+         * msg.arg1 = score - the score of the any network currently satisfying this
+         *            request.  If this bearer knows in advance it cannot
+         *            exceed this score it should not try to connect, holding the request
+         *            for the future.
+         *            Note that subsequent events may give a different (lower
+         *            or higher) score for this request, transmitted to each
+         *            NetworkFactory through additional CMD_REQUEST_NETWORK msgs
+         *            with the same NetworkRequest but an updated score.
+         *            Also, network conditions may change for this bearer
+         *            allowing for a better score in the future.
          */
         public static final int CMD_REQUEST_NETWORK = BASE;
 
@@ -42,7 +68,42 @@ public class ConnectivityServiceProtocol {
         public static final int CMD_CANCEL_REQUEST = BASE + 1;
     }
 
-    public static class NetworkAgentProtocol {
-        private NetworkAgentProtocol() {}
+    /**
+     * TODO - move to NetworkMonitor and document
+     */
+    public static class NetworkMonitorProtocol {
+        private NetworkMonitorProtocol() {}
+        /**
+         * Inform NetworkMonitor that their network is connected.
+         * Initiates Network Validation.
+         */
+        public static final int CMD_NETWORK_CONNECTED = BASE + 200;
+
+        /**
+         * Inform ConnectivityService that the network is validated.
+         * obj = NetworkAgent
+         */
+        public static final int EVENT_NETWORK_VALIDATED = BASE + 201;
+
+        /**
+         * Inform NetworkMonitor to linger a network.  The Monitor should
+         * start a timer and/or start watching for zero live connections while
+         * moving towards LINGER_COMPLETE.  After the Linger period expires
+         * (or other events mark the end of the linger state) the LINGER_COMPLETE
+         * event should be sent to ConnectivityService and ConnectivityService
+         * will shut down the network, telling the corresponding NetworkAgent
+         * to disconnect.  If a CMD_NETWORK_CONNECTED happens before the LINGER completes
+         * it indicates further desire to keep the network alive and so
+         * the LINGER is aborted.
+         * TODO - figure out who manages/does this simple state machine
+         */
+        public static final int CMD_NETWORK_LINGER = BASE + 202;
+
+        /**
+         * Inform ConnectivityService that the network LINGER period has
+         * expired.
+         * obj = NetworkAgent
+         */
+        public static final int EVENT_NETWORK_LINGER_COMPLETE = BASE + 203;
     }
 }