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_ */