Andrew Fox / BLE_API

add "LE Device Address" 0x1B to advertising data types

Fork of BLE_API by Bluetooth Low Energy

ble/GattCallbackParamTypes.h@716:11b41f651697, 2015-07-02 (annotated)

Committer:
rgrover1
Date:
Thu Jul 02 09:06:11 2015 +0100
Revision:
716:11b41f651697
Child:
737:79d95f9b93be
Synchronized with git rev d80fec88

Author: Rohit Grover

Release 0.4.0

=============



This is a major release which introduces the GATT Client functionality. It

also aligns BLE_API with builds using our new package manager: yotta

(https://github.com/armmbed/yotta).



Many APIs have seen some redesign. We encourage our users to pay attention to

the changes and migrate appropriately over time. We've also taken care to

ensure that existing code continues to work the same way. There's more

documentation in the form of comment headers for APIs to explain proper usage;

in many cases comment headers suggest alternative use of APIs.



Enhancements

~~~~~~~~~~~~



* Introduce GattClient. This includes functionality for service-discovery,

  connections, and attribute-reads and writes. You'll find a demo program for

  LEDBlinker on the mbed.org Bluetooth team page to use the new APIs. Some of

  the GATT client functionality hasn't been implemented yet, but the APIs have

  been added.



* Most APIs in the abstract base classes like Gap and GattServer return

  BLE_ERROR_NOT_IMPLEMENTED. Previously many APIs were pure-virtual, which did

  not permit partial ports to compile.



* We've added a new abstract base class for SecurityManager. All security

  related APIs have been moved into that.



* BLEDevice has been renamed as BLE. A deprecated alias for BLEDevice is

  available to support existing code.



* There has been a major cleanup of APIs under BLE. APIs have now been

  categorized as belonging to Gap, GattServer, GattClient, or SecurityManager.

  There are accessors to get references for Gap, GattServer, GattClient, and

  SecurityManager. A former call to ble.setAddress(...) is now expected to be

  achieved with ble.gap().setAddress(...).



* We've cleaned up our APIs, and this has resulted in dropping some APIs like

  BLE::reset().



* We've also dropped GattServer::initializeGattDatabase(). THis was added at

  some point to support controllers where a commit point was needed to

  indicate when the application had finished constructing the GATT database.

  This API would get called internally before Gap::startAdvertising(). We now

  expect the underlying port to do the equivalent of initializeGattDatabase()

  implicitly upon Gap::startAdvertising().



* The callback for BLE.onTimeout() now receives a TimeoutSource_t to indicate

  the cause of the timeout. This is perhaps the only breaking API change. We

  expect it to have very little disruptive effect.



* We've added a version of Gap::disconnect() which takes a connection handle.

  The previous API (which did not take a connection handle) has been

  deprecated; it will still work for situations where there's only a single

  active connection. We hold on to that API to allow existing code to migrate

  to the new API.



Bugfixes

~~~~~~~~



* None.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 716:11b41f651697 1 /* mbed Microcontroller Library
rgrover1 716:11b41f651697 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 716:11b41f651697 3 *
rgrover1 716:11b41f651697 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 716:11b41f651697 5 * you may not use this file except in compliance with the License.
rgrover1 716:11b41f651697 6 * You may obtain a copy of the License at
rgrover1 716:11b41f651697 7 *
rgrover1 716:11b41f651697 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 716:11b41f651697 9 *
rgrover1 716:11b41f651697 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 716:11b41f651697 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 716:11b41f651697 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 716:11b41f651697 13 * See the License for the specific language governing permissions and
rgrover1 716:11b41f651697 14 * limitations under the License.
rgrover1 716:11b41f651697 15 */
rgrover1 716:11b41f651697 16
rgrover1 716:11b41f651697 17 #ifndef __GATT_CALLBACK_PARAM_TYPES_H__
rgrover1 716:11b41f651697 18 #define __GATT_CALLBACK_PARAM_TYPES_H__
rgrover1 716:11b41f651697 19
rgrover1 716:11b41f651697 20 struct GattWriteCallbackParams {
rgrover1 716:11b41f651697 21 enum WriteOp_t {
rgrover1 716:11b41f651697 22 OP_INVALID = 0x00, /**< Invalid Operation. */
rgrover1 716:11b41f651697 23 OP_WRITE_REQ = 0x01, /**< Write Request. */
rgrover1 716:11b41f651697 24 OP_WRITE_CMD = 0x02, /**< Write Command. */
rgrover1 716:11b41f651697 25 OP_SIGN_WRITE_CMD = 0x03, /**< Signed Write Command. */
rgrover1 716:11b41f651697 26 OP_PREP_WRITE_REQ = 0x04, /**< Prepare Write Request. */
rgrover1 716:11b41f651697 27 OP_EXEC_WRITE_REQ_CANCEL = 0x05, /**< Execute Write Request: Cancel all prepared writes. */
rgrover1 716:11b41f651697 28 OP_EXEC_WRITE_REQ_NOW = 0x06, /**< Execute Write Request: Immediately execute all prepared writes. */
rgrover1 716:11b41f651697 29 };
rgrover1 716:11b41f651697 30
rgrover1 716:11b41f651697 31 GattAttribute::Handle_t handle;
rgrover1 716:11b41f651697 32 WriteOp_t writeOp; /**< Type of write operation, */
rgrover1 716:11b41f651697 33 uint16_t offset; /**< Offset for the write operation. */
rgrover1 716:11b41f651697 34 uint16_t len;
rgrover1 716:11b41f651697 35 const uint8_t *data; /* @note: data might not persist beyond the callback; make a local copy if needed. */
rgrover1 716:11b41f651697 36 };
rgrover1 716:11b41f651697 37
rgrover1 716:11b41f651697 38 struct GattReadCallbackParams {
rgrover1 716:11b41f651697 39 GattAttribute::Handle_t handle;
rgrover1 716:11b41f651697 40 uint16_t offset; /**< Offset for the read operation. */
rgrover1 716:11b41f651697 41 uint16_t len;
rgrover1 716:11b41f651697 42 const uint8_t *data; /* @note: data might not persist beyond the callback; make a local copy if needed. */
rgrover1 716:11b41f651697 43 };
rgrover1 716:11b41f651697 44
rgrover1 716:11b41f651697 45 enum GattAuthCallbackReply_t {
rgrover1 716:11b41f651697 46 AUTH_CALLBACK_REPLY_SUCCESS = 0x00, /**< Success. */
rgrover1 716:11b41f651697 47 AUTH_CALLBACK_REPLY_ATTERR_INVALID_HANDLE = 0x0101, /**< ATT Error: Invalid Attribute Handle. */
rgrover1 716:11b41f651697 48 AUTH_CALLBACK_REPLY_ATTERR_READ_NOT_PERMITTED = 0x0102, /**< ATT Error: Read not permitted. */
rgrover1 716:11b41f651697 49 AUTH_CALLBACK_REPLY_ATTERR_WRITE_NOT_PERMITTED = 0x0103, /**< ATT Error: Write not permitted. */
rgrover1 716:11b41f651697 50 AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHENTICATION = 0x0105, /**< ATT Error: Authenticated link required. */
rgrover1 716:11b41f651697 51 AUTH_CALLBACK_REPLY_ATTERR_INVALID_OFFSET = 0x0107, /**< ATT Error: Offset specified was past the end of the attribute. */
rgrover1 716:11b41f651697 52 AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHORIZATION = 0x0108, /**< ATT Error: Used in ATT as Insufficient Authorisation. */
rgrover1 716:11b41f651697 53 AUTH_CALLBACK_REPLY_ATTERR_PREPARE_QUEUE_FULL = 0x0109, /**< ATT Error: Used in ATT as Prepare Queue Full. */
rgrover1 716:11b41f651697 54 AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_FOUND = 0x010A, /**< ATT Error: Used in ATT as Attribute not found. */
rgrover1 716:11b41f651697 55 AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_LONG = 0x010B, /**< ATT Error: Attribute cannot be read or written using read/write blob requests. */
rgrover1 716:11b41f651697 56 AUTH_CALLBACK_REPLY_ATTERR_INVALID_ATT_VAL_LENGTH = 0x010D, /**< ATT Error: Invalid value size. */
rgrover1 716:11b41f651697 57 AUTH_CALLBACK_REPLY_ATTERR_INSUF_RESOURCES = 0x0111, /**< ATT Error: Encrypted link required. */
rgrover1 716:11b41f651697 58 };
rgrover1 716:11b41f651697 59
rgrover1 716:11b41f651697 60 struct GattWriteAuthCallbackParams {
rgrover1 716:11b41f651697 61 GattAttribute::Handle_t handle;
rgrover1 716:11b41f651697 62 uint16_t offset; /**< Offset for the write operation. */
rgrover1 716:11b41f651697 63 uint16_t len; /**< Length of the incoming data. */
rgrover1 716:11b41f651697 64 const uint8_t *data; /**< Incoming data, variable length. */
rgrover1 716:11b41f651697 65 GattAuthCallbackReply_t authorizationReply; /* This is the out parameter which needs to be set to true by the callback if the
rgrover1 716:11b41f651697 66 * request is to proceed; false otherwise. */
rgrover1 716:11b41f651697 67 };
rgrover1 716:11b41f651697 68
rgrover1 716:11b41f651697 69 struct GattReadAuthCallbackParams {
rgrover1 716:11b41f651697 70 GattAttribute::Handle_t handle;
rgrover1 716:11b41f651697 71 uint16_t offset; /**< Offset for the read operation. */
rgrover1 716:11b41f651697 72 uint16_t len; /**< Optional: new length of the outgoing data. */
rgrover1 716:11b41f651697 73 uint8_t *data; /**< Optional: new outgoing data. Leave at NULL if data is unchanged. */
rgrover1 716:11b41f651697 74 GattAuthCallbackReply_t authorizationReply; /* This is the out parameter which needs to be set to true by the callback if the
rgrover1 716:11b41f651697 75 * request is to proceed; false otherwise. */
rgrover1 716:11b41f651697 76 };
rgrover1 716:11b41f651697 77
rgrover1 716:11b41f651697 78 #endif /*__GATT_CALLBACK_PARAM_TYPES_H__*/