Line data Source code
1 0 : /*
2 : * Copyright (c) 2024 Croxel Inc.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_CTS_H_
8 : #define ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_CTS_H_
9 :
10 : /**
11 : * @brief Current Time Service (CTS)
12 : * @defgroup bt_cts Current Time Service (CTS)
13 : * @ingroup bluetooth
14 : * @{
15 : *
16 : */
17 :
18 : #include <stdint.h>
19 :
20 : #ifdef __cplusplus
21 : extern "C" {
22 : #endif
23 :
24 : /**
25 : * @brief CTS time update reason bits as defined in the specification
26 : */
27 0 : enum bt_cts_update_reason {
28 : /* Unknown reason of update no bit is set */
29 : BT_CTS_UPDATE_REASON_UNKNOWN = 0,
30 : /* When time is changed manually e.g. through UI */
31 : BT_CTS_UPDATE_REASON_MANUAL = BIT(0),
32 : /* If time is changed through external reference */
33 : BT_CTS_UPDATE_REASON_EXTERNAL_REF = BIT(1),
34 : /* time changed due to timezone adjust */
35 : BT_CTS_UPDATE_REASON_TIME_ZONE_CHANGE = BIT(2),
36 : /* time changed due to dst offset change */
37 : BT_CTS_UPDATE_REASON_DAYLIGHT_SAVING = BIT(3),
38 : };
39 :
40 : /**
41 : * @brief Current Time service data format, Please refer to
42 : * specifications for more details
43 : */
44 1 : struct bt_cts_time_format {
45 0 : uint16_t year;
46 0 : uint8_t mon;
47 0 : uint8_t mday;
48 0 : uint8_t hours;
49 0 : uint8_t min;
50 0 : uint8_t sec;
51 0 : uint8_t wday;
52 0 : uint8_t fractions256;
53 0 : uint8_t reason;
54 : } __packed;
55 :
56 : /** @brief Current Time Service callback structure */
57 1 : struct bt_cts_cb {
58 : /** @brief Current Time Service notifications changed
59 : *
60 : * @param enabled True if notifications are enabled, false if disabled
61 : */
62 1 : void (*notification_changed)(bool enabled);
63 :
64 : /**
65 : * @brief The Current Time has been updated by a peer.
66 : * It is the responsibility of the application to store the new time.
67 : *
68 : * @param cts_time [IN] updated time
69 : *
70 : * @return 0 application has decoded it successfully
71 : * @return negative error codes on failure
72 : *
73 : */
74 1 : int (*cts_time_write)(struct bt_cts_time_format *cts_time);
75 :
76 : /**
77 : * @brief When current time Read request or notification is triggered, CTS uses
78 : * this callback to retrieve current time information from application. Application
79 : * must implement it and provide cts formatted current time information
80 : *
81 : * @note this callback is mandatory
82 : *
83 : * @param cts_time [IN] updated time
84 : *
85 : * @return 0 application has encoded it successfully
86 : * @return negative error codes on failure
87 : */
88 1 : int (*fill_current_cts_time)(struct bt_cts_time_format *cts_time);
89 : };
90 :
91 : /**
92 : * @brief This API should be called at application init.
93 : * it is safe to call this API before or after bt_enable API
94 : *
95 : * @param cb pointer to required callback
96 : *
97 : * @return 0 on success
98 : * @return negative error codes on failure
99 : */
100 1 : int bt_cts_init(const struct bt_cts_cb *cb);
101 :
102 : /**
103 : * @brief Notify all connected clients that have enabled the
104 : * current time update notification
105 : *
106 : * @param reason update reason to be sent to the clients
107 : *
108 : * @return 0 on success
109 : * @return negative error codes on failure
110 : */
111 1 : int bt_cts_send_notification(enum bt_cts_update_reason reason);
112 :
113 : /**
114 : * @brief Helper API to decode CTS formatted time into milliseconds since epoch
115 : *
116 : * @note @kconfig{CONFIG_BT_CTS_HELPER_API} needs to be enabled to use this API.
117 : *
118 : * @param ct_time [IN] cts time formatted time
119 : * @param unix_ms [OUT] pointer to store parsed millisecond since epoch
120 : *
121 : * @return 0 on success
122 : * @return negative error codes on failure
123 : */
124 1 : int bt_cts_time_to_unix_ms(const struct bt_cts_time_format *ct_time, int64_t *unix_ms);
125 :
126 : /**
127 : * @brief Helper API to encode milliseconds since epoch to CTS formatted time
128 : *
129 : * @note @kconfig{CONFIG_BT_CTS_HELPER_API} needs to be enabled to use this API.
130 : *
131 : * @param ct_time [OUT] Pointer to store CTS formatted time
132 : * @param unix_ms [IN] milliseconds since epoch to be converted
133 : *
134 : * @return 0 on success
135 : * @return negative error codes on failure
136 : */
137 1 : int bt_cts_time_from_unix_ms(struct bt_cts_time_format *ct_time, int64_t unix_ms);
138 :
139 : #ifdef __cplusplus
140 : }
141 : #endif
142 :
143 : /**
144 : * @}
145 : */
146 :
147 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_CTS_H_ */
|
