1 /* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Sensor 18 * @{ 19 * 20 * @brief Provides unified APIs for sensor services to access sensor drivers. 21 * 22 * A sensor service can obtain a sensor driver object or agent and then call APIs provided by this object or agent to 23 * access different types of sensor devices based on the sensor IDs, thereby obtaining sensor information, 24 * subscribing to or unsubscribing from sensor data, enabling or disabling a sensor, 25 * setting the sensor data reporting mode, and setting sensor options such as the accuracy and measurement range. 26 * 27 * @since 2.2 28 */ 29 30 /** 31 * @file sensor_if.h 32 * 33 * @brief Declares the APIs provided by the sensor module for obtaining sensor information, subscribing to or 34 * unsubscribing from sensor data, enabling or disabling a sensor, setting the sensor data reporting mode, 35 * and setting sensor options such as the accuracy and measurement range. 36 * 37 * @since 2.2 38 * @version 1.0 39 */ 40 41 #ifndef SENSOR_IF_H 42 #define SENSOR_IF_H 43 44 #include <stdbool.h> 45 #include "sensor_type.h" 46 47 #ifdef __cplusplus 48 #if __cplusplus 49 extern "C" { 50 #endif 51 #endif /* __cplusplus */ 52 53 /** 54 * @brief Defines the functions for performing basic operations on sensors. 55 * 56 * The operations include obtaining sensor information, subscribing to or unsubscribing from sensor data, 57 * enabling or disabling a sensor, setting the sensor data reporting mode, and setting sensor options such as 58 * the accuracy and measurement range. 59 */ 60 struct SensorInterface { 61 /** 62 * @brief Obtains information about all sensors in the system. 63 * 64 * @param sensorInfo Indicates the double pointer to the information about all sensors in the system. 65 * The information about a sensor generally includes the sensor name, sensor vendor, firmware version, 66 * hardware version, sensor type ID, sensor ID, maximum measurement range, accuracy, and power. For details, 67 * see {@link SensorInformation}. 68 * @param count Indicates the pointer to the total number of sensors in the system. 69 * @return Returns <b>0</b> if the information is obtained; returns a negative value otherwise. 70 * 71 * @since 2.2 72 * @version 1.0 73 */ 74 int32_t (*GetAllSensors)(struct SensorInformation **sensorInfo, int32_t *count); 75 76 /** 77 * @brief Enables the sensor available in the sensor list based on the specified sensor ID. 78 * The subscriber can obtain the sensor data only after the sensor is enabled. 79 * 80 * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. 81 * @return Returns <b>0</b> if the sensor is successfully enabled; returns a negative value otherwise. 82 * 83 * @since 2.2 84 * @version 1.0 85 */ 86 int32_t (*Enable)(int32_t sensorId); 87 88 /** 89 * @brief Disables an enabled sensor. 90 * 91 * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. 92 * @return Returns <b>0</b> if the sensor is successfully disabled; returns a negative value otherwise. 93 * 94 * @since 2.2 95 * @version 1.0 96 */ 97 int32_t (*Disable)(int32_t sensorId); 98 99 /** 100 * @brief Sets the data sampling interval and data reporting interval for the specified sensor. 101 * 102 * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. 103 * @param samplingInterval Indicates the sensor data sampling interval to set, in nanoseconds. 104 * @param reportInterval Indicates the sensor data reporting interval, in nanoseconds. 105 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 106 * 107 * @since 2.2 108 * @version 1.0 109 */ 110 int32_t (*SetBatch)(int32_t sensorId, int64_t samplingInterval, int64_t reportInterval); 111 112 /** 113 * @brief Sets the data reporting mode for the specified sensor. 114 * 115 * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. 116 * @param mode Indicates the data reporting mode to set. For details, see {@link SensorModeType}. 117 * @return Returns <b>0</b> if the sensor data reporting mode is successfully set; 118 * returns a negative value otherwise. 119 * 120 * @since 2.2 121 * @version 1.0 122 */ 123 int32_t (*SetMode)(int32_t sensorId, int32_t mode); 124 125 /** 126 * @brief Sets options for the specified sensor, including its measurement range and accuracy. 127 * 128 * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. 129 * @param option Indicates the options to set, such as the measurement range and accuracy. 130 * @return Returns <b>0</b> if the options are successfully set; returns a negative value otherwise. 131 * 132 * @since 2.2 133 * @version 1.0 134 */ 135 int32_t (*SetOption)(int32_t sensorId, uint32_t option); 136 137 /** 138 * @brief Registers the callback for reporting sensor data to the subscriber. 139 * 140 * @param groupId Indicates the sensor group ID. 141 * The sensorId enumeration value range is 128-160, which means that the medical sensor service is subscribed. 142 * It only needs to be subscribed once successfully, and there is no need to subscribe repeatedly. 143 * The sensorId enumeration value range is not within 128-160, which means that the traditional sensor 144 * is subscribed, and the subscription is successful once. 145 * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. 146 * @return Returns <b>0</b> if the callback is successfully registered; returns a negative value otherwise. 147 * 148 * @since 2.2 149 * @version 1.0 150 */ 151 int32_t (*Register)(int32_t groupId, RecordDataCallback cb); 152 153 /** 154 * @brief Deregisters the callback for reporting sensor data. 155 * 156 * @param groupId Indicates the sensor group ID. 157 * The sensorId enumeration value range is 128-160, which means that the medical sensor service is subscribed. 158 * It only needs to cancel the subscription once successfully, and there is no need to 159 * cancel the subscription repeatedly. The sensorId enumeration value range is not within 128-160, 160 * which means that the traditional sensor is subscribed. You can cancel the subscription once successfully. 161 * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. 162 * @return Returns <b>0</b> if the callback is successfully deregistered; returns a negative value otherwise. 163 * 164 * @since 2.2 165 * @version 1.0 166 */ 167 int32_t (*Unregister)(int32_t groupId, RecordDataCallback cb); 168 169 /** 170 * @brief Obtain the sensor event data in the small system. 171 * 172 * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. 173 * @param event Indicates the vector of the sensor event data in the system. 174 * The sensor event data includes the sensor ID, sensor algorithm version, data generation time, 175 * data options (such as the measurement range and accuracy), data reporting mode, data address, and data length. 176 * For details, see {@link HdfSensorEvents}. 177 * @return Returns <b>0</b> if the event data is obtained; returns a negative value otherwise. 178 * 179 * @since 2.2 180 * @version 1.0 181 */ 182 int32_t (*ReadData)(int32_t sensorId, struct SensorEvents *event); 183 184 /** 185 * @brief Obtain sensor information for SDC 186 * 187 * @param sdcSensorInfo Indicates the data of the SDC type. 188 * @return Returns <b>0</b> if the event data is obtained; returns a negative value otherwise. 189 * 190 * @since 4.1 191 * @version 2.0 192 */ 193 int32_t (*GetSdcSensorInfo)(struct SdcSensorInfo sdcSensorInfo[]); 194 }; 195 196 /** 197 * @brief Creates a <b>SensorInterface</b> instance. 198 * 199 * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. 200 * You can use the instance to obtain sensor information, subscribe to or unsubscribe from sensor data, 201 * enable or disable a sensor, set the sensor data reporting mode, and set the sensor options such as the accuracy and 202 * measurement range. 203 * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. 204 * @return Returns a non-zero value if the instance is successfully created; returns <b>0</b> otherwise. 205 * 206 * @since 2.2 207 * @version 1.0 208 */ 209 const struct SensorInterface *NewSensorInterfaceInstance(void); 210 211 /** 212 * @brief Releases the <b>SensorInterface</b> instance. 213 * 214 * @return Returns <b>0</b> if the instance is successfully released; returns a negative value otherwise. 215 * 216 * @since 2.2 217 * @version 1.0 218 */ 219 int32_t FreeSensorInterfaceInstance(void); 220 221 #ifdef __cplusplus 222 #if __cplusplus 223 } 224 #endif 225 #endif /* __cplusplus */ 226 227 #endif /* SENSOR_IF_H */ 228 /** @} */ 229