Characteristic Access
=====================

.. contents::
  :local:
  :depth: 2

Review
^^^^^^

A characteristic's access callback implements its behavior. Recall that
services and characteristics are registered with NimBLE via attribute
tables. Each characteristic definition in an attribute table contains an
*access_cb* field. The *access_cb* field is an application callback
that gets executed whenever a peer device attempts to read or write the
characteristic.

Earlier in this tutorial, we looked at how *bleprph* implements the GAP
service. Let's take another look at how *bleprph* specifies the first
few characteristics in this service.

.. code:: c

    static const struct ble_gatt_svc_def gatt_svr_svcs[] = {
        {
            /*** Service: Security test. */
            .type               = BLE_GATT_SVC_TYPE_PRIMARY,
            .uuid               = &gatt_svr_svc_sec_test_uuid.u,
            .characteristics    = (struct ble_gatt_chr_def[]) { {
                /*** Characteristic: Random number generator. */
                .uuid               = &gatt_svr_chr_sec_test_rand_uuid.u,
                .access_cb          = gatt_svr_chr_access_sec_test,
                .flags              = BLE_GATT_CHR_F_READ | BLE_GATT_CHR_F_READ_ENC,
            }, {
                /*** Characteristic: Static value. */
                .uuid               = gatt_svr_chr_sec_test_static_uuid.u,
                .access_cb          = gatt_svr_chr_access_sec_test,
                .flags              = BLE_GATT_CHR_F_READ |
                                      BLE_GATT_CHR_F_WRITE | BLE_GATT_CHR_F_WRITE_ENC,
            }, {
        // [...]

As you can see, *bleprph* uses the same *access_cb* function for all
the GAP service characteristics, but the developer could have
implemented separate functions for each characteristic if they
preferred. Here is the *access_cb* function that the GAP service
characteristics use:

.. code:: c

    static int
    gatt_svr_chr_access_sec_test(uint16_t conn_handle, uint16_t attr_handle,
                                 struct ble_gatt_access_ctxt *ctxt,
                                 void *arg)
    {
        const ble_uuid_t *uuid;
        int rand_num;
        int rc;

        uuid = ctxt->chr->uuid;

        /* Determine which characteristic is being accessed by examining its
         * 128-bit UUID.
         */

        if (ble_uuid_cmp(uuid, &gatt_svr_chr_sec_test_rand_uuid.u) == 0) {
            assert(ctxt->op == BLE_GATT_ACCESS_OP_READ_CHR);

            /* Respond with a 32-bit random number. */
            rand_num = rand();
            rc = os_mbuf_append(ctxt->om, &rand_num, sizeof rand_num);
            return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES;
        }

        if (ble_uuid_cmp(uuid, &gatt_svr_chr_sec_test_static_uuid.u) == 0) {
            switch (ctxt->op) {
            case BLE_GATT_ACCESS_OP_READ_CHR:
                rc = os_mbuf_append(ctxt->om, &gatt_svr_sec_test_static_val,
                                    sizeof gatt_svr_sec_test_static_val);
                return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES;

            case BLE_GATT_ACCESS_OP_WRITE_CHR:
                rc = gatt_svr_chr_write(ctxt->om,
                                        sizeof gatt_svr_sec_test_static_val,
                                        sizeof gatt_svr_sec_test_static_val,
                                        &gatt_svr_sec_test_static_val, NULL);
                return rc;

            default:
                assert(0);
                return BLE_ATT_ERR_UNLIKELY;
            }
        }

    /* Unknown characteristic; the nimble stack should not have called this
     * function.
     */
    assert(0);
    return BLE_ATT_ERR_UNLIKELY;
}

After you've taken a moment to examine the structure of this function,
let's explore some details.

Function signature
^^^^^^^^^^^^^^^^^^

.. code:: c

    static int
    gatt_svr_chr_access_sec_test(uint16_t conn_handle, uint16_t attr_handle,
                                 struct ble_gatt_access_ctxt *ctxt, void *arg)

A characteristic access function always takes this same set of
parameters and always returns an int. The parameters to this function
type are documented below.

+----------------+--------------+------------+
| **Parameter**  | **Purpose**  | **Notes**  |
+================+==============+============+
| conn\_handle   | Indicates    | Use this   |
|                | which        | value to   |
|                | connection   | determine  |
|                | the          | which peer |
|                | characterist | is         |
|                | ic           | accessing  |
|                | access was   | the        |
|                | sent over.   | characteri |
|                |              | stic.      |
+----------------+--------------+------------+
| attr\_handle   | The          | Can be     |
|                | low-level    | used to    |
|                | ATT handle   | determine  |
|                | of the       | which      |
|                | characterist | characteri |
|                | ic           | stic       |
|                | value        | is being   |
|                | attribute.   | accessed   |
|                |              | if you     |
|                |              | don't want |
|                |              | to perform |
|                |              | a UUID     |
|                |              | lookup.    |
+----------------+--------------+------------+
| ctxt           | Contains the | For        |
|                | characterist | characteri |
|                | ic           | stic       |
|                | value        | accesses,  |
|                | pointer that | use the    |
|                | the          | *ctxt->chr |
|                | application  | \_access*  |
|                | needs to     | member;    |
|                | access.      | for        |
|                |              | descriptor |
|                |              | accesses,  |
|                |              | use the    |
|                |              | *ctxt->dsc |
|                |              | \_access*  |
|                |              | member.    |
+----------------+--------------+------------+

The return value of the access function tells the NimBLE stack how to
respond to the peer performing the operation. A value of 0 indicates
success. For failures, the function returns the specific ATT error code
that the NimBLE stack should respond with. The ATT error codes are
defined in
`net/nimble/host/include/host/ble\_att.h <https://github.com/apache/incubator-mynewt-core/blob/master/net/nimble/host/include/host/ble_att.h>`__.

Determine characteristic being accessed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: c

    ble_uuid_cmp(uuid, &gatt_svr_chr_sec_test_rand_uuid.u)

The function compares UUID with UUIDs of characteristic - if it fits,
characteristic is being accessed. There are two alternative methods *bleprph*
could have used to accomplish this task:

-  Map characteristics to ATT handles during service registration; use
   the *attr\_handle* parameter as a key into this table during
   characteristic access.
-  Implement a dedicated function for each characteristic; each function
   inherently knows which characteristic it corresponds to.

Read access
^^^^^^^^^^^

.. code:: c

        case BLE_GATT_ACCESS_OP_READ_CHR:
            rc = os_mbuf_append(ctxt->om, &gatt_svr_sec_test_static_val,
                                sizeof gatt_svr_sec_test_static_val);
            return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES;


This code excerpt handles read accesses to the device characteristic.
*ctxt->om* is chained memory buffer that for reads is being populated
with characteristic data. Returned value is either 0 for success or
*BLE_ATT_ERR_INSUFFICIENT_RES* if failed. The check makes sure the
NimBLE stack is doing its job; this characteristic was registered as
read-only, so the stack should have prevented write accesses.

Write access
^^^^^^^^^^^^

.. code:: c
    
    static int
    gatt_svr_chr_write(struct os_mbuf *om, uint16_t min_len, uint16_t max_len,
                       void *dst, uint16_t *len)
    {
        uint16_t om_len;
        int rc;

        om_len = OS_MBUF_PKTLEN(om);
        if (om_len < min_len || om_len > max_len) {
            return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN;
        }

        rc = ble_hs_mbuf_to_flat(om, dst, max_len, len);
        if (rc != 0) {
            return BLE_ATT_ERR_UNLIKELY;
        }

        return 0;
    }
    // [...]
    case BLE_GATT_ACCESS_OP_WRITE_CHR:
        rc = gatt_svr_chr_write(ctxt->om,
                                sizeof gatt_svr_sec_test_static_val,
                                sizeof gatt_svr_sec_test_static_val,
                                &gatt_svr_sec_test_static_val, NULL);
        return rc;

This code excerpt handles writes to the Static value
characteristic. This characteristic was registered as read-write, so the
*return rc* here is just a safety precaution to ensure the NimBLE stack
is doing its job.

Data is written to the *ctxt->om* buffer from *gatt_svr_sec_test_static_val*
by ``ble_hs_mbuf_to_flat()`` function. If length of written data greater or 
smaller than length of *gatt_svr_sec_test_static_val*, function return error.

Many characteristics have strict length requirements for write
operations.