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