1 /* 2 * Copyright (c) 2023 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 APIs to define common sensor attributes. 21 * 22 * @since 11 23 */ 24 25 /** 26 * @file oh_sensor_type.h 27 * 28 * @brief Declares the common sensor attributes. 29 * @library libohsensor.so 30 * @syscap SystemCapability.Sensors.Sensor 31 * @since 11 32 */ 33 34 #ifndef OH_SENSOR_TYPE_H 35 #define OH_SENSOR_TYPE_H 36 37 #include <cstdint> 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /** 44 * @brief Enumerates the sensor types. 45 * 46 * @since 11 47 */ 48 typedef enum Sensor_Type { 49 /** 50 * Acceleration sensor. 51 * @since 11 52 */ 53 SENSOR_TYPE_ACCELEROMETER = 1, 54 /** 55 * Gyroscope sensor. 56 * @since 11 57 */ 58 SENSOR_TYPE_GYROSCOPE = 2, 59 /** 60 * Ambient light sensor. 61 * @since 11 62 */ 63 SENSOR_TYPE_AMBIENT_LIGHT = 5, 64 /** 65 * Magnetic field sensor. 66 * @since 11 67 */ 68 SENSOR_TYPE_MAGNETIC_FIELD = 6, 69 /** 70 * Barometer sensor. 71 * @since 11 72 */ 73 SENSOR_TYPE_BAROMETER = 8, 74 /** 75 * Hall effect sensor. 76 * @since 11 77 */ 78 SENSOR_TYPE_HALL = 10, 79 /** 80 * Proximity sensor. 81 * @since 11 82 */ 83 SENSOR_TYPE_PROXIMITY = 12, 84 /** 85 * Orientation sensor. 86 * @since 11 87 */ 88 SENSOR_TYPE_ORIENTATION = 256, 89 /** 90 * Gravity sensor. 91 * @since 11 92 */ 93 SENSOR_TYPE_GRAVITY = 257, 94 /** 95 * Rotation vector sensor. 96 * @since 11 97 */ 98 SENSOR_TYPE_ROTATION_VECTOR = 259, 99 /** 100 * Pedometer detection sensor. 101 * @since 11 102 */ 103 SENSOR_TYPE_PEDOMETER_DETECTION = 265, 104 /** 105 * Pedometer sensor. 106 * @since 11 107 */ 108 SENSOR_TYPE_PEDOMETER = 266, 109 /** 110 * Heart rate sensor. 111 * @since 11 112 */ 113 SENSOR_TYPE_HEART_RATE = 278, 114 } Sensor_Type; 115 116 /** 117 * @brief Enumerates the sensor result codes. 118 * 119 * @since 11 120 */ 121 typedef enum Sensor_Result { 122 /** 123 * The operation is successful. 124 * @since 11 125 */ 126 SENSOR_SUCCESS = 0, 127 /** 128 * Permission verification failed. 129 * @since 11 130 */ 131 SENSOR_PERMISSION_DENIED = 201, 132 /** 133 * Parameter check failed. For example, a mandatory parameter is not passed in, 134 * or the parameter type passed in is incorrect. 135 * @since 11 136 */ 137 SENSOR_PARAMETER_ERROR = 401, 138 /** 139 * The sensor service is abnormal. 140 * @since 11 141 */ 142 SENSOR_SERVICE_EXCEPTION = 14500101, 143 } Sensor_Result; 144 145 /** 146 * @brief Enumerates the accuracy levels of data reported by a sensor. 147 * 148 * @since 11 149 */ 150 typedef enum Sensor_Accuracy { 151 /** 152 * The sensor data is unreliable. It is possible that the sensor does not contact with the device to measure. 153 * @since 11 154 */ 155 SENSOR_ACCURACY_UNRELIABLE = 0, 156 /** 157 * The sensor data is at a low accuracy level. The data must be calibrated based on 158 * the environment before being used. 159 * @since 11 160 */ 161 SENSOR_ACCURACY_LOW = 1, 162 /** 163 * The sensor data is at a medium accuracy level. You are advised to calibrate the data 164 * based on the environment before using it. 165 * @since 11 166 */ 167 SENSOR_ACCURACY_MEDIUM = 2, 168 /** 169 * The sensor data is at a high accuracy level. The data can be used directly. 170 * @since 11 171 */ 172 SENSOR_ACCURACY_HIGH = 3 173 } Sensor_Accuracy; 174 175 /** 176 * @brief Defines the sensor information. 177 * @since 11 178 */ 179 typedef struct Sensor_Info Sensor_Info; 180 181 /** 182 * @brief Creates an array of {@link Sensor_Info} instances with the given number. 183 * 184 * @param count - Number of {@link Sensor_Info} instances to create. 185 * @return Returns the double pointer to the array of {@link Sensor_Info} instances 186 * if the operation is successful; 187 * returns <b>NULL</b> otherwise. 188 * @since 11 189 */ 190 Sensor_Info **OH_Sensor_CreateInfos(uint32_t count); 191 192 /** 193 * @brief Destroys an array of {@link Sensor_Info} instances and reclaims memory. 194 * 195 * @param sensors - Double pointer to the array of {@link Sensor_Info} instances. 196 * @param count - Number of {@link Sensor_Info} instances to destroy. 197 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 198 * returns an error code defined in {@link Sensor_Result} otherwise. 199 * @since 11 200 */ 201 int32_t OH_Sensor_DestroyInfos(Sensor_Info **sensors, uint32_t count); 202 203 /** 204 * @brief Obtains the sensor name. 205 * 206 * @param sensor - Pointer to the sensor information. 207 * @param sensorName - Pointer to the sensor name. 208 * @param length - Pointer to the length, in bytes. 209 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 210 * returns an error code defined in {@link Sensor_Result} otherwise. 211 * @since 11 212 */ 213 int32_t OH_SensorInfo_GetName(Sensor_Info* sensor, char *sensorName, uint32_t *length); 214 215 /** 216 * @brief Obtains the sensor's vendor name. 217 * 218 * @param sensor - Pointer to the sensor information. 219 * @param vendorName - Pointer to the vendor name. 220 * @param length - Pointer to the length, in bytes. 221 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 222 * returns an error code defined in {@link Sensor_Result} otherwise. 223 * @since 11 224 */ 225 int32_t OH_SensorInfo_GetVendorName(Sensor_Info* sensor, char *vendorName, uint32_t *length); 226 227 /** 228 * @brief Obtains the sensor type. 229 * 230 * @param sensor - Pointer to the sensor information. 231 * @param sensorType - Pointer to the sensor type. 232 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 233 * returns an error code defined in {@link Sensor_Result} otherwise. 234 * @since 11 235 */ 236 int32_t OH_SensorInfo_GetType(Sensor_Info* sensor, Sensor_Type *sensorType); 237 238 /** 239 * @brief Obtains the sensor resolution. 240 * 241 * @param sensor - Pointer to the sensor information. 242 * @param resolution - Pointer to the sensor resolution. 243 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 244 * returns an error code defined in {@link Sensor_Result} otherwise. 245 * @since 11 246 */ 247 int32_t OH_SensorInfo_GetResolution(Sensor_Info* sensor, float *resolution); 248 249 /** 250 * @brief Obtains the minimum data reporting interval of a sensor. 251 * 252 * @param sensor - Pointer to the sensor information. 253 * @param minSamplingInterval - Pointer to the minimum data reporting interval, in nanoseconds. 254 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 255 * returns an error code defined in {@link Sensor_Result} otherwise. 256 * @since 11 257 */ 258 int32_t OH_SensorInfo_GetMinSamplingInterval(Sensor_Info* sensor, int64_t *minSamplingInterval); 259 260 /** 261 * @brief Obtains the maximum data reporting interval of a sensor. 262 * 263 * @param sensor - Pointer to the sensor information. 264 * @param maxSamplingInterval - Pointer to the maximum data reporting interval, in nanoseconds. 265 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 266 * returns an error code defined in {@link Sensor_Result} otherwise. 267 * @since 11 268 */ 269 int32_t OH_SensorInfo_GetMaxSamplingInterval(Sensor_Info* sensor, int64_t *maxSamplingInterval); 270 271 /** 272 * @brief Defines the sensor data information. 273 * @since 11 274 */ 275 typedef struct Sensor_Event Sensor_Event; 276 277 /** 278 * @brief Obtains the sensor type. 279 * 280 * @param Sensor_Event - Pointer to the sensor data information. 281 * @param sensorType - Pointer to the sensor type. 282 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 283 * returns an error code defined in {@link Sensor_Result} otherwise. 284 * @since 11 285 */ 286 int32_t OH_SensorEvent_GetType(Sensor_Event* Sensor_Event, Sensor_Type *sensorType); 287 288 /** 289 * @brief Obtains the timestamp of sensor data. 290 * 291 * @param Sensor_Event - Pointer to the sensor data information. 292 * @param timestamp - Pointer to the timestamp. 293 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 294 * returns an error code defined in {@link Sensor_Result} otherwise. 295 * @since 11 296 */ 297 int32_t OH_SensorEvent_GetTimestamp(Sensor_Event* Sensor_Event, int64_t *timestamp); 298 299 /** 300 * @brief Obtains the accuracy of sensor data. 301 * 302 * @param Sensor_Event - Pointer to the sensor data information. 303 * @param accuracy - Pointer to the accuracy. 304 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 305 * returns an error code defined in {@link Sensor_Result} otherwise. 306 * @since 11 307 */ 308 int32_t OH_SensorEvent_GetAccuracy(Sensor_Event* Sensor_Event, Sensor_Accuracy *accuracy); 309 310 /** 311 * @brief Obtains sensor data. The data length and content depend on the sensor type. 312 * The format of the sensor data reported is as follows: 313 * SENSOR_TYPE_ACCELEROMETER: data[0], data[1], and data[2], indicating the acceleration around 314 * the x, y, and z axes of the device, respectively, in m/s2. 315 * SENSOR_TYPE_GYROSCOPE: data[0], data[1], and data[2], indicating the angular velocity of rotation around 316 * the x, y, and z axes of the device, respectively, in rad/s. 317 * SENSOR_TYPE_AMBIENT_LIGHT: data[0], indicating the ambient light intensity, in lux. 318 * SENSOR_TYPE_MAGNETIC_FIELD: data[0], data[1], and data[2], indicating the magnetic field strength around 319 * the x, y, and z axes of the device, respectively, in μT. 320 * SENSOR_TYPE_BAROMETER: data[0], indicating the atmospheric pressure, in hPa. 321 * SENSOR_TYPE_HALL: data[0], indicating the opening/closing state of the flip cover. The value <b>0</b> means that 322 * the flip cover is opened, and a value greater than <b>0</b> means that the flip cover is closed. 323 * SENSOR_TYPE_PROXIMITY: data[0], indicates the approaching state. The value <b>0</b> means the two objects are close 324 * to each other, and a value greater than <b>0</b> means that they are far away from each other. 325 * SENSOR_TYPE_ORIENTATION: data[0], data[1], and data[2], indicating the rotation angles of a device around 326 * the z, x, and y axes, respectively, in degree. 327 * SENSOR_TYPE_GRAVITY: data[0], data[1], and data[2], indicating the gravitational acceleration around 328 * the x, y, and z axes of a device, respectively, in m/s2. 329 * SENSOR_TYPE_ROTATION_VECTOR: data[0], data[1] and data[2], indicating the rotation angles of a device around 330 * the x, y, and z axes, respectively, in degree. data[3] indicates the rotation vector. 331 * SENSOR_TYPE_PEDOMETER_DETECTION: data[0], indicating the pedometer detection status. 332 * The value <b>1</b> means that the number of detected steps changes. 333 * SENSOR_TYPE_PEDOMETER: data[0], indicating the number of steps a user has walked. 334 * SENSOR_TYPE_HEART_RATE: data[0], indicating the heart rate value. 335 * 336 * @param Sensor_Event - Pointer to the sensor data information. 337 * @param data - Double pointer to the sensor data. 338 * @param length - Pointer to the array length. 339 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 340 * returns an error code defined in {@link Sensor_Result} otherwise. 341 * @since 11 342 */ 343 int32_t OH_SensorEvent_GetData(Sensor_Event* Sensor_Event, float **data, uint32_t *length); 344 345 /** 346 * @brief Defines the sensor subscription ID, which uniquely identifies a sensor. 347 * @since 11 348 */ 349 typedef struct Sensor_SubscriptionId Sensor_SubscriptionId; 350 351 /** 352 * @brief Creates a {@link Sensor_SubscriptionId} instance. 353 * 354 * @return Returns the pointer to the {@link Sensor_SubscriptionId} instance if the operation is successful; 355 * returns <b>NULL</b> otherwise. 356 * @since 11 357 */ 358 Sensor_SubscriptionId *OH_Sensor_CreateSubscriptionId(void); 359 360 /** 361 * @brief Destroys a {@link Sensor_SubscriptionId} instance and reclaims memory. 362 * 363 * @param id - Pointer to the {@link Sensor_SubscriptionId} instance. 364 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 365 * returns an error code defined in {@link Sensor_Result} otherwise. 366 * @since 11 367 */ 368 int32_t OH_Sensor_DestroySubscriptionId(Sensor_SubscriptionId *id); 369 370 /** 371 * @brief Obtains the sensor type. 372 * 373 * @param id - Pointer to the sensor subscription ID. 374 * @param id - Pointer to the sensor type. 375 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 376 * returns an error code defined in {@link Sensor_Result} otherwise. 377 * @since 11 378 */ 379 int32_t OH_SensorSubscriptionId_GetType(Sensor_SubscriptionId* id, Sensor_Type *sensorType); 380 381 /** 382 * @brief Sets the sensor type. 383 * 384 * @param id - Pointer to the sensor subscription ID. 385 * @param sensorType - Sensor type to set. 386 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 387 * returns an error code defined in {@link Sensor_Result} otherwise. 388 * @since 11 389 */ 390 int32_t OH_SensorSubscriptionId_SetType(Sensor_SubscriptionId* id, const Sensor_Type sensorType); 391 392 /** 393 * @brief Defines the sensor subscription attribute. 394 * @since 11 395 */ 396 typedef struct Sensor_SubscriptionAttribute Sensor_SubscriptionAttribute; 397 398 /** 399 * @brief Creates a {@link Sensor_SubscriptionAttribute} instance. 400 * 401 * @return Returns the pointer to the {@link Sensor_SubscriptionAttribute} instance if the operation is successful; 402 * returns <b>NULL</b> otherwise. 403 * @since 11 404 */ 405 Sensor_SubscriptionAttribute *OH_Sensor_CreateSubscriptionAttribute(void); 406 407 /** 408 * @brief Destroys a {@link Sensor_SubscriptionAttribute} instance and reclaims memory. 409 * 410 * @param attribute - Pointer to the {@link Sensor_SubscriptionAttribute} instance. 411 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 412 * returns an error code defined in {@link Sensor_Result} otherwise. 413 * @since 11 414 */ 415 int32_t OH_Sensor_DestroySubscriptionAttribute(Sensor_SubscriptionAttribute *attribute); 416 417 /** 418 * @brief Sets the sensor data reporting interval. 419 * 420 * @param attribute - Pointer to the sensor subscription attribute. 421 * @param samplingInterval - Data reporting interval to set, in nanoseconds. 422 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 423 * returns an error code defined in {@link Sensor_Result} otherwise. 424 * @since 11 425 */ 426 int32_t OH_SensorSubscriptionAttribute_SetSamplingInterval(Sensor_SubscriptionAttribute* attribute, 427 const int64_t samplingInterval); 428 429 /** 430 * @brief Obtains the sensor data reporting interval. 431 * 432 * @param attribute - Pointer to the sensor subscription attribute. 433 * @param samplingInterval - Pointer to the data reporting interval, in nanoseconds. 434 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 435 * returns an error code defined in {@link Sensor_Result} otherwise. 436 * @since 11 437 */ 438 int32_t OH_SensorSubscriptionAttribute_GetSamplingInterval(Sensor_SubscriptionAttribute* attribute, 439 int64_t *samplingInterval); 440 441 /** 442 * @brief Defines the callback function used to report sensor data. 443 * @since 11 444 */ 445 typedef void (*Sensor_EventCallback)(Sensor_Event *event); 446 447 /** 448 * @brief Defines the sensor subscriber information. 449 * @since 11 450 */ 451 typedef struct Sensor_Subscriber Sensor_Subscriber; 452 453 /** 454 * @brief Creates a {@link Sensor_Subscriber} instance. 455 * 456 * @return Returns the pointer to the {@link Sensor_Subscriber} instance 457 * if the operation is successful; returns <b>NULL</b> otherwise. 458 * @since 11 459 */ 460 Sensor_Subscriber *OH_Sensor_CreateSubscriber(void); 461 462 /** 463 * @brief Destroys a {@link Sensor_Subscriber} instance and reclaims memory. 464 * 465 * @param subscriber - Pointer to the {@link Sensor_Subscriber} instance. 466 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 467 * returns an error code defined in {@link Sensor_Result} otherwise. 468 * @since 11 469 */ 470 int32_t OH_Sensor_DestroySubscriber(Sensor_Subscriber *subscriber); 471 472 /** 473 * @brief Sets a callback function to report sensor data. 474 * 475 * @param subscriber - Pointer to the sensor subscriber information. 476 * @param callback - Callback function to set. 477 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 478 * returns an error code defined in {@link Sensor_Result} otherwise. 479 * @since 11 480 */ 481 int32_t OH_SensorSubscriber_SetCallback(Sensor_Subscriber* subscriber, const Sensor_EventCallback callback); 482 483 /** 484 * @brief Obtains the callback function used to report sensor data. 485 * 486 * @param subscriber - Pointer to the sensor subscriber information. 487 * @param callback - Pointer to the callback function. 488 * @return Returns <b>SENSOR_SUCCESS</b> if the operation is successful; 489 * returns an error code defined in {@link Sensor_Result} otherwise. 490 * @since 11 491 */ 492 int32_t OH_SensorSubscriber_GetCallback(Sensor_Subscriber* subscriber, Sensor_EventCallback *callback); 493 #ifdef __cplusplus 494 } 495 #endif 496 /** @} */ 497 #endif // OH_SENSOR_TYPE_H