diff --git a/zh-cn/device_api/hdf/sensor/sensor_if.h b/zh-cn/device_api/hdf/sensor/sensor_if.h new file mode 100644 index 0000000000000000000000000000000000000000..e03eed290480bd2e1c57d3fb5a922d59ea4cf998 --- /dev/null +++ b/zh-cn/device_api/hdf/sensor/sensor_if.h @@ -0,0 +1,215 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Sensor + * @{ + * + * @brief Provides unified APIs for sensor services to access sensor drivers. + * + * A sensor service can obtain a sensor driver object or agent and then call APIs provided by this object or agent to + * access different types of sensor devices based on the sensor IDs, thereby obtaining sensor information, + * subscribing to or unsubscribing from sensor data, enabling or disabling a sensor, + * setting the sensor data reporting mode, and setting sensor options such as the accuracy and measurement range. + * + * @since 3.1 + */ + +/** + * @file sensor_if.h + * + * @brief Declares the APIs provided by the sensor module for obtaining sensor information, subscribing to or + * unsubscribing from sensor data, enabling or disabling a sensor, setting the sensor data reporting mode, + * and setting sensor options such as the accuracy and measurement range. + * + * @since 3.1 + * @version 1.0 + */ + +#ifndef SENSOR_IF_H +#define SENSOR_IF_H + +#include "sensor_type.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief Defines the functions for performing basic operations on sensors. + * + * The operations include obtaining sensor information, subscribing to or unsubscribing from sensor data, + * enabling or disabling a sensor, setting the sensor data reporting mode, and setting sensor options such as + * the accuracy and measurement range. + */ +struct SensorInterface { + /** + * @brief Obtains information about all sensors in the system. + * + * @param sensorInfo Indicates the double pointer to the information about all sensors in the system. + * The information about a sensor generally includes the sensor name, sensor vendor, firmware version, + * hardware version, sensor type ID, sensor ID, maximum measurement range, accuracy, and power. For details, + * see {@link SensorInformation}. + * @param count Indicates the pointer to the total number of sensors in the system. + * + * @return 0 if the information is obtained. + * @return Returns a negative value otherwise. + * + * @since 3.1 + * @version 1.0 + */ + int32_t (*GetAllSensors)(struct SensorInformation **sensorInfo, int32_t *count); + + /** + * @brief Enables the sensor available in the sensor list based on the specified sensor ID. + * The subscriber can obtain the sensor data only after the sensor is enabled. + * + * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. + * + * @return Returns 0 if the sensor is successfully enabled. + * @return Returns a negative value otherwise. + * + * @since 3.1 + * @version 1.0 + */ + int32_t (*Enable)(int32_t sensorId); + + /** + * @brief Disables an enabled sensor. + * + * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. + * + * @return Returns 0 if the sensor is successfully disabled. + * @return Returns a negative value otherwise. + * + * @since 3.1 + * @version 1.0 + */ + int32_t (*Disable)(int32_t sensorId); + + /** + * @brief Sets the data sampling interval and data reporting interval for the specified sensor. + * + * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. + * @param samplingInterval Indicates the sensor data sampling interval to set, in nanoseconds. + * @param reportInterval Indicates the sensor data reporting interval, in nanoseconds. + * + * @return Returns 0 if the setting is successful. + * @return Returns a negative value otherwise. + * + * @since 3.1 + * @version 1.0 + */ + int32_t (*SetBatch)(int32_t sensorId, int64_t samplingInterval, int64_t reportInterval); + + /** + * @brief Sets the data reporting mode for the specified sensor. + * + * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. + * @param mode Indicates the data reporting mode to set. For details, see {@link SensorModeType}. + * + * @return Returns 0 if the sensor data reporting mode is successfully set. + * @return Returns a negative value otherwise. + * + * @since 3.1 + * @version 1.0 + */ + int32_t (*SetMode)(int32_t sensorId, int32_t mode); + + /** + * @brief Sets options for the specified sensor, including its measurement range and accuracy. + * + * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. + * @param option Indicates the options to set, such as the measurement range and accuracy. + * + * @return Returns 0 if the options are successfully set. + * @return Returns a negative value otherwise. + * + * @since 3.1 + * @version 1.0 + */ + int32_t (*SetOption)(int32_t sensorId, uint32_t option); + + /** + * @brief Registers the callback for reporting sensor data to the subscriber. + * + * @param groupId 硬件服务分组id,值为0,代表传统sensor服务组号,值为1,代表医学sensor服务组号,对于传统 + * sensor服务,sensorId 值的范围为128-160,其他范围为医学sensor服务。回调函数只需要成功注册一次,不需要重复注册。 + * @param cb 需要注册的回调函数指针。详情看 {@link RecordDataCallback}。 + * + * @return 0 表示注册回调函数成功。 + * @return 负值 表示注册回调函数失败。 + * + * @since 3.1 + * @version 1.0 + */ + int32_t (*Register)(int32_t groupId, RecordDataCallback cb); + + /** + * @brief Deregisters the callback for reporting sensor data. + * + * @param groupId 硬件服务分组id,值为0,代表传统sensor服务组号,值为1,代表医学sensor服务组号, + * 对于传统sensor服务,sensorId 值的范围为128-160,其他范围为医学sensor服务。回调函数只需要成功取消注册一次,不需要 + * 重复取消注册。 + * @param cb 需要取消注册的回调函数指针。详情看 {@link RecordDataCallback}。 + * + * @return 0 表示取消注册回调函数成功。 + * @return 负值 表示取消注册回调函数失败。 + * + * @since 3.1 + * @version 1.0 + */ + int32_t (*Unregister)(int32_t groupId, RecordDataCallback cb); +}; + +/** + * @brief Creates a SensorInterface instance. + * + * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. + * You can use the instance to obtain sensor information, subscribe to or unsubscribe from sensor data, + * enable or disable a sensor, set the sensor data reporting mode, and set the sensor options such as the accuracy and + * measurement range. + * + * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. + * + * @return Returns a non-zero value if the instance is successfully created. + * @return Returns 0 otherwise. + * + * @since 3.1 + * @version 1.0 + */ +const struct SensorInterface *NewSensorInterfaceInstance(void); + +/** + * @brief Releases the SensorInterface instance. + * + * @return Returns 0 if the instance is successfully released; + * @return Returns a negative value otherwise. + * + * @since 3.1 + * @version 1.0 + */ +int32_t FreeSensorInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* SENSOR_IF_H */ +/** @} */