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.ResolverParamsParcel; 20 import android.net.metrics.INetdEventListener; 21 22 /** {@hide} */ 23 interface IDnsResolver { 24 /** 25 * Returns true if the service is responding. 26 */ isAlive()27 boolean isAlive(); 28 29 /** 30 * Register event listener 31 * DnsResolver supports multiple event listeners, but only one per unique address of the 32 * binder interface. A newer listener won't be registered if DnsResolver has an old one on 33 * the same address of the binder interface. 34 * 35 * @param listener event listener to register. 36 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 37 * unix errno. 38 */ registerEventListener(INetdEventListener listener)39 void registerEventListener(INetdEventListener listener); 40 41 // TODO: Delete these from the public interface 42 // Array indices for resolver parameters. 43 const int RESOLVER_PARAMS_SAMPLE_VALIDITY = 0; 44 const int RESOLVER_PARAMS_SUCCESS_THRESHOLD = 1; 45 const int RESOLVER_PARAMS_MIN_SAMPLES = 2; 46 const int RESOLVER_PARAMS_MAX_SAMPLES = 3; 47 const int RESOLVER_PARAMS_BASE_TIMEOUT_MSEC = 4; 48 const int RESOLVER_PARAMS_RETRY_COUNT = 5; 49 const int RESOLVER_PARAMS_COUNT = 6; 50 51 /** 52 * Sets the name servers, search domains and resolver params for the given network. Flushes the 53 * cache as needed (i.e. when the servers or the number of samples to store changes). 54 * 55 * @param resolverParams the resolver parameters to be wrapped into parcel. 56 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 57 * unix errno. 58 */ setResolverConfiguration(in ResolverParamsParcel resolverParams)59 void setResolverConfiguration(in ResolverParamsParcel resolverParams); 60 61 // Array indices for resolver stats. 62 const int RESOLVER_STATS_SUCCESSES = 0; 63 const int RESOLVER_STATS_ERRORS = 1; 64 const int RESOLVER_STATS_TIMEOUTS = 2; 65 const int RESOLVER_STATS_INTERNAL_ERRORS = 3; 66 const int RESOLVER_STATS_RTT_AVG = 4; 67 const int RESOLVER_STATS_LAST_SAMPLE_TIME = 5; 68 const int RESOLVER_STATS_USABLE = 6; 69 const int RESOLVER_STATS_COUNT = 7; 70 71 /** 72 * Retrieves the name servers, search domains and resolver stats associated with the given 73 * network ID. 74 * 75 * @param netId the network ID of the network for which information should be retrieved. 76 * @param servers the DNS servers that are currently configured for the network. 77 * @param domains the search domains currently configured. 78 * @param tlsServers the DNS-over-TLS servers that are currently configured for the network. 79 * @param params the resolver parameters configured, i.e. the contents of __res_params in order. 80 * @param stats the stats for each server in the order specified by RESOLVER_STATS_XXX 81 * constants, serialized as an int array. The contents of this array are the number of 82 * <ul> 83 * <li> successes, 84 * <li> errors, 85 * <li> timeouts, 86 * <li> internal errors, 87 * <li> the RTT average, 88 * <li> the time of the last recorded sample, 89 * <li> and an integer indicating whether the server is usable (1) or broken (0). 90 * </ul> 91 * in this order. For example, the timeout counter for server N is stored at position 92 * RESOLVER_STATS_COUNT*N + RESOLVER_STATS_TIMEOUTS 93 * @param wait_for_pending_req_timeout_count an internal counter used to count the number of 94 * timeouts while resolver is handling concurrent DNS queries on the same hostname. 95 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 96 * unix errno. 97 * 98 * TODO: Consider replacing stats and params with parcelables. 99 */ getResolverInfo(int netId, out @utf8InCpp String[] servers, out @utf8InCpp String[] domains, out @utf8InCpp String[] tlsServers, out int[] params, out int[] stats, out int[] wait_for_pending_req_timeout_count)100 void getResolverInfo(int netId, out @utf8InCpp String[] servers, 101 out @utf8InCpp String[] domains, out @utf8InCpp String[] tlsServers, out int[] params, 102 out int[] stats, out int[] wait_for_pending_req_timeout_count); 103 104 /** 105 * Starts NAT64 prefix discovery on the given network. 106 * 107 * @param netId the netId to start prefix discovery on. 108 */ startPrefix64Discovery(int netId)109 void startPrefix64Discovery(int netId); 110 111 /** 112 * Stops NAT64 prefix discovery on the given network. 113 * 114 * @param netId the netId to stop prefix discovery on. 115 */ stopPrefix64Discovery(int netId)116 void stopPrefix64Discovery(int netId); 117 118 /** 119 * Get NAT64 prefix in format Pref64::/n which is described in RFC6147 section 2. This 120 * interface is used for internal test only. Don't use it for other purposes because doing so 121 * would cause race conditions with the NAT64 prefix notifications. 122 * 123 * @param netId the network ID of the network to get the prefix 124 * @return the NAT64 prefix if the query operation was successful 125 * @throws ServiceSpecificException in case of failure, with an error code indicating the 126 * cause of the the failure. 127 * 128 * TODO: Remove this once the tests have been updated to listen for onNat64PrefixEvent. 129 */ getPrefix64(int netId)130 @utf8InCpp String getPrefix64(int netId); 131 132 /** 133 * Create cache for the given network. 134 * 135 * @param netId the network ID of the network to create. 136 * @throws ServiceSpecificException in case of failure, with an error code indicating the 137 * cause of the failure. 138 */ createNetworkCache(int netId)139 void createNetworkCache(int netId); 140 141 /** 142 * Destroy cache for the given network. 143 * 144 * @param netId the network ID of the network to destroy. 145 */ destroyNetworkCache(int netId)146 void destroyNetworkCache(int netId); 147 148 // Refer to enum LogSeverity from system/core/base/include/android-base/logging.h 149 const int DNS_RESOLVER_LOG_VERBOSE = 0; 150 const int DNS_RESOLVER_LOG_DEBUG = 1; 151 const int DNS_RESOLVER_LOG_INFO = 2; 152 const int DNS_RESOLVER_LOG_WARNING = 3; 153 const int DNS_RESOLVER_LOG_ERROR = 4; 154 155 /** 156 * Set DNS resolver log severity 157 * 158 * @param logSeverity print log in "VERBOSE", "DEBUG", "INFO", "WARNING", "ERROR". 159 * 160 * @throws ServiceSpecificException in case of failure, with an error code corresponding to the 161 * POSIX errno. 162 */ setLogSeverity(int logSeverity)163 void setLogSeverity(int logSeverity); 164 } 165