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 android.hardware.gnss.visibility_control@1.0;
18
19/**
20 * GNSS location reporting permissions and notification callback interface.
21 */
22interface IGnssVisibilityControlCallback {
23    /**
24     * Protocol stack that is requesting the non-framework location information.
25     */
26    enum NfwProtocolStack : uint8_t {
27        /** Cellular control plane requests */
28        CTRL_PLANE                      = 0,
29        /** All types of SUPL requests */
30        SUPL                            = 1,
31
32        /** All types of requests from IMS */
33        IMS                             = 10,
34        /** All types of requests from SIM */
35        SIM                             = 11,
36
37        /** Requests from other protocol stacks */
38        OTHER_PROTOCOL_STACK            = 100
39    };
40
41    /*
42     * Entity that is requesting/receiving the location information.
43     */
44    enum NfwRequestor : uint8_t {
45        /** Wireless service provider */
46        CARRIER                         = 0,
47
48        /** Device manufacturer */
49        OEM                             = 10,
50        /** Modem chipset vendor */
51        MODEM_CHIPSET_VENDOR            = 11,
52        /** GNSS chipset vendor */
53        GNSS_CHIPSET_VENDOR             = 12,
54        /** Other chipset vendor */
55        OTHER_CHIPSET_VENDOR            = 13,
56
57        /** Automobile client */
58        AUTOMOBILE_CLIENT               = 20,
59
60        /** Other sources */
61        OTHER_REQUESTOR                 = 100
62     };
63
64    /**
65     * GNSS response type for non-framework location requests.
66     */
67    enum NfwResponseType : uint8_t {
68        /** Request rejected because framework has not given permission for this use case */
69        REJECTED                        = 0,
70
71        /** Request accepted but could not provide location because of a failure */
72        ACCEPTED_NO_LOCATION_PROVIDED   = 1,
73
74        /** Request accepted and location provided */
75        ACCEPTED_LOCATION_PROVIDED      = 2,
76     };
77
78    /**
79     * Represents a non-framework location information request/response notification.
80     */
81    struct NfwNotification {
82        /**
83         * Package name of the Android proxy application representing the non-framework
84         * entity that requested location. Set to empty string if unknown.
85         */
86        string proxyAppPackageName;
87
88        /** Protocol stack that initiated the non-framework location request. */
89        NfwProtocolStack protocolStack;
90
91        /**
92         * Name of the protocol stack if protocolStack field is set to OTHER_PROTOCOL_STACK.
93         * Otherwise, set to empty string.
94         *
95         * This field is opaque to the framework and used for logging purposes.
96         */
97        string otherProtocolStackName;
98
99        /** Source initiating/receiving the location information. */
100        NfwRequestor requestor;
101
102        /**
103         * Identity of the endpoint receiving the location information. For example, carrier
104         * name, OEM name, SUPL SLP/E-SLP FQDN, chipset vendor name, etc.
105         *
106         * This field is opaque to the framework and used for logging purposes.
107         */
108        string requestorId;
109
110        /** Indicates whether location information was provided for this request. */
111        NfwResponseType responseType;
112
113        /** Is the device in user initiated emergency session. */
114        bool inEmergencyMode;
115
116        /** Is cached location provided */
117        bool isCachedLocation;
118    };
119
120    /**
121     * Callback to report a non-framework delivered location.
122     *
123     * The GNSS HAL implementation must call this method to notify the framework whenever
124     * a non-framework location request is made to the GNSS HAL.
125     *
126     * Non-framework entities like low power sensor hubs that request location from GNSS and
127     * only pass location information through Android framework controls are exempt from this
128     * power-spending reporting. However, low power sensor hubs or other chipsets which may send
129     * the location information to anywhere other than Android framework (which provides user
130     * visibility and control), must report location information use through this API whenever
131     * location information (or events driven by that location such as "home" location detection)
132     * leaves the domain of that low power chipset.
133     *
134     * To avoid overly spamming the framework, high speed location reporting of the exact same
135     * type may be throttled to report location at a lower rate than the actual report rate, as
136     * long as the location is reported with a latency of no more than the larger of 5 seconds,
137     * or the next the Android processor awake time. For example, if an Automotive client is
138     * getting location information from the GNSS location system at 20Hz, this method may be
139     * called at 1Hz. As another example, if a low power processor is getting location from the
140     * GNSS chipset, and the Android processor is asleep, the notification to the Android HAL may
141     * be delayed until the next wake of the Android processor.
142     *
143     * @param notification Non-framework delivered location request/response description.
144     */
145    nfwNotifyCb(NfwNotification notification);
146
147    /**
148     * Tells if the device is currently in an emergency session.
149     *
150     * Emergency session is defined as the device being actively in a user initiated emergency
151     * call or in post emergency call extension time period.
152     *
153     * If the GNSS HAL implementation cannot determine if the device is in emergency session
154     * mode, it must call this method to confirm that the device is in emergency session before
155     * serving network initiated emergency SUPL and Control Plane location requests.
156     *
157     * @return success True if the framework determines that the device is in emergency session.
158     */
159    isInEmergencySession() generates (bool success);
160};