From aa9ff1642f1effc610a6fb3073475a99d4666dd3 Mon Sep 17 00:00:00 2001 From: Szymon Janc Date: Wed, 30 May 2018 15:54:02 +0200 Subject: [PATCH 1/5] nimble/host: Add doxygen for ble_att.h --- nimble/host/include/host/ble_att.h | 80 +++++++++++++++++++++++++++++- nimble/host/src/ble_att.c | 32 ------------ nimble/host/src/ble_att_svr.c | 31 ------------ 3 files changed, 79 insertions(+), 64 deletions(-) diff --git a/nimble/host/include/host/ble_att.h b/nimble/host/include/host/ble_att.h index f2ccc2cde..7e2766865 100644 --- a/nimble/host/include/host/ble_att.h +++ b/nimble/host/include/host/ble_att.h @@ -20,6 +20,13 @@ #ifndef H_BLE_ATT_ #define H_BLE_ATT_ +/** + * @brief Bluetooth Attribute Protocol (ATT) + * @defgroup bt_att Bluetooth Attribute Protocol (ATT) + * @ingroup bt_host + * @{ + */ + #include "os/queue.h" #ifdef __cplusplus extern "C" { @@ -94,7 +101,8 @@ struct os_mbuf; #define BLE_ATT_ACCESS_OP_READ 1 #define BLE_ATT_ACCESS_OP_WRITE 2 -#define BLE_ATT_MTU_DFLT 23 /* Also the minimum. */ +/** Default ATT MTU. Also the minimum. */ +#define BLE_ATT_MTU_DFLT 23 /** * An ATT MTU of 527 allows the largest ATT command (signed write) to contain a @@ -102,15 +110,85 @@ struct os_mbuf; */ #define BLE_ATT_MTU_MAX 527 +/** + * Reads a locally registered attribute. If the specified attribute handle + * coresponds to a GATT characteristic value or descriptor, the read is + * performed by calling the registered GATT access callback. + * + * @param attr_handle The 16-bit handle of the attribute to read. + * @param out_om On success, this is made to point to a + * newly-allocated mbuf containing the + * attribute data read. + * + * @return 0 on success; + * NimBLE host ATT return code if the attribute + * access callback reports failure; + * NimBLE host core return code on unexpected + * error. + */ int ble_att_svr_read_local(uint16_t attr_handle, struct os_mbuf **out_om); + +/** + * Writes a locally registered attribute. This function consumes the supplied + * mbuf regardless of the outcome. If the specified attribute handle + * coresponds to a GATT characteristic value or descriptor, the write is + * performed by calling the registered GATT access callback. + * + * @param attr_handle The 16-bit handle of the attribute to write. + * @param om The value to write to the attribute. + * + * @return 0 on success; + * NimBLE host ATT return code if the attribute + * access callback reports failure; + * NimBLE host core return code on unexpected + * error. + */ int ble_att_svr_write_local(uint16_t attr_handle, struct os_mbuf *om); +/** + * Retrieves the ATT MTU of the specified connection. If an MTU exchange for + * this connection has occurred, the MTU is the lower of the two peers' + * preferred values. Otherwise, the MTU is the default value of 23. + * + * @param conn_handle The handle of the connection to query. + * + * @return The specified connection's ATT MTU, or 0 if + * there is no such connection. + */ uint16_t ble_att_mtu(uint16_t conn_handle); + +/** + * Retrieves the preferred ATT MTU. This is the value indicated by the device + * during an ATT MTU exchange. + * + * @return The preferred ATT MTU. + */ uint16_t ble_att_preferred_mtu(void); + +/** + * Sets the preferred ATT MTU; the device will indicate this value in all + * subseqeunt ATT MTU exchanges. The ATT MTU of a connection is equal to the + * lower of the two peers' preferred MTU values. The ATT MTU is what dictates + * the maximum size of any message sent during a GATT procedure. + * + * The specified MTU must be within the following range: [23, BLE_ATT_MTU_MAX]. + * 23 is a minimum imposed by the Bluetooth specification; BLE_ATT_MTU_MAX is a + * NimBLE compile-time setting. + * + * @param mtu The preferred ATT MTU. + * + * @return 0 on success; + * BLE_HS_EINVAL if the specifeid value is not + * within the allowed range. + */ int ble_att_set_preferred_mtu(uint16_t mtu); #ifdef __cplusplus } #endif +/** + * @} + */ + #endif diff --git a/nimble/host/src/ble_att.c b/nimble/host/src/ble_att.c index 32eb0a5e7..cc7a1f115 100644 --- a/nimble/host/src/ble_att.c +++ b/nimble/host/src/ble_att.c @@ -398,16 +398,6 @@ ble_att_truncate_to_mtu(const struct ble_l2cap_chan *att_chan, } } -/** - * Retrieves the ATT MTU of the specified connection. If an MTU exchange for - * this connection has occurred, the MTU is the lower of the two peers' - * preferred values. Otherwise, the MTU is the default value of 23. - * - * @param conn_handle The handle of the connection to query. - * - * @return The specified connection's ATT MTU, or 0 if - * there is no such connection. - */ uint16_t ble_att_mtu(uint16_t conn_handle) { @@ -521,34 +511,12 @@ ble_att_rx(struct ble_l2cap_chan *chan) return 0; } -/** - * Retrieves the preferred ATT MTU. This is the value indicated by the device - * during an ATT MTU exchange. - * - * @return The preferred ATT MTU. - */ uint16_t ble_att_preferred_mtu(void) { return ble_att_preferred_mtu_val; } -/** - * Sets the preferred ATT MTU; the device will indicate this value in all - * subseqeunt ATT MTU exchanges. The ATT MTU of a connection is equal to the - * lower of the two peers' preferred MTU values. The ATT MTU is what dictates - * the maximum size of any message sent during a GATT procedure. - * - * The specified MTU must be within the following range: [23, BLE_ATT_MTU_MAX]. - * 23 is a minimum imposed by the Bluetooth specification; BLE_ATT_MTU_MAX is a - * NimBLE compile-time setting. - * - * @param mtu The preferred ATT MTU. - * - * @return 0 on success; - * BLE_HS_EINVAL if the specifeid value is not - * within the allowed range. - */ int ble_att_set_preferred_mtu(uint16_t mtu) { diff --git a/nimble/host/src/ble_att_svr.c b/nimble/host/src/ble_att_svr.c index 2c1518f15..f37c01cae 100644 --- a/nimble/host/src/ble_att_svr.c +++ b/nimble/host/src/ble_att_svr.c @@ -476,22 +476,6 @@ ble_att_svr_read_handle(uint16_t conn_handle, uint16_t attr_handle, return 0; } -/** - * Reads a locally registered attribute. If the specified attribute handle - * coresponds to a GATT characteristic value or descriptor, the read is - * performed by calling the registered GATT access callback. - * - * @param attr_handle The 16-bit handle of the attribute to read. - * @param out_om On success, this is made to point to a - * newly-allocated mbuf containing the - * attribute data read. - * - * @return 0 on success; - * NimBLE host ATT return code if the attribute - * access callback reports failure; - * NimBLE host core return code on unexpected - * error. - */ int ble_att_svr_read_local(uint16_t attr_handle, struct os_mbuf **out_om) { @@ -2092,21 +2076,6 @@ ble_att_svr_rx_write_no_rsp(uint16_t conn_handle, struct os_mbuf **rxom) return ble_att_svr_write_handle(conn_handle, handle, 0, rxom, &att_err); } -/** - * Writes a locally registered attribute. This function consumes the supplied - * mbuf regardless of the outcome. If the specified attribute handle - * coresponds to a GATT characteristic value or descriptor, the write is - * performed by calling the registered GATT access callback. - * - * @param attr_handle The 16-bit handle of the attribute to write. - * @param om The value to write to the attribute. - * - * @return 0 on success; - * NimBLE host ATT return code if the attribute - * access callback reports failure; - * NimBLE host core return code on unexpected - * error. - */ int ble_att_svr_write_local(uint16_t attr_handle, struct os_mbuf *om) { From dd19d11f891f1a65db9bf5d51e93e0c19b076c2b Mon Sep 17 00:00:00 2001 From: Szymon Janc Date: Wed, 30 May 2018 15:57:45 +0200 Subject: [PATCH 2/5] nimble/host: Add doxygen from ble_eddystone.h --- nimble/host/include/host/ble_eddystone.h | 50 ++++++++++++++++++++++++ nimble/host/src/ble_eddystone.c | 38 ------------------ 2 files changed, 50 insertions(+), 38 deletions(-) diff --git a/nimble/host/include/host/ble_eddystone.h b/nimble/host/include/host/ble_eddystone.h index 4eb6d6819..b028a4aa8 100644 --- a/nimble/host/include/host/ble_eddystone.h +++ b/nimble/host/include/host/ble_eddystone.h @@ -20,6 +20,13 @@ #ifndef H_BLE_EDDYSTONE_ #define H_BLE_EDDYSTONE_ +/** + * @brief Eddystone - BLE beacon from Google + * @defgroup bt_eddystone Eddystone - BLE beacon from Google + * @ingroup bt_host + * @{ + */ + #include #ifdef __cplusplus extern "C" { @@ -51,8 +58,47 @@ struct ble_hs_adv_fields; #define BLE_EDDYSTONE_URL_SUFFIX_GOV 0x0d #define BLE_EDDYSTONE_URL_SUFFIX_NONE 0xff +/** + * Configures the device to advertise Eddystone UID beacons. + * + * @param adv_fields The base advertisement fields to transform into + * an eddystone beacon. All configured fields + * are preserved; you probably want to clear + * this struct before calling this function. + * @param uid The 16-byte UID to advertise. + * + * @return 0 on success; + * BLE_HS_EBUSY if advertising is in progress; + * BLE_HS_EMSGSIZE if the specified data is too + * large to fit in an advertisement; + * Other nonzero on failure. + */ int ble_eddystone_set_adv_data_uid(struct ble_hs_adv_fields *adv_fields, void *uid); + +/** + * Configures the device to advertise Eddystone URL beacons. + * + * @param adv_fields The base advertisement fields to transform into + * an eddystone beacon. All configured fields + * are preserved; you probably want to clear + * this struct before calling this function. + * @param url_scheme The prefix of the URL; one of the + * BLE_EDDYSTONE_URL_SCHEME values. + * @param url_body The middle of the URL. Don't include the + * suffix if there is a suitable suffix code. + * @param url_body_len The string length of the url_body argument. + * @param url_suffix The suffix of the URL; one of the + * BLE_EDDYSTONE_URL_SUFFIX values; use + * BLE_EDDYSTONE_URL_SUFFIX_NONE if the suffix + * is embedded in the body argument. + * + * @return 0 on success; + * BLE_HS_EBUSY if advertising is in progress; + * BLE_HS_EMSGSIZE if the specified data is too + * large to fit in an advertisement; + * Other nonzero on failure. + */ int ble_eddystone_set_adv_data_url(struct ble_hs_adv_fields *adv_fields, uint8_t url_scheme, char *url_body, uint8_t url_body_len, uint8_t suffix); @@ -61,4 +107,8 @@ int ble_eddystone_set_adv_data_url(struct ble_hs_adv_fields *adv_fields, } #endif +/** + * @} + */ + #endif diff --git a/nimble/host/src/ble_eddystone.c b/nimble/host/src/ble_eddystone.c index 6c367f43f..9f90ed4e3 100644 --- a/nimble/host/src/ble_eddystone.c +++ b/nimble/host/src/ble_eddystone.c @@ -105,21 +105,6 @@ ble_eddystone_set_adv_data_gen(struct ble_hs_adv_fields *adv_fields, return 0; } -/** - * Configures the device to advertise eddystone UID beacons. - * - * @param adv_fields The base advertisement fields to transform into - * an eddystone beacon. All configured fields - * are preserved; you probably want to clear - * this struct before calling this function. - * @param uid The 16-byte UID to advertise. - * - * @return 0 on success; - * BLE_HS_EBUSY if advertising is in progress; - * BLE_HS_EMSGSIZE if the specified data is too - * large to fit in an advertisement; - * Other nonzero on failure. - */ int ble_eddystone_set_adv_data_uid(struct ble_hs_adv_fields *adv_fields, void *uid) { @@ -152,29 +137,6 @@ ble_eddystone_set_adv_data_uid(struct ble_hs_adv_fields *adv_fields, void *uid) return 0; } -/** - * Configures the device to advertise eddystone URL beacons. - * - * @param adv_fields The base advertisement fields to transform into - * an eddystone beacon. All configured fields - * are preserved; you probably want to clear - * this struct before calling this function. - * @param url_scheme The prefix of the URL; one of the - * BLE_EDDYSTONE_URL_SCHEME values. - * @param url_body The middle of the URL. Don't include the - * suffix if there is a suitable suffix code. - * @param url_body_len The string length of the url_body argument. - * @param url_suffix The suffix of the URL; one of the - * BLE_EDDYSTONE_URL_SUFFIX values; use - * BLE_EDDYSTONE_URL_SUFFIX_NONE if the suffix - * is embedded in the body argument. - * - * @return 0 on success; - * BLE_HS_EBUSY if advertising is in progress; - * BLE_HS_EMSGSIZE if the specified data is too - * large to fit in an advertisement; - * Other nonzero on failure. - */ int ble_eddystone_set_adv_data_url(struct ble_hs_adv_fields *adv_fields, uint8_t url_scheme, char *url_body, From 65bda05e9a5a817542048c76c194e42185769090 Mon Sep 17 00:00:00 2001 From: Szymon Janc Date: Mon, 4 Jun 2018 11:55:09 +0200 Subject: [PATCH 3/5] nimble/host: Add doxygen for ble_gatt.h --- nimble/host/include/host/ble_gatt.h | 453 ++++++++++++++++++++++++++++ nimble/host/src/ble_gattc.c | 299 +----------------- nimble/host/src/ble_gatts.c | 98 ------ 3 files changed, 454 insertions(+), 396 deletions(-) diff --git a/nimble/host/include/host/ble_gatt.h b/nimble/host/include/host/ble_gatt.h index 86a99bfdf..89be1c982 100644 --- a/nimble/host/include/host/ble_gatt.h +++ b/nimble/host/include/host/ble_gatt.h @@ -20,6 +20,13 @@ #ifndef H_BLE_GATT_ #define H_BLE_GATT_ +/** + * @brief Bluetooth Generic Attribute Profile (GATT) + * @defgroup bt_gatt Bluetooth Generic Attribute Profile (GATT) + * @ingroup bt_host + * @{ + */ + #include #include "host/ble_att.h" #include "host/ble_uuid.h" @@ -140,56 +147,374 @@ typedef int ble_gatt_dsc_fn(uint16_t conn_handle, const struct ble_gatt_dsc *dsc, void *arg); +/** + * Initiates GATT procedure: Exchange MTU. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_exchange_mtu(uint16_t conn_handle, ble_gatt_mtu_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Discover All Primary Services. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + */ int ble_gattc_disc_all_svcs(uint16_t conn_handle, ble_gatt_disc_svc_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Discover Primary Service by Service UUID. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param service_uuid128 The 128-bit UUID of the service to discover. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_disc_svc_by_uuid(uint16_t conn_handle, const ble_uuid_t *uuid, ble_gatt_disc_svc_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Find Included Services. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param start_handle The handle to begin the search at (generally + * the service definition handle). + * @param end_handle The handle to end the search at (generally the + * last handle in the service). + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_find_inc_svcs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, ble_gatt_disc_svc_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Discover All Characteristics of a Service. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param start_handle The handle to begin the search at (generally + * the service definition handle). + * @param end_handle The handle to end the search at (generally the + * last handle in the service). + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_disc_all_chrs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, ble_gatt_chr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Discover Characteristics by UUID. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param start_handle The handle to begin the search at (generally + * the service definition handle). + * @param end_handle The handle to end the search at (generally the + * last handle in the service). + * @param chr_uuid128 The 128-bit UUID of the characteristic to + * discover. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_disc_chrs_by_uuid(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, const ble_uuid_t *uuid, ble_gatt_chr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Discover All Characteristic Descriptors. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param chr_val_handle The handle of the characteristic value + * attribute. + * @param chr_end_handle The last handle in the characteristic + * definition. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_disc_all_dscs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, ble_gatt_dsc_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Read Characteristic Value. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param attr_handle The handle of the characteristic value to read. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_read(uint16_t conn_handle, uint16_t attr_handle, ble_gatt_attr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Read Using Characteristic UUID. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param start_handle The first handle to search (generally the + * handle of the service definition). + * @param end_handle The last handle to search (generally the + * last handle in the service definition). + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_read_by_uuid(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, const ble_uuid_t *uuid, ble_gatt_attr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Read Long Characteristic Values. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param handle The handle of the characteristic value to read. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_read_long(uint16_t conn_handle, uint16_t handle, uint16_t offset, ble_gatt_attr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Read Multiple Characteristic Values. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param handles An array of 16-bit attribute handles to read. + * @param num_handles The number of entries in the "handles" array. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_read_mult(uint16_t conn_handle, const uint16_t *handles, uint8_t num_handles, ble_gatt_attr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Write Without Response. This function consumes + * the supplied mbuf regardless of the outcome. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param attr_handle The handle of the characteristic value to write + * to. + * @param txom The value to write to the characteristic. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_write_no_rsp(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om); + +/** + * Initiates GATT procedure: Write Without Response. This function consumes + * the supplied mbuf regardless of the outcome. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param attr_handle The handle of the characteristic value to write + * to. + * @param value The value to write to the characteristic. + * @param value_len The number of bytes to write. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_write_no_rsp_flat(uint16_t conn_handle, uint16_t attr_handle, const void *data, uint16_t data_len); + +/** + * Initiates GATT procedure: Write Characteristic Value. This function + * consumes the supplied mbuf regardless of the outcome. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param attr_handle The handle of the characteristic value to write + * to. + * @param txom The value to write to the characteristic. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_write(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om, ble_gatt_attr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Write Characteristic Value (flat buffer version). + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param attr_handle The handle of the characteristic value to write + * to. + * @param value The value to write to the characteristic. + * @param value_len The number of bytes to write. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_write_flat(uint16_t conn_handle, uint16_t attr_handle, const void *data, uint16_t data_len, ble_gatt_attr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Write Long Characteristic Values. This function + * consumes the supplied mbuf regardless of the outcome. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param attr_handle The handle of the characteristic value to write + * to. + * @param txom The value to write to the characteristic. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_write_long(uint16_t conn_handle, uint16_t attr_handle, uint16_t offset, struct os_mbuf *om, ble_gatt_attr_fn *cb, void *cb_arg); + +/** + * Initiates GATT procedure: Reliable Writes. This function consumes the + * supplied mbufs regardless of the outcome. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param attrs An array of attribute descriptors; specifies + * which characteristics to write to and what + * data to write to them. The mbuf pointer in + * each attribute is set to NULL by this + * function. + * @param num_attrs The number of characteristics to write; equal + * to the number of elements in the 'attrs' + * array. + * @param cb The function to call to report procedure status + * updates; null for no callback. + * @param cb_arg The optional argument to pass to the callback + * function. + */ int ble_gattc_write_reliable(uint16_t conn_handle, struct ble_gatt_attr *attrs, int num_attrs, ble_gatt_reliable_attr_fn *cb, void *cb_arg); + +/** + * Sends a "free-form" characteristic notification. This function consumes the + * supplied mbuf regardless of the outcome. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param chr_val_handle The attribute handle to indicate in the + * outgoing notification. + * @param txom The value to write to the characteristic. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_notify_custom(uint16_t conn_handle, uint16_t att_handle, struct os_mbuf *om); + +/** + * Sends a characteristic notification. The content of the message is read + * from the specified characteristic. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param chr_val_handle The value attribute handle of the + * characteristic to include in the outgoing + * notification. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_notify(uint16_t conn_handle, uint16_t chr_val_handle); + +/** + * Sends a characteristic indication. The content of the message is read from + * the specified characteristic. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param chr_val_handle The value attribute handle of the + * characteristic to include in the outgoing + * indication. + * @param txom The data to include in the indication. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_indicate_custom(uint16_t conn_handle, uint16_t chr_val_handle, struct os_mbuf *txom); + +/** + * Sends a characteristic indication. The content of the message is read from + * the specified characteristic. + * + * @param conn_handle The connection over which to execute the + * procedure. + * @param chr_val_handle The value attribute handle of the + * characteristic to include in the outgoing + * indication. + * + * @return 0 on success; nonzero on failure. + */ int ble_gattc_indicate(uint16_t conn_handle, uint16_t chr_val_handle); int ble_gattc_init(void); @@ -415,27 +740,155 @@ struct ble_gatt_register_ctxt { typedef void ble_gatt_register_fn(struct ble_gatt_register_ctxt *ctxt, void *arg); +/** + * Queues a set of service definitions for registration. All services queued + * in this manner get registered when ble_gatts_start() is called. + * + * @param svcs An array of service definitions to queue for + * registration. This array must be + * terminated with an entry whose 'type' + * equals 0. + * + * @return 0 on success; + * BLE_HS_ENOMEM on heap exhaustion. + */ int ble_gatts_add_svcs(const struct ble_gatt_svc_def *svcs); + +/** + * Set visibility of local GATT service. Invisible services are not removed + * from database but are not discoverable by peer devices. Service Changed + * should be handled by application when needed by calling + * ble_svc_gatt_changed(). + * + * @param handle Handle of service + * @param visible non-zero if service should be visible + * + * @return 0 on success; + * BLE_HS_ENOENT if service wasn't found. + */ int ble_gatts_svc_set_visibility(uint16_t handle, int visible); + +/** + * Adjusts a host configuration object's settings to accommodate the specified + * service definition array. This function adds the counts to the appropriate + * fields in the supplied configuration object without clearing them first, so + * it can be called repeatedly with different inputs to calculate totals. Be + * sure to zero the GATT server settings prior to the first call to this + * function. + * + * @param defs The service array containing the resource + * definitions to be counted. + * + * @return 0 on success; + * BLE_HS_EINVAL if the svcs array contains an + * invalid resource definition. + */ int ble_gatts_count_cfg(const struct ble_gatt_svc_def *defs); +/** + * Send notification (or indication) to any connected devices that have + * subscribed for notification (or indication) for specified characteristic. + * + * @param chr_def_handle Characteristic definition handle + */ void ble_gatts_chr_updated(uint16_t chr_def_handle); +/** + * Retrieves the attribute handle associated with a local GATT service. + * + * @param uuid The UUID of the service to look up. + * @param out_handle On success, populated with the handle of the + * service attribute. Pass null if you don't + * need this value. + * + * @return 0 on success; + * BLE_HS_ENOENT if the specified service could + * not be found. + */ int ble_gatts_find_svc(const ble_uuid_t *uuid, uint16_t *out_handle); + +/** + * Retrieves the pair of attribute handles associated with a local GATT + * characteristic. + * + * @param svc_uuid The UUID of the parent service. + * @param chr_uuid The UUID of the characteristic to look up. + * @param out_def_handle On success, populated with the handle + * of the characteristic definition attribute. + * Pass null if you don't need this value. + * @param out_val_handle On success, populated with the handle + * of the characteristic value attribute. + * Pass null if you don't need this value. + * + * @return 0 on success; + * BLE_HS_ENOENT if the specified service or + * characteristic could not be found. + */ int ble_gatts_find_chr(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, uint16_t *out_def_handle, uint16_t *out_val_handle); + +/** + * Retrieves the attribute handle associated with a local GATT descriptor. + * + * @param svc_uuid The UUID of the grandparent service. + * @param chr_uuid The UUID of the parent characteristic. + * @param dsc_uuid The UUID of the descriptor ro look up. + * @param out_handle On success, populated with the handle + * of the descripytor attribute. Pass null if + * you don't need this value. + * + * @return 0 on success; + * BLE_HS_ENOENT if the specified service, + * characteristic, or descriptor could not be + * found. + */ int ble_gatts_find_dsc(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, const ble_uuid_t *dsc_uuid, uint16_t *out_dsc_handle); typedef void (*ble_gatt_svc_foreach_fn)(const struct ble_gatt_svc_def *svc, uint16_t handle, uint16_t end_group_handle); + +/** + * Prints dump of local GATT database. This is useful to log local state of + * database in human readable form. + */ void ble_gatts_show_local(void); + +/** + * Resets the GATT server to its initial state. On success, this function + * removes all supported services, characteristics, and descriptors. This + * function requires that: + * o No peers are connected, and + * o No GAP operations are active (advertise, discover, or connect). + * + * @return 0 on success; + * BLE_HS_EBUSY if the GATT server could not be + * reset due to existing connections or active + * GAP procedures. + */ int ble_gatts_reset(void); + +/** + * Makes all registered services available to peers. This function gets called + * automatically by the NimBLE host on startup; manual calls are only necessary + * for replacing the set of supported services with a new one. This function + * requires that: + * o No peers are connected, and + * o No GAP operations are active (advertise, discover, or connect). + * + * @return 0 on success; + * A BLE host core return code on unexpected + * error. + */ int ble_gatts_start(void); #ifdef __cplusplus } #endif +/** + * @} + */ + #endif diff --git a/nimble/host/src/ble_gattc.c b/nimble/host/src/ble_gattc.c index 7d0add167..193e1178e 100644 --- a/nimble/host/src/ble_gattc.c +++ b/nimble/host/src/ble_gattc.c @@ -1288,18 +1288,6 @@ ble_gattc_mtu_tx(struct ble_gattc_proc *proc) return rc; } -/** - * Initiates GATT procedure: Exchange MTU. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_exchange_mtu(uint16_t conn_handle, ble_gatt_mtu_fn *cb, void *cb_arg) { @@ -1518,16 +1506,6 @@ ble_gattc_disc_all_svcs_rx_complete(struct ble_gattc_proc *proc, int status) return 0; } -/** - * Initiates GATT procedure: Discover All Primary Services. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - */ int ble_gattc_disc_all_svcs(uint16_t conn_handle, ble_gatt_disc_svc_fn *cb, void *cb_arg) @@ -1741,19 +1719,6 @@ ble_gattc_disc_svc_uuid_rx_complete(struct ble_gattc_proc *proc, int status) return 0; } -/** - * Initiates GATT procedure: Discover Primary Service by Service UUID. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param service_uuid128 The 128-bit UUID of the service to discover. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_disc_svc_by_uuid(uint16_t conn_handle, const ble_uuid_t *uuid, ble_gatt_disc_svc_fn *cb, void *cb_arg) @@ -2066,22 +2031,6 @@ ble_gattc_find_inc_svcs_rx_complete(struct ble_gattc_proc *proc, int status) return 0; } -/** - * Initiates GATT procedure: Find Included Services. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param start_handle The handle to begin the search at (generally - * the service definition handle). - * @param end_handle The handle to end the search at (generally the - * last handle in the service). - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_find_inc_svcs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, @@ -2310,22 +2259,6 @@ ble_gattc_disc_all_chrs_rx_complete(struct ble_gattc_proc *proc, int status) return 0; } -/** - * Initiates GATT procedure: Discover All Characteristics of a Service. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param start_handle The handle to begin the search at (generally - * the service definition handle). - * @param end_handle The handle to end the search at (generally the - * last handle in the service). - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_disc_all_chrs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, ble_gatt_chr_fn *cb, @@ -2565,24 +2498,6 @@ ble_gattc_disc_chr_uuid_rx_complete(struct ble_gattc_proc *proc, int status) return 0; } -/** - * Initiates GATT procedure: Discover Characteristics by UUID. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param start_handle The handle to begin the search at (generally - * the service definition handle). - * @param end_handle The handle to end the search at (generally the - * last handle in the service). - * @param chr_uuid128 The 128-bit UUID of the characteristic to - * discover. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_disc_chrs_by_uuid(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, const ble_uuid_t *uuid, @@ -2793,22 +2708,6 @@ ble_gattc_disc_all_dscs_rx_complete(struct ble_gattc_proc *proc, int status) return 0; } -/** - * Initiates GATT procedure: Discover All Characteristic Descriptors. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param chr_val_handle The handle of the characteristic value - * attribute. - * @param chr_end_handle The last handle in the characteristic - * definition. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_disc_all_dscs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, @@ -2948,19 +2847,6 @@ ble_gattc_read_tx(struct ble_gattc_proc *proc) return 0; } -/** - * Initiates GATT procedure: Read Characteristic Value. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param attr_handle The handle of the characteristic value to read. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_read(uint16_t conn_handle, uint16_t attr_handle, ble_gatt_attr_fn *cb, void *cb_arg) @@ -3122,22 +3008,6 @@ ble_gattc_read_uuid_tx(struct ble_gattc_proc *proc) &proc->read_uuid.chr_uuid.u); } -/** - * Initiates GATT procedure: Read Using Characteristic UUID. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param start_handle The first handle to search (generally the - * handle of the service definition). - * @param end_handle The last handle to search (generally the - * last handle in the service definition). - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_read_by_uuid(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, const ble_uuid_t *uuid, @@ -3335,19 +3205,6 @@ ble_gattc_read_long_rx_read_rsp(struct ble_gattc_proc *proc, int status, return 0; } -/** - * Initiates GATT procedure: Read Long Characteristic Values. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param handle The handle of the characteristic value to read. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_read_long(uint16_t conn_handle, uint16_t handle, uint16_t offset, ble_gatt_attr_fn *cb, void *cb_arg) @@ -3475,20 +3332,7 @@ ble_gattc_read_mult_tx(struct ble_gattc_proc *proc) return 0; } -/** - * Initiates GATT procedure: Read Multiple Characteristic Values. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param handles An array of 16-bit attribute handles to read. - * @param num_handles The number of entries in the "handles" array. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ + int ble_gattc_read_mult(uint16_t conn_handle, const uint16_t *handles, uint8_t num_handles, ble_gatt_attr_fn *cb, @@ -3542,18 +3386,6 @@ done: * $write no response * *****************************************************************************/ -/** - * Initiates GATT procedure: Write Without Response. This function consumes - * the supplied mbuf regardless of the outcome. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param attr_handle The handle of the characteristic value to write - * to. - * @param txom The value to write to the characteristic. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_write_no_rsp(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *txom) @@ -3576,19 +3408,6 @@ ble_gattc_write_no_rsp(uint16_t conn_handle, uint16_t attr_handle, return rc; } -/** - * Initiates GATT procedure: Write Without Response. This function consumes - * the supplied mbuf regardless of the outcome. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param attr_handle The handle of the characteristic value to write - * to. - * @param value The value to write to the characteristic. - * @param value_len The number of bytes to write. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_write_no_rsp_flat(uint16_t conn_handle, uint16_t attr_handle, const void *data, uint16_t data_len) @@ -3668,22 +3487,6 @@ ble_gattc_write_err(struct ble_gattc_proc *proc, int status, ble_gattc_write_cb(proc, status, att_handle); } -/** - * Initiates GATT procedure: Write Characteristic Value. This function - * consumes the supplied mbuf regardless of the outcome. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param attr_handle The handle of the characteristic value to write - * to. - * @param txom The value to write to the characteristic. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_write(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *txom, ble_gatt_attr_fn *cb, void *cb_arg) @@ -3729,22 +3532,6 @@ done: return rc; } -/** - * Initiates GATT procedure: Write Characteristic Value (flat buffer version). - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param attr_handle The handle of the characteristic value to write - * to. - * @param value The value to write to the characteristic. - * @param value_len The number of bytes to write. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_write_flat(uint16_t conn_handle, uint16_t attr_handle, const void *data, uint16_t data_len, @@ -4009,22 +3796,6 @@ ble_gattc_write_long_rx_exec(struct ble_gattc_proc *proc, int status) return BLE_HS_EDONE; } -/** - * Initiates GATT procedure: Write Long Characteristic Values. This function - * consumes the supplied mbuf regardless of the outcome. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param attr_handle The handle of the characteristic value to write - * to. - * @param txom The value to write to the characteristic. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_write_long(uint16_t conn_handle, uint16_t attr_handle, uint16_t offset, struct os_mbuf *txom, @@ -4299,25 +4070,6 @@ ble_gattc_write_reliable_rx_exec(struct ble_gattc_proc *proc, int status) return BLE_HS_EDONE; } -/** - * Initiates GATT procedure: Reliable Writes. This function consumes the - * supplied mbufs regardless of the outcome. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param attrs An array of attribute descriptors; specifies - * which characteristics to write to and what - * data to write to them. The mbuf pointer in - * each attribute is set to NULL by this - * function. - * @param num_attrs The number of characteristics to write; equal - * to the number of elements in the 'attrs' - * array. - * @param cb The function to call to report procedure status - * updates; null for no callback. - * @param cb_arg The optional argument to pass to the callback - * function. - */ int ble_gattc_write_reliable(uint16_t conn_handle, struct ble_gatt_attr *attrs, @@ -4387,18 +4139,6 @@ done: * $notify * *****************************************************************************/ -/** - * Sends a "free-form" characteristic notification. This function consumes the - * supplied mbuf regardless of the outcome. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param chr_val_handle The attribute handle to indicate in the - * outgoing notification. - * @param txom The value to write to the characteristic. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_notify_custom(uint16_t conn_handle, uint16_t chr_val_handle, struct os_mbuf *txom) @@ -4450,18 +4190,6 @@ done: return rc; } -/** - * Sends a characteristic notification. The content of the message is read - * from the specified characteristic. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param chr_val_handle The value attribute handle of the - * characteristic to include in the outgoing - * notification. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_notify(uint16_t conn_handle, uint16_t chr_val_handle) { @@ -4555,19 +4283,6 @@ ble_gatts_indicate_fail_notconn(uint16_t conn_handle) ble_gattc_fail_procs(conn_handle, BLE_GATT_OP_INDICATE, BLE_HS_ENOTCONN); } -/** - * Sends a characteristic indication. The content of the message is read from - * the specified characteristic. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param chr_val_handle The value attribute handle of the - * characteristic to include in the outgoing - * indication. - * @param txom The data to include in the indication. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_indicate_custom(uint16_t conn_handle, uint16_t chr_val_handle, struct os_mbuf *txom) @@ -4641,18 +4356,6 @@ done: return rc; } -/** - * Sends a characteristic indication. The content of the message is read from - * the specified characteristic. - * - * @param conn_handle The connection over which to execute the - * procedure. - * @param chr_val_handle The value attribute handle of the - * characteristic to include in the outgoing - * indication. - * - * @return 0 on success; nonzero on failure. - */ int ble_gattc_indicate(uint16_t conn_handle, uint16_t chr_val_handle) { diff --git a/nimble/host/src/ble_gatts.c b/nimble/host/src/ble_gatts.c index b47711622..7a53001f2 100644 --- a/nimble/host/src/ble_gatts.c +++ b/nimble/host/src/ble_gatts.c @@ -1167,18 +1167,6 @@ ble_gatts_free_mem(void) ble_gatts_svc_entries = NULL; } -/** - * Makes all registered services available to peers. This function gets called - * automatically by the NimBLE host on startup; manual calls are only necessary - * for replacing the set of supported services with a new one. This function - * requires that: - * o No peers are connected, and - * o No GAP operations are active (advertise, discover, or connect). - * - * @return 0 on success; - * A BLE host core return code on unexpected - * error. - */ int ble_gatts_start(void) { @@ -1833,18 +1821,6 @@ ble_gatts_find_svc_chr_attr(const ble_uuid_t *svc_uuid, } } -/** - * Retrieves the attribute handle associated with a local GATT service. - * - * @param uuid128 The UUID of the service to look up. - * @param out_handle On success, populated with the handle of the - * service attribute. Pass null if you don't - * need this value. - * - * @return 0 on success; - * BLE_HS_ENOENT if the specified service could - * not be found. - */ int ble_gatts_find_svc(const ble_uuid_t *uuid, uint16_t *out_handle) { @@ -1861,23 +1837,6 @@ ble_gatts_find_svc(const ble_uuid_t *uuid, uint16_t *out_handle) return 0; } -/** - * Retrieves the pair of attribute handles associated with a local GATT - * characteristic. - * - * @param svc_uuid128 The UUID of the parent service. - * @param chr_uuid128 The UUID of the characteristic to look up. - * @param out_def_handle On success, populated with the handle - * of the characteristic definition attribute. - * Pass null if you don't need this value. - * @param out_val_handle On success, populated with the handle - * of the characteristic value attribute. - * Pass null if you don't need this value. - * - * @return 0 on success; - * BLE_HS_ENOENT if the specified service or - * characteristic could not be found. - */ int ble_gatts_find_chr(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, uint16_t *out_def_handle, uint16_t *out_val_handle) @@ -1899,21 +1858,6 @@ ble_gatts_find_chr(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, return 0; } -/** - * Retrieves the attribute handle associated with a local GATT descriptor. - * - * @param svc_uuid128 The UUID of the grandparent service. - * @param chr_uuid128 The UUID of the parent characteristic. - * @param dsc_uuid128 The UUID of the descriptor ro look up. - * @param out_handle On success, populated with the handle - * of the descripytor attribute. Pass null if - * you don't need this value. - * - * @return 0 on success; - * BLE_HS_ENOENT if the specified service, - * characteristic, or descriptor could not be - * found. - */ int ble_gatts_find_dsc(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, const ble_uuid_t *dsc_uuid, uint16_t *out_handle) @@ -1958,18 +1902,6 @@ ble_gatts_find_dsc(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, } } -/** - * Queues a set of service definitions for registration. All services queued - * in this manner get registered when ble_gatts_start() is called. - * - * @param svcs An array of service definitions to queue for - * registration. This array must be - * terminated with an entry whose 'type' - * equals 0. - * - * @return 0 on success; - * BLE_HS_ENOMEM on heap exhaustion. - */ int ble_gatts_add_svcs(const struct ble_gatt_svc_def *svcs) { @@ -2129,24 +2061,6 @@ ble_gatts_count_resources(const struct ble_gatt_svc_def *svcs, return 0; } - -/** - * Adjusts a host configuration object's settings to accommodate the specified - * service definition array. This function adds the counts to the appropriate - * fields in the supplied configuration object without clearing them first, so - * it can be called repeatedly with different inputs to calculate totals. Be - * sure to zero the GATT server settings prior to the first call to this - * function. - * - * @param defs The service array containing the resource - * definitions to be counted. - * @param cfg The resource counts are accumulated in this - * configuration object. - * - * @return 0 on success; - * BLE_HS_EINVAL if the svcs array contains an - * invalid resource definition. - */ int ble_gatts_count_cfg(const struct ble_gatt_svc_def *defs) { @@ -2180,18 +2094,6 @@ ble_gatts_lcl_svc_foreach(ble_gatt_svc_foreach_fn cb) } } -/** - * Resets the GATT server to its initial state. On success, this function - * removes all supported services, characteristics, and descriptors. This - * function requires that: - * o No peers are connected, and - * o No GAP operations are active (advertise, discover, or connect). - * - * @return 0 on success; - * BLE_HS_EBUSY if the GATT server could not be - * reset due to existing connections or active - * GAP procedures. - */ int ble_gatts_reset(void) { From 9259e078f77f14c2f24023cc9b479c02afd83152 Mon Sep 17 00:00:00 2001 From: Szymon Janc Date: Mon, 4 Jun 2018 12:09:29 +0200 Subject: [PATCH 4/5] nimble/host: Add doxygen for ble_hs_hci.h --- nimble/host/include/host/ble_hs_hci.h | 62 +++++++++++++++++++++++++++ nimble/host/src/ble_hs_hci_util.c | 50 --------------------- 2 files changed, 62 insertions(+), 50 deletions(-) diff --git a/nimble/host/include/host/ble_hs_hci.h b/nimble/host/include/host/ble_hs_hci.h index 4b3607457..e10b8e62a 100644 --- a/nimble/host/include/host/ble_hs_hci.h +++ b/nimble/host/include/host/ble_hs_hci.h @@ -20,17 +20,79 @@ #ifndef H_BLE_HS_HCI_ #define H_BLE_HS_HCI_ +/** + * @brief Bluetooth Host HCI utils + * @defgroup bt_host_hci Bluetooth Host HCI utils + * @ingroup bt_host + * @{ + */ + #include #ifdef __cplusplus extern "C" { #endif +/** + * Queries the controller for the channel map used with the specified + * connection. The channel map is represented as an array of five bytes, with + * each bit corresponding to an individual channel. The array is interpreted + * as little-endian, such that: + * map[0] & 0x01 --> Channel 0. + * map[0] & 0x02 --> Channel 1. + * ... + * map[1] & 0x01 --> Channel 8. + * + * As there are 37 channels, only the first 37 bits get written. + * + * If a bit is 1, the corresponding channel is used. Otherwise, the channel is + * unused. + * + * @param conn_handle The handle of the connection whose channel map + * is being read. + * @param out_chan_map On success, the retrieved channel map gets + * written here. This buffer must have a size + * >= 5 bytes. + * + * @return 0 on success; + * A BLE host HCI return code if the controller + * rejected the request; + * A BLE host core return code on unexpected + * error. + */ int ble_hs_hci_read_chan_map(uint16_t conn_handle, uint8_t *out_chan_map); + +/** + * Instructs the controller to use the specified channel map. The channel map + * is represented as an array of five bytes, with each bit corresponding to an + * individual channel. The array is interpreted as little-endian, such that: + * map[0] & 0x01 --> Channel 0. + * map[0] & 0x02 --> Channel 1. + * ... + * map[1] & 0x01 --> Channel 8. + * + * As there are 37 channels, only the first 37 bits should be written are used. + * + * If a bit is 1, the corresponding channel can be used. Otherwise, the + * channel should not be used. + * + * @param chan_map The channel map to configure. This buffer + * should have a size of 5 bytes. + * + * @return 0 on success; + * A BLE host HCI return code if the controller + * rejected the request; + * A BLE host core return code on unexpected + * error. + */ int ble_hs_hci_set_chan_class(const uint8_t *chan_map); #ifdef __cplusplus } #endif +/** + * @} + */ + #endif diff --git a/nimble/host/src/ble_hs_hci_util.c b/nimble/host/src/ble_hs_hci_util.c index fabf65f1a..e99dcbdff 100644 --- a/nimble/host/src/ble_hs_hci_util.c +++ b/nimble/host/src/ble_hs_hci_util.c @@ -197,33 +197,6 @@ ble_hs_hci_util_data_hdr_strip(struct os_mbuf *om, return 0; } -/** - * Queries the controller for the channel map used with the specified - * connection. The channel map is represented as an array of five bytes, with - * each bit corresponding to an individual channel. The array is interpreted - * as little-endian, such that: - * map[0] & 0x01 --> Channel 0. - * map[0] & 0x02 --> Channel 1. - * ... - * map[1] & 0x01 --> Channel 8. - * - * As there are 37 channels, only the first 37 bits get written. - * - * If a bit is 1, the corresponding channel is used. Otherwise, the channel is - * unused. - * - * @param conn_handle The handle of the connection whose channel map - * is being read. - * @param out_chan_map On success, the retrieved channel map gets - * written here. This buffer must have a size - * >= 5 bytes. - * - * @return 0 on success; - * A BLE host HCI return code if the controller - * rejected the request; - * A BLE host core return code on unexpected - * error. - */ int ble_hs_hci_read_chan_map(uint16_t conn_handle, uint8_t *out_chan_map) { @@ -256,29 +229,6 @@ ble_hs_hci_read_chan_map(uint16_t conn_handle, uint8_t *out_chan_map) return 0; } -/** - * Instructs the controller to use the specified channel map. The channel map - * is represented as an array of five bytes, with each bit corresponding to an - * individual channel. The array is interpreted as little-endian, such that: - * map[0] & 0x01 --> Channel 0. - * map[0] & 0x02 --> Channel 1. - * ... - * map[1] & 0x01 --> Channel 8. - * - * As there are 37 channels, only the first 37 bits should be written are used. - * - * If a bit is 1, the corresponding channel can be used. Otherwise, the - * channel should not be used. - * - * @param chan_map The channel map to configure. This buffer - * should have a size of 5 bytes. - * - * @return 0 on success; - * A BLE host HCI return code if the controller - * rejected the request; - * A BLE host core return code on unexpected - * error. - */ int ble_hs_hci_set_chan_class(const uint8_t *chan_map) { From 87f3bde3ee73331f2d72e3f84b2e05163e35ac1b Mon Sep 17 00:00:00 2001 From: Szymon Janc Date: Mon, 4 Jun 2018 12:11:28 +0200 Subject: [PATCH 5/5] nimble/host: Add doxygen for ble_hs_id.h --- nimble/host/include/host/ble_hs_id.h | 92 ++++++++++++++++++++++++++++ nimble/host/src/ble_hs_id.c | 78 ----------------------- 2 files changed, 92 insertions(+), 78 deletions(-) diff --git a/nimble/host/include/host/ble_hs_id.h b/nimble/host/include/host/ble_hs_id.h index cb2593ab4..c96bd20f5 100644 --- a/nimble/host/include/host/ble_hs_id.h +++ b/nimble/host/include/host/ble_hs_id.h @@ -20,6 +20,13 @@ #ifndef H_BLE_HS_ID_ #define H_BLE_HS_ID_ +/** + * @brief Bluetooth Host Identity + * @defgroup bt_host_id Bluetooth Host Identity + * @ingroup bt_host + * @{ + */ + #include #include "nimble/ble.h" @@ -27,14 +34,99 @@ extern "C" { #endif +/** + * Generates a new random address. This function does not configure the device + * with the new address; the caller can use the address in subsequent + * operations. + * + * @param nrpa The type of random address to generate: + * 0: static + * 1: non-resolvable private + * @param out_addr On success, the generated address gets written + * here. + * + * @return 0 on success; nonzero on failure. + */ int ble_hs_id_gen_rnd(int nrpa, ble_addr_t *out_addr); + +/** + * Sets the device's random address. The address type (static vs. + * non-resolvable private) is inferred from the most-significant byte of the + * address. The address is specified in host byte order (little-endian!). + * + * @param rnd_addr The random address to set. + * + * @return 0 on success; + * BLE_HS_EINVAL if the specified address is not a + * valid static random or non-resolvable + * private address. + * Other nonzero on error. + */ int ble_hs_id_set_rnd(const uint8_t *rnd_addr); + +/** + * Retrieves one of the device's identity addresses. The device can have two + * identity addresses: one public and one random. The id_addr_type argument + * specifies which of these two addresses to retrieve. + * + * @param id_addr_type The type of identity address to retrieve. + * Valid values are: + * o BLE_ADDR_PUBLIC + * o BLE_ADDR_RANDOM + * @param out_id_addr On success, the requested identity address is + * copied into this buffer. The buffer must + * be at least six bytes in size. Pass NULL + * if you do not require this information. + * @param out_is_nrpa On success, the pointed-to value indicates + * whether the retrieved address is a + * non-resolvable private address. Pass NULL + * if you do not require this information. + * + * @return 0 on success; + * BLE_HS_EINVAL if an invalid address type was + * specified; + * BLE_HS_ENOADDR if the device does not have an + * identity address of the requested type; + * Other BLE host core code on error. + */ int ble_hs_id_copy_addr(uint8_t id_addr_type, uint8_t *out_id_addr, int *out_is_nrpa); + +/** + * Determines the best address type to use for automatic address type + * resolution. Calculation of the best address type is done as follows: + * + * if privacy requested: + * if we have a random static address: + * --> RPA with static random ID + * else + * --> RPA with public ID + * end + * else + * if we have a random static address: + * --> random static address + * else + * --> public address + * end + * end + * + * @param privacy (0/1) Whether to use a private address. + * @param out_addr_type On success, the "own addr type" code gets + * written here. + * + * @return 0 if an address type was successfully inferred. + * BLE_HS_ENOADDR if the device does not have a + * suitable address. + * Other BLE host core code on error. + */ int ble_hs_id_infer_auto(int privacy, uint8_t *out_addr_type); #ifdef __cplusplus } #endif +/** + * @} + */ + #endif diff --git a/nimble/host/src/ble_hs_id.c b/nimble/host/src/ble_hs_id.c index d27a10f85..33ef50f93 100644 --- a/nimble/host/src/ble_hs_id.c +++ b/nimble/host/src/ble_hs_id.c @@ -32,19 +32,6 @@ ble_hs_id_set_pub(const uint8_t *pub_addr) ble_hs_unlock(); } -/** - * Generates a new random address. This function does not configure the device - * with the new address; the caller can use the address in subsequent - * operations. - * - * @param nrpa The type of random address to generate: - * 0: static - * 1: non-resolvable private - * @param out_addr On success, the generated address gets written - * here. - * - * @return 0 on success; nonzero on failure. - */ int ble_hs_id_gen_rnd(int nrpa, ble_addr_t *out_addr) { @@ -66,19 +53,6 @@ ble_hs_id_gen_rnd(int nrpa, ble_addr_t *out_addr) return 0; } -/** - * Sets the device's random address. The address type (static vs. - * non-resolvable private) is inferred from the most-significant byte of the - * address. The address is specified in host byte order (little-endian!). - * - * @param rnd_addr The random address to set. - * - * @return 0 on success; - * BLE_HS_EINVAL if the specified address is not a - * valid static random or non-resolvable - * private address. - * Other nonzero on error. - */ int ble_hs_id_set_rnd(const uint8_t *rnd_addr) { @@ -171,31 +145,6 @@ ble_hs_id_addr(uint8_t id_addr_type, const uint8_t **out_id_addr, return 0; } -/** - * Retrieves one of the device's identity addresses. The device can have two - * identity addresses: one public and one random. The id_addr_type argument - * specifies which of these two addresses to retrieve. - * - * @param id_addr_type The type of identity address to retrieve. - * Valid values are: - * o BLE_ADDR_PUBLIC - * o BLE_ADDR_RANDOM - * @param out_id_addr On success, the requested identity address is - * copied into this buffer. The buffer must - * be at least six bytes in size. Pass NULL - * if you do not require this information. - * @param out_is_nrpa On success, the pointed-to value indicates - * whether the retrieved address is a - * non-resolvable private address. Pass NULL - * if you do not require this information. - * - * @return 0 on success; - * BLE_HS_EINVAL if an invalid address type was - * specified; - * BLE_HS_ENOADDR if the device does not have an - * identity address of the requested type; - * Other BLE host core code on error. - */ int ble_hs_id_copy_addr(uint8_t id_addr_type, uint8_t *out_id_addr, int *out_is_nrpa) @@ -273,33 +222,6 @@ ble_hs_id_use_addr(uint8_t own_addr_type) return 0; } -/** - * Determines the best address type to use for automatic address type - * resolution. Calculation of the best address type is done as follows: - * - * if privacy requested: - * if we have a random static address: - * --> RPA with static random ID - * else - * --> RPA with public ID - * end - * else - * if we have a random static address: - * --> random static address - * else - * --> public address - * end - * end - * - * @param privacy (0/1) Whether to use a private address. - * @param out_addr_type On success, the "own addr type" code gets - * written here. - * - * @return 0 if an address type was successfully inferred. - * BLE_HS_ENOADDR if the device does not have a - * suitable address. - * Other BLE host core code on error. - */ int ble_hs_id_infer_auto(int privacy, uint8_t *out_addr_type) {