1/* 2 * Copyright (C) 2016 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.sensors@1.0; 18 19interface ISensors { 20 /** 21 * Enumerate all available (static) sensors. 22 */ 23 getSensorsList() generates (vec<SensorInfo> list); 24 25 /** 26 * Place the module in a specific mode. The following modes are defined 27 * 28 * SENSOR_HAL_NORMAL_MODE - Normal operation. Default state of the module. 29 * 30 * SENSOR_HAL_DATA_INJECTION_MODE - Loopback mode. 31 * Data is injected for the supported sensors by the sensor service in 32 * this mode. 33 * 34 * @return OK on success 35 * BAD_VALUE if requested mode is not supported 36 * PERMISSION_DENIED if operation is not allowed 37 */ 38 setOperationMode(OperationMode mode) generates (Result result); 39 40 /** 41 * Activate/de-activate one sensor. 42 * 43 * After sensor de-activation, existing sensor events that have not 44 * been picked up by poll() must be abandoned immediately so that 45 * subsequent activation will not get stale sensor events (events 46 * that are generated prior to the latter activation). 47 * 48 * @param sensorHandle is the handle of the sensor to change. 49 * @param enabled set to true to enable, or false to disable the sensor. 50 * 51 * @return result OK on success, BAD_VALUE if sensorHandle is invalid. 52 */ 53 activate(int32_t sensorHandle, bool enabled) generates (Result result); 54 55 /** 56 * Generate a vector of sensor events containing at most "maxCount" 57 * entries. 58 * 59 * Additionally a vector of SensorInfos is returned for any dynamic sensors 60 * connected as notified by returned events of type DYNAMIC_SENSOR_META. 61 * 62 * If there is no sensor event when this function is being called, block 63 * until there are sensor events available. 64 * 65 * @param maxCount max number of samples can be returned, must be > 0. 66 * Actual number of events returned in data must be <= maxCount 67 * and > 0. 68 * @return result OK on success or BAD_VALUE if maxCount <= 0. 69 * @return data vector of Event contains sensor events. 70 * @return dynamicSensorsAdded vector of SensorInfo contains dynamic sensor 71 * added. Each element corresponds to a dynamic sensor meta events 72 * in data. 73 */ 74 poll(int32_t maxCount) 75 generates ( 76 Result result, 77 vec<Event> data, 78 vec<SensorInfo> dynamicSensorsAdded); 79 80 /** 81 * Sets a sensor’s parameters, including sampling frequency and maximum 82 * report latency. This function can be called while the sensor is 83 * activated, in which case it must not cause any sensor measurements to 84 * be lost: transitioning from one sampling rate to the other cannot cause 85 * lost events, nor can transitioning from a high maximum report latency to 86 * a low maximum report latency. 87 * See the Batching sensor results page for details: 88 * http://source.android.com/devices/sensors/batching.html 89 * 90 * @param sensorHandle handle of sensor to be changed. 91 * @param samplingPeriodNs specifies sensor sample period in nanoseconds. 92 * @param maxReportLatencyNs allowed delay time before an event is sampled 93 * to time of report. 94 * @return result OK on success, BAD_VALUE if any parameters are invalid. 95 */ 96 batch(int32_t sensorHandle, 97 int64_t samplingPeriodNs, 98 int64_t maxReportLatencyNs) generates (Result result); 99 100 /** 101 * Trigger a flush of internal FIFO. 102 * 103 * Flush adds a FLUSH_COMPLETE metadata event to the end of the "batch mode" 104 * FIFO for the specified sensor and flushes the FIFO. If the FIFO is empty 105 * or if the sensor doesn't support batching (FIFO size zero), return 106 * SUCCESS and add a trivial FLUSH_COMPLETE event added to the event stream. 107 * This applies to all sensors other than one-shot sensors. If the sensor 108 * is a one-shot sensor, flush must return BAD_VALUE and not generate any 109 * flush complete metadata. If the sensor is not active at the time flush() 110 * is called, flush() return BAD_VALUE. 111 * 112 * @param sensorHandle handle of sensor to be flushed. 113 * @return result OK on success and BAD_VALUE if sensorHandle is invalid. 114 */ 115 flush(int32_t sensorHandle) generates (Result result); 116 117 /** 118 * Inject a single sensor event or push operation environment parameters to 119 * device. 120 * 121 * When device is in NORMAL mode, this function is called to push operation 122 * environment data to device. In this operation, Event is always of 123 * SensorType::AdditionalInfo type. See operation evironment parameters 124 * section in AdditionalInfoType. 125 * 126 * When device is in DATA_INJECTION mode, this function is also used for 127 * injecting sensor events. 128 * 129 * Regardless of OperationMode, injected SensorType::ADDITIONAL_INFO 130 * type events should not be routed back to poll() function. 131 * 132 * @see AdditionalInfoType 133 * @see OperationMode 134 * @param event sensor event to be injected 135 * @return result OK on success; PERMISSION_DENIED if operation is not 136 * allowed; INVALID_OPERATION, if this functionality is 137 * unsupported; BAD_VALUE if sensor event cannot be injected. 138 */ 139 injectSensorData(Event event) generates (Result result); 140 141 /** 142 * Register direct report channel. 143 * 144 * Register a direct channel with supplied shared memory information. Upon 145 * return, the sensor hardware is responsible for resetting the memory 146 * content to initial value (depending on memory format settings). 147 * 148 * @param mem shared memory info data structure. 149 * @return result OK on success; BAD_VALUE if shared memory information is 150 * not consistent; NO_MEMORY if shared memory cannot be used by 151 * sensor system; INVALID_OPERATION if functionality is not 152 * supported. 153 * @return channelHandle a positive integer used for referencing registered 154 * direct channel (>0) in configureDirectReport and 155 * unregisterDirectChannel if result is OK, -1 otherwise. 156 */ 157 registerDirectChannel(SharedMemInfo mem) 158 generates (Result result, int32_t channelHandle); 159 160 /** 161 * Unregister direct report channel. 162 * 163 * Unregister a direct channel previously registered using 164 * registerDirectChannel, and remove all active sensor report configured in 165 * still active sensor report configured in the direct channel. 166 * 167 * @param channelHandle handle of direct channel to be unregistered. 168 * @return result OK if direct report is supported; INVALID_OPERATION 169 * otherwise. 170 */ 171 unregisterDirectChannel(int32_t channelHandle) generates (Result result); 172 173 /** 174 * Configure direct sensor event report in direct channel. 175 * 176 * This function start, modify rate or stop direct report of a sensor in a 177 * certain direct channel. 178 * 179 * @param sensorHandle handle of sensor to be configured. When combined 180 * with STOP rate, sensorHandle can be -1 to denote all active 181 * sensors in the direct channel specified by channel Handle. 182 * @param channelHandle handle of direct channel to be configured. 183 * @param rate rate level, see RateLevel enum. 184 * 185 * @return result OK on success; BAD_VALUE if parameter is invalid (such as 186 * rate level is not supported by sensor, channelHandle does not 187 * exist, etc); INVALID_OPERATION if functionality is not 188 * supported. 189 * @return reportToken positive integer to identify multiple sensors of 190 * the same type in a single direct channel. Ignored if rate is 191 * STOP. See SharedMemFormat. 192 */ 193 configDirectReport( 194 int32_t sensorHandle, int32_t channelHandle, RateLevel rate) 195 generates (Result result, int32_t reportToken); 196}; 197