1 /* 2 * Copyright (C) 2018 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.ipmemorystore.Blob; 20 import android.net.ipmemorystore.NetworkAttributesParcelable; 21 import android.net.ipmemorystore.IOnBlobRetrievedListener; 22 import android.net.ipmemorystore.IOnL2KeyResponseListener; 23 import android.net.ipmemorystore.IOnNetworkAttributesRetrievedListener; 24 import android.net.ipmemorystore.IOnNetworkEventCountRetrievedListener; 25 import android.net.ipmemorystore.IOnSameL3NetworkResponseListener; 26 import android.net.ipmemorystore.IOnStatusAndCountListener; 27 import android.net.ipmemorystore.IOnStatusListener; 28 29 /** {@hide} */ 30 oneway interface IIpMemoryStore { 31 /** 32 * Store network attributes for a given L2 key. 33 * If L2Key is null, choose automatically from the attributes ; passing null is equivalent to 34 * calling findL2Key with the attributes and storing in the returned value. 35 * 36 * @param l2Key The L2 key for the L2 network. Clients that don't know or care about the L2 37 * key and only care about grouping can pass a unique ID here like the ones 38 * generated by {@code java.util.UUID.randomUUID()}, but keep in mind the low 39 * relevance of such a network will lead to it being evicted soon if it's not 40 * refreshed. Use findL2Key to try and find a similar L2Key to these attributes. 41 * @param attributes The attributes for this network. 42 * @param listener A listener that will be invoked to inform of the completion of this call, 43 * or null if the client is not interested in learning about success/failure. 44 * @return (through the listener) A status to indicate success or failure. 45 */ storeNetworkAttributes(String l2Key, in NetworkAttributesParcelable attributes, IOnStatusListener listener)46 void storeNetworkAttributes(String l2Key, in NetworkAttributesParcelable attributes, 47 IOnStatusListener listener); 48 49 /** 50 * Store a binary blob associated with an L2 key and a name. 51 * 52 * @param l2Key The L2 key for this network. 53 * @param clientId The ID of the client. 54 * @param name The name of this data. 55 * @param data The data to store. 56 * @param listener A listener to inform of the completion of this call, or null if the client 57 * is not interested in learning about success/failure. 58 * @return (through the listener) A status to indicate success or failure. 59 */ storeBlob(String l2Key, String clientId, String name, in Blob data, IOnStatusListener listener)60 void storeBlob(String l2Key, String clientId, String name, in Blob data, 61 IOnStatusListener listener); 62 63 /** 64 * Returns the best L2 key associated with the attributes. 65 * 66 * This will find a record that would be in the same group as the passed attributes. This is 67 * useful to choose the key for storing a sample or private data when the L2 key is not known. 68 * If multiple records are group-close to these attributes, the closest match is returned. 69 * If multiple records have the same closeness, the one with the smaller (unicode codepoint 70 * order) L2 key is returned. 71 * If no record matches these attributes, null is returned. 72 * 73 * @param attributes The attributes of the network to find. 74 * @param listener The listener that will be invoked to return the answer. 75 * @return (through the listener) The L2 key if one matched, or null. 76 */ findL2Key(in NetworkAttributesParcelable attributes, IOnL2KeyResponseListener listener)77 void findL2Key(in NetworkAttributesParcelable attributes, IOnL2KeyResponseListener listener); 78 79 /** 80 * Returns whether, to the best of the store's ability to tell, the two specified L2 keys point 81 * to the same L3 network. Group-closeness is used to determine this. 82 * 83 * @param l2Key1 The key for the first network. 84 * @param l2Key2 The key for the second network. 85 * @param listener The listener that will be invoked to return the answer. 86 * @return (through the listener) A SameL3NetworkResponse containing the answer and confidence. 87 */ isSameNetwork(String l2Key1, String l2Key2, IOnSameL3NetworkResponseListener listener)88 void isSameNetwork(String l2Key1, String l2Key2, IOnSameL3NetworkResponseListener listener); 89 90 /** 91 * Retrieve the network attributes for a key. 92 * If no record is present for this key, this will return null attributes. 93 * 94 * @param l2Key The key of the network to query. 95 * @param listener The listener that will be invoked to return the answer. 96 * @return (through the listener) The network attributes and the L2 key associated with 97 * the query. 98 */ retrieveNetworkAttributes(String l2Key, IOnNetworkAttributesRetrievedListener listener)99 void retrieveNetworkAttributes(String l2Key, IOnNetworkAttributesRetrievedListener listener); 100 101 /** 102 * Retrieve previously stored private data. 103 * If no data was stored for this L2 key and name this will return null. 104 * 105 * @param l2Key The L2 key. 106 * @param clientId The id of the client that stored this data. 107 * @param name The name of the data. 108 * @param listener The listener that will be invoked to return the answer. 109 * @return (through the listener) The private data (or null), with the L2 key 110 * and the name of the data associated with the query. 111 */ retrieveBlob(String l2Key, String clientId, String name, IOnBlobRetrievedListener listener)112 void retrieveBlob(String l2Key, String clientId, String name, 113 IOnBlobRetrievedListener listener); 114 115 /** 116 * Delete all data because a factory reset operation is in progress. 117 */ factoryReset()118 void factoryReset(); 119 120 /** 121 * Delete a single entry. 122 * 123 * @param l2key The L2 key of the entry to delete. 124 * @param needWipe Whether the data must be wiped from disk immediately. This makes the 125 * operation vastly more expensive as the database files will have to be copied 126 * and created again from the old files (see sqlite3 VACUUM operation for 127 * details) and makes no functional difference; only pass true if security or 128 * privacy demands this data must be removed from disk immediately. 129 * Note that this can fail for storage reasons. The passed listener will then 130 * receive an appropriate error status with the number of deleted rows. 131 * @param listener A listener that will be invoked to inform of the completion of this call, 132 * or null if the client is not interested in learning about success/failure. 133 * @return (through the listener) A status to indicate success and the number of deleted records 134 */ delete(String l2Key, boolean needWipe, IOnStatusAndCountListener listener)135 void delete(String l2Key, boolean needWipe, IOnStatusAndCountListener listener); 136 137 /** 138 * Delete all entries in a cluster. 139 * 140 * This method will delete all entries in the memory store that have the cluster attribute 141 * passed as an argument. 142 * 143 * @param cluster The cluster to delete. 144 * @param needWipe Whether the data must be wiped from disk immediately. This makes the 145 * operation vastly more expensive as the database files will have to be copied 146 * and created again from the old files (see sqlite3 VACUUM operation for 147 * details) and makes no functional difference; only pass true if security or 148 * privacy demands this data must be removed from disk immediately. 149 * Note that this can fail for storage reasons. The passed listener will then 150 * receive an appropriate error status with the number of deleted rows. 151 * @param listener A listener that will be invoked to inform of the completion of this call, 152 * or null if the client is not interested in learning about success/failure. 153 * @return (through the listener) A status to indicate success and the number of deleted records 154 */ deleteCluster(String cluster, boolean needWipe, IOnStatusAndCountListener listener)155 void deleteCluster(String cluster, boolean needWipe, IOnStatusAndCountListener listener); 156 157 /** 158 * The network event types related to Neighbor Unreachability Detection(NUD) probe failure 159 * including probe fails due to L2 roam, low Wi-Fi RSSI checks, periodic kernel organic checks, 160 * or a neighbor's MAC address changing during a probe. 161 */ 162 const int NETWORK_EVENT_NUD_FAILURE_ROAM = 0; 163 const int NETWORK_EVENT_NUD_FAILURE_CONFIRM = 1; 164 const int NETWORK_EVENT_NUD_FAILURE_ORGANIC = 2; 165 const int NETWORK_EVENT_NUD_FAILURE_MAC_ADDRESS_CHANGED = 3; 166 167 /** 168 * Store a specific network event to database for a given cluster. 169 * 170 * @param cluster The cluster representing a notion of network group (e.g., BSSIDs with the 171 * same SSID). 172 * @param timestamp The timestamp {@link System.currentTimeMillis} when a specific network 173 * event occurred. 174 * @param expiry The timestamp {@link System.currentTimeMillis} when a specific network 175 * event stored in the database expires, e.g. it might be one week from now. 176 * @param eventType One of the NETWORK_EVENT constants above. 177 * @param listener A listener that will be invoked to inform of the completion of this call. 178 * @return (through the listener) A status to indicate success or failure. 179 */ storeNetworkEvent(String cluster, long timestamp, long expiry, int eventType, IOnStatusListener listener)180 void storeNetworkEvent(String cluster, long timestamp, long expiry, int eventType, 181 IOnStatusListener listener); 182 183 /** 184 * Retrieve the specific network event counts for a given cluster and event type since one or 185 * more timestamps in the past. 186 * 187 * @param cluster The cluster to query. 188 * @param sinceTimes An array of timestamps in the past. The query will return an array of 189 * equal size. Each element in the array will contain the number of network 190 * events between the corresponding timestamp and the current time, e.g. query 191 * since the last week and/or the last day. 192 * @param eventTypes An array of network event types to query, which can be one or more of the 193 * above NETWORK_EVENT constants. 194 * @param listener The listener that will be invoked to return the answer. 195 * @return (through the listener) The event counts associated with the query, or an empty array 196 * if the query failed. 197 */ retrieveNetworkEventCount(String cluster, in long[] sinceTimes, in int[] eventTypes, IOnNetworkEventCountRetrievedListener listener)198 void retrieveNetworkEventCount(String cluster, in long[] sinceTimes, in int[] eventTypes, 199 IOnNetworkEventCountRetrievedListener listener); 200 } 201