1 /*
2  * Copyright (C) 2012 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 com.android.location.provider;
18 
19 import android.annotation.NonNull;
20 import android.location.LocationRequest;
21 import android.location.provider.ProviderRequest;
22 import android.os.Build;
23 import android.os.WorkSource;
24 
25 import androidx.annotation.RequiresApi;
26 
27 import java.util.Collections;
28 import java.util.List;
29 
30 /**
31  * Represents a provider request for unbundled applications.
32  *
33  * <p>IMPORTANT: This class is effectively a public API for unbundled applications, and must remain
34  * API stable.
35  */
36 public final class ProviderRequestUnbundled {
37 
38     /**
39      * Represents a disabled request.
40      */
41     public static final long INTERVAL_DISABLED = ProviderRequest.INTERVAL_DISABLED;
42 
43     private final ProviderRequest mRequest;
44 
45     /** @hide */
ProviderRequestUnbundled(ProviderRequest request)46     public ProviderRequestUnbundled(ProviderRequest request) {
47         mRequest = request;
48     }
49 
50     /**
51      * True if this is an active request with a valid location reporting interval, false if this
52      * request is inactive and does not require any locations to be reported.
53      */
getReportLocation()54     public boolean getReportLocation() {
55         return mRequest.isActive();
56     }
57 
58     /**
59      * The interval at which a provider should report location. Will return
60      * {@link #INTERVAL_DISABLED} for an inactive request.
61      */
getInterval()62     public long getInterval() {
63         return mRequest.getIntervalMillis();
64     }
65 
66     /**
67      * The quality hint for this location request. The quality hint informs the provider how it
68      * should attempt to manage any accuracy vs power tradeoffs while attempting to satisfy this
69      * provider request.
70      */
71     @RequiresApi(Build.VERSION_CODES.S)
getQuality()72     public @LocationRequest.Quality int getQuality() {
73         return mRequest.getQuality();
74     }
75 
76     /**
77      * The maximum time any location update may be delayed, and thus grouped with following updates
78      * to enable location batching. If the maximum update delay is equal to or greater than
79      * twice the interval, then the provider may provide batched results if possible. The maximum
80      * batch size a provider is allowed to return is the maximum update delay divided by the
81      * interval.
82      */
83     @RequiresApi(Build.VERSION_CODES.S)
getMaxUpdateDelayMillis()84     public long getMaxUpdateDelayMillis() {
85         return mRequest.getMaxUpdateDelayMillis();
86     }
87 
88     /**
89      * Whether any applicable hardware low power modes should be used to satisfy this request.
90      */
91     @RequiresApi(Build.VERSION_CODES.S)
isLowPower()92     public boolean isLowPower() {
93         return mRequest.isLowPower();
94     }
95 
96     /**
97      * Whether the provider should ignore all location settings, user consents, power restrictions
98      * or any other restricting factors and always satisfy this request to the best of their
99      * ability. This should only be used in case of a user initiated emergency.
100      */
101     @RequiresApi(Build.VERSION_CODES.Q)
isLocationSettingsIgnored()102     public boolean isLocationSettingsIgnored() {
103         return mRequest.isLocationSettingsIgnored();
104     }
105 
106     /**
107      * The full list of location requests contributing to this provider request.
108      *
109      * @deprecated Do not use.
110      */
111     @Deprecated
getLocationRequests()112     public @NonNull List<LocationRequestUnbundled> getLocationRequests() {
113         if (!mRequest.isActive()) {
114             return Collections.emptyList();
115         }
116 
117         return Collections.singletonList(new LocationRequestUnbundled(
118                 new LocationRequest.Builder(mRequest.getIntervalMillis())
119                         .setQuality(mRequest.getQuality())
120                         .setLowPower(mRequest.isLowPower())
121                         .setLocationSettingsIgnored(mRequest.isLocationSettingsIgnored())
122                         .setWorkSource(mRequest.getWorkSource())
123                         .build()));
124     }
125 
126     /**
127      * The power blame for this provider request.
128      */
129     @RequiresApi(Build.VERSION_CODES.S)
getWorkSource()130     public @NonNull WorkSource getWorkSource() {
131         return mRequest.getWorkSource();
132     }
133 
134     @Override
toString()135     public String toString() {
136         return mRequest.toString();
137     }
138 }
139