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; 18 19 import android.net.ResolverOptionsParcel; 20 import android.net.ResolverParamsParcel; 21 import android.net.metrics.INetdEventListener; 22 import android.net.resolv.aidl.IDnsResolverUnsolicitedEventListener; 23 24 /** {@hide} */ 25 interface IDnsResolver { 26 /** 27 * Returns true if the service is responding. 28 */ 29 boolean isAlive(); 30 31 /** 32 * Register event listener 33 * DnsResolver supports multiple event listeners, but only one per unique address of the 34 * binder interface. A newer listener won't be registered if DnsResolver has an old one on 35 * the same address of the binder interface. 36 * 37 * @param listener event listener to register. 38 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 39 * unix errno. 40 */ 41 void registerEventListener(INetdEventListener listener); 42 43 // TODO: Delete these from the public interface 44 // Array indices for resolver parameters. 45 const int RESOLVER_PARAMS_SAMPLE_VALIDITY = 0; 46 const int RESOLVER_PARAMS_SUCCESS_THRESHOLD = 1; 47 const int RESOLVER_PARAMS_MIN_SAMPLES = 2; 48 const int RESOLVER_PARAMS_MAX_SAMPLES = 3; 49 const int RESOLVER_PARAMS_BASE_TIMEOUT_MSEC = 4; 50 const int RESOLVER_PARAMS_RETRY_COUNT = 5; 51 const int RESOLVER_PARAMS_COUNT = 6; 52 53 /** 54 * Sets the name servers, search domains and resolver params for the given network. Flushes the 55 * cache as needed (i.e. when the servers or the number of samples to store changes). 56 * 57 * @param resolverParams the resolver parameters to be wrapped into parcel. 58 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 59 * unix errno. 60 */ 61 void setResolverConfiguration(in ResolverParamsParcel resolverParams); 62 63 // Array indices for resolver stats. 64 const int RESOLVER_STATS_SUCCESSES = 0; 65 const int RESOLVER_STATS_ERRORS = 1; 66 const int RESOLVER_STATS_TIMEOUTS = 2; 67 const int RESOLVER_STATS_INTERNAL_ERRORS = 3; 68 const int RESOLVER_STATS_RTT_AVG = 4; 69 const int RESOLVER_STATS_LAST_SAMPLE_TIME = 5; 70 const int RESOLVER_STATS_USABLE = 6; 71 const int RESOLVER_STATS_COUNT = 7; 72 73 /** 74 * Retrieves the name servers, search domains and resolver stats associated with the given 75 * network ID. 76 * 77 * @param netId the network ID of the network for which information should be retrieved. 78 * @param servers the DNS servers that are currently configured for the network. 79 * @param domains the search domains currently configured. 80 * @param tlsServers the DNS-over-TLS servers that are currently configured for the network. 81 * @param params the resolver parameters configured, i.e. the contents of __res_params in order. 82 * @param stats the stats for each server in the order specified by RESOLVER_STATS_XXX 83 * constants, serialized as an int array. The contents of this array are the number of 84 * <ul> 85 * <li> successes, 86 * <li> errors, 87 * <li> timeouts, 88 * <li> internal errors, 89 * <li> the RTT average, 90 * <li> the time of the last recorded sample, 91 * <li> and an integer indicating whether the server is usable (1) or broken (0). 92 * </ul> 93 * in this order. For example, the timeout counter for server N is stored at position 94 * RESOLVER_STATS_COUNT*N + RESOLVER_STATS_TIMEOUTS 95 * @param wait_for_pending_req_timeout_count an internal counter used to count the number of 96 * timeouts while resolver is handling concurrent DNS queries on the same hostname. 97 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 98 * unix errno. 99 * 100 * TODO: Consider replacing stats and params with parcelables. 101 */ 102 void getResolverInfo(int netId, out @utf8InCpp String[] servers, 103 out @utf8InCpp String[] domains, out @utf8InCpp String[] tlsServers, out int[] params, 104 out int[] stats, out int[] wait_for_pending_req_timeout_count); 105 106 /** 107 * Starts NAT64 prefix discovery on the given network. 108 * 109 * @param netId the netId to start prefix discovery on. 110 */ 111 void startPrefix64Discovery(int netId); 112 113 /** 114 * Stops NAT64 prefix discovery on the given network. 115 * 116 * @param netId the netId to stop prefix discovery on. 117 */ 118 void stopPrefix64Discovery(int netId); 119 120 /** 121 * Get NAT64 prefix in format Pref64::/n which is described in RFC6147 section 2. This 122 * interface is used for internal test only. Don't use it for other purposes because doing so 123 * would cause race conditions with the NAT64 prefix notifications. 124 * 125 * @param netId the network ID of the network to get the prefix 126 * @return the NAT64 prefix if the query operation was successful 127 * @throws ServiceSpecificException in case of failure, with an error code indicating the 128 * cause of the the failure. 129 * 130 * TODO: Remove this once the tests have been updated to listen for onNat64PrefixEvent. 131 */ 132 @utf8InCpp String getPrefix64(int netId); 133 134 /** 135 * Create cache for the given network. 136 * 137 * @param netId the network ID of the network to create. 138 * @throws ServiceSpecificException in case of failure, with an error code indicating the 139 * cause of the failure. 140 */ 141 void createNetworkCache(int netId); 142 143 /** 144 * Destroy cache for the given network. 145 * 146 * @param netId the network ID of the network to destroy. 147 */ 148 void destroyNetworkCache(int netId); 149 150 // Refer to enum LogSeverity from system/libbase/include/android-base/logging.h 151 const int DNS_RESOLVER_LOG_VERBOSE = 0; 152 const int DNS_RESOLVER_LOG_DEBUG = 1; 153 const int DNS_RESOLVER_LOG_INFO = 2; 154 const int DNS_RESOLVER_LOG_WARNING = 3; 155 const int DNS_RESOLVER_LOG_ERROR = 4; 156 157 /** 158 * Set DNS resolver log severity 159 * 160 * @param logSeverity print log in "VERBOSE", "DEBUG", "INFO", "WARNING", "ERROR". 161 * 162 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 163 * POSIX errno. 164 */ 165 void setLogSeverity(int logSeverity); 166 167 /** 168 * Flush cache for the given network. 169 * 170 * @param netId the network ID of the network to flush. 171 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 172 * POSIX errno. 173 */ 174 void flushNetworkCache(int netId); 175 176 /** 177 * Values for {@code tcMode} of {@code ResolverOptionsParcel}. It controls the way DNS 178 * resolver handles truncated DNS response from UDP connection. 179 * 180 * TC_MODE_DEFAULT: resolver retries on TCP-only on each name server. 181 * TC_MODE_UDP_TCP: resolver retries on TCP on the same server, falls back to UDP from next. 182 */ 183 const int TC_MODE_DEFAULT = 0; 184 const int TC_MODE_UDP_TCP = 1; 185 186 /** 187 * Values for {@code transportTypes} of {@code ResolverParamsParcel}. These values are 188 * always the same as the TRANSPORT_* API definations of NetworkCapabilities except for 189 * TRANSPORT_UNKNOWN. It controls the transport types for a given network. 190 */ 191 const int TRANSPORT_UNKNOWN = -1; 192 const int TRANSPORT_CELLULAR = 0; 193 const int TRANSPORT_WIFI = 1; 194 const int TRANSPORT_BLUETOOTH = 2; 195 const int TRANSPORT_ETHERNET = 3; 196 const int TRANSPORT_VPN = 4; 197 const int TRANSPORT_WIFI_AWARE = 5; 198 const int TRANSPORT_LOWPAN = 6; 199 const int TRANSPORT_TEST = 7; 200 const int TRANSPORT_USB = 8; 201 202 /** 203 * Sets the NAT64 prefix for the given network. 204 * 205 * Used when the NAT64 prefix has been discovered outside the DNS resolver, e.g., from an RA. 206 * This method may only be called if prefix discovery on the given network has been stopped or 207 * was never started. Any prefix set by this method will be cleared if startPrefix64Discovery or 208 * stopPrefix64Discovery are called. 209 * 210 * Currently only /96 prefixes are supported. If an invalid, IPv4, or non-/96 prefix is passed 211 * in, EINVAL is returned. 212 * An empty string will clear the prefix if one was already set by this method. 213 * 214 * @param netId the netId on which to set the NAT64 prefix. 215 * @param prefix the NAT64 prefix to use. Must be a valid IPv6 prefix or an empty string. 216 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 217 * unix errno. 218 */ 219 void setPrefix64(int netId, @utf8InCpp String prefix); 220 221 /** 222 * Register unsolicited event listener 223 * DnsResolver supports multiple unsolicited event listeners. 224 * 225 * This is a non-public interface between DnsResolver and Connectivity/NetworkStack. 226 * It is subject to change on Mainline updates without notice. DO NOT DEPEND ON IT. 227 * 228 * Only system services(Connectivity/NetworkStack) will register the unsolicited listener. 229 * Besides, there is no unregister method since the system services will be always there to 230 * listen unsolicited events. 231 * 232 * @param listener unsolicited event listener to register 233 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 234 * unix errno. 235 */ 236 void registerUnsolicitedEventListener(IDnsResolverUnsolicitedEventListener listener); 237 238 /** 239 * Sets resolver options for the given network. 240 * 241 * @param netId the netId on which to set the options. 242 * @param optionParams the option parameters to be wrapped into parcel. 243 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 244 * unix errno. 245 */ 246 void setResolverOptions(int netId, in ResolverOptionsParcel optionParams); 247 } 248