1 /*
2  * Copyright (C) 2023 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 
17 package android.companion.virtual.sensor;
18 
19 
20 import android.annotation.IntRange;
21 import android.annotation.NonNull;
22 import android.annotation.SystemApi;
23 import android.hardware.Sensor;
24 import android.hardware.SensorDirectChannel;
25 import android.os.MemoryFile;
26 import android.os.SharedMemory;
27 
28 /**
29  * Interface for notifying the virtual device owner about any {@link SensorDirectChannel} events.
30  *
31  * <p>This callback can be used for controlling the sensor event injection to direct channels. A
32  * typical order of callback invocations is:
33  * <ul>
34  *     <li>{@code onDirectChannelCreated} - the channel handle and the associated shared memory
35  *     should be stored by the virtual device</li>
36  *     <li>{@code onDirectChannelConfigured} with a positive {@code rateLevel} - the virtual
37  *     device should start writing to the shared memory for the associated channel with the
38  *     requested parameters.</li>
39  *     <li>{@code onDirectChannelConfigured} with a {@code rateLevel = RATE_STOP} - the virtual
40  *     device should stop writing to the shared memory for the associated channel.</li>
41  *     <li>{@code onDirectChannelDestroyed} - the shared memory associated with the channel
42  *     handle should be closed.</li>
43  * </ul>
44  *
45  * <p>The callback is tied to the VirtualDevice's lifetime as the virtual sensors are created when
46  * the device is created and destroyed when the device is destroyed.
47  *
48  * @see VirtualSensorDirectChannelWriter
49  *
50  * @hide
51  */
52 @SystemApi
53 public interface VirtualSensorDirectChannelCallback {
54     /**
55      * Called when a {@link android.hardware.SensorDirectChannel} is created.
56      *
57      * <p>The {@link android.hardware.SensorManager} instance used to create the direct channel must
58      * be associated with the virtual device.
59      *
60      * @param channelHandle Identifier of the newly created channel.
61      * @param sharedMemory writable shared memory region.
62      *
63      * @see android.hardware.SensorManager#createDirectChannel(MemoryFile)
64      * @see #onDirectChannelConfigured
65      * @see #onDirectChannelDestroyed
66      */
onDirectChannelCreated(@ntRangefrom = 1) int channelHandle, @NonNull SharedMemory sharedMemory)67     void onDirectChannelCreated(@IntRange(from = 1) int channelHandle,
68             @NonNull SharedMemory sharedMemory);
69 
70     /**
71      * Called when a {@link android.hardware.SensorDirectChannel} is destroyed.
72      *
73      * <p>The virtual device must perform any clean-up and close the shared memory that was
74      * received with the {@link #onDirectChannelCreated} callback and the corresponding
75      * {@code channelHandle}.
76      *
77      * @param channelHandle Identifier of the channel that was destroyed.
78      *
79      * @see SensorDirectChannel#close()
80      */
onDirectChannelDestroyed(@ntRangefrom = 1) int channelHandle)81     void onDirectChannelDestroyed(@IntRange(from = 1) int channelHandle);
82 
83     /**
84      * Called when a {@link android.hardware.SensorDirectChannel} is configured.
85      *
86      * <p>Sensor events for the corresponding sensor should be written at the indicated rate to the
87      * shared memory region that was received with the {@link #onDirectChannelCreated} callback and
88      * the corresponding {@code channelHandle}. The events should be written in the correct format
89      * and with the provided {@code reportToken} until the channel is reconfigured with
90      * {@link SensorDirectChannel#RATE_STOP}.
91      *
92      * <p>The sensor must support direct channel in order for this callback to be invoked. Only
93      * {@link MemoryFile} sensor direct channels are supported for virtual sensors.
94      *
95      * @param channelHandle Identifier of the channel that was configured.
96      * @param sensor The sensor, for which the channel was configured.
97      * @param rateLevel The rate level used to configure the direct sensor channel.
98      * @param reportToken A positive sensor report token, used to differentiate between events from
99      *   different sensors within the same channel.
100      *
101      * @see VirtualSensorConfig.Builder#setHighestDirectReportRateLevel(int)
102      * @see VirtualSensorConfig.Builder#setDirectChannelTypesSupported(int)
103      * @see android.hardware.SensorManager#createDirectChannel(MemoryFile)
104      * @see #onDirectChannelCreated
105      * @see SensorDirectChannel#configure(Sensor, int)
106      */
onDirectChannelConfigured(@ntRangefrom = 1) int channelHandle, @NonNull VirtualSensor sensor, @SensorDirectChannel.RateLevel int rateLevel, @IntRange(from = 1) int reportToken)107     void onDirectChannelConfigured(@IntRange(from = 1) int channelHandle,
108             @NonNull VirtualSensor sensor, @SensorDirectChannel.RateLevel int rateLevel,
109             @IntRange(from = 1) int reportToken);
110 }
111