2 * Copyright (C) 2016 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package android.hardware.gnss@1.0;
19 import IGnssBatchingCallback;
22 * Extended interface for GNSS Batching support.
24 * If this interface is supported, this batching request must be able to run in
25 * parallel with, or without, non-batched location requested by the
26 * IGnss start() & stop() - i.e. both requests must be handled independently,
27 * and not interfere with each other.
29 * For example, if a 1Hz continuous output is underway on the IGnssCallback,
30 * due to an IGnss start() operation,
31 * and then a IGnssBatching start() is called for a location every 10
32 * seconds, the newly added batching request must not disrupt the 1Hz
33 * continuous location output on the IGnssCallback.
35 * As with GNSS Location outputs, source of location must be GNSS satellite
36 * measurements, optionally using interial and baro sensors to improve
37 * relative motion filtering. No additional absolute positioning information,
38 * such as WiFi derived location, may be mixed with the GNSS information.
41 interface IGnssBatching {
43 * Enum which holds the bit masks for batching control.
45 @export(name="", value_prefix="FLP_BATCH_")
48 * If this flag is set, the hardware implementation
49 * must wake up the application processor when the FIFO is full, and
50 * call IGnssBatchingCallback to return the locations.
52 * If the flag is not set, the hardware implementation must drop
53 * the oldest data when the FIFO is full.
55 WAKEUP_ON_FIFO_FULL = 0x01
60 * Time interval between samples in the location batch, in nano
66 * Flags controlling how batching should behave.
72 * Opens the interface and provides the callback routines
73 * to the implementation of this interface.
75 * @param callback Callback interface for IGnssBatching.
77 * @return success Returns true on success.
79 init(IGnssBatchingCallback callback) generates (bool success);
82 * Return the batch size (in number of GnssLocation objects)
83 * available in this hardware implementation.
85 * If the available size is variable, for example, based on other operations
86 * consuming memory, this is the minimum size guaranteed to be available
87 * for batching operations.
89 * This may, for example, be used by the upper layer, to decide on the
90 * batching interval and whether the AP should be woken up or not.
92 * @return batchSize number of location objects supported per batch
94 getBatchSize() generates (uint16_t batchSize);
97 * Start batching locations. This API is primarily used when the AP is
98 * asleep and the device can batch locations in the hardware.
100 * IGnssBatchingCallback is used to return the locations.
102 * When the buffer is full and WAKEUP_ON_FIFO_FULL is used,
103 * IGnssBatchingCallback must be called to return the locations.
105 * When the buffer is full and WAKEUP_ON_FIFO_FULL is not set,
106 * the oldest location object is dropped. In this case the AP must not be
107 * woken up. The AP would then generally be responsible for using
108 * flushBatchedLocation to explicitly ask for the location as needed,
109 * to avoid it being dropped.
111 * @param options See struct Options definition.
113 * @return success Returns true on success.
115 start(Options options) generates (bool success);
118 * Retrieve all batched locations currently stored.
120 * IGnssBatchingCallback is used to return the location.
122 * IGnssBatchingCallback must be called in response, even if there are
123 * no locations to flush (in which case the Location vector must be empty).
125 * Subsequent calls to flushBatchedLocation
126 * must not return any of the locations returned in this call.
133 * @return success Returns true on success.
135 stop() generates (bool success);
138 * Closes the interface. If any batch operations are in progress,
139 * they must be stopped. If any locations are in the hardware batch, they
140 * must be deleted (and not sent via callback.)
142 * init() may be called again, after this, if the interface is to be restored