| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Typedefs | Enumerations | Functions
Current Time Service client
BLE Services

Current Time Service client module. More...

## Modules
| Current Time Service Client configuration

## Data Structures
struct | day_date_time_t
| "Day Date Time" field of the "Exact Time 256" field of the Current Time Characteristic. More...
struct | exact_time_256_t
| "Exact Time 256" field of the Current Time Characteristic. More...
struct | adjust_reason_t
| "Adjust Reason" field of the Current Time Characteristic. More...
struct | current_time_char_t
| Data structure for the Current Time Characteristic. More...
struct | ble_cts_c_handles_t
| Structure containing the handles related to the Heart Rate Service found on the peer. More...
struct | ble_cts_c_evt_t
| Current Time Service client event. More...
struct | ble_cts_c_s
| Current Time Service client structure. This structure contains status information for the client. More...
struct | ble_cts_c_init_t
| Current Time Service client init structure. This structure contains all options and data needed for initialization of the client. More...

## Typedefs
typedef struct ble_cts_c_s | ble_cts_c_t
typedef void(* | ble_cts_c_evt_handler_t )(ble_cts_c_t *p_cts, ble_cts_c_evt_t *p_evt)
| Current Time Service client event handler type.

## Enumerations
enum | ble_cts_c_evt_type_t { BLE_CTS_C_EVT_DISCOVERY_COMPLETE, BLE_CTS_C_EVT_DISCOVERY_FAILED, BLE_CTS_C_EVT_DISCONN_COMPLETE, BLE_CTS_C_EVT_CURRENT_TIME, BLE_CTS_C_EVT_INVALID_TIME }
| Current Time Service client event type. More...

## Functions
uint32_t | ble_cts_c_init (ble_cts_c_t *p_cts, const ble_cts_c_init_t *p_cts_init)
| Function for initializing the Current Time Service client. More...
void | ble_cts_c_on_db_disc_evt (ble_cts_c_t *p_cts, ble_db_discovery_evt_t *p_evt)
| Function for handling events from the database discovery module. More...
void | ble_cts_c_on_ble_evt (ble_cts_c_t *p_cts, const ble_evt_t *p_ble_evt)
| Function for handling the application's BLE stack events. More...
static __INLINE bool | ble_cts_c_is_cts_discovered (const ble_cts_c_t *p_cts)
| Function for checking whether the peer's Current Time Service instance and the Current Time Characteristic have been discovered. More...
uint32_t | ble_cts_c_current_time_read (ble_cts_c_t const *p_cts)
| Function for reading the peer's Current Time Service Current Time Characteristic. More...
uint32_t | ble_cts_c_handles_assign (ble_cts_c_t *p_cts, const uint16_t conn_handle, const ble_cts_c_handles_t *p_peer_handles)
| Function for assigning handles to a this instance of cts_c. More...

## Detailed Description

Current Time Service client module.

This module implements the Current Time Service (CTS) client-peripheral role of the Time Profile. After security is established, the module tries to discover the Current Time Service and Characteristic on the central side. If this succeeds, the application can trigger a read of the current time from the connected server.

The module informs the application about a successful discovery using the BLE_CTS_C_EVT_DISCOVERY_COMPLETE event. The handles for the CTS server is now available in the ble_cts_c_evt_t structure. These handles must be assigned to an instance of CTS_C, using ble_cts_c_handles_assign. For more information about service discovery, see the ble_discovery module documentation Database Discovery Module.

The application can then use the function ble_cts_c_current_time_read to read the current time. If the read succeeds, it will trigger either a BLE_CTS_C_EVT_CURRENT_TIME event or a BLE_CTS_C_EVT_INVALID_TIME event (depending on if the data that was read was actually a valid time), which is then sent to the application. The current time is then available in the params field of the passed ble_cts_c_evt_t structure.

Note
  The application must propagate BLE stack events to this module by calling ble_cts_c_on_ble_evt() from the SoftDevice Event Handler callback function.

