GattClient.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __GATT_CLIENT_H__
00018 #define __GATT_CLIENT_H__
00019 
00020 #include "Gap.h"
00021 #include "GattAttribute.h"
00022 #include "ServiceDiscovery.h"
00023 
00024 #include "GattCallbackParamTypes.h"
00025 
00026 class GattClient {
00027 public:
00028     typedef void (*ReadCallback_t)(const GattReadCallbackParams *params);
00029 
00030     enum WriteOp_t {
00031         GATT_OP_WRITE_REQ = 0x01,  /**< Write Request. */
00032         GATT_OP_WRITE_CMD = 0x02,  /**< Write Command. */
00033     };
00034 
00035     typedef void (*WriteCallback_t)(const GattWriteCallbackParams *params);
00036 
00037     /*
00038      * The following functions are meant to be overridden in the platform-specific sub-class.
00039      */
00040 public:
00041     /**
00042      * Launch service discovery. Once launched, application callbacks will be
00043      * invoked for matching services/characteristics. isServiceDiscoveryActive()
00044      * can be used to determine status; and a termination callback (if setup)
00045      * will be invoked at the end. Service discovery can be terminated prematurely
00046      * if needed using terminateServiceDiscovery().
00047      *
00048      * @param  connectionHandle
00049      *           Handle for the connection with the peer.
00050      * @param  sc
00051      *           This is the application callback for matching service. Taken as
00052      *           NULL by default. Note: service discovery may still be active
00053      *           when this callback is issued; calling asynchronous BLE-stack
00054      *           APIs from within this application callback might cause the
00055      *           stack to abort service discovery. If this becomes an issue, it
00056      *           may be better to make local copy of the discoveredService and
00057      *           wait for service discovery to terminate before operating on the
00058      *           service.
00059      * @param  cc
00060      *           This is the application callback for matching characteristic.
00061      *           Taken as NULL by default. Note: service discovery may still be
00062      *           active when this callback is issued; calling asynchronous
00063      *           BLE-stack APIs from within this application callback might cause
00064      *           the stack to abort service discovery. If this becomes an issue,
00065      *           it may be better to make local copy of the discoveredCharacteristic
00066      *           and wait for service discovery to terminate before operating on the
00067      *           characteristic.
00068      * @param  matchingServiceUUID
00069      *           UUID based filter for specifying a service in which the application is
00070      *           interested. By default it is set as the wildcard UUID_UNKNOWN,
00071      *           in which case it matches all services. If characteristic-UUID
00072      *           filter (below) is set to the wildcard value, then a service
00073      *           callback will be invoked for the matching service (or for every
00074      *           service if the service filter is a wildcard).
00075      * @param  matchingCharacteristicUUIDIn
00076      *           UUID based filter for specifying characteristic in which the application
00077      *           is interested. By default it is set as the wildcard UUID_UKNOWN
00078      *           to match against any characteristic. If both service-UUID
00079      *           filter and characteristic-UUID filter are used with non- wildcard
00080      *           values, then only a single characteristic callback is
00081      *           invoked for the matching characteristic.
00082      *
00083      * @note     Using wildcard values for both service-UUID and characteristic-
00084      *           UUID will result in complete service discovery--callbacks being
00085      *           called for every service and characteristic.
00086      *
00087      * @note     Providing NULL for the characteristic callback will result in
00088      *           characteristic discovery being skipped for each matching
00089      *           service. This allows for an inexpensive method to discover only
00090      *           services.
00091      *
00092      * @return
00093      *           BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
00094      */
00095     virtual ble_error_t launchServiceDiscovery(Gap::Handle_t                               connectionHandle,
00096                                                ServiceDiscovery::ServiceCallback_t         sc                           = NULL,
00097                                                ServiceDiscovery::CharacteristicCallback_t  cc                           = NULL,
00098                                                const UUID                                 &matchingServiceUUID          = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
00099                                                const UUID                                 &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) {
00100         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00101     }
00102 
00103     /**
00104      * Launch service discovery for services. Once launched, service discovery will remain
00105      * active with service-callbacks being issued back into the application for matching
00106      * services. isServiceDiscoveryActive() can be used to
00107      * determine status; and a termination callback (if setup) will be invoked
00108      * at the end. Service discovery can be terminated prematurely if needed
00109      * using terminateServiceDiscovery().
00110      *
00111      * @param  connectionHandle
00112      *           Handle for the connection with the peer.
00113      * @param  sc
00114      *           This is the application callback for matching service. Note: service discovery may still be active
00115      *           when this callback is issued; calling asynchronous BLE-stack
00116      *           APIs from within this application callback might cause the
00117      *           stack to abort service discovery. If this becomes an issue, it
00118      *           may be better to make local copy of the discoveredService and
00119      *           wait for service discovery to terminate before operating on the
00120      *           service.
00121      * @param  matchingServiceUUID
00122      *           UUID based filter for specifying a service in which the application is
00123      *           interested. By default it is set as the wildcard UUID_UNKNOWN,
00124      *           in which case it matches all services.
00125      *
00126      * @return
00127      *           BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
00128      */
00129     virtual ble_error_t discoverServices(Gap::Handle_t                        connectionHandle,
00130                                          ServiceDiscovery::ServiceCallback_t  callback,
00131                                          const UUID                          &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) {
00132         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00133     }
00134 
00135     /**
00136      * Launch service discovery for services. Once launched, service discovery will remain
00137      * active with service-callbacks being issued back into the application for matching
00138      * services. isServiceDiscoveryActive() can be used to
00139      * determine status; and a termination callback (if setup) will be invoked
00140      * at the end. Service discovery can be terminated prematurely if needed
00141      * using terminateServiceDiscovery().
00142      *
00143      * @param  connectionHandle
00144      *           Handle for the connection with the peer.
00145      * @param  sc
00146      *           This is the application callback for matching service. Note: service discovery may still be active
00147      *           when this callback is issued; calling asynchronous BLE-stack
00148      *           APIs from within this application callback might cause the
00149      *           stack to abort service discovery. If this becomes an issue, it
00150      *           may be better to make local copy of the discoveredService and
00151      *           wait for service discovery to terminate before operating on the
00152      *           service.
00153      * @param  startHandle, endHandle
00154      *           Handle range within which to limit the search
00155      *
00156      * @return
00157      *           BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
00158      */
00159     virtual ble_error_t discoverServices(Gap::Handle_t                        connectionHandle,
00160                                          ServiceDiscovery::ServiceCallback_t  callback,
00161                                          GattAttribute::Handle_t              startHandle,
00162                                          GattAttribute::Handle_t              endHandle) {
00163         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00164     }
00165 
00166     /**
00167      * Is service-discovery currently active?
00168      */
00169     virtual bool isServiceDiscoveryActive(void) const {
00170         return false; /* default implementation; override this API if this capability is supported. */
00171     }
00172 
00173     /**
00174      * Terminate an ongoing service-discovery. This should result in an
00175      * invocation of the TerminationCallback if service-discovery is active.
00176      */
00177     virtual void terminateServiceDiscovery(void) {
00178         /* default implementation; override this API if this capability is supported. */
00179     }
00180 
00181     /* Initiate a Gatt Client read procedure by attribute-handle. */
00182     virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const {
00183         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00184     }
00185 
00186     /**
00187      * Initiate a GATT Client write procedure.
00188      *
00189      * @param[in] cmd
00190      *              Command can be either a write-request (which generates a
00191      *              matching response from the peripheral), or a write-command,
00192      *              which doesn't require the connected peer to respond.
00193      * @param[in] connHandle
00194      *              Connection handle.
00195      * @param[in] attributeHandle
00196      *              handle for the target attribtue on the remote GATT server.
00197      * @param[in] length
00198      *              length of the new value.
00199      * @param[in] value
00200      *              new value being written.
00201      */
00202     virtual ble_error_t write(GattClient::WriteOp_t    cmd,
00203                               Gap::Handle_t            connHandle,
00204                               GattAttribute::Handle_t  attributeHandle,
00205                               size_t                   length,
00206                               const uint8_t           *value) const {
00207         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00208     }
00209 
00210     /* Event callback handlers. */
00211 public:
00212     /**
00213      * Setup a callback for read response events.
00214      */
00215     void onDataRead(ReadCallback_t callback) {
00216         onDataReadCallback = callback;
00217     }
00218 
00219     /**
00220      * Setup a callback for write response events.
00221      * @Note: write commands (issued using writeWoResponse) don't generate a response.
00222      */
00223     void onDataWrite(WriteCallback_t callback) {
00224         onDataWriteCallback = callback;
00225     }
00226 
00227     /**
00228      * Setup callback for when serviceDiscovery terminates.
00229      */
00230     virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) {
00231         /* default implementation; override this API if this capability is supported. */
00232     }
00233 
00234 protected:
00235     GattClient() {
00236         /* empty */
00237     }
00238 
00239     /* Entry points for the underlying stack to report events back to the user. */
00240 public:
00241     void processReadResponse(const GattReadCallbackParams *params) {
00242         if (onDataReadCallback) {
00243             onDataReadCallback(params);
00244         }
00245     }
00246 
00247     void processWriteResponse(const GattWriteCallbackParams *params) {
00248         if (onDataWriteCallback) {
00249             onDataWriteCallback(params);
00250         }
00251     }
00252 
00253 protected:
00254     ReadCallback_t  onDataReadCallback;
00255     WriteCallback_t onDataWriteCallback;
00256 
00257 private:
00258     /* disallow copy and assignment */
00259     GattClient(const GattClient &);
00260     GattClient& operator=(const GattClient &);
00261 };
00262 
00263 #endif // ifndef __GATT_CLIENT_H__