1/*
2 * Copyright (C) 2013, 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/license/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.location;
18
19import android.hardware.location.IFusedLocationHardwareSink;
20import android.location.FusedBatchOptions;
21
22/**
23 * Fused Location hardware interface.
24 * This interface is the basic set of supported functionality by Fused Hardware
25 * modules that offer Location batching capabilities.
26 *
27 * @hide
28 */
29interface IFusedLocationHardware {
30    /**
31     * Registers a sink with the Location Hardware object.
32     *
33     * @param eventSink     The sink to register.
34     */
35    void registerSink(in IFusedLocationHardwareSink eventSink) = 0;
36
37    /**
38     * Unregisters a sink with the Location Hardware object.
39     *
40     * @param eventSink     The sink to unregister.
41     */
42    void unregisterSink(in IFusedLocationHardwareSink eventSink) = 1;
43
44    /**
45     * Provides access to the batch size available in Hardware.
46     *
47     * @return The batch size the hardware supports.
48     */
49    int getSupportedBatchSize() = 2;
50
51    /**
52     * Requests the Hardware to start batching locations.
53     *
54     * @param id            An Id associated with the request.
55     * @param batchOptions  The options required for batching.
56     *
57     * @throws RuntimeException if the request Id exists.
58     */
59    void startBatching(in int id, in FusedBatchOptions batchOptions) = 3;
60
61    /**
62     * Requests the Hardware to stop batching for the given Id.
63     *
64     * @param id    The request that needs to be stopped.
65     * @throws RuntimeException if the request Id is unknown.
66     */
67    void stopBatching(in int id) = 4;
68
69    /**
70     * Updates a batching operation in progress.
71     *
72     * @param id                The Id of the operation to update.
73     * @param batchOptions     The options to apply to the given operation.
74     *
75     * @throws RuntimeException if the Id of the request is unknown.
76     */
77    void updateBatchingOptions(in int id, in FusedBatchOptions batchOptions) = 5;
78
79    /**
80     * Requests the most recent locations available in Hardware.
81     * This operation does not dequeue the locations, so still other batching
82     * events will continue working.
83     *
84     * @param batchSizeRequested    The number of locations requested.
85     */
86    void requestBatchOfLocations(in int batchSizeRequested) = 6;
87
88    /**
89     * Flags if the Hardware supports injection of diagnostic data.
90     *
91     * @return True if data injection is supported, false otherwise.
92     */
93    boolean supportsDiagnosticDataInjection() = 7;
94
95    /**
96     * Injects diagnostic data into the Hardware subsystem.
97     *
98     * @param data  The data to inject.
99     * @throws RuntimeException if injection is not supported.
100     */
101    void injectDiagnosticData(in String data) = 8;
102
103    /**
104     * Flags if the Hardware supports injection of device context information.
105     *
106     * @return True if device context injection is supported, false otherwise.
107     */
108    boolean supportsDeviceContextInjection() = 9;
109
110    /**
111     * Injects device context information into the Hardware subsystem.
112     *
113     * @param deviceEnabledContext  The context to inject.
114     * @throws RuntimeException if injection is not supported.
115     */
116    void injectDeviceContext(in int deviceEnabledContext) = 10;
117
118    /**
119     * Requests all batched locations currently available in Hardware
120     * and clears the buffer.  Any subsequent calls will not return any
121     * of the locations returned in this call.
122     */
123    void flushBatchedLocations() = 11;
124
125    /**
126     * Returns the version of this FLP HAL implementation.
127     */
128    int getVersion() = 12;
129}
130