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/23 02:47:38 UTC
[11/11] incubator-mynewt-core git commit: BLE Host - Small doxygen
update.
BLE Host - Small doxygen update.
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/beab6f23
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/tree/beab6f23
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/diff/beab6f23
Branch: refs/heads/develop
Commit: beab6f23b48c47b115c5ff1cd237d441ebf2122c
Parents: d187742
Author: Christopher Collins <cc...@apache.org>
Authored: Fri Jul 22 19:34:03 2016 -0700
Committer: Christopher Collins <cc...@apache.org>
Committed: Fri Jul 22 19:40:24 2016 -0700
----------------------------------------------------------------------
net/nimble/host/include/host/ble_att.h | 74 ----------------------------
net/nimble/host/include/host/ble_gatt.h | 51 +++++++++++--------
net/nimble/host/src/ble_hs_mbuf.c | 27 ++++++++++
net/nimble/host/src/ble_uuid.c | 2 +-
4 files changed, 59 insertions(+), 95 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/beab6f23/net/nimble/host/include/host/ble_att.h
----------------------------------------------------------------------
diff --git a/net/nimble/host/include/host/ble_att.h b/net/nimble/host/include/host/ble_att.h
index 3bccea5..e5eb820 100644
--- a/net/nimble/host/include/host/ble_att.h
+++ b/net/nimble/host/include/host/ble_att.h
@@ -94,80 +94,6 @@ struct os_mbuf;
#define BLE_ATT_MTU_MAX 240
#define BLE_ATT_MTU_PREFERRED_DFLT 240
-/**
- * Context for an access to an ATT attribute. When a client reads or writes a
- * locally registered attribute, an instance of this struct gets passed to the
- * access callback.
- */
-struct ble_att_svr_access_ctxt {
- /**
- * The ATT operation being performed dictates which field in this union is
- * valid. If a read is being performed, the read field is valid.
- * Otherwise, a write is being performed, in which case the write field is
- * valid.
- */
- union {
- /** Context for reads of ATT attributes. */
- struct {
- /**
- * (stack --> app)
- * The offset within the attribute that the client is reading from.
- */
- uint16_t offset;
-
- /**
- * (stack --> app)
- * Maximum number of data bytes the stack can send in the read
- * response. This is based on the connection's ATT MTU.
- */
- uint16_t max_data_len;
-
- /**
- * (stack --> app)
- * A buffer that the app can use to write the characteristic
- * response value to. This buffer can hold up to max_data_len
- * bytes.
- */
- uint8_t *buf;
-
- /**
- * (app --> stack)
- * App points this at the characteristic data to respond with.
- * Initially this points to "buf".
- */
- const void *data;
-
- /**
- * (app --> stack)
- * App fills this with the number of data bytes contained in
- * characteristic response.
- */
- uint16_t len;
- } read;
-
- /** Context for writes of ATT attributes. */
- struct {
- /**
- * (stack --> app)
- * The data that the peer is writing to the characteristic.
- */
- const void *data;
-
- /**
- * (stack --> app)
- * The offset within the attribute that the client is writing to.
- */
- uint16_t offset;
-
- /**
- * (stack --> app)
- * The number of bytes of characteristic data being written.
- */
- int len;
- } write;
- };
-};
-
int ble_att_svr_read_local(uint16_t attr_handle, struct os_mbuf **out_om);
int ble_att_svr_write_local(uint16_t attr_handle, struct os_mbuf **om);
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/beab6f23/net/nimble/host/include/host/ble_gatt.h
----------------------------------------------------------------------
diff --git a/net/nimble/host/include/host/ble_gatt.h b/net/nimble/host/include/host/ble_gatt.h
index 3695401..31a8427 100644
--- a/net/nimble/host/include/host/ble_gatt.h
+++ b/net/nimble/host/include/host/ble_gatt.h
@@ -104,10 +104,22 @@ typedef int ble_gatt_disc_svc_fn(uint16_t conn_handle,
const struct ble_gatt_error *error,
const struct ble_gatt_svc *service,
void *arg);
+
+/**
+ * The host will free the attribute mbuf automatically after the callback is
+ * executed. The application can take ownership of the mbuf and prevent it
+ * from being freed by assigning NULL to attr->om.
+ */
typedef int ble_gatt_attr_fn(uint16_t conn_handle,
const struct ble_gatt_error *error,
struct ble_gatt_attr *attr,
void *arg);
+
+/**
+ * The host will free the attribute mbufs automatically after the callback is
+ * executed. The application can take ownership of the mbufs and prevent them
+ * from being freed by assigning NULL to each attribute's om field.
+ */
typedef int ble_gatt_reliable_attr_fn(uint16_t conn_handle,
const struct ble_gatt_error *error,
struct ble_gatt_attr *attrs,
@@ -245,6 +257,23 @@ struct ble_gatt_svc_def {
const struct ble_gatt_chr_def *characteristics;
};
+struct ble_gatt_dsc_def {
+ /**
+ * The first element in a uint8_t[16]; use the BLE_UUID16 macro for 16-bit
+ * UUIDs; NULL if there are no more descriptors in the characteristic.
+ */
+ uint8_t *uuid128;
+
+ /** Specifies the set of permitted operations for this descriptor. */
+ uint8_t att_flags;
+
+ /** Callback that gets executed when the descriptor is read or written. */
+ ble_gatt_access_fn *access_cb;
+
+ /** Optional argument for callback. */
+ void *arg;
+};
+
/**
* Context for an access to a GATT characteristic or descriptor. When a client
* reads or writes a locally registered characteristic or descriptor, an
@@ -267,8 +296,8 @@ struct ble_gatt_access_ctxt {
* characteristic or descriptor being read.
* o For writes: This is already populated with the value being written
* by the peer. If the application wishes to retain this mbuf for
- * later use, it must set this pointer to NULL to prevent the stack
- * from freeing it.
+ * later use, the access callback must set this pointer to NULL to
+ * prevent the stack from freeing it.
*/
struct os_mbuf *om;
@@ -293,23 +322,6 @@ struct ble_gatt_access_ctxt {
};
};
-struct ble_gatt_dsc_def {
- /**
- * The first element in a uint8_t[16]; use the BLE_UUID16 macro for 16-bit
- * UUIDs; NULL if there are no more descriptors in the characteristic.
- */
- uint8_t *uuid128;
-
- /** Specifies the set of permitted operations for this descriptor. */
- uint8_t att_flags;
-
- /** Callback that gets executed when the descriptor is read or written. */
- ble_gatt_access_fn *access_cb;
-
- /** Optional argument for callback. */
- void *arg;
-};
-
/**
* Context passed to the registration callback; represents the GATT service,
* characteristic, or descriptor being registered.
@@ -415,7 +427,6 @@ struct ble_gatt_resources {
uint16_t attrs;
};
-struct ble_gatt_register_ctxt;
typedef void ble_gatt_register_fn(struct ble_gatt_register_ctxt *ctxt,
void *arg);
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/beab6f23/net/nimble/host/src/ble_hs_mbuf.c
----------------------------------------------------------------------
diff --git a/net/nimble/host/src/ble_hs_mbuf.c b/net/nimble/host/src/ble_hs_mbuf.c
index 7b8f47f..870c88b 100644
--- a/net/nimble/host/src/ble_hs_mbuf.c
+++ b/net/nimble/host/src/ble_hs_mbuf.c
@@ -105,6 +105,16 @@ ble_hs_mbuf_att_pkt(void)
BLE_ATT_PREP_WRITE_CMD_BASE_SZ);
}
+/**
+ * Allocates a an mbuf and fills it with the contents of the specified flat
+ * buffer.
+ *
+ * @param buf The flat buffer to copy from.
+ * @param len The length of the flat buffer.
+ *
+ * @return A newly-allocated mbuf on success;
+ * NULL on memory exhaustion.
+ */
struct os_mbuf *
ble_hs_mbuf_from_flat(const void *buf, uint16_t len)
{
@@ -125,6 +135,23 @@ ble_hs_mbuf_from_flat(const void *buf, uint16_t len)
return om;
}
+/**
+ * Copies the contents of an mbuf into the specified flat buffer. If the flat
+ * buffer is too small to contain the mbuf's contents, it is filled to capacity
+ * and BLE_HS_EMSGSIZE is returned.
+ *
+ * @param om The mbuf to copy from.
+ * @param flat The destination flat buffer.
+ * @param max_len The size of the flat buffer.
+ * @param out_copy_len The number of bytes actually copied gets
+ * written here.
+ *
+ * @return 0 on success;
+ * BLE_HS_EMSGSIZE if the flat buffer is too small
+ * to contain the mbuf's contents;
+ * A BLE host core return code on unexpected
+ * error.
+ */
int
ble_hs_mbuf_to_flat(const struct os_mbuf *om, void *flat, uint16_t max_len,
uint16_t *out_copy_len)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/beab6f23/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 89a9bf4..805cf49 100644
--- a/net/nimble/host/src/ble_uuid.c
+++ b/net/nimble/host/src/ble_uuid.c
@@ -37,7 +37,7 @@ static uint8_t ble_uuid_base[16] = {
* @param uuid128 The 128-bit UUID to attempt to convert.
* This must point to 16 contiguous bytes.
*
- * @return Positive 16-bit unsigned integer on
+ * @return A positive 16-bit unsigned integer on
* success;
* 0 if the UUID cannot be represented in 16
* bits.