You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by cc...@apache.org on 2016/07/13 20:55:30 UTC
[17/50] [abbrv] incubator-mynewt-core git commit: BLE Host - Add API
doxygen comments.
BLE Host - Add API doxygen comments.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/commit/08539587
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/tree/08539587
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/diff/08539587
Branch: refs/heads/develop
Commit: 085395877352913107a5895d6ae087f8eaf559b2
Parents: 40b635e
Author: Christopher Collins <cc...@apache.org>
Authored: Fri Jul 1 12:13:58 2016 -0700
Committer: Christopher Collins <cc...@apache.org>
Committed: Mon Jul 11 16:43:33 2016 -0700
----------------------------------------------------------------------
net/nimble/host/include/host/ble_store.h | 72 ++++++++++
net/nimble/host/src/ble_eddystone.c | 12 +-
net/nimble/host/src/ble_gap.c | 200 +++++++++++++++++++++++---
net/nimble/host/src/ble_gattc.c | 127 ++++++++++++----
net/nimble/host/src/ble_gatts.c | 18 +++
net/nimble/host/src/ble_hs.c | 26 +++-
net/nimble/host/src/ble_hs_adv.c | 2 +-
net/nimble/host/src/ble_ibeacon.c | 13 ++
net/nimble/host/src/ble_uuid.c | 21 ++-
9 files changed, 433 insertions(+), 58 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/include/host/ble_store.h
----------------------------------------------------------------------
diff --git a/net/nimble/host/include/host/ble_store.h b/net/nimble/host/include/host/ble_store.h
index 9a7efab..a533159 100644
--- a/net/nimble/host/include/host/ble_store.h
+++ b/net/nimble/host/include/host/ble_store.h
@@ -28,6 +28,12 @@
#define BLE_STORE_ADDR_TYPE_NONE 0xff
+/**
+ * Used as a key for lookups of security material. This struct corresponds to
+ * the following store object types:
+ * o BLE_STORE_OBJ_TYPE_OUR_SEC
+ * o BLE_STORE_OBJ_TYPE_PEER_SEC
+ */
struct ble_store_key_sec {
/**
* Key by peer identity address;
@@ -52,6 +58,12 @@ struct ble_store_key_sec {
uint8_t idx;
};
+/**
+ * Represents stored security material. This struct corresponds to the
+ * following store object types:
+ * o BLE_STORE_OBJ_TYPE_OUR_SEC
+ * o BLE_STORE_OBJ_TYPE_PEER_SEC
+ */
struct ble_store_value_sec {
uint8_t peer_addr[6];
uint8_t peer_addr_type;
@@ -71,6 +83,11 @@ struct ble_store_value_sec {
unsigned sc:1;
};
+/**
+ * Used as a key for lookups of stored client characteristic configuration
+ * descriptors (CCCDs). This struct corresponds to the BLE_STORE_OBJ_TYPE_CCCD
+ * store object type.
+ */
struct ble_store_key_cccd {
/**
* Key by peer identity address;
@@ -89,6 +106,10 @@ struct ble_store_key_cccd {
uint8_t idx;
};
+/**
+ * Represents a stored client characteristic configuration descriptor (CCCD).
+ * This struct corresponds to the BLE_STORE_OBJ_TYPE_CCCD store object type.
+ */
struct ble_store_value_cccd {
uint8_t peer_addr[6];
uint8_t peer_addr_type;
@@ -97,21 +118,72 @@ struct ble_store_value_cccd {
unsigned value_changed:1;
};
+/**
+ * Used as a key for store lookups. This union must be accompanied by an
+ * object type code to indicate which field is valid.
+ */
union ble_store_key {
struct ble_store_key_sec sec;
struct ble_store_key_cccd cccd;
};
+/**
+ * Represents stored data. This union must be accompanied by an object type
+ * code to indicate which field is valid.
+ */
union ble_store_value {
struct ble_store_value_sec sec;
struct ble_store_value_cccd cccd;
};
+/**
+ * Searches the store for an object matching the specified criteria. If a
+ * match is found, it is read from the store and the dst parameter is populated
+ * with the retrieved object.
+ *
+ * @param obj_type The type of object to search for; one of the
+ * BLE_STORE_OBJ_TYPE_[...] codes.
+ * @param key Specifies properties of the object to search
+ * for. An object is retrieved if it matches
+ * these criteria.
+ * @param dst On success, this is populated with the
+ * retrieved object.
+ *
+ * @return 0 if an object was successfully retreived;
+ * BLE_HS_ENOENT if no matching object was found;
+ * Other nonzero on error.
+ */
typedef int ble_store_read_fn(int obj_type, union ble_store_key *key,
union ble_store_value *dst);
+/**
+ * Writes the specified object to the store. If an object with the same
+ * identity is already in the store, it is replaced. If the store lacks
+ * sufficient capacity to write the object, this function may remove previously
+ * stored values to make room.
+ *
+ * @param obj_type The type of object being written; one of the
+ * BLE_STORE_OBJ_TYPE_[...] codes.
+ * @param val The object to persist.
+ *
+ * @return 0 if the object was successfully written;
+ * Other nonzero on error.
+ */
typedef int ble_store_write_fn(int obj_type, union ble_store_value *val);
+/**
+ * Searches the store for the first object matching the specified criteria. If
+ * a match is found, it is deleted from the store.
+ *
+ * @param obj_type The type of object to delete; one of the
+ * BLE_STORE_OBJ_TYPE_[...] codes.
+ * @param key Specifies properties of the object to search
+ * for. An object is deleted if it matches
+ * these criteria.
+ * @return 0 if an object was successfully retreived;
+ * BLE_HS_ENOENT if no matching object was found;
+ * Other nonzero on error.
+ */
typedef int ble_store_delete_fn(int obj_type, union ble_store_key *key);
int ble_store_read(int obj_type, union ble_store_key *key,
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/src/ble_eddystone.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_eddystone.c b/net/nimble/host/src/ble_eddystone.c
index 2030c79..5e7a3f0 100644
--- a/net/nimble/host/src/ble_eddystone.c
+++ b/net/nimble/host/src/ble_eddystone.c
@@ -113,7 +113,11 @@ ble_eddystone_set_adv_data_gen(struct ble_hs_adv_fields *adv_fields,
* this struct before calling this function.
* @param uid The 16-byte UID to advertise.
*
- * @return 0 on success; BLE_HS_E... on failure.
+ * @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,7 +156,11 @@ ble_eddystone_set_adv_data_uid(struct ble_hs_adv_fields *adv_fields, void *uid)
* BLE_EDDYSTONE_URL_SUFFIX_NONE if the suffix
* is embedded in the body argument.
*
- * @return 0 on success; BLE_HS_E... on failure.
+ * @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,
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/src/ble_gap.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_gap.c b/net/nimble/host/src/ble_gap.c
index 78e8ac1..2745379 100644
--- a/net/nimble/host/src/ble_gap.c
+++ b/net/nimble/host/src/ble_gap.c
@@ -750,7 +750,7 @@ ble_gap_rx_update_complete(struct hci_le_conn_upd_complete *evt)
}
/**
- * Tells you if the BLE host is in the process of creating a master connection.
+ * Tells you if there is an active central GAP procedure (connect or discover).
*/
int
ble_gap_master_in_progress(void)
@@ -1173,6 +1173,14 @@ ble_gap_wl_tx_clear(void)
return 0;
}
+/**
+ * Overwrites the controller's white list with the specified contents.
+ *
+ * @param white_list The entries to write to the white list.
+ * @param white_list_count The number of entries in the white list.
+ *
+ * @return 0 on success; nonzero on failure.
+ */
int
ble_gap_wl_set(const struct ble_gap_white_entry *white_list,
uint8_t white_list_count)
@@ -1253,6 +1261,16 @@ ble_gap_adv_disable_tx(void)
return 0;
}
+/**
+ * Stops the currently-active advertising procedure. A success return
+ * code indicates that advertising has been fully aborted; a new advertising
+ * procedure can be initiated immediately.
+ *
+ * @return 0 on success;
+ * BLE_HS_EALREADY if there is no active
+ * advertising procedure;
+ * Other nonzero on error.
+ */
int
ble_gap_adv_stop(void)
{
@@ -1575,8 +1593,38 @@ ble_gap_adv_validate(uint8_t own_addr_type, uint8_t peer_addr_type,
}
/**
- * Enables the specified discoverable mode and connectable mode, and initiates
- * the advertising process.
+ * Initiates advertising.
+ *
+ * @param own_addr_type The type of address the stack should use for
+ * itself. Valid values are:
+ * o BLE_ADDR_TYPE_PUBLIC
+ * o BLE_ADDR_TYPE_RANDOM
+ * o BLE_ADDR_TYPE_RPA_PUB_DEFAULT
+ * o BLE_ADDR_TYPE_RPA_RND_DEFAULT
+ * @param peer_addr_type This parameter is ignored unless directed
+ * advertising is being used. Address type of
+ * the peer's identity address. Valid values
+ * are:
+ * o BLE_ADDR_TYPE_PUBLIC
+ * o BLE_ADDR_TYPE_RANDOM
+ * @param peer_addr This parameter is ignored unless directed
+ * advertising is being used. The peer's
+ * six-byte identity address.
+ * @param duration_ms The duration of the advertisement procedure.
+ * On expiration, the procedure ends and a
+ * BLE_GAP_EVENT_ADV_COMPLETE event is
+ * reported. Units are milliseconds. Specify
+ * BLE_HS_FOREVER for no expiration.
+ * @param adv_params Additional arguments specifying the particulars
+ * of the advertising procedure.
+ * @param cb The callback to associate with this advertising
+ * procedure. If advertising ends, the event
+ * is reported through this callback. If
+ * advertising results in a connection, the
+ * connection inherits this callback as its
+ * event-reporting mechanism.
+ * @param cb_arg The optional argument to pass to the callback
+ * function.
*
* @return 0 on success; nonzero on failure.
*/
@@ -1661,6 +1709,17 @@ done:
return rc;
}
+/**
+ * Configures the data to include in subsequent advertisements.
+ *
+ * @param adv_fields Specifies the advertisement data.
+ *
+ * @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_gap_adv_set_fields(const struct ble_hs_adv_fields *adv_fields)
{
@@ -1707,6 +1766,17 @@ done:
return rc;
}
+/**
+ * Configures the data to include in subsequent scan responses.
+ *
+ * @param adv_fields Specifies the scan response data.
+ *
+ * @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_gap_adv_rsp_set_fields(const struct ble_hs_adv_fields *rsp_fields)
{
@@ -1901,14 +1971,36 @@ ble_gap_disc_validate(uint8_t own_addr_type,
}
/**
- * Performs the Limited or General Discovery Procedures, as described in
- * vol. 3, part C, section 9.2.5 / 9.2.6.
+ * Performs the Limited or General Discovery Procedures (vol. 3, part C,
+ * section 9.2.5 / 9.2.6).
+ *
+ * @param own_addr_type This parameter is ignored unless active scanning
+ * is being used. The type of address the
+ * stack should use for itself when sending
+ * scan requests. Valid values are:
+ * o BLE_ADDR_TYPE_PUBLIC
+ * o BLE_ADDR_TYPE_RANDOM
+ * o BLE_ADDR_TYPE_RPA_PUB_DEFAULT
+ * o BLE_ADDR_TYPE_RPA_RND_DEFAULT
+ * @param duration_ms The duration of the discovery procedure.
+ * On expiration, the procedure ends and a
+ * BLE_GAP_EVENT_DISC_COMPLETE event is
+ * reported. Units are milliseconds. Specify
+ * BLE_HS_FOREVER for no expiration.
+ * @param disc_params Additional arguments specifying the particulars
+ * of the discovery procedure.
+ * @param cb The callback to associate with this discovery
+ * procedure. Advertising reports and discovery
+ * termination events are reported through
+ * this callback.
+ * @param cb_arg The optional argument to pass to the callback
+ * function.
*
* @return 0 on success; nonzero on failure.
*/
int
ble_gap_disc(uint8_t own_addr_type, int32_t duration_ms,
- const struct ble_gap_disc_params *in_disc_params,
+ const struct ble_gap_disc_params *disc_params,
ble_gap_disc_fn *cb, void *cb_arg)
{
#if !NIMBLE_OPT(ROLE_OBSERVER)
@@ -1926,7 +2018,7 @@ ble_gap_disc(uint8_t own_addr_type, int32_t duration_ms,
/* Make a copy of the parameter strcuture and fill unspecified values with
* defaults.
*/
- params = *in_disc_params;
+ params = *disc_params;
ble_gap_disc_fill_dflts(¶ms);
rc = ble_gap_disc_validate(own_addr_type, ¶ms);
@@ -2047,23 +2139,37 @@ ble_gap_conn_create_tx(uint8_t own_addr_type,
}
/**
- * Performs the Direct Connection Establishment Procedure, as described in
- * vol. 3, part C, section 9.3.8.
+ * Initiates a connect procedure.
*
- * @param addr_type The peer's address type; one of:
- * o BLE_HCI_CONN_PEER_ADDR_PUBLIC
- * o BLE_HCI_CONN_PEER_ADDR_RANDOM
- * o BLE_HCI_CONN_PEER_ADDR_PUBLIC_IDENT
- * o BLE_HCI_CONN_PEER_ADDR_RANDOM_IDENT
- * o BLE_GAP_ADDR_TYPE_WL
- * @param addr The address of the peer to connect to.
+ * @param own_addr_type The type of address the stack should use for
+ * itself during connection establishment.
+ * o BLE_ADDR_TYPE_PUBLIC
+ * o BLE_ADDR_TYPE_RANDOM
+ * o BLE_ADDR_TYPE_RPA_PUB_DEFAULT
+ * o BLE_ADDR_TYPE_RPA_RND_DEFAULT
+ * @param peer_addr_type The peer's identity address type. One of:
+ * o BLE_HCI_CONN_PEER_ADDR_PUBLIC
+ * o BLE_HCI_CONN_PEER_ADDR_RANDOM
+ * o BLE_HCI_CONN_PEER_ADDR_PUBLIC_IDENT
+ * o BLE_HCI_CONN_PEER_ADDR_RANDOM_IDENT
+ * o BLE_GAP_ADDR_TYPE_WL
+ * @param peer_addr The identity address of the peer to connect to.
+ * This parameter is ignored when the white
+ * list is used.
+ * @param duration_ms The duration of the discovery procedure.
+ * On expiration, the procedure ends and a
+ * BLE_GAP_EVENT_DISC_COMPLETE event is
+ * reported. Units are milliseconds.
+ * @param conn_params Additional arguments specifying the particulars
+ * of the connect procedure. Specify null for
+ * default values.
*
* @return 0 on success; nonzero on failure.
*/
int
ble_gap_connect(uint8_t own_addr_type,
uint8_t peer_addr_type, const uint8_t *peer_addr,
- const struct ble_gap_conn_params *params,
+ const struct ble_gap_conn_params *conn_params,
ble_gap_event_fn *cb, void *cb_arg)
{
#if !NIMBLE_OPT(ROLE_CENTRAL)
@@ -2096,14 +2202,14 @@ ble_gap_connect(uint8_t own_addr_type,
goto done;
}
- if (params == NULL) {
- params = &ble_gap_conn_params_dflt;
+ if (conn_params == NULL) {
+ conn_params = &ble_gap_conn_params_dflt;
}
- /* XXX: Verify params. */
+ /* XXX: Verify conn_params. */
BLE_HS_LOG(INFO, "GAP procedure initiated: connect; ");
- ble_gap_log_conn(own_addr_type, peer_addr_type, peer_addr, params);
+ ble_gap_log_conn(own_addr_type, peer_addr_type, peer_addr, conn_params);
BLE_HS_LOG(INFO, "\n");
ble_gap_master.conn.cb = cb;
@@ -2112,7 +2218,7 @@ ble_gap_connect(uint8_t own_addr_type,
ble_gap_master.conn.our_addr_type = own_addr_type;
rc = ble_gap_conn_create_tx(own_addr_type, peer_addr_type, peer_addr,
- params);
+ conn_params);
if (rc != 0) {
goto done;
}
@@ -2147,6 +2253,19 @@ ble_gap_conn_active(void)
* $terminate connection procedure *
*****************************************************************************/
+/**
+ * Terminates an established connection.
+ *
+ * @param conn_handle The handle corresponding to the connection to
+ * terminate.
+ * @param hci_reason The HCI error code to indicate as the reason
+ * for termination.
+ *
+ * @return 0 on success;
+ * BLE_HS_ENOTCONN if there is no connection with
+ * the specified handle;
+ * Other nonzero on failure.
+ */
int
ble_gap_terminate(uint16_t conn_handle, uint8_t hci_reason)
{
@@ -2188,6 +2307,14 @@ done:
* $cancel *
*****************************************************************************/
+/**
+ * Aborts a connect procedure in progress.
+ *
+ * @return 0 on success;
+ * BLE_HS_EALREADY if there is no active connect
+ * procedure.
+ * Other nonzero on error.
+ */
int
ble_gap_conn_cancel(void)
{
@@ -2357,6 +2484,22 @@ ble_gap_update_tx(uint16_t conn_handle,
return 0;
}
+/**
+ * Initiates a connection parameter update procedure.
+ *
+ * @param conn_handle The handle corresponding to the connection to
+ * update.
+ * @param params The connection parameters to attempt to update
+ * to.
+ *
+ * @return 0 on success;
+ * BLE_HS_ENOTCONN if the there is no connection
+ * with the specified handle;
+ * BLE_HS_EALREADY if a connection update
+ * procedure for this connection is already in
+ * progress;
+ * Other nonzero on error.
+ */
int
ble_gap_update_params(uint16_t conn_handle,
const struct ble_gap_upd_params *params)
@@ -2407,6 +2550,19 @@ done:
* $security *
*****************************************************************************/
+/**
+ * Initiates the GAP encryption procedure.
+ *
+ * @param conn_handle The handle corresponding to the connection to
+ * encrypt.
+ *
+ * @return 0 on success;
+ * BLE_HS_ENOTCONN if the there is no connection
+ * with the specified handle;
+ * BLE_HS_EALREADY if an encrpytion procedure for
+ * this connection is already in progress;
+ * Other nonzero on error.
+ */
int
ble_gap_security_initiate(uint16_t conn_handle)
{
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/src/ble_gattc.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_gattc.c b/net/nimble/host/src/ble_gattc.c
index 77daa19..04ff94f 100644
--- a/net/nimble/host/src/ble_gattc.c
+++ b/net/nimble/host/src/ble_gattc.c
@@ -950,7 +950,8 @@ ble_gattc_mtu_err(struct ble_gattc_proc *proc, int status, uint16_t att_handle)
* procedure.
* @param cb The function to call to report procedure status
* updates; null for no callback.
- * @param cb_arg The argument to pass to the callback function.
+ * @param cb_arg The optional argument to pass to the callback
+ * function.
*
* @return 0 on success; nonzero on failure.
*/
@@ -1180,7 +1181,8 @@ ble_gattc_disc_all_svcs_rx_complete(struct ble_gattc_proc *proc, int status)
* procedure.
* @param cb The function to call to report procedure status
* updates; null for no callback.
- * @param cb_arg The argument to pass to the callback function.
+ * @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,
@@ -1381,7 +1383,10 @@ ble_gattc_disc_svc_uuid_rx_complete(struct ble_gattc_proc *proc, int status)
* @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 argument to pass to the callback function.
+ * @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 void *svc_uuid128,
@@ -1694,7 +1699,10 @@ ble_gattc_find_inc_svcs_rx_complete(struct ble_gattc_proc *proc, int status)
* last handle in the service).
* @param cb The function to call to report procedure status
* updates; null for no callback.
- * @param cb_arg The argument to pass to the callback function.
+ * @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,
@@ -1923,7 +1931,10 @@ ble_gattc_disc_all_chrs_rx_complete(struct ble_gattc_proc *proc, int status)
* last handle in the service).
* @param cb The function to call to report procedure status
* updates; null for no callback.
- * @param cb_arg The argument to pass to the callback function.
+ * @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,
@@ -2165,7 +2176,10 @@ ble_gattc_disc_chr_uuid_rx_complete(struct ble_gattc_proc *proc, int status)
* discover.
* @param cb The function to call to report procedure status
* updates; null for no callback.
- * @param cb_arg The argument to pass to the callback function.
+ * @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,
@@ -2368,7 +2382,10 @@ ble_gattc_disc_all_dscs_rx_complete(struct ble_gattc_proc *proc, int status)
* definition.
* @param cb The function to call to report procedure status
* updates; null for no callback.
- * @param cb_arg The argument to pass to the callback function.
+ * @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 chr_def_handle,
@@ -2493,7 +2510,10 @@ ble_gattc_read_rx_read_rsp(struct ble_gattc_proc *proc, int status,
* @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 argument to pass to the callback function.
+ * @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,
@@ -2649,7 +2669,10 @@ ble_gattc_read_uuid_rx_complete(struct ble_gattc_proc *proc, int status)
* 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 argument to pass to the callback function.
+ * @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,
@@ -2830,7 +2853,10 @@ ble_gattc_read_long_rx_read_rsp(struct ble_gattc_proc *proc, int status,
* @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 argument to pass to the callback function.
+ * @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,
@@ -2944,7 +2970,10 @@ ble_gattc_read_mult_err(struct ble_gattc_proc *proc, int status,
* @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 argument to pass to the callback function.
+ * @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,
@@ -3000,9 +3029,8 @@ done:
* 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 argument to pass to the callback function.
+ *
+ * @return 0 on success; nonzero on failure.
*/
int
ble_gattc_write_no_rsp(uint16_t conn_handle, uint16_t attr_handle,
@@ -3089,7 +3117,10 @@ ble_gattc_write_err(struct ble_gattc_proc *proc, int status,
* @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 argument to pass to the callback function.
+ * @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, const void *value,
@@ -3328,7 +3359,10 @@ ble_gattc_write_long_rx_exec(struct ble_gattc_proc *proc, int status)
* @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 argument to pass to the callback function.
+ * @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,
@@ -3549,13 +3583,16 @@ ble_gattc_write_reliable_rx_exec(struct ble_gattc_proc *proc, int status)
*
* @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 attrs An array of attribute descriptors; specifies
+ * which characteristics to write to and what
+ * data to write to them.
+ * @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 argument to pass to the callback function.
+ * @param cb_arg The optional argument to pass to the callback
+ * function.
*/
int
ble_gattc_write_reliable(uint16_t conn_handle,
@@ -3607,11 +3644,22 @@ done:
*****************************************************************************/
/**
- * Sends an attribute notification. The content of the message is specified
- * in the attr parameter.
+ * Sends a "free-form" characteristic notification. The content of the message
+ * is specified in the attr parameter.
+ *
+ * @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 attr_data The characteristic value to include in the
+ * outgoing notification.
+ * @param attr_data_len The number of bytes of attribute data to include
+ * in the notification.
+ *
+ * @return 0 on success; nonzero on failure.
*/
int
-ble_gattc_notify_custom(uint16_t conn_handle, uint16_t att_handle,
+ble_gattc_notify_custom(uint16_t conn_handle, uint16_t chr_val_handle,
const void *attr_data, uint16_t attr_data_len)
{
#if !NIMBLE_OPT(GATT_NOTIFY)
@@ -3624,14 +3672,14 @@ ble_gattc_notify_custom(uint16_t conn_handle, uint16_t att_handle,
STATS_INC(ble_gattc_stats, notify);
- ble_gattc_log_notify(att_handle);
+ ble_gattc_log_notify(chr_val_handle);
if (attr_data == NULL) {
/* No custom attribute data; read the value from the specified
* attribute.
*/
rc = ble_att_svr_read_handle(BLE_HS_CONN_HANDLE_NONE,
- att_handle, &ctxt, NULL);
+ chr_val_handle, &ctxt, NULL);
if (rc != 0) {
/* Fatal error; application disallowed attribute read. */
rc = BLE_HS_EAPP;
@@ -3642,7 +3690,7 @@ ble_gattc_notify_custom(uint16_t conn_handle, uint16_t att_handle,
attr_data_len = ctxt.read.len;
}
- req.banq_handle = att_handle;
+ req.banq_handle = chr_val_handle;
rc = ble_att_clt_tx_notify(conn_handle, &req, attr_data, attr_data_len);
if (rc != 0) {
goto err;
@@ -3656,8 +3704,16 @@ err:
}
/**
- * Sends an attribute notification. The content of the message is read from
+ * 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)
@@ -3747,7 +3803,20 @@ ble_gattc_indicate_rx_rsp(struct ble_gattc_proc *proc)
}
/**
- * Sends an attribute indication.
+ * 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 cb The function to call to report procedure status;
+ * 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_indicate(uint16_t conn_handle, uint16_t chr_val_handle,
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/src/ble_gatts.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_gatts.c b/net/nimble/host/src/ble_gatts.c
index 82f21b2..2318fdf 100644
--- a/net/nimble/host/src/ble_gatts.c
+++ b/net/nimble/host/src/ble_gatts.c
@@ -901,6 +901,24 @@ ble_gatts_register_round(int *out_num_registered, ble_gatt_register_fn *cb,
return 0;
}
+/**
+ * Registers a set of services, characteristics, and descriptors to be accessed
+ * by GATT clients.
+ *
+ * @param svcs A table of the service definitions to be
+ * registered.
+ * @param cb The function to call for each service,
+ * characteristic, and descriptor that gets
+ * registered.
+ * @param cb_arg The optional argument to pass to the callback
+ * function.
+ *
+ * @return 0 on success;
+ * BLE_HS_ENOMEM if registration failed due to
+ * resource exhaustion;
+ * BLE_HS_EINVAL if the service definition table
+ * contains an invalid element.
+ */
int
ble_gatts_register_svcs(const struct ble_gatt_svc_def *svcs,
ble_gatt_register_fn *cb, void *cb_arg)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/src/ble_hs.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_hs.c b/net/nimble/host/src/ble_hs.c
index e78b5aa..e3f4bcb 100644
--- a/net/nimble/host/src/ble_hs.c
+++ b/net/nimble/host/src/ble_hs.c
@@ -285,6 +285,16 @@ ble_hs_event_enqueue(struct os_event *ev)
os_eventq_put(ble_hs_parent_evq, &ble_hs_event_co.cf_c.c_ev);
}
+/**
+ * Sends a sequence of HCI commands to the controller. This sequence of
+ * commands is necessary for the host and controller to remain in sync. This
+ * function must be called before any other host functionality is used, but it
+ * must be called after both the host and controller are initialized.
+ * Typically, the host-parent-task calls this function at the top of its task
+ * routine.
+ *
+ * @return 0 on success; nonzero on error.
+ */
int
ble_hs_start(void)
{
@@ -348,7 +358,21 @@ ble_hs_free_mem(void)
}
/**
- * Initializes the host portion of the BLE stack.
+ * Initializes the NimBLE host. This function must be called before the OS is
+ * started. The NimBLE stack requires an application task to function. One
+ * application task in particular is designated as the "host parent task". In
+ * addition to application-specific work, the host parent task does work for
+ * NimBLE by processing events generated by the host.
+ *
+ * @param app_evq The event queue associated with the host parent
+ * task.
+ * @param cfg The set of configuration settings to initialize
+ * the host with. Specify null for defaults.
+ *
+ * @return 0 on success;
+ * BLE_HS_ENOMEM if initialization failed due to
+ * resource exhaustion.
+ * Other nonzero on error.
*/
int
ble_hs_init(struct os_eventq *app_evq, struct ble_hs_cfg *cfg)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/src/ble_hs_adv.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_hs_adv.c b/net/nimble/host/src/ble_hs_adv.c
index dffbc1f..8a7ed50 100644
--- a/net/nimble/host/src/ble_hs_adv.c
+++ b/net/nimble/host/src/ble_hs_adv.c
@@ -107,7 +107,7 @@ ble_hs_adv_set_array32(uint8_t type, uint8_t num_elems, const uint32_t *elems,
/**
* Sets the significant part of the data in outgoing advertisements.
*
- * @return 0 on success; on failure.
+ * @return 0 on success; nonzero on failure.
*/
int
ble_hs_adv_set_fields(const struct ble_hs_adv_fields *adv_fields,
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/src/ble_ibeacon.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_ibeacon.c b/net/nimble/host/src/ble_ibeacon.c
index 06e203a..68c182f 100644
--- a/net/nimble/host/src/ble_ibeacon.c
+++ b/net/nimble/host/src/ble_ibeacon.c
@@ -23,6 +23,19 @@
#define BLE_IBEACON_MFG_DATA_SIZE 25
+/**
+ * Configures the device to advertise iBeacons.
+ *
+ * @param uuid The 128-bit UUID to advertise.
+ * @param major The major version number to include in
+ * iBeacons.
+ * @param minor The minor version number to include in
+ * iBeacons.
+ *
+ * @return 0 on success;
+ * BLE_HS_EBUSY if advertising is in progress;
+ * Other nonzero on failure.
+ */
int
ble_ibeacon_set_adv_data(void *uuid128, uint16_t major, uint16_t minor)
{
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/08539587/net/nimble/host/src/ble_uuid.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_uuid.c b/net/nimble/host/src/ble_uuid.c
index 118b6ea..89a9bf4 100644
--- a/net/nimble/host/src/ble_uuid.c
+++ b/net/nimble/host/src/ble_uuid.c
@@ -34,9 +34,13 @@ static uint8_t ble_uuid_base[16] = {
* Attempts to convert the supplied 128-bit UUID into its shortened 16-bit
* form.
*
+ * @param uuid128 The 128-bit UUID to attempt to convert.
+ * This must point to 16 contiguous bytes.
+ *
* @return Positive 16-bit unsigned integer on
* success;
- * 0 if the UUID could not be converted.
+ * 0 if the UUID cannot be represented in 16
+ * bits.
*/
uint16_t
ble_uuid_128_to_16(const void *uuid128)
@@ -68,8 +72,19 @@ ble_uuid_128_to_16(const void *uuid128)
return uuid16;
}
+/**
+ * Expands a 16-bit UUID into its 128-bit form.
+ *
+ * @param uuid16 The 16-bit UUID to convert.
+ * @param out_uuid128 On success, the resulting 128-bit UUID gets
+ * written here.
+ *
+ * @return 0 on success;
+ * BLE_HS_EINVAL if uuid16 is not a valid 16-bit
+ * UUID.
+ */
int
-ble_uuid_16_to_128(uint16_t uuid16, void *uuid128)
+ble_uuid_16_to_128(uint16_t uuid16, void *out_uuid128)
{
uint8_t *u8ptr;
@@ -77,7 +92,7 @@ ble_uuid_16_to_128(uint16_t uuid16, void *uuid128)
return BLE_HS_EINVAL;
}
- u8ptr = uuid128;
+ u8ptr = out_uuid128;
memcpy(u8ptr, ble_uuid_base, 16);
htole16(u8ptr + 12, uuid16);