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
17package [email protected];
18
19import @1.0::IGnssCallback;
20import @1.1::IGnssCallback;
21import GnssLocation;
22import GnssConstellationType;
23
24/**
25 * This interface is required for the HAL to communicate certain information
26 * like status and location info back to the platform, the platform implements
27 * the interfaces and passes a handle to the HAL.
28 */
29interface IGnssCallback extends @1.1::IGnssCallback {
30
31    /** Flags for the gnssSetCapabilities callback. */
32    @export(name="", value_prefix="GPS_CAPABILITY_")
33    enum Capabilities : @1.0::IGnssCallback.Capabilities {
34        /** GNSS supports low power mode */
35        LOW_POWER_MODE                          = 1 << 8,
36        /** GNSS supports blacklisting satellites */
37        SATELLITE_BLACKLIST                     = 1 << 9,
38        /** GNSS supports measurement corrections */
39        MEASUREMENT_CORRECTIONS                 = 1 << 10
40    };
41
42    /**
43     * Callback to inform framework of the GNSS HAL implementation's capabilities.
44     *
45     * @param capabilities Capability parameter is a bit field of the Capabilities enum.
46     */
47    gnssSetCapabilitiesCb_2_0(bitfield<Capabilities> capabilities);
48
49   /**
50     * Called when a GNSS location is available.
51     *
52     * @param location Location information from HAL.
53     */
54    gnssLocationCb_2_0(GnssLocation location);
55
56    /**
57     * Callback for requesting Location.
58     *
59     * HAL implementation must call this when it wants the framework to provide locations to assist
60     * with GNSS HAL operation, for example, to assist with time to first fix, error recovery, or to
61     * supplement GNSS location for other clients of the GNSS HAL.
62     *
63     * If a request is made with independentFromGnss set to true, the framework must avoid
64     * providing locations derived from GNSS locations (such as "fused" location), to help improve
65     * information independence for situations such as error recovery.
66     *
67     * In response to this method call, GNSS HAL can expect zero, one, or more calls to
68     * IGnss::injectLocation or IGnss::injectBestLocation, dependent on availability of location
69     * from other sources, which may happen at some arbitrary delay. Generally speaking, HAL
70     * implementations must be able to handle calls to IGnss::injectLocation or
71     * IGnss::injectBestLocation at any time.
72     *
73     * @param independentFromGnss True if requesting a location that is independent from GNSS.
74     * @param isUserEmergency True if the location request is for delivery of this location to an
75     *        emergency services endpoint, during a user-initiated emergency session (e.g.
76     *        during-call to E911, or up to 5 minutes after end-of-call or text to E911).
77     */
78    gnssRequestLocationCb_2_0(bool independentFromGnss, bool isUserEmergency);
79
80    /** Extends a GnssSvInfo, replacing the GnssConstellationType. */
81    struct GnssSvInfo {
82        /**
83         * GNSS satellite information for a single satellite and frequency.
84         *
85         * In this version of the HAL, the field 'constellation' in the v1_0 struct is deprecated,
86         * and is no longer used by the framework. The constellation type is instead reported in
87         * @2.0::IGnssCallback.GnssSvInfo.constellation.
88         */
89        @1.0::IGnssCallback.GnssSvInfo v1_0;
90
91        /** Defines the constellation of the given SV. */
92        GnssConstellationType constellation;
93    };
94
95    /**
96     * Callback for the HAL to pass a vector of GnssSvInfo back to the client.
97     *
98     * @param svInfo SV status information from HAL.
99     */
100    gnssSvStatusCb_2_0(vec<GnssSvInfo> svInfoList);
101};
102