1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.net;
18
19import java.util.Map;
20
21/**
22 * Interface used to get feedback about a {@link android.net.LinkSocket}.  Instance is optionally
23 * passed when a LinkSocket is constructed.  Multiple LinkSockets may use the same notifier.
24 * @hide
25 */
26public interface LinkSocketNotifier {
27    /**
28     * This callback function will be called if a better link
29     * becomes available.
30     * TODO - this shouldn't be checked for all cases - what's the conditional
31     *        flag?
32     * If the duplicate socket is accepted, the original will be marked invalid
33     * and additional use will throw exceptions.
34     * @param original the original LinkSocket
35     * @param duplicate the new LinkSocket that better meets the application
36     *                  requirements
37     * @return {@code true} if the application intends to use this link
38     *
39     * REM
40     * TODO - how agressive should we be?
41     * At a minimum CS tracks which LS have this turned on and tracks the requirements
42     * When a new link becomes available, automatically check if any of the LinkSockets
43     *   will care.
44     * If found, grab a refcount on the link so it doesn't go away and send notification
45     * Optionally, periodically setup connection on available networks to check for better links
46     * Maybe pass this info into the LinkFactories so condition changes can be acted on more quickly
47     */
48    public boolean onBetterLinkAvailable(LinkSocket original, LinkSocket duplicate);
49
50    /**
51     * This callback function will be called when a LinkSocket no longer has
52     * an active link.
53     * @param socket the LinkSocket that lost its link
54     *
55     * REM
56     * NetworkStateTracker tells us it is disconnected
57     * CS checks the table for LS on that link
58     * CS calls each callback (need to work out p2p cross process callback)
59     */
60    public void onLinkLost(LinkSocket socket);
61
62    /**
63     * This callback function will be called when an application calls
64     * requestNewLink on a LinkSocket but the LinkSocket is unable to find
65     * a suitable new link.
66     * @param socket the LinkSocket for which a new link was not found
67     * TODO - why the diff between initial request (sync) and requestNewLink?
68     *
69     * REM
70     * CS process of trying to find a new link must track the LS that started it
71     * on failure, call callback
72     */
73    public void onNewLinkUnavailable(LinkSocket socket);
74
75    /**
76     * This callback function will be called when any of the notification-marked
77     * capabilities of the LinkSocket (e.g. upstream bandwidth) have changed.
78     * @param socket the linkSocet for which capabilities have changed
79     * @param changedCapabilities the set of capabilities that the application
80     *                            is interested in and have changed (with new values)
81     *
82     * REM
83     * Maybe pass the interesting capabilities into the Links.
84     * Get notified of every capability change
85     * check for LinkSockets on that Link that are interested in that Capability - call them
86     */
87    public void onCapabilitiesChanged(LinkSocket socket, LinkCapabilities changedCapabilities);
88}
89