diff --git a/en/device_api/light/light_if.h b/en/device_api/light/light_if.h new file mode 100644 index 0000000000000000000000000000000000000000..2c5c41fa1a248a82b138c08742e6370c1fd8752c --- /dev/null +++ b/en/device_api/light/light_if.h @@ -0,0 +1,129 @@ +/* + * Copyright (c) 2022 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 Light + * @{ + * + * @brief Provides APIs for the light service. + * + * The light module provides a unified interface for the light service to access the light driver. + * After obtaining the driver object or proxy, the light service distinguishes light devices by id + * and call related APIs to obtain light information, turn on or off a light, or set the blinking mode. + * + * @since 3.1 + */ + +/** + * @file Light_if.h + * + * @brief Declares common APIs of the light module. These APIs can be used to obtain the light id, + * turn on or off a light, and set the light brightness and blinking mode. + * + * @since 3.1 + */ + +#ifndef LIGHT_IF_H +#define LIGHT_IF_H + +#include +#include "light_type.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief Defines the basic operations that can be performed on lights. + * + * The operations include obtaining light information, turning on or off a light, + * and setting the light brightness or blinking mode. + */ + +struct LightInterface { + /** + * @brief Obtains information about all the lights in the system. + * + * @param lightInfo Indicates the double pointer to the light information. For details, see {@link LightInfo}. + * @param count Indicates the pointer to the number of lights. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 3.1 + */ + int32_t (*GetLightInfo)(struct LightInfo **lightInfo, uint32_t *count); + + /** + * @brief Turns on available lights in the list based on the specified light id. + * + * @param lightId Indicates the light id. For details, see {@link LightId}. + * @param effect Indicates the pointer to the lighting effect, if the lightbrightness field is 0, + * light brightness according to the defaultBrightness configured by HCS. For details, see {@link LightEffect}. + * + * @return Returns 0 if the operation is successful. + * @return Returns -1 if the light id is not supported. + * @return Returns -2 if the blinking setting is not supported. + * @return Returns -3 if the brightness setting is not supported. + * + * @since 3.1 + */ + int32_t (*TurnOnLight)(uint32_t lightId, struct LightEffect *effect); + + /** + * @brief Turns off available lights in the list based on the specified light id. + * + * @param lightId Indicates the light id. For details, see {@link LightId}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 3.1 + */ + int32_t (*TurnOffLight)(uint32_t lightId); +}; + +/** + * @brief Creates a LightInterface instance. + * + * The LightInterface instance created can be used to perform related light control operations. + * + * @return Returns 0 if the operation fails. + * @return Returns a non-zero value if the operation is successful. + * + * @since 3.1 + */ +const struct LightInterface *NewLightInterfaceInstance(void); + +/** + * @brief Releases the LightInterface instance and related resources. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 3.1 + */ +int32_t FreeLightInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* LIGHT_IF_H */ +/** @} */ \ No newline at end of file diff --git a/en/device_api/light/light_type.h b/en/device_api/light/light_type.h new file mode 100644 index 0000000000000000000000000000000000000000..40a8b32dabaf18d9a4f82002d742b625d16fe1a8 --- /dev/null +++ b/en/device_api/light/light_type.h @@ -0,0 +1,150 @@ +/* + * Copyright (c) 2022 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 Light + * @{ + * + * @brief Provides APIs for the light service. + * + * The light module provides a unified interface for the light service to access the light driver. + * After obtaining the light driver object or proxy, the service can call related APIs to obtain light information, + * turn on or off a light, and set the light blinking mode based on the light id. + * @since 3.1 + */ + +/** + * @file light_type.h + * + * @brief Defines the light data structure, including the light id, lighting mode, + * blinking mode and duration, return values, and lighting effect. + * @since 3.1 + */ + +#ifndef LIGHT_TYPE_H +#define LIGHT_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief Enumerates the return values of the light module. + * + * @since 3.1 + */ +enum LightStatus { + /** The operation is successful. */ + LIGHT_SUCCESS = 0, + /** The light id is not supported. */ + LIGHT_NOT_SUPPORT = -1, + /** Blinking setting is not supported. */ + LIGHT_NOT_FLASH = -2, + /** Brightness setting is not supported. */ + LIGHT_NOT_BRIGHTNESS = -3, +}; + +/** + * @brief Enumerates the light ids. + * + * @since 3.1 + */ +enum LightId { + /** Unknown id */ + LIGHT_ID_NONE = 0, + /** Power light */ + LIGHT_ID_BATTERY = 1, + /** Notification light */ + LIGHT_ID_NOTIFICATIONS = 2, + /** Alarm light */ + LIGHT_ID_ATTENTION = 3, + /** Invalid id */ + LIGHT_ID_BUTT = 4, +}; + +/** + * @brief Enumerates the lighting modes. + * + * @since 3.1 + */ +enum LightFlashMode { + /** Steady on */ + LIGHT_FLASH_NONE = 0, + /** Blinking */ + LIGHT_FLASH_TIMED = 1, + /** Invalid mode */ + LIGHT_FLASH_BUTT = 2, +}; + +/** + * @brief Defines the blinking parameters. + * + * The parameters include the blinking mode and the on and off time for the light in a blinking period. + * + * @since 3.1 + */ +struct LightFlashEffect { + /** Blinking mode. For details, see {@link LightFlashMode}. */ + int32_t flashMode; + /** Duration (in ms) for which the light is on in a blinking period. */ + int32_t onTime; + /** Duration (in ms) for which the light is off in a blinking period. */ + int32_t offTime; +}; + +/** + * @brief Defines the lighting effect parameters. + * + * The parameters include the brightness and blinking mode. + * + * @since 3.1 + */ +struct LightEffect { + /** + * Brightness value. Bits 24–31 for extended bit, Bits 16–23 for red, + * bits 8–15 for green, and bits 0–7 for blue. if the byte segment is not equal to 0, + * indicates turn on light of the corresponding color. + */ + int32_t lightBrightness; + /** Blinking mode. For details, see {@link LightFlashEffect}. */ + struct LightFlashEffect flashEffect; +}; + +/** + * @brief Defines the basic light information. + * + * Basic light information includes the light id and custom extended information. + * + * @since 3.1 + */ +struct LightInfo { + /** Light id. For details, see {@link LightId}. */ + uint32_t lightId; + /** Custom extended information. */ + int32_t reserved; +}; + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* LIGHT_TYPE_H */ +/** @} */ diff --git a/en/device_api/sensor/sensor_if.h b/en/device_api/sensor/sensor_if.h new file mode 100644 index 0000000000000000000000000000000000000000..bca34655e1ab30418cd2456e433c8b9d073d91eb --- /dev/null +++ b/en/device_api/sensor/sensor_if.h @@ -0,0 +1,219 @@ +/* + * 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 2.2 + */ + +/** + * @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 2.2 + * @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 Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @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 operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @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 operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @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 operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @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 if the sensor data reporting mode is failed set. + * + * @since 2.2 + * @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 0 if the options are failed set. + * + * @since 2.2 + * @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 Indicates the sensor group ID. + * The sensorId enumeration value range is 128-160, which means that the medical sensor service is subscribed. + * It only needs to be subscribed once successfully, and there is no need to subscribe repeatedly. + * The sensorId enumeration value range is not within 128-160, which means that the traditional sensor + * is subscribed, and the subscription is successful once. + * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. + * + * @return Returns 0 if the callback is successfully registered. + * @return Returns a negative value if the callback is failed registered.. + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Register)(int32_t groupId, RecordDataCallback cb); + + /** + * @brief Deregisters the callback for reporting sensor data. + * + * @param groupId Indicates the sensor group ID. + * The sensorId enumeration value range is 128-160, which means that the medical sensor service is subscribed. + * It only needs to cancel the subscription once successfully, and there is no need to + * cancel the subscription repeatedly. The sensorId enumeration value range is not within 128-160, + * which means that the traditional sensor is subscribed. You can cancel the subscription once successfully. + * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. + * + * @return Returns 0 if the callback is successfully deregistered. + * @return Returns a negative value if the callback is failed deregistered. + * + * @since 2.2 + * @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 a negative value if the instance is failed created. + * + * @since 2.2 + * @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 if the instance is failed released. + * + * @since 2.2 + * @version 1.0 + */ +int32_t FreeSensorInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* SENSOR_IF_H */ +/** @} */ diff --git a/en/device_api/sensor/sensor_type.h b/en/device_api/sensor/sensor_type.h new file mode 100644 index 0000000000000000000000000000000000000000..c7af7feddc2101d3b184f34b178f7b54a2f7a6e8 --- /dev/null +++ b/en/device_api/sensor/sensor_type.h @@ -0,0 +1,291 @@ +/* + * 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. + * + * @version 1.0 + */ + +/** + * @file sensor_type.h + * + * @brief Defines the data used by the sensor module, including the sensor types, sensor information, + * and reported sensor data. + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef SENSOR_TYPE_H +#define SENSOR_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/**< Maximum length of the sensor name */ +#define SENSOR_NAME_MAX_LEN 32 +/**< Maximum length of the sensor version */ +#define SENSOR_VERSION_MAX_LEN 16 + +/** + * @brief Enumerates return values of the sensor module. + * + * @since 2.2 + */ +enum SensorStatus { + /**< The operation is successful. */ + SENSOR_SUCCESS = 0, + /**< The operation failed. */ + SENSOR_FAILURE = -1, + /**< The operation is not supported. */ + SENSOR_NOT_SUPPORT = -2, + /**< The sensor parameter is invalid. */ + SENSOR_INVALID_PARAM = -3, + /**< The sensor service is invalid. */ + SENSOR_INVALID_SERVICE = -4, + /**< The pointer is null. */ + SENSOR_NULL_PTR = -5, +}; + +/** + * @brief Enumerates sensor types. + * + * @since 2.2 + */ +enum SensorTypeTag { + /**< None, for testing only */ + SENSOR_TYPE_NONE = 0, + /**< Acceleration sensor */ + SENSOR_TYPE_ACCELEROMETER = 1, + /**< Gyroscope sensor */ + SENSOR_TYPE_GYROSCOPE = 2, + /**< Photoplethysmography sensor */ + SENSOR_TYPE_PHOTOPLETHYSMOGRAPH = 3, + /**< Electrocardiogram (ECG) sensor */ + SENSOR_TYPE_ELECTROCARDIOGRAPH = 4, + /**< Ambient light sensor */ + SENSOR_TYPE_AMBIENT_LIGHT = 5, + /**< Magnetic field sensor */ + SENSOR_TYPE_MAGNETIC_FIELD = 6, + /**< Capacitive sensor */ + SENSOR_TYPE_CAPACITIVE = 7, + /**< Barometric pressure sensor */ + SENSOR_TYPE_BAROMETER = 8, + /**< Temperature sensor */ + SENSOR_TYPE_TEMPERATURE = 9, + /**< Hall effect sensor */ + SENSOR_TYPE_HALL = 10, + /**< Gesture sensor */ + SENSOR_TYPE_GESTURE = 11, + /**< Proximity sensor */ + SENSOR_TYPE_PROXIMITY = 12, + /**< Humidity sensor */ + SENSOR_TYPE_HUMIDITY = 13, + /**< The begin of medical sensorId enumeration value range */ + SENSOR_TYPE_MEDICAL_BEGIN = 128, + /**< The end of medical sensorId enumeration value range */ + SENSOR_TYPE_MEDICAL_END = 160, + /**< Maximum type of a physical sensor */ + SENSOR_TYPE_PHYSICAL_MAX = 255, + /**< Orientation sensor */ + SENSOR_TYPE_ORIENTATION = 256, + /**< Gravity sensor */ + SENSOR_TYPE_GRAVITY = 257, + /**< Linear acceleration sensor */ + SENSOR_TYPE_LINEAR_ACCELERATION = 258, + /**< Rotation vector sensor */ + SENSOR_TYPE_ROTATION_VECTOR = 259, + /**< Ambient temperature sensor */ + SENSOR_TYPE_AMBIENT_TEMPERATURE = 260, + /**< Uncalibrated magnetic field sensor */ + SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 261, + /**< Game rotation vector sensor */ + SENSOR_TYPE_GAME_ROTATION_VECTOR = 262, + /**< Uncalibrated gyroscope sensor */ + SENSOR_TYPE_GYROSCOPE_UNCALIBRATED = 263, + /**< Significant motion sensor */ + SENSOR_TYPE_SIGNIFICANT_MOTION = 264, + /**< Pedometer detection sensor */ + SENSOR_TYPE_PEDOMETER_DETECTION = 265, + /**< Pedometer sensor */ + SENSOR_TYPE_PEDOMETER = 266, + /**< Geomagnetic rotation vector sensor */ + SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 277, + /**< Heart rate sensor */ + SENSOR_TYPE_HEART_RATE = 278, + /**< Device orientation sensor */ + SENSOR_TYPE_DEVICE_ORIENTATION = 279, + /**< Wear detection sensor */ + SENSOR_TYPE_WEAR_DETECTION = 280, + /**< Uncalibrated acceleration sensor */ + SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED = 281, + /**< Maximum number of sensor types */ + SENSOR_TYPE_MAX, +}; + +/** + * @brief Enumerates accuracy types of sensors. + * + * @since 2.2 + */ +enum SensorAccuracyType { + /**< No accuracy */ + SENSOR_NO_ACCURACY = 0, + /**< Low accuracy */ + SENSOR_LOW_ACCURACY = 1, + /**< Medium accuracy */ + SENSOR_MEDIUM_ACCURACY = 2, + /**< High accuracy */ + SENSOR_HIGH_ACCURACY = 3, + /**< Maximum accuracy */ + SENSOR_MAX_ACCURACY, +}; + +/** + * @brief Enumerates measurement ranges of sensors. + * + * @since 2.2 + */ +enum SensorRangeType { + /**< Measurement range level 1 */ + SENSOR_RANGE_LEVEL1 = 0, + /**< Measurement range level 2 */ + SENSOR_RANGE_LEVEL2 = 1, + /**< Measurement range level 3 */ + SENSOR_RANGE_LEVEL3 = 2, + /**< Maximum measurement range level */ + SENSOR_RANGE_LEVEL_MAX, +}; + +/** + * @brief Enumerates data reporting modes of sensors. + * + * @since 2.2 + */ +enum SensorModeType { + /**< Default data reporting mode */ + SENSOR_MODE_DEFAULT = 0, + /**< Real-time data reporting mode to report a group of data each time */ + SENSOR_MODE_REALTIME = 1, + /**< Real-time data reporting mode to report data upon status changes */ + SENSOR_MODE_ON_CHANGE = 2, + /**< Real-time data reporting mode to report data only once */ + SENSOR_MODE_ONE_SHOT = 3, + /**< FIFO-based data reporting mode to report data based on the configured cache size */ + SENSOR_MODE_FIFO_MODE = 4, + /**< Maximum sensor data reporting mode */ + SENSOR_MODE_MAX, +}; + +/** + * @brief Enumerates hardware service group for sensors. + * + * @since 2.2 + */ +enum SensorGroupType { + /**< traditional sensor type, the sensorId enumeration value range is 128-160 */ + TRADITIONAL_SENSOR_TYPE = 0, + /**< medical sensor type, the sensorId enumeration value range is not within 128-160 */ + MEDICAL_SENSOR_TYPE = 1, + /**< Maximum sensor type */ + SENSOR_GROUP_TYPE_MAX, +}; + +/** + * @brief Defines basic sensor information. + * + * Information about a sensor includes the sensor name, vendor, firmware version, hardware version, sensor type ID, + * sensor ID, maximum measurement range, accuracy, and power. + * + * @since 2.2 + */ +struct SensorInformation { + /**< Sensor name */ + char sensorName[SENSOR_NAME_MAX_LEN]; + /**< Sensor vendor */ + char vendorName[SENSOR_NAME_MAX_LEN]; + /**< Sensor firmware version */ + char firmwareVersion[SENSOR_VERSION_MAX_LEN]; + /**< Sensor hardware version */ + char hardwareVersion[SENSOR_VERSION_MAX_LEN]; + /**< Sensor type ID (described in {@link SensorTypeTag}) */ + int32_t sensorTypeId; + /**< Sensor ID, defined by the sensor driver developer */ + int32_t sensorId; + /**< Maximum measurement range of the sensor */ + float maxRange; + /**< Sensor accuracy */ + float accuracy; + /**< Sensor power */ + float power; +}; + +/** + * @brief Defines the data reported by the sensor. + * + * The reported sensor data includes the sensor ID, sensor algorithm version, data generation time, + * data options (such as the measurement range and accuracy), data reporting mode, data address, and data length. + * + * @since 2.2 + */ +struct SensorEvents { + /**< Sensor ID */ + int32_t sensorId; + /**< Sensor algorithm version */ + int32_t version; + /**< Time when sensor data was generated */ + int64_t timestamp; + /**< Sensor data options, including the measurement range and accuracy */ + uint32_t option; + /**< Sensor data reporting mode */ + int32_t mode; + /**< Sensor data address */ + uint8_t *data; + /**< Sensor data length */ + uint32_t dataLen; +}; + +/** + * @brief Defines the callback for reporting sensor data. This callback needs to be registered when + * a sensor user subscribes to sensor data. Only after the sensor is enabled, the sensor data subscriber can receive + * sensor data. For details, see {@link SensorInterface}. + * + * @since 2.2 + */ +typedef int32_t (*RecordDataCallback)(const struct SensorEvents*); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* SENSOR_TYPE_H */ +/** @} */ + diff --git a/en/device_api/vibrator/vibrator_if.h b/en/device_api/vibrator/vibrator_if.h new file mode 100644 index 0000000000000000000000000000000000000000..16f1b5502f611842a5f36eca6b7f0171644a4a37 --- /dev/null +++ b/en/device_api/vibrator/vibrator_if.h @@ -0,0 +1,133 @@ +/* + * 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 Vibrator + * @{ + * + * @brief Provides a driver for upper-layer vibrator services. + * + * After obtaining a driver object or agent, a vibrator service starts or stops the vibrator + * using the functions provided by the driver object or agent. + * + * @since 2.2 + */ + +/** + * @file vibrator_if.h + * + * @brief Declares common APIs in the vibrator module. The APIs can be used to control + * the vibrator to perform a one-shot or periodic vibration. + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef VIBRATOR_IF_H +#define VIBRATOR_IF_H + +#include +#include "vibrator_type.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +struct VibratorInterface { + /** + * @brief Controls the vibrator to perform a one-shot vibration that lasts for a given duration. + * + * One-shot vibration is mutually exclusive with periodic vibration. Before using one-shot vibration, + * exit periodic vibration. + * + * @param duration Indicates the duration that the one-shot vibration lasts, in milliseconds. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*StartOnce)(uint32_t duration); + + /** + * @brief Controls the vibrator to perform a periodic vibration with the preset effect. + * + * One-shot vibration is mutually exclusive with periodic vibration. Before using periodic vibration, + * exit one-shot vibration. + * + * @param effectType Indicates the pointer to the preset effect type. It is recommended that the + * maximum length be 64 bytes. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Start)(const char *effectType); + + /** + * @brief Stops the vibration. + * + * Before the vibrator starts, it must stop vibrating in any mode. This function can be used during + * and after the vibrating process. + * + * @param mode Indicates the vibration mode, which can be one-shot or periodic. For details, + * see {@link VibratorMode}. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Stop)(enum VibratorMode mode); +}; + +/** + * @brief Creates a VibratorInterface instance. + * + * The obtained VibratorInterface instance can be used to control the vibrator to vibrate as configured. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @version 1.0 + */ +const struct VibratorInterface *NewVibratorInterfaceInstance(void); + +/** + * @brief Releases this VibratorInterface instance to free up related resources. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 2.2 + * @version 1.0 + */ +int32_t FreeVibratorInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* VIBRATOR_IF_H */ +/** @} */ diff --git a/en/device_api/vibrator/vibrator_type.h b/en/device_api/vibrator/vibrator_type.h new file mode 100644 index 0000000000000000000000000000000000000000..d541228f8e452341e7150a035e836c0d838739d3 --- /dev/null +++ b/en/device_api/vibrator/vibrator_type.h @@ -0,0 +1,69 @@ +/* + * 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 Vibrator + * @{ + * + * @brief Provides unified APIs for vibrator services to access the vibrator driver. + * + * After obtaining a driver object or agent, a vibrator service starts or stops the vibrator + * using the functions provided by the driver object or agent. + * + * @version 1.0 + */ + +/** + * @file vibrator_type.h + * + * @brief Defines the vibrator data structure, including the vibration mode and effect type. + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef VIBRATOR_TYPE_H +#define VIBRATOR_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief Enumerates the vibration modes of this vibrator. + * + * @since 2.2 + */ +enum VibratorMode { + /** Indicates the one-shot vibration with the given duration. */ + VIBRATOR_MODE_ONCE = 0, + /** Indicates the periodic vibration with the preset effect. */ + VIBRATOR_MODE_PRESET = 1, + /** Indicates invalid the effect mode. */ + VIBRATOR_MODE_BUTT +}; + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* VIBRATOR_TYPE_H */ +/** @} */ diff --git a/zh-cn/device_api/light/light.type.h b/zh-cn/device_api/light/light.type.h new file mode 100644 index 0000000000000000000000000000000000000000..b00e75861c06e83f44bbf01a2fbb39014b956465 --- /dev/null +++ b/zh-cn/device_api/light/light.type.h @@ -0,0 +1,150 @@ +/* + * Copyright (c) 2022 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 灯 + * @{ + * + * @brief 灯模块对灯服务提供通用的接口能力。 + * + * 灯模块为灯服务提供通用的接口去访问灯驱动。 + * 服务获取灯驱动对象或代理后,可以调用相关的APIs接口获取灯信息。 + * 打开或关闭灯,并根据灯id设置灯闪烁模式。 + * + * @since 3.1 + */ + +/** + * @file Light_if.h + * + * @brief 定义灯的数据结构,包括灯id,灯的模式,灯的闪烁模式和持续时间,灯的状态,灯的效果。 + * @since 3.1 + */ + +#ifndef LIGHT_TYPE_H +#define LIGHT_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief 枚举灯模块的状态值。 + * @since 3.1 + */ + +enum LightStatus { + /** 操作成功 */ + LIGHT_SUCCESS = 0, + /** 灯id不支持 */ + LIGHT_NOT_SUPPORT = -1, + /** 设置闪烁不支持 */ + LIGHT_NOT_FLASH = -2, + /** 设置亮度不支持 */ + LIGHT_NOT_BRIGHTNESS = -3, +}; + +/** + * @brief 枚举灯ids + * + * @since 3.1 + */ +enum LightId { + /** 未知id */ + LIGHT_ID_NONE = 0, + /** 电源指示灯 */ + LIGHT_ID_BATTERY = 1, + /** 通知灯 */ + LIGHT_ID_NOTIFICATIONS = 2, + /** 报警灯 */ + LIGHT_ID_ATTENTION = 3, + /** 无效id */ + LIGHT_ID_BUTT = 4, +}; + +/** + * @brief 枚举灯的模式 + * + * @since 3.1 + */ +enum LightFlashMode { + /** 常亮 */ + LIGHT_FLASH_NONE = 0, + /** 闪烁 */ + LIGHT_FLASH_TIMED = 1, + /** 无效模式 */ + LIGHT_FLASH_BUTT = 2, +}; + +/** + * @brief 定义闪烁参数。 + * + * 这些参数包括闪烁模式以及闪烁期间指示灯的打开和关闭时间。 + * + * @since 3.1 + */ +struct LightFlashEffect { + /** 闪烁模式。详见{@link LightFlashMode}. */ + int32_t flashMode; + /** 表示灯在闪烁期间点亮时持续的时间(毫秒)。 */ + int32_t onTime; + /** 表示灯在闪烁期间熄灭时持续的时间(毫秒)。 */ + int32_t offTime; +}; + +/** + * @brief 定义灯的效果参数。 + * + * 参数包括亮度和闪烁模式。 + * + * @since 3.1 + */ +struct LightEffect { + /** + * 亮度值:Bits 24–31为扩展位,Bits 16–23为红色,bits 8–15为绿色,bits 0–7为蓝色。 + * 如果字节段不等于0,指示打开相应颜色的灯。 + */ + int32_t lightBrightness; + /** 闪烁模式。详见{@link LightFlashEffect}. */ + struct LightFlashEffect flashEffect; +}; + +/** + * @brief 定义灯的基本信息。 + * + * 基本的灯信息包括灯id和自定义扩展信息。 + * + * @since 3.1 + */ +struct LightInfo { + /** 灯id。 详见{@link LightId}. */ + uint32_t lightId; + /** 自定义扩展信息。 */ + int32_t reserved; +}; + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* LIGHT_TYPE_H */ +/** @} */ + diff --git a/zh-cn/device_api/light/light_if.h b/zh-cn/device_api/light/light_if.h new file mode 100644 index 0000000000000000000000000000000000000000..4c3d87fec0e09741177552f5ac4bbd1c6019d555 --- /dev/null +++ b/zh-cn/device_api/light/light_if.h @@ -0,0 +1,126 @@ +/* + * Copyright (c) 2022 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 灯 + * @{ + * + * @brief 灯模块对灯服务提供通用的接口能力。 + * + * 灯模块为灯服务提供通用的接口去访问灯驱动。 + * 服务获取灯驱动对象或代理后,可以调用相关的APIs接口获取灯信息。 + * 打开或关闭灯,并根据灯id设置灯闪烁模式。 + * + * @since 3.1 + */ + +/** + * @file Light_if.h + * + * @brief 定义灯的数据结构,包括灯id,灯的模式,灯的闪烁模式和持续时间,操作灯返回的状态,灯的效果。 + * @since 3.1 + */ + +#ifndef LIGHT_IF_H +#define LIGHT_IF_H + +#include +#include "light_type.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief 定义可以在灯上执行的基本操作。 + * + * 操作包括获取灯的信息, 打开或关闭灯,设置灯的亮度或闪烁模式。 + */ + +struct LightInterface { + /** + * @brief 获取当前系统中所有类型的灯信息。 + * + * @param lightInfo 表示指向灯信息的二级指针。详见{@link LightInfo}。 + * @param count 表示指向灯数量的指针。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 3.1 + */ + int32_t (*GetLightInfo)(struct LightInfo **lightInfo, uint32_t *count); + + /** + * @brief 根据指定的灯id打开列表中的可用灯。 + * + * @param lightId 表示灯id。详见{@link LightId}。 + * @param effect 表示指向灯效果的指针,如果lightbrightness字段为0时, + * 灯的亮度根据HCS配置的默认亮度进行设置。详见{@link LightEffect}。 + * + * @return 如果操作成功,则返回0。 + * @return 如果不支持灯id,则返回-1。 + * @return 如果不支持闪烁设置,则返回-2。 + * @return 如果不支持亮度设置,则返回3。 + * + * @since 3.1 + */ + int32_t (*TurnOnLight)(uint32_t lightId, struct LightEffect *effect); + + /** + * @brief 根据指定的灯id打开列表中的可用灯。 + * + * @param lightId 表示灯id。详见{@link LightId}。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 3.1 + */ + int32_t (*TurnOffLight)(uint32_t lightId); +}; + +/** + * @brief 创建LightInterface实例。 + * + * 创建的LightInterface实例可用于执行相关的灯控制操作。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 3.1 + */ +const struct LightInterface *NewLightInterfaceInstance(void); + +/** + * @brief 释放LightInterface实例和相关资源。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 3.1 + */ +int32_t FreeLightInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* LIGHT_IF_H */ +/** @} */ \ No newline at end of file diff --git a/zh-cn/device_api/sensor/sensor_if.h b/zh-cn/device_api/sensor/sensor_if.h new file mode 100644 index 0000000000000000000000000000000000000000..469246148a1992029f35e013e5d7ddcc5fed0467 --- /dev/null +++ b/zh-cn/device_api/sensor/sensor_if.h @@ -0,0 +1,207 @@ +/* + * 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 传感器 + * @{ + * + * @brief 传感器设备驱动对传感器服务提供通用的接口能力。 + * + * 模块提供传感器服务对传感器驱动访问统一接口,服务获取驱动对象或者代理后,通过其提供的各类方法,实现获取传感器设备信息、订阅/去订阅传感器数据、 + * 使能/去使能传感器、设置传感器模式、设置传感器精度,量程等可选配置等。 + * + * @since 2.2 + */ + +/** + * @file sensor_if.h + * + * @brief Sensor模块对外通用的接口声明文件,提供获取传感器设备信息、订阅/去订阅传感器数据、 + * 使能/去使能传感器、设置传感器模式、设置传感器精度,量程等可选配置接口定义。 + * + * @since 2.2 + * @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 提供sensor设备基本控制操作接口。 + * + * 结构体提供获取传感器设备信息、订阅/去订阅传感器数据、 + * 使能/去使能传感器、设置传感器模式、设置传感器精度,量程等可选配置接口定义。 + */ +struct SensorInterface { + /** + * @brief 获取当前系统中所有类型的传感器信息。 + * + * @param sensorInfo 输出系统中注册的所有传感器信息,一种类型传感器信息包括传感器名字、设备厂商、 + * 固件版本号、硬件版本号、传感器类型编号、传感器标识、最大量程、精度、功耗。详见{@link SensorInformation}。 + * @param count 输出系统中注册的传感器数量。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*GetAllSensors)(struct SensorInformation **sensorInfo, int32_t *count); + + /** + * @brief 根据传感器设备类型标识使能传感器信息列表里存在的设备,只有数据订阅者使能传感器后,才能获取订阅的传感器数据。 + * + * @param sensorId 唯一标识一个传感器设备类型。详见{@link SensorTypeTag}。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Enable)(int32_t sensorId); + + /** + * @brief 去使能一种传感器设备。 + * + * @param sensorId 唯一标识一个传感器设备类型。详见{@link SensorTypeTag}。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Disable)(int32_t sensorId); + + /** + * @brief 设置指定传感器的数据采样间隔和数据上报间隔。 + * + * @param sensorId 唯一标识一个传感器设备类型。详见{@link SensorTypeTag}。 + * @param samplingInterval 设置指定传感器的数据采样间隔,单位纳秒。 + * @param reportInterval 表示传感器数据上报间隔,单位纳秒。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*SetBatch)(int32_t sensorId, int64_t samplingInterval, int64_t reportInterval); + + /** + * @brief 设置指定传感器的数据上报模式,不同的工作模式,上报数据的方式不同。 + * + * @param sensorId 唯一标识一个传感器设备类型。详见{@link SensorTypeTag}。 + * @param mode 传感器的数据上报模式。详见{@link SensorModeType}。 + * + * @return 如果设置传感器数据报告模式成功,则返回0。 + * @return 如果设置传感器数据报告模式失败,则返回负数。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*SetMode)(int32_t sensorId, int32_t mode); + + /** + * @brief 设置指定传感器量程,精度等可选配置。 + * + * @param sensorId 唯一标识一个传感器设备类型。详见{@link SensorTypeTag}。 + * @param option 传感器的量程,精度等配置。 + * + * @return 如果设置参数成功,则返回0。 + * @return 如果设置参数失败,则返回负数。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*SetOption)(int32_t sensorId, uint32_t option); + + /** + * @brief 订阅者注册传感器数据回调函数,系统会将获取到的传感器数据上报给订阅者。 + * + * @param groupId 传感器组ID。 + * sensorId枚举值范围为128-160,表示已订阅医疗传感器服务,只需成功订阅一次,无需重复订阅。 + + * sensorId枚举值范围不在128-160之间,这意味着传统传感器已订阅,并且订阅成功一次。 + * @param cb 要注册的回调函数。详见{@link RecordDataCallback}。 + * + * @return 如果注册回调函数成功,则返回0。 + * @return 如果注册回调函数失败,则返回负数。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Register)(int32_t groupId, RecordDataCallback cb); + + /** + * @brief 订阅者去注册传感器数据回调函数。 + * + * @param groupId 传感器组ID。 + * sensorId枚举值范围为128-160,表示已订阅医疗传感器服务。只需成功取消订阅一次,无需重复取消订阅。 + * sensorId枚举值范围不在128-160之间,这意味着传统传感器已订阅。并且成功取消订阅。 + * @param cb 要注册的回调函数。详见{@link RecordDataCallback}。 + * + * @return 如果取消注册回调函数成功,则返回0。 + * @return 如果取消注册回调函数失败,则返回负数。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Unregister)(int32_t groupId, RecordDataCallback cb); +}; + +/** + * @brief 创建传感器接口实例。 + * + * @param sensorId 表示传感器ID。有关详细信息,请参阅{@link SensorTypeTag}。 + * 可以使用该实例获取传感器信息,订阅或取消订阅传感器数据,打开或关闭传感器, + * 设置传感器数据报告模式,并设置传感器参数,如精度和测量范围。 + * @param cb 表示要注册的回调函数。有关详细信息,请参阅{@link RecordDataCallback}。 + * + * @return 如果创建实例成功,则返回非零值。 + * @return 如果创建实例失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ +const struct SensorInterface *NewSensorInterfaceInstance(void); + +/** + * @brief 释放传感器接口实例。 + * + * @return 如果释放实例成功,则返回0。 + * @return 如果释放实例失败,则返回负值。 + * @since 2.2 + * @version 1.0 + */ +int32_t FreeSensorInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* SENSOR_IF_H */ +/** @} */ diff --git a/zh-cn/device_api/sensor/sensor_type.h b/zh-cn/device_api/sensor/sensor_type.h new file mode 100644 index 0000000000000000000000000000000000000000..4cfeb65d445cd98373c77db9947de7367aff7e5c --- /dev/null +++ b/zh-cn/device_api/sensor/sensor_type.h @@ -0,0 +1,285 @@ +/* + * 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 传感器 + * @{ + * + * @brief 传感器设备驱动对传感器服务提供通用的接口能力。 + * + * 模块提供传感器服务对传感器驱动访问统一接口,服务获取驱动对象或者代理后, + * 通过其提供的各类方法,以传感器id区分访问不同类型传感器设备,实现获取传感器设备信息、订阅/去订阅传感器数据、 + * 使能/去使能传感器、设置传感器模式、设置传感器精度,量程等可选配置等。 + * + * @version 1.0 + */ + +/** + * @file sensor_type.h + * + * @brief 定义传感器模块所使用的传感器类型,传感器信息,传感器数据结构等数据类型。 + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef SENSOR_TYPE_H +#define SENSOR_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/**< 传感器名称的最大长度 */ +#define SENSOR_NAME_MAX_LEN 32 +/**< 传感器版本的最大长度 */ +#define SENSOR_VERSION_MAX_LEN 16 + +/** + * @brief 定义传感器模块返回值类型。 + * + * @since 2.2 + */ +enum SensorStatus { + /**< 传感器执行成功 */ + SENSOR_SUCCESS = 0, + /**< 传感器执行失败 */ + SENSOR_FAILURE = -1, + /**< 传感器不支持 */ + SENSOR_NOT_SUPPORT = -2, + /**< 传感器无效参数 */ + SENSOR_INVALID_PARAM = -3, + /**< 传感器无效服务 */ + SENSOR_INVALID_SERVICE = -4, + /**< 传感器空指针 */ + SENSOR_NULL_PTR = -5, +}; + +/** + * @brief 定义传感器类型标识。 + * + * @since 2.2 + */ +enum SensorTypeTag { + /**< 空传感器类型,用于测试 */ + SENSOR_TYPE_NONE = 0, + /**< 加速度传感器 */ + SENSOR_TYPE_ACCELEROMETER = 1, + /**< 陀螺仪传感器 */ + SENSOR_TYPE_GYROSCOPE = 2, + /**< 心率传感器 */ + SENSOR_TYPE_PHOTOPLETHYSMOGRAPH = 3, + /**< 心电传感器 */ + SENSOR_TYPE_ELECTROCARDIOGRAPH = 4, + /**< 环境光传感器 */ + SENSOR_TYPE_AMBIENT_LIGHT = 5, + /**< 地磁传感器 */ + SENSOR_TYPE_MAGNETIC_FIELD = 6, + /**< 电容传感器 */ + SENSOR_TYPE_CAPACITIVE = 7, + /**< 气压计传感器 */ + SENSOR_TYPE_BAROMETER = 8, + /**< 温度传感器 */ + SENSOR_TYPE_TEMPERATURE = 9, + /**< 霍尔传感器 */ + SENSOR_TYPE_HALL = 10, + /**< 手势传感器 */ + SENSOR_TYPE_GESTURE = 11, + /**< 接近光传感器 */ + SENSOR_TYPE_PROXIMITY = 12, + /**< 湿度传感器 */ + SENSOR_TYPE_HUMIDITY = 13, + /**< 医疗传感器ID枚举值范围的开始 */ + SENSOR_TYPE_MEDICAL_BEGIN = 128, + /**< 医疗传感器ID枚举值范围的结束 */ + SENSOR_TYPE_MEDICAL_END = 160, + /**< 物理传感器最大类型 */ + SENSOR_TYPE_PHYSICAL_MAX = 255, + /**< 方向传感器 */ + SENSOR_TYPE_ORIENTATION = 256, + /**< 重力传感器 */ + SENSOR_TYPE_GRAVITY = 257, + /**< 线性加速度传感器 */ + SENSOR_TYPE_LINEAR_ACCELERATION = 258, + /**< 旋转矢量传感器 */ + SENSOR_TYPE_ROTATION_VECTOR = 259, + /**< 环境温度传感器 */ + SENSOR_TYPE_AMBIENT_TEMPERATURE = 260, + /**< 未校准磁场传感器 */ + SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 261, + /**< 游戏旋转矢量传感器 */ + SENSOR_TYPE_GAME_ROTATION_VECTOR = 262, + /**< 未校准陀螺仪传感器 */ + SENSOR_TYPE_GYROSCOPE_UNCALIBRATED = 263, + /**< 大幅度动作传感器 */ + SENSOR_TYPE_SIGNIFICANT_MOTION = 264, + /**< 计步器检测传感器 */ + SENSOR_TYPE_PEDOMETER_DETECTION = 265, + /**< 计步器传感器 */ + SENSOR_TYPE_PEDOMETER = 266, + /**< 地磁旋转矢量传感器 */ + SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 277, + /**< 心率传感器 */ + SENSOR_TYPE_HEART_RATE = 278, + /**< 设备方向传感器 */ + SENSOR_TYPE_DEVICE_ORIENTATION = 279, + /**< 佩戴检测传感器 */ + SENSOR_TYPE_WEAR_DETECTION = 280, + /**< 未校准加速度传感器 */ + SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED = 281, + /**< 传感器类型最大个数标r */ + SENSOR_TYPE_MAX, +}; + +/** + * @brief 传感器的精度类型。 + * + * @since 2.2 + */ +enum SensorAccuracyType { + /**< 无精度类型 */ + SENSOR_NO_ACCURACY = 0, + /**< 低精度类型 */ + SENSOR_LOW_ACCURACY = 1, + /**< 中等精度类型 */ + SENSOR_MEDIUM_ACCURACY = 2, + /**< 高精度类型 */ + SENSOR_HIGH_ACCURACY = 3, + /**< 最大精度类型 */ + SENSOR_MAX_ACCURACY, +}; + +/** + * @brief 传感器的量程级别。 + * + * @since 2.2 + */ +enum SensorRangeType { + /**< 量程级别1 */ + SENSOR_RANGE_LEVEL1 = 0, + /**< 量程级别2 */ + SENSOR_RANGE_LEVEL2 = 1, + /**< 量程级别3 */ + SENSOR_RANGE_LEVEL3 = 2, + /**< 量程最大级别 */ + SENSOR_RANGE_LEVEL_MAX, +}; + +/** + * @brief 传感器的工作模式。 + * + * @since 2.2 + */ +enum SensorModeType { + /**< 传感器默认工作模式状态 */ + SENSOR_MODE_DEFAULT = 0, + /**< 传感器实时工作模式状态,一组数据上报一次 */ + SENSOR_MODE_REALTIME = 1, + /**< 传感器实时工作模式状态,状态变更上报一次 */ + SENSOR_MODE_ON_CHANGE = 2, + /**< 传感器实时工作模式状态,只上报一次 */ + SENSOR_MODE_ONE_SHOT = 3, + /**< 传感器缓存工作模式状态,根据配置的缓存大小上报 */ + SENSOR_MODE_FIFO_MODE = 4, + /**< 传感器最大类型标识 */ + SENSOR_MODE_MAX, +}; + +/** + * @brief 枚举传感器的硬件服务组。 + * + * @since 2.2 + */ +enum SensorGroupType { + /** 传统传感器类型,传感器ID枚举值范围为128-160 */ + TRADITIONAL_SENSOR_TYPE = 0, + /** 医疗传感器类型,传感器ID枚举值范围不在128-160之间 */ + MEDICAL_SENSOR_TYPE = 1, + /** 最大传感器类型 */ + SENSOR_GROUP_TYPE_MAX, +}; + +/** + * @brief 定义传感器基本信息。 + * + * 一个传感器设备信息包括传感器名字、设备厂商、固件版本号、硬件版本号、传感器类型编号、传感器标识、最大量程、精度、功耗。 + * + * @since 2.2 + */ +struct SensorInformation { + /**< 传感器名称 */ + char sensorName[SENSOR_NAME_MAX_LEN]; + /**< 传感器设备厂商 */ + char vendorName[SENSOR_NAME_MAX_LEN]; + /**< 传感器固件版本号 */ + char firmwareVersion[SENSOR_VERSION_MAX_LEN]; + /**< 传感器硬件版本号 */ + char hardwareVersion[SENSOR_VERSION_MAX_LEN]; + /**< 传感器类型编号,唯一标识一个传感器设备类型,详见{@link SensorTypeTag} */ + int32_t sensorTypeId; + /**< 传感器的标识号,有传感器驱动开发者定义 */ + int32_t sensorId; + /**< 传感器的最大量程 */ + float maxRange; + /**< 传感器的精度 */ + float accuracy; + /**< 传感器的功耗 */ + float power; +}; + +/** + * @brief 上报传感器数据结构。。 + * + * 上报传感器设备数据事件信息包括传感器的标识号、传感器算法版本号、传感器数据生成时间、传感器量程精度可选配置、传感器工作模式、传感器数据地址、传感器数据长度。 + * + * @since 2.2 + */ +struct SensorEvents { + /**< 传感器的标识号 */ + int32_t sensorId; + /**< 传感器算法版本号 */ + int32_t version; + /**< 传感器数据生成时间 */ + int64_t timestamp; + /**< 传感器量程精度可选配置 */ + uint32_t option; + /**< 传感器工作模式 */ + int32_t mode; + /**< 传感器数据地址 */ + uint8_t *data; + /**< 传感器数据长度 */ + uint32_t dataLen; +}; + +/** + * @brief 传感器上报数据回调函数的定义,传感器服务用户在订阅传感器时, + * 需要注册上报数据回调函数,传感器使能后,传感器服务用户可以接受到传感器数据,{@link SensorInterface}。 + * + * @since 2.2 + */ +typedef int32_t (*RecordDataCallback)(const struct SensorEvents*); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* SENSOR_TYPE_H */ +/** @} */ \ No newline at end of file diff --git a/zh-cn/device_api/vibrator/vibrator_if.h b/zh-cn/device_api/vibrator/vibrator_if.h new file mode 100644 index 0000000000000000000000000000000000000000..27d13bd147285429cdc5bcb0e99675feba7ed20a --- /dev/null +++ b/zh-cn/device_api/vibrator/vibrator_if.h @@ -0,0 +1,127 @@ +/* + * 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 马达 + * @{ + * + * @brief 马达驱动对马达服务提供通用的接口能力。 + * + * 服务获取驱动对象或者代理后,马达服务启动或停止振动。 + * 通过驱动程序对象或代理提供使用功能。 + * + * @since 2.2 + */ + +/** + * @file vibrator_if.h + * + * @brief 定义马达数据结构,包括马达模式和效果振动。 + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef VIBRATOR_IF_H +#define VIBRATOR_IF_H + +#include +#include "vibrator_type.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +struct VibratorInterface { + /** + * @brief 控制马达以执行给定持续时间的一次性振动。 + * + * 单次振动与周期振动相互排斥。在执行一次性振动之前,需退出周期性振动。 + * + * @param duration 指示一次性振动的持续时间,以毫秒为单位。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*StartOnce)(uint32_t duration); + + /** + * @brief 控制马达以预置效果执行周期性振动。 + * + * 单次振动与周期振动相互排斥。在执行一次性振动之前,需退出周期性振动。 + * + * @param effectType 指向指示预置效果类型的指针。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Start)(const char *effectType); + + /** + * @brief 停止马达振动。 + * + * 马达启动前,必须在任何模式下停止振动。此功能可在振动过程之后。 + * + * @param mode 指示振动模式,可以是一次性或周期性的。详见{@link VibratorMode}。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Stop)(enum VibratorMode mode); +}; + +/** + * @brief 创建一个VibratorInterface实例。 + * + * 获的马达接口实例可用于控制马达按照配置进行振动。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ +const struct VibratorInterface *NewVibratorInterfaceInstance(void); + +/** + * @brief 释放VibratorInterface实例以及释放相关资源。 + * + * @return 如果操作成功,则返回0。 + * @return 如果操作失败,则返回负值。 + * + * @since 2.2 + * @version 1.0 + */ +int32_t FreeVibratorInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* VIBRATOR_IF_H */ +/** @} */ diff --git a/zh-cn/device_api/vibrator/vibrator_type.h b/zh-cn/device_api/vibrator/vibrator_type.h new file mode 100644 index 0000000000000000000000000000000000000000..e6fd7269bca8e6fea66de42f6c30a2742e55ca8c --- /dev/null +++ b/zh-cn/device_api/vibrator/vibrator_type.h @@ -0,0 +1,69 @@ +/* + * 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 马达 + * @{ + * + * @brief 马达驱动对马达服务提供通用的接口能力。 + * + * 服务获取驱动对象或者代理后,马达服务启动或停止振动。 + * 通过驱动程序对象或代理提供使用功能。 + * + * @version 1.0 + */ + +/** + * @file vibrator_type.h + * + * @brief 定义马达数据结构,包括马达模式和效果振动。 + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef VIBRATOR_TYPE_H +#define VIBRATOR_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief 枚举马达振动模式。 + * + * @since 2.2 + */ +enum VibratorMode { + /** 表示给定持续时间内的一次性振动。 */ + VIBRATOR_MODE_ONCE = 0, + /** 表示具有预置效果的周期性振动 */ + VIBRATOR_MODE_PRESET = 1, + /** 表示效果模式无效。 */ + VIBRATOR_MODE_BUTT +}; + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* VIBRATOR_TYPE_H */ +/** @} */ diff --git a/zh-cn/native_sdk/media/image/image_pixel_map_napi.h b/zh-cn/native_sdk/media/image/image_pixel_map_napi.h new file mode 100644 index 0000000000000000000000000000000000000000..3f6c47afe6008f66532e6314c3d7441466c97ae3 --- /dev/null +++ b/zh-cn/native_sdk/media/image/image_pixel_map_napi.h @@ -0,0 +1,145 @@ +/* + * Copyright (C) 2022 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 image + * @{ + * + * @brief 提供获取pixelmap的数据和信息的接口方法。 + * + * @Syscap SystemCapability.Multimedia.Image + * @since 8 + * @version 1.0 + */ + +/** + * @file image_pixel_map_napi.h + * + * @brief 声明可以锁定并访问pixelmap数据的方法,声明解锁的方法. + * + * @since 8 + * @version 1.0 + */ + +#ifndef IMAGE_PIXEL_MAP_NAPI_H +#define IMAGE_PIXEL_MAP_NAPI_H +#include +#include "napi/native_api.h" +#include "napi/native_node_api.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 函数方法返回值的错误码的枚举. + * + * @since 8 + * @version 1.0 + */ +enum { + /** 成功的结果 */ + OHOS_IMAGE_RESULT_SUCCESS = 0, + /** 无效值 */ + OHOS_IMAGE_RESULT_BAD_PARAMETER = -1, +}; + +/** + * @brief pixel 格式的枚举. + * + * @since 8 + * @version 1.0 + */ +enum { + /** + * 未知的格式 + */ + OHOS_PIXEL_MAP_FORMAT_NONE = 0, + /** + * 32-bit RGBA. 由 R, G, B组成,包括 A 都需要占用 8 bits。存储顺序是从高位到地位. + */ + OHOS_PIXEL_MAP_FORMAT_RGBA_8888 = 3, + /** + * 16-bit RGB. 仅由 R, G, B 组成. + * 存储顺序是从高位到地位: 红色占用5 bits,绿色占用6 bits,蓝色占用5 bits. + */ + OHOS_PIXEL_MAP_FORMAT_RGB_565 = 2, +}; + +/** + * @brief 用于定义 pixel map 的相关信息. + * + * @since 8 + * @version 1.0 + */ +struct OhosPixelMapInfo { + /** 图片的宽, 用pixels表示. */ + uint32_t width; + /** 图片的高, 用pixels表示. */ + uint32_t height; + /** 每行的bytes数 */ + uint32_t rowSize; + /** Pixel 的格式 */ + int32_t pixelFormat; +}; + +/** + * @brief 获取 PixelMap 的信息,并记录信息到{@link OhosPixelMapInfo}结构中. + * + * @param env napi的环境指针. + * @param value 应用层的 PixelMap 对象. + * @param info 用于保存信息的指针对象. 更多细节, 参看 {@link OhosPixelMapInfo}. + * @return 如果获取并保存信息成功,则返回0; 如果操作失败,则返回错误码. + * @see OhosPixelMapInfo + * @since 8 + * @version 1.0 + */ +int32_t OH_GetImageInfo(napi_env env, napi_value value, OhosPixelMapInfo *info); + +/** + * @brief 获取PixelMap对象数据的内存地址,并锁定该内存. + * + * 函数执行成功后,*addrPtr就是获取的待访问的内存地址. 访问操作完成后,必须要使用{@link OH_UnAccessPixels}来释放锁, 否则的话资源无法被释放. + * 待解锁后,内存地址就不可以再被访问和操作. + * + * @param env napi的环境指针. + * @param value 应用层的 PixelMap 对象. + * @param addrPtr 用于指向的内存地址的双指针对象. + * @see UnAccessPixels + * @return 操作成功则返回 {@link OHOS_IMAGE_RESULT_SUCCESS}; 如果操作失败,则返回错误码. + * @since 8 + * @version 1.0 + */ +int32_t OH_AccessPixels(napi_env env, napi_value value, void** addrPtr); + +/** + * @brief 释放PixelMap对象数据的内存锁, 用于匹配方法{@link OH_AccessPixels}. + * + * @param env napi的环境指针. + * @param value 应用层的 PixelMap 对象. + * @return 操作成功则返回 {@link OHOS_IMAGE_RESULT_SUCCESS}; 如果操作失败,则返回错误码. + * @see AccessPixels + * @since 8 + * @version 1.0 + */ +int32_t OH_UnAccessPixels(napi_env env, napi_value value); + +#ifdef __cplusplus +}; +#endif + +/** @} */ +#endif // IMAGE_PIXEL_MAP_NAPI_H +