1 /* 2 * Copyright (c) 2022 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 Light 18 * @{ 19 * 20 * @brief Provides APIs for the light service. 21 * 22 * The light module provides a unified interface for the light service to access the light driver. 23 * After obtaining the driver object or proxy, the light service distinguishes light devices by type 24 * and call related APIs to obtain light information, turn on or off a light, or set the blinking mode. 25 * @since 3.1 26 */ 27 28 /** 29 * @file Light_if.h 30 * 31 * @brief Declares common APIs of the light module. These APIs can be used to obtain the light type, 32 * turn on or off a light, and set the light brightness and blinking mode. 33 * @since 3.1 34 */ 35 36 #ifndef LIGHT_IF_H 37 #define LIGHT_IF_H 38 39 #include <stdint.h> 40 #include "light_type.h" 41 42 #ifdef __cplusplus 43 #if __cplusplus 44 extern "C" { 45 #endif 46 #endif /* __cplusplus */ 47 48 /** 49 * @brief Defines the basic operations that can be performed on lights. 50 * 51 * The operations include obtaining light information, turning on or off a light, 52 * and setting the light brightness or blinking mode. 53 */ 54 55 struct LightInterface { 56 /** 57 * @brief Obtains information about all the lights in the system. 58 * 59 * @param lightInfo Indicates the double pointer to the light information. For details, see {@link LightInfo}. 60 * @param count Indicates the pointer to the number of lights. 61 * 62 * @return Returns <b>0</b> if the operation is successful. 63 * @return Returns a negative value if the operation fails. 64 * 65 * @since 3.1 66 */ 67 int32_t (*GetLightInfo)(struct LightInfo **lightInfo, uint32_t *count); 68 69 /** 70 * @brief Turns on available lights in the list based on the specified light type. 71 * 72 * @param lightId Indicates the light type. For details, see {@link LightType}. 73 * 74 * @param effect Indicates the pointer to the lighting effect. For details, see {@link LightEffect}. 75 * 76 * @return Returns <b>0</b> if the operation is successful. 77 * @return Returns <b>-1</b> if the light type is not supported. 78 * @return Returns <b>-2</b> if the blinking setting is not supported. 79 * @return Returns <b>-3</b> if the brightness setting is not supported. 80 * 81 * @since 3.1 82 */ 83 int32_t (*TurnOnLight)(uint32_t lightId, struct LightEffect *effect); 84 85 /** 86 * @brief Turns off available lights in the list based on the specified light type. 87 * 88 * @param lightId Indicates the light type. For details, see {@link LightType}. 89 * 90 * @return Returns <b>0</b> if the operation is successful. 91 * @return Returns a negative value if the operation fails. 92 * 93 * @since 3.1 94 */ 95 int32_t (*TurnOffLight)(uint32_t lightId); 96 }; 97 98 /** 99 * @brief Creates a <b>LightInterface</b> instance. 100 * 101 * The <b>LightInterface</b> instance created can be used to perform related light control operations. 102 * 103 * @return Returns <b>0</b> if the operation fails. 104 * @return Returns a non-zero value if the operation is successful. 105 * 106 * @since 3.1 107 */ 108 const struct LightInterface *NewLightInterfaceInstance(void); 109 110 /** 111 * @brief Releases the <b>LightInterface</b> instance and related resources. 112 * 113 * @return Returns <b>0</b> if the operation is successful. 114 * @return Returns a negative value if the operation fails. 115 * 116 * @since 3.1 117 */ 118 int32_t FreeLightInterfaceInstance(void); 119 120 #ifdef __cplusplus 121 #if __cplusplus 122 } 123 #endif 124 #endif /* __cplusplus */ 125 126 #endif /* LIGHT_IF_H */ 127 /** @} */ 128