diff --git a/zh-cn/device-dev/driver/API/light_if.h b/zh-cn/device-dev/driver/API/light_if.h new file mode 100644 index 0000000000000000000000000000000000000000..f865567c670a89c9d53101c2a878795194d5c6e2 --- /dev/null +++ b/zh-cn/device-dev/driver/API/light_if.h @@ -0,0 +1,124 @@ +/* + * 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 灯设备驱动对灯服务提供通用的接口能力。 + * + * 模块提供灯服务对灯驱动访问统一接口,服务获取驱动程序对象或代理后, + * 通过其提供的各类方法,以灯类型区分访问不同类型灯设备,实现获取灯设备信息、打开或关闭灯、设置闪烁模式。 + * + * @since 2.2 + */ + +/** + * @file Light_if.h + * + * @brief 在light模块中声明通用API。这些API可用于获取类型、控制灯打开、关闭、亮度和闪烁模式 + * + * @since 2.2 + * @version 1.0 + */ + +#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;否则返回负值 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*GetLightInfo)(struct LightInfo **lightInfo, uint32_t *count); + + /** + * @brief 根据指定的灯类型打开灯列表中可用的灯 + * + * @param type表示灯类型。有关详细信息,请参考{@link LightType} + * + * @param effect表示设置灯的信息。有关详细信息,请参考{@link LightEffect} + * + * @return 命令执行结果:0成功,-1逻辑灯不支持,-2逻辑灯不支持闪烁设置,-3逻辑灯不支持亮度设置 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*TurnOnLight)(uint32_t type, struct LightEffect *effect); + + /** + * @brief 根据指定的灯类型关闭灯列表中可用的灯 + * + * @param type表示灯类型。有关详细信息,请参考{@link LightType} + * + * @return 如果成功关闭则返回0;否则返回负值 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*TurnOffLight)(uint32_t type); +}; + +/** + * @brief 创建一个LightInterface实例。 + * 使用实例获取灯信息,并执行打开、关闭指定类型灯的亮度设置和闪烁模式设置 + * + * @return 已成功创建实例返回一个非零值;否则返回0 + * + * @since 2.2 + * @version 1.0 + */ +const struct LightInterface *NewLightInterfaceInstance(void); + +/** + * @brief 释放LightInterface实例和释放相关资源 + * + * @return 如果操作成功,则返回0;否则返回负值 + * + * @since 2.2 + * @version 1.0 + */ +int32_t FreeLightInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* LIGHT_IF_H */ +/** @} */ diff --git a/zh-cn/device-dev/driver/API/light_type.h b/zh-cn/device-dev/driver/API/light_type.h new file mode 100644 index 0000000000000000000000000000000000000000..7aa9c124ff121627a8f8118d2155bb72104d0a26 --- /dev/null +++ b/zh-cn/device-dev/driver/API/light_type.h @@ -0,0 +1,128 @@ +/* + * 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 灯设备驱动对灯服务提供通用的接口能力。 + * + * 模块提供灯服务对灯驱动访问统一接口,服务获取驱动程序对象或代理后, + * 通过不同灯设备类型,实现获取灯设备信息、打开或关闭灯、设置闪烁模式的操作。 + * + * @since 2.2 + */ + +/** + * @file light_type.h + * + * @brief 定义灯数据结构,包括灯类型、闪烁模式和闪烁时间 + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef LIGHT_TYPE_H +#define LIGHT_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief 枚举灯模块的返回值 + * + * @since 2.2 + */ +enum LightStatus { + LIGHT_SUCCESS = 0, /**< 操作成功 */ + LIGHT_NOT_SUPPORT = -1, /**< 不支持类型错误 */ + LIGHT_NOT_FLASH = -2, /**< 不支持闪烁设置 */ + LIGHT_NOT_BRIGHTNESS = -3, /**< 不支持亮度设置 */ +}; + +/** + * @brief 枚举灯类型 + * + * @since 2.2 + */ +enum LightType { + LIGHT_TYPE_NONE = 0, /**< 不可知的类型 */ + LIGHT_TYPE_BATTERY = 1, /**< 电源灯 */ + LIGHT_TYPE_NOTIFICATIONS = 2, /**< 通知灯 */ + LIGHT_TYPE_ATTENTION = 3, /**< 告警灯 */ + LIGHT_TYPE_BUTT /**< 表示灯的无效类型 */ +}; + +/** + * @brief 枚举灯打开模式 + * + * @since 2.2 + */ +enum LightFlashMode { + LIGHT_FLASH_NONE = 0, /**< 常亮模式 */ + LIGHT_FLASH_TIMED = 1, /**< 闪烁模式 */ + LIGHT_FLASH_BUTT = 2, /**< 表示无效的打开模式 */ +}; + +/** + * @brief 定义灯的闪烁数据 + * + * 数据包括闪烁模式、打开和关闭灯的时间 + * + * @since 2.2 + */ +struct LightFlashEffect { + int32_t flashMode; /**< 闪烁模式,有关详细信息,请参考{@link LightFlashMode} */ + int32_t onTime; /**< 打开持续时间,单位:毫秒 */ + int32_t offTime; /**< 关闭持续时间,单位:毫秒 */ +}; + +/** + * @brief 定义打开灯的效果数据 + * + * 数据包括亮度值,闪烁模式数据 + * + * @since 2.2 + */ +struct LightEffect { + int32_t lightBrightness; /**< 亮度值,RGB最高位bit为1表示颜色RGB:R:16-31位、G:8-15位、B:0-7位 */ + struct LightFlashEffect flashEffect; /**< 闪烁模式数据,有关详细信息,请参考{@link LightFlashEffect} */ +}; + +/** + * @brief 定义获取到灯的基本信息。 + * + * 有关灯的信息包括灯类型、用户定义的扩展信息 + * + * @since 2.2 + */ +struct LightInfo { + uint32_t lightType; /**< 获取到的灯类型,有关详细信息,请参考{@link LightType} */ + int32_t reserved; /**< 用户定义的扩展信息 */ +}; + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* LIGHT_TYPE_H */ +/** @} */