espressif/esp-nimble
1
0
Fork 0
mirror of https://github.com/espressif/esp-nimble.git synced 2026-10-09 15:57:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

nimble/host: Add doxygen for ble_gatt.h

Browse Source
This commit is contained in:
Szymon Janc
2018-06-04 11:55:09 +02:00
parent dd19d11f89
commit 65bda05e9a
3 changed files with 454 additions and 396 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nimble/host/include/host/ble_gatt.h
+453
View File
@@ -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 <inttypes.h>
#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
nimble/host/src/ble_gattc.c
+1 -298
View File
@@ -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)
{
nimble/host/src/ble_gatts.c
-98
View File
@@ -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)
{