From 00cfe112b436eaafb44c0466ceacce3baf10a8f3 Mon Sep 17 00:00:00 2001
From: Wink Saville <wink@google.com>
Date: Thu, 16 Sep 2010 15:54:32 -0700
Subject: Add LinkSocket API

Restructuring ConnectivityService to handle multiple connections.

Change-Id: Ia993fbb120bebb844fd0d603dc76fbc700b31fd1
---
 core/java/android/net/LinkSocketNotifier.java | 88 +++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 core/java/android/net/LinkSocketNotifier.java

(limited to 'core/java/android/net/LinkSocketNotifier.java')

diff --git a/core/java/android/net/LinkSocketNotifier.java b/core/java/android/net/LinkSocketNotifier.java
new file mode 100644
index 0000000..183c767
--- /dev/null
+++ b/core/java/android/net/LinkSocketNotifier.java
@@ -0,0 +1,88 @@
+/*
+ * Copyright (C) 2010 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 java.util.Map;
+
+/**
+ * Interface used to get feedback about a {@link android.net.LinkSocket}.  Instance is optionally
+ * passed when a LinkSocket is constructed.  Multiple LinkSockets may use the same notifier.
+ * @hide
+ */
+public interface LinkSocketNotifier {
+    /**
+     * This callback function will be called if a better link
+     * becomes available.
+     * TODO - this shouldn't be checked for all cases - what's the conditional
+     *        flag?
+     * If the duplicate socket is accepted, the original will be marked invalid
+     * and additional use will throw exceptions.
+     * @param original the original LinkSocket
+     * @param duplicate the new LinkSocket that better meets the application
+     *                  requirements
+     * @return {@code true} if the application intends to use this link
+     *
+     * REM
+     * TODO - how agressive should we be?
+     * At a minimum CS tracks which LS have this turned on and tracks the requirements
+     * When a new link becomes available, automatically check if any of the LinkSockets
+     *   will care.
+     * If found, grab a refcount on the link so it doesn't go away and send notification
+     * Optionally, periodically setup connection on available networks to check for better links
+     * Maybe pass this info into the LinkFactories so condition changes can be acted on more quickly
+     */
+    public boolean onBetterLinkAvailable(LinkSocket original, LinkSocket duplicate);
+
+    /**
+     * This callback function will be called when a LinkSocket no longer has
+     * an active link.
+     * @param socket the LinkSocket that lost its link
+     *
+     * REM
+     * NetworkStateTracker tells us it is disconnected
+     * CS checks the table for LS on that link
+     * CS calls each callback (need to work out p2p cross process callback)
+     */
+    public void onLinkLost(LinkSocket socket);
+
+    /**
+     * This callback function will be called when an application calls
+     * requestNewLink on a LinkSocket but the LinkSocket is unable to find
+     * a suitable new link.
+     * @param socket the LinkSocket for which a new link was not found
+     * TODO - why the diff between initial request (sync) and requestNewLink?
+     *
+     * REM
+     * CS process of trying to find a new link must track the LS that started it
+     * on failure, call callback
+     */
+    public void onNewLinkUnavailable(LinkSocket socket);
+
+    /**
+     * This callback function will be called when any of the notification-marked
+     * capabilities of the LinkSocket (e.g. upstream bandwidth) have changed.
+     * @param socket the linkSocet for which capabilities have changed
+     * @param changedCapabilities the set of capabilities that the application
+     *                            is interested in and have changed (with new values)
+     *
+     * REM
+     * Maybe pass the interesting capabilities into the Links.
+     * Get notified of every capability change
+     * check for LinkSockets on that Link that are interested in that Capability - call them
+     */
+    public void onCapabilityChanged(LinkSocket socket, LinkCapabilities changedCapabilities);
+}
-- 
cgit v1.1