## Enumeration Type Documentation

enum ble_cts_c_evt_type_t

Current Time Service client event type.

Enumerator
BLE_CTS_C_EVT_DISCOVERY_COMPLETE | The Current Time Service was found at the peer.
BLE_CTS_C_EVT_DISCOVERY_FAILED | The Current Time Service was not found at the peer.
BLE_CTS_C_EVT_DISCONN_COMPLETE | Event indicating that the Current Time Service client module has finished processing the BLE_GAP_EVT_DISCONNECTED event. This event is raised only if a valid instance of the Current Time Service was found at the server. The event can be used by the application to do clean up related to the Current Time Service client.
BLE_CTS_C_EVT_CURRENT_TIME | A new current time reading has been received.
BLE_CTS_C_EVT_INVALID_TIME | The current time value received from the peer is invalid.

## Function Documentation

uint32_t ble_cts_c_current_time_read | ( | ble_cts_c_t const * | p_cts | ) |

Function for reading the peer's Current Time Service Current Time Characteristic.

Parameters

  [in] | p_cts | Current Time Service client structure.

Return values

  NRF_SUCCESS | If the operation is successful. Otherwise, an error code is returned.

uint32_t ble_cts_c_handles_assign | ( | ble_cts_c_t * | p_cts,
|  | const uint16_t | conn_handle,
|  | const ble_cts_c_handles_t * | p_peer_handles
| ) |  |

Function for assigning handles to a this instance of cts_c.

Call this function when a link has been established with a peer to associate the link to this instance of the module. This makes it possible to handle several links and associate each link to a particular instance of this module. The connection handle and attribute handles will be provided from the discovery event BLE_CTS_C_EVT_DISCOVERY_COMPLETE.

Parameters

  [in] | p_cts | Pointer to the CTS client structure instance to associate.
  [in] | conn_handle | Connection handle to associated with the given CTS instance.
  [in] | p_peer_handles | Attribute handles for the CTS server you want this CTS client to interact with.

Return values

  NRF_SUCCESS | If the operation was successful.
  NRF_ERROR_NULL | If a p_cts was a NULL pointer.

uint32_t ble_cts_c_init | ( | ble_cts_c_t * | p_cts,
|  | const ble_cts_c_init_t * | p_cts_init
| ) |  |

Function for initializing the Current Time Service client.

This function must be used by the application to initialize the Current Time Service client.

Parameters

  [out] | p_cts | Current Time Service client structure. This structure must be supplied by the application. It is initialized by this function and can later be used to identify this particular client instance.
  [in] | p_cts_init | Information needed to initialize the Current Time Service client.

Return values

  NRF_SUCCESS | If the service was initialized successfully.

static __INLINE bool ble_cts_c_is_cts_discovered | ( | const ble_cts_c_t * | p_cts | ) |
| static

Function for checking whether the peer's Current Time Service instance and the Current Time Characteristic have been discovered.

Parameters

  [in] | p_cts | Current Time Service client structure.

void ble_cts_c_on_ble_evt | ( | ble_cts_c_t * | p_cts,
|  | const ble_evt_t * | p_ble_evt
| ) |  |

Function for handling the application's BLE stack events.

This function handles all events from the BLE stack that are of interest to the Current Time Service client. This is a callback function that must be dispatched from main application context.

Parameters

  [in] | p_cts | Current Time Service client structure.
  [in] | p_ble_evt | Event received from the BLE stack.

void ble_cts_c_on_db_disc_evt | ( | ble_cts_c_t * | p_cts,
|  | ble_db_discovery_evt_t * | p_evt
| ) |  |

Function for handling events from the database discovery module.

This function will handle an event from the database discovery module, and determine if it relates to the discovery of CTS at the peer. If so, it will call the application's event handler indicating that CTS has been discovered. It also populates the event with the service related information before providing it to the application.

Parameters

  [in] | p_cts | Pointer to the CTS client structure.
  [in] | p_evt | Pointer to the event received from the database discovery module.