Cataract Gemuese / BLE_API

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of BLE_API by Bluetooth Low Energy

public/GattClient.h@559:1ee5106d3763, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:52:11 2015 +0100
Revision:
559:1ee5106d3763
Parent:
540:1fb1e0b809eb
Child:
564:1d8aa4ad07fe
Synchronized with git rev bf3cdb35

Author: Rohit Grover

GattClient: provide default implementation for virtual methods. fix comments.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 527:493185cebc03 1 /* mbed Microcontroller Library
rgrover1 527:493185cebc03 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 527:493185cebc03 3 *
rgrover1 527:493185cebc03 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 527:493185cebc03 5 * you may not use this file except in compliance with the License.
rgrover1 527:493185cebc03 6 * You may obtain a copy of the License at
rgrover1 527:493185cebc03 7 *
rgrover1 527:493185cebc03 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 527:493185cebc03 9 *
rgrover1 527:493185cebc03 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 527:493185cebc03 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 527:493185cebc03 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 527:493185cebc03 13 * See the License for the specific language governing permissions and
rgrover1 527:493185cebc03 14 * limitations under the License.
rgrover1 527:493185cebc03 15 */
rgrover1 527:493185cebc03 16
rgrover1 527:493185cebc03 17 #ifndef __GATT_CLIENT_H__
rgrover1 527:493185cebc03 18 #define __GATT_CLIENT_H__
rgrover1 527:493185cebc03 19
rgrover1 527:493185cebc03 20 #include "Gap.h"
rgrover1 527:493185cebc03 21 #include "GattAttribute.h"
rgrover1 527:493185cebc03 22 #include "ServiceDiscovery.h"
rgrover1 527:493185cebc03 23
rgrover1 527:493185cebc03 24 #include "GattCallbackParamTypes.h"
rgrover1 527:493185cebc03 25
rgrover1 527:493185cebc03 26 class GattClient {
rgrover1 527:493185cebc03 27 public:
rgrover1 527:493185cebc03 28 typedef void (*ReadCallback_t)(const GattReadCallbackParams *params);
rgrover1 527:493185cebc03 29
rgrover1 527:493185cebc03 30 enum WriteOp_t {
rgrover1 527:493185cebc03 31 GATT_OP_WRITE_REQ = 0x01, /**< Write Request. */
rgrover1 527:493185cebc03 32 GATT_OP_WRITE_CMD = 0x02, /**< Write Command. */
rgrover1 527:493185cebc03 33 };
rgrover1 527:493185cebc03 34
rgrover1 527:493185cebc03 35 typedef void (*WriteCallback_t)(const GattWriteCallbackParams *params);
rgrover1 527:493185cebc03 36
rgrover1 559:1ee5106d3763 37 /*
rgrover1 559:1ee5106d3763 38 * The following functions are meant to be overridden in the platform-specific sub-class.
rgrover1 559:1ee5106d3763 39 */
rgrover1 527:493185cebc03 40 public:
rgrover1 527:493185cebc03 41 /**
rgrover1 527:493185cebc03 42 * Launch service discovery. Once launched, service discovery will remain
rgrover1 527:493185cebc03 43 * active with callbacks being issued back into the application for matching
rgrover1 540:1fb1e0b809eb 44 * services/characteristics. isServiceDiscoveryActive() can be used to
rgrover1 540:1fb1e0b809eb 45 * determine status; and a termination callback (if setup) will be invoked
rgrover1 540:1fb1e0b809eb 46 * at the end. Service discovery can be terminated prematurely if needed
rgrover1 540:1fb1e0b809eb 47 * using terminateServiceDiscovery().
rgrover1 527:493185cebc03 48 *
rgrover1 527:493185cebc03 49 * @param connectionHandle
rgrover1 527:493185cebc03 50 * Handle for the connection with the peer.
rgrover1 527:493185cebc03 51 * @param sc
rgrover1 540:1fb1e0b809eb 52 * This is the application callback for matching service. Taken as
rgrover1 540:1fb1e0b809eb 53 * NULL by default. Note: service discovery may still be active
rgrover1 540:1fb1e0b809eb 54 * when this callback is issued; calling asynchronous BLE-stack
rgrover1 540:1fb1e0b809eb 55 * APIs from within this application callback might cause the
rgrover1 540:1fb1e0b809eb 56 * stack to abort service discovery. If this becomes an issue, it
rgrover1 540:1fb1e0b809eb 57 * may be better to make local copy of the discoveredService and
rgrover1 540:1fb1e0b809eb 58 * wait for service discovery to terminate before operating on the
rgrover1 540:1fb1e0b809eb 59 * service.
rgrover1 527:493185cebc03 60 * @param cc
rgrover1 527:493185cebc03 61 * This is the application callback for matching characteristic.
rgrover1 540:1fb1e0b809eb 62 * Taken as NULL by default. Note: service discovery may still be
rgrover1 540:1fb1e0b809eb 63 * active when this callback is issued; calling asynchronous
rgrover1 540:1fb1e0b809eb 64 * BLE-stack APIs from within this application callback might cause
rgrover1 540:1fb1e0b809eb 65 * the stack to abort service discovery. If this becomes an issue,
rgrover1 540:1fb1e0b809eb 66 * it may be better to make local copy of the discoveredCharacteristic
rgrover1 540:1fb1e0b809eb 67 * and wait for service discovery to terminate before operating on the
rgrover1 540:1fb1e0b809eb 68 * characteristic.
rgrover1 527:493185cebc03 69 * @param matchingServiceUUID
rgrover1 527:493185cebc03 70 * UUID based filter for specifying a service in which the application is
rgrover1 540:1fb1e0b809eb 71 * interested. By default it is set as the wildcard UUID_UNKNOWN,
rgrover1 540:1fb1e0b809eb 72 * in which case it matches all services. If characteristic-UUID
rgrover1 540:1fb1e0b809eb 73 * filter (below) is set to the wildcard value, then a service
rgrover1 540:1fb1e0b809eb 74 * callback will be invoked for the matching service (or for every
rgrover1 540:1fb1e0b809eb 75 * service if the service filter is a wildcard).
rgrover1 527:493185cebc03 76 * @param matchingCharacteristicUUIDIn
rgrover1 527:493185cebc03 77 * UUID based filter for specifying characteristic in which the application
rgrover1 540:1fb1e0b809eb 78 * is interested. By default it is set as the wildcard UUID_UKNOWN
rgrover1 540:1fb1e0b809eb 79 * to match against any characteristic. If both service-UUID
rgrover1 540:1fb1e0b809eb 80 * filter and characteristic-UUID filter are used with non- wildcard
rgrover1 540:1fb1e0b809eb 81 * values, then only a single characteristic callback is
rgrover1 540:1fb1e0b809eb 82 * invoked for the matching characteristic.
rgrover1 527:493185cebc03 83 *
rgrover1 540:1fb1e0b809eb 84 * @note Using wildcard values for both service-UUID and characteristic-
rgrover1 527:493185cebc03 85 * UUID will result in complete service discovery--callbacks being
rgrover1 527:493185cebc03 86 * called for every service and characteristic.
rgrover1 527:493185cebc03 87 *
rgrover1 559:1ee5106d3763 88 *
rgrover1 540:1fb1e0b809eb 89 * @note Providing NULL for the characteristic callback will result in
rgrover1 559:1ee5106d3763 90 * characteristic discovery being skipped for each matching
rgrover1 559:1ee5106d3763 91 * service. This allows for an inexpensive method to discover only
rgrover1 559:1ee5106d3763 92 * services.
rgrover1 540:1fb1e0b809eb 93 *
rgrover1 527:493185cebc03 94 * @return
rgrover1 527:493185cebc03 95 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
rgrover1 527:493185cebc03 96 */
rgrover1 527:493185cebc03 97 virtual ble_error_t launchServiceDiscovery(Gap::Handle_t connectionHandle,
rgrover1 527:493185cebc03 98 ServiceDiscovery::ServiceCallback_t sc = NULL,
rgrover1 527:493185cebc03 99 ServiceDiscovery::CharacteristicCallback_t cc = NULL,
rgrover1 527:493185cebc03 100 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
rgrover1 559:1ee5106d3763 101 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) {
rgrover1 559:1ee5106d3763 102 return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
rgrover1 559:1ee5106d3763 103 }
rgrover1 527:493185cebc03 104
rgrover1 527:493185cebc03 105 /**
rgrover1 527:493185cebc03 106 * Is service-discovery currently active?
rgrover1 527:493185cebc03 107 */
rgrover1 559:1ee5106d3763 108 virtual bool isServiceDiscoveryActive(void) const {
rgrover1 559:1ee5106d3763 109 return false; /* default implementation; override this API if this capability is supported. */
rgrover1 559:1ee5106d3763 110 }
rgrover1 527:493185cebc03 111
rgrover1 527:493185cebc03 112 /**
rgrover1 527:493185cebc03 113 * Terminate an ongoing service-discovery. This should result in an
rgrover1 527:493185cebc03 114 * invocation of the TerminationCallback if service-discovery is active.
rgrover1 527:493185cebc03 115 */
rgrover1 559:1ee5106d3763 116 virtual void terminateServiceDiscovery(void) {
rgrover1 559:1ee5106d3763 117 /* default implementation; override this API if this capability is supported. */
rgrover1 559:1ee5106d3763 118 }
rgrover1 527:493185cebc03 119
rgrover1 559:1ee5106d3763 120 /* Initiate a Gatt Client read procedure by attribute-handle. */
rgrover1 559:1ee5106d3763 121 virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const {
rgrover1 559:1ee5106d3763 122 return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
rgrover1 559:1ee5106d3763 123 }
rgrover1 527:493185cebc03 124
rgrover1 540:1fb1e0b809eb 125 /**
rgrover1 540:1fb1e0b809eb 126 * Initiate a GATT Client write procedure.
rgrover1 540:1fb1e0b809eb 127 *
rgrover1 540:1fb1e0b809eb 128 * @param[in] cmd
rgrover1 540:1fb1e0b809eb 129 * Command can be either a write-request (which generates a
rgrover1 540:1fb1e0b809eb 130 * matching response from the peripheral), or a write-command,
rgrover1 540:1fb1e0b809eb 131 * which doesn't require the connected peer to respond.
rgrover1 540:1fb1e0b809eb 132 * @param[in] connHandle
rgrover1 540:1fb1e0b809eb 133 * Connection handle.
rgrover1 540:1fb1e0b809eb 134 * @param[in] attributeHandle
rgrover1 540:1fb1e0b809eb 135 * handle for the target attribtue on the remote GATT server.
rgrover1 540:1fb1e0b809eb 136 * @param[in] length
rgrover1 540:1fb1e0b809eb 137 * length of the new value.
rgrover1 540:1fb1e0b809eb 138 * @param[in] value
rgrover1 540:1fb1e0b809eb 139 * new value being written.
rgrover1 540:1fb1e0b809eb 140 */
rgrover1 527:493185cebc03 141 virtual ble_error_t write(GattClient::WriteOp_t cmd,
rgrover1 527:493185cebc03 142 Gap::Handle_t connHandle,
rgrover1 527:493185cebc03 143 GattAttribute::Handle_t attributeHandle,
rgrover1 527:493185cebc03 144 size_t length,
rgrover1 559:1ee5106d3763 145 const uint8_t *value) const {
rgrover1 559:1ee5106d3763 146 return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this API if this capability is supported. */
rgrover1 559:1ee5106d3763 147 }
rgrover1 559:1ee5106d3763 148
rgrover1 559:1ee5106d3763 149 /**
rgrover1 559:1ee5106d3763 150 * Setup callback for when serviceDiscovery terminates.
rgrover1 559:1ee5106d3763 151 */
rgrover1 559:1ee5106d3763 152 virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) {
rgrover1 559:1ee5106d3763 153 /* default implementation; override this API if this capability is supported. */
rgrover1 559:1ee5106d3763 154 }
rgrover1 527:493185cebc03 155
rgrover1 527:493185cebc03 156 protected:
rgrover1 527:493185cebc03 157 GattClient() {
rgrover1 527:493185cebc03 158 /* empty */
rgrover1 527:493185cebc03 159 }
rgrover1 527:493185cebc03 160
rgrover1 527:493185cebc03 161 private:
rgrover1 527:493185cebc03 162 /* disallow copy and assignment */
rgrover1 527:493185cebc03 163 GattClient(const GattClient &);
rgrover1 527:493185cebc03 164 GattClient& operator=(const GattClient &);
rgrover1 527:493185cebc03 165 };
rgrover1 527:493185cebc03 166
rgrover1 527:493185cebc03 167 #endif // ifndef __GATT_CLIENT_H__