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.IOnSameL3NetworkResponseListener; 25 import android.net.ipmemorystore.IOnStatusAndCountListener; 26 import android.net.ipmemorystore.IOnStatusListener; 27 28 /** {@hide} */ 29 oneway interface IIpMemoryStore { 30 /** 31 * Store network attributes for a given L2 key. 32 * If L2Key is null, choose automatically from the attributes ; passing null is equivalent to 33 * calling findL2Key with the attributes and storing in the returned value. 34 * 35 * @param l2Key The L2 key for the L2 network. Clients that don't know or care about the L2 36 * key and only care about grouping can pass a unique ID here like the ones 37 * generated by {@code java.util.UUID.randomUUID()}, but keep in mind the low 38 * relevance of such a network will lead to it being evicted soon if it's not 39 * refreshed. Use findL2Key to try and find a similar L2Key to these attributes. 40 * @param attributes The attributes for this network. 41 * @param listener A listener that will be invoked to inform of the completion of this call, 42 * or null if the client is not interested in learning about success/failure. 43 * @return (through the listener) A status to indicate success or failure. 44 */ storeNetworkAttributes(String l2Key, in NetworkAttributesParcelable attributes, IOnStatusListener listener)45 void storeNetworkAttributes(String l2Key, in NetworkAttributesParcelable attributes, 46 IOnStatusListener listener); 47 48 /** 49 * Store a binary blob associated with an L2 key and a name. 50 * 51 * @param l2Key The L2 key for this network. 52 * @param clientId The ID of the client. 53 * @param name The name of this data. 54 * @param data The data to store. 55 * @param listener A listener to inform of the completion of this call, or null if the client 56 * is not interested in learning about success/failure. 57 * @return (through the listener) A status to indicate success or failure. 58 */ storeBlob(String l2Key, String clientId, String name, in Blob data, IOnStatusListener listener)59 void storeBlob(String l2Key, String clientId, String name, in Blob data, 60 IOnStatusListener listener); 61 62 /** 63 * Returns the best L2 key associated with the attributes. 64 * 65 * This will find a record that would be in the same group as the passed attributes. This is 66 * useful to choose the key for storing a sample or private data when the L2 key is not known. 67 * If multiple records are group-close to these attributes, the closest match is returned. 68 * If multiple records have the same closeness, the one with the smaller (unicode codepoint 69 * order) L2 key is returned. 70 * If no record matches these attributes, null is returned. 71 * 72 * @param attributes The attributes of the network to find. 73 * @param listener The listener that will be invoked to return the answer. 74 * @return (through the listener) The L2 key if one matched, or null. 75 */ findL2Key(in NetworkAttributesParcelable attributes, IOnL2KeyResponseListener listener)76 void findL2Key(in NetworkAttributesParcelable attributes, IOnL2KeyResponseListener listener); 77 78 /** 79 * Returns whether, to the best of the store's ability to tell, the two specified L2 keys point 80 * to the same L3 network. Group-closeness is used to determine this. 81 * 82 * @param l2Key1 The key for the first network. 83 * @param l2Key2 The key for the second network. 84 * @param listener The listener that will be invoked to return the answer. 85 * @return (through the listener) A SameL3NetworkResponse containing the answer and confidence. 86 */ isSameNetwork(String l2Key1, String l2Key2, IOnSameL3NetworkResponseListener listener)87 void isSameNetwork(String l2Key1, String l2Key2, IOnSameL3NetworkResponseListener listener); 88 89 /** 90 * Retrieve the network attributes for a key. 91 * If no record is present for this key, this will return null attributes. 92 * 93 * @param l2Key The key of the network to query. 94 * @param listener The listener that will be invoked to return the answer. 95 * @return (through the listener) The network attributes and the L2 key associated with 96 * the query. 97 */ retrieveNetworkAttributes(String l2Key, IOnNetworkAttributesRetrievedListener listener)98 void retrieveNetworkAttributes(String l2Key, IOnNetworkAttributesRetrievedListener listener); 99 100 /** 101 * Retrieve previously stored private data. 102 * If no data was stored for this L2 key and name this will return null. 103 * 104 * @param l2Key The L2 key. 105 * @param clientId The id of the client that stored this data. 106 * @param name The name of the data. 107 * @param listener The listener that will be invoked to return the answer. 108 * @return (through the listener) The private data (or null), with the L2 key 109 * and the name of the data associated with the query. 110 */ retrieveBlob(String l2Key, String clientId, String name, IOnBlobRetrievedListener listener)111 void retrieveBlob(String l2Key, String clientId, String name, 112 IOnBlobRetrievedListener listener); 113 114 /** 115 * Delete all data because a factory reset operation is in progress. 116 */ factoryReset()117 void factoryReset(); 118 119 /** 120 * Delete a single entry. 121 * 122 * @param l2key The L2 key of the entry to delete. 123 * @param needWipe Whether the data must be wiped from disk immediately. This makes the 124 * operation vastly more expensive as the database files will have to be copied 125 * and created again from the old files (see sqlite3 VACUUM operation for 126 * details) and makes no functional difference; only pass true if security or 127 * privacy demands this data must be removed from disk immediately. 128 * Note that this can fail for storage reasons. The passed listener will then 129 * receive an appropriate error status with the number of deleted rows. 130 * @param listener A listener that will be invoked to inform of the completion of this call, 131 * or null if the client is not interested in learning about success/failure. 132 * @return (through the listener) A status to indicate success and the number of deleted records 133 */ delete(String l2Key, boolean needWipe, IOnStatusAndCountListener listener)134 void delete(String l2Key, boolean needWipe, IOnStatusAndCountListener listener); 135 136 /** 137 * Delete all entries in a cluster. 138 * 139 * This method will delete all entries in the memory store that have the cluster attribute 140 * passed as an argument. 141 * 142 * @param cluster The cluster to delete. 143 * @param needWipe Whether the data must be wiped from disk immediately. This makes the 144 * operation vastly more expensive as the database files will have to be copied 145 * and created again from the old files (see sqlite3 VACUUM operation for 146 * details) and makes no functional difference; only pass true if security or 147 * privacy demands this data must be removed from disk immediately. 148 * Note that this can fail for storage reasons. The passed listener will then 149 * receive an appropriate error status with the number of deleted rows. 150 * @param listener A listener that will be invoked to inform of the completion of this call, 151 * or null if the client is not interested in learning about success/failure. 152 * @return (through the listener) A status to indicate success and the number of deleted records 153 */ deleteCluster(String cluster, boolean needWipe, IOnStatusAndCountListener listener)154 void deleteCluster(String cluster, boolean needWipe, IOnStatusAndCountListener listener); 155 } 156