1/*
2 * Copyright (c) 2024 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 OH_CommonEvent
18 * @{
19 *
20 * @brief Provides the APIs of common event service.
21 *
22 * @since 12
23 */
24/**
25 * @file oh_commonevent.h
26 *
27 * @brief Declares the APIs to subscribe and unsubscribe common event, and so on.
28 *
29 * @library libohcommonevent.so
30 * @kit BasicServicesKit
31 * @syscap SystemCapability.Notification.CommonEvent
32 * @since 12
33 * @version 1.0
34 */
35
36#ifndef OH_COMMONEVENT_H
37#define OH_COMMONEVENT_H
38
39#include <stdint.h>
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/**
46 * @brief Defines error codes.
47 *
48 * @since 12
49 * @version 1.0
50 */
51typedef enum CommonEvent_ErrCode {
52    /** @error Execution successful. */
53    COMMONEVENT_ERR_OK = 0,
54
55    /** @error permission verification failed. */
56    COMMONEVENT_ERR_PERMISSION_ERROR = 201,
57
58    /** @error invalid input parameter. */
59    COMMONEVENT_ERR_INVALID_PARAMETER = 401,
60
61    /** @error IPC request failed to send. */
62    COMMONEVENT_ERR_SENDING_REQUEST_FAILED = 1500007,
63
64    /** @error Common event service not init. */
65    COMMONEVENT_ERR_INIT_UNDONE = 1500008,
66
67    /** @error The subscriber number exceed system specification */
68    COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED = 1500010,
69
70    /** @error A memory allocation error occurs. */
71    COMMONEVENT_ERR_ALLOC_MEMORY_FAILED = 1500011,
72} CommonEvent_ErrCode;
73
74/**
75 * @brief the information of the subscriber
76 *
77 * @since 12
78 */
79typedef struct CommonEvent_SubscribeInfo CommonEvent_SubscribeInfo;
80
81/**
82 * @brief the subscriber of common event
83 *
84 * @since 12
85 */
86typedef void CommonEvent_Subscriber;
87
88/**
89 * @brief the data of the commonEvent callback
90 *
91 * @since 12
92 */
93typedef struct CommonEvent_RcvData CommonEvent_RcvData;
94
95/**
96 * @brief The description of the parameters in a common event callback data.
97 *
98 * @since 12
99 */
100typedef void CommonEvent_Parameters;
101
102/**
103 * @brief Common event callback.
104 *
105 * @param data common event callback data.
106 * @since 12
107 */
108typedef void (*CommonEvent_ReceiveCallback)(const CommonEvent_RcvData *data);
109
110/**
111 * @brief Create subscribe information.
112 *
113 * @param events Indicates the subscribed events.
114 * @param eventsNum Indicates the subscribed events of number.
115 * @return Returns the CommonEvent_SubscribeInfo, if allocate memory failed, returns null.
116 * @since 12
117 */
118CommonEvent_SubscribeInfo* OH_CommonEvent_CreateSubscribeInfo(const char* events[], int32_t eventsNum);
119
120/**
121 * @brief Set the subscribe information of permission.
122 *
123 * @param info Indicates the subscribed events.
124 * @param permission Indicates the subscribed events of permission.
125 * @return Returns the error code.
126 *         Returns {@link COMMONEVENT_ERR_OK} if the operation is successful.
127 *         Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs.
128 * @since 12
129 */
130CommonEvent_ErrCode OH_CommonEvent_SetPublisherPermission(CommonEvent_SubscribeInfo* info, const char* permission);
131
132/**
133 * @brief Set the subscribe information of bundleName.
134 *
135 * @param info Indicates the subscribed events.
136 * @param bundleName Indicates the subscribed events of bundleName.
137 * @return Returns the error code.
138 *         Returns {@link COMMONEVENT_ERR_OK} if the operation is successful.
139 *         Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER} if a parameter error occurs.
140 * @since 12
141 */
142CommonEvent_ErrCode OH_CommonEvent_SetPublisherBundleName(CommonEvent_SubscribeInfo* info, const char* bundleName);
143
144/**
145 * @brief Destroy the subscribe information.
146 *
147 * @param info Indicates the subscribe info.
148 * @since 12
149 */
150void OH_CommonEvent_DestroySubscribeInfo(CommonEvent_SubscribeInfo* info);
151
152/**
153 * @brief Create a subscriber.
154 *
155 * @param info Indicates the created subscribe Info.
156 * @param callback Indicates the received common event callback.
157 * @return Returns the CommonEvent_Subscriber, if allocate memory failed, returns null.
158 * @since 12
159 */
160CommonEvent_Subscriber* OH_CommonEvent_CreateSubscriber(const CommonEvent_SubscribeInfo* info,
161    CommonEvent_ReceiveCallback callback);
162
163/**
164 * @brief Destory the subscriber.
165 *
166 * @param subscriber Indicates the created subscriber.
167 * @since 12
168 */
169void OH_CommonEvent_DestroySubscriber(CommonEvent_Subscriber* subscriber);
170
171/**
172 * @brief Subscribe event by a subscriber.
173 *
174 * @param subscriber Indicates the subscriber.
175 * @return Returns the error code.
176 *         Returns {@link COMMONEVENT_ERR_OK} if the operation is successful.
177 *         Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid.
178 *         Returns {@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED } if IPC request failed to send.
179 *         Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done.
180 *         Returns {@link COMMONEVENT_ERR_SUBSCRIBER_NUM_EXCEEDED } if the subscriber number is exceeded.
181 *         Returns {@link COMMONEVENT_ERR_ALLOC_MEMORY_FAILED } if a memory allocation error occurs.
182 * @since 12
183 */
184CommonEvent_ErrCode OH_CommonEvent_Subscribe(const CommonEvent_Subscriber* subscriber);
185
186/**
187 * @brief Unsubscribe event by a subscriber.
188 *
189 * @param subscriber Indicates the subscriber.
190 * @return Returns the error code.
191 *         Returns {@link COMMONEVENT_ERR_OK} if the operation is successful.
192 *         Returns {@link COMMONEVENT_ERR_INVALID_PARAMETER } if the input parameter is invalid.
193 *         Returns {@link COMMONEVENT_ERR_SENDING_REQUEST_FAILED } if IPC request failed to send.
194 *         Returns {@link COMMONEVENT_ERR_INIT_UNDONE } if ces not init done.
195 * @since 12
196 */
197CommonEvent_ErrCode OH_CommonEvent_UnSubscribe(const CommonEvent_Subscriber* subscriber);
198
199/**
200 * @brief Get event name from callback data.
201 *
202 * @param rcvData Indicates the event of callback data.
203 * @return Returns the event name.
204 * @since 12
205 */
206const char* OH_CommonEvent_GetEventFromRcvData(const CommonEvent_RcvData* rcvData);
207
208/**
209 * @brief Get event result code from callback data.
210 *
211 * @param rcvData Indicates the event of callback data.
212 * @return Returns the event of result code, default is 0.
213 * @since 12
214 */
215int32_t OH_CommonEvent_GetCodeFromRcvData(const CommonEvent_RcvData* rcvData);
216
217/**
218 * @brief Get event result data from callback data.
219 *
220 * @param rcvData Indicates the event of callback data.
221 * @return Returns the event of result data, default is null.
222 * @since 12
223 */
224const char* OH_CommonEvent_GetDataStrFromRcvData(const CommonEvent_RcvData* rcvData);
225
226/**
227 * @brief Get event bundlename from callback data.
228 *
229 * @param rcvData Indicates the event of callback data.
230 * @return Returns the event of bundlename, default is null.
231 * @since 12
232 */
233const char* OH_CommonEvent_GetBundleNameFromRcvData(const CommonEvent_RcvData* rcvData);
234
235/**
236 * @brief Get event parameters data from callback data.
237 *
238 * @param rcvData Indicates the event of callback data.
239 * @return Returns the event of parameters data, default is null.
240 * @since 12
241 */
242const CommonEvent_Parameters* OH_CommonEvent_GetParametersFromRcvData(const CommonEvent_RcvData* rcvData);
243
244/**
245 * @brief Check whether the parameters contains a key.
246 *
247 * @param rcvData Indicates the event of callback data.
248 * @param key Indicates the key of parameter.
249 * @return Returns the result of check, true means it contains.
250 * @since 12
251 */
252bool OH_CommonEvent_HasKeyInParameters(const CommonEvent_Parameters* para, const char* key);
253
254/**
255 * @brief Get int data from parameters data by key.
256 *
257 * @param rcvData Indicates the event of parameters data.
258 * @param key Indicates the key of parameters data.
259 * @param defaultValue Indicates default return value.
260 * @return Returns the int data of the key in the parameters.
261 * @since 12
262 */
263int OH_CommonEvent_GetIntFromParameters(const CommonEvent_Parameters* para, const char* key, const int defaultValue);
264
265/**
266 * @brief Get int array data from parameters data by key.
267 *
268 * @param rcvData Indicates the event of parameters data.
269 * @param key Indicates the key of parameters data.
270 * @param array Indicates the int array.
271 * @return Returns the length of the array.
272 * @since 12
273 */
274int32_t OH_CommonEvent_GetIntArrayFromParameters(const CommonEvent_Parameters* para, const char* key, int** array);
275
276/**
277 * @brief Get long data from parameters data by key.
278 *
279 * @param rcvData Indicates the event of parameters data.
280 * @param key Indicates the key of parameters data.
281 * @param defaultValue Indicates default return value.
282 * @return Returns the long data of the key in the parameters.
283 * @since 12
284 */
285long OH_CommonEvent_GetLongFromParameters(const CommonEvent_Parameters* para, const char* key, const long defaultValue);
286
287/**
288 * @brief Get long array data from parameters data by key.
289 *
290 * @param rcvData Indicates the event of parameters data.
291 * @param key Indicates the key of parameters data.
292 * @param array Indicates the long array.
293 * @return Returns the length of the array.
294 * @since 12
295 */
296int32_t OH_CommonEvent_GetLongArrayFromParameters(const CommonEvent_Parameters* para, const char* key, long** array);
297
298/**
299 * @brief Get bool data from parameters data by key.
300 *
301 * @param rcvData Indicates the event of parameters data.
302 * @param key Indicates the key of parameters data.
303 * @param defaultValue Indicates default return value.
304 * @return Returns the bool data of the key in the parameters.
305 * @since 12
306 */
307bool OH_CommonEvent_GetBoolFromParameters(const CommonEvent_Parameters* para, const char* key, const bool defaultValue);
308
309/**
310 * @brief Get bool array data from parameters data by key.
311 *
312 * @param rcvData Indicates the event of parameters data.
313 * @param key Indicates the key of parameters data.
314 * @param array Indicates the bool array.
315 * @return Returns the length of the array.
316 * @since 12
317 */
318int32_t OH_CommonEvent_GetBoolArrayFromParameters(const CommonEvent_Parameters* para, const char* key, bool** array);
319
320/**
321 * @brief Get char data from parameters data by key.
322 *
323 * @param rcvData Indicates the event of parameters data.
324 * @param key Indicates the key of parameters data.
325 * @param defaultValue Indicates default return value.
326 * @return Returns the char data of the key in the parameters.
327 * @since 12
328 */
329char OH_CommonEvent_GetCharFromParameters(const CommonEvent_Parameters* para, const char* key, const char defaultValue);
330
331/**
332 * @brief Get char array data from parameters data by key.
333 *
334 * @param rcvData Indicates the event of parameters data.
335 * @param key Indicates the key of parameters data.
336 * @param array Indicates the char array.
337 * @return Returns the length of the array.
338 * @since 12
339 */
340int32_t OH_CommonEvent_GetCharArrayFromParameters(const CommonEvent_Parameters* para, const char* key, char** array);
341
342/**
343 * @brief Get double data from parameters data by key.
344 *
345 * @param rcvData Indicates the event of parameters data.
346 * @param key Indicates the key of parameters data.
347 * @param defaultValue Indicates default return value.
348 * @return Returns the double data of the key in the parameters.
349 * @since 12
350 */
351double OH_CommonEvent_GetDoubleFromParameters(const CommonEvent_Parameters* para, const char* key,
352    const double defaultValue);
353
354/**
355 * @brief Get double array data from parameters data by key.
356 *
357 * @param rcvData Indicates the event of parameters data.
358 * @param key Indicates the key of parameters data.
359 * @param array Indicates the double array.
360 * @return Returns the length of the array, default is 0.
361 * @since 12
362 */
363int32_t OH_CommonEvent_GetDoubleArrayFromParameters(const CommonEvent_Parameters* para, const char* key,
364    double** array);
365
366#ifdef __cplusplus
367}
368#endif
369#endif // OH_COMMONEVENT_H
370/** @} */
371