1/*
2 * Copyright (C) 2017 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
17package android.hardware.gnss@1.1;
18
19import @1.0::IGnss;
20import @1.0::GnssLocation;
21
22import IGnssCallback;
23import IGnssConfiguration;
24import IGnssMeasurement;
25
26/** Represents the standard GNSS (Global Navigation Satellite System) interface. */
27interface IGnss extends @1.0::IGnss {
28    /**
29     * Opens the interface and provides the callback routines to the implementation of this
30     * interface.
31     *
32     * The framework calls this method to instruct the GPS engine to prepare for serving requests
33     * from the framework. The GNSS HAL implementation must respond to all GNSS requests from the
34     * framework upon successful return from this method until cleanup() method is called to
35     * close this interface.
36     *
37     * @param callback Callback interface for IGnss.
38     *
39     * @return success Returns true on success.
40     */
41    setCallback_1_1(IGnssCallback callback) generates (bool success);
42
43    /**
44     * Sets the GnssPositionMode parameter, its associated recurrence value,
45     * the time between fixes, requested fix accuracy, time to first fix.
46     *
47     * @param mode Parameter must be one of MS_BASED or STANDALONE. It is allowed by the platform
48     *     (and it is recommended) to fallback to MS_BASED if MS_ASSISTED is passed in, and MS_BASED
49     *     is supported.
50     * @param recurrence GNSS position recurrence value, either periodic or single.
51     * @param minIntervalMs Represents the time between fixes in milliseconds.
52     * @param preferredAccuracyMeters Represents the requested fix accuracy in meters.
53     * @param preferredTimeMs Represents the requested time to first fix in milliseconds.
54     * @param lowPowerMode When true, and IGnss.hal is the only client to the GNSS hardware, the
55     *     GNSS hardware must make strong tradeoffs to substantially restrict power use.
56     *     Specifically, in the case of a several second long minIntervalMs, the GNSS hardware must
57     *     not, on average, run power hungry operations like RF and signal searches for more than
58     *     one second per interval, and must make exactly one call to gnssSvStatusCb(), and either
59     *     zero or one call to GnssLocationCb() at each interval. When false, HAL must operate in
60     *     the nominal mode (similar to V1.0 where this flag wasn't present) and is expected to make
61     *     power and performance tradoffs such as duty-cycling when signal conditions are good and
62     *     more active searches to reacquire GNSS signals when no signals are present.
63     *     When there are additional clients using the GNSS hardware other than IGnss.hal, the GNSS
64     *     hardware may operate in a higher power mode, on behalf of those clients.
65     *
66     * @return success Returns true if successful.
67     */
68    setPositionMode_1_1(GnssPositionMode mode,
69                        GnssPositionRecurrence recurrence,
70                        uint32_t minIntervalMs,
71                        uint32_t preferredAccuracyMeters,
72                        uint32_t preferredTimeMs,
73                        bool lowPowerMode)
74             generates (bool success);
75
76   /**
77    * This method returns the IGnssConfiguration interface.
78    *
79    * @return gnssConfigurationIface Handle to the IGnssConfiguration interface.
80    */
81    getExtensionGnssConfiguration_1_1() generates (IGnssConfiguration gnssConfigurationIface);
82
83   /**
84    * This method returns the IGnssMeasurement interface.
85    *
86    * @return gnssMeasurementIface Handle to the IGnssMeasurement interface.
87    */
88    getExtensionGnssMeasurement_1_1() generates (IGnssMeasurement gnssMeasurementIface);
89
90    /**
91     * Injects current location from the best available location provider.
92     *
93     * Unlike injectLocation, this method may inject a recent GNSS location from the HAL
94     * implementation, if that is the best available location known to the framework.
95     *
96     * @param location Location information from the best available location provider.
97     *
98     * @return success Returns true if successful.
99     */
100    injectBestLocation(GnssLocation location) generates (bool success);
101};