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 id
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 id,
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 id.
71      *
72      * @param lightId Indicates the light id. For details, see {@link LightId}.
73      *
74      * @param effect Indicates the pointer to the lighting effect, if the lightbrightness field is 0,
75      * light brightness according to the defaultBrightness configured by HCS. For details, see {@link LightEffect}.
76      *
77      * @return Returns <b>0</b> if the operation is successful.
78      * @return Returns <b>-1</b> if the light id is not supported.
79      * @return Returns <b>-2</b> if the blinking setting is not supported.
80      * @return Returns <b>-3</b> if the brightness setting is not supported.
81      *
82      * @since 3.1
83      */
84     int32_t (*TurnOnLight)(uint32_t lightId, struct LightEffect *effect);
85 
86     /**
87      * @brief Turn on multiple sub-lights contained in the corresponding light according to the specified light ID.
88      *
89      * @param lightId Indicates the light id. For details, see {@link HdfLightId}.
90      *
91      * @param colors Color and brightness corresponding to multiple lights, see {@link LightColor}.
92      *
93      * @return Returns <b>0</b> if the operation is successful.
94      * @return Returns negative value if the get failed.
95      *
96      * @since 3.2
97      */
98     int32_t (*TurnOnMultiLights)(uint32_t lightId, const struct LightColor *colors, const uint32_t count);
99 
100     /**
101      * @brief Turns off available lights in the list based on the specified light id.
102      *
103      * @param lightId Indicates the light id. For details, see {@link LightId}.
104      *
105      * @return Returns <b>0</b> if the operation is successful.
106      * @return Returns a negative value if the operation fails.
107      *
108      * @since 3.1
109      */
110     int32_t (*TurnOffLight)(uint32_t lightId);
111 };
112 
113 /**
114  * @brief Creates a <b>LightInterface</b> instance.
115  *
116  * The <b>LightInterface</b> instance created can be used to perform related light control operations.
117  *
118  * @return Returns <b>0</b> if the operation fails.
119  * @return Returns a non-zero value if the operation is successful.
120  *
121  * @since 3.1
122  */
123 const struct LightInterface *NewLightInterfaceInstance(void);
124 
125 /**
126  * @brief Releases the <b>LightInterface</b> instance and related resources.
127  *
128  * @return Returns <b>0</b> if the operation is successful.
129  * @return Returns a negative value if the operation fails.
130  *
131  * @since 3.1
132  */
133 int32_t FreeLightInterfaceInstance(void);
134 
135 #ifdef __cplusplus
136 #if __cplusplus
137 }
138 #endif
139 #endif /* __cplusplus */
140 
141 #endif /* LIGHT_IF_H */
142 /** @} */
143