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) {