1 /*
2  * Copyright (C) 2019 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 
17 package android.net.ip;
18 
19 import android.net.DhcpResultsParcelable;
20 import android.net.Layer2PacketParcelable;
21 import android.net.LinkProperties;
22 
23 import java.util.List;
24 
25 /**
26  * Callbacks for handling IpClient events.
27  *
28  * This is a convenience class to allow clients not to override all methods of IIpClientCallbacks,
29  * and avoid unparceling arguments.
30  * These methods are called asynchronously on a Binder thread, as IpClient lives in a different
31  * process.
32  * @hide
33  */
34 public class IpClientCallbacks {
35 
36     /**
37      * Callback called upon IpClient creation.
38      *
39      * @param ipClient The Binder token to communicate with IpClient.
40      */
onIpClientCreated(IIpClient ipClient)41     public void onIpClientCreated(IIpClient ipClient) {}
42 
43     /**
44      * Callback called prior to DHCP discovery/renewal.
45      *
46      * <p>In order to receive onPreDhcpAction(), call #withPreDhcpAction() when constructing a
47      * ProvisioningConfiguration.
48      *
49      * <p>Implementations of onPreDhcpAction() must call IpClient#completedPreDhcpAction() to
50      * indicate that DHCP is clear to proceed.
51       */
onPreDhcpAction()52     public void onPreDhcpAction() {}
53 
54     /**
55      * Callback called after DHCP discovery/renewal.
56      */
onPostDhcpAction()57     public void onPostDhcpAction() {}
58 
59     /**
60      * Callback called when new DHCP results are available.
61      *
62      * <p>This is purely advisory and not an indication of provisioning success or failure.  This is
63      * only here for callers that want to expose DHCPv4 results to other APIs
64      * (e.g., WifiInfo#setInetAddress).
65      *
66      * <p>DHCPv4 or static IPv4 configuration failure or success can be determined by whether or not
67      * the passed-in DhcpResults object is null.
68      */
onNewDhcpResults(DhcpResultsParcelable dhcpResults)69     public void onNewDhcpResults(DhcpResultsParcelable dhcpResults) {
70         // In general callbacks would not use a parcelable directly (DhcpResultsParcelable), and
71         // would use a wrapper instead. But there are already two classes in the tree for DHCP
72         // information: DhcpInfo and DhcpResults, and each of them do not expose an appropriate API
73         // (they are bags of mutable fields and can't be changed because they are public API and
74         // @UnsupportedAppUsage). Adding a third class would cost more than the gain considering
75         // that the only client of this callback is WiFi, which will end up converting the results
76         // to DhcpInfo anyway.
77     }
78 
79     /**
80      * Indicates that provisioning was successful.
81      */
onProvisioningSuccess(LinkProperties newLp)82     public void onProvisioningSuccess(LinkProperties newLp) {}
83 
84     /**
85      * Indicates that provisioning failed.
86      */
onProvisioningFailure(LinkProperties newLp)87     public void onProvisioningFailure(LinkProperties newLp) {}
88 
89     /**
90      * Invoked on LinkProperties changes.
91      */
onLinkPropertiesChange(LinkProperties newLp)92     public void onLinkPropertiesChange(LinkProperties newLp) {}
93 
94     /**Called when the internal IpReachabilityMonitor (if enabled) has
95      * detected the loss of a critical number of required neighbors.
96      */
onReachabilityLost(String logMsg)97     public void onReachabilityLost(String logMsg) {}
98 
99     /**
100      * Called when the IpClient state machine terminates.
101      */
onQuit()102     public void onQuit() {}
103 
104     /**
105      * Called to indicate that a new APF program must be installed to filter incoming packets.
106      */
installPacketFilter(byte[] filter)107     public void installPacketFilter(byte[] filter) {}
108 
109     /**
110      * Called to indicate that the APF Program & data buffer must be read asynchronously from the
111      * wifi driver.
112      *
113      * <p>Due to Wifi HAL limitations, the current implementation only supports dumping the entire
114      * buffer. In response to this request, the driver returns the data buffer asynchronously
115      * by sending an IpClient#EVENT_READ_PACKET_FILTER_COMPLETE message.
116      */
startReadPacketFilter()117     public void startReadPacketFilter() {}
118 
119     /**
120      * If multicast filtering cannot be accomplished with APF, this function will be called to
121      * actuate multicast filtering using another means.
122      */
setFallbackMulticastFilter(boolean enabled)123     public void setFallbackMulticastFilter(boolean enabled) {}
124 
125     /**
126      * Enabled/disable Neighbor Discover offload functionality. This is called, for example,
127      * whenever 464xlat is being started or stopped.
128      */
setNeighborDiscoveryOffload(boolean enable)129     public void setNeighborDiscoveryOffload(boolean enable) {}
130 
131     /**
132      * Invoked on starting preconnection process.
133      */
onPreconnectionStart(List<Layer2PacketParcelable> packets)134     public void onPreconnectionStart(List<Layer2PacketParcelable> packets) {}
135 }
136