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
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         * For user-initiated emergency use cases, this field must be set to empty string
87         * and the inEmergencyMode field must be set to true.
88         */
89        string proxyAppPackageName;
90
91        /** Protocol stack that initiated the non-framework location request. */
92        NfwProtocolStack protocolStack;
93
94        /**
95         * Name of the protocol stack if protocolStack field is set to OTHER_PROTOCOL_STACK.
96         * Otherwise, set to empty string.
97         *
98         * This field is opaque to the framework and used for logging purposes.
99         */
100        string otherProtocolStackName;
101
102        /** Source initiating/receiving the location information. */
103        NfwRequestor requestor;
104
105        /**
106         * Identity of the endpoint receiving the location information. For example, carrier
107         * name, OEM name, SUPL SLP/E-SLP FQDN, chipset vendor name, etc.
108         *
109         * This field is opaque to the framework and used for logging purposes.
110         */
111        string requestorId;
112
113        /** Indicates whether location information was provided for this request. */
114        NfwResponseType responseType;
115
116        /** Is the device in user initiated emergency session. */
117        bool inEmergencyMode;
118
119        /** Is cached location provided */
120        bool isCachedLocation;
121    };
122
123    /**
124     * Callback to report a non-framework delivered location.
125     *
126     * The GNSS HAL implementation must call this method to notify the framework whenever
127     * a non-framework location request is made to the GNSS HAL.
128     *
129     * Non-framework entities like low power sensor hubs that request location from GNSS and
130     * only pass location information through Android framework controls are exempt from this
131     * power-spending reporting. However, low power sensor hubs or other chipsets which may send
132     * the location information to anywhere other than Android framework (which provides user
133     * visibility and control), must report location information use through this API whenever
134     * location information (or events driven by that location such as "home" location detection)
135     * leaves the domain of that low power chipset.
136     *
137     * To avoid overly spamming the framework, high speed location reporting of the exact same
138     * type may be throttled to report location at a lower rate than the actual report rate, as
139     * long as the location is reported with a latency of no more than the larger of 5 seconds,
140     * or the next the Android processor awake time. For example, if an Automotive client is
141     * getting location information from the GNSS location system at 20Hz, this method may be
142     * called at 1Hz. As another example, if a low power processor is getting location from the
143     * GNSS chipset, and the Android processor is asleep, the notification to the Android HAL may
144     * be delayed until the next wake of the Android processor.
145     *
146     * @param notification Non-framework delivered location request/response description.
147     */
148    nfwNotifyCb(NfwNotification notification);
149
150    /**
151     * Tells if the device is currently in an emergency session.
152     *
153     * Emergency session is defined as the device being actively in a user initiated emergency
154     * call or in post emergency call extension time period.
155     *
156     * If the GNSS HAL implementation cannot determine if the device is in emergency session
157     * mode, it must call this method to confirm that the device is in emergency session before
158     * serving network initiated emergency SUPL and Control Plane location requests.
159     *
160     * @return success True if the framework determines that the device is in emergency session.
161     */
162    isInEmergencySession() generates (bool success);
163};
164