1 /* 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 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 struct bt_cts_time_format { 45 uint16_t year; 46 uint8_t mon; 47 uint8_t mday; 48 uint8_t hours; 49 uint8_t min; 50 uint8_t sec; 51 uint8_t wday; 52 uint8_t fractions256; 53 uint8_t reason; 54 } __packed; 55 56 /** @brief Current Time Service callback structure */ 57 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 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 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 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 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 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 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 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_ */ 148
