1 /*
2  * Copyright (C) 2023 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 package com.android.phone.satellite.accesscontrol;
17 
18 import android.annotation.NonNull;
19 
20 import java.io.Closeable;
21 import java.io.File;
22 import java.io.IOException;
23 
24 /**
25  * A class that performs location-based access control for satellite communication synchronously
26  * without exposing implementation details.
27  */
28 public abstract class SatelliteOnDeviceAccessController implements Closeable {
29 
30     /**
31      * Returns the default {@link SatelliteOnDeviceAccessController}. This method will open the
32      * underlying storage and may carry some CPU and I/O expense; callers may want to hold the
33      * {@link SatelliteOnDeviceAccessController} object for multiple lookups to amortize that cost
34      * but at the cost of some memory, or close it immediately after a single use.
35      *
36      * @param file The input file that contains the location-based access restriction information.
37      * @throws IOException in the unlikely event of errors when reading underlying file(s)
38      * @throws IllegalArgumentException if the input file format does not match the format defined
39      * by the device overlay configs.
40      */
create( @onNull File file)41     public static SatelliteOnDeviceAccessController create(
42             @NonNull File file) throws IOException, IllegalArgumentException {
43         return S2RangeSatelliteOnDeviceAccessController.create(file);
44     }
45 
46     /**
47      * Returns a token for a given location. See {@link LocationToken} for details.
48      */
createLocationTokenForLatLng(double latDegrees, double lngDegrees, int s2Level)49     public static LocationToken createLocationTokenForLatLng(double latDegrees, double lngDegrees,
50             int s2Level) {
51         return S2RangeSatelliteOnDeviceAccessController
52                 .createLocationTokenForLatLng(latDegrees, lngDegrees, s2Level);
53     }
54 
55     /**
56      * Returns {@code true} if the satellite communication is allowed at the provided location,
57      * {@code false} otherwise.
58      *
59      * @throws IOException in the unlikely event of errors when reading the underlying file
60      */
isSatCommunicationAllowedAtLocation(LocationToken locationToken)61     public abstract boolean isSatCommunicationAllowedAtLocation(LocationToken locationToken)
62             throws IOException;
63 
64     /**
65      * Returns the S2 level of the file.
66      */
getS2Level()67     public abstract int getS2Level();
68 
69     /**
70      * A class that represents an area with the same value. Two locations with tokens that
71      * {@link #equals(Object) equal each other} will definitely return the same value.
72      *
73      * <p>Depending on the implementation, it may be cheaper to obtain a {@link LocationToken} than
74      * doing a full lookup.
75      */
76     public abstract static class LocationToken {
77         @Override
equals(Object other)78         public abstract boolean equals(Object other);
79 
80         @Override
hashCode()81         public abstract int hashCode();
82 
83         /** This will print out the location information */
toPiiString()84         public abstract String toPiiString();
85     }
86 }
87